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

TICKET: CHALO-174

Author: abhijeet8986

modules/express/src/clientRoutes.ts

@@ -1096,6 +1096,49 @@ export async function handleV2EnableTokens(req: ExpressApiRouteRequest<'express.
   }
 }
 
+/**
+ * Handle close ATA request
+ * @param req
+ */
+export async function handleV2CloseAta(req: ExpressApiRouteRequest<'express.v2.wallet.closeata', 'post'>) {
+  const bitgo = req.bitgo;
+  const coin = bitgo.coin(req.decoded.coin);
+
+  if (!req.body.ataAddresses || !_.isArray(req.body.ataAddresses) || req.body.ataAddresses.length === 0) {
+    throw new Error('ataAddresses must be a non-empty array of addresses');
+  }
+
+  const wallet = await coin.wallets().get({ id: req.decoded.id });
+
+  let result: any;
+  try {
+    if (coin.supportsTss()) {
+      result = await wallet.sendCloseAtas(createTSSSendParams(req, wallet));
+    } else {
+      result = await wallet.sendCloseAtas(createSendParams(req));
+    }
+  } catch (err) {
+    err.status = 400;
+    throw err;
+  }
+
+  if (result.failure.length && result.failure.length > 0) {
+    let msg = '';
+    let status = 202;
+
+    if (result.success.length && result.success.length > 0) {
+      msg = `Close ATA transactions failed: ${result.failure.length} and succeeded: ${result.success.length}`;
+    } else {
+      status = 400;
+      msg = `All close ATA transactions failed`;
+    }
+
+    throw apiResponse(status, result, msg);
+  }
+
+  return result;
+}
+
 /**
  * Handle Update Wallet
  * @param req
@@ -1798,6 +1841,9 @@ export function setupAPIRoutes(app: express.Application, config: Config): void {
   // token enablement
   router.post('express.v2.wallet.enableTokens', [prepareBitGo(config), typedPromiseWrapper(handleV2EnableTokens)]);
 
+  // close ATA
+  router.post('express.v2.wallet.closeata', [prepareBitGo(config), typedPromiseWrapper(handleV2CloseAta)]);
+
   // unspent changes
   router.post('express.wallet.consolidateunspents', [
     prepareBitGo(config),

modules/express/src/typedRoutes/api/index.ts

@@ -46,6 +46,7 @@ import { PostOfcExtSignPayload } from './v2/ofcExtSignPayload';
 import { PostLightningWalletPayment } from './v2/lightningPayment';
 import { PostLightningWalletWithdraw } from './v2/lightningWithdraw';
 import { PutV2PendingApproval } from './v2/pendingApproval';
+import { PostCloseAta } from './v2/closeAta';
 import { PostConsolidateAccount } from './v2/consolidateAccount';
 import { PostCanonicalAddress } from './v2/canonicalAddress';
 import { PostWalletEnableTokens } from './v2/walletEnableTokens';
@@ -176,6 +177,12 @@ export const ExpressV2WalletConsolidateAccountApiSpec = apiSpec({
   },
 });
 
+export const ExpressV2WalletCloseAtaApiSpec = apiSpec({
+  'express.v2.wallet.closeata': {
+    post: PostCloseAta,
+  },
+});
+
 export const ExpressWalletFanoutUnspentsApiSpec = apiSpec({
   'express.v1.wallet.fanoutunspents': {
     put: PutFanoutUnspents,
@@ -358,6 +365,7 @@ export type ExpressApi = typeof ExpressPingApiSpec &
   typeof ExpressV1PendingApprovalConstructTxApiSpec &
   typeof ExpressWalletConsolidateUnspentsApiSpec &
   typeof ExpressV2WalletConsolidateAccountApiSpec &
+  typeof ExpressV2WalletCloseAtaApiSpec &
   typeof ExpressWalletFanoutUnspentsApiSpec &
   typeof ExpressV2WalletCreateAddressApiSpec &
   typeof ExpressV2WalletIsWalletAddressApiSpec &
@@ -403,6 +411,7 @@ export const ExpressApi: ExpressApi = {
   ...ExpressWalletFanoutUnspentsApiSpec,
   ...ExpressV2WalletCreateAddressApiSpec,
   ...ExpressV2WalletConsolidateAccountApiSpec,
+  ...ExpressV2WalletCloseAtaApiSpec,
   ...ExpressV2WalletIsWalletAddressApiSpec,
   ...ExpressKeychainLocalApiSpec,
   ...ExpressKeychainChangePasswordApiSpec,

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

@@ -0,0 +1,92 @@
+import * as t from 'io-ts';
+import { httpRoute, httpRequest, optional } from '@api-ts/io-ts-http';
+import { BitgoExpressError } from '../../schemas/error';
+
+/**
+ * Path parameters for close ATA endpoint
+ */
+export const CloseAtaParams = {
+  /** Coin identifier (e.g., 'sol', 'tsol') */
+  coin: t.string,
+  /** Wallet ID */
+  id: t.string,
+} as const;
+
+/**
+ * Request body for closing Associated Token Accounts
+ * Based on BuildCloseAtaOptions which extends PrebuildTransactionOptions and WalletSignTransactionOptions
+ */
+export const CloseAtaRequestBody = {
+  /** ATA addresses to close (required) */
+  ataAddresses: t.array(t.string),
+
+  /** Wallet passphrase to decrypt the user key */
+  walletPassphrase: optional(t.string),
+  /** Extended private key (alternative to walletPassphrase) */
+  xprv: optional(t.string),
+  /** One-time password for 2FA */
+  otp: optional(t.string),
+
+  /** Memo to include in the transaction */
+  memo: optional(t.string),
+  /** Fee rate for the transaction */
+  feeRate: optional(t.number),
+  /** Maximum fee rate */
+  maxFeeRate: optional(t.number),
+
+  /** Transaction request ID */
+  txRequestId: optional(t.string),
+
+  /** Private key for signing (from WalletSignBaseOptions) */
+  prv: optional(t.string),
+  /** Array of public keys */
+  pubs: optional(t.array(t.string)),
+} as const;
+
+/**
+ * Response for close ATA operation
+ * Returns arrays of successful and failed close ATA transactions
+ */
+export const CloseAtaResponse = t.type({
+  /** Array of successfully sent close ATA transactions */
+  success: t.array(t.unknown),
+  /** Array of errors from failed close ATA transactions */
+  failure: t.array(t.unknown),
+});
+
+/**
+ * Response for partial success or failure cases (202/400)
+ */
+export const CloseAtaErrorResponse = t.intersection([CloseAtaResponse, BitgoExpressError]);
+
+/**
+ * Close Associated Token Accounts
+ *
+ * This endpoint closes zero-balance Solana Associated Token Accounts (ATAs), returning
+ * the rent SOL (~0.002 SOL per ATA) to the wallet's root address.
+ *
+ * ATAs with non-zero token balance will be rejected — tokens must be consolidated first.
+ * Multiple ATAs can be batched into a single transaction (max ~27 per tx).
+ * ATAs owned by different receive addresses are grouped into separate transactions.
+ *
+ * The API may return partial success (status 202) if some batches succeed but others fail.
+ *
+ * @operationId express.v2.wallet.closeata
+ * @tag express
+ */
+export const PostCloseAta = httpRoute({
+  path: '/api/v2/{coin}/wallet/{id}/closeAta',
+  method: 'POST',
+  request: httpRequest({
+    params: CloseAtaParams,
+    body: CloseAtaRequestBody,
+  }),
+  response: {
+    /** Successfully closed ATAs */
+    200: CloseAtaResponse,
+    /** Partial success - some succeeded, others failed */
+    202: CloseAtaErrorResponse,
+    /** All closures failed */
+    400: CloseAtaErrorResponse,
+  },
+});

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

@@ -8,9 +8,11 @@ import { TransactionBuilder } from './transactionBuilder';
 import { validateAddress } from './utils';
 
 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 }[] = [];
+
+  // Track whether the legacy single-ATA API is being used
+  private _usingSingleAtaApi = false;
 
   constructor(_coinConfig: Readonly<CoinConfig>) {
     super(_coinConfig);
@@ -21,21 +23,79 @@ 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 {
     validateAddress(accountAddress, 'accountAddress');
-    this._accountAddress = accountAddress;
+    this._usingSingleAtaApi = true;
+    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 {
     validateAddress(destinationAddress, 'destinationAddress');
-    this._destinationAddress = destinationAddress;
+    this._usingSingleAtaApi = true;
+    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 {
     validateAddress(authorityAddress, 'authorityAddress');
-    this._authorityAddress = authorityAddress;
+    this._usingSingleAtaApi = true;
+    this._ensureSingleEntry();
+    this._closeAtaEntries[0].authorityAddress = authorityAddress;
+    return this;
+  }
+
+  /**
+   * 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._usingSingleAtaApi) {
+      throw new BuildTransactionError(
+        'Cannot mix addCloseAtaInstruction() with single-ATA API (accountAddress/destinationAddress/authorityAddress)'
+      );
+    }
+
+    validateAddress(accountAddress, 'accountAddress');
+    validateAddress(destinationAddress, 'destinationAddress');
+    validateAddress(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._closeAtaEntries.push({ accountAddress, destinationAddress, authorityAddress });
     return this;
   }
 
@@ -45,33 +105,39 @@ 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,
+        });
       }
     }
   }
 
   /** @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);