feat(sdk-coin-sol): add ATA closure support for Solana wallets

TICKET: CHALO-174

Author: abhijeet8986

modules/sdk-coin-sol/src/lib/closeAtaBuilder.ts

@@ -7,10 +7,21 @@ import { Transaction } from './transaction';
 import { TransactionBuilder } from './transactionBuilder';
 import { validateAddress } from './utils';
 
+type CloseAtaApiMode = 'single' | 'bulk';
+
+const MIX_API_ERROR_MESSAGE =
+  'Cannot mix single-ATA API (accountAddress/destinationAddress/authorityAddress) with bulk-ATA API (addCloseAtaInstruction)';
+
 export class CloseAtaBuilder extends TransactionBuilder {
-  protected _accountAddress: string;
-  protected _destinationAddress: string;
-  protected _authorityAddress: string;
+  // Unified storage for all close entries (single or bulk)
+  protected _closeAtaEntries: { accountAddress: string; destinationAddress: string; authorityAddress: string }[] = [];
+
+  // Which API has been used on this builder instance. Locks in on first call so we can
+  // reject attempts to mix the legacy single-ATA setters with the bulk addCloseAtaInstruction().
+  // After initBuilder(): remains undefined for a single parsed close (either API may extend/edit);
+  // set to 'bulk' when the parsed tx had multiple closes so legacy setters cannot partially
+  // overwrite entry[0] while leaving other parsed entries in place.
+  private _apiMode: CloseAtaApiMode | undefined = undefined;
 
   constructor(_coinConfig: Readonly<CoinConfig>) {
     super(_coinConfig);
@@ -21,21 +32,90 @@ export class CloseAtaBuilder extends TransactionBuilder {
     return TransactionType.CloseAssociatedTokenAccount;
   }
 
+  /**
+   * Sets the ATA account address to close (single-ATA API, backward compatible).
+   * Cannot be mixed with addCloseAtaInstruction().
+   */
   accountAddress(accountAddress: string): this {
+    this._assertSingleAtaApiUsable();
     validateAddress(accountAddress, 'accountAddress');
-    this._accountAddress = accountAddress;
+    this._apiMode = 'single';
+    this._ensureSingleEntry();
+    this._closeAtaEntries[0].accountAddress = accountAddress;
     return this;
   }
 
+  /**
+   * Sets the destination address for rent SOL (single-ATA API, backward compatible).
+   * Cannot be mixed with addCloseAtaInstruction().
+   */
   destinationAddress(destinationAddress: string): this {
+    this._assertSingleAtaApiUsable();
     validateAddress(destinationAddress, 'destinationAddress');
-    this._destinationAddress = destinationAddress;
+    this._apiMode = 'single';
+    this._ensureSingleEntry();
+    this._closeAtaEntries[0].destinationAddress = destinationAddress;
     return this;
   }
 
+  /**
+   * Sets the authority address / ATA owner (single-ATA API, backward compatible).
+   * Cannot be mixed with addCloseAtaInstruction().
+   */
   authorityAddress(authorityAddress: string): this {
+    this._assertSingleAtaApiUsable();
+    validateAddress(authorityAddress, 'authorityAddress');
+    this._apiMode = 'single';
+    this._ensureSingleEntry();
+    this._closeAtaEntries[0].authorityAddress = authorityAddress;
+    return this;
+  }
+
+  /**
+   * Throws if the bulk-ATA API has already been used on this builder.
+   */
+  private _assertSingleAtaApiUsable(): void {
+    if (this._apiMode === 'bulk') {
+      throw new BuildTransactionError(MIX_API_ERROR_MESSAGE);
+    }
+  }
+
+  /**
+   * Ensures a single entry exists in _closeAtaEntries for the legacy API.
+   */
+  private _ensureSingleEntry(): void {
+    if (this._closeAtaEntries.length === 0) {
+      this._closeAtaEntries.push({ accountAddress: '', destinationAddress: '', authorityAddress: '' });
+    }
+  }
+
+  /**
+   * Add an ATA to close in this transaction (for bulk closure).
+   * Cannot be mixed with the single-ATA API (accountAddress/destinationAddress/authorityAddress).
+   *
+   * @param {string} accountAddress - the ATA address to close
+   * @param {string} destinationAddress - where rent SOL goes (root wallet address)
+   * @param {string} authorityAddress - ATA owner who must sign
+   */
+  addCloseAtaInstruction(accountAddress: string, destinationAddress: string, authorityAddress: string): this {
+    if (this._apiMode === 'single') {
+      throw new BuildTransactionError(MIX_API_ERROR_MESSAGE);
+    }
+
+    validateAddress(accountAddress, 'accountAddress');
+    validateAddress(destinationAddress, 'destinationAddress');
     validateAddress(authorityAddress, 'authorityAddress');
-    this._authorityAddress = authorityAddress;
+
+    if (accountAddress === destinationAddress) {
+      throw new BuildTransactionError('Account address to close cannot be the same as the destination address');
+    }
+
+    if (this._closeAtaEntries.some((entry) => entry.accountAddress === accountAddress)) {
+      throw new BuildTransactionError('Duplicate ATA address: ' + accountAddress);
+    }
+
+    this._apiMode = 'bulk';
+    this._closeAtaEntries.push({ accountAddress, destinationAddress, authorityAddress });
     return this;
   }
 
@@ -45,33 +125,42 @@ export class CloseAtaBuilder extends TransactionBuilder {
     for (const instruction of this._instructionsData) {
       if (instruction.type === InstructionBuilderTypes.CloseAssociatedTokenAccount) {
         const ataCloseInstruction: AtaClose = instruction;
-        this.accountAddress(ataCloseInstruction.params.accountAddress);
-        this.destinationAddress(ataCloseInstruction.params.destinationAddress);
-        this.authorityAddress(ataCloseInstruction.params.authorityAddress);
+        this._closeAtaEntries.push({
+          accountAddress: ataCloseInstruction.params.accountAddress,
+          destinationAddress: ataCloseInstruction.params.destinationAddress,
+          authorityAddress: ataCloseInstruction.params.authorityAddress,
+        });
       }
     }
+    if (this._closeAtaEntries.length > 1) {
+      this._apiMode = 'bulk';
+    }
   }
 
   /** @inheritdoc */
   protected async buildImplementation(): Promise<Transaction> {
-    assert(this._accountAddress, 'Account Address must be set before building the transaction');
-    assert(this._destinationAddress, 'Destination Address must be set before building the transaction');
-    assert(this._authorityAddress, 'Authority Address must be set before building the transaction');
+    assert(this._closeAtaEntries.length > 0, 'At least one ATA must be specified before building the transaction');
 
-    if (this._accountAddress === this._destinationAddress) {
-      throw new BuildTransactionError('Account address to close cannot be the same as the destination address');
-    }
+    for (const entry of this._closeAtaEntries) {
+      assert(entry.accountAddress, 'Account Address must be set before building the transaction');
+      assert(entry.destinationAddress, 'Destination Address must be set before building the transaction');
+      assert(entry.authorityAddress, 'Authority Address must be set before building the transaction');
 
-    const closeAssociatedTokenAccountData: AtaClose = {
-      type: InstructionBuilderTypes.CloseAssociatedTokenAccount,
-      params: {
-        accountAddress: this._accountAddress,
-        destinationAddress: this._destinationAddress,
-        authorityAddress: this._authorityAddress,
-      },
-    };
+      if (entry.accountAddress === entry.destinationAddress) {
+        throw new BuildTransactionError('Account address to close cannot be the same as the destination address');
+      }
+    }
 
-    this._instructionsData = [closeAssociatedTokenAccountData];
+    this._instructionsData = this._closeAtaEntries.map(
+      (entry): AtaClose => ({
+        type: InstructionBuilderTypes.CloseAssociatedTokenAccount,
+        params: {
+          accountAddress: entry.accountAddress,
+          destinationAddress: entry.destinationAddress,
+          authorityAddress: entry.authorityAddress,
+        },
+      })
+    );
 
     return await super.buildImplementation();
   }

modules/sdk-coin-sol/src/lib/utils.ts

@@ -333,6 +333,18 @@ export function getTransactionType(transaction: SolTransaction): TransactionType
   if (memoData?.includes('WalletConnectDefiCustomTx')) {
     return TransactionType.CustomTx;
   }
+  // Check for close ATA instructions before classifying as Send.
+  // A bulk close-ATA tx contains only closeAccount instructions (zero-balance ATAs).
+  // Note: This assumes close-ATA transactions never contain TokenTransfer instructions.
+  // This holds for Phase 1 where non-zero balance ATAs are rejected (user must consolidate first).
+  // If atomic transfer+close is added in the future, this detection needs refinement.
+  const hasCloseAta = instructions.some(
+    (instruction) => getInstructionType(instruction) === ValidInstructionTypesEnum.CloseAssociatedTokenAccount
+  );
+  if (hasCloseAta) {
+    return TransactionType.CloseAssociatedTokenAccount;
+  }
+
   if (instructions.filter((instruction) => getInstructionType(instruction) === 'Deactivate').length === 0) {
     for (const instruction of instructions) {
       const instructionType = getInstructionType(instruction);

modules/sdk-coin-sol/src/sol.ts

@@ -50,6 +50,7 @@ import {
   TransactionExplanation,
   TransactionParams,
   TransactionRecipient,
+  TransactionType,
   VerifyTransactionOptions,
   TssVerifyAddressOptions,
   verifyEddsaTssWalletAddress,
@@ -64,7 +65,8 @@ import {
   TransactionBuilderFactory,
   explainSolTransaction,
 } from './lib';
-import { TransactionExplanation as SolLibTransactionExplanation } from './lib/iface';
+import { AtaClose, TransactionExplanation as SolLibTransactionExplanation } from './lib/iface';
+import { InstructionBuilderTypes } from './lib/constants';
 import {
   getAssociatedTokenAccountAddress,
   getSolTokenFromAddress,
@@ -367,6 +369,33 @@ export class Sol extends BaseCoin {
     }
   }
 
+  /**
+   * Verifies that a close-ATA transaction only sends rent SOL to the wallet's root address.
+   * All CloseAssociatedTokenAccount instructions must have destinationAddress = walletRootAddress.
+   *
+   * No-op when `walletRootAddress` is not provided: the auto-detect caller in verifyTransaction()
+   * runs this for every close-ATA transaction, but wallets without a configured rootAddress
+   * (e.g. uninitialized or non-standard wallets) should not be blocked from verifyTransaction().
+   */
+  private verifyCloseAtaTransaction(transaction: Transaction, walletRootAddress: string | undefined): void {
+    if (!walletRootAddress) {
+      return;
+    }
+
+    const txJson = transaction.toJson();
+
+    for (const instruction of txJson.instructionsData) {
+      if (instruction.type === InstructionBuilderTypes.CloseAssociatedTokenAccount) {
+        const closeInstruction = instruction as AtaClose;
+        if (closeInstruction.params.destinationAddress !== walletRootAddress) {
+          throw new Error(
+            `Close ATA destination must be wallet root address. Expected ${walletRootAddress}, got ${closeInstruction.params.destinationAddress}`
+          );
+        }
+      }
+    }
+  }
+
   private hasSolVersionedTransactionData(
     txParams: TransactionParams
   ): txParams is TransactionParams & { solVersionedTransactionData: SolVersionedTransactionData } {
@@ -471,6 +500,7 @@ export class Sol extends BaseCoin {
     }
     transaction.fromRawTransaction(rawTxBase64);
     const explainedTx = transaction.explainTransaction();
+    const isCloseAssociatedTokenAccountTx = transaction.type === TransactionType.CloseAssociatedTokenAccount;
 
     if (txParams.type === 'enabletoken' && verificationOptions?.verifyTokenEnablement) {
       this.verifyTxType(txParams.type, explainedTx.type);
@@ -481,8 +511,13 @@ export class Sol extends BaseCoin {
       await this.verifyTokenAddress(tokenEnablementsPrebuild, enableTokensConfig);
     }
 
+    if (isCloseAssociatedTokenAccountTx) {
+      this.verifyCloseAtaTransaction(transaction, walletRootAddress);
+    }
+
     // users do not input recipients for consolidation requests as they are generated by the server
-    if (txParams.recipients !== undefined) {
+    // Close-ATA txs do not populate explainedTx.outputs; recipients carry ATA addresses for intent only.
+    if (txParams.recipients !== undefined && !isCloseAssociatedTokenAccountTx) {
       const filteredRecipients = txParams.recipients?.map((recipient) =>
         _.pick(recipient, ['address', 'amount', 'tokenName'])
       );
@@ -580,7 +615,7 @@ export class Sol extends BaseCoin {
     if (memo && memo.value !== explainedTx.memo) {
       throw new Error('Tx memo does not match with expected txParams recipient memo');
     }
-    if (txParams.recipients) {
+    if (txParams.recipients && !isCloseAssociatedTokenAccountTx) {
       for (const recipients of txParams.recipients) {
         // totalAmount based on each token
         const assetName = recipients.tokenName || this.getChain();

modules/sdk-coin-sol/test/unit/sol.ts

@@ -280,6 +280,41 @@ describe('SOL:', function () {
       validTransaction.should.equal(true);
     });
 
+    it('should verify bulk close-ATA tx when txParams.recipients is present (outputs not populated)', async function () {
+      const accountKeys = new KeyPair(resources.authAccount).getKeys();
+      const nonceAccountKeys = new KeyPair(resources.nonceAccount).getKeys();
+      const account2Keys = new KeyPair(resources.authAccount2).getKeys();
+      const ataAddress1 = nonceAccountKeys.pub;
+      const ataAddress2 = account2Keys.pub;
+
+      const txBuilder = factory.getCloseAtaInitializationBuilder();
+      txBuilder.nonce(blockHash);
+      txBuilder.sender(accountKeys.pub);
+      txBuilder.addCloseAtaInstruction(ataAddress1, accountKeys.pub, accountKeys.pub);
+      txBuilder.addCloseAtaInstruction(ataAddress2, accountKeys.pub, accountKeys.pub);
+      const built = await txBuilder.build();
+      const txPrebuild = {
+        txBase64: built.toBroadcastFormat(),
+        txInfo: {
+          feePayer: accountKeys.pub,
+          nonce: blockHash,
+        },
+        coin: 'tsol',
+      };
+
+      const validTransaction = await basecoin.verifyTransaction({
+        txParams: {
+          recipients: [
+            { address: ataAddress1, amount: '0' },
+            { address: ataAddress2, amount: '0' },
+          ],
+        },
+        txPrebuild,
+        wallet: walletObj,
+      } as any);
+      validTransaction.should.equal(true);
+    });
+
     it('should fail verify transactions when have different memo', async function () {
       const txParams = newTxParams();
       const txPrebuild = newTxPrebuild();