Provider Options

Relevant source files

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

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

The Walletless library provides a "man-in-the-middle" virtual EIP-1193 provider designed specifically for high-performance E2E testing. It allows developers to configure a provider that redirects read operations to a remote or local RPC (like Anvil) while intercepting write and signing operations to be handled locally using pre-configured accounts.

This system is highly configurable through the E2EProviderConfig and E2EConnectorParameters types, enabling multichain support, custom RPC mapping, and deterministic account management without the overhead of browser extensions or manual wallet interactions.

Sources: src/types.ts:16-21, src/provider.ts:107-113, README.md:9-25

Provider Configuration (E2EProviderConfig)

The createE2EProvider function accepts a configuration object that defines the behavior of the virtual provider. If no configuration is provided, the system defaults to using Anvil's first test account on Ethereum Mainnet via a local RPC.

Configuration Fields

Parameter	Type	Default	Description
chains	readonly CompatibleChain[]	[mainnet]	Supported chains. The first chain in the array is used as the initial default.
rpcUrls	Record<number, string>	{}	A mapping of chain IDs to RPC URLs. Falls back to http://127.0.0.1:8545 if a chain ID is missing.
account	Hex | Account	Anvil Account #0	The private key (Hex) or viem Account used to sign transactions and messages.
debug	boolean	false	Enables verbose logging of RPC requests and internal state transitions.

Sources: src/types.ts:24-38, src/provider.ts:121-137, src/constants.ts:6-76

Initialization Flow

When initialized, the provider sets up an internal state that tracks the current active chain, the derived wallet client, and signing permissions.

The provider derives the initial RPC URL based on the default chain and the provided rpcUrls map. If no match is found, it uses the DEFAULT_ANVIL_RPC_URL.
Sources: src/provider.ts:139-165, src/constants.ts:4-6

Connector Options (Wagmi Integration)

For projects using Wagmi, the e2eConnector function acts as a bridge. It can be configured in two ways: by passing a full configuration object or by passing an existing provider instance.

Connector Parameter Types

1. Config-based (E2EConnectorConfigParams): Allows the connector to manage the lifecycle of the provider internally. It shares the same fields as E2EProviderConfig.
2. Provider-based (E2EConnectorProviderParams): Accepts a pre-constructed provider instance. This is the recommended approach for E2E tests where you need to reference the provider (e.g., via window) to call control methods like setSigningAccount.

Sources: src/connector.ts:18-53, README.md:144-155

Connector Logic Flow

The connector uses type guards to determine how to resolve the provider and its associated events.

Method Categorization and Routing

The provider routes EIP-1193 requests based on the method name. This logic is governed by the configuration of READ_METHODS, WRITE_METHODS, and WALLET_METHODS.

Routing Table

Category	Methods (Examples)	Routing Logic
Read	eth_call, eth_getBalance, eth_estimateGas	Forwarded via POST fetch to the current rpcUrl.
Write	eth_sendTransaction, personal_sign, eth_signTypedData_v4	Signed locally using the walletClient and then (for TXs) sent to RPC.
Wallet	eth_accounts, eth_chainId, wallet_switchEthereumChain	Handled by updating the provider's InternalState.

Sources: src/constants.ts:78-154, src/provider.ts:262-284

Runtime Control Options

Once initialized, the provider exposes several methods to manipulate the testing environment dynamically. These are accessible via standalone helper functions or directly on the E2EProviderWithInternal interface.

Dynamic Switching

• setSigningAccount(account): Updates the account and walletClient in the internal state. It accepts an index (0-9), an address, a raw private key, or a viem Account object.
• setChain(chainId): Validates if the chain is supported in the initial chains configuration, updates the RPC URL, and recreates the walletClient.

Failure Simulation

These options allow developers to test edge cases by forcing the provider to throw ProviderRpcError with code 4001 (User Rejected Request).

• setRejectSignature(boolean): Affects methods like personal_sign and eth_signTypedData.
• setRejectTransaction(boolean): Affects eth_sendTransaction.

Sources: src/provider-controls.ts:12-140, src/provider.ts:413-460, src/types.ts:133-143

Summary

Provider options in Walletless are designed to provide a deterministic environment for Web3 application testing. By configuring chains, rpcUrls, and account at startup, and utilizing control methods like setChain and setRejectTransaction during runtime, developers can simulate complex multichain scenarios and user behaviors with high performance and zero external dependencies.

Sources: README.md:27-33, src/provider.ts:107-113