feat(sdk-coin-canton): forward token and make choiceArgument optional

Ticket: SCAAS-9624

Author: abhijeet848

modules/sdk-coin-canton/src/lib/cantonCommandBuilder.ts

@@ -5,7 +5,7 @@ import {
   CantonCommand,
   CantonCommandResolveContractSpec,
 } from '@bitgo/sdk-core';
-import { BaseCoin as CoinConfig } from '@bitgo/statics';
+import { BaseCoin as CoinConfig, coins } from '@bitgo/statics';
 import { CANTON_COMMAND_KEYS, CantonCommandRequest, CantonPrepareCommandResponse } from './iface';
 import { TransactionBuilder } from './transactionBuilder';
 import { Transaction } from './transaction/transaction';
@@ -17,6 +17,7 @@ export class CantonCommandBuilder extends TransactionBuilder {
   private _readAs: string[] = [];
   private _command: CantonCommand;
   private _resolveContracts: CantonCommandResolveContractSpec[] = [];
+  private _token?: string;
 
   constructor(_coinConfig: Readonly<CoinConfig>) {
     super(_coinConfig);
@@ -137,6 +138,34 @@ export class CantonCommandBuilder extends TransactionBuilder {
     return this;
   }
 
+  /**
+   * Sets the Canton token identifier (e.g. 'tcanton:stgusd1') forwarded to IMS for
+   * choice-context resolution on token-specific commands such as mint and burn.
+   *
+   * @param name - Registered BitGo canton token name
+   * @returns The current builder instance for chaining.
+   */
+  token(name: string): this {
+    if (typeof name !== 'string' || !name.trim()) {
+      throw new Error('token must be a non-empty string');
+    }
+    const tokenName = name.trim();
+    let coinConfig: ReturnType<typeof coins.get>;
+    try {
+      coinConfig = coins.get(tokenName);
+    } catch {
+      throw new Error(`token is not a registered coin: ${tokenName}`);
+    }
+    if (coinConfig.network.type !== this._coinConfig.network.type) {
+      throw new Error(`token network must match builder network: ${tokenName}`);
+    }
+    if (coinConfig.family !== 'canton' || !coinConfig.isToken) {
+      throw new Error(`token must be a registered canton token: ${tokenName}`);
+    }
+    this._token = tokenName;
+    return this;
+  }
+
   /**
    * Builds and returns the CantonCommandRequest from the builder's internal state.
    *
@@ -146,13 +175,17 @@ export class CantonCommandBuilder extends TransactionBuilder {
   toRequestObject(): CantonCommandRequest {
     this.validate();
 
-    return {
+    const req: CantonCommandRequest = {
       commandId: this._commandId,
       actAs: this._actAs,
       readAs: this._readAs ?? [],
       command: this._command,
       resolveContracts: this._resolveContracts ?? [],
     };
+    if (this._token) {
+      req.token = this._token;
+    }
+    return req;
   }
 
   private validate(): void {

modules/sdk-coin-canton/src/lib/iface.ts

@@ -231,6 +231,7 @@ export interface CantonCommandRequest {
   readAs?: string[];
   command: CantonCommand;
   resolveContracts?: CantonCommandResolveContractSpec[];
+  token?: string;
 }
 
 // Root command decoded from the prepared Canton transaction protobuf, used during verifyTransaction.

modules/sdk-coin-canton/test/unit/builder/cantonCommand/cantonCommandBuilder.ts

@@ -138,6 +138,66 @@ describe('CantonCommandBuilder', () => {
     });
   });
 
+  describe('token()', () => {
+    it('should set the token', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      builder.commandId('cmd-tok-1').actAs([PARTY_A]).command(sampleExerciseCommand).token('tcanton:testtoken');
+      assert.equal(builder.toRequestObject().token, 'tcanton:testtoken');
+    });
+
+    it('should trim whitespace', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      builder.commandId('cmd-tok-2').actAs([PARTY_A]).command(sampleExerciseCommand).token('  tcanton:testtoken  ');
+      assert.equal(builder.toRequestObject().token, 'tcanton:testtoken');
+    });
+
+    it('should throw on empty string', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      assert.throws(() => builder.token(''), /token must be a non-empty string/);
+    });
+
+    it('should throw on whitespace-only string', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      assert.throws(() => builder.token('   '), /token must be a non-empty string/);
+    });
+
+    it('should throw on an unregistered coin name', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      assert.throws(() => builder.token('tcanton:fakecoin'), /token is not a registered coin/);
+    });
+
+    it('should throw when token is not a canton family token', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      assert.throws(() => builder.token('teth'), /token must be a registered canton token/);
+    });
+
+    it('should throw when token network does not match builder network', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      assert.throws(() => builder.token('canton:usd1'), /token network must match builder network/);
+    });
+
+    it('should throw when token is the base canton coin (not a token)', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      assert.throws(() => builder.token('tcanton'), /token must be a registered canton token/);
+    });
+  });
+
   describe('resolveContracts()', () => {
     it('should set the spec array', function () {
       const spec = [{ templateId: TEMPLATE_ID, actAs: [PARTY_A], injectAs: 'command.ExerciseCommand.contractId' }];
@@ -206,6 +266,24 @@ describe('CantonCommandBuilder', () => {
       const req = builder.toRequestObject();
       assert.deepEqual(req.resolveContracts, []);
     });
+
+    it('should include token when set', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      builder.commandId('cmd-003').actAs([PARTY_A]).command(sampleExerciseCommand).token('tcanton:testtoken');
+      const req = builder.toRequestObject();
+      assert.equal(req.token, 'tcanton:testtoken');
+    });
+
+    it('should not include token key when not set', function () {
+      const builder = new CantonCommandBuilder(coins.get('tcanton'));
+      const tx = new Transaction(coins.get('tcanton'));
+      builder.initBuilder(tx);
+      builder.commandId('cmd-004').actAs([PARTY_A]).command(sampleExerciseCommand);
+      const req = builder.toRequestObject();
+      assert.ok(!('token' in req));
+    });
   });
 
   describe('initBuilder()', () => {

modules/sdk-core/src/bitgo/utils/tss/baseTypes.ts

@@ -93,7 +93,7 @@ export interface CantonExerciseCommand {
     templateId: string;
     contractId?: string;
     choice: string;
-    choiceArgument: Record<string, unknown>;
+    choiceArgument?: Record<string, unknown>;
   };
 }
 

modules/sdk-core/src/bitgo/wallet/wallet.ts

@@ -4301,6 +4301,7 @@ export class Wallet implements IWallet {
             reqId,
             intentType: 'cantonCommand',
             cantonCommandParams: params.cantonCommandParams,
+            tokenName: params.tokenName,
             sequenceId: params.sequenceId,
             comment: params.comment,
           },