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

package/index.cjs

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -85,6 +85,8 @@ const ERROR_TYPES = {
     RPC: 'RPC',
     /** Internet connectivity, DNS resolution, connection issues */
     NETWORK: 'NETWORK',
+    /** Catch-all for unrecognized errors (code 0) */
+    UNKNOWN: 'UNKNOWN',
 };
 /**
  * Array of valid error type values for validation.
@@ -98,6 +100,8 @@ const ERROR_TYPE_ARRAY = [...ERROR_TYPE_VALUES];
 /**
  * Error code ranges for validation.
  * Single source of truth for valid error code ranges.
+ *
+ * Note: Code 0 is special - it's the UNKNOWN catch-all error.
  */
 const ERROR_CODE_RANGES = [
     { min: 1000, max: 1999, type: 'INPUT' },
@@ -106,6 +110,8 @@ const ERROR_CODE_RANGES = [
     { min: 5000, max: 5999, type: 'ONCHAIN' },
     { min: 9000, max: 9999, type: 'BALANCE' },
 ];
+/** Special code for UNKNOWN errors */
+const UNKNOWN_ERROR_CODE = 0;
 /**
  * Zod schema for validating ErrorDetails objects.
  *
@@ -144,6 +150,7 @@ const ERROR_CODE_RANGES = [
 const errorDetailsSchema = zod.z.object({
     /**
      * Numeric identifier following standardized ranges:
+     * - 0: UNKNOWN - Catch-all for unrecognized errors
      * - 1000-1999: INPUT errors - Parameter validation
      * - 3000-3999: NETWORK errors - Connectivity issues
      * - 4000-4999: RPC errors - Provider issues, gas estimation
@@ -153,8 +160,9 @@ const errorDetailsSchema = zod.z.object({
     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)',
+        .refine((code) => code === UNKNOWN_ERROR_CODE ||
+        ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
+        message: 'Error code must be 0 (UNKNOWN) or 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
@@ -164,7 +172,7 @@ const errorDetailsSchema = zod.z.object({
     /** 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',
+            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK, UNKNOWN',
         }),
     }),
     /** Error handling strategy */
@@ -347,6 +355,7 @@ class KitError extends Error {
 /**
  * Standardized error code ranges for consistent categorization:
  *
+ * - 0: UNKNOWN - Catch-all for unrecognized errors
  * - 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
@@ -623,7 +632,7 @@ function createValidationErrorFromZod(zodError, context) {
  *
  * @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)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with insufficient token balance details
  *
  * @example
@@ -636,24 +645,28 @@ function createValidationErrorFromZod(zodError, context) {
  *
  * @example
  * ```typescript
- * // With raw error for debugging
+ * // With trace context for debugging
  * try {
  *   await transfer(...)
  * } catch (error) {
- *   throw createInsufficientTokenBalanceError('Base', 'USDC', error)
+ *   throw createInsufficientTokenBalanceError('Base', 'USDC', {
+ *     rawError: error,
+ *     balance: '1000000',
+ *     amount: '5000000',
+ *   })
  * }
  * ```
  */
-function createInsufficientTokenBalanceError(chain, token, rawError) {
+function createInsufficientTokenBalanceError(chain, token, trace) {
     return new KitError({
         ...BalanceError.INSUFFICIENT_TOKEN,
         recoverability: 'FATAL',
         message: `Insufficient ${token} balance on ${chain}`,
         cause: {
             trace: {
+                ...trace,
                 chain,
                 token,
-                rawError,
             },
         },
     });
@@ -666,7 +679,7 @@ function createInsufficientTokenBalanceError(chain, token, rawError) {
  * 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)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with insufficient gas details
  *
  * @example
@@ -676,16 +689,27 @@ function createInsufficientTokenBalanceError(chain, token, rawError) {
  * throw createInsufficientGasError('Ethereum')
  * // Message: "Insufficient gas funds on Ethereum"
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createInsufficientGasError('Ethereum', {
+ *   rawError: error,
+ *   gasRequired: '21000',
+ *   gasAvailable: '10000',
+ *   walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+ * })
+ * ```
  */
-function createInsufficientGasError(chain, rawError) {
+function createInsufficientGasError(chain, trace) {
     return new KitError({
         ...BalanceError.INSUFFICIENT_GAS,
         recoverability: 'FATAL',
         message: `Insufficient gas funds on ${chain}`,
         cause: {
             trace: {
+                ...trace,
                 chain,
-                rawError,
             },
         },
     });
@@ -700,7 +724,7 @@ function createInsufficientGasError(chain, rawError) {
  *
  * @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)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with simulation failure details
  *
  * @example
@@ -710,17 +734,27 @@ function createInsufficientGasError(chain, rawError) {
  * throw createSimulationFailedError('Ethereum', 'ERC20: insufficient allowance')
  * // Message: "Simulation failed on Ethereum: ERC20: insufficient allowance"
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createSimulationFailedError('Ethereum', 'ERC20: insufficient allowance', {
+ *   rawError: error,
+ *   txHash: '0x1234...',
+ *   gasLimit: '21000',
+ * })
+ * ```
  */
-function createSimulationFailedError(chain, reason, rawError) {
+function createSimulationFailedError(chain, reason, trace) {
     return new KitError({
         ...OnchainError.SIMULATION_FAILED,
         recoverability: 'FATAL',
         message: `Simulation failed on ${chain}: ${reason}`,
         cause: {
             trace: {
+                ...trace,
                 chain,
                 reason,
-                rawError,
             },
         },
     });
@@ -734,7 +768,7 @@ function createSimulationFailedError(chain, reason, rawError) {
  *
  * @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)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with transaction revert details
  *
  * @example
@@ -744,17 +778,27 @@ function createSimulationFailedError(chain, reason, rawError) {
  * throw createTransactionRevertedError('Base', 'Slippage exceeded')
  * // Message: "Transaction reverted on Base: Slippage exceeded"
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createTransactionRevertedError('Base', 'Slippage exceeded', {
+ *   rawError: error,
+ *   txHash: '0xabc...',
+ *   blockNumber: '12345',
+ * })
+ * ```
  */
-function createTransactionRevertedError(chain, reason, rawError) {
+function createTransactionRevertedError(chain, reason, trace) {
     return new KitError({
         ...OnchainError.TRANSACTION_REVERTED,
         recoverability: 'FATAL',
         message: `Transaction reverted on ${chain}: ${reason}`,
         cause: {
             trace: {
+                ...trace,
                 chain,
                 reason,
-                rawError,
             },
         },
     });
@@ -766,7 +810,7 @@ function createTransactionRevertedError(chain, reason, rawError) {
  * 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)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with out of gas details
  *
  * @example
@@ -776,16 +820,26 @@ function createTransactionRevertedError(chain, reason, rawError) {
  * throw createOutOfGasError('Polygon')
  * // Message: "Transaction ran out of gas on Polygon"
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createOutOfGasError('Polygon', {
+ *   rawError: error,
+ *   gasUsed: '50000',
+ *   gasLimit: '45000',
+ * })
+ * ```
  */
-function createOutOfGasError(chain, rawError) {
+function createOutOfGasError(chain, trace) {
     return new KitError({
         ...OnchainError.OUT_OF_GAS,
         recoverability: 'FATAL',
         message: `Transaction ran out of gas on ${chain}`,
         cause: {
             trace: {
+                ...trace,
                 chain,
-                rawError,
             },
         },
     });
@@ -798,7 +852,7 @@ function createOutOfGasError(chain, rawError) {
  * 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)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with RPC endpoint error details
  *
  * @example
@@ -808,16 +862,26 @@ function createOutOfGasError(chain, rawError) {
  * throw createRpcEndpointError('Ethereum')
  * // Message: "RPC endpoint error on Ethereum"
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createRpcEndpointError('Ethereum', {
+ *   rawError: error,
+ *   endpoint: 'https://mainnet.infura.io/v3/...',
+ *   statusCode: 429,
+ * })
+ * ```
  */
-function createRpcEndpointError(chain, rawError) {
+function createRpcEndpointError(chain, trace) {
     return new KitError({
         ...RpcError.ENDPOINT_ERROR,
         recoverability: 'RETRYABLE',
         message: `RPC endpoint error on ${chain}`,
         cause: {
             trace: {
+                ...trace,
                 chain,
-                rawError,
             },
         },
     });
@@ -831,7 +895,7 @@ function createRpcEndpointError(chain, rawError) {
  * often temporary.
  *
  * @param chain - The blockchain network where the connection failed
- * @param rawError - The original error from the underlying system (optional)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
  * @returns KitError with network connection error details
  *
  * @example
@@ -841,16 +905,26 @@ function createRpcEndpointError(chain, rawError) {
  * throw createNetworkConnectionError('Ethereum')
  * // Message: "Network connection failed for Ethereum"
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createNetworkConnectionError('Ethereum', {
+ *   rawError: error,
+ *   endpoint: 'https://eth-mainnet.g.alchemy.com/v2/...',
+ *   retryCount: 3,
+ * })
+ * ```
  */
-function createNetworkConnectionError(chain, rawError) {
+function createNetworkConnectionError(chain, trace) {
     return new KitError({
         ...NetworkError.CONNECTION_FAILED,
         recoverability: 'RETRYABLE',
         message: `Network connection failed for ${chain}`,
         cause: {
             trace: {
+                ...trace,
                 chain,
-                rawError,
             },
         },
     });
@@ -905,7 +979,9 @@ function parseBlockchainError(error, context) {
     // 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);
+        return createInsufficientTokenBalanceError(context.chain, token, {
+            rawError: error,
+        });
     }
     // Pattern 2: Simulation and execution reverts
     // Matches contract revert errors and simulation failures
@@ -915,46 +991,50 @@ function parseBlockchainError(error, context) {
         // "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);
+            return createSimulationFailedError(context.chain, reason, {
+                rawError: error,
+            });
         }
         // Transaction execution failures or reverts
-        return createTransactionRevertedError(context.chain, reason, error);
+        return createTransactionRevertedError(context.chain, reason, {
+            rawError: 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);
+        return createRpcEndpointError(context.chain, { rawError: 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);
+        return createOutOfGasError(context.chain, { rawError: error });
     }
     // Insufficient funds for gas
     if (/insufficient funds for gas/i.test(msg)) {
-        return createInsufficientGasError(context.chain, error);
+        return createInsufficientGasError(context.chain, { rawError: 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);
+        return createNetworkConnectionError(context.chain, { rawError: 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);
+        return createRpcEndpointError(context.chain, { rawError: error });
     }
     // Fallback based on operation context
     // Gas-related operations are RPC calls
     if (context.operation === 'estimateGas' ||
         context.operation === 'getGasPrice') {
-        return createRpcEndpointError(context.chain, error);
+        return createRpcEndpointError(context.chain, { rawError: 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);
+    return createSimulationFailedError(context.chain, msg.length > 0 ? msg : 'Unknown error', { rawError: error });
 }
 /**
  * Type guard to check if error has Solana-Kit structure with logs.
@@ -1097,6 +1177,8 @@ exports.Blockchain = void 0;
     Blockchain["Ink_Testnet"] = "Ink_Testnet";
     Blockchain["Linea"] = "Linea";
     Blockchain["Linea_Sepolia"] = "Linea_Sepolia";
+    Blockchain["Monad"] = "Monad";
+    Blockchain["Monad_Testnet"] = "Monad_Testnet";
     Blockchain["NEAR"] = "NEAR";
     Blockchain["NEAR_Testnet"] = "NEAR_Testnet";
     Blockchain["Noble"] = "Noble";
@@ -1188,6 +1270,7 @@ var BridgeChain;
     BridgeChain["HyperEVM"] = "HyperEVM";
     BridgeChain["Ink"] = "Ink";
     BridgeChain["Linea"] = "Linea";
+    BridgeChain["Monad"] = "Monad";
     BridgeChain["Optimism"] = "Optimism";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
@@ -1207,6 +1290,7 @@ var BridgeChain;
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
     BridgeChain["Ink_Testnet"] = "Ink_Testnet";
     BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
+    BridgeChain["Monad_Testnet"] = "Monad_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
@@ -1401,8 +1485,11 @@ const ArcTestnet = defineChain({
     name: 'Arc Testnet',
     title: 'ArcTestnet',
     nativeCurrency: {
-        name: 'Arc',
-        symbol: 'Arc',
+        name: 'USDC',
+        symbol: 'USDC',
+        // Arc uses native USDC with 18 decimals for gas payments (EVM standard).
+        // Note: The ERC-20 USDC contract at usdcAddress uses 6 decimals.
+        // See: https://docs.arc.network/arc/references/contract-addresses
         decimals: 18,
     },
     chainId: 5042002,
@@ -2190,6 +2277,86 @@ const LineaSepolia = defineChain({
     },
 });
 
+/**
+ * Monad Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const Monad = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Monad,
+    name: 'Monad',
+    title: 'Monad Mainnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 143,
+    isTestnet: false,
+    explorerUrl: 'https://monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Monad Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const MonadTestnet = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Monad_Testnet,
+    name: 'Monad Testnet',
+    title: 'Monad Testnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 10143,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://testnet-rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * NEAR Protocol Mainnet chain definition
  * @remarks
@@ -3274,6 +3441,8 @@ var Blockchains = {
     InkTestnet: InkTestnet,
     Linea: Linea,
     LineaSepolia: LineaSepolia,
+    Monad: Monad,
+    MonadTestnet: MonadTestnet,
     NEAR: NEAR,
     NEARTestnet: NEARTestnet,
     Noble: Noble,
@@ -8506,6 +8675,60 @@ const customBurn = async (params, adapter, context) => {
     }, context);
 };
 
+/**
+ * Prepares an EVM-compatible native token balance read (ETH, MATIC, etc.).
+ *
+ * This function creates a prepared chain request for reading the native token balance
+ * of a given wallet address on an EVM-based chain. If no wallet address is provided,
+ * the adapter's default address from context is used.
+ *
+ * @param params - The action payload for the native balance lookup:
+ *   - `walletAddress` (optional): The wallet address to check. Defaults to context address.
+ * @param adapter - The EVM adapter providing chain context.
+ * @param context - The resolved operation context providing chain and address information.
+ * @returns A promise resolving to a prepared chain request.
+ *   The `execute` method returns the balance as a string (in wei).
+ * @throws {KitError} If the current chain is not EVM-compatible (INPUT_INVALID_CHAIN).
+ * @throws Error If address validation fails.
+ *
+ * @example
+ * ```typescript
+ * import { Ethereum } from '@core/chains'
+ *
+ * const prepared = await balanceOf(
+ *   { walletAddress: '0x1234...' },
+ *   adapter,
+ *   context
+ * )
+ * const balance = await prepared.execute()
+ * console.log(balance) // e.g., "1000000000000000000" (1 ETH in wei)
+ *
+ * // Check balance for the adapter's address (no walletAddress provided)
+ * const prepared2 = await balanceOf({}, adapter, context)
+ * const balance2 = await prepared2.execute()
+ * ```
+ */
+const balanceOf$2 = async (params, adapter, context) => {
+    const chain = context.chain;
+    if (chain.type !== 'evm') {
+        throw createInvalidChainError(chain.name, `Expected EVM chain definition, but received chain type: ${chain.type}`);
+    }
+    // Use provided wallet address or fall back to context address
+    const walletAddress = params.walletAddress ?? context.address;
+    // Validate the address
+    assertEvmAddress(walletAddress);
+    // Create noop request for gas estimation (reading balance is free)
+    const noopRequest = await createNoopChainRequest();
+    return {
+        type: 'evm',
+        estimate: noopRequest.estimate,
+        execute: async () => {
+            const balance = await adapter.readNativeBalance(walletAddress, chain);
+            return balance.toString();
+        },
+    };
+};
+
 /**
  * Prepares an EVM-compatible `balanceOf` read for any ERC-20 token.
  *
@@ -8832,6 +9055,14 @@ const getHandlers = (adapter) => {
         'cctp.v2.customBurn': async (params, context) => {
             return customBurn(params, adapter, context);
         },
+        /**
+         * Handler for native token balance operations on EVM chains.
+         *
+         * Gets the native balance (ETH, MATIC, etc.) for the given address.
+         */
+        'native.balanceOf': async (params, context) => {
+            return balanceOf$2(params, adapter, context);
+        },
     };
 };
 
@@ -10845,18 +11076,13 @@ class EthersAdapter extends EvmAdapter {
         return this._signer;
     }
     /**
-     * Creates a contract instance for the given address, ABI, and wallet.
+     * Parses and validates an ABI, ensuring the specified function exists.
+     *
+     * @param abi - The ABI to parse (can be a string array or object array).
+     * @param functionName - The function name to validate exists in the ABI.
+     * @throws Error when ABI parsing fails or function is not found.
      */
-    createContractInstance(params, signer, walletAddress, provider) {
-        const { address, abi: abiInput, functionName } = params;
-        // Wallet address is passed as parameter to avoid race conditions in concurrent requests
-        if (!walletAddress) {
-            throw new Error('Unable to retrieve account from signer. Please ensure a valid wallet is connected.');
-        }
-        assertEvmPreparedChainRequestParams(params);
-        const abi = Array.isArray(abiInput) && typeof abiInput[0] === 'string'
-            ? abiInput
-            : abiInput;
+    _parseAndValidateAbi(abi, functionName) {
         let contractInterface = undefined;
         try {
             contractInterface = new ethers.Interface(abi);
@@ -10871,6 +11097,21 @@ class EthersAdapter extends EvmAdapter {
         if (!functionNames.includes(functionName)) {
             throw new Error(`Function '${functionName}' not found in ABI.`);
         }
+    }
+    /**
+     * Creates a contract instance for the given address, ABI, and wallet.
+     */
+    createContractInstance(params, signer, walletAddress, provider) {
+        const { address, abi: abiInput, functionName } = params;
+        // Wallet address is passed as parameter to avoid race conditions in concurrent requests
+        if (!walletAddress) {
+            throw new Error('Unable to retrieve account from signer. Please ensure a valid wallet is connected.');
+        }
+        assertEvmPreparedChainRequestParams(params);
+        const abi = Array.isArray(abiInput) && typeof abiInput[0] === 'string'
+            ? abiInput
+            : abiInput;
+        this._parseAndValidateAbi(abi, functionName);
         const contract = provider
             ? new ethers.Contract(address, abi, provider).connect(signer)
             : new ethers.Contract(address, abi, signer);
@@ -11131,27 +11372,24 @@ class EthersAdapter extends EvmAdapter {
         if (targetChain.type !== 'evm') {
             throw new Error(`Invalid chain type '${String(targetChain.type)}' for EthersAdapter. Expected 'evm' chain type.`);
         }
-        // Ensure we're on the correct chain BEFORE resolving context
-        // This is critical because resolveOperationContext may call getAddress(),
-        // which queries the wallet. For browser wallets, we must be on the correct
-        // chain before querying wallet state (especially for smart contract wallets).
-        await this.ensureChain(targetChain);
-        // Now resolve the full operation context (address resolution happens on correct chain)
-        const resolvedContext = await resolveOperationContext(this, ctx);
-        if (!resolvedContext) {
-            throw new Error('OperationContext resolution failed. Ensure the adapter has capabilities configured.');
-        }
-        const signer = this.getSigner();
-        const provider = await this.getProvider(targetChain);
         // Check if the function is read-only (view or pure)
+        // Read-only functions don't need chain switching
         // If function is not found in ABI or ABI is invalid, default to false
         const isReadOnly = Array.isArray(abi)
             ? isReadOnlyFunction(abi, functionName, false)
             : false;
+        const provider = await this.getProvider(targetChain);
         if (isReadOnly) {
-            return this.handleReadOnlyFunction(params, signer, provider, resolvedContext.address);
+            return this.handleReadOnlyFunction(params, provider);
+        }
+        // For state-changing functions, ensure we're on the correct chain
+        await this.ensureChain(targetChain);
+        // Resolve the full operation context (address resolution happens here)
+        const resolvedContext = await resolveOperationContext(this, ctx);
+        if (!resolvedContext) {
+            throw new Error('OperationContext resolution failed. Ensure the adapter has capabilities configured.');
         }
-        // For state-changing functions, use the original logic
+        const signer = this.getSigner();
         const contract = this.createContractInstance(params, signer, resolvedContext.address, provider);
         return {
             type: 'evm',
@@ -11216,8 +11454,6 @@ class EthersAdapter extends EvmAdapter {
         if (!chain) {
             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);
         const signer = this.getSigner();
         const address = await signer.getAddress();
         return address;
@@ -11269,6 +11505,44 @@ class EthersAdapter extends EvmAdapter {
         }
         return feeData.gasPrice;
     }
+    /**
+     * Reads the native token balance (ETH, MATIC, etc.) for a given address.
+     *
+     * @param address - The wallet address to check the balance for.
+     * @param chain - The chain definition to fetch the balance from.
+     * @returns Promise resolving to the balance in wei as a bigint.
+     * @throws Error when balance retrieval fails.
+     *
+     * @example
+     * ```typescript
+     * const balance = await adapter.readNativeBalance(
+     *   '0x1234...',
+     *   Ethereum
+     * )
+     * console.log('Balance:', balance.toString(), 'wei')
+     * ```
+     */
+    async readNativeBalance(address, chain) {
+        const provider = await this.getProvider(chain);
+        try {
+            return await provider.getBalance(address);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new KitError({
+                ...RpcError.ENDPOINT_ERROR,
+                recoverability: 'RETRYABLE',
+                message: `Failed to get native balance for ${address}: ${errorMessage}`,
+                cause: {
+                    trace: {
+                        operation: 'readNativeBalance',
+                        address,
+                        chain: chain.name,
+                    },
+                },
+            });
+        }
+    }
     /**
      * Signs EIP-712 typed data using the configured signer with OperationContext.
      *
@@ -11383,8 +11657,6 @@ class EthersAdapter extends EvmAdapter {
         if (targetChain.type !== 'evm') {
             throw new Error(`Invalid chain type '${String(targetChain.type)}' for EthersAdapter. Expected 'evm' chain type.`);
         }
-        // Ensure adapter is connected to correct chain
-        await this.ensureChain(targetChain);
         const signer = this.getSigner();
         if (!signer) {
             throw new Error('No signer is configured. Please provide a signer to sign typed data.');
@@ -11405,13 +11677,11 @@ class EthersAdapter extends EvmAdapter {
      * Handle read-only function execution with noop estimation.
      *
      * @param params - The EVM prepared chain request parameters.
-     * @param signer - The Ethers signer instance.
-     * @param provider - The Ethers provider instance.
-     * @param walletAddress - The wallet address (prevents race conditions in concurrent requests).
+     * @param provider - The Ethers provider instance configured for the target chain.
      * @returns A prepared chain request for read-only function execution.
      */
-    async handleReadOnlyFunction(params, signer, provider, walletAddress) {
-        const { functionName, args } = params;
+    async handleReadOnlyFunction(params, provider) {
+        const { address, abi: abiInput, functionName, args } = params;
         // For read-only functions, use contract call and noop estimation
         const noopRequest = await createNoopChainRequest();
         return {
@@ -11419,8 +11689,12 @@ class EthersAdapter extends EvmAdapter {
             estimate: noopRequest.estimate,
             execute: async () => {
                 try {
-                    // Create contract instance for read-only function
-                    const contract = this.createContractInstance(params, signer, walletAddress, provider);
+                    // For read-only functions, create contract with provider only (no signer needed)
+                    // This ensures we query the correct target chain, not the wallet's current chain
+                    const abi = Array.isArray(abiInput) && typeof abiInput[0] === 'string'
+                        ? abiInput
+                        : abiInput;
+                    const contract = new ethers.Contract(address, abi, provider);
                     const contractFunction = contract.getFunction(functionName);
                     const result = await contractFunction.staticCall(...args);
                     // For read-only functions, return the result as a string
@@ -11764,7 +12038,7 @@ const createAdapterFromPrivateKey = createEthersAdapterFromPrivateKey;
  * const adapter = await createEthersAdapterFromProvider({
  *   provider: window.ethereum,
  *   getProvider: ({ chain }) => new JsonRpcProvider(
- *     `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
+ *     `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
  *     { name: chain.name, chainId: chain.chainId }
  *   )
  * })
@@ -11934,7 +12208,7 @@ const createEthersAdapterFromProvider = async (params) => {
  * const adapter = await createAdapterFromProvider({
  *   provider: window.ethereum,
  *   getProvider: ({ chain }) => new JsonRpcProvider(
- *     `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
+ *     `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
  *     { name: chain.name, chainId: chain.chainId }
  *   )
  * })