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 Open
.env file with three new private keys for the bundler..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: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
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
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 reusessetup.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 withsudoMint.
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 theSimple7702Account implementation. This requires EntryPoint 0.8. The first UserOperation carries the signed authorization, and Alto submits it in an EIP-7702 transaction.
eip7702.ts
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 withevm_snapshot, revert to it with evm_revert over the Admin RPC, and restart Alto after every revert. The example uses jq.
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:- After
evm_increaseTime, block timestamps run ahead of the machine’s clock (see Working with timestamps on Virtual Environments). - After
evm_revert, block timestamps continue from the snapshot’s timestamp, so they run behind the machine’s clock by the time that passed since the snapshot.
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 ofPAYMASTER_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
getFundedWalletdoes. - Sign validity windows from the later of the two clocks. Compute
validUntilfrom 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 withUserOperation expires too soon. - Give the service the Public RPC URL. Reading the chain and sending signed transactions doesn’t need the Admin RPC.
Troubleshooting
Related
- Admin RPC reference for
eth_sendTransaction,evm_snapshot,evm_revert, andevm_increaseTime - Revert Virtual Environment state with snapshots or the dashboard
- Working with timestamps on Virtual Environments
- Viem on a Virtual Environment: custom chains and custom RPC methods
- Debugging Transactions to step through a bundle transaction