chore: implement a helper createAssetId function (#2665)

* draft: included a new createAssetId fn in receipt; added documentation

* chore: implemented tests for new createAssetId function

* docs: improved documentation for obtaining and minting new asset

* docs: replaced source code reference for createAssetId docs

* docs: improved create assetId docs; updated spell checks

* chore: added missing changeset package

* chore: fixed test

---------

Co-authored-by: Anderson Arboleya <anderson@arboleya.me>
Co-authored-by: Sérgio Torres <30977845+Torres-ssf@users.noreply.github.com>
Co-authored-by: Peter Smith <peter@blueoceancomputing.co.uk>

.changeset/free-birds-soar.md

@@ -0,0 +1,5 @@
+---
+"@fuel-ts/transactions": patch
+---
+
+chore: implement a helper createAssetId function

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

@@ -1,7 +1,8 @@
-import { bn, getMintedAssetId } from 'fuels';
+import type { AssetId } from 'fuels';
+import { bn, getMintedAssetId, createAssetId } from 'fuels';
 import { launchTestNode } from 'fuels/test-utils';
 
-import { TokenFactory } from '../../../test/typegen';
+import { EchoAssetIdFactory, TokenFactory } from '../../../test/typegen';
 
 /**
  * @group node
@@ -32,4 +33,26 @@ describe(__filename, () => {
     expect(mintedAssetId).toBeDefined();
     expect(txResult.transactionResult.isStatusSuccess).toBeTruthy();
   });
+
+  it('should create valid asset ID', async () => {
+    using launched = await launchTestNode({
+      contractsConfigs: [{ factory: EchoAssetIdFactory }],
+    });
+
+    const {
+      contracts: [contract],
+    } = launched;
+
+    // #region create-asset-id-1
+    // #import { createAssetId, AssetId };
+
+    const subID = '0xc7fd1d987ada439fc085cfa3c49416cf2b504ac50151e3c2335d60595cb90745';
+
+    const assetId: AssetId = createAssetId(contract.id.toB256(), subID);
+    // #endregion create-asset-id-1
+    const { value } = await contract.functions.echo_asset_id_input(assetId).simulate();
+
+    expect(assetId).toBeDefined();
+    expect(value).toEqual(assetId);
+  });
 });

apps/docs-snippets/test/fixtures/forc-projects/echo-asset-id/src/main.sw

@@ -4,6 +4,7 @@ contract;
 abi EvmTest {
     fn echo_asset_id() -> AssetId;
     fn echo_asset_id_comparison(asset_id: AssetId) -> bool;
+    fn echo_asset_id_input(asset_id: AssetId) -> AssetId;
 }
 
 const ASSET_ID: AssetId = AssetId::from(0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c);
@@ -16,5 +17,9 @@ impl EvmTest for Contract {
     fn echo_asset_id_comparison(asset_id: AssetId) -> bool {
         asset_id == ASSET_ID
     }
+
+    fn echo_asset_id_input(asset_id: AssetId) -> AssetId {
+        asset_id
+    }
 }
 // #endregion asset-id-1

apps/docs/spell-check-custom-words.txt

@@ -1,6 +1,7 @@
 ABI
 ABIs
 ASM
+AssetId
 IDE
 IDEs
 LSP

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

@@ -17,4 +17,12 @@ Imagine that this contract is already deployed and we are about to mint some coi
 
 <<< @/../../docs-snippets/src/guide/contracts/minted-token-asset-id.test.ts#minted-token-asset-id-2{ts:line-numbers}
 
+## Obtaining the Asset ID
+
 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.
+
+## Create Asset Id
+
+The SDK provides a helper named `createAssetId` which takes the contract ID and sub ID as parameters. This helper internally calls `getMintedAssetId` and returns the Sway native parameter [AssetId](https://docs.fuel.network/docs/fuels-ts/interfaces/#assetid), ready to be used in a Sway program invocation:
+
+<<< @/../../docs-snippets/src/guide/contracts/minted-token-asset-id.test.ts#create-asset-id-1{ts:line-numbers}

packages/transactions/src/coders/receipt.ts

@@ -2,6 +2,7 @@
 import { Coder, BigNumberCoder, B256Coder, NumberCoder } from '@fuel-ts/abi-coder';
 import { ErrorCode, FuelError } from '@fuel-ts/errors';
 import { sha256 } from '@fuel-ts/hasher';
+import type { AssetId } from '@fuel-ts/interfaces';
 import type { BN } from '@fuel-ts/math';
 import { arrayify, concat } from '@fuel-ts/utils';
 
@@ -774,6 +775,10 @@ export const getMintedAssetId = (contractId: string, subId: string): string => {
   return sha256(concat([contractIdBytes, subIdBytes]));
 };
 
+export const createAssetId = (contractId: string, subId: string): AssetId => ({
+  bits: getMintedAssetId(contractId, subId),
+});
+
 export class ReceiptMintCoder extends Coder<ReceiptMint, ReceiptMint> {
   constructor() {
     super('ReceiptMint', 'struct ReceiptMint', 0);