feat: add bridgingParams support for BTC-to-sBTC bridging

Add bridgingParams to the BTC transaction build pipeline for
cross-chain BTC-to-sBTC bridging. The parameter flows through all
wallet types: non-TSS (hot/cold via BuildParams whitelist),
TSS (via new 'bridging' case in prebuild switch), and custodial.

Shared types (SbtcBridgingParams, BridgingParams) defined once in
iWallet.ts and reused across sdk-core and express typed routes.
bridgingParams is conditionally included in populateIntent only
for intentType === 'bridging'.

Ticket: CSHLD-906

Author: abhi-bitgo

modules/bitgo/test/v2/unit/wallet.ts

@@ -1710,6 +1710,45 @@ describe('V2 Wallet:', function () {
       postProcessStub.restore();
     });
 
+    it('should pass bridgingParams to tx/build for non-TSS BTC wallet', async function () {
+      const bridgingParams = {
+        sbtc: {
+          amount: 100000,
+          stacksRecipient: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
+          maxFee: 5000,
+          lockTime: 144,
+        },
+      };
+      const expectedBuildParams = {
+        type: 'bridging',
+        txFormat: 'psbt',
+        recipients: [],
+        bridgingParams,
+        changeAddressType: ['p2trMusig2', 'p2wsh', 'p2shP2wsh', 'p2sh', 'p2tr'],
+      };
+
+      const scope = nock(bgUrl)
+        .post(`/api/v2/${wallet.coin()}/wallet/${wallet.id()}/tx/build`, expectedBuildParams)
+        .query({})
+        .reply(200, {});
+      const blockHeightStub = sinon.stub(basecoin, 'getLatestBlockHeight').resolves(100);
+      const postProcessStub = sinon.stub(basecoin, 'postProcessPrebuild').resolves({});
+      await wallet.prebuildTransaction({
+        type: 'bridging',
+        txFormat: 'psbt',
+        recipients: [],
+        bridgingParams,
+      });
+      postProcessStub.should.have.been.calledOnceWith({
+        blockHeight: 100,
+        wallet: wallet,
+        buildParams: expectedBuildParams,
+      });
+      scope.done();
+      blockHeightStub.restore();
+      postProcessStub.restore();
+    });
+
     it('prebuild should call build but not getLatestBlockHeight for account coins', async function () {
       ['txrp', 'txlm', 'teth'].forEach(async function (coin) {
         const accountcoin = bitgo.coin(coin);
@@ -2468,8 +2507,22 @@ describe('V2 Wallet:', function () {
       multisigType: 'tss',
     };
 
+    const btcWalletData = {
+      id: '5b34252f1bf349930e34020a11111111',
+      coin: 'tbtc',
+      keys: [
+        '598f606cd8fc24710d2ebad89dce86c2',
+        '598f606cc8e43aef09fcb785221d9dd2',
+        '5935d59cf660764331bafcade1855fd7',
+      ],
+      multisigType: 'tss',
+      coinSpecific: {},
+      type: 'hot',
+    };
+
     const tssSolWallet = new Wallet(bitgo, tsol, walletData);
     const tssAdaWallet = new Wallet(bitgo, tada, adaWalletData);
+    const tssBtcWallet = new Wallet(bitgo, basecoin, btcWalletData);
 
     let tssEthWallet = new Wallet(bitgo, bitgo.coin('teth'), ethWalletData);
     const tssPolygonWallet = new Wallet(bitgo, bitgo.coin('tpolygon'), polygonWalletData);
@@ -3536,6 +3589,35 @@ describe('V2 Wallet:', function () {
         args[1]!.should.equal('full');
       });
 
+      it('should call prebuildTxWithIntent with the correct params for bridging on BTC wallet', async function () {
+        const bridgingParams = {
+          sbtc: {
+            amount: 100000,
+            stacksRecipient: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
+            maxFee: 5000,
+            lockTime: 144,
+          },
+        };
+
+        const prebuildTxWithIntent = sandbox.stub(ECDSAUtils.EcdsaUtils.prototype, 'prebuildTxWithIntent');
+        prebuildTxWithIntent.resolves(txRequestFull);
+
+        await tssBtcWallet.prebuildTransaction({
+          reqId,
+          type: 'bridging',
+          recipients: [],
+          bridgingParams,
+          txFormat: 'psbt',
+        });
+
+        sinon.assert.calledOnce(prebuildTxWithIntent);
+        const args = prebuildTxWithIntent.args[0];
+        args[0]!.intentType.should.equal('bridging');
+        args[0]!.bridgingParams!.should.deepEqual(bridgingParams);
+        args[0]!.recipients!.should.deepEqual([]);
+        args[1]!.should.equal('full');
+      });
+
       it('should call prebuildTxWithIntent with the correct params for Export', async function () {
         const recipients = [
           {
@@ -3915,6 +3997,37 @@ describe('V2 Wallet:', function () {
         intent.should.have.property('recipients', undefined);
       });
 
+      it('populate intent should include bridgingParams only for bridging intent type on BTC', async function () {
+        const tbtc = bitgo.coin('tbtc');
+        const mpcUtils = new ECDSAUtils.EcdsaUtils(bitgo, tbtc);
+        const bridgingParams = {
+          sbtc: {
+            amount: 100000,
+            stacksRecipient: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
+            maxFee: 5000,
+            lockTime: 144,
+          },
+        };
+
+        // bridgingParams should be included when intentType is 'bridging'
+        const bridgingIntent = mpcUtils.populateIntent(tbtc, {
+          reqId,
+          intentType: 'bridging',
+          recipients: [{ address: 'tb1qexample', amount: '100000' }],
+          bridgingParams,
+        });
+        bridgingIntent.bridgingParams!.should.deepEqual(bridgingParams);
+
+        // bridgingParams should NOT be included for other intent types
+        const paymentIntent = mpcUtils.populateIntent(tbtc, {
+          reqId,
+          intentType: 'payment',
+          recipients: [{ address: 'tb1qexample', amount: '100000' }],
+          bridgingParams,
+        });
+        paymentIntent.should.not.have.property('bridgingParams');
+      });
+
       it('populate intent should return valid export intent for EVM cross-chain', async function () {
         const mpcUtils = new ECDSAUtils.EcdsaUtils(bitgo, bitgo.coin('hteth'));
         const feeOptions = {

modules/express/src/typedRoutes/api/v2/prebuildAndSignTransaction.ts

@@ -9,6 +9,7 @@ import {
   SignedTransactionRequestResponse,
   EIP1559,
 } from './coinSignTx';
+import { BridgingParamsCodec } from './sendmany';
 
 /**
  * Request parameters for prebuild and sign transaction
@@ -384,6 +385,8 @@ export const PrebuildAndSignTransactionBody = {
   eip1559: optional(EIP1559),
   /** Gas limit */
   gasLimit: optional(t.number),
+  /** Parameters for bridging transactions (e.g., BTC to sBTC). Used with type: 'bridging'. */
+  bridgingParams: optional(BridgingParamsCodec),
   /** Low fee transaction ID for CPFP */
   lowFeeTxid: optional(t.string),
   /** Receive address */

modules/express/src/typedRoutes/api/v2/sendmany.ts

@@ -105,6 +105,27 @@ export const TokenEnablement = t.intersection([
   }),
 ]);
 
+/**
+ * sBTC bridging parameters codec
+ */
+export const SbtcBridgingParamsCodec = t.type({
+  /** Amount in satoshis to bridge */
+  amount: t.union([t.number, t.string]),
+  /** Stacks recipient address */
+  stacksRecipient: t.string,
+  /** Maximum fee in satoshis */
+  maxFee: t.union([t.number, t.string]),
+  /** Lock time for the bridging transaction */
+  lockTime: t.number,
+});
+
+/**
+ * Bridging parameters codec for cross-chain bridging transactions (e.g., BTC to sBTC).
+ */
+export const BridgingParamsCodec = t.partial({
+  sbtc: SbtcBridgingParamsCodec,
+});
+
 /**
  * Request body for sending to multiple recipients (v2)
  *
@@ -344,6 +365,9 @@ export const SendManyRequestBody = {
   /** Array of tokens to enable on the wallet */
   enableTokens: optional(t.array(TokenEnablement)),
 
+  /** Parameters for bridging transactions (e.g., BTC to sBTC). Used with type: 'bridging'. */
+  bridgingParams: optional(BridgingParamsCodec),
+
   /** Low fee transaction ID (for CPFP - Child Pays For Parent) */
   lowFeeTxid: optional(t.string),
 

modules/sdk-core/src/bitgo/utils/mpcUtils.ts

@@ -183,6 +183,7 @@ export abstract class MpcUtils {
         'transferOfferWithdrawn',
         'bridgeFunds',
         'cantonCommand',
+        'bridging',
       ].includes(params.intentType)
     ) {
       assert(params.recipients, `'recipients' is a required parameter for ${params.intentType} intent`);
@@ -222,6 +223,7 @@ export abstract class MpcUtils {
       recipients: intentRecipients,
       tokenName: params.tokenName,
       isTestTransaction: params.isTestTransaction,
+      ...(params.intentType === 'bridging' && params.bridgingParams ? { bridgingParams: params.bridgingParams } : {}),
     };
 
     if (baseCoin.isEVM() && baseCoin.supportsTss()) {

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

@@ -2,7 +2,7 @@ import { Key, SerializedKeyPair } from 'openpgp';
 import { EncryptionVersion, IEncryptionSession, IRequestTracer } from '../../../api';
 import { type ITransactionRecipient, KeychainsTriplet, ParsedTransaction, TransactionParams } from '../../baseCoin';
 import { ApiKeyShare, Keychain, WebauthnKeyEncryptionInfo } from '../../keychain';
-import { ApiVersion, Memo, WalletType } from '../../wallet';
+import { ApiVersion, BridgingParams, Memo, WalletType } from '../../wallet';
 import { EDDSA, GShare, Signature, SignShare } from '../../../account-lib/mpc/tss';
 import { Signature as EcdsaSignature } from '../../../account-lib/mpc/tss/ecdsa/types';
 import { KeyShare } from './ecdsa';
@@ -354,6 +354,10 @@ export interface PrebuildTransactionWithIntentOptions extends IntentOptionsBase
   feeToken?: string;
   /** Canton-specific params for the cantonCommand intent. */
   cantonCommandParams?: CantonCommandParams;
+  /**
+   * Parameters for bridging transactions (e.g., BTC to sBTC).
+   */
+  bridgingParams?: BridgingParams;
 }
 export interface IntentRecipient {
   address: {
@@ -437,6 +441,10 @@ export interface PopulatedIntent extends PopulatedIntentBase {
   amount?: { value: string; symbol: string };
   /** Canton-specific params serialized into the cantonCommand intent payload. */
   cantonCommandParams?: CantonCommandParams;
+  /**
+   * Parameters for bridging transactions (e.g., BTC to sBTC).
+   */
+  bridgingParams?: BridgingParams;
 }
 
 export type TxRequestState =

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

@@ -132,6 +132,8 @@ export const BuildParams = t.exact(
       aptosCustomTransactionParams: t.unknown,
       isTestTransaction: t.unknown,
       feeToken: t.unknown,
+      // Bridging parameters for cross-chain operations (e.g., BTC to sBTC)
+      bridgingParams: t.unknown,
     }),
   ])
 );

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

@@ -124,6 +124,23 @@ export type NftBalance = BaseBalance & {
 
 export type ApiVersion = 'lite' | 'full';
 
+/** Parameters for sBTC bridging (BTC to sBTC). */
+export interface SbtcBridgingParams {
+  /** Amount in satoshis to bridge */
+  amount: number | string;
+  /** Stacks recipient address */
+  stacksRecipient: string;
+  /** Maximum fee in satoshis */
+  maxFee: number | string;
+  /** Lock time for the bridging transaction */
+  lockTime: number;
+}
+
+/** Parameters for cross-chain bridging transactions. */
+export interface BridgingParams {
+  sbtc?: SbtcBridgingParams;
+}
+
 export interface PrebuildTransactionOptions {
   reqId?: IRequestTracer;
   recipients?: {
@@ -267,6 +284,11 @@ export interface PrebuildTransactionOptions {
    * When specified, fees will be deducted in this token instead of the native currency.
    */
   feeToken?: string;
+  /**
+   * Parameters for bridging transactions (e.g., BTC to sBTC).
+   * Used with type: 'bridging' for cross-chain bridging operations.
+   */
+  bridgingParams?: BridgingParams;
 }
 
 export interface PrebuildAndSignTransactionOptions extends PrebuildTransactionOptions, WalletSignTransactionOptions {

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

@@ -4162,6 +4162,21 @@ export class Wallet implements IWallet {
           params.preview
         );
         break;
+      case 'bridging':
+        txRequest = await this.tssUtils!.prebuildTxWithIntent(
+          {
+            reqId,
+            intentType: 'bridging',
+            sequenceId: params.sequenceId,
+            comment: params.comment,
+            recipients: params.recipients || [],
+            bridgingParams: params.bridgingParams,
+            feeOptions,
+          },
+          apiVersion,
+          params.preview
+        );
+        break;
       case 'bridgeFunds':
         txRequest = await this.tssUtils!.prebuildTxWithIntent(
           {

modules/sdk-core/test/unit/bitgo/wallet/BuildParams.ts

@@ -37,4 +37,41 @@ describe('BuildParams', function () {
       }
     );
   });
+
+  it('should whitelist bridgingParams', function () {
+    const bridgingParams = {
+      sbtc: {
+        amount: 100000,
+        stacksRecipient: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
+        maxFee: 5000,
+        lockTime: 144,
+      },
+    };
+    assert.deepStrictEqual(
+      BuildParams.encode({
+        type: 'bridging',
+        txFormat: 'psbt',
+        recipients: [],
+        bridgingParams,
+      } as any),
+      {
+        type: 'bridging',
+        txFormat: 'psbt',
+        recipients: [],
+        bridgingParams,
+      }
+    );
+  });
+
+  it('should strip unknown params while keeping bridgingParams', function () {
+    assert.deepStrictEqual(
+      BuildParams.encode({
+        bridgingParams: { sbtc: { amount: 50000, stacksRecipient: 'SP123', maxFee: 1000, lockTime: 100 } },
+        unknownField: 'should be stripped',
+      } as any),
+      {
+        bridgingParams: { sbtc: { amount: 50000, stacksRecipient: 'SP123', maxFee: 1000, lockTime: 100 } },
+      }
+    );
+  });
 });