@circle-fin/usdckit 0.24.2 → 0.25.1

package/dist/cjs/metadata.js

@@ -14,4 +14,4 @@ exports.VERSION = void 0;
 /**
  * The current semantic version of the SDK
  */
-exports.VERSION = `${'0.24.2' || '0.0.0'}`;
+exports.VERSION = `${'0.25.1' || '0.0.0'}`;

package/dist/cjs/providers/circle-wallets/index.d.ts

@@ -10418,6 +10418,194 @@ export declare const SUPPORTED_CONTRACT_QUERY_CHAINS: readonly [{
     readonly blockchainId: "ARB-SEPOLIA";
     readonly blockchainVm: "EVM";
     readonly formatters?: undefined | undefined;
+}, {
+    blockExplorers: {
+        readonly default: {
+            readonly name: "ArcScan";
+            readonly url: "https://testnet.arcscan.app";
+            readonly apiUrl: "https://testnet.arcscan.app/api";
+        };
+    };
+    blockTime?: number | undefined | undefined;
+    contracts: {
+        readonly USDC: {
+            readonly address: "0x3600000000000000000000000000000000000000";
+            readonly abi: readonly [{
+                readonly type: "event";
+                readonly name: "Approval";
+                readonly inputs: readonly [{
+                    readonly indexed: true;
+                    readonly name: "owner";
+                    readonly type: "address";
+                }, {
+                    readonly indexed: true;
+                    readonly name: "spender";
+                    readonly type: "address";
+                }, {
+                    readonly indexed: false;
+                    readonly name: "value";
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "event";
+                readonly name: "Transfer";
+                readonly inputs: readonly [{
+                    readonly indexed: true;
+                    readonly name: "from";
+                    readonly type: "address";
+                }, {
+                    readonly indexed: true;
+                    readonly name: "to";
+                    readonly type: "address";
+                }, {
+                    readonly indexed: false;
+                    readonly name: "value";
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "allowance";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [{
+                    readonly name: "owner";
+                    readonly type: "address";
+                }, {
+                    readonly name: "spender";
+                    readonly type: "address";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "approve";
+                readonly stateMutability: "nonpayable";
+                readonly inputs: readonly [{
+                    readonly name: "spender";
+                    readonly type: "address";
+                }, {
+                    readonly name: "amount";
+                    readonly type: "uint256";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "bool";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "balanceOf";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [{
+                    readonly name: "account";
+                    readonly type: "address";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "decimals";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [];
+                readonly outputs: readonly [{
+                    readonly type: "uint8";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "name";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [];
+                readonly outputs: readonly [{
+                    readonly type: "string";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "symbol";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [];
+                readonly outputs: readonly [{
+                    readonly type: "string";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "totalSupply";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [];
+                readonly outputs: readonly [{
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "transfer";
+                readonly stateMutability: "nonpayable";
+                readonly inputs: readonly [{
+                    readonly name: "recipient";
+                    readonly type: "address";
+                }, {
+                    readonly name: "amount";
+                    readonly type: "uint256";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "bool";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "transferFrom";
+                readonly stateMutability: "nonpayable";
+                readonly inputs: readonly [{
+                    readonly name: "sender";
+                    readonly type: "address";
+                }, {
+                    readonly name: "recipient";
+                    readonly type: "address";
+                }, {
+                    readonly name: "amount";
+                    readonly type: "uint256";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "bool";
+                }];
+            }];
+            readonly read: {
+                readonly decimals: () => 6;
+            };
+        };
+        readonly multicall3: {
+            readonly address: "0xcA11bde05977b3631167028862bE2a173976CA11";
+            readonly blockCreated: 0;
+        };
+    };
+    ensTlds?: readonly string[] | undefined;
+    id: 5042002;
+    name: "Arc Testnet";
+    nativeCurrency: {
+        readonly name: "USDC";
+        readonly symbol: "USDC";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://rpc.testnet.arc.network", "https://rpc.quicknode.testnet.arc.network", "https://rpc.blockdaemon.testnet.arc.network"];
+            readonly webSocket: readonly ["wss://rpc.testnet.arc.network", "wss://rpc.quicknode.testnet.arc.network"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    testnet: true;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable<bigint, number>> | undefined;
+    verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+    readonly blockchainId: "ARC-TESTNET";
+    readonly blockchainVm: "EVM";
+    readonly formatters?: undefined | undefined;
 }, {
     blockExplorers: {
         readonly default: {

package/dist/cjs/providers/circle-wallets/index.js

@@ -73,6 +73,7 @@ exports.SUPPORTED_CONTRACT_QUERY_CHAINS = [
     index_js_1.MATIC_AMOY,
     index_js_1.ARB,
     index_js_1.ARB_SEPOLIA,
+    index_js_1.ARC_TESTNET,
     index_js_1.UNI,
     index_js_1.UNI_SEPOLIA,
     index_js_1.BASE,

package/dist/cjs/providers/circle-wallets/transports/index.js

@@ -120,17 +120,47 @@ class Provider extends index_js_2.Provider {
     }
     async eth_call(params, blockIdentifier = 'latest') {
         // NOTE: https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call
-        // In JSON-RPC `eth_call` spec, blockIdentifier is a required parameter.
-        // It is a hex string of the block number, 'latest', 'earliest', 'pending', 'safe' or 'finalized'.
-        // Although Circle's query contract API does not support it, we still add it to be compatible with the JSON-RPC spec.
+        // Circle's query contract API has a narrow surface (blockchain, to, data, from). For anything
+        // it cannot represent, throw `MethodNotFoundRpcError` so `Provider.request` falls back to the
+        // embedded viem RPC transport instead of hard-failing the caller. This matters in particular
+        // for viem-based adapters (e.g. the Circle Wallets adapter's pre-flight `publicClient.call`
+        // during a swap), which forward `gas`/`value` into `eth_call` as a matter of course.
         if (blockIdentifier !== 'latest') {
-            throw new index_js_1.ErrorWithCause('Only `latest` block identifier is supported');
+            throw new viem_1.MethodNotFoundRpcError(new index_js_1.ErrorWithCause('Only `latest` block identifier is supported by Circle queryContract'), {
+                method: 'eth_call',
+            });
+        }
+        // gas / gasPrice / maxFeePerGas / maxPriorityFeePerGas are EVM-visible during the target
+        // call: `gas` bounds `gasleft()` and affects out-of-gas behavior; the fee fields determine
+        // `tx.gasprice`, which contracts can read. Circle's queryContract cannot thread these
+        // through, so surface `MethodNotFoundRpcError` to trigger fallback rather than silently
+        // returning an SCP result that ignored the caller's explicit simulation constraints.
+        const gasPricingParams = ['gas', 'gasPrice', 'maxFeePerGas', 'maxPriorityFeePerGas'];
+        if (gasPricingParams.some((param) => params[param] !== undefined)) {
+            throw new viem_1.MethodNotFoundRpcError(new index_js_1.ErrorWithCause('gas / gasPrice / maxFeePerGas / maxPriorityFeePerGas are not supported by Circle queryContract'), { method: 'eth_call' });
+        }
+        // `nonce` is transaction-level and not EVM-visible inside eth_call, so silently drop it —
+        // forwarding would be a no-op and throwing would break callers that forward nonce for parity.
+        // `value` is the one remaining param with read semantics (payable view calls). `0x0` / `0n`
+        // mean "no native value" and are accepted; anything else cannot be expressed through
+        // queryContract, so fall back to the RPC transport. Accept both the typed `bigint` and the
+        // runtime JSON-RPC `Hex` shape (viem's `TransactionRequest.value` is typed `bigint`, but
+        // transports deliver hex).
+        const rawValue = params.value;
+        let valueAsBigInt;
+        if (rawValue === undefined) {
+            valueAsBigInt = 0n;
         }
-        // Since Circle's query contract API does not support some transaction params,
-        // to prevent misuse, we throw an error if they are provided.
-        const unsupportedTransactionParams = ['gas', 'gasPrice', 'maxFeePerGas', 'maxPriorityFeePerGas', 'nonce', 'value'];
-        if (unsupportedTransactionParams.some((param) => params[param] !== undefined)) {
-            throw new index_js_1.ErrorWithCause(`Unsupported transaction params: ${unsupportedTransactionParams.join(', ')}`);
+        else if (typeof rawValue === 'bigint') {
+            valueAsBigInt = rawValue;
+        }
+        else {
+            valueAsBigInt = (0, viem_1.hexToBigInt)(rawValue);
+        }
+        if (valueAsBigInt !== 0n) {
+            throw new viem_1.MethodNotFoundRpcError(new index_js_1.ErrorWithCause('Non-zero `value` is not supported by Circle queryContract'), {
+                method: 'eth_call',
+            });
         }
         // Provider's chainId is used to determine the blockchain
         // When the chain is not supported by Circle's query contract API, throw MethodNotFoundRpcError to fallback.

package/dist/cjs/providers/circle-wallets/transports/index.test.js

@@ -1886,12 +1886,21 @@ vitest_1.vi.mock('@circle-fin/developer-controlled-wallets', () => ({
         });
     });
     (0, vitest_1.describe)('eth_call', () => {
+        // Build a provider with `fallbackTransport: null` so the inner `eth_call` errors
+        // surface raw instead of being silently retried on the fallback RPC transport.
+        // The production default IS to fall back; these tests pin the inner contract.
+        const makeProviderWithoutFallback = (chainId) => new index_js_4.Provider({
+            apiKey: 'test-api-key',
+            entitySecret: 'test-entity-secret',
+            chainId,
+            fallbackTransport: null,
+        });
+        const baseParams = {
+            to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
+            data: '0x70a08231000000000000000000000000742d35cc6634c0532925a3b8d0c8c0c8d8d8d8d8',
+            from: '0x123456789abcdef123456789abcdef123456789a',
+        };
         (0, vitest_1.it)('should perform contract query successfully', async () => {
-            const params = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231000000000000000000000000742d35cc6634c0532925a3b8d0c8c0c8d8d8d8d8',
-                from: '0x123456789abcdef123456789abcdef123456789a',
-            };
             mockScp.queryContract.mockResolvedValue({
                 data: {
                     outputData: '0x0000000000000000000000000000000000000000000000000de0b6b3a7640000',
@@ -1899,36 +1908,18 @@ vitest_1.vi.mock('@circle-fin/developer-controlled-wallets', () => ({
             });
             const result = await provider.request({
                 method: 'eth_call',
-                params: [params],
+                params: [baseParams],
             });
             (0, vitest_1.expect)(result).toBe('0x0000000000000000000000000000000000000000000000000de0b6b3a7640000');
             (0, vitest_1.expect)(mockScp.queryContract).toHaveBeenCalledWith({
                 blockchain: 'ETH',
-                address: params.to,
-                callData: params.data,
-                fromAddress: params.from,
+                address: baseParams.to,
+                callData: baseParams.data,
+                fromAddress: baseParams.from,
             });
         });
-        (0, vitest_1.it)('should throw UnsupportedChainError when chainId is not supported for contract queries', async () => {
-            const provider = new index_js_4.Provider({
-                apiKey: 'test-api-key',
-                entitySecret: 'test-entity-secret',
-                chainId: 999999, // Unsupported chain
-            });
-            const params = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231',
-            };
-            await (0, vitest_1.expect)(provider.request({
-                method: 'eth_call',
-                params: [params],
-            })).rejects.toThrow();
-        });
         (0, vitest_1.it)('should work without from parameter', async () => {
-            const params = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231000000000000000000000000742d35cc6634c0532925a3b8d0c8c0c8d8d8d8d8',
-            };
+            const params = { to: baseParams.to, data: baseParams.data };
             mockScp.queryContract.mockResolvedValue({
                 data: {
                     outputData: '0x0000000000000000000000000000000000000000000000000de0b6b3a7640000',
@@ -1946,52 +1937,111 @@ vitest_1.vi.mock('@circle-fin/developer-controlled-wallets', () => ({
                 fromAddress: undefined,
             });
         });
-        (0, vitest_1.it)('should throw error when blockIdentifier is not "latest"', async () => {
-            const params = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231',
-            };
+        // gas / gasPrice / maxFeePerGas / maxPriorityFeePerGas are EVM-visible during the call:
+        // `gas` affects `gasleft()` and the fee fields determine `tx.gasprice`. Circle's
+        // queryContract cannot represent them, so surface MethodNotFoundRpcError to trigger
+        // fallback rather than silently returning an SCP result that ignored the constraints.
+        vitest_1.it.each([
+            { label: 'gas', param: { gas: (0, viem_1.numberToHex)(1000000n) } },
+            { label: 'gasPrice', param: { gasPrice: (0, viem_1.numberToHex)((0, viem_1.parseEther)('0.00000001')) } },
+            { label: 'maxFeePerGas', param: { maxFeePerGas: (0, viem_1.numberToHex)((0, viem_1.parseEther)('0.00000001')) } },
+            {
+                label: 'maxPriorityFeePerGas',
+                param: { maxPriorityFeePerGas: (0, viem_1.numberToHex)((0, viem_1.parseEther)('0.000000001')) },
+            },
+        ])('should throw MethodNotFoundRpcError when $label is set (fallback trigger)', async ({ param }) => {
+            const provider = makeProviderWithoutFallback(1);
             await (0, vitest_1.expect)(provider.request({
                 method: 'eth_call',
-                params: [params, 'earliest'],
-            })).rejects.toThrow('Only `latest` block identifier is supported');
+                params: [{ ...baseParams, ...param }],
+            })).rejects.toBeInstanceOf(viem_1.MethodNotFoundRpcError);
+            (0, vitest_1.expect)(mockScp.queryContract).not.toHaveBeenCalled();
+        });
+        // `nonce` is transaction-level and not visible inside eth_call, so it's fine to silently
+        // drop — forwarding would be a no-op and throwing would break callers (e.g. viem's
+        // publicClient.call) that may surface nonce for parity with standard JSON-RPC shapes.
+        (0, vitest_1.it)('should silently ignore nonce', async () => {
+            mockScp.queryContract.mockResolvedValue({ data: { outputData: '0xok' } });
+            const result = await provider.request({
+                method: 'eth_call',
+                params: [{ ...baseParams, nonce: (0, viem_1.numberToHex)(42n) }],
+            });
+            (0, vitest_1.expect)(result).toBe('0xok');
+            // nonce must not be forwarded — queryContract only accepts {blockchain, to, data, from}.
+            (0, vitest_1.expect)(mockScp.queryContract).toHaveBeenCalledWith({
+                blockchain: 'ETH',
+                address: baseParams.to,
+                callData: baseParams.data,
+                fromAddress: baseParams.from,
+            });
+        });
+        // `value` arrives as a `Hex` at runtime from JSON-RPC transports, but the
+        // TypeScript surface (`ExactPartial<TransactionRequest>`) admits `bigint`.
+        // Exercise both shapes so the dual-type contract is regression-tested.
+        vitest_1.it.each([
+            { label: 'hex 0x0', value: '0x0' },
+            { label: 'bigint 0n', value: 0n },
+        ])('should accept zero value ($label) as equivalent to no native value', async ({ value }) => {
+            mockScp.queryContract.mockResolvedValue({ data: { outputData: '0xzero' } });
+            const result = await provider.request({
+                method: 'eth_call',
+                params: [{ ...baseParams, value }],
+            });
+            (0, vitest_1.expect)(result).toBe('0xzero');
+            (0, vitest_1.expect)(mockScp.queryContract).toHaveBeenCalledTimes(1);
+        });
+        // `value` is the one param with read semantics (payable view calls). Non-zero must
+        // surface `MethodNotFoundRpcError` so `Provider.request` falls back to the RPC transport.
+        // Again, cover both the hex and bigint shapes.
+        vitest_1.it.each([
+            { label: 'hex 0x1', value: (0, viem_1.numberToHex)(1n) },
+            { label: 'bigint 1n', value: 1n },
+        ])('should throw MethodNotFoundRpcError for non-zero value ($label) (fallback trigger)', async ({ value }) => {
+            const provider = makeProviderWithoutFallback(1);
             await (0, vitest_1.expect)(provider.request({
                 method: 'eth_call',
-                params: [params, '0x1234'],
-            })).rejects.toThrow('Only `latest` block identifier is supported');
+                params: [{ ...baseParams, value }],
+            })).rejects.toBeInstanceOf(viem_1.MethodNotFoundRpcError);
+            (0, vitest_1.expect)(mockScp.queryContract).not.toHaveBeenCalled();
         });
-        (0, vitest_1.it)('should throw error when unsupported transaction params are provided', async () => {
-            const baseParams = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231',
-            };
-            // Test each unsupported parameter individually
-            const unsupportedParams = [
-                { gas: '0x186A0' },
-                { gasPrice: '0x3B9ACA00' },
-                { maxFeePerGas: '0x3B9ACA00' },
-                { maxPriorityFeePerGas: '0x3B9ACA00' },
-                { nonce: '0x1' },
-                { value: '0x0' },
-            ];
-            for (const param of unsupportedParams) {
-                const testParams = { ...baseParams, ...param };
-                await (0, vitest_1.expect)(provider.request({
-                    method: 'eth_call',
-                    params: [testParams],
-                })).rejects.toThrow();
-            }
-            // Test multiple unsupported params together
-            const multipleUnsupportedParams = {
-                ...baseParams,
-                gas: '0x186A0',
-                value: '0x0',
-                nonce: '0x1',
-            };
+        (0, vitest_1.it)('should throw MethodNotFoundRpcError when blockIdentifier is not "latest" (fallback trigger)', async () => {
+            const provider = makeProviderWithoutFallback(1);
             await (0, vitest_1.expect)(provider.request({
                 method: 'eth_call',
-                params: [multipleUnsupportedParams],
-            })).rejects.toThrow();
+                params: [baseParams, 'earliest'],
+            })).rejects.toBeInstanceOf(viem_1.MethodNotFoundRpcError);
+            await (0, vitest_1.expect)(provider.request({
+                method: 'eth_call',
+                params: [baseParams, '0x1234'],
+            })).rejects.toBeInstanceOf(viem_1.MethodNotFoundRpcError);
+            (0, vitest_1.expect)(mockScp.queryContract).not.toHaveBeenCalled();
+        });
+        // AVAX_FUJI (43113) is in SUPPORTED_CHAINS but NOT SUPPORTED_CONTRACT_QUERY_CHAINS.
+        (0, vitest_1.it)('should throw MethodNotFoundRpcError when chain is not supported by queryContract (fallback trigger)', async () => {
+            const provider = makeProviderWithoutFallback(43113);
+            await (0, vitest_1.expect)(provider.request({ method: 'eth_call', params: [baseParams] })).rejects.toBeInstanceOf(viem_1.MethodNotFoundRpcError);
+            (0, vitest_1.expect)(mockScp.queryContract).not.toHaveBeenCalled();
+        });
+        // ARC_TESTNET (5042002) IS in SUPPORTED_CONTRACT_QUERY_CHAINS — reads flow through Circle's SCP.
+        (0, vitest_1.it)('should route Arc Testnet eth_call through queryContract', async () => {
+            // `vi.restoreAllMocks` in the outer beforeEach clears the module-level mock
+            // return; re-prime it before constructing a second Provider for Arc Testnet.
+            ;
+            smart_contract_platform_1.initiateSmartContractPlatformClient.mockReturnValue(mockScp);
+            const arcProvider = new index_js_4.Provider({
+                apiKey: 'test-api-key',
+                entitySecret: 'test-entity-secret',
+                chainId: 5042002, // ARC_TESTNET
+            });
+            mockScp.queryContract.mockResolvedValue({ data: { outputData: '0xarc' } });
+            const result = await arcProvider.request({ method: 'eth_call', params: [baseParams] });
+            (0, vitest_1.expect)(result).toBe('0xarc');
+            (0, vitest_1.expect)(mockScp.queryContract).toHaveBeenCalledWith({
+                blockchain: 'ARC-TESTNET',
+                address: baseParams.to,
+                callData: baseParams.data,
+                fromAddress: baseParams.from,
+            });
         });
     });
     (0, vitest_1.describe)('eth_estimateGas', () => {

package/dist/esm/metadata.js

@@ -11,4 +11,4 @@
 /**
  * The current semantic version of the SDK
  */
-export const VERSION = `${'0.24.2' || '0.0.0'}`;
+export const VERSION = `${'0.25.1' || '0.0.0'}`;

package/dist/esm/providers/circle-wallets/index.d.ts

@@ -10418,6 +10418,194 @@ export declare const SUPPORTED_CONTRACT_QUERY_CHAINS: readonly [{
     readonly blockchainId: "ARB-SEPOLIA";
     readonly blockchainVm: "EVM";
     readonly formatters?: undefined | undefined;
+}, {
+    blockExplorers: {
+        readonly default: {
+            readonly name: "ArcScan";
+            readonly url: "https://testnet.arcscan.app";
+            readonly apiUrl: "https://testnet.arcscan.app/api";
+        };
+    };
+    blockTime?: number | undefined | undefined;
+    contracts: {
+        readonly USDC: {
+            readonly address: "0x3600000000000000000000000000000000000000";
+            readonly abi: readonly [{
+                readonly type: "event";
+                readonly name: "Approval";
+                readonly inputs: readonly [{
+                    readonly indexed: true;
+                    readonly name: "owner";
+                    readonly type: "address";
+                }, {
+                    readonly indexed: true;
+                    readonly name: "spender";
+                    readonly type: "address";
+                }, {
+                    readonly indexed: false;
+                    readonly name: "value";
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "event";
+                readonly name: "Transfer";
+                readonly inputs: readonly [{
+                    readonly indexed: true;
+                    readonly name: "from";
+                    readonly type: "address";
+                }, {
+                    readonly indexed: true;
+                    readonly name: "to";
+                    readonly type: "address";
+                }, {
+                    readonly indexed: false;
+                    readonly name: "value";
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "allowance";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [{
+                    readonly name: "owner";
+                    readonly type: "address";
+                }, {
+                    readonly name: "spender";
+                    readonly type: "address";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "approve";
+                readonly stateMutability: "nonpayable";
+                readonly inputs: readonly [{
+                    readonly name: "spender";
+                    readonly type: "address";
+                }, {
+                    readonly name: "amount";
+                    readonly type: "uint256";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "bool";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "balanceOf";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [{
+                    readonly name: "account";
+                    readonly type: "address";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "decimals";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [];
+                readonly outputs: readonly [{
+                    readonly type: "uint8";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "name";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [];
+                readonly outputs: readonly [{
+                    readonly type: "string";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "symbol";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [];
+                readonly outputs: readonly [{
+                    readonly type: "string";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "totalSupply";
+                readonly stateMutability: "view";
+                readonly inputs: readonly [];
+                readonly outputs: readonly [{
+                    readonly type: "uint256";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "transfer";
+                readonly stateMutability: "nonpayable";
+                readonly inputs: readonly [{
+                    readonly name: "recipient";
+                    readonly type: "address";
+                }, {
+                    readonly name: "amount";
+                    readonly type: "uint256";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "bool";
+                }];
+            }, {
+                readonly type: "function";
+                readonly name: "transferFrom";
+                readonly stateMutability: "nonpayable";
+                readonly inputs: readonly [{
+                    readonly name: "sender";
+                    readonly type: "address";
+                }, {
+                    readonly name: "recipient";
+                    readonly type: "address";
+                }, {
+                    readonly name: "amount";
+                    readonly type: "uint256";
+                }];
+                readonly outputs: readonly [{
+                    readonly type: "bool";
+                }];
+            }];
+            readonly read: {
+                readonly decimals: () => 6;
+            };
+        };
+        readonly multicall3: {
+            readonly address: "0xcA11bde05977b3631167028862bE2a173976CA11";
+            readonly blockCreated: 0;
+        };
+    };
+    ensTlds?: readonly string[] | undefined;
+    id: 5042002;
+    name: "Arc Testnet";
+    nativeCurrency: {
+        readonly name: "USDC";
+        readonly symbol: "USDC";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://rpc.testnet.arc.network", "https://rpc.quicknode.testnet.arc.network", "https://rpc.blockdaemon.testnet.arc.network"];
+            readonly webSocket: readonly ["wss://rpc.testnet.arc.network", "wss://rpc.quicknode.testnet.arc.network"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    testnet: true;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable<bigint, number>> | undefined;
+    verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+    readonly blockchainId: "ARC-TESTNET";
+    readonly blockchainVm: "EVM";
+    readonly formatters?: undefined | undefined;
 }, {
     blockExplorers: {
         readonly default: {

package/dist/esm/providers/circle-wallets/index.js

@@ -52,6 +52,7 @@ export const SUPPORTED_CONTRACT_QUERY_CHAINS = [
     MATIC_AMOY,
     ARB,
     ARB_SEPOLIA,
+    ARC_TESTNET,
     UNI,
     UNI_SEPOLIA,
     BASE,

package/dist/esm/providers/circle-wallets/transports/index.js

@@ -116,17 +116,47 @@ export class Provider extends BaseProvider {
     }
     async eth_call(params, blockIdentifier = 'latest') {
         // NOTE: https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call
-        // In JSON-RPC `eth_call` spec, blockIdentifier is a required parameter.
-        // It is a hex string of the block number, 'latest', 'earliest', 'pending', 'safe' or 'finalized'.
-        // Although Circle's query contract API does not support it, we still add it to be compatible with the JSON-RPC spec.
+        // Circle's query contract API has a narrow surface (blockchain, to, data, from). For anything
+        // it cannot represent, throw `MethodNotFoundRpcError` so `Provider.request` falls back to the
+        // embedded viem RPC transport instead of hard-failing the caller. This matters in particular
+        // for viem-based adapters (e.g. the Circle Wallets adapter's pre-flight `publicClient.call`
+        // during a swap), which forward `gas`/`value` into `eth_call` as a matter of course.
         if (blockIdentifier !== 'latest') {
-            throw new Error('Only `latest` block identifier is supported');
+            throw new MethodNotFoundRpcError(new Error('Only `latest` block identifier is supported by Circle queryContract'), {
+                method: 'eth_call',
+            });
+        }
+        // gas / gasPrice / maxFeePerGas / maxPriorityFeePerGas are EVM-visible during the target
+        // call: `gas` bounds `gasleft()` and affects out-of-gas behavior; the fee fields determine
+        // `tx.gasprice`, which contracts can read. Circle's queryContract cannot thread these
+        // through, so surface `MethodNotFoundRpcError` to trigger fallback rather than silently
+        // returning an SCP result that ignored the caller's explicit simulation constraints.
+        const gasPricingParams = ['gas', 'gasPrice', 'maxFeePerGas', 'maxPriorityFeePerGas'];
+        if (gasPricingParams.some((param) => params[param] !== undefined)) {
+            throw new MethodNotFoundRpcError(new Error('gas / gasPrice / maxFeePerGas / maxPriorityFeePerGas are not supported by Circle queryContract'), { method: 'eth_call' });
+        }
+        // `nonce` is transaction-level and not EVM-visible inside eth_call, so silently drop it —
+        // forwarding would be a no-op and throwing would break callers that forward nonce for parity.
+        // `value` is the one remaining param with read semantics (payable view calls). `0x0` / `0n`
+        // mean "no native value" and are accepted; anything else cannot be expressed through
+        // queryContract, so fall back to the RPC transport. Accept both the typed `bigint` and the
+        // runtime JSON-RPC `Hex` shape (viem's `TransactionRequest.value` is typed `bigint`, but
+        // transports deliver hex).
+        const rawValue = params.value;
+        let valueAsBigInt;
+        if (rawValue === undefined) {
+            valueAsBigInt = 0n;
         }
-        // Since Circle's query contract API does not support some transaction params,
-        // to prevent misuse, we throw an error if they are provided.
-        const unsupportedTransactionParams = ['gas', 'gasPrice', 'maxFeePerGas', 'maxPriorityFeePerGas', 'nonce', 'value'];
-        if (unsupportedTransactionParams.some((param) => params[param] !== undefined)) {
-            throw new Error(`Unsupported transaction params: ${unsupportedTransactionParams.join(', ')}`);
+        else if (typeof rawValue === 'bigint') {
+            valueAsBigInt = rawValue;
+        }
+        else {
+            valueAsBigInt = hexToBigInt(rawValue);
+        }
+        if (valueAsBigInt !== 0n) {
+            throw new MethodNotFoundRpcError(new Error('Non-zero `value` is not supported by Circle queryContract'), {
+                method: 'eth_call',
+            });
         }
         // Provider's chainId is used to determine the blockchain
         // When the chain is not supported by Circle's query contract API, throw MethodNotFoundRpcError to fallback.

package/dist/esm/providers/circle-wallets/transports/index.test.js

@@ -1851,12 +1851,21 @@ describe('Provider', () => {
         });
     });
     describe('eth_call', () => {
+        // Build a provider with `fallbackTransport: null` so the inner `eth_call` errors
+        // surface raw instead of being silently retried on the fallback RPC transport.
+        // The production default IS to fall back; these tests pin the inner contract.
+        const makeProviderWithoutFallback = (chainId) => new Provider({
+            apiKey: 'test-api-key',
+            entitySecret: 'test-entity-secret',
+            chainId,
+            fallbackTransport: null,
+        });
+        const baseParams = {
+            to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
+            data: '0x70a08231000000000000000000000000742d35cc6634c0532925a3b8d0c8c0c8d8d8d8d8',
+            from: '0x123456789abcdef123456789abcdef123456789a',
+        };
         it('should perform contract query successfully', async () => {
-            const params = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231000000000000000000000000742d35cc6634c0532925a3b8d0c8c0c8d8d8d8d8',
-                from: '0x123456789abcdef123456789abcdef123456789a',
-            };
             mockScp.queryContract.mockResolvedValue({
                 data: {
                     outputData: '0x0000000000000000000000000000000000000000000000000de0b6b3a7640000',
@@ -1864,36 +1873,18 @@ describe('Provider', () => {
             });
             const result = await provider.request({
                 method: 'eth_call',
-                params: [params],
+                params: [baseParams],
             });
             expect(result).toBe('0x0000000000000000000000000000000000000000000000000de0b6b3a7640000');
             expect(mockScp.queryContract).toHaveBeenCalledWith({
                 blockchain: 'ETH',
-                address: params.to,
-                callData: params.data,
-                fromAddress: params.from,
+                address: baseParams.to,
+                callData: baseParams.data,
+                fromAddress: baseParams.from,
             });
         });
-        it('should throw UnsupportedChainError when chainId is not supported for contract queries', async () => {
-            const provider = new Provider({
-                apiKey: 'test-api-key',
-                entitySecret: 'test-entity-secret',
-                chainId: 999999, // Unsupported chain
-            });
-            const params = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231',
-            };
-            await expect(provider.request({
-                method: 'eth_call',
-                params: [params],
-            })).rejects.toThrow();
-        });
         it('should work without from parameter', async () => {
-            const params = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231000000000000000000000000742d35cc6634c0532925a3b8d0c8c0c8d8d8d8d8',
-            };
+            const params = { to: baseParams.to, data: baseParams.data };
             mockScp.queryContract.mockResolvedValue({
                 data: {
                     outputData: '0x0000000000000000000000000000000000000000000000000de0b6b3a7640000',
@@ -1911,52 +1902,111 @@ describe('Provider', () => {
                 fromAddress: undefined,
             });
         });
-        it('should throw error when blockIdentifier is not "latest"', async () => {
-            const params = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231',
-            };
+        // gas / gasPrice / maxFeePerGas / maxPriorityFeePerGas are EVM-visible during the call:
+        // `gas` affects `gasleft()` and the fee fields determine `tx.gasprice`. Circle's
+        // queryContract cannot represent them, so surface MethodNotFoundRpcError to trigger
+        // fallback rather than silently returning an SCP result that ignored the constraints.
+        it.each([
+            { label: 'gas', param: { gas: numberToHex(1000000n) } },
+            { label: 'gasPrice', param: { gasPrice: numberToHex(parseEther('0.00000001')) } },
+            { label: 'maxFeePerGas', param: { maxFeePerGas: numberToHex(parseEther('0.00000001')) } },
+            {
+                label: 'maxPriorityFeePerGas',
+                param: { maxPriorityFeePerGas: numberToHex(parseEther('0.000000001')) },
+            },
+        ])('should throw MethodNotFoundRpcError when $label is set (fallback trigger)', async ({ param }) => {
+            const provider = makeProviderWithoutFallback(1);
             await expect(provider.request({
                 method: 'eth_call',
-                params: [params, 'earliest'],
-            })).rejects.toThrow('Only `latest` block identifier is supported');
+                params: [{ ...baseParams, ...param }],
+            })).rejects.toBeInstanceOf(MethodNotFoundRpcError);
+            expect(mockScp.queryContract).not.toHaveBeenCalled();
+        });
+        // `nonce` is transaction-level and not visible inside eth_call, so it's fine to silently
+        // drop — forwarding would be a no-op and throwing would break callers (e.g. viem's
+        // publicClient.call) that may surface nonce for parity with standard JSON-RPC shapes.
+        it('should silently ignore nonce', async () => {
+            mockScp.queryContract.mockResolvedValue({ data: { outputData: '0xok' } });
+            const result = await provider.request({
+                method: 'eth_call',
+                params: [{ ...baseParams, nonce: numberToHex(42n) }],
+            });
+            expect(result).toBe('0xok');
+            // nonce must not be forwarded — queryContract only accepts {blockchain, to, data, from}.
+            expect(mockScp.queryContract).toHaveBeenCalledWith({
+                blockchain: 'ETH',
+                address: baseParams.to,
+                callData: baseParams.data,
+                fromAddress: baseParams.from,
+            });
+        });
+        // `value` arrives as a `Hex` at runtime from JSON-RPC transports, but the
+        // TypeScript surface (`ExactPartial<TransactionRequest>`) admits `bigint`.
+        // Exercise both shapes so the dual-type contract is regression-tested.
+        it.each([
+            { label: 'hex 0x0', value: '0x0' },
+            { label: 'bigint 0n', value: 0n },
+        ])('should accept zero value ($label) as equivalent to no native value', async ({ value }) => {
+            mockScp.queryContract.mockResolvedValue({ data: { outputData: '0xzero' } });
+            const result = await provider.request({
+                method: 'eth_call',
+                params: [{ ...baseParams, value }],
+            });
+            expect(result).toBe('0xzero');
+            expect(mockScp.queryContract).toHaveBeenCalledTimes(1);
+        });
+        // `value` is the one param with read semantics (payable view calls). Non-zero must
+        // surface `MethodNotFoundRpcError` so `Provider.request` falls back to the RPC transport.
+        // Again, cover both the hex and bigint shapes.
+        it.each([
+            { label: 'hex 0x1', value: numberToHex(1n) },
+            { label: 'bigint 1n', value: 1n },
+        ])('should throw MethodNotFoundRpcError for non-zero value ($label) (fallback trigger)', async ({ value }) => {
+            const provider = makeProviderWithoutFallback(1);
             await expect(provider.request({
                 method: 'eth_call',
-                params: [params, '0x1234'],
-            })).rejects.toThrow('Only `latest` block identifier is supported');
+                params: [{ ...baseParams, value }],
+            })).rejects.toBeInstanceOf(MethodNotFoundRpcError);
+            expect(mockScp.queryContract).not.toHaveBeenCalled();
         });
-        it('should throw error when unsupported transaction params are provided', async () => {
-            const baseParams = {
-                to: '0x742d35cc6634C0532925a3b8D0c8c0C8D8d8d8d8',
-                data: '0x70a08231',
-            };
-            // Test each unsupported parameter individually
-            const unsupportedParams = [
-                { gas: '0x186A0' },
-                { gasPrice: '0x3B9ACA00' },
-                { maxFeePerGas: '0x3B9ACA00' },
-                { maxPriorityFeePerGas: '0x3B9ACA00' },
-                { nonce: '0x1' },
-                { value: '0x0' },
-            ];
-            for (const param of unsupportedParams) {
-                const testParams = { ...baseParams, ...param };
-                await expect(provider.request({
-                    method: 'eth_call',
-                    params: [testParams],
-                })).rejects.toThrow();
-            }
-            // Test multiple unsupported params together
-            const multipleUnsupportedParams = {
-                ...baseParams,
-                gas: '0x186A0',
-                value: '0x0',
-                nonce: '0x1',
-            };
+        it('should throw MethodNotFoundRpcError when blockIdentifier is not "latest" (fallback trigger)', async () => {
+            const provider = makeProviderWithoutFallback(1);
             await expect(provider.request({
                 method: 'eth_call',
-                params: [multipleUnsupportedParams],
-            })).rejects.toThrow();
+                params: [baseParams, 'earliest'],
+            })).rejects.toBeInstanceOf(MethodNotFoundRpcError);
+            await expect(provider.request({
+                method: 'eth_call',
+                params: [baseParams, '0x1234'],
+            })).rejects.toBeInstanceOf(MethodNotFoundRpcError);
+            expect(mockScp.queryContract).not.toHaveBeenCalled();
+        });
+        // AVAX_FUJI (43113) is in SUPPORTED_CHAINS but NOT SUPPORTED_CONTRACT_QUERY_CHAINS.
+        it('should throw MethodNotFoundRpcError when chain is not supported by queryContract (fallback trigger)', async () => {
+            const provider = makeProviderWithoutFallback(43113);
+            await expect(provider.request({ method: 'eth_call', params: [baseParams] })).rejects.toBeInstanceOf(MethodNotFoundRpcError);
+            expect(mockScp.queryContract).not.toHaveBeenCalled();
+        });
+        // ARC_TESTNET (5042002) IS in SUPPORTED_CONTRACT_QUERY_CHAINS — reads flow through Circle's SCP.
+        it('should route Arc Testnet eth_call through queryContract', async () => {
+            // `vi.restoreAllMocks` in the outer beforeEach clears the module-level mock
+            // return; re-prime it before constructing a second Provider for Arc Testnet.
+            ;
+            initiateSmartContractPlatformClient.mockReturnValue(mockScp);
+            const arcProvider = new Provider({
+                apiKey: 'test-api-key',
+                entitySecret: 'test-entity-secret',
+                chainId: 5042002, // ARC_TESTNET
+            });
+            mockScp.queryContract.mockResolvedValue({ data: { outputData: '0xarc' } });
+            const result = await arcProvider.request({ method: 'eth_call', params: [baseParams] });
+            expect(result).toBe('0xarc');
+            expect(mockScp.queryContract).toHaveBeenCalledWith({
+                blockchain: 'ARC-TESTNET',
+                address: baseParams.to,
+                callData: baseParams.data,
+                fromAddress: baseParams.from,
+            });
         });
     });
     describe('eth_estimateGas', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/usdckit",
-  "version": "0.24.2",
+  "version": "0.25.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/crcl-main/w3s-node-sdk.git"
@@ -19,7 +19,7 @@
     "@solana-program/token-2022": "^0.4.2",
     "@solana/kit": "^2.3.0",
     "@wagmi/core": "^2.20.3",
-    "axios": "^1.9.0",
+    "axios": "^1.13.5",
     "commander": "^14.0.0",
     "pino": "^9.9.0",
     "uuid": "^11.0.3",