@lombard.finance/sdk 3.7.4 → 4.0.0

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

@@ -0,0 +1,66 @@
+/**
+ * Starknet Chain Configuration
+ *
+ * Handles Starknet destination chains (mainnet and Sepolia).
+ * Uses Starknet wallet signing via the Starknet SDK module.
+ * Note: Starknet requires address padding and returns a public key.
+ *
+ * BTC Stake: BTC → LBTC (yield-bearing staked BTC)
+ * Supported chains derived from ASSET_CATALOG.
+ *
+ * @module chains/btc/actions/stake/config/starknet
+ */
+
+import type { StarknetService } from '@lombard.finance/sdk-common';
+import { pad } from 'viem';
+
+import { AssetId, Chain, Env, getAllAssetChains } from '../../../../../core';
+import { starknetAddressSchema } from '../../../../../shared/validation';
+import { isStarknetChain } from '../../../../../utils/chain';
+import type { ChainConfig } from './types';
+
+/**
+ * Starknet chain configuration for BTC stake
+ *
+ * Supports staking BTC to LBTC on Starknet.
+ * Requires the @lombard.finance/sdk-starknet module to be installed.
+ */
+export const starknetConfig: ChainConfig = {
+  chainType: 'starknet',
+
+  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 - Starknet chains where LBTC is deployed
+  destChains: getAllAssetChains(AssetId.LBTC).filter(chain =>
+    isStarknetChain(chain),
+  ),
+
+  // BTC Stake only produces LBTC
+  supportedAssetsOut: [AssetId.LBTC],
+
+  addressSchema: starknetAddressSchema,
+
+  // Starknet never requires fee authorization
+  getFeeAuthConfig: () => null,
+
+  async getSignature(ctx, recipient, chainId) {
+    const starknet = ctx.capabilities.require('starknet') as StarknetService;
+    const { signature, pubKey } = await starknet.signLbtcDestination({
+      chainId: chainId as string,
+    });
+
+    // Starknet addresses need to be padded to 32 bytes
+    const paddedAddress = pad(recipient as `0x${string}`, { size: 32 });
+
+    return { signature, pubKey, paddedAddress };
+  },
+};

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

@@ -0,0 +1,61 @@
+/**
+ * Sui Chain Configuration
+ *
+ * Handles Sui destination chains (mainnet and testnet).
+ * Uses Sui wallet signing via the Sui SDK module.
+ *
+ * BTC Stake: BTC → LBTC (yield-bearing staked BTC)
+ * Supported chains derived from ASSET_CATALOG.
+ *
+ * @module chains/btc/actions/stake/config/sui
+ */
+
+import type { SuiService } from '@lombard.finance/sdk-common';
+
+import { AssetId, Chain, Env, getAllAssetChains } from '../../../../../core';
+import { suiAddressSchema } from '../../../../../shared/validation';
+import { isSuiChain } from '../../../../../utils/chain';
+import type { ChainConfig } from './types';
+
+/**
+ * Sui chain configuration for BTC stake
+ *
+ * Supports staking BTC to LBTC on Sui.
+ * Requires the @lombard.finance/sdk-sui module to be installed.
+ */
+export const suiConfig: ChainConfig = {
+  chainType: 'sui',
+
+  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 - Sui chains where LBTC is deployed
+  destChains: getAllAssetChains(AssetId.LBTC).filter(chain =>
+    isSuiChain(chain),
+  ),
+
+  // BTC Stake only produces LBTC
+  supportedAssetsOut: [AssetId.LBTC],
+
+  addressSchema: suiAddressSchema,
+
+  // Sui never requires fee authorization
+  getFeeAuthConfig: () => null,
+
+  async getSignature(ctx, _recipient, chainId) {
+    const sui = ctx.capabilities.require('sui') as SuiService;
+    const { signature } = await sui.signLbtcDestination({
+      chainId: chainId as string,
+    });
+
+    return { signature };
+  },
+};

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

@@ -0,0 +1,165 @@
+/**
+ * Chain Configuration Types
+ *
+ * Defines the interface for destination chain configurations.
+ * Each supported chain implements this interface to provide
+ * chain-specific behavior for BTC stake operations.
+ *
+ * BTC Stake: BTC → LBTC (yield-bearing staked BTC)
+ *
+ * @module chains/btc/actions/stake/config/types
+ */
+
+import type { z } from 'zod';
+
+import type { AssetId, Chain, ChainType, Env } from '../../../../../core';
+import type { BtcCoreContext } from '../../../../../shared/context';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Signature Result
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Result from chain signature acquisition
+ */
+export interface SignatureResult {
+  /** The signature to use for deposit address generation */
+  signature: string;
+  /** EIP-712 typed data (for EVM fee authorization) */
+  typedData?: string;
+  /** Public key (required for Starknet) */
+  pubKey?: string;
+  /** Padded address if chain requires it (Starknet) */
+  paddedAddress?: string;
+}
+
+/**
+ * Stored fee signature result from restore operation
+ * 
+ * Note: The API may return hasSignature: true but not the actual signature string.
+ * The caller should check hasSignature to determine if a valid signature exists on the server.
+ */
+export interface StoredFeeSignature {
+  hasSignature: boolean;
+  signature?: string;
+  typedData?: string;
+  expirationDate?: string;
+}
+
+/**
+ * Fee authorization result
+ */
+export interface FeeAuthResult {
+  signature: string;
+  typedData?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Route Definition
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Route definition for a chain configuration
+ */
+export interface RouteDefinition {
+  /** Supported source chains (Bitcoin networks) */
+  sourceChains: Chain[];
+  /** Supported environments */
+  envs: Env[];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Fee Authorization Config
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Fee authorization configuration
+ *
+ * When present, ALL methods are guaranteed to exist.
+ * Used for chains that require fee authorization (e.g., Ethereum mainnet).
+ */
+export interface FeeAuthConfig {
+  /**
+   * Get minting fee for display
+   * Called in prepare() to fetch fee before authorization
+   */
+  getMintingFee: (ctx: BtcCoreContext, chainId: unknown) => Promise<string>;
+
+  /**
+   * Try to restore a stored fee signature (resume flow)
+   * Called in prepare() before getMintingFee
+   */
+  restoreFeeSignature: (
+    ctx: BtcCoreContext,
+    chainId: unknown,
+    address: string,
+  ) => Promise<StoredFeeSignature | null>;
+
+  /**
+   * Authorize fee (EIP-712 signing)
+   * Called in authorize() when fee auth is required
+   */
+  authorizeFee: (
+    ctx: BtcCoreContext,
+    params: { chainId: unknown; recipient: string; fee: string },
+  ) => Promise<FeeAuthResult>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Chain Configuration
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Chain-specific configuration for BTC stake operations
+ *
+ * Each supported destination chain type has a config that defines:
+ * - Supported routes (source chains × environments)
+ * - Supported destination chains
+ * - Supported output assets (BTC Stake produces LBTC)
+ * - How to validate addresses (via Zod schema)
+ * - Fee authorization config (if required for this chain)
+ * - How to acquire the destination signature
+ */
+export interface ChainConfig {
+  /** Chain type identifier */
+  chainType: ChainType;
+
+  /** Supported routes for this chain type */
+  routes: RouteDefinition[];
+
+  /** Supported destination chains */
+  destChains: Chain[];
+
+  /** Supported output assets - BTC Stake should only produce LBTC */
+  supportedAssetsOut: AssetId[];
+
+  /** Address validation Zod schema */
+  addressSchema: z.ZodType<string>;
+
+  /**
+   * Get fee authorization config for a destination chain
+   *
+   * Returns FeeAuthConfig if fee auth is required for this destination,
+   * null otherwise. When non-null, all FeeAuthConfig methods are guaranteed.
+   *
+   * @param destChain - Destination chain to check
+   * @returns FeeAuthConfig or null
+   */
+  getFeeAuthConfig: (destChain: Chain) => FeeAuthConfig | null;
+
+  /**
+   * Acquire destination signature for deposit address generation
+   *
+   * Used for non-fee-auth chains or as fallback signature method.
+   *
+   * @param ctx - BTC core context with capabilities
+   * @param recipient - Recipient address on destination chain
+   * @param chainId - Parsed chain identifier
+   * @returns Signature result with signature and optional metadata
+   */
+  getSignature: (
+    ctx: BtcCoreContext,
+    recipient: string,
+    chainId: unknown,
+  ) => Promise<SignatureResult>;
+}

package/src/chains/btc/actions/stake/factory.ts

@@ -0,0 +1,53 @@
+/**
+ * BTC Stake Factory Functions
+ *
+ * Provides factory functions for creating BtcStake instances.
+ * Separates instantiation from the main class.
+ *
+ * @module chains/btc/actions/stake/factory
+ */
+
+import type { LombardConfig } from '../../../../config/types';
+import type { BtcCoreContext } from '../../../../shared/context';
+import { createBtcCoreContext } from '../../../../shared/context';
+import { BtcStake } from './BtcStake';
+import type { BtcStakeParams } from './types';
+
+/**
+ * Create BtcStake action from config
+ *
+ * @internal This factory is for internal use. Use createLombardSDK() instead:
+ *
+ * @example
+ * ```typescript
+ * const sdk = await createLombardSDK({ env: Env.prod, providers: { ... } });
+ * const stake = sdk.chain.btc.stake({
+ *   assetOut: AssetId.LBTC,
+ *   destChain: Chain.ETHEREUM,
+ * });
+ * await stake.prepare({ amount: '0.1', recipient: '0x...' });
+ * ```
+ */
+export function btcStake(
+  config: LombardConfig,
+  params: BtcStakeParams,
+): BtcStake {
+  const ctx = createBtcCoreContext(config);
+  return new BtcStake(ctx, params);
+}
+
+/**
+ * Create BtcStake action from context
+ *
+ * Use this when you already have a BtcCoreContext (e.g., in BtcActions).
+ *
+ * @param ctx - BtcCoreContext
+ * @param params - Stake parameters
+ * @returns BtcStake instance
+ */
+export function createBtcStake(
+  ctx: BtcCoreContext,
+  params: BtcStakeParams,
+): BtcStake {
+  return new BtcStake(ctx, params);
+}

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

@@ -0,0 +1,22 @@
+/**
+ * BTC Stake Action Exports
+ *
+ * @module chains/btc/actions/stake
+ */
+
+// Main action class
+export { BtcStake } from './BtcStake';
+
+// Factory functions
+export { btcStake, createBtcStake } from './factory';
+
+// Types
+export type {
+  BtcStakeParams,
+  BtcStakeProgress,
+  BtcStake as IBtcStake,
+} from './types';
+export { BtcActionStatus } from './types';
+
+// Configuration types (for advanced usage / extending)
+export type { ChainConfig, RouteDefinition, SignatureResult } from './config';

package/src/chains/btc/actions/stake/types.ts

@@ -0,0 +1,175 @@
+/**
+ * BTC Stake Action Types
+ *
+ * Defines types for the BTC → LBTC staking flow.
+ *
+ * @module chains/btc/actions/stake/types
+ */
+
+import type {
+  AssetId,
+  Chain,
+  StepStatus,
+  StrategyProgress,
+} from '../../../../core';
+import type { MonitorableAction } from '../../../../shared/actions/BaseAction';
+import { BtcActionStatus } from '../../../../shared/constants/statusConstants';
+import type { MonitorProgress } from '../../../../shared/monitoring';
+
+// Re-export for convenience (single export statement avoids duplicate identifier)
+export { BtcActionStatus };
+
+/**
+ * BTC Stake parameters
+ *
+ * Parameters for initiating a BTC stake operation.
+ */
+export interface BtcStakeParams {
+  /** Output asset (LBTC) */
+  assetOut: AssetId;
+  /** Destination chain to mint LBTC on */
+  destChain: Chain;
+  /** Source Bitcoin network (optional, defaults based on env) */
+  sourceChain?: typeof Chain.BITCOIN_MAINNET | typeof Chain.BITCOIN_SIGNET;
+}
+
+/**
+ * BTC Stake progress
+ *
+ * Detailed progress information for a BTC stake operation.
+ */
+export interface BtcStakeProgress extends StrategyProgress<BtcActionStatus> {
+  /** Current status */
+  status: BtcActionStatus;
+
+  /** Step statuses */
+  steps: {
+    created: StepStatus;
+    verifying: StepStatus;
+    issuing: StepStatus;
+  };
+
+  /** Optional: Current confirmations */
+  confirmations?: number;
+
+  /** Optional: Required confirmations */
+  requiredConfirmations?: number;
+
+  /** Optional: Has enough confirmations */
+  hasEnoughConfirmations?: boolean;
+
+  /** Optional: Is minting claimed */
+  isClaimed?: boolean;
+
+  /** Optional: BTC deposit address */
+  depositAddress?: string;
+
+  /** Optional: Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * BTC Stake interface
+ *
+ * Interface for BTC → LBTC staking operations.
+ *
+ * Flow:
+ * 1. prepare(amount, recipient) - Validate and store parameters
+ * 2. authorize() - Performs any required authorization (fee or address confirmation)
+ * 3. generateDepositAddress() - Generate BTC deposit address
+ * 4. execute() - Returns address for user to send BTC
+ * 5. Monitor progress via events
+ *
+ * @example
+ * ```typescript
+ * const stake = sdk.chain.btc.stake({
+ *   assetOut: AssetId.LBTC,
+ *   destChain: Chain.ETHEREUM,
+ * });
+ *
+ * await stake.prepare({ amount: '0.1', recipient: '0x...' });
+ * await stake.authorize();
+ * const address = await stake.generateDepositAddress();
+ *
+ * // User sends BTC to address
+ * // Monitor progress
+ * stake.on('progress', (progress) => {
+ *   console.log(progress.confirmations, progress.requiredConfirmations);
+ * });
+ * ```
+ */
+export interface BtcStake extends MonitorableAction {
+  /** Current status */
+  readonly status: BtcActionStatus;
+
+  /** Amount to stake (human-readable BTC) */
+  readonly amount?: string;
+
+  /** Recipient address on destination chain */
+  readonly recipient?: string;
+
+  /** BTC deposit address (after generation) */
+  readonly depositAddress?: string;
+
+  /** Referral code applied during prepare(), if any */
+  readonly referralCode?: string;
+
+  /**
+   * Prepare the stake operation
+   *
+   * Validates amount and recipient, checks for existing fee authorization.
+   *
+   * @param params - Object containing amount and recipient
+   * @param params.amount - Amount to stake (human-readable BTC, e.g., "0.1")
+   * @param params.recipient - Recipient address on destination chain
+   * @param params.referralCode - Optional referral code
+   * @throws LombardError if parameters are invalid
+   */
+  prepare(params: {
+    amount: string;
+    recipient: string;
+    referralCode?: string;
+  }): Promise<void>;
+
+  /**
+   * Authorize the stake operation
+   *
+   * Handles any required authorization step depending on destination chain.
+   * For Ethereum destinations this requests an EIP-712 fee signature; for
+   * other EVM chains it confirms the destination address signature.
+   *
+   * @throws LombardError if the user rejects or provider fails
+   */
+  authorize(): Promise<void>;
+
+  /**
+   * Generate BTC deposit address
+   *
+   * Creates a unique BTC deposit address for this stake operation.
+   * Requires authorization to be completed first.
+   *
+   * @returns BTC deposit address (bc1...)
+   * @throws LombardError if not authorized or API fails
+   */
+  generateDepositAddress(): Promise<string>;
+
+  /**
+   * Execute the stake operation
+   *
+   * Returns the deposit address. User should send BTC to this address.
+   * Progress can be monitored via events.
+   *
+   * @returns Object with depositAddress and optional txHash
+   */
+  execute(): Promise<{ depositAddress: string; txHash?: string }>;
+
+  /**
+   * Monitor deposit progress
+   *
+   * Single-shot check for deposit status. Call repeatedly for continuous monitoring.
+   * Emits progress events and completion when deposit is fully claimed.
+   *
+   * @returns Progress information or undefined if deposit not found yet
+   */
+  monitorDeposit?(): Promise<MonitorProgress | undefined>;
+}