feat(tx-construction): add fluent minting to the transaction builder

Add `TxBuilder.addMint({ policy, assets, redeemer })` so consumers can mint or
burn assets under a policy without dropping to the lower-level `initializeTx`.
The policy script is attached to the witness set, the asset quantities are added
to the body, and (for Plutus policies) the redeemer is included and its execution
units evaluated during `build()`. Previously `GenericTxBuilder` had no minting
support — `mint` was never forwarded to `initializeTx`.

This also fixes redeemer index reconciliation for non-spend purposes: builder
redeemers are stamped with a sentinel index by `buildRedeemers`, but
`reorgRedeemers` only reindexed spend redeemers, so mint/withdrawal/certificate
redeemers reached `updateRedeemers` with an index the evaluator could not match.
Sentinel-indexed non-spend redeemers are now reindexed by their position within
their purpose; redeemers that already carry a concrete index are left untouched.

Coverage: unit tests for plutus mint, burn (negative quantity), native-script
mint without a redeemer, and multi-policy redeemer reindexing; plus an e2e test
that mints through the builder and submits. The `web-extension` remote-api
property map gains the new method.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rhyslbw

packages/e2e/test/wallet_epoch_0/PersonalWallet/mint.test.ts

@@ -1,6 +1,5 @@
-import { BaseWallet, FinalizeTxProps } from '@cardano-sdk/wallet';
+import { BaseWallet } from '@cardano-sdk/wallet';
 import { Cardano, nativeScriptPolicyId } from '@cardano-sdk/core';
-import { InitializeTxProps } from '@cardano-sdk/tx-construction';
 import { KeyRole, util } from '@cardano-sdk/key-management';
 import {
   bip32Ed25519Factory,
@@ -66,38 +65,16 @@ describe('PersonalWallet/mint', () => {
 
     const policyId = nativeScriptPolicyId(policyScript);
     const assetId = Cardano.AssetId(`${policyId}`); // skip asset name
-    const tokens = new Map([[assetId, 1n]]);
 
-    const walletAddress = (await firstValueFrom(wallet.addresses$))[0].address;
+    // Mint through the fluent transaction builder. The minted asset is balanced into the wallet's
+    // change; the policy requires Alice's signature, supplied as an extra signer.
+    const { tx: signedTx } = await wallet
+      .createTxBuilder()
+      .addMint({ assets: new Map([[Cardano.AssetName(''), 1n]]), policy: policyScript })
+      .extraSigners([alicePolicySigner])
+      .build()
+      .sign();
 
-    const txProps: InitializeTxProps = {
-      mint: tokens,
-      outputs: new Set([
-        {
-          address: walletAddress,
-          value: {
-            assets: tokens,
-            coins
-          }
-        }
-      ]),
-      signingOptions: {
-        extraSigners: [alicePolicySigner]
-      },
-      witness: { scripts: [policyScript] }
-    };
-
-    const unsignedTx = await wallet.initializeTx(txProps);
-
-    const finalizeProps: FinalizeTxProps = {
-      signingOptions: {
-        extraSigners: [alicePolicySigner]
-      },
-      tx: unsignedTx,
-      witness: { scripts: [policyScript] }
-    };
-
-    const signedTx = await wallet.finalizeTx(finalizeProps);
     const [, txFoundInHistory] = await submitAndConfirm(wallet, signedTx, 1);
 
     expect(txFoundInHistory.id).toEqual(signedTx.id);

packages/tx-construction/src/input-selection/selectionConstraints.ts

@@ -75,6 +75,23 @@ const updateRedeemers = (
   return result;
 };
 
+/**
+ * `buildRedeemers` stamps builder-provided redeemers with a sentinel index. Spend redeemers are
+ * reindexed by input position elsewhere; the remaining (mint/withdrawal/certificate/...) redeemers
+ * carrying the sentinel are reindexed here by their position within their purpose, matching the
+ * canonical ordering in which they were added (e.g. mint redeemers in sorted-policy order).
+ * Redeemers that already carry a concrete index are left untouched.
+ */
+const reindexSentinelRedeemers = (redeemers: Cardano.Redeemer[]): void => {
+  const indexByPurpose = new Map<Cardano.RedeemerPurpose, number>();
+  for (const redeemer of redeemers) {
+    if (redeemer.index !== Number.MAX_SAFE_INTEGER) continue;
+    const index = indexByPurpose.get(redeemer.purpose) ?? 0;
+    redeemer.index = index;
+    indexByPurpose.set(redeemer.purpose, index + 1);
+  }
+};
+
 const reorgRedeemers = (
   redeemerByType: RedeemersByType,
   witness: Cardano.Witness,
@@ -86,6 +103,8 @@ const reorgRedeemers = (
     // Lets remove all spend redeemers if any.
     redeemers = witness.redeemers.filter((redeemer) => redeemer.purpose !== Cardano.RedeemerPurpose.spend);
 
+    reindexSentinelRedeemers(redeemers);
+
     // Add them back with the correct redeemer index.
     if (redeemerByType.spend) {
       for (const [key, value] of redeemerByType.spend) {

packages/tx-construction/src/tx-builder/TxBuilder.ts

@@ -12,6 +12,7 @@ import { Cardano, HandleProvider, HandleResolution, Serialization, inConwayEra,
 import {
   CustomizeCb,
   InsufficientRewardAccounts,
+  MintProps,
   OutOfSyncRewardAccounts,
   OutputBuilderTxOut,
   PartialTx,
@@ -219,6 +220,32 @@ export class GenericTxBuilder implements TxBuilder {
     return this;
   }
 
+  addMint({ policy, assets, redeemer }: MintProps): TxBuilder {
+    const policyHash = Serialization.Script.fromCore(policy).hash();
+    this.#knownScripts.set(policyHash, policy);
+
+    const policyId = Cardano.PolicyId(policyHash);
+    const mint = new Map(this.partialTxBody.mint);
+    for (const [assetName, quantity] of assets) {
+      mint.set(Cardano.AssetId.fromParts(policyId, assetName), quantity);
+    }
+    this.partialTxBody = { ...this.partialTxBody, mint };
+
+    if (redeemer) {
+      this.#knownRedeemers.mint?.push({
+        data: redeemer,
+        executionUnits: { memory: 0, steps: 0 },
+        // Position within the mint redeemers; reconciled to canonical (sorted-policy) order
+        // during input selection. Callers minting under multiple policies should add them in
+        // sorted-policy order.
+        index: this.#knownRedeemers.mint.length,
+        purpose: Cardano.RedeemerPurpose.mint
+      });
+    }
+
+    return this;
+  }
+
   addDatum(datum: Cardano.PlutusData): TxBuilder {
     const hash = Serialization.PlutusData.fromCore(datum).hash();
 
@@ -412,6 +439,7 @@ export class GenericTxBuilder implements TxBuilder {
               customizeCb: this.#customizeCb,
               handleResolutions: this.#handleResolutions,
               inputs: new Set(this.#preSelectedInputs.values()),
+              mint: this.partialTxBody.mint,
               options: {
                 validityInterval: this.partialTxBody.validityInterval
               },

packages/tx-construction/src/tx-builder/types.ts

@@ -266,6 +266,15 @@ export type ScriptUnlockProps = {
   datum?: Cardano.PlutusData;
 };
 
+export type MintProps = {
+  /** The minting policy script. The policy id is derived from its hash. */
+  policy: Cardano.Script;
+  /** Asset names mapped to the quantity to mint (positive) or burn (negative), under the policy. */
+  assets: Map<Cardano.AssetName, bigint>;
+  /** Redeemer for Plutus minting policies; omit for native scripts. */
+  redeemer?: Cardano.PlutusData;
+};
+
 export interface TxBuilder {
   /**
    * @returns a partial transaction that has properties set by calling other TxBuilder methods. Does not validate the transaction.
@@ -289,6 +298,16 @@ export interface TxBuilder {
    */
   addInput(input: Cardano.TxIn | Cardano.Utxo, scriptUnlockProps?: ScriptUnlockProps): TxBuilder;
 
+  /**
+   * Mints (or burns) assets under a minting policy. The policy script is attached to the witness
+   * set and, for Plutus policies, the redeemer is included and its execution units are evaluated
+   * during `build()`. Call multiple times to mint under several policies.
+   *
+   * @param props - The minting policy, the assets (by name) to mint/burn, and an optional redeemer.
+   * @returns {TxBuilder} The current TxBuilder instance for chaining.
+   */
+  addMint(props: MintProps): TxBuilder;
+
   /**
    * Adds a datum to the transaction.
    *

packages/tx-construction/test/tx-builder/TxBuilderPlutusScripts.test.ts

@@ -1,7 +1,7 @@
 /* eslint-disable sonarjs/no-duplicate-string */
 import * as Crypto from '@cardano-sdk/crypto';
 import { AddressType, Bip32Account, InMemoryKeyAgent, util } from '@cardano-sdk/key-management';
-import { Cardano, coalesceValueQuantities } from '@cardano-sdk/core';
+import { Cardano, Serialization, coalesceValueQuantities } from '@cardano-sdk/core';
 import {
   DatumResolver,
   GenericTxBuilder,
@@ -282,6 +282,101 @@ describe('TxBuilder/plutusScripts', () => {
     expect(roundRobinRandomImprove).toHaveBeenCalled();
   });
 
+  it('can mint assets under a plutus policy with a redeemer', async () => {
+    const assetName = Cardano.AssetName('4d794e4654'); // "MyNFT"
+    const tx = await txBuilder
+      .addMint({ assets: new Map([[assetName, 1n]]), policy: script, redeemer: 1n })
+      .build()
+      .inspect();
+
+    const policyId = Cardano.PolicyId(Serialization.Script.fromCore(script).hash());
+    const assetId = Cardano.AssetId.fromParts(policyId, assetName);
+
+    expect(tx.body.mint?.get(assetId)).toEqual(1n);
+    expect(tx.witness?.scripts?.some((s) => s === script)).toBeTruthy();
+    expect(
+      tx.witness?.redeemers?.some(
+        (redeemer) => redeemer.purpose === Cardano.RedeemerPurpose.mint && redeemer.data === 1n
+      )
+    ).toBeTruthy();
+    expect(tx.body.scriptIntegrityHash).toBeDefined();
+  });
+
+  it('can burn assets under a plutus policy (negative quantity)', async () => {
+    const assetName = Cardano.AssetName('4d794e4654');
+    const policyId = Cardano.PolicyId(Serialization.Script.fromCore(script).hash());
+    const assetId = Cardano.AssetId.fromParts(policyId, assetName);
+
+    // The asset being burned must be available on an input.
+    const assetHolderAddress = Cardano.PaymentAddress(
+      'addr_test1qqt9c69kjqf0wsnlp7hs8xees5l6pm4yxdqa3hknqr0kfe0htmj4e5t8n885zxm4qzpfzwruqx3ey3f5q8kpkr0gt9ms8dcsz6'
+    );
+    const inputWithAsset: Cardano.Utxo = [
+      {
+        address: assetHolderAddress,
+        index: 0,
+        txId: Cardano.TransactionId('aa21ffbaff60ff0cff8cff55ffa6ff6dff78ff78ffaeffceff36ff3fffc5ffe0')
+      },
+      {
+        address: assetHolderAddress,
+        value: { assets: new Map([[assetId, 1n]]), coins: 10_000_000n }
+      }
+    ];
+
+    const tx = await txBuilder
+      .addInput(inputWithAsset)
+      .addMint({ assets: new Map([[assetName, -1n]]), policy: script, redeemer: 1n })
+      .build()
+      .inspect();
+
+    expect(tx.body.mint?.get(assetId)).toEqual(-1n);
+    expect(tx.body.scriptIntegrityHash).toBeDefined();
+  });
+
+  it('can mint under a native policy without a redeemer', async () => {
+    const nativePolicy: Cardano.NativeScript = {
+      __type: Cardano.ScriptType.Native,
+      kind: Cardano.NativeScriptKind.RequireAllOf,
+      scripts: []
+    };
+    const assetName = Cardano.AssetName('4e6174697665'); // "Native"
+    const policyId = Cardano.PolicyId(Serialization.Script.fromCore(nativePolicy).hash());
+    const assetId = Cardano.AssetId.fromParts(policyId, assetName);
+
+    const tx = await txBuilder
+      .addMint({ assets: new Map([[assetName, 5n]]), policy: nativePolicy })
+      .build()
+      .inspect();
+
+    expect(tx.body.mint?.get(assetId)).toEqual(5n);
+    expect(tx.witness?.scripts?.some((s) => s === nativePolicy)).toBeTruthy();
+    // Native minting has no redeemer and therefore no script-data-hash.
+    expect(tx.witness?.redeemers?.some((r) => r.purpose === Cardano.RedeemerPurpose.mint)).toBeFalsy();
+    expect(tx.body.scriptIntegrityHash).toBeUndefined();
+  });
+
+  it('reindexes mint redeemers across multiple policies', async () => {
+    const policyA = script;
+    const policyB: Cardano.PlutusScript = {
+      __type: Cardano.ScriptType.Plutus,
+      bytes: HexBlob('4d01000033222220051200120011'),
+      version: Cardano.PlutusLanguageVersion.V2
+    };
+
+    const tx = await txBuilder
+      .addMint({ assets: new Map([[Cardano.AssetName('41'), 1n]]), policy: policyA, redeemer: 1n })
+      .addMint({ assets: new Map([[Cardano.AssetName('42'), 1n]]), policy: policyB, redeemer: 2n })
+      .build()
+      .inspect();
+
+    const mintRedeemers = (tx.witness?.redeemers ?? []).filter((r) => r.purpose === Cardano.RedeemerPurpose.mint);
+    expect(mintRedeemers).toHaveLength(2);
+    // Reindexed to canonical sequential positions, each with evaluated execution units.
+    expect(mintRedeemers.map((r) => r.index).sort()).toEqual([0, 1]);
+    expect(mintRedeemers.every((r) => r.executionUnits.steps > 0)).toBeTruthy();
+    expect(new Set(mintRedeemers.map((r) => r.data))).toEqual(new Set([1n, 2n]));
+  });
+
   it('can point the redeemer to the right input', async () => {
     const tx = await txBuilder
       .addInput(

packages/web-extension/src/observableWallet/util.ts

@@ -47,6 +47,10 @@ export const txBuilderProperties: RemoteApiProperties<Omit<TxBuilder, 'customize
     getApiProperties: () => txBuilderProperties,
     propType: RemoteApiPropertyType.ApiFactory
   },
+  addMint: {
+    getApiProperties: () => txBuilderProperties,
+    propType: RemoteApiPropertyType.ApiFactory
+  },
   addOutput: {
     getApiProperties: () => txBuilderProperties,
     propType: RemoteApiPropertyType.ApiFactory