Core Dependencies

Relevant source files

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

• package.json
• src/provider.ts
• src/connector.ts
• src/types.ts
• src/constants.ts
• src/index.ts

The @wonderland/walletless project is a lightweight E2E provider designed for Web3 DApps, functioning as a virtual EIP-1193 provider. Its primary purpose is to enable deterministic and high-performance end-to-end testing by intercepting blockchain interactions. It distinguishes between read operations, which are forwarded to a local RPC node (typically Anvil), and write operations, which are signed locally using a virtual wallet client.

The architecture relies heavily on two primary peer dependencies: viem and wagmi. These libraries provide the foundational types, account management, and connector abstractions required to integrate seamlessly into modern Ethereum development workflows.

Sources: package.json:11-20, README.md:1-25, src/provider.ts:106-118

Primary Framework Dependencies

The project is built to be framework-agnostic but provides native support for the Wagmi ecosystem. The core logic is implemented using viem for low-level Ethereum interactions.

Viem

viem serves as the engine for account management, transaction signing, and JSON-RPC communication. The project utilizes viem's createWalletClient to handle local signing and privateKeyToAccount for managing the virtual test accounts.

Wagmi

wagmi provides the createConnector utility, which allows the virtual provider to be used as a standard wallet connector within DApps. This allows developers to swap real wallets for the e2eConnector during CI/CD or local testing.

Dependency	Version Requirement	Role in Project
viem	^2.43.5 (Peer: >=2.0.0)	Account handling, signing logic, and RPC types.
wagmi	^3.2.0 (Peer: >=2.0.0)	Connector abstraction for DApp integration.
typescript	^5.5.4	Static typing and build compilation.

Sources: package.json:54-61, src/connector.ts:4-8, src/provider.ts:4-8

Internal Logic and Data Flow

The "Man-in-the-Middle" architecture depends on the categorization of RPC methods into Read, Write, and Wallet categories.

Request Routing Architecture

The following diagram illustrates how the provider routes different types of JSON-RPC requests based on the categorized method lists defined in the core constants.

The routing logic relies on specific constant arrays that define the behavior for every supported EIP-1193 method.

• Read Methods: Redirected to internal.rpcUrl using a standard fetch POST request. Examples include eth_call, eth_getBalance, and eth_getBlockByNumber.
• Write Methods: Handled by the internal walletClient. Examples include eth_sendTransaction, personal_sign, and eth_signTypedData_v4.
• Wallet Methods: Managed by the ProviderState to simulate account access and chain switching. Examples include eth_accounts, eth_chainId, and wallet_switchEthereumChain.

Sources: src/constants.ts:68-155, src/provider.ts:333-352, README.md:14-30

Configuration and State Management

The core dependencies are configured through two primary interfaces that define the behavior of the virtual environment.

E2EProviderConfig

This interface defines the parameters for the standalone provider, which defaults to Anvil's first test account and local RPC URL.

Parameter	Type	Default
chains	CompatibleChain[]	[mainnet]
rpcUrls	Record<number, string>	{} (Falls back to 127.0.0.1:8545)
account	Hex | Account	Anvil Account #0
debug	boolean	false

Sources: src/types.ts:25-42, src/constants.ts:7-50

Internal Provider State

The provider maintains an internal state to track the connected environment without requiring external browser extensions.

Development and Build Tooling

The project utilizes a modern TypeScript stack for development and testing.

• Vitest: Used for unit and integration testing of the provider and connector.
• ESLint/Prettier: Ensures code quality and consistent formatting.
• Husky: Manages git hooks for linting and formatting during the development lifecycle.
• PNPM: Specified as the package manager (pnpm@9.7.1).

Sources: package.json:34-52, vitest.config.ts:1-20

Conclusion

The core dependencies of the walletless project provide a robust foundation for simulating a real Ethereum wallet environment. By leveraging viem for cryptographic operations and wagmi for standard DApp connectivity, the library achieves a significant speedup in E2E testing (up to 16x compared to traditional tools like Synpress) by removing the overhead of browser extensions and UI-based wallet interactions.

Sources: README.md:38-48, src/index.ts:1-55