@lombard.finance/sdk 3.7.4 → 4.0.0

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

@@ -0,0 +1,108 @@
+/**
+ * BTC Deposit Chain Configuration Types
+ *
+ * @module chains/btc/actions/deposit/config/types
+ */
+
+import type { z } from 'zod';
+
+import type { AssetId, Chain, Env } from '../../../../../core';
+import type { BtcCoreContext } from '../../../../../shared/context';
+
+/**
+ * Stored fee signature result
+ */
+export interface StoredFeeSignature {
+  hasSignature: boolean;
+  signature?: string;
+  typedData?: string;
+}
+
+/**
+ * Fee authorization result
+ */
+export interface FeeAuthResult {
+  signature: string;
+  typedData?: string;
+}
+
+/**
+ * Signature result for address confirmation
+ */
+export interface SignatureResult {
+  signature: string;
+  typedData?: string;
+}
+
+/**
+ * Route definition for deposit configs
+ */
+export interface DepositRouteDefinition {
+  sourceChains: Chain[];
+  envs: Env[];
+}
+
+/**
+ * Fee authorization configuration
+ *
+ * When present, ALL methods are guaranteed to exist.
+ * Used for chains that require fee authorization (e.g., Ethereum mainnet).
+ */
+export interface DepositFeeAuthConfig {
+  /**
+   * Get the minting fee for this chain (in BTC)
+   * Called in prepare() when fee authorization is needed
+   */
+  getMintingFee: (ctx: BtcCoreContext, chainId: unknown) => Promise<string>;
+
+  /**
+   * Try to restore a stored fee signature (resume flow)
+   */
+  restoreFeeSignature: (
+    ctx: BtcCoreContext,
+    chainId: unknown,
+    address: string,
+  ) => Promise<StoredFeeSignature | null>;
+
+  /**
+   * Authorize fee (EIP-712 signing)
+   */
+  authorizeFee: (
+    ctx: BtcCoreContext,
+    params: { chainId: unknown; recipient: string; fee: string },
+  ) => Promise<FeeAuthResult>;
+}
+
+/**
+ * Deposit chain configuration
+ *
+ * BTC Deposit produces BTC.b (wrapped BTC without yield).
+ * Fee authorization is only required for Ethereum mainnet.
+ * Other chains use address confirmation signing.
+ */
+export interface DepositChainConfig {
+  chainType: 'evm';
+  routes: DepositRouteDefinition[];
+  destChains: Chain[];
+  /** Supported output assets - BTC Deposit should only produce BTC.b */
+  supportedAssetsOut: AssetId[];
+  addressSchema: z.ZodString;
+
+  /**
+   * Get fee authorization config for a destination chain
+   *
+   * Returns DepositFeeAuthConfig if fee auth is required (Ethereum mainnet),
+   * null otherwise (address confirmation will be used instead).
+   */
+  getFeeAuthConfig: (destChain: Chain) => DepositFeeAuthConfig | null;
+
+  /**
+   * Sign destination address confirmation
+   * Used for non-fee-auth chains
+   */
+  signDestination: (
+    ctx: BtcCoreContext,
+    recipient: string,
+    chainId: unknown,
+  ) => Promise<SignatureResult>;
+}

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

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

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

@@ -0,0 +1,23 @@
+/**
+ * BTC Deposit Action Exports
+ *
+ * @module chains/btc/actions/deposit
+ */
+
+// Main action class
+export { BtcDeposit } from './BtcDeposit';
+
+// Factory functions
+export { btcDeposit, createBtcDeposit } from './factory';
+
+// Types
+export type {
+  BtcDepositParams,
+  BtcDepositPrepareParams,
+  BtcDepositProgress,
+  BtcDeposit as IBtcDeposit,
+} from './types';
+export { BtcActionStatus } from './types';
+
+// Configuration types (for advanced usage)
+export type { DepositChainConfig, DepositRouteDefinition } from './config';

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

@@ -0,0 +1,120 @@
+/**
+ * BTC Deposit Action Types
+ *
+ * Type definitions for BTC deposit operations.
+ *
+ * @module chains/btc/actions/deposit/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 };
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Parameters
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * BTC Deposit parameters
+ *
+ * Note: BTC Deposit is for custody operations (BTC → BTC.b).
+ * For staking operations (BTC → LBTC), use BtcStake instead.
+ */
+export interface BtcDepositParams {
+  /** Output asset - should be BTCb for deposit, LBTC for stake */
+  assetOut: AssetId;
+  /** Destination chain for minted asset */
+  destChain: Chain;
+  /** Source Bitcoin network (optional, defaults based on env) */
+  sourceChain?: typeof Chain.BITCOIN_MAINNET | typeof Chain.BITCOIN_SIGNET;
+}
+
+/**
+ * Prepare parameters
+ */
+export interface BtcDepositPrepareParams {
+  /** Amount of BTC to deposit (human-readable, e.g., "0.1") */
+  amount: string;
+  /** Recipient address on destination chain */
+  recipient: string;
+  /** Optional referral code */
+  referralCode?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Progress
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * BTC Deposit progress
+ */
+export interface BtcDepositProgress extends StrategyProgress<BtcActionStatus> {
+  status: BtcActionStatus;
+  steps: {
+    created: StepStatus;
+    verifying: StepStatus;
+    issuing: StepStatus;
+  };
+  confirmations?: number;
+  requiredConfirmations?: number;
+  hasEnoughConfirmations?: boolean;
+  isClaimed?: boolean;
+  depositAddress?: string;
+  metadata?: Record<string, unknown>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Interface
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * BTC Deposit interface
+ */
+export interface BtcDeposit extends MonitorableAction {
+  readonly status: BtcActionStatus;
+  readonly amount?: string;
+  readonly recipient?: string;
+  readonly depositAddress?: string;
+  readonly referralCode?: string;
+
+  /**
+   * Prepare the deposit operation
+   */
+  prepare(params: BtcDepositPrepareParams): Promise<void>;
+
+  /**
+   * Authorize the network fee (Ethereum mainnet only)
+   * For other chains, use confirmAddress() instead.
+   */
+  authorizeFee(): Promise<void>;
+
+  /**
+   * Confirm destination address (non-Ethereum chains)
+   * For Ethereum mainnet, use authorizeFee() instead.
+   */
+  confirmAddress(): Promise<void>;
+
+  /**
+   * Generate BTC deposit address
+   */
+  generateDepositAddress(): Promise<string>;
+
+  /**
+   * Execute the deposit
+   */
+  execute(): Promise<{ depositAddress: string; txHash?: string }>;
+
+  /**
+   * Monitor deposit progress
+   */
+  monitorDeposit?(): Promise<MonitorProgress | undefined>;
+}

package/src/chains/btc/actions/depositAndDeploy/BtcDepositAndDeploy.ts

@@ -0,0 +1,366 @@
+/**
+ * BTC DepositAndDeploy Action
+ *
+ * Handles BTC → BTC.b → Vault deposit in a single atomic operation.
+ * Similar to StakeAndDeploy but produces BTC.b instead of LBTC.
+ * Used for protocols like Silo on Avalanche that accept BTC.b.
+ *
+ * @module chains/btc/actions/depositAndDeploy/BtcDepositAndDeploy
+ */
+
+import type { z } from 'zod';
+
+import type { ChainId } from '../../../../common/chains';
+import { isValidChain } from '../../../../common/chains';
+import { Chain, parseChainIdentifier,StepStatus } from '../../../../core';
+import type { BtcCoreContext } from '../../../../shared/context';
+import { LombardError, ValidationErrorCode } from '../../../../shared/errors';
+import type { DepositAndDeployEventMap } from '../../../../shared/events';
+import {
+  monitorDeposit,
+  type MonitorProgress,
+} from '../../../../shared/monitoring';
+import { Token } from '../../../../tokens/token-addresses';
+import { ensureNotSanctionedAddress } from '../../../../utils/ensureNotSanctionedAddress';
+import { toSatoshi } from '../../../../utils/satoshi';
+import {
+  assetIdToToken,
+  BaseBtcAction,
+  type StatusConfig,
+  type StepDefinition,
+} from '../shared';
+import {
+  depositAndDeployConfig,
+  getVaultKey,
+  isAssetOutSupported,
+  isDestChainSupported,
+  isProtocolSupported,
+  isRouteAvailable,
+} from './config';
+import {
+  BtcActionStatus,
+  type BtcDepositAndDeploy as IBtcDepositAndDeploy,
+  type BtcDepositAndDeployParams,
+  type BtcDepositAndDeployPrepareParams,
+} from './types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface AuthState {
+  fee?: string;
+  signature?: string;
+  typedData?: string;
+  approvalTxHash?: string;
+  authorized: boolean;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BtcDepositAndDeploy Implementation
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * BTC DepositAndDeploy Action
+ *
+ * Combines deposit (BTC → BTC.b) and vault deployment in a single atomic operation.
+ *
+ * @example
+ * ```typescript
+ * const depositAndDeploy = new BtcDepositAndDeploy(ctx, {
+ *   assetOut: AssetId.BTCb,
+ *   destChain: Chain.AVALANCHE,
+ *   protocol: DeployProtocol.Silo,
+ * });
+ *
+ * await depositAndDeploy.prepare({ amount: '0.1', recipient: '0x...' });
+ * await depositAndDeploy.authorizeDeposit();
+ * const address = await depositAndDeploy.generateDepositAddress();
+ * ```
+ */
+export class BtcDepositAndDeploy
+  extends BaseBtcAction<
+    DepositAndDeployEventMap,
+    BtcActionStatus,
+    BtcDepositAndDeployParams
+  >
+  implements IBtcDepositAndDeploy
+{
+  private readonly chainId: ChainId;
+  private readonly authState: AuthState = { authorized: false };
+
+  constructor(ctx: BtcCoreContext, params: BtcDepositAndDeployParams) {
+    super(ctx, params, BtcActionStatus.IDLE);
+
+    // Validate assetOut - DepositAndDeploy should only produce BTC.b
+    if (!isAssetOutSupported(params.assetOut)) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_ASSET,
+        `Asset ${params.assetOut} is not supported for deposit and deploy. ` +
+          `DepositAndDeploy produces BTC.b which is then deployed to a vault like Silo.`,
+      );
+    }
+
+    if (!isDestChainSupported(params.destChain)) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_CHAIN,
+        `Destination chain ${params.destChain} is not supported for deposit and deploy. ` +
+          `Supported chains: Avalanche, Avalanche Fuji`,
+      );
+    }
+
+    if (!isProtocolSupported(params.protocol)) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_PARAMETER,
+        `Protocol ${params.protocol} is not supported for deposit and deploy. ` +
+          `DepositAndDeploy with BTC.b only supports Silo protocol.`,
+      );
+    }
+
+    const sourceChain = params.sourceChain ?? Chain.BITCOIN_MAINNET;
+    if (!isRouteAvailable(sourceChain, ctx.env)) {
+      throw LombardError.routeNotFound({
+        assetOut: params.assetOut,
+        sourceChain,
+        destChain: params.destChain,
+        env: ctx.env,
+      });
+    }
+
+    const parsed = parseChainIdentifier(params.destChain);
+    if (typeof parsed !== 'number' || !isValidChain(parsed)) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_CHAIN,
+        `Unsupported EVM chain: ${params.destChain}`,
+      );
+    }
+
+    this.chainId = parsed as ChainId;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Abstract Method Implementations
+  // ─────────────────────────────────────────────────────────────────────────
+
+  protected getAddressSchema(): z.ZodType<string> {
+    return depositAndDeployConfig.addressSchema;
+  }
+
+  protected getStatusConfig(): StatusConfig<BtcActionStatus> {
+    return {
+      idle: BtcActionStatus.IDLE,
+      ready: BtcActionStatus.READY,
+      addressReady: BtcActionStatus.ADDRESS_READY,
+    };
+  }
+
+  protected getInitialSteps(): StepDefinition {
+    return {
+      created: StepStatus.IDLE,
+      verifying: StepStatus.IDLE,
+      wrapping: StepStatus.IDLE,
+      depositing: StepStatus.IDLE,
+    };
+  }
+
+  protected isAuthorized(): boolean {
+    return this.authState.authorized;
+  }
+
+  protected getChainId(): ChainId {
+    return this.chainId;
+  }
+
+  protected getDepositAddressParams() {
+    const recipient = this.ensureRecipient();
+    return {
+      address: recipient,
+      chainId: this.chainId,
+      signature: this.authState.signature!,
+      token: this.getExpectedToken(),
+      eip712Data: this.authState.typedData,
+      partnerId: this.ctx.partner.getPartnerId(),
+      referrerCode: this._referralCode,
+    };
+  }
+
+  /**
+   * Get expected token for this action (BTCb by default for DepositAndDeploy)
+   */
+  protected getExpectedToken(): string {
+    return assetIdToToken(this.params.assetOut, Token.BTCb);
+  }
+
+  protected getAuthRequiredMessage(): string {
+    return 'Deposit authorization required. Call authorizeDeposit() first.';
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Public Getters
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /** Get deposit and deploy fee (available after prepare()) */
+  get fee(): string | undefined {
+    return this.authState.fee;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Public Methods
+  // ─────────────────────────────────────────────────────────────────────────
+
+  async prepare(params: BtcDepositAndDeployPrepareParams): Promise<void> {
+    this.assertStatus(BtcActionStatus.IDLE, 'prepare');
+
+    return this.act(async () => {
+      const validated = this.validatePrepareParams(params);
+
+      this._amount = validated.amount;
+      this._recipient = validated.recipient;
+      this._referralCode = validated.referralCode;
+
+      // Get fee for deposit and deploy (uses config's getVaultKey for validation)
+      this.authState.fee = await depositAndDeployConfig.getDepositAndDeployFee(
+        this.ctx,
+        this.chainId,
+        getVaultKey(this.params.protocol),
+      );
+
+      this.updateStatus(BtcActionStatus.NEEDS_DEPLOY_AUTHORIZATION);
+      this.emitInitialProgress();
+    }, BtcActionStatus.NEEDS_DEPLOY_AUTHORIZATION);
+  }
+
+  async authorizeDeposit(): Promise<void> {
+    this.assertStatus(
+      [BtcActionStatus.NEEDS_DEPLOY_AUTHORIZATION, BtcActionStatus.READY],
+      'authorizeDeposit',
+    );
+
+    if (this.status === BtcActionStatus.READY) return;
+
+    const recipient = this.ensureRecipient();
+    const amount = this.ensureAmount();
+
+    return this.act(async () => {
+      const amountSats = toSatoshi(amount);
+
+      // For BTC → BTC.b deposit and deploy, use the output token (BTCb).
+      // Unlike LBTC which has a variable ratio with BTC, BTC.b is 1:1 with BTC
+      // so no ratio conversion is needed (amountStrategy: 'identity').
+      // Using assetIdToToken ensures we use the correct token for the permit.
+      const outputToken = assetIdToToken(this.params.assetOut, Token.BTCb);
+
+      const result = await depositAndDeployConfig.authorizeDepositAndDeploy(
+        this.ctx,
+        {
+          chainId: this.chainId,
+          recipient,
+          amount: amountSats.toString(),
+          vaultKey: getVaultKey(this.params.protocol),
+          token: outputToken,
+        },
+      );
+
+      this.authState.signature = result.signature;
+      this.authState.typedData = result.typedData;
+      this.authState.authorized = true;
+    }, BtcActionStatus.READY);
+  }
+
+  async generateDepositAddress(): Promise<string> {
+    this.assertStatus(BtcActionStatus.READY, 'generateDepositAddress');
+    this.ensureAuthorized();
+
+    if (this._depositAddress) {
+      return this._depositAddress;
+    }
+
+    return this.act(async () => {
+      const apiParams = this.getDepositAddressParams();
+      const depositAddress =
+        await this.ctx.api.generateDepositAddress(apiParams);
+
+      ensureNotSanctionedAddress(depositAddress);
+      this._depositAddress = depositAddress;
+
+      this.emitProgress({
+        status: BtcActionStatus.ADDRESS_READY,
+        steps: {
+          created: StepStatus.COMPLETE,
+          verifying: StepStatus.IDLE,
+          wrapping: StepStatus.IDLE,
+          depositing: StepStatus.IDLE,
+        },
+        metadata: { depositAddress },
+      });
+
+      return depositAddress;
+    }, BtcActionStatus.ADDRESS_READY);
+  }
+
+  async execute(): Promise<{ depositAddress: string; txHash?: string }> {
+    return this.act(async () => {
+      this.assertStatus(BtcActionStatus.ADDRESS_READY, 'execute');
+
+      if (!this._depositAddress) {
+        await this.generateDepositAddress();
+      }
+
+      const depositAddress = this.ensureDepositAddress();
+      const txHash = await this.trySendBitcoin(depositAddress);
+
+      return txHash ? { depositAddress, txHash } : { depositAddress };
+    });
+  }
+
+  // Custom monitorDeposit with different step names
+  async monitorDeposit(): Promise<MonitorProgress | undefined> {
+    const depositAddress = this._depositAddress;
+    const recipient = this._recipient;
+
+    if (!depositAddress || !recipient) {
+      throw LombardError.missingParameter('depositAddress or recipient');
+    }
+
+    const progress = await monitorDeposit({
+      network: this.bitcoinNetwork,
+      btcService: this.ctx.btc,
+      fetchDeposit: async () => {
+        const deposits = await this.ctx.api.getDeposits(recipient);
+        const ourDeposit = deposits.find(
+          deposit => deposit.depositAddress === depositAddress,
+        );
+
+        if (!ourDeposit) {
+          return undefined;
+        }
+
+        return {
+          blockHeight: ourDeposit.blockHeight,
+          isClaimed: ourDeposit.isClaimed,
+        };
+      },
+      onProgress: p => {
+        this.emitProgress({
+          status: this.status,
+          steps: {
+            created: StepStatus.COMPLETE,
+            verifying: p.hasEnoughConfirmations
+              ? StepStatus.COMPLETE
+              : StepStatus.PENDING,
+            wrapping: p.isClaimed ? StepStatus.COMPLETE : StepStatus.PENDING,
+            depositing: StepStatus.PENDING,
+          },
+          confirmations: p.confirmations,
+          requiredConfirmations: p.requiredConfirmations,
+          metadata: { isClaimed: p.isClaimed },
+        });
+      },
+      onComplete: () => {
+        this.emitCompleted();
+      },
+    });
+
+    return progress;
+  }
+}