@lombard.finance/sdk 4.0.0 → 4.1.2

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

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

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

@@ -1,180 +0,0 @@
-/**
- * Shared Validation Utilities for BTC Actions
- *
- * Provides common validation logic used across all BTC actions.
- * Reduces code duplication and ensures consistent error handling.
- *
- * @module chains/btc/actions/shared/validation
- */
-
-import type { AssetId, Chain, Env } from '../../../../core';
-import { LombardError, ValidationErrorCode } from '../../../../shared/errors';
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Types
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Common config interface for validation
- * All BTC action configs should implement these properties
- */
-export interface ValidatableConfig {
-  destChains: Chain[];
-  supportedAssetsOut: AssetId[];
-  routes: Array<{
-    sourceChains: Chain[];
-    envs: Env[];
-  }>;
-}
-
-/**
- * Common params interface for validation
- */
-export interface ValidatableParams {
-  assetOut: AssetId;
-  destChain: Chain;
-  sourceChain?: Chain;
-}
-
-/**
- * Validation context
- */
-export interface ValidationContext {
-  env: Env;
-  actionName: string;
-  expectedAssets: AssetId[];
-  alternativeAction?: string;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Validation Functions
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Check if an asset is in the supported list
- */
-export function isAssetSupported(
-  supportedAssets: AssetId[],
-  assetOut: AssetId,
-): boolean {
-  return supportedAssets.includes(assetOut);
-}
-
-/**
- * Check if a destination chain is in the supported list
- */
-export function isDestChainSupported(
-  supportedChains: Chain[],
-  destChain: Chain,
-): boolean {
-  return supportedChains.includes(destChain);
-}
-
-/**
- * Check if a route is available for the given source chain and environment
- */
-export function isRouteAvailable(
-  routes: ValidatableConfig['routes'],
-  sourceChain: Chain | undefined,
-  env: Env,
-): boolean {
-  if (!sourceChain) return true; // No source chain specified, allow all
-
-  return routes.some(
-    route =>
-      route.sourceChains.includes(sourceChain) && route.envs.includes(env),
-  );
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Combined Validation
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Validate common BTC action parameters
- *
- * Performs all standard validations in one call:
- * - Asset output validation
- * - Destination chain validation
- * - Route availability validation
- *
- * Throws descriptive errors if validation fails.
- *
- * @param config - Action configuration with supported chains/assets
- * @param params - Action parameters to validate
- * @param context - Validation context (env, action name, etc.)
- *
- * @throws LombardError with appropriate code and message
- *
- * @example
- * ```typescript
- * validateBtcActionParams(
- *   stakeConfig,
- *   { assetOut: AssetId.LBTC, destChain: Chain.ETHEREUM },
- *   {
- *     env: 'prod',
- *     actionName: 'BTC Stake',
- *     expectedAssets: [AssetId.LBTC],
- *     alternativeAction: 'BtcDeposit',
- *   }
- * );
- * ```
- */
-export function validateBtcActionParams(
-  config: ValidatableConfig,
-  params: ValidatableParams,
-  context: ValidationContext,
-): void {
-  // 1. Validate asset output
-  if (!isAssetSupported(config.supportedAssetsOut, params.assetOut)) {
-    const supported = config.supportedAssetsOut.join(', ');
-    const alternative = context.alternativeAction
-      ? ` Use ${context.alternativeAction} instead.`
-      : '';
-
-    throw new LombardError(
-      ValidationErrorCode.INVALID_ASSET,
-      `Asset ${params.assetOut} is not supported for ${context.actionName}. ` +
-        `Supported: ${supported}.${alternative}`,
-    );
-  }
-
-  // 2. Validate destination chain
-  if (!isDestChainSupported(config.destChains, params.destChain)) {
-    throw new LombardError(
-      ValidationErrorCode.INVALID_CHAIN,
-      `Destination chain ${params.destChain} is not supported for ${context.actionName}`,
-    );
-  }
-
-  // 3. Validate route availability
-  if (!isRouteAvailable(config.routes, params.sourceChain, context.env)) {
-    throw LombardError.routeNotFound({
-      assetOut: params.assetOut,
-      sourceChain: params.sourceChain,
-      destChain: params.destChain,
-      env: context.env,
-    });
-  }
-}
-
-/**
- * Validate protocol is supported (for deploy actions)
- *
- * @param supportedProtocols - List of supported protocols
- * @param protocol - Protocol to validate
- * @param actionName - Name of action for error message
- */
-export function validateProtocol(
-  supportedProtocols: string[],
-  protocol: string,
-  actionName: string,
-): void {
-  if (!supportedProtocols.includes(protocol)) {
-    throw new LombardError(
-      ValidationErrorCode.INVALID_PARAMETER,
-      `Protocol ${protocol} is not supported for ${actionName}. ` +
-        `Supported: ${supportedProtocols.join(', ')}`,
-    );
-  }
-}

package/src/chains/btc/actions/stake/BtcStake.ts

@@ -1,433 +0,0 @@
-/**
- * BTC Stake Action
- *
- * A configuration-driven action that handles BTC → LBTC staking
- * to any supported destination chain. Chain-specific logic is delegated
- * to ChainConfig objects in the config/ folder.
- *
- * @module chains/btc/actions/stake/BtcStake
- */
-
-import type { z } from 'zod';
-
-import type {
-    ChainId,
-    SolanaChain,
-    StarknetChainId,
-    SuiChain,
-} from '../../../../common/chains';
-import {
-    getChainType,
-    parseChainIdentifier,
-    StepStatus,
-} from '../../../../core';
-import { BtcActionStatus } from '../../../../shared/constants/statusConstants';
-import type { BtcCoreContext } from '../../../../shared/context';
-import { LombardError, ValidationErrorCode } from '../../../../shared/errors';
-import type { StakeEventMap } from '../../../../shared/events';
-import type { MonitorProgress } from '../../../../shared/monitoring';
-import { Token } from '../../../../tokens/token-addresses';
-import { ensureNotSanctionedAddress } from '../../../../utils/ensureNotSanctionedAddress';
-import {
-    assetIdToToken,
-    BaseBtcAction,
-    type StatusConfig,
-    type StepDefinition,
-} from '../shared';
-import {
-    type ChainConfig,
-    type FeeAuthConfig,
-    getChainConfig,
-    isAssetOutSupported,
-    isDestChainSupported,
-    isRouteAvailable,
-    type SignatureResult,
-} from './config';
-import type { BtcStake as IBtcStake,BtcStakeParams } from './types';
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Types
-// ═══════════════════════════════════════════════════════════════════════════
-
-type AnyChainId = ChainId | SolanaChain | SuiChain | StarknetChainId;
-
-interface AuthorizationState {
-  mintingFee?: string;
-  networkFee?: {
-    signature: string;
-    typedData?: string;
-  };
-  destinationSignature?: SignatureResult;
-  authorized: boolean;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// BtcStake Implementation
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * BTC Stake Action
- *
- * Handles BTC → LBTC staking to any supported destination chain.
- * Uses configuration-driven design for chain-specific logic.
- *
- * @example
- * ```typescript
- * const stake = new BtcStake(ctx, {
- *   assetOut: AssetId.LBTC,
- *   destChain: Chain.ETHEREUM,
- * });
- *
- * await stake.prepare({ amount: '0.1', recipient: '0x...' });
- * await stake.authorize();
- * const address = await stake.generateDepositAddress();
- * ```
- */
-export class BtcStake
-  extends BaseBtcAction<StakeEventMap, BtcActionStatus, BtcStakeParams>
-  implements IBtcStake
-{
-  private readonly config: ChainConfig;
-  private readonly chainId: AnyChainId;
-  private readonly authState: AuthorizationState = { authorized: false };
-
-  /** Fee auth config - null if not required for this destination */
-  private feeAuthConfig: FeeAuthConfig | null = null;
-
-  constructor(ctx: BtcCoreContext, params: BtcStakeParams) {
-    super(ctx, params, BtcActionStatus.IDLE);
-
-    const chainType = getChainType(params.destChain);
-    const config = getChainConfig(chainType);
-
-    if (!config) {
-      throw new LombardError(
-        ValidationErrorCode.INVALID_CHAIN,
-        `Unsupported destination chain type: ${chainType} (${params.destChain})`,
-      );
-    }
-
-    // Validate assetOut - BTC Stake should only produce LBTC
-    if (!isAssetOutSupported(config, params.assetOut)) {
-      throw new LombardError(
-        ValidationErrorCode.INVALID_ASSET,
-        `Asset ${params.assetOut} is not supported for BTC staking. ` +
-          `BTC Stake produces LBTC. For BTC.b, use BtcDeposit instead.`,
-      );
-    }
-
-    if (!isDestChainSupported(config, params.destChain)) {
-      throw new LombardError(
-        ValidationErrorCode.INVALID_CHAIN,
-        `Destination chain ${params.destChain} is not supported for ${chainType}`,
-      );
-    }
-
-    if (!isRouteAvailable(config, params.sourceChain, ctx.env)) {
-      throw LombardError.routeNotFound({
-        assetOut: params.assetOut,
-        sourceChain: params.sourceChain,
-        destChain: params.destChain,
-        env: ctx.env,
-      });
-    }
-
-    this.config = config;
-    this.chainId = parseChainIdentifier(params.destChain);
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────
-  // Abstract Method Implementations
-  // ─────────────────────────────────────────────────────────────────────────
-
-  protected getAddressSchema(): z.ZodType<string> {
-    return this.config.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(): AnyChainId {
-    return this.chainId;
-  }
-
-  protected getDepositAddressParams() {
-    const recipient = this.ensureRecipient();
-    const signature = this.getActiveSignature();
-
-    if (!signature) {
-      throw new LombardError(
-        ValidationErrorCode.INVALID_PARAMETER,
-        'Missing signature. Complete authorization first.',
-      );
-    }
-
-    return {
-      address: signature.paddedAddress ?? recipient,
-      chainId: this.chainId,
-      signature: signature.signature,
-      token: this.getExpectedToken(),
-      eip712Data: this.authState.networkFee?.typedData,
-      pubKey: signature.pubKey,
-      partnerId: this.ctx.partner.getPartnerId(),
-      referrerCode: this._referralCode,
-    };
-  }
-
-  /**
-   * Get expected token for this action (LBTC by default for BTC Stake)
-   */
-  protected getExpectedToken(): string {
-    return assetIdToToken(this.params.assetOut, Token.LBTC);
-  }
-
-  protected getAuthRequiredMessage(): string {
-    return 'Authorization required. Call authorize() first.';
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────
-  // Public Getters
-  // ─────────────────────────────────────────────────────────────────────────
-
-  /** Get minting fee (available after prepare() for fee-auth chains) */
-  get mintingFee(): string | undefined {
-    return this.authState.mintingFee;
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────
-  // Public Methods
-  // ─────────────────────────────────────────────────────────────────────────
-
-  async prepare(params: {
-    amount: string;
-    recipient: string;
-    referralCode?: string;
-  }): 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 = this.config.getFeeAuthConfig(this.params.destChain);
-
-      // Check for existing deposit (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
-            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.networkFee = {
-              signature: stored.signature,
-              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 - try to restore stored signature first
-        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.networkFee = {
-              signature: stored.signature,
-              typedData: stored.typedData,
-            };
-          }
-          this.authState.authorized = true;
-          this.updateStatus(BtcActionStatus.READY);
-          this.emitInitialProgress();
-          return;
-        }
-
-        // Get minting fee for display
-        this.authState.mintingFee = await this.feeAuthConfig.getMintingFee(
-          this.ctx,
-          this.chainId,
-        );
-        this.updateStatus(BtcActionStatus.NEEDS_FEE_AUTHORIZATION);
-      } else {
-        // No fee auth required - go to address confirmation
-        this.updateStatus(BtcActionStatus.NEEDS_ADDRESS_CONFIRMATION);
-      }
-
-      this.emitInitialProgress();
-    });
-  }
-
-  async authorize(): Promise<void> {
-    this.assertStatus(
-      [
-        BtcActionStatus.NEEDS_FEE_AUTHORIZATION,
-        BtcActionStatus.NEEDS_ADDRESS_CONFIRMATION,
-        BtcActionStatus.READY,
-      ],
-      'authorize',
-    );
-
-    if (this.status === BtcActionStatus.READY) return;
-
-    const recipient = this.ensureRecipient();
-    const needsFeeAuth = this.feeAuthConfig !== null;
-
-    return this.act(async () => {
-      if (needsFeeAuth) {
-        // Fee authorization flow
-        const fee = this.ensureMintingFee();
-        const result = await this.feeAuthConfig!.authorizeFee(this.ctx, {
-          chainId: this.chainId,
-          recipient,
-          fee,
-        });
-        this.authState.networkFee = {
-          signature: result.signature,
-          typedData: result.typedData,
-        };
-      } else {
-        // Destination signature flow
-        this.authState.destinationSignature = await this.config.getSignature(
-          this.ctx,
-          recipient,
-          this.chainId,
-        );
-      }
-
-      this.authState.authorized = true;
-    }, BtcActionStatus.READY);
-  }
-
-  async generateDepositAddress(): Promise<string> {
-    this.assertStatus(BtcActionStatus.READY, 'generateDepositAddress');
-    this.ensureAuthorized();
-
-    if (this._depositAddress) {
-      return this._depositAddress;
-    }
-
-    // If no signature is available locally (fee auth exists on server but wasn't returned),
-    // fall back to signing the destination address
-    if (!this.getActiveSignature()) {
-      const result = await this.config.getSignature(
-        this.ctx,
-        this.ensureRecipient(),
-        this.chainId,
-      );
-      this.authState.destinationSignature = result;
-    }
-
-    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,
-          issuing: StepStatus.IDLE,
-        },
-        metadata: { depositAddress },
-      });
-
-      return depositAddress;
-    }, BtcActionStatus.ADDRESS_READY);
-  }
-
-  async execute(): Promise<{ depositAddress: string; txHash?: string }> {
-    return this.executeImpl();
-  }
-
-  async monitorDeposit(): Promise<MonitorProgress | undefined> {
-    return super.monitorDeposit();
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────
-  // Private: Ensure Methods
-  // ─────────────────────────────────────────────────────────────────────────
-
-  private ensureMintingFee(): string {
-    if (!this.authState.mintingFee) {
-      throw new LombardError(
-        ValidationErrorCode.INVALID_PARAMETER,
-        'Minting fee not fetched. Call prepare() first.',
-      );
-    }
-    return this.authState.mintingFee;
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────
-  // Private: Signature Helpers
-  // ─────────────────────────────────────────────────────────────────────────
-
-  private getActiveSignature(): SignatureResult | undefined {
-    if (this.authState.networkFee?.signature) {
-      return { signature: this.authState.networkFee.signature };
-    }
-    return this.authState.destinationSignature;
-  }
-}