@circle-fin/app-kit 1.4.1 → 1.5.0

package/index.cjs

@@ -3405,6 +3405,8 @@ exports.Blockchain = void 0;
     Blockchain["Hedera_Testnet"] = "Hedera_Testnet";
     Blockchain["HyperEVM"] = "HyperEVM";
     Blockchain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    Blockchain["Injective"] = "Injective";
+    Blockchain["Injective_Testnet"] = "Injective_Testnet";
     Blockchain["Ink"] = "Ink";
     Blockchain["Ink_Testnet"] = "Ink_Testnet";
     Blockchain["Linea"] = "Linea";
@@ -3419,6 +3421,8 @@ exports.Blockchain = void 0;
     Blockchain["Noble_Testnet"] = "Noble_Testnet";
     Blockchain["Optimism"] = "Optimism";
     Blockchain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    Blockchain["Pharos"] = "Pharos";
+    Blockchain["Pharos_Testnet"] = "Pharos_Testnet";
     Blockchain["Polkadot_Asset_Hub"] = "Polkadot_Asset_Hub";
     Blockchain["Polkadot_Westmint"] = "Polkadot_Westmint";
     Blockchain["Plume"] = "Plume";
@@ -3622,11 +3626,13 @@ exports.BridgeChain = void 0;
     BridgeChain["Edge"] = "Edge";
     BridgeChain["Ethereum"] = "Ethereum";
     BridgeChain["HyperEVM"] = "HyperEVM";
+    BridgeChain["Injective"] = "Injective";
     BridgeChain["Ink"] = "Ink";
     BridgeChain["Linea"] = "Linea";
     BridgeChain["Monad"] = "Monad";
     BridgeChain["Morph"] = "Morph";
     BridgeChain["Optimism"] = "Optimism";
+    BridgeChain["Pharos"] = "Pharos";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
     BridgeChain["Sei"] = "Sei";
@@ -3644,11 +3650,13 @@ exports.BridgeChain = void 0;
     BridgeChain["Edge_Testnet"] = "Edge_Testnet";
     BridgeChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    BridgeChain["Injective_Testnet"] = "Injective_Testnet";
     BridgeChain["Ink_Testnet"] = "Ink_Testnet";
     BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
     BridgeChain["Monad_Testnet"] = "Monad_Testnet";
     BridgeChain["Morph_Testnet"] = "Morph_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    BridgeChain["Pharos_Testnet"] = "Pharos_Testnet";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
     BridgeChain["Sei_Testnet"] = "Sei_Testnet";
@@ -3994,6 +4002,12 @@ const SWAP_TOKEN_REGISTRY = {
         category: 'wrapped',
         description: 'Wrapped Polygon',
     },
+    CIRBTC: {
+        symbol: 'CIRBTC',
+        decimals: 8,
+        category: 'wrapped',
+        description: 'Circle Bitcoin',
+    },
 };
 /**
  * Special NATIVE token constant for swap operations.
@@ -5081,6 +5095,98 @@ const HyperEVMTestnet = defineChain({
     },
 });
 
+/**
+ * Injective Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Injective blockchain.
+ * Injective is a high-performance, interoperable Layer-1 blockchain built for
+ * finance, with an EVM execution layer on top of a Cosmos SDK base and
+ * sub-second block finality.
+ */
+const Injective = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Injective,
+    name: 'Injective',
+    title: 'Injective Mainnet',
+    nativeCurrency: {
+        name: 'Injective',
+        symbol: 'INJ',
+        decimals: 18,
+    },
+    chainId: 1776,
+    isTestnet: false,
+    explorerUrl: 'https://injscan.com/transaction/{hash}',
+    rpcEndpoints: ['https://sentry.evm-rpc.injective.network'],
+    eurcAddress: null,
+    usdcAddress: '0xa00C59fF5a080D2b954d0c75e46E22a0c371235a',
+    usdtAddress: null,
+    cctp: {
+        domain: 29,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Injective Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Injective blockchain.
+ * Injective is a high-performance, interoperable Layer-1 blockchain built for
+ * finance, with an EVM execution layer on top of a Cosmos SDK base and
+ * sub-second block finality.
+ */
+const InjectiveTestnet = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Injective_Testnet,
+    name: 'Injective Testnet',
+    title: 'Injective Testnet',
+    nativeCurrency: {
+        name: 'Injective',
+        symbol: 'INJ',
+        decimals: 18,
+    },
+    chainId: 1439,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.explorer.injective.network/transaction/{hash}',
+    rpcEndpoints: ['https://k8s.testnet.json-rpc.injective.network'],
+    eurcAddress: null,
+    usdcAddress: '0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d',
+    usdtAddress: null,
+    cctp: {
+        domain: 29,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * Ink Mainnet chain definition
  * @remarks
@@ -5690,6 +5796,96 @@ const OptimismSepolia = defineChain({
     },
 });
 
+/**
+ * Pharos Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Pharos blockchain.
+ * Pharos is a modular, full-stack parallel Layer 1 blockchain with
+ * sub-second finality and EVM compatibility.
+ */
+const Pharos = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Pharos,
+    name: 'Pharos',
+    title: 'Pharos Mainnet',
+    nativeCurrency: {
+        name: 'Pharos',
+        symbol: 'PHAROS',
+        decimals: 18,
+    },
+    chainId: 1672,
+    isTestnet: false,
+    explorerUrl: 'https://pharos.socialscan.io/tx/{hash}',
+    rpcEndpoints: ['https://rpc.pharos.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0xC879C018dB60520F4355C26eD1a6D572cdAC1815',
+    usdtAddress: null,
+    cctp: {
+        domain: 31,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Pharos Atlantic Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Pharos blockchain.
+ * Pharos is a modular, full-stack parallel Layer 1 blockchain with
+ * sub-second finality and EVM compatibility.
+ */
+const PharosTestnet = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Pharos_Testnet,
+    name: 'Pharos Atlantic',
+    title: 'Pharos Atlantic Testnet',
+    nativeCurrency: {
+        name: 'Pharos',
+        symbol: 'PHAROS',
+        decimals: 18,
+    },
+    chainId: 688689,
+    isTestnet: true,
+    explorerUrl: 'https://atlantic.pharosscan.xyz/tx/{hash}',
+    rpcEndpoints: ['https://atlantic.dplabs-internal.com'],
+    eurcAddress: null,
+    usdcAddress: '0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B',
+    usdtAddress: null,
+    cctp: {
+        domain: 31,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * Plume Mainnet chain definition
  * @remarks
@@ -5972,7 +6168,7 @@ const Sei = defineChain({
     },
     chainId: 1329,
     isTestnet: false,
-    explorerUrl: 'https://seitrace.com/tx/{hash}?chain=pacific-1',
+    explorerUrl: 'https://seiscan.io/tx/{hash}',
     rpcEndpoints: ['https://evm-rpc.sei-apis.com'],
     eurcAddress: null,
     usdcAddress: '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392',
@@ -6030,7 +6226,7 @@ const SeiTestnet = defineChain({
     },
     chainId: 1328,
     isTestnet: true,
-    explorerUrl: 'https://seitrace.com/tx/{hash}?chain=atlantic-2',
+    explorerUrl: 'https://testnet.seiscan.io/tx/{hash}',
     rpcEndpoints: ['https://evm-rpc-testnet.sei-apis.com'],
     eurcAddress: null,
     usdcAddress: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED',
@@ -6833,6 +7029,8 @@ var Chains = {
     HederaTestnet: HederaTestnet,
     HyperEVM: HyperEVM,
     HyperEVMTestnet: HyperEVMTestnet,
+    Injective: Injective,
+    InjectiveTestnet: InjectiveTestnet,
     Ink: Ink,
     InkTestnet: InkTestnet,
     Linea: Linea,
@@ -6847,6 +7045,8 @@ var Chains = {
     NobleTestnet: NobleTestnet,
     Optimism: Optimism,
     OptimismSepolia: OptimismSepolia,
+    Pharos: Pharos,
+    PharosTestnet: PharosTestnet,
     Plume: Plume,
     PlumeTestnet: PlumeTestnet,
     PolkadotAssetHub: PolkadotAssetHub,
@@ -7452,6 +7652,44 @@ function resolveChainIdentifier(chainIdentifier) {
     throw new Error(`Invalid chain identifier type: ${typeof chainIdentifier}. Expected ChainDefinition object, Blockchain enum, or string literal.`);
 }
 
+/**
+ * Resolve a chain identifier to a plain chain-name string.
+ *
+ * Accept a string literal (`'Ethereum'`), a `ChainDefinition`-like
+ * object (`{ chain: 'Ethereum' }`), or `null`/`undefined` and return
+ * the chain name as a string. Return `undefined` when the value
+ * cannot be resolved.
+ *
+ * @remarks
+ * Unlike `resolveChainIdentifier` (which returns a full `ChainDefinition`
+ * and throws on invalid input), this helper is intentionally lenient and
+ * never throws — it is safe to call in error-handling and telemetry paths.
+ *
+ * @param value - A string, chain-definition object, or nullish value.
+ * @returns The chain name string, or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * import { resolveChainName } from '@core/chains'
+ *
+ * resolveChainName('Ethereum')              // 'Ethereum'
+ * resolveChainName({ chain: 'Ethereum' })   // 'Ethereum'
+ * resolveChainName(undefined)               // undefined
+ * ```
+ */
+function resolveChainName(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object' &&
+        'chain' in value &&
+        typeof value.chain === 'string') {
+        return value.chain;
+    }
+    return undefined;
+}
+
 /**
  * @packageDocumentation
  * @module SwapTokenUtils
@@ -9108,6 +9346,7 @@ const USDC = {
         [exports.Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
         [exports.Blockchain.Hedera]: '0.0.456858',
         [exports.Blockchain.HyperEVM]: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
+        [exports.Blockchain.Injective]: '0xa00C59fF5a080D2b954d0c75e46E22a0c371235a',
         [exports.Blockchain.Ink]: '0x2D270e6886d130D724215A266106e6832161EAEd',
         [exports.Blockchain.Linea]: '0x176211869ca2b568f2a7d4ee941e073a821ee1ff',
         [exports.Blockchain.Monad]: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
@@ -9115,6 +9354,7 @@ const USDC = {
         [exports.Blockchain.NEAR]: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
         [exports.Blockchain.Noble]: 'uusdc',
         [exports.Blockchain.Optimism]: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
+        [exports.Blockchain.Pharos]: '0xC879C018dB60520F4355C26eD1a6D572cdAC1815',
         [exports.Blockchain.Plume]: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
         [exports.Blockchain.Polkadot_Asset_Hub]: '1337',
         [exports.Blockchain.Polygon]: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
@@ -9139,6 +9379,7 @@ const USDC = {
         [exports.Blockchain.Ethereum_Sepolia]: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
         [exports.Blockchain.Hedera_Testnet]: '0.0.429274',
         [exports.Blockchain.HyperEVM_Testnet]: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
+        [exports.Blockchain.Injective_Testnet]: '0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d',
         [exports.Blockchain.Ink_Testnet]: '0xFabab97dCE620294D2B0b0e46C68964e326300Ac',
         [exports.Blockchain.Linea_Sepolia]: '0xfece4462d57bd51a6a552365a011b95f0e16d9b7',
         [exports.Blockchain.Monad_Testnet]: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
@@ -9146,6 +9387,7 @@ const USDC = {
         [exports.Blockchain.NEAR_Testnet]: '3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af',
         [exports.Blockchain.Noble_Testnet]: 'uusdc',
         [exports.Blockchain.Optimism_Sepolia]: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
+        [exports.Blockchain.Pharos_Testnet]: '0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B',
         [exports.Blockchain.Plume_Testnet]: '0xcB5f30e335672893c7eb944B374c196392C19D18',
         [exports.Blockchain.Polkadot_Westmint]: '31337',
         [exports.Blockchain.Polygon_Amoy_Testnet]: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
@@ -9426,6 +9668,32 @@ const MON = {
     },
 };
 
+/**
+ * cirBTC (Circle Bitcoin) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in cirBTC definition for the TokenRegistry. Currently deployed
+ * on Arc Testnet.
+ *
+ * @example
+ * ```typescript
+ * import { CIRBTC } from '@core/tokens'
+ * import { Blockchain } from '@core/chains'
+ *
+ * console.log(CIRBTC.symbol)   // 'cirBTC'
+ * console.log(CIRBTC.decimals) // 8
+ * console.log(CIRBTC.locators[Blockchain.Arc_Testnet])
+ * // '0xf0C4a4CE82A5746AbAAd9425360Ab04fbBA432BF'
+ * ```
+ */
+const CIRBTC = {
+    symbol: 'cirBTC',
+    decimals: 8,
+    locators: {
+        [exports.Blockchain.Arc_Testnet]: '0xf0C4a4CE82A5746AbAAd9425360Ab04fbBA432BF',
+    },
+};
+
 // Re-export for consumers
 /**
  * All default token definitions.
@@ -9434,7 +9702,7 @@ const MON = {
  * 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.
+ * WPOL, ETH, POL, PLUME, MON, and cirBTC.
  *
  * @example
  * ```typescript
@@ -9465,6 +9733,7 @@ const DEFAULT_TOKENS = [
     POL,
     PLUME,
     MON,
+    CIRBTC,
 ];
 /**
  * Uppercased token symbols approved for swap fee collection.
@@ -10212,8 +10481,325 @@ async function retryAsync(fn, options) {
     throw new Error('retryAsync: unreachable');
 }
 
+/**
+ * Default telemetry endpoint.
+ *
+ * Override via the `STABLECOIN_KITS_TELEMETRY_URL` environment variable
+ * (e.g. for staging or local development).
+ *
+ * @internal
+ */
+const DEFAULT_LOGS_URL = 'https://api.circle.com/v1/stablecoinKits/logs';
+/**
+ * Resolve the telemetry endpoint URL.
+ *
+ * @internal
+ */
+function getLogsUrl() {
+    if (isNodeEnvironment() &&
+        typeof process.env['STABLECOIN_KITS_TELEMETRY_URL'] === 'string' &&
+        process.env['STABLECOIN_KITS_TELEMETRY_URL'].length > 0) {
+        return process.env['STABLECOIN_KITS_TELEMETRY_URL'];
+    }
+    return DEFAULT_LOGS_URL;
+}
+/**
+ * Send a telemetry event to the proxy service.
+ *
+ * @remarks
+ * Fire-and-forget: the returned promise is intentionally not awaited
+ * by the caller. A fetch failure (network error, non-2xx, timeout)
+ * is silently swallowed so telemetry never blocks or fails user
+ * operations.
+ *
+ * @param payload - The structured log payload matching the server schema.
+ *
+ * @example
+ * ```typescript
+ * import { emitAnalyticsLog } from '@core/utils'
+ *
+ * // Fire-and-forget — do not await
+ * void emitAnalyticsLog(payload)
+ * ```
+ */
+async function emitAnalyticsLog(payload) {
+    try {
+        const isNode = isNodeEnvironment();
+        const userAgent = getUserAgent();
+        await fetch(getLogsUrl(), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                // Browser restricts setting User-Agent; use X-User-Agent instead.
+                ...(isNode
+                    ? { 'User-Agent': userAgent }
+                    : { 'X-User-Agent': userAgent }),
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(5_000),
+        });
+    }
+    catch {
+        // Silently swallow — telemetry must never break user operations.
+    }
+}
+
+/**
+ * Build the `clientContext` object for telemetry payloads.
+ *
+ * @remarks
+ * Use the exported `getRuntime()` and `isNodeEnvironment()` from
+ * `@core/utils` to detect the runtime environment. The returned
+ * string is parsed into the structured `ClientContext` fields
+ * expected by the server schema.
+ *
+ * @returns A {@link ClientContext} with platform, OS, and runtime name
+ *   populated from the current environment.
+ *
+ * @example
+ * ```typescript
+ * import { buildClientContext } from '@core/utils'
+ *
+ * const ctx = buildClientContext()
+ * // Node: { platform: 'node', os: 'darwin', runtimeName: null }
+ * // Browser: { platform: 'browser', os: null, runtimeName: 'chrome' }
+ * ```
+ */
+function buildClientContext() {
+    const runtime = getRuntime();
+    if (runtime.startsWith('browser/')) {
+        return {
+            platform: 'browser',
+            os: null,
+            runtimeName: runtime.slice('browser/'.length).toLowerCase(),
+        };
+    }
+    if (runtime.startsWith('node/')) {
+        return {
+            platform: 'node',
+            os: isNodeEnvironment() ? process.platform : null,
+            runtimeName: null,
+        };
+    }
+    return {
+        platform: 'node',
+        os: null,
+        runtimeName: null,
+    };
+}
+
+/**
+ * Extract structured error details from an unknown error value.
+ *
+ * @remarks
+ * Handle three cases:
+ * - `KitError` — extract `code` and `name`.
+ * - `Error` — extract `name`.
+ * - Anything else — return empty details.
+ *
+ * Only structured, bounded fields (`errorCode`, `errorType`) are
+ * included. Free-text fields (`message`, `stack`) are intentionally
+ * omitted to avoid leaking secrets or PII through vendor telemetry.
+ *
+ * @param error - The thrown value to extract details from.
+ * @returns A {@link ErrorDetails} object suitable for telemetry payloads.
+ *
+ * @example
+ * ```typescript
+ * import { extractErrorDetails } from '@core/utils'
+ *
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   const details = extractErrorDetails(error)
+ *   // { errorCode: '1001', errorType: 'INPUT_NETWORK_MISMATCH' }
+ * }
+ * ```
+ */
+function extractErrorDetails(error) {
+    if (error instanceof KitError) {
+        return {
+            errorCode: String(error.code),
+            errorType: error.name,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            errorType: error.name,
+        };
+    }
+    return {};
+}
+
+/**
+ * Register event handlers on an action dispatcher that emit analytics
+ * telemetry for the configured events.
+ *
+ * @remarks
+ * Subscribe to each action name in `actionEventMap`, call `mapEventToPayload`
+ * for each event, and fire-and-forget `emitAnalyticsLog` if a non-null
+ * payload is returned. All errors are silently swallowed so telemetry
+ * never blocks or fails user operations.
+ *
+ * @param dispatcher - The `Actionable` instance from the kit.
+ * @param sdkName - SDK package name (e.g. `'unified-balance-kit'`).
+ * @param sdkVersion - SDK version string (e.g. `'1.0.0'`).
+ * @param actionEventMap - Map of action names to subscribe to.
+ * @param mapEventToPayload - Function that maps an action name and payload
+ *   to a {@link ClientLogPayload}, or `null` to skip logging.
+ *
+ * @example
+ * ```typescript
+ * import { registerTelemetryHandler } from '@core/utils'
+ *
+ * registerTelemetryHandler(
+ *   dispatcher,
+ *   'unified-balance-kit',
+ *   '1.0.0',
+ *   VERB_EVENT_MAP,
+ *   mapSucceededEventToLog,
+ * )
+ * ```
+ */
+function registerTelemetryHandler$1(dispatcher, sdkName, sdkVersion, actionEventMap, mapEventToPayload) {
+    for (const actionName of Object.keys(actionEventMap)) {
+        dispatcher.on(actionName, (payload) => {
+            try {
+                const log = mapEventToPayload(actionName, payload, sdkName, sdkVersion);
+                if (log) {
+                    // Fire-and-forget — intentionally not awaited.
+                    void emitAnalyticsLog(log);
+                }
+            }
+            catch {
+                // Silently swallow — telemetry must never break user operations.
+            }
+        });
+    }
+}
+
+/**
+ * Strip the `@circle-fin/` scope from a kit package name to produce the
+ * short SDK name used in telemetry payloads.
+ *
+ * @param pkgName - The full npm package name (e.g. `@circle-fin/bridge-kit`).
+ * @returns The unscoped kit name (e.g. `bridge-kit`).
+ *
+ * @example
+ * ```typescript
+ * import pkg from '../../package.json'
+ * import { resolveKitSdkName } from '@core/utils'
+ *
+ * const SDK_NAME = resolveKitSdkName(pkg.name) // 'bridge-kit'
+ * ```
+ */
+function resolveKitSdkName(pkgName) {
+    return pkgName.replace('@circle-fin/', '');
+}
+
+/**
+ * Build a telemetry payload from common fields.
+ *
+ * @internal
+ */
+function buildPayload$1(config, eventType, errorDetails, context) {
+    return {
+        sdkName: config.sdkName,
+        sdkVersion: config.sdkVersion,
+        eventType,
+        timestamp: new Date().toISOString(),
+        errorDetails,
+        clientContext: buildClientContext(),
+        ...(context?.sourceChain != null && {
+            sourceChain: context.sourceChain,
+        }),
+        ...(context?.destinationChain != null && {
+            destinationChain: context.destinationChain,
+        }),
+        ...(context?.tokenIn != null && { tokenIn: context.tokenIn }),
+        ...(context?.tokenOut != null && { tokenOut: context.tokenOut }),
+    };
+}
+/**
+ * Wrap an async operation with error telemetry.
+ *
+ * Execute `fn` and, if it throws, emit an error telemetry payload
+ * before re-throwing. No-ops when `config.disabled` is `true`.
+ *
+ * @param fn - The async operation to execute.
+ * @param eventType - The telemetry event type for this operation.
+ * @param config - Per-kit SDK identity and disabled flag.
+ * @param context - Optional chain/token context.
+ * @returns The result of the operation.
+ * @throws Re-throws any error after emitting telemetry.
+ *
+ * @example
+ * ```typescript
+ * import { withErrorTelemetry } from '@core/utils'
+ *
+ * const result = await withErrorTelemetry(
+ *   () => provider.bridge(params),
+ *   'bridge_bridge',
+ *   { sdkName: 'bridge-kit', sdkVersion: '1.0.0', disabled: false },
+ *   { sourceChain: 'Ethereum', destinationChain: 'Base', tokenIn: 'USDC' },
+ * )
+ * ```
+ */
+async function withErrorTelemetry(fn, eventType, config, context) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (!config.disabled) {
+            void emitAnalyticsLog(buildPayload$1(config, eventType, extractErrorDetails(error), context));
+        }
+        throw error;
+    }
+}
+/**
+ * Emit error telemetry for a result-reported step error.
+ *
+ * Handle the case where a provider reports a step failure inside a
+ * result object (e.g. `BridgeResult.state === 'error'`) rather than
+ * throwing. The caller extracts the failed step as a simple
+ * {@link FailedStepInfo} — this function handles sanitization,
+ * step-to-event mapping, and emission.
+ *
+ * No-ops when `config.disabled` is `true`.
+ *
+ * @param failedStep - The failed step info, or undefined if none found.
+ * @param stepEventMap - Ordered mapping from step names to event types.
+ * @param fallbackEventType - Event type when step is not in the map.
+ * @param config - Per-kit SDK identity and disabled flag.
+ * @param context - Optional chain/token context.
+ *
+ * @example
+ * ```typescript
+ * import { emitResultStepErrorTelemetry } from '@core/utils'
+ *
+ * const failedStep = result.steps.find((s) => s.state === 'error')
+ * emitResultStepErrorTelemetry(
+ *   failedStep,
+ *   BRIDGE_STEP_EVENT_MAP,
+ *   'bridge_bridge',
+ *   { sdkName: 'bridge-kit', sdkVersion: '1.0.0', disabled: false },
+ *   { sourceChain: 'Ethereum', tokenIn: 'USDC' },
+ * )
+ * ```
+ */
+function emitResultStepErrorTelemetry(failedStep, stepEventMap, fallbackEventType, config, context) {
+    if (config.disabled) {
+        return;
+    }
+    const stepEntry = stepEventMap.find(([name]) => name === failedStep?.name);
+    const errorDetails = {
+        ...(failedStep?.name != null && { errorType: failedStep.name }),
+    };
+    void emitAnalyticsLog(buildPayload$1(config, stepEntry?.[1] ?? fallbackEventType, errorDetails, context));
+}
+
 var name$2 = "@circle-fin/bridge-kit";
-var version$3 = "1.8.3";
+var version$3 = "1.10.0";
 var pkg$3 = {
 	name: name$2,
 	version: version$3};
@@ -13178,18 +13764,16 @@ const buildIrisUrl = (sourceDomainId, transactionHash, isTestnet) => {
 };
 /**
  * Fetches attestation data from the IRIS API with retry and timeout handling.
- * Since fetching starts after a confirmed burn transaction, we attempt up to 10 retries.
- * Implements a conservative delay between requests to respect the API rate
- * limit of 35 requests per second. To avoid rate limiting when multiple processes are
- * running concurrently, we enforce a 200ms delay between retries.
  *
- * Each HTTP request is given a maximum of 2 seconds before it is aborted.
- * We retry up to 10 times, waiting 200ms between attempts.
+ * Polls the IRIS API until a complete attestation is available. The default
+ * window is sized for slow source chains where finality may take many
+ * confirmations.
  *
- * The total maximum time this function might take (worst case) is:
- * - Per‐attempt timeout: 2 000 ms
- * - Retry delays: 9 × 200 ms = 1 800 ms
- * - Total max time: 2 000 ms + 1 800 ms = 3 800 ms
+ * Defaults (see `DEFAULT_CONFIG`):
+ * - Per-attempt timeout: 2 000 ms (each HTTP request aborts after 2 s)
+ * - Retry delay: 2 000 ms between attempts
+ * - Max retries: 600 (30 × 20)
+ * - Total worst-case polling window: 600 × (2 000 ms + 2 000 ms) ≈ 40 minutes
  *
  * @param sourceDomainId - The CCTP domain ID.
  * @param transactionHash - The transaction hash to fetch attestation for.
@@ -14344,11 +14928,18 @@ async function executePreparedChainRequest({ name, request, adapter, chain, conf
         step.explorerUrl = buildExplorerUrl(chain, txHash);
         if (outcome.errorMessage) {
             step.errorMessage = outcome.errorMessage;
+            // Transaction was mined but reverted on-chain.
+            step.errorCategory = 'chain_revert';
         }
     }
     catch (err) {
         step.state = 'error';
         step.error = err;
+        // Sequential path does not yet attempt fine-grained classification of
+        // pre-submission errors (user_rejected, capability errors, etc.). Mark
+        // as `unknown` so consumers can at least detect the category is
+        // populated uniformly across batched and sequential flows.
+        step.errorCategory = 'unknown';
         // Optionally parse for common blockchain error formats
         if (err instanceof Error) {
             step.errorMessage = err.message;
@@ -15014,16 +15605,70 @@ async function executeBatchedApproveAndBurn(params, provider) {
     const batchResult = await adapter.batchExecute([approveCallData, burnCallData], chain);
     const approveReceipt = batchResult.receipts[0];
     const burnReceipt = batchResult.receipts[1];
-    const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain);
-    const burnStep = await buildBatchedStep('burn', burnReceipt, batchResult.batchId, adapter, chain);
+    const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain, batchResult.statusCode, batchResult.error);
+    const burnStep = await buildBatchedStep('burn', burnReceipt, batchResult.batchId, adapter, chain, batchResult.statusCode, batchResult.error);
     if (burnStep.state !== 'error' && !burnStep.txHash) {
         burnStep.state = 'error';
         burnStep.errorMessage =
             'Batched burn step completed but no transaction hash was returned.';
+        burnStep.errorCategory = 'unknown';
     }
     const context = { burnTxHash: burnStep.txHash ?? '' };
     return { approveStep, burnStep, context };
 }
+/**
+ * Derive a {@link BridgeStepErrorCategory} for a missing receipt.
+ *
+ * Combines the EIP-5792 `statusCode` (when present) with the underlying
+ * polling error (when set) to produce the most specific category available.
+ * Falls back to `'unknown'` when neither signal is conclusive.
+ *
+ * @param statusCode - The terminal `statusCode` from `wallet_getCallsStatus`, if any.
+ * @param batchError - The polling error from `batchExecute`, if any.
+ * @returns The derived error category for a missing-receipt step.
+ *
+ * @internal
+ */
+function categorizeMissingReceipt(statusCode, batchError) {
+    if (statusCode === 400)
+        return 'failed_offchain';
+    if (statusCode === 500)
+        return 'reverted_onchain';
+    if (statusCode === 600)
+        return 'partial_reverted';
+    if (batchError instanceof KitError &&
+        batchError.code === NetworkError.TIMEOUT.code) {
+        return 'polling_timeout';
+    }
+    return 'unknown';
+}
+/**
+ * Derive a {@link BridgeStepErrorCategory} for a receipt that was returned
+ * but whose per-call `status` is not `'success'`.
+ *
+ * A numeric EIP-5792 `statusCode` of 500 or 600 tells us the whole batch
+ * reverted on-chain (completely or partially); otherwise the receipt
+ * itself signalled a revert without a distinguishing code, so classify
+ * as a plain on-chain revert.
+ *
+ * @param statusCode - The terminal `statusCode` from `wallet_getCallsStatus`, if any.
+ * @returns The derived error category for a failed-receipt step.
+ *
+ * @internal
+ */
+function categorizeFailedReceipt(statusCode) {
+    // Mirror categorizeMissingReceipt: if the wallet's terminal status is
+    // 400 ("batch not included onchain"), that judgement is authoritative
+    // even when a non-success receipt is attached. Without this, a wrapped
+    // 400 receipt would fall through to `chain_revert` and mislead UX.
+    if (statusCode === 400)
+        return 'failed_offchain';
+    if (statusCode === 600)
+        return 'partial_reverted';
+    if (statusCode === 500)
+        return 'reverted_onchain';
+    return 'chain_revert';
+}
 /**
  * Build a {@link BridgeStep} from a single receipt within a batch.
  *
@@ -15038,11 +15683,17 @@ async function executeBatchedApproveAndBurn(params, provider) {
  * @param batchId - Wallet-assigned batch identifier.
  * @param adapter - The batch-capable adapter (used for confirmation).
  * @param chain - The EVM chain the batch was executed on.
+ * @param statusCode - Optional EIP-5792 `statusCode` for the batch.
+ *   Used to classify the step's error category when the receipt is
+ *   missing or failed.
+ * @param batchError - Optional polling error from `batchExecute`.
+ *   Preserved on the step so callers can inspect underlying timeouts
+ *   or RPC failures.
  * @returns A fully-populated bridge step with state, tx hash and explorer URL.
  *
  * @internal
  */
-async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
+async function buildBatchedStep(name, receipt, batchId, adapter, chain, statusCode, batchError) {
     const step = {
         name,
         state: 'pending',
@@ -15052,6 +15703,10 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
     if (!receipt) {
         step.state = 'error';
         step.errorMessage = `No receipt returned for ${name} in batch ${batchId}.`;
+        step.errorCategory = categorizeMissingReceipt(statusCode, batchError);
+        if (batchError !== undefined) {
+            step.error = batchError;
+        }
         return step;
     }
     step.txHash = receipt.txHash;
@@ -15061,11 +15716,13 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
     if (receipt.status !== 'success') {
         step.state = 'error';
         step.errorMessage = `${name} call failed within batch ${batchId}.`;
+        step.errorCategory = categorizeFailedReceipt(statusCode);
         return step;
     }
     if (!receipt.txHash) {
         step.state = 'error';
         step.errorMessage = `${name} succeeded in batch but returned an empty transaction hash.`;
+        step.errorCategory = 'unknown';
         return step;
     }
     try {
@@ -15080,6 +15737,7 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
         step.data = transaction;
         if (outcome.errorMessage) {
             step.errorMessage = outcome.errorMessage;
+            step.errorCategory = 'chain_revert';
         }
     }
     catch (err) {
@@ -15087,11 +15745,12 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
         step.error = err;
         step.errorMessage =
             err instanceof Error ? err.message : 'Unknown error during confirmation.';
+        step.errorCategory = 'unknown';
     }
     return step;
 }
 
-var version$2 = "1.6.3";
+var version$2 = "1.8.0";
 var pkg$2 = {
 	version: version$2};
 
@@ -15167,6 +15826,7 @@ async function executeBatchedPath(params, provider, result, invocation) {
             errorMessage: error_ instanceof Error
                 ? error_.message
                 : 'Batched approve + burn failed.',
+            errorCategory: classifyPreSubmissionError(error_),
         });
         return undefined;
     }
@@ -15181,6 +15841,89 @@ function ensureStepErrorMessage(name, step) {
         step.errorMessage = `${name} step failed: ${getErrorMessage(step.error)}`;
     }
 }
+/**
+ * Coerce a raw JSON-RPC `code` to a number.
+ *
+ * Some wallet SDKs serialize the JSON-RPC `code` as a string ("4001")
+ * after round-tripping through JSON; accept both shapes so strict `===`
+ * comparisons downstream still classify 5720/5730/5740 correctly — those
+ * codes have no message-pattern fallback.
+ *
+ * @param rawCode - The raw `code` extracted from the error object.
+ * @returns The numeric code, or `undefined` if the value cannot be parsed.
+ *
+ * @internal
+ */
+function coerceRpcCode(rawCode) {
+    if (typeof rawCode === 'number') {
+        return rawCode;
+    }
+    if (typeof rawCode === 'string') {
+        return Number.parseInt(rawCode, 10);
+    }
+    return undefined;
+}
+/**
+ * Classify a pre-submission error thrown during `wallet_sendCalls`.
+ *
+ * Inspect the error's JSON-RPC `code` (falling back to message pattern
+ * matching for wrapper errors like viem's `ChainMismatchError`) and map
+ * it to a {@link BridgeStepErrorCategory}. This lets downstream consumers
+ * distinguish user rejections, wallet capability gaps, and unknown
+ * failures without parsing error messages.
+ *
+ * @remarks
+ * Does NOT alter control flow — the SDK continues to surface a
+ * `state: 'error'` step. Auto-fallback to sequential execution is
+ * intentionally out of scope for this helper.
+ *
+ * @param err - The error thrown by `wallet_sendCalls`.
+ * @returns The derived error category, or `'unknown'` if no match.
+ *
+ * @internal
+ */
+function classifyPreSubmissionError(err) {
+    // Cross-realm-safe duck typing: `instanceof Error` returns false for
+    // errors thrown in a different JavaScript realm (e.g., a wallet
+    // provider running inside an iframe, which is common with WalletConnect
+    // and the Coinbase Wallet SDK).
+    if (typeof err !== 'object' || err === null || !('message' in err)) {
+        return 'unknown';
+    }
+    const code = coerceRpcCode(err.code);
+    const message = String(err.message);
+    // Numeric JSON-RPC codes are authoritative; check them before falling
+    // back to message-pattern matching. Order matters: an error carrying
+    // `code === 5750` with a message like "user rejected the upgrade"
+    // is a capability problem, not a plain user rejection.
+    if (code === 4001) {
+        return 'user_rejected';
+    }
+    if (code === 5700 || code === 5710 || code === 5750) {
+        return 'atomic_unsupported';
+    }
+    if (code === 5720) {
+        return 'duplicate_batch_id';
+    }
+    if (code === 5730) {
+        return 'unknown_bundle';
+    }
+    if (code === 5740) {
+        return 'batch_too_large';
+    }
+    // Fall back to message patterns when no specific code is available —
+    // viem (and other wrapper layers) sometimes strip the numeric code
+    // while preserving the original wallet message in `Details:`.
+    if (/EIP-7702 not supported/i.test(message) ||
+        /does not support the requested chain/i.test(message) ||
+        /rejected the upgrade/i.test(message)) {
+        return 'atomic_unsupported';
+    }
+    if (/user rejected/i.test(message)) {
+        return 'user_rejected';
+    }
+    return 'unknown';
+}
 /**
  * Execute a cross-chain USDC bridge using the CCTP v2 protocol.
  *
@@ -16673,6 +17416,35 @@ const formatBridgeResult = (result, formatDirection) => {
     };
 };
 
+/**
+ * Telemetry event type identifiers for bridge-kit operations.
+ *
+ * @internal
+ */
+const BRIDGE_EVENT_TYPES = {
+    BRIDGE: 'bridge_bridge',
+    RETRY: 'bridge_retry',
+    ESTIMATE: 'bridge_estimate',
+};
+/**
+ * Ordered mapping from provider step event names to telemetry event types.
+ *
+ * @remarks
+ * The order matches the CCTP v2 bridge execution sequence. During
+ * `bridge()`, completed step events are counted so the failing step
+ * can be identified by its index.
+ *
+ * @internal
+ */
+const BRIDGE_STEP_EVENT_MAP = [
+    ['approve', 'bridge_approve'],
+    ['burn', 'bridge_burn'],
+    ['fetchAttestation', 'bridge_fetch_attestation'],
+    ['mint', 'bridge_mint'],
+];
+
+/** SDK name used in telemetry payloads. */
+const SDK_NAME$2 = resolveKitSdkName(pkg$3.name);
 /**
  * BridgeKit caller component for retry and estimate operations.
  */
@@ -16756,6 +17528,10 @@ class BridgeKit {
      * A custom fee policy for the kit.
      */
     customFeePolicy;
+    /** Whether error telemetry is disabled. */
+    disableErrorReporting;
+    /** Per-kit telemetry identity for shared helpers. */
+    telemetryConfig;
     /**
      * Create a new BridgeKit instance.
      *
@@ -16773,6 +17549,12 @@ class BridgeKit {
         const defaultProviders = getDefaultProviders$2();
         this.providers = [...defaultProviders, ...(config.providers ?? [])];
         this.actionDispatcher = new Actionable();
+        this.disableErrorReporting = config.disableErrorReporting === true;
+        this.telemetryConfig = {
+            sdkName: SDK_NAME$2,
+            sdkVersion: pkg$3.version,
+            disabled: this.disableErrorReporting,
+        };
         for (const provider of this.providers) {
             provider.registerDispatcher(this.actionDispatcher);
         }
@@ -16846,19 +17628,36 @@ class BridgeKit {
      * ```
      */
     async bridge(params) {
-        // First validate the parameters
-        assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
-        // Then resolve chain definitions (includes adapter chain support validation)
-        const resolvedParams = await resolveBridgeParams(params);
-        // Validate network compatibility
-        this.validateNetworkCompatibility(resolvedParams);
-        // Merge the custom fee config into the resolved params
-        const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
-        // Find a provider that supports this route
-        const provider = this.findProviderForRoute(finalResolvedParams);
-        // Execute the transfer using the provider
-        // Format the bridge result into human-readable string values for the user
-        return formatBridgeResult(await provider.bridge(finalResolvedParams), 'to-human-readable');
+        return withErrorTelemetry(async () => {
+            // First validate the parameters
+            assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
+            // Then resolve chain definitions (includes adapter chain support validation)
+            const resolvedParams = await resolveBridgeParams(params);
+            // Validate network compatibility
+            this.validateNetworkCompatibility(resolvedParams);
+            // Merge the custom fee config into the resolved params
+            const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
+            // Find a provider that supports this route
+            const provider = this.findProviderForRoute(finalResolvedParams);
+            // Execute the transfer using the provider
+            // Format the bridge result into human-readable string values for the user
+            const result = formatBridgeResult(await provider.bridge(finalResolvedParams), 'to-human-readable');
+            // Emit error telemetry when the provider returns an error state
+            // (provider records step failures in the result instead of throwing).
+            if (result.state === 'error') {
+                const failedStep = result.steps.find((s) => s.state === 'error');
+                emitResultStepErrorTelemetry(failedStep, BRIDGE_STEP_EVENT_MAP, BRIDGE_EVENT_TYPES.BRIDGE, this.telemetryConfig, {
+                    sourceChain: resolveChainName(params.from.chain),
+                    destinationChain: resolveChainName(params.to.chain),
+                    tokenIn: params.token,
+                });
+            }
+            return result;
+        }, BRIDGE_EVENT_TYPES.BRIDGE, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from.chain),
+            destinationChain: resolveChainName(params.to.chain),
+            tokenIn: params.token,
+        });
     }
     /**
      * Retry a failed or incomplete cross-chain USDC bridge operation.
@@ -16930,17 +17729,33 @@ class BridgeKit {
      * ```
      */
     async retry(result, context, invocationMeta) {
-        const provider = this.providers.find((p) => p.name === result.provider);
-        if (!provider) {
-            throw new Error(`Provider ${result.provider} not found`);
-        }
-        // Merge BridgeKit caller into invocation metadata for retry operation
-        const mergedMeta = mergeRetryInvocationMeta(invocationMeta);
-        // Format the bridge result into bigint string values for internal use
-        const formattedBridgeResultInternal = formatBridgeResult(result, 'to-internal');
-        // Execute the retry using the provider
-        // Format the bridge result into human-readable string values for the user
-        return formatBridgeResult(await provider.retry(formattedBridgeResultInternal, context, mergedMeta), 'to-human-readable');
+        return withErrorTelemetry(async () => {
+            const provider = this.providers.find((p) => p.name === result.provider);
+            if (!provider) {
+                throw new Error(`Provider ${result.provider} not found`);
+            }
+            // Merge BridgeKit caller into invocation metadata for retry operation
+            const mergedMeta = mergeRetryInvocationMeta(invocationMeta);
+            // Format the bridge result into bigint string values for internal use
+            const formattedBridgeResultInternal = formatBridgeResult(result, 'to-internal');
+            // Execute the retry using the provider
+            // Format the bridge result into human-readable string values for the user
+            const retryResult = formatBridgeResult(await provider.retry(formattedBridgeResultInternal, context, mergedMeta), 'to-human-readable');
+            // Emit error telemetry when the provider returns an error state.
+            if (retryResult.state === 'error') {
+                const failedStep = retryResult.steps.find((s) => s.state === 'error');
+                emitResultStepErrorTelemetry(failedStep, BRIDGE_STEP_EVENT_MAP, BRIDGE_EVENT_TYPES.RETRY, this.telemetryConfig, {
+                    sourceChain: result.source.chain.chain,
+                    destinationChain: result.destination.chain.chain,
+                    tokenIn: result.token,
+                });
+            }
+            return retryResult;
+        }, BRIDGE_EVENT_TYPES.RETRY, this.telemetryConfig, {
+            sourceChain: result.source.chain.chain,
+            destinationChain: result.destination.chain.chain,
+            tokenIn: result.token,
+        });
     }
     /**
      * Estimate the cost and fees for a cross-chain USDC bridge operation.
@@ -16979,18 +17794,24 @@ class BridgeKit {
      * ```
      */
     async estimate(params) {
-        // First validate the parameters
-        assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
-        // Then resolve chain definitions (includes adapter chain support validation)
-        const resolvedParams = await resolveBridgeParams(params);
-        // Validate network compatibility
-        this.validateNetworkCompatibility(resolvedParams);
-        // Merge the custom fee config into the resolved params
-        const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
-        // Find a provider that supports this route
-        const provider = this.findProviderForRoute(finalResolvedParams);
-        // Estimate the transfer using the provider and format amounts to human-readable strings
-        return formatBridgeResult(await provider.estimate(finalResolvedParams), 'to-human-readable');
+        return withErrorTelemetry(async () => {
+            // First validate the parameters
+            assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
+            // Then resolve chain definitions (includes adapter chain support validation)
+            const resolvedParams = await resolveBridgeParams(params);
+            // Validate network compatibility
+            this.validateNetworkCompatibility(resolvedParams);
+            // Merge the custom fee config into the resolved params
+            const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
+            // Find a provider that supports this route
+            const provider = this.findProviderForRoute(finalResolvedParams);
+            // Estimate the transfer using the provider and format amounts to human-readable strings
+            return formatBridgeResult(await provider.estimate(finalResolvedParams), 'to-human-readable');
+        }, BRIDGE_EVENT_TYPES.ESTIMATE, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from.chain),
+            destinationChain: resolveChainName(params.to.chain),
+            tokenIn: params.token,
+        });
     }
     /**
      * Get all chains supported by any provider in the kit, with optional filtering.
@@ -17307,7 +18128,11 @@ const createBridgeKit = (context) => {
     const getFee = context.getFee?.bind(context);
     const getFeeRecipient = context.getFeeRecipient?.bind(context);
     const hasBoth = typeof getFee === 'function' && typeof getFeeRecipient === 'function';
-    const kit = new BridgeKit();
+    const kit = new BridgeKit({
+        ...(context.disableErrorReporting != null && {
+            disableErrorReporting: context.disableErrorReporting,
+        }),
+    });
     if (hasBoth) {
         kit.setCustomFeePolicy({
             calculateFee: async (params) => {
@@ -17324,7 +18149,7 @@ const createBridgeKit = (context) => {
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.1.0";
+var version$1 = "1.2.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -27785,6 +28610,18 @@ function createSwapKitContext(config = {}) {
     return context;
 }
 
+/**
+ * Telemetry event type identifiers for swap-kit operations.
+ *
+ * @internal
+ */
+const SWAP_EVENT_TYPES = {
+    SWAP: 'swap_swap',
+    ESTIMATE: 'swap_estimate',
+};
+
+/** SDK name used in telemetry payloads. */
+const SDK_NAME$1 = resolveKitSdkName(pkg$1.name);
 /**
  * A high-level class-based interface for single-chain token swap operations.
  *
@@ -27856,6 +28693,10 @@ function createSwapKitContext(config = {}) {
  */
 class SwapKit {
     context;
+    /** Whether error telemetry is disabled. */
+    disableErrorReporting;
+    /** Per-kit telemetry identity for shared helpers. */
+    telemetryConfig;
     /**
      * Create a new SwapKit instance.
      *
@@ -27904,6 +28745,12 @@ class SwapKit {
      */
     constructor(config = {}) {
         this.context = createSwapKitContext(config);
+        this.disableErrorReporting = config.disableErrorReporting === true;
+        this.telemetryConfig = {
+            sdkName: SDK_NAME$1,
+            sdkVersion: pkg$1.version,
+            disabled: this.disableErrorReporting,
+        };
     }
     /**
      * Estimate the output amount and fees for a swap operation.
@@ -27945,7 +28792,11 @@ class SwapKit {
      * ```
      */
     async estimate(params) {
-        return estimate(this.context, params);
+        return withErrorTelemetry(async () => estimate(this.context, params), SWAP_EVENT_TYPES.ESTIMATE, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from.chain),
+            tokenIn: params.tokenIn,
+            tokenOut: params.tokenOut,
+        });
     }
     /**
      * Execute a token swap operation on a single chain.
@@ -28001,7 +28852,11 @@ class SwapKit {
      * ```
      */
     async swap(params) {
-        return swap$1(this.context, params);
+        return withErrorTelemetry(async () => swap$1(this.context, params), SWAP_EVENT_TYPES.SWAP, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from.chain),
+            tokenIn: params.tokenIn,
+            tokenOut: params.tokenOut,
+        });
     }
     /**
      * Get all chains supported by the configured swap providers.
@@ -28194,7 +29049,11 @@ const createSwapKit = (context) => {
     const getFee = context.getFee?.bind(context);
     const getFeeRecipient = context.getFeeRecipient?.bind(context);
     const hasBoth = typeof getFee === 'function' && typeof getFeeRecipient === 'function';
-    const kit = new SwapKit();
+    const kit = new SwapKit({
+        ...(context.disableErrorReporting != null && {
+            disableErrorReporting: context.disableErrorReporting,
+        }),
+    });
     if (hasBoth) {
         kit.setCustomFeePolicy({
             computeFee: async (params) => {
@@ -28698,7 +29557,7 @@ const prepareSend = async (params) => {
     const fromContext = params.from;
     const fromAdapter = fromContext.adapter;
     const fromChain = resolveChainIdentifier(fromContext.chain);
-    const fromAddress = await fromAdapter.getAddress(fromChain);
+    const fromAddress = fromContext.address ?? (await fromAdapter.getAddress(fromChain));
     // resolve input parameters
     const token = params.token ?? 'USDC';
     // Validate token and determine if it's an alias or custom address
@@ -29143,121 +30002,11 @@ const getSupportedChains$2 = (context, operationType, unifiedBalance) => {
 };
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.0.1";
+var version = "1.1.0";
 var pkg = {
 	name: name,
 	version: version};
 
-/**
- * Default telemetry endpoint.
- *
- * Override via the `STABLECOIN_KITS_TELEMETRY_URL` environment variable
- * (e.g. for staging or local development).
- *
- * @internal
- */
-const DEFAULT_LOGS_URL = 'https://api.circle.com/v1/stablecoinKits/logs';
-/**
- * Resolve the telemetry endpoint URL.
- *
- * @internal
- */
-function getLogsUrl() {
-    if (isNodeEnvironment() &&
-        typeof process.env['STABLECOIN_KITS_TELEMETRY_URL'] === 'string' &&
-        process.env['STABLECOIN_KITS_TELEMETRY_URL'].length > 0) {
-        return process.env['STABLECOIN_KITS_TELEMETRY_URL'];
-    }
-    return DEFAULT_LOGS_URL;
-}
-/**
- * Send a telemetry event to the proxy service.
- *
- * @remarks
- * Fire-and-forget: the returned promise is intentionally not awaited
- * by the caller. A fetch failure (network error, non-2xx, timeout)
- * is silently swallowed so telemetry never blocks or fails user
- * operations.
- *
- * @param payload - The structured log payload matching the server schema.
- *
- * @example
- * ```typescript
- * import { emitAnalyticsLog } from './emitLog'
- *
- * // Fire-and-forget — do not await
- * emitAnalyticsLog(payload).catch(() => {})
- * ```
- *
- * @internal
- */
-async function emitAnalyticsLog(payload) {
-    try {
-        const isNode = isNodeEnvironment();
-        const userAgent = getUserAgent();
-        await fetch(getLogsUrl(), {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                // Browser restricts setting User-Agent; use X-User-Agent instead.
-                ...(isNode
-                    ? { 'User-Agent': userAgent }
-                    : { 'X-User-Agent': userAgent }),
-            },
-            body: JSON.stringify(payload),
-            signal: AbortSignal.timeout(5_000),
-        });
-    }
-    catch {
-        // Silently swallow — telemetry must never break user operations.
-    }
-}
-
-/**
- * Build the `clientContext` object for telemetry payloads.
- *
- * @remarks
- * Uses the exported `getRuntime()` and `isNodeEnvironment()` from
- * `@core/utils` to detect the runtime environment (per Dominik's
- * feedback to reuse existing infrastructure). The returned string
- * is parsed into the structured `ClientContext` fields expected by
- * the server schema.
- *
- * @returns A {@link ClientContext} with platform, OS, and runtime name
- *   populated from the current environment.
- *
- * @example
- * ```typescript
- * import { buildClientContext } from './clientContext'
- *
- * const ctx = buildClientContext()
- * // Node: { platform: 'node', os: 'darwin', runtimeName: null }
- * // Browser: { platform: 'browser', os: null, runtimeName: 'chrome' }
- * ```
- */
-function buildClientContext() {
-    const runtime = getRuntime();
-    if (runtime.startsWith('browser/')) {
-        return {
-            platform: 'browser',
-            os: null,
-            runtimeName: runtime.slice('browser/'.length).toLowerCase(),
-        };
-    }
-    if (runtime.startsWith('node/')) {
-        return {
-            platform: 'node',
-            os: isNodeEnvironment() ? process.platform : null,
-            runtimeName: null,
-        };
-    }
-    return {
-        platform: 'node',
-        os: null,
-        runtimeName: null,
-    };
-}
-
 /**
  * Event type identifiers accepted by the server-side logs endpoint.
  *
@@ -29270,6 +30019,11 @@ const EVENT_TYPES = {
     DEPOSIT_FOR: 'unified_balance_deposit_for',
     SPEND: 'unified_balance_spend',
     SPEND_FORWARDER: 'unified_balance_spend_forwarder',
+    ESTIMATE_SPEND: 'unified_balance_estimate_spend',
+    GET_BALANCES: 'unified_balance_get_balances',
+    ADD_DELEGATE: 'unified_balance_add_delegate',
+    REMOVE_DELEGATE: 'unified_balance_remove_delegate',
+    GET_DELEGATE_STATUS: 'unified_balance_get_delegate_status',
     INITIATE_REMOVE_FUND: 'unified_balance_initiate_remove_fund',
     REMOVE_FUND: 'unified_balance_remove_fund',
 };
@@ -29307,33 +30061,29 @@ function extractSingleChainResult(data) {
         txHash: data.txHash,
     };
 }
-/**
- * Resolve a chain identifier that may be a string or a
- * `ChainDefinition` object to a plain string.
- *
- * @internal
- */
-function resolveChainString(chain) {
-    if (typeof chain === 'string')
-        return chain;
-    return chain.chain;
-}
 /**
  * Extract log-relevant fields from a spend result.
  *
+ * @remarks
+ * Collects all source chains from allocations and joins them with
+ * commas so multi-chain spends are fully represented.
+ *
  * @internal
  */
 function extractSpend(data) {
-    const rawChain = data.allocations?.[0]?.chain;
-    let firstSourceChain;
-    if (rawChain != null) {
-        firstSourceChain = resolveChainString(rawChain);
+    const allocs = data.allocations ?? [];
+    const chains = [];
+    for (const alloc of allocs) {
+        const name = resolveChainName(alloc.chain);
+        if (name != null) {
+            chains.push(name);
+        }
     }
-    const hasAllocations = data.allocations?.[0] != null;
+    const sourceChain = chains.length > 0 ? chains.join(',') : undefined;
     return {
-        ...(firstSourceChain != null && { sourceChain: firstSourceChain }),
+        ...(sourceChain != null && { sourceChain }),
         destinationChain: data.destinationChain,
-        ...(hasAllocations && { tokenIn: 'USDC' }),
+        ...(allocs.length > 0 && { tokenIn: 'USDC' }),
         txHash: data.txHash,
     };
 }
@@ -29432,10 +30182,9 @@ function mapSucceededEventToLog(actionName, payload, sdkName, sdkVersion) {
  * telemetry for successful verb operations.
  *
  * @remarks
- * Follows Dominik's feedback to reuse the existing event bus as the
- * SDK-side hook for telemetry. Registers a handler for each verb's
- * `.succeeded` event. Non-verb and non-succeeded events are not
- * subscribed to.
+ * Registers a handler for each verb's `.succeeded` event using the
+ * shared `registerTelemetryHandler` from `@core/utils`. Non-verb and
+ * non-succeeded events are not subscribed to.
  *
  * The HTTP POST is fire-and-forget — telemetry never blocks or fails
  * user operations.
@@ -29455,20 +30204,7 @@ function mapSucceededEventToLog(actionName, payload, sdkName, sdkVersion) {
  * @internal
  */
 function registerTelemetryHandler(dispatcher, sdkName, sdkVersion) {
-    for (const actionName of Object.keys(VERB_EVENT_MAP)) {
-        dispatcher.on(actionName, (payload) => {
-            try {
-                const log = mapSucceededEventToLog(actionName, payload, sdkName, sdkVersion);
-                if (log) {
-                    // Fire-and-forget — intentionally not awaited.
-                    void emitAnalyticsLog(log);
-                }
-            }
-            catch {
-                // Silently swallow — telemetry must never break user operations.
-            }
-        });
-    }
+    registerTelemetryHandler$1(dispatcher, sdkName, sdkVersion, VERB_EVENT_MAP, mapSucceededEventToLog);
 }
 
 /**
@@ -35498,6 +36234,8 @@ function getSupportedChains(context, token, options) {
     return Object.values(Object.fromEntries(filtered.map((chain) => [chain.chain, chain])));
 }
 
+/** SDK name used in telemetry payloads. */
+const SDK_NAME = resolveKitSdkName(pkg.name);
 /**
  * A high-level class-based interface for cross-chain USDC deposits,
  * spending, balance queries, delegation management, and withdrawals.
@@ -35545,6 +36283,10 @@ class UnifiedBalanceKit {
      * The action dispatcher for the kit.
      */
     actionDispatcher;
+    /** Whether error telemetry is disabled. */
+    disableErrorReporting;
+    /** Per-kit telemetry identity for shared helpers. */
+    telemetryConfig;
     /**
      * Create a new UnifiedBalanceKit instance.
      *
@@ -35557,14 +36299,49 @@ class UnifiedBalanceKit {
     constructor(config = {}) {
         this.context = createUnifiedBalanceKitContext(config);
         this.actionDispatcher = new Actionable();
+        this.disableErrorReporting = config.disableErrorReporting === true;
+        this.telemetryConfig = {
+            sdkName: SDK_NAME,
+            sdkVersion: pkg.version,
+            disabled: this.disableErrorReporting,
+        };
         for (const provider of this.context.providers) {
             provider.registerDispatcher(this.actionDispatcher);
         }
         if (!config.disableAnalytics) {
-            const sdkName = pkg.name.replace('@circle-fin/', '');
-            registerTelemetryHandler(this.actionDispatcher, sdkName, pkg.version);
+            registerTelemetryHandler(this.actionDispatcher, SDK_NAME, pkg.version);
         }
     }
+    /**
+     * Extract comma-separated source chain names from spend params.
+     *
+     * @internal
+     */
+    static extractSpendSourceChains(params) {
+        if (params == null || typeof params !== 'object' || !('from' in params)) {
+            return undefined;
+        }
+        const fromVal = params.from;
+        const sources = Array.isArray(fromVal) ? fromVal : [fromVal];
+        const chains = [];
+        for (const src of sources) {
+            const allocs = src?.allocations;
+            let allocArr;
+            if (allocs == null) {
+                allocArr = [];
+            }
+            else {
+                allocArr = Array.isArray(allocs) ? allocs : [allocs];
+            }
+            for (const alloc of allocArr) {
+                const name = resolveChainName(alloc.chain);
+                if (name != null) {
+                    chains.push(name);
+                }
+            }
+        }
+        return chains.length > 0 ? chains.join(',') : undefined;
+    }
     // implementation just forwards to the bus
     on(actionOrWildcard, handler) {
         this.actionDispatcher.on(actionOrWildcard, handler);
@@ -35587,7 +36364,10 @@ class UnifiedBalanceKit {
      * @see UnifiedBalanceKit.depositFor to deposit into another account.
      */
     async deposit(params) {
-        return deposit(this.context, params);
+        return withErrorTelemetry(async () => deposit(this.context, params), EVENT_TYPES.DEPOSIT, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from?.chain),
+            tokenIn: params.token ?? 'USDC',
+        });
     }
     /**
      * Deposit USDC into another account (not the caller's).
@@ -35599,7 +36379,10 @@ class UnifiedBalanceKit {
      * @see UnifiedBalanceKit.deposit to deposit into your own account.
      */
     async depositFor(params) {
-        return depositFor(this.context, params);
+        return withErrorTelemetry(async () => depositFor(this.context, params), EVENT_TYPES.DEPOSIT_FOR, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from?.chain),
+            tokenIn: params.token ?? 'USDC',
+        });
     }
     /**
      * Spend (mint) USDC on a destination chain by pulling funds from one
@@ -35612,7 +36395,17 @@ class UnifiedBalanceKit {
      * @see UnifiedBalanceKit.estimateSpend to preview fees before spending.
      */
     async spend(params) {
-        return spend(this.context, params);
+        const destChain = 'to' in params
+            ? resolveChainName(params.to.chain)
+            : undefined;
+        const tokenIn = 'token' in params
+            ? (params.token ?? 'USDC')
+            : 'USDC';
+        return withErrorTelemetry(async () => spend(this.context, params), EVENT_TYPES.SPEND, this.telemetryConfig, {
+            sourceChain: UnifiedBalanceKit.extractSpendSourceChains(params),
+            ...(destChain != null && { destinationChain: destChain }),
+            tokenIn,
+        });
     }
     /**
      * Estimate the fees for a spend operation without executing it.
@@ -35622,7 +36415,17 @@ class UnifiedBalanceKit {
      * @returns Promise resolving to the fee estimate.
      */
     async estimateSpend(params) {
-        return estimateSpend(this.context, params);
+        const destChain = 'to' in params
+            ? resolveChainName(params.to.chain)
+            : undefined;
+        const sourceChain = UnifiedBalanceKit.extractSpendSourceChains(params);
+        return withErrorTelemetry(async () => estimateSpend(this.context, params), EVENT_TYPES.ESTIMATE_SPEND, this.telemetryConfig, {
+            ...(sourceChain != null && { sourceChain }),
+            ...(destChain != null && { destinationChain: destChain }),
+            tokenIn: 'token' in params
+                ? (params.token ?? 'USDC')
+                : 'USDC',
+        });
     }
     /**
      * Fetch aggregated and per-chain balances for one or more accounts.
@@ -35631,7 +36434,7 @@ class UnifiedBalanceKit {
      * @returns Promise resolving to the aggregated balance result.
      */
     async getBalances(params) {
-        return getBalances(this.context, params);
+        return withErrorTelemetry(async () => getBalances(this.context, params), EVENT_TYPES.GET_BALANCES, this.telemetryConfig);
     }
     /**
      * Grant spending rights to another address on the owner's account.
@@ -35646,7 +36449,7 @@ class UnifiedBalanceKit {
      * @see UnifiedBalanceKit.getDelegateStatus to check delegate status.
      */
     async addDelegate(params) {
-        return addDelegate(this.context, params);
+        return withErrorTelemetry(async () => addDelegate(this.context, params), EVENT_TYPES.ADD_DELEGATE, this.telemetryConfig, { sourceChain: resolveChainName(params.from?.chain) });
     }
     /**
      * Revoke spending rights from a delegate on the owner's account.
@@ -35661,7 +36464,7 @@ class UnifiedBalanceKit {
      * @see UnifiedBalanceKit.getDelegateStatus to check delegate status.
      */
     async removeDelegate(params) {
-        return removeDelegate(this.context, params);
+        return withErrorTelemetry(async () => removeDelegate(this.context, params), EVENT_TYPES.REMOVE_DELEGATE, this.telemetryConfig, { sourceChain: resolveChainName(params.from?.chain) });
     }
     /**
      * Kick off a delayed fund removal from an account.
@@ -35673,7 +36476,10 @@ class UnifiedBalanceKit {
      * @see UnifiedBalanceKit.removeFund to complete the fund removal.
      */
     async initiateRemoveFund(params) {
-        return initiateRemoveFund(this.context, params);
+        return withErrorTelemetry(async () => initiateRemoveFund(this.context, params), EVENT_TYPES.INITIATE_REMOVE_FUND, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from?.chain),
+            tokenIn: params.token ?? 'USDC',
+        });
     }
     /**
      * Complete a fund removal once the activation period has passed.
@@ -35685,7 +36491,10 @@ class UnifiedBalanceKit {
      * @see UnifiedBalanceKit.initiateRemoveFund to start the process.
      */
     async removeFund(params) {
-        return removeFund(this.context, params);
+        return withErrorTelemetry(async () => removeFund(this.context, params), EVENT_TYPES.REMOVE_FUND, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from?.chain),
+            tokenIn: params.token ?? 'USDC',
+        });
     }
     /**
      * Check the finality-aware delegate status of an address.
@@ -35713,7 +36522,7 @@ class UnifiedBalanceKit {
      * ```
      */
     async getDelegateStatus(params) {
-        return getDelegateStatus(this.context, params);
+        return withErrorTelemetry(async () => getDelegateStatus(this.context, params), EVENT_TYPES.GET_DELEGATE_STATUS, this.telemetryConfig, { sourceChain: resolveChainName(params.from?.chain) });
     }
     /**
      * Get all chains supported by the kit.
@@ -36203,8 +37012,18 @@ class AppKit {
      * ```
      */
     constructor(config = {}) {
-        this.context = createContext(config);
-        this.unifiedBalance = new AppKitUnifiedBalance(config.unifiedBalance);
+        this.context = createContext({
+            ...config,
+            ...(config.disableErrorReporting != null && {
+                disableErrorReporting: config.disableErrorReporting,
+            }),
+        });
+        this.unifiedBalance = new AppKitUnifiedBalance({
+            ...config.unifiedBalance,
+            ...(config.disableErrorReporting != null && {
+                disableErrorReporting: config.disableErrorReporting,
+            }),
+        });
     }
     /**
      * Execute a cross-chain USDC bridge transfer.