Encapsulation for std-lib (#5658)

## Description Merges the staging branch into master from the following PRs: #5640 #5630 #5621 #5613 ## Checklist - [x] I have linked to any relevant issues. - [x] I have commented my code, particularly in hard-to-understand areas. - [x] I have updated the documentation where relevant (API docs, the reference, and the Sway book). - [x] I have added tests that prove my fix is effective or that my feature works. - [x] I have added (or requested a maintainer to add) the necessary `Breaking*` or `New Feature` labels where relevant. - [x] I have done my best to ensure that my PR adheres to [the Fuel Labs Code Review Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md). - [x] I have requested a review from the relevant team or maintainers. --------- Co-authored-by: IGI-111 <[email protected]> Co-authored-by: Sophie Dankel <[email protected]>
FuelLabs · Mar 3, 2024 · d5b8cb8 · d5b8cb8
1 parent 28669da
commit d5b8cb8
Show file tree

Hide file tree

Showing 74 changed files with 832 additions and 508 deletions.
diff --git a/docs/reference/src/code/operations/namespace/src/lib.sw b/docs/reference/src/code/operations/namespace/src/lib.sw
@@ -2,12 +2,12 @@ library;
 
 // ANCHOR: address
 pub struct Address {
-    value: b256,
+    bits: b256,
 }
 // ANCHOR_END: address
 // ANCHOR: contract_id
 pub struct ContractId {
-    value: b256,
+    bits: b256,
 }
 // ANCHOR_END: contract_id
 // ANCHOR: identity

diff --git a/examples/liquidity_pool/src/main.sw b/examples/liquidity_pool/src/main.sw
@@ -19,9 +19,7 @@ abi LiquidityPool {
     fn withdraw(recipient: Address);
 }
 
-const BASE_ASSET: AssetId = AssetId {
-    value: 0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c,
-};
+const BASE_ASSET: AssetId = AssetId::from(0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c);
 
 impl LiquidityPool for Contract {
     fn deposit(recipient: Address) {

diff --git a/examples/signatures/src/main.sw b/examples/signatures/src/main.sw
@@ -15,7 +15,7 @@ fn main() {
     // A recovered Fuel address.
     let result_address: Result<Address, EcRecoverError> = ec_recover_address(signature, MSG_HASH);
     if let Ok(address) = result_address {
-        log(address.value);
+        log(address.bits());
     } else {
         revert(0);
     }

diff --git a/sway-lib-core/src/storage.sw b/sway-lib-core/src/storage.sw
@@ -12,9 +12,107 @@ library;
 /// represent different storage constructs.
 pub struct StorageKey<T> {
     /// The assigned location in storage.
-    pub slot: b256,
+    slot: b256,
     /// The assigned offset based on the data structure `T`.
-    pub offset: u64,
+    offset: u64,
     /// A unique identifier.
-    pub field_id: b256,
+    field_id: b256,
+}
+
+impl<T> StorageKey<T> {
+    /// Create a new `StorageKey`.
+    ///
+    /// # Arguments
+    ///
+    /// * `slot`: [b256] - The assigned location in storage for the new `StorageKey`.
+    /// * `offset`: [u64] - The assigned offset based on the data structure `T` for the new `StorageKey`.
+    /// * `field_id`: [b256] - A unique identifier for the new `StorageKey`.
+    ///
+    /// # Returns
+    ///
+    /// * [StorageKey] - The newly create `StorageKey`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use std::{constants::ZERO_B256, hash::sha256};
+    ///
+    /// fn foo() {
+    ///     let my_key = StorageKey::<u64>::new(ZERO_B256, 0, sha256(ZERO_B256));
+    ///     assert(my_key.slot() == ZERO_B256);
+    /// }
+    /// ```
+    pub fn new(slot: b256, offset: u64, field_id: b256) -> Self {
+        Self {
+            slot,
+            offset,
+            field_id,
+        }
+    }
+
+    /// Returns the storage slot address.
+    ///
+    /// # Returns
+    ///
+    /// * [b256] - The address in storage that this storage slot points to.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use std::{constants::ZERO_B256, hash::sha256};
+    ///
+    /// fn foo() {
+    ///     let my_key = StorageKey::<u64>::new(ZERO_B256, 0, sha256(ZERO_B256));
+    ///     assert(my_key.slot() == ZERO_B256);
+    /// }
+    /// ```
+    pub fn slot(self) -> b256 {
+        self.slot
+    }
+
+    /// Returns the offset on the storage slot.
+    ///
+    /// # Returns
+    ///
+    /// * [u64] - The offset in storage that this storage slot points to.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use std::{constants::ZERO_B256, hash::sha256};
+    ///
+    /// fn foo() {
+    ///     let my_key = StorageKey::<u64>::new(ZERO_B256, 0, sha256(ZERO_B256));
+    ///     assert(my_key.offset() == 0);
+    /// }
+    /// ```
+    pub fn offset(self) -> u64 {
+        self.offset
+    }
+
+    /// Returns the storage slot field id.
+    ///
+    /// # Additional Information
+    ///
+    /// The field id is a unique identifier for the storage field being referred to, it is different even
+    /// for multiple zero sized fields that might live at the same location but
+    /// represent different storage constructs.
+    ///
+    /// # Returns
+    ///
+    /// * [b256] - The field id for this storage slot.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use std::{constants::ZERO_B256, hash::sha256};
+    ///
+    /// fn foo() {
+    ///     let my_key = StorageKey::<u64>::new(ZERO_B256, 0, sha256(ZERO_B256));
+    ///     assert(my_key.field_id() == sha256(ZERO_B256));
+    /// }
+    /// ```
+    pub fn field_id(self) -> b256 {
+        self.field_id
+    }
 }
diff --git a/sway-lib-std/src/address.sw b/sway-lib-std/src/address.sw
@@ -7,12 +7,34 @@ use ::hash::{Hash, Hasher};
 /// The `Address` type, a struct wrapper around the inner `b256` value.
 pub struct Address {
     /// The underlying raw `b256` data of the address.
-    pub value: b256,
+    bits: b256,
+}
+
+impl Address {
+    /// Returns the underlying raw `b256` data of the address.
+    ///
+    /// # Returns
+    ///
+    /// * [b256] - The raw data of the address.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use std::constants::ZERO_B256;
+    ///
+    /// fn foo() -> {
+    ///     let my_address = Address::from(ZERO_B256);
+    ///     assert(my_address.bits() == ZERO_B256);
+    /// }
+    /// ```
+    pub fn bits(self) -> b256 {
+        self.bits
+    }
 }
 
 impl core::ops::Eq for Address {
     fn eq(self, other: Self) -> bool {
-        self.value == other.value
+        self.bits == other.bits
     }
 }
 
@@ -38,7 +60,7 @@ impl From<b256> for Address {
     /// }
     /// ```
     fn from(bits: b256) -> Self {
-        Self { value: bits }
+        Self { bits }
     }
 }
 
@@ -60,14 +82,14 @@ impl From<Address> for b256 {
     ///     assert(b256_data == ZERO_B256);
     /// }
     /// ```
-    fn from(address: Address) -> b256 {
-        address.value
+    fn from(address: Address) -> Self {
+        address.bits()
     }
 }
 
 impl Hash for Address {
     fn hash(self, ref mut state: Hasher) {
-        let Address { value } = self;
-        value.hash(state);
+        let Address { bits } = self;
+        bits.hash(state);
     }
 }
diff --git a/sway-lib-std/src/asset.sw b/sway-lib-std/src/asset.sw
@@ -218,7 +218,7 @@ pub fn transfer(to: Identity, asset_id: AssetId, amount: u64) {
 /// }
 /// ```
 pub fn force_transfer_to_contract(to: ContractId, asset_id: AssetId, amount: u64) {
-    asm(r1: amount, r2: asset_id, r3: to.value) {
+    asm(r1: amount, r2: asset_id, r3: to.bits()) {
         tr r3 r1 r2;
     }
 }
@@ -259,7 +259,7 @@ pub fn transfer_to_address(to: Address, asset_id: AssetId, amount: u64) {
     while index < number_of_outputs {
         if let Output::Variable = output_type(index) {
             if output_amount(index) == 0 {
-                asm(r1: to.value, r2: index, r3: amount, r4: asset_id) {
+                asm(r1: to.bits(), r2: index, r3: amount, r4: asset_id) {
                     tro r1 r2 r3 r4;
                 };
                 return;

diff --git a/sway-lib-std/src/asset_id.sw b/sway-lib-std/src/asset_id.sw
@@ -16,19 +16,19 @@ use ::hash::{Hash, Hasher};
 ///
 /// The SubId is used to differentiate between different assets that are created by the same contract.
 pub struct AssetId {
-    pub value: b256,
+    bits: b256,
 }
 
 impl Hash for AssetId {
     fn hash(self, ref mut state: Hasher) {
-        let Self { value } = self;
-        value.hash(state);
+        let Self { bits } = self;
+        bits.hash(state);
     }
 }
 
 impl core::ops::Eq for AssetId {
     fn eq(self, other: Self) -> bool {
-        self.value == other.value
+        self.bits == other.bits
     }
 }
 
@@ -53,30 +53,7 @@ impl From<b256> for AssetId {
     /// }
     /// ```
     fn from(bits: b256) -> Self {
-        Self { value: bits }
-    }
-}
-
-impl From<AssetId> for b256 {
-    /// Casts an `AssetId` to raw `b256` data.
-    ///
-    /// # Returns
-    ///
-    /// * [b256] - The underlying raw `b256` data of the `AssetId`.
-    ///
-    /// # Examples
-    ///
-    /// ```sway
-    /// use std::constants::ZERO_B256;
-    ///
-    /// fn foo() {
-    ///     let asset_id = AssetId::from(ZERO_B256);
-    ///     let b256_data = asset_id.into();
-    ///     assert(b256_data == ZERO_B256);
-    /// }
-    /// ```
-    fn from(id: AssetId) -> b256 {
-        id.value
+        Self { bits }
     }
 }
 
@@ -115,7 +92,7 @@ impl AssetId {
         };
 
         Self {
-            value: result_buffer,
+            bits: result_buffer,
         }
     }
 
@@ -152,7 +129,7 @@ impl AssetId {
         };
 
         Self {
-            value: result_buffer,
+            bits: result_buffer,
         }
     }
 
@@ -180,9 +157,52 @@ impl AssetId {
     /// ```
     pub fn base_asset_id() -> Self {
         Self {
-            value: 0x0000000000000000000000000000000000000000000000000000000000000000,
+            bits: 0x0000000000000000000000000000000000000000000000000000000000000000,
         }
     }
+
+    /// Returns the underlying raw `b256` data of the asset id.
+    ///
+    /// # Returns
+    ///
+    /// * [b256] - The raw data of the asset id.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use std::constants::ZERO_B256;
+    ///
+    /// fn foo() -> {
+    ///     let my_asset = AssetId::from(ZERO_B256);
+    ///     assert(my_asset.bits() == ZERO_B256);
+    /// }
+    /// ```
+    pub fn bits(self) -> b256 {
+        self.bits
+    }
+}
+
+impl From<AssetId> for b256 {
+    /// Casts an `AssetId` to raw `b256` data.
+    ///
+    /// # Returns
+    ///
+    /// * [b256] - The underlying raw `b256` data of the `AssetId`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use std::constants::ZERO_B256;
+    ///
+    /// fn foo() {
+    ///     let asset_id = AssetId::from(ZERO_B256);
+    ///     let b256_data = asset_id.into();
+    ///     assert(b256_data == ZERO_B256);
+    /// }
+    /// ```
+    fn from(id: AssetId) -> Self {
+        id.bits()
+    }
 }
 
 #[test()]