TypeScript Definitions

Relevant source files

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

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

The TypeScript definitions in the @wonderland/walletless project establish the structural foundation for a "Man-in-the-Middle" EIP-1193 provider designed for E2E testing. These definitions ensure type safety across the core provider logic, the Wagmi connector integration, and the internal state management required to simulate wallet interactions without a browser extension.

The type system is primarily built upon viem primitives, extending them to support virtualized signing, multi-chain RPC routing, and test-control mechanisms such as manual signature rejection and account switching.

Sources: src/types.ts, src/provider.ts:102-111, README.md

Core Provider Types

The provider implements an EIP-1193 compatible interface, allowing it to be used as a drop-in replacement for standard injected wallets.

E2EProvider Interface

The E2EProvider is the primary interface for interacting with the virtual wallet. It defines the standard request method and event emitter functionality.

Property	Type	Description
request	E2ERequestFn	Standard EIP-1193 request function for JSON-RPC methods.
on	Function	Subscribes to provider events like accountsChanged or chainChanged.
removeListener	Function	Unsubscribes from specific provider events.
emit	Function	Manually triggers provider events (used internally).

Sources: src/types.ts:79-88

Provider Internal State

To support testing features, the provider maintains an internal state that tracks connectivity and supported chains.

JSON-RPC and Method Routing

The project categorizes RPC methods to determine whether they should be forwarded to an external RPC node (Anvil) or handled locally.

Method Categories

Category	Description	Key Methods
Read Methods	Forwarded to Anvil RPC	eth_call, eth_getBalance, eth_blockNumber
Wallet Methods	Handled via internal state	eth_accounts, eth_requestAccounts, wallet_switchEthereumChain
Write Methods	Locally signed then sent to RPC	eth_sendTransaction, personal_sign, eth_signTypedData_v4

Sources: src/constants.ts:76-159, src/provider.ts:114-118

Request Structure

Standard JSON-RPC request and response objects are defined to maintain compatibility with the Ethereum wire protocol.

Configuration and Initialization

Initialization types allow for flexible setup of the provider, supporting either automated Anvil defaults or complex multi-chain configurations.

E2EProviderConfig

This type defines the options available when calling createE2EProvider.

• chains: A list of CompatibleChain objects. The first chain in the list becomes the default.
• rpcUrls: A mapping of chainId to RPC endpoints (e.g., { 1: 'http://localhost:8545' }).
• account: A hex string (private key) or a viem Account object.
• debug: Boolean to enable verbose logging of RPC traffic.

Sources: src/types.ts:21-40, src/provider.ts:130-135

SigningAccountInput

The project supports multiple formats for defining a signing account, which are resolved at runtime.

export type SigningAccountInput = number | Address | Hex | Account;

• number: Index (0-9) into the default Anvil accounts array.
• Address: 42-character Ethereum address (must be a default Anvil address for lookup).
• Hex: 66-character raw private key.
• Account: A pre-constructed viem Account object.

Sources: src/provider.ts:29-34, src/provider.ts:46-78

Wagmi Connector Integration

The e2eConnector leverages the TypeScript definitions to provide a seamless experience within the Wagmi ecosystem.

Connector Parameters

The E2EConnectorParameters type is a union that allows providing configuration options OR an existing provider instance.

Transaction and Data Signing

Specific types define the structures for signing operations, ensuring compliance with EIP-712 and standard transaction formats.

TransactionRequest

Used for eth_sendTransaction, this type maps hex strings from the RPC request to values that viem can process.
Sources: src/types.ts:103-113

TypedData and Domain

Definitions for EIP-712 structured data signing.
Sources: src/types.ts:118-135

Error Handling

The project implements custom error classes to simulate standard EIP-1193 provider errors, specifically for rejecting requests in a test environment.

ProviderRpcError

A specialized error class that includes an EIP-1193 error code.

Constant	Code	Description
UserRejectedRequest	4001	Triggered when setRejectSignature or setRejectTransaction is true.
Unauthorized	4100	The provider is not authorized for the requested operation.
UnsupportedMethod	4200	The requested JSON-RPC method is not implemented.
Disconnected	4900	The provider has been disconnected.

Sources: src/types.ts:145-168, src/provider.ts:241-255

Summary

The TypeScript definitions in @wonderland/walletless serve as the bridge between the high-level EIP-1193 interface and the internal virtualization logic. By extending viem types and providing a robust set of configuration and state interfaces, the library allows developers to maintain strict type safety while simulating complex wallet behaviors like chain switching, account impersonation, and manual request rejection in E2E testing environments.