Standalone Provider Usage
Relevant source files
The following files were used as context for generating this wiki page:
The @wonderland/walletless standalone provider is a virtual EIP-1193 compatible provider designed for high-performance E2E testing of Web3 applications. It functions as a "man-in-the-middle," where blockchain read operations are forwarded to an RPC node (typically Anvil), while write and signing operations are handled locally using private keys or viem accounts.
This standalone implementation allows developers to bypass browser extensions and manual wallet interactions, enabling deterministic testing environments. It can be integrated directly into testing frameworks like Playwright or Cypress by exposing the provider on the global window object.
Sources: README.md:1-15, src/provider.ts:108-115
Provider Architecture and Request Routing
The provider implements a routing logic that classifies incoming JSON-RPC methods into three categories: Read, Write, and Wallet. This classification determines whether the request is fulfilled by a local signing client or forwarded to an external RPC endpoint.
The diagram shows how the provider intercepts DApp requests and routes them based on method type.
Sources: src/provider.ts:468-490, src/constants.ts:77-160
Method Classification
The routing logic is governed by specific method lists defined in the core constants:
| Category | Description | Key Methods |
|---|---|---|
| Read | Fetches data from the chain. Forwarded to rpcUrl. | eth_getBalance, eth_call, eth_getTransactionReceipt |
| Write | Requires cryptographic signatures. Handled by walletClient. | eth_sendTransaction, personal_sign, eth_signTypedData_v4 |
| Wallet | Manages provider/account state. Handled internally. | eth_requestAccounts, wallet_switchEthereumChain, eth_chainId |
Sources: src/constants.ts:77-160
Configuration and Initialization
The provider is instantiated using createE2EProvider(), which accepts an E2EProviderConfig object. If no configuration is provided, it defaults to using the first Anvil test account and a local RPC at http://127.0.0.1:8545.
Configuration Options
| Parameter | Type | Default | Description |
|---|---|---|---|
chains | Chain[] | [mainnet] | Supported chains; the first entry is the default. |
rpcUrls | Record<number, string> | {} | Mapping of chain IDs to RPC endpoints. |
account | Hex | Account | Anvil #0 Key | Private key or viem Account used for signing. |
debug | boolean | false | Enables verbose logging of RPC traffic. |
Sources: src/types.ts:25-45, src/provider.ts:133-145
Initialization Example
import { createE2EProvider } from "@wonderland/walletless";
import { mainnet, arbitrum } from "viem/chains";
const provider = createE2EProvider({
chains: [mainnet, arbitrum],
rpcUrls: {
1: "http://localhost:8545",
42161: "http://localhost:8546",
},
debug: true
});
Sources: README.md:144-155, src/provider.ts:133-145
Test Control API
The standalone provider exposes a specific control API that allows tests to manipulate the provider's state programmatically. This is essential for simulating user rejections, switching accounts, or changing networks mid-test.
Account Management
The setSigningAccount method allows switching the active signer. It accepts various input formats:
- Index (0-9): Selects one of the ten default Anvil accounts.
- Address: Looks up a matching Anvil account address.
- Private Key (Hex): Uses a raw 66-character hex string.
- Account: Accepts a standard viem
Accountobject.
Sources: src/provider.ts:42-79, src/provider.ts:515-520
Transaction and Signature Control
Developers can simulate "User Rejected" errors by toggling internal flags. When enabled, the provider throws a ProviderRpcError with code 4001.
Summary of Control Methods
| Method | Description | Source |
|---|---|---|
setSigningAccount(input) | Updates the active signer and emits accountsChanged. | src/provider.ts:515 |
setChain(chainId) | Switches current chain/RPC and emits chainChanged. | src/provider.ts:530 |
setRejectSignature(bool) | Rejects signature requests when true. | src/provider.ts:522 |
setRejectTransaction(bool) | Rejects transaction requests when true. | src/provider.ts:526 |
disconnect() | Emits the EIP-1193 disconnect event. | src/provider.ts:553 |
Error Handling
The provider utilizes the ProviderRpcError class to communicate failures according to EIP-1193 specifications.
| Error Code | Constant | Meaning |
|---|---|---|
4001 | UserRejectedRequest | User (the test runner) rejected the request. |
4200 | UnsupportedMethod | The requested RPC method is not implemented. |
4900 | Disconnected | The provider is disconnected from the chain. |
4902 | ChainDisconnected | Attempted to switch to an unsupported chain. |
Sources: src/types.ts:137-156, src/provider.ts:382-390
Conclusion
Standalone usage of the Walletless provider enables deterministic Web3 testing by providing a controllable, virtualized EIP-1193 interface. By separating read and write concerns and providing a dedicated control API, it allows for high-speed E2E tests that can simulate complex user behaviors and network conditions without the overhead of physical wallet interactions.