diff --git a/CHANGELOG.md b/CHANGELOG.md index a248bf6..b5dae55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,8 +24,19 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ### Breaking Unreleased -- Some breaking change here 1 -- Some breaking change here 2 +- [#131](https://github.com/FuelLabs/sway-standards/pull/131) Makes the SRC-3 `mint()` function's `SubId` argument an `Option`. + +Before: + +```sway +mint(Identity::Address(Address::zero()), SubId::zero(), 100); +``` + +After: + +```sway +mint(Identity::Address(Address::zero()), Some(SubId::zero()), 100); +``` ## [Version 0.5.2] diff --git a/docs/src/src-3-minting-and-burning.md b/docs/src/src-3-minting-and-burning.md index 53fd352..c36b177 100644 --- a/docs/src/src-3-minting-and-burning.md +++ b/docs/src/src-3-minting-and-burning.md @@ -16,15 +16,16 @@ Minting and burning were initially added to the [SRC-20](./src-20-native-asset.m The following functions MUST be implemented to follow the SRC-3 standard: -#### `fn mint(recipient: Identity, sub_id: SubId, amount: u64)` +#### `fn mint(recipient: Identity, sub_id: Option, amount: u64)` -This function MUST mint `amount` coins with sub-identifier `sub_id` and transfer them to the `recipient`. +This function MUST mint `amount` coins with a sub-identifier and transfer them to the `recipient`. +This function MUST use the `sub_id` as the sub-identifier IF `sub_id` is `Some`, otherwise this function MUST assign a `SubId` if the `sub_id` argument is `None`. This function MAY contain arbitrary conditions for minting, and revert if those conditions are not met. ##### Mint Arguments * `recipient` - The `Identity` to which the newly minted asset is transferred to. -* `sub_id` - The sub-identifier of the asset to mint. +* `sub_id` - The sub-identifier of the asset to mint. If this is `None`, a `SubId` MUST be assigned. * `amount` - The quantity of coins to mint. #### `fn burn(sub_id: SubId, amount: u64)` @@ -57,7 +58,7 @@ The burn function may also introduce a security consideration if the total suppl ```sway abi MySRC3Asset { #[storage(read, write)] - fn mint(recipient: Identity, sub_id: SubId, amount: u64); + fn mint(recipient: Identity, sub_id: Option, amount: u64); #[payable] #[storage(read, write)] fn burn(sub_id: SubId, amount: u64); diff --git a/examples/src3-mint-burn/multi_asset/src/multi_asset.sw b/examples/src3-mint-burn/multi_asset/src/multi_asset.sw index b8af9ba..673b536 100644 --- a/examples/src3-mint-burn/multi_asset/src/multi_asset.sw +++ b/examples/src3-mint-burn/multi_asset/src/multi_asset.sw @@ -7,6 +7,7 @@ use std::{ mint_to, }, call_frames::msg_asset_id, + constants::DEFAULT_SUB_ID, context::msg_amount, hash::Hash, storage::storage_string::*, @@ -36,7 +37,7 @@ impl SRC3 for Contract { /// # Arguments /// /// * `recipient`: [Identity] - The user to which the newly minted asset is transferred to. - /// * `sub_id`: [SubId] - The sub-identifier of the newly minted asset. + /// * `sub_id`: [Option] - The sub-identifier of the newly minted asset. /// * `amount`: [u64] - The quantity of coins to mint. /// /// # Number of Storage Accesses @@ -52,11 +53,15 @@ impl SRC3 for Contract { /// /// fn foo(contract_id: ContractId) { /// let contract_abi = abi(SRC3, contract_id); - /// contract_abi.mint(Identity::ContractId(contract_id), DEFAULT_SUB_ID, 100); + /// contract_abi.mint(Identity::ContractId(contract_id), Some(DEFAULT_SUB_ID), 100); /// } /// ``` #[storage(read, write)] - fn mint(recipient: Identity, sub_id: SubId, amount: u64) { + fn mint(recipient: Identity, sub_id: Option, amount: u64) { + let sub_id = match sub_id { + Some(s) => s, + None => DEFAULT_SUB_ID, + }; let asset_id = AssetId::new(ContractId::this(), sub_id); // If this SubId is new, increment the total number of distinguishable assets this contract has minted. diff --git a/examples/src3-mint-burn/single_asset/src/single_asset.sw b/examples/src3-mint-burn/single_asset/src/single_asset.sw index d21b31c..41360a2 100644 --- a/examples/src3-mint-burn/single_asset/src/single_asset.sw +++ b/examples/src3-mint-burn/single_asset/src/single_asset.sw @@ -52,12 +52,17 @@ impl SRC3 for Contract { /// /// fn foo(contract_id: ContractId) { /// let contract_abi = abi(SRC3, contract); - /// contract_abi.mint(Identity::ContractId(contract_id), DEFAULT_SUB_ID, 100); + /// contract_abi.mint(Identity::ContractId(contract_id), Some(DEFAULT_SUB_ID), 100); /// } /// ``` #[storage(read, write)] - fn mint(recipient: Identity, sub_id: SubId, amount: u64) { - require(sub_id == DEFAULT_SUB_ID, "Incorrect Sub Id"); + fn mint(recipient: Identity, sub_id: Option, amount: u64) { + require( + sub_id + .is_some() && sub_id + .unwrap() == DEFAULT_SUB_ID, + "Incorrect Sub Id", + ); // Increment total supply of the asset and mint to the recipient. storage diff --git a/standards/src/src3.sw b/standards/src/src3.sw index faeb870..8f1b927 100644 --- a/standards/src/src3.sw +++ b/standards/src/src3.sw @@ -6,7 +6,7 @@ abi SRC3 { /// # Arguments /// /// * `recipient`: [Identity] - The user to which the newly minted asset is transferred to. - /// * `sub_id`: [SubId] - The sub-identifier of the newly minted asset. + /// * `sub_id`: [Option] - The sub-identifier of the newly minted asset. /// * `amount`: [u64] - The quantity of coins to mint. /// /// # Examples @@ -20,7 +20,7 @@ abi SRC3 { /// } /// ``` #[storage(read, write)] - fn mint(recipient: Identity, sub_id: SubId, amount: u64); + fn mint(recipient: Identity, sub_id: Option, amount: u64); /// Burns assets sent with the given `sub_id`. ///