@lombard.finance/sdk 3.7.4 → 4.0.0

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

@@ -0,0 +1,123 @@
+/**
+ * EVM Chain Configuration for Unstake
+ *
+ * Handles unstaking LBTC to BTC (cross-chain) or BTC.b (same-chain).
+ * Routes are derived from ASSET_CATALOG to ensure consistency.
+ *
+ * @module chains/evm/actions/unstake/config/evm
+ */
+
+import {
+  AssetId,
+  Chain,
+  Env,
+  getEvmAssetChains,
+  getEvmChainsWithAllAssets,
+} from '../../../../../core';
+import {
+  bitcoinAddressSchema,
+  evmAddressSchema,
+} from '../../../../../shared/validation';
+import type { ChainConfig } from './types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Catalog-Derived Chain Lists
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** EVM chains with LBTC deployed (can unstake to BTC) */
+const LBTC_PROD_CHAINS = getEvmAssetChains(AssetId.LBTC, [Env.prod]);
+const LBTC_TESTNET_CHAINS = getEvmAssetChains(AssetId.LBTC, [
+  Env.testnet,
+  Env.stage,
+  Env.dev,
+  Env.ibc,
+]);
+
+/** EVM chains with BOTH LBTC and BTCb deployed (can unstake to BTCb) */
+const LBTC_BTCB_PROD_CHAINS = getEvmChainsWithAllAssets(
+  [AssetId.LBTC, AssetId.BTCb],
+  [Env.prod],
+);
+const LBTC_BTCB_TESTNET_CHAINS = getEvmChainsWithAllAssets(
+  [AssetId.LBTC, AssetId.BTCb],
+  [Env.testnet, Env.stage, Env.dev, Env.ibc],
+);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Configuration Objects
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * EVM → BTC configuration (cross-chain unstake)
+ *
+ * Burns LBTC on EVM, releases BTC on Bitcoin network.
+ * Source chains derived from ASSET_CATALOG LBTC deployments.
+ */
+export const evmToBtcConfig: ChainConfig = {
+  chainType: 'evm',
+
+  routes: [
+    // Production: EVM chains with LBTC → Bitcoin Mainnet
+    {
+      sourceChains: LBTC_PROD_CHAINS,
+      destChain: Chain.BITCOIN_MAINNET,
+      envs: [Env.prod],
+    },
+    // Testnet: EVM chains with LBTC → Bitcoin Signet
+    {
+      sourceChains: LBTC_TESTNET_CHAINS,
+      destChain: Chain.BITCOIN_SIGNET,
+      envs: [Env.testnet, Env.stage, Env.dev, Env.ibc],
+    },
+  ],
+
+  recipientSchema: bitcoinAddressSchema,
+};
+
+/**
+ * EVM → BTC.b configuration (same-chain wrapped)
+ *
+ * Burns LBTC on EVM, mints BTC.b on same EVM chain.
+ * Only available on chains with BOTH LBTC and BTCb deployed.
+ * Routes are generated dynamically from catalog.
+ */
+export const evmToBtcbConfig: ChainConfig = {
+  chainType: 'evm',
+
+  routes: [
+    // Production: Same-chain routes for chains with both LBTC and BTCb
+    ...LBTC_BTCB_PROD_CHAINS.map(chain => ({
+      sourceChains: [chain],
+      destChain: chain,
+      envs: [Env.prod] as Env[],
+    })),
+    // Testnet: Same-chain routes
+    ...LBTC_BTCB_TESTNET_CHAINS.map(chain => ({
+      sourceChains: [chain],
+      destChain: chain,
+      envs: [Env.testnet, Env.stage, Env.dev, Env.ibc] as Env[],
+    })),
+  ],
+
+  recipientSchema: evmAddressSchema,
+};
+
+/**
+ * Check if unstake to BTC is supported
+ */
+export function isBtcUnstakeSupported(sourceChain: Chain, env: Env): boolean {
+  return evmToBtcConfig.routes.some(
+    route =>
+      route.sourceChains.includes(sourceChain) && route.envs.includes(env),
+  );
+}
+
+/**
+ * Check if unstake to BTC.b is supported
+ */
+export function isBtcbUnstakeSupported(sourceChain: Chain, env: Env): boolean {
+  return evmToBtcbConfig.routes.some(
+    route =>
+      route.sourceChains.includes(sourceChain) && route.envs.includes(env),
+  );
+}

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

@@ -0,0 +1,13 @@
+/**
+ * EVM Unstake Chain Configurations
+ *
+ * @module chains/evm/actions/unstake/config
+ */
+
+export {
+  evmToBtcbConfig,
+  evmToBtcConfig,
+  isBtcbUnstakeSupported,
+  isBtcUnstakeSupported,
+} from './evm';
+export type { ChainConfig, RouteDefinition } from './types';

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

@@ -0,0 +1,37 @@
+/**
+ * EVM Unstake Chain Configuration Types
+ *
+ * @module chains/evm/actions/unstake/config/types
+ */
+
+import type { z } from 'zod';
+
+import type { Chain, ChainType, Env } from '../../../../../core';
+
+/**
+ * Route definition for EVM unstake operations
+ */
+export interface RouteDefinition {
+  /** Supported source chains (where LBTC is burned) */
+  sourceChains: Chain[];
+  /** Destination chain (where BTC/BTC.b is received) */
+  destChain: Chain;
+  /** Supported environments */
+  envs: Env[];
+}
+
+/**
+ * Chain-specific configuration for EVM unstake operations
+ *
+ * EVM unstake burns LBTC and releases BTC (cross-chain) or BTC.b (same-chain).
+ */
+export interface ChainConfig {
+  /** Chain type identifier */
+  chainType: ChainType;
+
+  /** Supported routes for this chain type */
+  routes: RouteDefinition[];
+
+  /** Recipient address validation Zod schema */
+  recipientSchema: z.ZodType<string>;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * EVM Unstake Factory Functions
+ *
+ * @module chains/evm/actions/unstake/factory
+ */
+
+import type { LombardConfig } from '../../../../config/types';
+import type { EvmCoreContext } from '../../../../shared/context';
+import { createEvmCoreContext } from '../../../../shared/context';
+import { EvmUnstake } from './EvmUnstake';
+import type { EvmUnstakeParams } from './types';
+
+/**
+ * Create EvmUnstake 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 unstake = sdk.chain.evm.unstake({
+ *   sourceChain: Chain.ETHEREUM,
+ *   assetOut: AssetId.BTC,
+ * });
+ * await unstake.prepare({ amount: '0.1', recipient: 'bc1q...' });
+ * ```
+ */
+export function evmUnstake(
+  config: LombardConfig,
+  params: EvmUnstakeParams,
+): EvmUnstake {
+  const ctx = createEvmCoreContext(config);
+  return new EvmUnstake(ctx, params);
+}
+
+/**
+ * Create EvmUnstake action from context
+ */
+export function createEvmUnstake(
+  ctx: EvmCoreContext,
+  params: EvmUnstakeParams,
+): EvmUnstake {
+  return new EvmUnstake(ctx, params);
+}

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

@@ -0,0 +1,22 @@
+/**
+ * EVM Unstake Action
+ *
+ * @module chains/evm/actions/unstake
+ */
+
+export type { ChainConfig, RouteDefinition } from './config';
+export {
+  evmToBtcbConfig,
+  evmToBtcConfig,
+  isBtcbUnstakeSupported,
+  isBtcUnstakeSupported,
+} from './config';
+export { EvmUnstake } from './EvmUnstake';
+export { createEvmUnstake,evmUnstake } from './factory';
+export {
+  type EvmUnstakeParams,
+  type EvmUnstakePrepareParams,
+  type EvmUnstakeProgress,
+  EvmUnstakeStatus,
+  type IEvmUnstake,
+} from './types';

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

@@ -0,0 +1,87 @@
+/**
+ * EVM Unstake Action Types
+ *
+ * ## 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/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 EvmUnstakeStatus } from '../../../../shared/constants/statusConstants';
+
+/**
+ * EVM Unstake parameters
+ */
+export interface EvmUnstakeParams {
+  /** Input asset (LBTC) */
+  assetIn: AssetId;
+  /** Output asset (BTC for cross-chain, BTCb for same-chain) */
+  assetOut: AssetId;
+  /** Source chain (where LBTC is burned) */
+  sourceChain: Chain;
+  /** Destination chain (Bitcoin or same EVM chain) */
+  destChain: Chain;
+}
+
+/**
+ * EVM Unstake prepare parameters
+ */
+export interface EvmUnstakePrepareParams {
+  /** Amount to unstake (in LBTC) */
+  amount: string;
+  /** Recipient address (BTC address or EVM address) */
+  recipient: string;
+}
+
+/**
+ * EVM Unstake progress
+ */
+export interface EvmUnstakeProgress
+  extends StrategyProgress<EvmOperationStatus> {
+  status: EvmOperationStatus;
+  steps: {
+    burning: StepStatus;
+    releasing: StepStatus;
+  };
+  txHash?: string;
+}
+
+/**
+ * EVM Unstake interface
+ */
+export interface IEvmUnstake extends MonitorableAction {
+  readonly status: EvmOperationStatus;
+  readonly error: LombardError | null;
+  readonly amount?: string;
+  readonly recipient?: string;
+  readonly txHash?: string;
+
+  /** Fee authorization state (for UI display) */
+  readonly feeAuth: FeeAuthState;
+
+  prepare(params: EvmUnstakePrepareParams): Promise<void>;
+  /** Authorize the network fee (when status is NEEDS_FEE_AUTHORIZATION) */
+  authorizeFee(): Promise<void>;
+  execute(): Promise<{ txHash: string }>;
+}

package/src/chains/evm/index.ts

@@ -0,0 +1,16 @@
+/**
+ * EVM Chain
+ *
+ * Exports for the EVM chain namespace.
+ *
+ * @module chains/evm
+ */
+
+// Main actions class
+export { EvmActions, evmActions } from './EvmActions';
+
+// All action exports
+export * from './actions';
+
+// Shared utilities
+export * from './shared';

package/src/chains/evm/shared/feeAuth.ts

@@ -0,0 +1,198 @@
+/**
+ * Shared Fee Authorization Logic for EVM Actions
+ *
+ * Provides fee authorization support for EVM actions that require it:
+ * - EvmStake (BTC.b → LBTC on Ethereum/Sepolia)
+ * - EvmRedeem (BTC.b → BTC on Ethereum/Sepolia)
+ * - EvmUnstake (LBTC → BTC.b on Ethereum/Sepolia)
+ *
+ * Fee authorization is only required on unsubsidized chains (Ethereum, Sepolia).
+ * Other chains (Base, BSC, Avalanche) are subsidized by Lombard.
+ *
+ * @module chains/evm/shared/feeAuth
+ */
+
+import type { EIP1193Provider } from 'viem';
+
+import { getNetworkFeeSignature } from '../../../api-functions';
+import { storeNetworkFeeSignature } from '../../../api-functions/storeNetworkFeeSignature/storeNetworkFeeSignature';
+import type { ChainId } from '../../../common/chains';
+import { requiresAutoMintFee } from '../../../common/fee-requirements';
+import { getMintingFee } from '../../../contract-functions';
+import { signNetworkFee } from '../../../contract-functions/signNetworkFee/signNetworkFee';
+import type { Env } from '../../../core';
+import { Token } from '../../../tokens/token-addresses';
+import { getTokenContractInfo } from '../../../tokens/tokens';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Fee authorization state
+ */
+export interface FeeAuthState {
+  /** Whether fee authorization is required for this chain */
+  requiresAuth: boolean;
+  /** Whether fee authorization is complete (valid signature exists) */
+  isAuthorized: boolean;
+  /** Minting fee in satoshis (for signing) */
+  feeInSatoshis: bigint | null;
+  /** Minting fee formatted in BTC (for display) */
+  feeFormatted: string | null;
+  /** Signature expiration date (Unix timestamp in seconds) */
+  expirationDate: string | null;
+}
+
+/**
+ * Fee authorization check result
+ */
+export interface FeeAuthCheckResult {
+  /** Whether fee authorization is required */
+  requiresAuth: boolean;
+  /** Whether a valid (non-expired) signature exists */
+  hasValidSignature: boolean;
+  /** Minting fee in satoshis */
+  feeInSatoshis: bigint | null;
+  /** Minting fee formatted in BTC */
+  feeFormatted: string | null;
+  /** Expiration date if signature exists */
+  expirationDate: string | null;
+}
+
+/**
+ * Parameters for fee authorization
+ */
+export interface AuthorizeFeeParams {
+  chainId: ChainId;
+  account: `0x${string}`;
+  feeInSatoshis: bigint;
+  provider: EIP1193Provider;
+  env: Env;
+  token: Token;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Fee Authorization Logic
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if fee authorization is required and if a valid signature exists
+ *
+ * This should be called in the action's prepare() method to determine
+ * whether to transition to NEEDS_FEE_AUTHORIZATION or READY status.
+ *
+ * @param chainId - The EVM chain ID
+ * @param account - The user's EVM account address
+ * @param env - The environment (prod, stage, testnet)
+ * @param token - The token type (BTCb or LBTC)
+ * @returns Fee authorization check result
+ */
+export async function checkFeeAuthorization(
+  chainId: ChainId,
+  account: `0x${string}`,
+  env: Env,
+  token: Token,
+): Promise<FeeAuthCheckResult> {
+  // Check if this chain requires fee authorization
+  if (!requiresAutoMintFee(chainId)) {
+    return {
+      requiresAuth: false,
+      hasValidSignature: false,
+      feeInSatoshis: null,
+      feeFormatted: null,
+      expirationDate: null,
+    };
+  }
+
+  // Get token address for signature lookup
+  const tokenInfo = await getTokenContractInfo(token, chainId, env);
+
+  // Check for existing valid signature on server
+  const existingSignature = await getNetworkFeeSignature({
+    address: account,
+    chainId,
+    env,
+    tokenAddress: tokenInfo.address,
+  });
+
+  // Check if signature exists and is not expired
+  const isExpired = existingSignature.expirationDate
+    ? new Date(Number(existingSignature.expirationDate) * 1000) < new Date()
+    : false;
+
+  const hasValidSignature = existingSignature.hasSignature && !isExpired;
+
+  // If no valid signature, fetch the minting fee
+  let feeInSatoshis: bigint | null = null;
+  let feeFormatted: string | null = null;
+
+  if (!hasValidSignature) {
+    const feeInBtc = await getMintingFee({
+      token,
+      chainId,
+      env,
+    });
+    feeInSatoshis = BigInt(feeInBtc.times(1e8).toFixed(0));
+    feeFormatted = feeInBtc.toFixed(8);
+  }
+
+  return {
+    requiresAuth: true,
+    hasValidSignature,
+    feeInSatoshis,
+    feeFormatted,
+    expirationDate: existingSignature.expirationDate ?? null,
+  };
+}
+
+/**
+ * Authorize fee by signing and storing the signature
+ *
+ * This should be called from the action's authorizeFee() method.
+ *
+ * @param params - Authorization parameters
+ * @returns The signature
+ */
+export async function authorizeFee(
+  params: AuthorizeFeeParams,
+): Promise<{ signature: `0x${string}`; typedData: string }> {
+  const { chainId, account, feeInSatoshis, provider, env, token } = params;
+
+  // Get token address for storing signature
+  const tokenInfo = await getTokenContractInfo(token, chainId, env);
+
+  // Sign the network fee
+  const signResult = await signNetworkFee({
+    fee: feeInSatoshis,
+    account,
+    chainId,
+    provider,
+    env,
+    token,
+  });
+
+  // Store the signature on the server
+  await storeNetworkFeeSignature({
+    signature: signResult.signature,
+    typedData: signResult.typedData,
+    address: account,
+    env,
+    tokenAddress: tokenInfo.address,
+  });
+
+  return signResult;
+}
+
+/**
+ * Create initial fee auth state
+ */
+export function createInitialFeeAuthState(): FeeAuthState {
+  return {
+    requiresAuth: false,
+    isAuthorized: false,
+    feeInSatoshis: null,
+    feeFormatted: null,
+    expirationDate: null,
+  };
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Shared EVM Action Utilities
+ *
+ * @module chains/evm/shared
+ */
+
+export * from './feeAuth';

package/src/chains/solana/SolanaActions.ts

@@ -0,0 +1,85 @@
+/**
+ * Solana Actions
+ *
+ * Provides factory methods for Solana operations (unstake).
+ *
+ * Note: Solana module must be registered before using these actions.
+ *
+ * @example
+ * ```typescript
+ * import { solanaActions } from '@lombard.finance/sdk';
+ *
+ * const solana = solanaActions(config);
+ * const unstake = solana.unstake({ ... });
+ * ```
+ */
+
+import type { SolanaService } from '@lombard.finance/sdk-common';
+
+import { PartnerConfiguration } from '../../client/PartnerConfiguration';
+import type { LombardConfig } from '../../config/types';
+import { getProviderGetter } from '../../config/types';
+import { CapabilityRegistry } from '../../modules/CapabilityRegistry';
+import type { SolanaCoreContext } from '../../shared/context';
+import { SolanaUnstake } from './actions/unstake/SolanaUnstake';
+import type {
+  ISolanaUnstake,
+  SolanaUnstakeParams,
+} from './actions/unstake/types';
+
+/**
+ * Create Solana core context from config
+ * Only called when an action is invoked (lazy initialization)
+ */
+function createSolanaCoreContext(config: LombardConfig): SolanaCoreContext {
+  const registry = new CapabilityRegistry(config.modules, config);
+  const solana = registry.require('solana') as SolanaService;
+
+  return {
+    env: config.env,
+    partner: new PartnerConfiguration(config.partner),
+    getProvider: async key => {
+      const getter = getProviderGetter(config.providers, key);
+      if (!getter) return undefined;
+      return getter();
+    },
+    solana,
+  };
+}
+
+/**
+ * Solana Actions
+ *
+ * Actions are lazy-loaded - the solana module is only required when
+ * an action is actually called.
+ */
+export class SolanaActions {
+  private _ctx: SolanaCoreContext | null = null;
+
+  constructor(private readonly config: LombardConfig) {}
+
+  private get ctx(): SolanaCoreContext {
+    if (!this._ctx) {
+      this._ctx = createSolanaCoreContext(this.config);
+    }
+    return this._ctx;
+  }
+
+  /**
+   * Unstake LBTC → BTC
+   *
+   * Burns LBTC on Solana and releases BTC on Bitcoin.
+   *
+   * @throws LombardError if solana module is not registered
+   */
+  unstake(params: SolanaUnstakeParams): ISolanaUnstake {
+    return new SolanaUnstake(this.ctx, params);
+  }
+}
+
+/**
+ * Create Solana actions from config
+ */
+export function solanaActions(config: LombardConfig): SolanaActions {
+  return new SolanaActions(config);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Solana Actions
+ *
+ * @module chains/solana/actions
+ */
+
+export * from './unstake';