@lombard.finance/sdk-solana 1.2.2 → 2.0.0

package/src/web3Sdk/redeemToken/redeemLbtc.ts

@@ -0,0 +1,174 @@
+import { BN } from '@coral-xyz/anchor';
+import {
+  ASSOCIATED_TOKEN_PROGRAM_ID,
+  getAssociatedTokenAddress,
+} from '@solana/spl-token';
+import { PublicKey, SystemProgram } from '@solana/web3.js';
+
+import { sendAndConfirmTransaction } from '../../utils';
+import { BTC_NATIVE_TOKEN_ADDRESS, RedeemContext } from './shared';
+
+/**
+ * LBTC → BTC redemption via Asset Router's `redeem_for_btc`.
+ *
+ * Burns LBTC tokens and sends a GMP message through the Mailbox to trigger
+ * a BTC payout to the specified Bitcoin address.
+ */
+export async function redeemLbtcForBtc(ctx: RedeemContext): Promise<string> {
+  const {
+    provider, params, config, connection,
+    payer, mint, tokenProgramId, scriptPubKey,
+    assetRouterProgramId, mailboxProgramId,
+    solanaRoutingChainId, bitcoinRoutingChainId,
+    assetRouterProgram, assetRouterConfigPDA, mailboxConfigPDA,
+    arTreasury, mailboxTreasury,
+    debugLog,
+  } = ctx;
+
+  const { amount, skipPreflight = false } = params;
+
+  // ── LBTC-specific PDAs ──
+  const [tokenConfigPDA] = PublicKey.findProgramAddressSync(
+    [Buffer.from('token_config'), mint.toBuffer()],
+    assetRouterProgramId,
+  );
+  const [tokenRoutePDA] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from('token_route'),
+      solanaRoutingChainId,
+      mint.toBuffer(),
+      bitcoinRoutingChainId,
+      BTC_NATIVE_TOKEN_ADDRESS,
+    ],
+    assetRouterProgramId,
+  );
+  const [messagingAuthorityPDA] = PublicKey.findProgramAddressSync(
+    [Buffer.from('messaging_authority')],
+    assetRouterProgramId,
+  );
+
+  debugLog('Token config PDA:', tokenConfigPDA.toBase58());
+  debugLog('Token route PDA:', tokenRoutePDA.toBase58());
+  debugLog('Messaging authority PDA:', messagingAuthorityPDA.toBase58());
+
+  // ── Mailbox PDAs ──
+  if (!config.ledgerChainId) {
+    throw new Error(`Ledger chain ID not configured for network: ${params.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('Outbound message path PDA:', outboundMessagePathPDA.toBase58());
+  debugLog('Sender config PDA:', senderConfigPDA.toBase58());
+
+  // ── Token accounts ──
+  const payerTokenAccount = await getAssociatedTokenAddress(
+    mint,
+    payer,
+    false,
+    tokenProgramId,
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+  );
+  const treasuryTokenAccount = await getAssociatedTokenAddress(
+    mint,
+    arTreasury,
+    true,
+    tokenProgramId,
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+  );
+
+  debugLog('Payer token account:', payerTokenAccount.toBase58());
+  debugLog('Treasury token account:', treasuryTokenAccount.toBase58());
+
+  // ── Balance check ──
+  const tokenBalance = await connection.getTokenAccountBalance(payerTokenAccount);
+  const userBalance = BigInt(tokenBalance.value.amount);
+  const parsedAmount = BigInt(amount);
+  if (userBalance < parsedAmount) {
+    throw new Error(
+      `Insufficient LBTC balance: have ${tokenBalance.value.uiAmountString}, need ${Number(parsedAmount) / 1e8}`,
+    );
+  }
+
+  // ── Build & send with nonce retry ──
+  // The outbound_message PDA depends on global_nonce which can change between
+  // reads. Retry up to 3 times if the nonce becomes stale.
+  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');
+    }
+    // global_nonce is a u64 at offset 137; need 137 + 8 = 145 bytes
+    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
+      .redeemForBtc(scriptPubKey, new BN(amount))
+      .accounts({
+        payer,
+        config: assetRouterConfigPDA,
+        tokenConfig: tokenConfigPDA,
+        tokenRoute: tokenRoutePDA,
+        payerTokenAccount,
+        tokenProgram: tokenProgramId,
+        mint,
+        treasuryTokenAccount,
+        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 redeem_for_btc (LBTC)',
+        skipPreflight,
+      });
+
+      debugLog('LBTC redeem_for_btc completed, signature:', signature);
+      return signature;
+    } catch (err: unknown) {
+      const isNonceError =
+        err instanceof Error &&
+        err.message.includes('0x7d6'); // ConstraintSeeds
+      if (isNonceError && attempt < MAX_NONCE_RETRIES - 1) {
+        debugLog(`Nonce stale (ConstraintSeeds), retrying...`);
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  throw new Error('Failed after max nonce retries');
+}

package/src/web3Sdk/redeemToken/shared.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+
+import { BTC_NATIVE_TOKEN_ADDRESS, validateAmount } from './shared';
+
+describe('validateAmount', () => {
+  it('should accept valid positive integer strings', () => {
+    expect(() => validateAmount('1')).not.toThrow();
+    expect(() => validateAmount('100000')).not.toThrow();
+    expect(() => validateAmount('18446744073709551615')).not.toThrow(); // u64 max
+  });
+
+  it('should reject zero', () => {
+    expect(() => validateAmount('0')).toThrow('greater than zero');
+  });
+
+  it('should reject non-numeric strings', () => {
+    expect(() => validateAmount('abc')).toThrow('positive integer string');
+    expect(() => validateAmount('1.5')).toThrow('positive integer string');
+    expect(() => validateAmount('-1')).toThrow('positive integer string');
+    expect(() => validateAmount('')).toThrow('positive integer string');
+    expect(() => validateAmount(' 100')).toThrow('positive integer string');
+  });
+
+  it('should reject amounts exceeding u64 max', () => {
+    expect(() => validateAmount('18446744073709551616')).toThrow('exceeds the u64 maximum');
+    expect(() => validateAmount('99999999999999999999999')).toThrow('exceeds the u64 maximum');
+  });
+});
+
+describe('BTC_NATIVE_TOKEN_ADDRESS', () => {
+  it('should be a 32-byte buffer', () => {
+    expect(BTC_NATIVE_TOKEN_ADDRESS).toBeInstanceOf(Buffer);
+    expect(BTC_NATIVE_TOKEN_ADDRESS.length).toBe(32);
+  });
+
+  it('should have value 1 in the last byte', () => {
+    expect(BTC_NATIVE_TOKEN_ADDRESS[31]).toBe(1);
+  });
+
+  it('should have all other bytes as zero', () => {
+    for (let i = 0; i < 31; i++) {
+      expect(BTC_NATIVE_TOKEN_ADDRESS[i]).toBe(0);
+    }
+  });
+});

package/src/web3Sdk/redeemToken/shared.ts

@@ -0,0 +1,97 @@
+import { Program } from '@coral-xyz/anchor';
+import { Env } from '@lombard.finance/sdk-common';
+import { Connection, PublicKey } from '@solana/web3.js';
+
+import { IConfig } from '../../const/getConfig';
+import { ISolanaWalletProvider, SolanaNetwork } from '../../types';
+
+// ── Types ──
+
+export interface RedeemForBtcParams {
+  amount: string;
+  btcAddress: string;
+  /**
+   * SPL token mint to redeem. Must equal the environment’s configured LBTC or
+   * BTC.b mint; any other value fails before building a redemption transaction.
+   */
+  tokenMint: string;
+  network: SolanaNetwork;
+  /**
+   * Optional environment override. When provided, used instead of
+   * the default `networkToEnv[network]` mapping to resolve config.
+   * Useful when multiple environments share the same Solana network
+   * (e.g. both 'dev' and 'stage' use devnet).
+   */
+  env?: Env;
+  rpcUrl?: string;
+  debug?: boolean;
+  /**
+   * Skip preflight transaction simulation before broadcast.
+   *
+   * Defaults to `false` (simulation enabled). Set to `true` if preflight
+   * simulation gives false negatives — for example, when the simulation node
+   * has not yet seen the latest global nonce for the `outbound_message` PDA,
+   * leading to a spurious `ConstraintSeeds (0x7d6)` failure even though the
+   * transaction would land correctly on-chain.
+   */
+  skipPreflight?: boolean;
+}
+
+export type DebugLog = (...args: unknown[]) => void;
+
+/**
+ * Common context shared between BTC.b and LBTC redemption flows.
+ */
+export interface RedeemContext {
+  provider: ISolanaWalletProvider;
+  params: RedeemForBtcParams;
+  env: Env;
+  config: IConfig;
+  connection: Connection;
+  payer: PublicKey;
+  mint: PublicKey;
+  tokenProgramId: PublicKey;
+  scriptPubKey: Buffer;
+  assetRouterProgramId: PublicKey;
+  mailboxProgramId: PublicKey;
+  solanaRoutingChainId: Buffer;
+  bitcoinRoutingChainId: Buffer;
+  assetRouterProgram: Program;
+  assetRouterConfigPDA: PublicKey;
+  mailboxConfigPDA: PublicKey;
+  arTreasury: PublicKey;
+  mailboxTreasury: PublicKey;
+  debugLog: DebugLog;
+}
+
+// ── Constants ──
+
+/**
+ * BTC native token address in Lombard protocol (to_token_address for BTC in token_route PDA).
+ * BTC is represented as 0x...01 (32 bytes, value 1).
+ */
+export const BTC_NATIVE_TOKEN_ADDRESS = (() => {
+  const buf = Buffer.alloc(32, 0);
+  buf[31] = 1;
+  return buf;
+})();
+
+// ── Helpers ──
+
+export function validateAmount(amount: string): void {
+  const U64_MAX = 18446744073709551615n;
+  if (!/^\d+$/.test(amount)) {
+    throw new Error(
+      `Invalid amount "${amount}": must be a positive integer string (lamports, no decimals or signs)`,
+    );
+  }
+  const parsedAmount = BigInt(amount);
+  if (parsedAmount === 0n) {
+    throw new Error('Amount must be greater than zero');
+  }
+  if (parsedAmount > U64_MAX) {
+    throw new Error(
+      `Amount ${amount} exceeds the u64 maximum (${U64_MAX})`,
+    );
+  }
+}

package/src/web3Sdk/claimLBTC/claimLBTC.stories.tsx

@@ -1,189 +0,0 @@
-import { Env } from '@lombard.finance/sdk-common';
-import type { Meta, StoryObj } from '@storybook/react';
-import { useEffect, useState } from 'react';
-
-import { envToNetwork } from '../../const/getConfig';
-import {
-  Button,
-  CodeBlock,
-  ConnectButton,
-  ErrorDisplay,
-  OutputSelector,
-  ResultDisplay,
-  SectionCard,
-} from '../../stories/components';
-import { functionType } from '../../stories/decorators/function-type';
-import { useConnect } from '../../stories/hooks/useConnect';
-import { IOutput, useFetchOutputs } from '../../stories/hooks/useFetchOutputs';
-import useQuery from '../../stories/hooks/useQuery';
-import { claimLBTC } from './claimLBTC';
-import { parseTransactionLogs } from './utils/parseTransactionLogs';
-
-interface ClaimLbtcStoryArgs {
-  environment: Env;
-}
-
-export const StoryView = ({ environment }: ClaimLbtcStoryArgs) => {
-  const network = envToNetwork[environment];
-  const [selectedOutput, setSelectedOutput] = useState<IOutput | null>(null);
-  const [transactionLogs, setTransactionLogs] = useState<string[] | null>(null);
-
-  const {
-    data: connectionData,
-    error: connectError,
-    isLoading: isConnecting,
-    connect,
-    disconnect,
-  } = useConnect();
-  const isConnected = !!connectionData;
-  const address = connectionData?.address;
-  const provider = connectionData?.provider;
-
-  const { refetchOutputs } = useFetchOutputs({
-    address: address ?? undefined,
-    environment,
-    isConnected: isConnected,
-  });
-
-  const request = async () => {
-    if (!provider || !address) throw new Error('Wallet not connected.');
-    if (!selectedOutput) throw new Error('Please select an output to claim.');
-    if (!selectedOutput.raw_payload)
-      throw new Error('Selected output has no raw_payload.');
-    if (!selectedOutput.proof)
-      throw new Error('Selected output has no proof (required for LBTC).');
-
-    setTransactionLogs(null);
-    try {
-      const txHash = await claimLBTC(provider, {
-        recipientAddress: address,
-        amount: selectedOutput.value,
-        network,
-        proofSignature: selectedOutput.proof,
-        rawPayload: selectedOutput.raw_payload,
-        debug: true,
-      });
-
-      refetchOutputs();
-      setSelectedOutput(null);
-      return txHash;
-    } catch (err: unknown) {
-      const { errorMessage, errorLogs } = parseTransactionLogs(err);
-      setTransactionLogs(errorLogs);
-      throw new Error(errorMessage);
-    }
-  };
-
-  const {
-    data: result,
-    error,
-    isLoading,
-    refetch: handleClaim,
-  } = useQuery(
-    request,
-    [provider, address, selectedOutput, environment, refetchOutputs],
-    false,
-  );
-
-  useEffect(() => {
-    setSelectedOutput(null);
-    setTransactionLogs(null);
-  }, [isConnected, address, environment]);
-
-  return (
-    <>
-      <ConnectButton
-        connect={connect}
-        disconnect={disconnect}
-        isConnected={isConnected}
-        isLoading={isConnecting}
-        error={connectError}
-        network={network}
-        walletName={connectionData?.walletName}
-        address={connectionData?.address}
-      />
-
-      {isConnected && address && provider && (
-        <>
-          <SectionCard title="Available Bitcoin Outputs">
-            <OutputSelector
-              address={address}
-              environment={environment}
-              isConnected={isConnected}
-              selectedOutput={selectedOutput}
-              onOutputSelect={setSelectedOutput}
-            />
-          </SectionCard>
-
-          <div className="d-grid gap-2 mb-4">
-            <Button
-              primary
-              size="large"
-              onClick={handleClaim}
-              isLoading={isLoading}
-              disabled={
-                isLoading ||
-                !selectedOutput ||
-                !selectedOutput.raw_payload
-              }
-              actionName="claimLBTC"
-            />
-            {selectedOutput && !selectedOutput.raw_payload && (
-              <p className="text-warning small mt-1 mb-0">
-                Output is still awaiting notarization. Use "Refresh Outputs" to
-                check for updates.
-              </p>
-            )}
-          </div>
-
-          {result && (
-            <ResultDisplay
-              result={result}
-              title="Claim Transaction Hash"
-              successMessage="LBTC claimed!"
-            />
-          )}
-
-          {error && (
-            <ErrorDisplay error={error || connectError} title="Claim Error" />
-          )}
-
-          {transactionLogs && transactionLogs.length > 0 && (
-            <SectionCard title="Transaction Logs (Debug)">
-              <CodeBlock text={transactionLogs.join('\n')} />
-            </SectionCard>
-          )}
-        </>
-      )}
-    </>
-  );
-};
-
-const meta: Meta<typeof StoryView> = {
-  title: 'write/claimLBTC',
-  component: StoryView,
-  tags: ['autodocs'],
-  decorators: [functionType('write')],
-  parameters: {
-    docs: {
-      description: {
-        component: `Claim LBTC tokens on Solana.
-
-Uses the legacy 3-step on-chain flow (\`claimLBTC\`):
-1. Create Mint Payload → 2. Post Mint Signatures → 3. Mint From Payload`,
-      },
-    },
-  },
-  args: {
-    environment: Env.stage,
-  },
-  argTypes: {
-    environment: {
-      control: { type: 'select' },
-      options: Object.values(Env),
-    },
-  },
-};
-export default meta;
-
-type Story = StoryObj<typeof meta>;