@lombard.finance/sdk 3.7.3 → 4.0.0

package/src/tokens/token-addresses.ts

@@ -1,3 +1,21 @@
+/**
+ * Token Address Constants
+ *
+ * @deprecated v4.1 Migration Target
+ *
+ * This module contains hardcoded token addresses. For v4.1, these should be
+ * migrated to use the Asset Catalog (`core/assets/`) which supports dynamic
+ * address loading from remote sources.
+ *
+ * See: docs/ADDRESS_SYSTEM_UNIFICATION.md
+ *
+ * Current usage (~26 files) should migrate to:
+ * - `getAssetAddress()` from `core/assets/utils`
+ * - Pass `catalog` from `ResolvedLombardConfig`
+ *
+ * @module tokens/token-addresses
+ */
+
 import { DEFAULT_ENV, Env } from '@lombard.finance/sdk-common';
 import { Address } from 'viem';
 
@@ -112,7 +130,7 @@ type TokenAddresses<
 const EVM_BTCB_ADDRESSES: TokenAddressesPerEnv<Token.BTCb, ChainId> = {
   [Env.prod]: {
     [ChainId.katana]: '0xB0F70C0bD6FD87dbEb7C10dC692a2a6106817072',
-    ...(featureConfig.isAvalancheEnabled
+    ...(featureConfig.isAvalancheMainnetEnabled
       ? {
           [ChainId.avalanche]: {
             token: '0x152b9d0FdC40C096757F570A51E494bd4b943E50',
@@ -129,7 +147,7 @@ const EVM_BTCB_ADDRESSES: TokenAddressesPerEnv<Token.BTCb, ChainId> = {
     [ChainId.stable]: '0xB0F70C0bD6FD87dbEb7C10dC692a2a6106817072',
   },
   [Env.ibc]: {
-    ...(featureConfig.isAvalancheEnabled
+    ...(featureConfig.isAvalancheFujiEnabled
       ? {
           [ChainId.avalancheFuji]: {
             adapter: '0x1391f9AC408cf13214DDB71d359002658eaF9ebb',
@@ -139,7 +157,7 @@ const EVM_BTCB_ADDRESSES: TokenAddressesPerEnv<Token.BTCb, ChainId> = {
       : {}),
   },
   [Env.dev]: {
-    ...(featureConfig.isAvalancheEnabled
+    ...(featureConfig.isAvalancheFujiEnabled
       ? {
           [ChainId.avalancheFuji]: {
             adapter: '0x0A65C37d07c32E5eA8ea40495b7f249cdE26935e',
@@ -153,11 +171,19 @@ const EVM_BTCB_ADDRESSES: TokenAddressesPerEnv<Token.BTCb, ChainId> = {
     [ChainId.katanaTatara]: '0xA74D838817f3098166d74a141b7d241efB15F42c',
   },
   [Env.stage]: {
+    ...(featureConfig.isAvalancheFujiEnabled
+      ? {
+          [ChainId.avalancheFuji]: {
+            adapter: '0x0A65C37d07c32E5eA8ea40495b7f249cdE26935e',
+            token: '0x7FbdC44BfEBDe80C970ba622B678daB36cee31f6',
+          },
+        }
+      : {}),
     [ChainId.sepolia]: '0x600e4006278EB11FA1691cA0FE6C5fcfC4992d58',
     [ChainId.katanaTatara]: '0x600e4006278EB11FA1691cA0FE6C5fcfC4992d58',
   },
   [Env.testnet]: {
-    ...(featureConfig.isAvalancheEnabled
+    ...(featureConfig.isAvalancheFujiEnabled
       ? {
           [ChainId.avalancheFuji]: {
             adapter: '0x41BCd71e7C92b1c8dDe53037F9b2c4AA2058b1cB',
@@ -173,7 +199,7 @@ const EVM_BTCB_ADDRESSES: TokenAddressesPerEnv<Token.BTCb, ChainId> = {
 export const EVM_LBTC_ADDRESSES: TokenAddressesPerEnv<Token.LBTC, ChainId> = {
   [Env.prod]: {
     [ChainId.ethereum]: '0x8236a87084f8b84306f72007f36f2618a5634494',
-    ...(featureConfig.isAvalancheEnabled
+    ...(featureConfig.isAvalancheMainnetEnabled
       ? {
           [ChainId.avalanche]: undefined,
         }
@@ -184,6 +210,7 @@ export const EVM_LBTC_ADDRESSES: TokenAddressesPerEnv<Token.LBTC, ChainId> = {
     [ChainId.corn]: '0xecAc9C5F704e954931349Da37F60E39f515c11c1',
     [ChainId.etherlink]: '0xecAc9C5F704e954931349Da37F60E39f515c11c1',
     [ChainId.katana]: '0xecAc9C5F704e954931349Da37F60E39f515c11c1',
+    [ChainId.megaeth]: '0xecAc9C5F704e954931349Da37F60E39f515c11c1',
     [ChainId.morph]: '0xecAc9C5F704e954931349Da37F60E39f515c11c1',
     [ChainId.sonic]: '0xecAc9C5F704e954931349Da37F60E39f515c11c1',
     [ChainId.stable]: '0xecAc9C5F704e954931349Da37F60E39f515c11c1',
@@ -195,10 +222,9 @@ export const EVM_LBTC_ADDRESSES: TokenAddressesPerEnv<Token.LBTC, ChainId> = {
           [ChainId.monad]: '0xecAc9C5F704e954931349Da37F60E39f515c11c1',
         }
       : {}),
-    [ChainId.megaeth]: '0xecAc9C5F704e954931349Da37F60E39f515c11c1',
   },
   [Env.stage]: {
-    ...(featureConfig.isAvalancheEnabled
+    ...(featureConfig.isAvalancheFujiEnabled
       ? {
           [ChainId.avalancheFuji]: undefined,
         }
@@ -214,11 +240,12 @@ export const EVM_LBTC_ADDRESSES: TokenAddressesPerEnv<Token.LBTC, ChainId> = {
     [ChainId.sonicBlazeTestnet]: '0x731eFa688F3679688cf60A3993b8658138953ED6',
   },
   [Env.testnet]: {
-    ...(featureConfig.isAvalancheEnabled
+    ...(featureConfig.isAvalancheFujiEnabled
       ? {
           [ChainId.avalancheFuji]: '0x107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5',
         }
       : {}),
+    [ChainId.baseSepoliaTestnet]: '0x107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5',
     [ChainId.berachainBartioTestnet]:
       '0xc47e4b3124597FDF8DD07843D4a7052F2eE80C30',
     [ChainId.binanceSmartChainTestnet]:
@@ -227,10 +254,9 @@ export const EVM_LBTC_ADDRESSES: TokenAddressesPerEnv<Token.LBTC, ChainId> = {
     [ChainId.sepolia]: '0x107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5',
     [ChainId.sonicBlazeTestnet]: '0x107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5',
     [ChainId.katanaTatara]: '0x107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5',
-    [ChainId.baseSepoliaTestnet]: '0x107Fc7d90484534704dD2A9e24c7BD45DB4dD1B5',
   },
   [Env.dev]: {
-    ...(featureConfig.isAvalancheEnabled
+    ...(featureConfig.isAvalancheFujiEnabled
       ? {
           [ChainId.avalancheFuji]: '0xc47e4b3124597FDF8DD07843D4a7052F2eE80C30',
         }
@@ -356,6 +382,29 @@ export const getTokenByAddress = (
   }
 };
 
+export const getTokenAddressForChain = (
+  chainId: ChainId | SuiChain | SolanaChain | StarknetChainId,
+  adapter: AddressKind = AddressKind.Token,
+  env: Env = DEFAULT_ENV,
+): string | undefined => {
+  if (isValidChain(chainId)) {
+    const found = TOKEN_ADDRESSES[Token.LBTC]?.[env]?.[chainId];
+    if (found) {
+      return typeof found === 'string' ? found : found[adapter];
+    }
+  }
+  if (isSuiChain(chainId)) {
+    return SUI_TOKEN_ADDRESSES[Token.LBTC]?.[env]?.[chainId];
+  }
+  if (isSolanaChain(chainId)) {
+    return SOLANA_TOKEN_ADDRESSES[Token.LBTC]?.[env]?.[chainId];
+  }
+  if (isStarknetChainId(chainId)) {
+    return STARKNET_TOKEN_ADDRESSES[Token.LBTC]?.[env]?.[chainId];
+  }
+  return undefined;
+};
+
 // Starknet token addresses
 // See: packages/sdk-starknet/src/tokens/lib/tokens.ts
 export const STARKNET_TOKEN_ADDRESSES: TokenAddresses<

package/src/tokens/tokens.ts

@@ -1,3 +1,16 @@
+/**
+ * Token Contract Utilities
+ *
+ * @deprecated v4.1 Migration Target
+ *
+ * Functions like `getTokenContractInfo()` use hardcoded TOKEN_ADDRESSES.
+ * For v4.1, migrate to use Asset Catalog with catalog injection.
+ *
+ * See: docs/ADDRESS_SYSTEM_UNIFICATION.md
+ *
+ * @module tokens/tokens
+ */
+
 import { DEFAULT_ENV, Env } from '@lombard.finance/sdk-common';
 import BigNumber from 'bignumber.js';
 import { type Abi, Address, erc20Abi, PublicClient, zeroAddress } from 'viem';
@@ -10,7 +23,7 @@ import BTCK_ABI from './abi/BTCK_ABI';
 import { LBTC_ABI } from './abi/LBTC_ABI';
 import NATIVE_LBTC_ABI from './abi/NATIVE_LBTC_ABI';
 import STLBTC_ABI from './abi/STLBTC_ABI';
-import { AddressKind, Token, TOKEN_ADDRESSES } from './token-addresses';
+import { AddressKind, Token,TOKEN_ADDRESSES } from './token-addresses';
 
 export type TokenInfo = {
   address: Address;
@@ -117,6 +130,7 @@ export async function getTokenContractInfo<
 
   let abi: AbiFor<TToken, chain, TAddressKind> | undefined = undefined;
 
+  // nosemgrep: codacy.tools-configs.rules_lgpl_javascript_crypto_rule-node-timing-attack -- comparing Token enum values, not secrets
   if (token === Token.LBTC) {
     if (await isUpgradedContract(Token.LBTC, chainId, environment)) {
       abi = STLBTC_ABI as AbiFor<TToken, chain, TAddressKind>;

package/src/utils/chain.ts

@@ -0,0 +1,152 @@
+/**
+ * Chain Utility Functions
+ *
+ * Provides type-safe utilities for working with Chain enum values.
+ * Handles parsing and validation of CAIP-2 chain identifiers.
+ *
+ * @module utils/chain
+ */
+
+import { CAIP2_SEPARATOR, Chain,CHAIN_PREFIXES } from '../core';
+import { LombardError, ValidationErrorCode } from '../shared/errors';
+
+/** Helper to get prefix with separator */
+const withSeparator = (prefix: string) => `${prefix}${CAIP2_SEPARATOR}`;
+
+/**
+ * Parse EVM chain ID from Chain enum
+ *
+ * Extracts the numeric chain ID from an EVM chain identifier.
+ *
+ * @param chain - Chain enum value
+ * @returns Numeric EVM chain ID
+ * @throws {ValidationError} If chain is not an EVM chain
+ *
+ * @example
+ * ```typescript
+ * parseEvmChainId(Chain.ETHEREUM) // 1
+ * parseEvmChainId(Chain.BASE) // 8453
+ * parseEvmChainId(Chain.BITCOIN_MAINNET) // throws ValidationError
+ * ```
+ */
+export function parseEvmChainId(chain: Chain): number {
+  const chainStr = String(chain);
+  const evmPrefix = withSeparator(CHAIN_PREFIXES.EIP155);
+  const isEvm = chainStr.startsWith(evmPrefix);
+
+  if (!isEvm) {
+    throw new LombardError(
+      ValidationErrorCode.INVALID_PARAMETER,
+      `Not an EVM chain: ${chainStr}`,
+    );
+  }
+
+  const chainId = Number.parseInt(chainStr.slice(evmPrefix.length), 10);
+
+  if (Number.isNaN(chainId)) {
+    throw new LombardError(
+      ValidationErrorCode.INVALID_PARAMETER,
+      `Invalid EVM chain ID: ${chainStr}`,
+    );
+  }
+
+  return chainId;
+}
+
+/**
+ * Check if chain is an EVM chain
+ *
+ * @param chain - Chain enum value
+ * @returns True if chain is an EVM chain
+ *
+ * @example
+ * ```typescript
+ * isEvmChain(Chain.ETHEREUM) // true
+ * isEvmChain(Chain.BITCOIN_MAINNET) // false
+ * ```
+ */
+export function isEvmChain(chain: Chain): boolean {
+  return String(chain).startsWith(withSeparator(CHAIN_PREFIXES.EIP155));
+}
+
+/**
+ * Check if chain is a Bitcoin chain
+ *
+ * @param chain - Chain enum value
+ * @returns True if chain is a Bitcoin chain
+ *
+ * @example
+ * ```typescript
+ * isBitcoinChain(Chain.BITCOIN_MAINNET) // true
+ * isBitcoinChain(Chain.ETHEREUM) // false
+ * ```
+ */
+export function isBitcoinChain(chain: Chain): boolean {
+  return String(chain).startsWith(withSeparator(CHAIN_PREFIXES.BIP122));
+}
+
+/**
+ * Check if chain is a Solana chain
+ *
+ * @param chain - Chain enum value
+ * @returns True if chain is a Solana chain
+ *
+ * @example
+ * ```typescript
+ * isSolanaChain(Chain.SOLANA_MAINNET) // true
+ * isSolanaChain(Chain.ETHEREUM) // false
+ * ```
+ */
+export function isSolanaChain(chain: Chain): boolean {
+  return String(chain).startsWith(withSeparator(CHAIN_PREFIXES.SOLANA));
+}
+
+/**
+ * Check if chain is a Sui chain
+ *
+ * @param chain - Chain enum value
+ * @returns True if chain is a Sui chain
+ *
+ * @example
+ * ```typescript
+ * isSuiChain(Chain.SUI_MAINNET) // true
+ * isSuiChain(Chain.ETHEREUM) // false
+ * ```
+ */
+export function isSuiChain(chain: Chain): boolean {
+  return String(chain).startsWith(withSeparator(CHAIN_PREFIXES.SUI));
+}
+
+/**
+ * Check if chain is a Starknet chain
+ *
+ * @param chain - Chain enum value
+ * @returns True if chain is a Starknet chain
+ *
+ * @example
+ * ```typescript
+ * isStarknetChain(Chain.STARKNET_MAINNET) // true
+ * isStarknetChain(Chain.ETHEREUM) // false
+ * ```
+ */
+export function isStarknetChain(chain: Chain): boolean {
+  return String(chain).startsWith(withSeparator(CHAIN_PREFIXES.STARKNET));
+}
+
+/**
+ * Get chain namespace from Chain enum
+ *
+ * Returns the CAIP-2 namespace prefix (eip155, bip122, solana, etc.)
+ *
+ * @param chain - Chain enum value
+ * @returns CAIP-2 namespace string
+ *
+ * @example
+ * ```typescript
+ * getChainNamespace(Chain.ETHEREUM) // 'eip155'
+ * getChainNamespace(Chain.BITCOIN_MAINNET) // 'bip122'
+ * ```
+ */
+export function getChainNamespace(chain: Chain): string {
+  return String(chain).split(CAIP2_SEPARATOR)[0];
+}

package/src/utils/consoleLogger.ts

@@ -0,0 +1,140 @@
+/**
+ * Console Logger Factory
+ *
+ * Creates a logger that outputs to the console with configurable log levels.
+ * Used when `debug: true` is set in SDK configuration.
+ *
+ * @module utils/consoleLogger
+ */
+
+import type { Logger } from '../shared/context/types';
+
+/**
+ * Log level hierarchy (from most to least verbose)
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+
+/**
+ * Options for creating a console logger
+ */
+export interface ConsoleLoggerOptions {
+  /**
+   * Minimum log level to output
+   *
+   * - 'debug': All logs (most verbose)
+   * - 'info': Info, warnings, and errors
+   * - 'warn': Warnings and errors only
+   * - 'error': Errors only
+   * - 'none': No logs (silent)
+   *
+   * @default 'debug'
+   */
+  level?: LogLevel;
+
+  /**
+   * Prefix for all log messages
+   *
+   * @default '[Lombard SDK]'
+   */
+  prefix?: string;
+
+  /**
+   * Include timestamp in log messages
+   *
+   * @default false
+   */
+  timestamp?: boolean;
+}
+
+const LOG_LEVELS: LogLevel[] = ['debug', 'info', 'warn', 'error', 'none'];
+
+/**
+ * Create a console logger with configurable options
+ *
+ * @param options - Logger configuration options
+ * @returns Logger instance that outputs to console
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - log everything
+ * const logger = createConsoleLogger();
+ *
+ * // Only warnings and errors
+ * const logger = createConsoleLogger({ level: 'warn' });
+ *
+ * // Custom prefix with timestamp
+ * const logger = createConsoleLogger({
+ *   prefix: '[MyApp SDK]',
+ *   timestamp: true,
+ * });
+ * ```
+ */
+export function createConsoleLogger(
+  options: ConsoleLoggerOptions = {},
+): Logger {
+  const { level = 'debug', prefix = '[Lombard SDK]', timestamp = false } = options;
+
+  const minLevelIndex = LOG_LEVELS.indexOf(level);
+
+  const shouldLog = (logLevel: LogLevel): boolean => {
+    const levelIndex = LOG_LEVELS.indexOf(logLevel);
+    return levelIndex >= minLevelIndex && level !== 'none';
+  };
+
+  const formatMessage = (msg: string): string => {
+    if (timestamp) {
+      const ts = new Date().toISOString();
+      return `${prefix} ${ts} ${msg}`;
+    }
+    return `${prefix} ${msg}`;
+  };
+
+  const formatMeta = (meta?: Record<string, unknown>): unknown[] => {
+    if (!meta || Object.keys(meta).length === 0) {
+      return [];
+    }
+    return [meta];
+  };
+
+  return {
+    debug(message: string, meta?: Record<string, unknown>): void {
+      if (shouldLog('debug')) {
+        console.debug(formatMessage(message), ...formatMeta(meta));
+      }
+    },
+
+    info(message: string, meta?: Record<string, unknown>): void {
+      if (shouldLog('info')) {
+        console.info(formatMessage(message), ...formatMeta(meta));
+      }
+    },
+
+    warn(message: string, meta?: Record<string, unknown>): void {
+      if (shouldLog('warn')) {
+        console.warn(formatMessage(message), ...formatMeta(meta));
+      }
+    },
+
+    error(message: string, meta?: Record<string, unknown>): void {
+      if (shouldLog('error')) {
+        console.error(formatMessage(message), ...formatMeta(meta));
+      }
+    },
+  };
+}
+
+/**
+ * Create a silent logger (no-op)
+ *
+ * Useful for testing or when you want to suppress all logs.
+ */
+export function createSilentLogger(): Logger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  };
+}
+
+

package/src/utils/ensureNotSanctionedAddress.ts

@@ -0,0 +1,11 @@
+import { SANCTIONED_ADDRESS } from '../api-functions/generateDepositBtcAddress/generateDepositBtcAddress';
+import { LombardError, ValidationErrorCode } from '../shared/errors';
+
+export function ensureNotSanctionedAddress(address: string): void {
+  if (address === SANCTIONED_ADDRESS) {
+    throw new LombardError(
+      ValidationErrorCode.INVALID_PARAMETER,
+      'Destination address is under sanctions',
+    );
+  }
+}

package/src/utils/evmAccount.ts

@@ -0,0 +1,47 @@
+import type { Address } from 'viem';
+
+import type { EvmProvider } from '../config/providers';
+
+export class WalletError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'WalletError';
+  }
+}
+
+/**
+ * Retrieve the active EVM account from an EIP-1193 provider.
+ *
+ * Attempts a silent `eth_accounts` call first, then falls back to
+ * `eth_requestAccounts` to prompt the wallet if necessary.
+ */
+export async function getActiveEvmAccount(
+  provider: EvmProvider,
+): Promise<Address> {
+  try {
+    const accounts = (await provider.request({
+      method: 'eth_accounts',
+    })) as string[] | undefined;
+
+    const account =
+      accounts?.[0] ??
+      (
+        (await provider.request({
+          method: 'eth_requestAccounts',
+        })) as string[] | undefined
+      )?.[0];
+
+    if (!account) {
+      throw new WalletError('Wallet not connected');
+    }
+
+    return account as Address;
+  } catch (error) {
+    if (error instanceof WalletError) {
+      throw error;
+    }
+    throw new WalletError('Failed to retrieve wallet account', {
+      cause: error as Error,
+    });
+  }
+}