@circle-fin/bridge-kit 1.1.1 → 1.2.0

package/index.cjs

@@ -19,10 +19,10 @@
 'use strict';
 
 var zod = require('zod');
-var units = require('@ethersproject/units');
 require('@ethersproject/bytes');
 require('@ethersproject/address');
 require('bs58');
+var units = require('@ethersproject/units');
 var providerCctpV2 = require('@circle-fin/provider-cctp-v2');
 
 /**
@@ -66,200 +66,961 @@ const registerKit = (kitIdentifier) => {
     }
 };
 
-// -----------------------------------------------------------------------------
-// Blockchain Enum
-// -----------------------------------------------------------------------------
 /**
- * Enumeration of all blockchains supported by this library.
- * @enum
- * @category Enums
- * @description Provides string identifiers for each supported blockchain.
+ * Valid recoverability values for error handling strategies.
+ *
+ * - FATAL errors are thrown immediately (invalid inputs, insufficient funds)
+ * - RETRYABLE errors are returned when a flow fails to start but could work later
+ * - RESUMABLE errors are returned when a flow fails mid-execution but can be continued
  */
-exports.Blockchain = void 0;
-(function (Blockchain) {
-    Blockchain["Algorand"] = "Algorand";
-    Blockchain["Algorand_Testnet"] = "Algorand_Testnet";
-    Blockchain["Aptos"] = "Aptos";
-    Blockchain["Aptos_Testnet"] = "Aptos_Testnet";
-    Blockchain["Arc_Testnet"] = "Arc_Testnet";
-    Blockchain["Arbitrum"] = "Arbitrum";
-    Blockchain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
-    Blockchain["Avalanche"] = "Avalanche";
-    Blockchain["Avalanche_Fuji"] = "Avalanche_Fuji";
-    Blockchain["Base"] = "Base";
-    Blockchain["Base_Sepolia"] = "Base_Sepolia";
-    Blockchain["Celo"] = "Celo";
-    Blockchain["Celo_Alfajores_Testnet"] = "Celo_Alfajores_Testnet";
-    Blockchain["Codex"] = "Codex";
-    Blockchain["Codex_Testnet"] = "Codex_Testnet";
-    Blockchain["Ethereum"] = "Ethereum";
-    Blockchain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
-    Blockchain["Hedera"] = "Hedera";
-    Blockchain["Hedera_Testnet"] = "Hedera_Testnet";
-    Blockchain["HyperEVM"] = "HyperEVM";
-    Blockchain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
-    Blockchain["Ink"] = "Ink";
-    Blockchain["Ink_Testnet"] = "Ink_Testnet";
-    Blockchain["Linea"] = "Linea";
-    Blockchain["Linea_Sepolia"] = "Linea_Sepolia";
-    Blockchain["NEAR"] = "NEAR";
-    Blockchain["NEAR_Testnet"] = "NEAR_Testnet";
-    Blockchain["Noble"] = "Noble";
-    Blockchain["Noble_Testnet"] = "Noble_Testnet";
-    Blockchain["Optimism"] = "Optimism";
-    Blockchain["Optimism_Sepolia"] = "Optimism_Sepolia";
-    Blockchain["Polkadot_Asset_Hub"] = "Polkadot_Asset_Hub";
-    Blockchain["Polkadot_Westmint"] = "Polkadot_Westmint";
-    Blockchain["Plume"] = "Plume";
-    Blockchain["Plume_Testnet"] = "Plume_Testnet";
-    Blockchain["Polygon"] = "Polygon";
-    Blockchain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
-    Blockchain["Sei"] = "Sei";
-    Blockchain["Sei_Testnet"] = "Sei_Testnet";
-    Blockchain["Solana"] = "Solana";
-    Blockchain["Solana_Devnet"] = "Solana_Devnet";
-    Blockchain["Sonic"] = "Sonic";
-    Blockchain["Sonic_Testnet"] = "Sonic_Testnet";
-    Blockchain["Stellar"] = "Stellar";
-    Blockchain["Stellar_Testnet"] = "Stellar_Testnet";
-    Blockchain["Sui"] = "Sui";
-    Blockchain["Sui_Testnet"] = "Sui_Testnet";
-    Blockchain["Unichain"] = "Unichain";
-    Blockchain["Unichain_Sepolia"] = "Unichain_Sepolia";
-    Blockchain["World_Chain"] = "World_Chain";
-    Blockchain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
-    Blockchain["XDC"] = "XDC";
-    Blockchain["XDC_Apothem"] = "XDC_Apothem";
-    Blockchain["ZKSync_Era"] = "ZKSync_Era";
-    Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
-})(exports.Blockchain || (exports.Blockchain = {}));
-
+const RECOVERABILITY_VALUES = [
+    'RETRYABLE',
+    'RESUMABLE',
+    'FATAL',
+];
 /**
- * Helper function to define a chain with proper TypeScript typing.
+ * Error type constants for categorizing errors by origin.
  *
- * This utility function works with TypeScript's `as const` assertion to create
- * strongly-typed, immutable chain definition objects. It preserves literal types
- * from the input and ensures the resulting object maintains all type information.
+ * This const object provides a reference for error types, enabling
+ * IDE autocomplete and preventing typos when creating custom errors.
+ *
+ * @remarks
+ * While internal error definitions use string literals with type annotations
+ * for strict type safety, this constant is useful for developers creating
+ * custom error instances or checking error types programmatically.
  *
- * When used with `as const`, it allows TypeScript to infer the most specific
- * possible types for all properties, including string literals and numeric literals,
- * rather than widening them to general types like string or number.
- * @typeParam T - The specific chain definition type (must extend ChainDefinition)
- * @param chain - The chain definition object, typically with an `as const` assertion
- * @returns The same chain definition with preserved literal types
  * @example
  * ```typescript
- * // Define an EVM chain with literal types preserved
- * const Ethereum = defineChain({
- *   type: 'evm',
- *   chain: Blockchain.Ethereum,
- *   chainId: 1,
- *   name: 'Ethereum',
- *   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
- *   isTestnet: false,
- *   usdcAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
- *   eurcAddress: null,
- *   cctp: {
- *     domain: 0,
- *     contracts: {
- *       TokenMessengerV1: '0xbd3fa81b58ba92a82136038b25adec7066af3155',
- *       MessageTransmitterV1: '0x0a992d191deec32afe36203ad87d7d289a738f81'
- *     }
- *   }
- * } as const);
+ * import { ERROR_TYPES, KitError } from '@core/errors'
+ *
+ * // Use for type checking
+ * if (error.type === ERROR_TYPES.BALANCE) {
+ *   console.log('This is a balance error')
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use as reference when creating custom errors
+ * const error = new KitError({
+ *   code: 9999,
+ *   name: 'CUSTOM_ERROR',
+ *   type: ERROR_TYPES.BALANCE,  // IDE autocomplete works here
+ *   recoverability: 'FATAL',
+ *   message: 'Custom balance error'
+ * })
  * ```
  */
-function defineChain(chain) {
-    return chain;
-}
-
+const ERROR_TYPES = {
+    /** User input validation and parameter checking */
+    INPUT: 'INPUT',
+    /** Insufficient token balances and amount validation */
+    BALANCE: 'BALANCE',
+    /** On-chain execution: reverts, gas issues, transaction failures */
+    ONCHAIN: 'ONCHAIN',
+    /** Blockchain RPC provider issues and endpoint problems */
+    RPC: 'RPC',
+    /** Internet connectivity, DNS resolution, connection issues */
+    NETWORK: 'NETWORK',
+};
 /**
- * Algorand Mainnet chain definition
- * @remarks
- * This represents the official production network for the Algorand blockchain.
+ * Array of valid error type values for validation.
+ * Derived from ERROR_TYPES const object.
  */
-const Algorand = defineChain({
-    type: 'algorand',
-    chain: exports.Blockchain.Algorand,
-    name: 'Algorand',
-    title: 'Algorand Mainnet',
-    nativeCurrency: {
-        name: 'Algo',
-        symbol: 'ALGO',
-        decimals: 6,
-    },
-    isTestnet: false,
-    explorerUrl: 'https://explorer.perawallet.app/tx/{hash}',
-    rpcEndpoints: ['https://mainnet-api.algonode.cloud'],
-    eurcAddress: null,
-    usdcAddress: '31566704',
-    cctp: null,
-});
+const ERROR_TYPE_VALUES = Object.values(ERROR_TYPES);
 
+// Create mutable arrays for Zod enum validation
+const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
+const ERROR_TYPE_ARRAY = [...ERROR_TYPE_VALUES];
 /**
- * Algorand Testnet chain definition
- * @remarks
- * This represents the official testnet for the Algorand blockchain.
+ * Error code ranges for validation.
+ * Single source of truth for valid error code ranges.
  */
-const AlgorandTestnet = defineChain({
-    type: 'algorand',
-    chain: exports.Blockchain.Algorand_Testnet,
-    name: 'Algorand Testnet',
-    title: 'Algorand Test Network',
-    nativeCurrency: {
-        name: 'Algo',
-        symbol: 'ALGO',
-        decimals: 6,
-    },
-    isTestnet: true,
-    explorerUrl: 'https://testnet.explorer.perawallet.app/tx/{hash}',
-    rpcEndpoints: ['https://testnet-api.algonode.cloud'],
-    eurcAddress: null,
-    usdcAddress: '10458941',
-    cctp: null,
-});
-
+const ERROR_CODE_RANGES = [
+    { min: 1000, max: 1999, type: 'INPUT' },
+    { min: 3000, max: 3999, type: 'NETWORK' },
+    { min: 4000, max: 4999, type: 'RPC' },
+    { min: 5000, max: 5999, type: 'ONCHAIN' },
+    { min: 9000, max: 9999, type: 'BALANCE' },
+];
 /**
- * Aptos Mainnet chain definition
- * @remarks
- * This represents the official production network for the Aptos blockchain.
+ * Zod schema for validating ErrorDetails objects.
+ *
+ * This schema provides runtime validation for all ErrorDetails properties,
+ * ensuring type safety and proper error handling for JavaScript consumers.
+ *
+ * @example
+ * ```typescript
+ * import { errorDetailsSchema } from '@core/errors'
+ *
+ * const result = errorDetailsSchema.safeParse({
+ *   code: 1001,
+ *   name: 'INPUT_NETWORK_MISMATCH',
+ *   type: 'INPUT',
+ *   recoverability: 'FATAL',
+ *   message: 'Source and destination networks must be different'
+ * })
+ *
+ * if (!result.success) {
+ *   console.error('Validation failed:', result.error.issues)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Runtime error
+ * const result = errorDetailsSchema.safeParse({
+ *   code: 9001,
+ *   name: 'BALANCE_INSUFFICIENT_TOKEN',
+ *   type: 'BALANCE',
+ *   recoverability: 'FATAL',
+ *   message: 'Insufficient USDC balance'
+ * })
+ * ```
  */
-const Aptos = defineChain({
-    type: 'aptos',
-    chain: exports.Blockchain.Aptos,
-    name: 'Aptos',
-    title: 'Aptos Mainnet',
-    nativeCurrency: {
-        name: 'Aptos',
-        symbol: 'APT',
-        decimals: 8,
-    },
-    isTestnet: false,
-    explorerUrl: 'https://explorer.aptoslabs.com/txn/{hash}?network=mainnet',
-    rpcEndpoints: ['https://fullnode.mainnet.aptoslabs.com/v1'],
-    eurcAddress: null,
-    usdcAddress: '0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b',
-    cctp: {
-        domain: 9,
-        contracts: {
-            v1: {
-                type: 'split',
-                tokenMessenger: '0x9bce6734f7b63e835108e3bd8c36743d4709fe435f44791918801d0989640a9d',
-                messageTransmitter: '0x177e17751820e4b4371873ca8c30279be63bdea63b88ed0f2239c2eea10f1772',
-                confirmations: 1,
-            },
-        },
-    },
+const errorDetailsSchema = zod.z.object({
+    /**
+     * Numeric identifier following standardized ranges:
+     * - 1000-1999: INPUT errors - Parameter validation
+     * - 3000-3999: NETWORK errors - Connectivity issues
+     * - 4000-4999: RPC errors - Provider issues, gas estimation
+     * - 5000-5999: ONCHAIN errors - Transaction/simulation failures
+     * - 9000-9999: BALANCE errors - Insufficient funds
+     */
+    code: zod.z
+        .number()
+        .int('Error code must be an integer')
+        .refine((code) => ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
+        message: 'Error code must be in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
+    }),
+    /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
+    name: zod.z
+        .string()
+        .min(1, 'Error name must be a non-empty string')
+        .regex(/^[A-Z_][A-Z0-9_]*$/, 'Error name must match pattern: ^[A-Z_][A-Z0-9_]*$'),
+    /** Error category indicating where the error originated */
+    type: zod.z.enum(ERROR_TYPE_ARRAY, {
+        errorMap: () => ({
+            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK',
+        }),
+    }),
+    /** Error handling strategy */
+    recoverability: zod.z.enum(RECOVERABILITY_ARRAY, {
+        errorMap: () => ({
+            message: 'Recoverability must be one of: RETRYABLE, RESUMABLE, FATAL',
+        }),
+    }),
+    /** User-friendly explanation with context */
+    message: zod.z
+        .string()
+        .min(1, 'Error message must be a non-empty string')
+        .max(1000, 'Error message must be 1000 characters or less'),
+    /** Raw error details, context, or the original error that caused this one. */
+    cause: zod.z
+        .object({
+        /** Free-form error payload from underlying system */
+        trace: zod.z.unknown().optional(),
+    })
+        .optional(),
 });
 
 /**
- * Aptos Testnet chain definition
- * @remarks
- * This represents the official test network for the Aptos blockchain.
- */
-const AptosTestnet = defineChain({
-    type: 'aptos',
-    chain: exports.Blockchain.Aptos_Testnet,
+ * Validates an ErrorDetails object using Zod schema.
+ *
+ * @param details - The object to validate
+ * @returns The validated ErrorDetails object
+ * @throws TypeError When validation fails
+ *
+ * @example
+ * ```typescript
+ * import { validateErrorDetails } from '@core/errors'
+ *
+ * try {
+ *   const validDetails = validateErrorDetails({
+ *     code: 1001,
+ *     name: 'NETWORK_MISMATCH',
+ *     recoverability: 'FATAL',
+ *     message: 'Source and destination networks must be different'
+ *   })
+ * } catch (error) {
+ *   console.error('Validation failed:', error.message)
+ * }
+ * ```
+ */
+function validateErrorDetails(details) {
+    const result = errorDetailsSchema.safeParse(details);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+            .join(', ');
+        throw new TypeError(`Invalid ErrorDetails: ${issues}`);
+    }
+    return result.data;
+}
+
+/**
+ * Maximum length for error messages in fallback validation errors.
+ *
+ * KitError enforces a 1000-character limit on error messages. When creating
+ * fallback validation errors that combine multiple Zod issues, we use 950
+ * characters to leave a 50-character buffer for:
+ * - The error message prefix ("Invalid bridge parameters: ")
+ * - Potential encoding differences or formatting overhead
+ * - Safety margin to prevent KitError constructor failures
+ *
+ * This ensures that even with concatenated issue summaries, the final message
+ * stays within KitError's constraints.
+ */
+const MAX_MESSAGE_LENGTH = 950;
+
+/**
+ * Structured error class for Stablecoin 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
+ * error objects cannot be modified after creation.
+ *
+ * @example
+ * ```typescript
+ * import { KitError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   code: 1001,
+ *   name: 'INPUT_NETWORK_MISMATCH',
+ *   recoverability: 'FATAL',
+ *   message: 'Cannot bridge between mainnet and testnet'
+ * })
+ *
+ * if (error instanceof KitError) {
+ *   console.log(`Error ${error.code}: ${error.name}`)
+ *   // → "Error 1001: INPUT_NETWORK_MISMATCH"
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { KitError } from '@core/errors'
+ *
+ * // Error with cause information
+ * const error = new KitError({
+ *   code: 1002,
+ *   name: 'INVALID_AMOUNT',
+ *   recoverability: 'FATAL',
+ *   message: 'Amount must be greater than zero',
+ *   cause: {
+ *     trace: { providedAmount: -100, minimumAmount: 0 }
+ *   }
+ * })
+ *
+ * throw error
+ * ```
+ */
+class KitError extends Error {
+    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    code;
+    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
+    name;
+    /** Error category indicating where the error originated */
+    type;
+    /** Error handling strategy */
+    recoverability;
+    /** Raw error details, context, or the original error that caused this one. */
+    cause;
+    /**
+     * Create a new KitError instance.
+     *
+     * @param details - The error details object containing all required properties.
+     * @throws \{TypeError\} When details parameter is missing or invalid.
+     */
+    constructor(details) {
+        // Truncate message if it exceeds maximum length to prevent validation errors
+        let message = details.message;
+        if (message.length > MAX_MESSAGE_LENGTH) {
+            message = `${message.slice(0, MAX_MESSAGE_LENGTH - 3)}...`;
+        }
+        const truncatedDetails = { ...details, message };
+        // Validate input at runtime for JavaScript consumers using Zod
+        const validatedDetails = validateErrorDetails(truncatedDetails);
+        super(validatedDetails.message);
+        // Set properties as readonly at runtime
+        Object.defineProperties(this, {
+            name: {
+                value: validatedDetails.name,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
+            code: {
+                value: validatedDetails.code,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
+            type: {
+                value: validatedDetails.type,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
+            recoverability: {
+                value: validatedDetails.recoverability,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
+            ...(validatedDetails.cause && {
+                cause: {
+                    value: validatedDetails.cause,
+                    writable: false,
+                    enumerable: true,
+                    configurable: false,
+                },
+            }),
+        });
+    }
+}
+
+/**
+ * Standardized error code ranges for consistent categorization:
+ *
+ * - 1000-1999: INPUT errors - Parameter validation, input format errors
+ * - 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
+ * - 9000-9999: BALANCE errors - Insufficient funds, token balance, allowance
+ */
+/**
+ * Standardized error definitions for INPUT type errors.
+ *
+ * Each entry combines the numeric error code, string name, and type
+ * to ensure consistency when creating error instances.
+ *
+ * Error codes follow a hierarchical numbering scheme where the first digit
+ * indicates the error category (1 = INPUT) and subsequent digits provide
+ * specific error identification within that category.
+ *
+ *
+ * @example
+ * ```typescript
+ * import { InputError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...InputError.NETWORK_MISMATCH,
+ *   recoverability: 'FATAL',
+ *   message: 'Source and destination networks must be different'
+ * })
+ *
+ * // Access code, name, and type individually if needed
+ * console.log(InputError.NETWORK_MISMATCH.code)  // 1001
+ * console.log(InputError.NETWORK_MISMATCH.name)  // 'INPUT_NETWORK_MISMATCH'
+ * console.log(InputError.NETWORK_MISMATCH.type)  // 'INPUT'
+ * ```
+ */
+const InputError = {
+    /** Network type mismatch between chains (mainnet vs testnet) */
+    NETWORK_MISMATCH: {
+        code: 1001,
+        name: 'INPUT_NETWORK_MISMATCH',
+        type: 'INPUT',
+    },
+    /** Invalid amount format or value (negative, zero, or malformed) */
+    INVALID_AMOUNT: {
+        code: 1002,
+        name: 'INPUT_INVALID_AMOUNT',
+        type: 'INPUT',
+    },
+    /** Unsupported or invalid bridge route configuration */
+    UNSUPPORTED_ROUTE: {
+        code: 1003,
+        name: 'INPUT_UNSUPPORTED_ROUTE',
+        type: 'INPUT',
+    },
+    /** Invalid wallet or contract address format */
+    INVALID_ADDRESS: {
+        code: 1004,
+        name: 'INPUT_INVALID_ADDRESS',
+        type: 'INPUT',
+    },
+    /** Invalid or unsupported chain identifier */
+    INVALID_CHAIN: {
+        code: 1005,
+        name: 'INPUT_INVALID_CHAIN',
+        type: 'INPUT',
+    },
+    /** General validation failure for complex validation rules */
+    VALIDATION_FAILED: {
+        code: 1098,
+        name: 'INPUT_VALIDATION_FAILED',
+        type: 'INPUT',
+    },
+};
+
+/**
+ * Creates error for network type mismatch between source and destination.
+ *
+ * This error is thrown when attempting to bridge between chains that have
+ * different network types (e.g., mainnet to testnet), which is not supported
+ * for security reasons.
+ *
+ * @param sourceChain - The source chain definition
+ * @param destChain - The destination chain definition
+ * @returns KitError with specific network mismatch details
+ *
+ * @example
+ * ```typescript
+ * import { createNetworkMismatchError } from '@core/errors'
+ * import { Ethereum, BaseSepolia } from '@core/chains'
+ *
+ * // This will throw a detailed error
+ * throw createNetworkMismatchError(Ethereum, BaseSepolia)
+ * // Message: "Cannot bridge between Ethereum (mainnet) and Base Sepolia (testnet). Source and destination networks must both be testnet or both be mainnet."
+ * ```
+ */
+function createNetworkMismatchError(sourceChain, destChain) {
+    const sourceNetworkType = sourceChain.isTestnet ? 'testnet' : 'mainnet';
+    const destNetworkType = destChain.isTestnet ? 'testnet' : 'mainnet';
+    const errorDetails = {
+        ...InputError.NETWORK_MISMATCH,
+        recoverability: 'FATAL',
+        message: `Cannot bridge between ${sourceChain.name} (${sourceNetworkType}) and ${destChain.name} (${destNetworkType}). Source and destination networks must both be testnet or both be mainnet.`,
+        cause: {
+            trace: { sourceChain: sourceChain.name, destChain: destChain.name },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for unsupported bridge route.
+ *
+ * This error is thrown when attempting to bridge between chains that don't
+ * have a supported bridge route configured.
+ *
+ * @param source - Source chain name
+ * @param destination - Destination chain name
+ * @returns KitError with specific route details
+ *
+ * @example
+ * ```typescript
+ * import { createUnsupportedRouteError } from '@core/errors'
+ *
+ * throw createUnsupportedRouteError('Ethereum', 'Solana')
+ * // Message: "Route from Ethereum to Solana is not supported"
+ * ```
+ */
+function createUnsupportedRouteError(source, destination) {
+    const errorDetails = {
+        ...InputError.UNSUPPORTED_ROUTE,
+        recoverability: 'FATAL',
+        message: `Route from ${source} to ${destination} is not supported.`,
+        cause: {
+            trace: { source, destination },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for invalid amount format or precision.
+ *
+ * This error is thrown when the provided amount doesn't meet validation
+ * requirements such as precision, range, or format.
+ *
+ * @param amount - The invalid amount string
+ * @param reason - Specific reason why amount is invalid
+ * @returns KitError with amount details and validation rule
+ *
+ * @example
+ * ```typescript
+ * import { createInvalidAmountError } from '@core/errors'
+ *
+ * throw createInvalidAmountError('0.000001', 'Amount must be at least 0.01 USDC')
+ * // Message: "Invalid amount '0.000001': Amount must be at least 0.01 USDC"
+ *
+ * throw createInvalidAmountError('1,000.50', 'Amount must be a numeric string with dot (.) as decimal separator, with no thousand separators or comma decimals')
+ * // Message: "Invalid amount '1,000.50': Amount must be a numeric string with dot (.) as decimal separator, with no thousand separators or comma decimals."
+ * ```
+ */
+function createInvalidAmountError(amount, reason) {
+    const errorDetails = {
+        ...InputError.INVALID_AMOUNT,
+        recoverability: 'FATAL',
+        message: `Invalid amount '${amount}': ${reason}.`,
+        cause: {
+            trace: { amount, reason },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for invalid wallet address format.
+ *
+ * This error is thrown when the provided address doesn't match the expected
+ * format for the specified chain.
+ *
+ * @param address - The invalid address string
+ * @param chain - Chain name where address is invalid
+ * @param expectedFormat - Description of expected address format
+ * @returns KitError with address details and format requirements
+ *
+ * @example
+ * ```typescript
+ * import { createInvalidAddressError } from '@core/errors'
+ *
+ * throw createInvalidAddressError('0x123', 'Ethereum', '42-character hex string starting with 0x')
+ * // Message: "Invalid address '0x123' for Ethereum. Expected 42-character hex string starting with 0x."
+ *
+ * throw createInvalidAddressError('invalid', 'Solana', 'base58-encoded string')
+ * // Message: "Invalid address 'invalid' for Solana. Expected base58-encoded string."
+ * ```
+ */
+function createInvalidAddressError(address, chain, expectedFormat) {
+    const errorDetails = {
+        ...InputError.INVALID_ADDRESS,
+        recoverability: 'FATAL',
+        message: `Invalid address '${address}' for ${chain}. Expected ${expectedFormat}.`,
+        cause: {
+            trace: { address, chain, expectedFormat },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for invalid chain configuration.
+ *
+ * This error is thrown when the provided chain doesn't meet the required
+ * configuration or is not supported for the operation.
+ *
+ * @param chain - The invalid chain name or identifier
+ * @param reason - Specific reason why chain is invalid
+ * @returns KitError with chain details and validation rule
+ *
+ * @example
+ * ```typescript
+ * import { createInvalidChainError } from '@core/errors'
+ *
+ * throw createInvalidChainError('UnknownChain', 'Chain is not supported by this bridge')
+ * // Message: "Invalid chain 'UnknownChain': Chain is not supported by this bridge"
+ * ```
+ */
+function createInvalidChainError(chain, reason) {
+    const errorDetails = {
+        ...InputError.INVALID_CHAIN,
+        recoverability: 'FATAL',
+        message: `Invalid chain '${chain}': ${reason}`,
+        cause: {
+            trace: { chain, reason },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for general validation failure.
+ *
+ * This error is thrown when input validation fails for reasons not covered
+ * by more specific error types.
+ *
+ * @param field - The field that failed validation
+ * @param value - The invalid value (can be any type)
+ * @param reason - Specific reason why validation failed
+ * @returns KitError with validation details
+ *
+ * @example
+ * ```typescript
+ * import { createValidationFailedError } from '@core/errors'
+ *
+ * throw createValidationFailedError('recipient', 'invalid@email', 'Must be a valid wallet address')
+ * // Message: "Validation failed for 'recipient': 'invalid@email' - Must be a valid wallet address"
+ *
+ * throw createValidationFailedError('chainId', 999, 'Unsupported chain ID')
+ * // Message: "Validation failed for 'chainId': 999 - Unsupported chain ID"
+ *
+ * throw createValidationFailedError('config', { invalid: true }, 'Missing required properties')
+ * // Message: "Validation failed for 'config': [object Object] - Missing required properties"
+ * ```
+ */
+function createValidationFailedError$1(field, value, reason) {
+    // Convert value to string for display, handling different types appropriately
+    let valueString;
+    if (typeof value === 'string') {
+        valueString = `'${value}'`;
+    }
+    else if (typeof value === 'object' && value !== null) {
+        valueString = JSON.stringify(value);
+    }
+    else {
+        valueString = String(value);
+    }
+    const errorDetails = {
+        ...InputError.VALIDATION_FAILED,
+        recoverability: 'FATAL',
+        message: `Validation failed for '${field}': ${valueString} - ${reason}.`,
+        cause: {
+            trace: { field, value, reason },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates a KitError from a Zod validation error with detailed error information.
+ *
+ * This factory function converts Zod validation failures into standardized KitError
+ * instances with INPUT_VALIDATION_FAILED code (1098). It extracts all Zod issues
+ * and includes them in both the error message and trace for debugging, providing
+ * developers with comprehensive validation feedback.
+ *
+ * The error message includes all validation errors concatenated with semicolons.
+ *
+ * @param zodError - The Zod validation error containing one or more validation issues
+ * @param context - Context string describing what was being validated (e.g., 'bridge parameters', 'user input')
+ * @returns KitError with INPUT_VALIDATION_FAILED code and structured validation details
+ *
+ * @example
+ * ```typescript
+ * import { createValidationErrorFromZod } from '@core/errors'
+ * import { z } from 'zod'
+ *
+ * const schema = z.object({
+ *   name: z.string().min(3),
+ *   age: z.number().positive()
+ * })
+ *
+ * const result = schema.safeParse({ name: 'ab', age: -1 })
+ * if (!result.success) {
+ *   throw createValidationErrorFromZod(result.error, 'user data')
+ * }
+ * // Throws: KitError with message:
+ * // "Invalid user data: name: String must contain at least 3 character(s); age: Number must be greater than 0"
+ * // And cause.trace.validationErrors containing all validation errors as an array
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage in validation functions
+ * import { createValidationErrorFromZod } from '@core/errors'
+ *
+ * function validateBridgeParams(params: unknown): asserts params is BridgeParams {
+ *   const result = bridgeParamsSchema.safeParse(params)
+ *   if (!result.success) {
+ *     throw createValidationErrorFromZod(result.error, 'bridge parameters')
+ *   }
+ * }
+ * ```
+ */
+function createValidationErrorFromZod(zodError, context) {
+    // Format each Zod issue as "path: message"
+    const validationErrors = zodError.issues.map((issue) => {
+        const path = issue.path.length > 0 ? `${issue.path.join('.')}: ` : '';
+        return `${path}${issue.message}`;
+    });
+    // Join all errors with semicolons to show complete validation feedback
+    const issueSummary = validationErrors.join('; ');
+    const allErrors = issueSummary || 'Invalid Input';
+    // Build full message from context and validation errors
+    const fullMessage = `Invalid ${context}: ${allErrors}`;
+    const errorDetails = {
+        ...InputError.VALIDATION_FAILED,
+        recoverability: 'FATAL',
+        message: fullMessage,
+        cause: {
+            trace: {
+                validationErrors, // Array of formatted error strings for display
+                zodError: zodError.message, // Original Zod error message
+                zodIssues: zodError.issues, // Full Zod issues array for debugging
+            },
+        },
+    };
+    return new KitError(errorDetails);
+}
+
+// -----------------------------------------------------------------------------
+// Blockchain Enum
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of all blockchains known to this library.
+ *
+ * This enum contains every blockchain that has a chain definition, regardless
+ * of whether bridging is currently supported. For chains that support bridging
+ * via CCTPv2, see {@link BridgeChain}.
+ *
+ * @enum
+ * @category Enums
+ * @description Provides string identifiers for each blockchain with a definition.
+ * @see {@link BridgeChain} for the subset of chains that support CCTPv2 bridging.
+ */
+exports.Blockchain = void 0;
+(function (Blockchain) {
+    Blockchain["Algorand"] = "Algorand";
+    Blockchain["Algorand_Testnet"] = "Algorand_Testnet";
+    Blockchain["Aptos"] = "Aptos";
+    Blockchain["Aptos_Testnet"] = "Aptos_Testnet";
+    Blockchain["Arc_Testnet"] = "Arc_Testnet";
+    Blockchain["Arbitrum"] = "Arbitrum";
+    Blockchain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
+    Blockchain["Avalanche"] = "Avalanche";
+    Blockchain["Avalanche_Fuji"] = "Avalanche_Fuji";
+    Blockchain["Base"] = "Base";
+    Blockchain["Base_Sepolia"] = "Base_Sepolia";
+    Blockchain["Celo"] = "Celo";
+    Blockchain["Celo_Alfajores_Testnet"] = "Celo_Alfajores_Testnet";
+    Blockchain["Codex"] = "Codex";
+    Blockchain["Codex_Testnet"] = "Codex_Testnet";
+    Blockchain["Ethereum"] = "Ethereum";
+    Blockchain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
+    Blockchain["Hedera"] = "Hedera";
+    Blockchain["Hedera_Testnet"] = "Hedera_Testnet";
+    Blockchain["HyperEVM"] = "HyperEVM";
+    Blockchain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    Blockchain["Ink"] = "Ink";
+    Blockchain["Ink_Testnet"] = "Ink_Testnet";
+    Blockchain["Linea"] = "Linea";
+    Blockchain["Linea_Sepolia"] = "Linea_Sepolia";
+    Blockchain["NEAR"] = "NEAR";
+    Blockchain["NEAR_Testnet"] = "NEAR_Testnet";
+    Blockchain["Noble"] = "Noble";
+    Blockchain["Noble_Testnet"] = "Noble_Testnet";
+    Blockchain["Optimism"] = "Optimism";
+    Blockchain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    Blockchain["Polkadot_Asset_Hub"] = "Polkadot_Asset_Hub";
+    Blockchain["Polkadot_Westmint"] = "Polkadot_Westmint";
+    Blockchain["Plume"] = "Plume";
+    Blockchain["Plume_Testnet"] = "Plume_Testnet";
+    Blockchain["Polygon"] = "Polygon";
+    Blockchain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
+    Blockchain["Sei"] = "Sei";
+    Blockchain["Sei_Testnet"] = "Sei_Testnet";
+    Blockchain["Solana"] = "Solana";
+    Blockchain["Solana_Devnet"] = "Solana_Devnet";
+    Blockchain["Sonic"] = "Sonic";
+    Blockchain["Sonic_Testnet"] = "Sonic_Testnet";
+    Blockchain["Stellar"] = "Stellar";
+    Blockchain["Stellar_Testnet"] = "Stellar_Testnet";
+    Blockchain["Sui"] = "Sui";
+    Blockchain["Sui_Testnet"] = "Sui_Testnet";
+    Blockchain["Unichain"] = "Unichain";
+    Blockchain["Unichain_Sepolia"] = "Unichain_Sepolia";
+    Blockchain["World_Chain"] = "World_Chain";
+    Blockchain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
+    Blockchain["XDC"] = "XDC";
+    Blockchain["XDC_Apothem"] = "XDC_Apothem";
+    Blockchain["ZKSync_Era"] = "ZKSync_Era";
+    Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
+})(exports.Blockchain || (exports.Blockchain = {}));
+// -----------------------------------------------------------------------------
+// Bridge Chain Enum (CCTPv2 Supported Chains)
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support cross-chain bridging via CCTPv2.
+ *
+ * The enum is derived from the full {@link Blockchain} enum but filtered to only
+ * include chains with active CCTPv2 support. When new chains gain CCTPv2 support,
+ * they are added to this enum.
+ *
+ * @enum
+ * @category Enums
+ *
+ * @remarks
+ * - This enum is the **canonical source** of bridging-supported chains.
+ * - Use this enum (or its string literals) in `kit.bridge()` calls for type safety.
+ * - Attempting to use a chain not in this enum will produce a TypeScript compile error.
+ *
+ * @example
+ * ```typescript
+ * import { BridgeKit, BridgeChain } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ *
+ * // ✅ Valid - autocomplete suggests only supported chains
+ * await kit.bridge({
+ *   from: { adapter, chain: BridgeChain.Ethereum },
+ *   to: { adapter, chain: BridgeChain.Base },
+ *   amount: '100'
+ * })
+ *
+ * // ✅ Also valid - string literals work with autocomplete
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   to: { adapter, chain: 'Base_Sepolia' },
+ *   amount: '100'
+ * })
+ *
+ * // ❌ Compile error - Algorand is not in BridgeChain
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Algorand' }, // TypeScript error!
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '100'
+ * })
+ * ```
+ *
+ * @see {@link Blockchain} for the complete list of all known blockchains.
+ * @see {@link BridgeChainIdentifier} for the type that accepts these values.
+ */
+exports.BridgeChain = void 0;
+(function (BridgeChain) {
+    // Mainnet chains with CCTPv2 support
+    BridgeChain["Arbitrum"] = "Arbitrum";
+    BridgeChain["Avalanche"] = "Avalanche";
+    BridgeChain["Base"] = "Base";
+    BridgeChain["Codex"] = "Codex";
+    BridgeChain["Ethereum"] = "Ethereum";
+    BridgeChain["HyperEVM"] = "HyperEVM";
+    BridgeChain["Ink"] = "Ink";
+    BridgeChain["Linea"] = "Linea";
+    BridgeChain["Optimism"] = "Optimism";
+    BridgeChain["Plume"] = "Plume";
+    BridgeChain["Polygon"] = "Polygon";
+    BridgeChain["Sei"] = "Sei";
+    BridgeChain["Solana"] = "Solana";
+    BridgeChain["Sonic"] = "Sonic";
+    BridgeChain["Unichain"] = "Unichain";
+    BridgeChain["World_Chain"] = "World_Chain";
+    BridgeChain["XDC"] = "XDC";
+    // Testnet chains with CCTPv2 support
+    BridgeChain["Arc_Testnet"] = "Arc_Testnet";
+    BridgeChain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
+    BridgeChain["Avalanche_Fuji"] = "Avalanche_Fuji";
+    BridgeChain["Base_Sepolia"] = "Base_Sepolia";
+    BridgeChain["Codex_Testnet"] = "Codex_Testnet";
+    BridgeChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
+    BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    BridgeChain["Ink_Testnet"] = "Ink_Testnet";
+    BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
+    BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    BridgeChain["Plume_Testnet"] = "Plume_Testnet";
+    BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
+    BridgeChain["Sei_Testnet"] = "Sei_Testnet";
+    BridgeChain["Solana_Devnet"] = "Solana_Devnet";
+    BridgeChain["Sonic_Testnet"] = "Sonic_Testnet";
+    BridgeChain["Unichain_Sepolia"] = "Unichain_Sepolia";
+    BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
+    BridgeChain["XDC_Apothem"] = "XDC_Apothem";
+})(exports.BridgeChain || (exports.BridgeChain = {}));
+
+/**
+ * Helper function to define a chain with proper TypeScript typing.
+ *
+ * This utility function works with TypeScript's `as const` assertion to create
+ * strongly-typed, immutable chain definition objects. It preserves literal types
+ * from the input and ensures the resulting object maintains all type information.
+ *
+ * When used with `as const`, it allows TypeScript to infer the most specific
+ * possible types for all properties, including string literals and numeric literals,
+ * rather than widening them to general types like string or number.
+ * @typeParam T - The specific chain definition type (must extend ChainDefinition)
+ * @param chain - The chain definition object, typically with an `as const` assertion
+ * @returns The same chain definition with preserved literal types
+ * @example
+ * ```typescript
+ * // Define an EVM chain with literal types preserved
+ * const Ethereum = defineChain({
+ *   type: 'evm',
+ *   chain: Blockchain.Ethereum,
+ *   chainId: 1,
+ *   name: 'Ethereum',
+ *   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+ *   isTestnet: false,
+ *   usdcAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   eurcAddress: null,
+ *   cctp: {
+ *     domain: 0,
+ *     contracts: {
+ *       TokenMessengerV1: '0xbd3fa81b58ba92a82136038b25adec7066af3155',
+ *       MessageTransmitterV1: '0x0a992d191deec32afe36203ad87d7d289a738f81'
+ *     }
+ *   }
+ * } as const);
+ * ```
+ */
+function defineChain(chain) {
+    return chain;
+}
+
+/**
+ * Algorand Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Algorand blockchain.
+ */
+const Algorand = defineChain({
+    type: 'algorand',
+    chain: exports.Blockchain.Algorand,
+    name: 'Algorand',
+    title: 'Algorand Mainnet',
+    nativeCurrency: {
+        name: 'Algo',
+        symbol: 'ALGO',
+        decimals: 6,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://explorer.perawallet.app/tx/{hash}',
+    rpcEndpoints: ['https://mainnet-api.algonode.cloud'],
+    eurcAddress: null,
+    usdcAddress: '31566704',
+    cctp: null,
+});
+
+/**
+ * Algorand Testnet chain definition
+ * @remarks
+ * This represents the official testnet for the Algorand blockchain.
+ */
+const AlgorandTestnet = defineChain({
+    type: 'algorand',
+    chain: exports.Blockchain.Algorand_Testnet,
+    name: 'Algorand Testnet',
+    title: 'Algorand Test Network',
+    nativeCurrency: {
+        name: 'Algo',
+        symbol: 'ALGO',
+        decimals: 6,
+    },
+    isTestnet: true,
+    explorerUrl: 'https://testnet.explorer.perawallet.app/tx/{hash}',
+    rpcEndpoints: ['https://testnet-api.algonode.cloud'],
+    eurcAddress: null,
+    usdcAddress: '10458941',
+    cctp: null,
+});
+
+/**
+ * Aptos Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Aptos blockchain.
+ */
+const Aptos = defineChain({
+    type: 'aptos',
+    chain: exports.Blockchain.Aptos,
+    name: 'Aptos',
+    title: 'Aptos Mainnet',
+    nativeCurrency: {
+        name: 'Aptos',
+        symbol: 'APT',
+        decimals: 8,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://explorer.aptoslabs.com/txn/{hash}?network=mainnet',
+    rpcEndpoints: ['https://fullnode.mainnet.aptoslabs.com/v1'],
+    eurcAddress: null,
+    usdcAddress: '0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b',
+    cctp: {
+        domain: 9,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x9bce6734f7b63e835108e3bd8c36743d4709fe435f44791918801d0989640a9d',
+                messageTransmitter: '0x177e17751820e4b4371873ca8c30279be63bdea63b88ed0f2239c2eea10f1772',
+                confirmations: 1,
+            },
+        },
+    },
+});
+
+/**
+ * Aptos Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Aptos blockchain.
+ */
+const AptosTestnet = defineChain({
+    type: 'aptos',
+    chain: exports.Blockchain.Aptos_Testnet,
     name: 'Aptos Testnet',
     title: 'Aptos Test Network',
     nativeCurrency: {
@@ -2363,13 +3124,51 @@ const chainDefinitionSchema$1 = zod.z.discriminatedUnion('type', [
  * chainIdentifierSchema.parse(Ethereum)
  * ```
  */
-const chainIdentifierSchema = zod.z.union([
+zod.z.union([
     zod.z
         .string()
         .refine((val) => val in exports.Blockchain, 'Must be a valid Blockchain enum value as string'),
     zod.z.nativeEnum(exports.Blockchain),
     chainDefinitionSchema$1,
 ]);
+/**
+ * Zod schema for validating bridge chain identifiers.
+ *
+ * This schema validates that the provided chain is supported for CCTPv2 bridging.
+ * It accepts either a BridgeChain enum value, a string matching a BridgeChain value,
+ * or a ChainDefinition for a supported chain.
+ *
+ * Use this schema when validating chain parameters for bridge operations to ensure
+ * only CCTPv2-supported chains are accepted at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { bridgeChainIdentifierSchema } from '@core/chains/validation'
+ * import { BridgeChain, Chains } from '@core/chains'
+ *
+ * // Valid - BridgeChain enum value
+ * bridgeChainIdentifierSchema.parse(BridgeChain.Ethereum)
+ *
+ * // Valid - string literal
+ * bridgeChainIdentifierSchema.parse('Base_Sepolia')
+ *
+ * // Valid - ChainDefinition (validated by CCTP support)
+ * bridgeChainIdentifierSchema.parse(Chains.Solana)
+ *
+ * // Invalid - Algorand is not in BridgeChain (throws ZodError)
+ * bridgeChainIdentifierSchema.parse('Algorand')
+ * ```
+ *
+ * @see {@link BridgeChain} for the enum of supported chains.
+ */
+const bridgeChainIdentifierSchema = zod.z.union([
+    zod.z.string().refine((val) => val in exports.BridgeChain, (val) => ({
+        message: `Chain "${val}" is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
+    })),
+    chainDefinitionSchema$1.refine((chainDef) => chainDef.chain in exports.BridgeChain, (chainDef) => ({
+        message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
+    })),
+]);
 
 /**
  * Retrieve a chain definition by its blockchain enum value.
@@ -2398,1464 +3197,1150 @@ const getChainByEnum = (blockchain) => {
     if (!chain) {
         throw new Error(`No chain definition found for blockchain: ${blockchain}`);
     }
-    return chain;
-};
-
-/**
- * Resolves a flexible chain identifier to a ChainDefinition.
- *
- * This function handles all three supported formats:
- * - ChainDefinition objects (passed through unchanged)
- * - Blockchain enum values (resolved via getChainByEnum)
- * - String literals of blockchain values (resolved via getChainByEnum)
- *
- * @param chainIdentifier - The chain identifier to resolve
- * @returns The resolved ChainDefinition object
- * @throws Error if the chain identifier cannot be resolved
- *
- * @example
- * ```typescript
- * import { resolveChainIdentifier } from '@core/chains'
- * import { Blockchain, Ethereum } from '@core/chains'
- *
- * // All of these resolve to the same ChainDefinition:
- * const chain1 = resolveChainIdentifier(Ethereum)
- * const chain2 = resolveChainIdentifier(Blockchain.Ethereum)
- * const chain3 = resolveChainIdentifier('Ethereum')
- * ```
- */
-function resolveChainIdentifier(chainIdentifier) {
-    // If it's already a ChainDefinition object, return it unchanged
-    if (typeof chainIdentifier === 'object') {
-        return chainIdentifier;
-    }
-    // If it's a string or enum value, resolve it via getChainByEnum
-    if (typeof chainIdentifier === 'string') {
-        return getChainByEnum(chainIdentifier);
-    }
-    // This should never happen with proper typing, but provide a fallback
-    throw new Error(`Invalid chain identifier type: ${typeof chainIdentifier}. Expected ChainDefinition object, Blockchain enum, or string literal.`);
-}
-
-/**
- * Convert a human-readable decimal string to its smallest unit representation.
- *
- * This function converts user-friendly decimal values into the integer representation
- * required by blockchain operations, where all values are stored in the smallest
- * denomination. Uses the battle-tested implementation from @ethersproject/units.
- *
- * @param value - The decimal string to convert (e.g., "1.0")
- * @param decimals - The number of decimal places for the unit conversion
- * @returns The value in smallest units as a bigint (e.g., 1000000n for 1 USDC with 6 decimals)
- * @throws Error if the value is not a valid decimal string
- *
- * @example
- * ```typescript
- * import { parseUnits } from '@core/utils'
- *
- * // Parse USDC (6 decimals)
- * const usdcParsed = parseUnits('1.0', 6)
- * console.log(usdcParsed) // 1000000n
- *
- * // Parse ETH (18 decimals)
- * const ethParsed = parseUnits('1.0', 18)
- * console.log(ethParsed) // 1000000000000000000n
- *
- * // Parse fractional amount
- * const fractionalParsed = parseUnits('1.5', 6)
- * console.log(fractionalParsed) // 1500000n
- *
- * // Parse integer (no decimal point)
- * const integerParsed = parseUnits('42', 6)
- * console.log(integerParsed) // 42000000n
- * ```
- */
-const parseUnits = (value, decimals) => {
-    return units.parseUnits(value, decimals).toBigInt();
-};
-
-/**
- * Custom error class for validation errors.
- * Provides structured error information while hiding implementation details.
- */
-class ValidationError extends Error {
-    errors;
-    constructor(message, errors) {
-        super(message);
-        this.errors = errors;
-        this.name = 'ValidationError';
-    }
-}
-
-/**
- * Formats a Zod error for display.
- * @internal
- */
-const formatZodError = (error) => {
-    const path = error.path.length > 0 ? `${error.path.join('.')}: ` : '';
-    return `${path}${error.message}`;
-};
-/**
- * Validates data against a Zod schema with enhanced error reporting.
- *
- * This function performs validation using Zod schemas and provides detailed error
- * messages that include the validation context. It's designed to give developers
- * clear feedback about what went wrong during validation.
- *
- * @param schema - The Zod schema to validate against
- * @param data - The data to validate
- * @param context - Context string to include in error messages (e.g., 'bridge parameters')
- * @returns The validated and parsed data
- * @throws {ValidationError} If validation fails
- *
- * @example
- * ```typescript
- * const result = validate(BridgeParamsSchema, params, 'bridge parameters')
- * ```
- */
-function validate(value, schema, context) {
-    const result = schema.safeParse(value);
-    if (!result.success) {
-        const errors = result.error.errors.map(formatZodError);
-        const firstError = errors[0] ?? 'Invalid value';
-        throw new ValidationError(`Invalid ${context}: ${firstError}`, errors);
-    }
-}
+    return chain;
+};
 
 /**
- * Symbol used to track validation state on objects.
- * This allows us to attach metadata to objects without interfering with their structure,
- * enabling optimized validation by skipping already validated objects.
- * @internal
- */
-const VALIDATION_STATE = Symbol('validationState');
-/**
- * Validates data against a Zod schema with state tracking and enhanced error reporting.
+ * Resolves a flexible chain identifier to a ChainDefinition.
  *
- * This function performs validation using Zod schemas while tracking validation state
- * and providing detailed error messages. It's designed for use in scenarios where
- * validation state needs to be monitored and reported.
+ * This function handles all three supported formats:
+ * - ChainDefinition objects (passed through unchanged)
+ * - Blockchain enum values (resolved via getChainByEnum)
+ * - String literals of blockchain values (resolved via getChainByEnum)
  *
- * @param schema - The Zod schema to validate against
- * @param data - The data to validate
- * @param context - Context string to include in error messages (e.g., 'bridge parameters')
- * @returns Object containing validation result and state information
- * @throws {ValidationError} If validation fails
+ * @param chainIdentifier - The chain identifier to resolve
+ * @returns The resolved ChainDefinition object
+ * @throws Error if the chain identifier cannot be resolved
  *
  * @example
  * ```typescript
- * const result = validateWithStateTracking(BridgeParamsSchema, params, 'bridge parameters')
+ * import { resolveChainIdentifier } from '@core/chains'
+ * import { Blockchain, Ethereum } from '@core/chains'
+ *
+ * // All of these resolve to the same ChainDefinition:
+ * const chain1 = resolveChainIdentifier(Ethereum)
+ * const chain2 = resolveChainIdentifier(Blockchain.Ethereum)
+ * const chain3 = resolveChainIdentifier('Ethereum')
  * ```
  */
-function validateWithStateTracking(value, schema, context, validatorName) {
-    // Skip validation for null or undefined values
-    if (value === null) {
-        throw new ValidationError(`Invalid ${context}: Value is null`, [
-            `Value is null`,
-        ]);
-    }
-    if (value === undefined) {
-        throw new ValidationError(`Invalid ${context}: Value is undefined`, [
-            `Value is undefined`,
-        ]);
-    }
-    // Ensure value is an object that can hold validation state
-    if (typeof value !== 'object') {
-        throw new ValidationError(`Invalid ${context}: Value must be an object`, [
-            `Value must be an object, got ${typeof value}`,
-        ]);
+function resolveChainIdentifier(chainIdentifier) {
+    // If it's already a ChainDefinition object, return it unchanged
+    if (typeof chainIdentifier === 'object') {
+        return chainIdentifier;
     }
-    // Get or initialize validation state
-    const valueWithState = value;
-    const state = valueWithState[VALIDATION_STATE] ?? { validatedBy: [] };
-    // Skip validation if already validated by this validator
-    if (state.validatedBy.includes(validatorName)) {
-        return;
+    // If it's a string or enum value, resolve it via getChainByEnum
+    if (typeof chainIdentifier === 'string') {
+        return getChainByEnum(chainIdentifier);
     }
-    // Delegate to the validate function for actual validation
-    validate(value, schema, context);
-    // Update validation state
-    state.validatedBy.push(validatorName);
-    valueWithState[VALIDATION_STATE] = state;
+    // This should never happen with proper typing, but provide a fallback
+    throw new Error(`Invalid chain identifier type: ${typeof chainIdentifier}. Expected ChainDefinition object, Blockchain enum, or string literal.`);
 }
 
 /**
- * Zod schema for validating chain definition objects used in buildExplorerUrl.
- * This schema ensures the chain definition has the required properties for URL generation.
- */
-const chainDefinitionSchema = zod.z.object({
-    name: zod.z
-        .string({
-        required_error: 'Chain name is required',
-        invalid_type_error: 'Chain name must be a string',
-    })
-        .min(1, 'Chain name cannot be empty'),
-    explorerUrl: zod.z
-        .string({
-        required_error: 'Explorer URL template is required',
-        invalid_type_error: 'Explorer URL template must be a string',
-    })
-        .min(1, 'Explorer URL template cannot be empty')
-        .refine((url) => url.includes('{hash}'), 'Explorer URL template must contain a {hash} placeholder'),
-});
-/**
- * Zod schema for validating transaction hash strings used in buildExplorerUrl.
- * This schema ensures the transaction hash is a non-empty string.
- */
-const transactionHashSchema = zod.z
-    .string({
-    required_error: 'Transaction hash is required',
-    invalid_type_error: 'Transaction hash must be a string',
-})
-    .min(1, 'Transaction hash cannot be empty')
-    .transform((hash) => hash.trim()) // Automatically trim whitespace
-    .refine((hash) => hash.length > 0, 'Transaction hash must not be empty or whitespace-only');
-/**
- * Zod schema for validating buildExplorerUrl function parameters.
- * This schema validates both the chain definition and transaction hash together.
- */
-zod.z.object({
-    chainDef: chainDefinitionSchema,
-    txHash: transactionHashSchema,
-});
-/**
- * Zod schema for validating the generated explorer URL.
- * This schema ensures the generated URL is valid.
- */
-zod.z
-    .string()
-    .url('Generated explorer URL is invalid');
-
-/**
- * A type-safe event emitter for managing action-based event subscriptions.
+ * Extracts chain information including name, display name, and expected address format.
  *
- * Actionable provides a strongly-typed publish/subscribe pattern for events,
- * where each event (action) has its own specific payload type. Handlers can
- * subscribe to specific events or use a wildcard to receive all events.
+ * This function determines the chain type by checking the explicit `type` property first,
+ * then falls back to name-based matching for Solana chains. The expected address format
+ * is determined based on the chain type:
+ * - EVM chains: 42-character hex address starting with 0x
+ * - Solana chains: 44-character base58 encoded string
+ * - Other chains: Generic format message based on chain type
  *
- * @typeParam AllActions - A record mapping action names to their payload types.
+ * @param chain - The chain identifier (ChainDefinition object, string name, or undefined/null)
+ * @returns Chain information with name, display name, and expected address format
  *
  * @example
  * ```typescript
- * import { Actionable } from '@circle-fin/bridge-kit/utils';
- *
- * // Define your action types
- * type TransferActions = {
- *   started: { txHash: string; amount: string };
- *   completed: { txHash: string; destinationTxHash: string };
- *   failed: { error: Error };
- * };
+ * import { extractChainInfo } from '@core/chains'
  *
- * // Create an actionable instance
- * const transferEvents = new Actionable<TransferActions>();
+ * // EVM chain with explicit type
+ * const info1 = extractChainInfo({ name: 'Ethereum', type: 'evm' })
+ * console.log(info1.name) // → "Ethereum"
+ * console.log(info1.displayName) // → "Ethereum"
+ * console.log(info1.expectedAddressFormat)
+ * // → "42-character hex address starting with 0x"
  *
- * // Subscribe to a specific event
- * transferEvents.on('completed', (payload) => {
- *   console.log(`Transfer completed with hash: ${payload.destinationTxHash}`);
- * });
+ * // Solana chain (inferred from name)
+ * const info2 = extractChainInfo('Solana')
+ * console.log(info2.expectedAddressFormat)
+ * // → "44-character base58 encoded string"
  *
- * // Subscribe to all events
- * transferEvents.on('*', (payload) => {
- *   console.log('Event received:', payload);
- * });
+ * // Non-EVM chain with explicit type
+ * const info3 = extractChainInfo({ name: 'Algorand', type: 'algorand' })
+ * console.log(info3.expectedAddressFormat)
+ * // → "valid algorand address"
  *
- * // Dispatch an event
- * transferEvents.dispatch('completed', {
- *   txHash: '0x123',
- *   destinationTxHash: '0xabc'
- * });
+ * // Unknown chain
+ * const info4 = extractChainInfo(undefined)
+ * console.log(info4.name) // → "unknown"
+ * console.log(info4.expectedAddressFormat) // → "valid blockchain address"
  * ```
  */
-class Actionable {
-    // Store event handlers by action key
-    handlers = {};
-    // Store wildcard handlers that receive all events
-    wildcard = [];
-    // Implementation that handles both overloads
-    on(action, handler) {
-        if (action === '*') {
-            // Add to wildcard handlers array
-            this.wildcard.push(handler);
-        }
-        else {
-            // Initialize the action's handler array if it doesn't exist
-            if (!this.handlers[action]) {
-                this.handlers[action] = [];
-            }
-            // Add the handler to the specific action's array
-            this.handlers[action].push(handler);
-        }
+function extractChainInfo(chain) {
+    const name = typeof chain === 'string' ? chain : (chain?.name ?? 'unknown');
+    const chainType = typeof chain === 'object' && chain !== null ? chain.type : undefined;
+    // Use explicit chain type if available, fallback to name matching
+    const isSolana = chainType === undefined
+        ? name.toLowerCase().includes('solana')
+        : chainType === 'solana';
+    // Default to EVM if not Solana and no explicit non-EVM type
+    const isEVM = chainType === undefined
+        ? !isSolana // Default to EVM for unknown chains (unless they're Solana)
+        : chainType === 'evm';
+    // Determine expected address format based on chain type
+    let expectedAddressFormat;
+    if (isSolana) {
+        expectedAddressFormat = '44-character base58 encoded string';
     }
-    // Implementation that handles both overloads
-    off(action, handler) {
-        if (action === '*') {
-            // Find and remove the handler from wildcard array
-            const index = this.wildcard.indexOf(handler);
-            if (index !== -1) {
-                this.wildcard.splice(index, 1);
-            }
-        }
-        else if (this.handlers[action]) {
-            // Check if there are handlers for this action
-            // Find and remove the specific handler
-            const index = this.handlers[action].indexOf(handler);
-            if (index !== -1) {
-                this.handlers[action].splice(index, 1);
-            }
-        }
+    else if (isEVM) {
+        expectedAddressFormat = '42-character hex address starting with 0x';
     }
-    /**
-     * Dispatch an action with its payload to all registered handlers.
-     *
-     * This method notifies both:
-     * - Handlers registered specifically for this action
-     * - Wildcard handlers registered for all actions
-     *
-     * @param action - The action key identifying the event type.
-     * @param payload - The data associated with the action.
-     *
-     * @example
-     * ```typescript
-     * type Actions = {
-     *   transferStarted: { amount: string; destination: string };
-     *   transferComplete: { txHash: string };
-     * };
-     *
-     * const events = new Actionable<Actions>();
-     *
-     * // Dispatch an event
-     * events.dispatch('transferStarted', {
-     *   amount: '100',
-     *   destination: '0xABC123'
-     * });
-     * ```
-     */
-    dispatch(action, payload) {
-        // Execute all handlers registered for this specific action
-        for (const h of this.handlers[action] ?? [])
-            h(payload);
-        // Execute all wildcard handlers
-        for (const h of this.wildcard)
-            h(payload);
+    else {
+        expectedAddressFormat = `valid ${chainType ?? 'blockchain'} address`;
     }
+    return {
+        name,
+        displayName: name.replaceAll('_', ' '),
+        expectedAddressFormat,
+    };
 }
 
-var name = "@circle-fin/bridge-kit";
-var version = "1.1.1";
-var pkg = {
-	name: name,
-	version: version};
-
 /**
- * Valid recoverability values for error handling strategies.
+ * Type guard to check if an error is a KitError instance.
  *
- * - FATAL errors are thrown immediately (invalid inputs, insufficient funds)
- * - RETRYABLE errors are returned when a flow fails to start but could work later
- * - RESUMABLE errors are returned when a flow fails mid-execution but can be continued
- */
-const RECOVERABILITY_VALUES = [
-    'RETRYABLE',
-    'RESUMABLE',
-    'FATAL',
-];
-
-// Create a mutable array for Zod enum validation
-const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
-/**
- * Zod schema for validating ErrorDetails objects.
+ * This guard enables TypeScript to narrow the type from `unknown` to
+ * `KitError`, providing access to structured error properties like
+ * code, name, and recoverability.
  *
- * This schema provides runtime validation for all ErrorDetails properties,
- * ensuring type safety and proper error handling for JavaScript consumers.
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with proper type narrowing
  *
  * @example
  * ```typescript
- * import { errorDetailsSchema } from '@core/errors'
- *
- * const result = errorDetailsSchema.safeParse({
- *   code: 1001,
- *   name: 'NETWORK_MISMATCH',
- *   recoverability: 'FATAL',
- *   message: 'Source and destination networks must be different'
- * })
+ * import { isKitError } from '@core/errors'
  *
- * if (!result.success) {
- *   console.error('Validation failed:', result.error.issues)
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isKitError(error)) {
+ *     // TypeScript knows this is KitError
+ *     console.log(`Structured error: ${error.name} (${error.code})`)
+ *   } else {
+ *     console.log('Regular error:', error)
+ *   }
  * }
  * ```
  */
-const errorDetailsSchema = zod.z.object({
-    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
-    code: zod.z
-        .number()
-        .int('Error code must be an integer')
-        .min(1000, 'Error code must be within valid range (1000+)')
-        .max(1099, 'Error code must be within valid range (1099 max)'),
-    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
-    name: zod.z
-        .string()
-        .min(1, 'Error name must be a non-empty string')
-        .regex(/^[A-Z_][A-Z0-9_]*$/, 'Error name must match pattern: ^[A-Z_][A-Z0-9_]*$'),
-    /** Error handling strategy */
-    recoverability: zod.z.enum(RECOVERABILITY_ARRAY, {
-        errorMap: () => ({
-            message: 'Recoverability must be one of: RETRYABLE, RESUMABLE, FATAL',
-        }),
-    }),
-    /** User-friendly explanation with network context */
-    message: zod.z
-        .string()
-        .min(1, 'Error message must be a non-empty string')
-        .max(500, 'Error message must be 500 characters or less'),
-    /** Raw error details, context, or the original error that caused this one. */
-    cause: zod.z
-        .object({
-        /** Free-form error payload from underlying system */
-        trace: zod.z.unknown().optional(),
-    })
-        .optional(),
-});
-
+function isKitError(error) {
+    return error instanceof KitError;
+}
 /**
- * Validates an ErrorDetails object using Zod schema.
+ * Checks if an error is a KitError with FATAL recoverability.
  *
- * @param details - The object to validate
- * @returns The validated ErrorDetails object
- * @throws {TypeError} When validation fails
+ * FATAL errors indicate issues that cannot be resolved through retries,
+ * such as invalid inputs, configuration problems, or business rule
+ * violations. These errors require user intervention to fix.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is a KitError with FATAL recoverability
  *
  * @example
  * ```typescript
- * import { validateErrorDetails } from '@core/errors'
+ * import { isFatalError } from '@core/errors'
  *
  * try {
- *   const validDetails = validateErrorDetails({
- *     code: 1001,
- *     name: 'NETWORK_MISMATCH',
- *     recoverability: 'FATAL',
- *     message: 'Source and destination networks must be different'
- *   })
+ *   await kit.bridge(params)
  * } catch (error) {
- *   console.error('Validation failed:', error.message)
+ *   if (isFatalError(error)) {
+ *     // Show user-friendly error message - don't retry
+ *     showUserError(error.message)
+ *   }
  * }
  * ```
  */
-function validateErrorDetails(details) {
-    const result = errorDetailsSchema.safeParse(details);
-    if (!result.success) {
-        const issues = result.error.issues
-            .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
-            .join(', ');
-        throw new TypeError(`Invalid ErrorDetails: ${issues}`);
-    }
-    return result.data;
+function isFatalError(error) {
+    return isKitError(error) && error.recoverability === 'FATAL';
 }
-
 /**
- * Structured error class for Stablecoin Kit operations.
+ * Checks if an error is a KitError with RETRYABLE recoverability.
  *
- * 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
- * error objects cannot be modified after creation.
+ * RETRYABLE errors indicate transient failures that may succeed on
+ * subsequent attempts, such as network timeouts or temporary service
+ * unavailability. These errors are safe to retry after a delay.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is a KitError with RETRYABLE recoverability
  *
  * @example
  * ```typescript
- * import { KitError } from '@core/errors'
- *
- * const error = new KitError({
- *   code: 1001,
- *   name: 'INPUT_NETWORK_MISMATCH',
- *   recoverability: 'FATAL',
- *   message: 'Cannot bridge between mainnet and testnet'
- * })
+ * import { isRetryableError } from '@core/errors'
  *
- * if (error instanceof KitError) {
- *   console.log(`Error ${error.code}: ${error.name}`)
- *   // → "Error 1001: INPUT_NETWORK_MISMATCH"
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     // Implement retry logic with exponential backoff
+ *     setTimeout(() => retryOperation(), 5000)
+ *   }
  * }
  * ```
+ */
+function isRetryableError(error) {
+    return isKitError(error) && error.recoverability === 'RETRYABLE';
+}
+/**
+ * Type guard to check if error is KitError with INPUT type.
+ *
+ * INPUT errors represent validation failures, invalid parameters,
+ * or user input problems. These errors are always FATAL and require
+ * the user to correct their input before retrying.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with INPUT type
  *
  * @example
  * ```typescript
- * import { KitError } from '@core/errors'
+ * import { isInputError } from '@core/errors'
  *
- * // Error with cause information
- * const error = new KitError({
- *   code: 1002,
- *   name: 'INVALID_AMOUNT',
- *   recoverability: 'FATAL',
- *   message: 'Amount must be greater than zero',
- *   cause: {
- *     trace: { providedAmount: -100, minimumAmount: 0 }
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isInputError(error)) {
+ *     console.log('Validation error:', error.message)
+ *     showValidationUI()
  *   }
- * })
- *
- * throw error
+ * }
  * ```
  */
-class KitError extends Error {
-    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
-    code;
-    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
-    name;
-    /** Error handling strategy */
-    recoverability;
-    /** Raw error details, context, or the original error that caused this one. */
-    cause;
-    /**
-     * Create a new KitError instance.
-     *
-     * @param details - The error details object containing all required properties.
-     * @throws \{TypeError\} When details parameter is missing or invalid.
-     */
-    constructor(details) {
-        // Validate input at runtime for JavaScript consumers using Zod
-        const validatedDetails = validateErrorDetails(details);
-        super(validatedDetails.message);
-        // Set properties as readonly at runtime
-        Object.defineProperties(this, {
-            name: {
-                value: validatedDetails.name,
-                writable: false,
-                enumerable: true,
-                configurable: false,
-            },
-            code: {
-                value: validatedDetails.code,
-                writable: false,
-                enumerable: true,
-                configurable: false,
-            },
-            recoverability: {
-                value: validatedDetails.recoverability,
-                writable: false,
-                enumerable: true,
-                configurable: false,
-            },
-            ...(validatedDetails.cause && {
-                cause: {
-                    value: validatedDetails.cause,
-                    writable: false,
-                    enumerable: true,
-                    configurable: false,
-                },
-            }),
-        });
-    }
+function isInputError(error) {
+    return isKitError(error) && error.type === ERROR_TYPES.INPUT;
 }
-
 /**
- * Minimum error code for INPUT type errors.
- * INPUT errors represent validation failures and invalid parameters.
- */
-const INPUT_ERROR_CODE_MIN = 1000;
-/**
- * Maximum error code for INPUT type errors (exclusive).
- * INPUT error codes range from 1000 to 1099 inclusive.
- */
-const INPUT_ERROR_CODE_MAX = 1100;
-/**
- * Standardized error definitions for INPUT type errors.
- *
- * Each entry combines the numeric error code with its corresponding
- * string name to ensure consistency when creating error instances.
+ * Safely extracts error message from any error type.
  *
- * Error codes follow a hierarchical numbering scheme where the first digit
- * indicates the error category (1 = INPUT) and subsequent digits provide
- * specific error identification within that category.
+ * This utility handles different error types gracefully, extracting
+ * meaningful messages from Error instances, string errors, or providing
+ * a fallback for unknown error types. Never throws.
  *
+ * @param error - Unknown error to extract message from
+ * @returns Error message string, or fallback message
  *
  * @example
  * ```typescript
- * import { InputError } from '@core/errors'
- *
- * const error = new KitError({
- *   ...InputError.NETWORK_MISMATCH,
- *   recoverability: 'FATAL',
- *   message: 'Source and destination networks must be different'
- * })
+ * import { getErrorMessage } from '@core/errors'
  *
- * // Access code and name individually if needed
- * console.log(InputError.NETWORK_MISMATCH.code)  // 1001
- * console.log(InputError.NETWORK_MISMATCH.name)  // 'INPUT_NETWORK_MISMATCH'
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   const message = getErrorMessage(error)
+ *   console.log('Error occurred:', message)
+ *   // Works with Error, KitError, string, or any other type
+ * }
  * ```
  */
-const InputError = {
-    /** Network type mismatch between chains (mainnet vs testnet) */
-    NETWORK_MISMATCH: {
-        code: 1001,
-        name: 'INPUT_NETWORK_MISMATCH',
-    },
-    /** Invalid amount format or value (negative, zero, or malformed) */
-    INVALID_AMOUNT: {
-        code: 1002,
-        name: 'INPUT_INVALID_AMOUNT',
-    },
-    /** Unsupported or invalid bridge route configuration */
-    UNSUPPORTED_ROUTE: {
-        code: 1003,
-        name: 'INPUT_UNSUPPORTED_ROUTE',
-    },
-    /** Invalid wallet or contract address format */
-    INVALID_ADDRESS: {
-        code: 1004,
-        name: 'INPUT_INVALID_ADDRESS',
-    },
-    /** Invalid or unsupported chain identifier */
-    INVALID_CHAIN: {
-        code: 1005,
-        name: 'INPUT_INVALID_CHAIN',
-    },
-    /** General validation failure for complex validation rules */
-    VALIDATION_FAILED: {
-        code: 1098,
-        name: 'INPUT_VALIDATION_FAILED',
-    },
-};
-
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'An unknown error occurred';
+}
 /**
- * Creates error for network type mismatch between source and destination.
+ * Gets the error code from a KitError, or null if not applicable.
  *
- * This error is thrown when attempting to bridge between chains that have
- * different network types (e.g., mainnet to testnet), which is not supported
- * for security reasons.
+ * This utility safely extracts the numeric error code from KitError
+ * instances, returning null for non-KitError types. Useful for
+ * programmatic error handling based on specific error codes.
  *
- * @param sourceChain - The source chain definition
- * @param destChain - The destination chain definition
- * @returns KitError with specific network mismatch details
+ * @param error - Unknown error to extract code from
+ * @returns Error code number, or null if not a KitError
  *
  * @example
  * ```typescript
- * import { createNetworkMismatchError } from '@core/errors'
- * import { Ethereum, BaseSepolia } from '@core/chains'
+ * import { getErrorCode, InputError } from '@core/errors'
  *
- * // This will throw a detailed error
- * throw createNetworkMismatchError(Ethereum, BaseSepolia)
- * // Message: "Cannot bridge between Ethereum (mainnet) and Base Sepolia (testnet). Source and destination networks must both be testnet or both be mainnet."
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   const code = getErrorCode(error)
+ *   if (code === InputError.NETWORK_MISMATCH.code) {
+ *     // Handle network mismatch specifically
+ *     showNetworkMismatchHelp()
+ *   }
+ * }
  * ```
  */
-function createNetworkMismatchError(sourceChain, destChain) {
-    const sourceNetworkType = sourceChain.isTestnet ? 'testnet' : 'mainnet';
-    const destNetworkType = destChain.isTestnet ? 'testnet' : 'mainnet';
-    const errorDetails = {
-        ...InputError.NETWORK_MISMATCH,
-        recoverability: 'FATAL',
-        message: `Cannot bridge between ${sourceChain.name} (${sourceNetworkType}) and ${destChain.name} (${destNetworkType}). Source and destination networks must both be testnet or both be mainnet.`,
-        cause: {
-            trace: { sourceChain: sourceChain.name, destChain: destChain.name },
-        },
-    };
-    return new KitError(errorDetails);
+function getErrorCode(error) {
+    return isKitError(error) ? error.code : null;
 }
+
 /**
- * Creates error for unsupported bridge route.
+ * Validates if an address format is correct for the specified chain.
  *
- * This error is thrown when attempting to bridge between chains that don't
- * have a supported bridge route configured.
+ * This function checks the explicit chain `type` property first, then falls back
+ * to name-based matching to determine whether to validate as a Solana or EVM address.
  *
- * @param source - Source chain name
- * @param destination - Destination chain name
- * @returns KitError with specific route details
+ * @param address - The address to validate
+ * @param chain - The chain identifier or chain definition (cannot be null)
+ * @returns True if the address format is valid for the chain, false otherwise
  *
  * @example
  * ```typescript
- * import { createUnsupportedRouteError } from '@core/errors'
+ * import { isValidAddressForChain } from '@core/errors'
  *
- * throw createUnsupportedRouteError('Ethereum', 'Solana')
- * // Message: "Route from Ethereum to Solana is not supported"
+ * // EVM address validation
+ * isValidAddressForChain('0x742d35Cc6634C0532925a3b8D0C0C1C4C5C6C7C8', 'Ethereum')
+ * // → true
+ *
+ * // Solana address validation
+ * isValidAddressForChain('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM', { name: 'Solana', type: 'solana' })
+ * // → true
+ *
+ * // Invalid format
+ * isValidAddressForChain('invalid', 'Ethereum')
+ * // → false
  * ```
  */
-function createUnsupportedRouteError(source, destination) {
-    const errorDetails = {
-        ...InputError.UNSUPPORTED_ROUTE,
-        recoverability: 'FATAL',
-        message: `Route from ${source} to ${destination} is not supported.`,
-        cause: {
-            trace: { source, destination },
-        },
-    };
-    return new KitError(errorDetails);
+function isValidAddressForChain(address, chain) {
+    const chainType = typeof chain === 'object' ? chain.type : undefined;
+    const name = typeof chain === 'string' ? chain : chain.name;
+    // Use explicit chain type if available, fallback to name matching
+    const isSolana = chainType !== undefined
+        ? chainType === 'solana'
+        : name.toLowerCase().includes('solana');
+    if (isSolana) {
+        // Solana base58 address: 32-44 characters from base58 alphabet
+        return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(address);
+    }
+    // EVM hex address: 0x followed by 40 hex characters
+    return /^0x[a-fA-F0-9]{40}$/.test(address);
 }
 /**
- * Creates error for invalid amount format or precision.
+ * Type guard to check if a value is an object.
  *
- * This error is thrown when the provided amount doesn't meet validation
- * requirements such as precision, range, or format.
+ * @param val - The value to check
+ * @returns True if the value is a non-null object
+ */
+function isObject(val) {
+    return typeof val === 'object' && val !== null;
+}
+/**
+ * Type guard to check if a value is a chain with isTestnet property.
  *
- * @param amount - The invalid amount string
- * @param reason - Specific reason why amount is invalid
- * @returns KitError with amount details and validation rule
+ * @param chain - The value to check
+ * @returns True if the value is a chain object with name and isTestnet properties
  *
  * @example
  * ```typescript
- * import { createInvalidAmountError } from '@core/errors'
+ * import { isChainWithTestnet } from '@core/errors'
  *
- * throw createInvalidAmountError('0.000001', 'Amount must be at least 0.01 USDC')
- * // Message: "Invalid amount '0.000001': Amount must be at least 0.01 USDC"
+ * const chain1 = { name: 'Ethereum', isTestnet: false }
+ * isChainWithTestnet(chain1) // → true
+ *
+ * const chain2 = { name: 'Ethereum' }
+ * isChainWithTestnet(chain2) // → false
  *
- * throw createInvalidAmountError('abc', 'Amount must be a valid number')
- * // Message: "Invalid amount 'abc': Amount must be a valid number"
+ * const chain3 = 'Ethereum'
+ * isChainWithTestnet(chain3) // → false
  * ```
  */
-function createInvalidAmountError(amount, reason) {
-    const errorDetails = {
-        ...InputError.INVALID_AMOUNT,
-        recoverability: 'FATAL',
-        message: `Invalid amount '${amount}': ${reason}.`,
-        cause: {
-            trace: { amount, reason },
-        },
-    };
-    return new KitError(errorDetails);
+function isChainWithTestnet(chain) {
+    return (isObject(chain) &&
+        'isTestnet' in chain &&
+        typeof chain['isTestnet'] === 'boolean' &&
+        'name' in chain &&
+        typeof chain['name'] === 'string');
 }
 /**
- * Creates error for invalid wallet address format.
+ * Gets chain identifier from toData object.
  *
- * This error is thrown when the provided address doesn't match the expected
- * format for the specified chain.
+ * Looks for chain in context.chain first, then falls back to direct chain property.
  *
- * @param address - The invalid address string
- * @param chain - Chain name where address is invalid
- * @param expectedFormat - Description of expected address format
- * @returns KitError with address details and format requirements
+ * @param toData - The destination data object
+ * @returns The chain identifier or null
+ */
+function getChainFromToData(toData) {
+    const context = toData['context'];
+    const chain = context?.['chain'] ?? toData['chain'];
+    return chain;
+}
+/**
+ * Gets chain name from params object.
  *
- * @example
- * ```typescript
- * import { createInvalidAddressError } from '@core/errors'
+ * @param params - The parameters object
+ * @returns The chain name as a string, or null if not found
+ */
+function getChainName(params) {
+    if (isObject(params)) {
+        const chain = params['chain'];
+        if (typeof chain === 'string') {
+            return chain;
+        }
+        if (isObject(chain) && 'name' in chain) {
+            return chain.name;
+        }
+    }
+    return null;
+}
+/**
+ * Extracts from data from params object.
  *
- * throw createInvalidAddressError('0x123', 'Ethereum', '42-character hex string starting with 0x')
- * // Message: "Invalid address '0x123' for Ethereum. Expected 42-character hex string starting with 0x."
+ * Supports both 'from' and 'source' property names.
  *
- * throw createInvalidAddressError('invalid', 'Solana', 'base58-encoded string')
- * // Message: "Invalid address 'invalid' for Solana. Expected base58-encoded string."
- * ```
+ * @param params - The parameters object
+ * @returns The from/source data or undefined
  */
-function createInvalidAddressError(address, chain, expectedFormat) {
-    const errorDetails = {
-        ...InputError.INVALID_ADDRESS,
-        recoverability: 'FATAL',
-        message: `Invalid address '${address}' for ${chain}. Expected ${expectedFormat}.`,
-        cause: {
-            trace: { address, chain, expectedFormat },
-        },
-    };
-    return new KitError(errorDetails);
+function extractFromData(params) {
+    return (params['from'] ?? params['source']);
 }
 /**
- * Creates error for invalid chain configuration.
+ * Extracts to data from params object.
  *
- * This error is thrown when the provided chain doesn't meet the required
- * configuration or is not supported for the operation.
+ * Supports both 'to' and 'destination' property names.
  *
- * @param chain - The invalid chain name or identifier
- * @param reason - Specific reason why chain is invalid
- * @returns KitError with chain details and validation rule
+ * @param params - The parameters object
+ * @returns The to/destination data or undefined
+ */
+function extractToData(params) {
+    return (params['to'] ?? params['destination']);
+}
+/**
+ * Gets address from params object using a dot-separated path.
+ *
+ * Traverses nested objects to extract the address value at the specified path.
+ *
+ * @param params - The parameters object
+ * @param path - Dot-separated path to extract address from (e.g., 'to.recipientAddress')
+ * @returns The address as a string, or 'unknown' if not found
  *
  * @example
  * ```typescript
- * import { createInvalidChainError } from '@core/errors'
- *
- * throw createInvalidChainError('UnknownChain', 'Chain is not supported by this bridge')
- * // Message: "Invalid chain 'UnknownChain': Chain is not supported by this bridge"
+ * // Extract from specific path
+ * getAddressFromParams(params, 'to.recipientAddress')
+ * // Returns the value at params.to.recipientAddress
  * ```
  */
-function createInvalidChainError(chain, reason) {
-    const errorDetails = {
-        ...InputError.INVALID_CHAIN,
-        recoverability: 'FATAL',
-        message: `Invalid chain '${chain}': ${reason}`,
-        cause: {
-            trace: { chain, reason },
-        },
-    };
-    return new KitError(errorDetails);
+function getAddressFromParams(params, path) {
+    const parts = path.split('.');
+    let current = params;
+    for (const part of parts) {
+        if (current !== null &&
+            current !== undefined &&
+            typeof current === 'object' &&
+            part in current) {
+            current = current[part];
+        }
+        else {
+            return 'unknown';
+        }
+    }
+    return typeof current === 'string' ? current : 'unknown';
+}
+/**
+ * Gets chain identifier from params object.
+ *
+ * Looks for chain in to.context.chain, to.chain, or direct chain property.
+ *
+ * @param params - The parameters object
+ * @returns The chain identifier or null
+ */
+function getChainFromParams(params) {
+    const to = extractToData(params);
+    const chain = to?.['chain'] ?? params['chain'];
+    return chain;
 }
 
 /**
- * Type guard to check if an error is a KitError instance.
- *
- * This guard enables TypeScript to narrow the type from `unknown` to
- * `KitError`, providing access to structured error properties like
- * code, name, and recoverability.
- *
- * @param error - Unknown error to check
- * @returns True if error is KitError with proper type narrowing
+ * Converts a Zod validation error into a specific KitError instance using structured pattern matching.
  *
- * @example
- * ```typescript
- * import { isKitError } from '@core/errors'
+ * This function inspects Zod's error details (path, code, message) and delegates each issue
+ * to specialized handlers that generate domain-specific KitError objects. It leverages
+ * Zod's error codes and path information for robust matching, avoiding fragile string checks.
  *
- * try {
- *   await kit.bridge(params)
- * } catch (error) {
- *   if (isKitError(error)) {
- *     // TypeScript knows this is KitError
- *     console.log(`Structured error: ${error.name} (${error.code})`)
- *   } else {
- *     console.log('Regular error:', error)
- *   }
- * }
- * ```
+ * @param zodError - The Zod validation error containing one or more issues
+ * @param params - The original parameters that failed validation (used to extract invalid values)
+ * @returns A specific KitError instance with actionable error details
  */
-function isKitError(error) {
-    return error instanceof KitError;
+function convertZodErrorToStructured(zodError, params) {
+    // Handle null/undefined params gracefully
+    if (params === null || params === undefined) {
+        return createValidationFailedError(zodError);
+    }
+    const paramsObj = params;
+    const toData = extractToData(paramsObj);
+    const fromData = extractFromData(paramsObj);
+    for (const issue of zodError.issues) {
+        const path = issue.path.join('.');
+        const code = issue.code;
+        // Try to handle specific error types
+        const amountError = handleAmountError(path, code, issue.message, paramsObj);
+        if (amountError)
+            return amountError;
+        const chainError = handleChainError(path, code, issue.message, fromData, toData);
+        if (chainError)
+            return chainError;
+        const addressError = handleAddressError(path, code, issue.message, paramsObj);
+        if (addressError)
+            return addressError;
+    }
+    // Fallback
+    return createValidationFailedError(zodError);
 }
 /**
- * Checks if an error is a KitError with FATAL recoverability.
- *
- * FATAL errors indicate issues that cannot be resolved through retries,
- * such as invalid inputs, configuration problems, or business rule
- * violations. These errors require user intervention to fix.
+ * Creates a generic validation failed error for null/undefined params or unmapped error cases.
  *
- * @param error - Unknown error to check
- * @returns True if error is a KitError with FATAL recoverability
+ * This is a fallback handler used when:
+ * - Parameters are null or undefined
+ * - No specific error handler matches the Zod error
+ * - The error doesn't fit into amount/chain/address categories
  *
- * @example
- * ```typescript
- * import { isFatalError } from '@core/errors'
+ * This function delegates to createValidationErrorFromZod with a generic "parameters" context.
  *
- * try {
- *   await kit.bridge(params)
- * } catch (error) {
- *   if (isFatalError(error)) {
- *     // Show user-friendly error message - don't retry
- *     showUserError(error.message)
- *   }
- * }
- * ```
+ * @param zodError - The Zod validation error with all issues
+ * @returns A generic KitError with INPUT_VALIDATION_FAILED code
  */
-function isFatalError(error) {
-    return isKitError(error) && error.recoverability === 'FATAL';
+function createValidationFailedError(zodError) {
+    return createValidationErrorFromZod(zodError, 'parameters');
 }
+const AMOUNT_FORMAT_ERROR_MESSAGE = 'Amount must be a numeric string with dot (.) as decimal separator, with no thousand separators or comma decimals';
 /**
- * Checks if an error is a KitError with RETRYABLE recoverability.
- *
- * RETRYABLE errors indicate transient failures that may succeed on
- * subsequent attempts, such as network timeouts or temporary service
- * unavailability. These errors are safe to retry after a delay.
- *
- * @param error - Unknown error to check
- * @returns True if error is a KitError with RETRYABLE recoverability
+ * Handles amount-related validation errors from Zod.
  *
- * @example
- * ```typescript
- * import { isRetryableError } from '@core/errors'
+ * Checks if the validation error path includes 'amount' and attempts
+ * to convert generic Zod errors into specific KitError instances with
+ * actionable messages. Delegates to specialized handlers in order of specificity:
+ * 1. Negative amount errors (too_small)
+ * 2. Custom validation errors (decimal places, numeric string)
+ * 3. Invalid string format errors
+ * 4. Invalid type errors
  *
- * try {
- *   await kit.bridge(params)
- * } catch (error) {
- *   if (isRetryableError(error)) {
- *     // Implement retry logic with exponential backoff
- *     setTimeout(() => retryOperation(), 5000)
- *   }
- * }
- * ```
+ * @param path - The Zod error path (e.g., 'amount' or 'config.amount')
+ * @param code - The Zod error code (e.g., 'too_small', 'invalid_string', 'custom')
+ * @param message - The original Zod error message
+ * @param paramsObj - The original params object for extracting the invalid amount value
+ * @returns KitError with INPUT_INVALID_AMOUNT code if this is an amount error, null otherwise
  */
-function isRetryableError(error) {
-    return isKitError(error) && error.recoverability === 'RETRYABLE';
+function handleAmountError(path, code, message, paramsObj) {
+    if (!path.includes('amount'))
+        return null;
+    const amount = typeof paramsObj['amount'] === 'string' ? paramsObj['amount'] : 'unknown';
+    // Try different error handlers in order of specificity
+    const negativeError = handleNegativeAmountError(code, message, amount);
+    if (negativeError)
+        return negativeError;
+    const customError = handleCustomAmountError(code, message, amount);
+    if (customError)
+        return customError;
+    const stringFormatError = handleInvalidStringAmountError(code, message, amount);
+    if (stringFormatError)
+        return stringFormatError;
+    const typeError = handleInvalidTypeAmountError(code, amount);
+    if (typeError)
+        return typeError;
+    return null;
 }
 /**
- * Combined type guard to check if error is KitError with INPUT type.
- *
- * INPUT errors have error codes in the 1000-1099 range and represent
- * validation failures, invalid parameters, or user input problems.
- * These errors are always FATAL and require the user to correct their
- * input before retrying.
+ * Handles negative or too-small amount validation errors.
  *
- * @param error - Unknown error to check
- * @returns True if error is KitError with INPUT error code range
+ * Detects Zod 'too_small' error codes or messages containing 'greater than'
+ * and creates a specific error indicating the amount must be positive.
  *
- * @example
- * ```typescript
- * import { isInputError } from '@core/errors'
- * import { createBridgeKit } from '@core/bridge'
+ * @param code - The Zod error code
+ * @param message - The Zod error message
+ * @param amount - The invalid amount value as a string
+ * @returns KitError if this is a negative/too-small amount error, null otherwise
+ */
+function handleNegativeAmountError(code, message, amount) {
+    if (code === 'too_small' || message.includes('greater than')) {
+        return createInvalidAmountError(amount, 'Amount must be greater than 0');
+    }
+    return null;
+}
+/**
+ * Handles custom Zod refinement validation errors for amounts.
  *
- * async function handleBridge() {
- *   const kit = createBridgeKit(config)
- *   const params = { amount: '100', from: 'ethereum', to: 'polygon' }
+ * Processes Zod 'custom' error codes from .refine() validators and matches
+ * against known patterns:
+ * - 'non-negative' - amount must be \>= 0
+ * - 'decimal places' - too many decimal places
+ * - 'numeric string' - value is not a valid numeric string
  *
- *   try {
- *     await kit.bridge(params)
- *   } catch (error) {
- *     if (isInputError(error)) {
- *       console.log(`Input error: ${error.message} (code: ${error.code})`)
- *     }
- *   }
- * }
- * ```
+ * @param code - The Zod error code (must be 'custom')
+ * @param message - The custom error message from the refinement
+ * @param amount - The invalid amount value as a string
+ * @returns KitError with specific message if pattern matches, null otherwise
  */
-function isInputError(error) {
-    return (isKitError(error) &&
-        error.code >= INPUT_ERROR_CODE_MIN &&
-        error.code < INPUT_ERROR_CODE_MAX);
+function handleCustomAmountError(code, message, amount) {
+    if (code !== 'custom')
+        return null;
+    if (message.includes('non-negative')) {
+        return createInvalidAmountError(amount, 'Amount must be non-negative');
+    }
+    if (message.includes('greater than 0')) {
+        return createInvalidAmountError(amount, 'Amount must be greater than 0');
+    }
+    if (message.includes('decimal places')) {
+        return createInvalidAmountError(amount, message);
+    }
+    if (message.includes('numeric string')) {
+        return createInvalidAmountError(amount, AMOUNT_FORMAT_ERROR_MESSAGE);
+    }
+    return null;
 }
 /**
- * Safely extracts error message from any error type.
- *
- * This utility handles different error types gracefully, extracting
- * meaningful messages from Error instances, string errors, or providing
- * a fallback for unknown error types. Never throws.
+ * Handles Zod 'invalid_string' errors for amount values.
  *
- * @param error - Unknown error to extract message from
- * @returns Error message string, or fallback message
+ * Processes string validation failures (e.g., regex mismatches) and categorizes them:
+ * 1. Negative numbers that pass Number() but fail other validations
+ * 2. Decimal places validation failures (too many decimal places)
+ * 3. Numeric format validation failures (invalid characters, comma decimals, thousand separators)
+ * 4. Generic invalid number strings (must use dot decimal notation)
  *
- * @example
- * ```typescript
- * import { getErrorMessage } from '@core/errors'
+ * Note: The SDK enforces strict dot-decimal notation. Comma decimals (e.g., "1,5") and
+ * thousand separators (e.g., "1,000.50") are not allowed. UI layers should normalize
+ * locale-specific formats before passing values to the SDK.
  *
- * try {
- *   await riskyOperation()
- * } catch (error) {
- *   const message = getErrorMessage(error)
- *   console.log('Error occurred:', message)
- *   // Works with Error, KitError, string, or any other type
- * }
- * ```
+ * @param code - The Zod error code (must be 'invalid_string')
+ * @param message - The Zod error message from string validation
+ * @param amount - The invalid amount value as a string
+ * @returns KitError with context-specific message if pattern matches, null otherwise
  */
-function getErrorMessage(error) {
-    if (error instanceof Error) {
-        return error.message;
+function handleInvalidStringAmountError(code, message, amount) {
+    if (code !== 'invalid_string')
+        return null;
+    // Check for decimal places validation
+    if (isDecimalPlacesError(message)) {
+        return createInvalidAmountError(amount, 'Maximum supported decimal places: 6');
     }
-    if (typeof error === 'string') {
-        return error;
+    // Check for numeric format validation
+    if (isNumericFormatError(message)) {
+        return createInvalidAmountError(amount, AMOUNT_FORMAT_ERROR_MESSAGE);
     }
-    return 'An unknown error occurred';
+    // For other cases like 'abc', return specific error
+    if (!message.includes('valid number format')) {
+        return createInvalidAmountError(amount, AMOUNT_FORMAT_ERROR_MESSAGE);
+    }
+    return null;
 }
 /**
- * Gets the error code from a KitError, or null if not applicable.
+ * Handles Zod 'invalid_type' errors for amount values.
  *
- * This utility safely extracts the numeric error code from KitError
- * instances, returning null for non-KitError types. Useful for
- * programmatic error handling based on specific error codes.
+ * Triggered when the amount is not a string type (e.g., number, boolean, object).
+ * Creates an error indicating the amount must be a string representation of a number
+ * using strict dot-decimal notation (no comma decimals or thousand separators).
  *
- * @param error - Unknown error to extract code from
- * @returns Error code number, or null if not a KitError
+ * @param code - The Zod error code (must be 'invalid_type')
+ * @param amount - The invalid amount value (will be converted to string for error message)
+ * @returns KitError if this is a type mismatch, null otherwise
+ */
+function handleInvalidTypeAmountError(code, amount) {
+    if (code === 'invalid_type') {
+        return createInvalidAmountError(amount, AMOUNT_FORMAT_ERROR_MESSAGE);
+    }
+    return null;
+}
+/**
+ * Checks if an error message indicates a decimal places validation failure.
  *
- * @example
- * ```typescript
- * import { getErrorCode, InputError } from '@core/errors'
+ * Looks for keywords like 'maximum', 'at most', and 'decimal places' to identify
+ * errors related to too many decimal digits in an amount value.
  *
- * try {
- *   await kit.bridge(params)
- * } catch (error) {
- *   const code = getErrorCode(error)
- *   if (code === InputError.NETWORK_MISMATCH.code) {
- *     // Handle network mismatch specifically
- *     showNetworkMismatchHelp()
- *   }
- * }
- * ```
+ * @param message - The error message to analyze
+ * @returns True if the message indicates a decimal places error, false otherwise
  */
-function getErrorCode(error) {
-    return isKitError(error) ? error.code : null;
+function isDecimalPlacesError(message) {
+    return ((message.includes('maximum') || message.includes('at most')) &&
+        message.includes('decimal places'));
 }
-
 /**
- * Extracts chain information including name, display name, and expected address format.
+ * Checks if an error message indicates a numeric format validation failure.
  *
- * This function determines the chain type by checking the explicit `type` property first,
- * then falls back to name-based matching. This approach is more robust than relying solely
- * on string matching and future-proofs the code for new chain ecosystems.
+ * Identifies errors where a value contains 'numeric' but is not specifically
+ * about 'valid number format' or 'numeric string' (to avoid false positives).
  *
- * @param chain - The chain identifier (string, chain object, or undefined/null)
- * @returns Chain information with name, display name, and expected address format
+ * @param message - The error message to analyze
+ * @returns True if the message indicates a numeric format error, false otherwise
+ */
+function isNumericFormatError(message) {
+    return (message.includes('numeric') &&
+        !message.includes('valid number format') &&
+        !message.includes('numeric string'));
+}
+/**
+ * Handles chain-related validation errors from Zod.
  *
- * @example
- * ```typescript
- * import { extractChainInfo } from '@core/errors'
+ * Checks if the validation error path includes 'chain' and extracts the
+ * chain name from either the source (from) or destination (to) data.
+ * Creates a KitError with the invalid chain name and original error message.
  *
- * // With chain object
- * const info1 = extractChainInfo({ name: 'Ethereum', type: 'evm' })
- * console.log(info1.expectedAddressFormat)
- * // → "42-character hex address starting with 0x"
+ * @param path - The Zod error path (e.g., 'from.chain' or 'to.chain')
+ * @param _code - The Zod error code (unused, prefixed with _ to indicate intentionally ignored)
+ * @param message - The original Zod error message
+ * @param fromData - The source/from data object (may contain chain info)
+ * @param toData - The destination/to data object (may contain chain info)
+ * @returns KitError with INPUT_INVALID_CHAIN code if this is a chain error, null otherwise
+ */
+function handleChainError(path, _code, message, fromData, toData) {
+    if (!path.includes('chain'))
+        return null;
+    const chain = getChainName(fromData) ?? getChainName(toData);
+    return createInvalidChainError(chain ?? 'unknown', message);
+}
+/**
+ * Handles address-related validation errors from Zod.
  *
- * // With string
- * const info2 = extractChainInfo('Solana')
- * console.log(info2.expectedAddressFormat)
- * // → "44-character base58 encoded string"
+ * Checks if the validation error path includes 'address' and extracts both
+ * the invalid address from the path and the target chain from the params.
+ * Uses chain utilities to determine the expected address format (EVM or Solana)
+ * and creates a context-specific error message.
  *
- * // With undefined
- * const info3 = extractChainInfo(undefined)
- * console.log(info3.name) // → "unknown"
- * ```
+ * @param path - The Zod error path (e.g., 'to.recipientAddress')
+ * @param _code - The Zod error code (unused, prefixed with _ to indicate intentionally ignored)
+ * @param _message - The original Zod error message (unused, we create a more specific message)
+ * @param paramsObj - The original params object for extracting address and chain info
+ * @returns KitError with INPUT_INVALID_ADDRESS code if this is an address error, null otherwise
  */
-function extractChainInfo(chain) {
-    const name = typeof chain === 'string' ? chain : (chain?.name ?? 'unknown');
-    const chainType = typeof chain === 'object' && chain !== null ? chain.type : undefined;
-    // Use explicit chain type if available, fallback to name matching
-    const isSolana = chainType !== undefined
-        ? chainType === 'solana'
-        : name.toLowerCase().includes('solana');
-    return {
-        name,
-        displayName: name.replace(/_/g, ' '),
-        expectedAddressFormat: isSolana
-            ? '44-character base58 encoded string'
-            : '42-character hex address starting with 0x',
-    };
+function handleAddressError(path, _code, _message, paramsObj) {
+    if (!path.toLowerCase().includes('address'))
+        return null;
+    const address = getAddressFromParams(paramsObj, path);
+    const chain = getChainFromParams(paramsObj);
+    const chainInfo = extractChainInfo(chain);
+    return createInvalidAddressError(address, chainInfo.displayName, chainInfo.expectedAddressFormat);
 }
+
 /**
- * Validates if an address format is correct for the specified chain.
+ * Validates data against a Zod schema with enhanced error reporting.
  *
- * This function checks the explicit chain `type` property first, then falls back
- * to name-based matching to determine whether to validate as a Solana or EVM address.
+ * This function performs validation using Zod schemas and provides detailed error
+ * messages that include the validation context. It's designed to give developers
+ * clear feedback about what went wrong during validation.
  *
- * @param address - The address to validate
- * @param chain - The chain identifier or chain definition (cannot be null)
- * @returns True if the address format is valid for the chain, false otherwise
+ * @param value - The value to validate
+ * @param schema - The Zod schema to validate against
+ * @param context - Context string to include in error messages (e.g., 'bridge parameters')
+ * @returns Asserts that value is of type T (type narrowing)
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098)
  *
  * @example
  * ```typescript
- * import { isValidAddressForChain } from '@core/errors'
- *
- * // EVM address validation
- * isValidAddressForChain('0x742d35Cc6634C0532925a3b8D0C0C1C4C5C6C7C8', 'Ethereum')
- * // → true
- *
- * // Solana address validation
- * isValidAddressForChain('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM', { name: 'Solana', type: 'solana' })
- * // → true
- *
- * // Invalid format
- * isValidAddressForChain('invalid', 'Ethereum')
- * // → false
+ * validate(params, BridgeParamsSchema, 'bridge parameters')
+ * // After this call, TypeScript knows params is of type BridgeParams
  * ```
  */
-function isValidAddressForChain(address, chain) {
-    const chainType = typeof chain === 'object' ? chain.type : undefined;
-    const name = typeof chain === 'string' ? chain : chain.name;
-    // Use explicit chain type if available, fallback to name matching
-    const isSolana = chainType !== undefined
-        ? chainType === 'solana'
-        : name.toLowerCase().includes('solana');
-    if (isSolana) {
-        // Solana base58 address: 32-44 characters from base58 alphabet
-        return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(address);
+function validate(value, schema, context) {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        throw createValidationErrorFromZod(result.error, context);
     }
-    // EVM hex address: 0x followed by 40 hex characters
-    return /^0x[a-fA-F0-9]{40}$/.test(address);
 }
+
 /**
- * Type guard to check if a value is an object.
- *
- * @param val - The value to check
- * @returns True if the value is a non-null object
+ * Symbol used to track validation state on objects.
+ * This allows us to attach metadata to objects without interfering with their structure,
+ * enabling optimized validation by skipping already validated objects.
+ * @internal
  */
-function isObject(val) {
-    return typeof val === 'object' && val !== null;
-}
+const VALIDATION_STATE = Symbol('validationState');
 /**
- * Type guard to check if a value is a chain with isTestnet property.
+ * Validates data against a Zod schema with state tracking and enhanced error reporting.
  *
- * @param chain - The value to check
- * @returns True if the value is a chain object with name and isTestnet properties
+ * This function performs validation using Zod schemas while tracking validation state
+ * and providing detailed error messages. It's designed for use in scenarios where
+ * validation state needs to be monitored and reported.
+ *
+ * @param value - The value to validate
+ * @param schema - The Zod schema to validate against
+ * @param context - Context string to include in error messages (e.g., 'bridge parameters')
+ * @param validatorName - Symbol identifying the validator for state tracking
+ * @returns Asserts that value is of type T (type narrowing)
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098)
  *
  * @example
  * ```typescript
- * import { isChainWithTestnet } from '@core/errors'
- *
- * const chain1 = { name: 'Ethereum', isTestnet: false }
- * isChainWithTestnet(chain1) // → true
- *
- * const chain2 = { name: 'Ethereum' }
- * isChainWithTestnet(chain2) // → false
- *
- * const chain3 = 'Ethereum'
- * isChainWithTestnet(chain3) // → false
+ * const result = validateWithStateTracking(BridgeParamsSchema, params, 'bridge parameters')
  * ```
  */
-function isChainWithTestnet(chain) {
-    return (isObject(chain) &&
-        'isTestnet' in chain &&
-        typeof chain['isTestnet'] === 'boolean' &&
-        'name' in chain &&
-        typeof chain['name'] === 'string');
+function validateWithStateTracking(value, schema, context, validatorName) {
+    // Skip validation for null or undefined values
+    if (value === null) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Invalid ${context}: Value is null`,
+            cause: {
+                trace: {
+                    validationErrors: ['Value is null'],
+                },
+            },
+        });
+    }
+    if (value === undefined) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Invalid ${context}: Value is undefined`,
+            cause: {
+                trace: {
+                    validationErrors: ['Value is undefined'],
+                },
+            },
+        });
+    }
+    // Ensure value is an object that can hold validation state
+    if (typeof value !== 'object') {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Invalid ${context}: Value must be an object`,
+            cause: {
+                trace: {
+                    validationErrors: [`Value must be an object, got ${typeof value}`],
+                },
+            },
+        });
+    }
+    // Get or initialize validation state
+    const valueWithState = value;
+    const state = valueWithState[VALIDATION_STATE] ?? { validatedBy: [] };
+    // Skip validation if already validated by this validator
+    if (state.validatedBy.includes(validatorName)) {
+        return;
+    }
+    // Delegate to the validate function for actual validation (now throws KitError)
+    validate(value, schema, context);
+    // Update validation state
+    state.validatedBy.push(validatorName);
+    valueWithState[VALIDATION_STATE] = state;
 }
+
 /**
- * Gets chain identifier from toData object.
- *
- * Looks for chain in context.chain first, then falls back to direct chain property.
- *
- * @param toData - The destination data object
- * @returns The chain identifier or null
+ * Zod schema for validating chain definition objects used in buildExplorerUrl.
+ * This schema ensures the chain definition has the required properties for URL generation.
  */
-function getChainFromToData(toData) {
-    const context = toData['context'];
-    const chain = context?.['chain'] ?? toData['chain'];
-    return chain;
-}
+const chainDefinitionSchema = zod.z.object({
+    name: zod.z
+        .string({
+        required_error: 'Chain name is required',
+        invalid_type_error: 'Chain name must be a string',
+    })
+        .min(1, 'Chain name cannot be empty'),
+    explorerUrl: zod.z
+        .string({
+        required_error: 'Explorer URL template is required',
+        invalid_type_error: 'Explorer URL template must be a string',
+    })
+        .min(1, 'Explorer URL template cannot be empty')
+        .refine((url) => url.includes('{hash}'), 'Explorer URL template must contain a {hash} placeholder'),
+});
 /**
- * Gets chain name from params object.
- *
- * @param params - The parameters object
- * @returns The chain name as a string, or null if not found
+ * Zod schema for validating transaction hash strings used in buildExplorerUrl.
+ * This schema ensures the transaction hash is a non-empty string.
  */
-function getChainName(params) {
-    if (isObject(params)) {
-        const chain = params['chain'];
-        if (typeof chain === 'string') {
-            return chain;
-        }
-        if (isObject(chain) && 'name' in chain) {
-            return chain.name;
-        }
-    }
-    return null;
-}
+const transactionHashSchema = zod.z
+    .string({
+    required_error: 'Transaction hash is required',
+    invalid_type_error: 'Transaction hash must be a string',
+})
+    .min(1, 'Transaction hash cannot be empty')
+    .transform((hash) => hash.trim()) // Automatically trim whitespace
+    .refine((hash) => hash.length > 0, 'Transaction hash must not be empty or whitespace-only');
 /**
- * Extracts from data from params object.
- *
- * Supports both 'from' and 'source' property names.
- *
- * @param params - The parameters object
- * @returns The from/source data or undefined
+ * Zod schema for validating buildExplorerUrl function parameters.
+ * This schema validates both the chain definition and transaction hash together.
  */
-function extractFromData(params) {
-    return (params['from'] ?? params['source']);
-}
+zod.z.object({
+    chainDef: chainDefinitionSchema,
+    txHash: transactionHashSchema,
+});
 /**
- * Extracts to data from params object.
- *
- * Supports both 'to' and 'destination' property names.
- *
- * @param params - The parameters object
- * @returns The to/destination data or undefined
+ * Zod schema for validating the generated explorer URL.
+ * This schema ensures the generated URL is valid.
  */
-function extractToData(params) {
-    return (params['to'] ?? params['destination']);
-}
+zod.z
+    .string()
+    .url('Generated explorer URL is invalid');
+
 /**
- * Gets address from params object using a dot-separated path.
+ * A type-safe event emitter for managing action-based event subscriptions.
  *
- * Traverses nested objects to extract the address value at the specified path.
+ * Actionable provides a strongly-typed publish/subscribe pattern for events,
+ * where each event (action) has its own specific payload type. Handlers can
+ * subscribe to specific events or use a wildcard to receive all events.
  *
- * @param params - The parameters object
- * @param path - Dot-separated path to extract address from (e.g., 'to.recipientAddress')
- * @returns The address as a string, or 'unknown' if not found
+ * @typeParam AllActions - A record mapping action names to their payload types.
  *
  * @example
  * ```typescript
- * // Extract from specific path
- * getAddressFromParams(params, 'to.recipientAddress')
- * // Returns the value at params.to.recipientAddress
- * ```
- */
-function getAddressFromParams(params, path) {
-    const parts = path.split('.');
-    let current = params;
-    for (const part of parts) {
-        if (current !== null &&
-            current !== undefined &&
-            typeof current === 'object' &&
-            part in current) {
-            current = current[part];
-        }
-        else {
-            return 'unknown';
-        }
-    }
-    return typeof current === 'string' ? current : 'unknown';
-}
-/**
- * Gets chain identifier from params object.
- *
- * Looks for chain in to.context.chain, to.chain, or direct chain property.
+ * import { Actionable } from '@circle-fin/bridge-kit/utils';
  *
- * @param params - The parameters object
- * @returns The chain identifier or null
- */
-function getChainFromParams(params) {
-    const to = extractToData(params);
-    const chain = to?.['chain'] ?? params['chain'];
-    return chain;
-}
-
-/**
- * Maximum length for error messages in fallback validation errors.
+ * // Define your action types
+ * type TransferActions = {
+ *   started: { txHash: string; amount: string };
+ *   completed: { txHash: string; destinationTxHash: string };
+ *   failed: { error: Error };
+ * };
  *
- * KitError enforces a 500-character limit on error messages. When creating
- * fallback validation errors that combine multiple Zod issues, we use 450
- * characters to leave a 50-character buffer for:
- * - The error message prefix ("Invalid bridge parameters: ")
- * - Potential encoding differences or formatting overhead
- * - Safety margin to prevent KitError constructor failures
+ * // Create an actionable instance
+ * const transferEvents = new Actionable<TransferActions>();
  *
- * This ensures that even with concatenated issue summaries, the final message
- * stays within KitError's constraints.
- */
-const MAX_MESSAGE_LENGTH = 450;
-
-/**
- * Converts a Zod validation error into a specific KitError instance using structured pattern matching.
+ * // Subscribe to a specific event
+ * transferEvents.on('completed', (payload) => {
+ *   console.log(`Transfer completed with hash: ${payload.destinationTxHash}`);
+ * });
  *
- * This function inspects Zod's error details (path, code, message) and delegates each issue
- * to specialized handlers that generate domain-specific KitError objects. It leverages
- * Zod's error codes and path information for robust matching, avoiding fragile string checks.
+ * // Subscribe to all events
+ * transferEvents.on('*', (payload) => {
+ *   console.log('Event received:', payload);
+ * });
  *
- * @param zodError - The Zod validation error containing one or more issues
- * @param params - The original parameters that failed validation (used to extract invalid values)
- * @returns A specific KitError instance with actionable error details
+ * // Dispatch an event
+ * transferEvents.dispatch('completed', {
+ *   txHash: '0x123',
+ *   destinationTxHash: '0xabc'
+ * });
+ * ```
  */
-function convertZodErrorToStructured(zodError, params) {
-    // Handle null/undefined params gracefully
-    if (params === null || params === undefined) {
-        return createValidationFailedError(zodError);
+class Actionable {
+    // Store event handlers by action key
+    handlers = {};
+    // Store wildcard handlers that receive all events
+    wildcard = [];
+    // Implementation that handles both overloads
+    on(action, handler) {
+        if (action === '*') {
+            // Add to wildcard handlers array
+            this.wildcard.push(handler);
+        }
+        else {
+            // Initialize the action's handler array if it doesn't exist
+            if (!this.handlers[action]) {
+                this.handlers[action] = [];
+            }
+            // Add the handler to the specific action's array
+            this.handlers[action].push(handler);
+        }
     }
-    const paramsObj = params;
-    const toData = extractToData(paramsObj);
-    const fromData = extractFromData(paramsObj);
-    for (const issue of zodError.issues) {
-        const path = issue.path.join('.');
-        const code = issue.code;
-        // Try to handle specific error types
-        const amountError = handleAmountError(path, code, issue.message, paramsObj);
-        if (amountError)
-            return amountError;
-        const chainError = handleChainError(path, code, issue.message, fromData, toData);
-        if (chainError)
-            return chainError;
-        const addressError = handleAddressError(path, code, issue.message, paramsObj);
-        if (addressError)
-            return addressError;
+    // Implementation that handles both overloads
+    off(action, handler) {
+        if (action === '*') {
+            // Find and remove the handler from wildcard array
+            const index = this.wildcard.indexOf(handler);
+            if (index !== -1) {
+                this.wildcard.splice(index, 1);
+            }
+        }
+        else if (this.handlers[action]) {
+            // Check if there are handlers for this action
+            // Find and remove the specific handler
+            const index = this.handlers[action].indexOf(handler);
+            if (index !== -1) {
+                this.handlers[action].splice(index, 1);
+            }
+        }
+    }
+    /**
+     * Dispatch an action with its payload to all registered handlers.
+     *
+     * This method notifies both:
+     * - Handlers registered specifically for this action
+     * - Wildcard handlers registered for all actions
+     *
+     * @param action - The action key identifying the event type.
+     * @param payload - The data associated with the action.
+     *
+     * @example
+     * ```typescript
+     * type Actions = {
+     *   transferStarted: { amount: string; destination: string };
+     *   transferComplete: { txHash: string };
+     * };
+     *
+     * const events = new Actionable<Actions>();
+     *
+     * // Dispatch an event
+     * events.dispatch('transferStarted', {
+     *   amount: '100',
+     *   destination: '0xABC123'
+     * });
+     * ```
+     */
+    dispatch(action, payload) {
+        // Execute all handlers registered for this specific action
+        for (const h of this.handlers[action] ?? [])
+            h(payload);
+        // Execute all wildcard handlers
+        for (const h of this.wildcard)
+            h(payload);
     }
-    // Fallback
-    return createValidationFailedError(zodError);
-}
-/**
- * Creates a generic validation failed error for null/undefined params or unmapped error cases.
- *
- * This is a fallback handler used when:
- * - Parameters are null or undefined
- * - No specific error handler matches the Zod error
- * - The error doesn't fit into amount/chain/address categories
- *
- * The function truncates the error message to stay within KitError's 500-character limit.
- *
- * @param zodError - The Zod validation error with all issues
- * @param params - The original parameters (may be null/undefined)
- * @returns A generic KitError with INPUT_VALIDATION_FAILED code
- */
-function createValidationFailedError(zodError) {
-    const issueSummary = zodError.issues
-        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
-        .join('; ');
-    // Truncate message to avoid KitError constructor failure.
-    const fullMessage = `Invalid parameters: ${issueSummary}`;
-    const truncatedMessage = fullMessage.length > MAX_MESSAGE_LENGTH
-        ? `${fullMessage.substring(0, MAX_MESSAGE_LENGTH)}...`
-        : fullMessage;
-    return new KitError({
-        ...InputError.VALIDATION_FAILED,
-        recoverability: 'FATAL',
-        message: truncatedMessage,
-        cause: {
-            trace: {
-                originalError: zodError.message,
-                zodIssues: zodError.issues,
-            },
-        },
-    });
-}
-/**
- * Handles amount-related validation errors from Zod.
- *
- * Checks if the validation error path includes 'amount' and attempts
- * to convert generic Zod errors into specific KitError instances with
- * actionable messages. Delegates to specialized handlers in order of specificity:
- * 1. Negative amount errors (too_small)
- * 2. Custom validation errors (decimal places, numeric string)
- * 3. Invalid string format errors
- * 4. Invalid type errors
- *
- * @param path - The Zod error path (e.g., 'amount' or 'config.amount')
- * @param code - The Zod error code (e.g., 'too_small', 'invalid_string', 'custom')
- * @param message - The original Zod error message
- * @param paramsObj - The original params object for extracting the invalid amount value
- * @returns KitError with INPUT_INVALID_AMOUNT code if this is an amount error, null otherwise
- */
-function handleAmountError(path, code, message, paramsObj) {
-    if (!path.includes('amount'))
-        return null;
-    const amount = typeof paramsObj['amount'] === 'string' ? paramsObj['amount'] : 'unknown';
-    // Try different error handlers in order of specificity
-    const negativeError = handleNegativeAmountError(code, message, amount);
-    if (negativeError)
-        return negativeError;
-    const customError = handleCustomAmountError(code, message, amount);
-    if (customError)
-        return customError;
-    const stringFormatError = handleInvalidStringAmountError(code, message, amount);
-    if (stringFormatError)
-        return stringFormatError;
-    const typeError = handleInvalidTypeAmountError(code, amount);
-    if (typeError)
-        return typeError;
-    return null;
 }
+
 /**
- * Handles negative or too-small amount validation errors.
+ * Convert a value from its smallest unit representation to a human-readable decimal string.
  *
- * Detects Zod 'too_small' error codes or messages containing 'greater than'
- * and creates a specific error indicating the amount must be positive.
+ * 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.
  *
- * @param code - The Zod error code
- * @param message - The Zod error message
- * @param amount - The invalid amount value as a string
- * @returns KitError if this is a negative/too-small amount error, null otherwise
- */
-function handleNegativeAmountError(code, message, amount) {
-    if (code === 'too_small' || message.includes('greater than')) {
-        return createInvalidAmountError(amount, 'Amount must be greater than 0');
-    }
-    return null;
-}
-/**
- * Handles custom Zod refinement validation errors for amounts.
+ * @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
+ * @returns A human-readable decimal string (e.g., "1.0")
+ * @throws Error if the value is not a valid numeric string
  *
- * Processes Zod 'custom' error codes from .refine() validators and matches
- * against known patterns:
- * - 'non-negative' - amount must be \>= 0
- * - 'decimal places' - too many decimal places
- * - 'numeric string' - value is not a valid numeric string
+ * @example
+ * ```typescript
+ * import { formatUnits } from '@core/utils'
  *
- * @param code - The Zod error code (must be 'custom')
- * @param message - The custom error message from the refinement
- * @param amount - The invalid amount value as a string
- * @returns KitError with specific message if pattern matches, null otherwise
- */
-function handleCustomAmountError(code, message, amount) {
-    if (code !== 'custom')
-        return null;
-    if (message.includes('non-negative')) {
-        return createInvalidAmountError(amount, 'Amount must be non-negative');
-    }
-    if (message.includes('decimal places')) {
-        return createInvalidAmountError(amount, message);
-    }
-    if (message.includes('numeric string')) {
-        return createInvalidAmountError(amount, 'Amount must be a numeric string');
-    }
-    return null;
-}
-/**
- * Handles Zod 'invalid_string' errors for amount values.
+ * // Format USDC (6 decimals)
+ * const usdcFormatted = formatUnits('1000000', 6)
+ * console.log(usdcFormatted) // "1.0"
  *
- * Processes string validation failures (e.g., regex mismatches) and categorizes them:
- * 1. Negative numbers that pass Number() but fail other validations
- * 2. Decimal places validation failures (too many decimal places)
- * 3. Numeric format validation failures (contains non-numeric characters)
- * 4. Generic invalid number strings
+ * // Format ETH (18 decimals)
+ * const ethFormatted = formatUnits('1000000000000000000', 18)
+ * console.log(ethFormatted) // "1.0"
  *
- * @param code - The Zod error code (must be 'invalid_string')
- * @param message - The Zod error message from string validation
- * @param amount - The invalid amount value as a string
- * @returns KitError with context-specific message if pattern matches, null otherwise
+ * // Format with fractional part
+ * const fractionalFormatted = formatUnits('1500000', 6)
+ * console.log(fractionalFormatted) // "1.5"
+ * ```
  */
-function handleInvalidStringAmountError(code, message, amount) {
-    if (code !== 'invalid_string')
-        return null;
-    // Check if it's a negative number first
-    if (amount.startsWith('-') && !isNaN(Number(amount))) {
-        return createInvalidAmountError(amount, 'Amount must be greater than 0');
-    }
-    // Check for decimal places validation
-    if (isDecimalPlacesError(message)) {
-        return createInvalidAmountError(amount, 'Maximum supported decimal places: 6');
-    }
-    // Check for numeric format validation
-    if (isNumericFormatError(message)) {
-        return createInvalidAmountError(amount, 'Amount must be a valid number format');
-    }
-    // For other cases like 'abc', return specific error
-    if (!message.includes('valid number format')) {
-        return createInvalidAmountError(amount, 'Amount must be a valid number string');
-    }
-    return null;
-}
+const formatUnits = (value, decimals) => {
+    return units.formatUnits(value, decimals);
+};
 /**
- * Handles Zod 'invalid_type' errors for amount values.
+ * Convert a human-readable decimal string to its smallest unit representation.
  *
- * Triggered when the amount is not a string type (e.g., number, boolean, object).
- * Creates an error indicating the amount must be a string representation of a number.
+ * This function converts user-friendly decimal values into the integer representation
+ * required by blockchain operations, where all values are stored in the smallest
+ * denomination. Uses the battle-tested implementation from @ethersproject/units.
  *
- * @param code - The Zod error code (must be 'invalid_type')
- * @param amount - The invalid amount value (will be converted to string for error message)
- * @returns KitError if this is a type mismatch, null otherwise
- */
-function handleInvalidTypeAmountError(code, amount) {
-    if (code === 'invalid_type') {
-        return createInvalidAmountError(amount, 'Amount must be a valid number string');
-    }
-    return null;
-}
-/**
- * Checks if an error message indicates a decimal places validation failure.
+ * @param value - The decimal string to convert (e.g., "1.0")
+ * @param decimals - The number of decimal places for the unit conversion
+ * @returns The value in smallest units as a bigint (e.g., 1000000n for 1 USDC with 6 decimals)
+ * @throws Error if the value is not a valid decimal string
  *
- * Looks for keywords like 'maximum', 'at most', and 'decimal places' to identify
- * errors related to too many decimal digits in an amount value.
+ * @example
+ * ```typescript
+ * import { parseUnits } from '@core/utils'
  *
- * @param message - The error message to analyze
- * @returns True if the message indicates a decimal places error, false otherwise
- */
-function isDecimalPlacesError(message) {
-    return ((message.includes('maximum') || message.includes('at most')) &&
-        message.includes('decimal places'));
-}
-/**
- * Checks if an error message indicates a numeric format validation failure.
+ * // Parse USDC (6 decimals)
+ * const usdcParsed = parseUnits('1.0', 6)
+ * console.log(usdcParsed) // 1000000n
  *
- * Identifies errors where a value contains 'numeric' but is not specifically
- * about 'valid number format' or 'numeric string' (to avoid false positives).
+ * // Parse ETH (18 decimals)
+ * const ethParsed = parseUnits('1.0', 18)
+ * console.log(ethParsed) // 1000000000000000000n
  *
- * @param message - The error message to analyze
- * @returns True if the message indicates a numeric format error, false otherwise
+ * // Parse fractional amount
+ * const fractionalParsed = parseUnits('1.5', 6)
+ * console.log(fractionalParsed) // 1500000n
+ *
+ * // Parse integer (no decimal point)
+ * const integerParsed = parseUnits('42', 6)
+ * console.log(integerParsed) // 42000000n
+ * ```
  */
-function isNumericFormatError(message) {
-    return (message.includes('numeric') &&
-        !message.includes('valid number format') &&
-        !message.includes('numeric string'));
-}
+const parseUnits = (value, decimals) => {
+    return units.parseUnits(value, decimals).toBigInt();
+};
+
 /**
- * Handles chain-related validation errors from Zod.
+ * Format a token amount into a human-readable decimal string.
  *
- * Checks if the validation error path includes 'chain' and extracts the
- * chain name from either the source (from) or destination (to) data.
- * Creates a KitError with the invalid chain name and original error message.
+ * Accepts a smallest-unit string and either assumes USDC's 6 decimals or derives the
+ * native decimals from the provided chain definition. Delegates to {@link formatUnits}
+ * to preserve consistent rounding and formatting behaviour across the SDK.
  *
- * @param path - The Zod error path (e.g., 'from.chain' or 'to.chain')
- * @param _code - The Zod error code (unused, prefixed with _ to indicate intentionally ignored)
- * @param message - The original Zod error message
- * @param fromData - The source/from data object (may contain chain info)
- * @param toData - The destination/to data object (may contain chain info)
- * @returns KitError with INPUT_INVALID_CHAIN code if this is a chain error, null otherwise
+ * @remarks
+ * When `token` is `'native'`, supply a chain identifier that {@link resolveChainIdentifier}
+ * can resolve so the native currency decimals can be determined.
+ *
+ * @param params - The formatting input including the raw value and token selector.
+ * @returns The decimal string representation of the amount.
+ * @throws Error if the value cannot be parsed or if the chain identifier is unknown.
+ *
+ * @example
+ * ```typescript
+ * import { formatAmount } from '@core/utils'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const usdcAmount = formatAmount({ value: '1000000', token: 'USDC' })
+ * console.log(usdcAmount) // "1"
+ *
+ * const ethAmount = formatAmount({
+ *   value: '3141592000000000000',
+ *   token: 'native',
+ *   chain: Ethereum,
+ * })
+ * console.log(ethAmount) // "3.141592"
+ * ```
  */
-function handleChainError(path, _code, message, fromData, toData) {
-    if (!path.includes('chain'))
-        return null;
-    const chain = getChainName(fromData) ?? getChainName(toData);
-    return createInvalidChainError(chain ?? 'unknown', message);
-}
+const formatAmount = (params) => {
+    const { value, token } = params;
+    switch (token) {
+        case 'USDC':
+            return formatUnits(value, 6);
+        case 'native':
+            return formatUnits(value, resolveChainIdentifier(params.chain).nativeCurrency.decimals);
+        default:
+            // This will cause a compile-time error if a new token type is added to
+            // `FormatAmountParams` but not handled in this switch statement, ensuring exhaustiveness.
+            throw new Error(`formatAmount: Unhandled token type: ${token}`);
+    }
+};
+
 /**
- * Handles address-related validation errors from Zod.
+ * Parse a human-readable token amount into its smallest unit representation.
  *
- * Checks if the validation error path includes 'address' and extracts both
- * the invalid address from the path and the target chain from the params.
- * Uses chain utilities to determine the expected address format (EVM or Solana)
- * and creates a context-specific error message.
+ * Accepts a decimal string and either assumes USDC's 6 decimals or derives the
+ * native decimals from the provided chain definition. Delegates to {@link parseUnits}
+ * to preserve deterministic rounding and bigint conversions across the SDK.
  *
- * @param path - The Zod error path (e.g., 'to.recipientAddress')
- * @param _code - The Zod error code (unused, prefixed with _ to indicate intentionally ignored)
- * @param _message - The original Zod error message (unused, we create a more specific message)
- * @param paramsObj - The original params object for extracting address and chain info
- * @returns KitError with INPUT_INVALID_ADDRESS code if this is an address error, null otherwise
+ * @remarks
+ * When `token` is `'native'`, supply a chain identifier that {@link resolveChainIdentifier}
+ * can resolve so the native currency decimals can be determined.
+ *
+ * @param params - The parsing input including the amount value, token, and optional chain identifier.
+ * @returns The bigint representation of the amount in smallest units.
+ * @throws Error if the value cannot be parsed or if the chain identifier is unknown.
+ *
+ * @example
+ * ```typescript
+ * import { parseAmount } from '@core/utils'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const usdcAmount = parseAmount({ value: '1', token: 'USDC' })
+ * console.log(usdcAmount) // 1000000n
+ *
+ * const ethAmount = parseAmount({
+ *   value: '3.141592',
+ *   token: 'native',
+ *   chain: Ethereum,
+ * })
+ * console.log(ethAmount) // 3141592000000000000n
+ * ```
  */
-function handleAddressError(path, _code, _message, paramsObj) {
-    if (!path.toLowerCase().includes('address'))
-        return null;
-    const address = getAddressFromParams(paramsObj, path);
-    const chain = getChainFromParams(paramsObj);
-    const chainInfo = extractChainInfo(chain);
-    return createInvalidAddressError(address, chainInfo.displayName, chainInfo.expectedAddressFormat);
-}
+const parseAmount = (params) => {
+    const { value, token } = params;
+    switch (token) {
+        case 'USDC':
+            return parseUnits(value, 6);
+        case 'native':
+            return parseUnits(value, resolveChainIdentifier(params.chain).nativeCurrency.decimals);
+        default:
+            // This will cause a compile-time error if a new token type is added to
+            // `FormatAmountParams` but not handled in this switch statement, ensuring exhaustiveness.
+            throw new Error(`parseAmount: Unhandled token type: ${token}`);
+    }
+};
+
+var name = "@circle-fin/bridge-kit";
+var version = "1.2.0";
+var pkg = {
+	name: name,
+	version: version};
 
 const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
 /**
@@ -3864,17 +4349,22 @@ const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
  * Validates the shape of {@link CustomFeePolicy}, which lets SDK consumers
  * provide custom fee calculation and fee-recipient resolution logic.
  *
- * - calculateFee: required function that returns a fee as a string (or Promise<string>).
+ * - computeFee: optional function (recommended) that receives human-readable amounts
+ *   and returns a fee as a string (or Promise<string>).
+ * - calculateFee: optional function (deprecated) that receives smallest-unit amounts
+ *   and returns a fee as a string (or Promise<string>).
  * - resolveFeeRecipientAddress: required function that returns a recipient address as a
  *   string (or Promise<string>).
  *
+ * Exactly one of `computeFee` or `calculateFee` must be provided (not both).
+ *
  * This schema only ensures the presence and return types of the functions; it
  * does not validate their argument types.
  *
  * @example
  * ```ts
  * const config = {
- *   calculateFee: async () => '1000000',
+ *   computeFee: async () => '1', // 1 USDC (human-readable)
  *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
  * }
  * const result = customFeePolicySchema.safeParse(config)
@@ -3883,12 +4373,27 @@ const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
  */
 const customFeePolicySchema = zod.z
     .object({
-    calculateFee: zod.z.function().returns(zod.z.string().or(zod.z.promise(zod.z.string()))),
+    computeFee: zod.z
+        .function()
+        .returns(zod.z.string().or(zod.z.promise(zod.z.string())))
+        .optional(),
+    calculateFee: zod.z
+        .function()
+        .returns(zod.z.string().or(zod.z.promise(zod.z.string())))
+        .optional(),
     resolveFeeRecipientAddress: zod.z
         .function()
         .returns(zod.z.string().or(zod.z.promise(zod.z.string()))),
 })
-    .strict();
+    .strict()
+    .refine((data) => {
+    const hasComputeFee = data.computeFee !== undefined;
+    const hasCalculateFee = data.calculateFee !== undefined;
+    // XOR: exactly one must be provided
+    return hasComputeFee !== hasCalculateFee;
+}, {
+    message: 'Provide either computeFee or calculateFee, not both. Use computeFee (recommended) for human-readable amounts.',
+});
 /**
  * Assert that the provided value conforms to {@link CustomFeePolicy}.
  *
@@ -3900,7 +4405,7 @@ const customFeePolicySchema = zod.z
  * @example
  * ```ts
  * const config = {
- *   calculateFee: () => '1000000',
+ *   computeFee: () => '1', // 1 USDC (human-readable)
  *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
  * }
  * assertCustomFeePolicy(config)
@@ -3967,16 +4472,16 @@ function assertBridgeParams(params, schema) {
         validateWithStateTracking(params, schema, 'bridge parameters', ASSERT_BRIDGE_PARAMS_SYMBOL);
     }
     catch (error) {
-        // Convert ValidationError to structured KitError
-        if (error instanceof ValidationError) {
-            // Extract the underlying Zod error from ValidationError
-            // ValidationError wraps the Zod validation failure
+        // Convert generic KitError validation failure to structured KitError with specific codes
+        if (error instanceof KitError &&
+            error.code === InputError.VALIDATION_FAILED.code) {
+            // Re-parse to get the underlying Zod error for enhanced error mapping
             const result = schema.safeParse(params);
             if (!result.success) {
                 throw convertZodErrorToStructured(result.error, params);
             }
         }
-        // Re-throw if it's not a ValidationError
+        // Re-throw if it's not a validation error or couldn't be parsed
         throw error;
     }
     // Additional business logic checks that Zod cannot handle
@@ -4006,7 +4511,7 @@ function assertBridgeParams(params, schema) {
  * This schema does not validate length, making it suitable for various hex string types
  * like addresses, transaction hashes, and other hex-encoded data.
  *
- * @throws {ValidationError} If validation fails, with details about which properties failed
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
@@ -4037,7 +4542,7 @@ const hexStringSchema = zod.z
  * - Must be a valid hex string with '0x' prefix
  * - Must be exactly 42 characters long (0x + 40 hex characters)
  *
- * @throws {ValidationError} If validation fails, with details about which properties failed
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
@@ -4057,7 +4562,7 @@ hexStringSchema.refine((value) => value.length === 42, 'EVM address must be exac
  * - Must be a valid hex string with '0x' prefix
  * - Must be exactly 66 characters long (0x + 64 hex characters)
  *
- * @throws {ValidationError} If validation fails, with details about which properties failed
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
@@ -4083,7 +4588,7 @@ hexStringSchema.refine((value) => value.length === 66, 'Transaction hash must be
  * This schema does not validate length, making it suitable for various base58-encoded data
  * like Solana addresses, transaction signatures, and other base58-encoded data.
  *
- * @throws {ValidationError} If validation fails, with details about which properties failed
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
@@ -4115,7 +4620,7 @@ const base58StringSchema = zod.z
  * - Must be a valid base58-encoded string
  * - Must be between 32-44 characters long (typical length for base58-encoded 32-byte addresses)
  *
- * @throws {ValidationError} If validation fails, with details about which properties failed
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
@@ -4135,7 +4640,7 @@ base58StringSchema.refine((value) => value.length >= 32 && value.length <= 44, '
  * - Must be a valid base58-encoded string
  * - Must be between 86-88 characters long (typical length for base58-encoded 64-byte signatures)
  *
- * @throws {ValidationError} If validation fails, with details about which properties failed
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
@@ -4173,23 +4678,35 @@ exports.TransferSpeed = void 0;
 })(exports.TransferSpeed || (exports.TransferSpeed = {}));
 
 /**
- * Factory to validate a numeric string that may include thousand separators and decimal part.
- * Supports either comma or dot as decimal separator and the other as thousands.
+ * Factory to validate a numeric string with strict dot-decimal notation.
+ * Only accepts dot (.) as the decimal separator. Thousand separators are not allowed.
+ *
+ * This enforces an unambiguous format for SDK inputs. Internationalization concerns
+ * (comma vs dot decimal separators) should be handled in the UI layer before passing
+ * values to the SDK.
+ *
+ * Accepts the following formats:
+ * - Whole numbers: "1", "100", "1000"
+ * - Leading zero decimals: "0.1", "0.5", "0.001"
+ * - Shorthand decimals: ".1", ".5", ".001"
+ * - Standard decimals: "1.23", "100.50"
+ *
+ * Does NOT accept:
+ * - Comma decimal separator: "1,5" (use "1.5" instead)
+ * - Thousand separators: "1,000.50" or "1.000,50" (use "1000.50" instead)
+ * - Multiple decimal points: "1.2.3"
+ * - Negative numbers: "-100"
+ * - Non-numeric characters: "abc", "100a"
  *
  * Behavior differences controlled by options:
  * - allowZero: when false, value must be strictly greater than 0; when true, non-negative.
  * - regexMessage: error message when the basic numeric format fails.
+ * - maxDecimals: maximum number of decimal places allowed (e.g., 6 for USDC).
  */
 const createDecimalStringValidator = (options) => (schema) => schema
-    .regex(/^\d+(?:[.,]\d{3})*(?:[.,]\d+)?$/, options.regexMessage)
+    .regex(/^-?(?:\d+(?:\.\d+)?|\.\d+)$/, options.regexMessage)
     .superRefine((val, ctx) => {
-    const lastSeparator = val.lastIndexOf(',');
-    const lastDot = val.lastIndexOf('.');
-    const isCommaSeparated = lastSeparator > lastDot;
-    const normalizedValue = val
-        .replace(isCommaSeparated ? /\./g : /,/g, '')
-        .replace(isCommaSeparated ? ',' : '.', '.');
-    const amount = parseFloat(normalizedValue);
+    const amount = Number.parseFloat(val);
     if (Number.isNaN(amount)) {
         ctx.addIssue({
             code: zod.z.ZodIssueCode.custom,
@@ -4199,7 +4716,7 @@ const createDecimalStringValidator = (options) => (schema) => schema
     }
     // Check decimal precision if maxDecimals is specified
     if (options.maxDecimals !== undefined) {
-        const decimalPart = normalizedValue.split('.')[1];
+        const decimalPart = val.split('.')[1];
         if (decimalPart && decimalPart.length > options.maxDecimals) {
             ctx.addIssue({
                 code: zod.z.ZodIssueCode.custom,
@@ -4226,7 +4743,7 @@ const createDecimalStringValidator = (options) => (schema) => schema
  * This ensures the basic structure of a chain definition is valid.
  * A chain definition must include at minimum a name and type.
  *
- * @throws ValidationError If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -4253,7 +4770,7 @@ zod.z.object({
  * - A valid Ethereum address
  * - A valid chain definition with required properties
  *
- * @throws ValidationError If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -4294,7 +4811,7 @@ const walletContextSchema = zod.z.object({
  * - An optional fee amount as string
  * - An optional fee recipient as string address
  *
- * @throws ValidationError If validation fails
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -4313,11 +4830,12 @@ const customFeeSchema = zod.z
     .object({
     /**
      * The fee to charge for the transfer as string.
-     * Must be a non-negative value.
+     * Must be a non-negative value using dot (.) as decimal separator,
+     * with no thousand separators or comma decimals.
      */
     value: createDecimalStringValidator({
         allowZero: true,
-        regexMessage: 'Value must be non-negative',
+        regexMessage: 'Value must be a non-negative numeric string with dot (.) as decimal separator, with no thousand separators or comma decimals.',
         attributeName: 'value',
     })(zod.z.string()).optional(),
     /**
@@ -4340,7 +4858,7 @@ const customFeeSchema = zod.z
  * - USDC as the token
  * - Optional config with transfer speed and max fee settings
  *
- * @throws ValidationError If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -4361,9 +4879,9 @@ const customFeeSchema = zod.z
  *   token: 'USDC',
  *   config: {
  *     transferSpeed: 'FAST',
- *     maxFee: '1.5', // Decimal format
+ *     maxFee: '1.5', // Must use dot as decimal separator
  *     customFee: {
- *       value: '0.5', // Decimal format
+ *       value: '0.5', // Must use dot as decimal separator
  *       recipientAddress: '0x1234567890123456789012345678901234567890'
  *     }
  *   }
@@ -4379,7 +4897,7 @@ zod.z.object({
         .min(1, 'Required')
         .pipe(createDecimalStringValidator({
         allowZero: false,
-        regexMessage: 'Amount must be a numeric string with optional decimal places (e.g., 10.5, 10,5, 1.000,50 or 1,000.50)',
+        regexMessage: 'Amount must be a numeric string with dot (.) as decimal separator (e.g., "0.1", ".1", "10.5", "1000.50"), with no thousand separators or comma decimals.',
         attributeName: 'amount',
         maxDecimals: 6,
     })(zod.z.string())),
@@ -4392,7 +4910,7 @@ zod.z.object({
             .string()
             .pipe(createDecimalStringValidator({
             allowZero: true,
-            regexMessage: 'maxFee must be a numeric string with optional decimal places (e.g., "1", "0.5", "1.5")',
+            regexMessage: '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.',
             attributeName: 'maxFee',
             maxDecimals: 6,
         })(zod.z.string()))
@@ -4402,13 +4920,19 @@ zod.z.object({
 });
 
 /**
- * Schema for validating AdapterContext.
+ * Error message constants for validation
+ */
+const AMOUNT_VALIDATION_MESSAGE = 'Amount must be a numeric string with dot (.) as decimal separator (e.g., "0.1", ".1", "10.5", "1000.50"), with no thousand separators or comma decimals.';
+const MAX_FEE_VALIDATION_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.';
+/**
+ * Schema for validating AdapterContext for bridge operations.
  * Must always contain both adapter and chain explicitly.
+ *
  * Optionally includes address for developer-controlled adapters.
  */
 const adapterContextSchema = zod.z.object({
     adapter: adapterSchema,
-    chain: chainIdentifierSchema,
+    chain: bridgeChainIdentifierSchema,
     address: zod.z.string().optional(),
 });
 /**
@@ -4494,7 +5018,7 @@ const bridgeParamsWithChainIdentifierSchema = zod.z.object({
         .min(1, 'Required')
         .pipe(createDecimalStringValidator({
         allowZero: false,
-        regexMessage: 'Amount must be a numeric string with optional decimal places (e.g., 10.5, 10,5, 1.000,50 or 1,000.50)',
+        regexMessage: AMOUNT_VALIDATION_MESSAGE,
         attributeName: 'amount',
         maxDecimals: 6,
     })(zod.z.string())),
@@ -4507,7 +5031,7 @@ const bridgeParamsWithChainIdentifierSchema = zod.z.object({
             .min(1, 'Required')
             .pipe(createDecimalStringValidator({
             allowZero: true,
-            regexMessage: 'Max fee must be a numeric string with optional decimal places (e.g., 1, 0.5, 1.5)',
+            regexMessage: MAX_FEE_VALIDATION_MESSAGE,
             attributeName: 'maxFee',
             maxDecimals: 6,
         })(zod.z.string()))
@@ -4716,6 +5240,10 @@ function resolveConfig(params) {
 async function resolveBridgeParams(params) {
     const fromChain = resolveChainDefinition(params.from);
     const toChain = resolveChainDefinition(params.to);
+    // Validate adapter chain support after resolution
+    // This ensures adapters support the resolved chains before proceeding
+    params.from.adapter.validateChainSupport(fromChain);
+    params.to.adapter.validateChainSupport(toChain);
     const [fromAddress, toAddress] = await Promise.all([
         resolveAddress(params.from),
         resolveAddress(params.to),
@@ -4754,6 +5282,70 @@ async function resolveBridgeParams(params) {
  */
 const getDefaultProviders = () => [new providerCctpV2.CCTPV2BridgingProvider()];
 
+/**
+ * A helper function to get a function that transforms an amount into a human-readable string or a bigint string.
+ * @param formatDirection - The direction to format the amount in.
+ * @returns A function that transforms an amount into a human-readable string or a bigint string.
+ */
+const getAmountTransformer = (formatDirection) => formatDirection === 'to-human-readable'
+    ? (params) => formatAmount(params)
+    : (params) => parseAmount(params).toString();
+/**
+ * Format the bridge result into human-readable string values for the user or bigint string values for internal use.
+ * @param result - The bridge result to format.
+ * @param formatDirection - The direction to format the result in.
+ *   - If 'to-human-readable', the result will be converted to human-readable string values.
+ *   - If 'to-internal', the result will be converted to bigint string values (usually for internal use).
+ * @returns The formatted bridge result.
+ *
+ * @example
+ * ```typescript
+ * const result = await kit.bridge({
+ *   amount: '1000000',
+ *   token: 'USDC',
+ *   from: { adapter: adapter, chain: 'Ethereum' },
+ *   to: { adapter: adapter, chain: 'Base' },
+ * })
+ *
+ * // Format the bridge result into human-readable string values for the user
+ * const formattedResultHumanReadable = formatBridgeResult(result, 'to-human-readable')
+ * console.log(formattedResultHumanReadable)
+ *
+ * // Format the bridge result into bigint string values for internal use
+ * const formattedResultInternal = formatBridgeResult(result, 'to-internal')
+ * console.log(formattedResultInternal)
+ * ```
+ */
+const formatBridgeResult = (result, formatDirection) => {
+    const transform = getAmountTransformer(formatDirection);
+    return {
+        ...result,
+        amount: transform({ value: result.amount, token: result.token }),
+        ...(result.config && {
+            config: {
+                ...result.config,
+                ...(result.config.maxFee && {
+                    maxFee: transform({
+                        value: result.config.maxFee,
+                        token: result.token,
+                    }),
+                }),
+                ...(result.config.customFee && {
+                    customFee: {
+                        ...result.config.customFee,
+                        value: result.config.customFee.value
+                            ? transform({
+                                value: result.config.customFee.value,
+                                token: result.token,
+                            })
+                            : undefined,
+                    },
+                }),
+            },
+        }),
+    };
+};
+
 /**
  * Route cross-chain USDC bridging through Circle's Cross-Chain Transfer Protocol v2 (CCTPv2).
  *
@@ -4768,18 +5360,18 @@ const getDefaultProviders = () => [new providerCctpV2.CCTPV2BridgingProvider()];
  *
  * @param params - The bridge parameters containing source, destination, amount, and token
  * @returns Promise resolving to the bridge result with transaction details and steps
- * @throws {ValidationError} If the parameters are invalid
+ * @throws {KitError} If the parameters are invalid
  * @throws {BridgeError} If the bridging process fails
  * @throws {UnsupportedRouteError} If the route is not supported
  *
  * @example
  * ```typescript
  * import { BridgeKit } from '@circle-fin/bridge-kit'
- * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
  *
  * // Create kit with default CCTPv2 provider
  * const kit = new BridgeKit()
- * const adapter = createAdapterFromPrivateKey({ privateKey: '0x...' })
+ * const adapter = createViemAdapterFromPrivateKey({ privateKey: '0x...' })
  *
  * // Execute cross-chain transfer
  * const result = await kit.bridge({
@@ -4852,18 +5444,18 @@ class BridgeKit {
      *
      * @param params - The transfer parameters containing source, destination, amount, and token
      * @returns Promise resolving to the transfer result with transaction details and steps
-     * @throws {ValidationError} When any parameter validation fails.
+     * @throws {KitError} When any parameter validation fails.
      * @throws {Error} When CCTPv2 does not support the specified route.
      *
      * @example
      * ```typescript
      * import { BridgeKit } from '@circle-fin/bridge-kit'
-     * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+     * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
      *
      * const kit = new BridgeKit()
      *
      * // Create a single adapter that can work across chains
-     * const adapter = createAdapterFromPrivateKey({
+     * const adapter = createViemAdapterFromPrivateKey({
      *   privateKey: process.env.PRIVATE_KEY,
      * })
      *
@@ -4893,7 +5485,7 @@ class BridgeKit {
     async bridge(params) {
         // First validate the parameters
         assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
-        // Then resolve chain definitions
+        // Then resolve chain definitions (includes adapter chain support validation)
         const resolvedParams = await resolveBridgeParams(params);
         // Validate network compatibility
         this.validateNetworkCompatibility(resolvedParams);
@@ -4902,7 +5494,8 @@ class BridgeKit {
         // Find a provider that supports this route
         const provider = this.findProviderForRoute(finalResolvedParams);
         // Execute the transfer using the provider
-        return provider.bridge(finalResolvedParams);
+        // Format the bridge result into human-readable string values for the user
+        return formatBridgeResult(await provider.bridge(finalResolvedParams), 'to-human-readable');
     }
     /**
      * Retry a failed or incomplete cross-chain USDC bridge operation.
@@ -4935,10 +5528,14 @@ class BridgeKit {
      * @example
      * ```typescript
      * import { BridgeKit } from '@circle-fin/bridge-kit'
-     * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+     * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
      *
      * const kit = new BridgeKit()
      *
+     * // Create adapters for source and destination chains
+     * const sourceAdapter = createViemAdapterFromPrivateKey({ privateKey: '...' })
+     * const destAdapter = createViemAdapterFromPrivateKey({ privateKey: '...' })
+     *
      * // Assume we have a failed bridge result from a previous operation
      * const failedResult: BridgeResult = {
      *   state: 'error',
@@ -4970,7 +5567,11 @@ class BridgeKit {
         if (!provider) {
             throw new Error(`Provider ${result.provider} not found`);
         }
-        return provider.retry(result, context);
+        // 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), 'to-human-readable');
     }
     /**
      * Estimate the cost and fees for a cross-chain USDC bridge operation.
@@ -4980,7 +5581,7 @@ class BridgeKit {
      * as the bridge method but stops before execution.
      * @param params - The bridge parameters for cost estimation
      * @returns Promise resolving to detailed cost breakdown including gas estimates
-     * @throws {ValidationError} When the parameters are invalid.
+     * @throws {KitError} When the parameters are invalid.
      * @throws {UnsupportedRouteError} When the route is not supported.
      *
      * @example
@@ -4997,7 +5598,7 @@ class BridgeKit {
     async estimate(params) {
         // First validate the parameters
         assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
-        // Then resolve chain definitions
+        // Then resolve chain definitions (includes adapter chain support validation)
         const resolvedParams = await resolveBridgeParams(params);
         // Validate network compatibility
         this.validateNetworkCompatibility(resolvedParams);
@@ -5097,7 +5698,7 @@ class BridgeKit {
         const existingFee = providerParams.config?.customFee?.value;
         const existingFeeRecipient = providerParams.config?.customFee?.recipientAddress;
         // Fill missing values using kit-level configuration (if available)
-        const fee = existingFee ?? (await this.customFeePolicy?.calculateFee(providerParams));
+        const fee = existingFee ?? (await this.resolveFee(providerParams));
         const feeRecipient = existingFeeRecipient ??
             (await this.customFeePolicy?.resolveFeeRecipientAddress(providerParams.source.chain, providerParams));
         // Only attach customFee if at least one value is defined
@@ -5113,56 +5714,94 @@ class BridgeKit {
         return providerParams;
     }
     /**
-     * Sets the custom fee policy for the kit.
+     * Resolve the custom fee for a bridge transfer.
      *
-     * Ensures the fee is represented in the smallest unit of the token.
-     * - If the token is USDC, the fee is converted to base units (6 decimals).
-     * - If the token is not USDC, the fee is returned as is.
+     * Checks which fee function the user provided and executes accordingly:
+     * - `computeFee`: receives human-readable amounts, returns human-readable fee
+     * - `calculateFee` (deprecated): receives smallest units, returns smallest units
      *
-     * This allows developers to specify the kit-level fee in base units (e.g., USDC: 1, ETH: 0.000001),
-     * and the kit will handle conversion to the smallest unit as needed.
+     * @param providerParams - The resolved bridge parameters (amounts in smallest units).
+     * @returns The resolved fee in smallest units, or undefined if no fee policy is set.
+     */
+    async resolveFee(providerParams) {
+        if (!this.customFeePolicy) {
+            return undefined;
+        }
+        const token = providerParams.token ?? 'USDC';
+        if (token !== 'USDC') {
+            throw createValidationFailedError$1('token', token, 'Custom fee policy only supports USDC');
+        }
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- intentionally support deprecated calculateFee
+        const { computeFee, calculateFee } = this.customFeePolicy;
+        let fee;
+        if (computeFee) {
+            // Convert amount to human-readable for the user's computeFee
+            const humanReadableParams = {
+                ...providerParams,
+                amount: formatUnits(providerParams.amount, 6),
+            };
+            fee = await computeFee(humanReadableParams);
+        }
+        // Fall back to deprecated calculateFee (receives smallest units)
+        if (calculateFee) {
+            fee = await calculateFee(providerParams);
+        }
+        if (fee) {
+            return parseUnits(fee, 6).toString();
+        }
+        return undefined;
+    }
+    /**
+     * Set the custom fee policy for the kit.
+     *
+     * Use `computeFee` (recommended) for human-readable amounts, or `calculateFee`
+     * (deprecated) for smallest-unit amounts. Only one should be provided.
+     *
+     * ```text
+     * Transfer amount (user input, e.g., 1,000 USDC)
+     *   ↓ Wallet signs for transfer + custom fee (e.g., 1,000 + 10 = 1,010 USDC)
+     *   ↓ Custom fee split (10% Circle, 90% your recipientAddress wallet)
+     *   ↓ Full transfer amount (1,000 USDC) forwarded to CCTPv2
+     *   ↓ CCTPv2 protocol fee (e.g., 0.1 USDC) deducted from transfer amount
+     *   ↓ User receives funds on destination chain (e.g., 999.9 USDC)
+     * ```
      *
      * @param customFeePolicy - The custom fee policy to set.
-     * @throws {ValidationError} If the custom fee policy is invalid or missing required functions
+     * @throws {KitError} If the custom fee policy is invalid or missing required functions
      *
      * @example
      * ```typescript
      * import { BridgeKit } from '@circle-fin/bridge-kit'
-     * import { Blockchain } from '@core/chains'
      *
      * const kit = new BridgeKit()
      *
      * kit.setCustomFeePolicy({
-     *   calculateFee: (params) => {
-     *     // Return decimal string - kit converts to smallest units automatically
-     *     // '0.1' becomes '100000' (0.1 USDC with 6 decimals)
-     *     return params.source.chain.chain === Blockchain.Ethereum_Sepolia
-     *       ? '0.1'  // 0.1 USDC
-     *       : '0.2'; // 0.2 USDC
+     *   // computeFee receives human-readable amounts (e.g., '100' for 100 USDC)
+     *   computeFee: (params) => {
+     *     const amount = parseFloat(params.amount)
+     *
+     *     // 1% fee, bounded to 5-50 USDC
+     *     const fee = Math.min(Math.max(amount * 0.01, 5), 50)
+     *     return fee.toFixed(6)
      *   },
-     *   resolveFeeRecipientAddress: (feePayoutChain, params) => {
-     *     // Return valid address for the source chain
-     *     return params.source.chain.chain === Blockchain.Ethereum_Sepolia
-     *       ? '0x23f9a5BEA7B92a0638520607407BC7f0310aEeD4'
-     *       : '0x1E1A18B7bD95bcFcFb4d6E245D289C1e95547b35';
+     *   resolveFeeRecipientAddress: (feePayoutChain) => {
+     *     return feePayoutChain.type === 'solana'
+     *       ? '9xQeWvG816bUx9EP9MnZ4buHh3A6E2dFQa4Xz6V7C7Gn'
+     *       : '0x23f9a5BEA7B92a0638520607407BC7f0310aEeD4'
      *   },
-     * });
+     * })
+     *
+     * // 100 USDC transfer + 5 USDC custom fee results:
+     * // - Wallet signs for 105 USDC total.
+     * // - Circle receives 0.5 USDC (10% share of the custom fee).
+     * // - Your recipientAddress wallet receives 4.5 USDC.
+     * // - CCTPv2 processes 100 USDC and later deducts its own protocol fee.
      * ```
      */
     setCustomFeePolicy(customFeePolicy) {
         assertCustomFeePolicy(customFeePolicy);
-        const { calculateFee, resolveFeeRecipientAddress } = customFeePolicy;
-        // Format the calculateFee function to convert the fee to the smallest unit of the token
-        const formattedCalculateFee = async (params) => {
-            const fee = await calculateFee(params);
-            const token = params.token ?? 'USDC';
-            return token === 'USDC' ? parseUnits(fee, 6).toString() : fee;
-        };
-        // Return a new custom fee policy with the formatted calculateFee function
-        this.customFeePolicy = {
-            calculateFee: formattedCalculateFee,
-            resolveFeeRecipientAddress,
-        };
+        // Store the policy as-is; resolveFee handles the branching logic
+        this.customFeePolicy = customFeePolicy;
     }
     /**
      * Remove the custom fee policy for the kit.
@@ -5196,5 +5835,6 @@ exports.isFatalError = isFatalError;
 exports.isInputError = isInputError;
 exports.isKitError = isKitError;
 exports.isRetryableError = isRetryableError;
+exports.resolveChainIdentifier = resolveChainIdentifier;
 exports.setExternalPrefix = setExternalPrefix;
 //# sourceMappingURL=index.cjs.map