@circle-fin/adapter-ethers-v6 1.1.0 → 1.2.0

package/index.cjs

@@ -20,247 +20,1055 @@
 
 var ethers = require('ethers');
 var zod = require('zod');
-require('@ethersproject/units');
 var bytes = require('@ethersproject/bytes');
 var address = require('@ethersproject/address');
 var bs58 = require('bs58');
+require('@ethersproject/units');
 
 function _interopDefault (e) { return e && e.__esModule ? e.default : e; }
 
 var bs58__default = /*#__PURE__*/_interopDefault(bs58);
 
 /**
- * Type-safe registry for managing and executing blockchain action handlers.
+ * Valid recoverability values for error handling strategies.
  *
- * Provides a centralized system for registering action handlers with full
- * TypeScript type safety, ensuring that handlers can only be registered
- * with compatible action keys and payload types. Supports both individual
- * handler registration and batch registration operations.
+ * - 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',
+];
+/**
+ * Error type constants for categorizing errors by origin.
+ *
+ * This const object provides a reference for error types, enabling
+ * IDE autocomplete and preventing typos when creating custom errors.
  *
  * @remarks
- * The registry uses a Map internally for O(1) lookups and maintains type
- * safety through generic constraints and careful type assertions. All
- * type assertions are validated at registration time to ensure runtime
- * type safety matches compile-time guarantees.
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * 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'
+ * })
+ * ```
  */
-class ActionRegistry {
-    actionHandlers = new Map();
+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',
+};
+/**
+ * Array of valid error type values for validation.
+ * Derived from ERROR_TYPES const object.
+ */
+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];
+/**
+ * Error code ranges for validation.
+ * Single source of truth for valid error code ranges.
+ */
+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' },
+];
+/**
+ * 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 errorDetailsSchema = zod.z.object({
     /**
-     * Register a type-safe action handler for a specific action key.
-     *
-     * Associates an action handler function with its corresponding action key,
-     * ensuring compile-time type safety between the action and its expected
-     * payload structure. The handler will be available for execution via
-     * {@link executeAction}.
-     *
-     * @typeParam TActionKey - The specific action key being registered.
-     * @param action - The action key to register the handler for.
-     * @param handler - The handler function for processing this action type.
-     * @returns Void.
-     *
-     * @throws Error When action parameter is not a valid string.
-     * @throws TypeError When handler parameter is not a function.
-     *
-     * @example
-     * ```typescript
-     * import { ActionRegistry } from '@core/adapter'
-     * import type { ActionHandler } from '@core/adapter'
-     *
-     * const registry = new ActionRegistry()
-     *
-     * // Register a CCTP deposit handler
-     * const depositHandler: ActionHandler<'cctp.v2.depositForBurn'> = async (params, resolved) => {
-     *   console.log('Processing deposit:', params.amount)
-     *   return {
-     *     chainId: params.chainId,
-     *     data: '0x...',
-     *     to: '0x...',
-     *     value: '0'
-     *   }
-     * }
-     *
-     * registry.registerHandler('cctp.v2.depositForBurn', depositHandler)
-     * ```
+     * 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
      */
-    registerHandler(action, handler) {
-        // Runtime validation for JavaScript consumers
-        if (typeof action !== 'string' || action.length === 0) {
-            throw new TypeError(`Action must be a non-empty string, received: ${typeof action}`);
-        }
-        if (typeof handler !== 'function') {
-            throw new TypeError(`Handler must be a function, received: ${typeof handler}`);
-        }
-        // The handler is upcast to ActionHandler<ActionKeys> for storage,
-        // but type safety is maintained at the call site through the generic constraint
-        this.actionHandlers.set(action, handler);
+    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(),
+});
+
+/**
+ * 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;
     /**
-     * Register multiple action handlers in a single operation.
-     *
-     * Efficiently register multiple handlers from a record object, where keys
-     * are action identifiers and values are their corresponding handler
-     * functions. Provides a convenient way to bulk-register handlers while
-     * maintaining type safety.
-     *
-     * @param handlers - A record mapping action keys to their handler functions.
-     * @returns Void.
-     *
-     * @throws {Error} When handlers parameter is not a valid object.
-     * @throws {Error} When any individual handler registration fails.
+     * Create a new KitError instance.
      *
-     * @example
-     * ```typescript
-     * import { ActionRegistry } from '@core/adapter'
-     * import type { ActionHandler, ActionHandlers } from '@core/adapter'
-     *
-     * const registry = new ActionRegistry()
-     *
-     * // Register multiple handlers at once
-     * const tokenHandlers: ActionHandlers = {
-     *   'token.approve': async (params, resolved) => ({
-     *     chainId: resolved.chain,
-     *     data: '0x095ea7b3...',
-     *     to: params.tokenAddress,
-     *     value: '0'
-     *   }),
-     *   'token.transfer': async (params, resolved) => ({
-     *     chainId: resolved.chain,
-     *     data: '0xa9059cbb...',
-     *     to: params.tokenAddress,
-     *     value: '0'
-     *   })
-     * }
-     *
-     * registry.registerHandlers(tokenHandlers)
-     * console.log('Registered multiple token handlers')
-     * ```
+     * @param details - The error details object containing all required properties.
+     * @throws \{TypeError\} When details parameter is missing or invalid.
      */
-    registerHandlers(handlers) {
-        // Runtime validation for JavaScript consumers
-        if (typeof handlers !== 'object' || handlers === null) {
-            throw new Error(`Handlers must be a non-null object, received: ${typeof handlers}`);
-        }
-        // Register each handler individually to benefit from per-handler validation
-        for (const [action, handler] of Object.entries(handlers)) {
-            this.registerHandler(action, handler);
+    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,
+                },
+            }),
+        });
     }
-    /**
-     * Check whether a specific action is supported by this registry.
-     *
-     * Determine if a handler has been registered for the given action key.
-     * Use this method to conditionally execute actions or provide appropriate
-     * error messages when actions are not available.
-     *
-     * @param action - The action key to check for support.
-     * @returns True if the action is supported, false otherwise.
-     *
-     * @throws {Error} When action parameter is not a valid string.
-     *
-     * @example
-     * ```typescript
-     * import { ActionRegistry } from '@core/adapter'
-     *
-     * const registry = new ActionRegistry()
-     *
-     * // Check if actions are supported before attempting to use them
-     * if (registry.supportsAction('token.approve')) {
-     *   console.log('Token approval is supported')
-     * } else {
-     *   console.log('Token approval not available')
-     * }
-     *
-     * // Conditional logic based on support
-     * const action = 'cctp.v2.depositForBurn'
-     * if (registry.supportsAction(action)) {
-     *   // Safe to execute
-     *   console.log(`${action} is available`)
-     * } else {
-     *   console.warn(`${action} is not registered`)
-     * }
-     * ```
-     */
-    supportsAction(action) {
-        // Runtime validation for JavaScript consumers
-        if (typeof action !== 'string' || action.length === 0) {
-            throw new TypeError(`Action must be a non-empty string, received: ${typeof action}`);
-        }
-        return this.actionHandlers.has(action);
+}
+
+/**
+ * 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 = {
+    /** 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',
+    },
+};
+/**
+ * Standardized error definitions for BALANCE type errors.
+ *
+ * BALANCE errors indicate insufficient funds or allowance issues
+ * that prevent transaction execution.
+ *
+ * @example
+ * ```typescript
+ * import { BalanceError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...BalanceError.INSUFFICIENT_TOKEN,
+ *   recoverability: 'FATAL',
+ *   message: 'Insufficient USDC balance on Ethereum',
+ *   cause: { trace: { required: '100', available: '50' } }
+ * })
+ * ```
+ */
+const BalanceError = {
+    /** Insufficient token balance for transaction */
+    INSUFFICIENT_TOKEN: {
+        code: 9001,
+        name: 'BALANCE_INSUFFICIENT_TOKEN',
+        type: 'BALANCE',
+    },
+    /** Insufficient native token (ETH/SOL/etc) for gas fees */
+    INSUFFICIENT_GAS: {
+        code: 9002,
+        name: 'BALANCE_INSUFFICIENT_GAS',
+        type: 'BALANCE',
+    }};
+/**
+ * Standardized error definitions for ONCHAIN type errors.
+ *
+ * ONCHAIN errors occur during transaction execution, simulation,
+ * or interaction with smart contracts on the blockchain.
+ *
+ * @example
+ * ```typescript
+ * import { OnchainError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...OnchainError.SIMULATION_FAILED,
+ *   recoverability: 'FATAL',
+ *   message: 'Simulation failed: ERC20 transfer amount exceeds balance',
+ *   cause: { trace: { reason: 'ERC20: transfer amount exceeds balance' } }
+ * })
+ * ```
+ */
+const OnchainError = {
+    /** Transaction reverted on-chain after execution */
+    TRANSACTION_REVERTED: {
+        code: 5001,
+        name: 'ONCHAIN_TRANSACTION_REVERTED',
+        type: 'ONCHAIN',
+    },
+    /** Pre-flight transaction simulation failed */
+    SIMULATION_FAILED: {
+        code: 5002,
+        name: 'ONCHAIN_SIMULATION_FAILED',
+        type: 'ONCHAIN',
+    },
+    /** Transaction ran out of gas during execution */
+    OUT_OF_GAS: {
+        code: 5003,
+        name: 'ONCHAIN_OUT_OF_GAS',
+        type: 'ONCHAIN',
+    }};
+/**
+ * Standardized error definitions for RPC type errors.
+ *
+ * RPC errors occur when communicating with blockchain RPC providers,
+ * including endpoint failures, invalid responses, and provider-specific issues.
+ *
+ * @example
+ * ```typescript
+ * import { RpcError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...RpcError.ENDPOINT_ERROR,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'RPC endpoint unavailable on Ethereum',
+ *   cause: { trace: { endpoint: 'https://mainnet.infura.io' } }
+ * })
+ * ```
+ */
+const RpcError = {
+    /** RPC endpoint returned error or is unavailable */
+    ENDPOINT_ERROR: {
+        code: 4001,
+        name: 'RPC_ENDPOINT_ERROR',
+        type: 'RPC',
+    }};
+/**
+ * Standardized error definitions for NETWORK type errors.
+ *
+ * NETWORK errors indicate connectivity issues at the network layer,
+ * including DNS failures, connection timeouts, and unreachable endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { NetworkError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...NetworkError.CONNECTION_FAILED,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'Failed to connect to Ethereum network',
+ *   cause: { trace: { error: 'ECONNREFUSED' } }
+ * })
+ * ```
+ */
+const NetworkError = {
+    /** Network connection failed or unreachable */
+    CONNECTION_FAILED: {
+        code: 3001,
+        name: 'NETWORK_CONNECTION_FAILED',
+        type: 'NETWORK',
+    }};
+
+/**
+ * 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 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);
+}
+
+/**
+ * Creates error for insufficient token balance.
+ *
+ * This error is thrown when a wallet does not have enough tokens to
+ * complete a transaction. The error is FATAL as it requires user
+ * intervention to add funds.
+ *
+ * @param chain - The blockchain network where the balance check failed
+ * @param token - The token symbol (e.g., 'USDC', 'ETH')
+ * @param rawError - The original error from the underlying system (optional)
+ * @returns KitError with insufficient token balance details
+ *
+ * @example
+ * ```typescript
+ * import { createInsufficientTokenBalanceError } from '@core/errors'
+ *
+ * throw createInsufficientTokenBalanceError('Ethereum', 'USDC')
+ * // Message: "Insufficient USDC balance on Ethereum"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With raw error for debugging
+ * try {
+ *   await transfer(...)
+ * } catch (error) {
+ *   throw createInsufficientTokenBalanceError('Base', 'USDC', error)
+ * }
+ * ```
+ */
+function createInsufficientTokenBalanceError(chain, token, rawError) {
+    return new KitError({
+        ...BalanceError.INSUFFICIENT_TOKEN,
+        recoverability: 'FATAL',
+        message: `Insufficient ${token} balance on ${chain}`,
+        cause: {
+            trace: {
+                chain,
+                token,
+                rawError,
+            },
+        },
+    });
+}
+/**
+ * Creates error for insufficient gas funds.
+ *
+ * This error is thrown when a wallet does not have enough native tokens
+ * (ETH, SOL, etc.) to pay for transaction gas fees. The error is FATAL
+ * as it requires user intervention to add gas funds.
+ *
+ * @param chain - The blockchain network where the gas check failed
+ * @param rawError - The original error from the underlying system (optional)
+ * @returns KitError with insufficient gas details
+ *
+ * @example
+ * ```typescript
+ * import { createInsufficientGasError } from '@core/errors'
+ *
+ * throw createInsufficientGasError('Ethereum')
+ * // Message: "Insufficient gas funds on Ethereum"
+ * ```
+ */
+function createInsufficientGasError(chain, rawError) {
+    return new KitError({
+        ...BalanceError.INSUFFICIENT_GAS,
+        recoverability: 'FATAL',
+        message: `Insufficient gas funds on ${chain}`,
+        cause: {
+            trace: {
+                chain,
+                rawError,
+            },
+        },
+    });
+}
+
+/**
+ * Creates error for transaction simulation failures.
+ *
+ * This error is thrown when a pre-flight transaction simulation fails,
+ * typically due to contract logic that would revert. The error is FATAL
+ * as it indicates the transaction would fail if submitted.
+ *
+ * @param chain - The blockchain network where the simulation failed
+ * @param reason - The reason for simulation failure (e.g., revert message)
+ * @param rawError - The original error from the underlying system (optional)
+ * @returns KitError with simulation failure details
+ *
+ * @example
+ * ```typescript
+ * import { createSimulationFailedError } from '@core/errors'
+ *
+ * throw createSimulationFailedError('Ethereum', 'ERC20: insufficient allowance')
+ * // Message: "Simulation failed on Ethereum: ERC20: insufficient allowance"
+ * ```
+ */
+function createSimulationFailedError(chain, reason, rawError) {
+    return new KitError({
+        ...OnchainError.SIMULATION_FAILED,
+        recoverability: 'FATAL',
+        message: `Simulation failed on ${chain}: ${reason}`,
+        cause: {
+            trace: {
+                chain,
+                reason,
+                rawError,
+            },
+        },
+    });
+}
+/**
+ * Creates error for transaction reverts.
+ *
+ * This error is thrown when a transaction is submitted and confirmed
+ * but reverts on-chain. The error is FATAL as it indicates the
+ * transaction executed but failed.
+ *
+ * @param chain - The blockchain network where the transaction reverted
+ * @param reason - The reason for the revert (e.g., revert message)
+ * @param rawError - The original error from the underlying system (optional)
+ * @returns KitError with transaction revert details
+ *
+ * @example
+ * ```typescript
+ * import { createTransactionRevertedError } from '@core/errors'
+ *
+ * throw createTransactionRevertedError('Base', 'Slippage exceeded')
+ * // Message: "Transaction reverted on Base: Slippage exceeded"
+ * ```
+ */
+function createTransactionRevertedError(chain, reason, rawError) {
+    return new KitError({
+        ...OnchainError.TRANSACTION_REVERTED,
+        recoverability: 'FATAL',
+        message: `Transaction reverted on ${chain}: ${reason}`,
+        cause: {
+            trace: {
+                chain,
+                reason,
+                rawError,
+            },
+        },
+    });
+}
+/**
+ * Creates error for out of gas failures.
+ *
+ * This error is thrown when a transaction runs out of gas during execution.
+ * The error is FATAL as it requires adjusting gas limits or transaction logic.
+ *
+ * @param chain - The blockchain network where the transaction ran out of gas
+ * @param rawError - The original error from the underlying system (optional)
+ * @returns KitError with out of gas details
+ *
+ * @example
+ * ```typescript
+ * import { createOutOfGasError } from '@core/errors'
+ *
+ * throw createOutOfGasError('Polygon')
+ * // Message: "Transaction ran out of gas on Polygon"
+ * ```
+ */
+function createOutOfGasError(chain, rawError) {
+    return new KitError({
+        ...OnchainError.OUT_OF_GAS,
+        recoverability: 'FATAL',
+        message: `Transaction ran out of gas on ${chain}`,
+        cause: {
+            trace: {
+                chain,
+                rawError,
+            },
+        },
+    });
+}
+
+/**
+ * Creates error for RPC endpoint failures.
+ *
+ * This error is thrown when an RPC provider endpoint fails, returns an error,
+ * or is unavailable. The error is RETRYABLE as RPC issues are often temporary.
+ *
+ * @param chain - The blockchain network where the RPC error occurred
+ * @param rawError - The original error from the underlying system (optional)
+ * @returns KitError with RPC endpoint error details
+ *
+ * @example
+ * ```typescript
+ * import { createRpcEndpointError } from '@core/errors'
+ *
+ * throw createRpcEndpointError('Ethereum')
+ * // Message: "RPC endpoint error on Ethereum"
+ * ```
+ */
+function createRpcEndpointError(chain, rawError) {
+    return new KitError({
+        ...RpcError.ENDPOINT_ERROR,
+        recoverability: 'RETRYABLE',
+        message: `RPC endpoint error on ${chain}`,
+        cause: {
+            trace: {
+                chain,
+                rawError,
+            },
+        },
+    });
+}
+
+/**
+ * Creates error for network connection failures.
+ *
+ * This error is thrown when network connectivity issues prevent reaching
+ * the blockchain network. The error is RETRYABLE as network issues are
+ * often temporary.
+ *
+ * @param chain - The blockchain network where the connection failed
+ * @param rawError - The original error from the underlying system (optional)
+ * @returns KitError with network connection error details
+ *
+ * @example
+ * ```typescript
+ * import { createNetworkConnectionError } from '@core/errors'
+ *
+ * throw createNetworkConnectionError('Ethereum')
+ * // Message: "Network connection failed for Ethereum"
+ * ```
+ */
+function createNetworkConnectionError(chain, rawError) {
+    return new KitError({
+        ...NetworkError.CONNECTION_FAILED,
+        recoverability: 'RETRYABLE',
+        message: `Network connection failed for ${chain}`,
+        cause: {
+            trace: {
+                chain,
+                rawError,
+            },
+        },
+    });
+}
+
+/**
+ * Parses raw blockchain errors into structured KitError instances.
+ *
+ * This function uses pattern matching to identify common blockchain error
+ * types and converts them into standardized KitError format. It handles
+ * errors from viem, ethers, Solana web3.js, and other blockchain libraries.
+ *
+ * The parser recognizes 5 main error patterns:
+ * 1. Insufficient balance errors
+ * 2. Simulation/execution reverted errors
+ * 3. Gas-related errors
+ * 4. Network connectivity errors
+ * 5. RPC provider errors
+ *
+ * @param error - The raw error from the blockchain library
+ * @param context - Context information including chain and optional token
+ * @returns A structured KitError instance
+ *
+ * @example
+ * ```typescript
+ * import { parseBlockchainError } from '@core/errors'
+ *
+ * try {
+ *   await walletClient.sendTransaction(...)
+ * } catch (error) {
+ *   throw parseBlockchainError(error, {
+ *     chain: 'Ethereum',
+ *     token: 'USDC',
+ *     operation: 'transfer'
+ *   })
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Minimal usage
+ * try {
+ *   await connection.sendTransaction(...)
+ * } catch (error) {
+ *   throw parseBlockchainError(error, { chain: 'Solana' })
+ * }
+ * ```
+ */
+function parseBlockchainError(error, context) {
+    const msg = extractMessage(error);
+    const token = context.token ?? 'token';
+    // Pattern 1: Insufficient balance errors
+    // Matches balance-related errors from ERC20 contracts, native transfers, and Solana programs
+    if (/transfer amount exceeds balance|insufficient (balance|funds)|burn amount exceeded/i.test(msg)) {
+        return createInsufficientTokenBalanceError(context.chain, token, error);
     }
-    /**
-     * Execute a registered action handler with type-safe parameters.
-     *
-     * Look up and execute the handler associated with the given action key,
-     * passing the provided parameters and context, returning the resulting prepared
-     * chain request. TypeScript ensures the parameters match the expected
-     * structure for the specified action.
-     *
-     * @typeParam TActionKey - The specific action key being executed.
-     * @param action - The action key identifying which handler to execute.
-     * @param params - The parameters to pass to the action handler.
-     * @param context - The resolved operation context with concrete chain and address values.
-     * @returns A promise resolving to the prepared chain request.
-     *
-     * @throws {Error} When action parameter is not a valid string.
-     * @throws {Error} When no handler is registered for the specified action.
-     * @throws {Error} When the handler execution fails.
-     *
-     * @example
-     * ```typescript
-     * import { ActionRegistry } from '@core/adapter'
-     * import type { ChainEnum } from '@core/chains'
-     *
-     * const registry = new ActionRegistry()
-     *
-     * // First register a handler
-     * registry.registerHandler('token.approve', async (params, context) => ({
-     *   chainId: context.chain, // Always defined
-     *   data: '0x095ea7b3...',
-     *   to: params.tokenAddress,
-     *   value: '0'
-     * }))
-     *
-     * // Execute the action with resolved context (typically called from adapter.prepareAction)
-     * const resolvedContext = { chain: 'Base', address: '0x123...' }
-     * const result = await registry.executeAction('token.approve', {
-     *   chainId: ChainEnum.Ethereum,
-     *   tokenAddress: '0xA0b86a33E6441c8C1c7C16e4c5e3e5b5e4c5e3e5b5e4c5e',
-     *   delegate: '0x1234567890123456789012345678901234567890',
-     *   amount: '1000000'
-     * }, resolvedContext)
-     *
-     * console.log('Transaction prepared:', result.data)
-     * ```
-     */
-    async executeAction(action, params, context) {
-        // Runtime validation for JavaScript consumers
-        if (typeof action !== 'string' || action.length === 0) {
-            throw new TypeError(`Action must be a non-empty string, received: ${typeof action}`);
+    // Pattern 2: Simulation and execution reverts
+    // Matches contract revert errors and simulation failures
+    if (/execution reverted|simulation failed|transaction reverted|transaction failed/i.test(msg)) {
+        const reason = extractRevertReason(msg) ?? 'Transaction reverted';
+        // Distinguish between simulation failures and transaction reverts
+        // "simulation failed" or "eth_call" indicates pre-flight simulation
+        // "transaction failed" or context.operation === 'transaction' indicates post-execution
+        if (/simulation failed/i.test(msg) || context.operation === 'simulation') {
+            return createSimulationFailedError(context.chain, reason, error);
         }
-        const handler = this.actionHandlers.get(action);
-        if (!handler) {
-            throw new Error(`Action ${action} is not supported`);
-        }
-        try {
-            // Type safety is guaranteed by the registration process
-            return await handler(params, context);
+        // Transaction execution failures or reverts
+        return createTransactionRevertedError(context.chain, reason, error);
+    }
+    // Pattern 3: Gas-related errors
+    // Matches gas estimation failures and gas exhaustion
+    // Check specific patterns first, then generic "gas" patterns
+    // Gas estimation failures are RPC issues
+    if (/gas estimation failed|cannot estimate gas/i.test(msg)) {
+        return createRpcEndpointError(context.chain, error);
+    }
+    // Gas exhaustion errors
+    // Use specific patterns without wildcards to avoid ReDoS
+    if (/out of gas|gas limit exceeded|exceeds block gas limit/i.test(msg)) {
+        return createOutOfGasError(context.chain, error);
+    }
+    // Insufficient funds for gas
+    if (/insufficient funds for gas/i.test(msg)) {
+        return createInsufficientGasError(context.chain, error);
+    }
+    // Pattern 4: Network connectivity errors
+    // Matches connection failures, DNS errors, and timeouts
+    if (/connection (refused|failed)|network|timeout|ENOTFOUND|ECONNREFUSED/i.test(msg)) {
+        return createNetworkConnectionError(context.chain, error);
+    }
+    // Pattern 5: RPC provider errors
+    // Matches RPC endpoint errors, invalid responses, and rate limits
+    if (/rpc|invalid response|rate limit|too many requests/i.test(msg)) {
+        return createRpcEndpointError(context.chain, error);
+    }
+    // Fallback based on operation context
+    // Gas-related operations are RPC calls
+    if (context.operation === 'estimateGas' ||
+        context.operation === 'getGasPrice') {
+        return createRpcEndpointError(context.chain, error);
+    }
+    // Fallback for unrecognized errors
+    // Defaults to simulation failed as transaction execution is the most common failure point
+    return createSimulationFailedError(context.chain, msg.length > 0 ? msg : 'Unknown error', error);
+}
+/**
+ * Type guard to check if error has Solana-Kit structure with logs.
+ *
+ * Checks if the error object contains a context with logs array,
+ * which is the structure used by Solana Kit errors.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error has Solana-Kit logs structure
+ */
+function hasSolanaLogs(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'context' in error &&
+        error.context !== null &&
+        typeof error.context === 'object' &&
+        'logs' in error.context &&
+        Array.isArray(error.context.logs));
+}
+/**
+ * Extracts a human-readable error message from various error types.
+ *
+ * Handles Error objects, string errors, objects with message properties,
+ * Solana-Kit errors with context logs, and falls back to string representation.
+ * For Solana-Kit errors, extracts Anchor error messages from transaction logs.
+ *
+ * @param error - Unknown error to extract message from
+ * @returns Extracted error message string
+ *
+ * @example
+ * ```typescript
+ * const msg1 = extractMessage(new Error('test'))  // 'test'
+ * const msg2 = extractMessage('string error')     // 'string error'
+ * const msg3 = extractMessage({ message: 'obj' }) // 'obj'
+ * ```
+ */
+function extractMessage(error) {
+    // Check for Solana-Kit errors with context.logs
+    if (hasSolanaLogs(error)) {
+        // Extract Anchor error message from logs
+        const anchorLog = error.context.logs.find((log) => log.includes('AnchorError') || log.includes('Error Message'));
+        if (anchorLog !== undefined) {
+            // Return the anchor error log which contains the detailed message
+            return anchorLog;
         }
-        catch (error) {
-            // Re-throw with context for better debugging
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to execute action ${action}: ${message}`);
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (typeof error === 'object' && error !== null && 'message' in error) {
+        return String(error.message);
+    }
+    return String(error);
+}
+/**
+ * Extracts the revert reason from an error message.
+ *
+ * Attempts to parse out the meaningful reason from execution revert errors,
+ * removing common prefixes like "execution reverted:" or "reverted:".
+ *
+ * @param msg - The error message to extract from
+ * @returns The extracted revert reason, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const reason = extractRevertReason(
+ *   'execution reverted: ERC20: transfer amount exceeds balance'
+ * )
+ * // Returns: 'ERC20: transfer amount exceeds balance'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const reason = extractRevertReason(
+ *   'Simulation failed: Execution reverted with reason: Insufficient allowance'
+ * )
+ * // Returns: 'Insufficient allowance'
+ * ```
+ */
+function extractRevertReason(msg) {
+    // Try to extract reason after "execution reverted:" or "reason:"
+    // Use [^\n.]+ instead of .+? to avoid ReDoS vulnerability
+    const patterns = [
+        /(?:execution reverted|reverted):\s*([^\n.]+)/i,
+        /reason:\s*([^\n.]+)/i,
+        /with reason:\s*([^\n.]+)/i,
+    ];
+    for (const pattern of patterns) {
+        const match = pattern.exec(msg);
+        const extractedReason = match?.at(1);
+        if (extractedReason !== undefined && extractedReason.length > 0) {
+            return extractedReason.trim();
         }
     }
+    return null;
 }
 
 // -----------------------------------------------------------------------------
 // Blockchain Enum
 // -----------------------------------------------------------------------------
 /**
- * Enumeration of all blockchains supported by this library.
+ * 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 supported blockchain.
+ * @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) {
@@ -320,6 +1128,95 @@ exports.Blockchain = void 0;
     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.
+ */
+var BridgeChain;
+(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";
+})(BridgeChain || (BridgeChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -2608,6 +3505,44 @@ zod.z.union([
     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.
+ */
+zod.z.union([
+    zod.z.string().refine((val) => val in 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 BridgeChain, (chainDef) => ({
+        message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
+    })),
+]);
 
 /**
  * Get all supported EVM chain definitions.
@@ -2755,7 +3690,235 @@ const resolveCCTPV2ContractAddress = (chain, contractType) => {
             throw new Error(`Unsupported CCTP v2 contract type on chain ${chain.name}. Expected "split" or "merged", but received '${unknownContract.type ?? 'unknown'}'.`);
         }
     }
-};
+};
+
+/**
+ * Type-safe registry for managing and executing blockchain action handlers.
+ *
+ * Provides a centralized system for registering action handlers with full
+ * TypeScript type safety, ensuring that handlers can only be registered
+ * with compatible action keys and payload types. Supports both individual
+ * handler registration and batch registration operations.
+ *
+ * @remarks
+ * The registry uses a Map internally for O(1) lookups and maintains type
+ * safety through generic constraints and careful type assertions. All
+ * type assertions are validated at registration time to ensure runtime
+ * type safety matches compile-time guarantees.
+ */
+class ActionRegistry {
+    actionHandlers = new Map();
+    /**
+     * Register a type-safe action handler for a specific action key.
+     *
+     * Associates an action handler function with its corresponding action key,
+     * ensuring compile-time type safety between the action and its expected
+     * payload structure. The handler will be available for execution via
+     * {@link executeAction}.
+     *
+     * @typeParam TActionKey - The specific action key being registered.
+     * @param action - The action key to register the handler for.
+     * @param handler - The handler function for processing this action type.
+     * @returns Void.
+     *
+     * @throws Error When action parameter is not a valid string.
+     * @throws TypeError When handler parameter is not a function.
+     *
+     * @example
+     * ```typescript
+     * import { ActionRegistry } from '@core/adapter'
+     * import type { ActionHandler } from '@core/adapter'
+     *
+     * const registry = new ActionRegistry()
+     *
+     * // Register a CCTP deposit handler
+     * const depositHandler: ActionHandler<'cctp.v2.depositForBurn'> = async (params, resolved) => {
+     *   console.log('Processing deposit:', params.amount)
+     *   return {
+     *     chainId: params.chainId,
+     *     data: '0x...',
+     *     to: '0x...',
+     *     value: '0'
+     *   }
+     * }
+     *
+     * registry.registerHandler('cctp.v2.depositForBurn', depositHandler)
+     * ```
+     */
+    registerHandler(action, handler) {
+        // Runtime validation for JavaScript consumers
+        if (typeof action !== 'string' || action.length === 0) {
+            throw new TypeError(`Action must be a non-empty string, received: ${typeof action}`);
+        }
+        if (typeof handler !== 'function') {
+            throw new TypeError(`Handler must be a function, received: ${typeof handler}`);
+        }
+        // The handler is upcast to ActionHandler<ActionKeys> for storage,
+        // but type safety is maintained at the call site through the generic constraint
+        this.actionHandlers.set(action, handler);
+    }
+    /**
+     * Register multiple action handlers in a single operation.
+     *
+     * Efficiently register multiple handlers from a record object, where keys
+     * are action identifiers and values are their corresponding handler
+     * functions. Provides a convenient way to bulk-register handlers while
+     * maintaining type safety.
+     *
+     * @param handlers - A record mapping action keys to their handler functions.
+     * @returns Void.
+     *
+     * @throws {Error} When handlers parameter is not a valid object.
+     * @throws {Error} When any individual handler registration fails.
+     *
+     * @example
+     * ```typescript
+     * import { ActionRegistry } from '@core/adapter'
+     * import type { ActionHandler, ActionHandlers } from '@core/adapter'
+     *
+     * const registry = new ActionRegistry()
+     *
+     * // Register multiple handlers at once
+     * const tokenHandlers: ActionHandlers = {
+     *   'token.approve': async (params, resolved) => ({
+     *     chainId: resolved.chain,
+     *     data: '0x095ea7b3...',
+     *     to: params.tokenAddress,
+     *     value: '0'
+     *   }),
+     *   'token.transfer': async (params, resolved) => ({
+     *     chainId: resolved.chain,
+     *     data: '0xa9059cbb...',
+     *     to: params.tokenAddress,
+     *     value: '0'
+     *   })
+     * }
+     *
+     * registry.registerHandlers(tokenHandlers)
+     * console.log('Registered multiple token handlers')
+     * ```
+     */
+    registerHandlers(handlers) {
+        // Runtime validation for JavaScript consumers
+        if (typeof handlers !== 'object' || handlers === null) {
+            throw new Error(`Handlers must be a non-null object, received: ${typeof handlers}`);
+        }
+        // Register each handler individually to benefit from per-handler validation
+        for (const [action, handler] of Object.entries(handlers)) {
+            this.registerHandler(action, handler);
+        }
+    }
+    /**
+     * Check whether a specific action is supported by this registry.
+     *
+     * Determine if a handler has been registered for the given action key.
+     * Use this method to conditionally execute actions or provide appropriate
+     * error messages when actions are not available.
+     *
+     * @param action - The action key to check for support.
+     * @returns True if the action is supported, false otherwise.
+     *
+     * @throws {Error} When action parameter is not a valid string.
+     *
+     * @example
+     * ```typescript
+     * import { ActionRegistry } from '@core/adapter'
+     *
+     * const registry = new ActionRegistry()
+     *
+     * // Check if actions are supported before attempting to use them
+     * if (registry.supportsAction('token.approve')) {
+     *   console.log('Token approval is supported')
+     * } else {
+     *   console.log('Token approval not available')
+     * }
+     *
+     * // Conditional logic based on support
+     * const action = 'cctp.v2.depositForBurn'
+     * if (registry.supportsAction(action)) {
+     *   // Safe to execute
+     *   console.log(`${action} is available`)
+     * } else {
+     *   console.warn(`${action} is not registered`)
+     * }
+     * ```
+     */
+    supportsAction(action) {
+        // Runtime validation for JavaScript consumers
+        if (typeof action !== 'string' || action.length === 0) {
+            throw new TypeError(`Action must be a non-empty string, received: ${typeof action}`);
+        }
+        return this.actionHandlers.has(action);
+    }
+    /**
+     * Execute a registered action handler with type-safe parameters.
+     *
+     * Look up and execute the handler associated with the given action key,
+     * passing the provided parameters and context, returning the resulting prepared
+     * chain request. TypeScript ensures the parameters match the expected
+     * structure for the specified action.
+     *
+     * @typeParam TActionKey - The specific action key being executed.
+     * @param action - The action key identifying which handler to execute.
+     * @param params - The parameters to pass to the action handler.
+     * @param context - The resolved operation context with concrete chain and address values.
+     * @returns A promise resolving to the prepared chain request.
+     * @throws {KitError} When the handler execution fails with a structured error.
+     * @throws {Error} When no handler is registered for the specified action.
+     * @throws {Error} When the handler execution fails with an unstructured error.
+     *
+     * @example
+     * ```typescript
+     * import { ActionRegistry } from '@core/adapter'
+     * import type { ChainEnum } from '@core/chains'
+     *
+     * const registry = new ActionRegistry()
+     *
+     * // First register a handler
+     * registry.registerHandler('token.approve', async (params, context) => ({
+     *   chainId: context.chain, // Always defined
+     *   data: '0x095ea7b3...',
+     *   to: params.tokenAddress,
+     *   value: '0'
+     * }))
+     *
+     * // Execute the action with resolved context (typically called from adapter.prepareAction)
+     * const resolvedContext = { chain: 'Base', address: '0x123...' }
+     * const result = await registry.executeAction('token.approve', {
+     *   chainId: ChainEnum.Ethereum,
+     *   tokenAddress: '0xA0b86a33E6441c8C1c7C16e4c5e3e5b5e4c5e3e5b5e4c5e',
+     *   delegate: '0x1234567890123456789012345678901234567890',
+     *   amount: '1000000'
+     * }, resolvedContext)
+     *
+     * console.log('Transaction prepared:', result.data)
+     * ```
+     */
+    async executeAction(action, params, context) {
+        // Runtime validation for JavaScript consumers
+        if (typeof action !== 'string' || action.length === 0) {
+            throw new TypeError(`Action must be a non-empty string, received: ${typeof action}`);
+        }
+        const handler = this.actionHandlers.get(action);
+        if (!handler) {
+            throw new Error(`Action ${action} is not supported`);
+        }
+        try {
+            // Type safety is guaranteed by the registration process
+            return await handler(params, context);
+        }
+        catch (error) {
+            // If it's already a KitError with structured information, re-throw as-is
+            // to preserve error code, name, type, recoverability, and cause
+            if (error instanceof KitError) {
+                throw error;
+            }
+            // For other errors, re-throw with context for better debugging
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to execute action ${action}: ${message}`);
+        }
+    }
+}
 
 /**
  * Resolves an operation context into concrete chain and address values.
@@ -2826,281 +3989,17 @@ async function resolveOperationContext(adapter, ctx) {
         try {
             // Pass resolved chain to getAddress for adapters that support it (like ViemAdapter)
             // The chain parameter is optional in implementations, so this is safe
-            resolvedAddress = await adapter.getAddress(resolvedChain);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to resolve address from user-controlled adapter: ${message}`);
-        }
-    }
-    return {
-        chain: resolvedChain,
-        address: resolvedAddress,
-    };
-}
-
-/**
- * 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
- */
-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 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: 'NETWORK_MISMATCH',
- *   recoverability: 'FATAL',
- *   message: 'Source and destination networks must be different'
- * })
- *
- * if (!result.success) {
- *   console.error('Validation failed:', result.error.issues)
- * }
- * ```
- */
-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(),
-});
-
-/**
- * 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;
-}
-
-/**
- * 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 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,
-                },
-            }),
-        });
-    }
-}
-
-/**
- * Minimum error code for INPUT type errors.
- * INPUT errors represent validation failures and invalid parameters.
- */
-/**
- * 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.
- *
- * 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 and name individually if needed
- * console.log(InputError.NETWORK_MISMATCH.code)  // 1001
- * console.log(InputError.NETWORK_MISMATCH.name)  // 'INPUT_NETWORK_MISMATCH'
- * ```
- */
-const InputError = {
-    /** Unsupported or invalid bridge route configuration */
-    UNSUPPORTED_ROUTE: {
-        code: 1003,
-        name: 'INPUT_UNSUPPORTED_ROUTE',
-    }};
-
-/**
- * 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 },
-        },
+            resolvedAddress = await adapter.getAddress(resolvedChain);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to resolve address from user-controlled adapter: ${message}`);
+        }
+    }
+    return {
+        chain: resolvedChain,
+        address: resolvedAddress,
     };
-    return new KitError(errorDetails);
 }
 
 /**
@@ -3248,45 +4147,28 @@ class Adapter {
      * Validate that the target chain is supported by this adapter.
      *
      * @param targetChain - The chain to validate.
-     * @throws Error if the chain is not supported.
+     * @throws KitError with INVALID_CHAIN code if the chain is not supported by this adapter.
      */
     validateChainSupport(targetChain) {
         if (this.capabilities?.supportedChains) {
             const isSupported = this.capabilities.supportedChains.some((supportedChain) => supportedChain.chain === targetChain.chain);
             if (!isSupported) {
                 const supportedCount = this.capabilities.supportedChains.length;
-                const message = `Chain ${targetChain.name} (${targetChain.type}) is not supported by this adapter (supports ${supportedCount.toString()} chains)`;
-                throw createUnsupportedRouteError(targetChain.name, message);
+                // List supported chain names for better user experience
+                const supportedChainNames = this.capabilities.supportedChains
+                    .map((chainDef) => chainDef.name)
+                    .join(', ');
+                const reason = `Not supported by this adapter. It supports ${supportedCount.toString()} ${supportedCount === 1 ? 'chain' : 'chains'}: ${supportedChainNames}`;
+                throw createInvalidChainError(targetChain.name, reason);
             }
         }
         else if (this.chainType && targetChain.type !== this.chainType) {
-            const message = `Chain type mismatch: adapter supports ${this.chainType} chains, but received ${targetChain.type} chain: ${targetChain.name}`;
-            throw createUnsupportedRouteError(targetChain.name, message);
+            const reason = `Chain type mismatch: adapter supports ${this.chainType} chains, but received ${targetChain.type ?? 'unknown'} chain`;
+            throw createInvalidChainError(targetChain.name, reason);
         }
     }
 }
 
-/**
- * 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.
  *
@@ -3294,23 +4176,22 @@ const formatZodError = (error) => {
  * messages that include the validation context. It's designed to give developers
  * clear feedback about what went wrong during validation.
  *
+ * @param value - The value to validate
  * @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
+ * @returns Asserts that value is of type T (type narrowing)
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098)
  *
  * @example
  * ```typescript
- * const result = validate(BridgeParamsSchema, params, 'bridge parameters')
+ * validate(params, BridgeParamsSchema, 'bridge parameters')
+ * // After this call, TypeScript knows params is of type BridgeParams
  * ```
  */
 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);
+        throw createValidationErrorFromZod(result.error, context);
     }
 }
 
@@ -3328,11 +4209,12 @@ const VALIDATION_STATE = Symbol('validationState');
  * 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 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 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
@@ -3342,20 +4224,41 @@ const VALIDATION_STATE = Symbol('validationState');
 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`,
-        ]);
+        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 ValidationError(`Invalid ${context}: Value is undefined`, [
-            `Value is 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 ValidationError(`Invalid ${context}: Value must be an object`, [
-            `Value must be an object, got ${typeof value}`,
-        ]);
+        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;
@@ -3364,7 +4267,7 @@ function validateWithStateTracking(value, schema, context, validatorName) {
     if (state.validatedBy.includes(validatorName)) {
         return;
     }
-    // Delegate to the validate function for actual validation
+    // Delegate to the validate function for actual validation (now throws KitError)
     validate(value, schema, context);
     // Update validation state
     state.validatedBy.push(validatorName);
@@ -3419,7 +4322,7 @@ zod.z
     .url('Generated explorer URL is invalid');
 
 /**
- * Validates data against a Zod schema and throws a ValidationError on failure.
+ * Validates data against a Zod schema and throws a KitError on failure.
  *
  * This utility function provides consistent validation and error formatting across the codebase.
  * It performs the validation and formats error messages with contextual information while
@@ -3428,7 +4331,8 @@ zod.z
  * @param value - The value to validate
  * @param schema - The Zod schema to validate against
  * @param message - Error message (e.g., 'Invalid EVM address', 'Configuration error')
- * @throws {ValidationError} If validation fails, with formatted error details and all individual errors
+ * @returns Asserts that value is of type T (type narrowing)
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098) and detailed error information
  *
  * @example
  * ```typescript
@@ -3440,10 +4344,9 @@ zod.z
  *   age: z.number().positive()
  * })
  *
- * // This will throw ValidationError if validation fails
+ * // This will throw KitError if validation fails
  * validateOrThrow({ name: 'Jo', age: -1 }, userSchema, 'Invalid user data')
- * // Throws: ValidationError("Invalid user data: name: String must contain at least 3 character(s)",
- * //                       ["name: String must contain at least 3 character(s)", "age: Number must be greater than 0"])
+ * // Throws: KitError with code 1098 and message "Invalid user data: name: String must contain at least 3 character(s)"
  * ```
  *
  * @example
@@ -3466,13 +4369,7 @@ zod.z
 function validateOrThrow(value, schema, message) {
     const result = schema.safeParse(value);
     if (!result.success) {
-        const errors = result.error.errors.map((error) => {
-            const path = error.path.length > 0 ? `${error.path.join('.')}: ` : '';
-            return `${path}${error.message}`;
-        });
-        const firstError = errors[0];
-        const errorMessage = firstError !== undefined ? `${message}: ${firstError}` : message;
-        throw new ValidationError(errorMessage, errors);
+        throw createValidationErrorFromZod(result.error, message);
     }
 }
 
@@ -3650,7 +4547,7 @@ const convertAddress = (address, targetFormat) => {
  * 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
@@ -3681,7 +4578,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
@@ -3701,7 +4598,7 @@ const evmAddressSchema = hexStringSchema.refine((value) => value.length === 42,
  * - 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
@@ -3727,7 +4624,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
@@ -3759,7 +4656,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
@@ -3779,7 +4676,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
@@ -3808,7 +4705,7 @@ const adapterSchema = zod.z.object({
  * - A valid EVM address
  *
  * @param address - The address to validate
- * @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
@@ -8348,7 +9245,9 @@ function isReadOnlyFunction(abi, functionName, defaultValue) {
  * to EVM adapters (Ethers, Viem, etc.). For non-EVM adapters, a different validation
  * schema should be used.
  *
- * @throws Error if validation fails, with details about which properties failed
+ * When used with the validate() function from @core/utils, this throws KitError
+ * with INPUT_VALIDATION_FAILED code if validation fails, with details about which
+ * properties failed.
  *
  * @example
  * ```typescript
@@ -8379,7 +9278,7 @@ function isReadOnlyFunction(abi, functionName, defaultValue) {
  *   supportedChains: [{ type: 'solana', name: 'Solana', chainId: 0 }]
  * }
  *
- * AdapterCapabilitiesSchema.parse(invalidCapabilities) // throws ValidationError
+ * AdapterCapabilitiesSchema.parse(invalidCapabilities) // throws Zod validation error
  * ```
  */
 const AdapterCapabilitiesSchema = zod.z
@@ -8424,7 +9323,7 @@ const AdapterCapabilitiesSchema = zod.z
  * specification with all required fields and proper types. The domain
  * separator prevents signature replay attacks across different domains.
  *
- * @throws \{ValidationError\} If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -8482,7 +9381,7 @@ const eip712DomainSchema = zod.z.object({
  * This schema validates individual field definitions within EIP-712 type
  * definitions. Each field must have a name and a valid Solidity type.
  *
- * @throws \{ValidationError\} If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -8522,7 +9421,7 @@ const typedDataFieldSchema = zod.z.object({
  * domain, types, primaryType, and message. It ensures all components are
  * properly structured and the primaryType exists in the types definition.
  *
- * @throws \{ValidationError\} If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -8600,7 +9499,7 @@ const abiParameterSchema = zod.z.object({
  * This schema validates individual ABI entries that describe contract functions,
  * constructors, events, and other contract interface elements.
  *
- * @throws \{ValidationError\} If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -8644,7 +9543,7 @@ const abiEntrySchema = zod.z.object({
  * This schema validates arrays of ABI entries, ensuring each entry is properly
  * structured for contract interaction.
  *
- * @throws \{ValidationError\} If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -8675,7 +9574,7 @@ const abiSchema = zod.z
  * - An actionRegistry with registerHandlers method and actionHandlers record
  * - A prepare method for creating chain requests
  *
- * @throws \{ValidationError\} If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -8709,7 +9608,7 @@ adapterSchema.extend({
  * This schema validates the parameters needed to execute a contract call on an EVM-compatible chain.
  * It ensures proper formatting of addresses, ABI structure, and function parameters.
  *
- * @throws \{ValidationError\} If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -8761,7 +9660,7 @@ const evmPreparedChainRequestParamsSchema = zod.z.object({
  * - Must be exactly 66 characters long (0x + 64 hex characters)
  * - Must contain only valid hexadecimal characters (0-9, a-f, A-F)
  *
- * @throws \{ValidationError\} If validation fails, with details about which properties failed
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -8804,7 +9703,7 @@ const evmTransactionHashSchema = zod.z
  * This is a shared schema used by both ethers.v6 and viem.v2 adapters to ensure
  * consistent private key validation across all EVM adapters.
  *
- * @throws \{ValidationError\} If validation fails, with details about the issue
+ * @throws KitError if validation fails
  *
  * @example
  * ```typescript
@@ -8840,7 +9739,7 @@ const assertEvmPreparedChainRequestParamsSymbol = Symbol('assertEvmPreparedChain
  * - Arguments that match the function signature
  *
  * @param params - The parameters to validate
- * @throws ValidationError If validation fails, with details about which properties failed
+ * @throws KitError with INPUT_VALIDATION_FAILED code if validation fails, with details about which properties failed
  *
  * @example
  * ```typescript
@@ -8855,7 +9754,7 @@ const assertEvmPreparedChainRequestParamsSymbol = Symbol('assertEvmPreparedChain
  *   args: ['0xSpenderAddress', BigInt(1000000)]
  * }
  *
- * // This will throw if validation fails
+ * // This will throw KitError if validation fails
  * assertEvmPreparedChainRequestParams(requestParams)
  *
  * // If we get here, request parameters are guaranteed to be valid
@@ -8876,7 +9775,7 @@ function assertEvmPreparedChainRequestParams(params) {
  * - Must contain only valid hexadecimal characters (0-9, a-f, A-F)
  *
  * @param txHash - The transaction hash to validate
- * @throws ValidationError If validation fails, with details about which properties failed
+ * @throws KitError with INPUT_VALIDATION_FAILED code if validation fails, with details about which properties failed
  *
  * @example
  * ```typescript
@@ -8888,7 +9787,7 @@ function assertEvmPreparedChainRequestParams(params) {
  *
  * // Invalid transaction hash
  * assertEvmTransactionHash('invalid-hash')
- * // Throws ValidationError with descriptive message
+ * // Throws KitError with descriptive message
  * ```
  */
 function assertEvmTransactionHash(txHash) {
@@ -8912,7 +9811,7 @@ function assertEvmTransactionHash(txHash) {
  * @typeParam Types - The EIP-712 types definition for the standard being validated
  * @typeParam Message - The message structure for the standard being validated
  * @param typedData - The typed data to validate
- * @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
@@ -9711,7 +10610,7 @@ zod.z.object({
  * Validates EthersAdapterOptions configuration.
  *
  * @param options - The EthersAdapterOptions to validate. Must include a `getProvider` function and a `signer` object.
- * @throws \{ValidationError\} If validation fails.
+ * @throws KitError with INPUT_VALIDATION_FAILED code if validation fails.
  *
  * @example
  * ```typescript
@@ -9723,7 +10622,7 @@ zod.z.object({
  *   signer: Wallet.createRandom(),
  * }
  *
- * validateEthersAdapterOptions(options) // throws if invalid
+ * validateEthersAdapterOptions(options) // throws KitError if invalid
  * ```
  */
 function validateEthersAdapterOptions(options) {
@@ -9732,11 +10631,11 @@ function validateEthersAdapterOptions(options) {
 /**
  * Validates parameters for creating an Ethers adapter from an EIP-1193 provider.
  *
- * This function validates the parameters used by the createAdapterFromProvider
+ * This function validates the parameters used by the createEthersAdapterFromProvider
  * factory function for the Ethers adapter.
  *
  * @param params - The parameters to validate. Must include a `provider` object (EIP-1193 compatible) and optionally a `getProvider` function.
- * @throws \{ValidationError\} If validation fails.
+ * @throws KitError with INPUT_VALIDATION_FAILED code if validation fails.
  * @example
  * ```typescript
  * import { validateCreateAdapterFromProviderParams } from '@circle-fin/adapter-ethers-v6/validation'
@@ -9745,7 +10644,7 @@ function validateEthersAdapterOptions(options) {
  *   provider: window.ethereum,
  * }
  *
- * validateCreateAdapterFromProviderParams(params) // throws if invalid
+ * validateCreateAdapterFromProviderParams(params) // throws KitError if invalid
  * ```
  */
 function validateCreateAdapterFromProviderParams(params) {
@@ -9759,7 +10658,7 @@ function validateCreateAdapterFromProviderParams(params) {
  * checking the supportedChains property for EVM compatibility.
  *
  * @param capabilities - The adapter capabilities to validate
- * @throws ValidationError when capabilities validation fails
+ * @throws KitError with INPUT_VALIDATION_FAILED code when capabilities validation fails
  *
  * @example
  * ```typescript
@@ -9790,7 +10689,7 @@ function validateAdapterCapabilities(capabilities) {
  * Creates a new EthersAdapter instance with explicit capabilities and OperationContext support.
  *
  * This constructor is typically not called directly. Instead, use the factory functions
- * {@link createAdapterFromPrivateKey} or {@link createAdapterFromProvider} which provide
+ * {@link createEthersAdapterFromPrivateKey} or {@link createEthersAdapterFromProvider} which provide
  * smart defaults and better developer experience.
  *
  * @remarks
@@ -9802,8 +10701,8 @@ function validateAdapterCapabilities(capabilities) {
  * - `supportedChains`: Array of EVM chains this adapter can operate on
  *
  * **Factory Functions (Recommended):**
- * - {@link createAdapterFromPrivateKey} - For server-side/programmatic use with private keys
- * - {@link createAdapterFromProvider} - For browser wallets (MetaMask, WalletConnect, etc.)
+ * - {@link createEthersAdapterFromPrivateKey} - For server-side/programmatic use with private keys
+ * - {@link createEthersAdapterFromProvider} - For browser wallets (MetaMask, WalletConnect, etc.)
  *
  * @param options - Configuration options including provider getter and signer
  * @param capabilities - Adapter capabilities defining address control and supported chains
@@ -9827,10 +10726,10 @@ function validateAdapterCapabilities(capabilities) {
  * @example
  * ```typescript
  * // Recommended: Use factory functions instead
- * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
  *
  * // Minimal configuration with default capabilities
- * const adapter = createAdapterFromPrivateKey({
+ * const adapter = createEthersAdapterFromPrivateKey({
  *   privateKey: '0x...'
  *   // Defaults: user-controlled + all EVM chains
  * })
@@ -9890,8 +10789,31 @@ class EthersAdapter extends EvmAdapter {
         if (chain.type !== 'evm') {
             throw new Error(`EthersAdapter can only switch to EVM chains. Received: ${String(chain.type)} (${chain.name})`);
         }
-        // TypeScript now knows chain is EVMChainDefinition after the validation above
-        this._signer = await switchChain(this.getSigner(), chain);
+        // Check if we're already on the target chain
+        const currentSigner = this.getSigner();
+        const currentProvider = currentSigner?.provider;
+        if (currentProvider) {
+            try {
+                const network = await currentProvider.getNetwork();
+                // If already on the target chain, skip switching
+                if (network.chainId === BigInt(chain.chainId)) {
+                    return;
+                }
+            }
+            catch {
+                // If we can't get the current chain ID, proceed with switching
+                // This ensures we don't break existing functionality if getNetwork fails
+            }
+        }
+        const provider = await this.getProvider(chain);
+        // If the signer is a Wallet, reconnect it with the correct provider
+        if (currentSigner instanceof ethers.Wallet) {
+            this._signer = currentSigner.connect(provider);
+        }
+        else {
+            // For browser wallets, use the original switchChain logic
+            this._signer = await switchChain(currentSigner, chain);
+        }
     }
     /**
      * Gets the cached Provider or initializes it from options if not already cached.
@@ -9957,14 +10879,17 @@ class EthersAdapter extends EvmAdapter {
     /**
      * Simulates a contract function call using Ethers v6 `.staticCall`.
      */
-    async simulateFunctionCall(contract, functionName, args) {
+    async simulateFunctionCall(contract, functionName, args, chain) {
         try {
             const func = contract.getFunction(functionName);
             await func.staticCall(...args);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(`Simulation failed for ${functionName}: ${msg}`);
+            // Wrap simulation errors with structured error format
+            throw parseBlockchainError(err, {
+                chain: chain.name,
+                operation: 'simulation',
+            });
         }
     }
     /**
@@ -9991,7 +10916,11 @@ class EthersAdapter extends EvmAdapter {
                 errorMessage.toLocaleLowerCase().includes('execution reverted')) {
                 return fallback;
             }
-            throw new Error(`Gas estimation failed: ${errorMessage}`);
+            // Wrap gas estimation errors with structured error format
+            throw parseBlockchainError(error, {
+                chain: chain.name,
+                operation: 'estimateGas',
+            });
         }
         let gasPrice;
         try {
@@ -9999,7 +10928,11 @@ class EthersAdapter extends EvmAdapter {
             gasPrice = await this.fetchGasPrice(chain);
         }
         catch (error) {
-            throw new Error(`Gas price retrieval failed: ${error.message}`);
+            // Wrap gas price errors with structured error format
+            throw parseBlockchainError(error, {
+                chain: chain.name,
+                operation: 'getGasPrice',
+            });
         }
         return { gas, gasPrice, fee: (gas * gasPrice).toString() };
     }
@@ -10055,7 +10988,11 @@ class EthersAdapter extends EvmAdapter {
                 const shouldRetry = ethersNonceManager.shouldRetryNonceError(error, userProvidedNonce);
                 // Don't retry if: not a nonce error, user provided nonce, or this is the last attempt
                 if (!shouldRetry || attempt === maxAttempts) {
-                    throw error;
+                    // Wrap transaction execution errors with structured error format
+                    throw parseBlockchainError(error, {
+                        chain: chain.name,
+                        operation: 'sendTransaction',
+                    });
                 }
                 // Retry with resync on nonce-related errors (this will set a new nonce)
                 txRequest.nonce = await ethersNonceManager.resyncAndAllocate(provider, chain.chainId, fromAddress);
@@ -10094,10 +11031,10 @@ class EthersAdapter extends EvmAdapter {
      *
      * @example
      * ```typescript
-     * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+     * import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
      * import { parseAbi } from 'ethers'
      *
-     * const adapter = createAdapterFromPrivateKey({
+     * const adapter = createEthersAdapterFromPrivateKey({
      *   privateKey: process.env.PRIVATE_KEY
      * })
      *
@@ -10121,7 +11058,7 @@ class EthersAdapter extends EvmAdapter {
      * @example
      * ```typescript
      * // Multi-chain usage with same adapter instance
-     * const adapter = createAdapterFromPrivateKey({
+     * const adapter = createEthersAdapterFromPrivateKey({
      *   privateKey: process.env.PRIVATE_KEY
      * })
      *
@@ -10149,9 +11086,9 @@ class EthersAdapter extends EvmAdapter {
      * @example
      * ```typescript
      * // Address resolution patterns
-     * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+     * import { createEthersAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
      *
-     * const adapter = await createAdapterFromProvider({
+     * const adapter = await createEthersAdapterFromProvider({
      *   provider: window.ethereum
      *   // Defaults to user-controlled address context
      * })
@@ -10228,7 +11165,7 @@ class EthersAdapter extends EvmAdapter {
             },
             execute: async (overrides) => {
                 // Simulate the function call to catch errors before submission
-                await this.simulateFunctionCall(contract, functionName, args);
+                await this.simulateFunctionCall(contract, functionName, args, targetChain);
                 await this.ensureChain(targetChain);
                 // Reconnect the contract with the current signer, which is on the correct
                 // chain after `ensureChain`, to ensure the transaction is populated and
@@ -10257,7 +11194,7 @@ class EthersAdapter extends EvmAdapter {
      * adapter interface, it is effectively required and enforced at runtime. This ensures
      * the adapter is connected to the correct chain before querying the signer.
      *
-     * @param chain - The chain to use for address resolution (provided by OperationContext)
+     * @param chain - The chain to use for address resolution.
      * @returns A promise that resolves to the signer's address
      * @throws Error when no chain is provided
      *
@@ -10269,26 +11206,15 @@ class EthersAdapter extends EvmAdapter {
      * const address = await adapter.getAddress(Ethereum)
      * console.log('Wallet address:', address)
      * ```
-     *
-     * @example
-     * ```typescript
-     * // In practice, address resolution happens automatically
-     * const prepared = await adapter.prepare(params, {
-     *   chain: 'Ethereum'
-     *   // Address automatically resolved via getAddress() internally
-     * })
-     * ```
      */
     async getAddress(chain) {
         // Prevent calling getAddress on developer-controlled adapters
         if (this.capabilities?.addressContext === 'developer-controlled') {
-            throw new Error('Cannot call getAddress() on developer-controlled adapters. ' +
-                'Address must be provided explicitly in the operation context.');
+            throw new Error('Cannot call getAddress() on developer-controlled adapters. Address must be provided explicitly in the operation context.');
         }
         // Chain parameter should now be provided by resolveOperationContext
         if (!chain) {
-            throw new Error('Chain parameter is required for address resolution. ' +
-                'This should be provided by the OperationContext pattern.');
+            throw new Error('Chain parameter is required for address resolution. This should be provided by the OperationContext pattern.');
         }
         // Ensure we're on the correct chain before getting address
         await this.ensureChain(chain);
@@ -10376,9 +11302,9 @@ class EthersAdapter extends EvmAdapter {
      *
      * @example
      * ```typescript
-     * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+     * import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
      *
-     * const adapter = createAdapterFromPrivateKey({
+     * const adapter = createEthersAdapterFromPrivateKey({
      *   privateKey: process.env.PRIVATE_KEY
      * })
      *
@@ -10416,7 +11342,7 @@ class EthersAdapter extends EvmAdapter {
      * @example
      * ```typescript
      * // Multi-chain permit signing with same adapter
-     * const adapter = createAdapterFromPrivateKey({
+     * const adapter = createEthersAdapterFromPrivateKey({
      *   privateKey: process.env.PRIVATE_KEY
      * })
      *
@@ -10434,9 +11360,9 @@ class EthersAdapter extends EvmAdapter {
      * @example
      * ```typescript
      * // Browser wallet usage
-     * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+     * import { createEthersAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
      *
-     * const adapter = await createAdapterFromProvider({
+     * const adapter = await createEthersAdapterFromProvider({
      *   provider: window.ethereum
      * })
      *
@@ -10568,14 +11494,14 @@ class EthersAdapter extends EvmAdapter {
  *
  * @example
  * ```typescript
- * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
  *
  * // Both private key formats are supported (with or without '0x' prefix):
- * const adapter1 = createAdapterFromPrivateKey({
+ * const adapter1 = createEthersAdapterFromPrivateKey({
  *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // With prefix
  * })
  *
- * const adapter2 = createAdapterFromPrivateKey({
+ * const adapter2 = createEthersAdapterFromPrivateKey({
  *   privateKey: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // Without prefix (automatically normalized)
  * })
  *
@@ -10590,10 +11516,10 @@ class EthersAdapter extends EvmAdapter {
  *
  * @example
  * ```typescript
- * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
  *
  * // Multi-chain usage with same adapter instance
- * const adapter = createAdapterFromPrivateKey({
+ * const adapter = createEthersAdapterFromPrivateKey({
  *   privateKey: process.env.PRIVATE_KEY as `0x${string}`
  * })
  *
@@ -10606,11 +11532,11 @@ class EthersAdapter extends EvmAdapter {
  *
  * @example
  * ```typescript
- * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
  * import { Ethereum, Base, Polygon } from '@core/chains'
  *
  * // Custom capabilities configuration
- * const adapter = createAdapterFromPrivateKey({
+ * const adapter = createEthersAdapterFromPrivateKey({
  *   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
  *   capabilities: {
  *     supportedChains: [Ethereum, Base, Polygon]
@@ -10620,11 +11546,11 @@ class EthersAdapter extends EvmAdapter {
  *
  * @example
  * ```typescript
- * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
  * import { JsonRpcProvider } from 'ethers'
  *
  * // Custom provider configuration with explicit chain mapping
- * const adapter = createAdapterFromPrivateKey({
+ * const adapter = createEthersAdapterFromPrivateKey({
  *   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
  *   getProvider: ({ chain }) => {
  *     const rpcEndpoints: Record<string, string> = {
@@ -10638,7 +11564,7 @@ class EthersAdapter extends EvmAdapter {
  * })
  * ```
  */
-function createAdapterFromPrivateKey(params) {
+function createEthersAdapterFromPrivateKey(params) {
     // Parse and validate input parameters at runtime (normalizes the private key by adding '0x' prefix if missing)
     const { privateKey } = createAdapterFromPrivateKeyParamsSchema.parse(params);
     const { getProvider, capabilities } = params;
@@ -10664,6 +11590,94 @@ function createAdapterFromPrivateKey(params) {
         signer: wallet,
     }, resolvedCapabilities);
 }
+/**
+ * @deprecated Use {@link createEthersAdapterFromPrivateKey} instead.
+ *
+ * Creates an EthersAdapter instance from a private key with automatic type inference.
+ *
+ * This function creates an EthersAdapter for server-side or programmatic use
+ * by deriving a wallet from the provided private key. It uses lazy initialization
+ * where the wallet is created without a provider and is connected to chain-specific
+ * providers on-demand during operations. This matches the Viem adapter pattern and
+ * enables seamless multi-chain operations with a single adapter instance.
+ *
+ * @remarks
+ * The function performs the following operations:
+ * 1. Validates the input parameters at runtime
+ * 2. Creates a Wallet from the private key (without provider - lazy initialization)
+ * 3. Applies smart defaults for capabilities (user-controlled + all EVM chains)
+ * 4. Returns a configured EthersAdapter instance
+ *
+ * Chain context is provided through OperationContext during individual operations.
+ * The wallet will be connected to a provider when ensureChain() is called in prepare().
+ *
+ * **Default Configuration:**
+ * - `addressContext`: `'user-controlled'` (address derived from private key automatically)
+ * - `supportedChains`: All EVM-compatible chains (~29 networks)
+ * - Lazy initialization: Chain connection deferred until first operation
+ *
+ * **Security Warning:** Never use this function in client-side code or expose
+ * private keys in any way. This function is intended for server-side use only.
+ * Store private keys securely using environment variables or secret management systems.
+ *
+ * @typeParam TCapabilities - The adapter capabilities type for compile-time address validation
+ * @param params - Configuration parameters for creating the adapter
+ * @returns A configured EthersAdapter instance with automatically inferred capabilities
+ * @throws Error when validation fails or wallet derivation fails
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ *
+ * // Both private key formats are supported (with or without '0x' prefix):
+ * const adapter1 = createAdapterFromPrivateKey({
+ *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // With prefix
+ * })
+ *
+ * const adapter2 = createAdapterFromPrivateKey({
+ *   privateKey: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // Without prefix (automatically normalized)
+ * })
+ *
+ * // Chain specified per-operation via OperationContext
+ * const prepared = await adapter1.prepare({
+ *   address: '0x...',
+ *   abi: contractAbi,
+ *   functionName: 'transfer',
+ *   args: ['0xto', '1000']
+ * }, { chain: 'Ethereum' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ *
+ * // Multi-chain usage with same adapter instance
+ * const adapter = createAdapterFromPrivateKey({
+ *   privateKey: process.env.PRIVATE_KEY as `0x${string}`
+ * })
+ *
+ * // Transfer USDC on Ethereum
+ * await adapter.prepare(params, { chain: 'Ethereum' })
+ *
+ * // Transfer USDC on Base using the same adapter
+ * await adapter.prepare(params, { chain: 'Base' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { Ethereum, Base, Polygon } from '@core/chains'
+ *
+ * // Custom capabilities configuration
+ * const adapter = createAdapterFromPrivateKey({
+ *   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+ *   capabilities: {
+ *     supportedChains: [Ethereum, Base, Polygon]
+ *   }
+ * })
+ * ```
+ */
+const createAdapterFromPrivateKey = createEthersAdapterFromPrivateKey;
 
 /**
  * Creates an EthersAdapter instance from an EIP-1193 provider with smart default capabilities.
@@ -10707,10 +11721,10 @@ function createAdapterFromPrivateKey(params) {
  *
  * @example
  * ```typescript
- * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
  *
  * // Minimal browser wallet configuration
- * const adapter = await createAdapterFromProvider({
+ * const adapter = await createEthersAdapterFromProvider({
  *   provider: window.ethereum
  *   // Smart defaults applied:
  *   // - addressContext: 'user-controlled'
@@ -10728,11 +11742,11 @@ function createAdapterFromPrivateKey(params) {
  *
  * @example
  * ```typescript
- * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
  * import { Ethereum, Base, Polygon } from '@core/chains'
  *
  * // Advanced: custom capabilities for production use
- * const adapter = await createAdapterFromProvider({
+ * const adapter = await createEthersAdapterFromProvider({
  *   provider: window.ethereum,
  *   capabilities: {
  *     supportedChains: [Ethereum, Base, Polygon] // Restrict to specific chains
@@ -10743,11 +11757,11 @@ function createAdapterFromPrivateKey(params) {
  *
  * @example
  * ```typescript
- * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
  * import { JsonRpcProvider } from 'ethers'
  *
  * // Advanced usage with custom provider logic for production
- * const adapter = await createAdapterFromProvider({
+ * const adapter = await createEthersAdapterFromProvider({
  *   provider: window.ethereum,
  *   getProvider: ({ chain }) => new JsonRpcProvider(
  *     `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
@@ -10764,10 +11778,10 @@ function createAdapterFromPrivateKey(params) {
  * @example
  * ```typescript
  * // Cross-chain transfer using a single adapter
- * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
  * import { BridgeKit } from '@circle-fin/bridge-kit'
  *
- * const adapter = await createAdapterFromProvider({
+ * const adapter = await createEthersAdapterFromProvider({
  *   provider: window.ethereum
  * })
  *
@@ -10783,11 +11797,11 @@ function createAdapterFromPrivateKey(params) {
  *
  * @example
  * ```typescript
- * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { createEthersAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
  *
  * // Error handling example - wallet prompt occurs during factory creation
  * try {
- *   const adapter = await createAdapterFromProvider({
+ *   const adapter = await createEthersAdapterFromProvider({
  *     provider: window.ethereum
  *   })
  *
@@ -10804,7 +11818,7 @@ function createAdapterFromPrivateKey(params) {
  * }
  * ```
  */
-const createAdapterFromProvider = async (params) => {
+const createEthersAdapterFromProvider = async (params) => {
     // Validate input
     // Type assertion needed due to Partial<AdapterCapabilities> with exactOptionalPropertyTypes
     validateCreateAdapterFromProviderParams(params);
@@ -10833,6 +11847,105 @@ const createAdapterFromProvider = async (params) => {
         signer,
     }, resolvedCapabilities);
 };
+/**
+ * @deprecated Use {@link createEthersAdapterFromProvider} instead.
+ *
+ * Creates an EthersAdapter instance from an EIP-1193 provider with smart default capabilities.
+ *
+ * This function creates an EthersAdapter for browser or injected wallet use
+ * by connecting to the provided EIP-1193-compatible provider (such as MetaMask,
+ * WalletConnect, or any browser wallet). The adapter is automatically configured
+ * with user-controlled address context and support for all EVM-compatible chains.
+ *
+ * @remarks
+ * The function performs the following operations:
+ * 1. Validates the input parameters at runtime
+ * 2. Creates a BrowserProvider for the injected provider
+ * 3. Requests account access from the user (wallet prompt appears here)
+ * 4. Retrieves the signer from the connected wallet
+ * 5. Applies smart defaults for capabilities (user-controlled + all EVM chains)
+ * 6. Returns a configured EthersAdapter instance ready for immediate use
+ *
+ * The adapter will be ready to use immediately after creation with the
+ * specified provider and signer active. Chain context is provided through
+ * OperationContext during individual operations.
+ *
+ * **Smart Defaults:**
+ * - `addressContext`: `'user-controlled'` (addresses managed through wallet UI)
+ * - `supportedChains`: All EVM-compatible chains (~29 networks) for maximum flexibility
+ * - OperationContext support for per-operation chain specification
+ *
+ * **Account Access:**
+ * Note: Unlike Viem, Ethers requires eager signer initialization because:
+ * - Ethers Signer objects are chain-specific and must be recreated during chain switches
+ * - The switchChain utility requires an initialized Signer as input
+ * - This is an architectural difference between Ethers and Viem, not a limitation
+ * The user will be prompted for account access when this factory is called (before adapter is returned).
+ *
+ * **Security Note:** This function is intended for use with injected/browser wallets.
+ * Do not use in server-side code with private keys.
+ *
+ * @param params - Configuration parameters for creating the adapter
+ * @returns A configured EthersAdapter instance
+ * @throws Error when validation fails, user rejects connection, or provider initialization fails
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ *
+ * // Minimal browser wallet configuration
+ * const adapter = await createAdapterFromProvider({
+ *   provider: window.ethereum
+ *   // Smart defaults applied:
+ *   // - addressContext: 'user-controlled'
+ *   // - supportedChains: all EVM chains (~29 networks)
+ * })
+ *
+ * // Use with OperationContext pattern
+ * const prepared = await adapter.prepare({
+ *   address: '0x...',
+ *   abi: contractAbi,
+ *   functionName: 'transfer',
+ *   args: ['0xto', '1000']
+ * }, { chain: 'Ethereum' }) // Chain specified in context
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { Ethereum, Base, Polygon } from '@core/chains'
+ *
+ * // Advanced: custom capabilities for production use
+ * const adapter = await createAdapterFromProvider({
+ *   provider: window.ethereum,
+ *   capabilities: {
+ *     supportedChains: [Ethereum, Base, Polygon] // Restrict to specific chains
+ *     // addressContext still defaults to 'user-controlled'
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { JsonRpcProvider } from 'ethers'
+ *
+ * // Advanced usage with custom provider logic for production
+ * const adapter = await createAdapterFromProvider({
+ *   provider: window.ethereum,
+ *   getProvider: ({ chain }) => new JsonRpcProvider(
+ *     `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
+ *     { name: chain.name, chainId: chain.chainId }
+ *   )
+ * })
+ *
+ * // Address is automatically resolved from connected wallet
+ * const prepared = await adapter.prepare(params, {
+ *   chain: 'Polygon' // Address comes from wallet UI
+ * })
+ * ```
+ */
+const createAdapterFromProvider = createEthersAdapterFromProvider;
 
 exports.JsonRpcProvider = ethers.JsonRpcProvider;
 exports.EthersAdapter = EthersAdapter;
@@ -10840,6 +11953,8 @@ exports.buildEIP2612TypedData = buildEIP2612TypedData;
 exports.computeDefaultDeadline = computeDefaultDeadline;
 exports.createAdapterFromPrivateKey = createAdapterFromPrivateKey;
 exports.createAdapterFromProvider = createAdapterFromProvider;
+exports.createEthersAdapterFromPrivateKey = createEthersAdapterFromPrivateKey;
+exports.createEthersAdapterFromProvider = createEthersAdapterFromProvider;
 exports.parseSignature = parseSignature;
 exports.validateAdapterCapabilities = validateAdapterCapabilities;
 //# sourceMappingURL=index.cjs.map