@lombard.finance/sdk 4.0.0 → 4.1.2

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

@@ -1,66 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-/**
- * 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

@@ -1,165 +0,0 @@
-/**
- * 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

@@ -1,53 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * 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

@@ -1,175 +0,0 @@
-/**
- * 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>;
-}