Merge branch 'master' into ps/chore/upgrade-fuel-core-to-0.28.0

.changeset/gold-rice-burn.md

@@ -0,0 +1,2 @@
+---
+---

apps/docs-snippets/src/guide/contracts/minted-token-asset-id.test.ts

@@ -0,0 +1,33 @@
+import type { Contract } from 'fuels';
+import { bn, getMintedAssetId } from 'fuels';
+
+import { DocSnippetProjectsEnum } from '../../../test/fixtures/forc-projects';
+import { createAndDeployContractFromProject } from '../../utils';
+
+/**
+ * @group node
+ */
+describe(__filename, () => {
+  let contract: Contract;
+
+  beforeAll(async () => {
+    contract = await createAndDeployContractFromProject(DocSnippetProjectsEnum.TOKEN);
+  });
+
+  it('should successfully execute contract call with forwarded amount', async () => {
+    // #region minted-token-asset-id-2
+    // #import { bn, getMintedAssetId };
+
+    // Any valid bits256 string can be used as a sub ID
+    const subID = '0xc7fd1d987ada439fc085cfa3c49416cf2b504ac50151e3c2335d60595cb90745';
+    const mintAmount = bn(1000);
+
+    const txResult = await contract.functions.mint_coins(subID, mintAmount).call();
+
+    const mintedAssetId = getMintedAssetId(subID, contract.id.toB256());
+    // #endregion minted-token-asset-id-2
+
+    expect(mintedAssetId).toBeDefined();
+    expect(txResult.transactionResult.isStatusSuccess).toBeTruthy();
+  });
+});

apps/docs-snippets/test/fixtures/forc-projects/token/src/main.sw

@@ -1,3 +1,4 @@
+// #region minted-token-asset-id-1
 contract;
 
 use std::asset::{burn, mint, transfer};
@@ -27,3 +28,4 @@ impl Token for Contract {
         burn(sub_id, burn_amount);
     }
 }
+// #endregion minted-token-asset-id-1

apps/docs/.vitepress/config.ts

@@ -235,6 +235,10 @@ export default defineConfig({
                 text: 'Configurable Constants',
                 link: '/guide/contracts/configurable-constants',
               },
+              {
+                text: 'Minted Token Asset ID',
+                link: '/guide/contracts/minted-token-asset-id',
+              },
               {
                 text: 'Managing Deployed Contracts',
                 link: '/guide/contracts/managing-deployed-contracts',

apps/docs/src/guide/contracts/minted-token-asset-id.md

@@ -0,0 +1,20 @@
+# Minted Token Asset ID
+
+The asset ID of a token on the Fuel network is determined by two factors:
+
+- The ID of the contract that minted the token,
+- A sub-identifier (Sub ID)
+
+> Both of which are [bits256](../types/bits256.md) strings.
+
+The process involves applying a SHA-256 hash algorithm to the combination of the Contract ID and the Sub ID, to derive an Asset ID - as explained [here](https://docs.fuel.network/docs/specs/identifiers/asset/#asset-id).
+
+Consider the following simplified token contract:
+
+<<< @/../../docs-snippets/test/fixtures/forc-projects/token/src/main.sw#minted-token-asset-id-1{rs:line-numbers}
+
+Imagine that this contract is already deployed and we are about to mint some coins:
+
+<<< @/../../docs-snippets/src/guide/contracts/minted-token-asset-id.test.ts#minted-token-asset-id-2{ts:line-numbers}
+
+Since the asset ID depends on the contract ID, which is always dynamic (unlike the sub ID, which can be set to a fixed value), the helper `getMintedAssetId` can be used to easily obtain the asset ID for a given contract ID and sub ID.