@lombard.finance/sdk 3.7.4 → 4.0.0

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

@@ -0,0 +1,388 @@
+/**
+ * BTC Deposit Action
+ *
+ * Handles BTC deposit operations for custody without staking.
+ * Currently supports EVM destination chains.
+ *
+ * Fee authorization is ONLY required for Ethereum mainnet.
+ * Other chains use address confirmation signing.
+ *
+ * @module chains/btc/actions/deposit/BtcDeposit
+ */
+
+import type { z } from 'zod';
+
+import type { ChainId } from '../../../../common/chains';
+import { isValidChain } from '../../../../common/chains';
+import { parseChainIdentifier, StepStatus } from '../../../../core';
+import type { BtcCoreContext } from '../../../../shared/context';
+import { LombardError, ValidationErrorCode } from '../../../../shared/errors';
+import type { DepositEventMap } from '../../../../shared/events';
+import type { MonitorProgress } from '../../../../shared/monitoring';
+import { Token } from '../../../../tokens/token-addresses';
+import {
+  assetIdToToken,
+  BaseBtcAction,
+  type StatusConfig,
+  type StepDefinition,
+} from '../shared';
+import {
+  depositConfig,
+  type DepositFeeAuthConfig,
+  isAssetOutSupported,
+  isDestChainSupported,
+  isRouteAvailable,
+} from './config';
+import {
+  BtcActionStatus,
+  type BtcDeposit as IBtcDeposit,
+  type BtcDepositParams,
+  type BtcDepositPrepareParams,
+} from './types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface AuthorizationState {
+  signature?: string;
+  typedData?: string;
+  authorized: boolean;
+  /** Minting fee in BTC (e.g., "0.00000032") */
+  mintingFee?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BtcDeposit Implementation
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * BTC Deposit Action
+ *
+ * Handles BTC deposit to custody with BTC.b minting on destination chain.
+ * This is for custody without staking. For staking (BTC → LBTC), use BtcStake.
+ *
+ * @example
+ * ```typescript
+ * const deposit = new BtcDeposit(ctx, {
+ *   assetOut: AssetId.BTCb,
+ *   destChain: Chain.AVALANCHE,
+ * });
+ *
+ * await deposit.prepare({ amount: '0.1', recipient: '0x...' });
+ * await deposit.authorizeFee();
+ * const address = await deposit.generateDepositAddress();
+ * ```
+ */
+export class BtcDeposit
+  extends BaseBtcAction<DepositEventMap, BtcActionStatus, BtcDepositParams>
+  implements IBtcDeposit
+{
+  private readonly chainId: ChainId;
+  private readonly authState: AuthorizationState = { authorized: false };
+
+  /** Fee auth config - null if not required for this destination */
+  private feeAuthConfig: DepositFeeAuthConfig | null = null;
+
+  constructor(ctx: BtcCoreContext, params: BtcDepositParams) {
+    super(ctx, params, BtcActionStatus.IDLE);
+
+    // Validate assetOut - BTC Deposit should only produce BTC.b
+    if (!isAssetOutSupported(params.assetOut)) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_ASSET,
+        `Asset ${params.assetOut} is not supported for BTC deposits. ` +
+          `BTC Deposit produces BTC.b. For LBTC, use BtcStake instead.`,
+      );
+    }
+
+    if (!isDestChainSupported(params.destChain)) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_CHAIN,
+        `Destination chain ${params.destChain} is not supported for BTC deposits. ` +
+          `BTC.b is currently available on Avalanche and Katana.`,
+      );
+    }
+
+    if (!isRouteAvailable(params.sourceChain, ctx.env)) {
+      throw LombardError.routeNotFound({
+        assetOut: params.assetOut,
+        sourceChain: params.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 depositConfig.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,
+      issuing: StepStatus.IDLE,
+    };
+  }
+
+  protected isAuthorized(): boolean {
+    return this.authState.authorized;
+  }
+
+  protected getChainId(): ChainId {
+    return this.chainId;
+  }
+
+  /**
+   * Get the minting fee for this deposit (in BTC)
+   * Available after prepare() when fee authorization is required
+   */
+  get mintingFee(): string | undefined {
+    return this.authState.mintingFee;
+  }
+
+  protected getDepositAddressParams() {
+    const recipient = this.ensureRecipient();
+    return {
+      address: recipient,
+      chainId: this.chainId,
+      signature: this.authState.signature!, // Must be set before calling
+      token: this.getExpectedToken(),
+      eip712Data: this.authState.typedData,
+      partnerId: this.ctx.partner.getPartnerId(),
+      referrerCode: this._referralCode,
+    };
+  }
+
+  /**
+   * Override to ensure we have a signature before generating deposit address.
+   * 
+   * When fee auth exists on server but signature isn't available locally,
+   * we fall back to signing the destination address.
+   */
+  async generateDepositAddress(): Promise<string> {
+    // If signature isn't available locally, sign the destination address as fallback
+    if (!this.authState.signature) {
+      const result = await depositConfig.signDestination(
+        this.ctx,
+        this.ensureRecipient(),
+        this.chainId,
+      );
+      this.authState.signature = result.signature;
+      this.authState.typedData = result.typedData;
+    }
+
+    return this.generateDepositAddressImpl();
+  }
+
+  /**
+   * Get expected token for this action (BTCb by default for BTC Deposit)
+   */
+  protected getExpectedToken(): string {
+    return assetIdToToken(this.params.assetOut, Token.BTCb);
+  }
+
+  protected getAuthRequiredMessage(): string {
+    return this.feeAuthConfig
+      ? 'Fee authorization required. Call authorizeFee() first.'
+      : 'Address confirmation required. Call confirmAddress() first.';
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Public Methods
+  // ─────────────────────────────────────────────────────────────────────────
+
+  async prepare(params: BtcDepositPrepareParams): 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 auth config for this destination chain (needed for both resume and new flow)
+      this.feeAuthConfig = depositConfig.getFeeAuthConfig(
+        this.params.destChain,
+      );
+
+      // Check for existing deposit address (resume flow)
+      const hasExistingDeposit = await this.resumeFromExistingDeposit(
+        validated.recipient,
+      );
+
+      if (hasExistingDeposit) {
+        // We have a deposit address, but we still need to validate fee authorization
+        // The deposit address might have been created when fee auth was valid,
+        // but the fee auth could have expired since then
+        if (this.feeAuthConfig) {
+          const stored = await this.feeAuthConfig.restoreFeeSignature(
+            this.ctx,
+            this.chainId,
+            validated.recipient,
+          );
+
+          // Check hasSignature flag - the actual signature string may not be returned by API
+          if (!stored?.hasSignature) {
+            // Fee auth is required but expired/missing - need re-authorization
+            // Fetch the minting fee for display purposes
+            this.authState.mintingFee = await this.feeAuthConfig.getMintingFee(
+              this.ctx,
+              this.chainId,
+            );
+            this.updateStatus(BtcActionStatus.NEEDS_FEE_AUTHORIZATION);
+            this.emitInitialProgress();
+            return;
+          }
+
+          // Fee auth is still valid on server - store signature if available
+          if (stored.signature) {
+            this.authState.signature = stored.signature;
+            this.authState.typedData = stored.typedData;
+          }
+          this.authState.authorized = true;
+        }
+
+        // Deposit address exists and fee auth is valid (or not required)
+        // Now we can safely set the status to ADDRESS_READY
+        this.updateStatus(BtcActionStatus.ADDRESS_READY);
+        this.emitInitialProgress();
+        return;
+      }
+
+      // No existing deposit - proceed with normal flow
+      if (this.feeAuthConfig) {
+        // Fee authorization required (Ethereum mainnet only)
+        const stored = await this.feeAuthConfig.restoreFeeSignature(
+          this.ctx,
+          this.chainId,
+          validated.recipient,
+        );
+
+        // Check hasSignature flag - the actual signature string may not be returned by API
+        if (stored?.hasSignature) {
+          // Fee auth already exists on server - store signature if available
+          if (stored.signature) {
+            this.authState.signature = stored.signature;
+            this.authState.typedData = stored.typedData;
+          }
+          this.authState.authorized = true;
+          this.updateStatus(BtcActionStatus.READY);
+          this.emitInitialProgress();
+          return;
+        }
+
+        // Fetch the minting fee for display purposes
+        this.authState.mintingFee = await this.feeAuthConfig.getMintingFee(
+          this.ctx,
+          this.chainId,
+        );
+        this.updateStatus(BtcActionStatus.NEEDS_FEE_AUTHORIZATION);
+      } else {
+        this.updateStatus(BtcActionStatus.NEEDS_ADDRESS_CONFIRMATION);
+      }
+
+      this.emitInitialProgress();
+    });
+  }
+
+  async authorizeFee(): Promise<void> {
+    this.assertStatus(
+      [BtcActionStatus.NEEDS_FEE_AUTHORIZATION, BtcActionStatus.READY],
+      'authorizeFee',
+    );
+
+    if (this.status === BtcActionStatus.READY) return;
+
+    if (!this.feeAuthConfig) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_PARAMETER,
+        'Fee authorization is not required for this destination chain. Use confirmAddress() instead.',
+      );
+    }
+
+    const recipient = this.ensureRecipient();
+
+    // Use the minting fee that was fetched during prepare(), not the deposit amount
+    if (!this.authState.mintingFee) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_STATE,
+        'Minting fee not available. Call prepare() first.',
+      );
+    }
+
+    return this.act(async () => {
+      const result = await this.feeAuthConfig!.authorizeFee(this.ctx, {
+        chainId: this.chainId,
+        recipient,
+        fee: this.authState.mintingFee!,
+      });
+
+      this.authState.signature = result.signature;
+      this.authState.typedData = result.typedData;
+      this.authState.authorized = true;
+    }, BtcActionStatus.READY);
+  }
+
+  async confirmAddress(): Promise<void> {
+    this.assertStatus(
+      [BtcActionStatus.NEEDS_ADDRESS_CONFIRMATION, BtcActionStatus.READY],
+      'confirmAddress',
+    );
+
+    if (this.status === BtcActionStatus.READY) return;
+
+    if (this.feeAuthConfig) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_PARAMETER,
+        'This destination chain requires fee authorization. Use authorizeFee() instead.',
+      );
+    }
+
+    const recipient = this.ensureRecipient();
+
+    return this.act(async () => {
+      const result = await depositConfig.signDestination(
+        this.ctx,
+        recipient,
+        this.chainId,
+      );
+
+      this.authState.signature = result.signature;
+      this.authState.typedData = result.typedData;
+      this.authState.authorized = true;
+    }, BtcActionStatus.READY);
+  }
+
+  async execute(): Promise<{ depositAddress: string; txHash?: string }> {
+    return this.executeImpl();
+  }
+
+  async monitorDeposit(): Promise<MonitorProgress | undefined> {
+    return super.monitorDeposit();
+  }
+}

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

@@ -0,0 +1,197 @@
+/**
+ * EVM Chain Configuration for BTC Deposit
+ *
+ * BTC Deposit: BTC → BTC.b (wrapped BTC without yield)
+ * For staking (BTC → LBTC), use BtcStake instead.
+ *
+ * Supported chains are derived from ASSET_CATALOG - single source of truth.
+ *
+ * Fee authorization is ONLY required for Ethereum mainnet.
+ * Other chains use address confirmation signing.
+ *
+ * @module chains/btc/actions/deposit/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,
+    isEvmChain,
+} 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 { toSatoshi } from '../../../../../utils/satoshi';
+import type { DepositChainConfig, DepositFeeAuthConfig } from './types';
+
+/**
+ * Chains that require fee authorization (unsubsidized chains).
+ * 
+ * Ethereum mainnet and Sepolia require EIP-712 network fee signing.
+ * Other chains are subsidized by Lombard.
+ */
+const UNSUBSIDIZED_CHAINS = [Chain.ETHEREUM, Chain.SEPOLIA] as const;
+
+/**
+ * Fee authorization config for unsubsidized chains
+ *
+ * BTC Deposit produces BTC.b, so we must use Token.BTCb for fee signatures.
+ * This ensures the backend can distinguish between LBTC and BTC.b signatures.
+ */
+const feeAuthConfig: DepositFeeAuthConfig = {
+  async getMintingFee(ctx, chainId) {
+    const evm = ctx.capabilities.require('evm') as EvmService;
+    // Fetch BTC.b minting fee (not LBTC!)
+    return evm.getMintingFee(chainId as ChainId, Token.BTCb);
+  },
+
+  async restoreFeeSignature(ctx, chainId, address) {
+    // Get BTC.b token address for this chain to distinguish from LBTC signatures
+    const tokenInfo = await getTokenContractInfo(
+      Token.BTCb,
+      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 BTC.b token info for this chain
+    const tokenInfo = await getTokenContractInfo(
+      Token.BTCb,
+      chainId as ChainId,
+      ctx.env,
+    );
+
+    // Sign the network fee with BTC.b token (not LBTC!)
+    const result = await evm.signNetworkFee({
+      fee: feeInSatoshis,
+      account: recipient,
+      chainId: chainId as ChainId,
+      provider: provider as EIP1193Provider,
+      token: Token.BTCb,
+    });
+
+    // Store the signature with token address to distinguish from LBTC signatures
+    await ctx.api.storeFeeSignature({
+      address: recipient,
+      signature: result.signature,
+      typedData: result.typedData,
+      tokenAddress: tokenInfo.address,
+    });
+
+    return {
+      signature: result.signature,
+      typedData: result.typedData,
+    };
+  },
+};
+
+/**
+ * EVM deposit configuration
+ *
+ * BTC Deposit produces BTC.b (wrapped BTC without yield).
+ * Supported chains are derived from ASSET_CATALOG[AssetId.BTCb].deployments.
+ */
+export const evmDepositConfig: DepositChainConfig = {
+  chainType: 'evm',
+
+  routes: [
+    {
+      sourceChains: [Chain.BITCOIN_MAINNET],
+      envs: [Env.prod],
+    },
+    {
+      sourceChains: [Chain.BITCOIN_SIGNET],
+      envs: [Env.stage, Env.dev, Env.testnet, Env.ibc],
+    },
+  ],
+
+  // Derived from ASSET_CATALOG - all chains where BTC.b is deployed
+  destChains: getAllAssetChains(AssetId.BTCb).filter(chain =>
+    isEvmChain(chain),
+  ),
+
+  // BTC Deposit only produces BTC.b
+  supportedAssetsOut: [AssetId.BTCb],
+
+  addressSchema: evmAddressSchema,
+
+  /**
+   * Get fee auth config - unsubsidized chains require fee authorization
+   * Other chains use address confirmation signing
+   */
+  getFeeAuthConfig(destChain: Chain): DepositFeeAuthConfig | null {
+    return (UNSUBSIDIZED_CHAINS as readonly Chain[]).includes(destChain)
+      ? feeAuthConfig
+      : null;
+  },
+
+  /**
+   * Sign destination address confirmation
+   * Used for non-fee-auth chains (e.g., Avalanche, Katana)
+   */
+  async signDestination(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);
+
+    const result = await evm.signLbtcDestination({
+      address: recipient,
+      chainId: chainId as ChainId,
+      provider: provider as EIP1193Provider,
+    });
+
+    return {
+      signature: result.signature,
+    };
+  },
+};

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

@@ -0,0 +1,53 @@
+/**
+ * BTC Deposit Chain Configuration Registry
+ *
+ * BTC Deposit: BTC → BTC.b (wrapped BTC without yield)
+ *
+ * @module chains/btc/actions/deposit/config
+ */
+
+import type { AssetId, Chain, Env } from '../../../../../core';
+import { evmDepositConfig } from './evm';
+
+export type {
+  DepositChainConfig,
+  DepositFeeAuthConfig,
+  DepositRouteDefinition,
+  FeeAuthResult,
+  SignatureResult,
+  StoredFeeSignature,
+} from './types';
+
+/**
+ * All deposit configs (currently only EVM)
+ */
+export const depositConfig = evmDepositConfig;
+
+/**
+ * Check if destination chain is supported
+ */
+export function isDestChainSupported(chain: Chain): boolean {
+  return depositConfig.destChains.includes(chain);
+}
+
+/**
+ * Check if assetOut is supported for BTC Deposit
+ * BTC Deposit should only produce BTC.b
+ */
+export function isAssetOutSupported(assetOut: AssetId): boolean {
+  return depositConfig.supportedAssetsOut.includes(assetOut);
+}
+
+/**
+ * Check if route is available for given source chain and environment
+ */
+export function isRouteAvailable(
+  sourceChain: Chain | undefined,
+  env: Env,
+): boolean {
+  if (!sourceChain) return true;
+  return depositConfig.routes.some(
+    route =>
+      route.sourceChains.includes(sourceChain) && route.envs.includes(env),
+  );
+}