@circle-fin/adapter-ethers-v6 1.0.1 → 1.1.1

package/index.mjs

@@ -19,10 +19,10 @@
 import { JsonRpcProvider, Wallet, BrowserProvider, Interface, Contract } from 'ethers';
 export { JsonRpcProvider } from 'ethers';
 import { z } from 'zod';
+import '@ethersproject/units';
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
 import { getAddress } from '@ethersproject/address';
 import bs58 from 'bs58';
-import '@ethersproject/units';
 
 /**
  * Type-safe registry for managing and executing blockchain action handlers.
@@ -2846,9 +2846,71 @@ const RECOVERABILITY_VALUES = [
     '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
+ * 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'
+ * })
+ * ```
+ */
+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 a mutable array for Zod enum validation
+// 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.
  *
@@ -2861,7 +2923,8 @@ const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
  *
  * const result = errorDetailsSchema.safeParse({
  *   code: 1001,
- *   name: 'NETWORK_MISMATCH',
+ *   name: 'INPUT_NETWORK_MISMATCH',
+ *   type: 'INPUT',
  *   recoverability: 'FATAL',
  *   message: 'Source and destination networks must be different'
  * })
@@ -2870,30 +2933,56 @@ const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
  *   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 = z.object({
-    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    /**
+     * Numeric identifier following standardized ranges:
+     * - 1000-1999: INPUT errors - Parameter validation
+     * - 3000-3999: NETWORK errors - Connectivity issues
+     * - 4000-4999: RPC errors - Provider issues, gas estimation
+     * - 5000-5999: ONCHAIN errors - Transaction/simulation failures
+     * - 9000-9999: BALANCE errors - Insufficient funds
+     */
     code: 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") */
+        .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: 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: z.enum(ERROR_TYPE_ARRAY, {
+        errorMap: () => ({
+            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK',
+        }),
+    }),
     /** Error handling strategy */
     recoverability: z.enum(RECOVERABILITY_ARRAY, {
         errorMap: () => ({
             message: 'Recoverability must be one of: RETRYABLE, RESUMABLE, FATAL',
         }),
     }),
-    /** User-friendly explanation with network context */
+    /** User-friendly explanation with context */
     message: z
         .string()
         .min(1, 'Error message must be a non-empty string')
-        .max(500, 'Error message must be 500 characters or less'),
+        .max(1000, 'Error message must be 1000 characters or less'),
     /** Raw error details, context, or the original error that caused this one. */
     cause: z
         .object({
@@ -2908,7 +2997,7 @@ const errorDetailsSchema = z.object({
  *
  * @param details - The object to validate
  * @returns The validated ErrorDetails object
- * @throws {TypeError} When validation fails
+ * @throws TypeError When validation fails
  *
  * @example
  * ```typescript
@@ -2985,6 +3074,8 @@ class KitError extends Error {
     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. */
@@ -3013,6 +3104,12 @@ class KitError extends Error {
                 enumerable: true,
                 configurable: false,
             },
+            type: {
+                value: validatedDetails.type,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
             recoverability: {
                 value: validatedDetails.recoverability,
                 writable: false,
@@ -3032,14 +3129,19 @@ class KitError extends Error {
 }
 
 /**
- * Minimum error code for INPUT type errors.
- * INPUT errors represent validation failures and invalid parameters.
+ * 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 with its corresponding
- * string name to ensure consistency when creating error instances.
+ * 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
@@ -3056,48 +3158,609 @@ class KitError extends Error {
  *   message: 'Source and destination networks must be different'
  * })
  *
- * // Access code and name individually if needed
+ * // 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 = {
-    /** Unsupported or invalid bridge route configuration */
-    UNSUPPORTED_ROUTE: {
-        code: 1003,
-        name: 'INPUT_UNSUPPORTED_ROUTE',
+    /** Invalid or unsupported chain identifier */
+    INVALID_CHAIN: {
+        code: 1005,
+        name: 'INPUT_INVALID_CHAIN',
+        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 unsupported bridge route.
+ * Creates error for invalid chain configuration.
  *
- * This error is thrown when attempting to bridge between chains that don't
- * have a supported bridge route configured.
+ * This error is thrown when the provided chain doesn't meet the required
+ * configuration or is not supported for the operation.
  *
- * @param source - Source chain name
- * @param destination - Destination chain name
- * @returns KitError with specific route details
+ * @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 { createUnsupportedRouteError } from '@core/errors'
+ * import { createInvalidChainError } from '@core/errors'
  *
- * throw createUnsupportedRouteError('Ethereum', 'Solana')
- * // Message: "Route from Ethereum to Solana is not supported"
+ * throw createInvalidChainError('UnknownChain', 'Chain is not supported by this bridge')
+ * // Message: "Invalid chain 'UnknownChain': Chain is not supported by this bridge"
  * ```
  */
-function createUnsupportedRouteError(source, destination) {
+function createInvalidChainError(chain, reason) {
     const errorDetails = {
-        ...InputError.UNSUPPORTED_ROUTE,
+        ...InputError.INVALID_CHAIN,
         recoverability: 'FATAL',
-        message: `Route from ${source} to ${destination} is not supported.`,
+        message: `Invalid chain '${chain}': ${reason}`,
         cause: {
-            trace: { source, destination },
+            trace: { chain, reason },
         },
     };
     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);
+    }
+    // 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);
+        }
+        // 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;
+        }
+    }
+    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;
+}
+
 /**
  * Abstract class defining the standard interface for an adapter that interacts with a specific blockchain.
  *
@@ -3243,20 +3906,24 @@ 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);
         }
     }
 }
@@ -9952,14 +10619,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',
+            });
         }
     }
     /**
@@ -9972,7 +10642,7 @@ class EthersAdapter extends EvmAdapter {
      * @param overrides - Optional estimate overrides.
      * @returns Promise resolving to the estimated gas, gas price, and total fee.
      */
-    async estimateGasForFunction(contract, functionName, args, chain, overrides) {
+    async estimateGasForFunction(contract, functionName, args, chain, overrides, fallback) {
         let gas;
         try {
             const contractFunction = contract.getFunction(functionName);
@@ -9981,7 +10651,16 @@ class EthersAdapter extends EvmAdapter {
                 : await contractFunction.estimateGas(...args);
         }
         catch (error) {
-            throw new Error(`Gas estimation failed: ${error.message}`);
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            if (fallback &&
+                errorMessage.toLocaleLowerCase().includes('execution reverted')) {
+                return fallback;
+            }
+            // Wrap gas estimation errors with structured error format
+            throw parseBlockchainError(error, {
+                chain: chain.name,
+                operation: 'estimateGas',
+            });
         }
         let gasPrice;
         try {
@@ -9989,7 +10668,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() };
     }
@@ -10045,7 +10728,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);
@@ -10206,18 +10893,19 @@ class EthersAdapter extends EvmAdapter {
         }
         // For state-changing functions, use the original logic
         const contract = this.createContractInstance(params, signer, resolvedContext.address, provider);
-        await this.simulateFunctionCall(contract, functionName, args);
         return {
             type: 'evm',
-            estimate: async (overrides) => {
+            estimate: async (overrides, fallback) => {
                 await this.ensureChain(targetChain);
                 // Reconnect the contract with the correct provider for the target chain to ensure
                 // gas estimation and fee data retrieval use the correct network.
                 const estimationProvider = await this.getProvider(targetChain);
                 const contractForEstimation = contract.connect(estimationProvider);
-                return this.estimateGasForFunction(contractForEstimation, functionName, args, targetChain, overrides);
+                return this.estimateGasForFunction(contractForEstimation, functionName, args, targetChain, overrides, fallback);
             },
             execute: async (overrides) => {
+                // Simulate the function call to catch errors before submission
+                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
@@ -10246,7 +10934,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
      *
@@ -10258,26 +10946,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);