@lombard.finance/sdk 3.7.4 → 4.0.0

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

@@ -0,0 +1,100 @@
+/**
+ * EVM Chain Configuration for Deposit
+ *
+ * Handles depositing wrapped BTC (WBTC, BTCb) to get LBTC.
+ * Routes are derived from ASSET_CATALOG to ensure consistency.
+ *
+ * @module chains/evm/actions/deposit/config/evm
+ */
+
+import {
+  AssetId,
+  Chain,
+  Env,
+  getEvmAssetChains,
+} from '../../../../../core';
+import { evmAddressSchema } from '../../../../../shared/validation';
+import type { ChainConfig } from './types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Catalog-Derived Chain Lists
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** 
+ * Source chains: EVM chains with deposit assets (WBTC or BTCb) 
+ * Note: We check for chains with any of the deposit assets
+ */
+const DEPOSIT_PROD_SOURCE_CHAINS = [
+  ...new Set([
+    ...getEvmAssetChains(AssetId.WBTC, [Env.prod]),
+    ...getEvmAssetChains(AssetId.BTCb, [Env.prod]),
+  ]),
+];
+
+const DEPOSIT_TESTNET_SOURCE_CHAINS = [
+  ...new Set([
+    ...getEvmAssetChains(AssetId.WBTC, [Env.testnet, Env.stage, Env.dev, Env.ibc]),
+    ...getEvmAssetChains(AssetId.BTCb, [Env.testnet, Env.stage, Env.dev, Env.ibc]),
+  ]),
+];
+
+/** Dest chains: EVM chains with LBTC deployed */
+const LBTC_PROD_CHAINS = getEvmAssetChains(AssetId.LBTC, [Env.prod]);
+const LBTC_TESTNET_CHAINS = getEvmAssetChains(AssetId.LBTC, [
+  Env.testnet,
+  Env.stage,
+  Env.dev,
+  Env.ibc,
+]);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Configuration Objects
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * EVM deposit configuration
+ *
+ * Supports depositing WBTC/BTCb to get LBTC on EVM chains.
+ * Source chains derived from WBTC/BTCb deployments.
+ * Dest chains derived from LBTC deployments.
+ */
+export const evmConfig: ChainConfig = {
+  chainType: 'evm',
+
+  routes: [
+    // Production: WBTC/BTCb → LBTC
+    {
+      assetsIn: [AssetId.WBTC, AssetId.BTCb],
+      assetOut: AssetId.LBTC,
+      sourceChains: DEPOSIT_PROD_SOURCE_CHAINS,
+      destChains: LBTC_PROD_CHAINS,
+      envs: [Env.prod],
+    },
+    // Testnet
+    {
+      assetsIn: [AssetId.WBTC, AssetId.BTCb],
+      assetOut: AssetId.LBTC,
+      sourceChains: DEPOSIT_TESTNET_SOURCE_CHAINS,
+      destChains: LBTC_TESTNET_CHAINS,
+      envs: [Env.testnet, Env.stage, Env.dev, Env.ibc],
+    },
+  ],
+
+  addressSchema: evmAddressSchema,
+};
+
+/**
+ * Check if a deposit route is supported
+ */
+export function isDepositSupported(
+  assetIn: AssetId,
+  sourceChain: Chain,
+  env: Env,
+): boolean {
+  return evmConfig.routes.some(
+    route =>
+      route.assetsIn.includes(assetIn) &&
+      route.sourceChains.includes(sourceChain) &&
+      route.envs.includes(env),
+  );
+}

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

@@ -0,0 +1,8 @@
+/**
+ * EVM Deposit Chain Configurations
+ *
+ * @module chains/evm/actions/deposit/config
+ */
+
+export { evmConfig, isDepositSupported } from './evm';
+export type { ChainConfig, RouteDefinition } from './types';

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

@@ -0,0 +1,39 @@
+/**
+ * EVM Deposit Chain Configuration Types
+ *
+ * @module chains/evm/actions/deposit/config/types
+ */
+
+import type { z } from 'zod';
+
+import type { AssetId, Chain, ChainType, Env } from '../../../../../core';
+
+/**
+ * Route definition for EVM deposit operations
+ */
+export interface RouteDefinition {
+  /** Supported input assets (e.g., WBTC, BTCb) */
+  assetsIn: AssetId[];
+  /** Output asset (e.g., LBTC) */
+  assetOut: AssetId;
+  /** Supported source chains */
+  sourceChains: Chain[];
+  /** Supported destination chains */
+  destChains: Chain[];
+  /** Supported environments */
+  envs: Env[];
+}
+
+/**
+ * Chain-specific configuration for EVM deposit operations
+ */
+export interface ChainConfig {
+  /** Chain type identifier */
+  chainType: ChainType;
+
+  /** Supported routes for this chain type */
+  routes: RouteDefinition[];
+
+  /** Address validation Zod schema */
+  addressSchema: z.ZodString;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * EVM Deposit Factory Functions
+ *
+ * @module chains/evm/actions/deposit/factory
+ */
+
+import type { LombardConfig } from '../../../../config/types';
+import type { EvmCoreContext } from '../../../../shared/context';
+import { createEvmCoreContext } from '../../../../shared/context';
+import { EvmDeposit } from './EvmDeposit';
+import type { EvmDepositParams } from './types';
+
+/**
+ * Create EvmDeposit action from config
+ *
+ * @internal This factory is for internal use. Use createLombardSDK() instead:
+ *
+ * @example
+ * ```typescript
+ * const sdk = await createLombardSDK({ env: Env.prod, providers: { evm: () => window.ethereum } });
+ * const deposit = sdk.chain.evm.deposit({
+ *   sourceChain: Chain.ETHEREUM,
+ *   assetIn: AssetId.WBTC,
+ * });
+ * await deposit.prepare({ amount: '0.1' });
+ * ```
+ */
+export function evmDeposit(
+  config: LombardConfig,
+  params: EvmDepositParams,
+): EvmDeposit {
+  const ctx = createEvmCoreContext(config);
+  return new EvmDeposit(ctx, params);
+}
+
+/**
+ * Create EvmDeposit action from context
+ */
+export function createEvmDeposit(
+  ctx: EvmCoreContext,
+  params: EvmDepositParams,
+): EvmDeposit {
+  return new EvmDeposit(ctx, params);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * EVM Deposit Action
+ *
+ * @module chains/evm/actions/deposit
+ */
+
+export type { ChainConfig, RouteDefinition } from './config';
+export { evmConfig, isDepositSupported } from './config';
+export { EvmDeposit } from './EvmDeposit';
+export { createEvmDeposit,evmDeposit } from './factory';
+export {
+  type EvmDepositParams,
+  type EvmDepositPrepareParams,
+  type EvmDepositProgress,
+  EvmDepositStatus,
+  type IEvmDeposit,
+} from './types';

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

@@ -0,0 +1,87 @@
+/**
+ * EVM Deposit Action Types
+ *
+ * @module chains/evm/actions/deposit/types
+ */
+
+import type {
+  AssetId,
+  Chain,
+  StepStatus,
+  StrategyProgress,
+} from '../../../../core';
+import type { MonitorableAction } from '../../../../shared/actions/BaseAction';
+import type { LombardError } from '../../../../shared/errors';
+
+/**
+ * EVM Deposit status
+ *
+ * Note: There is NO 'failed' status. Error handling is separate from status:
+ * - `status` = "What step are you at?" (flow position)
+ * - `error` = "Did something go wrong?" (Error | null)
+ * - `isFailed` = Derived from `error !== null`
+ *
+ * Use `isLoading` for operation-in-progress state (no transitional statuses).
+ */
+export enum EvmDepositStatus {
+  IDLE = 'idle',
+  NEEDS_APPROVAL = 'needs-approval',
+  READY = 'ready',
+  BRIDGING = 'bridging',
+  COMPLETED = 'completed',
+}
+
+/**
+ * EVM Deposit parameters
+ */
+export interface EvmDepositParams {
+  /** Input asset (WBTC, BTCb) */
+  assetIn: AssetId;
+  /** Output asset (LBTC) */
+  assetOut: AssetId;
+  /** Source chain */
+  sourceChain: Chain;
+  /** Destination chain */
+  destChain: Chain;
+}
+
+/**
+ * EVM Deposit prepare parameters
+ */
+export interface EvmDepositPrepareParams {
+  /** Amount to deposit */
+  amount: string;
+  /** Recipient address */
+  recipient: string;
+}
+
+/**
+ * EVM Deposit progress
+ */
+export interface EvmDepositProgress extends StrategyProgress<EvmDepositStatus> {
+  status: EvmDepositStatus;
+  steps: {
+    approval: StepStatus;
+    execution: StepStatus;
+    bridging?: StepStatus;
+  };
+  txHash?: string;
+}
+
+/**
+ * EVM Deposit interface
+ */
+export interface IEvmDeposit extends MonitorableAction {
+  readonly status: EvmDepositStatus;
+  readonly error: LombardError | null;
+  readonly amount?: string;
+  readonly recipient?: string;
+  readonly needsApproval: boolean;
+  readonly txHash?: string;
+
+  /** Set claim data from a notarized deposit (required before execute) */
+  setClaimData(data: string, proofSignature: string): void;
+  prepare(params: EvmDepositPrepareParams): Promise<void>;
+  approve(): Promise<void>;
+  execute(): Promise<{ txHash: string }>;
+}

package/src/chains/evm/actions/index.ts

@@ -0,0 +1,67 @@
+/**
+ * EVM Actions
+ *
+ * Exports for all EVM chain actions.
+ *
+ * @module chains/evm/actions
+ */
+
+// Stake action
+export {
+  createEvmStake,
+  EvmStake,
+  evmStake,
+  type EvmStakeParams,
+  type EvmStakePrepareParams,
+  type EvmStakeProgress,
+  EvmStakeStatus,
+  type IEvmStake,
+} from './stake';
+
+// Unstake action
+export {
+  createEvmUnstake,
+  EvmUnstake,
+  evmUnstake,
+  type EvmUnstakeParams,
+  type EvmUnstakePrepareParams,
+  type EvmUnstakeProgress,
+  EvmUnstakeStatus,
+  type IEvmUnstake,
+} from './unstake';
+
+// Deposit action
+export {
+  createEvmDeposit,
+  EvmDeposit,
+  evmDeposit,
+  type EvmDepositParams,
+  type EvmDepositPrepareParams,
+  type EvmDepositProgress,
+  EvmDepositStatus,
+  type IEvmDeposit,
+} from './deposit';
+
+// Deploy action
+export {
+  createEvmDeploy,
+  EvmDeploy,
+  evmDeploy,
+  type EvmDeployParams,
+  type EvmDeployPrepareParams,
+  type EvmDeployProgress,
+  EvmDeployStatus,
+  type IEvmDeploy,
+} from './deploy';
+
+// Redeem action
+export {
+  createEvmRedeem,
+  EvmRedeem,
+  evmRedeem,
+  type EvmRedeemParams,
+  type EvmRedeemPrepareParams,
+  type EvmRedeemProgress,
+  EvmRedeemStatus,
+  type IEvmRedeem,
+} from './redeem';

package/src/chains/evm/actions/redeem/EvmRedeem.ts

@@ -0,0 +1,263 @@
+/**
+ * EVM Redeem Action
+ *
+ * Redeems BTC.b to native BTC (cross-chain).
+ * This is the opposite operation to BTC Deposit.
+ *
+ * Flow: BTC.b (EVM) → BTC (Bitcoin)
+ *
+ * ## Fee Authorization
+ *
+ * On Ethereum/Sepolia, fee authorization is required before redemption.
+ * This covers the gas cost of the auto-mint operation on the destination.
+ *
+ * **Flow with fee auth (Ethereum/Sepolia):**
+ * IDLE → NEEDS_FEE_AUTHORIZATION → READY → COMPLETED
+ *
+ * **Flow without fee auth (Base, BSC - subsidized):**
+ * IDLE → READY → COMPLETED
+ *
+ * @module chains/evm/actions/redeem/EvmRedeem
+ */
+
+import type { EIP1193Provider } from 'viem';
+import { z } from 'zod';
+
+import type { ChainId } from '../../../../common/chains';
+import { redeemToken } from '../../../../contract-functions';
+import { parseChainIdentifier, StepStatus } from '../../../../core';
+import { BaseAction } from '../../../../shared/actions/BaseAction';
+import { EvmOperationStatus } from '../../../../shared/constants/statusConstants';
+import type { EvmCoreContext } from '../../../../shared/context';
+import { LombardError } from '../../../../shared/errors';
+import type { RedeemEventMap } from '../../../../shared/events';
+import {
+  evmAmountSchema,
+  validatePrepareParams,
+} from '../../../../shared/validation';
+import { Token } from '../../../../tokens/token-addresses';
+import {
+  authorizeFee as authorizeFeeShared,
+  checkFeeAuthorization,
+  createInitialFeeAuthState,
+  type FeeAuthState,
+} from '../../shared/feeAuth';
+import { evmConfig } from './config';
+import type {
+  EvmRedeemParams,
+  EvmRedeemPrepareParams,
+  IEvmRedeem,
+} from './types';
+
+export class EvmRedeem
+  extends BaseAction<RedeemEventMap, EvmOperationStatus>
+  implements IEvmRedeem
+{
+  private _amount?: string;
+  private _recipient?: string;
+  private _needsApproval = false;
+  private _txHash?: string;
+  private _feeAuth: FeeAuthState = createInitialFeeAuthState();
+
+  constructor(
+    private readonly ctx: EvmCoreContext,
+    private readonly params: EvmRedeemParams,
+  ) {
+    super(EvmOperationStatus.IDLE);
+  }
+
+  get amount(): string | undefined {
+    return this._amount;
+  }
+
+  get recipient(): string | undefined {
+    return this._recipient;
+  }
+
+  get needsApproval(): boolean {
+    return this._needsApproval;
+  }
+
+  get txHash(): string | undefined {
+    return this._txHash;
+  }
+
+  /** Fee authorization state (for UI display) */
+  get feeAuth(): FeeAuthState {
+    return this._feeAuth;
+  }
+
+  async prepare(params: EvmRedeemPrepareParams): Promise<void> {
+    this.assertStatus(EvmOperationStatus.IDLE, 'prepare');
+
+    return this.act(async () => {
+      const validated = validatePrepareParams(this.prepareSchema, params, {
+        destChain: this.params.destChain,
+      });
+      this._amount = validated.amount as string;
+      this._recipient = validated.recipient as string;
+
+      const chainId = parseChainIdentifier(this.params.sourceChain) as ChainId;
+
+      // Get EVM account for fee auth check
+      const provider = await this.ctx.getProvider('evm');
+      if (!provider) {
+        throw LombardError.providerMissing(this.params.sourceChain, 'evm');
+      }
+      const accounts = await (provider as EIP1193Provider).request({
+        method: 'eth_accounts',
+      });
+      const account = accounts[0] as `0x${string}`;
+
+      // Check fee authorization status (BTC.b redeem uses Token.BTCb)
+      const feeAuthResult = await checkFeeAuthorization(
+        chainId,
+        account,
+        this.ctx.env,
+        Token.BTCb,
+      );
+
+      // Update fee auth state
+      this._feeAuth = {
+        requiresAuth: feeAuthResult.requiresAuth,
+        isAuthorized: feeAuthResult.hasValidSignature,
+        feeInSatoshis: feeAuthResult.feeInSatoshis,
+        feeFormatted: feeAuthResult.feeFormatted,
+        expirationDate: feeAuthResult.expirationDate,
+      };
+
+      // Determine next status based on fee auth
+      if (feeAuthResult.requiresAuth && !feeAuthResult.hasValidSignature) {
+        this.emitProgress({
+          status: EvmOperationStatus.NEEDS_FEE_AUTHORIZATION,
+          steps: { burning: StepStatus.IDLE, releasing: StepStatus.IDLE },
+        });
+        return; // Don't transition to READY yet
+      }
+
+      // No fee auth required or already authorized
+      this._needsApproval = false;
+      this.emitProgress({
+        status: EvmOperationStatus.READY,
+        steps: { burning: StepStatus.IDLE, releasing: StepStatus.IDLE },
+      });
+    }, this._feeAuth.requiresAuth && !this._feeAuth.isAuthorized
+      ? EvmOperationStatus.NEEDS_FEE_AUTHORIZATION
+      : EvmOperationStatus.READY);
+  }
+
+  /**
+   * Authorize the network fee
+   *
+   * Must be called when status is NEEDS_FEE_AUTHORIZATION.
+   * Signs the fee authorization and stores it on the server.
+   */
+  async authorizeFee(): Promise<void> {
+    this.assertStatus(EvmOperationStatus.NEEDS_FEE_AUTHORIZATION, 'authorizeFee');
+
+    if (!this._feeAuth.feeInSatoshis) {
+      throw LombardError.missingParameter('feeInSatoshis');
+    }
+
+    return this.act(async () => {
+      const chainId = parseChainIdentifier(this.params.sourceChain) as ChainId;
+
+      const provider = await this.ctx.getProvider('evm');
+      if (!provider) {
+        throw LombardError.providerMissing(this.params.sourceChain, 'evm');
+      }
+
+      const accounts = await (provider as EIP1193Provider).request({
+        method: 'eth_accounts',
+      });
+      const account = accounts[0] as `0x${string}`;
+
+      // Sign and store fee authorization
+      await authorizeFeeShared({
+        chainId,
+        account,
+        feeInSatoshis: this._feeAuth.feeInSatoshis!,
+        provider: provider as EIP1193Provider,
+        env: this.ctx.env,
+        token: Token.BTCb,
+      });
+
+      // Update state
+      this._feeAuth.isAuthorized = true;
+
+      this.emitProgress({
+        status: EvmOperationStatus.READY,
+        steps: { burning: StepStatus.IDLE, releasing: StepStatus.IDLE },
+      });
+    }, EvmOperationStatus.READY);
+  }
+
+  async approve(): Promise<void> {
+    this.assertStatus(EvmOperationStatus.NEEDS_APPROVAL, 'approve');
+
+    return this.act(async () => {
+      this._needsApproval = false;
+      this.emitProgress({
+        status: EvmOperationStatus.READY,
+        steps: { burning: StepStatus.IDLE, releasing: StepStatus.IDLE },
+      });
+    }, EvmOperationStatus.READY);
+  }
+
+  async execute(): Promise<{ txHash: string }> {
+    this.assertStatus(EvmOperationStatus.READY, 'execute');
+
+    return this.act(async () => {
+      const provider = await this.ctx.getProvider('evm');
+      if (!provider) {
+        throw LombardError.providerMissing(this.params.sourceChain, 'evm');
+      }
+
+      // Get the connected EVM account address from the provider
+      const accounts = await (provider as EIP1193Provider).request({
+        method: 'eth_accounts',
+      });
+      const evmAccount = accounts[0] as `0x${string}`;
+      if (!evmAccount) {
+        throw LombardError.providerMissing(this.params.sourceChain, 'evm');
+      }
+
+      const chainId = parseChainIdentifier(this.params.sourceChain) as ChainId;
+
+      this.emitProgress({
+        status: EvmOperationStatus.READY,
+        steps: { burning: StepStatus.PENDING, releasing: StepStatus.IDLE },
+      });
+
+      // Execute BTC.b → BTC redemption (burn BTC.b, release BTC to Bitcoin address)
+      const txHash = await redeemToken({
+        provider: provider as EIP1193Provider,
+        account: evmAccount,
+        amount: this._amount!,
+        btcAddress: this._recipient!, // Bitcoin address to receive BTC
+        chainId,
+        env: this.ctx.env,
+        tokenIn: Token.BTCb,
+        tokenOut: undefined, // Native BTC output
+      });
+
+      this._txHash = txHash;
+
+      this.emitProgress({
+        status: EvmOperationStatus.COMPLETED,
+        steps: { burning: StepStatus.COMPLETE, releasing: StepStatus.PENDING },
+      });
+
+      this.emitCompleted();
+
+      return { txHash };
+    }, EvmOperationStatus.COMPLETED);
+  }
+
+  private get prepareSchema() {
+    return z.object({
+      amount: evmAmountSchema,
+      recipient: evmConfig.recipientSchema,
+    });
+  }
+}