Merge pull request #53 from FuelLabs/bitzoic-asset-terminology

Formalize Asset and Coin Terminology in Standards

README.md

@@ -35,11 +35,11 @@ If you don't find what you're looking for, feel free to create an issue and prop
 
 ### Native Assets
 
-- [SRC-20; Token Standard](./standards/src20-token/) defines the implementation of a standard API for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) using the Sway Language.
+- [SRC-20; Native Asset Standard](./standards/src20-native-asset/) defines the implementation of a standard API for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) using the Sway Language.
 - [SRC-3; Mint and Burn](./standards/src3-mint-burn/) is used to enable mint and burn functionality for Native Assets.
 - [SRC-7; Arbitrary Asset Metadata Standard](./standards/src7-metadata/) is used to store metadata for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets).
 - [SRC-9; Metadata Keys Standard](./standards/src9-metadata-keys/) is used to store standardized metadata keys for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) in combination with the SRC-7 standard.
-- [SRC-6; Vault Standard](./standards/src6-vault/) defines the implementation of a standard API for token vaults developed in Sway.
+- [SRC-6; Vault Standard](./standards/src6-vault/) defines the implementation of a standard API for asset vaults developed in Sway.
 
 ### Access Control
 
@@ -68,7 +68,7 @@ You may then import your desired standard in your Sway Smart Contract as so:
 use standard::<standard_abi>;
 ```
 
-For example, to import the SRC-20 Token Standard use the following statements in your `Forc.toml` and Sway Smart Contract file respectively:
+For example, to import the SRC-20 Native Asset Standard use the following statements in your `Forc.toml` and Sway Smart Contract file respectively:
 
 ```rust
 src20 = { git = "https://github.com/FuelLabs/sway-standards", tag = "v0.3.0" }
@@ -82,13 +82,13 @@ use src20::SRC20;
 
 Minimal example implementations for every standard can be found in the [`examples/`](./examples/) folder.
 
-#### SRC-20; Token Standard Examples
+#### SRC-20; Native Asset Standard Examples
 
-##### - [Single Native Assset](./examples/src20-token/single_asset/src/single_asset.sw)
+##### - [Single Native Assset](./examples/src20-native-asset/single_asset/src/single_asset.sw)
 
 Example of the SRC-20 implementation where a contract contains a single asset with one `SubId`. This implementation is recommended for users that intend to deploy a single asset with their contract.
 
-##### - [Multi Native Asset](./examples/src20-token/multi_asset/src/multi_asset.sw)
+##### - [Multi Native Asset](./examples/src20-native-asset/multi_asset/src/multi_asset.sw)
 
 Example of the SRC-20 implementation where a contract contains multiple assets with differing `SubId`s. This implementation is recommended for users that intend to deploy multiple assets with their contract.
 
@@ -114,15 +114,15 @@ Example of the SRC-5 implementation where a contract has an owner set at compile
 
 #### SRC-6; Vault Standard Examples
 
-##### [Multi Token Vault](./examples/src6-vault/multi_token_vault/)
+##### [Multi Asset Vault](./examples/src6-vault/multi_asset_vault/)
 
 A basic implementation of the vault standard that supports any number of sub vaults being created for every AssetId.
 
-##### [Single Token Vault](./examples/src6-vault/single_token_vault/)
+##### [Single Asset Vault](./examples/src6-vault/single_asset_vault/)
 
 A basic implementation of the vault standard demonstrating how to restrict deposits and withdrawals to a single AssetId.
 
-##### [Single Token Single Sub Vault](./examples/src6-vault/single_token_single_sub_vault/)
+##### [Single Asset Single Sub Vault](./examples/src6-vault/single_asset_single_sub_vault/)
 
 A basic implementation of the vault standard demonstrating how to restrict deposits and withdrawals to a single AssetId, and to a single Sub vault.
 

examples/Forc.toml

@@ -6,6 +6,6 @@ members = [
   "src5-ownership/uninitialized_example",
   "src7-metadata/single_asset",
   "src7-metadata/multi_asset",
-  "src20-token/single_asset",
-  "src20-token/multi_asset",
+  "src20-native-asset/single_asset",
+  "src20-native-asset/multi_asset",
 ]

examples/src20-token/multi_asset/Forc.toml → examples/src20-native-asset/multi_asset/Forc.toml

@@ -5,4 +5,4 @@ license = "Apache-2.0"
 name = "multi_src20_asset"
 
 [dependencies]
-src20 = { path = "../../../standards/src20-token" }
+src20 = { path = "../../../standards/src20-native-asset" }

examples/src20-token/multi_asset/src/multi_asset.sw → examples/src20-native-asset/multi_asset/src/multi_asset.sw

@@ -4,9 +4,9 @@ use src20::SRC20;
 use std::{hash::Hash, storage::storage_string::*, string::String};
 
 storage {
-    /// The total number of distinguishable tokens minted by this contract.
+    /// The total number of distinguishable assets minted by this contract.
     total_assets: u64 = 0,
-    /// The total supply of tokens for a specific asset minted by this contract.
+    /// The total supply of coins for a specific asset minted by this contract.
     total_supply: StorageMap<AssetId, u64> = StorageMap {},
     /// The name of a specific asset minted by this contract.
     name: StorageMap<AssetId, StorageString> = StorageMap {},
@@ -47,7 +47,7 @@ impl SRC20 for Contract {
         storage.total_assets.read()
     }
 
-    /// Returns the total supply of tokens for an asset.
+    /// Returns the total supply of coins for an asset.
     ///
     /// # Arguments
     ///

examples/src20-token/single_asset/Forc.toml → examples/src20-native-asset/single_asset/Forc.toml

@@ -5,4 +5,4 @@ license = "Apache-2.0"
 name = "single_src20_asset"
 
 [dependencies]
-src20 = { path = "../../../standards/src20-token" }
+src20 = { path = "../../../standards/src20-native-asset" }

examples/src20-token/single_asset/src/single_asset.sw → examples/src20-native-asset/single_asset/src/single_asset.sw

@@ -4,12 +4,12 @@ use src20::SRC20;
 use std::{call_frames::contract_id, string::String};
 
 configurable {
-    /// The total supply of tokens for the asset minted by this contract.
+    /// The total supply of coins for the asset minted by this contract.
     TOTAL_SUPPLY: u64 = 100_000_000,
     /// The decimals of the asset minted by this contract.
     DECIMALS: u8 = 9u8,
     /// The name of the asset minted by this contract.
-    NAME: str[7] = __to_str_array("MyToken"),
+    NAME: str[7] = __to_str_array("MyAsset"),
     /// The symbol of the asset minted by this contract.
     SYMBOL: str[5] = __to_str_array("MYTKN"),
 }
@@ -41,7 +41,7 @@ impl SRC20 for Contract {
         1
     }
 
-    /// Returns the total supply of tokens for the asset.
+    /// Returns the total supply of coins for the asset.
     ///
     /// # Arguments
     ///

examples/src3-mint-burn/multi_asset/Forc.toml

@@ -5,5 +5,5 @@ license = "Apache-2.0"
 name = "multi_src3_asset"
 
 [dependencies]
-src20 = { path = "../../../standards/src20-token" }
+src20 = { path = "../../../standards/src20-native-asset" }
 src3 = { path = "../../../standards/src3-mint-burn" }

examples/src3-mint-burn/multi_asset/src/multi_asset.sw

@@ -35,13 +35,13 @@ storage {
 }
 
 impl SRC3 for Contract {
-    /// Unconditionally mints new tokens using the `sub_id` sub-identifier.
+    /// Unconditionally mints new assets using the `sub_id` sub-identifier.
     ///
     /// # Arguments
     ///
-    /// * `recipient`: [Identity] - The user to which the newly minted tokens are transferred to.
-    /// * `sub_id`: [SubId] - The sub-identifier of the newly minted token.
-    /// * `amount`: [u64] - The quantity of tokens to mint.
+    /// * `recipient`: [Identity] - The user to which the newly minted asset is transferred to.
+    /// * `sub_id`: [SubId] - The sub-identifier of the newly minted asset.
+    /// * `amount`: [u64] - The quantity of coins to mint.
     ///
     /// # Number of Storage Accesses
     ///
@@ -81,12 +81,12 @@ impl SRC3 for Contract {
         mint_to(recipient, sub_id, amount);
     }
 
-    /// Unconditionally burns tokens sent with the `sub_id` sub-identifier.
+    /// Unconditionally burns assets sent with the `sub_id` sub-identifier.
     ///
     /// # Arguments
     ///
-    /// * `sub_id`: [SubId] - The sub-identifier of the token to burn.
-    /// * `amount`: [u64] - The quantity of tokens to burn.
+    /// * `sub_id`: [SubId] - The sub-identifier of the asset to burn.
+    /// * `amount`: [u64] - The quantity of coins to burn.
     ///
     /// # Number of Storage Accesses
     ///
@@ -95,7 +95,7 @@ impl SRC3 for Contract {
     ///
     /// # Reverts
     ///
-    /// * When the transaction did not include at least `amount` tokens.
+    /// * When the transaction did not include at least `amount` coins.
     /// * When the asset included in the transaction does not have the SubId `sub_id`.
     ///
     /// # Examples

examples/src3-mint-burn/single_asset/Forc.toml

@@ -5,5 +5,5 @@ license = "Apache-2.0"
 name = "single_src3_asset"
 
 [dependencies]
-src20 = { path = "../../../standards/src20-token" }
+src20 = { path = "../../../standards/src20-native-asset" }
 src3 = { path = "../../../standards/src3-mint-burn" }

examples/src3-mint-burn/single_asset/src/single_asset.sw

@@ -20,7 +20,7 @@ configurable {
     /// The decimals of the asset minted by this contract.
     DECIMALS: u8 = 9u8,
     /// The name of the asset minted by this contract.
-    NAME: str[7] = __to_str_array("MyToken"),
+    NAME: str[7] = __to_str_array("MyAsset"),
     /// The symbol of the asset minted by this contract.
     SYMBOL: str[5] = __to_str_array("MYTKN"),
 }
@@ -31,13 +31,13 @@ storage {
 }
 
 impl SRC3 for Contract {
-    /// Unconditionally mints new tokens using the default SubId.
+    /// Unconditionally mints new assets using the default SubId.
     ///
     /// # Arguments
     ///
-    /// * `recipient`: [Identity] - The user to which the newly minted tokens are transferred to.
+    /// * `recipient`: [Identity] - The user to which the newly minted asset is transferred to.
     /// * `sub_id`: [SubId] - The default SubId.
-    /// * `amount`: [u64] - The quantity of tokens to mint.
+    /// * `amount`: [u64] - The quantity of coins to mint.
     ///
     /// # Number of Storage Accesses
     ///
@@ -70,12 +70,12 @@ impl SRC3 for Contract {
         mint_to(recipient, DEFAULT_SUB_ID, amount);
     }
 
-    /// Unconditionally burns tokens sent with the default SubId.
+    /// Unconditionally burns assets sent with the default SubId.
     ///
     /// # Arguments
     ///
     /// * `sub_id`: [SubId] - The default SubId.
-    /// * `amount`: [u64] - The quantity of tokens to burn.
+    /// * `amount`: [u64] - The quantity of coins to burn.
     ///
     /// # Number of Storage Accesses
     ///
@@ -85,7 +85,7 @@ impl SRC3 for Contract {
     /// # Reverts
     ///
     /// * When the `sub_id` is not the default SubId.
-    /// * When the transaction did not include at least `amount` tokens.
+    /// * When the transaction did not include at least `amount` coins.
     /// * When the transaction did not include the asset minted by this contract.
     ///
     /// # Examples

examples/src6-vault/multi_token_vault/Forc.toml

@@ -2,8 +2,8 @@
 authors = ["Fuel Labs <contact@fuel.sh>"]
 entry = "main.sw"
 license = "Apache-2.0"
-name = "multi_token_vault"
+name = "multi_asset_vault"
 
 [dependencies]
-src20 = { path = "../../../standards/src20-token" }
+src20 = { path = "../../../standards/src20-native-asset" }
 src6 = { path = "../../../standards/src6-vault" }

examples/src6-vault/multi_token_vault/src/main.sw

@@ -238,7 +238,7 @@ pub fn _burn(asset_id: AssetId, vault_sub_id: SubId, amount: u64) {
 
     require(
         this_balance(asset_id) >= amount,
-        "BurnError::NotEnoughTokens",
+        "BurnError::NotEnoughCoins",
     );
     // If we pass the check above, we can assume it is safe to unwrap.
     let supply = storage.total_supply.get(asset_id).try_read().unwrap();

examples/src6-vault/single_token_single_sub_vault/Forc.toml

@@ -2,8 +2,8 @@
 authors = ["Fuel Labs <contact@fuel.sh>"]
 entry = "main.sw"
 license = "Apache-2.0"
-name = "single_token_single_sub_vault"
+name = "single_asset_single_sub_vault"
 
 [dependencies]
-src20 = { path = "../../../standards/src20-token" }
+src20 = { path = "../../../standards/src20-native-asset" }
 src6 = { path = "../../../standards/src6-vault" }

examples/src6-vault/single_token_single_sub_vault/src/main.sw

@@ -21,7 +21,7 @@ use src20::SRC20;
 
 configurable {
     /// The only asset that can be deposited and withdrawn from this vault.
-    ACCEPTED_TOKEN: AssetId = BASE_ASSET_ID,
+    ACCEPTED_ASSET: AssetId = BASE_ASSET_ID,
     /// The only sub vault that can be deposited and withdrawn from this vault.
     ACCEPTED_SUB_VAULT: SubId = ZERO_B256,
     PRE_CALCULATED_SHARE_VAULT_SUB_ID: SubId = 0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b,
@@ -43,7 +43,7 @@ impl SRC6 for Contract {
         require(vault_sub_id == ACCEPTED_SUB_VAULT, "INVALID_vault_sub_id");
 
         let underlying_asset = msg_asset_id();
-        require(underlying_asset == ACCEPTED_TOKEN, "INVALID_ASSET_ID");
+        require(underlying_asset == ACCEPTED_ASSET, "INVALID_ASSET_ID");
 
         let asset_amount = msg_amount();
         require(asset_amount != 0, "ZERO_ASSETS");
@@ -77,7 +77,7 @@ impl SRC6 for Contract {
         underlying_asset: AssetId,
         vault_sub_id: SubId,
     ) -> u64 {
-        require(underlying_asset == ACCEPTED_TOKEN, "INVALID_ASSET_ID");
+        require(underlying_asset == ACCEPTED_ASSET, "INVALID_ASSET_ID");
         require(vault_sub_id == ACCEPTED_SUB_VAULT, "INVALID_vault_sub_id");
 
         let shares = msg_amount();
@@ -109,7 +109,7 @@ impl SRC6 for Contract {
 
     #[storage(read)]
     fn managed_assets(underlying_asset: AssetId, vault_sub_id: SubId) -> u64 {
-        if underlying_asset == ACCEPTED_TOKEN && vault_sub_id == ACCEPTED_SUB_VAULT {
+        if underlying_asset == ACCEPTED_ASSET && vault_sub_id == ACCEPTED_SUB_VAULT {
             // In this implementation managed_assets and max_withdrawable are the same. However in case of lending out of assets, managed_assets should be greater than max_withdrawable.
             storage.managed_assets.read()
         } else {
@@ -123,7 +123,7 @@ impl SRC6 for Contract {
         underlying_asset: AssetId,
         vault_sub_id: SubId,
     ) -> Option<u64> {
-        if underlying_asset == ACCEPTED_TOKEN {
+        if underlying_asset == ACCEPTED_ASSET {
             // This is the max value of u64 minus the current managed_assets. Ensures that the sum will always be lower than u64::MAX.
             Some(u64::max() - storage.managed_assets.read())
         } else {
@@ -133,7 +133,7 @@ impl SRC6 for Contract {
 
     #[storage(read)]
     fn max_withdrawable(underlying_asset: AssetId, vault_sub_id: SubId) -> Option<u64> {
-        if underlying_asset == ACCEPTED_TOKEN {
+        if underlying_asset == ACCEPTED_ASSET {
             // In this implementation managed_assets and max_withdrawable are the same. However in case of lending out of assets, managed_assets should be greater than max_withdrawable.
             Some(storage.managed_assets.read())
         } else {
@@ -210,7 +210,7 @@ pub fn _burn(asset_id: AssetId, amount: u64) {
 
     require(
         this_balance(asset_id) >= amount,
-        "BurnError::NotEnoughTokens",
+        "BurnError::NotEnoughCoins",
     );
     // If we pass the check above, we can assume it is safe to unwrap.
     let supply = storage.total_supply.read();

examples/src6-vault/single_token_vault/Forc.toml

@@ -2,8 +2,8 @@
 authors = ["Fuel Labs <contact@fuel.sh>"]
 entry = "main.sw"
 license = "Apache-2.0"
-name = "single_token_vault"
+name = "single_asset_vault"
 
 [dependencies]
-src20 = { path = "../../../standards/src20-token" }
+src20 = { path = "../../../standards/src20-native-asset" }
 src6 = { path = "../../../standards/src6-vault" }

examples/src6-vault/single_token_vault/src/main.sw

@@ -42,7 +42,7 @@ storage {
 
 configurable {
     /// The only asset that can be deposited and withdrawn from this vault.
-    ACCEPTED_TOKEN: AssetId = BASE_ASSET_ID,
+    ACCEPTED_ASSET: AssetId = BASE_ASSET_ID,
 }
 
 impl SRC6 for Contract {
@@ -52,7 +52,7 @@ impl SRC6 for Contract {
         let asset_amount = msg_amount();
         let underlying_asset = msg_asset_id();
 
-        require(underlying_asset == ACCEPTED_TOKEN, "INVALID_ASSET_ID");
+        require(underlying_asset == ACCEPTED_ASSET, "INVALID_ASSET_ID");
         let (shares, share_asset, share_asset_vault_sub_id) = preview_deposit(underlying_asset, vault_sub_id, asset_amount);
         require(asset_amount != 0, "ZERO_ASSETS");
 
@@ -126,7 +126,7 @@ impl SRC6 for Contract {
 
     #[storage(read)]
     fn managed_assets(underlying_asset: AssetId, vault_sub_id: SubId) -> u64 {
-        if underlying_asset == ACCEPTED_TOKEN {
+        if underlying_asset == ACCEPTED_ASSET {
             let vault_share_asset = vault_asset_id(underlying_asset, vault_sub_id).0;
             // In this implementation managed_assets and max_withdrawable are the same. However in case of lending out of assets, managed_assets should be greater than max_withdrawable.
             managed_assets(vault_share_asset)
@@ -141,7 +141,7 @@ impl SRC6 for Contract {
         underlying_asset: AssetId,
         vault_sub_id: SubId,
     ) -> Option<u64> {
-        if underlying_asset == ACCEPTED_TOKEN {
+        if underlying_asset == ACCEPTED_ASSET {
             // This is the max value of u64 minus the current managed_assets. Ensures that the sum will always be lower than u64::MAX.
             Some(u64::max() - managed_assets(underlying_asset))
         } else {
@@ -151,7 +151,7 @@ impl SRC6 for Contract {
 
     #[storage(read)]
     fn max_withdrawable(underlying_asset: AssetId, vault_sub_id: SubId) -> Option<u64> {
-        if underlying_asset == ACCEPTED_TOKEN {
+        if underlying_asset == ACCEPTED_ASSET {
             // In this implementation total_assets and max_withdrawable are the same. However in case of lending out of assets, total_assets should be greater than max_withdrawable.
             Some(managed_assets(underlying_asset))
         } else {
@@ -259,7 +259,7 @@ pub fn _burn(asset_id: AssetId, vault_sub_id: SubId, amount: u64) {
 
     require(
         this_balance(asset_id) >= amount,
-        "BurnError::NotEnoughTokens",
+        "BurnError::NotEnoughCoins",
     );
     // If we pass the check above, we can assume it is safe to unwrap.
     let supply = storage.total_supply.get(asset_id).try_read().unwrap();

examples/src7-metadata/multi_asset/Forc.toml

@@ -5,5 +5,5 @@ license = "Apache-2.0"
 name = "multi_src7_asset"
 
 [dependencies]
-src20 = { path = "../../../standards/src20-token" }
+src20 = { path = "../../../standards/src20-native-asset" }
 src7 = { path = "../../../standards/src7-metadata" }