@circle-fin/provider-cctp-v2 1.4.0 → 1.4.1

package/index.cjs

@@ -19,7 +19,7 @@
 'use strict';
 
 // Buffer polyfill setup - executes before any other code
-// Ensures globalThis.Buffer is available for @solana/spl-token and other Solana libraries
+// Ensures globalThis.Buffer is available for Solana libraries
 const { Buffer } = require('buffer');
 if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
     globalThis.Buffer = Buffer;
@@ -116,6 +116,122 @@ var Blockchain;
     Blockchain["ZKSync_Era"] = "ZKSync_Era";
     Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
 })(Blockchain || (Blockchain = {}));
+/**
+ * Enum representing the subset of {@link Blockchain} that supports swap operations.
+ *
+ * This enum provides compile-time type safety for swap chain selection,
+ * ensuring only supported chains are available in IDE autocomplete
+ * when building swap parameters.
+ *
+ * @remarks
+ * Unlike the full {@link Blockchain} enum, SwapChain only includes networks
+ * where the swap functionality is actively supported by the library.
+ * Using this enum prevents runtime errors from attempting unsupported
+ * cross-chain swaps.
+ *
+ * Currently supports:
+ * - Ethereum mainnet
+ * - Base mainnet
+ * - Polygon mainnet
+ * - Solana mainnet
+ *
+ * @example
+ * ```typescript
+ * import { SwapChain, swap, createSwapKitContext } from '@circle-fin/swap-kit'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ *
+ * const context = createSwapKitContext()
+ * const adapter = createViemAdapterFromPrivateKey({
+ *   privateKey: process.env.PRIVATE_KEY
+ * })
+ *
+ * // ✅ Autocomplete shows only swap-supported chains
+ * const result = await swap(context, {
+ *   from: {
+ *     adapter,
+ *     chain: SwapChain.Ethereum // Autocomplete: Ethereum, Base, Polygon, Solana
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'USDT',
+ *   amount: '100.0'
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // String literals also work (constrained to SwapChain values)
+ * const result = await swap(context, {
+ *   from: {
+ *     adapter,
+ *     chain: 'Ethereum' // ✅ Only SwapChain strings allowed
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'NATIVE',
+ *   amount: '50.0'
+ * })
+ *
+ * // ❌ TypeScript error - Sui not in SwapChain enum
+ * const invalidResult = await swap(context, {
+ *   from: {
+ *     adapter,
+ *     chain: 'Sui' // Compile-time error!
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'USDT',
+ *   amount: '100.0'
+ * })
+ * ```
+ */
+/**
+ * Enum representing chains that support same-chain swaps through the Swap Kit.
+ *
+ * Unlike the full {@link Blockchain} enum, SwapChain includes only mainnet
+ * networks where adapter contracts are deployed (CCTPv2 support).
+ *
+ * Dynamic validation via {@link isSwapSupportedChain} ensures chains
+ * automatically work when adapter contracts and supported tokens are deployed.
+ *
+ * @example
+ * ```typescript
+ * import { SwapChain } from '@core/chains'
+ * import { swap } from '@circle-fin/swap-kit'
+ *
+ * const result = await swap(context, {
+ *   from: {
+ *     adapter,
+ *     chain: SwapChain.Arbitrum  // Now supported!
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'WETH',
+ *   amount: '100.0'
+ * })
+ * ```
+ *
+ * @see {@link isSwapSupportedChain} for runtime validation
+ * @see {@link getSwapSupportedChains} for all supported chains
+ */
+var SwapChain;
+(function (SwapChain) {
+    // Original 4 chains
+    SwapChain["Ethereum"] = "Ethereum";
+    SwapChain["Base"] = "Base";
+    SwapChain["Polygon"] = "Polygon";
+    SwapChain["Solana"] = "Solana";
+    // Additional supported chains
+    SwapChain["Arbitrum"] = "Arbitrum";
+    SwapChain["Optimism"] = "Optimism";
+    SwapChain["Avalanche"] = "Avalanche";
+    SwapChain["Linea"] = "Linea";
+    SwapChain["Ink"] = "Ink";
+    SwapChain["World_Chain"] = "World_Chain";
+    SwapChain["Unichain"] = "Unichain";
+    SwapChain["Plume"] = "Plume";
+    SwapChain["Sei"] = "Sei";
+    SwapChain["Sonic"] = "Sonic";
+    SwapChain["XDC"] = "XDC";
+    SwapChain["HyperEVM"] = "HyperEVM";
+    SwapChain["Monad"] = "Monad";
+})(SwapChain || (SwapChain = {}));
 // -----------------------------------------------------------------------------
 // Bridge Chain Enum (CCTPv2 Supported Chains)
 // -----------------------------------------------------------------------------
@@ -267,6 +383,7 @@ const Algorand = defineChain({
     rpcEndpoints: ['https://mainnet-api.algonode.cloud'],
     eurcAddress: null,
     usdcAddress: '31566704',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -290,6 +407,7 @@ const AlgorandTestnet = defineChain({
     rpcEndpoints: ['https://testnet-api.algonode.cloud'],
     eurcAddress: null,
     usdcAddress: '10458941',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -313,6 +431,7 @@ const Aptos = defineChain({
     rpcEndpoints: ['https://fullnode.mainnet.aptoslabs.com/v1'],
     eurcAddress: null,
     usdcAddress: '0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b',
+    usdtAddress: '0x357b0b74bc833e95a115ad22604854d6b0fca151cecd94111770e5d6ffc9dc2b',
     cctp: {
         domain: 9,
         contracts: {
@@ -350,6 +469,7 @@ const AptosTestnet = defineChain({
     rpcEndpoints: ['https://fullnode.testnet.aptoslabs.com/v1'],
     eurcAddress: null,
     usdcAddress: '0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832',
+    usdtAddress: null,
     cctp: {
         domain: 9,
         contracts: {
@@ -367,6 +487,121 @@ const AptosTestnet = defineChain({
     },
 });
 
+/**
+ * Complete swap token registry - single source of truth for all swap-supported tokens.
+ *
+ * @remarks
+ * All packages should import from this registry for swap operations.
+ * Adding a new swap token requires updating only this registry.
+ *
+ * The NATIVE token is handled separately as it resolves dynamically based on chain.
+ *
+ * @example
+ * ```typescript
+ * import { SWAP_TOKEN_REGISTRY } from '@core/chains'
+ *
+ * // Get token decimals
+ * const decimals = SWAP_TOKEN_REGISTRY.USDC.decimals  // 6
+ *
+ * // Check if token is stablecoin
+ * const isStable = SWAP_TOKEN_REGISTRY.DAI.category === 'stablecoin'  // true
+ * ```
+ */
+const SWAP_TOKEN_REGISTRY = {
+    // ============================================================================
+    // Stablecoins (6 decimals)
+    // ============================================================================
+    USDC: {
+        symbol: 'USDC',
+        decimals: 6,
+        category: 'stablecoin',
+        description: 'USD Coin',
+    },
+    EURC: {
+        symbol: 'EURC',
+        decimals: 6,
+        category: 'stablecoin',
+        description: 'Euro Coin',
+    },
+    USDT: {
+        symbol: 'USDT',
+        decimals: 6,
+        category: 'stablecoin',
+        description: 'Tether USD',
+    },
+    PYUSD: {
+        symbol: 'PYUSD',
+        decimals: 6,
+        category: 'stablecoin',
+        description: 'PayPal USD',
+    },
+    // ============================================================================
+    // Stablecoins (18 decimals)
+    // ============================================================================
+    DAI: {
+        symbol: 'DAI',
+        decimals: 18,
+        category: 'stablecoin',
+        description: 'MakerDAO stablecoin',
+    },
+    USDE: {
+        symbol: 'USDE',
+        decimals: 18,
+        category: 'stablecoin',
+        description: 'Ethena USD (synthetic dollar)',
+    },
+    // ============================================================================
+    // Wrapped Tokens
+    // ============================================================================
+    WBTC: {
+        symbol: 'WBTC',
+        decimals: 8,
+        category: 'wrapped',
+        description: 'Wrapped Bitcoin',
+    },
+    WETH: {
+        symbol: 'WETH',
+        decimals: 18,
+        category: 'wrapped',
+        description: 'Wrapped Ethereum',
+    },
+    WSOL: {
+        symbol: 'WSOL',
+        decimals: 9,
+        category: 'wrapped',
+        description: 'Wrapped Solana',
+    },
+    WAVAX: {
+        symbol: 'WAVAX',
+        decimals: 18,
+        category: 'wrapped',
+        description: 'Wrapped Avalanche',
+    },
+    WPOL: {
+        symbol: 'WPOL',
+        decimals: 18,
+        category: 'wrapped',
+        description: 'Wrapped Polygon',
+    },
+};
+/**
+ * Special NATIVE token constant for swap operations.
+ *
+ * @remarks
+ * NATIVE is handled separately from SWAP_TOKEN_REGISTRY because it resolves
+ * dynamically based on the chain (ETH on Ethereum, SOL on Solana, etc.).
+ * Its decimals are chain-specific.
+ */
+const NATIVE_TOKEN = 'NATIVE';
+/**
+ * Array of all supported swap token symbols including NATIVE.
+ * Useful for iteration, validation, and filtering.
+ */
+[
+    ...Object.keys(SWAP_TOKEN_REGISTRY),
+    NATIVE_TOKEN,
+];
+
 /**
  * The bridge contract address for EVM testnet networks.
  *
@@ -383,6 +618,13 @@ const BRIDGE_CONTRACT_EVM_TESTNET = '0xC5567a5E3370d4DBfB0540025078e283e36A363d'
  * USDC transfers on live networks.
  */
 const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0';
+/**
+ * The adapter contract address for EVM mainnet networks.
+ *
+ * This contract serves as an adapter for integrating with various protocols
+ * on EVM-compatible chains. Use this address for mainnet adapter integrations.
+ */
+const ADAPTER_CONTRACT_EVM_MAINNET = '0x7FB8c7260b63934d8da38aF902f87ae6e284a845';
 
 /**
  * Arc Testnet chain definition
@@ -412,6 +654,7 @@ const ArcTestnet = defineChain({
     rpcEndpoints: ['https://rpc.testnet.arc.network/'],
     eurcAddress: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
     usdcAddress: '0x3600000000000000000000000000000000000000',
+    usdtAddress: null,
     cctp: {
         domain: 26,
         contracts: {
@@ -454,6 +697,7 @@ const Arbitrum = defineChain({
     rpcEndpoints: ['https://arb1.arbitrum.io/rpc'],
     eurcAddress: null,
     usdcAddress: '0xaf88d065e77c8cc2239327c5edb3a432268e5831',
+    usdtAddress: null,
     cctp: {
         domain: 3,
         contracts: {
@@ -478,6 +722,7 @@ const Arbitrum = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -502,6 +747,7 @@ const ArbitrumSepolia = defineChain({
     rpcEndpoints: ['https://sepolia-rollup.arbitrum.io/rpc'],
     eurcAddress: null,
     usdcAddress: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
+    usdtAddress: null,
     cctp: {
         domain: 3,
         contracts: {
@@ -550,6 +796,7 @@ const Avalanche = defineChain({
     rpcEndpoints: ['https://api.avax.network/ext/bc/C/rpc'],
     eurcAddress: '0xc891eb4cbdeff6e073e859e987815ed1505c2acd',
     usdcAddress: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E',
+    usdtAddress: '0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7',
     cctp: {
         domain: 1,
         contracts: {
@@ -574,6 +821,7 @@ const Avalanche = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -597,6 +845,7 @@ const AvalancheFuji = defineChain({
     explorerUrl: 'https://subnets-test.avax.network/c-chain/tx/{hash}',
     eurcAddress: '0x5e44db7996c682e92a960b65ac713a54ad815c6b',
     usdcAddress: '0x5425890298aed601595a70ab815c96711a31bc65',
+    usdtAddress: null,
     cctp: {
         domain: 1,
         contracts: {
@@ -646,6 +895,7 @@ const Base = defineChain({
     rpcEndpoints: ['https://mainnet.base.org', 'https://base.publicnode.com'],
     eurcAddress: '0x60a3e35cc302bfa44cb288bc5a4f316fdb1adb42',
     usdcAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    usdtAddress: null,
     cctp: {
         domain: 6,
         contracts: {
@@ -670,6 +920,7 @@ const Base = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -694,6 +945,7 @@ const BaseSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.base.org'],
     eurcAddress: '0x808456652fdb597867f38412077A9182bf77359F',
     usdcAddress: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+    usdtAddress: null,
     cctp: {
         domain: 6,
         contracts: {
@@ -742,6 +994,7 @@ const Celo = defineChain({
     rpcEndpoints: ['https://forno.celo.org'],
     eurcAddress: null,
     usdcAddress: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
+    usdtAddress: '0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e',
     cctp: null,
 });
 
@@ -766,6 +1019,7 @@ const CeloAlfajoresTestnet = defineChain({
     rpcEndpoints: ['https://alfajores-forno.celo-testnet.org'],
     eurcAddress: null,
     usdcAddress: '0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -790,6 +1044,7 @@ const Codex = defineChain({
     rpcEndpoints: ['https://rpc.codex.xyz'],
     eurcAddress: null,
     usdcAddress: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
+    usdtAddress: null,
     cctp: {
         domain: 12,
         contracts: {
@@ -832,6 +1087,7 @@ const CodexTestnet = defineChain({
     rpcEndpoints: ['https://rpc.codex-stg.xyz'],
     eurcAddress: null,
     usdcAddress: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
+    usdtAddress: null,
     cctp: {
         domain: 12,
         contracts: {
@@ -874,6 +1130,7 @@ const Ethereum = defineChain({
     rpcEndpoints: ['https://eth.merkle.io', 'https://ethereum.publicnode.com'],
     eurcAddress: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
     usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+    usdtAddress: '0xdac17f958d2ee523a2206206994597c13d831ec7',
     cctp: {
         domain: 0,
         contracts: {
@@ -898,6 +1155,7 @@ const Ethereum = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -922,6 +1180,7 @@ const EthereumSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.drpc.org'],
     eurcAddress: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4',
     usdcAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+    usdtAddress: null,
     cctp: {
         domain: 0,
         contracts: {
@@ -969,6 +1228,7 @@ const Hedera = defineChain({
     rpcEndpoints: ['https://mainnet.hashio.io/api'],
     eurcAddress: null,
     usdcAddress: '0.0.456858',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -992,6 +1252,7 @@ const HederaTestnet = defineChain({
     rpcEndpoints: ['https://testnet.hashio.io/api'],
     eurcAddress: null,
     usdcAddress: '0.0.429274',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -1018,6 +1279,7 @@ const HyperEVM = defineChain({
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
+    usdtAddress: null,
     cctp: {
         domain: 19,
         contracts: {
@@ -1036,6 +1298,7 @@ const HyperEVM = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1061,6 +1324,7 @@ const HyperEVMTestnet = defineChain({
     rpcEndpoints: ['https://rpc.hyperliquid-testnet.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
+    usdtAddress: null,
     cctp: {
         domain: 19,
         contracts: {
@@ -1108,6 +1372,7 @@ const Ink = defineChain({
     ],
     eurcAddress: null,
     usdcAddress: '0x2D270e6886d130D724215A266106e6832161EAEd',
+    usdtAddress: null,
     cctp: {
         domain: 21,
         contracts: {
@@ -1126,6 +1391,7 @@ const Ink = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1154,6 +1420,7 @@ const InkTestnet = defineChain({
     ],
     eurcAddress: null,
     usdcAddress: '0xFabab97dCE620294D2B0b0e46C68964e326300Ac',
+    usdtAddress: null,
     cctp: {
         domain: 21,
         contracts: {
@@ -1196,6 +1463,7 @@ const Linea = defineChain({
     rpcEndpoints: ['https://rpc.linea.build'],
     eurcAddress: null,
     usdcAddress: '0x176211869ca2b568f2a7d4ee941e073a821ee1ff',
+    usdtAddress: null,
     cctp: {
         domain: 11,
         contracts: {
@@ -1214,6 +1482,7 @@ const Linea = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1238,6 +1507,7 @@ const LineaSepolia = defineChain({
     rpcEndpoints: ['https://rpc.sepolia.linea.build'],
     eurcAddress: null,
     usdcAddress: '0xfece4462d57bd51a6a552365a011b95f0e16d9b7',
+    usdtAddress: null,
     cctp: {
         domain: 11,
         contracts: {
@@ -1282,6 +1552,7 @@ const Monad = defineChain({
     rpcEndpoints: ['https://rpc.monad.xyz'],
     eurcAddress: null,
     usdcAddress: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+    usdtAddress: null,
     cctp: {
         domain: 15,
         contracts: {
@@ -1300,6 +1571,7 @@ const Monad = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1326,6 +1598,7 @@ const MonadTestnet = defineChain({
     rpcEndpoints: ['https://testnet-rpc.monad.xyz'],
     eurcAddress: null,
     usdcAddress: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
+    usdtAddress: null,
     cctp: {
         domain: 15,
         contracts: {
@@ -1367,6 +1640,7 @@ const NEAR = defineChain({
     rpcEndpoints: ['https://eth-rpc.mainnet.near.org'],
     eurcAddress: null,
     usdcAddress: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
+    usdtAddress: 'usdt.tether-token.near',
     cctp: null,
 });
 
@@ -1390,6 +1664,7 @@ const NEARTestnet = defineChain({
     rpcEndpoints: ['https://eth-rpc.testnet.near.org'],
     eurcAddress: null,
     usdcAddress: '3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -1413,6 +1688,7 @@ const Noble = defineChain({
     rpcEndpoints: ['https://noble-rpc.polkachu.com'],
     eurcAddress: null,
     usdcAddress: 'uusdc',
+    usdtAddress: null,
     cctp: {
         domain: 4,
         contracts: {
@@ -1449,6 +1725,7 @@ const NobleTestnet = defineChain({
     rpcEndpoints: ['https://noble-testnet-rpc.polkachu.com'],
     eurcAddress: null,
     usdcAddress: 'uusdc',
+    usdtAddress: null,
     cctp: {
         domain: 4,
         contracts: {
@@ -1486,6 +1763,7 @@ const Optimism = defineChain({
     rpcEndpoints: ['https://mainnet.optimism.io'],
     eurcAddress: null,
     usdcAddress: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
+    usdtAddress: null,
     cctp: {
         domain: 2,
         contracts: {
@@ -1510,6 +1788,7 @@ const Optimism = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1534,6 +1813,7 @@ const OptimismSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.optimism.io'],
     eurcAddress: null,
     usdcAddress: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
+    usdtAddress: null,
     cctp: {
         domain: 2,
         contracts: {
@@ -1584,6 +1864,7 @@ const Plume = defineChain({
     rpcEndpoints: ['https://rpc.plume.org'],
     eurcAddress: null,
     usdcAddress: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
+    usdtAddress: null,
     cctp: {
         domain: 22,
         contracts: {
@@ -1602,6 +1883,7 @@ const Plume = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1627,6 +1909,7 @@ const PlumeTestnet = defineChain({
     rpcEndpoints: ['https://testnet-rpc.plume.org'],
     eurcAddress: null,
     usdcAddress: '0xcB5f30e335672893c7eb944B374c196392C19D18',
+    usdtAddress: null,
     cctp: {
         domain: 22,
         contracts: {
@@ -1668,6 +1951,7 @@ const PolkadotAssetHub = defineChain({
     rpcEndpoints: ['https://asset-hub-polkadot-rpc.n.dwellir.com'],
     eurcAddress: null,
     usdcAddress: '1337',
+    usdtAddress: '1984',
     cctp: null,
 });
 
@@ -1691,6 +1975,7 @@ const PolkadotWestmint = defineChain({
     rpcEndpoints: ['https://westmint-rpc.polkadot.io'],
     eurcAddress: null,
     usdcAddress: 'Asset ID 31337',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -1712,9 +1997,10 @@ const Polygon = defineChain({
     chainId: 137,
     isTestnet: false,
     explorerUrl: 'https://polygonscan.com/tx/{hash}',
-    rpcEndpoints: ['https://polygon-rpc.com', 'https://polygon.publicnode.com'],
+    rpcEndpoints: ['https://polygon.publicnode.com', 'https://polygon.drpc.org'],
     eurcAddress: null,
     usdcAddress: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
+    usdtAddress: null,
     cctp: {
         domain: 7,
         contracts: {
@@ -1739,6 +2025,7 @@ const Polygon = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1763,6 +2050,7 @@ const PolygonAmoy = defineChain({
     rpcEndpoints: ['https://rpc-amoy.polygon.technology'],
     eurcAddress: null,
     usdcAddress: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
+    usdtAddress: null,
     cctp: {
         domain: 7,
         contracts: {
@@ -1813,6 +2101,7 @@ const Sei = defineChain({
     rpcEndpoints: ['https://evm-rpc.sei-apis.com'],
     eurcAddress: null,
     usdcAddress: '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392',
+    usdtAddress: null,
     cctp: {
         domain: 16,
         contracts: {
@@ -1831,6 +2120,7 @@ const Sei = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1856,6 +2146,7 @@ const SeiTestnet = defineChain({
     rpcEndpoints: ['https://evm-rpc-testnet.sei-apis.com'],
     eurcAddress: null,
     usdcAddress: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED',
+    usdtAddress: null,
     cctp: {
         domain: 16,
         contracts: {
@@ -1898,6 +2189,7 @@ const Sonic = defineChain({
     rpcEndpoints: ['https://rpc.soniclabs.com'],
     eurcAddress: null,
     usdcAddress: '0x29219dd400f2Bf60E5a23d13Be72B486D4038894',
+    usdtAddress: null,
     cctp: {
         domain: 13,
         contracts: {
@@ -1916,6 +2208,7 @@ const Sonic = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1940,6 +2233,7 @@ const SonicTestnet = defineChain({
     rpcEndpoints: ['https://rpc.testnet.soniclabs.com'],
     eurcAddress: null,
     usdcAddress: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
+    usdtAddress: null,
     cctp: {
         domain: 13,
         contracts: {
@@ -1981,6 +2275,7 @@ const Solana = defineChain({
     rpcEndpoints: ['https://api.mainnet-beta.solana.com'],
     eurcAddress: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
     usdcAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    usdtAddress: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
     cctp: {
         domain: 5,
         contracts: {
@@ -2027,6 +2322,7 @@ const SolanaDevnet = defineChain({
     explorerUrl: 'https://solscan.io/tx/{hash}?cluster=devnet',
     eurcAddress: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
     usdcAddress: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
+    usdtAddress: null,
     cctp: {
         domain: 5,
         contracts: {
@@ -2075,6 +2371,7 @@ const Stellar = defineChain({
     rpcEndpoints: ['https://horizon.stellar.org'],
     eurcAddress: 'EURC-GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2',
     usdcAddress: 'USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -2098,6 +2395,7 @@ const StellarTestnet = defineChain({
     rpcEndpoints: ['https://horizon-testnet.stellar.org'],
     eurcAddress: 'EURC-GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO7VTC3NM2ZTVO',
     usdcAddress: 'USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -2121,6 +2419,7 @@ const Sui = defineChain({
     rpcEndpoints: ['https://fullnode.mainnet.sui.io'],
     eurcAddress: null,
     usdcAddress: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+    usdtAddress: null,
     cctp: {
         domain: 8,
         contracts: {
@@ -2158,6 +2457,7 @@ const SuiTestnet = defineChain({
     rpcEndpoints: ['https://fullnode.testnet.sui.io'],
     eurcAddress: null,
     usdcAddress: '0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC',
+    usdtAddress: null,
     cctp: {
         domain: 8,
         contracts: {
@@ -2196,6 +2496,7 @@ const Unichain = defineChain({
     rpcEndpoints: ['https://mainnet.unichain.org'],
     eurcAddress: null,
     usdcAddress: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
+    usdtAddress: null,
     cctp: {
         domain: 10,
         contracts: {
@@ -2220,6 +2521,7 @@ const Unichain = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2244,6 +2546,7 @@ const UnichainSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.unichain.org'],
     eurcAddress: null,
     usdcAddress: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
+    usdtAddress: null,
     cctp: {
         domain: 10,
         contracts: {
@@ -2292,6 +2595,7 @@ const WorldChain = defineChain({
     rpcEndpoints: ['https://worldchain-mainnet.g.alchemy.com/public'],
     eurcAddress: null,
     usdcAddress: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
+    usdtAddress: null,
     cctp: {
         domain: 14,
         contracts: {
@@ -2310,6 +2614,7 @@ const WorldChain = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2337,6 +2642,7 @@ const WorldChainSepolia = defineChain({
     ],
     eurcAddress: null,
     usdcAddress: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
+    usdtAddress: null,
     cctp: {
         domain: 14,
         contracts: {
@@ -2381,6 +2687,7 @@ const XDC = defineChain({
     rpcEndpoints: ['https://erpc.xdcrpc.com', 'https://erpc.xinfin.network'],
     eurcAddress: null,
     usdcAddress: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+    usdtAddress: null,
     cctp: {
         domain: 18,
         contracts: {
@@ -2399,6 +2706,7 @@ const XDC = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2423,6 +2731,7 @@ const XDCApothem = defineChain({
     rpcEndpoints: ['https://erpc.apothem.network'],
     eurcAddress: null,
     usdcAddress: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+    usdtAddress: null,
     cctp: {
         domain: 18,
         contracts: {
@@ -2465,6 +2774,7 @@ const ZKSyncEra = defineChain({
     rpcEndpoints: ['https://mainnet.era.zksync.io'],
     eurcAddress: null,
     usdcAddress: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -2489,6 +2799,7 @@ const ZKSyncEraSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.era.zksync.dev'],
     eurcAddress: null,
     usdcAddress: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -2656,10 +2967,12 @@ const baseChainDefinitionSchema = zod.z.object({
     rpcEndpoints: zod.z.array(zod.z.string()),
     eurcAddress: zod.z.string().nullable(),
     usdcAddress: zod.z.string().nullable(),
+    usdtAddress: zod.z.string().nullable(),
     cctp: zod.z.any().nullable(), // We'll accept any CCTP config structure
     kitContracts: zod.z
         .object({
         bridge: zod.z.string().optional(),
+        adapter: zod.z.string().optional(),
     })
         .optional(),
 });
@@ -2774,6 +3087,29 @@ zod.z.union([
     zod.z.nativeEnum(Blockchain),
     chainDefinitionSchema$2,
 ]);
+/**
+ * Zod schema for validating swap-specific chain identifiers.
+ *
+ * Validates chains based on:
+ * - CCTPv2 support (adapter contract deployed)
+ * - Mainnet only (no testnets)
+ * - At least one supported token available
+ *
+ */
+zod.z.union([
+    // String blockchain identifier (accepts SwapChain enum values)
+    zod.z.string().refine((val) => val in SwapChain, (val) => ({
+        message: `"${val}" is not a supported swap chain. ` +
+            `Supported chains: ${Object.values(SwapChain).join(', ')}`,
+    })),
+    // SwapChain enum
+    zod.z.nativeEnum(SwapChain),
+    // ChainDefinition object (checks if chain.chain is in SwapChain)
+    chainDefinitionSchema$2.refine((chain) => chain.chain in SwapChain, (chain) => ({
+        message: `"${chain.chain}" is not a supported swap chain. ` +
+            `Supported chains: ${Object.values(SwapChain).join(', ')}`,
+    })),
+]);
 /**
  * Zod schema for validating bridge chain identifiers.
  *
@@ -2813,6 +3149,38 @@ zod.z.union([
     })),
 ]);
 
+/**
+ * @packageDocumentation
+ * @module SwapTokenSchemas
+ *
+ * Zod validation schemas for supported swap tokens.
+ */
+// Internal enum used after input normalization.
+const swapTokenEnumSchema = zod.z.enum([
+    ...Object.keys(SWAP_TOKEN_REGISTRY),
+    NATIVE_TOKEN,
+]);
+/**
+ * Zod schema for validating supported swap token symbols.
+ *
+ * Accepts any token symbol from the SWAP_TOKEN_REGISTRY plus NATIVE.
+ * Input matching is case-insensitive and normalized to uppercase.
+ *
+ * @example
+ * ```typescript
+ * import { supportedSwapTokenSchema } from '@core/chains'
+ *
+ * const result = supportedSwapTokenSchema.safeParse('USDC')
+ * if (result.success) {
+ *   console.log('Valid swap token:', result.data)
+ * }
+ * ```
+ */
+zod.z
+    .string()
+    .transform((value) => value.toUpperCase())
+    .pipe(swapTokenEnumSchema);
+
 /**
  * Retrieve a chain definition by its blockchain enum value.
  *
@@ -2867,6 +3235,11 @@ const getChainByEnum = (blockchain) => {
  * ```
  */
 function resolveChainIdentifier(chainIdentifier) {
+    // Handle null explicitly (typeof null === 'object' in JavaScript)
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (chainIdentifier === null) {
+        throw new Error(`Invalid chain identifier type: null. Expected ChainDefinition object, Blockchain enum, or string literal.`);
+    }
     // If it's already a ChainDefinition object, return it unchanged
     if (typeof chainIdentifier === 'object') {
         return chainIdentifier;
@@ -3158,11 +3531,11 @@ const formatComponent = (nameWithVersion) => {
 const createRequestContext = () => {
     const context = {};
     if (typeof globalThis !== 'undefined') {
-        if (globalThis.__STABLECOIN_KITS_EXTERNAL_PREFIX__ !== undefined) {
-            context.externalPrefix = globalThis.__STABLECOIN_KITS_EXTERNAL_PREFIX__;
+        if (globalThis.__APP_KITS_EXTERNAL_PREFIX__ !== undefined) {
+            context.externalPrefix = globalThis.__APP_KITS_EXTERNAL_PREFIX__;
         }
-        if (globalThis.__STABLECOIN_KITS_CURRENT_KIT__ !== undefined) {
-            context.kit = globalThis.__STABLECOIN_KITS_CURRENT_KIT__;
+        if (globalThis.__APP_KITS_CURRENT_KIT__ !== undefined) {
+            context.kit = globalThis.__APP_KITS_CURRENT_KIT__;
         }
     }
     return context;
@@ -3268,6 +3641,10 @@ const ERROR_TYPES = {
     RPC: 'RPC',
     /** Internet connectivity, DNS resolution, connection issues */
     NETWORK: 'NETWORK',
+    /** API throttling, request frequency limits errors */
+    RATE_LIMIT: 'RATE_LIMIT',
+    /** Service errors */
+    SERVICE: 'SERVICE',
     /** Catch-all for unrecognized errors (code 0) */
     UNKNOWN: 'UNKNOWN',
 };
@@ -3291,6 +3668,8 @@ const ERROR_CODE_RANGES = [
     { min: 3000, max: 3999, type: 'NETWORK' },
     { min: 4000, max: 4999, type: 'RPC' },
     { min: 5000, max: 5999, type: 'ONCHAIN' },
+    { min: 7000, max: 7999, type: 'RATE_LIMIT' },
+    { min: 8000, max: 8999, type: 'SERVICE' },
     { min: 9000, max: 9999, type: 'BALANCE' },
 ];
 /** Special code for UNKNOWN errors */
@@ -3338,6 +3717,8 @@ const errorDetailsSchema = zod.z.object({
      * - 3000-3999: NETWORK errors - Connectivity issues
      * - 4000-4999: RPC errors - Provider issues, gas estimation
      * - 5000-5999: ONCHAIN errors - Transaction/simulation failures
+     * - 7000-7999: RATE_LIMIT errors - API throttling
+     * - 8000-8999: SERVICE errors - Internal service errors
      * - 9000-9999: BALANCE errors - Insufficient funds
      */
     code: zod.z
@@ -3446,11 +3827,11 @@ const AMOUNT_FORMAT_ERROR_MESSAGE = 'Amount must be a numeric string with dot (.
 const MAX_FEE_FORMAT_ERROR_MESSAGE = 'maxFee must be a numeric string with dot (.) as decimal separator (e.g., "1", "0.5", ".5", "1.5"), with no thousand separators or comma decimals';
 
 /**
- * Structured error class for Stablecoin Kit operations.
+ * Structured error class for App Kit operations.
  *
  * This class extends the native Error class while implementing the ErrorDetails
  * interface, providing a consistent error format for programmatic handling
- * across the Stablecoin Kits ecosystem. All properties are immutable to ensure
+ * across the App Kits ecosystem. All properties are immutable to ensure
  * error objects cannot be modified after creation.
  *
  * @example
@@ -3460,6 +3841,7 @@ const MAX_FEE_FORMAT_ERROR_MESSAGE = 'maxFee must be a numeric string with dot (
  * const error = new KitError({
  *   code: 1001,
  *   name: 'INPUT_NETWORK_MISMATCH',
+ *   type: 'INPUT',
  *   recoverability: 'FATAL',
  *   message: 'Cannot bridge between mainnet and testnet'
  * })
@@ -3477,7 +3859,8 @@ const MAX_FEE_FORMAT_ERROR_MESSAGE = 'maxFee must be a numeric string with dot (
  * // Error with cause information
  * const error = new KitError({
  *   code: 1002,
- *   name: 'INVALID_AMOUNT',
+ *   name: 'INPUT_INVALID_AMOUNT',
+ *   type: 'INPUT',
  *   recoverability: 'FATAL',
  *   message: 'Amount must be greater than zero',
  *   cause: {
@@ -3561,6 +3944,8 @@ class KitError extends Error {
  * - 3000-3999: NETWORK errors - Internet connectivity, DNS, connection issues
  * - 4000-4999: RPC errors - Blockchain provider issues, gas estimation, nonce errors
  * - 5000-5999: ONCHAIN errors - Transaction/simulation failures, gas exhaustion, reverts
+ * - 7000-7999: RATE_LIMIT errors - API throttling, request frequency limits
+ * - 8000-8999: SERVICE errors - Internal service errors, server failures
  * - 9000-9999: BALANCE errors - Insufficient funds, token balance, allowance
  */
 /**
@@ -3621,10 +4006,22 @@ const InputError = {
         name: 'INPUT_INVALID_CHAIN',
         type: 'INPUT',
     },
-    /** Invalid or unknown token (symbol not found, missing decimals, etc.) */
-    INVALID_TOKEN: {
+    /** Unsupported token for chain */
+    UNSUPPORTED_TOKEN: {
         code: 1006,
-        name: 'INPUT_INVALID_TOKEN',
+        name: 'INPUT_UNSUPPORTED_TOKEN',
+        type: 'INPUT',
+    },
+    /** Insufficient swap amount for the token pair */
+    INSUFFICIENT_SWAP_AMOUNT: {
+        code: 1007,
+        name: 'INPUT_INSUFFICIENT_SWAP_AMOUNT',
+        type: 'INPUT',
+    },
+    /** Action not supported by this adapter / ecosystem */
+    UNSUPPORTED_ACTION: {
+        code: 1008,
+        name: 'INPUT_UNSUPPORTED_ACTION',
         type: 'INPUT',
     },
     /** General validation failure for complex validation rules */
@@ -3633,6 +4030,12 @@ const InputError = {
         name: 'INPUT_VALIDATION_FAILED',
         type: 'INPUT',
     },
+    /** User cancelled wallet interaction (signature, transaction, connection) */
+    USER_CANCELLED: {
+        code: 1099,
+        name: 'INPUT_USER_CANCELLED',
+        type: 'INPUT',
+    },
 };
 /**
  * Standardized error definitions for BALANCE type errors.
@@ -3720,8 +4123,7 @@ const NetworkError = {
         code: 3004,
         name: 'NETWORK_RELAYER_PENDING',
         type: 'NETWORK',
-    },
-};
+    }};
 
 /**
  * Creates error for network type mismatch between source and destination.
@@ -3808,7 +4210,7 @@ function createInvalidChainError(chain, reason) {
     const errorDetails = {
         ...InputError.INVALID_CHAIN,
         recoverability: 'FATAL',
-        message: `Invalid chain '${chain}': ${reason}`,
+        message: `Invalid chain '${chain}': ${reason}.`,
         cause: {
             trace: { chain, reason },
         },
@@ -4157,6 +4559,9 @@ function getErrorMessage(error) {
     if (typeof error === 'string') {
         return error;
     }
+    if (typeof error === 'object' && error !== null && 'message' in error) {
+        return String(error.message);
+    }
     return 'An unknown error occurred';
 }
 /**
@@ -4213,6 +4618,9 @@ function extractErrorInfo(error) {
     if (typeof err.code === 'number') {
         info.code = err.code;
     }
+    if (isKitError(error)) {
+        info.type = error.type;
+    }
     return info;
 }
 
@@ -4335,7 +4743,17 @@ const makeApiRequest = async (url, method, isValidType, config, body) => {
         const response = await fetch(url, requestInit);
         clearTimeout(timeoutId);
         if (!response.ok) {
-            throw new Error(`HTTP ${String(response.status)} - ${response.statusText}`);
+            let responseBody;
+            try {
+                responseBody = (await response.json());
+            }
+            catch {
+                // Parse response body for diagnostics; continue even if malformed
+                // so callers always receive HTTP status context
+            }
+            const httpError = new Error(`HTTP ${String(response.status)} - ${response.statusText}`);
+            httpError.responseBody = responseBody;
+            throw httpError;
         }
         const parsedJson = (await response.json());
         if (!isValidType(parsedJson)) {
@@ -4907,7 +5325,7 @@ const convertAddress = (address, targetFormat) => {
  *
  * This function normalizes token values from their blockchain representation (where
  * everything is stored as integers in the smallest denomination) to human-readable
- * decimal format. Uses the battle-tested implementation from @ethersproject/units.
+ * decimal format. Uses the battle-tested implementation from \@ethersproject/units.
  *
  * @param value - The value in smallest units (e.g., "1000000" for 1 USDC with 6 decimals)
  * @param decimals - The number of decimal places for the unit conversion
@@ -4936,116 +5354,837 @@ const formatUnits = (value, decimals) => {
 };
 
 /**
- * Build a complete explorer URL from a chain definition and transaction hash.
- *
- * This function takes a chain definition containing an explorer URL template
- * and replaces the `{hash}` placeholder with the provided transaction hash
- * to create a complete, valid explorer URL.
- *
- * @param chainDef - The chain definition containing the explorer URL template.
- * @param txHash - The transaction hash to insert into the URL template.
- * @returns A complete explorer URL with the transaction hash inserted.
- * @throws Error if the chain definition is null/undefined.
- * @throws Error if the transaction hash is null/undefined/empty.
- * @throws Error if the explorer URL template is missing or empty.
- * @throws Error if the explorer URL template doesn't contain the {hash} placeholder.
- * @throws Error if the resulting URL is invalid.
- *
- * @example
- * ```typescript
- * import { buildExplorerUrl } from '@core/utils'
- * import { Ethereum } from '@core/chains'
- *
- * // Build URL for Ethereum transaction
- * const url = buildExplorerUrl(Ethereum, '0x1234567890abcdef...')
- * console.log(url) // 'https://etherscan.io/tx/0x1234567890abcdef...'
- * ```
+ * Create a structured error for token resolution failures.
  *
- * @example
- * ```typescript
- * import { buildExplorerUrl } from '@core/utils'
- * import { Solana } from '@core/chains'
+ * @remarks
+ * Returns a `KitError` with `INPUT_UNSUPPORTED_TOKEN` code (1006).
+ * The error trace contains the selector and chain context for debugging.
  *
- * // Build URL for Solana transaction
- * const url = buildExplorerUrl(Solana, 'abc123def456...')
- * console.log(url) // 'https://solscan.io/tx/abc123def456...'
- * ```
+ * @param message - Human-readable error description.
+ * @param selector - The token selector that failed to resolve.
+ * @param chainId - The chain being resolved for (optional).
+ * @param cause - The underlying error, if any (optional).
+ * @returns A KitError with INPUT type and FATAL recoverability.
  *
  * @example
  * ```typescript
- * import { buildExplorerUrl } from '@core/utils'
- * import { Aptos } from '@core/chains'
- *
- * // Build URL for Aptos transaction with query parameters
- * const url = buildExplorerUrl(Aptos, '0xabc123...')
- * console.log(url) // 'https://explorer.aptoslabs.com/txn/0xabc123...?network=mainnet'
+ * throw createTokenResolutionError(
+ *   'Unknown token symbol: FAKE',
+ *   'FAKE',
+ *   'Ethereum'
+ * )
  * ```
  */
-function buildExplorerUrl(chainDef, txHash) {
-    // Validate input parameters using our standard validation pattern
-    validateOrThrow({ chainDef, txHash }, buildExplorerUrlParamsSchema, 'Invalid buildExplorerUrl parameters');
-    // Parse and transform input parameters (e.g., trim whitespace from txHash)
-    const { chainDef: validChainDef, txHash: validTxHash } = buildExplorerUrlParamsSchema.parse({ chainDef, txHash });
-    // Replace all occurrences of the placeholder with the transaction hash
-    const explorerUrl = validChainDef.explorerUrl.replace(/{hash}/g, validTxHash);
-    // Validate the resulting URL
-    validate(explorerUrl, explorerUrlSchema, 'explorer URL');
-    return explorerUrl;
+function createTokenResolutionError(message, selector, chainId, cause) {
+    const trace = {
+        selector,
+        ...(chainId === undefined ? {} : { chainId }),
+        ...({} ),
+    };
+    return new KitError({
+        ...InputError.UNSUPPORTED_TOKEN,
+        recoverability: 'FATAL',
+        message,
+        cause: { trace },
+    });
 }
 
 /**
- * CCTP forwarding magic bytes prefix.
- *
- * The ASCII string "cctp-forward" (12 bytes) that identifies a forwarding request.
- * This prefix is right-padded to 24 bytes in the final hookData.
- */
-const CCTP_FORWARD_MAGIC_PREFIX = 'cctp-forward';
-/**
- * CCTP forwarding version number.
- *
- * Version 0 is used for basic forwarding requests.
- */
-const CCTP_FORWARD_VERSION = 0;
-/**
- * Length of Circle-reserved payload for basic forwarding (0 bytes).
- *
- * Set to 0 when no additional Circle-reserved data is needed.
- */
-const CCTP_FORWARD_PAYLOAD_LENGTH = 0;
-/**
- * Build the hookData bytes for CCTP forwarding.
- *
- * Constructs a 32-byte hookData payload that signals to Circle's Orbit relayer
- * that the user wants automated attestation fetching and destination mint execution.
+ * USDC token definition with addresses and metadata.
  *
- * The hookData format is:
- * - Bytes 0-23: ASCII "cctp-forward" right-padded to 24 bytes with zeros
- * - Bytes 24-27: uint32 version (big-endian) - currently 0
- * - Bytes 28-31: uint32 length (big-endian) - 0 for basic forwarding
+ * @remarks
+ * This is the built-in USDC definition used by the TokenRegistry.
+ * Includes all known USDC addresses across supported chains.
  *
- * @returns A 0x-prefixed hex string representing the 32-byte hookData
+ * Keys use the `Blockchain` enum for type safety. Both enum values
+ * and string literals are supported:
+ * - `Blockchain.Ethereum` or `'Ethereum'`
  *
  * @example
  * ```typescript
- * import { buildForwardingHookData } from '@core/utils'
- *
- * const hookData = buildForwardingHookData()
- * // Returns: '0x636374702d666f72776172640000000000000000000000000000000000000000'
+ * import { USDC } from '@core/tokens'
+ * import { Blockchain } from '@core/chains'
  *
- * // Use with depositForBurnWithHook action
- * await adapter.action('cctp.v2.depositForBurnWithHook', {
- *   amount: BigInt('1000000'),
- *   mintRecipient: '0x...',
- *   maxFee: BigInt('50000'),
- *   minFinalityThreshold: 1000,
- *   fromChain: ethereum,
- *   toChain: base,
- *   hookData
- * })
+ * console.log(USDC.symbol)   // 'USDC'
+ * console.log(USDC.decimals) // 6
+ * console.log(USDC.locators[Blockchain.Ethereum])
+ * // '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
  * ```
  */
-// Cached result for memoization (computed once on first call)
-let cachedHookDataHex = null;
+const USDC = {
+    symbol: 'USDC',
+    decimals: 6,
+    locators: {
+        // =========================================================================
+        // Mainnets (alphabetically sorted)
+        // =========================================================================
+        [Blockchain.Arbitrum]: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+        [Blockchain.Avalanche]: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E',
+        [Blockchain.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        [Blockchain.Celo]: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
+        [Blockchain.Codex]: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
+        [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+        [Blockchain.Hedera]: '0.0.456858',
+        [Blockchain.HyperEVM]: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
+        [Blockchain.Ink]: '0x2D270e6886d130D724215A266106e6832161EAEd',
+        [Blockchain.Linea]: '0x176211869ca2b568f2a7d4ee941e073a821ee1ff',
+        [Blockchain.Monad]: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+        [Blockchain.NEAR]: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
+        [Blockchain.Noble]: 'uusdc',
+        [Blockchain.Optimism]: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
+        [Blockchain.Plume]: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
+        [Blockchain.Polkadot_Asset_Hub]: '1337',
+        [Blockchain.Polygon]: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
+        [Blockchain.Sei]: '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392',
+        [Blockchain.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        [Blockchain.Sonic]: '0x29219dd400f2Bf60E5a23d13Be72B486D4038894',
+        [Blockchain.Stellar]: 'USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
+        [Blockchain.Sui]: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+        [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
+        [Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
+        [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
+        // =========================================================================
+        // Testnets (alphabetically sorted)
+        // =========================================================================
+        [Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
+        [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
+        [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+        [Blockchain.Codex_Testnet]: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
+        [Blockchain.Ethereum_Sepolia]: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+        [Blockchain.Hedera_Testnet]: '0.0.429274',
+        [Blockchain.HyperEVM_Testnet]: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
+        [Blockchain.Ink_Testnet]: '0xFabab97dCE620294D2B0b0e46C68964e326300Ac',
+        [Blockchain.Linea_Sepolia]: '0xfece4462d57bd51a6a552365a011b95f0e16d9b7',
+        [Blockchain.Monad_Testnet]: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
+        [Blockchain.NEAR_Testnet]: '3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af',
+        [Blockchain.Noble_Testnet]: 'uusdc',
+        [Blockchain.Optimism_Sepolia]: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
+        [Blockchain.Plume_Testnet]: '0xcB5f30e335672893c7eb944B374c196392C19D18',
+        [Blockchain.Polkadot_Westmint]: '31337',
+        [Blockchain.Polygon_Amoy_Testnet]: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
+        [Blockchain.Sei_Testnet]: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED',
+        [Blockchain.Solana_Devnet]: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
+        [Blockchain.Sonic_Testnet]: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
+        [Blockchain.Stellar_Testnet]: 'USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
+        [Blockchain.Sui_Testnet]: '0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC',
+        [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
+        [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
+        [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853',
+    },
+};
+
+/**
+ * USDT (Tether) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in USDT definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const USDT = {
+    symbol: 'USDT',
+    decimals: 6,
+    locators: {
+        [Blockchain.Aptos]: '0x357b0b74bc833e95a115ad22604854d6b0fca151cecd94111770e5d6ffc9dc2b',
+        [Blockchain.Arbitrum]: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',
+        [Blockchain.Avalanche]: '0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7',
+        [Blockchain.Celo]: '0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e',
+        [Blockchain.Ethereum]: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+        [Blockchain.HyperEVM]: '0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb',
+        [Blockchain.Ink]: '0x0200C29006150606B650577BBE7B6248F58470c1',
+        [Blockchain.Linea]: '0xA219439258ca9da29E9Cc4cE5596924745e12B93',
+        [Blockchain.Monad]: '0xe7cd86e13AC4309349F30B3435a9d337750fC82D',
+        [Blockchain.NEAR]: 'usdt.tether-token.near',
+        [Blockchain.Optimism]: '0x94b008aA00579c1307B0EF2c499aD98a8ce58e58',
+        [Blockchain.Polkadot_Asset_Hub]: '1984',
+        [Blockchain.Polygon]: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
+        [Blockchain.Sei]: '0x9151434b16b9763660705744891fA906F660EcC5',
+        [Blockchain.Solana]: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
+        [Blockchain.Unichain]: '0x9151434b16b9763660705744891fA906F660EcC5',
+    },
+};
+
+/**
+ * EURC (Euro Coin) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in EURC definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const EURC = {
+    symbol: 'EURC',
+    decimals: 6,
+    locators: {
+        [Blockchain.Avalanche]: '0xc891EB4cbdEFf6e073e859e987815Ed1505c2ACD',
+        [Blockchain.Base]: '0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42',
+        [Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
+        [Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
+        [Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
+    },
+};
+
+/**
+ * DAI (Maker DAO) stablecoin token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in DAI definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const DAI = {
+    symbol: 'DAI',
+    decimals: 18,
+    chainDecimals: {
+        [Blockchain.Solana]: 8,
+    },
+    locators: {
+        [Blockchain.Arbitrum]: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
+        [Blockchain.Avalanche]: '0xd586E7F844cEa2F87f50152665BCbc2C279D8d70',
+        [Blockchain.Base]: '0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb',
+        [Blockchain.Ethereum]: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
+        [Blockchain.Linea]: '0x4AF15ec2A0BD43Db75dd04E62FAA3B8EF36b00d5',
+        [Blockchain.Optimism]: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
+        [Blockchain.Polygon]: '0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063',
+        [Blockchain.Solana]: 'EjmyN6qEC1Tf1JxiG1ae7UTJhUxSwk1TCWNWqxWV4J6o',
+    },
+};
+
+/**
+ * USDe (Ethena) synthetic dollar token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in USDE definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const USDE = {
+    symbol: 'USDe',
+    decimals: 18,
+    chainDecimals: {
+        [Blockchain.Solana]: 9,
+    },
+    locators: {
+        [Blockchain.Arbitrum]: '0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34',
+        [Blockchain.Base]: '0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34',
+        [Blockchain.Ethereum]: '0x4c9EDD5852cd905f086C759E8383e09bff1E68B3',
+        [Blockchain.Linea]: '0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34',
+        [Blockchain.Optimism]: '0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34',
+        [Blockchain.Solana]: 'DEkqHyPN7GMRJ5cArtQFAWefqbZb33Hyf6s5iCwjEonT',
+    },
+};
+
+/**
+ * PYUSD (PayPal USD) stablecoin token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in PYUSD definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const PYUSD = {
+    symbol: 'PYUSD',
+    decimals: 6,
+    locators: {
+        [Blockchain.Arbitrum]: '0x46850aD61C2B7d64d08c9C754F45254596696984',
+        [Blockchain.Ethereum]: '0x6c3ea9036406852006290770BEdFcAbA0e23A0e8',
+        [Blockchain.Solana]: '2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo',
+    },
+};
+
+/**
+ * WETH (Wrapped Ether) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WETH definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WETH is available.
+ */
+const WETH = {
+    symbol: 'WETH',
+    decimals: 18,
+    chainDecimals: {
+        [Blockchain.Solana]: 9,
+    },
+    locators: {
+        [Blockchain.Arbitrum]: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',
+        [Blockchain.Avalanche]: '0x49D5c2BdFfac6CE2BFdB6640F4F80f226bc10bAB',
+        [Blockchain.Base]: '0x4200000000000000000000000000000000000006',
+        [Blockchain.Ethereum]: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+        [Blockchain.Optimism]: '0x4200000000000000000000000000000000000006',
+        [Blockchain.Polygon]: '0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619',
+        [Blockchain.Solana]: '7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs',
+    },
+};
+
+/**
+ * WBTC (Wrapped Bitcoin) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WBTC definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WBTC is available.
+ */
+const WBTC = {
+    symbol: 'WBTC',
+    decimals: 8,
+    locators: {
+        [Blockchain.Ethereum]: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599',
+        [Blockchain.Arbitrum]: '0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f',
+        [Blockchain.Avalanche]: '0x50b7545627a5162F82A992c33b87aDc75187B218',
+    },
+};
+
+/**
+ * WSOL (Wrapped SOL) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WSOL definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WSOL is available.
+ */
+const WSOL = {
+    symbol: 'WSOL',
+    decimals: 9,
+    locators: {
+        [Blockchain.Solana]: 'So11111111111111111111111111111111111111112',
+    },
+};
+
+/**
+ * WAVAX (Wrapped AVAX) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WAVAX definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WAVAX is available.
+ */
+const WAVAX = {
+    symbol: 'WAVAX',
+    decimals: 18,
+    locators: {
+        [Blockchain.Avalanche]: '0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7',
+    },
+};
+
+/**
+ * WPOL (Wrapped POL) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WPOL definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WPOL is available.
+ */
+const WPOL = {
+    symbol: 'WPOL',
+    decimals: 18,
+    locators: {
+        [Blockchain.Polygon]: '0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270',
+    },
+};
+
+/**
+ * ETH (native Ether alias) token definition with metadata.
+ *
+ * @remarks
+ * Built-in ETH definition for the TokenRegistry. Used as a symbol alias
+ * for native ETH (e.g. in swap flows). Chain locators are TBD and will
+ * be added when addresses are available. Use raw selector with
+ * locator + decimals where native gas token is represented as a contract.
+ */
+const ETH = {
+    symbol: 'ETH',
+    decimals: 18,
+    locators: {},
+};
+
+/**
+ * POL (Polygon native token) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in POL definition for the TokenRegistry. Includes chain locators
+ * where POL is available as a bridged/wrapped asset.
+ */
+const POL = {
+    symbol: 'POL',
+    decimals: 18,
+    locators: {
+        [Blockchain.Ethereum]: '0x455e53CBB86018Ac2B8092FdCd39d8444aFFC3F6',
+    },
+};
+
+/**
+ * PLUME (Plume network token) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in PLUME definition for the TokenRegistry. Includes chain locators
+ * where PLUME is available.
+ */
+const PLUME = {
+    symbol: 'PLUME',
+    decimals: 18,
+    locators: {
+        [Blockchain.Ethereum]: '0x4C1746A800D224393fE2470C70A35717eD4eA5F1',
+    },
+};
+
+/**
+ * MON token definition with Solana mint metadata.
+ *
+ * @remarks
+ * Built-in MON definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const MON = {
+    symbol: 'MON',
+    decimals: 18,
+    chainDecimals: {
+        [Blockchain.Solana]: 8,
+    },
+    locators: {
+        [Blockchain.Solana]: 'CrAr4RRJMBVwRsZtT62pEhfA9H5utymC2mVx8e7FreP2',
+    },
+};
+
+// Re-export for consumers
+/**
+ * All default token definitions.
+ *
+ * @remarks
+ * These tokens are automatically included in the TokenRegistry when created
+ * without explicit defaults. Extensions can override these definitions.
+ * Includes USDC, USDT, EURC, DAI, USDE, PYUSD, WETH, WBTC, WSOL, WAVAX,
+ * WPOL, ETH, POL, PLUME, and MON.
+ *
+ * @example
+ * ```typescript
+ * import { createTokenRegistry } from '@core/tokens'
+ *
+ * // Registry uses these by default
+ * const registry = createTokenRegistry()
+ *
+ * // Add custom tokens (built-ins are still included)
+ * const customRegistry = createTokenRegistry({
+ *   tokens: [myCustomToken],
+ * })
+ * ```
+ */
+const DEFAULT_TOKENS = [
+    USDC,
+    USDT,
+    EURC,
+    DAI,
+    USDE,
+    PYUSD,
+    WETH,
+    WBTC,
+    WSOL,
+    WAVAX,
+    WPOL,
+    ETH,
+    POL,
+    PLUME,
+    MON,
+];
+/**
+ * Uppercased token symbols approved for swap fee collection.
+ *
+ * @remarks
+ * Derived from {@link DEFAULT_TOKENS} so all consumers share a single
+ * allowlist source and stay in sync when defaults change.
+ */
+new Set(DEFAULT_TOKENS.map((t) => t.symbol.toUpperCase()));
+
+/**
+ * Resolve the effective decimals for a token on a specific chain.
+ *
+ * Returns the chain-specific override from `chainDecimals` when available,
+ * otherwise falls back to the token's default `decimals`.
+ *
+ * @param token - The token definition to resolve decimals for.
+ * @param chain - Optional chain identifier. When omitted, the default decimals are returned.
+ * @returns The number of decimal places for the token on the given chain.
+ *
+ * @example
+ * ```typescript
+ * import { resolveTokenDecimals } from '\@core/tokens'
+ *
+ * // DAI: 18 decimals on EVM, 8 on Solana
+ * resolveTokenDecimals(DAI)            // 18 (default)
+ * resolveTokenDecimals(DAI, 'Solana')  // 8  (chain override)
+ * resolveTokenDecimals(DAI, 'Ethereum') // 18 (no override, falls back)
+ * ```
+ */
+function resolveTokenDecimals(token, chain) {
+    if (chain === undefined) {
+        return token.decimals;
+    }
+    return token.chainDecimals?.[chain] ?? token.decimals;
+}
+
+/**
+ * Check if a selector is a raw token selector (object form).
+ *
+ * @param selector - The token selector to check.
+ * @returns True if the selector is a raw token selector.
+ */
+function isRawSelector(selector) {
+    return typeof selector === 'object' && 'locator' in selector;
+}
+/**
+ * Normalize a symbol to uppercase for case-insensitive lookup.
+ *
+ * @param symbol - The symbol to normalize.
+ * @returns The normalized (uppercase) symbol.
+ */
+function normalizeSymbol(symbol) {
+    return symbol.toUpperCase();
+}
+/**
+ * Normalize a locator for stable chain-aware lookup.
+ *
+ * @remarks
+ * EVM-style addresses (`0x...`) are normalized to lowercase for
+ * case-insensitive matching. Non-EVM locators keep original casing.
+ */
+function normalizeLocator(locator) {
+    if (locator.startsWith('0x') || locator.startsWith('0X')) {
+        return locator.toLowerCase();
+    }
+    return locator;
+}
+/**
+ * Build a stable map key for a chain + locator pair.
+ */
+function buildAddressKey(chainId, locator) {
+    return `${chainId}::${normalizeLocator(locator)}`;
+}
+/**
+ * Create a token registry with built-in tokens and optional extensions.
+ *
+ * @remarks
+ * The registry always includes built-in tokens (DEFAULT_TOKENS) like USDC.
+ * Custom tokens are merged on top - use this to add new tokens or override
+ * built-in definitions.
+ *
+ * @param options - Configuration options for the registry.
+ * @returns A token registry instance.
+ *
+ * @example
+ * ```typescript
+ * import { createTokenRegistry } from '@core/tokens'
+ *
+ * // Create registry with built-in tokens (USDC, etc.)
+ * const registry = createTokenRegistry()
+ *
+ * // Resolve USDC on Ethereum
+ * const usdc = registry.resolve('USDC', 'Ethereum')
+ * console.log(usdc.locator) // '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
+ * console.log(usdc.decimals) // 6
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Add custom tokens (built-ins are still included)
+ * const myToken: TokenDefinition = {
+ *   symbol: 'MY',
+ *   decimals: 18,
+ *   locators: { Ethereum: '0x...' },
+ * }
+ *
+ * const registry = createTokenRegistry({ tokens: [myToken] })
+ * registry.resolve('USDC', 'Ethereum') // Still works!
+ * registry.resolve('MY', 'Ethereum')   // Also works
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Override a built-in token
+ * const customUsdc: TokenDefinition = {
+ *   symbol: 'USDC',
+ *   decimals: 6,
+ *   locators: { MyChain: '0xCustomAddress' },
+ * }
+ *
+ * const registry = createTokenRegistry({ tokens: [customUsdc] })
+ * // Now USDC resolves to customUsdc definition
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Resolve arbitrary tokens by raw locator
+ * const registry = createTokenRegistry()
+ * const token = registry.resolve(
+ *   { locator: '0x1234...', decimals: 18 },
+ *   'Ethereum'
+ * )
+ * ```
+ */
+function createTokenRegistry(options = {}) {
+    const { tokens = [], requireDecimals = false } = options;
+    // Build the token map: always start with DEFAULT_TOKENS, then add custom tokens
+    const tokenMap = new Map();
+    // Add built-in tokens first
+    for (const def of DEFAULT_TOKENS) {
+        tokenMap.set(normalizeSymbol(def.symbol), def);
+    }
+    // Custom tokens override built-ins
+    for (const def of tokens) {
+        tokenMap.set(normalizeSymbol(def.symbol), def);
+    }
+    // Build an address index from the resolved token map so overrides win.
+    const addressMap = new Map();
+    for (const token of tokenMap.values()) {
+        for (const [chainId, locator] of Object.entries(token.locators)) {
+            if (typeof locator !== 'string' || locator.trim() === '') {
+                continue;
+            }
+            addressMap.set(buildAddressKey(chainId, locator), token);
+        }
+    }
+    /**
+     * Resolve a symbol selector to token information.
+     */
+    function resolveSymbol(symbol, chainId) {
+        const normalizedSymbol = normalizeSymbol(symbol);
+        const definition = tokenMap.get(normalizedSymbol);
+        if (definition === undefined) {
+            throw createTokenResolutionError(`Unknown token symbol: ${symbol}. Register it via createTokenRegistry({ tokens: [...] }) or use a raw selector.`, symbol, chainId);
+        }
+        const locator = definition.locators[chainId];
+        if (locator === undefined || locator.trim() === '') {
+            throw createTokenResolutionError(`Token ${symbol} has no locator for chain ${chainId}`, symbol, chainId);
+        }
+        const decimals = resolveTokenDecimals(definition, chainId);
+        return {
+            symbol: definition.symbol,
+            decimals,
+            locator: normalizeLocator(locator),
+        };
+    }
+    /**
+     * Resolve a raw selector to token information.
+     */
+    function resolveRaw(selector, chainId) {
+        const { locator, decimals } = selector;
+        // Validate locator
+        if (!locator || typeof locator !== 'string') {
+            throw createTokenResolutionError('Raw selector must have a valid locator string', selector, chainId);
+        }
+        // Decimals are always required for raw selectors
+        if (decimals === undefined) {
+            const message = requireDecimals
+                ? 'Decimals required for raw token selector (requireDecimals: true)'
+                : 'Decimals required for raw token selector. Provide { locator, decimals }.';
+            throw createTokenResolutionError(message, selector, chainId);
+        }
+        // Validate decimals
+        if (typeof decimals !== 'number' ||
+            decimals < 0 ||
+            !Number.isInteger(decimals)) {
+            throw createTokenResolutionError(`Invalid decimals: ${String(decimals)}. Must be a non-negative integer.`, selector, chainId);
+        }
+        return {
+            decimals,
+            locator: normalizeLocator(locator),
+        };
+    }
+    return {
+        resolve(selector, chainId) {
+            // Runtime validation of inputs - these checks are for JS consumers
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (selector === null || selector === undefined) {
+                throw createTokenResolutionError('Token selector cannot be null or undefined', selector, chainId);
+            }
+            if (chainId === '' || typeof chainId !== 'string') {
+                throw createTokenResolutionError('Chain ID is required for token resolution', selector, chainId);
+            }
+            // Dispatch based on selector type
+            if (isRawSelector(selector)) {
+                return resolveRaw(selector, chainId);
+            }
+            if (typeof selector === 'string') {
+                return resolveSymbol(selector, chainId);
+            }
+            throw createTokenResolutionError(`Invalid selector type: ${typeof selector}. Expected string or object with locator.`, selector, chainId);
+        },
+        resolveByAddress(address, chainId) {
+            if (!address || typeof address !== 'string') {
+                throw createTokenResolutionError('Token address is required for address resolution', { locator: address }, chainId);
+            }
+            if (chainId === '' || typeof chainId !== 'string') {
+                throw createTokenResolutionError('Chain ID is required for token resolution', { locator: address }, chainId);
+            }
+            const definition = addressMap.get(buildAddressKey(chainId, address));
+            if (definition === undefined) {
+                throw createTokenResolutionError(`Unknown token address: ${address} for chain ${chainId}`, { locator: address }, chainId);
+            }
+            const locator = definition.locators[chainId];
+            if (locator === undefined || locator.trim() === '') {
+                throw createTokenResolutionError(`Token ${definition.symbol} has no locator for chain ${chainId}`, definition.symbol, chainId);
+            }
+            const decimals = resolveTokenDecimals(definition, chainId);
+            return {
+                symbol: definition.symbol,
+                decimals,
+                locator: normalizeLocator(locator),
+            };
+        },
+        get(symbol) {
+            if (!symbol || typeof symbol !== 'string') {
+                return undefined;
+            }
+            return tokenMap.get(normalizeSymbol(symbol));
+        },
+        has(symbol) {
+            if (!symbol || typeof symbol !== 'string') {
+                return false;
+            }
+            return tokenMap.has(normalizeSymbol(symbol));
+        },
+        symbols() {
+            return Array.from(tokenMap.values()).map((def) => def.symbol);
+        },
+        entries() {
+            return Array.from(tokenMap.values());
+        },
+    };
+}
+
+/**
+ * Define a schema for token registry interfaces.
+ *
+ * @remarks
+ * Validate that a registry exposes the `resolve()` API used by adapters.
+ *
+ * @example
+ * ```typescript
+ * import { tokenRegistrySchema } from '@core/tokens'
+ *
+ * const registry = {
+ *   resolve: () => ({ locator: '0x0', decimals: 6 }),
+ * }
+ *
+ * tokenRegistrySchema.parse(registry)
+ * ```
+ */
+zod.z.custom((value) => {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return (typeof record['resolve'] === 'function' &&
+        typeof record['get'] === 'function' &&
+        typeof record['has'] === 'function' &&
+        typeof record['symbols'] === 'function' &&
+        typeof record['entries'] === 'function');
+}, {
+    message: 'Invalid token registry',
+});
+
+/**
+ * Build a complete explorer URL from a chain definition and transaction hash.
+ *
+ * This function takes a chain definition containing an explorer URL template
+ * and replaces the `{hash}` placeholder with the provided transaction hash
+ * to create a complete, valid explorer URL.
+ *
+ * @param chainDef - The chain definition containing the explorer URL template.
+ * @param txHash - The transaction hash to insert into the URL template.
+ * @returns A complete explorer URL with the transaction hash inserted.
+ * @throws Error if the chain definition is null/undefined.
+ * @throws Error if the transaction hash is null/undefined/empty.
+ * @throws Error if the explorer URL template is missing or empty.
+ * @throws Error if the explorer URL template doesn't contain the {hash} placeholder.
+ * @throws Error if the resulting URL is invalid.
+ *
+ * @example
+ * ```typescript
+ * import { buildExplorerUrl } from '@core/utils'
+ * import { Ethereum } from '@core/chains'
+ *
+ * // Build URL for Ethereum transaction
+ * const url = buildExplorerUrl(Ethereum, '0x1234567890abcdef...')
+ * console.log(url) // 'https://etherscan.io/tx/0x1234567890abcdef...'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { buildExplorerUrl } from '@core/utils'
+ * import { Solana } from '@core/chains'
+ *
+ * // Build URL for Solana transaction
+ * const url = buildExplorerUrl(Solana, 'abc123def456...')
+ * console.log(url) // 'https://solscan.io/tx/abc123def456...'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { buildExplorerUrl } from '@core/utils'
+ * import { Aptos } from '@core/chains'
+ *
+ * // Build URL for Aptos transaction with query parameters
+ * const url = buildExplorerUrl(Aptos, '0xabc123...')
+ * console.log(url) // 'https://explorer.aptoslabs.com/txn/0xabc123...?network=mainnet'
+ * ```
+ */
+function buildExplorerUrl(chainDef, txHash) {
+    // Validate input parameters using our standard validation pattern
+    validateOrThrow({ chainDef, txHash }, buildExplorerUrlParamsSchema, 'Invalid buildExplorerUrl parameters');
+    // Parse and transform input parameters (e.g., trim whitespace from txHash)
+    const { chainDef: validChainDef, txHash: validTxHash } = buildExplorerUrlParamsSchema.parse({ chainDef, txHash });
+    // Replace all occurrences of the placeholder with the transaction hash
+    const explorerUrl = validChainDef.explorerUrl.replace(/{hash}/g, validTxHash);
+    // Validate the resulting URL
+    validate(explorerUrl, explorerUrlSchema, 'explorer URL');
+    return explorerUrl;
+}
+
+/**
+ * CCTP forwarding magic bytes prefix.
+ *
+ * The ASCII string "cctp-forward" (12 bytes) that identifies a forwarding request.
+ * This prefix is right-padded to 24 bytes in the final hookData.
+ */
+const CCTP_FORWARD_MAGIC_PREFIX = 'cctp-forward';
+/**
+ * CCTP forwarding version number.
+ *
+ * Version 0 is used for basic forwarding requests.
+ */
+const CCTP_FORWARD_VERSION = 0;
+/**
+ * Length of Circle-reserved payload for basic forwarding (0 bytes).
+ *
+ * Set to 0 when no additional Circle-reserved data is needed.
+ */
+const CCTP_FORWARD_PAYLOAD_LENGTH = 0;
+/**
+ * Build the hookData bytes for CCTP forwarding.
+ *
+ * Constructs a 32-byte hookData payload that signals to Circle's Orbit relayer
+ * that the user wants automated attestation fetching and destination mint execution.
+ *
+ * The hookData format is:
+ * - Bytes 0-23: ASCII "cctp-forward" right-padded to 24 bytes with zeros
+ * - Bytes 24-27: uint32 version (big-endian) - currently 0
+ * - Bytes 28-31: uint32 length (big-endian) - 0 for basic forwarding
+ *
+ * @returns A 0x-prefixed hex string representing the 32-byte hookData
+ *
+ * @example
+ * ```typescript
+ * import { buildForwardingHookData } from '@core/utils'
+ *
+ * const hookData = buildForwardingHookData()
+ * // Returns: '0x636374702d666f72776172640000000000000000000000000000000000000000'
+ *
+ * // Use with depositForBurnWithHook action
+ * await adapter.action('cctp.v2.depositForBurnWithHook', {
+ *   amount: BigInt('1000000'),
+ *   mintRecipient: '0x...',
+ *   maxFee: BigInt('50000'),
+ *   minFinalityThreshold: 1000,
+ *   fromChain: ethereum,
+ *   toChain: base,
+ *   hookData
+ * })
+ * ```
+ */
+// Cached result for memoization (computed once on first call)
+let cachedHookDataHex = null;
 function buildForwardingHookData() {
     // Return cached result if already computed
     if (cachedHookDataHex !== null) {
@@ -5549,6 +6688,21 @@ async function fetchUsdcFastBurnFee(sourceDomain, destinationDomain, isTestnet)
     return minimumFee;
 }
 
+/**
+ * Well-known SPL Token program ID.
+ * Duplicated here as a raw string to avoid a static import of \@core/adapter-solana
+ * (which would transitively pull \@solana/web3.js into the top-level bundle and
+ * break lazy-loading for EVM-only consumers).
+ *
+ * This MUST match TOKEN_PROGRAM_ID in @core/adapter-solana/src/utils/splTokenUtils.
+ */
+const TOKEN_PROGRAM_ID_BASE58 = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'; // NOSONAR — public Solana program address
+/**
+ * Well-known SPL Associated Token Account program ID (same rationale as above).
+ *
+ * This MUST match ASSOCIATED_TOKEN_PROGRAM_ID in @core/adapter-solana/src/utils/splTokenUtils.
+ */
+const ASSOCIATED_TOKEN_PROGRAM_ID_BASE58 = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'; // NOSONAR — public Solana program address
 /**
  * Get the token account address where USDC will be minted for the recipient.
  *
@@ -5592,20 +6746,30 @@ mintAddress) => {
         return rawAddress;
     }
     else {
-        // Solana: derive the associated token account
-        // Use dynamic import to avoid loading Solana dependencies for EVM-only users
+        // Solana: derive the associated token account.
+        // Both @solana/web3.js and the program-ID constants are resolved lazily
+        // so that EVM-only consumers never load Solana code.
+        const { PublicKey } = await import('@solana/web3.js').catch(() => {
+            throw new KitError({
+                ...InputError.VALIDATION_FAILED,
+                recoverability: 'FATAL',
+                message: 'Failed to load @solana/web3.js. Please ensure it is installed: npm install @solana/web3.js',
+            });
+        });
         try {
-            const [{ PublicKey }, { getAssociatedTokenAddressSync }] = await Promise.all([
-                import('@solana/web3.js'),
-                import('@solana/spl-token'),
-            ]);
             const owner = new PublicKey(rawAddress);
             const mintPub = new PublicKey(mintAddress);
-            const ata = getAssociatedTokenAddressSync(mintPub, owner);
+            const tokenProgramId = new PublicKey(TOKEN_PROGRAM_ID_BASE58);
+            const ataProgramId = new PublicKey(ASSOCIATED_TOKEN_PROGRAM_ID_BASE58);
+            const [ata] = PublicKey.findProgramAddressSync([owner.toBuffer(), tokenProgramId.toBuffer(), mintPub.toBuffer()], ataProgramId);
             return ata.toBase58();
         }
-        catch {
-            throw new Error('Failed to derive Solana token account. Please ensure @solana/web3.js and @solana/spl-token are installed: npm install @solana/web3.js @solana/spl-token');
+        catch (error) {
+            throw new KitError({
+                ...InputError.INVALID_ADDRESS,
+                recoverability: 'FATAL',
+                message: `Failed to derive Solana Associated Token Account for recipient "${rawAddress}": ${error instanceof Error ? error.message : String(error)}`,
+            });
         }
     }
 };
@@ -7921,590 +9085,239 @@ function createLogger(options, stream) {
     const finalOptions = redactConfig
         ? { ...pinoOptions, redact: redactConfig }
         : pinoOptions;
-    const pinoInstance = pino__default(finalOptions);
-    return wrapPino(pinoInstance);
-}
-
-/**
- * Factory for creating Runtime instances with defaults.
- *
- * @packageDocumentation
- */
-// ============================================================================
-// Validation Schema
-// ============================================================================
-/**
- * Schema for validating {@link RuntimeOptions}.
- *
- * @remarks
- * Used internally by {@link createRuntime} to validate options from JS consumers.
- * Exported for advanced use cases where manual validation is needed.
- */
-zod.z
-    .object({
-    logger: loggerSchema.optional(),
-    metrics: metricsSchema.optional(),
-})
-    .passthrough();
-// ============================================================================
-// Factory
-// ============================================================================
-/**
- * Create a complete Runtime with sensible defaults.
- *
- * @param options - Optional configuration to override logger and metrics.
- * @returns A frozen, immutable Runtime with all services guaranteed present.
- * @throws KitError (INPUT_VALIDATION_FAILED) if options contain invalid services.
- *
- * @remarks
- * Creates a fully-configured runtime by merging provided options with defaults.
- * The returned runtime is frozen to enforce immutability.
- *
- * | Service | Default | Configurable |
- * |---------|---------|--------------|
- * | `logger` | pino logger (info level) | Yes |
- * | `metrics` | No-op metrics | Yes |
- * | `events` | Internal event bus | No |
- * | `clock` | `Date.now()` | No |
- *
- * **Why only logger and metrics?**
- *
- * - **Logger/Metrics**: Integration points with your infrastructure
- * - **Events**: Internal pub/sub mechanism - subscribe via `runtime.events.on()`
- * - **Clock**: Testing concern - use mock factories for tests
- *
- * @example
- * ```typescript
- * import { createRuntime, createLogger } from '@core/runtime'
- *
- * // Use all defaults
- * const runtime = createRuntime()
- *
- * // Custom logger
- * const runtime = createRuntime({
- *   logger: createLogger({ level: 'debug' }),
- * })
- *
- * // Custom metrics (e.g., Prometheus)
- * const runtime = createRuntime({
- *   metrics: myPrometheusMetrics,
- * })
- *
- * // Subscribe to events (don't replace the bus)
- * runtime.events.on('operation.*', (event) => {
- *   console.log('Event:', event.name)
- * })
- * ```
- */
-function createRuntime(options) {
-    // Resolve logger first (events may need it)
-    const logger = createLogger();
-    // Internal services - not configurable
-    const events = createEventBus({ logger });
-    const clock = defaultClock;
-    // Resolve metrics
-    const metrics = noopMetrics;
-    return Object.freeze({ logger, events, metrics, clock });
-}
-
-/**
- * Invocation context resolution - resolves the **WHO/HOW** of an operation.
- *
- * @packageDocumentation
- */
-// ============================================================================
-// Validation Schemas
-// ============================================================================
-/**
- * Schema for validating Caller.
- */
-const callerSchema = zod.z.object({
-    type: zod.z.string(),
-    name: zod.z.string(),
-    version: zod.z.string().optional(),
-});
-/**
- * Schema for validating InvocationMeta input.
- */
-const invocationMetaSchema = zod.z
-    .object({
-    traceId: zod.z.string().optional(),
-    runtime: zod.z.object({}).passthrough().optional(),
-    tokens: zod.z.object({}).passthrough().optional(),
-    callers: zod.z.array(callerSchema).optional(),
-})
-    .strict();
-// ============================================================================
-// Invocation Context Resolution
-// ============================================================================
-/**
- * Resolve invocation metadata to invocation context.
- *
- * @param meta - User-provided invocation metadata (**WHO/HOW**), optional.
- * @param defaults - Default runtime and tokens to use if not overridden.
- * @returns Frozen, immutable invocation context with guaranteed values.
- * @throws KitError when meta contains invalid properties.
- *
- * @remarks
- * Resolves the **WHO** called and **HOW** to observe:
- * - TraceId: Uses provided value or generates new one
- * - Runtime: Uses meta.runtime if provided, otherwise defaults.runtime
- * - Tokens: Uses meta.tokens if provided, otherwise defaults.tokens
- * - Callers: Uses provided array or empty array
- *
- * The returned context is frozen to enforce immutability.
- *
- * @example
- * ```typescript
- * import { resolveInvocationContext, createRuntime } from '@core/runtime'
- * import { createTokenRegistry } from '@core/tokens'
- *
- * const defaults = {
- *   runtime: createRuntime(),
- *   tokens: createTokenRegistry(),
- * }
- *
- * // Minimal - just using defaults
- * const ctx = resolveInvocationContext(undefined, defaults)
- *
- * // With trace ID and caller info
- * const ctx = resolveInvocationContext(
- *   {
- *     traceId: 'abc-123',
- *     callers: [{ type: 'kit', name: 'BridgeKit', version: '1.0.0' }],
- *   },
- *   defaults
- * )
- *
- * // With runtime override (complete replacement)
- * const ctx = resolveInvocationContext(
- *   { runtime: createRuntime({ logger: myLogger }) },
- *   defaults
- * )
- * ```
- */
-function resolveInvocationContext(meta, defaults) {
-    // Validate meta input if provided
-    if (meta !== undefined) {
-        const result = invocationMetaSchema.safeParse(meta);
-        if (!result.success) {
-            throw createValidationFailedError('invocationMeta', meta, result.error.errors.map((e) => e.message).join(', '));
-        }
-    }
-    // Generate trace ID if not provided
-    const traceId = meta?.traceId ?? createTraceId();
-    // Use meta overrides or fall back to defaults
-    const runtime = meta?.runtime ?? defaults.runtime;
-    const tokens = meta?.tokens ?? defaults.tokens;
-    const callers = meta?.callers ?? [];
-    return Object.freeze({ traceId, runtime, tokens, callers });
+    const pinoInstance = pino__default(finalOptions);
+    return wrapPino(pinoInstance);
 }
 
 /**
- * Extend an invocation context by appending a caller to its call chain.
+ * Factory for creating Runtime instances with defaults.
  *
- * @param context - The existing invocation context to extend.
- * @param caller - The caller to append to the call chain.
- * @returns A new frozen invocation context with the caller appended.
+ * @packageDocumentation
+ */
+// ============================================================================
+// Validation Schema
+// ============================================================================
+/**
+ * Schema for validating {@link RuntimeOptions}.
  *
  * @remarks
- * This function creates a new immutable context with the caller appended
- * to the `callers` array while preserving all other context properties
- * (traceId, runtime, tokens).
- *
- * The returned context is frozen to enforce immutability.
- *
- * @example
- * ```typescript
- * import { extendInvocationContext } from '@core/runtime'
- *
- * const caller = { type: 'provider', name: 'CCTPV2', version: '1.0.0' }
- * const extended = extendInvocationContext(existingContext, caller)
- * // extended.callers === [...existingContext.callers, caller]
- * ```
+ * Used internally by {@link createRuntime} to validate options from JS consumers.
+ * Exported for advanced use cases where manual validation is needed.
  */
-function extendInvocationContext(context, caller) {
-    return Object.freeze({
-        traceId: context.traceId,
-        runtime: context.runtime,
-        tokens: context.tokens,
-        callers: [...context.callers, caller],
-    });
-}
-
-// Clock - expose defaultClock for backward compatibility
-/** Clock validation schema (backward compatibility). */
-zod.z.custom((val) => val !== null &&
-    typeof val === 'object' &&
-    'now' in val &&
-    typeof val['now'] === 'function');
-/** EventBus validation schema (backward compatibility). */
-zod.z.custom((val) => val !== null &&
-    typeof val === 'object' &&
-    'emit' in val &&
-    typeof val['emit'] === 'function');
-/** Runtime validation schema (backward compatibility). */
 zod.z
     .object({
-    logger: zod.z.any().optional(),
-    events: zod.z.any().optional(),
-    metrics: zod.z.any().optional(),
-    clock: zod.z.any().optional(),
+    logger: loggerSchema.optional(),
+    metrics: metricsSchema.optional(),
 })
     .passthrough();
-
+// ============================================================================
+// Factory
+// ============================================================================
 /**
- * Create a structured error for token resolution failures.
+ * Create a complete Runtime with sensible defaults.
  *
- * @remarks
- * Returns a `KitError` with `INPUT_INVALID_TOKEN` code (1006).
- * The error trace contains the selector and chain context for debugging.
+ * @param options - Optional configuration to override logger and metrics.
+ * @returns A frozen, immutable Runtime with all services guaranteed present.
+ * @throws KitError (INPUT_VALIDATION_FAILED) if options contain invalid services.
  *
- * @param message - Human-readable error description.
- * @param selector - The token selector that failed to resolve.
- * @param chainId - The chain being resolved for (optional).
- * @param cause - The underlying error, if any (optional).
- * @returns A KitError with INPUT type and FATAL recoverability.
+ * @remarks
+ * Creates a fully-configured runtime by merging provided options with defaults.
+ * The returned runtime is frozen to enforce immutability.
  *
- * @example
- * ```typescript
- * throw createTokenResolutionError(
- *   'Unknown token symbol: FAKE',
- *   'FAKE',
- *   'Ethereum'
- * )
- * ```
- */
-function createTokenResolutionError(message, selector, chainId, cause) {
-    const trace = {
-        selector,
-        ...(chainId === undefined ? {} : { chainId }),
-        ...({} ),
-    };
-    return new KitError({
-        ...InputError.INVALID_TOKEN,
-        recoverability: 'FATAL',
-        message,
-        cause: { trace },
-    });
-}
-
-/**
- * USDC token definition with addresses and metadata.
+ * | Service | Default | Configurable |
+ * |---------|---------|--------------|
+ * | `logger` | pino logger (info level) | Yes |
+ * | `metrics` | No-op metrics | Yes |
+ * | `events` | Internal event bus | No |
+ * | `clock` | `Date.now()` | No |
  *
- * @remarks
- * This is the built-in USDC definition used by the TokenRegistry.
- * Includes all known USDC addresses across supported chains.
+ * **Why only logger and metrics?**
  *
- * Keys use the `Blockchain` enum for type safety. Both enum values
- * and string literals are supported:
- * - `Blockchain.Ethereum` or `'Ethereum'`
+ * - **Logger/Metrics**: Integration points with your infrastructure
+ * - **Events**: Internal pub/sub mechanism - subscribe via `runtime.events.on()`
+ * - **Clock**: Testing concern - use mock factories for tests
  *
  * @example
  * ```typescript
- * import { USDC } from '@core/tokens'
- * import { Blockchain } from '@core/chains'
- *
- * console.log(USDC.symbol)   // 'USDC'
- * console.log(USDC.decimals) // 6
- * console.log(USDC.locators[Blockchain.Ethereum])
- * // '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
- * ```
- */
-const USDC = {
-    symbol: 'USDC',
-    decimals: 6,
-    locators: {
-        // =========================================================================
-        // Mainnets (alphabetically sorted)
-        // =========================================================================
-        [Blockchain.Arbitrum]: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
-        [Blockchain.Avalanche]: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E',
-        [Blockchain.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
-        [Blockchain.Celo]: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
-        [Blockchain.Codex]: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
-        [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
-        [Blockchain.Hedera]: '0.0.456858',
-        [Blockchain.HyperEVM]: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
-        [Blockchain.Ink]: '0x2D270e6886d130D724215A266106e6832161EAEd',
-        [Blockchain.Linea]: '0x176211869ca2b568f2a7d4ee941e073a821ee1ff',
-        [Blockchain.NEAR]: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
-        [Blockchain.Noble]: 'uusdc',
-        [Blockchain.Optimism]: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
-        [Blockchain.Plume]: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
-        [Blockchain.Polkadot_Asset_Hub]: '1337',
-        [Blockchain.Polygon]: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
-        [Blockchain.Sei]: '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392',
-        [Blockchain.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
-        [Blockchain.Sonic]: '0x29219dd400f2Bf60E5a23d13Be72B486D4038894',
-        [Blockchain.Stellar]: 'USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
-        [Blockchain.Sui]: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
-        [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
-        [Blockchain.World_Chain]: '0x79A02482A880bCe3F13E09da970dC34dB4cD24D1',
-        [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
-        [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
-        // =========================================================================
-        // Testnets (alphabetically sorted)
-        // =========================================================================
-        [Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
-        [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
-        [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
-        [Blockchain.Codex_Testnet]: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
-        [Blockchain.Ethereum_Sepolia]: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
-        [Blockchain.Hedera_Testnet]: '0.0.429274',
-        [Blockchain.HyperEVM_Testnet]: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
-        [Blockchain.Ink_Testnet]: '0xFabab97dCE620294D2B0b0e46C68964e326300Ac',
-        [Blockchain.Linea_Sepolia]: '0xfece4462d57bd51a6a552365a011b95f0e16d9b7',
-        [Blockchain.NEAR_Testnet]: '3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af',
-        [Blockchain.Noble_Testnet]: 'uusdc',
-        [Blockchain.Optimism_Sepolia]: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
-        [Blockchain.Plume_Testnet]: '0xcB5f30e335672893c7eb944B374c196392C19D18',
-        [Blockchain.Polkadot_Westmint]: '31337',
-        [Blockchain.Polygon_Amoy_Testnet]: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
-        [Blockchain.Sei_Testnet]: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED',
-        [Blockchain.Solana_Devnet]: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
-        [Blockchain.Sonic_Testnet]: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
-        [Blockchain.Stellar_Testnet]: 'USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
-        [Blockchain.Sui_Testnet]: '0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC',
-        [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
-        [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
-        [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
-        [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853',
-    },
-};
-
-// Re-export for consumers
-/**
- * All default token definitions.
+ * import { createRuntime, createLogger } from '@core/runtime'
  *
- * @remarks
- * These tokens are automatically included in the TokenRegistry when created
- * without explicit defaults. Extensions can override these definitions.
+ * // Use all defaults
+ * const runtime = createRuntime()
  *
- * @example
- * ```typescript
- * import { createTokenRegistry } from '@core/tokens'
+ * // Custom logger
+ * const runtime = createRuntime({
+ *   logger: createLogger({ level: 'debug' }),
+ * })
  *
- * // Registry uses these by default
- * const registry = createTokenRegistry()
+ * // Custom metrics (e.g., Prometheus)
+ * const runtime = createRuntime({
+ *   metrics: myPrometheusMetrics,
+ * })
  *
- * // Add custom tokens (built-ins are still included)
- * const customRegistry = createTokenRegistry({
- *   tokens: [myCustomToken],
+ * // Subscribe to events (don't replace the bus)
+ * runtime.events.on('operation.*', (event) => {
+ *   console.log('Event:', event.name)
  * })
  * ```
  */
-const DEFAULT_TOKENS = [USDC];
+function createRuntime(options) {
+    // Resolve logger first (events may need it)
+    const logger = createLogger();
+    // Internal services - not configurable
+    const events = createEventBus({ logger });
+    const clock = defaultClock;
+    // Resolve metrics
+    const metrics = noopMetrics;
+    return Object.freeze({ logger, events, metrics, clock });
+}
 
 /**
- * Check if a selector is a raw token selector (object form).
+ * Invocation context resolution - resolves the **WHO/HOW** of an operation.
  *
- * @param selector - The token selector to check.
- * @returns True if the selector is a raw token selector.
+ * @packageDocumentation
  */
-function isRawSelector(selector) {
-    return typeof selector === 'object' && 'locator' in selector;
-}
+// ============================================================================
+// Validation Schemas
+// ============================================================================
+/**
+ * Schema for validating Caller.
+ */
+const callerSchema = zod.z.object({
+    type: zod.z.string(),
+    name: zod.z.string(),
+    version: zod.z.string().optional(),
+});
+/**
+ * Schema for validating InvocationMeta input.
+ */
+const invocationMetaSchema = zod.z
+    .object({
+    traceId: zod.z.string().optional(),
+    runtime: zod.z.object({}).passthrough().optional(),
+    tokens: zod.z.object({}).passthrough().optional(),
+    callers: zod.z.array(callerSchema).optional(),
+})
+    .strict();
+// ============================================================================
+// Invocation Context Resolution
+// ============================================================================
 /**
- * Normalize a symbol to uppercase for case-insensitive lookup.
+ * Resolve invocation metadata to invocation context.
  *
- * @param symbol - The symbol to normalize.
- * @returns The normalized (uppercase) symbol.
- */
-function normalizeSymbol(symbol) {
-    return symbol.toUpperCase();
-}
-/**
- * Create a token registry with built-in tokens and optional extensions.
+ * @param meta - User-provided invocation metadata (**WHO/HOW**), optional.
+ * @param defaults - Default runtime and tokens to use if not overridden.
+ * @returns Frozen, immutable invocation context with guaranteed values.
+ * @throws KitError when meta contains invalid properties.
  *
  * @remarks
- * The registry always includes built-in tokens (DEFAULT_TOKENS) like USDC.
- * Custom tokens are merged on top - use this to add new tokens or override
- * built-in definitions.
+ * Resolves the **WHO** called and **HOW** to observe:
+ * - TraceId: Uses provided value or generates new one
+ * - Runtime: Uses meta.runtime if provided, otherwise defaults.runtime
+ * - Tokens: Uses meta.tokens if provided, otherwise defaults.tokens
+ * - Callers: Uses provided array or empty array
  *
- * @param options - Configuration options for the registry.
- * @returns A token registry instance.
+ * The returned context is frozen to enforce immutability.
  *
  * @example
  * ```typescript
+ * import { resolveInvocationContext, createRuntime } from '@core/runtime'
  * import { createTokenRegistry } from '@core/tokens'
  *
- * // Create registry with built-in tokens (USDC, etc.)
- * const registry = createTokenRegistry()
- *
- * // Resolve USDC on Ethereum
- * const usdc = registry.resolve('USDC', 'Ethereum')
- * console.log(usdc.locator) // '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
- * console.log(usdc.decimals) // 6
- * ```
- *
- * @example
- * ```typescript
- * // Add custom tokens (built-ins are still included)
- * const myToken: TokenDefinition = {
- *   symbol: 'MY',
- *   decimals: 18,
- *   locators: { Ethereum: '0x...' },
+ * const defaults = {
+ *   runtime: createRuntime(),
+ *   tokens: createTokenRegistry(),
  * }
  *
- * const registry = createTokenRegistry({ tokens: [myToken] })
- * registry.resolve('USDC', 'Ethereum') // Still works!
- * registry.resolve('MY', 'Ethereum')   // Also works
- * ```
- *
- * @example
- * ```typescript
- * // Override a built-in token
- * const customUsdc: TokenDefinition = {
- *   symbol: 'USDC',
- *   decimals: 6,
- *   locators: { MyChain: '0xCustomAddress' },
- * }
+ * // Minimal - just using defaults
+ * const ctx = resolveInvocationContext(undefined, defaults)
  *
- * const registry = createTokenRegistry({ tokens: [customUsdc] })
- * // Now USDC resolves to customUsdc definition
- * ```
+ * // With trace ID and caller info
+ * const ctx = resolveInvocationContext(
+ *   {
+ *     traceId: 'abc-123',
+ *     callers: [{ type: 'kit', name: 'BridgeKit', version: '1.0.0' }],
+ *   },
+ *   defaults
+ * )
  *
- * @example
- * ```typescript
- * // Resolve arbitrary tokens by raw locator
- * const registry = createTokenRegistry()
- * const token = registry.resolve(
- *   { locator: '0x1234...', decimals: 18 },
- *   'Ethereum'
+ * // With runtime override (complete replacement)
+ * const ctx = resolveInvocationContext(
+ *   { runtime: createRuntime({ logger: myLogger }) },
+ *   defaults
  * )
  * ```
  */
-function createTokenRegistry(options = {}) {
-    const { tokens = [], requireDecimals = false } = options;
-    // Build the token map: always start with DEFAULT_TOKENS, then add custom tokens
-    const tokenMap = new Map();
-    // Add built-in tokens first
-    for (const def of DEFAULT_TOKENS) {
-        tokenMap.set(normalizeSymbol(def.symbol), def);
-    }
-    // Custom tokens override built-ins
-    for (const def of tokens) {
-        tokenMap.set(normalizeSymbol(def.symbol), def);
-    }
-    /**
-     * Resolve a symbol selector to token information.
-     */
-    function resolveSymbol(symbol, chainId) {
-        const normalizedSymbol = normalizeSymbol(symbol);
-        const definition = tokenMap.get(normalizedSymbol);
-        if (definition === undefined) {
-            throw createTokenResolutionError(`Unknown token symbol: ${symbol}. Register it via createTokenRegistry({ tokens: [...] }) or use a raw selector.`, symbol, chainId);
-        }
-        const locator = definition.locators[chainId];
-        if (locator === undefined || locator.trim() === '') {
-            throw createTokenResolutionError(`Token ${symbol} has no locator for chain ${chainId}`, symbol, chainId);
-        }
-        return {
-            symbol: definition.symbol,
-            decimals: definition.decimals,
-            locator,
-        };
-    }
-    /**
-     * Resolve a raw selector to token information.
-     */
-    function resolveRaw(selector, chainId) {
-        const { locator, decimals } = selector;
-        // Validate locator
-        if (!locator || typeof locator !== 'string') {
-            throw createTokenResolutionError('Raw selector must have a valid locator string', selector, chainId);
-        }
-        // Decimals are always required for raw selectors
-        if (decimals === undefined) {
-            const message = requireDecimals
-                ? 'Decimals required for raw token selector (requireDecimals: true)'
-                : 'Decimals required for raw token selector. Provide { locator, decimals }.';
-            throw createTokenResolutionError(message, selector, chainId);
-        }
-        // Validate decimals
-        if (typeof decimals !== 'number' ||
-            decimals < 0 ||
-            !Number.isInteger(decimals)) {
-            throw createTokenResolutionError(`Invalid decimals: ${String(decimals)}. Must be a non-negative integer.`, selector, chainId);
+function resolveInvocationContext(meta, defaults) {
+    // Validate meta input if provided
+    if (meta !== undefined) {
+        const result = invocationMetaSchema.safeParse(meta);
+        if (!result.success) {
+            throw createValidationFailedError('invocationMeta', meta, result.error.errors.map((e) => e.message).join(', '));
         }
-        return {
-            decimals,
-            locator,
-        };
     }
-    return {
-        resolve(selector, chainId) {
-            // Runtime validation of inputs - these checks are for JS consumers
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            if (selector === null || selector === undefined) {
-                throw createTokenResolutionError('Token selector cannot be null or undefined', selector, chainId);
-            }
-            if (chainId === '' || typeof chainId !== 'string') {
-                throw createTokenResolutionError('Chain ID is required for token resolution', selector, chainId);
-            }
-            // Dispatch based on selector type
-            if (isRawSelector(selector)) {
-                return resolveRaw(selector, chainId);
-            }
-            if (typeof selector === 'string') {
-                return resolveSymbol(selector, chainId);
-            }
-            throw createTokenResolutionError(`Invalid selector type: ${typeof selector}. Expected string or object with locator.`, selector, chainId);
-        },
-        get(symbol) {
-            if (!symbol || typeof symbol !== 'string') {
-                return undefined;
-            }
-            return tokenMap.get(normalizeSymbol(symbol));
-        },
-        has(symbol) {
-            if (!symbol || typeof symbol !== 'string') {
-                return false;
-            }
-            return tokenMap.has(normalizeSymbol(symbol));
-        },
-        symbols() {
-            return Array.from(tokenMap.values()).map((def) => def.symbol);
-        },
-        entries() {
-            return Array.from(tokenMap.values());
-        },
-    };
+    // Generate trace ID if not provided
+    const traceId = meta?.traceId ?? createTraceId();
+    // Use meta overrides or fall back to defaults
+    const runtime = meta?.runtime ?? defaults.runtime;
+    const tokens = meta?.tokens ?? defaults.tokens;
+    const callers = meta?.callers ?? [];
+    return Object.freeze({ traceId, runtime, tokens, callers });
 }
 
 /**
- * Define a schema for token registry interfaces.
+ * Extend an invocation context by appending a caller to its call chain.
+ *
+ * @param context - The existing invocation context to extend.
+ * @param caller - The caller to append to the call chain.
+ * @returns A new frozen invocation context with the caller appended.
  *
  * @remarks
- * Validate that a registry exposes the `resolve()` API used by adapters.
+ * This function creates a new immutable context with the caller appended
+ * to the `callers` array while preserving all other context properties
+ * (traceId, runtime, tokens).
+ *
+ * The returned context is frozen to enforce immutability.
  *
  * @example
  * ```typescript
- * import { tokenRegistrySchema } from '@core/tokens'
- *
- * const registry = {
- *   resolve: () => ({ locator: '0x0', decimals: 6 }),
- * }
+ * import { extendInvocationContext } from '@core/runtime'
  *
- * tokenRegistrySchema.parse(registry)
+ * const caller = { type: 'provider', name: 'CCTPV2', version: '1.0.0' }
+ * const extended = extendInvocationContext(existingContext, caller)
+ * // extended.callers === [...existingContext.callers, caller]
  * ```
  */
-zod.z.custom((value) => {
-    if (value === null || typeof value !== 'object') {
-        return false;
-    }
-    const record = value;
-    return (typeof record['resolve'] === 'function' &&
-        typeof record['get'] === 'function' &&
-        typeof record['has'] === 'function' &&
-        typeof record['symbols'] === 'function' &&
-        typeof record['entries'] === 'function');
-}, {
-    message: 'Invalid token registry',
-});
+function extendInvocationContext(context, caller) {
+    return Object.freeze({
+        traceId: context.traceId,
+        runtime: context.runtime,
+        tokens: context.tokens,
+        callers: [...context.callers, caller],
+    });
+}
+
+// Clock - expose defaultClock for backward compatibility
+/** Clock validation schema (backward compatibility). */
+zod.z.custom((val) => val !== null &&
+    typeof val === 'object' &&
+    'now' in val &&
+    typeof val['now'] === 'function');
+/** EventBus validation schema (backward compatibility). */
+zod.z.custom((val) => val !== null &&
+    typeof val === 'object' &&
+    'emit' in val &&
+    typeof val['emit'] === 'function');
+/** Runtime validation schema (backward compatibility). */
+zod.z
+    .object({
+    logger: zod.z.any().optional(),
+    events: zod.z.any().optional(),
+    metrics: zod.z.any().optional(),
+    clock: zod.z.any().optional(),
+})
+    .passthrough();
 
-var version = "1.4.0";
+var version = "1.4.1";
 var pkg = {
 	version: version};
 
@@ -8987,6 +9800,24 @@ const validateNativeBalanceForTransaction = async (params) => {
     }
 };
 
+/**
+ * Permit signature standards for gasless token approvals.
+ *
+ * Defines the permit types that can be used to approve token spending
+ * without requiring a separate approval transaction.
+ *
+ * @remarks
+ * - NONE: No permit, tokens must be pre-approved via separate transaction
+ * - EIP2612: Standard ERC-20 permit (USDC, DAI v2, and most modern tokens)
+ */
+var PermitType;
+(function (PermitType) {
+    /** No permit required - tokens must be pre-approved */
+    PermitType[PermitType["NONE"] = 0] = "NONE";
+    /** EIP-2612 standard permit */
+    PermitType[PermitType["EIP2612"] = 1] = "EIP2612";
+})(PermitType || (PermitType = {}));
+
 /**
  * CCTP bridge step names that can occur in the bridging flow.
  *