@lombard.finance/sdk 3.7.3 → 4.0.0

package/src/defi/README.md

@@ -101,31 +101,47 @@ export async function signStakeAndBake(params) {
 
 ## 🔧 Adding New Integrations
 
-### Example 1: Add Existing Token to New Chain
+### Example 1: Add Existing Token to New Chain (Veda Stake & Deploy)
 
-**Scenario:** Add LBTC support on Base for Veda protocol.
+**Scenario:** Add LBTC support on a new chain for Veda protocol Stake & Deploy.
+
+**Source of Truth:** `packages/sdk/src/vaults/lib/config.ts`
 
 ```typescript
-// In defi-registry.ts
+// Step 1: In vaults/lib/config.ts - Add chain to VEDA_VAULT_STAKE_AND_BAKE_CHAINS
 
-const VEDA_STAKE_AND_BAKE_CHAINS = [
+export const VEDA_VAULT_STAKE_AND_BAKE_CHAINS = [
   ChainId.ethereum,
   ChainId.binanceSmartChain,
-  ChainId.base, // ← ADD THIS
+  ChainId.base,
+  ChainId.newChain, // ← ADD THIS
   // Testnets:
   ChainId.binanceSmartChainTestnet,
   ChainId.holesky,
-] as const;
-
-// That's it! LBTC now works on Base because it uses forChains()
-// which generates config for all chains in the array.
+];
+
+// Step 2: In vaults/lib/config.ts - Add spender contract
+export const VEDA_VAULT_SPENDER_CONTRACTS: Record<
+  VedaVaultStakeAndBakeChain,
+  ContractInfo
+> = {
+  // ... existing contracts
+  [ChainId.newChain]: {
+    abi: VEDA_VAULT_SPENDER_ABI as Abi,
+    address: '0x...', // Spender contract address on new chain
+    chainId: ChainId.newChain,
+  },
+};
 ```
 
 **What Happens:**
 
-- `forChains()` automatically creates registry entries for all chains
-- LBTC inherits the same `LBTC_PERMIT_CONFIG` on Base
-- Uses the correct spender contract from `VEDA_VAULT_SPENDER_CONTRACTS[ChainId.base]`
+- `DEFI_REGISTRY` imports `VEDA_VAULT_STAKE_AND_BAKE_CHAINS` (single source of truth)
+- LBTC inherits the same `LBTC_PERMIT_CONFIG` on new chain
+- Uses the correct spender contract from `VEDA_VAULT_SPENDER_CONTRACTS`
+
+**Important:** Do NOT add chains directly to `defi-registry.ts` - it uses the imported
+`VEDA_VAULT_STAKE_AND_BAKE_CHAINS` to ensure consistency
 
 ---
 

package/src/defi/defi-registry.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 { CHAIN_ID_TO_VIEM_CHAIN_MAP, ChainId } from '../common/chains';
 import {
   DEFI_REGISTRY,

package/src/defi/defi-registry.ts

@@ -10,10 +10,12 @@ import { Abi } from 'viem';
 
 import { ChainId } from '../common/chains';
 import { ContractInfo } from '../common/contract-info';
+import { AssetId } from '../core/assets';
 import { Token } from '../tokens/token-addresses';
 import { SILO_VAULT_SPENDER_ABI } from '../vaults/abi';
 import {
   VEDA_VAULT_SPENDER_CONTRACTS,
+  VEDA_VAULT_STAKE_AND_BAKE_CHAINS,
   VedaVaultStakeAndBakeChain,
 } from '../vaults/lib/config';
 
@@ -54,12 +56,8 @@ export type StakeAndBakeRegistry = Record<DefiProtocol, TokenStrategyMap>;
 
 const ALL_ENVS = Object.values(Env) as Env[];
 
-const VEDA_STAKE_AND_BAKE_CHAINS = [
-  ChainId.ethereum,
-  ChainId.binanceSmartChain,
-  ChainId.binanceSmartChainTestnet,
-  ChainId.holesky,
-] as const satisfies readonly ChainId[];
+// Use single source of truth from vaults/lib/config.ts
+// VEDA_VAULT_STAKE_AND_BAKE_CHAINS is imported and used directly below
 
 export const SILO_VAULT_SPENDER_CONTRACT_GASTALD_FUJI: `0x${string}` =
   '0xFe1e76D9e065e879A9D1914482f0F13d85F39877';
@@ -94,18 +92,24 @@ function getVedaSpenderContract(
   return contract;
 }
 
-export const DefiRegistryTokens = {
+const _DefiRegistryTokens = {
   LBTC: Token.LBTC,
   BTCb: Token.BTCb,
   BTC: 'BTC',
 } as const;
 
 export type DefiRegistryToken =
-  (typeof DefiRegistryTokens)[keyof typeof DefiRegistryTokens];
+  (typeof _DefiRegistryTokens)[keyof typeof _DefiRegistryTokens];
 
+/**
+ * DeFi Protocol identifiers - SINGLE SOURCE OF TRUTH
+ *
+ * These are the canonical protocol identifiers used throughout the SDK.
+ * All other protocol references should use these values.
+ */
 export const DefiProtocol = {
-  Veda: 'Veda',
-  Silo: 'Silo',
+  Veda: 'veda',
+  Silo: 'silo',
 } as const;
 
 export type DefiProtocol = (typeof DefiProtocol)[keyof typeof DefiProtocol];
@@ -139,18 +143,20 @@ const SILO_BTCB_APPROVE_APPROVAL: StakeAndBakeStrategyConfig['approval'] = {
 
 /**
  * DeFi Registry: Token approval configurations by vault, token, env, and chain.
+ * 
+ * TODO: Update the format of this registry to match asset catalog and chain catalog
  */
 export const DEFI_REGISTRY: StakeAndBakeRegistry = {
   [DefiProtocol.Veda]: {
     [Token.LBTC]: mapEnvs(ALL_ENVS, () =>
-      mapChains(VEDA_STAKE_AND_BAKE_CHAINS, chain => ({
+      mapChains(VEDA_VAULT_STAKE_AND_BAKE_CHAINS, chain => ({
         amountStrategy: 'identity',
         approval: { ...VEDA_LBTC_PERMIT_APPROVAL },
         spenderContract: getVedaSpenderContract(chain),
       })),
     ),
     BTC: mapEnvs(ALL_ENVS, () =>
-      mapChains(VEDA_STAKE_AND_BAKE_CHAINS, chain => ({
+      mapChains(VEDA_VAULT_STAKE_AND_BAKE_CHAINS, chain => ({
         amountStrategy: 'btcToLbtc',
         approval: { ...VEDA_LBTC_PERMIT_APPROVAL },
         spenderContract: getVedaSpenderContract(chain),
@@ -159,6 +165,8 @@ export const DEFI_REGISTRY: StakeAndBakeRegistry = {
   },
   [DefiProtocol.Silo]: {
     [Token.BTCb]: {
+      // Silo on Avalanche Fuji is only available on testnet (Gastald backend)
+      // Stage environment does not support Avalanche Fuji
       [Env.testnet]: mapChains([ChainId.avalancheFuji], chain => ({
         amountStrategy: 'identity',
         approval: { ...SILO_BTCB_APPROVE_APPROVAL },
@@ -177,3 +185,111 @@ export const DEFI_REGISTRY: StakeAndBakeRegistry = {
  * Includes both Token enum values and virtual tokens like 'BTC'.
  */
 export type StakeAndBakeToken = DefiRegistryToken;
+
+/**
+ * Get supported chains for a protocol/token/env combination.
+ *
+ * @example
+ * ```typescript
+ * // Get chains supporting Veda with BTC token on testnet
+ * const chains = getStakeAndBakeSupportedChains(DefiProtocol.Veda, 'BTC', Env.testnet);
+ * // Returns: [ChainId.binanceSmartChainTestnet, ChainId.holesky]
+ * ```
+ */
+export function getStakeAndBakeSupportedChains(
+  protocol: DefiProtocol,
+  token: StakeAndBakeToken,
+  env: Env,
+): ChainId[] {
+  const protocolRegistry = DEFI_REGISTRY[protocol];
+  if (!protocolRegistry) return [];
+
+  const tokenRegistry =
+    protocolRegistry[token as keyof typeof protocolRegistry];
+  if (!tokenRegistry) return [];
+
+  const envRegistry = tokenRegistry[env];
+  if (!envRegistry) return [];
+
+  return Object.keys(envRegistry).map(Number) as ChainId[];
+}
+
+/**
+ * Get all supported protocols for stake and bake (regardless of environment).
+ */
+export function getSupportedProtocols(assetId: AssetId): DefiProtocol[] {
+  return Object.entries(DEFI_REGISTRY)
+    .filter(([_, tokenMap]) => assetId in tokenMap)
+    .map(([protocol]) => protocol as DefiProtocol);
+}
+
+/**
+ * Get available protocols for a specific environment and token.
+ *
+ * This filters protocols based on what is actually configured in the DEFI_REGISTRY
+ * for the given environment. Use this to determine which protocol options should
+ * be shown in the UI.
+ *
+ * @example
+ * ```typescript
+ * // Get protocols available for LBTC in production
+ * const prodProtocols = getAvailableProtocols(AssetId.LBTC, Env.prod);
+ * // Returns: ['veda'] - Silo is only on Avalanche which has no mainnet prod config
+ *
+ * // Get protocols available for BTCb in testnet
+ * const testnetProtocols = getAvailableProtocols(AssetId.BTCb, Env.testnet);
+ * // Returns: ['silo'] - Silo is available on Avalanche Fuji in testnet
+ * ```
+ */
+export function getAvailableProtocols(
+  assetId: AssetId,
+  env: Env,
+): DefiProtocol[] {
+  // Map asset IDs to registry tokens
+  const tokenMap: Partial<Record<AssetId, StakeAndBakeToken[]>> = {
+    [AssetId.LBTC]: [Token.LBTC, 'BTC'],
+    [AssetId.BTCb]: [Token.BTCb],
+    [AssetId.BTC]: ['BTC'],
+  };
+
+  const tokens = tokenMap[assetId];
+  if (!tokens) return [];
+
+  const availableProtocols: Set<DefiProtocol> = new Set();
+
+  for (const [protocol, tokenStrategyMap] of Object.entries(DEFI_REGISTRY)) {
+    for (const token of tokens) {
+      const tokenRegistry = tokenStrategyMap[token as keyof typeof tokenStrategyMap];
+      if (!tokenRegistry) continue;
+
+      const envRegistry = tokenRegistry[env];
+      if (!envRegistry || Object.keys(envRegistry).length === 0) continue;
+
+      availableProtocols.add(protocol as DefiProtocol);
+    }
+  }
+
+  return Array.from(availableProtocols);
+}
+
+/**
+ * Get available protocols with their metadata for UI display.
+ *
+ * @example
+ * ```typescript
+ * const protocols = getAvailableProtocolsWithMetadata(AssetId.LBTC, Env.prod);
+ * // Returns: [{ value: 'veda', label: 'Lombard DeFi Vault', url: '...' }]
+ * ```
+ */
+export function getAvailableProtocolsWithMetadata(
+  assetId: AssetId,
+  env: Env,
+): Array<{ value: DefiProtocol; label: string; url: string }> {
+  const protocols = getAvailableProtocols(assetId, env);
+  
+  return protocols.map(protocol => ({
+    value: protocol,
+    label: DefiProtocols[protocol]?.name ?? protocol,
+    url: DefiProtocols[protocol]?.url ?? '',
+  }));
+}

package/src/defi/index.ts

@@ -1,5 +1,17 @@
 export {
+  isVedaVaultStakeAndBakeChain,
+  VEDA_VAULT_STAKE_AND_BAKE_CHAINS,
+  type VedaVaultStakeAndBakeChain,
+} from '../vaults/lib/config';
+export {
+  DEFI_REGISTRY,
   DefiProtocol,
+  DefiProtocols,
   type DefiRegistryToken,
+  getAvailableProtocols,
+  getAvailableProtocolsWithMetadata,
+  getStakeAndBakeSupportedChains,
+  getSupportedProtocols,
+  type StakeAndBakeRegistry,
   type StakeAndBakeToken,
 } from './defi-registry';

package/src/index.ts

@@ -1,84 +1,336 @@
-// API functions:
-export * from './api-functions';
+/**
+ * Lombard SDK - Public API
+ *
+ * Main entry point for the Lombard SDK.
+ */
 
-// READ and WRITE functions:
-export * from './contract-functions';
+// SDK Version (injected at build time)
+export { SDK_NAME, SDK_RUNTIME, SDK_VERSION } from './version';
 
-// Vault:
-export * from './vaults';
+// Logging utilities
+export {
+type ConsoleLoggerOptions,   createConsoleLogger,
+  createSilentLogger, type LogLevel
+} from './utils/consoleLogger';
 
-// DeFi:
-export * from './defi';
+// HTTP utilities (for advanced users)
+export { getSdkHeaders } from './utils/http';
+
+// Main SDK exports
+export type {
+  ApiVersion,
+  DepositAddressOptions,
+  DestinationChain,
+  ExchangeRateOptions,
+  UnstakeOptions
+} from './client/ApiNamespace';
+export { ApiNamespace } from './client/ApiNamespace';
+export { createConfig } from './client/createConfig';
+export { createLombardSDK } from './client/createLombardSDK';
+export { LombardSDK } from './client/LombardSDK';
+export { PartnerConfiguration } from './client/PartnerConfiguration';
+
+// Chain Actions (user-facing API)
+export { BtcActions, btcActions } from './chains/btc/BtcActions';
+export { EvmActions, evmActions } from './chains/evm/EvmActions';
+export { SolanaActions, solanaActions } from './chains/solana/SolanaActions';
+export {
+  StarknetActions,
+  starknetActions
+} from './chains/starknet/StarknetActions';
+export { SuiActions, suiActions } from './chains/sui/SuiActions';
+
+// Shared EVM utilities (fee authorization)
+export type { FeeAuthState } from './chains/evm/shared/feeAuth';
+
+// Status constants (single export to avoid duplicates)
+export {
+  BtcActionStatus,
+  EvmOperationStatus,
+  NonEvmUnstakeStatus
+} from './shared/constants/statusConstants';
+
+// Module exports
+export { btcModule, type BtcService } from './modules/btcModule';
+export type {
+  FeeAuthorizationResult,
+  StoredFeeSignature
+} from './modules/evmModule';
+export { evmModule, type EvmService } from './modules/evmModule';
+
+// Context types
+export type {
+  BtcCoreContext,
+  CoreContext,
+  EvmCoreContext,
+  EvmDestination,
+  Logger,
+  ProviderKey,
+  ProviderResolver,
+  SolanaDestination,
+  StarknetDestination,
+  SuiDestination
+} from './shared/context';
+
+// Configuration types
+export type {
+  CreateConfigOptions,
+  CustomAsset,
+  LombardConfig,
+  LombardSDKOptions,
+  PartnerConfig,
+  ProviderGetter,
+  ProviderGetters
+} from './config/types';
+
+// Provider types
+export type {
+  AnyProvider,
+  BtcProvider,
+  EvmProvider,
+  SolanaProvider,
+  StarknetProvider,
+  SuiProvider
+} from './config/providers';
+export {
+  isBtcProvider,
+  isEvmProvider,
+  isSolanaProvider,
+  isStarknetProvider,
+  isSuiProvider
+} from './config/providers';
+
+// Shared types
+export type { ChainMetadata, DeployConfig, RouteParams, StrategyProgress } from './core';
+export {
+  AssetId,
+  assetValueToKey, Chain,
+  // Chain utility functions
+  CHAIN_CATALOG, chainValueToKey, DeployProtocol,
+  Env, evmChainIdToChain,
+  getAllAssetChains,
+  getAssetAddress,
+  // Asset utility functions for dynamic chain discovery
+  getAssetChains,
+  getAssetChainsForEnvs,
+  getChainMetadata,
+  getChainName,
+  isAssetDeployed,
+  isAssetId,
+  isChain,
+  isEvmChain,
+  isMainnet,
+  isTestnet,
+  StepStatus,
+  StrategyStatus
+} from './core';
+
+// Event types
+export type {
+  BridgeEventMap,
+  DeployEventMap,
+  DepositEventMap,
+  RedeemEventMap,
+  StakeEventMap,
+  StrategyEvent,
+  StrategyEventMap,
+  UnstakeEventMap
+} from './shared/events';
+export {
+  BridgeEvent,
+  DeployEvent,
+  DepositEvent,
+  RedeemEvent,
+  StakeEvent,
+  UnstakeEvent
+} from './shared/events';
+
+// Error handling
+export {
+  ContractErrorCode,
+  ErrorCode, isLombardError, LombardError,
+  ProviderErrorCode,
+  RegistryErrorCode,
+  ValidationErrorCode, wrapError
+} from './shared/errors';
+
+// Action interfaces
+export type { LogMeta, MonitorableAction } from './shared/actions/BaseAction';
+
+// BTC types and direct actions
+export type {
+  BtcDepositAndDeployParams,
+  BtcDepositAndDeployPrepareParams,
+  BtcDepositAndDeployProgress,
+  BtcDepositParams,
+  BtcDepositPrepareParams,
+  BtcDepositProgress,
+  BtcStakeAndDeployParams,
+  BtcStakeAndDeployPrepareParams,
+  BtcStakeAndDeployProgress,
+  BtcStakeParams,
+  BtcStakeProgress,
+  IBtcDeposit,
+  IBtcDepositAndDeploy,
+  IBtcStake,
+  IBtcStakeAndDeploy
+} from './chains/btc';
+export {
+  BtcDeposit,
+  BtcDepositAndDeploy,
+  BtcStake,
+  BtcStakeAndDeploy
+} from './chains/btc';
+
+// Note: Sync factory functions (btcStake, btcDeposit, etc.) are intentionally
+// not exported. Use createLombardSDK() instead:
+//
+//   const sdk = await createLombardSDK({ env: Env.prod, ... });
+//   const stake = sdk.chain.btc.stake({ ... });
+//
+// This ensures consistent behavior when remote catalog fetching is added in v4.1.
+
+// EVM types and direct actions
+export type {
+  EvmDeployParams,
+  EvmDeployPrepareParams,
+  EvmDeployProgress,
+  EvmDepositParams,
+  EvmDepositPrepareParams,
+  EvmDepositProgress,
+  EvmRedeemParams,
+  EvmRedeemPrepareParams,
+  EvmRedeemProgress,
+  EvmStakeParams,
+  EvmStakePrepareParams,
+  EvmStakeProgress,
+  EvmUnstakeParams,
+  EvmUnstakePrepareParams,
+  EvmUnstakeProgress,
+  IEvmDeploy,
+  IEvmDeposit,
+  IEvmRedeem,
+  IEvmStake,
+  IEvmUnstake
+} from './chains/evm';
+export {
+  EvmDeployStatus,
+  EvmDepositStatus,
+  EvmRedeemStatus,
+  EvmStakeStatus,
+  EvmUnstakeStatus
+} from './chains/evm';
+
+// Note: Sync factory functions (evmStake, evmUnstake, etc.) are intentionally
+// not exported. Use createLombardSDK() instead:
+//
+//   const sdk = await createLombardSDK({ env: Env.prod, ... });
+//   const unstake = sdk.chain.evm.unstake({ ... });
 
 // Utils:
 export * from './common/api-config';
 export * from './common/blockchain-identifier';
 export * from './common/chains';
-export {
-  SOLANA_DEVNET_CHAIN,
-  SOLANA_MAINNET_CHAIN,
-  SOLANA_TESTNET_CHAIN,
-  SUI_DEVNET_CHAIN,
-  SUI_MAINNET_CHAIN,
-  SUI_TESTNET_CHAIN,
-} from './common/chains';
+export * from './common/fee-requirements';
+
+// Token utilities
 export * from './tokens/lbtc-addresses';
 export * from './tokens/token-addresses';
+export * from './tokens/tokens';
 export * from './utils/satoshi';
 
+// DeFi registry
+export * from './defi';
+
 // Metrics:
 export {
   getAdditionalRewards,
-  type RewardsDistribution,
+  type RewardsDistribution
 } from './metrics/get-additional-rewards';
 export {
   getApy,
   getEstimatedApy,
   type LbtcApy,
-  type LbtcEstimatedApy,
+  type LbtcEstimatedApy
 } from './metrics/get-lbtc-apy';
 export { getLBTCStats } from './metrics/get-lbtc-stats';
 export {
   getPositionsSummary,
-  type PositionsSummary,
+  type PositionsSummary
 } from './metrics/get-positions-summary';
 
-// Tokens:
-export * from './tokens/lbtc-addresses';
-export * from './tokens/tokens';
+// Referrals
+export { ReferralsClient } from './referrals';
+export type {
+  ReferralLookupParams,
+  ReferralLookupResult
+} from './referrals/ReferralsClient';
+
+// API response types
+export type { Deposit } from './api-functions/getDepositsByAddress/getDepositsByAddress';
+export type { Unstake } from './api-functions/getUnstakesByAddress/getUnstakesByAddress';
+export { PayoutTxStatus } from './api-functions/getUnstakesByAddress/getUnstakesByAddress';
 
-// Re-exports:
-export { Env } from '@lombard.finance/sdk-common';
+// Deposit status utilities
+export {
+  calcConfirmations, type ConfirmationProgress, depositRequiresAction, type DepositStatus,
+  type DepositStatusDisplay, getConfirmationProgress,
+  getDepositStatus,
+  getDepositStatusDisplay,
+  isDepositClaimable,
+  isDepositPending,
+  isDepositTerminal, MIN_CLAIM_AMOUNT_BTC,
+  REQUIRED_CONFIRMATIONS, type StatusSeverity
+} from './shared/deposits';
+
+// External types
 export type { Address, EIP1193Provider } from 'viem';
 
+// Contract/API functions
+export * from './api-functions';
+export * from './contract-functions';
+
+// Vault:
+export * from './vaults';
+
 // Signer support (custom transaction signing):
 export {
   createAccountFromSigner,
-  createWalletClientFromSigner,
-  type DispatchCallback,
+  createWalletClientFromSigner, type DispatchCallback,
   type EvmTransactionRequest,
   type SignerAdapter,
-  SignerError,
-  validateTransactionRequest,
-} from './clients/evm-signer-adapter';
+SignerError, validateTransactionRequest} from './clients/evm-signer-adapter';
+
+// RPC URL configuration (for wagmi/viem setup):
+export {
+  getRpcUrlConfig,
+  RPC_URL,
+  rpcUrlConfig,
+  type TRpcUrlConfig
+} from './clients/rpc-url-config';
 export {
-  type CommonSignerWriteParameters,
+type CommonSignerWriteParameters,
   isProviderFlow,
-  isSignerFlow,
-} from './common/parameters';
+  isSignerFlow} from './common/parameters';
 
 // Bridge:
 export {
   bridge,
-  bridgeCCIP,
-  type BridgeCCIPParameters,
-  bridgeOFT,
-  type BridgeParameters,
-  getBridgeInfo,
-  OFT_GAS_LIMIT,
+  bridgeCCIP, type BridgeCCIPParameters, bridgeOFT, type BridgeParameters,
+getBridgeInfo, OFT_GAS_LIMIT,
   OFT_HI_GAS_LIMIT,
-  OFT_HI_GAS_LIMIT_CHAINS,
-} from './bridge';
+  OFT_HI_GAS_LIMIT_CHAINS} from './bridge';
 
 // Debug:
 export * from './debug-api';
+
+// Internal utilities (used by apps/main):
+export { makePublicClient } from './clients/public-client';
+export {
+  getErrorMessage,
+  TokenContractAddressNotFoundError,
+  UnsupportedTokenFlow
+} from './utils/err';
+export { ensureHex, isHex } from './utils/hex';
+export { DAY, HOUR, MINUTE, now, SECOND, toUnix } from './utils/time';
+

package/src/metrics/get-lbtc-stats.stories.tsx

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

package/src/metrics/get-positions-summary.stories.tsx

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