@lombard.finance/sdk 3.7.4 → 4.0.0

package/src/shared/evm/switchChain.ts

@@ -0,0 +1,109 @@
+/**
+ * EVM Chain Switching Utility
+ *
+ * Helper to ensure wallet is on the correct chain before signing.
+ * Uses EIP-3326 (wallet_switchEthereumChain) and EIP-3085 (wallet_addEthereumChain).
+ *
+ * @module shared/evm/switchChain
+ */
+
+import type { EIP1193Provider } from 'viem';
+
+import { addChain, type ChainId } from '../../common/chains';
+import { LombardError, ValidationErrorCode } from '../errors';
+
+/**
+ * Request to switch wallet to the target chain
+ * If chain is not available, attempts to add it first.
+ *
+ * @param provider - EIP-1193 provider
+ * @param targetChainId - Chain ID to switch to
+ * @throws LombardError if chain switching fails
+ */
+export async function requestChainSwitch(
+  provider: EIP1193Provider,
+  targetChainId: ChainId,
+): Promise<void> {
+  try {
+    await provider.request({
+      method: 'wallet_switchEthereumChain',
+      params: [{ chainId: `0x${targetChainId.toString(16)}` }],
+    });
+  } catch (error) {
+    const err = error as { code?: number; message?: string };
+
+    // 4902 = chain not added - try to add it automatically
+    if (err.code === 4902) {
+      try {
+        await addChain({ provider, chainId: targetChainId });
+        // After adding, try to switch again
+        await provider.request({
+          method: 'wallet_switchEthereumChain',
+          params: [{ chainId: `0x${targetChainId.toString(16)}` }],
+        });
+        return;
+      } catch (addError) {
+        const addErr = addError as { code?: number; message?: string };
+
+        // User rejected adding chain
+        if (addErr.code === 4001) {
+          throw new LombardError(
+            ValidationErrorCode.INVALID_PARAMETER,
+            'User rejected adding chain to wallet.',
+          );
+        }
+
+        throw new LombardError(
+          ValidationErrorCode.INVALID_CHAIN,
+          `Failed to add chain ${targetChainId} to wallet: ${addErr.message || 'Unknown error'}`,
+        );
+      }
+    }
+
+    // User rejected
+    if (err.code === 4001) {
+      throw new LombardError(
+        ValidationErrorCode.INVALID_PARAMETER,
+        'User rejected chain switch request.',
+      );
+    }
+
+    throw new LombardError(
+      ValidationErrorCode.INVALID_CHAIN,
+      `Failed to switch to chain ${targetChainId}: ${err.message || 'Unknown error'}`,
+    );
+  }
+}
+
+/**
+ * Get current chain ID from wallet
+ *
+ * @param provider - EIP-1193 provider
+ * @returns Current chain ID as number
+ */
+export async function getCurrentChainId(
+  provider: EIP1193Provider,
+): Promise<number> {
+  const chainIdHex = (await provider.request({
+    method: 'eth_chainId',
+  })) as string;
+  return parseInt(chainIdHex, 16);
+}
+
+/**
+ * Ensure wallet is on the correct chain, switching if necessary
+ *
+ * @param provider - EIP-1193 provider
+ * @param targetChainId - Required chain ID
+ * @throws LombardError if chain switching fails
+ */
+export async function ensureCorrectChain(
+  provider: EIP1193Provider,
+  targetChainId: ChainId,
+): Promise<void> {
+  const currentChainId = await getCurrentChainId(provider);
+
+  if (currentChainId !== targetChainId) {
+    await requestChainSwitch(provider, targetChainId);
+  }
+}

package/src/shared/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared utilities for the Lombard SDK
+ *
+ * This module exports events, errors, monitoring utilities, and validation schemas.
+ * For types like Chain, AssetId, etc., import from '@lombard.finance/sdk/core'.
+ */
+
+// Events
+export * from './events';
+
+// Errors
+export * from './errors';
+
+// Deposit utilities
+export {
+  calcConfirmations,
+  type ConfirmationProgress,
+  depositRequiresAction,
+  type DepositStatus,
+  type DepositStatusDisplay,
+  getConfirmationProgress,
+  getDepositStatus,
+  getDepositStatusDisplay,
+  isDepositClaimable,
+  isDepositPending,
+  isDepositTerminal,
+  MIN_CLAIM_AMOUNT_BTC,
+  REQUIRED_CONFIRMATIONS,
+  type StatusSeverity,
+} from './deposits';
+
+// Monitoring utilities
+export {
+  createPollingMonitor,
+  type DepositInfo,
+  monitorDeposit,
+  type MonitorOptions,
+  type MonitorProgress,
+} from './monitoring';
+
+// Validation schemas (selective exports for public API)
+export {
+  addressSchemasByChainType,
+  bitcoinAddressSchema,
+  // Schemas
+  btcAmountSchema,
+  evmAddressSchema,
+  solanaAddressSchema,
+  starknetAddressSchema,
+  suiAddressSchema,
+  // Helpers
+  validate,
+  validateOrThrow,
+} from './validation';

package/src/shared/monitoring/__tests__/createEventEmitter.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Tests for strongly-typed event emitter factory
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import type { StrategyProgress } from '../../../core/types';
+import { DepositEvent, type DepositEventMap } from '../../events';
+import { createEventEmitter } from '../createEventEmitter';
+
+describe('createEventEmitter', () => {
+  it('should create an event emitter', () => {
+    const emitter = createEventEmitter<DepositEventMap>();
+    expect(emitter).toBeDefined();
+    expect(typeof emitter.on).toBe('function');
+    expect(typeof emitter.emit).toBe('function');
+    expect(typeof emitter.off).toBe('function');
+    expect(typeof emitter.clear).toBe('function');
+  });
+
+  it('should register and call event handlers', () => {
+    const emitter = createEventEmitter<DepositEventMap>();
+    const handler = vi.fn();
+
+    emitter.on(DepositEvent.StatusChange, handler);
+    emitter.emit(DepositEvent.StatusChange, 'ready');
+
+    expect(handler).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledWith('ready');
+  });
+
+  it('should support multiple handlers for same event', () => {
+    const emitter = createEventEmitter<DepositEventMap>();
+    const handler1 = vi.fn();
+    const handler2 = vi.fn();
+
+    emitter.on(DepositEvent.Completed, handler1);
+    emitter.on(DepositEvent.Completed, handler2);
+    emitter.emit(DepositEvent.Completed);
+
+    expect(handler1).toHaveBeenCalledOnce();
+    expect(handler2).toHaveBeenCalledOnce();
+  });
+
+  it('should remove specific handler with off()', () => {
+    const emitter = createEventEmitter<DepositEventMap>();
+    const handler1 = vi.fn();
+    const handler2 = vi.fn();
+
+    const unsub1 = emitter.on(DepositEvent.Completed, handler1);
+    emitter.on(DepositEvent.Completed, handler2);
+
+    unsub1(); // Remove first handler
+    emitter.emit(DepositEvent.Completed);
+
+    expect(handler1).not.toHaveBeenCalled();
+    expect(handler2).toHaveBeenCalledOnce();
+  });
+
+  it('should remove handler with returned unsubscribe function', () => {
+    const emitter = createEventEmitter<DepositEventMap>();
+    const handler = vi.fn();
+
+    const unsubscribe = emitter.on(DepositEvent.StatusChange, handler);
+    unsubscribe();
+    emitter.emit(DepositEvent.StatusChange, 'ready');
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('should clear all handlers', () => {
+    const emitter = createEventEmitter<DepositEventMap>();
+    const handler1 = vi.fn();
+    const handler2 = vi.fn();
+    const handler3 = vi.fn();
+
+    emitter.on(DepositEvent.StatusChange, handler1);
+    emitter.on(DepositEvent.Completed, handler2);
+    emitter.on(DepositEvent.Progress, handler3);
+
+    emitter.clear();
+
+    emitter.emit(DepositEvent.StatusChange, 'ready');
+    emitter.emit(DepositEvent.Completed);
+    emitter.emit(DepositEvent.Progress, { status: 'ready', steps: {} });
+
+    expect(handler1).not.toHaveBeenCalled();
+    expect(handler2).not.toHaveBeenCalled();
+    expect(handler3).not.toHaveBeenCalled();
+  });
+
+  it('should handle progress events with correct types', () => {
+    const emitter = createEventEmitter<DepositEventMap>();
+    const handler = vi.fn((progress: StrategyProgress<string>) => {
+      expect(progress.status).toBeDefined();
+      expect(progress.steps).toBeDefined();
+    });
+
+    emitter.on(DepositEvent.Progress, handler);
+    emitter.emit(DepositEvent.Progress, {
+      status: 'executing',
+      steps: {
+        approval: 'complete',
+        execution: 'pending',
+      },
+      confirmations: 2,
+      requiredConfirmations: 6,
+    });
+
+    expect(handler).toHaveBeenCalledOnce();
+  });
+
+  it('should not throw if emitting with no handlers', () => {
+    const emitter = createEventEmitter<DepositEventMap>();
+
+    expect(() => {
+      emitter.emit(DepositEvent.Completed);
+      emitter.emit(DepositEvent.StatusChange, 'ready');
+    }).not.toThrow();
+  });
+
+  it('should handle handler errors gracefully', () => {
+    // Mock console.error to suppress expected error output
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const emitter = createEventEmitter<DepositEventMap>();
+    const errorHandler = vi.fn(() => {
+      throw new Error('Handler error');
+    });
+    const normalHandler = vi.fn();
+
+    emitter.on(DepositEvent.Completed, errorHandler);
+    emitter.on(DepositEvent.Completed, normalHandler);
+
+    // Should not throw and should still call other handlers
+    expect(() => {
+      emitter.emit(DepositEvent.Completed);
+    }).not.toThrow();
+
+    expect(errorHandler).toHaveBeenCalled();
+    expect(normalHandler).toHaveBeenCalled();
+    // Verify error was logged
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Error in event handler for "completed":',
+      expect.any(Error),
+    );
+
+    consoleSpy.mockRestore();
+  });
+});

package/src/shared/monitoring/createEventEmitter.ts

@@ -0,0 +1,160 @@
+/**
+ * Strongly-typed event emitter factory
+ *
+ * Creates lightweight event emitters with full TypeScript type safety.
+ * Unlike EventEmitter3, this implementation:
+ * - Is specifically tailored for strategy events
+ * - Has minimal overhead
+ * - Provides perfect type inference
+ * - Handles errors gracefully
+ */
+
+/**
+ * Event handler function type
+ */
+export type EventHandler<TArgs extends unknown[] = unknown[]> = (
+  ...args: TArgs
+) => void;
+
+/**
+ * Event emitter interface
+ */
+export interface EventEmitter<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Event emitter requires bivariant `any` for generic event handler constraint
+  TEventMap extends Record<string, EventHandler<any>>,
+> {
+  /**
+   * Register an event handler
+   *
+   * @param event - Event name
+   * @param handler - Handler function
+   * @returns Unsubscribe function
+   */
+  on<TEvent extends keyof TEventMap>(
+    event: TEvent,
+    handler: TEventMap[TEvent],
+  ): () => void;
+
+  /**
+   * Emit an event to all registered handlers
+   *
+   * @param event - Event name
+   * @param data - Event data (if any)
+   */
+  emit<TEvent extends keyof TEventMap>(
+    event: TEvent,
+    ...args: Parameters<TEventMap[TEvent]>
+  ): void;
+
+  /**
+   * Remove a specific event handler
+   *
+   * @param event - Event name
+   * @param handler - Handler function to remove
+   */
+  off<TEvent extends keyof TEventMap>(
+    event: TEvent,
+    handler: TEventMap[TEvent],
+  ): void;
+
+  /**
+   * Clear all event handlers
+   */
+  clear(): void;
+}
+
+/**
+ * Create a strongly-typed event emitter
+ *
+ * @returns Event emitter instance
+ *
+ * @example
+ * ```typescript
+ * const emitter = createEventEmitter<DepositEventMap>();
+ *
+ * // Register handler
+ * const unsubscribe = emitter.on(DepositEvent.Progress, (progress) => {
+ *   console.log(progress.status);
+ * });
+ *
+ * // Emit event
+ * emitter.emit(DepositEvent.Progress, { status: 'ready', steps: {} });
+ *
+ * // Unsubscribe
+ * unsubscribe();
+ * ```
+ */
+export function createEventEmitter<
+  TEventMap extends Record<string, EventHandler>,
+>(): EventEmitter<TEventMap> {
+  // Store handlers in a Map for efficient lookup
+  const handlers = new Map<keyof TEventMap, Set<EventHandler>>();
+
+  return {
+    on<TEvent extends keyof TEventMap>(
+      event: TEvent,
+      handler: TEventMap[TEvent],
+    ): () => void {
+      // Get or create handler set for this event
+      let eventHandlers = handlers.get(event);
+      if (!eventHandlers) {
+        eventHandlers = new Set();
+        handlers.set(event, eventHandlers);
+      }
+
+      // Add handler
+      eventHandlers.add(handler as EventHandler);
+
+      // Return unsubscribe function
+      return () => {
+        eventHandlers?.delete(handler as EventHandler);
+        // Clean up empty sets
+        if (eventHandlers && eventHandlers.size === 0) {
+          handlers.delete(event);
+        }
+      };
+    },
+
+    emit<TEvent extends keyof TEventMap>(
+      event: TEvent,
+      ...args: Parameters<TEventMap[TEvent]>
+    ): void {
+      const eventHandlers = handlers.get(event);
+      if (!eventHandlers || eventHandlers.size === 0) {
+        return;
+      }
+
+      // Call all handlers for this event
+      // Wrap in try-catch to prevent one handler from breaking others
+      for (const handler of eventHandlers) {
+        try {
+          handler(...args);
+        } catch (error) {
+          // Log error but don't throw - one handler failing shouldn't break others
+          console.error(
+            `Error in event handler for "${String(event)}":`,
+            error,
+          );
+        }
+      }
+    },
+
+    off<TEvent extends keyof TEventMap>(
+      event: TEvent,
+      handler: TEventMap[TEvent],
+    ): void {
+      const eventHandlers = handlers.get(event);
+      if (eventHandlers) {
+        eventHandlers.delete(handler as EventHandler);
+        // Clean up empty sets
+        if (eventHandlers.size === 0) {
+          handlers.delete(event);
+        }
+      }
+    },
+
+    clear(): void {
+      handlers.clear();
+    },
+  };
+}

package/src/shared/monitoring/createProgressEmitter.ts

@@ -0,0 +1,46 @@
+/**
+ * Progress Emitter Utility
+ *
+ * Creates a lightweight event emitter for progress updates.
+ * Used by strategy implementations to notify listeners of state changes.
+ */
+
+export interface ProgressEmitter<T> {
+  subscribe(callback: (progress: T) => void): () => void;
+  emit(progress: T): void;
+  clear(): void;
+}
+
+/**
+ * Creates a progress emitter
+ *
+ * @returns ProgressEmitter instance with subscribe, emit, and clear methods
+ */
+export function createProgressEmitter<T>(): ProgressEmitter<T> {
+  const listeners = new Set<(progress: T) => void>();
+
+  return {
+    subscribe(callback: (progress: T) => void): () => void {
+      listeners.add(callback);
+
+      // Return unsubscribe function
+      return () => {
+        listeners.delete(callback);
+      };
+    },
+
+    emit(progress: T): void {
+      for (const listener of listeners) {
+        try {
+          listener(progress);
+        } catch (error) {
+          console.error('Error in progress listener:', error);
+        }
+      }
+    },
+
+    clear(): void {
+      listeners.clear();
+    },
+  };
+}