@lombard.finance/sdk 3.7.3 → 4.0.0

package/src/modules/CapabilityRegistry.ts

@@ -0,0 +1,125 @@
+/**
+ * Capability Registry
+ *
+ * Manages optional module services and provides dependency injection for actions.
+ * Works exclusively with LombardConfig, never requiring the full SDK instance.
+ *
+ * @module modules/CapabilityRegistry
+ */
+
+import type {
+  AnyModule,
+  ModuleId,
+  ProviderFor,
+  ProviderKey,
+  RegisterContext,
+  SdkModule,
+  ServiceOf,
+  SharedToken,
+} from '@lombard.finance/sdk-common';
+
+import type { LombardConfig } from '../config/types';
+import { getProviderGetter } from '../config/types';
+import { LombardError } from '../shared/errors';
+
+/**
+ * Capability Registry
+ *
+ * Manages optional module services (BTC, EVM, API, Solana, Sui, Starknet, etc.)
+ * and provides lazy loading with descriptive error messages.
+ *
+ * Services are internal implementations for action DI.
+ * Public APIs should call underlying functions directly for rich types.
+ *
+ * @example
+ * ```typescript
+ * const registry = new CapabilityRegistry(config.modules, config);
+ * const btcService = registry.require('btc');
+ * const solanaService = registry.optional('solana'); // null if not installed
+ * ```
+ */
+export class CapabilityRegistry<
+  TModules extends readonly AnyModule[] = readonly AnyModule[],
+> {
+  private readonly modules = new Map<string, AnyModule>();
+  private readonly services = new Map<string, unknown>();
+  private readonly shared = new Map<SharedToken<unknown>, unknown>();
+
+  constructor(
+    modules: readonly AnyModule[],
+    private readonly config: LombardConfig,
+  ) {
+    modules.forEach(mod => this.modules.set(mod.id, mod));
+  }
+
+  /**
+   * Require a module service
+   *
+   * Throws LombardError.moduleMissing if module not installed.
+   *
+   * @param id - Module identifier
+   * @returns Module service
+   */
+  require<TId extends ModuleId<TModules[number]>>(
+    id: TId,
+  ): ServiceOf<TModules[number] & SdkModule<TId, unknown>, TId> {
+    const mod = this.modules.get(id as string);
+    if (!mod) {
+      throw LombardError.moduleMissing(id as string);
+    }
+    if (!this.services.has(mod.id)) {
+      this.services.set(mod.id, mod.register(this.createContext()));
+    }
+    return this.services.get(mod.id) as ServiceOf<
+      TModules[number] & SdkModule<TId, unknown>,
+      TId
+    >;
+  }
+
+  /**
+   * Optionally get a module service
+   *
+   * Returns null if module not installed (no error thrown).
+   *
+   * @param id - Module identifier
+   * @returns Module service or null
+   */
+  optional<TId extends ModuleId<TModules[number]>>(
+    id: TId,
+  ): ServiceOf<TModules[number] & SdkModule<TId, unknown>, TId> | null {
+    const mod = this.modules.get(id as string);
+    if (!mod) {
+      return null;
+    }
+    if (!this.services.has(mod.id)) {
+      this.services.set(mod.id, mod.register(this.createContext()));
+    }
+    return this.services.get(mod.id) as ServiceOf<
+      TModules[number] & SdkModule<TId, unknown>,
+      TId
+    >;
+  }
+
+  /**
+   * Create registration context for modules
+   *
+   * Provides modules with access to config-based services.
+   */
+  private createContext(): RegisterContext {
+    return {
+      env: this.config.env,
+      getProvider: async <TKey extends ProviderKey>(key: TKey) => {
+        const getter = getProviderGetter(this.config.providers, key);
+        if (!getter) {
+          return undefined as unknown as ProviderFor<TKey>;
+        }
+        return (await getter()) as ProviderFor<TKey>;
+      },
+      getShared: <T>(token: SharedToken<T>) =>
+        this.shared.get(token as SharedToken<unknown>) as T | undefined,
+      setShared: <T>(token: SharedToken<T>, value: T) => {
+        this.shared.set(token as SharedToken<unknown>, value);
+      },
+    };
+  }
+}

package/src/modules/apiModule.ts

@@ -0,0 +1,51 @@
+/**
+ * API Module
+ *
+ * Provides Lombard backend API service for internal use by actions.
+ * Uses Service-First pattern: module is a thin factory that instantiates the service.
+ *
+ * Note: This is an internal service for dependency injection into actions.
+ * For public APIs, use the SDK namespace methods (e.g., sdk.deposits.getByAddress())
+ * which call the underlying functions directly and return rich types.
+ *
+ * @module modules/apiModule
+ */
+
+import type {
+  ApiService as IApiService,
+  SdkModule,
+} from '@lombard.finance/sdk-common';
+
+import { ApiService } from '../services/ApiService';
+
+/**
+ * Create API module
+ *
+ * Internal module that provides ApiService. Automatically included by createLombardSDK().
+ *
+ * @example
+ * ```ts
+ * const sdk = await createLombardSDK({
+ *   env: Env.prod,
+ *   providers: { evm: () => window.ethereum },
+ * });
+ * const deposits = await sdk.api.deposits('0x...');
+ * ```
+ */
+export function apiModule(): SdkModule<'api', IApiService> {
+  return {
+    id: 'api',
+    register(ctx) {
+      return new ApiService(ctx.env);
+    },
+  };
+}
+
+// Re-export service class and interface type
+export { ApiService };
+export type { IApiService as ApiServiceInterface };
+export type {
+  DepositInfo,
+  GenerateDepositAddressParams,
+  GetDepositAddressParams,
+} from '@lombard.finance/sdk-common';

package/src/modules/btcModule.ts

@@ -0,0 +1,43 @@
+/**
+ * BTC Module
+ *
+ * Provides Bitcoin chain service for deposit monitoring and address operations.
+ * Uses Service-First pattern: module is a thin factory that instantiates the service.
+ *
+ * @module modules/btcModule
+ */
+
+import type {
+  BtcService as IBtcService,
+  ChainModule,
+} from '@lombard.finance/sdk-common';
+
+import { BtcService } from '../services/BtcService';
+
+/**
+ * Create BTC module
+ *
+ * Built-in module that provides BtcService. Automatically included by createLombardSDK().
+ *
+ * @example
+ * ```ts
+ * const sdk = await createLombardSDK({
+ *   env: Env.prod,
+ *   providers: { evm: () => window.ethereum },
+ * });
+ * const stake = sdk.chain.btc.stake({ ... });
+ * ```
+ */
+export function btcModule(): ChainModule<'btc', IBtcService> {
+  return {
+    id: 'btc',
+    chain: 'btc',
+    register() {
+      return new BtcService();
+    },
+  };
+}
+
+// Re-export service class and interface type
+export { BtcService };
+export type { IBtcService as BtcServiceInterface };

package/src/modules/evmModule.ts

@@ -0,0 +1,48 @@
+/**
+ * EVM Module
+ *
+ * Provides EVM chain service for contract interactions and fee authorization.
+ * Uses Service-First pattern: module is a thin factory that instantiates the service.
+ *
+ * @module modules/evmModule
+ */
+
+import type {
+  ChainModule,
+  EvmService as IEvmService,
+} from '@lombard.finance/sdk-common';
+
+import { EvmService } from '../services/EvmService';
+
+/**
+ * Create EVM module
+ *
+ * Built-in module that provides EvmService. Automatically included by createLombardSDK().
+ *
+ * @example
+ * ```ts
+ * const sdk = await createLombardSDK({
+ *   env: Env.prod,
+ *   providers: { evm: () => window.ethereum },
+ * });
+ * const unstake = sdk.chain.evm.unstake({ ... });
+ * ```
+ */
+export function evmModule(): ChainModule<'evm', IEvmService> {
+  return {
+    id: 'evm',
+    chain: 'evm',
+    register(ctx) {
+      return new EvmService(ctx.env);
+    },
+  };
+}
+
+// Re-export service class and interface type
+export { EvmService };
+export type { IEvmService as EvmServiceInterface };
+export type {
+  EvmChainId,
+  FeeAuthorizationResult,
+  StoredFeeSignature,
+} from '@lombard.finance/sdk-common';

package/src/modules/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Module System Exports
+ *
+ * Modules provide service implementations using the Service-First pattern:
+ * - Service interfaces define the contract (in sdk-common)
+ * - Service classes implement the interfaces (in services/)
+ * - Module factories instantiate services with context
+ *
+ * Module Types:
+ * - SdkModule: Generic module (e.g., apiModule) - for non-chain services
+ * - ChainModule: Chain-specific module (e.g., btcModule, evmModule)
+ *
+ * Service Types:
+ * - Internal services: Minimal types, for action DI (not exposed publicly)
+ * - Public APIs: Rich types, for user-facing methods (sdk.deposits.*, etc.)
+ *
+ * @module modules
+ */
+
+export { CapabilityRegistry } from './CapabilityRegistry';
+
+// BTC Module (chain-specific)
+export { btcModule, BtcService } from './btcModule';
+
+// EVM Module (chain-specific)
+export type {
+  EvmChainId,
+  FeeAuthorizationResult,
+  StoredFeeSignature,
+} from './evmModule';
+export { evmModule, EvmService } from './evmModule';
+
+// API Module (generic SDK module, not chain-specific)
+export type {
+  DepositInfo,
+  GenerateDepositAddressParams,
+  GetDepositAddressParams,
+} from './apiModule';
+export { apiModule, ApiService } from './apiModule';
+
+// Module types from sdk-common
+export type {
+  // Any module
+  AnyModule,
+  // Chain-specific module type
+  ChainModule,
+  ModuleId,
+  // Helper types
+  RegisterContext,
+  // Generic module type
+  SdkModule,
+  ServiceOf,
+} from '@lombard.finance/sdk-common';
+
+// Service interface types (from sdk-common, aliased for clarity)
+export type {
+  ApiService as IApiService,
+  BtcService as IBtcService,
+  EvmService as IEvmService,
+} from '@lombard.finance/sdk-common';

package/src/referrals/ReferralsClient.ts

@@ -0,0 +1,34 @@
+import { getDepositAddressReferrer } from '../api-functions/getDepositAddressReferrer';
+import type { LombardSDK } from '../client/LombardSDK';
+
+export interface ReferralLookupParams {
+  /** Destination account that previously generated a BTC deposit address */
+  address: string;
+}
+
+export interface ReferralLookupResult {
+  hasDepositAddress: boolean;
+  referrer?: string;
+}
+
+/**
+ * Referral helper namespace.
+ *
+ * Provides read APIs for referral metadata so partners do not need to query
+ * Lombard REST endpoints directly.
+ */
+export class ReferralsClient {
+  constructor(private readonly sdk: LombardSDK) {}
+
+  /**
+   * Fetch the referrer bound to a previously generated BTC deposit address.
+   */
+  async lookupReferrer({
+    address,
+  }: ReferralLookupParams): Promise<ReferralLookupResult> {
+    return getDepositAddressReferrer({
+      address,
+      env: this.sdk.config.env,
+    });
+  }
+}

package/src/referrals/index.ts

@@ -0,0 +1 @@
+export * from './ReferralsClient';

package/src/services/ApiService.ts

@@ -0,0 +1,152 @@
+/**
+ * API Service
+ *
+ * Provides Lombard backend API operations for internal use by actions.
+ * Returns minimal types defined in sdk-common.
+ *
+ * For public APIs with full types, use the exported functions in api-functions/
+ * or the SDK namespace methods.
+ *
+ * @module services/ApiService
+ */
+
+import type { Env } from '@lombard.finance/sdk-common';
+import type {
+  ApiService as IApiService,
+  DepositInfo,
+  FeeSignatureResult,
+  GenerateDepositAddressParams,
+  GetDepositAddressParams,
+  GetFeeSignatureParams,
+  StoreFeeSignatureParams,
+  StoreStakeAndBakeParams,
+} from '@lombard.finance/sdk-common';
+
+import { generateDepositBtcAddress } from '../api-functions/generateDepositBtcAddress/generateDepositBtcAddress';
+import { getDepositBtcAddress } from '../api-functions/getDepositBtcAddress/getDepositBtcAddress';
+import { getDepositsByAddress } from '../api-functions/getDepositsByAddress/getDepositsByAddress';
+import { getNetworkFeeSignature } from '../api-functions/getNetworkFeeSignature/getNetworkFeeSignature';
+import { storeNetworkFeeSignature } from '../api-functions/storeNetworkFeeSignature/storeNetworkFeeSignature';
+import { storeStakeAndBakeSignature } from '../api-functions/storeStakeAndBakeSignature/storeStakeAndBakeSignature';
+import type {
+  ChainId,
+  SolanaChain,
+  StarknetChainId,
+  SuiChain,
+} from '../common/chains';
+import { Token } from '../tokens/token-addresses';
+
+type DestChainId = ChainId | SolanaChain | SuiChain | StarknetChainId;
+
+/**
+ * API Service
+ *
+ * Implementation of the ApiService interface from sdk-common.
+ * Wraps low-level API functions for use by actions.
+ *
+ * @remarks
+ * This service returns minimal types (DepositInfo) suitable for internal use.
+ * For full deposit details, use getDepositsByAddress() directly.
+ */
+export class ApiService implements IApiService {
+  constructor(private readonly env: Env) {}
+
+  /**
+   * Generate a new BTC deposit address
+   */
+  async generateDepositAddress(
+    params: GenerateDepositAddressParams,
+  ): Promise<string> {
+    return generateDepositBtcAddress({
+      address: params.address,
+      chainId: params.chainId as DestChainId,
+      signature: params.signature,
+      token: params.token as Token,
+      eip712Data: params.eip712Data,
+      signatureData: params.signatureData,
+      pubKey: params.pubKey,
+      env: this.env,
+      partnerId: params.partnerId,
+      referrerCode: params.referrerCode,
+    });
+  }
+
+  /**
+   * Get existing deposit address for a recipient
+   */
+  async getDepositAddress(
+    params: GetDepositAddressParams,
+  ): Promise<string | undefined> {
+    try {
+      const address = await getDepositBtcAddress({
+        address: params.address,
+        chainId: params.chainId as DestChainId,
+        token: params.token as Token,
+        env: this.env,
+        partnerId: params.partnerId,
+      });
+      return address || undefined;
+    } catch {
+      // No address found
+      return undefined;
+    }
+  }
+
+  /**
+   * Get deposits for an address
+   */
+  async getDeposits(address: string): Promise<DepositInfo[]> {
+    const deposits = await getDepositsByAddress({
+      address,
+      env: this.env,
+    });
+
+    return deposits.map(d => ({
+      depositAddress: d.depositAddress ?? '',
+      blockHeight: d.blockHeight,
+      isClaimed: d.isClaimed,
+      txid: d.txHash,
+      amount: d.amount?.toString(),
+    }));
+  }
+
+  /**
+   * Store network fee signature
+   */
+  async storeFeeSignature(params: StoreFeeSignatureParams): Promise<void> {
+    await storeNetworkFeeSignature({
+      address: params.address,
+      signature: params.signature,
+      typedData: params.typedData,
+      env: this.env,
+      tokenAddress: params.tokenAddress,
+    });
+  }
+
+  /**
+   * Get stored network fee signature
+   */
+  async getFeeSignature(
+    params: GetFeeSignatureParams,
+  ): Promise<FeeSignatureResult> {
+    return getNetworkFeeSignature({
+      address: params.address,
+      chainId: params.chainId as ChainId,
+      env: this.env,
+      tokenAddress: params.tokenAddress,
+    });
+  }
+
+  /**
+   * Store stake and bake signature
+   */
+  async storeStakeAndBakeSignature(
+    params: StoreStakeAndBakeParams,
+  ): Promise<void> {
+    await storeStakeAndBakeSignature({
+      signature: params.signature,
+      typedData: params.typedData,
+      env: this.env,
+    });
+  }
+}

package/src/services/BtcService.ts

@@ -0,0 +1,29 @@
+/**
+ * BTC Service
+ *
+ * Provides Bitcoin-specific operations via mempool API.
+ *
+ * @module services/BtcService
+ */
+
+import type {
+  BtcNetworkMode,
+  BtcService as IBtcService,
+} from '@lombard.finance/sdk-common';
+
+import { getCurrentBlockHeight } from '../chains/btc/client/getCurrentBlockHeight';
+
+/**
+ * BTC Service
+ *
+ * Implementation of the BtcService interface from sdk-common.
+ * Provides Bitcoin blockchain operations.
+ */
+export class BtcService implements IBtcService {
+  /**
+   * Get current block height from mempool
+   */
+  async getCurrentBlockHeight(network: BtcNetworkMode): Promise<number> {
+    return getCurrentBlockHeight(network);
+  }
+}

package/src/services/EvmService.ts

@@ -0,0 +1,127 @@
+/**
+ * EVM Service
+ *
+ * Provides EVM-specific operations via contract functions.
+ *
+ * @module services/EvmService
+ */
+
+import type {
+    Env,
+    EvmChainId,
+    EvmProvider,
+    EvmService as IEvmService,
+    SignNetworkFeeParams,
+    SignNetworkFeeResult,
+    SignStakeAndBakeParams,
+} from '@lombard.finance/sdk-common';
+import BigNumber from 'bignumber.js';
+import type { EIP1193Provider } from 'viem';
+
+import type { ChainId } from '../common/chains';
+import { getMintingFee } from '../contract-functions/getLBTCMintingFee/getLBTCMintingFee';
+import { getStakeAndBakeFee } from '../contract-functions/getStakeAndBakeFee/getStakeAndBakeFee';
+import { signLbtcDestinationAddr } from '../contract-functions/signLbtcDestionationAddr/signLbtcDestinationAddr';
+import { signNetworkFee } from '../contract-functions/signNetworkFee/signNetworkFee';
+import { signStakeAndBake } from '../contract-functions/signStakeAndBake/signStakeAndBake';
+import type { DefiProtocol, StakeAndBakeToken } from '../defi/defi-registry';
+import { Token } from '../tokens/token-addresses';
+
+/**
+ * EVM Service
+ *
+ * Implementation of the EvmService interface from sdk-common.
+ * Provides EVM contract interactions and fee authorization.
+ */
+export class EvmService implements IEvmService {
+  constructor(private readonly env: Env) {}
+
+  /**
+   * Get minting fee for a chain
+   * @param chainId - The chain ID
+   * @param token - Optional token (defaults to LBTC). Use Token.BTCb for BTC.b deposits.
+   */
+  async getMintingFee(chainId: EvmChainId, token?: string): Promise<string> {
+    const fee = await getMintingFee({
+      token: (token as Token) || Token.LBTC,
+      chainId: chainId as ChainId,
+      env: this.env,
+    });
+    return fee.toString();
+  }
+
+  /**
+   * Sign network fee authorization (EIP-712)
+   */
+  async signNetworkFee(
+    params: SignNetworkFeeParams,
+  ): Promise<SignNetworkFeeResult> {
+    const result = await signNetworkFee({
+      fee: new BigNumber(params.fee),
+      account: params.account as `0x${string}`,
+      chainId: params.chainId as ChainId,
+      provider: params.provider as EIP1193Provider,
+      env: this.env,
+      // Pass token for signing - defaults to LBTC for backwards compatibility
+      token: (params.token as Token) ?? Token.LBTC,
+    });
+
+    return {
+      signature: result.signature,
+      typedData: result.typedData,
+    };
+  }
+
+  /**
+   * Get stake and bake fee for a vault
+   */
+  async getStakeAndBakeFee(
+    chainId: EvmChainId,
+    protocol: DefiProtocol,
+  ): Promise<string> {
+    const fee = await getStakeAndBakeFee({
+      chainId: chainId as ChainId,
+      protocol,
+    });
+    return fee.toString();
+  }
+
+  /**
+   * Sign stake and bake authorization
+   */
+  async signStakeAndBake(
+    params: SignStakeAndBakeParams,
+  ): Promise<SignNetworkFeeResult> {
+    const result = await signStakeAndBake({
+      value: new BigNumber(params.value),
+      account: params.account as `0x${string}`,
+      chainId: params.chainId as ChainId,
+      provider: params.provider as EIP1193Provider,
+      env: this.env,
+      vaultKey: params.vaultKey as DefiProtocol,
+      token: params.token as StakeAndBakeToken,
+    });
+
+    return {
+      signature: result.signature,
+      typedData: result.typedData,
+    };
+  }
+
+  /**
+   * Sign LBTC destination address (for non-Ethereum EVM chains)
+   */
+  async signLbtcDestination(params: {
+    chainId: EvmChainId;
+    address: string;
+    provider: EvmProvider;
+  }): Promise<{ signature: string }> {
+    const signature = await signLbtcDestinationAddr({
+      account: params.address as `0x${string}`,
+      chainId: params.chainId as ChainId,
+      provider: params.provider as EIP1193Provider,
+    });
+
+    return { signature };
+  }
+}