@lombard.finance/sdk 3.7.4 → 4.0.0

package/src/client/createConfig.ts

@@ -0,0 +1,90 @@
+import type { AnyModule, ProviderKey } from '@lombard.finance/sdk-common';
+
+import type { CreateConfigOptions, LombardConfig } from '../config/types';
+import { validateAndApplyDefaults } from '../config/validation';
+import { apiModule } from '../modules/apiModule';
+import { btcModule } from '../modules/btcModule';
+import { evmModule } from '../modules/evmModule';
+import { LombardError } from '../shared/errors';
+import { createConsoleLogger } from '../utils/consoleLogger';
+
+function mergeModules(provided: readonly AnyModule[] | undefined): AnyModule[] {
+  const modules = new Map<string, AnyModule>();
+  const builtIns: AnyModule[] = [btcModule(), evmModule(), apiModule()];
+  for (const mod of builtIns) {
+    modules.set(mod.id, mod);
+  }
+  if (provided) {
+    for (const mod of provided) {
+      modules.set(mod.id, mod);
+    }
+  }
+  return Array.from(modules.values());
+}
+
+function ensureProviders(
+  modules: readonly AnyModule[],
+  config: Pick<LombardConfig, 'providers'>,
+): void {
+  for (const mod of modules) {
+    for (const key of mod.requiresProviders ?? []) {
+      if (!hasProvider(config, key)) {
+        throw LombardError.providerMissing(key, key);
+      }
+    }
+  }
+}
+
+function hasProvider(
+  config: Pick<LombardConfig, 'providers'>,
+  key: ProviderKey,
+): boolean {
+  return Boolean(config.providers?.[key]);
+}
+
+/**
+ * Create SDK configuration
+ *
+ * This is a **synchronous** function that validates options and returns
+ * a configuration object. The config can be exported from a module and
+ * passed around as a plain object.
+ *
+ * The asset catalog is NOT fetched here - it's fetched asynchronously
+ * when createLombardSDK() is called. This keeps config creation simple
+ * and predictable.
+ *
+ * @param options - Configuration options
+ * @returns Validated SDK configuration
+ *
+ * @example
+ * ```typescript
+ * // lib/lombard.ts - Config is sync, can be exported directly
+ * export const config = createConfig({
+ *   env: Env.prod,
+ *   providers: { evm: () => window.ethereum },
+ * });
+ *
+ * // Usage - SDK creation is async
+ * import { config } from './lib/lombard';
+ * const sdk = await createLombardSDK(config);
+ * ```
+ */
+export function createConfig(options: CreateConfigOptions): LombardConfig {
+  const normalized = validateAndApplyDefaults(options);
+  const modules = mergeModules(
+    options.modules as readonly AnyModule[] | undefined,
+  );
+  ensureProviders(modules, normalized);
+
+  // Resolve logger: explicit logger > debug mode > undefined
+  let logger = options.logger;
+  if (!logger && options.debug) {
+    logger = createConsoleLogger({ level: 'debug' });
+  }
+
+  return {
+    ...normalized,
+    modules,
+    logger,
+  };
+}

package/src/client/createLombardSDK.ts

@@ -0,0 +1,130 @@
+/**
+ * Async factory for creating LombardSDK instances
+ *
+ * This is the primary entry point for the Lombard SDK.
+ * It fetches the asset catalog asynchronously and initializes the SDK.
+ */
+
+import type { Env } from '@lombard.finance/sdk-common';
+
+import type {
+    CreateConfigOptions,
+    LombardConfig,
+    ResolvedLombardConfig,
+} from '../config/types';
+import { ASSET_CATALOG } from '../core/assets/catalog';
+import type { AssetCatalog } from '../core/assets/types';
+import { createConfig } from './createConfig';
+import { LombardSDK } from './LombardSDK';
+
+/**
+ * Module-level catalog cache
+ *
+ * Caches the catalog promise per environment to avoid redundant fetches.
+ * Multiple calls to createLombardSDK() with the same env will share
+ * the same catalog fetch.
+ *
+ * @internal
+ */
+const catalogCache = new Map<Env, Promise<AssetCatalog>>();
+
+/**
+ * Fetch asset catalog with caching
+ *
+ * Currently returns bundled catalog immediately.
+ * Future: Will fetch from remote S3/CDN with bundled fallback.
+ *
+ * The catalog is cached per environment - subsequent calls with the
+ * same env return the same promise, avoiding duplicate fetches.
+ *
+ * @internal
+ */
+function fetchCatalogCached(env: Env): Promise<AssetCatalog> {
+  if (!catalogCache.has(env)) {
+    // TODO (APP-1834): Implement remote catalog fetching
+    // When backend is ready:
+    // 1. Fetch from CDN: https://cdn.lombard.finance/catalog/{env}.json
+    // 2. Fallback to ASSET_CATALOG on network failure
+    // 3. Cache-Control headers will define CDN TTL
+    //
+    // For now, return bundled catalog immediately (wrapped in Promise)
+    catalogCache.set(env, Promise.resolve(ASSET_CATALOG));
+  }
+  return catalogCache.get(env)!;
+}
+
+/**
+ * Create a LombardSDK instance
+ *
+ * This is an async factory that:
+ * 1. Validates configuration (sync)
+ * 2. Fetches the asset catalog (async, cached per env)
+ * 3. Initializes the SDK with all chain actions
+ *
+ * The catalog is cached at the module level - multiple SDK instances
+ * with the same environment share the same catalog fetch.
+ *
+ * @param options - SDK configuration options or pre-made LombardConfig
+ * @returns Promise resolving to LombardSDK instance
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Direct creation (recommended for simple cases)
+ * const sdk = await createLombardSDK({
+ *   env: Env.prod,
+ *   providers: {
+ *     evm: () => window.ethereum,
+ *     bitcoin: () => bitcoinProvider,
+ *   },
+ * });
+ *
+ * // Option 2: Separate config (recommended for shared config)
+ * // lib/lombard.ts
+ * export const config = createConfig({
+ *   env: Env.prod,
+ *   providers: { evm: () => window.ethereum },
+ * });
+ *
+ * // app.ts
+ * import { config } from './lib/lombard';
+ * const sdk = await createLombardSDK(config);
+ *
+ * // Use the SDK
+ * const stake = sdk.chain.btc.stake({
+ *   destChain: Chain.ETHEREUM,
+ *   assetOut: AssetId.LBTC,
+ * });
+ * ```
+ */
+export async function createLombardSDK<E extends Env = Env>(
+  options: (CreateConfigOptions & { env: E }) | LombardConfig,
+): Promise<LombardSDK<E>> {
+  // If already a LombardConfig (validated), use it
+  // Otherwise, create config (sync validation)
+  const config: LombardConfig =
+    'modules' in options && Array.isArray(options.modules)
+      ? (options as LombardConfig)
+      : createConfig(options as CreateConfigOptions & { env: E });
+
+  // Fetch catalog (async, cached per env)
+  const catalog = await fetchCatalogCached(config.env);
+
+  // Create resolved config with catalog
+  const resolvedConfig: ResolvedLombardConfig = {
+    ...config,
+    catalog,
+  };
+
+  return new LombardSDK<E>(resolvedConfig);
+}
+
+/**
+ * Clear the catalog cache
+ *
+ * Useful for testing or forcing a fresh catalog fetch.
+ *
+ * @internal
+ */
+export function clearCatalogCache(): void {
+  catalogCache.clear();
+}

package/src/clients/public-client.ts

@@ -38,10 +38,6 @@ export function makePublicClient({
     chain = getChain(chainId);
   }
 
-  console.info(
-    `Creating a public client for ${chainId} with RPC: ${rpcUrls[chainId]}`,
-  );
-
   const transport = http(rpcUrls[chainId]);
 
   const publicClient = createPublicClient({

package/src/clients/rpc-url-config.ts

@@ -6,7 +6,6 @@ import { ChainId } from '../common/chains';
 export type TRpcUrlConfig = Record<number, string>;
 
 export const RPC_URL = 'https://bff.prod.lombard-fi.com/multi-rpc/proxy';
-// export const RPC_URL = 'http://localhost:8001/multi-rpc/proxy';
 
 export const rpcUrlConfig: TRpcUrlConfig = {
   [ChainId.ethereum]: `${RPC_URL}/eth`,
@@ -29,7 +28,8 @@ export const rpcUrlConfig: TRpcUrlConfig = {
   [ChainId.holesky]: `${RPC_URL}/eth_holesky`,
   [ChainId.katanaTatara]: `${RPC_URL}/katana_tatara`,
   [ChainId.sepolia]: `${RPC_URL}/eth_sepolia`,
-  [ChainId.sonicBlazeTestnet]: `${RPC_URL}/sonic_blaze_testnet`,
+  // Use direct Sonic Labs RPC for testnet (proxy returns 403)
+  [ChainId.sonicBlazeTestnet]: 'https://rpc.blaze.soniclabs.com',
 };
 
 export function getRpcUrlConfig(env: Env) {
@@ -43,8 +43,12 @@ export function getRpcUrlConfig(env: Env) {
     [ChainId.binanceSmartChain]: 'https://bsc-dataseed.bnbchain.org',
     [ChainId.corn]: `${proxy}/corn_maizenet`,
     [ChainId.katana]: `${proxy}/katana`,
+    [ChainId.monad]: `${proxy}/monad_mainnet`,
+    [ChainId.megaeth]:
+      'https://alpha.megaeth.com/rpc?user=lombard+v1&token=1763427229-%2Bx6HFUDu9OhJwV%2FTCFOL0xTt%2FPJRAXPeirIcuytvnes%3D',
     [ChainId.sonic]: `${proxy}/sonic_mainnet`,
     [ChainId.tac]: `${proxy}/tac`,
+
     // Testnets:
     [ChainId.baseSepoliaTestnet]: `${proxy}/base_sepolia`,
     [ChainId.binanceSmartChainTestnet]:
@@ -52,6 +56,9 @@ export function getRpcUrlConfig(env: Env) {
     [ChainId.holesky]: `${proxy}/eth_holesky`,
     [ChainId.katanaTatara]: `${proxy}/katana_tatara`,
     [ChainId.sepolia]: `${proxy}/eth_sepolia`,
-    [ChainId.sonicBlazeTestnet]: `${proxy}/sonic_blaze_testnet`,
+    // Use direct Sonic Labs RPC for testnet (proxy returns 403)
+    [ChainId.sonicBlazeTestnet]: 'https://rpc.blaze.soniclabs.com',
+    [ChainId.stable]:
+      'https://partners-rpc.stable.xyz/lombard.075830647a2c30190712a9d102011ffe5a2a01d24ff3405f711d6ea8aca10baf',
   } as TRpcUrlConfig;
 }

package/src/common/api-config.ts

@@ -1,6 +1,6 @@
 import { DEFAULT_ENV, Env } from '@lombard.finance/sdk-common';
 
-interface IApiConfig {
+export interface IApiConfig {
   baseApiUrl: string;
   bffApiUrl: string | undefined;
 }

package/src/common/blockchain-identifier.ts

@@ -71,8 +71,8 @@ export function getChainNameById(
   }
 
   if (
-    featureConfig.isAvalancheEnabled &&
-    (chainId === ChainId.avalanche || chainId === ChainId.avalancheFuji)
+    (featureConfig.isAvalancheMainnetEnabled && chainId === ChainId.avalanche) ||
+    (featureConfig.isAvalancheFujiEnabled && chainId === ChainId.avalancheFuji)
   ) {
     return BlockchainIdentifier.avalanche;
   }
@@ -100,6 +100,10 @@ export function getChainNameById(
     return BlockchainIdentifier.monad;
   }
 
+  if (chainId === ChainId.megaeth) {
+    return BlockchainIdentifier.megaeth;
+  }
+
   if (chainId === ChainId.stable) {
     return BlockchainIdentifier.stable;
   }
@@ -123,10 +127,6 @@ export function getChainNameById(
     return BlockchainIdentifier.starknet;
   }
 
-  if (chainId === ChainId.megaeth) {
-    return BlockchainIdentifier.megaeth;
-  }
-
   throw new Error(`Unknown chain ID: ${chainId}`);
 }
 

package/src/common/chains.stories.tsx

@@ -1,4 +1,5 @@
 import { Meta, StoryObj } from '@storybook/react';
+
 import { chainSelector } from '../stories/arg-types';
 import { Button } from '../stories/components/Button';
 import { CodeBlock } from '../stories/components/CodeBlock';
@@ -10,7 +11,7 @@ import {
   useConnection,
 } from '../stories/hooks/useConnection';
 import useQuery from '../stories/hooks/useQuery';
-import { AddChainParameters, ChainId, addChain } from './chains';
+import { addChain,AddChainParameters, ChainId } from './chains';
 
 const meta = {
   title: 'write/addChain',

package/src/common/chains.ts

@@ -298,6 +298,7 @@ export const ChainId = {
   corn: 21000000,
   etherlink: 42793,
   katana: 747474,
+  megaeth: 4326,
   monad: 143,
   morph: 2818,
   sonic: 146,
@@ -305,7 +306,6 @@ export const ChainId = {
   swell: 1923,
   tac: 239,
   bob: 60808,
-  megaeth: 4326,
   // Testnets:
   avalancheFuji: 43113,
   baseSepoliaTestnet: 84532,
@@ -322,33 +322,46 @@ export type ChainId = (typeof ChainId)[keyof typeof ChainId];
 
 export const CHAIN_ID_TO_VIEM_CHAIN_MAP = {
   [ChainId.ethereum]: mainnet,
-  ...(featureConfig.isAvalancheEnabled
+  // Avalanche mainnet - BTC.b not released yet
+  ...(featureConfig.isAvalancheMainnetEnabled
     ? { [ChainId.avalanche]: avalanche }
     : {}),
   [ChainId.base]: base,
-  [ChainId.berachain]: berachain,
+  // APP-1975: Feature-gated chains
+  ...(featureConfig.isBerachainEnabled
+    ? { [ChainId.berachain]: berachain }
+    : {}),
   [ChainId.binanceSmartChain]: bsc,
-  [ChainId.corn]: corn,
-  [ChainId.etherlink]: etherlink,
+  ...(featureConfig.isCornEnabled ? { [ChainId.corn]: corn } : {}),
+  ...(featureConfig.isEtherlinkEnabled
+    ? { [ChainId.etherlink]: etherlink }
+    : {}),
   [ChainId.katana]: katana,
-  ...(featureConfig.isMonadEnabled ? { [ChainId.monad]: monad } : {}),
-  [ChainId.morph]: morph,
+  [ChainId.megaeth]: megaeth,
+  [ChainId.monad]: monad,
+  ...(featureConfig.isMorphEnabled ? { [ChainId.morph]: morph } : {}),
   [ChainId.sonic]: sonic,
   [ChainId.stable]: stable,
-  [ChainId.swell]: swellchain,
-  [ChainId.tac]: tac,
-  [ChainId.bob]: bob,
-  [ChainId.megaeth]: megaeth,
+  ...(featureConfig.isSwellchainEnabled
+    ? { [ChainId.swell]: swellchain }
+    : {}),
+  ...(featureConfig.isTacEnabled ? { [ChainId.tac]: tac } : {}),
+  ...(featureConfig.isBobEnabled ? { [ChainId.bob]: bob } : {}),
   // Testnets:
-  ...(featureConfig.isAvalancheEnabled
+  // Avalanche Fuji - enabled for testing (Silo integration)
+  ...(featureConfig.isAvalancheFujiEnabled
     ? { [ChainId.avalancheFuji]: avalancheFuji }
     : {}),
   [ChainId.baseSepoliaTestnet]: baseSepolia,
-  [ChainId.berachainBartioTestnet]: berachainTestnetbArtio,
+  ...(featureConfig.isBerachainEnabled
+    ? { [ChainId.berachainBartioTestnet]: berachainTestnetbArtio }
+    : {}),
   [ChainId.binanceSmartChainTestnet]: bscTestnet,
   [ChainId.holesky]: holesky,
   [ChainId.katanaTatara]: katanaTatara,
-  [ChainId.morphHolesky]: morphHolesky,
+  ...(featureConfig.isMorphEnabled
+    ? { [ChainId.morphHolesky]: morphHolesky }
+    : {}),
   [ChainId.sepolia]: sepolia,
   [ChainId.sonicBlazeTestnet]: sonicBlazeTestnet,
 };
@@ -380,7 +393,7 @@ export const isMegaethChain = (chainId: unknown): chainId is MegaethChain => {
 };
 export const CHAIN_ID_TO_LLAMA_CHAIN_NAME_MAP = {
   [ChainId.ethereum]: 'ethereum',
-  ...(featureConfig.isAvalancheEnabled
+  ...(featureConfig.isAvalancheMainnetEnabled
     ? { [ChainId.avalanche]: 'avalanche' }
     : {}),
   [ChainId.base]: 'base',

package/src/common/feature-config.ts

@@ -1,18 +1,79 @@
 export interface FeatureConfig {
   /**
    * Enable/disable Monad blockchain support
-   * @default false - Currently disabled
+   * @default true - Enabled
    */
   isMonadEnabled: boolean;
 
   /**
-   * Enable/disable Avalanche blockchain support
-   * @default false - Currently disabled
+   * Enable/disable Avalanche mainnet support
+   * @default false - BTC.b not released on mainnet yet
    */
-  isAvalancheEnabled: boolean;
+  isAvalancheMainnetEnabled: boolean;
+
+  /**
+   * Enable/disable Avalanche Fuji testnet support
+   * @default true - Enabled for testing
+   */
+  isAvalancheFujiEnabled: boolean;
+
+  /**
+   * Enable/disable Berachain support
+   * @default false - Not yet fully supported (APP-1975)
+   */
+  isBerachainEnabled: boolean;
+
+  /**
+   * Enable/disable Corn chain support
+   * @default false - Not yet fully supported (APP-1975)
+   */
+  isCornEnabled: boolean;
+
+  /**
+   * Enable/disable Morph chain support
+   * @default false - Not yet fully supported (APP-1975)
+   */
+  isMorphEnabled: boolean;
+
+  /**
+   * Enable/disable Swellchain support
+   * @default false - Not yet fully supported (APP-1975)
+   */
+  isSwellchainEnabled: boolean;
+
+  /**
+   * Enable/disable TAC chain support
+   * @default false - Not yet fully supported (APP-1975)
+   */
+  isTacEnabled: boolean;
+
+  /**
+   * Enable/disable BOB chain support
+   * @default false - Not yet fully supported (APP-1975)
+   */
+  isBobEnabled: boolean;
+
+  /**
+   * Enable/disable Etherlink chain support
+   * @default false - Not yet fully supported (APP-1975)
+   */
+  isEtherlinkEnabled: boolean;
 }
 
 export const featureConfig: FeatureConfig = {
   isMonadEnabled: true,
-  isAvalancheEnabled: false,
+  // Avalanche mainnet - BTC.b not released yet, keep disabled
+  isAvalancheMainnetEnabled: false,
+  // Avalanche Fuji testnet - enabled for testing (Silo integration)
+  isAvalancheFujiEnabled: true,
+
+  isCornEnabled: true,
+  // APP-1975: Chains in asset catalog but not yet fully supported
+  // These are hidden from UI until fully tested and released
+  isBerachainEnabled: false,
+  isMorphEnabled: false,
+  isSwellchainEnabled: false,
+  isTacEnabled: false,
+  isBobEnabled: false,
+  isEtherlinkEnabled: false,
 };

package/src/common/fee-requirements.ts

@@ -0,0 +1,34 @@
+/**
+ * Network fee requirement utilities
+ *
+ * Determines which chains require network fee authorization for auto-minting.
+ */
+
+import type { ChainId } from './chains';
+
+/**
+ * Chains that require network fee authorization (auto-mint fee)
+ *
+ * Ethereum mainnet and Sepolia (testnet) require fee authorization.
+ * Other chains (Base, BSC, etc.) are subsidized - Lombard absorbs gas costs.
+ */
+export const AUTO_MINT_FEE_CHAINS: readonly ChainId[] = [
+  1, // Ethereum mainnet
+  11155111, // Sepolia (testnet/stage)
+] as const;
+
+/**
+ * Check if a chain requires network fee authorization
+ *
+ * @param chainId - The chain ID to check
+ * @returns True if the chain requires fee authorization
+ *
+ * @example
+ * ```ts
+ * requiresAutoMintFee(1) // true (Ethereum)
+ * requiresAutoMintFee(8453) // false (Base)
+ * ```
+ */
+export function requiresAutoMintFee(chainId: ChainId): boolean {
+  return AUTO_MINT_FEE_CHAINS.includes(chainId);
+}

package/src/config/defaults.ts

@@ -0,0 +1,49 @@
+import type { Env } from '@lombard.finance/sdk-common';
+
+import { ChainId } from '../common/chains';
+
+type ChainDescriptor = {
+  id: ChainId;
+  name: string;
+  type: 'evm' | 'bitcoin' | 'solana' | 'sui' | 'starknet';
+};
+
+interface FeatureFlags {
+  analytics: boolean;
+  sandbox: boolean;
+}
+
+/**
+ * Default configuration for each environment
+ */
+interface DefaultConfig {
+  chains: ChainDescriptor[];
+  features: FeatureFlags;
+}
+
+/**
+ * Get default configuration for an environment
+ *
+ * @param env - Environment identifier
+ * @returns Default configuration for the environment
+ */
+export function getDefaultConfig(env: Env): DefaultConfig {
+  const baseFeatures: FeatureFlags = {
+    analytics: false,
+    sandbox: env !== 'prod',
+  };
+
+  // Default chains based on environment
+  const defaultChains: ChainDescriptor[] = [
+    {
+      id: env === 'prod' ? (1 as ChainId) : (11155111 as ChainId), // Ethereum mainnet or Sepolia
+      name: env === 'prod' ? 'Ethereum' : 'Sepolia',
+      type: 'evm',
+    },
+  ];
+
+  return {
+    chains: defaultChains,
+    features: baseFeatures,
+  };
+}

package/src/config/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Configuration module for the Lombard SDK
+ *
+ * This module provides:
+ * - Provider type definitions and type guards
+ * - SDK configuration types
+ * - Configuration validation and defaults
+ */
+
+export * from './providers';
+export * from './types';
+export * from './validation';

package/src/config/providers.ts

@@ -0,0 +1,81 @@
+export type {
+  AnyProvider,
+  BtcProvider,
+  EvmProvider,
+  ProviderKey,
+  ProviderMap,
+  SolanaProvider,
+  StarknetProvider,
+  SuiProvider,
+} from '@lombard.finance/sdk-common';
+import type {
+  BtcProvider,
+  EvmProvider,
+  SolanaProvider,
+  StarknetProvider,
+  SuiProvider,
+} from '@lombard.finance/sdk-common';
+
+/**
+ * Type guard to check if a provider is an EVM provider
+ */
+export function isEvmProvider(provider: unknown): provider is EvmProvider {
+  return (
+    typeof provider === 'object' &&
+    provider !== null &&
+    'request' in provider &&
+    typeof (provider as EvmProvider).request === 'function'
+  );
+}
+
+/**
+ * Type guard to check if a provider is a Bitcoin provider
+ */
+export function isBtcProvider(provider: unknown): provider is BtcProvider {
+  return (
+    typeof provider === 'object' &&
+    provider !== null &&
+    'getAddresses' in provider &&
+    typeof (provider as BtcProvider).getAddresses === 'function'
+  );
+}
+
+/**
+ * Type guard to check if a provider is a Solana provider
+ */
+export function isSolanaProvider(
+  provider: unknown,
+): provider is SolanaProvider {
+  return (
+    typeof provider === 'object' &&
+    provider !== null &&
+    'publicKey' in provider &&
+    'signAndSendTransaction' in provider
+  );
+}
+
+/**
+ * Type guard to check if a provider is a Sui provider
+ */
+export function isSuiProvider(provider: unknown): provider is SuiProvider {
+  return (
+    typeof provider === 'object' &&
+    provider !== null &&
+    'getAddress' in provider &&
+    'signAndExecuteTransactionBlock' in provider
+  );
+}
+
+/**
+ * Type guard to check if a provider is a Starknet provider
+ */
+export function isStarknetProvider(
+  provider: unknown,
+): provider is StarknetProvider {
+  return (
+    typeof provider === 'object' &&
+    provider !== null &&
+    'address' in provider &&
+    'execute' in provider
+  );
+}