Skip to main content
To test ERC-4337 smart accounts on a Virtual Environment, run Alto, Pimlico’s open-source bundler, and Pimlico’s mock paymaster in Docker, and point both at the Virtual Environment’s RPC URLs. The EntryPoint contracts and account factories deployed on the parent network are part of the forked state, and each bundle is a transaction you can open in the Virtual Environment Explorer. This guide sends UserOperations in four ways: sponsored by a paymaster, paid by the account, paid in an ERC-20 token, and from an EIP-7702 account. It was tested with Alto 1.2.8, permissionless 0.5.0, and viem 2.57.7 on Virtual Environments forked from Ethereum Mainnet, Base, OP Mainnet, and Arbitrum One, with EntryPoint 0.6, 0.7, and 0.8.

Which RPC URL does each service use?

A Virtual Environment has a Public RPC URL and an Admin RPC URL. Alto runs on the Public RPC. The funding job, the mock paymaster, and test code that funds accounts use the Admin RPC.

Before you begin

  • A Virtual Environment forked from a network where the ERC-4337 EntryPoint contracts are deployed, such as Ethereum Mainnet, Base, OP Mainnet, or Arbitrum One. It can keep the parent network’s chain ID or use a custom one. To create one, follow the Virtual Environment quickstart.
  • The Virtual Environment’s Public RPC and Admin RPC URLs, listed in the Integrate Virtual RPC card on the Home tab (see the dashboard reference)
  • Docker with Docker Compose
  • Node.js 20.6 or later and npm
  • jq, for the snapshot example

Run Alto and the mock paymaster

1

Create the project and its .env file

The command creates a project folder and a .env file with three new private keys for the bundler.
Open .env, replace the two placeholder URLs with the Virtual Environment’s Public RPC and Admin RPC URLs, and set ALTO_CHAIN_TYPE for the parent network:
Generate new keys. Don’t use well-known test keys such as the Anvil or Hardhat defaults. On forks of live networks, those addresses are delegated through EIP-7702 to a contract that forwards any ETH they receive, so they never hold a balance.
2

Add the funding script

Alto needs ETH on its keys before it starts. The utility key deploys Alto’s simulation contracts on the first start, and the executor keys pay for bundle transactions.A Virtual Environment starts with pre-funded accounts, which eth_accounts returns. The Admin RPC accepts unsigned eth_sendTransaction requests, so the script funds each key with a transfer from one of those accounts.Save the script as fund-accounts.mjs:
fund-accounts.mjs
3

Add the Compose file

Save the file as docker-compose.yml:
docker-compose.yml
The mock paymaster is for testing only. It sponsors every request and signs with a publicly known key.
4

Start the stack

The funder runs first, then Alto, then the mock paymaster. The stack is usually ready in under 30 seconds.
5

Check the bundler and the paymaster

Ask the bundler for its EntryPoints:
Then ping the paymaster:

Mock paymaster contract addresses

On its first start on a Virtual Environment, the mock paymaster deploys the contracts below. The addresses are the same on every network. Each paymaster gets a 50 ETH deposit in its EntryPoint.

Send a sponsored UserOperation

1

Install viem and permissionless

Run the commands in the project folder to install viem and permissionless:
2

Create setup.ts

setup.ts holds the clients and constants that all scripts on this page share.
setup.ts
3

Create sponsored.ts

The script creates a smart account that holds no ETH and sends a UserOperation that the mock paymaster pays for.
sponsored.ts
4

Run the script

The account was deployed and made its call in one UserOperation, and it still holds no ETH. To see the full trace of the bundle, search for the transaction hash in the Virtual Environment Explorer.
To use another EntryPoint version, change the entryPoint constant, for example to { address: entryPoint08Address, version: "0.8" }. Alto is configured for EntryPoint 0.6, 0.7, and 0.8, and the mock paymaster deploys a paymaster for each.
Keep the three endpoints apart. Alto answers only bundler methods: if you send it a read such as eth_call, viem reports The method "eth_call" does not exist / is not available. Paymaster methods such as pm_getPaymasterStubData go to the paymaster URL.

Other ways to pay for gas

Each script below is complete and reuses setup.ts. Run it the same way as sponsored.ts, for example npx tsx --env-file=.env erc20.ts.

Pay gas from the account’s balance

Without a paymaster, the account needs ETH before its first UserOperation. getFundedWallet sends it from a pre-funded account through the Admin RPC.
self-funded.ts

Pay gas in an ERC-20 token

The mock paymaster accepts its own test token as payment for gas. Anyone can mint the token with sudoMint.
erc20.ts
The script mints 1 wei of the token to the paymaster’s treasury before the first payment. Without it, the first ERC-20 UserOperation on a new Virtual Environment fails with AA50 postOp reverted. Alto measures the paymaster’s postOp gas with fees of 1 wei, where the token fee rounds to zero. With real fees, the first transfer into an empty treasury needs about 22,600 more gas than Alto measured, and postOp runs out of gas.

Send a UserOperation from an EIP-7702 account

An externally owned account (EOA) can act as a smart account by delegating to the Simple7702Account implementation. This requires EntryPoint 0.8. The first UserOperation carries the signed authorization, and Alto submits it in an EIP-7702 transaction.
eip7702.ts
After the first UserOperation, the EOA’s code is 0xef0100 followed by the implementation address. Later UserOperations from the same account don’t need the authorization field.

Reset state between test runs

To return the Virtual Environment to a known state between test runs, take a snapshot with evm_snapshot, revert to it with evm_revert over the Admin RPC, and restart Alto after every revert. The example uses jq.
You can revert to the same snapshot as many times as you need. For the dashboard flow and the revert distance limit, see Revert Virtual Environment state.
Restart Alto after every evm_revert. Alto keeps submitted bundles, pending account deployments, and recent receipts in memory, and after a revert that state describes blocks that no longer exist. Without a restart, UserOperations can fail with AA10 ... Another deployment operation for this sender is already being processed, never confirm, or return receipts for UserOperations that were reverted. Clearing Alto’s mempool with debug_bundler_clearState doesn’t replace the restart.

Time travel and paymaster validity windows

Paymaster signatures usually carry a validity window, and two clocks check it: the EntryPoint compares it with the block timestamp, and Alto compares it with the clock of the machine it runs on. On a Virtual Environment, the two can differ: The mock paymaster signs each sponsorship for 60,000 seconds from the machine’s clock. If you move time forward by more than that, its sponsorships are already expired on chain: the UserOperation never confirms, and Alto keeps resubmitting the failing bundle until you restart it. For tests that jump further ahead, send UserOperations without a paymaster, or use your own paymaster service.

Use your own paymaster service

To test your own sponsorship rules, run your paymaster service against the same Virtual Environment and pass its URL to the paymaster client in place of PAYMASTER_URL. Any service that implements ERC-7677 (pm_getPaymasterStubData and pm_getPaymasterData) works with the scripts on this page. Three things are specific to a Virtual Environment:
  • Fund the paymaster through the Admin RPC. The paymaster contract needs an EntryPoint deposit, and the account that deploys it needs ETH. Send both from a pre-funded account, as getFundedWallet does.
  • Sign validity windows from the later of the two clocks. Compute validUntil from the later of the latest block timestamp and the service’s own clock. A signature based on the block timestamp alone fails when the Virtual Environment’s clock is behind: Alto rejects the UserOperation with UserOperation expires too soon.
  • Give the service the Public RPC URL. Reading the chain and sending signed transactions doesn’t need the Admin RPC.

Troubleshooting