@lombard.finance/sdk 4.0.0 → 4.1.2

package/src/client/ApiNamespace.ts

@@ -1,302 +0,0 @@
-/**
- * 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

@@ -1,112 +0,0 @@
-/**
- * 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

@@ -1,212 +0,0 @@
-/**
- * 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

@@ -1,50 +0,0 @@
-/**
- * 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;
-  }
-}