@lombard.finance/sdk 3.7.3 → 4.0.0

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

@@ -0,0 +1,89 @@
+/**
+ * EVM Chain Configuration for Stake
+ *
+ * Handles staking LBTC to DeFi protocols on EVM chains.
+ *
+ * Protocol availability:
+ * - Veda: Ethereum, Base, BSC, Corn (prod only)
+ * - Silo: Avalanche (prod only)
+ *
+ * @module chains/evm/actions/stake/config/evm
+ */
+
+import { Chain, DeployProtocol, Env } from '../../../../../core';
+import { evmAddressSchema } from '../../../../../shared/validation';
+import type { ChainConfig } from './types';
+
+/**
+ * EVM chain configuration for stake operations
+ *
+ * Supports staking LBTC to Veda and Silo protocols.
+ */
+export const evmConfig: ChainConfig = {
+  chainType: 'evm',
+
+  routes: [
+    // Veda - Ethereum
+    {
+      sourceChains: [Chain.ETHEREUM],
+      destChains: [Chain.ETHEREUM],
+      protocols: [DeployProtocol.Veda],
+      envs: [Env.prod],
+    },
+    // Veda - Base
+    {
+      sourceChains: [Chain.BASE],
+      destChains: [Chain.BASE],
+      protocols: [DeployProtocol.Veda],
+      envs: [Env.prod],
+    },
+    // Veda - BSC
+    {
+      sourceChains: [Chain.BSC],
+      destChains: [Chain.BSC],
+      protocols: [DeployProtocol.Veda],
+      envs: [Env.prod],
+    },
+    // Veda - Corn
+    {
+      sourceChains: [Chain.CORN],
+      destChains: [Chain.CORN],
+      protocols: [DeployProtocol.Veda],
+      envs: [Env.prod],
+    },
+    // Silo - Avalanche
+    {
+      sourceChains: [Chain.AVALANCHE],
+      destChains: [Chain.AVALANCHE],
+      protocols: [DeployProtocol.Silo],
+      envs: [Env.prod],
+    },
+  ],
+
+  addressSchema: evmAddressSchema,
+};
+
+/**
+ * Check if a source chain is supported for stake
+ */
+export function isSourceChainSupported(chain: Chain, env: Env): boolean {
+  return evmConfig.routes.some(
+    route => route.sourceChains.includes(chain) && route.envs.includes(env),
+  );
+}
+
+/**
+ * Check if a protocol is supported for a given chain
+ */
+export function isProtocolSupported(
+  chain: Chain,
+  protocol: DeployProtocol,
+  env: Env,
+): boolean {
+  return evmConfig.routes.some(
+    route =>
+      route.sourceChains.includes(chain) &&
+      route.protocols.includes(protocol) &&
+      route.envs.includes(env),
+  );
+}

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

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

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

@@ -0,0 +1,89 @@
+/**
+ * EVM Stake Chain Configuration Types
+ *
+ * Defines the interface for source chain configurations.
+ * Each supported chain implements this interface to provide
+ * chain-specific behavior for EVM stake operations.
+ *
+ * @module chains/evm/actions/stake/config/types
+ */
+
+import type { z } from 'zod';
+
+import type {
+  Chain,
+  ChainType,
+  DeployProtocol,
+  Env,
+} from '../../../../../core';
+import type { EvmCoreContext } from '../../../../../shared/context';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Route Definition
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Route definition for EVM stake operations
+ *
+ * Defines which source chains, protocols, and environments are supported.
+ */
+export interface RouteDefinition {
+  /** Supported source chains */
+  sourceChains: Chain[];
+  /** Supported destination chains */
+  destChains: Chain[];
+  /** Supported DeFi protocols */
+  protocols: DeployProtocol[];
+  /** Supported environments */
+  envs: Env[];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Chain Configuration
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Chain-specific configuration for EVM stake operations
+ *
+ * EVM stake deposits already-owned LBTC to DeFi vaults (Veda, Silo).
+ */
+export interface ChainConfig {
+  /** Chain type identifier */
+  chainType: ChainType;
+
+  /** Supported routes for this chain type */
+  routes: RouteDefinition[];
+
+  /** Address validation Zod schema */
+  addressSchema: z.ZodString;
+
+  /**
+   * Check if user has sufficient LBTC balance
+   *
+   * @param ctx - EVM core context
+   * @param address - User address
+   * @param amount - Amount to stake
+   * @returns true if balance is sufficient
+   */
+  checkBalance?: (
+    ctx: EvmCoreContext,
+    address: string,
+    amount: string,
+  ) => Promise<boolean>;
+
+  /**
+   * Get required approval amount
+   *
+   * @param ctx - EVM core context
+   * @param address - User address
+   * @param spender - Vault/protocol address
+   * @param amount - Amount to stake
+   * @returns Approval amount needed (0 if already approved)
+   */
+  getApprovalNeeded?: (
+    ctx: EvmCoreContext,
+    address: string,
+    spender: string,
+    amount: string,
+  ) => Promise<string>;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * EVM Stake Factory Functions
+ *
+ * Provides factory functions for creating EvmStake instances.
+ *
+ * @module chains/evm/actions/stake/factory
+ */
+
+import type { LombardConfig } from '../../../../config/types';
+import type { EvmCoreContext } from '../../../../shared/context';
+import { createEvmCoreContext } from '../../../../shared/context';
+import { EvmStake } from './EvmStake';
+import type { EvmStakeParams } from './types';
+
+/**
+ * Create EvmStake 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 stake = sdk.chain.evm.stake({
+ *   sourceChain: Chain.ETHEREUM,
+ *   destChain: Chain.ETHEREUM,
+ * });
+ * await stake.prepare({ amount: '0.1' });
+ * ```
+ */
+export function evmStake(
+  config: LombardConfig,
+  params: EvmStakeParams,
+): EvmStake {
+  const ctx = createEvmCoreContext(config);
+  return new EvmStake(ctx, params);
+}
+
+/**
+ * Create EvmStake action from context
+ *
+ * Use this when you already have an EvmCoreContext (e.g., in EvmActions).
+ *
+ * @param ctx - EvmCoreContext
+ * @param params - Stake parameters
+ * @returns EvmStake instance
+ */
+export function createEvmStake(
+  ctx: EvmCoreContext,
+  params: EvmStakeParams,
+): EvmStake {
+  return new EvmStake(ctx, params);
+}

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

@@ -0,0 +1,30 @@
+/**
+ * EVM Stake Action
+ *
+ * Exports for the EVM stake action.
+ *
+ * @module chains/evm/actions/stake
+ */
+
+// Main action
+export { EvmStake } from './EvmStake';
+
+// Factory functions
+export { createEvmStake,evmStake } from './factory';
+
+// Types
+export {
+  type EvmStakeParams,
+  type EvmStakePrepareParams,
+  type EvmStakeProgress,
+  EvmStakeStatus,
+  type IEvmStake,
+} from './types';
+
+// Config (for advanced usage)
+export type { ChainConfig, RouteDefinition } from './config';
+export {
+  evmConfig,
+  isProtocolSupported,
+  isSourceChainSupported,
+} from './config';

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

@@ -0,0 +1,104 @@
+/**
+ * EVM Stake Action Types
+ *
+ * Stake BTC.b to receive LBTC via Asset Router.
+ *
+ * ## Approval (Avalanche only)
+ *
+ * On Avalanche, users must approve the Adapter contract to spend their BTC.b.
+ *
+ * ## Fee Authorization (Ethereum/Sepolia only)
+ *
+ * Fee authorization is required on unsubsidized chains (Ethereum, Sepolia).
+ * On subsidized chains (Avalanche, Base, BSC), no fee auth is required.
+ *
+ * ## Flow Examples
+ *
+ * **Avalanche (needs approval):**
+ * IDLE → NEEDS_APPROVAL → READY → COMPLETED
+ *
+ * **Ethereum/Sepolia (needs fee auth):**
+ * IDLE → NEEDS_FEE_AUTHORIZATION → READY → COMPLETED
+ *
+ * **Base/BSC (neither):**
+ * IDLE → READY → COMPLETED
+ *
+ * @module chains/evm/actions/stake/types
+ */
+
+import type {
+    AssetId,
+    Chain,
+    StepStatus,
+    StrategyProgress,
+} from '../../../../core';
+import type { MonitorableAction } from '../../../../shared/actions/BaseAction';
+import type { EvmOperationStatus } from '../../../../shared/constants/statusConstants';
+import type { LombardError } from '../../../../shared/errors';
+import type { FeeAuthState } from '../../shared/feeAuth';
+
+// Re-export status for convenience
+export { EvmOperationStatus as EvmStakeStatus } from '../../../../shared/constants/statusConstants';
+
+/**
+ * EVM Stake parameters
+ *
+ * Stakes BTC.b to receive LBTC.
+ */
+export interface EvmStakeParams {
+  /** Input asset (BTC.b) */
+  assetIn: AssetId;
+  /** Output asset (LBTC) */
+  assetOut: AssetId;
+  /** Source chain (where BTC.b is held) */
+  sourceChain: Chain;
+  /** Destination chain (same as source) */
+  destChain: Chain;
+}
+
+/**
+ * EVM Stake prepare parameters
+ */
+export interface EvmStakePrepareParams {
+  /** Amount of BTC.b to stake */
+  amount: string;
+}
+
+/**
+ * EVM Stake progress
+ */
+export interface EvmStakeProgress extends StrategyProgress<EvmOperationStatus> {
+  status: EvmOperationStatus;
+  steps: {
+    approval?: StepStatus;
+    staking: StepStatus;
+  };
+  txHash?: string;
+}
+
+/**
+ * EVM Stake interface
+ */
+export interface IEvmStake extends MonitorableAction {
+  readonly status: EvmOperationStatus;
+  readonly error: LombardError | null;
+  readonly amount?: string;
+  readonly txHash?: string;
+  /** Fee authorization state (for UI display) */
+  readonly feeAuth: FeeAuthState;
+  /** Whether approval is needed (Avalanche only) */
+  readonly needsApproval: boolean;
+
+  prepare(params: EvmStakePrepareParams): Promise<void>;
+  /**
+   * Approve BTC.b spending (Avalanche only)
+   * Only needed when status is NEEDS_APPROVAL.
+   */
+  approve(): Promise<void>;
+  /**
+   * Authorize fee (EIP-712 signing)
+   * Only needed on unsubsidized chains (Ethereum/Sepolia).
+   */
+  authorizeFee(): Promise<void>;
+  execute(): Promise<{ txHash: string }>;
+}

package/src/chains/evm/actions/unstake/EvmUnstake.ts

@@ -0,0 +1,258 @@
+/**
+ * EVM Unstake Action
+ *
+ * Burns LBTC on EVM chains and releases BTC (cross-chain) or BTC.b (same-chain).
+ *
+ * ## Fee Authorization
+ *
+ * Fee authorization is required when:
+ * - Output asset is BTC.b (LBTC → BTC.b conversion)
+ * - Source chain is Ethereum/Sepolia (unsubsidized chains)
+ *
+ * **Flow with fee auth (LBTC → BTC.b on Ethereum/Sepolia):**
+ * IDLE → NEEDS_FEE_AUTHORIZATION → READY → COMPLETED
+ *
+ * **Flow without fee auth (LBTC → BTC, or BTC.b on Base/BSC):**
+ * IDLE → READY → COMPLETED
+ *
+ * @module chains/evm/actions/unstake/EvmUnstake
+ */
+
+import type { EIP1193Provider } from 'viem';
+import { z } from 'zod';
+
+import type { ChainId } from '../../../../common/chains';
+import { redeemToken } from '../../../../contract-functions';
+import { AssetId, 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 { UnstakeEventMap } 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 { evmToBtcbConfig, evmToBtcConfig } from './config';
+import type {
+  EvmUnstakeParams,
+  EvmUnstakePrepareParams,
+  IEvmUnstake,
+} from './types';
+
+export class EvmUnstake
+  extends BaseAction<UnstakeEventMap, EvmOperationStatus>
+  implements IEvmUnstake
+{
+  private _amount?: string;
+  private _recipient?: string;
+  private _txHash?: string;
+  private _feeAuth: FeeAuthState = createInitialFeeAuthState();
+
+  constructor(
+    private readonly ctx: EvmCoreContext,
+    private readonly params: EvmUnstakeParams,
+  ) {
+    super(EvmOperationStatus.IDLE);
+  }
+
+  get amount(): string | undefined {
+    return this._amount;
+  }
+
+  get recipient(): string | undefined {
+    return this._recipient;
+  }
+
+  get txHash(): string | undefined {
+    return this._txHash;
+  }
+
+  /** Fee authorization state (for UI display) */
+  get feeAuth(): FeeAuthState {
+    return this._feeAuth;
+  }
+
+  /** Whether output is BTC.b (requires fee auth on unsubsidized chains) */
+  private get isBtcbOutput(): boolean {
+    return this.params.assetOut === AssetId.BTCb;
+  }
+
+  async prepare(params: EvmUnstakePrepareParams): 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;
+      this._recipient = validated.recipient;
+
+      const chainId = parseChainIdentifier(this.params.sourceChain) as ChainId;
+
+      // Fee auth is only required for BTC.b output on unsubsidized chains
+      if (this.isBtcbOutput) {
+        // 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 (use Token.BTCb for LBTC → BTC.b)
+        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,
+        };
+
+        // If fee auth required and not authorized, transition to NEEDS_FEE_AUTHORIZATION
+        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.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 (use Token.BTCb for LBTC → BTC.b)
+      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 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;
+      const isBtcbOutput = this.params.assetOut === AssetId.BTCb;
+
+      this.emitProgress({
+        status: EvmOperationStatus.READY,
+        steps: { burning: StepStatus.PENDING, releasing: StepStatus.IDLE },
+      });
+
+      // For BTC output: account = EVM wallet (executing burn), btcAddress = recipient (Bitcoin)
+      // For BTCb output: account = recipient (same EVM address receives BTCb)
+      const txHash = await redeemToken({
+        provider: provider as EIP1193Provider,
+        account: isBtcbOutput ? (this._recipient! as `0x${string}`) : evmAccount,
+        amount: this._amount!,
+        btcAddress: isBtcbOutput ? undefined : this._recipient!,
+        chainId,
+        env: this.ctx.env,
+        tokenIn: Token.LBTC,
+        tokenOut: isBtcbOutput ? Token.BTCb : undefined,
+      });
+
+      this._txHash = txHash;
+
+      this.emitProgress({
+        status: EvmOperationStatus.COMPLETED,
+        steps: {
+          burning: StepStatus.COMPLETE,
+          releasing: isBtcbOutput ? StepStatus.COMPLETE : StepStatus.PENDING,
+        },
+      });
+
+      this.emitCompleted();
+
+      return { txHash };
+    }, EvmOperationStatus.COMPLETED);
+  }
+
+  private get prepareSchema() {
+    const config =
+      this.params.assetOut === AssetId.BTC ? evmToBtcConfig : evmToBtcbConfig;
+    return z.object({
+      amount: evmAmountSchema,
+      recipient: config.recipientSchema,
+    });
+  }
+}