Installation & Setup

Relevant source files

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

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

The @wonderland/walletless library provides a virtual EIP-1193 provider designed for high-performance E2E testing of Web3 decentralized applications (DApps). It functions as a man-in-the-middle injected provider that intercepts write operations for local signing while forwarding read operations to an Anvil RPC node.

This setup eliminates the overhead of browser extensions like MetaMask during testing, allowing for deterministic and fast execution in CI/CD environments and headless browsers.
Sources: README.md:1-13, package.json:2-10

System Requirements

Before installing the library, ensure your environment meets the following technical requirements:

• Node.js: Version 20 or higher is required.
• Package Manager: The project is configured to use pnpm (v9.7.1 internally), but it is compatible with standard npm or yarn.
• Peer Dependencies: You must have viem (>=2.0.0) and wagmi (>=2.0.0) installed in your project.
• Local Node: Foundry (Anvil) is the recommended local Ethereum node for the backend RPC.

Sources: package.json:71-85, README.md:213-225

Core Installation

To add the library to your project, execute the following command:

pnpm add @wonderland/walletless

Sources: README.md:46-48

Provider Architecture

The library operates by bifurcating RPC traffic based on the method type. The following diagram illustrates how the E2EProvider manages data flow between the DApp UI and the Ethereum node.

Read operations (e.g., eth_call, eth_getBalance) are forwarded directly to the RPC URL. Write operations (e.g., eth_sendTransaction, eth_sign) are signed using a local private key and then broadcasted.
Sources: README.md:15-32, src/provider.ts:168-180, src/constants.ts:79-138

Configuration Options

The provider and connector can be customized using the E2EProviderConfig and E2EConnectorParameters structures.

Provider Configuration

Parameter	Type	Default	Description
chains	CompatibleChain[]	[mainnet]	Array of supported chains; the first entry is the default.
rpcUrls	Record<number, string>	{}	Mapping of chain IDs to RPC endpoints. Defaults to http://127.0.0.1:8545.
account	Hex | Account	Anvil Account #0	Private key or viem Account object used for signing.
debug	boolean	false	Enables verbose console logging of RPC requests.

Sources: src/types.ts:21-39, src/constants.ts:4-6, src/provider.ts:140-155

Integration Patterns

Wagmi Connector Setup

The e2eConnector is a plug-and-play solution for Wagmi configurations. It can be initialized with custom parameters or a pre-existing provider instance.

Standalone Provider Setup

For non-Wagmi environments or direct EIP-1193 interactions, the provider can be instantiated directly.

import { createE2EProvider } from "@wonderland/walletless";
import { mainnet } from "viem/chains";

const provider = createE2EProvider({
    chains: [mainnet],
    rpcUrls: {
        1: "http://localhost:8545"
    }
});

Sources: README.md:105-115, src/provider.ts:138-160

Local Node Setup (Anvil)

To utilize @wonderland/walletless effectively, a local Anvil instance must be running. Anvil provides the 10 default test accounts used by the library if no custom account is provided.

Account Index	Address	Usage
0	0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266	Default Signing Account
1-9	Various	Accessible via setSigningAccount(index)

Commands to initialize the environment:

1. Standard Start: anvil
2. Mainnet Fork: anvil --fork-url <RPC_ENDPOINT>
3. Custom Port: anvil --port 8545

Sources: src/constants.ts:15-64, README.md:213-255

Conclusion

Setting up @wonderland/walletless involves installing the package, configuring the e2eConnector for Wagmi (or using the standalone provider), and ensuring an Anvil node is available for RPC requests. By leveraging the default Anvil accounts and the man-in-the-middle architecture, developers can achieve significant speedups in E2E testing suites without external wallet dependencies.
Sources: README.md:34-44, package.json:2-10