Merge pull request #8920 from BitGo/CSHLD-948

feat(sdk-coin-sui): handle fab balance instruction

Author: abhishekagrawal080

modules/sdk-coin-sui/src/lib/transferBuilder.ts

@@ -20,9 +20,9 @@ export class TransferBuilder extends TransactionBuilder<TransferProgrammableTran
   /**
    * Balance held in the Sui address balance system (not in coin objects).
    * When set, this amount is included in the total available balance for transfer.
-   * At execution time, Sui's GasCoin automatically draws from both coin objects
-   * (gasData.payment) and address balance, so SplitCoins(GasCoin, [amount])
-   * can spend funds from either source.
+   * Note: Sui does NOT automatically merge address balance into the gas coin when
+   * gasData.payment is non-empty. Path 2c explicitly redeems it via redeem_funds
+   * and merges it into the gas coin before splitting.
    */
   protected _fundsInAddressBalance: BigNumber = new BigNumber(0);
 
@@ -179,7 +179,7 @@ export class TransferBuilder extends TransactionBuilder<TransferProgrammableTran
   /**
    * Build transfer programmable transaction.
    *
-   * Three build paths:
+   * Four build paths:
    *
    * Path 1a — Sponsored with coin objects (sender ≠ gasData.owner, inputObjects provided):
    *   [optional withdrawal(fundsInAddressBalance) → redeem_funds → Coin<SUI>]
@@ -193,10 +193,16 @@ export class TransferBuilder extends TransactionBuilder<TransferProgrammableTran
    *   Handles Case 5 (sponsor coin-object gas) and Case 7/Phase-4b (sponsor addr-bal gas).
    *   Caller must set ValidDuring expiration when gasData.payment = [] (Cases 7, 9).
    *
-   * Path 2 — Self-pay (sender === gasData.owner):
+   * Path 2a/2b — Self-pay, coin objects only OR address-balance only (sender === gasData.owner):
    *   SplitCoins(GasCoin, [amount]) → TransferObjects
-   *   GasCoin at Sui execution time = gasData.payment objects merged + fundsInAddressBalance.
-   *   Handles Case 1 (coins), Case 2 (addr-bal only, caller sets ValidDuring), Case 3 (mixed).
+   *   Handles Case 1 (coins only) and Case 2 (addr-bal only, caller sets ValidDuring).
+   *
+   * Path 2c — Self-pay, mixed (sender === gasData.owner, gasData.payment non-empty AND fundsInAddressBalance > 0):
+   *   Sui does NOT automatically merge address balance into gas coin when payment is non-empty.
+   *   withdrawal(fundsInAddressBalance) → redeem_funds → Coin<SUI>
+   *   MergeCoins(GasCoin, [addrCoin])
+   *   SplitCoins(GasCoin, [amount]) → TransferObjects
+   *   Handles Case 3 (mixed funds — coin objects + address balance, self-pay).
    *
    * @protected
    */
@@ -297,6 +303,63 @@ export class TransferBuilder extends TransactionBuilder<TransferProgrammableTran
         fundsInAddressBalance: this._fundsInAddressBalance.toFixed(),
       };
     } else {
+      // Path 2c: self-pay, mixed — coin objects (gasData.payment) AND address balance both present.
+      // Sui does NOT automatically merge fundsInAddressBalance into the gas coin when
+      // gasData.payment is non-empty. We must explicitly redeem the address balance as a
+      // Coin<SUI> and merge it into the gas coin before splitting for recipients.
+      if (this._fundsInAddressBalance.gt(0) && this._gasData.payment.length > 0) {
+        // Merge excess gas payment objects first (same overflow logic as Path 2a/2b below).
+        if (this._gasData.payment.length >= MAX_GAS_OBJECTS) {
+          const gasPaymentObjects = this._gasData.payment
+            .slice(MAX_GAS_OBJECTS - 1)
+            .map((object) => Inputs.ObjectRef(object));
+
+          while (gasPaymentObjects.length > 0) {
+            programmableTxBuilder.mergeCoins(
+              programmableTxBuilder.gas,
+              gasPaymentObjects.splice(0, MAX_COMMAND_ARGS - 1).map((object) => programmableTxBuilder.object(object))
+            );
+          }
+        }
+
+        // Redeem address balance as Coin<SUI> and merge into the gas coin so that
+        // SplitCoins(GasCoin, [amount]) can draw from the full available balance:
+        //   gas coin = sum(coinObjects) + fundsInAddressBalance
+        const [addrCoin] = programmableTxBuilder.moveCall({
+          target: '0x2::coin::redeem_funds',
+          typeArguments: ['0x2::sui::SUI'],
+          arguments: [programmableTxBuilder.withdrawal({ amount: BigInt(this._fundsInAddressBalance.toFixed()) })],
+        });
+        programmableTxBuilder.mergeCoins(programmableTxBuilder.gas, [addrCoin]);
+
+        this._recipients.forEach((recipient) => {
+          const coin = programmableTxBuilder.add(
+            TransactionsConstructor.SplitCoins(programmableTxBuilder.gas, [
+              programmableTxBuilder.pure(BigInt(recipient.amount)),
+            ])
+          );
+          programmableTxBuilder.add(
+            TransactionsConstructor.TransferObjects([coin], programmableTxBuilder.object(recipient.address))
+          );
+        });
+        const txData2c = programmableTxBuilder.blockData;
+        return {
+          type: this._type,
+          sender: this._sender,
+          tx: {
+            inputs: [...txData2c.inputs],
+            transactions: [...txData2c.transactions],
+          },
+          gasData: {
+            ...this._gasData,
+            payment: this._gasData.payment.slice(0, MAX_GAS_OBJECTS - 1),
+          },
+          expiration: this._expiration,
+          fundsInAddressBalance: this._fundsInAddressBalance.toFixed(),
+        };
+      }
+
+      // Path 2a / 2b: self-pay, coin objects only OR address-balance only.
       // number of objects passed as gas payment should be strictly less than `MAX_GAS_OBJECTS`. When the transaction
       // requires a larger number of inputs we use the merge command to merge the rest of the objects into the gasCoin
       if (this._gasData.payment.length >= MAX_GAS_OBJECTS) {

modules/sdk-coin-sui/test/unit/transactionBuilder/transferBuilder.ts

@@ -346,25 +346,51 @@ describe('Sui Transfer Builder', () => {
       rebuiltTx.toBroadcastFormat().should.equal(rawTx);
     });
 
-    it('should build a self-pay transfer with coin objects + address balance', async function () {
+    it('should build a self-pay transfer with coin objects + address balance (Path 2c)', async function () {
+      // Regression test for COINS-331: when both gasData.payment (coin objects) and
+      // fundsInAddressBalance are set, Sui does NOT automatically merge address balance into
+      // the gas coin.  Path 2c must explicitly call redeem_funds + MergeCoins(gas, [addrCoin])
+      // before SplitCoins so that the gas coin holds the full spendable amount.
       const txBuilder = factory.getTransferBuilder();
       txBuilder.type(SuiTransactionType.Transfer);
       txBuilder.sender(testData.sender.address);
       txBuilder.send(testData.recipients);
-      txBuilder.gasData(testData.gasData);
+      txBuilder.gasData(testData.gasData); // non-empty payment — triggers Path 2c
       txBuilder.fundsInAddressBalance(FUNDS_IN_ADDRESS_BALANCE);
 
       const tx = await txBuilder.build();
       should.equal(tx.type, TransactionType.Send);
 
       const suiTx = tx as SuiTransaction<TransferProgrammableTransaction>;
 
-      // Self-pay path: SplitCoins(GasCoin) — protocol merges coin objects + address balance automatically
+      // Path 2c PTB command sequence (for 2 recipients):
+      //   0: MoveCall(redeem_funds)     — materialize addrCoin from address balance
+      //   1: MergeCoins(gas, [addrCoin])— gas coin = coinObjects + addrBal (full spendable amount)
+      //   2: SplitCoins(gas)            — split for recipient 0
+      //   3: TransferObjects            — send to recipient 0
+      //   4: SplitCoins(gas)            — split for recipient 1
+      //   5: TransferObjects            — send to recipient 1
       const programmableTx = suiTx.suiTransaction.tx;
-      (programmableTx.transactions[0] as any).kind.should.equal('SplitCoins');
+      const cmds = programmableTx.transactions as any[];
+      cmds[0].kind.should.equal('MoveCall', 'command 0 must be MoveCall(redeem_funds)');
+      cmds[0].target.should.equal('0x2::coin::redeem_funds');
+      cmds[1].kind.should.equal('MergeCoins', 'command 1 must be MergeCoins(gas, [addrCoin])');
+      cmds[2].kind.should.equal('SplitCoins', 'command 2 must be SplitCoins(gas, [amount0])');
+      cmds[3].kind.should.equal('TransferObjects');
+      cmds[4].kind.should.equal('SplitCoins', 'command 4 must be SplitCoins(gas, [amount1])');
+      cmds[5].kind.should.equal('TransferObjects');
+
+      // fundsInAddressBalance must be persisted in the serialized transaction
+      suiTx.suiTransaction.fundsInAddressBalance!.should.equal(FUNDS_IN_ADDRESS_BALANCE);
 
       const rawTx = tx.toBroadcastFormat();
       should.equal(utils.isValidRawTransaction(rawTx), true);
+
+      // Round-trip: rebuilt transaction must be bit-for-bit identical
+      const rebuilder = factory.from(rawTx);
+      rebuilder.addSignature({ pub: testData.sender.publicKey }, Buffer.from(testData.sender.signatureHex));
+      const rebuiltTx = await rebuilder.build();
+      rebuiltTx.toBroadcastFormat().should.equal(rawTx);
     });
 
     it('should build a sponsored transfer with coin objects + address balance', async function () {