feat(sdk-coin-ada): add explicit-output build for consolidation

Adds ExplicitOutput interface and explicitOutput() builder method to
support single-asset consolidation and token withdrawal flows. Uses a
two-pass fee-calculation approach (mirrors processTokenBuild) where
outputs are pre-computed by the caller; only fee and fee-address change
output are appended by the SDK. Requires sponsorshipInfo to be set.

Ticket: CSHLD-641

Author: Ranjna-G

modules/sdk-coin-ada/src/lib/index.ts

@@ -1,7 +1,7 @@
 import * as Utils from './utils';
 
 export { KeyPair } from './keyPair';
-export { Transaction } from './transaction';
+export { ExplicitOutput, Transaction } from './transaction';
 export { TransactionBuilder } from './transactionBuilder';
 export { TransferBuilder } from './transferBuilder';
 export { TransactionBuilderFactory } from './transactionBuilderFactory';

modules/sdk-coin-ada/src/lib/transaction.ts

@@ -29,6 +29,16 @@ export interface TransactionOutput {
   multiAssets?: CardanoWasm.MultiAsset | Asset;
 }
 
+/**
+ * A plain-object output descriptor used in single-asset consolidation mode.
+ */
+export interface ExplicitOutput {
+  address: string;
+  amount: string;
+  /** Native tokens carried by this output (optional). */
+  assets?: Asset[];
+}
+
 export interface Witness {
   publicKey: string;
   signature: string;

modules/sdk-coin-ada/src/lib/transactionBuilder.ts

@@ -10,7 +10,15 @@ import {
   TransactionType,
   UtilsError,
 } from '@bitgo/sdk-core';
-import { Asset, Transaction, TransactionInput, TransactionOutput, Withdrawal, SponsorshipInfo } from './transaction';
+import {
+  Asset,
+  ExplicitOutput,
+  SponsorshipInfo,
+  Transaction,
+  TransactionInput,
+  TransactionOutput,
+  Withdrawal,
+} from './transaction';
 import { KeyPair } from './keyPair';
 import util, { MIN_ADA_FOR_ONE_ASSET } from './utils';
 import * as CardanoWasm from '@emurgo/cardano-serialization-lib-nodejs';
@@ -50,6 +58,12 @@ export abstract class TransactionBuilder extends BaseTransactionBuilder {
   private _fee: BigNum;
   /** Flag indicating if this is a token transaction */
   private _isTokenTransaction = false;
+  /**
+   * Pre-computed outputs for single-asset consolidation / explicit-output builds.
+   * When non-empty, build() uses processExplicitOutputsBuild: the SDK only
+   * calculates fee and appends the fee-address change output (requires sponsorshipInfo).
+   */
+  private _explicitOutputs: ExplicitOutput[] = [];
   /** Deep clone of _senderAssetList - for manipulating during two iterations
    *   - one for calculating the fee
    *   - one for the actual transaction build with the calculated fee
@@ -119,6 +133,17 @@ export abstract class TransactionBuilder extends BaseTransactionBuilder {
     return this;
   }
 
+  /**
+   * Adds a pre-computed output for single-asset consolidation / explicit-output builds.
+   * When at least one explicit output is present, build() uses the explicit-output path
+   * (fee + fee-address change only); requires sponsorshipInfo.
+   * Uses plain Asset objects so callers do not need to import CardanoWasm.
+   */
+  explicitOutput(o: ExplicitOutput): this {
+    this._explicitOutputs.push(o);
+    return this;
+  }
+
   /**
    * Initialize the transaction builder fields using the decoded transaction data
    *
@@ -474,8 +499,88 @@ export abstract class TransactionBuilder extends BaseTransactionBuilder {
     return txDraft;
   }
 
+  /**
+   * Converts a plain ExplicitOutput into a Cardano TransactionOutput and
+   * adds it to `outputs`.  Supports multiple policy IDs / asset names.
+   */
+  private addExplicitOutput(output: ExplicitOutput, outputs: CardanoWasm.TransactionOutputs): void {
+    const amount = CardanoWasm.BigNum.from_str(output.amount);
+    const addr = util.getWalletAddress(output.address);
+    if (output.assets && output.assets.length > 0) {
+      const multiAsset = CardanoWasm.MultiAsset.new();
+      for (const asset of output.assets) {
+        const policyId = CardanoWasm.ScriptHash.from_bytes(Buffer.from(asset.policy_id, 'hex'));
+        const assetName = CardanoWasm.AssetName.new(Buffer.from(asset.asset_name, 'hex'));
+        const qty = CardanoWasm.BigNum.from_str(asset.quantity);
+        let existingAssets = multiAsset.get(policyId);
+        if (!existingAssets) {
+          existingAssets = CardanoWasm.Assets.new();
+        }
+        existingAssets.insert(assetName, qty);
+        multiAsset.insert(policyId, existingAssets);
+      }
+      const txOutputBuilder = CardanoWasm.TransactionOutputBuilder.new().with_address(addr);
+      let txOutputAmountBuilder = txOutputBuilder.next();
+      txOutputAmountBuilder = txOutputAmountBuilder.with_coin_and_asset(amount, multiAsset);
+      outputs.add(txOutputAmountBuilder.build());
+    } else {
+      outputs.add(CardanoWasm.TransactionOutput.new(addr, CardanoWasm.Value.new(amount)));
+    }
+  }
+
+  /**
+   * Builds a Cardano outputs collection from _explicitOutputs and appends
+   * the fee-address change output based on the supplied fee amount.
+   * Used exclusively by processExplicitOutputsBuild.
+   */
+  private buildExplicitOutputsCollection(fee: BigNum): CardanoWasm.TransactionOutputs {
+    if (!this._sponsorshipInfo) {
+      throw new BuildTransactionError('explicit outputs build requires sponsorshipInfo to be set');
+    }
+    const outputs = CardanoWasm.TransactionOutputs.new();
+    for (const output of this._explicitOutputs) {
+      this.addExplicitOutput(output, outputs);
+    }
+    const feeBalance = CardanoWasm.BigNum.from_str(this._sponsorshipInfo.feeAddressInputBalance);
+    const feeAddressChange = feeBalance.checked_sub(fee);
+    if (!feeAddressChange.is_zero()) {
+      const feeAddr = util.getWalletAddress(this._sponsorshipInfo.feeAddress);
+      outputs.add(CardanoWasm.TransactionOutput.new(feeAddr, CardanoWasm.Value.new(feeAddressChange)));
+    }
+    return outputs;
+  }
+
+  /**
+   * Build path for single-asset consolidation and token withdrawal builds
+   *
+   * Two-pass approach mirrors processTokenBuild:
+   *  1. Draft with zero fee → calculate actual fee.
+   *  2. Rebuild outputs with actual fee deducted from fee-address balance.
+   */
+  private processExplicitOutputsBuild(): Transaction {
+    if (this._explicitOutputs.length === 0) {
+      throw new BuildTransactionError('explicit outputs build requires at least one explicitOutput');
+    }
+    const inputs = CardanoWasm.TransactionInputs.new();
+    this.addInputs(inputs);
+
+    if (this._fee.is_zero()) {
+      const draftOutputs = this.buildExplicitOutputsCollection(BigNum.zero());
+      const txDraft = this.prepareAdaTransactionDraft(inputs, draftOutputs, false);
+      this.calculateFee(txDraft);
+      this.setFeeInTransaction();
+    }
+
+    const finalOutputs = this.buildExplicitOutputsCollection(this._fee);
+    this._transaction.transaction = this.prepareAdaTransactionDraft(inputs, finalOutputs, true);
+    return this.transaction;
+  }
+
   /** @inheritdoc */
   protected async buildImplementation(): Promise<Transaction> {
+    if (this._explicitOutputs.length > 0) {
+      return this.processExplicitOutputsBuild();
+    }
     /**
      * Fee address utxo reservation builds a new transaction that goes through legacy build
      * rebuild flag is just a hack to redirect the flow to the legacy build

modules/sdk-coin-ada/test/unit/transactionBuilder.ts

@@ -1,7 +1,8 @@
 import should from 'should';
+import * as sinon from 'sinon';
 import { TransactionType } from '@bitgo/sdk-core';
 import * as testData from '../resources';
-import { KeyPair, TransactionBuilderFactory } from '../../src';
+import { KeyPair, TransactionBuilder, TransactionBuilderFactory } from '../../src';
 import { coins } from '@bitgo/statics';
 import * as CardanoWasm from '@emurgo/cardano-serialization-lib-nodejs';
 import { Transaction } from '../../src/lib/transaction';
@@ -360,6 +361,105 @@ describe('ADA Transaction Builder', async () => {
     should.equal(sig1, sig2);
   });
 
+  describe('explicit outputs build (processExplicitOutputsBuild)', () => {
+    afterEach(() => {
+      sinon.restore();
+    });
+
+    it('builds a sponsored tx with explicit token output, inputs, fee change, and correct asset data', async () => {
+      const policyId = 'e16c2dc8ae937e8d3790c7fd7168d7b994621ba14ca11415f39fed72';
+      const assetNameHex = '4d494e';
+      const tokenQty = '2000000';
+      const explicitAda = '2000000';
+      const feeAddress = testData.rawTx.outputAddress2.address;
+      const recipient = testData.rawTx.outputAddress1.address;
+
+      const txBuilder = factory.getTransferBuilder();
+      txBuilder.input({
+        transaction_id: '3677e75c7ba699bfdc6cd57d42f246f86f63aefd76025006ac78313fad2bba21',
+        transaction_index: 1,
+      });
+      txBuilder.sponsorshipInfo({
+        feeAddress,
+        feeAddressInputBalance: '10000000',
+      });
+      txBuilder.explicitOutput({
+        address: recipient,
+        amount: explicitAda,
+        assets: [
+          {
+            policy_id: policyId,
+            asset_name: assetNameHex,
+            quantity: tokenQty,
+          },
+        ],
+      });
+      txBuilder.ttl(800000000);
+
+      const tx = (await txBuilder.build()) as Transaction;
+      should.equal(tx.type, TransactionType.Send);
+      const txData = tx.toJson();
+
+      txData.inputs.length.should.equal(1);
+      txData.inputs[0].transaction_id.should.equal('3677e75c7ba699bfdc6cd57d42f246f86f63aefd76025006ac78313fad2bba21');
+      txData.inputs[0].transaction_index.should.equal(1);
+
+      txData.outputs.length.should.equal(2);
+      txData.outputs[0].address.should.equal(recipient);
+      txData.outputs[0].amount.should.equal(explicitAda);
+      txData.outputs[0].should.have.property('multiAssets');
+      const expectedPolicyId = CardanoWasm.ScriptHash.from_bytes(Buffer.from(policyId, 'hex'));
+      const expectedAssetName = CardanoWasm.AssetName.new(Buffer.from(assetNameHex, 'hex'));
+      (txData.outputs[0].multiAssets as CardanoWasm.MultiAsset)
+        .get_asset(expectedPolicyId, expectedAssetName)
+        .to_str()
+        .should.equal(tokenQty);
+
+      txData.outputs[1].address.should.equal(feeAddress);
+      const fee = Number(tx.getFee);
+      (Number(txData.outputs[1].amount) + fee).should.equal(10000000);
+      should(fee).be.above(0);
+    });
+
+    it('does not call processExplicitOutputsBuild when _explicitOutputs is empty', async () => {
+      const spy = sinon.spy(TransactionBuilder.prototype as any, 'processExplicitOutputsBuild');
+      const txBuilder = factory.getTransferBuilder();
+      txBuilder.input({
+        transaction_id: '3677e75c7ba699bfdc6cd57d42f246f86f63aefd76025006ac78313fad2bba21',
+        transaction_index: 1,
+      });
+      txBuilder.output({
+        address: testData.rawTx.outputAddress1.address,
+        amount: '7823121',
+      });
+      txBuilder.changeAddress(testData.rawTx.outputAddress2.address, '21032023');
+      txBuilder.ttl(800000000);
+      await txBuilder.build();
+      spy.called.should.be.false();
+    });
+
+    it('throws when explicitOutput is set but sponsorshipInfo is missing', async () => {
+      const txBuilder = factory.getTransferBuilder();
+      txBuilder.input({
+        transaction_id: '3677e75c7ba699bfdc6cd57d42f246f86f63aefd76025006ac78313fad2bba21',
+        transaction_index: 1,
+      });
+      txBuilder.explicitOutput({
+        address: testData.rawTx.outputAddress1.address,
+        amount: '2000000',
+        assets: [
+          {
+            policy_id: 'e16c2dc8ae937e8d3790c7fd7168d7b994621ba14ca11415f39fed72',
+            asset_name: '4d494e',
+            quantity: '2000000',
+          },
+        ],
+      });
+      txBuilder.ttl(800000000);
+      await txBuilder.build().should.rejectedWith('explicit outputs build requires sponsorshipInfo to be set');
+    });
+  });
+
   // NOTE: The tests below have been commented out as they are for testing during development changes. We don't
   // want full node tests as part of our sdk unit tests. If you are commenting these back in, add axios and
   // AddressFormat imports.