Formalize Asset and Coin Terminology in Sway Libraries (#208)

## Type of change

<!--Delete points that do not apply-->

- Improvement (refactoring, restructuring repository, cleaning tech
debt, ...)

## Changes

The following changes have been made:

- This PR is a continuation of
FuelLabs/sway#5461 where the terms "Asset" and
"Coin" have been defined and formalized in the Sway lang

.docs/contributing-book/src/documentation/library-quality/documentation/specification.md

@@ -8,7 +8,7 @@ For simplicity, a specification can be broken into two levels of detail and the
 
 A non-technical specification is aimed at an audience that may not have the expertise in an area to appreciate the technical challenges involved in achieving the goals and thus it can be seen as an overview or summary.
 
-As an example, this may be a developer explaining how a user would interact with the user interface in order to send a coin / token to someone, without revealing the functionality behind signing a transaction and why a transaction may take some amount of time to be confirmed.
+As an example, this may be a developer explaining how a user would interact with the user interface in order to send a coin / asset to someone, without revealing the functionality behind signing a transaction and why a transaction may take some amount of time to be confirmed.
 
 This type of specification is simple so that any layperson can follow the basic concepts of the workflow.
 

README.md

@@ -33,7 +33,7 @@ These libraries contain helper functions and other tools valuable to blockchain
 
 #### Assets
 
-- [Token](./libs/token/) provides helper functions for the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20), [SRC-3](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_3), and [SRC-7](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_7) standards.
+- [Native Assets](./libs/native_assets/) provides helper functions for the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src20-native-asset), [SRC-3](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_3), and [SRC-7](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_7) standards.
 
 #### Access Control and Security
 

libs/Forc.toml

@@ -3,10 +3,10 @@ members = [
   "admin",
   "fixed_point",
   "merkle_proof",
+  "native_asset",
   "ownership",
   "pausable",
   "queue",
   "reentrancy",
   "signed_integers",
-  "token",
 ]

libs/merkle_proof/SPECIFICATION.md

@@ -6,7 +6,7 @@ It outlines the use cases, i.e. specification, and describes how to implement th
 
 # Use Cases
 
-A common use case for Merkle Tree verification is airdrops. An airdrop is a method of distribution a set amount of tokens to a specified number of users. These often include a list of addresses and amounts. By posting the root hash, users can provide a proof and claim their airdrop.
+A common use case for Merkle Tree verification is airdrops. An airdrop is a method of distribution a set amount of assets to a specified number of users. These often include a list of addresses and amounts. By posting the root hash, users can provide a proof and claim their airdrop.
 
 ## Public Functions
 

libs/token/Forc.toml → libs/native_asset/Forc.toml

@@ -2,7 +2,7 @@
 authors = ["Fuel Labs <[email protected]>"]
 entry = "lib.sw"
 license = "Apache-2.0"
-name = "token"
+name = "asset"
 
 [dependencies]
-src_7 = { git = "https://github.com/FuelLabs/sway-standards", tag = "v0.2.2" }
+src7 = { git = "https://github.com/FuelLabs/sway-standards", tag = "v0.3.3" }

libs/token/README.md → libs/native_asset/README.md

@@ -1,29 +1,29 @@
 <p align="center">
     <picture>
-        <source media="(prefers-color-scheme: dark)" srcset=".docs/token-logo-dark-theme.png">
-        <img alt="SwayApps logo" width="400px" src=".docs/token-logo-light-theme.png">
+        <source media="(prefers-color-scheme: dark)" srcset=".docs/asset-logo-dark-theme.png">
+        <img alt="SwayApps logo" width="400px" src=".docs/asset-logo-light-theme.png">
     </picture>
 </p>
 
 # Overview
 
-The Token library provides basic helper functions for the [SRC-20; Token Standard](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20), [SRC-3; Mint and Burn Standard](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_3), and the [SRC-7; Arbitrary Asset Metadata Standard](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_7). It is intended to make develpment of Native Assets using Sway quick and easy while following the standard's specifications.
+The Native Asset Library provides basic helper functions for the [SRC-20; Native Asset Standard](https://github.com/FuelLabs/sway-standards/tree/master/standards/src20-native-asset), [SRC-3; Mint and Burn Standard](https://github.com/FuelLabs/sway-standards/tree/master/standards/src3-mint-burn), and the [SRC-7; Arbitrary Asset Metadata Standard](https://github.com/FuelLabs/sway-standards/tree/master/standards/src7-metadata). It is intended to make develpment of Native Assets using Sway quick and easy while following the standard's specifications.
 
 For more information please see the [specification](./SPECIFICATION.md).
 
 # Using the Library
 
 ## Getting Started
 
-In order to use the Token library it must be added to the Forc.toml file and then imported into your Sway project. To add Sway-libs as a dependency to the Forc.toml file in your project please see the [README.md](../../README.md).
+In order to use the Native Asset Library it must be added to the Forc.toml file and then imported into your Sway project. To add Sway-libs as a dependency to the Forc.toml file in your project please see the [README.md](../../README.md).
 
-You may import the Token library's functionalities like so:
+You may import the Native Asset Library's functionalities like so:
 
 ```rust
-use token::*;
+use asset::*;
 ```
 
-Once imported, the Token library's functions should be available. To use them, be sure to add the storage block bellow to your contract which enables the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard.
+Once imported, the Native Asset Library's functions should be available. To use them, be sure to add the storage block bellow to your contract which enables the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src20-native-asset) standard.
 
 ```rust
 storage {
@@ -37,10 +37,10 @@ storage {
 
 ## Basic Functionality
 
-To use a function, simply pass the `StorageKey` from the prescribed storage block above. The example below shows the implementation of the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard in combination with the Token library with no user defined restrictions or custom functionality.
+To use a function, simply pass the `StorageKey` from the prescribed storage block above. The example below shows the implementation of the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src20-native-asset) standard in combination with the Native Asset Library with no user defined restrictions or custom functionality.
 
 ```rust
-use token::base::{
+use asset::base::{
     _total_assets, 
     _total_supply,
     _name,
@@ -88,4 +88,4 @@ impl SRC20 for Contract {
 
 For more information please see the [specification](./SPECIFICATION.md).
 
-> **NOTE** Until [Issue #5025](https://github.com/FuelLabs/sway/issues/5025) is resolved, in order to use the SRC-7 portion of the library, you must also add the [SRC-7](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_7) standard as a dependency.
+> **NOTE** Until [Issue #5025](https://github.com/FuelLabs/sway/issues/5025) is resolved, in order to use the SRC-7 portion of the library, you must also add the [SRC-7](https://github.com/FuelLabs/sway-standards/tree/master/standards/src7-metadata) standard as a dependency.

libs/token/SPECIFICATION.md → libs/native_asset/SPECIFICATION.md

@@ -1,12 +1,12 @@
 # Overview
 
-This document provides an overview of the Token library.
+This document provides an overview of the Native Asset Library.
 
 It outlines the use cases, i.e. specification, and describes how to implement the library.
 
 ## Use Cases
 
-The Token library can be used anytime a contract needs a basic implementation of the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) and [SRC-3](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_3) standards.
+The Native Asset Library can be used anytime a contract needs a basic implementation of the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) and [SRC-3](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_3) standards.
 
 ## Public Functions
 
@@ -18,7 +18,7 @@ This function will return the total number of individual assets for a contract.
 
 #### `_total_supply()`
 
-This function will return the total supply of tokens for an asset.
+This function will return the total supply of coins for an asset.
 
 #### `_name()`
 
@@ -48,11 +48,11 @@ This function will unconditionally set the decimals of an asset.
 
 #### `_mint()`
 
-This function will unconditionally mint new tokens using a sub-identifier.
+This function will unconditionally mint new assets using a sub-identifier.
 
 #### `_burn()`
 
-This function will burns tokens with the given sub-identifier.
+This function will burns assets with the given sub-identifier.
 
 ### SRC-7
 

libs/token/src/base.sw → libs/native_asset/src/base.sw

@@ -19,7 +19,7 @@ use std::{hash::{Hash, sha256}, storage::storage_string::*, string::String};
 /// # Examples
 ///
 /// ```sway
-/// use token::_total_assets;
+/// use asset::_total_assets;
 ///
 /// storage {
 ///     total_assets: u64 = 0,
@@ -35,7 +35,7 @@ pub fn _total_assets(total_assets_key: StorageKey<u64>) -> u64 {
     total_assets_key.try_read().unwrap_or(0)
 }
 
-/// Returns the total supply of tokens for an asset.
+/// Returns the total supply of coins for an asset.
 ///
 /// # Arguments
 ///
@@ -53,7 +53,7 @@ pub fn _total_assets(total_assets_key: StorageKey<u64>) -> u64 {
 /// # Examples
 ///
 /// ```sway
-/// use token::_total_supply;
+/// use asset::_total_supply;
 ///
 /// storage {
 ///     total_supply: StorageMap<AssetId, u64> = StorageMap {},
@@ -90,7 +90,7 @@ pub fn _total_supply(
 /// # Examples
 ///
 /// ```sway
-/// use token::_name;
+/// use asset::_name;
 /// use std::string::String;
 ///
 /// storage {
@@ -127,7 +127,7 @@ pub fn _name(
 /// # Examples
 ///
 /// ```sway
-/// use token::_symbol;
+/// use asset::_symbol;
 /// use std::string::String;
 ///
 /// storage {
@@ -150,7 +150,7 @@ pub fn _symbol(
 ///
 /// # Additional Information
 ///
-/// e.g. 8, means to divide the token amount by 100000000 to get its user representation.
+/// e.g. 8, means to divide the coins amount by 100000000 to get its user representation.
 ///
 /// # Arguments
 ///
@@ -168,7 +168,7 @@ pub fn _symbol(
 /// # Examples
 ///
 /// ```sway
-/// use token::_decimals;
+/// use asset::_decimals;
 ///
 /// storage {
 ///     decimals: StorageMap<AssetId, u8> = StorageMap {},
@@ -205,7 +205,7 @@ pub fn _decimals(
 /// # Examples
 ///
 /// ```sway
-/// use token::{_set_name, _name};
+/// use asset::{_set_name, _name};
 /// use std::string::String;
 ///
 /// storage {
@@ -246,7 +246,7 @@ pub fn _set_name(
 /// # Examples
 ///
 /// ```sway
-/// use token::{_set_symbol, _symbol};
+/// use asset::{_set_symbol, _symbol};
 /// use std::string::String;
 ///
 /// storage {
@@ -287,7 +287,7 @@ pub fn _set_symbol(
 /// # Examples
 ///
 /// ```sway
-/// use token::{_set_decimals, _decimals};
+/// use asset::{_set_decimals, _decimals};
 /// use std::string::String;
 ///
 /// storage {
@@ -308,7 +308,7 @@ pub fn _set_decimals(
 ) {
     decimals_key.insert(asset, decimals);
 }
-abi SetTokenAttributes {
+abi SetAssetAttributes {
     #[storage(write)]
     fn set_name(asset: AssetId, name: String);
     #[storage(write)]

libs/native_asset/src/errors.sw

@@ -0,0 +1,7 @@
+library;
+
+/// Error log for when something goes wrong when burning assets.
+pub enum BurnError {
+    /// Emitted when there are not enough coins owned by the contract to burn.
+    NotEnoughCoins: (),
+}

libs/token/src/metadata.sw → libs/native_asset/src/metadata.sw

@@ -1,6 +1,6 @@
 library;
 
-use src_7::Metadata;
+use src7::Metadata;
 use std::{
     bytes::Bytes,
     hash::{
@@ -42,7 +42,7 @@ impl StorageKey<StorageMetadata> {
     ///
     /// ```sway
     /// use src_7::Metadata;
-    /// use token::metdata::*;
+    /// use asset::metadata::*;
     ///
     /// storage {
     ///     metadata: StorageMetadata = StorageMetadata {}
@@ -97,7 +97,7 @@ impl StorageKey<StorageMetadata> {
     ///
     /// ```sway
     /// use src_7::Metadata;
-    /// use token::metdata::*;
+    /// use asset::metadata::*;
     ///
     /// storage {
     ///     metadata: StorageMetadata = StorageMetadata {}
@@ -149,7 +149,7 @@ impl StorageKey<StorageMetadata> {
 ///
 /// ```sway
 /// use src_7::Metadata;
-/// use token::metdata::*;
+/// use asset::metadata::*;
 ///
 /// storage {
 ///     metadata: StorageMetadata = StorageMetadata {}
@@ -169,7 +169,7 @@ pub fn _set_metadata(
     metadata_key.insert(asset, key, metadata);
 }
 
-abi SetTokenMetadata {
+abi SetAssetMetadata {
     #[storage(read, write)]
     fn set_metadata(asset: AssetId, key: String, metadata: Metadata);
 }
@@ -185,7 +185,7 @@ impl Metadata {
     ///
     /// ```sway
     /// use std::string::String;
-    /// use token::src_7::*;
+    /// use asset::metadata::*;
     /// use src_7::{SRC7, Metadata};
     ///
     /// fn foo(contract_id: ContractId, asset: AssetId, key: String) {
@@ -213,7 +213,7 @@ impl Metadata {
     ///
     /// ```sway
     /// use std::string::String;
-    /// use token::src_7::*;
+    /// use asset::metadata::*;
     /// use src_7::{SRC7, Metadata};
     ///
     /// fn foo(contract_id: ContractId, asset: AssetId, key: String) {
@@ -240,7 +240,7 @@ impl Metadata {
     ///
     /// ```sway
     /// use std::string::String;
-    /// use token::src_7::*;
+    /// use asset::metadata::*;
     /// use src_7::{SRC7, Metadata};
     ///
     /// fn foo(contract_id: ContractId, asset: AssetId, key: String) {
@@ -268,7 +268,7 @@ impl Metadata {
     ///
     /// ```sway
     /// use std::string::String;
-    /// use token::src_7::*;
+    /// use asset::metadata::*;
     /// use src_7::{SRC7, Metadata};
     ///
     /// fn foo(contract_id: ContractId, asset: AssetId, key: String) {
@@ -295,7 +295,7 @@ impl Metadata {
     ///
     /// ```sway
     /// use std::{bytes::Bytes, string::String};
-    /// use token::src_7::*;
+    /// use asset::metadata::*;
     /// use src_7::{SRC7, Metadata};
     ///
     /// fn foo(contract_id: ContractId, asset: AssetId, key: String) {
@@ -323,7 +323,7 @@ impl Metadata {
     ///
     /// ```sway
     /// use std::{bytes::Bytes, string::String};
-    /// use token::src_7::*;
+    /// use asset::metadata::*;
     /// use src_7::{SRC7, Metadata};
     ///
     /// fn foo(contract_id: ContractId, asset: AssetId, key: String) {
@@ -350,7 +350,7 @@ impl Metadata {
     ///
     /// ```sway
     /// use std::{constants::ZERO_B256, string::String};
-    /// use token::src_7::*;
+    /// use asset::metadata::*;
     /// use src_7::{SRC7, Metadata};
     ///
     /// fn foo(contract_id: ContractId, asset: AssetId, key: String) {
@@ -378,7 +378,7 @@ impl Metadata {
     ///
     /// ```sway
     /// use std::string::String;
-    /// use token::src_7::*;
+    /// use asset::metadata::*;
     /// use src_7::{SRC7, Metadata};
     ///
     /// fn foo(contract_id: ContractId, asset: AssetId, key: String) {