Make the SubId an Option in SRC-3's mint() function (#131)

* Update specifications to change SRC-3 mint sub_id to an Option

* Update SRC-3 standard for option in mint

* Update examples

* Udpate CHANGELOG

* Run formatter

* Fix spelling

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]
 

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<SubId>, 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<SubId>, amount: u64);
     #[payable]
     #[storage(read, write)]
     fn burn(sub_id: SubId, amount: u64);

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<SubId>] - 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<SubId>, 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.

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<SubId>, 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

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<SubId>] - 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<SubId>, amount: u64);
 
     /// Burns assets sent with the given `sub_id`.
     ///