@lombard.finance/sdk-solana 1.2.2 → 2.0.0

package/src/services/SolanaServiceImpl.ts

@@ -1,7 +1,7 @@
 /**
  * Solana Service Implementation
  *
- * Provides Solana-specific operations for LBTC destination signing and unstaking.
+ * Provides Solana-specific operations for LBTC destination signing, redeem and deposit.
  *
  * @module services/SolanaServiceImpl
  */
@@ -9,9 +9,10 @@
 import type { Env, SolanaService } from '@lombard.finance/sdk-common';
 
 import type { ISolanaWalletProvider, SolanaNetwork } from '../types';
+import { deposit } from '../web3Sdk/deposit/deposit';
+import { redeem } from '../web3Sdk/redeem/redeem';
 import { redeemForBtc } from '../web3Sdk/redeemToken/redeemForBtc';
 import { signLbtcDestinationAddrSolana } from '../web3Sdk/signLbtcDestinationAddrSolana';
-import { unstakeLBTC } from '../web3Sdk/unstakeLBTC/unstakeLBTC';
 
 /**
  * Provider resolver function type
@@ -41,46 +42,81 @@ export class SolanaServiceImpl implements SolanaService {
   }
 
   /**
-   * Unstake LBTC on Solana to receive BTC
+   * Redeem BTC.b or LBTC on Solana to receive BTC
    *
-   * Burns LBTC on Solana and releases BTC to the provided Bitcoin address.
+   * Burns the source token and sends a GMP message to trigger a BTC payout.
    */
-  async unstake(args: {
+  async redeemForBtc(args: {
     amount: string;
     btcAddress: string;
     network: string;
-  }): Promise<{ txHash: string }> {
+    env?: Env;
+    tokenMint: string;
+  }): Promise<{ signature: string }> {
     const provider = (await this.getProvider()) as ISolanaWalletProvider;
 
-    const txHash = await unstakeLBTC(provider, {
+    const signature = await redeemForBtc(provider, {
       amount: args.amount,
       btcAddress: args.btcAddress,
       network: args.network as SolanaNetwork,
+      env: args.env,
+      tokenMint: args.tokenMint,
     });
 
-    return { txHash };
+    return { signature };
   }
 
   /**
-   * Redeem BTC.b on Solana to receive BTC
-   *
-   * Burns BTC.b and sends a GMP message to trigger a BTC payout.
+   * Generic redeem via Asset Router (default: LBTC → BTC.b)
    */
-  async redeemForBtc(args: {
+  async redeem(args: {
     amount: string;
-    btcAddress: string;
+    recipient: string;
     network: string;
     env?: Env;
-  }): Promise<{ txHash: string }> {
+    tokenMint?: string;
+    toLchainId?: string;
+    toTokenAddress?: string;
+  }): Promise<{ signature: string }> {
     const provider = (await this.getProvider()) as ISolanaWalletProvider;
 
-    const txHash = await redeemForBtc(provider, {
+    const signature = await redeem(provider, {
       amount: args.amount,
-      btcAddress: args.btcAddress,
+      recipient: args.recipient,
+      network: args.network as SolanaNetwork,
+      env: args.env,
+      tokenMint: args.tokenMint,
+      toLchainId: args.toLchainId,
+      toTokenAddress: args.toTokenAddress,
+    });
+
+    return { signature };
+  }
+
+  /**
+   * Deposit via Asset Router (default: BTC.b → LBTC)
+   */
+  async deposit(args: {
+    amount: string;
+    recipient: string;
+    network: string;
+    env?: Env;
+    sourceTokenMint?: string;
+    toLchainId?: string;
+    toTokenAddress?: string;
+  }): Promise<{ signature: string }> {
+    const provider = (await this.getProvider()) as ISolanaWalletProvider;
+
+    const signature = await deposit(provider, {
+      amount: args.amount,
+      recipient: args.recipient,
       network: args.network as SolanaNetwork,
       env: args.env,
+      sourceTokenMint: args.sourceTokenMint,
+      toLchainId: args.toLchainId,
+      toTokenAddress: args.toTokenAddress,
     });
 
-    return { txHash };
+    return { signature };
   }
 }

package/src/stories/components/OutputSelector/OutputSelector.tsx

@@ -41,6 +41,7 @@ export const OutputSelector: React.FC<OutputSelectorProps> = ({
       case 'NOTARIZATION_STATUS_SESSION_APPROVED':
         return 'Ready to mint';
       case 'NOTARIZATION_STATUS_PENDING':
+      case 'NOTARIZATION_STATUS_GMP_PENDING':
         return 'Pending';
       case 'NOTARIZATION_STATUS_SUBMITTED':
         return 'Submitted';

package/src/types/errors.ts

@@ -40,6 +40,8 @@ export enum ErrorCode {
   INSUFFICIENT_FUNDS = 'INSUFFICIENT_FUNDS',
   SIGNING_REJECTED = 'SIGNING_REJECTED',
   CLAIM_REJECTED = 'CLAIM_REJECTED',
+  DEPOSIT_REJECTED = 'DEPOSIT_REJECTED',
+  REDEEM_REJECTED = 'REDEEM_REJECTED',
   UNSTAKE_REJECTED = 'UNSTAKE_REJECTED',
 
   // Network errors

package/src/utils/createDebugLogger.ts

@@ -25,33 +25,26 @@ export function createDebugLogger(options: CreateDebugLoggerOptions = {}) {
   const { debug = false, prefix = '' } = options;
   const logs: string[] = [];
 
-  // Return the actual logger function
   const debugLog = (...args: unknown[]): void => {
-    // Only proceed if debugging is enabled
-    if (!debug) {
-      return;
-    }
-
-    // Format arguments: stringify objects, keep others as strings
     const formattedArgs = args.map(arg =>
       typeof arg === 'object' && arg !== null
         ? JSON.stringify(arg)
         : String(arg),
     );
 
-    // Construct the final log message with optional prefix
     const logMessage = prefix
       ? `${prefix} ${formattedArgs.join(' ')}`
       : formattedArgs.join(' ');
 
-    // Log to the console
-    console.log(logMessage);
-  };
+    logs.push(logMessage);
 
-  const printLogs = (): void => {
-    console.log(logs.join('\n'));
+    if (debug) {
+      console.log(logMessage);
+    }
   };
 
+  const printLogs = (): string => logs.join('\n');
+
   return { debugLog, printLogs };
 }
 

package/src/utils/errors.ts

@@ -11,6 +11,8 @@ export enum ErrorCode {
   CONNECTION_ERROR = 'CONNECTION_ERROR',
   CONNECTION_REJECTED = 'CONNECTION_REJECTED',
   CONNECTION_TIMEOUT = 'CONNECTION_TIMEOUT',
+  DEPOSIT_REJECTED = 'DEPOSIT_REJECTED',
+  REDEEM_REJECTED = 'REDEEM_REJECTED',
   INSUFFICIENT_FUNDS = 'INSUFFICIENT_FUNDS',
   INVALID_ADDRESS = 'INVALID_ADDRESS',
   INVALID_AMOUNT = 'INVALID_AMOUNT',

package/src/utils/tokenAccount.ts

@@ -51,11 +51,13 @@ export async function createOrGetAssociatedTokenAccount({
   connection,
   ownerAddress,
   mintAddress,
+  allowOwnerOffCurve = false,
 }: {
   provider: ISolanaWalletProvider;
   connection: Connection;
   ownerAddress: string;
   mintAddress: string;
+  allowOwnerOffCurve?: boolean;
 }): Promise<string> {
   const mintPubkey = new PublicKey(mintAddress);
   const ownerPubkey = new PublicKey(ownerAddress);
@@ -65,7 +67,7 @@ export async function createOrGetAssociatedTokenAccount({
   const associatedTokenAddress = await getAssociatedTokenAddress(
     mintPubkey,
     ownerPubkey,
-    true,
+    allowOwnerOffCurve,
     tokenProgramId,
     ASSOCIATED_TOKEN_PROGRAM_ID,
   );

package/src/utils/transactions.ts

@@ -12,7 +12,7 @@ export async function sendAndConfirmTransaction({
   connection,
   provider,
   debugLabel = 'Transaction',
-  skipPreflight = false,
+  skipPreflight = true,
 }: {
   instruction: Transaction | TransactionInstruction;
   connection: Connection;

package/src/web3Sdk/claimToken/claimBtcb.ts

@@ -3,7 +3,7 @@ import { PublicKey, SystemProgram } from '@solana/web3.js';
 
 import { sendAndConfirmTransaction } from '../../utils';
 import { createOrGetAssociatedTokenAccount } from '../../utils/tokenAccount';
-import { ALREADY_MINTED_TX_HASH } from '../claimLBTC';
+import { ALREADY_MINTED_TX_HASH } from './constants';
 import {
   assertBtcbDepositRecipientMatchesWallet,
   ClaimContext,
@@ -80,57 +80,66 @@ export async function claimBtcbFromPayload(ctx: ClaimContext): Promise<string> {
     connection,
     ownerAddress: params.recipientAddress,
     mintAddress: mint.toBase58(),
+    allowOwnerOffCurve: true,
   });
 
-  // Build mint_from_payload instruction
+  // Build mint_from_payload instruction.
+  // Optional bascule accounts must be passed explicitly (null when disabled),
+  // otherwise Anchor builder throws "Account <x> not provided".
   debugLog('mint_from_payload...');
   const mintPayloadArray = Array.from(payloadBytes);
-  const mintIx = await assetRouterProgram.methods
-    .mintFromPayload(mintPayloadArray, payloadHashArray)
-    .accounts({
-      payer: provider.publicKey,
-      config: assetRouterConfigPDA,
-      tokenProgram: tokenProgramId,
-      recipient: recipientTokenAccount,
-      mint,
-      mintAuthority,
-      tokenAuthority: tokenAuthorityPDA,
-      consortiumValidatedPayload: validatedPayloadPDA,
-      depositPayloadSpent: depositPayloadSpentPDA,
-      systemProgram: SystemProgram.programId,
-    })
-    .instruction();
 
-  // Append bascule remaining accounts
+  let basculeValidatorPDA: PublicKey | undefined;
+  let basculeDataPDA: PublicKey | undefined;
+  let basculeDepositPDA: PublicKey | undefined;
+
   if (effectiveBasculeProgramId) {
-    const [basculeValidatorPDA] = PublicKey.findProgramAddressSync(
+    [basculeValidatorPDA] = PublicKey.findProgramAddressSync(
       [Buffer.from('bascule_validator')],
       assetRouterProgramId,
     );
-    const [basculeDataPDA] = PublicKey.findProgramAddressSync(
+    [basculeDataPDA] = PublicKey.findProgramAddressSync(
       [Buffer.from('bascule')],
       effectiveBasculeProgramId,
     );
     const depositId = computeDepositIdFromPayload(payloadBytes);
     debugLog('Deposit ID:', Buffer.from(depositId).toString('hex'));
 
-    const [basculeDepositPDA] = PublicKey.findProgramAddressSync(
+    [basculeDepositPDA] = PublicKey.findProgramAddressSync(
       [Buffer.from('deposit'), depositId],
       effectiveBasculeProgramId,
     );
 
+    debugLog('Asset router program:', assetRouterProgramId.toBase58());
+    debugLog('Bascule program:', effectiveBasculeProgramId.toBase58());
     debugLog('Bascule validator PDA:', basculeValidatorPDA.toBase58());
     debugLog('Bascule data PDA:', basculeDataPDA.toBase58());
     debugLog('Bascule deposit PDA:', basculeDepositPDA.toBase58());
-
-    mintIx.keys.push(
-      { pubkey: basculeValidatorPDA, isSigner: false, isWritable: false },
-      { pubkey: effectiveBasculeProgramId, isSigner: false, isWritable: false },
-      { pubkey: basculeDataPDA, isSigner: false, isWritable: true },
-      { pubkey: basculeDepositPDA, isSigner: false, isWritable: true },
-    );
   }
 
+  // Anchor optional accounts: when disabled, pass the program's own ID as a
+  // "None" sentinel — this is the convention anchor-client uses for optional accounts.
+  const basculeSentinel = assetRouterProgramId;
+  const mintIx = await assetRouterProgram.methods
+    .mintFromPayload(mintPayloadArray, payloadHashArray)
+    .accountsPartial({
+      payer: provider.publicKey,
+      config: assetRouterConfigPDA,
+      tokenProgram: tokenProgramId,
+      recipient: recipientTokenAccount,
+      mint,
+      mintAuthority,
+      tokenAuthority: tokenAuthorityPDA,
+      consortiumValidatedPayload: validatedPayloadPDA,
+      depositPayloadSpent: depositPayloadSpentPDA,
+      systemProgram: SystemProgram.programId,
+      basculeValidator: basculeValidatorPDA ?? basculeSentinel,
+      basculeProgram: effectiveBasculeProgramId ?? basculeSentinel,
+      basculeData: basculeDataPDA ?? basculeSentinel,
+      basculeDeposit: basculeDepositPDA ?? basculeSentinel,
+    })
+    .instruction();
+
   debugLog('Instruction account count:', mintIx.keys.length);
 
   const { signature } = await sendAndConfirmTransaction({

package/src/web3Sdk/claimToken/claimLbtcGmp.ts

@@ -1,13 +1,44 @@
 import { Program } from '@coral-xyz/anchor';
 import { getMint } from '@solana/spl-token';
 import { PublicKey, SystemProgram } from '@solana/web3.js';
+import { keccak256 } from 'js-sha3';
 
 import { getMailboxIdl } from '../../idl/getMailboxIdl';
 import { sendAndConfirmTransaction } from '../../utils';
 import { createOrGetAssociatedTokenAccount } from '../../utils/tokenAccount';
-import { ALREADY_MINTED_TX_HASH } from '../claimLBTC';
+import { ALREADY_MINTED_TX_HASH } from './constants';
 import { ClaimContext, executeConsortiumSession } from './shared';
 
+/**
+ * Mirrors bascule_gmp MintMessage.mint_id():
+ *   keccak256( nonce_u256_be || chain_id(32) || recipient(32) || token(32) || amount_u256_be )
+ * Payload: nonce u256 at [36:68], token at [232:264], recipient at [264:296], amount u256 at [296:328].
+ * Only the low 8 bytes of each u256 are used (placed in the last 8 bytes of the 32-byte slot).
+ */
+function computeBasculeGmpMintId(
+  payload: Buffer,
+  chainId: Buffer,
+): Uint8Array {
+  if (payload.length < 328) {
+    throw new Error(
+      `payload too short for bascule_gmp mint_id: ${payload.length} bytes`,
+    );
+  }
+  if (chainId.length !== 32) {
+    throw new Error(`chain_id must be 32 bytes, got ${chainId.length}`);
+  }
+
+  const data = Buffer.alloc(160);
+  payload.copy(data, 24, 60, 68);
+  chainId.copy(data, 32);
+  payload.copy(data, 64, 264, 296);
+  payload.copy(data, 96, 232, 264);
+  payload.copy(data, 152, 320, 328);
+
+  const hash = keccak256(new Uint8Array(data));
+  return new Uint8Array(Buffer.from(hash, 'hex'));
+}
+
 /**
  * LBTC GMP flow via Consortium + Mailbox + Asset Router gmp_receive.
  *
@@ -25,9 +56,9 @@ export async function claimLbtcGmp(ctx: ClaimContext): Promise<string> {
     validatedPayloadPDA, arConfig, debugLog,
   } = ctx;
 
-  if (payloadBytes.length < 296) {
+  if (payloadBytes.length < 328) {
     throw new Error(
-      `LBTC GMP payload too short: expected >= 296 bytes, got ${payloadBytes.length}`,
+      `LBTC GMP payload too short: expected >= 328 bytes, got ${payloadBytes.length}`,
     );
   }
 
@@ -74,7 +105,7 @@ export async function claimLbtcGmp(ctx: ClaimContext): Promise<string> {
       connection,
       provider,
       debugLabel: 'Consortium post_session_payload',
-      skipPreflight: params.skipPreflight ?? false,
+      skipPreflight: params.skipPreflight ?? true,
     });
     debugLog('post_session_payload completed');
   }
@@ -133,7 +164,7 @@ export async function claimLbtcGmp(ctx: ClaimContext): Promise<string> {
       connection,
       provider,
       debugLabel: 'Mailbox deliver_message',
-      skipPreflight: params.skipPreflight ?? false,
+      skipPreflight: params.skipPreflight ?? true,
     });
     debugLog('deliver_message completed');
   }
@@ -169,6 +200,7 @@ export async function claimLbtcGmp(ctx: ClaimContext): Promise<string> {
     connection,
     ownerAddress: tokenRecipient.toBase58(),
     mintAddress: mint.toBase58(),
+    allowOwnerOffCurve: true,
   });
 
   // Build handle_message instruction
@@ -210,16 +242,31 @@ export async function claimLbtcGmp(ctx: ClaimContext): Promise<string> {
       effectiveBasculeGmpProgramId,
     );
     const [basculeGmpAccountRolesPDA] = PublicKey.findProgramAddressSync(
-      [Buffer.from('account_roles'), basculeGmpConfigPDA.toBytes()],
+      [Buffer.from('account_roles'), basculeValidatorPDA.toBytes()],
       effectiveBasculeGmpProgramId,
     );
+
+    if (!config.solanaRoutingChainId) {
+      throw new Error(
+        `Solana routing chain ID not configured for network: ${params.network}`,
+      );
+    }
+    const solanaChainId = Buffer.from(config.solanaRoutingChainId, 'hex');
+    const mintId = computeBasculeGmpMintId(payloadBytes, solanaChainId);
     const [basculeGmpMintPayloadPDA] = PublicKey.findProgramAddressSync(
-      [Buffer.from('mint_payload'), payloadHash],
+      [Buffer.from('mint_payload'), Buffer.from(mintId)],
       effectiveBasculeGmpProgramId,
     );
 
+    debugLog('Asset router program:', assetRouterProgramId.toBase58());
+    debugLog('Bascule GMP program:', effectiveBasculeGmpProgramId.toBase58());
+    debugLog('Bascule validator PDA:', basculeValidatorPDA.toBase58());
+    debugLog('Bascule GMP config PDA:', basculeGmpConfigPDA.toBase58());
+    debugLog('Bascule GMP account roles PDA:', basculeGmpAccountRolesPDA.toBase58());
+    debugLog('Bascule GMP mint payload PDA:', basculeGmpMintPayloadPDA.toBase58());
+
     handleIx.keys.push(
-      { pubkey: basculeValidatorPDA, isSigner: false, isWritable: false },
+      { pubkey: basculeValidatorPDA, isSigner: false, isWritable: true },
       { pubkey: effectiveBasculeGmpProgramId, isSigner: false, isWritable: false },
       { pubkey: basculeGmpConfigPDA, isSigner: false, isWritable: false },
       { pubkey: basculeGmpAccountRolesPDA, isSigner: false, isWritable: false },
@@ -235,6 +282,17 @@ export async function claimLbtcGmp(ctx: ClaimContext): Promise<string> {
   }
 
   debugLog('handle_message account count:', handleIx.keys.length);
+  debugLog(
+    'handle_message program:', handleIx.programId.toBase58(),
+  );
+  debugLog(
+    'handle_message data (hex):', Buffer.from(handleIx.data).toString('hex'),
+  );
+  handleIx.keys.forEach((k, i) => {
+    debugLog(
+      `  [${i}] ${k.pubkey.toBase58()} signer=${k.isSigner} writable=${k.isWritable}`,
+    );
+  });
 
   const { signature } = await sendAndConfirmTransaction({
     instruction: handleIx,

package/src/web3Sdk/claimToken/claimToken.stories.tsx

@@ -206,8 +206,8 @@ const meta: Meta<typeof StoryView> = {
 3. Wait for backend to notarize the deposit (Consortium validation)
 4. Call \`claimToken\` to mint tokens via Asset Router's \`mint_from_payload\`
 
-Unlike the legacy \`claimLBTC\` (which uses a 3-step on-chain process), this function
-performs a single transaction — the Consortium validation is handled entirely by the backend.`,
+The Consortium validation is handled entirely by the backend, so the on-chain flow
+is a single transaction.`,
       },
     },
   },

package/src/web3Sdk/claimToken/claimToken.ts

@@ -1,7 +1,7 @@
 import { AnchorProvider, Program, setProvider } from '@coral-xyz/anchor';
 import { PublicKey } from '@solana/web3.js';
 
-import { getConfig, networkToEnv } from '../../const/getConfig';
+import { DEFAULT_ENV, getConfig } from '../../const/getConfig';
 import { getConnection } from '../../const/rpcUrls';
 import { getAssetRouterIdl } from '../../idl/getAssetRouterIdl';
 import { getConsortiumIdl } from '../../idl/getConsortiumIdl';
@@ -14,11 +14,11 @@ import {
   ClaimTokenParams,
   computePayloadHash,
   DEPOSIT_SELECTOR_V1,
+  fetchAssetRouterConfig,
   fetchCurrentEpoch,
   getConsortiumConfigPDA,
   getConsortiumSessionPDA,
   GMP_MESSAGE_V1_SELECTOR,
-  parseAssetRouterConfig,
 } from './shared';
 
 export type { ClaimTokenParams } from './shared';
@@ -34,7 +34,7 @@ export async function claimToken(
   provider: ISolanaWalletProvider,
   params: ClaimTokenParams,
 ): Promise<string> {
-  const { network, env: envOverride, rawPayload, rpcUrl, debug = false } = params;
+  const { network, env = DEFAULT_ENV, rawPayload, rpcUrl, debug = false } = params;
   const { debugLog, printLogs } = createDebugLogger({ debug });
 
   try {
@@ -42,8 +42,8 @@ export async function claimToken(
       throw new Error('Wallet not found');
     }
 
-    const env = envOverride ?? networkToEnv[network];
     const config = getConfig(env);
+
     if (!config.assetRouter) {
       throw new Error(`Asset Router not configured for network: ${network}`);
     }
@@ -72,7 +72,10 @@ export async function claimToken(
     const consortiumProgramId = new PublicKey(config.consortium);
 
     // Parse payload
-    const payloadBytes = Buffer.from(rawPayload, 'hex');
+    const cleanPayload = rawPayload.startsWith('0x')
+      ? rawPayload.slice(2)
+      : rawPayload;
+    const payloadBytes = Buffer.from(cleanPayload, 'hex');
     if (payloadBytes.length < 4) {
       throw new Error(`Payload too short: ${payloadBytes.length} bytes`);
     }
@@ -92,7 +95,7 @@ export async function claimToken(
 
     // Fetch current epoch from on-chain consortium config
     const currentEpoch = await fetchCurrentEpoch(
-      connection,
+      consortiumProgram,
       consortiumConfigPDA,
     );
     debugLog('Current consortium epoch:', currentEpoch.toString());
@@ -116,18 +119,19 @@ export async function claimToken(
       assetRouterProgramId,
     );
 
-    // Read on-chain Asset Router config
+    // Read on-chain Asset Router config via Anchor (IDL-based deserialization)
     debugLog('Asset Router program ID:', assetRouterProgramId.toBase58());
     debugLog('Asset Router config PDA:', assetRouterConfigPDA.toBase58());
-    const configAccountInfo =
-      await connection.getAccountInfo(assetRouterConfigPDA);
-    debugLog('Config account exists:', !!configAccountInfo);
-    if (!configAccountInfo) {
-      throw new Error(
-        `Asset Router config account not found at ${assetRouterConfigPDA.toBase58()} (program: ${assetRouterProgramId.toBase58()})`,
-      );
-    }
-    const arConfig = parseAssetRouterConfig(configAccountInfo.data);
+    const arConfig = await fetchAssetRouterConfig(
+      assetRouterProgram,
+      assetRouterConfigPDA,
+    );
+    debugLog(
+      'Asset Router config — paused:', arConfig.paused,
+      'nativeMint:', arConfig.nativeMint.toBase58(),
+      'bascule:', arConfig.basculeProgramId?.toBase58() ?? 'null',
+      'basculeGmp:', arConfig.basculeGmpProgramId?.toBase58() ?? 'null',
+    );
 
     if (arConfig.paused) {
       throw new Error('Asset Router contract is paused');

package/src/web3Sdk/claimToken/constants.ts

@@ -0,0 +1,5 @@
+/**
+ * Sentinel tx hash returned when a payload has already been processed on-chain.
+ * Used by BTC.b mint and LBTC GMP flows to signal an idempotent no-op to callers.
+ */
+export const ALREADY_MINTED_TX_HASH = 'ALREADY_MINTED';

package/src/web3Sdk/claimToken/index.ts

@@ -1 +1,2 @@
 export * from './claimToken';
+export { ALREADY_MINTED_TX_HASH } from './constants';