@lombard.finance/sdk 3.7.3 → 4.0.0

package/src/config/types.ts

@@ -0,0 +1,216 @@
+/**
+ * Configuration types for the Lombard SDK
+ *
+ * This module defines the types for SDK configuration, including
+ * provider getters, partner configuration, and custom asset registration.
+ */
+
+import type { AnyModule, Env } from '@lombard.finance/sdk-common';
+
+import type { AssetId, Chain } from '../core';
+import type { Logger } from '../shared/context/types';
+import type {
+  BtcProvider,
+  EvmProvider,
+  SolanaProvider,
+  StarknetProvider,
+  SuiProvider,
+} from './providers';
+
+/**
+ * Provider getter function
+ *
+ * A function that returns a provider instance for a specific chain.
+ * This allows lazy loading of providers only when needed.
+ *
+ * @param chain - Optional chain identifier (for multi-chain providers like EVM)
+ * @returns Provider instance or promise of provider instance
+ */
+export type ProviderGetter<TProvider> = (
+  chain?: Chain,
+) => TProvider | Promise<TProvider>;
+
+export interface ProviderGetters {
+  evm?: ProviderGetter<EvmProvider>;
+  bitcoin?: ProviderGetter<BtcProvider>;
+  solana?: ProviderGetter<SolanaProvider>;
+  sui?: ProviderGetter<SuiProvider>;
+  starknet?: ProviderGetter<StarknetProvider>;
+}
+
+/**
+ * Get provider getter from config by key
+ *
+ * Uses explicit property access to avoid security concerns with dynamic keys.
+ * This pattern is required by static analysis tools (Codacy/Semgrep) to prevent
+ * potential object injection vulnerabilities.
+ *
+ * @param providers - Provider getters configuration
+ * @param key - Provider key to retrieve
+ * @returns Provider getter function or undefined if not configured
+ */
+export function getProviderGetter<T = unknown>(
+  providers: ProviderGetters,
+  key: string,
+): ProviderGetter<T> | undefined {
+  let getter: ProviderGetter<unknown> | undefined;
+  switch (key) {
+    case 'evm':
+      getter = providers.evm;
+      break;
+    case 'bitcoin':
+      getter = providers.bitcoin;
+      break;
+    case 'solana':
+      getter = providers.solana;
+      break;
+    case 'sui':
+      getter = providers.sui;
+      break;
+    case 'starknet':
+      getter = providers.starknet;
+      break;
+    default:
+      getter = undefined;
+  }
+  return getter as ProviderGetter<T> | undefined;
+}
+
+/**
+ * SDK configuration options
+ *
+ * Options passed to createConfig(). `modules` is optional; built-ins are
+ * registered automatically if not provided.
+ *
+ * @example
+ * ```typescript
+ * // Config is synchronous - can be exported directly
+ * export const config = createConfig({
+ *   env: Env.prod,
+ *   providers: { evm: () => window.ethereum },
+ *   debug: true,  // Enable console logging
+ * });
+ *
+ * // SDK creation is async (fetches catalog)
+ * const sdk = await createLombardSDK(config);
+ * ```
+ */
+export interface CreateConfigOptions {
+  /** Environment (prod, testnet, stage, dev) */
+  env: Env;
+
+  /** Wallet provider getters for each chain */
+  providers?: ProviderGetters;
+
+  /** Optional modules to register */
+  modules?: readonly AnyModule[];
+
+  /** Partner configuration */
+  partner?: PartnerConfig;
+
+  /**
+   * Optional logger for SDK operations
+   *
+   * Provide your own logger to integrate with your logging infrastructure
+   * (e.g., Sentry, DataDog, custom logging).
+   *
+   * @example
+   * ```typescript
+   * logger: {
+   *   error: (msg, meta) => Sentry.captureMessage(msg, { extra: meta }),
+   *   warn: console.warn,
+   *   info: console.info,
+   *   debug: () => {},  // Suppress debug logs
+   * }
+   * ```
+   */
+  logger?: Logger;
+
+  /**
+   * Enable debug mode
+   *
+   * When true, creates a console logger that outputs all SDK operations.
+   * Useful for development and debugging.
+   *
+   * Note: If both `logger` and `debug` are provided, `logger` takes precedence.
+   *
+   * @default false
+   */
+  debug?: boolean;
+}
+
+/**
+ * Validated SDK configuration
+ *
+ * Configuration object returned by createConfig(). This is a plain,
+ * synchronous object that can be exported from a module and passed around.
+ *
+ * The asset catalog is NOT included here - it's fetched asynchronously
+ * when createLombardSDK() is called.
+ */
+export interface LombardConfig {
+  env: Env;
+  providers: ProviderGetters;
+  modules: readonly AnyModule[];
+  partner?: PartnerConfig;
+  logger?: Logger;
+}
+
+/**
+ * Resolved SDK configuration (internal)
+ *
+ * Extended config with the asset catalog, used internally by LombardSDK.
+ * Users don't interact with this type directly.
+ *
+ * @internal
+ */
+export interface ResolvedLombardConfig extends LombardConfig {
+  /**
+   * Asset catalog (fetched during SDK initialization)
+   *
+   * Contains all asset deployments, chain configs, and addresses.
+   * This is fetched asynchronously during createLombardSDK() to allow
+   * for dynamic updates without SDK releases.
+   */
+  catalog: import('../core/assets/types').AssetCatalog;
+}
+
+export type LombardSDKOptions = CreateConfigOptions;
+
+/**
+ * Partner configuration
+ *
+ * Configuration for partners integrating the SDK.
+ */
+export interface PartnerConfig {
+  /** Unique partner identifier */
+  partnerId: string;
+}
+
+/**
+ * Custom asset registration
+ *
+ * Allows partners to register custom assets (e.g., SPL tokens).
+ */
+export interface CustomAsset {
+  /** Asset type */
+  type: 'spl' | 'erc20' | 'native';
+
+  /** Contract address (for token assets) */
+  address?: string;
+
+  /** Asset symbol */
+  symbol: string;
+
+  /** Number of decimals */
+  decimals: number;
+
+  /** L-Asset symbol (how it will be named in Lombard) */
+  lAssetSymbol: string;
+
+  /** Chain where the asset exists */
+  chain?: Chain;
+
+  /** Optional: Asset ID mapping */
+  assetId?: AssetId;
+}

package/src/config/validation.ts

@@ -0,0 +1,69 @@
+/**
+ * Configuration validation and defaults
+ *
+ * This module provides validation and default application for SDK configuration.
+ */
+
+import { LombardError } from '../shared/errors';
+import type { CreateConfigOptions, LombardConfig } from './types';
+
+/**
+ * Normalized options after validation (before modules/logger are added)
+ * @internal
+ */
+export type NormalizedOptions = Omit<LombardConfig, 'modules' | 'logger'>;
+
+/**
+ * Validate and apply defaults to SDK options
+ *
+ * @param options - User-provided SDK options
+ * @returns Validated and normalized options (catalog added separately)
+ * @throws LombardError if configuration is invalid
+ * @internal
+ */
+export function validateAndApplyDefaults(
+  options: CreateConfigOptions,
+): NormalizedOptions {
+  // Validate environment
+  if (!options.env) {
+    throw LombardError.missingParameter('env');
+  }
+
+  // Build normalized options with defaults
+  const normalized: NormalizedOptions = {
+    env: options.env,
+    providers: options.providers || {},
+  };
+
+  // Add partner config if provided
+  if (options.partner) {
+    validatePartnerConfig(options.partner);
+    normalized.partner = options.partner;
+  }
+
+  return normalized;
+}
+
+/**
+ * Validate partner configuration
+ *
+ * @param partner - Partner configuration to validate
+ * @throws LombardError if configuration is invalid
+ */
+function validatePartnerConfig(partner: unknown): void {
+  if (typeof partner !== 'object' || partner === null) {
+    throw LombardError.invalidConfiguration(
+      'Partner configuration must be an object',
+    );
+  }
+
+  const config = partner as { partnerId?: string };
+
+  if (!config.partnerId || typeof config.partnerId !== 'string') {
+    throw LombardError.missingParameter('partner.partnerId');
+  }
+
+  if (config.partnerId.trim().length === 0) {
+    throw LombardError.invalidConfiguration('Partner ID cannot be empty');
+  }
+}

package/src/contract-functions/approveLBTC/approveLBTC.stories.tsx

@@ -1,5 +1,6 @@
 import { Env } from '@lombard.finance/sdk-common';
 import type { Meta, StoryObj } from '@storybook/react';
+
 import { ChainId } from '../../common/chains';
 import { chainSelector } from '../../stories/arg-types';
 import { Button } from '../../stories/components/Button';
@@ -14,8 +15,8 @@ import {
   useConnection,
 } from '../../stories/hooks/useConnection';
 import useQuery from '../../stories/hooks/useQuery';
-import { VAULTS, Vault } from '../../vaults/lib/config';
-import { IApproveLBTCParams, approveLBTC } from './approveLBTC';
+import { Vault,VAULTS } from '../../vaults/lib/config';
+import { approveLBTC,IApproveLBTCParams } from './approveLBTC';
 
 const meta = {
   title: 'write/approveLBTC',
@@ -31,8 +32,8 @@ type Story = StoryObj<typeof meta>;
 
 export const WithParams: Story = {
   args: {
-    chainId: ChainId.holesky,
-    spender: VAULTS[Vault.Veda].spenderContracts[ChainId.holesky]?.address,
+    chainId: ChainId.sepolia,
+    spender: VAULTS[Vault.Veda].spenderContracts[ChainId.sepolia]?.address,
     amount: 0.00001,
     env: Env.stage,
   },

package/src/contract-functions/claimLBTC/claimLBTC.stories.tsx

@@ -1,5 +1,6 @@
 import { DEFAULT_ENV } from '@lombard.finance/sdk-common';
 import type { Meta, StoryObj } from '@storybook/react';
+
 import { makeTokenSelector } from '../../stories/arg-types';
 import { Button } from '../../stories/components/Button';
 import { CodeBlock } from '../../stories/components/CodeBlock';

package/src/contract-functions/deposit/depositToken.stories.tsx

@@ -1,5 +1,6 @@
 import { DEFAULT_ENV } from '@lombard.finance/sdk-common';
 import type { Meta, StoryObj } from '@storybook/react';
+
 import { makeTokenSelector } from '../../stories/arg-types';
 import { Button } from '../../stories/components/Button';
 import { CodeBlock } from '../../stories/components/CodeBlock';

package/src/contract-functions/getBasculeDepositStatus/getBasculeDepositStatus.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
+
 import { ChainId } from '../../common/chains';
 import {
   chainSelector,
@@ -11,8 +12,8 @@ import { functionType } from '../../stories/components/decorators';
 import useQuery from '../../stories/hooks/useQuery';
 import { Token } from '../../tokens/token-addresses';
 import {
-  IGetBasculeDepositStatusParameters,
   getBasculeDepositStatus,
+  IGetBasculeDepositStatusParameters,
 } from './getBasculeDepositStatus';
 
 const meta = {

package/src/contract-functions/getLBTCMintingFee/getLBTCMintingFee.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
+
 import { ChainId } from '../../common/chains';
 import { chainSelector, envSelector } from '../../stories/arg-types';
 import { Button } from '../../stories/components/Button';

package/src/contract-functions/getLBTCTotalSupply/getLBTCTotalSupply.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
+
 import { ChainId } from '../../common/chains';
 import { chainSelector, envSelector } from '../../stories/arg-types';
 import { Button } from '../../stories/components/Button';

package/src/contract-functions/getPermitNonce/getPermitNonce.stories.tsx

@@ -1,9 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react';
+
 import { Button } from '../../stories/components/Button';
 import { CodeBlock } from '../../stories/components/CodeBlock';
 import { functionType } from '../../stories/components/decorators';
 import useQuery from '../../stories/hooks/useQuery';
-import { IGetPermitNonceParams, getPermitNonce } from './getPermitNonce';
+import { getPermitNonce } from './getPermitNonce';
 
 const meta = {
   title: 'read/getPermitNonce',

package/src/contract-functions/getShareValue/getShareValue.stories.tsx

@@ -5,7 +5,7 @@ import { Button } from '../../stories/components/Button';
 import { functionType } from '../../stories/components/decorators';
 import useQuery from '../../stories/hooks/useQuery';
 import { Vault } from '../../vaults/lib/config';
-import { IGetShareValueParameters, getShareValue } from './getShareValue';
+import { getShareValue,IGetShareValueParameters } from './getShareValue';
 
 const meta = {
   title: 'read/getShareValue',
@@ -32,7 +32,7 @@ export function StoryView(props: IGetShareValueParameters) {
     });
   };
 
-  const { data, error, isLoading, refetch } = useQuery(request, [], false);
+  const { data, error: _error, isLoading, refetch } = useQuery(request, [], false);
 
   const value = data?.toString();
 
@@ -47,8 +47,10 @@ export function StoryView(props: IGetShareValueParameters) {
 
       {data && (
         <div className="mt-4 p-4 border rounded">
-          <h3 className="text-lg font-bold mb-2">LBTCv share value</h3>
-          <p>1 LBTCv = {value} LBTC</p>
+          <h3 className="text-lg font-bold mb-2">
+            LBTCv (Vault shares) share value
+          </h3>
+          <p>1 LBTCv (Vault shares) = {value} LBTC</p>
         </div>
       )}
     </div>

package/src/contract-functions/getSharesByAddress/getSharesByAddress.stories.tsx

@@ -8,8 +8,8 @@ import { EXAMPLE_EVM_ADDRESS } from '../../stories/constants';
 import useQuery from '../../stories/hooks/useQuery';
 import { Vault } from '../../vaults/lib/config';
 import {
-  IGetSharesByAddressParameters,
   getSharesByAddress,
+  IGetSharesByAddressParameters,
 } from './getSharesByAddress';
 
 const meta = {
@@ -53,9 +53,9 @@ export function StoryView(props: IGetSharesByAddressParameters) {
 
       {data && (
         <div className="mt-4 p-4 border rounded">
-          <h3 className="text-lg font-bold mb-2">LBTCv shares owned</h3>
+          <h3 className="text-lg font-bold mb-2">Vault shares owned</h3>
           <p>
-            <b>{data.balance.toString()}</b> LBTCv ={' '}
+            <b>{data.balance.toString()}</b> Vault shares ={' '}
             {data.balanceLbtc.toString()} LBTC
           </p>
         </div>

package/src/contract-functions/getStakeAndBakeFee/getStakeAndBakeFee.stories.tsx

@@ -10,8 +10,8 @@ import useQuery from '../../stories/hooks/useQuery';
 import { Token } from '../../tokens/token-addresses';
 import { VEDA_VAULT_STAKE_AND_BAKE_CHAINS } from '../../vaults/lib/config';
 import {
-  IGetStakeAndBakeFeeParams,
   getStakeAndBakeFee,
+  IGetStakeAndBakeFeeParams,
 } from './getStakeAndBakeFee';
 
 const meta = {

package/src/contract-functions/signLbtcDestionationAddr/signLbtcDestionationAddr.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta } from '@storybook/react';
+
 import { Button } from '../../stories/components/Button';
 import { CodeBlock } from '../../stories/components/CodeBlock';
 import { ConnectButton } from '../../stories/components/ConnectButton';

package/src/contract-functions/signNetworkFee/signNetworkFee.stories.tsx

@@ -1,5 +1,6 @@
 import { Env } from '@lombard.finance/sdk-common';
 import type { Meta, StoryObj } from '@storybook/react';
+
 import { Button } from '../../stories/components/Button';
 import { CodeBlock } from '../../stories/components/CodeBlock';
 import { ConnectButton } from '../../stories/components/ConnectButton';

package/src/contract-functions/signStakeAndBake/__tests__/signStakeAndBake.test.ts

@@ -69,6 +69,7 @@ vi.mock('../../../clients/public-client', () => ({
 vi.mock('../../../tokens/tokens', () => ({
   getTokenContractInfo: vi.fn(async (token, chainId, _env, _addressKind) => {
     // Return mock contract info based on token
+    // nosemgrep: codacy.tools-configs.rules_lgpl_javascript_crypto_rule-node-timing-attack -- comparing Token enum values in test mock, not secrets
     if (token === Token.LBTC) {
       return {
         address: '0xLBTC_CONTRACT_ADDRESS',
@@ -157,13 +158,13 @@ describe('signStakeAndBake - Current Behavior Tests', () => {
       });
     });
 
-    it('should generate permit for LBTC on BSC', async () => {
+    it('should generate permit for LBTC on Ethereum', async () => {
       const result = await signStakeAndBake({
         account: MOCK_ACCOUNT,
         value: new BigNumber('0.5'),
         token: Token.LBTC,
         vaultKey: DefiProtocol.Veda,
-        chainId: ChainId.binanceSmartChain,
+        chainId: ChainId.ethereum,
         provider: MOCK_PROVIDER,
         expiry: MOCK_EXPIRY,
         env: Env.prod,
@@ -391,7 +392,7 @@ describe('signStakeAndBake - Current Behavior Tests', () => {
           value: new BigNumber('1'),
           token: Token.BTCb,
           vaultKey: DefiProtocol.Veda, // BTCb not configured for Veda
-          chainId: ChainId.holesky, // BTCb not configured for Holesky
+          chainId: ChainId.sepolia, // BTCb not configured for Sepolia
           provider: MOCK_PROVIDER,
           env: Env.testnet,
         }),
@@ -651,20 +652,20 @@ describe('signStakeAndBake - Current Behavior Tests', () => {
       );
     });
 
-    it('should use correct spender contract for Veda on BSC', async () => {
+    it('should use correct spender contract for Veda on Sepolia (testnet)', async () => {
       const result = await signStakeAndBake({
         account: MOCK_ACCOUNT,
         value: new BigNumber('1'),
         token: Token.LBTC,
         vaultKey: DefiProtocol.Veda,
-        chainId: ChainId.binanceSmartChain,
+        chainId: ChainId.sepolia,
         provider: MOCK_PROVIDER,
-        env: Env.prod,
+        env: Env.testnet,
       });
 
       const typedData = JSON.parse(result.typedData);
       expect(typedData.message.spender).toBe(
-        '0xC8bbF6153D7Ba105f1399D992ebd32B0541996ef',
+        '0x77eD6a84fEF665156e81247ECbd43A847B8A6398',
       );
     });
 
@@ -693,7 +694,7 @@ describe('signStakeAndBake - Current Behavior Tests', () => {
         value: new BigNumber('1'),
         token: Token.LBTC,
         vaultKey: DefiProtocol.Veda,
-        chainId: ChainId.holesky,
+        chainId: ChainId.sepolia,
         provider: MOCK_PROVIDER,
         env: Env.testnet,
       });

package/src/contract-functions/signStakeAndBake/signStakeAndBake.stories.tsx

@@ -1,6 +1,7 @@
 import { Env } from '@lombard.finance/sdk-common';
 import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
+
 import { DefiProtocol } from '../../defi/defi-registry';
 import { Button } from '../../stories/components/Button';
 import { CodeBlock } from '../../stories/components/CodeBlock';

package/src/contract-functions/signStakeAndBake/signStakeAndBake.ts

@@ -93,14 +93,15 @@ export async function signStakeAndBake({
   account,
   expiry = toUnix(now() + DAY),
   value,
-  vaultKey = DefiProtocol.Veda,
+  // TODO: Rename vaultKey to protocol
+  vaultKey: protocol = DefiProtocol.Veda,
   token = 'BTC',
   chainId,
   provider,
   rpcUrl,
   env = DEFAULT_ENV,
 }: ISignStakeAndBakeParams): Promise<ISignStakeAndBakeResult> {
-  const strategy = getStakeAndBakeConfig(vaultKey, token, chainId, env);
+  const strategy = getStakeAndBakeConfig(protocol, token, chainId, env);
 
   const spenderAddress = strategy.spenderContract.address;
 

package/src/contract-functions/signStakeAndBake/validation.ts

@@ -40,28 +40,28 @@ export class StakeAndBakeValidationError extends Error {
  * @throws {StakeAndBakeValidationError} If vault/token/chain/env combination is invalid
  */
 export function getStakeAndBakeConfig(
-  vaultKey: DefiProtocol,
+  protocol: DefiProtocol,
   token: StakeAndBakeToken,
   chainId: ChainId,
   env: Env,
 ): StakeAndBakeStrategy {
   // Get token approval config from DeFi registry
-  const vaultRegistry = DEFI_REGISTRY[vaultKey];
-  if (!vaultRegistry) {
+  const protocolRegistry = DEFI_REGISTRY[protocol];
+  if (!protocolRegistry) {
     throw new StakeAndBakeValidationError(
       'UNSUPPORTED_VAULT',
-      `Vault ${vaultKey} not found in DeFi registry`,
-      { vaultKey },
+      `Vault ${protocol} not found in DeFi registry`,
+      { protocol },
     );
   }
 
-  const tokenRegistry = vaultRegistry[token as keyof typeof vaultRegistry];
+  const tokenRegistry = protocolRegistry[token as keyof typeof protocolRegistry];
   if (!tokenRegistry) {
     throw new StakeAndBakeValidationError(
       'UNSUPPORTED_TOKEN',
-      `Token ${token} is not supported for stake and bake on vault ${vaultKey}. ` +
-        `Supported tokens: ${Object.keys(vaultRegistry).join(', ')}`,
-      { vaultKey, token, supportedTokens: Object.keys(vaultRegistry) },
+      `Token ${token} is not supported for stake and bake on vault ${protocol}. ` +
+        `Supported tokens: ${Object.keys(protocolRegistry).join(', ')}`,
+      { protocol, token, supportedTokens: Object.keys(protocolRegistry) },
     );
   }
 
@@ -69,8 +69,8 @@ export function getStakeAndBakeConfig(
   if (!envRegistry) {
     throw new StakeAndBakeValidationError(
       'UNSUPPORTED_ENV',
-      `Environment ${env} is not supported for token ${token} on vault ${vaultKey}`,
-      { vaultKey, token, env },
+      `Environment ${env} is not supported for token ${token} on vault ${protocol}`,
+      { protocol, token, env },
     );
   }
 
@@ -78,10 +78,10 @@ export function getStakeAndBakeConfig(
   if (!registryEntry) {
     throw new StakeAndBakeValidationError(
       'UNSUPPORTED_TOKEN_CHAIN',
-      `Token ${token} is not supported on chain ${chainId} for vault ${vaultKey} in ${env}. ` +
+      `Token ${token} is not supported on chain ${chainId} for vault ${protocol} in ${env}. ` +
         `Supported chains: ${Object.keys(envRegistry).join(', ')}`,
       {
-        vaultKey,
+        protocol,
         token,
         chainId,
         env,
@@ -91,7 +91,7 @@ export function getStakeAndBakeConfig(
   }
 
   return {
-    protocol: vaultKey,
+    protocol: protocol,
     token,
     env,
     chainId,
@@ -103,20 +103,20 @@ export function getStakeAndBakeConfig(
  * Checks if a token approval config exists for a given vault/token/chain/env combination.
  * Useful for determining if config-driven logic should be used.
  *
- * @param vaultKey - The vault to check
+ * @param protocol - The vault to check
  * @param token - The token to check
  * @param chainId - The chain ID to check
  * @param env - The environment to check
  * @returns true if config exists, false otherwise
  */
 export function hasTokenApprovalConfig(
-  vaultKey: DefiProtocol,
+  protocol: DefiProtocol,
   token: StakeAndBakeToken,
   chainId: ChainId,
   env: Env,
 ): boolean {
   try {
-    const config = getStakeAndBakeConfig(vaultKey, token, chainId, env);
+    const config = getStakeAndBakeConfig(protocol, token, chainId, env);
     return config !== undefined;
   } catch {
     return false;

package/src/contract-functions/unstakeLBTC/unstakeLBTC.stories.tsx

@@ -1,5 +1,6 @@
 import { DEFAULT_ENV } from '@lombard.finance/sdk-common';
 import type { Meta, StoryObj } from '@storybook/react';
+
 import { makeTokenSelector } from '../../stories/arg-types';
 import { Button } from '../../stories/components/Button';
 import { CodeBlock } from '../../stories/components/CodeBlock';