@lombard.finance/sdk 3.7.4 → 4.0.0

package/src/chains/btc/actions/stake/__tests__/BtcStake.test.ts

@@ -0,0 +1,247 @@
+/**
+ * Tests for BTC Stake Action
+ *
+ * Tests the BTC → LBTC staking flow with fee authorization and deposit address generation.
+ */
+
+import { Env } from '@lombard.finance/sdk-common';
+import { describe, expect, it, vi } from 'vitest';
+
+import { AssetId, Chain } from '../../../../../core';
+import { LombardError, ProviderErrorCode } from '../../../../../shared/errors';
+import type { BtcStakeParams, BtcStakeProgress } from '../types';
+
+// Mock SDK for testing (reserved for future tests)
+const _createMockSDK = () => ({
+  config: {
+    env: Env.prod,
+  },
+  getProvider: vi.fn(),
+});
+
+describe('BtcStake Interface', () => {
+  describe('BtcStakeParams', () => {
+    it('should accept valid stake parameters', () => {
+      const params: BtcStakeParams = {
+        assetOut: AssetId.LBTC,
+        destChain: Chain.ETHEREUM,
+      };
+
+      expect(params.assetOut).toBe(AssetId.LBTC);
+      expect(params.destChain).toBe(Chain.ETHEREUM);
+    });
+
+    it('should support different destination chains', () => {
+      const ethereumParams: BtcStakeParams = {
+        assetOut: AssetId.LBTC,
+        destChain: Chain.ETHEREUM,
+      };
+
+      const baseParams: BtcStakeParams = {
+        assetOut: AssetId.LBTC,
+        destChain: Chain.BASE,
+      };
+
+      expect(ethereumParams.destChain).toBe(Chain.ETHEREUM);
+      expect(baseParams.destChain).toBe(Chain.BASE);
+    });
+  });
+
+  describe('BtcStake Status Transitions', () => {
+    it('should define all required status values', () => {
+      const statuses = [
+        'idle',
+        'preparing',
+        'needs_fee_authorization',
+        'needs_address_confirmation',
+        'authorizing',
+        'ready',
+        'ready',
+        'address_ready',
+        // Note: 'failed' is no longer a status - errors tracked separately,
+      ];
+
+      // Verify all status strings are defined
+      statuses.forEach(status => {
+        expect(typeof status).toBe('string');
+      });
+    });
+  });
+
+  describe('BtcStakeProgress Interface', () => {
+    it('should include required progress fields', () => {
+      const progress: BtcStakeProgress = {
+        status: 'address_ready',
+        steps: {
+          created: 'complete',
+          verifying: 'pending',
+          issuing: 'idle',
+        },
+        confirmations: 2,
+        requiredConfirmations: 6,
+        hasEnoughConfirmations: false,
+        isClaimed: false,
+      };
+
+      expect(progress.confirmations).toBe(2);
+      expect(progress.requiredConfirmations).toBe(6);
+      expect(progress.hasEnoughConfirmations).toBe(false);
+      expect(progress.isClaimed).toBe(false);
+    });
+
+    it('should track deposit address', () => {
+      const progress: BtcStakeProgress = {
+        status: 'address_ready',
+        steps: {
+          created: 'complete',
+          verifying: 'idle',
+          issuing: 'idle',
+        },
+        depositAddress: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
+      };
+
+      expect(progress.depositAddress).toBeDefined();
+      expect(progress.depositAddress).toMatch(/^bc1/);
+    });
+  });
+
+  describe('BtcStake Method Signatures', () => {
+    it('should define prepare method', () => {
+      // Type-only test - verifies interface is correctly defined
+      type PrepareMethod = (amount: string, recipient: string) => Promise<void>;
+
+      const testType: PrepareMethod = async () => {};
+      expect(testType).toBeDefined();
+    });
+
+    it('should define authorize method', () => {
+      type AuthorizeMethod = () => Promise<void>;
+
+      const testType: AuthorizeMethod = async () => {};
+      expect(testType).toBeDefined();
+    });
+
+    it('should define generateDepositAddress method', () => {
+      type GenerateAddressMethod = () => Promise<string>;
+
+      const testType: GenerateAddressMethod = async () =>
+        'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh';
+      expect(testType).toBeDefined();
+    });
+
+    it('should define execute method', () => {
+      type ExecuteMethod = () => Promise<{ depositAddress: string }>;
+
+      const testType: ExecuteMethod = async () => ({
+        depositAddress: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
+      });
+      expect(testType).toBeDefined();
+    });
+  });
+
+  describe('Event Emissions', () => {
+    it('should emit progress events with correct type', () => {
+      const handler = vi.fn((progress: BtcStakeProgress) => {
+        expect(progress.status).toBeDefined();
+        expect(progress.steps).toBeDefined();
+      });
+
+      // Simulate event emission
+      handler({
+        status: 'address_ready',
+        steps: { created: 'complete', verifying: 'pending', issuing: 'idle' },
+      });
+
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('should emit status change events', () => {
+      const handler = vi.fn((status: string) => {
+        expect(typeof status).toBe('string');
+      });
+
+      handler('ready');
+      expect(handler).toHaveBeenCalledWith('ready');
+    });
+
+    it('should emit completed event', () => {
+      const handler = vi.fn();
+      handler();
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('should emit error events', () => {
+      const handler = vi.fn((error: LombardError) => {
+        expect(error).toBeInstanceOf(LombardError);
+      });
+
+      handler(
+        new LombardError(ProviderErrorCode.PROVIDER_MISSING, 'Test error'),
+      );
+      expect(handler).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle missing provider errors', () => {
+      const error = LombardError.providerMissing('ethereum', 'evm');
+
+      expect(error.code).toBe(ProviderErrorCode.PROVIDER_MISSING);
+      expect(error.message).toContain('ethereum');
+    });
+
+    it('should handle user rejection errors', () => {
+      const error = LombardError.userRejected('fee authorization');
+
+      expect(error.code).toBe(ProviderErrorCode.USER_REJECTED);
+      expect(error.message).toContain('fee authorization');
+    });
+
+    it('should handle API errors', () => {
+      const error = LombardError.providerCallFailed(
+        'getNetworkFeeSignature',
+        'Network error',
+      );
+
+      expect(error.code).toBe(ProviderErrorCode.PROVIDER_CALL_FAILED);
+      expect(error.message).toContain('getNetworkFeeSignature');
+    });
+  });
+
+  describe('Public Properties', () => {
+    it('should expose status property', () => {
+      // Type check - verifies readonly status: string exists
+      type HasStatus = { readonly status: string };
+      const obj: HasStatus = { status: 'idle' };
+      expect(obj.status).toBe('idle');
+    });
+
+    it('should expose error property', () => {
+      type HasError = { readonly error: LombardError | null };
+      const obj: HasError = { error: null };
+      expect(obj.error).toBeNull();
+    });
+
+    it('should expose amount property', () => {
+      type HasAmount = { readonly amount?: string };
+      const obj: HasAmount = { amount: '0.1' };
+      expect(obj.amount).toBe('0.1');
+    });
+
+    it('should expose recipient property', () => {
+      type HasRecipient = { readonly recipient?: string };
+      const obj: HasRecipient = {
+        recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+      };
+      expect(obj.recipient).toBeDefined();
+    });
+
+    it('should expose depositAddress property', () => {
+      type HasDepositAddress = { readonly depositAddress?: string };
+      const obj: HasDepositAddress = {
+        depositAddress: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
+      };
+      expect(obj.depositAddress).toBeDefined();
+    });
+  });
+});

package/src/chains/btc/actions/stake/config/evm.ts

@@ -0,0 +1,183 @@
+/**
+ * EVM Chain Configuration
+ *
+ * Handles all EVM-compatible destination chains (Ethereum, Base, Arbitrum, etc.)
+ * Includes fee authorization for Ethereum mainnet and destination signing for others.
+ *
+ * Supported chains are derived from ASSET_CATALOG - single source of truth.
+ *
+ * @module chains/btc/actions/stake/config/evm
+ */
+
+import type { EvmService } from '@lombard.finance/sdk-common';
+import type { EIP1193Provider } from 'viem';
+
+import type { ChainId } from '../../../../../common/chains';
+import { AssetId, Chain, Env, getAllAssetChains } from '../../../../../core';
+import { LombardError } from '../../../../../shared/errors';
+import { ensureCorrectChain } from '../../../../../shared/evm/switchChain';
+import { evmAddressSchema } from '../../../../../shared/validation';
+import { Token } from '../../../../../tokens/token-addresses';
+import { getTokenContractInfo } from '../../../../../tokens/tokens';
+import { isEvmChain } from '../../../../../utils/chain';
+import { toSatoshi } from '../../../../../utils/satoshi';
+import type { ChainConfig, FeeAuthConfig } from './types';
+
+/**
+ * Chains that require fee authorization (unsubsidized chains).
+ * 
+ * These chains require users to sign a fee authorization message
+ * before minting LBTC. On subsidized chains, Lombard covers the fees.
+ */
+const UNSUBSIDIZED_CHAINS = [Chain.ETHEREUM, Chain.SEPOLIA] as const;
+
+/**
+ * Fee authorization config for unsubsidized chains.
+ *
+ * Ethereum mainnet and Sepolia require fee authorization.
+ * All methods access EvmService via capabilities.
+ *
+ * BTC Stake produces LBTC, so we use Token.LBTC for fee signatures.
+ * This ensures the backend can distinguish between LBTC and BTC.b signatures.
+ */
+const feeAuthConfig: FeeAuthConfig = {
+  async getMintingFee(ctx, chainId) {
+    const evm = ctx.capabilities.require('evm') as EvmService;
+    return evm.getMintingFee(chainId as ChainId);
+  },
+
+  async restoreFeeSignature(ctx, chainId, address) {
+    // Get LBTC token address for this chain to distinguish from BTC.b signatures
+    const tokenInfo = await getTokenContractInfo(
+      Token.LBTC,
+      chainId as ChainId,
+      ctx.env,
+    );
+
+    const result = await ctx.api.getFeeSignature({
+      address,
+      chainId: chainId as ChainId,
+      tokenAddress: tokenInfo.address,
+    });
+
+    // Check if signature exists on server (API returns has_signature flag)
+    if (!result.hasSignature) {
+      return null;
+    }
+
+    // Check expiration - expirationDate is Unix timestamp in seconds
+    // Convert to milliseconds for Date comparison
+    if (result.expirationDate && new Date(Number(result.expirationDate) * 1000) < new Date()) {
+      return null;
+    }
+
+    // Return hasSignature: true even if actual signature string is not returned by API
+    // The server has the signature stored; we just need to know it's valid
+    return {
+      hasSignature: true,
+      signature: result.signature, // May be undefined - that's OK
+      typedData: result.typedData,
+    };
+  },
+
+  async authorizeFee(ctx, { chainId, recipient, fee }) {
+    const evm = ctx.capabilities.require('evm') as EvmService;
+    const provider = await ctx.getProvider('evm');
+    if (!provider) {
+      throw LombardError.providerMissing(String(chainId), 'evm');
+    }
+
+    // Ensure wallet is on the correct chain before signing
+    await ensureCorrectChain(provider as EIP1193Provider, chainId as ChainId);
+
+    // getMintingFee returns BTC (e.g., "0.00000032"), but signNetworkFee expects satoshis
+    const feeInSatoshis = toSatoshi(fee).toString();
+
+    // Get LBTC token info for this chain
+    const tokenInfo = await getTokenContractInfo(
+      Token.LBTC,
+      chainId as ChainId,
+      ctx.env,
+    );
+
+    // Sign the network fee with LBTC token (explicitly specified)
+    const result = await evm.signNetworkFee({
+      fee: feeInSatoshis,
+      account: recipient,
+      chainId: chainId as ChainId,
+      provider: provider as EIP1193Provider,
+      token: Token.LBTC,
+    });
+
+    // Store the signature with token address to distinguish from BTC.b signatures
+    await ctx.api.storeFeeSignature({
+      address: recipient,
+      signature: result.signature,
+      typedData: result.typedData,
+      tokenAddress: tokenInfo.address,
+    });
+
+    return {
+      signature: result.signature,
+      typedData: result.typedData,
+    };
+  },
+};
+
+/**
+ * EVM chain configuration for BTC stake
+ *
+ * BTC Stake: BTC → LBTC (yield-bearing staked BTC)
+ * Supports staking BTC to LBTC on any EVM-compatible chain.
+ * Supported chains are derived from ASSET_CATALOG[AssetId.LBTC].deployments.
+ */
+export const evmConfig: ChainConfig = {
+  chainType: 'evm',
+
+  routes: [
+    {
+      sourceChains: [Chain.BITCOIN_MAINNET],
+      envs: [Env.prod],
+    },
+    {
+      sourceChains: [Chain.BITCOIN_SIGNET],
+      envs: [Env.testnet, Env.stage, Env.dev, Env.ibc],
+    },
+  ],
+
+  // Derived from ASSET_CATALOG - all EVM chains where LBTC is deployed
+  // Note: This includes all chains across all environments
+  // The `routes` config above filters by source chain + env
+  destChains: getAllAssetChains(AssetId.LBTC).filter(chain => {
+    return isEvmChain(chain);
+  }),
+
+  // BTC Stake only produces LBTC
+  supportedAssetsOut: [AssetId.LBTC],
+
+  addressSchema: evmAddressSchema,
+
+  getFeeAuthConfig(destChain) {
+    // Unsubsidized chains require fee authorization
+    return (UNSUBSIDIZED_CHAINS as readonly Chain[]).includes(destChain)
+      ? feeAuthConfig
+      : null;
+  },
+
+  async getSignature(ctx, recipient, chainId) {
+    const evm = ctx.capabilities.require('evm') as EvmService;
+    const provider = await ctx.getProvider('evm');
+    if (!provider) {
+      throw LombardError.providerMissing(String(chainId), 'evm');
+    }
+
+    // Ensure wallet is on the correct chain before signing
+    await ensureCorrectChain(provider as EIP1193Provider, chainId as ChainId);
+
+    return evm.signLbtcDestination({
+      chainId: chainId as ChainId,
+      address: recipient,
+      provider: provider as EIP1193Provider,
+    });
+  },
+};

package/src/chains/btc/actions/stake/config/index.ts

@@ -0,0 +1,122 @@
+/**
+ * Chain Configuration Registry
+ *
+ * Exports all chain configurations and provides registry lookup functions.
+ *
+ * BTC Stake: BTC → LBTC (yield-bearing staked BTC)
+ *
+ * @module chains/btc/actions/stake/config
+ */
+
+import type { AssetId, Chain, ChainType, Env } from '../../../../../core';
+import { evmConfig } from './evm';
+import { solanaConfig } from './solana';
+import { starknetConfig } from './starknet';
+import { suiConfig } from './sui';
+import type { ChainConfig } from './types';
+
+// Re-export types
+export type {
+  ChainConfig,
+  FeeAuthConfig,
+  FeeAuthResult,
+  RouteDefinition,
+  SignatureResult,
+  StoredFeeSignature,
+} from './types';
+
+// Re-export individual configs
+export { evmConfig } from './evm';
+export { solanaConfig } from './solana';
+export { starknetConfig } from './starknet';
+export { suiConfig } from './sui';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Registry
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Registry of all chain configurations
+ *
+ * Add new chain types here to support additional destination chains.
+ * The key must match the ChainType from the chain catalog.
+ */
+export const chainConfigs: Partial<Record<ChainType, ChainConfig>> = {
+  evm: evmConfig,
+  solana: solanaConfig,
+  sui: suiConfig,
+  starknet: starknetConfig,
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Lookup Functions
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get chain configuration by chain type
+ *
+ * @param chainType - The chain type from getChainType()
+ * @returns ChainConfig or undefined if not supported
+ */
+export function getChainConfig(chainType: ChainType): ChainConfig | undefined {
+  return chainConfigs[chainType];
+}
+
+/**
+ * Check if a chain type is supported for BTC staking
+ *
+ * @param chainType - The chain type to check
+ * @returns true if supported
+ */
+export function isChainTypeSupported(chainType: ChainType): boolean {
+  return chainType in chainConfigs;
+}
+
+/**
+ * Check if a specific route is available
+ *
+ * @param config - Chain configuration
+ * @param sourceChain - Source chain (Bitcoin network)
+ * @param env - Environment
+ * @returns true if route is available
+ */
+export function isRouteAvailable(
+  config: ChainConfig,
+  sourceChain: Chain | undefined,
+  env: Env,
+): boolean {
+  if (!sourceChain) return true; // No source chain specified, allow all
+
+  return config.routes.some(
+    route =>
+      route.sourceChains.includes(sourceChain) && route.envs.includes(env),
+  );
+}
+
+/**
+ * Check if a destination chain is supported by a config
+ *
+ * @param config - Chain configuration
+ * @param destChain - Destination chain
+ * @returns true if destination chain is supported
+ */
+export function isDestChainSupported(
+  config: ChainConfig,
+  destChain: Chain,
+): boolean {
+  return config.destChains.includes(destChain);
+}
+
+/**
+ * Check if an output asset is supported by a config
+ *
+ * @param config - Chain configuration
+ * @param assetOut - Output asset
+ * @returns true if output asset is supported
+ */
+export function isAssetOutSupported(
+  config: ChainConfig,
+  assetOut: AssetId,
+): boolean {
+  return config.supportedAssetsOut.includes(assetOut);
+}

package/src/chains/btc/actions/stake/config/solana.ts

@@ -0,0 +1,96 @@
+/**
+ * Solana Chain Configuration
+ *
+ * Handles Solana destination chains (mainnet and devnet).
+ * Uses Solana wallet signing via the Solana SDK module.
+ *
+ * BTC Stake: BTC → LBTC (yield-bearing staked BTC)
+ * Supported chains derived from ASSET_CATALOG.
+ *
+ * @module chains/btc/actions/stake/config/solana
+ */
+
+import type { SolanaService } from '@lombard.finance/sdk-common';
+
+import { AssetId, Chain, Env, getAllAssetChains } from '../../../../../core';
+import { LombardError, ValidationErrorCode } from '../../../../../shared/errors';
+import { solanaAddressSchema } from '../../../../../shared/validation';
+import { isSolanaChain } from '../../../../../utils/chain';
+import type { ChainConfig } from './types';
+
+/**
+ * Map CAIP-2 Solana chain identifier to SolanaNetwork format.
+ * 
+ * The Solana SDK's signLbtcDestination expects network names like 'devnet', 'mainnet-beta',
+ * but the SDK uses CAIP-2 chain identifiers with genesis hash references.
+ * 
+ * @param chainId - CAIP-2 chain identifier (e.g., 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1')
+ * @returns SolanaNetwork format (e.g., 'devnet')
+ */
+function chainToSolanaNetwork(chainId: string): string {
+  // Map from CAIP-2 genesis hash references to SolanaNetwork names
+  const CHAIN_TO_NETWORK: Record<string, string> = {
+    // CAIP-2 format using genesis hash
+    [Chain.SOLANA_MAINNET]: 'mainnet-beta',
+    [Chain.SOLANA_DEVNET]: 'devnet',
+    [Chain.SOLANA_TESTNET]: 'testnet',
+    // Legacy format (solana:network-name)
+    'solana:mainnet-beta': 'mainnet-beta',
+    'solana:devnet': 'devnet',
+    'solana:testnet': 'testnet',
+  };
+
+  const network = CHAIN_TO_NETWORK[chainId];
+  if (!network) {
+    throw new LombardError(
+      ValidationErrorCode.INVALID_CHAIN,
+      `Unknown Solana chain: ${chainId}. Expected one of: ${Object.keys(CHAIN_TO_NETWORK).join(', ')}`,
+    );
+  }
+  return network;
+}
+
+/**
+ * Solana chain configuration for BTC stake
+ *
+ * Supports staking BTC to LBTC on Solana.
+ * Requires the @lombard.finance/sdk-solana module to be installed.
+ */
+export const solanaConfig: ChainConfig = {
+  chainType: 'solana',
+
+  routes: [
+    {
+      sourceChains: [Chain.BITCOIN_MAINNET],
+      envs: [Env.prod],
+    },
+    {
+      sourceChains: [Chain.BITCOIN_SIGNET],
+      envs: [Env.testnet, Env.stage, Env.dev, Env.ibc],
+    },
+  ],
+
+  // Derived from ASSET_CATALOG - Solana chains where LBTC is deployed
+  destChains: getAllAssetChains(AssetId.LBTC).filter(chain =>
+    isSolanaChain(chain),
+  ),
+
+  // BTC Stake only produces LBTC
+  supportedAssetsOut: [AssetId.LBTC],
+
+  addressSchema: solanaAddressSchema,
+
+  // Solana never requires fee authorization
+  getFeeAuthConfig: () => null,
+
+  async getSignature(ctx, _recipient, chainId) {
+    const solana = ctx.capabilities.require('solana') as SolanaService;
+    // Convert CAIP-2 chain ID to SolanaNetwork format (e.g., 'devnet')
+    const network = chainToSolanaNetwork(chainId as string);
+    const { signature } = await solana.signLbtcDestination({
+      network,
+    });
+
+    return { signature };
+  },
+};