Request Routing Logic

Relevant source files

The following files were used as context for generating this wiki page:

• src/provider.ts
• src/constants.ts
• src/types.ts
• src/connector.ts
• README.md

Introduction

The request routing logic in the Walletless project functions as a "Man-in-the-Middle" system for EIP-1193 compatible providers. Its primary purpose is to intercept JSON-RPC requests from a DApp and determine whether they should be forwarded to an external RPC node (such as Anvil) or handled locally through internal signing and state management.

This logic ensures high-performance E2E testing by virtualizing wallet interactions while maintaining chain realism. Read-only operations are routed to the blockchain, while write and wallet operations are processed by the internal E2EProvider to allow for deterministic testing and manual control over account and chain states.

Sources: src/provider.ts:109-115, README.md:14-25

Routing Architecture

The core of the routing logic resides within the request function of the createE2EProvider. It classifies incoming RPC methods into three distinct categories to decide the execution path.

Classification Categories

Category	Method Type	Handling Logic
Wallet Methods	State & Configuration	Handled locally; updates internal provider state like chainId or accounts.
Write Methods	Signing & Transactions	Handled locally using a viem wallet client and a private key.
Read Methods	Blockchain Queries	Forwarded via HTTP POST to the configured Anvil/RPC URL.

Sources: src/provider.ts:400-422, src/constants.ts:133-186

Request Flow Overview

The following diagram illustrates how a request is intercepted and routed based on its method type.

The provider maintains an internal requestId that increments with every call to track and log the request/response lifecycle.
Sources: src/provider.ts:392-425, src/provider.ts:153

Detailed Handling Logic

Wallet Methods (handleWalletMethod)

These methods manage the provider's connection status and configuration. Key operations include:

• Account Discovery: eth_accounts and eth_requestAccounts return the current signing account's address stored in the internal state.
• Chain Management: wallet_switchEthereumChain validates the requested chainId against supportedChainIds. If valid, it updates the rpcUrl and recreates the walletClient for the new chain.
• Events: Triggers connect on the first account request and chainChanged when switching networks.

Sources: src/provider.ts:321-370, src/types.ts:117-122

Write Methods (handleWriteMethod)

Write operations are intercepted to perform local signing, preventing the need for browser extensions or manual interaction during tests.

• Transaction Interception: eth_sendTransaction parameters (to, value, data, gas) are parsed and passed to the walletClient.sendTransaction method.
• Message Signing: Supports personal_sign, eth_sign, and various eth_signTypedData versions using the internal private key account.
• Rejection Simulation: Before processing, the logic checks rejectTransaction and rejectSignature flags. If enabled, the provider throws a ProviderRpcError with code 4001 (User Rejected Request).

Sources: src/provider.ts:221-305, src/types.ts:175-181

Read Methods (handleReadMethod)

Read methods are forwarded to the current rpcUrl using the native fetch API.

• The request is wrapped in a standard JSON-RPC 2.0 structure.
• The system uses internal.rpcUrl, which dynamically changes if the user switches chains via setChain or wallet_switchEthereumChain.

Method Categorization Utilities

The routing logic relies on helper functions defined in constants.ts to identify method types using string arrays.

export function isReadMethod(method: string): method is ReadMethod {
    return READ_METHODS.includes(method as ReadMethod);
}

export function isWalletMethod(method: string): method is WalletMethod {
    return WALLET_METHODS.includes(method as WalletMethod);
}

export function isWriteMethod(method: string): method is WriteMethod {
    return WRITE_METHODS.includes(method as WriteMethod);
}

Sources: src/constants.ts:188-208

Summary

The request routing logic centralizes the distinction between chain state and wallet interaction. By segmenting methods into Wallet, Write, and Read categories, the system allows for transparent blockchain data retrieval while providing developers with tools to programmatically control account switching, network changes, and transaction outcomes during E2E test execution.

Sources: src/provider.ts:400-425, README.md:18-28