@lombard.finance/sdk 3.7.4 → 4.0.0

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

@@ -0,0 +1,93 @@
+/**
+ * BTC StakeAndDeploy Chain Configuration Types
+ *
+ * BTC StakeAndDeploy: BTC → LBTC → DeFi vault
+ *
+ * @module chains/btc/actions/stakeAndDeploy/config/types
+ */
+
+import type { z } from 'zod';
+
+import type { AssetId, Chain, DeployProtocol, Env } from '../../../../../core';
+import type { BtcCoreContext } from '../../../../../shared/context';
+
+/**
+ * Route definition
+ */
+export interface StakeAndDeployRouteDefinition {
+  sourceChains: Chain[];
+  envs: Env[];
+}
+
+/**
+ * Authorization result
+ */
+export interface StakeAndBakeAuthResult {
+  signature: string;
+  typedData?: string;
+}
+
+/**
+ * Result from restoring existing stake and bake signature
+ */
+export interface StakeAndBakeRestoreResult {
+  /** Whether a valid signature exists on the server */
+  hasSignature: boolean;
+  /** The signature (may be undefined even if hasSignature is true) */
+  signature?: string;
+  /** The deposit amount from the existing signature */
+  depositAmount?: string;
+  /** Expiration date (Unix timestamp) */
+  expirationDate?: string;
+}
+
+/**
+ * StakeAndDeploy chain configuration
+ *
+ * StakeAndDeploy produces LBTC then deploys to a vault.
+ */
+export interface StakeAndDeployChainConfig {
+  chainType: 'evm';
+  routes: StakeAndDeployRouteDefinition[];
+  destChains: Chain[];
+  /** Supported output assets - StakeAndDeploy produces LBTC */
+  supportedAssetsOut: AssetId[];
+  supportedProtocols: DeployProtocol[];
+  addressSchema: z.ZodString;
+
+  /**
+   * Get stake and bake fee for a protocol
+   */
+  getStakeAndBakeFee: (
+    ctx: BtcCoreContext,
+    chainId: unknown,
+    vaultKey: string,
+  ) => Promise<string>;
+
+  /**
+   * Authorize stake and bake (EIP-712 signing)
+   */
+  authorizeStakeAndBake: (
+    ctx: BtcCoreContext,
+    params: {
+      chainId: unknown;
+      recipient: string;
+      amount: string;
+      vaultKey: string;
+      token: string;
+    },
+  ) => Promise<StakeAndBakeAuthResult>;
+
+  /**
+   * Restore existing stake and bake signature from the server.
+   * Used to check if a valid unexpired signature already exists,
+   * allowing the action to skip the signing step.
+   *
+   * @returns null if no valid signature exists, otherwise the restore result
+   */
+  restoreStakeAndBakeSignature: (
+    ctx: BtcCoreContext,
+    chainId: unknown,
+    recipient: string,
+  ) => Promise<StakeAndBakeRestoreResult | null>;
+}

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

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

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

@@ -0,0 +1,26 @@
+/**
+ * BTC StakeAndDeploy Action Exports
+ *
+ * @module chains/btc/actions/stakeAndDeploy
+ */
+
+// Main action class
+export { BtcStakeAndDeploy } from './BtcStakeAndDeploy';
+
+// Factory functions
+export { btcStakeAndDeploy, createBtcStakeAndDeploy } from './factory';
+
+// Types
+export type {
+  BtcStakeAndDeployParams,
+  BtcStakeAndDeployPrepareParams,
+  BtcStakeAndDeployProgress,
+  BtcStakeAndDeploy as IBtcStakeAndDeploy,
+} from './types';
+export { BtcActionStatus } from './types';
+
+// Configuration types (for advanced usage)
+export type {
+  StakeAndDeployChainConfig,
+  StakeAndDeployRouteDefinition,
+} from './config';

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

@@ -0,0 +1,118 @@
+/**
+ * BTC StakeAndDeploy Action Types
+ *
+ * Type definitions for BTC → LBTC → Vault operations.
+ *
+ * @module chains/btc/actions/stakeAndDeploy/types
+ */
+
+import type {
+  AssetId,
+  Chain,
+  DeployProtocol,
+  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 };
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Parameters
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * BTC StakeAndDeploy parameters
+ */
+export interface BtcStakeAndDeployParams {
+  /** Input asset (BTC) */
+  assetIn?: AssetId;
+  /** Output asset (LBTC vault shares) */
+  assetOut: AssetId;
+  /** Source Bitcoin network */
+  sourceChain?: typeof Chain.BITCOIN_MAINNET | typeof Chain.BITCOIN_SIGNET;
+  /** Destination chain where vault exists */
+  destChain: Chain;
+  /** Protocol/vault to deploy to */
+  protocol: DeployProtocol;
+}
+
+/**
+ * Prepare parameters
+ */
+export interface BtcStakeAndDeployPrepareParams {
+  /** Amount of BTC to stake and deploy (human-readable) */
+  amount: string;
+  /** Recipient address on destination chain */
+  recipient: string;
+  /** Optional referral code */
+  referralCode?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Progress
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * BTC StakeAndDeploy progress
+ */
+export interface BtcStakeAndDeployProgress
+  extends StrategyProgress<BtcActionStatus> {
+  status: BtcActionStatus;
+  steps: {
+    created: StepStatus;
+    verifying: StepStatus;
+    issuing: StepStatus;
+    depositing: StepStatus;
+  };
+  depositAddress?: string;
+  confirmations?: number;
+  requiredConfirmations?: number;
+  hasEnoughConfirmations?: boolean;
+  isClaimed?: boolean;
+  isDeposited?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Interface
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * BTC StakeAndDeploy interface
+ */
+export interface BtcStakeAndDeploy extends MonitorableAction {
+  readonly status: BtcActionStatus;
+  readonly amount?: string;
+  readonly recipient?: string;
+  readonly depositAddress?: string;
+  readonly referralCode?: string;
+
+  /**
+   * Prepare the operation
+   */
+  prepare(params: BtcStakeAndDeployPrepareParams): Promise<void>;
+
+  /**
+   * Authorize vault deposit via signature
+   */
+  authorizeDeposit(): Promise<void>;
+
+  /**
+   * Generate BTC deposit address
+   */
+  generateDepositAddress(): Promise<string>;
+
+  /**
+   * Execute the operation
+   */
+  execute(): Promise<{ depositAddress: string; txHash?: string }>;
+
+  /**
+   * Monitor deposit progress
+   */
+  monitorDeposit?(): Promise<MonitorProgress | undefined>;
+}

package/src/chains/btc/client/getCurrentBlockHeight.ts

@@ -0,0 +1,28 @@
+import axios from 'axios';
+
+import { handleMempoolApiError } from './mempool/error';
+import { getBtcApiConfig,TNetworkMode } from './mempool/mempool';
+
+interface Response {
+  height: number;
+  hash: string;
+  timestamp: string;
+}
+
+/**
+ * Returns the current block height from the mempool.space API
+ */
+export async function getCurrentBlockHeight(
+  mode: TNetworkMode,
+): Promise<number> {
+  const { mempoolApiUrl } = getBtcApiConfig(mode);
+  const timestamp = Math.floor(Date.now() / 1000);
+  const url = `${mempoolApiUrl}/api/v1/mining/blocks/timestamp/${timestamp}`;
+
+  try {
+    const { data } = await axios.get<Response>(url);
+    return data.height;
+  } catch (error) {
+    handleMempoolApiError(error);
+  }
+}

package/src/chains/btc/client/mempool/error.ts

@@ -0,0 +1,24 @@
+import { AxiosError } from 'axios';
+
+const ADBLOCKER_ERROR_CODE = 'ERR_NETWORK';
+
+const ADBLOCK_ERROR_MSG =
+  'This may be due to your Adblocker. Please disable any Adblocker and refresh the page to restore full functionality.';
+
+/**
+ * Handles the error from the mempool.space API.
+ * If the error is due to an adblocker, it throws an error with a message to disable the adblocker.
+ *
+ * @param error Error object.
+ *
+ * @throws Error with the error message.
+ */
+export function handleMempoolApiError(error: unknown): never {
+  const { code, message } = error as AxiosError;
+
+  if (code === ADBLOCKER_ERROR_CODE) {
+    throw new Error(ADBLOCK_ERROR_MSG);
+  }
+
+  throw new Error(message);
+}

package/src/chains/btc/client/mempool/mempool.ts

@@ -0,0 +1,23 @@
+export type TNetworkMode = 'mainnet' | 'testnet';
+
+interface IApiConfig {
+  mempoolApiUrl: string;
+}
+
+const stageConfig: IApiConfig = {
+  mempoolApiUrl: 'https://mempool.space/signet',
+};
+
+const prodConfig: IApiConfig = {
+  mempoolApiUrl: 'https://mempool.space',
+};
+
+/**
+ * Returns the configuration for the Bitcoin related APIs.
+ *
+ * @param mode - The network mode.
+ *
+ * @returns The configuration.
+ */
+export const getBtcApiConfig = (mode: TNetworkMode): IApiConfig =>
+  mode === 'mainnet' ? prodConfig : stageConfig;

package/src/chains/btc/index.ts

@@ -0,0 +1,71 @@
+/**
+ * BTC Chain Exports
+ *
+ * Provides Bitcoin operations (stake, stakeAndDeploy, deposit).
+ *
+ * @module chains/btc
+ */
+
+// Main exports
+export { BtcActions, btcActions } from './BtcActions';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Unified BTC Action Status
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Single export to avoid duplicate identifiers
+export { BtcActionStatus } from '../../shared/constants/statusConstants';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Stake Action
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type {
+  BtcStakeParams,
+  BtcStakeProgress,
+  BtcStake as IBtcStake,
+} from './actions/stake';
+export { BtcStake, btcStake, createBtcStake } from './actions/stake';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Deposit Action
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type {
+  BtcDepositParams,
+  BtcDepositPrepareParams,
+  BtcDepositProgress,
+  BtcDeposit as IBtcDeposit,
+} from './actions/deposit';
+export { BtcDeposit, btcDeposit, createBtcDeposit } from './actions/deposit';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// StakeAndDeploy Action
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type {
+  BtcStakeAndDeployParams,
+  BtcStakeAndDeployPrepareParams,
+  BtcStakeAndDeployProgress,
+  BtcStakeAndDeploy as IBtcStakeAndDeploy,
+} from './actions/stakeAndDeploy';
+export {
+  BtcStakeAndDeploy,
+  btcStakeAndDeploy,
+  createBtcStakeAndDeploy,
+} from './actions/stakeAndDeploy';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DepositAndDeploy Action
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type {
+  BtcDepositAndDeployParams,
+  BtcDepositAndDeployPrepareParams,
+  BtcDepositAndDeployProgress,
+  BtcDepositAndDeploy as IBtcDepositAndDeploy,
+} from './actions/depositAndDeploy';
+export {
+  BtcDepositAndDeploy,
+  createBtcDepositAndDeploy,
+} from './actions/depositAndDeploy';

package/src/chains/evm/EvmActions.ts

@@ -0,0 +1,185 @@
+/**
+ * EVM Actions
+ *
+ * Provides factory methods for EVM chain operations.
+ *
+ * Operations:
+ * - stake: BTC.b → LBTC (stake wrapped BTC to get LBTC)
+ * - unstake: LBTC → BTC (cross-chain) or LBTC → BTC.b (same-chain)
+ * - deposit: Claim LBTC with notarized proof
+ * - deploy: LBTC/BTC.b → DeFi protocols (Veda, Silo)
+ * - redeem: LBTC → BTC.b (same-chain unwrap)
+ *
+ * @example
+ * ```typescript
+ * import { createLombardSDK, Chain, Env } from '@lombard.finance/sdk';
+ *
+ * const sdk = await createLombardSDK({
+ *   env: Env.prod,
+ *   providers: { evm: () => window.ethereum },
+ * });
+ *
+ * const unstake = sdk.chain.evm.unstake({
+ *   sourceChain: Chain.ETHEREUM,
+ *   assetOut: AssetId.BTC,
+ * });
+ *
+ * await unstake.prepare({ amount: '0.1', recipient: 'bc1q...' });
+ * const { txHash } = await unstake.execute();
+ * ```
+ *
+ * @module chains/evm/EvmActions
+ */
+
+import type { LombardConfig } from '../../config/types';
+import type { EvmCoreContext } from '../../shared/context';
+import { createEvmCoreContext } from '../../shared/context';
+import {
+  createEvmDeploy,
+  type EvmDeployParams,
+  type IEvmDeploy,
+} from './actions/deploy';
+import {
+  createEvmDeposit,
+  type EvmDepositParams,
+  type IEvmDeposit,
+} from './actions/deposit';
+import {
+  createEvmRedeem,
+  type EvmRedeemParams,
+  type IEvmRedeem,
+} from './actions/redeem';
+// Import action factories
+import {
+  createEvmStake,
+  type EvmStakeParams,
+  type IEvmStake,
+} from './actions/stake';
+import {
+  createEvmUnstake,
+  type EvmUnstakeParams,
+  type IEvmUnstake,
+} from './actions/unstake';
+
+/**
+ * EVM Actions
+ *
+ * User-facing class for EVM operations.
+ * Created via evmActions(config) factory function.
+ */
+export class EvmActions {
+  private readonly ctx: EvmCoreContext;
+
+  constructor(config: LombardConfig) {
+    this.ctx = createEvmCoreContext(config);
+  }
+
+  /**
+   * Stake BTC.b to receive LBTC
+   *
+   * Converts wrapped BTC (BTC.b) to LBTC via the Asset Router.
+   * Currently supported on Avalanche.
+   *
+   * @example
+   * ```typescript
+   * const stake = evm.stake({
+   *   assetIn: AssetId.BTCb,
+   *   assetOut: AssetId.LBTC,
+   *   sourceChain: Chain.AVALANCHE,
+   *   destChain: Chain.AVALANCHE,
+   * });
+   * ```
+   */
+  stake(params: EvmStakeParams): IEvmStake {
+    return createEvmStake(this.ctx, params);
+  }
+
+  /**
+   * Unstake LBTC to BTC or BTC.b
+   *
+   * - LBTC → BTC: Cross-chain to Bitcoin mainnet/signet
+   * - LBTC → BTC.b: Same-chain wrapped BTC on EVM
+   *
+   * @example
+   * ```typescript
+   * const unstake = evm.unstake({
+   *   assetIn: AssetId.LBTC,
+   *   assetOut: AssetId.BTC,
+   *   sourceChain: Chain.ETHEREUM,
+   *   destChain: Chain.BITCOIN_MAINNET,
+   * });
+   * ```
+   */
+  unstake(params: EvmUnstakeParams): IEvmUnstake {
+    return createEvmUnstake(this.ctx, params);
+  }
+
+  /**
+   * Deposit wrapped BTC to get LBTC
+   *
+   * Deposits WBTC or BTCb to receive LBTC.
+   *
+   * @example
+   * ```typescript
+   * const deposit = evm.deposit({
+   *   assetIn: AssetId.WBTC,
+   *   assetOut: AssetId.LBTC,
+   *   sourceChain: Chain.ETHEREUM,
+   *   destChain: Chain.ETHEREUM,
+   * });
+   * ```
+   */
+  deposit(params: EvmDepositParams): IEvmDeposit {
+    return createEvmDeposit(this.ctx, params);
+  }
+
+  /**
+   * Deploy L-Assets to DeFi protocols
+   *
+   * Currently supports Veda and Silo protocols.
+   *
+   * @example
+   * ```typescript
+   * const deploy = evm.deploy({
+   *   asset: AssetId.LBTC,
+   *   sourceChain: Chain.ETHEREUM,
+   *   protocol: DeployProtocol.Veda,
+   *   recipient: '0x...',
+   * });
+   * ```
+   */
+  deploy(params: EvmDeployParams): IEvmDeploy {
+    return createEvmDeploy(this.ctx, params);
+  }
+
+  /**
+   * Redeem LBTC to BTC.b (same-chain unwrap)
+   *
+   * Converts LBTC to BTC.b on the same EVM chain.
+   * For cross-chain BTC redemption, use unstake() with destChain set to Bitcoin.
+   *
+   * @example
+   * ```typescript
+   * const redeem = evm.redeem({
+   *   assetIn: AssetId.LBTC,
+   *   assetOut: AssetId.BTCb,
+   *   sourceChain: Chain.AVALANCHE,
+   * });
+   * ```
+   */
+  redeem(params: EvmRedeemParams): IEvmRedeem {
+    return createEvmRedeem(this.ctx, params);
+  }
+}
+
+/**
+ * Create EVM actions from config
+ *
+ * Factory function that creates EvmActions for EVM operations.
+ *
+ * @param config - LombardConfig instance
+ * @returns EvmActions instance
+ */
+export function evmActions(config: LombardConfig): EvmActions {
+  return new EvmActions(config);
+}