Merge pull request #16 from FuelLabs/src-3-mint-burn-standard

SRC-3 Mint and Burn Standard

README.md

@@ -35,6 +35,7 @@ If you don't find what you're looking for, feel free to create an issue and prop
 
 - [SRC-20; Token Standard](./standards/src_20/) defines the implementation of a standard API for [Native Assets](https://fuellabs.github.io/sway/v0.44.0/book/blockchain-development/native_assets.html) using the Sway Language.
 - [SRC-2; Inline Documentation](./standards/src_2/) defines how to document your Sway files.
+- [SRC-3; Mint and Burn](./standards/src_3/) is used to enabling mint and burn functionality for Native Assets.
 - [SRC-5; Ownership Standard](./standards/src_5/) is used to restrict function calls to admin users in contracts.
 
 ## Using a standard

standards/Forc.toml

@@ -1,2 +1,2 @@
 [workspace]
-members = ["src_5", "src_20"]
+members = ["src_3", "src_5", "src_20"]

standards/src_3/Forc.toml

@@ -0,0 +1,5 @@
+[project]
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "src_3.sw"
+license = "Apache-2.0"
+name = "src_3"

standards/src_3/README.md

@@ -0,0 +1,66 @@
+### Motivation
+
+# Abstract
+
+The following standard enables the minting and burning of tokens for any fungible assets within the Sway Language. It seeks to define mint and burn functions defined separately from the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard. Any contract that implements the SRC-3 standard MUST implement the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard.
+
+# Motivation
+
+The intent of this standard is to separate the extensions of minting and burning from the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard.
+
+# Prior Art
+
+Minting and burning were initially added to the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard.
+
+# Specification
+
+## Required Public Functions
+
+The following functions MUST be implemented to follow the SRC-3 standard:
+
+### `fn mint(recipient: Identity, sub_id: SubId, amount: u64)`
+
+This function MUST mint `amount` tokens with sub-identifier `sub_id` and transfer them to the `recipient`. 
+This function MAY contain arbitrary conditions for minting, and revert if those conditions are not met.
+
+##### Arguments
+
+* `recipient` - The `Identity` to which the newly minted tokens are transferred to.
+* `sub_id` - The sub-identifier of the asset to mint.
+* `amount` - The quantity of tokens to mint.
+
+### `fn burn(sub_id: SubId, amount: u64)`
+
+This function MUST burn `amount` tokens with the sub-identifier `sub_id` and MUST ensure the `AssetId` of the token is the sha-256 hash of `(ContractId, SubId)` for the implementing contract. 
+This function MUST ensure at least `amount` tokens have been transfered to the implementing contract. 
+This function MUST update the total supply defined in the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard. 
+This function MAY contain arbitrary conditions for burning, and revert if those conditions are not met.
+
+##### Arguments
+
+* `sub_id` - The sub-identifier of the asset to burn.
+* `amount` - The quantity of tokens to burn.
+
+# Rationale
+
+This standard has been added to enable compatibility between applications and allow minting and burning tokens per use case. This standard has been separated from the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard to allow for the minting and burning for all fungible tokens, irrelevant of whether they are [Native Assets](https://fuellabs.github.io/sway/v0.44.1/book/blockchain-development/native_assets.html) or not.
+
+# Backwards Compatibility
+
+This standard is compatible with Fuel's [Native Assets](https://fuellabs.github.io/sway/v0.38.0/book/blockchain-development/native_assets.html) ensuring it's compatibility with the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard.
+
+# Security Considerations
+
+This standard may introduce security considerations if no checks are implemented to ensure the calling of the `mint()` function is deemed valid or permitted. Checks are highly encouraged.
+The burn function may also introduce a security consideration if the total supply within the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20) standard is not modified.
+
+# Example ABI
+
+```rust
+abi MySRC3Token {
+    fn mint(recipient: Identity, sub_id: SubId, amount: u64);
+    fn burn(sub_id: SubId, amount: u64);
+}
+```
+
+This draft standard is to be released as `v0.1`. 

standards/src_3/src/src_3.sw

@@ -0,0 +1,53 @@
+library;
+
+abi SRC3 {
+    /// Mints new tokens 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.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src3::SRC3;
+    ///
+    /// fn foo(contract: ContractId) {
+    ///     let contract_abi = abi(SR3, contract);
+    ///     contract_abi.mint(Identity::ContractId(this_contract()), ZERO_B256, 100);
+    /// }
+    /// ```
+    #[storage(read, write)]
+    fn mint(recipient: Identity, sub_id: SubId, amount: u64);
+
+    /// Burns tokens sent with the given `sub_id`.
+    ///
+    /// # Additional Information
+    ///
+    /// NOTE: The sha-256 hash of `(ContractId, SubId)` must match the `AssetId` where `ContractId` is the id of
+    /// the implementing contract and `SubId` is the given `sub_id` argument.
+    ///
+    /// # Arguments
+    ///
+    /// * `sub_id`: [SubId] - The sub-identifier of the token to burn.
+    /// * `amount`: [u64] - The quantity of tokens to burn.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src3::SRC3;
+    ///
+    /// fn foo(contract: ContractId, asset_id: AssetId) {
+    ///     let contract_abi = abi(SR3, contract);
+    ///     contract_abi {
+    ///         gas: 10000,
+    ///         coins: 100,
+    ///         asset_id: AssetId,
+    ///     }.burn(ZERO_B256, 100);
+    /// }
+    /// ```
+    #[storage(read, write)]
+    fn burn(sub_id: SubId, amount: u64);
+}