EIP-1193 Compliance

Relevant source files

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

• src/provider.ts
• src/types.ts
• src/constants.ts
• src/connector.ts
• README.md
• test/provider.spec.ts

Introduction

EIP-1193 Compliance in the Walletless project refers to the implementation of a "man-in-the-middle" virtual Ethereum provider that adheres to the Ethereum Provider JavaScript API standard. This allows DApps to interact with the provider using standard methods while the library redirects read operations to an RPC node (like Anvil) and handles write operations through local signing.

Sources: README.md:9-14, src/types.ts:98-103

The architecture ensures that high-performance E2E testing can be achieved by removing browser extension overhead and providing deterministic control over wallet interactions, such as signature rejections or account switching, all through an interface compatible with common libraries like Wagmi and Viem.

Sources: README.md:21-27, package.json:2-15

Core Architecture and Data Flow

The provider implements the EIP-1193 request method as the primary entry point for all JSON-RPC interactions. It categorizes incoming requests into three logical flows: Read, Write, and Wallet methods.

Request Routing Logic

The routing is determined by identifying the nature of the RPC method:

• Read Methods: Routed directly to the configured Anvil RPC URL via standard fetch POST requests.
• Write/Signing Methods: Handled locally using an internal walletClient and a private key or Account object.
• Wallet Methods: Managed by the provider's internal state machine to track current accounts, chain IDs, and connection status.

Implementation Details

The E2EProvider Interface

The project defines the E2EProvider type to match EIP-1193 requirements, including the request function and event emitter capabilities (on, removeListener, emit).

Sources: src/types.ts:91-104

Component	Description	Source
request	The main EIP-1193 function for sending JSON-RPC requests.	src/types.ts:91-95
InternalState	Tracks the active account, walletClient, currentChain, and RPC endpoints.	src/provider.ts:80-89
walletClient	A Viem-based client used to sign transactions and messages locally.	src/provider.ts:145-149

Event Handling

Compliance requires the emission of specific events to notify the DApp of state changes. The provider implements:

• accountsChanged: Triggered when setSigningAccount is called.
• chainChanged: Triggered on wallet_switchEthereumChain or setChain.
• connect: Triggered upon the first successful eth_requestAccounts call.
• disconnect: Triggered when the provider is manually disconnected.

Sources: src/types.ts:74-82, src/provider.ts:200-207

Method Categorization

The system maintains strict lists of methods to determine how to process each request.

Method Types Summary

Category	Example Methods	Handling Logic
Read	eth_call, eth_getBalance, eth_blockNumber	Forwarded to rpcUrl.
Write	eth_sendTransaction, personal_sign, eth_signTypedData_v4	Signed by local account.
Wallet	eth_accounts, eth_chainId, wallet_switchEthereumChain	Returns internal state.

Sources: src/constants.ts:89-150

Transaction and Signature Handling

When a write method like eth_sendTransaction is called, the provider uses its internal walletClient to sign the payload before sending it to the network. This process supports EIP-712 typed data and standard personal message signing.

EIP-1193 Error Codes

The provider implements standard error codes to simulate realistic wallet behavior, particularly for testing failure modes in DApps.

Error Name	Code	Meaning
UserRejectedRequest	4001	The user rejected the transaction or signature.
Unauthorized	4100	The provider is not authorized for the requested method.
UnsupportedMethod	4200	The method is not supported by the provider.
Disconnected	4900	The provider is disconnected from all chains.
ChainDisconnected	4901	The provider is disconnected from the specific chain.

Sources: src/types.ts:162-172

Integration with Wagmi (e2eConnector)

The e2eConnector acts as a bridge between the virtual EIP-1193 provider and the Wagmi library. It ensures that events emitted by the provider (like accountsChanged) are correctly forwarded to Wagmi's internal emitter to trigger UI updates.

Conclusion

EIP-1193 Compliance in Walletless enables a high-fidelity simulation of Ethereum wallets within automated testing environments. By adhering to the standard, it allows developers to swap real wallets for a virtualized, programmable instance that provides fine-grained control over blockchain interactions without requiring modifications to the DApp's core logic.

Sources: README.md:1-6, src/provider.ts:108-117