@lombard.finance/sdk 3.7.3 → 4.0.0

package/src/core/assets/utils.ts

@@ -0,0 +1,287 @@
+/**
+ * Asset Query Functions
+ *
+ * Simple utility functions for querying the asset catalog.
+ *
+ * @module core/assets/utils
+ */
+
+import type { Env } from '@lombard.finance/sdk-common';
+
+import { type Chain, isEvmChain } from '../chains';
+import { ASSET_CATALOG } from './catalog';
+import type { AssetCatalog, AssetId, Deployment } from './types';
+
+const DEFAULT_DECIMALS = 8;
+
+/** Find a deployment matching asset, env, and chain */
+function findDeployment(
+  catalog: AssetCatalog,
+  asset: AssetId,
+  env: Env,
+  chain: Chain,
+): Deployment | undefined {
+  const entry = catalog.assets[asset];
+  if (!entry) return undefined;
+  return entry.deployments.find(
+    d => d.env === env && (d.chain === chain || d.chains?.includes(chain)),
+  );
+}
+
+/** Get token address for a specific asset on a chain */
+export function getAssetAddress(
+  asset: AssetId,
+  env: Env,
+  chain: Chain,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): string | undefined {
+  return findDeployment(catalog, asset, env, chain)?.address;
+}
+
+/** Get token decimals for an asset */
+export function getAssetDecimals(
+  asset: AssetId,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): number {
+  return catalog.assets[asset]?.decimals ?? DEFAULT_DECIMALS;
+}
+
+/** Get asset router contract address */
+export function getAssetRouter(
+  asset: AssetId,
+  env: Env,
+  chain: Chain,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): string | undefined {
+  return findDeployment(catalog, asset, env, chain)?.assetRouter;
+}
+
+/** Check if an asset uses an asset router contract */
+export function usesAssetRouter(
+  asset: AssetId,
+  env: Env,
+  chain: Chain,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): boolean {
+  return !!findDeployment(catalog, asset, env, chain)?.assetRouter;
+}
+
+/** Get bridge adapter address */
+export function getBridgeAdapter(
+  asset: AssetId,
+  env: Env,
+  chain: Chain,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): string | undefined {
+  return findDeployment(catalog, asset, env, chain)?.bridgeAdapter;
+}
+
+/** Get public market maker address */
+export function getPublicMarketMaker(
+  asset: AssetId,
+  env: Env,
+  chain: Chain,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): string | undefined {
+  return findDeployment(catalog, asset, env, chain)?.publicMarketMaker;
+}
+
+/** Check if an asset is deployed on a specific chain */
+export function isAssetDeployed(
+  asset: AssetId,
+  env: Env,
+  chain: Chain,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): boolean {
+  return !!findDeployment(catalog, asset, env, chain);
+}
+
+/** Find asset by contract address (reverse lookup) */
+export function getAssetByAddress(
+  address: string,
+  env: Env,
+  chain: Chain,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): AssetId | undefined {
+  const normalized = address.toLowerCase();
+
+  for (const [assetId, entry] of Object.entries(catalog.assets)) {
+    if (!entry) continue;
+    const deployment = entry.deployments.find(
+      d =>
+        d.env === env &&
+        (d.chain === chain || d.chains?.includes(chain)) &&
+        d.address.toLowerCase() === normalized,
+    );
+    if (deployment) return assetId as AssetId;
+  }
+  return undefined;
+}
+
+/** Get all chains where an asset is deployed in a specific environment */
+export function getAssetChains(
+  asset: AssetId,
+  env: Env,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): Chain[] {
+  const entry = catalog.assets[asset];
+  if (!entry) return [];
+
+  const chains: Chain[] = [];
+  for (const d of entry.deployments) {
+    if (d.env !== env) continue;
+    if (d.chain) chains.push(d.chain);
+    if (d.chains) chains.push(...d.chains);
+  }
+  return chains;
+}
+
+/** Get all environments where an asset is deployed on a specific chain */
+export function getAssetEnvironments(
+  asset: AssetId,
+  chain: Chain,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): Env[] {
+  const entry = catalog.assets[asset];
+  if (!entry) return [];
+
+  const envs = new Set<Env>();
+  for (const d of entry.deployments) {
+    if (d.chain === chain || d.chains?.includes(chain)) {
+      envs.add(d.env);
+    }
+  }
+  return Array.from(envs);
+}
+
+/** Get all supported assets */
+export function getSupportedAssets(
+  catalog: AssetCatalog = ASSET_CATALOG,
+): AssetId[] {
+  return Object.keys(catalog.assets) as AssetId[];
+}
+
+/**
+ * Get all chains where an asset is deployed across ALL environments
+ *
+ * Useful for action configs that need to know all possible destination chains.
+ * Deduplicates chains that appear in multiple environments.
+ */
+export function getAllAssetChains(
+  asset: AssetId,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): Chain[] {
+  const entry = catalog.assets[asset];
+  if (!entry) return [];
+
+  const chainSet = new Set<Chain>();
+  for (const d of entry.deployments) {
+    if (d.chain) chainSet.add(d.chain);
+    if (d.chains) d.chains.forEach(c => chainSet.add(c));
+  }
+  return Array.from(chainSet);
+}
+
+/**
+ * Get chains for specific environments
+ *
+ * @param asset - Asset ID
+ * @param envs - Array of environments to include
+ * @returns Deduplicated array of chains
+ */
+export function getAssetChainsForEnvs(
+  asset: AssetId,
+  envs: Env[],
+  catalog: AssetCatalog = ASSET_CATALOG,
+): Chain[] {
+  const entry = catalog.assets[asset];
+  if (!entry) return [];
+
+  const chainSet = new Set<Chain>();
+  for (const d of entry.deployments) {
+    if (!envs.includes(d.env)) continue;
+    if (d.chain) chainSet.add(d.chain);
+    if (d.chains) d.chains.forEach(c => chainSet.add(c));
+  }
+  return Array.from(chainSet);
+}
+
+/** Get asset metadata (decimals, symbol, name) */
+export function getAssetMetadata(
+  asset: AssetId,
+  catalog: AssetCatalog = ASSET_CATALOG,
+): { decimals: number; symbol: string; name?: string } | undefined {
+  const entry = catalog.assets[asset];
+  if (!entry) return undefined;
+  return { decimals: entry.decimals, symbol: entry.symbol, name: entry.name };
+}
+
+/**
+ * Get EVM chains where an asset is deployed for specific environments
+ *
+ * Filters chains by type 'evm' from the catalog.
+ *
+ * @param asset - Asset ID
+ * @param envs - Array of environments to include
+ * @returns Array of EVM chains where asset is deployed
+ */
+export function getEvmAssetChains(
+  asset: AssetId,
+  envs: Env[],
+  catalog: AssetCatalog = ASSET_CATALOG,
+): Chain[] {
+
+  return getAssetChainsForEnvs(asset, envs, catalog).filter(chain =>
+    isEvmChain(chain),
+  );
+}
+
+/**
+ * Get chains where multiple assets are ALL deployed (intersection)
+ *
+ * Useful for finding chains that support both LBTC and BTCb for same-chain unstake.
+ *
+ * @param assets - Array of Asset IDs that must all be present
+ * @param envs - Array of environments to include
+ * @returns Array of chains where ALL assets are deployed
+ */
+export function getChainsWithAllAssets(
+  assets: AssetId[],
+  envs: Env[],
+  catalog: AssetCatalog = ASSET_CATALOG,
+): Chain[] {
+  if (assets.length === 0) return [];
+
+  // Get chains for first asset
+  const firstAssetChains = new Set(getAssetChainsForEnvs(assets[0], envs, catalog));
+
+  // Intersect with chains for remaining assets
+  for (let i = 1; i < assets.length; i++) {
+    const assetChains = new Set(getAssetChainsForEnvs(assets[i], envs, catalog));
+    for (const chain of firstAssetChains) {
+      if (!assetChains.has(chain)) {
+        firstAssetChains.delete(chain);
+      }
+    }
+  }
+
+  return Array.from(firstAssetChains);
+}
+
+/**
+ * Get EVM chains where multiple assets are ALL deployed
+ *
+ * @param assets - Array of Asset IDs that must all be present
+ * @param envs - Array of environments to include
+ * @returns Array of EVM chains where ALL assets are deployed
+ */
+export function getEvmChainsWithAllAssets(
+  assets: AssetId[],
+  envs: Env[],
+  catalog: AssetCatalog = ASSET_CATALOG,
+): Chain[] {
+
+  return getChainsWithAllAssets(assets, envs, catalog).filter(chain =>
+    isEvmChain(chain),
+  );
+}

package/src/core/chains/catalog.ts

@@ -0,0 +1,396 @@
+/**
+ * Chain Catalog
+ *
+ * Complete metadata for all chains.
+ *
+ * @module core/chains/catalog
+ */
+
+import { Chain, ChainMetadata } from './types';
+
+/**
+ * Chain catalog with metadata for all chains.
+ * TypeScript will error if any Chain is missing.
+ */
+export const CHAIN_CATALOG: Record<Chain, ChainMetadata> = {
+  // ─────────────────────────────────────────────────────────────────────────
+  // Bitcoin
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.BITCOIN_MAINNET]: {
+    name: 'Bitcoin',
+    type: 'bitcoin',
+    isTestnet: false,
+    explorerUrl: 'https://mempool.space',
+    nativeCurrency: 'BTC',
+    badgeVariant: 'warning',
+  },
+  [Chain.BITCOIN_SIGNET]: {
+    name: 'Bitcoin Signet',
+    type: 'bitcoin',
+    isTestnet: true,
+    explorerUrl: 'https://mempool.space/signet',
+    nativeCurrency: 'BTC',
+    badgeVariant: 'warning',
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // EVM Mainnets
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.ETHEREUM]: {
+    name: 'Ethereum',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://etherscan.io',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'info',
+  },
+  [Chain.BASE]: {
+    name: 'Base',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://basescan.org',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'info',
+  },
+  [Chain.OPTIMISM]: {
+    name: 'Optimism',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://optimistic.etherscan.io',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'info',
+  },
+  [Chain.POLYGON]: {
+    name: 'Polygon',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://polygonscan.com',
+    nativeCurrency: 'MATIC',
+    badgeVariant: 'info',
+  },
+  [Chain.BSC]: {
+    name: 'BNB Chain',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://bscscan.com',
+    nativeCurrency: 'BNB',
+    badgeVariant: 'info',
+  },
+  [Chain.AVALANCHE]: {
+    name: 'Avalanche',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://snowtrace.io',
+    nativeCurrency: 'AVAX',
+    badgeVariant: 'info',
+  },
+  [Chain.BERACHAIN]: {
+    name: 'Berachain',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://beratrail.io',
+    nativeCurrency: 'BERA',
+    badgeVariant: 'info',
+  },
+  [Chain.BOB]: {
+    name: 'BOB',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://explorer.gobob.xyz',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'info',
+  },
+  [Chain.CORN]: {
+    name: 'Corn',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://cornscan.io',
+    nativeCurrency: 'BTCN',
+    badgeVariant: 'info',
+  },
+  [Chain.ETHERLINK]: {
+    name: 'Etherlink',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://explorer.etherlink.com',
+    nativeCurrency: 'XTZ',
+    badgeVariant: 'info',
+  },
+  [Chain.KATANA]: {
+    name: 'Katana',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://explorer.katanarpc.com',
+    nativeCurrency: 'BTC.b',
+    badgeVariant: 'info',
+  },
+  [Chain.MORPH]: {
+    name: 'Morph',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://explorer.morphl2.io',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'info',
+  },
+  [Chain.SONIC]: {
+    name: 'Sonic',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://sonicscan.org',
+    nativeCurrency: 'S',
+    badgeVariant: 'info',
+  },
+  [Chain.SWELL]: {
+    name: 'Swell',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://explorer.swellnetwork.io',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'info',
+  },
+  [Chain.TAC]: {
+    name: 'TAC',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://explorer.tac.build',
+    nativeCurrency: 'TAC',
+    badgeVariant: 'info',
+  },
+  [Chain.MEGAETH]: {
+    name: 'MegaETH',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://megaeth-testnet-v3.blockscout.com',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'info',
+  },
+  [Chain.MONAD]: {
+    name: 'Monad',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://monadvision.com',
+    nativeCurrency: 'MONAD',
+    badgeVariant: 'info',
+  },
+  [Chain.STABLE]: {
+    name: 'Stable',
+    type: 'evm',
+    isTestnet: false,
+    explorerUrl: 'https://stablescan.xyz',
+    nativeCurrency: 'USD',
+    badgeVariant: 'info',
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // EVM Testnets
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.BASE_SEPOLIA]: {
+    name: 'Base Sepolia',
+    type: 'evm',
+    isTestnet: true,
+    explorerUrl: 'https://sepolia.basescan.org',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'secondary',
+  },
+  [Chain.BSC_TESTNET]: {
+    name: 'BNB Testnet',
+    type: 'evm',
+    isTestnet: true,
+    explorerUrl: 'https://testnet.bscscan.com',
+    nativeCurrency: 'BNB',
+    badgeVariant: 'secondary',
+  },
+  [Chain.AVALANCHE_FUJI]: {
+    name: 'Avalanche Fuji',
+    type: 'evm',
+    isTestnet: true,
+    explorerUrl: 'https://testnet.snowtrace.io',
+    nativeCurrency: 'AVAX',
+    badgeVariant: 'secondary',
+  },
+  [Chain.BERACHAIN_BARTIO]: {
+    name: 'Berachain Bartio',
+    type: 'evm',
+    isTestnet: true,
+    explorerUrl: 'https://bartio.beratrail.io',
+    nativeCurrency: 'BERA',
+    badgeVariant: 'secondary',
+  },
+  [Chain.KATANA_TATARA]: {
+    name: 'Katana Tatara',
+    type: 'evm',
+    isTestnet: true,
+    explorerUrl: 'https://explorer.tatara.katanarpc.com',
+    nativeCurrency: 'BTC.b',
+    badgeVariant: 'secondary',
+  },
+  // Note: SONIC_TESTNET and SONIC_BLAZE_TESTNET are the same chain (eip155:57054)
+  [Chain.SONIC_TESTNET]: {
+    name: 'Sonic Blaze Testnet',
+    type: 'evm',
+    isTestnet: true,
+    explorerUrl: 'https://testnet.sonicscan.org',
+    nativeCurrency: 'S',
+    badgeVariant: 'secondary',
+  },
+  [Chain.SEPOLIA]: {
+    name: 'Sepolia',
+    type: 'evm',
+    isTestnet: true,
+    explorerUrl: 'https://sepolia.etherscan.io',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'secondary',
+  },
+  [Chain.HOLESKY]: {
+    name: 'Holesky',
+    type: 'evm',
+    isTestnet: true,
+    explorerUrl: 'https://holesky.etherscan.io',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'secondary',
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Solana
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.SOLANA_MAINNET]: {
+    name: 'Solana',
+    type: 'solana',
+    isTestnet: false,
+    explorerUrl: 'https://solscan.io',
+    nativeCurrency: 'SOL',
+    badgeVariant: 'success',
+  },
+  [Chain.SOLANA_DEVNET]: {
+    name: 'Solana Devnet',
+    type: 'solana',
+    isTestnet: true,
+    explorerUrl: 'https://solscan.io?cluster=devnet',
+    nativeCurrency: 'SOL',
+    badgeVariant: 'secondary',
+  },
+  [Chain.SOLANA_TESTNET]: {
+    name: 'Solana Testnet',
+    type: 'solana',
+    isTestnet: true,
+    explorerUrl: 'https://solscan.io?cluster=testnet',
+    nativeCurrency: 'SOL',
+    badgeVariant: 'secondary',
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Sui
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.SUI_MAINNET]: {
+    name: 'Sui',
+    type: 'sui',
+    isTestnet: false,
+    explorerUrl: 'https://suiscan.xyz',
+    nativeCurrency: 'SUI',
+    badgeVariant: 'info',
+  },
+  [Chain.SUI_TESTNET]: {
+    name: 'Sui Testnet',
+    type: 'sui',
+    isTestnet: true,
+    explorerUrl: 'https://suiscan.xyz/testnet',
+    nativeCurrency: 'SUI',
+    badgeVariant: 'secondary',
+  },
+  [Chain.SUI_DEVNET]: {
+    name: 'Sui Devnet',
+    type: 'sui',
+    isTestnet: true,
+    explorerUrl: 'https://suiscan.xyz/devnet',
+    nativeCurrency: 'SUI',
+    badgeVariant: 'secondary',
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Starknet
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.STARKNET_MAINNET]: {
+    name: 'Starknet',
+    type: 'starknet',
+    isTestnet: false,
+    explorerUrl: 'https://starkscan.co',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'info',
+  },
+  [Chain.STARKNET_SEPOLIA]: {
+    name: 'Starknet Sepolia',
+    type: 'starknet',
+    isTestnet: true,
+    explorerUrl: 'https://sepolia.starkscan.co',
+    nativeCurrency: 'ETH',
+    badgeVariant: 'secondary',
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Zcash
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.ZCASH_MAINNET]: {
+    name: 'Zcash',
+    type: 'zcash',
+    isTestnet: false,
+    explorerUrl: 'https://zcashblockexplorer.com',
+    nativeCurrency: 'ZEC',
+    badgeVariant: 'warning',
+  },
+  [Chain.ZCASH_TESTNET]: {
+    name: 'Zcash Testnet',
+    type: 'zcash',
+    isTestnet: true,
+    nativeCurrency: 'ZEC',
+    badgeVariant: 'secondary',
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Ripple
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.RIPPLE_MAINNET]: {
+    name: 'XRP Ledger',
+    type: 'ripple',
+    isTestnet: false,
+    explorerUrl: 'https://xrpscan.com',
+    nativeCurrency: 'XRP',
+    badgeVariant: 'secondary',
+  },
+  [Chain.RIPPLE_TESTNET]: {
+    name: 'XRP Testnet',
+    type: 'ripple',
+    isTestnet: true,
+    nativeCurrency: 'XRP',
+    badgeVariant: 'secondary',
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Dogecoin
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.DOGECOIN_MAINNET]: {
+    name: 'Dogecoin',
+    type: 'dogecoin',
+    isTestnet: false,
+    explorerUrl: 'https://dogechain.info',
+    nativeCurrency: 'DOGE',
+    badgeVariant: 'warning',
+  },
+  [Chain.DOGECOIN_TESTNET]: {
+    name: 'Dogecoin Testnet',
+    type: 'dogecoin',
+    isTestnet: true,
+    nativeCurrency: 'DOGE',
+    badgeVariant: 'secondary',
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Other
+  // ─────────────────────────────────────────────────────────────────────────
+  [Chain.HYPERLIQUID]: {
+    name: 'Hyperliquid',
+    type: 'hyperliquid',
+    isTestnet: false,
+    nativeCurrency: 'USDC',
+    badgeVariant: 'secondary',
+  },
+};