@lombard.finance/sdk 3.7.3 → 4.0.0

package/src/client/ApiNamespace.ts

@@ -0,0 +1,302 @@
+/**
+ * API Namespace
+ *
+ * Provides convenient access to Lombard API data-fetching operations,
+ * with environment pre-configured from SDK initialization.
+ *
+ * All API-related read operations are namespaced under `sdk.api.*`
+ *
+ * @example
+ * ```ts
+ * const sdk = new LombardSDK({ env: Env.prod, providers: {...} });
+ *
+ * // Fetch deposits for an address
+ * const deposits = await sdk.api.deposits('0x...');
+ *
+ * // Fetch unstakes with options
+ * const unstakes = await sdk.api.unstakes('0x...', { show_redeems: true });
+ *
+ * // Fetch points (defaults to current season)
+ * const points = await sdk.api.points('0x...');
+ *
+ * // Fetch LBTC exchange rate
+   * const rate = await sdk.api.exchangeRatio();
+ *
+ * // Get existing BTC deposit address
+ * const depositAddr = await sdk.api.depositAddress('0x...', ChainId.ethereum);
+ * ```
+ *
+ * @module client/ApiNamespace
+ */
+
+import { DEFAULT_ENV, Env } from '@lombard.finance/sdk-common';
+import type BigNumber from 'bignumber.js';
+
+import { getDepositBtcAddress } from '../api-functions/getDepositBtcAddress/getDepositBtcAddress';
+import {
+  type Deposit,
+  getDepositsByAddress,
+} from '../api-functions/getDepositsByAddress/getDepositsByAddress';
+import { getExchangeRatio } from '../api-functions/getLBTCExchangeRate/get-exchange-ratio';
+import {
+  getPointsByAddress,
+  type IPointsByAddressSeason1,
+  type IPointsByAddressSeason2,
+} from '../api-functions/getPointsByAddress/getPointsByAddress';
+import {
+  getUnstakesByAddress,
+  type Unstake,
+} from '../api-functions/getUnstakesByAddress/getUnstakesByAddress';
+import type { ChainId, SolanaChain, StarknetChainId, SuiChain } from '../common/chains';
+import type { Token } from '../tokens/token-addresses';
+
+/* -------------------------------------------------------------------------- */
+/*                                   Types                                    */
+/* -------------------------------------------------------------------------- */
+
+/** Supported API versions (for future v2 migration) */
+export type ApiVersion = 'v1' | 'v2';
+
+/** Options for fetching unstakes */
+export interface UnstakeOptions {
+  /** Include redeem operations */
+  show_redeems?: boolean;
+  /** Include unstake operations */
+  show_unstakes?: boolean;
+  /** Filter for native chain redemptions */
+  to_native?: boolean;
+}
+
+/** Options for fetching exchange rate */
+export interface ExchangeRateOptions {
+  /** Chain ID (exchange rate is same for all chains, defaults to Ethereum) */
+  chainId?: ChainId;
+  /** Amount in satoshis to calculate exchange for */
+  amount?: BigNumber.Value;
+}
+
+/** Options for fetching deposit address */
+export interface DepositAddressOptions {
+  /** Partner ID for the deposit address */
+  partnerId?: string;
+  /** Token type (LBTC, BTCK, BTCb) */
+  token?: Token;
+}
+
+/** Destination chain types for deposit address */
+export type DestinationChain = ChainId | SuiChain | SolanaChain | StarknetChainId;
+
+/* -------------------------------------------------------------------------- */
+/*                              ApiNamespace                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * API Namespace Class
+ *
+ * Provides convenient wrappers around Lombard API functions with
+ * environment pre-bound from SDK configuration.
+ *
+ * Designed for easy migration to API v2 when available (January 2025).
+ */
+export class ApiNamespace {
+  /**
+   * Internal API version flag for future v2 migration.
+   * When v2 is ready, we can switch implementations transparently.
+   */
+  private readonly apiVersion: ApiVersion = 'v1';
+
+  constructor(private readonly env: Env = DEFAULT_ENV) {}
+
+  /* -------------------------------------------------------------------------- */
+  /*                               Deposits                                     */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Fetch all deposits for an address.
+   *
+   * Returns deposits from both Direct BTC Deposits and Native Deposits APIs,
+   * unified into a single list sorted by block time (newest first).
+   *
+   * @param address - The EVM/BTC address to fetch deposits for
+   * @returns Promise resolving to array of Deposit objects
+   *
+   * @example
+   * ```ts
+   * const deposits = await sdk.api.deposits('0x1234...');
+   * deposits.forEach(d => {
+   *   console.log(`${d.amount} BTC deposited at block ${d.blockHeight}`);
+   * });
+   * ```
+   */
+  async deposits(address: string): Promise<Deposit[]> {
+    // Future: if (this.apiVersion === 'v2') return this.depositsV2(address);
+    return getDepositsByAddress({ address, env: this.env });
+  }
+
+  /* -------------------------------------------------------------------------- */
+  /*                               Unstakes                                     */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Fetch all unstakes/redemptions for an address.
+   *
+   * Returns unstake records for both direct BTC unstakes and
+   * native blockchain redemptions.
+   *
+   * @param address - The address that initiated the unstakes
+   * @param options - Optional filters (show_redeems, show_unstakes, to_native)
+   * @returns Promise resolving to array of Unstake objects
+   *
+   * @example
+   * ```ts
+   * // Get all unstakes
+   * const unstakes = await sdk.api.unstakes('0x1234...');
+   *
+   * // Get only native chain redemptions
+   * const redeems = await sdk.api.unstakes('0x1234...', { to_native: true });
+   * ```
+   */
+  async unstakes(address: string, options?: UnstakeOptions): Promise<Unstake[]> {
+    // Future: if (this.apiVersion === 'v2') return this.unstakesV2(address, options);
+    return getUnstakesByAddress({ address, env: this.env, options });
+  }
+
+  /* -------------------------------------------------------------------------- */
+  /*                                Points                                      */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Fetch Lux points for an address (Season 1).
+   *
+   * @param address - The wallet address
+   * @param season - Season number (1)
+   * @returns Promise resolving to Season 1 points breakdown
+   */
+  async points(
+    address: string,
+    season: 1,
+  ): Promise<IPointsByAddressSeason1>;
+
+  /**
+   * Fetch Lux points for an address (Season 2).
+   *
+   * @param address - The wallet address
+   * @param season - Season number (2)
+   * @returns Promise resolving to Season 2 points breakdown
+   */
+  async points(
+    address: string,
+    season: 2,
+  ): Promise<IPointsByAddressSeason2>;
+
+  /**
+   * Fetch Lux points for an address (defaults to current season).
+   *
+   * @param address - The wallet address
+   * @param season - Optional season number (defaults to current)
+   * @returns Promise resolving to points breakdown
+   *
+   * @example
+   * ```ts
+   * // Get current season points
+   * const points = await sdk.api.points('0x1234...');
+   * console.log(`Total: ${points.totalPoints}, Holding: ${points.holdingPoints}`);
+   *
+   * // Get Season 1 points
+   * const s1 = await sdk.api.points('0x1234...', 1);
+   * ```
+   */
+  async points(
+    address: string,
+    season?: number,
+  ): Promise<IPointsByAddressSeason1 | IPointsByAddressSeason2>;
+
+  async points(
+    address: string,
+    season?: number,
+  ): Promise<IPointsByAddressSeason1 | IPointsByAddressSeason2> {
+    // Future: if (this.apiVersion === 'v2') return this.pointsV2(address, season);
+    return getPointsByAddress({ address, env: this.env, season });
+  }
+
+  /* -------------------------------------------------------------------------- */
+  /*                          Token Exchange Ratios                             */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Fetch the current exchange ratios for all supported tokens.
+   *
+   * Returns Token:BTC and BTC:Token ratios for LBTC and other supported tokens.
+   * This is the recommended method for getting exchange rate information.
+   *
+   * @returns Promise resolving to exchange ratio info for each token
+   *
+   * @example
+   * ```ts
+   * const ratios = await sdk.api.exchangeRatio();
+   *
+   * // Access LBTC ratios
+   * const lbtcRatio = ratios.LBTC;
+   * console.log(`LBTC:BTC = ${lbtcRatio.tokenBTCRatio}`);  // How many LBTC per 1 BTC
+   * console.log(`BTC:LBTC = ${lbtcRatio.BTCTokenRatio}`);  // How many BTC per 1 LBTC
+   * ```
+   */
+  async exchangeRatio() {
+    return getExchangeRatio({ env: this.env });
+  }
+
+  /* -------------------------------------------------------------------------- */
+  /*                           Deposit Address                                  */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Get an existing BTC deposit address for a recipient.
+   *
+   * Returns the most recent non-deprecated deposit address for the
+   * given recipient address and destination chain.
+   *
+   * @param address - The destination address where LBTC will be claimed
+   * @param chainId - The destination chain
+   * @param options - Optional partner ID and token type
+   * @returns Promise resolving to the BTC deposit address
+   * @throws Error if no deposit address found
+   *
+   * @example
+   * ```ts
+   * try {
+   *   const btcAddr = await sdk.api.depositAddress('0x1234...', ChainId.ethereum);
+   *   console.log(`Send BTC to: ${btcAddr}`);
+   * } catch (e) {
+   *   console.log('No deposit address found - need to generate one');
+   * }
+   * ```
+   */
+  async depositAddress(
+    address: string,
+    chainId: DestinationChain,
+    options?: DepositAddressOptions,
+  ): Promise<string> {
+    // Future: if (this.apiVersion === 'v2') return this.depositAddressV2(address, chainId, options);
+    return getDepositBtcAddress({
+      address,
+      chainId,
+      env: this.env,
+      partnerId: options?.partnerId,
+      token: options?.token,
+    });
+  }
+
+  /* -------------------------------------------------------------------------- */
+  /*                            Utility Methods                                 */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Get the current API version being used.
+   *
+   * @returns The API version string ('v1' or 'v2')
+   */
+  getApiVersion(): ApiVersion {
+    return this.apiVersion;
+  }
+}
+

package/src/client/AssetNamespace.ts

@@ -0,0 +1,112 @@
+/**
+ * Asset Namespace
+ *
+ * Provides type-safe access to the asset catalog bound to an environment.
+ * All asset-related operations are namespaced under `sdk.assets.*`
+ *
+ * @example
+ * ```ts
+ * const sdk = createLombardSDK({ env: Env.prod });
+ *
+ * const address = sdk.assets.getAddress(AssetId.LBTC, Chain.ETHEREUM);
+ * const decimals = sdk.assets.getDecimals(AssetId.LBTC);
+ * const chains = sdk.assets.getChains(AssetId.LBTC);
+ * ```
+ */
+
+import { DEFAULT_ENV, Env } from '@lombard.finance/sdk-common';
+
+import {
+  ASSET_CATALOG,
+  type AssetCatalog,
+  type AssetId,
+  type Chain,
+  getAssetAddress,
+  getAssetByAddress,
+  getAssetChains,
+  getAssetDecimals,
+  getAssetEnvironments,
+  getAssetMetadata,
+  getAssetRouter,
+  getBridgeAdapter,
+  getPublicMarketMaker,
+  getSupportedAssets,
+  isAssetDeployed,
+  usesAssetRouter,
+} from '../core';
+
+export class AssetNamespace {
+  private readonly catalog: AssetCatalog;
+
+  constructor(
+    private readonly env: Env = DEFAULT_ENV,
+    catalog?: AssetCatalog,
+  ) {
+    this.catalog = catalog ?? ASSET_CATALOG;
+  }
+
+  /** Get token contract address */
+  getAddress(asset: AssetId, chain: Chain): string | undefined {
+    return getAssetAddress(asset, this.env, chain, this.catalog);
+  }
+
+  /** Get token decimals */
+  getDecimals(asset: AssetId): number {
+    return getAssetDecimals(asset, this.catalog);
+  }
+
+  /** Get asset metadata (decimals, symbol, name) */
+  getMetadata(asset: AssetId) {
+    return getAssetMetadata(asset, this.catalog);
+  }
+
+  /** Check if asset uses an asset router contract */
+  usesAssetRouter(asset: AssetId, chain: Chain): boolean {
+    return usesAssetRouter(asset, this.env, chain, this.catalog);
+  }
+
+  /** Get asset router contract address */
+  getAssetRouter(asset: AssetId, chain: Chain): string | undefined {
+    return getAssetRouter(asset, this.env, chain, this.catalog);
+  }
+
+  /** Get bridge adapter address */
+  getBridgeAdapter(asset: AssetId, chain: Chain): string | undefined {
+    return getBridgeAdapter(asset, this.env, chain, this.catalog);
+  }
+
+  /** Get public market maker address */
+  getPublicMarketMaker(asset: AssetId, chain: Chain): string | undefined {
+    return getPublicMarketMaker(asset, this.env, chain, this.catalog);
+  }
+
+  /** Find asset by contract address (reverse lookup) */
+  getByAddress(address: string, chain: Chain): AssetId | undefined {
+    return getAssetByAddress(address, this.env, chain, this.catalog);
+  }
+
+  /** Check if asset is deployed on a chain */
+  isDeployed(asset: AssetId, chain: Chain): boolean {
+    return isAssetDeployed(asset, this.env, chain, this.catalog);
+  }
+
+  /** Get all chains where asset is deployed */
+  getChains(asset: AssetId): Chain[] {
+    return getAssetChains(asset, this.env, this.catalog);
+  }
+
+  /** Get all environments where asset is deployed on a chain */
+  getEnvironments(asset: AssetId, chain: Chain): Env[] {
+    return getAssetEnvironments(asset, chain, this.catalog);
+  }
+
+  /** Get all supported assets */
+  getSupportedAssets(): AssetId[] {
+    return getSupportedAssets(this.catalog);
+  }
+
+  /** Direct access to the asset catalog */
+  getCatalog(): AssetCatalog {
+    return this.catalog;
+  }
+}

package/src/client/LombardSDK.ts

@@ -0,0 +1,212 @@
+/**
+ * Main Lombard SDK Class
+ *
+ * Entry point for all Lombard operations.
+ *
+ * @module client/LombardSDK
+ */
+
+import type { Env } from '@lombard.finance/sdk-common';
+
+import { BtcActions } from '../chains/btc/BtcActions';
+import { EvmActions } from '../chains/evm/EvmActions';
+import { SolanaActions } from '../chains/solana/SolanaActions';
+import { StarknetActions } from '../chains/starknet/StarknetActions';
+import { SuiActions } from '../chains/sui/SuiActions';
+import type {
+  AnyProvider,
+  BtcProvider,
+  EvmProvider,
+  SolanaProvider,
+  StarknetProvider,
+  SuiProvider,
+} from '../config/providers';
+import type { ProviderGetters, ResolvedLombardConfig } from '../config/types';
+import { getProviderGetter } from '../config/types';
+import { CapabilityRegistry } from '../modules/CapabilityRegistry';
+import { ReferralsClient } from '../referrals/ReferralsClient';
+import { LombardError, ProviderErrorCode } from '../shared/errors';
+import { ApiNamespace } from './ApiNamespace';
+import { AssetNamespace } from './AssetNamespace';
+import { PartnerConfiguration } from './PartnerConfiguration';
+
+type ProviderType = keyof ProviderGetters;
+type ProviderCache = Map<ProviderType, AnyProvider>;
+
+/**
+ * Main Lombard SDK
+ *
+ * Provides access to all chain actions and features.
+ *
+ * **Important**: Use `createLombardSDK()` to create instances.
+ * Direct instantiation is not recommended.
+ *
+ * @example
+ * ```typescript
+ * // Recommended: Use the async factory
+ * const sdk = await createLombardSDK({
+ *   env: Env.prod,
+ *   providers: {
+ *     evm: (chain) => window.ethereum,
+ *   },
+ * });
+ *
+ * // Access chain actions
+ * const btcStake = sdk.chain.btc.stake({
+ *   assetOut: AssetId.LBTC,
+ *   destChain: Chain.ETHEREUM,
+ * });
+ * ```
+ */
+export class LombardSDK<E extends Env = Env> {
+  readonly config: ResolvedLombardConfig;
+  readonly env: Env;
+
+  /** Partner configuration manager */
+  private partnerConfig: PartnerConfiguration;
+
+  /** Provider cache */
+  private providerCache: ProviderCache = new Map();
+
+  /**
+   * Chain actions (user-facing API)
+   *
+   * Access operations for each supported chain:
+   * - btc: Bitcoin operations (stake, stakeAndDeploy, deposit)
+   * - evm: EVM operations (deposit, stake, unstake, deploy, redeem)
+   * - solana: Solana operations (unstake)
+   * - sui: Sui operations (unstake)
+   * - starknet: Starknet operations (unstake)
+   */
+  public readonly chain: {
+    btc: BtcActions;
+    evm: EvmActions;
+    solana: SolanaActions;
+    sui: SuiActions;
+    starknet: StarknetActions;
+  };
+
+  public readonly assets: AssetNamespace;
+
+  /**
+   * API namespace for data-fetching operations
+   *
+   * Provides convenient access to Lombard API read operations:
+   * - deposits: Fetch deposit history
+   * - unstakes: Fetch unstake/redemption history
+   * - points: Fetch Lux points
+   * - exchangeRatio: Get exchange ratios for all supported tokens
+   * - depositAddress: Get existing BTC deposit address
+   */
+  public readonly api: ApiNamespace;
+
+  /** Feature clients */
+  public readonly referrals: ReferralsClient;
+
+  /** Capability registry (manages optional module services) */
+  public readonly capabilities: CapabilityRegistry;
+
+  constructor(config: ResolvedLombardConfig) {
+    this.config = config;
+    this.env = config.env as E;
+
+    // Initialize partner configuration
+    this.partnerConfig = new PartnerConfiguration(config.partner);
+
+    // Initialize capability registry (config-only, no SDK reference needed)
+    this.capabilities = new CapabilityRegistry(
+      this.config.modules,
+      this.config,
+    );
+
+    // Initialize chain actions with config (not SDK)
+    this.chain = {
+      btc: new BtcActions(this.config),
+      evm: new EvmActions(this.config),
+      solana: new SolanaActions(this.config),
+      sui: new SuiActions(this.config),
+      starknet: new StarknetActions(this.config),
+    };
+
+    // Initialize feature clients
+    this.referrals = new ReferralsClient(this);
+
+    // Initialize asset namespace
+    this.assets = new AssetNamespace(this.env);
+
+    // Initialize API namespace
+    this.api = new ApiNamespace(this.env);
+  }
+
+  /**
+   * Get a provider for a specific chain type
+   *
+   * Providers are lazily loaded and cached.
+   *
+   * @param type - Provider type ('evm', 'bitcoin', etc.)
+   * @returns Provider instance
+   * @throws LombardError if provider not configured
+   */
+  async getProvider(type: 'evm'): Promise<EvmProvider>;
+  async getProvider(type: 'bitcoin'): Promise<BtcProvider>;
+  async getProvider(type: 'solana'): Promise<SolanaProvider>;
+  async getProvider(type: 'sui'): Promise<SuiProvider>;
+  async getProvider(type: 'starknet'): Promise<StarknetProvider>;
+  async getProvider(type: ProviderType): Promise<AnyProvider>;
+  async getProvider(type: ProviderType): Promise<AnyProvider> {
+    const cacheKey = type;
+
+    // Check cache first
+    if (this.providerCache.has(cacheKey)) {
+      return this.providerCache.get(cacheKey) as AnyProvider;
+    }
+
+    // Get provider getter from config using safe accessor
+    const getter = getProviderGetter<AnyProvider>(this.config.providers, type);
+    if (!getter) {
+      throw LombardError.providerMissing(type, type);
+    }
+
+    // Call getter to get provider
+    const provider = await getter();
+    if (!provider) {
+      throw new LombardError(
+        ProviderErrorCode.PROVIDER_INITIALIZATION_FAILED,
+        `Failed to initialize ${type} provider`,
+      );
+    }
+
+    // Cache and return
+    this.providerCache.set(cacheKey, provider);
+    return provider;
+  }
+
+  /**
+   * Configure partner settings
+   *
+   * @param config - Partner configuration
+   */
+  configure(config: Parameters<PartnerConfiguration['update']>[0]): void {
+    this.partnerConfig.update(config);
+  }
+
+  /**
+   * Register a custom asset
+   *
+   * TODO: Implement asset registration
+   */
+  registerAsset(_asset: unknown): void {
+    throw new Error('Not implemented yet');
+  }
+
+  /**
+   * Get partner configuration
+   */
+  getPartnerConfig(): PartnerConfiguration {
+    return this.partnerConfig;
+  }
+
+  getPartnerId(): string | undefined {
+    return this.partnerConfig.getPartnerId();
+  }
+}

package/src/client/PartnerConfiguration.ts

@@ -0,0 +1,50 @@
+/**
+ * Partner configuration management
+ *
+ * This module handles partner-specific configuration.
+ */
+
+import type { PartnerConfig } from '../config/types';
+
+/**
+ * Partner configuration manager
+ *
+ * Manages partner-specific settings.
+ */
+export class PartnerConfiguration {
+  private config: PartnerConfig | undefined;
+
+  constructor(config?: PartnerConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Get partner ID
+   */
+  getPartnerId(): string | undefined {
+    return this.config?.partnerId;
+  }
+
+  /**
+   * Check if partner is configured
+   */
+  isConfigured(): boolean {
+    return this.config !== undefined;
+  }
+
+  /**
+   * Update partner configuration
+   *
+   * @param config - New partner configuration
+   */
+  update(config: PartnerConfig): void {
+    this.config = config;
+  }
+
+  /**
+   * Clear partner configuration
+   */
+  clear(): void {
+    this.config = undefined;
+  }
+}