Introduce the Token Library (#190)

## Type of change

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

- New feature

## Changes

The following changes have been made:

- Creates token library that enables developers to quickly spin up
SRC-20 compliant tokens

## Notes

- The standards themselves will need to be merged and the Forc.toml
files updates before this PR can be merged
FuelLabs/sway-standards#16
FuelLabs/sway-standards#13

## Related Issues

<!--Delete everything after the "#" symbol and replace it with a number.
No spaces between hash and number-->

Closes #187

---------

Co-authored-by: bitzoic <[email protected]>

.github/workflows/ci.yml

@@ -73,7 +73,7 @@ jobs:
           run: |
             cargo test --manifest-path tests/Cargo.toml
 
-  forc-unit-tests:
+  forc-inline-tests:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -95,9 +95,12 @@ jobs:
           name: my-toolchain
           components: forc@${{ env.FORC_VERSION }}, fuel-core@${{ env.CORE_VERSION }}
 
-      - name: Run Unit Tests
+      - name: Run Libs Tests
         run: forc build --path libs && forc test --path libs
 
+      - name: Run Tests Tests
+        run: forc build --path tests && forc test --path tests
+
   contributing-book:
     runs-on: ubuntu-latest
 

README.md

@@ -37,6 +37,7 @@ These libraries contain helper functions and other tools valuable to blockchain
 - [Signed Integers](./libs/signed_integers/) is an interface to implement signed integers.
 - [Fixed Point Number](./libs/fixed_point/) is an interface to implement fixed-point numbers.
 - [Queue](./libs/queue/) is a linear data structure that provides First-In-First-Out (FIFO) operations. 
+- [Token](./libs/token/) is 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.
 
 ## Using a library
 

libs/Forc.toml

@@ -6,4 +6,5 @@ members = [
   "queue",
   "reentrancy",
   "signed_integers",
+  "token",
 ]

libs/token/Forc.toml

@@ -0,0 +1,5 @@
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "lib.sw"
+license = "Apache-2.0"
+name = "token"

libs/token/README.md

@@ -0,0 +1,89 @@
+<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">
+    </picture>
+</p>
+
+# Overview
+
+The Token library provides basic function implementations of the [SRC-20; Token Standard](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) and the [SRC-3; Mint and Burn Standard](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_3). 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).
+
+You may import the Token library's functionalities like so:
+
+```rust
+use token::*;
+```
+
+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.
+
+```rust
+storage {
+    total_assets: u64 = 0,
+    total_supply: StorageMap<AssetId, u64> = StorageMap {},
+    name: StorageMap<AssetId, StorageKey<StorageString>> = StorageMap {},
+    symbol: StorageMap<AssetId, StorageKey<StorageString>> = StorageMap {},
+    decimals: StorageMap<AssetId, u8> = StorageMap {},
+}
+```
+
+## 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.
+
+```rust
+use token::{
+    _total_assets, 
+    _total_supply,
+    _name,
+    _symbol,
+    _decimals
+};
+use src_20::SRC20;
+use std::string::String;
+
+storage {
+    total_assets: u64 = 0,
+    total_supply: StorageMap<AssetId, u64> = StorageMap {},
+    name: StorageMap<AssetId, StorageKey<StorageString>> = StorageMap {},
+    symbol: StorageMap<AssetId, StorageKey<StorageString>> = StorageMap {},
+    decimals: StorageMap<AssetId, u8> = StorageMap {},
+}
+
+impl SRC20 for Contract {
+    #[storage(read)]
+    fn total_assets() -> u64 {
+        _total_assets(storage.total_assets)
+    }
+
+    #[storage(read)]
+    fn total_supply(asset: AssetId) -> Option<u64> {
+        _total_supply(storage.total_supply, asset)
+    }
+
+    #[storage(read)]
+    fn name(asset: AssetId) -> Option<String> {
+        _name(storage.name, asset)
+    }
+
+    #[storage(read)]
+    fn symbol(asset: AssetId) -> Option<String> {
+        _symbol(storage.symbol, asset)
+    }
+
+    #[storage(read)]
+    fn decimals(asset: AssetId) -> Option<u8> {
+        _decimals(storage.decimals, asset)
+    }
+}
+```
+
+For more information please see the [specification](./SPECIFICATION.md).

libs/token/SPECIFICATION.md

@@ -0,0 +1,51 @@
+# Overview
+
+This document provides an overview of the Token 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.
+
+## Public Functions
+
+### `_total_assets()`
+
+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.
+
+### `_name()`
+
+This function will return the name of an asset, such as “Ether”.
+
+### `_symbol()`
+
+This function will return the symbol of an asset, such as “ETH”.
+
+### `_decimals()`
+
+This function will return the number of decimals an asset uses.
+
+### `_mint()`
+
+This function will unconditionally mint new tokens using a sub-identifier.
+
+### `_burn()`
+
+This function will burns tokens with the given sub-identifier.
+
+### `_set_name()`
+
+This function will unconditionally set the name of an asset.
+
+### `_set_symbol()`
+
+This function will unconditionally set the symbol of an asset.
+
+### `_set_decimals`
+
+This function will unconditionally set the decimals of an asset.

libs/token/src/errors.sw

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