Account Management

Relevant source files

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

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

Account Management within the walletless project facilitates the simulation of Ethereum accounts and signing logic for E2E testing. It allows developers to programmatically switch between accounts, impersonate specific addresses, and control the success or failure of signing requests without requiring a physical wallet or browser extension.

The system uses a "Man-in-the-Middle" pattern where read operations are forwarded to an RPC provider (like Anvil), while account-specific write operations and signing requests are intercepted and handled locally using viem accounts.
Sources: src/provider.ts:110-117, README.md:16-27

Core Components and Data Structures

Internal State Tracking

The provider maintains an internal state to track the active account and its associated walletClient. This state is mutable via control methods, allowing real-time updates during test execution.

Property	Type	Description
account	PrivateKeyAccount | Account	The current active viem account used for signing.
walletClient	WalletClient	A viem wallet client instance bound to the current account and chain.
rejectSignature	boolean	Flag to simulate user rejection of signature requests (Error 4001).
rejectTransaction	boolean	Flag to simulate user rejection of transaction requests (Error 4001).

Sources: src/provider.ts:77-86, src/types.ts:105-110

Default Test Accounts

The project includes a set of 10 deterministic Anvil test accounts, derived from the standard mnemonic: "test test test test test test test test test test test junk".

export const ANVIL_ACCOUNTS: readonly AnvilAccount[] = [
    {
        address: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
        privateKey: "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
    },
    // ... total of 10 accounts
];

Sources: src/constants.ts:16-65

Account Resolution Logic

The system provides a flexible input mechanism for selecting accounts via the resolveAccount function. It supports four distinct input types to simplify test setup.

Supported Input Types

1. Numeric Index (0-9): Targets one of the 10 default Anvil accounts.
2. Ethereum Address (42 chars): Looks up a matching address within the ANVIL_ACCOUNTS array.
3. Private Key Hex (66 chars): Creates a PrivateKeyAccount from a raw hex string.
4. viem Account Object: Uses a pre-constructed viem account, enabling complex impersonation or custom logic.

Sources: src/provider.ts:33-73, README.md:270-277

Account Resolution Flow

The following diagram illustrates how the resolveAccount function processes different inputs to return a valid account object.

The diagram shows the logic within resolveAccount to transform various inputs into a PrivateKeyAccount or Account.
Sources: src/provider.ts:40-73

Switching Accounts

When the signing account is updated via setSigningAccount, the provider performs a synchronized update of its internal components.

1. Resolve Account: The new account is identified using the resolution logic.
2. Update State: The internal account reference is updated, and the state.accounts array is refreshed.
3. Recreate Wallet Client: A new viem wallet client is instantiated, bound to the new account and the current RPC URL/Chain.
4. Emit Event: An accountsChanged event is emitted to notify the DApp or Wagmi connector of the change.

Sources: src/provider.ts:413-433, test/provider.spec.ts:420-435

Sequence: Account Switching via Page Evaluate

In an E2E testing environment (e.g., Playwright), account switching is typically triggered from the test runner.

The sequence shows how a test runner interacts with the provider to switch accounts and how the provider propagates that change.
Sources: src/provider.ts:419-424, README.md:195-207

Signature and Transaction Control

Account management includes the ability to simulate user interactions, specifically rejecting requests. This is handled through the rejectSignature and rejectTransaction flags.

• setRejectSignature(boolean): When true, any signing method (e.g., personal_sign, eth_signTypedData_v4) will immediately throw a ProviderRpcError with code 4001 (User Rejected Request).
• setRejectTransaction(boolean): When true, eth_sendTransaction requests will throw the same 4001 error.

Sources: src/provider.ts:219-236, src/types.ts:167-175, test/provider.spec.ts:503-518

Conclusion

Account Management in walletless provides a controlled environment for testing wallet-dependent flows. By virtualizing accounts through viem and offering direct APIs for account switching and error simulation, it enables high-performance E2E tests that remain architecturally compatible with standard EIP-1193 providers and Wagmi connectors.
Sources: README.md:10-27, src/connector.ts:133-150