Wagmi Connector Integration

Relevant source files

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

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

The Wagmi Connector Integration provides a specialized EIP-1193 "Virtual Wallet" connector designed specifically for end-to-end (E2E) testing of Web3 decentralized applications (DApps). By implementing the standard Wagmi connector interface, it allows developers to swap real browser extensions or mobile wallets for a deterministic, locally-controlled provider during automated tests.

This integration facilitates a "Man-in-the-Middle" pattern where the DApp interacts with the standard EIP-1193 interface. Internally, the connector routes read-only blockchain operations (like eth_call) directly to a development node like Anvil, while write operations (like eth_sendTransaction) are signed locally using pre-configured private keys. This results in significantly faster test execution—up to 16x faster than traditional browser extension-based tools—while maintaining full chain realism.
Sources: src/connector.ts:87-95, README.md:16-36, README.md:50-57

Architecture and Configuration

The connector is built using Wagmi's createConnector factory. It can be initialized in two primary ways: by passing a pre-constructed E2EProvider instance or by providing configuration parameters that the connector uses to instantiate a provider internally.

Initialization Patterns

1. Internal Creation: The connector creates its own E2EProvider instance when connect() is called. This is the "plug-and-play" method for standard testing scenarios.
2. External Provider: A pre-constructed provider is passed to the connector. This is the recommended approach for advanced E2E testing (e.g., with Playwright), as it allows the test runner to maintain a reference to the provider to trigger state changes like switching accounts or rejecting signatures mid-test.

Configuration Parameters

The e2eConnector accepts E2EConnectorParameters, which are defined by two distinct types:

Parameter	Type	Default	Description
chains	CompatibleChain[]	[mainnet]	Supported chains. The first chain is the default.
rpcUrls	Record<number, string>	{}	Mapping of chain IDs to RPC endpoints. Falls back to http://127.0.0.1:8545.
account	Hex | Account	Anvil Acc #0	Private key or viem Account object for signing transactions.
provider	E2EProvider	undefined	An existing provider instance to use instead of creating one internally.
debug	boolean	false	Enables detailed logging of JSON-RPC requests/responses.

Sources: src/connector.ts:21-50, src/constants.ts:10-23, src/types.ts:24-41

Implementation Details

The connector implements the standard Wagmi Connector interface, mapping EIP-1193 events and methods to the internal E2EProvider.

Connection Lifecycle

When connect() is invoked, the connector ensures an E2EProvider exists. It then retrieves the current account and chain ID from the provider to satisfy the Wagmi connection handshake.

Event Forwarding

To keep Wagmi's state synchronized with the virtual wallet, the connector sets up listeners during the setup() or connect() phase. It forwards internal provider events to the Wagmi emitter.

• accountsChanged: Triggered via setSigningAccount. Emits a change event with checksummed addresses.
• chainChanged: Triggered via setChain or wallet_switchEthereumChain. Emits a change event with the new decimal chain ID.
• disconnect: Forwards the disconnection state to Wagmi.

Sources: src/connector.ts:156-171, src/connector.ts:279-305, src/provider.ts:488-510

Integration Examples

Basic Plug-and-Play

import { e2eConnector } from "@wonderland/walletless";
import { createConfig, http } from "wagmi";
import { mainnet } from "wagmi/chains";

const config = createConfig({
  chains: [mainnet],
  connectors: [e2eConnector()],
  transports: {
    [mainnet.id]: http('http://127.0.0.1:8545'),
  },
});

Sources: src/connector.ts:64-77

Multi-chain with Playwright Control

When testing complex flows like chain switching, the provider is often exposed on the window object to allow page.evaluate() calls to modify the wallet state during the test.

// App Setup
const provider = createE2EProvider({ chains: [mainnet, arbitrum] });
(window as any).__provider = provider;

const config = createConfig({
  connectors: [e2eConnector({ provider })],
  // ...
});

// Playwright Test
await page.evaluate(() => {
  window.__provider.setChain(42161); // Switch virtual wallet to Arbitrum
});

Sources: README.md:120-141, README.md:173-195

Summary

The Wagmi Connector Integration enables a high-performance testing environment by bridging Wagmi's standard interface with a "Walletless" virtual provider. It abstracts the complexities of local transaction signing and RPC routing, providing developers with a deterministic tool for E2E testing that mimics production behavior without the overhead of physical or browser-based wallets.
Sources: README.md:10-15, src/connector.ts:87-95