@lombard.finance/sdk-solana 1.2.2 → 2.0.0

package/src/web3Sdk/deposit/deposit.test.ts

@@ -0,0 +1,327 @@
+import { PublicKey } from '@solana/web3.js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { IConfig } from '../../const/getConfig';
+import { type ISolanaWalletProvider, SolanaNetwork } from '../../types';
+import { ErrorCode, SolanaSdkError } from '../../utils';
+
+// ── Constants ──
+
+const MOCK_LBTC_MINT = 'LBTCojyVJ63rsEED2DLEGWMzSxWJyQynXE91LMLgV1J';
+const MOCK_BTCB_MINT = 'BTCB3ripBAut19jM8kDPVbJHb2ZdR2GcZvGZkCmFPtV8';
+const MOCK_ASSET_ROUTER = 'LomVyJDZ91jeVbNnTupJXKJTQFakJVMc87CmwDHYt95';
+const MOCK_MAILBOX = 'LomJw912MoUd7iiAesTQAgz1paLcTqi6ndG3w3pnKH9';
+const MOCK_SOLANA_CHAIN_ID = '0259db5080fc2c6d3bcf7ca90712d3c2e5e6c28f27f0dfbb9953bdb0894c03ab';
+const MOCK_LEDGER_CHAIN_ID = '031f51c4e4cc1dae1c752d2f8fe2ae045da668a13f2e47a465964d630f5ed22e';
+const MOCK_PAYER = '8yarEiDaJVikHZbk3PQSoWiDn2T3oM1FHZN1Jv4VZFdr';
+const MOCK_RECIPIENT = 'DVMiNi7uxHEPABTBt1nLMoxnPniPKbLAFj4MPJq1RDjg';
+/** Distinct pubkey returned for ATA(mint=LBTC, owner=recipient) */
+const MOCK_RECIPIENT_ATA = 'GRq2yasTvWWPPqSwxCZvqfCTfDhP3MswDH4nW2v6F5To';
+/** Distinct pubkey returned for ATA(mint=BTC.b, owner=payer) */
+const MOCK_PAYER_ATA = 'GfYV1f1bR9vy41mSyQ8quxYbds121kijSBj5A3nG8oDQ';
+
+const fullConfig: IConfig = {
+  lbtcTokenMint: MOCK_LBTC_MINT,
+  btcbTokenMint: MOCK_BTCB_MINT,
+  assetRouter: MOCK_ASSET_ROUTER,
+  mailbox: MOCK_MAILBOX,
+  solanaRoutingChainId: MOCK_SOLANA_CHAIN_ID,
+  bitcoinRoutingChainId: 'ff000008819873e925422c1ff0f99f7cc9bbb232af63a077a480a3633bee1ef6',
+  ledgerChainId: MOCK_LEDGER_CHAIN_ID,
+  lbtcProgramId: 'HEY7PCJe3GB27UWdopuYb1xDbB5SNtTcYPxRjntvfBSA',
+  treasuryAddress: 'ByHNGi4zPJw5StyWZoLQJ9n2wT12oupJF2pTSNKMnnAZ',
+  bascule: null,
+  basculeData: null,
+  admin: '6MKjyWZnkSMitJYAixvJzqhJiVsjTA3hYHX8aP9qNioj',
+  lzOftAdapter: 'AEFwQgaSNhQcZhAcGZGM9iTyGML3fsJC2aBvYmzV81FE',
+  lzOftStore: '3SG3oyrG3KSvJ9bbxPDu7ZXEe5o1TW1QkgudkKvK6FK4',
+  lzMultisig: 'GfYV1f1bR9vy41mSyQ8quxYbds121kijSBj5A3nG8oDQ',
+  lzEscrow: 'GRq2yasTvWWPPqSwxCZvqfCTfDhP3MswDH4nW2v6F5To',
+  consortium: null,
+  ratioOracle: null,
+  bridge: null,
+  lombardTokenPool: null,
+};
+
+// ── Mocks ──
+
+vi.mock('../../const/getConfig', () => ({
+  DEFAULT_ENV: 'dev' as const,
+  networkToEnv: { devnet: 'dev', testnet: 'testnet', 'mainnet-beta': 'prod' },
+  getConfig: vi.fn(() => fullConfig),
+}));
+
+function buildArConfigData(paused = false) {
+  const data = Buffer.alloc(145, 0);
+  const treasury = new PublicKey(MOCK_PAYER);
+  treasury.toBuffer().copy(data, 72);
+  data[104] = paused ? 1 : 0;
+  data.writeBigUInt64LE(42n, 137);
+  return data;
+}
+
+function buildMailboxConfigData() {
+  const data = Buffer.alloc(145, 0);
+  const treasury = new PublicKey(MOCK_PAYER);
+  treasury.toBuffer().copy(data, 72);
+  data.writeBigUInt64LE(42n, 137);
+  return data;
+}
+
+const arConfigPDA = PublicKey.findProgramAddressSync(
+  [Buffer.from('asset_router_config')],
+  new PublicKey(MOCK_ASSET_ROUTER),
+)[0];
+
+function defaultGetAccountInfo(pubkey: PublicKey) {
+  if (pubkey.toBase58() === arConfigPDA.toBase58()) {
+    return Promise.resolve({ data: buildArConfigData() });
+  }
+  return Promise.resolve({ data: buildMailboxConfigData() });
+}
+
+const mockConnection = {
+  getAccountInfo: vi.fn().mockImplementation(defaultGetAccountInfo),
+  getTokenAccountBalance: vi.fn().mockResolvedValue({
+    value: { amount: '999999999', uiAmountString: '9.99' },
+  }),
+};
+
+vi.mock('../../const/rpcUrls', () => ({
+  getConnection: vi.fn(() => mockConnection),
+}));
+
+vi.mock('../../utils/tokenAccount', () => ({
+  getTokenProgramForMint: vi.fn().mockResolvedValue(new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')),
+}));
+
+vi.mock('../../idl/getAssetRouterIdl', () => ({
+  getAssetRouterIdl: vi.fn(() => ({
+    address: MOCK_ASSET_ROUTER,
+    metadata: { name: 'asset_router', version: '0.1.0', spec: '0.1.0' },
+    instructions: [],
+  })),
+}));
+
+vi.mock('@solana/spl-token', () => ({
+  getAssociatedTokenAddress: vi
+    .fn()
+    .mockImplementation(async (mint: PublicKey) => {
+      if (mint.toBase58() === MOCK_LBTC_MINT) {
+        return new PublicKey(MOCK_RECIPIENT_ATA);
+      }
+      return new PublicKey(MOCK_PAYER_ATA);
+    }),
+  ASSOCIATED_TOKEN_PROGRAM_ID: new PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'),
+}));
+
+const mockTx = { instructions: [{ keys: [] }] };
+const mockMethods = {
+  deposit: vi.fn().mockReturnValue({
+    accounts: vi.fn().mockReturnValue({
+      transaction: vi.fn().mockResolvedValue(mockTx),
+    }),
+  }),
+};
+
+vi.mock('@coral-xyz/anchor', () => ({
+  Program: vi.fn().mockImplementation(() => ({ methods: mockMethods })),
+  BN: vi.fn().mockImplementation((v: string) => ({ toString: () => v })),
+}));
+
+vi.mock('../../utils', async () => {
+  const actual = await vi.importActual('../../utils');
+  return {
+    ...actual,
+    sendAndConfirmTransaction: vi.fn().mockResolvedValue({
+      signature: 'mock-deposit-sig',
+    }),
+  };
+});
+
+const baseParams = {
+  amount: '100000',
+  recipient: MOCK_RECIPIENT,
+  network: SolanaNetwork.devnet,
+};
+
+function testWallet(pubkeyBase58: string): ISolanaWalletProvider {
+  const pk = new PublicKey(pubkeyBase58);
+  return {
+    isConnected: true,
+    publicKey: pk,
+    connect: async () => {},
+    disconnect: async () => {},
+    signMessage: async () => ({ signature: new Uint8Array(), publicKey: pk }),
+    signTransaction: async <T>(tx: T) => tx,
+    signAllTransactions: async <T>(txs: T[]) => txs,
+  };
+}
+
+const disconnectedWallet: ISolanaWalletProvider = {
+  isConnected: false,
+  publicKey: null as unknown as PublicKey,
+  connect: async () => {},
+  disconnect: async () => {},
+  signMessage: async () => {
+    throw new Error('not used');
+  },
+  signTransaction: async <T>(tx: T) => tx,
+  signAllTransactions: async <T>(txs: T[]) => txs,
+};
+
+describe('deposit', () => {
+  let depositFn: typeof import('./deposit').deposit;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockConnection.getAccountInfo.mockImplementation(defaultGetAccountInfo);
+    mockConnection.getTokenAccountBalance.mockResolvedValue({
+      value: { amount: '999999999', uiAmountString: '9.99' },
+    });
+    const mod = await import('./deposit');
+    depositFn = mod.deposit;
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should throw when wallet is not connected', async () => {
+    await expect(depositFn(disconnectedWallet, baseParams)).rejects.toThrow(
+      'Wallet not connected',
+    );
+  });
+
+  it('should throw when Asset Router is not configured', async () => {
+    const { getConfig } = await import('../../const/getConfig');
+    vi.mocked(getConfig).mockReturnValueOnce({ ...fullConfig, assetRouter: null });
+
+    await expect(
+      depositFn(testWallet(MOCK_PAYER), baseParams),
+    ).rejects.toThrow('Asset Router not configured');
+  });
+
+  it('should throw when Mailbox is not configured', async () => {
+    const { getConfig } = await import('../../const/getConfig');
+    vi.mocked(getConfig).mockReturnValueOnce({ ...fullConfig, mailbox: null });
+
+    await expect(
+      depositFn(testWallet(MOCK_PAYER), baseParams),
+    ).rejects.toThrow('Mailbox not configured');
+  });
+
+  it('should throw when Solana routing chain ID is not configured', async () => {
+    const { getConfig } = await import('../../const/getConfig');
+    vi.mocked(getConfig).mockReturnValueOnce({
+      ...fullConfig,
+      solanaRoutingChainId: null,
+    });
+
+    await expect(
+      depositFn(testWallet(MOCK_PAYER), baseParams),
+    ).rejects.toThrow('Solana routing chain ID not configured');
+  });
+
+  it('should throw when source token mint is not resolved', async () => {
+    const { getConfig } = await import('../../const/getConfig');
+    vi.mocked(getConfig).mockReturnValueOnce({ ...fullConfig, btcbTokenMint: '' });
+
+    await expect(
+      depositFn(testWallet(MOCK_PAYER), baseParams),
+    ).rejects.toThrow('Source token mint not configured');
+  });
+
+  it('should throw when destination token is not configured', async () => {
+    const { getConfig } = await import('../../const/getConfig');
+    vi.mocked(getConfig).mockReturnValueOnce({ ...fullConfig, lbtcTokenMint: '' });
+
+    await expect(
+      depositFn(testWallet(MOCK_PAYER), baseParams),
+    ).rejects.toThrow('Destination token not configured');
+  });
+
+  it('should throw when amount is zero', async () => {
+    await expect(
+      depositFn(testWallet(MOCK_PAYER), { ...baseParams, amount: '0' }),
+    ).rejects.toThrow('greater than zero');
+  });
+
+  it('should throw when Asset Router is paused', async () => {
+    mockConnection.getAccountInfo.mockImplementation((pubkey: PublicKey) => {
+      if (pubkey.toBase58() === arConfigPDA.toBase58()) {
+        return Promise.resolve({ data: buildArConfigData(true) });
+      }
+      return Promise.resolve({ data: buildMailboxConfigData() });
+    });
+
+    await expect(
+      depositFn(testWallet(MOCK_PAYER), baseParams),
+    ).rejects.toThrow('Asset Router is paused');
+  });
+
+  it('should throw on insufficient balance', async () => {
+    mockConnection.getTokenAccountBalance.mockResolvedValue({
+      value: { amount: '10', uiAmountString: '0.0000001' },
+    });
+
+    await expect(
+      depositFn(testWallet(MOCK_PAYER), baseParams),
+    ).rejects.toThrow('Insufficient balance');
+  });
+
+  it('should throw when Ledger chain ID is not configured', async () => {
+    const { getConfig } = await import('../../const/getConfig');
+    vi.mocked(getConfig).mockReturnValueOnce({ ...fullConfig, ledgerChainId: null });
+
+    await expect(
+      depositFn(testWallet(MOCK_PAYER), baseParams),
+    ).rejects.toThrow('Ledger chain ID not configured');
+  });
+
+  it('should return transaction signature on success', async () => {
+    mockConnection.getAccountInfo.mockResolvedValue({ data: buildMailboxConfigData() });
+
+    const sig = await depositFn(testWallet(MOCK_PAYER), baseParams);
+
+    expect(sig).toBe('mock-deposit-sig');
+  });
+
+  it('should pass destination associated token account bytes to deposit()', async () => {
+    mockConnection.getAccountInfo.mockResolvedValue({ data: buildMailboxConfigData() });
+
+    await depositFn(testWallet(MOCK_PAYER), baseParams);
+
+    expect(mockMethods.deposit).toHaveBeenCalled();
+    const recipientArg = mockMethods.deposit.mock.calls[0][2] as number[];
+    expect(recipientArg).toEqual(
+      Array.from(new PublicKey(MOCK_RECIPIENT_ATA).toBytes()),
+    );
+  });
+
+  it('should wrap errors with SolanaSdkError', async () => {
+    const { getConfig } = await import('../../const/getConfig');
+    vi.mocked(getConfig).mockReturnValueOnce({ ...fullConfig, assetRouter: null });
+
+    try {
+      await depositFn(testWallet(MOCK_PAYER), baseParams);
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(SolanaSdkError);
+      expect((err as SolanaSdkError).code).toBe(ErrorCode.DEPOSIT_REJECTED);
+    }
+  });
+
+  it('should use env override when provided', async () => {
+    mockConnection.getAccountInfo.mockResolvedValue({ data: buildMailboxConfigData() });
+
+    const { getConfig } = await import('../../const/getConfig');
+
+    await depositFn(testWallet(MOCK_PAYER), {
+      ...baseParams,
+      env: 'stage',
+    });
+
+    expect(getConfig).toHaveBeenCalledWith('stage');
+  });
+});

package/src/web3Sdk/deposit/deposit.ts

@@ -0,0 +1,339 @@
+import { BN, Program } from '@coral-xyz/anchor';
+import { Env } from '@lombard.finance/sdk-common';
+import {
+  ASSOCIATED_TOKEN_PROGRAM_ID,
+  getAssociatedTokenAddress,
+} from '@solana/spl-token';
+import { PublicKey, SystemProgram } from '@solana/web3.js';
+
+import { DEFAULT_ENV, getConfig, networkToEnv } from '../../const/getConfig';
+import { getConnection } from '../../const/rpcUrls';
+import { getAssetRouterIdl } from '../../idl/getAssetRouterIdl';
+import { ISolanaWalletProvider, SolanaNetwork } from '../../types';
+import {
+  ErrorCode,
+  sendAndConfirmTransaction,
+  SolanaSdkError,
+} from '../../utils';
+import { createDebugLogger } from '../../utils/createDebugLogger';
+import { getTokenProgramForMint } from '../../utils/tokenAccount';
+import { validateAmount } from '../redeemToken/shared';
+
+export interface DepositParams {
+  amount: string;
+  /**
+   * Owner wallet that will receive the destination token (e.g. LBTC).
+   * Solana pubkey (base58). The GMP payload uses the associated token account
+   * for `toTokenAddress` / default LBTC mint — matching api backend and claimer expectations.
+   */
+  recipient: string;
+  /**
+   * Source token mint to burn (e.g. BTC.b). Defaults to `config.btcbTokenMint`.
+   */
+  sourceTokenMint?: string;
+  /**
+   * Destination Lombard routing chain ID (hex, 32 bytes).
+   * Defaults to `config.solanaRoutingChainId` (same-chain deposit).
+   */
+  toLchainId?: string;
+  /**
+   * Destination token address / mint (e.g. LBTC). Defaults to `config.lbtcTokenMint`.
+   */
+  toTokenAddress?: string;
+  network: SolanaNetwork;
+  env?: Env;
+  rpcUrl?: string;
+  debug?: boolean;
+  skipPreflight?: boolean;
+}
+
+/**
+ * Deposit (swap) source token to destination token via Asset Router's `deposit` instruction.
+ *
+ * Burns the source token (e.g. BTC.b) and sends a GMP message through the Mailbox
+ * to mint the destination token (e.g. LBTC) to the recipient's ATA for that mint.
+ *
+ * Default flow (all optional params omitted): BTC.b → LBTC on Solana.
+ */
+export async function deposit(
+  provider: ISolanaWalletProvider,
+  params: DepositParams,
+): Promise<string> {
+  const {
+    amount,
+    recipient,
+    network,
+    env: envOverride,
+    rpcUrl,
+    debug = false,
+    skipPreflight = true,
+  } = params;
+  const { debugLog, printLogs } = createDebugLogger({ debug });
+
+  try {
+    if (!provider.publicKey) {
+      throw new Error('Wallet not connected');
+    }
+
+    const env = envOverride ?? networkToEnv[network] ?? DEFAULT_ENV;
+    const config = getConfig(env);
+
+    if (!config.assetRouter) {
+      throw new Error(`Asset Router not configured for network: ${network}`);
+    }
+    if (!config.mailbox) {
+      throw new Error(`Mailbox not configured for network: ${network}`);
+    }
+    if (!config.solanaRoutingChainId) {
+      throw new Error(
+        `Solana routing chain ID not configured for network: ${network}`,
+      );
+    }
+
+    const sourceMintAddress = params.sourceTokenMint ?? config.btcbTokenMint;
+    if (!sourceMintAddress) {
+      throw new Error(
+        `Source token mint not configured for network: ${network}`,
+      );
+    }
+
+    const toLchainIdHex = params.toLchainId ?? config.solanaRoutingChainId;
+    const toTokenAddressStr = params.toTokenAddress ?? config.lbtcTokenMint;
+    if (!toTokenAddressStr) {
+      throw new Error(
+        `Destination token not configured for network: ${network}`,
+      );
+    }
+
+    validateAmount(amount);
+
+    const connection = getConnection(network, rpcUrl);
+    const payer = new PublicKey(provider.publicKey);
+    const mint = new PublicKey(sourceMintAddress);
+    const recipientPubkey = new PublicKey(recipient);
+    const assetRouterProgramId = new PublicKey(config.assetRouter);
+    const mailboxProgramId = new PublicKey(config.mailbox);
+    const solanaRoutingChainId = Buffer.from(
+      config.solanaRoutingChainId,
+      'hex',
+    );
+    const toLchainId = Buffer.from(toLchainIdHex, 'hex');
+    const destinationMint = new PublicKey(toTokenAddressStr);
+    const toTokenAddress = destinationMint.toBytes();
+
+    debugLog('Payer:', payer.toBase58());
+    debugLog('Mint (source, e.g. BTC.b):', mint.toBase58());
+    debugLog('Destination token (e.g. LBTC):', toTokenAddressStr);
+    debugLog('Recipient (owner):', recipientPubkey.toBase58());
+    debugLog('Amount:', amount);
+
+    const [tokenProgramId, destinationTokenProgramId] = await Promise.all([
+      getTokenProgramForMint(connection, mint),
+      getTokenProgramForMint(connection, destinationMint),
+    ]);
+    debugLog('Source token program:', tokenProgramId.toBase58());
+    debugLog('Destination token program:', destinationTokenProgramId.toBase58());
+
+    const [assetRouterConfigPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('asset_router_config')],
+      assetRouterProgramId,
+    );
+    const [tokenRoutePDA] = PublicKey.findProgramAddressSync(
+      [
+        Buffer.from('token_route'),
+        solanaRoutingChainId,
+        mint.toBuffer(),
+        toLchainId,
+        Buffer.from(toTokenAddress),
+      ],
+      assetRouterProgramId,
+    );
+    const [messagingAuthorityPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('messaging_authority')],
+      assetRouterProgramId,
+    );
+
+    debugLog('Asset Router config PDA:', assetRouterConfigPDA.toBase58());
+    debugLog('Token route PDA:', tokenRoutePDA.toBase58());
+    debugLog('Messaging authority PDA:', messagingAuthorityPDA.toBase58());
+
+    const [mailboxConfigPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('mailbox_config')],
+      mailboxProgramId,
+    );
+    if (!config.ledgerChainId) {
+      throw new Error(
+        `Ledger chain ID not configured for network: ${network}`,
+      );
+    }
+    const ledgerChainId = Buffer.from(config.ledgerChainId, 'hex');
+    const [outboundMessagePathPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('outbound_message_path'), ledgerChainId],
+      mailboxProgramId,
+    );
+    const [senderConfigPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('sender_config'), assetRouterProgramId.toBuffer()],
+      mailboxProgramId,
+    );
+
+    debugLog('Mailbox config PDA:', mailboxConfigPDA.toBase58());
+    debugLog(
+      'Outbound message path PDA:',
+      outboundMessagePathPDA.toBase58(),
+    );
+    debugLog('Sender config PDA:', senderConfigPDA.toBase58());
+
+    const [arConfigInfo, mailboxConfigInfo] = await Promise.all([
+      connection.getAccountInfo(assetRouterConfigPDA),
+      connection.getAccountInfo(mailboxConfigPDA),
+    ]);
+
+    if (!arConfigInfo) {
+      throw new Error('Asset Router config account not found');
+    }
+    if (!mailboxConfigInfo) {
+      throw new Error('Mailbox config account not found');
+    }
+
+    if (arConfigInfo.data.length < 105) {
+      throw new Error(
+        `Asset Router config account data too short: expected >= 105 bytes, got ${arConfigInfo.data.length}`,
+      );
+    }
+    const paused = arConfigInfo.data[104] !== 0;
+    if (paused) {
+      throw new Error('Asset Router is paused');
+    }
+
+    if (mailboxConfigInfo.data.length < 104) {
+      throw new Error(
+        `Mailbox config account data too short: expected >= 104 bytes, got ${mailboxConfigInfo.data.length}`,
+      );
+    }
+    const mailboxTreasury = new PublicKey(
+      mailboxConfigInfo.data.subarray(72, 104),
+    );
+    debugLog('Mailbox treasury:', mailboxTreasury.toBase58());
+
+    const payerTokenAccount = await getAssociatedTokenAddress(
+      mint,
+      payer,
+      false,
+      tokenProgramId,
+      ASSOCIATED_TOKEN_PROGRAM_ID,
+    );
+    const recipientTokenAccount = await getAssociatedTokenAddress(
+      destinationMint,
+      recipientPubkey,
+      false,
+      destinationTokenProgramId,
+      ASSOCIATED_TOKEN_PROGRAM_ID,
+    );
+    debugLog('Payer token account:', payerTokenAccount.toBase58());
+    debugLog('Recipient token account (payload):', recipientTokenAccount.toBase58());
+
+    const tokenBalance =
+      await connection.getTokenAccountBalance(payerTokenAccount);
+    const userBalance = BigInt(tokenBalance.value.amount);
+    const parsedAmount = BigInt(amount);
+    if (userBalance < parsedAmount) {
+      throw new Error(
+        `Insufficient balance: have ${tokenBalance.value.uiAmountString}, need ${Number(parsedAmount) / 1e8}`,
+      );
+    }
+
+    const assetRouterProgram = new Program(
+      getAssetRouterIdl(env),
+      { connection },
+    );
+
+    const toLchainIdArray = Array.from(toLchainId);
+    const toTokenAddressArray = Array.from(toTokenAddress);
+    const recipientArray = Array.from(recipientTokenAccount.toBytes());
+
+    const MAX_NONCE_RETRIES = 3;
+    for (let attempt = 0; attempt < MAX_NONCE_RETRIES; attempt++) {
+      const freshMailboxConfig =
+        await connection.getAccountInfo(mailboxConfigPDA);
+      if (!freshMailboxConfig) {
+        throw new Error('Mailbox config account not found');
+      }
+      if (freshMailboxConfig.data.length < 145) {
+        throw new Error(
+          `Mailbox config account data too short: expected >= 145 bytes, got ${freshMailboxConfig.data.length}`,
+        );
+      }
+      const globalNonce = freshMailboxConfig.data.readBigUInt64LE(137);
+      const nonceBuf = Buffer.alloc(8);
+      nonceBuf.writeBigUInt64BE(globalNonce);
+
+      const [outboundMessagePDA] = PublicKey.findProgramAddressSync(
+        [Buffer.from('outbound_message'), nonceBuf],
+        mailboxProgramId,
+      );
+
+      debugLog(
+        `Attempt ${attempt + 1}: global nonce=${globalNonce}, outbound_message=${outboundMessagePDA.toBase58()}`,
+      );
+
+      const tx = await assetRouterProgram.methods
+        .deposit(
+          toLchainIdArray,
+          toTokenAddressArray,
+          recipientArray,
+          new BN(amount),
+        )
+        .accounts({
+          payer,
+          config: assetRouterConfigPDA,
+          tokenRoute: tokenRoutePDA,
+          payerTokenAccount,
+          tokenProgram: tokenProgramId,
+          mint,
+          messagingAuthority: messagingAuthorityPDA,
+          mailbox: mailboxProgramId,
+          mailboxConfig: mailboxConfigPDA,
+          outboundMessagePath: outboundMessagePathPDA,
+          outboundMessage: outboundMessagePDA,
+          senderConfig: senderConfigPDA,
+          treasury: mailboxTreasury,
+          systemProgram: SystemProgram.programId,
+        })
+        .transaction();
+
+      debugLog('Instruction account count:', tx.instructions[0]?.keys.length);
+
+      try {
+        const { signature } = await sendAndConfirmTransaction({
+          instruction: tx,
+          connection,
+          provider,
+          debugLabel: 'Asset Router deposit',
+          skipPreflight,
+        });
+
+        debugLog('deposit completed, signature:', signature);
+        return signature;
+      } catch (err: unknown) {
+        const isNonceError =
+          err instanceof Error && err.message.includes('0x7d6');
+        if (isNonceError && attempt < MAX_NONCE_RETRIES - 1) {
+          debugLog('Nonce stale (ConstraintSeeds), retrying...');
+          continue;
+        }
+        throw err;
+      }
+    }
+
+    throw new Error('Failed after max nonce retries');
+  } catch (error: unknown) {
+    if (error instanceof Error && debug) {
+      error.message = `${error.message}\n\nDebug logs:\n${printLogs()}`;
+    }
+    throw SolanaSdkError.wrap(
+      error,
+      ErrorCode.DEPOSIT_REJECTED,
+      'deposit operation failed',
+    );
+  }
+}

package/src/web3Sdk/deposit/index.ts

@@ -0,0 +1 @@
+export { deposit, type DepositParams } from './deposit';