Debugging & Logging
Relevant source files
The following files were used as context for generating this wiki page:
Debugging and logging in the Walletless project are centered around providing visibility into the "Man-in-the-Middle" JSON-RPC request lifecycle. Since the library intercepts EIP-1193 provider calls to separate read operations from write operations, the logging system tracks how requests are routed, signed, and forwarded to Anvil or handled locally.
The primary mechanism for visibility is an internal log function within the provider that outputs structured data to the console when enabled. This system allows developers to inspect the internal state—including the active signing account, current chain, and RPC URL—alongside every incoming and outgoing RPC method.
Sources: src/provider.ts:101-109, README.md:14-25
Logging Architecture
The logging system is integrated directly into the createE2EProvider factory. It is controlled by a debug boolean flag passed during initialization. When active, the provider assigns a unique requestId to every call made via the request method to help correlate asynchronous logs.
The Internal Logger
The log function captures the context of the provider at the moment of the request. It displays:
- Request ID: An incrementing integer for tracking call sequences.
- Internal State: The current account address, chain ID, and the RPC URL being utilized.
- Directional Data: Markers for "incoming" requests and "outgoing" results.
Sources: src/provider.ts:121-140, src/provider.ts:404-406
Logging Data Flow
The following diagram illustrates how the logger intercepts the request flow to provide visibility into the routing logic.
The logger captures state before routing and after processing to ensure the full lifecycle of the RPC call is transparent.
Sources: src/provider.ts:148-154, src/provider.ts:192-194
Configuration and Activation
Logging is disabled by default to prevent console clutter in production-like testing environments. It can be enabled through the E2EProviderConfig or via the e2eConnector parameters in Wagmi.
Configuration Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
debug | boolean | false | When true, enables detailed console logging for all RPC requests. |
Sources: src/types.ts:36, src/connector.ts:25, src/provider.ts:111-115
Implementation Example
// Enabling debug mode in a standalone provider
const provider = createE2EProvider({
debug: true,
chains: [mainnet],
rpcUrls: { 1: "http://localhost:8545" }
});
// Enabling debug mode via Wagmi connector
const connector = e2eConnector({
debug: true,
account: "0x..."
});
Sources: src/provider.ts:101-109, src/connector.ts:86-93
RPC Error Handling and Debugging
Debugging failed transactions or signatures is supported through specialized EIP-1193 error codes and simulation controls. The provider allows for intentional rejections to test DApp error handling.
Error Simulation
Developers can debug their application's error paths by forcing the provider to reject requests. This is useful for testing "User Rejected Request" scenarios (Error Code 4001).
setRejectSignature(boolean): Intercepts signing methods likepersonal_signoreth_signTypedData.setRejectTransaction(boolean): Interceptseth_sendTransaction.
Sources: src/provider.ts:200-215, src/provider.ts:503-509
Standard Error Codes
The project utilizes the ProviderRpcError class to ensure errors conform to EIP-1193, making them easier to debug in standard Web3 tooling.
| Constant | Code | Description |
|---|---|---|
UserRejectedRequest | 4001 | User rejected the transaction or signature. |
Unauthorized | 4100 | The provider is not authorized for the requested method. |
UnsupportedMethod | 4200 | The RPC method is not supported by the provider. |
Disconnected | 4900 | The provider is disconnected from the chain. |
ChainDisconnected | 4901 | The provider is not connected to the specific chain. |
Sources: src/types.ts:143-150, test/provider.spec.ts:1010-1025
Sequence of an Error Log
This sequence shows how an intentional rejection is logged and returned as an EIP-1193 error.
Internal State Inspection
For advanced debugging, the provider exposes an __internal property (accessible in E2EProviderWithInternal). This allows developers to inspect the current state of the virtual wallet without relying solely on console logs.
Inspectable Properties
account: The currentPrivateKeyAccountorAccountobject used for signing.currentChain: The configuration of the active chain.rpcUrl: The endpoint currently receiving forwarded read requests.state: Includesaccounts,chainId, andsupportedChainIds.
Sources: src/provider.ts:522-555, test/provider.spec.ts:140-150
Conclusion
The logging and debugging features of Walletless provide a robust toolkit for E2E testing. By combining structured console output via the debug flag with the ability to simulate standard EIP-1193 errors and inspect internal state, developers can quickly identify issues in the interaction between their DApp, the virtual provider, and the underlying Anvil nodes.
Sources: README.md:14-25, src/provider.ts:121-140