RPC & Network Config
Relevant source files
The following files were used as context for generating this wiki page:
RPC and Network configuration in the Walletless library enables a "Man-in-the-Middle" pattern for E2E testing. The system distinguishes between blockchain read operations, which are forwarded to a configured RPC provider (typically Anvil), and write operations or wallet state requests, which are handled locally. This architecture provides production-realistic chain interactions while maintaining deterministic control over signing accounts and network state.
Sources: src/provider.ts:101-107, README.md:14-25
Core Configuration Architecture
The configuration is centered around the E2EProviderConfig and E2EConnectorParameters types. These define the supported chains, per-chain RPC endpoints, and the primary signing account.
Configuration Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
chains | CompatibleChain[] | [mainnet] | Array of supported blockchain networks. The first entry is used as the initial default. |
rpcUrls | Record<number, string> | {} | Mapping of chain IDs to specific RPC endpoints. Falls back to http://127.0.0.1:8545. |
account | Hex | Account | Anvil Account 0 | The private key or viem Account object used for signing transactions. |
debug | boolean | false | Enables verbose logging of RPC requests and internal state transitions. |
Sources: src/types.ts:25-45, src/constants.ts:5-10, src/constants.ts:79-80
Network Data Flow
The provider routes requests based on the RPC method type. Read methods are dispatched via HTTP POST to the active RPC URL, while wallet and write methods update internal state or use a local walletClient.
The diagram above illustrates how the provider acts as a router for different categories of Ethereum JSON-RPC calls.
Sources: src/provider.ts:311-334, README.md:14-25
RPC Method Categorization
The system maintains explicit lists of supported methods to determine how to route traffic.
Read Methods
Methods such as eth_call, eth_getBalance, and eth_getTransactionReceipt are forwarded directly to the RPC endpoint. These represent the "Chain Realism" aspect of the provider.
Sources: src/constants.ts:86-136
Wallet and State Methods
Methods like eth_accounts, eth_chainId, and wallet_switchEthereumChain interact with the provider's internal ProviderState. These calls never reach the external RPC server.
Sources: src/constants.ts:142-155, src/provider.ts:258-305
Write and Signing Methods
Methods requiring cryptographic signatures, such as eth_sendTransaction or personal_sign, are intercepted. The provider uses a internal walletClient configured with the current account and rpcUrl to sign and potentially broadcast transactions.
Sources: src/constants.ts:161-172, src/provider.ts:187-252
Multichain and Chain Switching
The configuration supports multiple concurrent networks. When a chain switch is triggered via wallet_switchEthereumChain or the setChain helper, the provider performs a coordinated update of its internal components.
Chain Switch Sequence
The provider ensures that the WalletClient always uses the transport corresponding to the active chain's RPC URL.
Sources: src/provider.ts:275-300, src/provider.ts:365-375, test/provider.spec.ts:125-155
RPC Communication Implementation
The provider uses the native fetch API to communicate with external RPC nodes. It wraps requests in a standard JSON-RPC 2.0 envelope and handles error codes returned by the remote server.
async function sendJsonRpc<T>(method: string, params?: unknown[]): Promise<T> {
const rpcRequest: JsonRpcRequest = {
jsonrpc: "2.0",
method,
params,
id: requestId,
};
const response = await fetch(internal.rpcUrl, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(rpcRequest),
});
const data: JsonRpcResponse<T> = (await response.json()) as JsonRpcResponse<T>;
// Error handling logic...
}
Sources: src/provider.ts:153-181
Default Network Constants
| Constant | Value | Description |
|---|---|---|
DEFAULT_ANVIL_RPC_URL | http://127.0.0.1:8545 | Primary fallback URL if no RPC map is provided. |
DEFAULT_CHAIN | mainnet (viem) | Initial network used if the chains array is empty. |
ANVIL_ACCOUNTS | 10 Pre-defined accounts | Deterministic accounts derived from the standard Anvil mnemonic. |
Sources: src/constants.ts:5-76, src/constants.ts:80
The RPC and Network configuration provides a flexible bridge between a local testing environment and realistic blockchain state. By mapping chain IDs to specific URLs and intercepting state-changing calls, it allows developers to simulate complex multi-chain scenarios with zero latency from browser extensions.
Sources: README.md:27-33, src/provider.ts:101-115