@lombard.finance/sdk 4.0.0 → 4.1.2

package/src/shared/context/types.ts

@@ -1,156 +0,0 @@
-/**
- * Strategy Context Types
- *
- * Defines the lightweight context objects passed to strategies instead of the full SDK.
- * This improves testability, reduces coupling, and makes dependencies explicit.
- *
- * Architecture:
- * - CoreContext = What ALL strategies of a source chain need (env, partner, chain service)
- * - Destination = What strategies need for their destination chain (injected by namespace)
- */
-
-import type {
-  ApiService,
-  BtcService,
-  Env,
-  EvmService,
-  SolanaService,
-  StarknetService,
-  SuiService,
-} from '@lombard.finance/sdk-common';
-// Note: EvmService is still imported for EvmCoreContext and EvmDestination
-import type { EIP1193Provider } from 'viem';
-
-import type { PartnerConfiguration } from '../../client/PartnerConfiguration';
-import type { CapabilityRegistry } from '../../modules/CapabilityRegistry';
-
-// ============ Logger ============
-
-/**
- * Logger interface for strategy operations
- */
-export interface Logger {
-  debug(message: string, meta?: Record<string, unknown>): void;
-  info(message: string, meta?: Record<string, unknown>): void;
-  warn(message: string, meta?: Record<string, unknown>): void;
-  error(message: string, meta?: Record<string, unknown>): void;
-}
-
-// ============ Provider Resolution ============
-
-/**
- * Provider key for chain-specific wallet providers
- */
-export type ProviderKey = 'bitcoin' | 'evm' | 'solana' | 'sui' | 'starknet';
-
-/**
- * Provider resolver function
- * Lazily resolves chain-specific wallet providers
- */
-export type ProviderResolver = (
-  key: ProviderKey,
-) => Promise<EIP1193Provider | unknown>;
-
-// ============ Core Contexts (Source Chain) ============
-
-/**
- * Base Core Context
- *
- * Minimal context shared by ALL strategies, regardless of chain.
- * Contains only environment, partner config, and provider resolution.
- *
- * TODO (v4.1): Add `catalog: AssetCatalog` field for remote catalog support.
- * See: docs/ADDRESS_SYSTEM_UNIFICATION.md
- */
-export interface CoreContext {
-  readonly env: Env;
-  readonly partner: PartnerConfiguration;
-  readonly getProvider: ProviderResolver;
-  readonly logger?: Logger;
-  // TODO (v4.1): readonly catalog: AssetCatalog;
-}
-
-/**
- * BTC Core Context
- *
- * What ALL Bitcoin strategies need (source chain operations).
- * Includes BTC service, API service, and capabilities registry.
- *
- * Note: Chain-specific destination services (EVM, Solana, etc.) are accessed
- * via capabilities.require('evm') when needed by chain configs.
- */
-export interface BtcCoreContext extends CoreContext {
-  readonly btc: BtcService;
-  readonly api: ApiService;
-  readonly capabilities: CapabilityRegistry;
-}
-
-/**
- * EVM Core Context
- *
- * What ALL EVM strategies need (source chain operations).
- */
-export interface EvmCoreContext extends CoreContext {
-  readonly evm: EvmService;
-}
-
-/**
- * Solana Core Context
- *
- * What ALL Solana strategies need (source chain operations).
- */
-export interface SolanaCoreContext extends CoreContext {
-  readonly solana: SolanaService;
-}
-
-/**
- * Sui Core Context
- *
- * What ALL Sui strategies need (source chain operations).
- */
-export interface SuiCoreContext extends CoreContext {
-  readonly sui: SuiService;
-}
-
-/**
- * Starknet Core Context
- *
- * What ALL Starknet strategies need (source chain operations).
- */
-export interface StarknetCoreContext extends CoreContext {
-  readonly starknet: StarknetService;
-}
-
-// ============ Destination Services (Injected per-strategy) ============
-
-/**
- * EVM as destination chain
- * Injected into strategies that mint/send to EVM chains
- */
-export interface EvmDestination {
-  readonly evm: EvmService;
-}
-
-/**
- * Solana as destination chain
- * Injected into strategies that mint/send to Solana
- */
-export interface SolanaDestination {
-  readonly solana: SolanaService;
-}
-
-/**
- * Sui as destination chain
- * Injected into strategies that mint/send to Sui
- */
-export interface SuiDestination {
-  readonly sui: SuiService;
-}
-
-/**
- * Starknet as destination chain
- * Injected into strategies that mint/send to Starknet
- */
-export interface StarknetDestination {
-  readonly starknet: StarknetService;
-}

package/src/shared/deposits/depositStatus.ts

@@ -1,402 +0,0 @@
-/**
- * Deposit Status Utilities
- *
- * Centralized logic for determining deposit status based on notarization state,
- * confirmations, and other factors. This module provides a single source of truth
- * for deposit status that can be used by the SDK demo, apps/main, and other consumers.
- *
- * Status determination is based on both notarization status and block confirmations.
- * The notarization status from the backend is the primary source of truth for where
- * in the flow a deposit currently is.
- *
- * @module shared/deposits/depositStatus
- */
-
-import {
-  type Deposit,
-  ENotarizationStatus,
-} from '../../api-functions/getDepositsByAddress/getDepositsByAddress';
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Constants
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Number of confirmations required before a deposit can be claimed.
- * Production/Testnet: 6, Stage/Dev: 3
- */
-export const REQUIRED_CONFIRMATIONS = 6;
-
-/**
- * Minimum deposit amount that can be claimed (in BTC).
- * Deposits below this amount cannot be minted.
- */
-export const MIN_CLAIM_AMOUNT_BTC = 0.0002;
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Types
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Possible deposit statuses - ordered by lifecycle
- */
-export type DepositStatus =
-  | 'pending_confirmations' // Waiting for BTC block confirmations
-  | 'pending_notarization' // Confirmations complete, waiting for notarization service
-  | 'claimable' // Notarization approved, ready to be claimed manually
-  | 'claiming' // Claim transaction submitted
-  | 'claimed' // Successfully claimed (has claimTxHash)
-  | 'auto_claimed' // Claimed via GMP (cross-chain messaging)
-  | 'expired' // Signature expired, needs re-auth
-  | 'failed' // Notarization failed
-  | 'restricted' // Sanctioned or restricted
-  | 'too_small'; // Amount below minimum
-
-/**
- * Status severity for UI styling
- */
-export type StatusSeverity = 'info' | 'warning' | 'success' | 'error' | 'neutral';
-
-/**
- * Status display configuration
- */
-export interface DepositStatusDisplay {
-  /** Human-readable label for the status */
-  label: string;
-  /** Severity level for styling */
-  severity: StatusSeverity;
-  /** Detailed description of the status */
-  description: string;
-  /** Whether the deposit is in a terminal state (claimed, failed, restricted) */
-  isTerminal: boolean;
-  /** Whether user action is required */
-  requiresAction: boolean;
-}
-
-/**
- * Confirmation progress information
- */
-export interface ConfirmationProgress {
-  /** Current number of confirmations */
-  current: number;
-  /** Required number of confirmations */
-  required: number;
-  /** Percentage complete (0-100) */
-  percentage: number;
-  /** Whether enough confirmations have been received */
-  isComplete: boolean;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Core Functions
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Calculate the number of confirmations for a deposit
- *
- * @param currentBlockHeight - Current Bitcoin block height
- * @param depositBlockHeight - Block height where deposit was confirmed
- * @returns Number of confirmations (0 if either height is missing)
- */
-export function calcConfirmations(
-  currentBlockHeight?: number,
-  depositBlockHeight?: number,
-): number {
-  if (!depositBlockHeight || !currentBlockHeight) {
-    return 0;
-  }
-  // Deposit block height counts as the first confirmation
-  return Math.max(0, currentBlockHeight - depositBlockHeight + 1);
-}
-
-/**
- * Get confirmation progress for a deposit
- *
- * @param currentBlockHeight - Current Bitcoin block height
- * @param depositBlockHeight - Block height where deposit was confirmed
- * @param requiredConfirmations - Number of confirmations required (default: REQUIRED_CONFIRMATIONS)
- * @returns Confirmation progress info, or null if block heights unavailable
- */
-export function getConfirmationProgress(
-  currentBlockHeight?: number,
-  depositBlockHeight?: number,
-  requiredConfirmations: number = REQUIRED_CONFIRMATIONS,
-): ConfirmationProgress | null {
-  if (currentBlockHeight === undefined || depositBlockHeight === undefined) {
-    return null;
-  }
-
-  const current = calcConfirmations(currentBlockHeight, depositBlockHeight);
-  const percentage = Math.min(
-    100,
-    Math.round((current / requiredConfirmations) * 100),
-  );
-
-  return {
-    current,
-    required: requiredConfirmations,
-    percentage,
-    isComplete: current >= requiredConfirmations,
-  };
-}
-
-/**
- * Determine the status of a deposit
- *
- * Logic priority (matches apps/main useDepositState):
- * 1. Sanctioned → restricted
- * 2. Already claimed → claimed
- * 3. Amount too small → too_small
- * 4. GMP handled → auto_claimed
- * 5. Notarization failed → failed
- * 6. Based on notarization status + proof availability:
- *    - PENDING/SUBMITTED without enough confirmations → pending_confirmations
- *    - PENDING/SUBMITTED with confirmations → pending_notarization
- *    - SESSION_APPROVED with proof → claimable
- *    - SESSION_APPROVED without proof → pending_notarization (edge case)
- *
- * @param deposit - The deposit object from the SDK
- * @param currentBlockHeight - Current BTC block height (optional, enhances accuracy)
- * @param requiredConfirmations - Confirmations required (default: REQUIRED_CONFIRMATIONS)
- * @returns The deposit status
- */
-export function getDepositStatus(
-  deposit: Deposit,
-  currentBlockHeight?: number,
-  requiredConfirmations: number = REQUIRED_CONFIRMATIONS,
-): DepositStatus {
-  // 1. Check for sanctioned/restricted first
-  if (deposit.sanctioned) {
-    return 'restricted';
-  }
-
-  // 2. Check if already claimed
-  if (deposit.isClaimed || deposit.claimTxHash) {
-    return 'claimed';
-  }
-
-  // 3. Check if amount is too small
-  const amountBtc = deposit.amount?.toNumber?.() ?? Number(deposit.amount);
-  if (amountBtc > 0 && amountBtc < MIN_CLAIM_AMOUNT_BTC) {
-    return 'too_small';
-  }
-
-  // 4. Check for GMP auto-claim
-  if (
-    deposit.notarizationStatus ===
-    ENotarizationStatus.NOTARIZATION_STATUS_GMP_HANDLED
-  ) {
-    return 'auto_claimed';
-  }
-
-  // 5. Check for notarization failure
-  if (
-    deposit.notarizationStatus ===
-    ENotarizationStatus.NOTARIZATION_STATUS_FAILED
-  ) {
-    return 'failed';
-  }
-
-  // 6. Determine status based on notarization status and proof availability
-  const hasProof = !!deposit.proof && !!deposit.rawPayload;
-  const notarizationStatus = deposit.notarizationStatus;
-
-  // Check confirmations only if we have block height data
-  const confirmations = calcConfirmations(
-    currentBlockHeight,
-    deposit.blockHeight,
-  );
-  const hasEnoughConfirmations =
-    currentBlockHeight === undefined ||
-    confirmations >= requiredConfirmations;
-
-  switch (notarizationStatus) {
-    case ENotarizationStatus.NOTARIZATION_STATUS_PENDING:
-    case ENotarizationStatus.NOTARIZATION_STATUS_SUBMITTED:
-      // Still in notarization queue
-      // If we know block height and not enough confirmations, show that
-      if (currentBlockHeight !== undefined && !hasEnoughConfirmations) {
-        return 'pending_confirmations';
-      }
-      // Otherwise, we're waiting for notarization
-      return 'pending_notarization';
-
-    case ENotarizationStatus.NOTARIZATION_STATUS_SESSION_APPROVED:
-      // Notarization approved
-      if (hasProof) {
-        return 'claimable';
-      }
-      // Edge case: approved but no proof yet (should be rare)
-      return 'pending_notarization';
-
-    case ENotarizationStatus.NOTARIZATION_STATUS_UNSPECIFIED:
-    default:
-      // Unknown status - check confirmations if we can
-      if (currentBlockHeight !== undefined && !hasEnoughConfirmations) {
-        return 'pending_confirmations';
-      }
-      return 'pending_notarization';
-  }
-}
-
-/**
- * Get display configuration for a deposit status
- *
- * @param status - The deposit status
- * @returns Display configuration with label, severity, and description
- */
-export function getDepositStatusDisplay(
-  status: DepositStatus,
-): DepositStatusDisplay {
-  switch (status) {
-    case 'pending_confirmations':
-      return {
-        label: 'Pending Confirmations',
-        severity: 'warning',
-        description: `Waiting for Bitcoin block confirmations (${REQUIRED_CONFIRMATIONS} required)`,
-        isTerminal: false,
-        requiresAction: false,
-      };
-    case 'pending_notarization':
-      return {
-        label: 'Pending Notarization',
-        severity: 'info',
-        description:
-          'Confirmations complete, waiting for notarization service to generate proof',
-        isTerminal: false,
-        requiresAction: false,
-      };
-    case 'claimable':
-      return {
-        label: 'Claimable',
-        severity: 'success',
-        description: 'Ready to mint - proof available, claim to receive tokens',
-        isTerminal: false,
-        requiresAction: true,
-      };
-    case 'claiming':
-      return {
-        label: 'Claiming',
-        severity: 'info',
-        description: 'Claim transaction in progress',
-        isTerminal: false,
-        requiresAction: false,
-      };
-    case 'claimed':
-      return {
-        label: 'Claimed',
-        severity: 'neutral',
-        description: 'Tokens have been minted to your address',
-        isTerminal: true,
-        requiresAction: false,
-      };
-    case 'auto_claimed':
-      return {
-        label: 'Auto-Claimed',
-        severity: 'success',
-        description: 'Automatically claimed via cross-chain messaging (GMP)',
-        isTerminal: true,
-        requiresAction: false,
-      };
-    case 'expired':
-      return {
-        label: 'Expired',
-        severity: 'error',
-        description: 'Fee signature expired, requires re-authorization',
-        isTerminal: false,
-        requiresAction: true,
-      };
-    case 'failed':
-      return {
-        label: 'Failed',
-        severity: 'error',
-        description: 'Notarization failed - contact support',
-        isTerminal: true,
-        requiresAction: false,
-      };
-    case 'restricted':
-      return {
-        label: 'Restricted',
-        severity: 'error',
-        description: 'This deposit is restricted or sanctioned',
-        isTerminal: true,
-        requiresAction: false,
-      };
-    case 'too_small':
-      return {
-        label: 'Too Small',
-        severity: 'neutral',
-        description: `Amount below minimum claimable amount (${MIN_CLAIM_AMOUNT_BTC} BTC)`,
-        isTerminal: true,
-        requiresAction: false,
-      };
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Helper Functions
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Check if a deposit can be claimed manually
- *
- * @param deposit - The deposit object
- * @param currentBlockHeight - Current BTC block height (optional)
- * @returns True if the deposit is in claimable state
- */
-export function isDepositClaimable(
-  deposit: Deposit,
-  currentBlockHeight?: number,
-): boolean {
-  return getDepositStatus(deposit, currentBlockHeight) === 'claimable';
-}
-
-/**
- * Check if a deposit is in a pending state (confirmations or notarization)
- *
- * @param deposit - The deposit object
- * @param currentBlockHeight - Current BTC block height (optional)
- * @returns True if deposit is pending
- */
-export function isDepositPending(
-  deposit: Deposit,
-  currentBlockHeight?: number,
-): boolean {
-  const status = getDepositStatus(deposit, currentBlockHeight);
-  return (
-    status === 'pending_confirmations' || status === 'pending_notarization'
-  );
-}
-
-/**
- * Check if a deposit is in a terminal state (no further action possible)
- *
- * @param deposit - The deposit object
- * @param currentBlockHeight - Current BTC block height (optional)
- * @returns True if deposit is in terminal state
- */
-export function isDepositTerminal(
-  deposit: Deposit,
-  currentBlockHeight?: number,
-): boolean {
-  const status = getDepositStatus(deposit, currentBlockHeight);
-  const display = getDepositStatusDisplay(status);
-  return display.isTerminal;
-}
-
-/**
- * Check if a deposit requires user action
- *
- * @param deposit - The deposit object
- * @param currentBlockHeight - Current BTC block height (optional)
- * @returns True if user action is required
- */
-export function depositRequiresAction(
-  deposit: Deposit,
-  currentBlockHeight?: number,
-): boolean {
-  const status = getDepositStatus(deposit, currentBlockHeight);
-  const display = getDepositStatusDisplay(status);
-  return display.requiresAction;
-}
-

package/src/shared/deposits/index.ts

@@ -1,29 +0,0 @@
-/**
- * Deposit Utilities
- *
- * Centralized utilities for working with deposits, including status
- * determination, confirmation tracking, and display helpers.
- *
- * @module shared/deposits
- */
-
-export {
-  // Core functions
-  calcConfirmations,
-  // Types
-  type ConfirmationProgress,
-  depositRequiresAction,
-  type DepositStatus,
-  type DepositStatusDisplay,
-  getConfirmationProgress,
-  getDepositStatus,
-  getDepositStatusDisplay,
-  isDepositClaimable,
-  isDepositPending,
-  isDepositTerminal,
-  // Constants
-  MIN_CLAIM_AMOUNT_BTC,
-  REQUIRED_CONFIRMATIONS,
-  type StatusSeverity,
-} from './depositStatus';
-