@lombard.finance/sdk 3.7.4 → 4.0.0

package/src/chains/btc/actions/shared/BaseBtcAction.ts

@@ -0,0 +1,495 @@
+/**
+ * Base BTC Action Class
+ *
+ * Provides common functionality for all BTC actions:
+ * - State management (amount, recipient, depositAddress, referralCode)
+ * - Ensure methods for validation
+ * - Bitcoin network helpers
+ * - Deposit monitoring
+ * - Bitcoin send operations
+ * - Common validation and prepare patterns
+ *
+ * @module chains/btc/actions/shared/BaseBtcAction
+ */
+
+import { z } from 'zod';
+
+import {
+  ChainId,
+  SolanaChain,
+  StarknetChainId,
+  SuiChain,
+} from '../../../../common/chains';
+import { Chain, StepStatus } from '../../../../core';
+import { BaseAction } from '../../../../shared/actions';
+import type { BtcCoreContext } from '../../../../shared/context';
+import { LombardError, ValidationErrorCode } from '../../../../shared/errors';
+import type {
+  MonitorProgress,
+  NetworkMode,
+} from '../../../../shared/monitoring';
+import { monitorDeposit } from '../../../../shared/monitoring';
+import type { EventHandler } from '../../../../shared/monitoring/createEventEmitter';
+import {
+  btcStakeAmountSchema,
+  referralCodeSchema,
+  validatePrepareParams as zodValidate,
+} from '../../../../shared/validation';
+import { ensureNotSanctionedAddress } from '../../../../utils/ensureNotSanctionedAddress';
+import { toSatoshi } from '../../../../utils/satoshi';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Common authorization state for BTC actions
+ */
+export interface BtcAuthorizationState {
+  authorized: boolean;
+  signature?: string;
+  typedData?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Common params that all BTC actions share
+ */
+export interface BaseBtcParams {
+  sourceChain?: typeof Chain.BITCOIN_MAINNET | typeof Chain.BITCOIN_SIGNET;
+  destChain: Chain;
+}
+
+/**
+ * Common prepare params
+ */
+export interface BasePrepareParams {
+  amount: string;
+  recipient: string;
+  referralCode?: string;
+}
+
+/**
+ * Progress step definitions
+ */
+export type StepDefinition = Record<string, StepStatus>;
+
+/**
+ * Status configuration for template methods
+ */
+export interface StatusConfig<TStatus extends string> {
+  idle: TStatus;
+  ready: TStatus;
+  addressReady: TStatus;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Base Class
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Base class for BTC actions
+ *
+ * Provides template methods for common patterns:
+ * - prepare() with validation and resume
+ * - generateDepositAddress()
+ * - execute()
+ * - monitorDeposit()
+ *
+ * Subclasses implement abstract methods to customize behavior.
+ *
+ * @example
+ * ```typescript
+ * class BtcStake extends BaseBtcAction<StakeEventMap, BtcActionStatus, BtcStakeParams> {
+ *   protected getAddressSchema() { return evmAddressSchema; }
+ *   protected getStatusConfig() { return { idle: BtcActionStatus.IDLE, ... }; }
+ *   protected getInitialSteps() { return { created: StepStatus.IDLE, ... }; }
+ * }
+ * ```
+ */
+export abstract class BaseBtcAction<
+  TEventMap extends Record<string, EventHandler<unknown[]>>,
+  TStatus extends string,
+  TParams extends BaseBtcParams,
+> extends BaseAction<TEventMap, TStatus> {
+  // ─────────────────────────────────────────────────────────────────────────
+  // Common State
+  // ─────────────────────────────────────────────────────────────────────────
+
+  protected _amount?: string;
+  protected _recipient?: string;
+  protected _depositAddress?: string;
+  protected _referralCode?: string;
+  protected _chainId?: unknown;
+
+  constructor(
+    protected readonly ctx: BtcCoreContext,
+    protected readonly params: TParams,
+    initialStatus: TStatus,
+  ) {
+    super(initialStatus);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Abstract Methods - Subclasses Must Implement
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /** Get the address validation schema for this action */
+  protected abstract getAddressSchema(): z.ZodType<string>;
+
+  /** Get the status configuration for template methods */
+  protected abstract getStatusConfig(): StatusConfig<TStatus>;
+
+  /** Get the initial progress steps for this action */
+  protected abstract getInitialSteps(): StepDefinition;
+
+  /** Check if the action has been authorized */
+  protected abstract isAuthorized(): boolean;
+
+  /** Get the chain ID (after parsing in constructor) */
+  protected abstract getChainId():
+    | ChainId
+    | SuiChain
+    | SolanaChain
+    | StarknetChainId;
+
+  /**
+   * Get API params for generateDepositAddress
+   * Subclasses provide action-specific parameters
+   */
+  protected abstract getDepositAddressParams(): {
+    address: string;
+    chainId: ChainId | SuiChain | SolanaChain | StarknetChainId;
+    signature: string;
+    token: string;
+    eip712Data?: string;
+    signatureData?: string;
+    pubKey?: string;
+    partnerId?: string;
+    referrerCode?: string;
+  };
+
+  /**
+   * Get the expected destination token (LBTC, BTCb, etc.)
+   * Used for resuming from existing deposits before authorization is complete
+   */
+  protected abstract getExpectedToken(): string;
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Common Getters
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /** Amount of BTC to stake/deposit */
+  get amount(): string | undefined {
+    return this._amount;
+  }
+
+  /** Recipient address on destination chain */
+  get recipient(): string | undefined {
+    return this._recipient;
+  }
+
+  /** Generated Bitcoin deposit address */
+  get depositAddress(): string | undefined {
+    return this._depositAddress;
+  }
+
+  /** Referral code (optional) */
+  get referralCode(): string | undefined {
+    return this._referralCode;
+  }
+
+  /** Bitcoin network mode for monitoring */
+  protected get bitcoinNetwork(): NetworkMode {
+    const source = this.params.sourceChain;
+    return source === Chain.BITCOIN_MAINNET ? 'mainnet' : 'testnet';
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Common Validation
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the prepare schema (amount + recipient + referralCode)
+   * Uses abstract getAddressSchema() for chain-specific validation
+   */
+  protected get prepareSchema() {
+    return z.object({
+      amount: btcStakeAmountSchema,
+      recipient: this.getAddressSchema(),
+      referralCode: referralCodeSchema,
+    });
+  }
+
+  /**
+   * Validate prepare params using Zod
+   * Subclasses can override if they need custom validation
+   */
+  protected validatePrepareParams(
+    params: BasePrepareParams,
+  ): BasePrepareParams {
+    return zodValidate(this.prepareSchema, params, {
+      destChain: this.params.destChain,
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Ensure Methods (throw if missing)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  protected ensureRecipient(): string {
+    if (!this._recipient) {
+      throw LombardError.missingParameter('recipient');
+    }
+    return this._recipient;
+  }
+
+  protected ensureAmount(): string {
+    if (!this._amount) {
+      throw LombardError.missingParameter('amount');
+    }
+    return this._amount;
+  }
+
+  protected ensureDepositAddress(): string {
+    if (!this._depositAddress) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_PARAMETER,
+        'Deposit address not generated. Call generateDepositAddress() first.',
+      );
+    }
+    return this._depositAddress;
+  }
+
+  /**
+   * Get error message for missing authorization
+   * Subclasses can override to provide specific messages
+   */
+  protected getAuthRequiredMessage(): string {
+    return 'Authorization required. Complete the authorization step first.';
+  }
+
+  protected ensureAuthorized(): void {
+    if (!this.isAuthorized()) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_PARAMETER,
+        this.getAuthRequiredMessage(),
+      );
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Common Resume Logic
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Try to resume from an existing deposit address
+   *
+   * This method only stores the deposit address if found.
+   * It does NOT update the status - the caller must do that
+   * after performing any additional validation (e.g., fee authorization).
+   *
+   * @param recipient - The recipient address to check
+   * @returns true if a deposit address was found, false otherwise
+   */
+  protected async resumeFromExistingDeposit(
+    recipient: string,
+  ): Promise<boolean> {
+    try {
+      const depositAddress = await this.ctx.api.getDepositAddress({
+        address: recipient,
+        chainId: this.getChainId(),
+        token: this.getExpectedToken(),
+        partnerId: this.ctx.partner.getPartnerId(),
+      });
+
+      if (!depositAddress) {
+        return false;
+      }
+
+      this._depositAddress = depositAddress;
+      // NOTE: Status is NOT updated here - caller must set appropriate status
+      // after validating fee authorization (which may have expired)
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Common Generate Deposit Address
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Generate a Bitcoin deposit address
+   *
+   * Template method that:
+   * 1. Validates status and authorization
+   * 2. Calls API to generate address
+   * 3. Updates state and emits progress
+   *
+   * Subclasses must implement getDepositAddressParams() to provide API params.
+   */
+  protected async generateDepositAddressImpl(): Promise<string> {
+    const statusConfig = this.getStatusConfig();
+
+    this.assertStatus(statusConfig.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;
+
+      // Emit progress with address ready
+      const steps = this.getInitialSteps();
+      const addressReadySteps = Object.fromEntries(
+        Object.entries(steps).map(([key], index) => [
+          key,
+          index === 0 ? StepStatus.COMPLETE : StepStatus.IDLE,
+        ]),
+      );
+
+      this.emitProgress({
+        status: statusConfig.addressReady,
+        steps: addressReadySteps,
+        metadata: { depositAddress },
+      });
+
+      return depositAddress;
+    }, statusConfig.addressReady);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Common Execute Pattern
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Execute the action - generate address and optionally send BTC
+   *
+   * Template method that:
+   * 1. Ensures deposit address exists
+   * 2. Tries to send BTC if provider available
+   * 3. Returns result
+   */
+  protected async executeImpl(): Promise<{
+    depositAddress: string;
+    txHash?: string;
+  }> {
+    const statusConfig = this.getStatusConfig();
+
+    return this.act(async () => {
+      this.assertStatus(statusConfig.addressReady, 'execute');
+
+      if (!this._depositAddress) {
+        await this.generateDepositAddressImpl();
+      }
+
+      const depositAddress = this.ensureDepositAddress();
+      const txHash = await this.trySendBitcoin(depositAddress);
+
+      return txHash ? { depositAddress, txHash } : { depositAddress };
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Common Progress Emission
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Emit initial progress with action-specific steps
+   */
+  protected emitInitialProgress(): void {
+    this.emitProgress({
+      status: this.status,
+      steps: this.getInitialSteps(),
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Deposit Monitoring
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Monitor Bitcoin deposit progress
+   */
+  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: p.steps,
+          confirmations: p.confirmations,
+          requiredConfirmations: p.requiredConfirmations,
+          metadata: { isClaimed: p.isClaimed },
+        });
+      },
+      onComplete: () => {
+        this.emitCompleted();
+      },
+    });
+
+    return progress;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Bitcoin Send (Optional)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  protected async trySendBitcoin(
+    depositAddress: string,
+  ): Promise<string | undefined> {
+    const amount = this._amount;
+    if (!amount) return undefined;
+
+    try {
+      const btcProvider = await this.ctx.getProvider('bitcoin');
+      if (!btcProvider) return undefined;
+
+      const provider = btcProvider as {
+        sendBitcoin?: (address: string, amountSats: number) => Promise<string>;
+      };
+
+      if (provider.sendBitcoin) {
+        const amountSats = toSatoshi(amount).toNumber();
+        return provider.sendBitcoin(depositAddress, amountSats);
+      }
+    } catch {
+      // Fall back to manual send
+    }
+
+    return undefined;
+  }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Shared BTC Action Utilities
+ *
+ * Common utilities and base classes for BTC actions.
+ *
+ * @module chains/btc/actions/shared
+ */
+
+export type {
+  BaseBtcParams,
+  BtcAuthorizationState,
+  StatusConfig,
+  StepDefinition,
+} from './BaseBtcAction';
+export { BaseBtcAction } from './BaseBtcAction';
+export { assetIdToToken } from './tokenUtils';
+export type {
+  ValidatableConfig,
+  ValidatableParams,
+  ValidationContext,
+} from './validation';
+export {
+  isAssetSupported,
+  isDestChainSupported,
+  isRouteAvailable,
+  validateBtcActionParams,
+  validateProtocol,
+} from './validation';

package/src/chains/btc/actions/shared/tokenUtils.ts

@@ -0,0 +1,68 @@
+/**
+ * Token Utilities for BTC Actions
+ *
+ * Shared utilities for mapping asset IDs to tokens.
+ *
+ * ## Token Parameter Pattern for StakeAndBake/DepositAndDeploy
+ *
+ * The `token` parameter in authorization functions determines which DEFI_REGISTRY
+ * entry is used, which affects the `amountStrategy`:
+ *
+ * | Action              | Flow               | Token Param   | Strategy    | Reason                     |
+ * |---------------------|-------------------|---------------|-------------|----------------------------|
+ * | BtcStakeAndDeploy   | BTC → LBTC → Vault | AssetId.BTC  | btcToLbtc   | Apply BTC/LBTC ratio       |
+ * | BtcDepositAndDeploy | BTC → BTCb → Vault | Token.BTCb   | identity    | 1:1 ratio, no conversion   |
+ *
+ * **Key Insight:**
+ * - LBTC has a variable exchange rate with BTC (~1.00265 BTC = 1 LBTC)
+ * - BTC.b is 1:1 with BTC (wrapped representation)
+ *
+ * For LBTC outputs, use the SOURCE asset (`'BTC'`) to trigger ratio conversion.
+ * For BTC.b outputs, use the OUTPUT asset (`Token.BTCb`) since no conversion needed.
+ *
+ * @see DEFI_REGISTRY in defi/defi-registry.ts
+ * @see signStakeAndBake for how amountStrategy is applied
+ *
+ * @module chains/btc/actions/shared/tokenUtils
+ */
+
+import { AssetId } from '../../../../core/assets';
+import { Token } from '../../../../tokens/token-addresses';
+
+/**
+ * Maps an AssetId to its corresponding Token value for API calls.
+ *
+ * **Note:** This function handles LBTC and BTCb. For BTC → LBTC flows that need
+ * ratio conversion, use `AssetId.BTC` directly instead of this function.
+ *
+ * @param assetId - The asset ID to convert
+ * @param defaultToken - The default token if assetId doesn't match known types (defaults to LBTC)
+ * @returns The corresponding Token value
+ *
+ * @example
+ * // For BTC.b outputs (1:1 with BTC)
+ * assetIdToToken(AssetId.BTCb) // returns Token.BTCb
+ *
+ * @example
+ * // For LBTC outputs from LBTC source (no ratio conversion)
+ * assetIdToToken(AssetId.LBTC) // returns Token.LBTC
+ *
+ * @example
+ * // For BTC → LBTC (needs ratio conversion)
+ * // DON'T use assetIdToToken, use AssetId.BTC directly
+ * token: AssetId.BTC // triggers btcToLbtc strategy
+ */
+export function assetIdToToken(
+  assetId: AssetId,
+  defaultToken: Token = Token.LBTC,
+): Token {
+  switch (assetId) {
+    case AssetId.LBTC:
+      return Token.LBTC;
+    case AssetId.BTCb:
+      return Token.BTCb;
+    default:
+      return defaultToken;
+  }
+}
+