@lombard.finance/sdk 3.7.4 → 4.0.0

package/src/shared/actions/__tests__/BaseAction.test.ts

@@ -0,0 +1,292 @@
+/**
+ * Tests for BaseAction abstract class
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import type { StrategyProgress } from '../../../core/types';
+import { ErrorCode, LombardError } from '../../errors';
+import { DepositEvent, type DepositEventMap } from '../../events';
+import { BaseAction } from '../BaseAction';
+
+// Concrete implementation for testing
+class TestAction extends BaseAction<DepositEventMap, string> {
+  constructor() {
+    super('idle');
+  }
+
+  // Expose protected methods for testing
+  public testEmitProgress(progress: StrategyProgress<string>): void {
+    this.emitProgress(progress);
+  }
+
+  public testUpdateStatus(status: string): void {
+    this.updateStatus(status);
+  }
+
+  public testEmitCompleted(): void {
+    this.updateStatus('completed');
+    this.emitCompleted();
+  }
+
+  public testEmitFailed(): void {
+    this.updateStatus('failed');
+    this.emitFailed();
+  }
+
+  public testEmitError(error: LombardError): void {
+    this._error = error;
+    this.emitError(error);
+  }
+
+  public testAssertStatus(expected: string | string[], action: string): void {
+    this.assertStatus(expected, action);
+  }
+
+  public testGuard<T>(fn: () => Promise<T>): Promise<T> {
+    return this.act(fn);
+  }
+
+  public testIsFailed(): boolean {
+    return this.isFailed;
+  }
+
+  public testClearError(): void {
+    this.clearError();
+  }
+
+  public testClear(): void {
+    this.clearListeners();
+  }
+}
+
+describe('BaseAction', () => {
+  it('should create an action with initial state', () => {
+    const action = new TestAction();
+    expect(action.status).toBe('idle');
+    expect(action.error).toBeNull();
+  });
+
+  it('should register and call progress handlers', () => {
+    const action = new TestAction();
+    const handler = vi.fn();
+
+    action.on(DepositEvent.Progress, handler);
+    action.testEmitProgress({
+      status: 'executing',
+      steps: { approval: 'complete' },
+    });
+
+    expect(handler).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledWith({
+      status: 'executing',
+      steps: { approval: 'complete' },
+    });
+  });
+
+  it('should register and call status change handlers', () => {
+    const action = new TestAction();
+    const handler = vi.fn();
+
+    action.on(DepositEvent.StatusChange, handler);
+    action.testUpdateStatus('ready');
+
+    expect(handler).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledWith('ready');
+  });
+
+  it('should register and call completed handlers', () => {
+    const action = new TestAction();
+    const handler = vi.fn();
+
+    action.on(DepositEvent.Completed, handler);
+    action.testEmitCompleted();
+
+    expect(handler).toHaveBeenCalledOnce();
+  });
+
+  it('should register and call failed handlers', () => {
+    const action = new TestAction();
+    const handler = vi.fn();
+
+    action.on(DepositEvent.Failed, handler);
+    action.testEmitFailed();
+
+    expect(handler).toHaveBeenCalledOnce();
+  });
+
+  it('should register and call error handlers', () => {
+    const action = new TestAction();
+    const handler = vi.fn();
+    const error = new LombardError(ErrorCode.UNKNOWN_ERROR, 'Test error');
+
+    action.on(DepositEvent.Error, handler);
+    action.testEmitError(error);
+
+    expect(handler).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledWith(error);
+    expect(action.error).toBe(error);
+  });
+
+  it('should return unsubscribe function from on()', () => {
+    const action = new TestAction();
+    const handler = vi.fn();
+
+    const unsubscribe = action.on(DepositEvent.Progress, handler);
+    expect(typeof unsubscribe).toBe('function');
+
+    unsubscribe();
+    action.testEmitProgress({ status: 'ready', steps: {} });
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('should support multiple handlers for same event', () => {
+    const action = new TestAction();
+    const handler1 = vi.fn();
+    const handler2 = vi.fn();
+
+    action.on(DepositEvent.Completed, handler1);
+    action.on(DepositEvent.Completed, handler2);
+    action.testEmitCompleted();
+
+    expect(handler1).toHaveBeenCalledOnce();
+    expect(handler2).toHaveBeenCalledOnce();
+  });
+
+  it('should clear all listeners', () => {
+    const action = new TestAction();
+    const progressHandler = vi.fn();
+    const statusHandler = vi.fn();
+    const completedHandler = vi.fn();
+
+    action.on(DepositEvent.Progress, progressHandler);
+    action.on(DepositEvent.StatusChange, statusHandler);
+    action.on(DepositEvent.Completed, completedHandler);
+
+    action.testClear();
+
+    action.testEmitProgress({ status: 'ready', steps: {} });
+    action.testUpdateStatus('ready');
+    action.testEmitCompleted();
+
+    expect(progressHandler).not.toHaveBeenCalled();
+    expect(statusHandler).not.toHaveBeenCalled();
+    expect(completedHandler).not.toHaveBeenCalled();
+  });
+
+  it('should maintain status property', () => {
+    const action = new TestAction();
+    expect(action.status).toBe('idle');
+
+    action.testUpdateStatus('preparing');
+    expect(action.status).toBe('preparing');
+
+    action.testEmitCompleted();
+    expect(action.status).toBe('completed');
+  });
+
+  it('should maintain error property', () => {
+    const action = new TestAction();
+    expect(action.error).toBeNull();
+
+    const error = new LombardError(ErrorCode.UNKNOWN_ERROR, 'Test error');
+    action.testEmitError(error);
+    expect(action.error).toBe(error);
+  });
+
+  it('should handle multiple emissions correctly', () => {
+    const action = new TestAction();
+    const handler = vi.fn();
+
+    action.on(DepositEvent.Progress, handler);
+
+    action.testEmitProgress({ status: 'preparing', steps: {} });
+    action.testEmitProgress({ status: 'ready', steps: {} });
+    action.testEmitProgress({ status: 'executing', steps: {} });
+
+    expect(handler).toHaveBeenCalledTimes(3);
+  });
+
+  describe('assertStatus', () => {
+    it('should pass when status matches single expected', () => {
+      const action = new TestAction();
+      expect(() => action.testAssertStatus('idle', 'test')).not.toThrow();
+    });
+
+    it('should pass when status matches one of expected array', () => {
+      const action = new TestAction();
+      expect(() =>
+        action.testAssertStatus(['idle', 'ready'], 'test'),
+      ).not.toThrow();
+    });
+
+    it('should throw when status does not match', () => {
+      const action = new TestAction();
+      expect(() => action.testAssertStatus('ready', 'test')).toThrow();
+    });
+  });
+
+  describe('act', () => {
+    it('should return result on success', async () => {
+      const action = new TestAction();
+      const result = await action.testGuard(async () => 'success');
+      expect(result).toBe('success');
+    });
+
+    it('should preserve status on failure and set error', async () => {
+      const action = new TestAction();
+      const handler = vi.fn();
+      action.on(DepositEvent.Failed, handler);
+
+      // Set status to 'preparing' before the failure
+      action.testUpdateStatus('preparing');
+
+      await expect(
+        action.testGuard(async () => {
+          throw new Error('test error');
+        }),
+      ).rejects.toThrow();
+
+      // Status should be preserved at 'preparing' (NOT changed to 'failed')
+      expect(action.status).toBe('preparing');
+      expect(action.error).not.toBeNull();
+      expect(action.testIsFailed()).toBe(true);
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('should clear error on retry', async () => {
+      const action = new TestAction();
+
+      // First call fails
+      await expect(
+        action.testGuard(async () => {
+          throw new Error('test error');
+        }),
+      ).rejects.toThrow();
+
+      expect(action.error).not.toBeNull();
+      expect(action.testIsFailed()).toBe(true);
+
+      // Second call succeeds - error should be cleared
+      const result = await action.testGuard(async () => 'success');
+      expect(result).toBe('success');
+      expect(action.error).toBeNull();
+      expect(action.testIsFailed()).toBe(false);
+    });
+  });
+
+  describe('isFailed', () => {
+    it('should return false when no error', () => {
+      const action = new TestAction();
+      expect(action.testIsFailed()).toBe(false);
+    });
+
+    it('should return true when error is set', () => {
+      const action = new TestAction();
+      const error = new LombardError(ErrorCode.UNKNOWN_ERROR, 'Test error');
+      action.testEmitError(error);
+      expect(action.testIsFailed()).toBe(true);
+    });
+  });
+});

package/src/shared/actions/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared Actions
+ *
+ * Base classes and interfaces for action implementations.
+ *
+ * @module shared/actions
+ */
+
+export { BaseAction, type MonitorableAction } from './BaseAction';

package/src/shared/constants/statusConstants.ts

@@ -0,0 +1,108 @@
+/**
+ * Status constants for all action types
+ *
+ * These constants replace magic strings throughout the codebase
+ * and provide type-safe status values.
+ *
+ * ## Error Design
+ *
+ * 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`
+ *
+ * When an error occurs, status stays at the step where it happened.
+ * This allows:
+ * 1. Knowing WHERE the error occurred (status tells you)
+ * 2. Easy retry - just call the method again
+ * 3. Simpler state machine - status only flows forward
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BTC Actions - Unified Status
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Unified BTC Action Status
+ *
+ * Single source of truth for all BTC action statuses.
+ * All BTC actions (Stake, Deposit, StakeAndDeploy, DepositAndDeploy) use this.
+ *
+ * Status represents "what step are you at" - no transitional statuses.
+ * Use `isLoading` for operation-in-progress state.
+ *
+ * ## Flow Examples
+ *
+ * **BtcStake/BtcDeposit (to Ethereum):**
+ * IDLE → NEEDS_FEE_AUTHORIZATION → READY → ADDRESS_READY
+ *
+ * **BtcStake/BtcDeposit (to non-Ethereum):**
+ * IDLE → NEEDS_ADDRESS_CONFIRMATION → READY → ADDRESS_READY
+ *
+ * **BtcStakeAndDeploy/BtcDepositAndDeploy:**
+ * IDLE → NEEDS_DEPLOY_AUTHORIZATION → READY → ADDRESS_READY
+ */
+export const BtcActionStatus = {
+  /** Initial state - ready for prepare() */
+  IDLE: 'idle',
+
+  // Authorization states (mutually exclusive - action uses one based on config)
+  /** User needs to sign fee authorization (EVM stake/deposit to Ethereum) */
+  NEEDS_FEE_AUTHORIZATION: 'needs_fee_authorization',
+  /** User needs to confirm destination address (non-Ethereum destinations) */
+  NEEDS_ADDRESS_CONFIRMATION: 'needs_address_confirmation',
+  /** User needs to sign vault deploy authorization (stake-and-deploy, deposit-and-deploy) */
+  NEEDS_DEPLOY_AUTHORIZATION: 'needs_deploy_authorization',
+
+  /** Authorization complete - ready to generate address */
+  READY: 'ready',
+
+  /** Deposit address generated - awaiting BTC deposit */
+  ADDRESS_READY: 'address_ready',
+} as const;
+
+export type BtcActionStatus =
+  (typeof BtcActionStatus)[keyof typeof BtcActionStatus];
+
+/**
+ * EVM operation statuses (Deposit, Stake, Deploy, Unstake, Redeem)
+ *
+ * Simplified - use isLoading for operation-in-progress.
+ *
+ * ## Flow Examples
+ *
+ * **EVM Unstake (LBTC → BTC.b on Ethereum/Sepolia):**
+ * IDLE → NEEDS_FEE_AUTHORIZATION → READY → COMPLETED
+ *
+ * **EVM Unstake (LBTC → BTC.b on Base/BSC - subsidized):**
+ * IDLE → READY → COMPLETED
+ *
+ * **EVM Redeem (BTC.b → BTC on Ethereum/Sepolia):**
+ * IDLE → NEEDS_FEE_AUTHORIZATION → READY → COMPLETED
+ */
+export const EvmOperationStatus = {
+  IDLE: 'idle',
+  /** User needs to sign fee authorization (Ethereum/Sepolia only) */
+  NEEDS_FEE_AUTHORIZATION: 'needs_fee_authorization',
+  /** User needs to approve token spending */
+  NEEDS_APPROVAL: 'needs-approval',
+  READY: 'ready',
+  CONFIRMING: 'confirming',
+  COMPLETED: 'completed',
+} as const;
+
+export type EvmOperationStatus =
+  (typeof EvmOperationStatus)[keyof typeof EvmOperationStatus];
+
+/**
+ * Solana/Sui/Starknet Unstake operation statuses
+ */
+export const NonEvmUnstakeStatus = {
+  IDLE: 'idle',
+  READY: 'ready',
+  CONFIRMING: 'confirming',
+  COMPLETED: 'completed',
+} as const;
+
+export type NonEvmUnstakeStatus =
+  (typeof NonEvmUnstakeStatus)[keyof typeof NonEvmUnstakeStatus];

package/src/shared/context/ContextBuilder.ts

@@ -0,0 +1,149 @@
+/**
+ * Context Builder
+ *
+ * Builds lightweight action contexts from LombardConfig.
+ * Contexts are passed to actions instead of the full SDK instance,
+ * improving testability and reducing coupling.
+ *
+ * NOTE: All context creation now works from config only.
+ * The SDK class should pass this.config when creating actions.
+ *
+ * @module shared/context/ContextBuilder
+ */
+
+import type {
+  ApiService,
+  BtcService,
+  EvmService,
+  ProviderKey,
+} from '@lombard.finance/sdk-common';
+
+import { PartnerConfiguration } from '../../client/PartnerConfiguration';
+// Note: EvmService is imported for createEvmCoreContext
+import type { LombardConfig } from '../../config/types';
+import { getProviderGetter } from '../../config/types';
+import { CapabilityRegistry } from '../../modules/CapabilityRegistry';
+import type {
+  BtcCoreContext,
+  CoreContext,
+  EvmCoreContext,
+  ProviderResolver,
+} from './types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Provider Resolution
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create a provider resolver from config
+ */
+function createProviderResolver(config: LombardConfig): ProviderResolver {
+  return async key => {
+    const getter = getProviderGetter(config.providers, key as ProviderKey);
+    if (!getter) {
+      return undefined;
+    }
+    return getter();
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Capability Registry Cache
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Cache capability registries by config to avoid recreating them
+const registryCache = new WeakMap<LombardConfig, CapabilityRegistry>();
+
+/**
+ * Get or create capability registry from config
+ * @internal
+ */
+function getCapabilityRegistry(config: LombardConfig): CapabilityRegistry {
+  let registry = registryCache.get(config);
+  if (!registry) {
+    registry = new CapabilityRegistry(config.modules, config);
+    registryCache.set(config, registry);
+  }
+  return registry;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Context Factories
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create core context from config
+ * @internal
+ */
+function createCoreContext(config: LombardConfig): CoreContext {
+  return {
+    env: config.env,
+    partner: new PartnerConfiguration(config.partner),
+    getProvider: createProviderResolver(config),
+    logger: undefined,
+  };
+}
+
+/**
+ * Create BTC core context from config
+ *
+ * Used by BtcActions and BTC factory functions.
+ *
+ * @example
+ * ```typescript
+ * // In BtcActions
+ * constructor(config: LombardConfig) {
+ *   this.ctx = createBtcCoreContext(config);
+ * }
+ *
+ * // Or directly for factory functions
+ * const stake = btcStake(config, params);
+ * ```
+ */
+export function createBtcCoreContext(config: LombardConfig): BtcCoreContext {
+  const baseContext = createCoreContext(config);
+  const registry = getCapabilityRegistry(config);
+
+  // Type assertions needed because registry doesn't know module types at compile time
+  const btc = registry.require('btc') as BtcService;
+  const api = registry.require('api') as ApiService;
+
+  return {
+    ...baseContext,
+    btc,
+    api,
+    capabilities: registry,
+  };
+}
+
+/**
+ * Create EVM core context from config
+ *
+ * Used by EvmActions and EVM factory functions.
+ */
+export function createEvmCoreContext(config: LombardConfig): EvmCoreContext {
+  const baseContext = createCoreContext(config);
+  const registry = getCapabilityRegistry(config);
+
+  // Type assertion needed because registry doesn't know module types at compile time
+  const evm = registry.require('evm') as EvmService;
+
+  return {
+    ...baseContext,
+    evm,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Legacy Exports (for backward compatibility during migration)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * @deprecated Use createBtcCoreContext(config) instead
+ */
+export const createBtcCoreContextFromConfig = createBtcCoreContext;
+
+/**
+ * @deprecated Use createEvmCoreContext(config) instead
+ */
+export const createEvmCoreContextFromConfig = createEvmCoreContext;

package/src/shared/context/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Strategy Context System
+ *
+ * Exports context types and builder functions for dependency injection.
+ */
+
+export * from './ContextBuilder';
+export * from './types';