diff --git a/README.md b/README.md index eca6fea..00b619c 100644 --- a/README.md +++ b/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 diff --git a/standards/Forc.toml b/standards/Forc.toml index 6982908..0ca2b5e 100644 --- a/standards/Forc.toml +++ b/standards/Forc.toml @@ -1,2 +1,2 @@ [workspace] -members = ["src_5", "src_20"] +members = ["src_3", "src_5", "src_20"] diff --git a/standards/src_3/Forc.toml b/standards/src_3/Forc.toml new file mode 100644 index 0000000..a6fd513 --- /dev/null +++ b/standards/src_3/Forc.toml @@ -0,0 +1,5 @@ +[project] +authors = ["Fuel Labs "] +entry = "src_3.sw" +license = "Apache-2.0" +name = "src_3" diff --git a/standards/src_3/README.md b/standards/src_3/README.md new file mode 100644 index 0000000..a23f633 --- /dev/null +++ b/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`. \ No newline at end of file diff --git a/standards/src_3/src/src_3.sw b/standards/src_3/src/src_3.sw new file mode 100644 index 0000000..987be34 --- /dev/null +++ b/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); +}