A transaction your account checks for itself
ERC-4337 is the standard that gives Ethereum smart accounts without changing the chain's own rules. Instead of a transaction, you sign a UserOperation, and a bundler carries it to a contract called the EntryPoint.
Most new smart accounts work this way, so knowing the flow lets you read any of them.
By the end of this lesson
Note
I can follow one UserOperation from signing to the EntryPoint's event.
Key words
| Word | What it means |
|---|---|
| UserOperation | a signed request for what a smart account should do |
| Bundler | a server that sends UserOperations to the chain |
| EntryPoint | the one contract that checks and runs UserOperations |
| Validation | the phase where the account says yes or no |
| Execution | the phase where the account makes its call |
| Deposit | ETH held by the EntryPoint to pay for gas |
The cells students fill in are left blank in this preview.
Who does what in ERC-4337
- The user signs a UserOperation for their smart account.
- A bundler collects UserOperations and sends them to the EntryPoint in one ordinary transaction, calling handleOps.
- The EntryPoint asks each account to validate its operation.
- It then executes every operation and pays the bundler back from the account's deposit.
The bundler pays the transaction's gas first, so it wants paying back.
What a UserOperation holds
A UserOperation names the sender, its smart account. It holds a nonce, the callData to run and three gas limits. It also holds the most it will pay per unit of gas, an optional paymaster and a signature.
The account signs a hash of every field except the signature. The hash also covers the EntryPoint's address and the chain id, so it cannot be replayed elsewhere.
Send one UserOperation through the bundler
docker exec chain ./steps/userop.shShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: what the lab printed
| Step | What the lab printed |
|---|---|
| Count before | 0 |
| Nonce in the EntryPoint | 0 |
| Hash Alex signed | 0x8806a321... (64 hex digits) |
| handleOps transaction | gas used 133003 |
| UserOperationEvent | success true, gas 114672, cost 0.000114672 ETH |
| Count after | 1 |
The cells students fill in are left blank in this preview.
Validation first, then execution
The EntryPoint validates every operation in a bundle before it executes any of them. Validation checks the nonce, asks the account to check the signature and takes the most the operation could cost.
If one operation fails validation, the whole bundle reverts and the bundler pays for nothing useful. So a bundler simulates the bundle first and drops any operation that would fail.
See what validation refuses
docker exec chain ./steps/refused.shShown here, not run. Press Start lab to type it into your own lab’s terminal.
Three tries, three answers
| Try | What the bundler printed |
|---|---|
| Signed by Mallory, not Alex | simulation failed, not sent: AA24 signature error |
| Signed by Alex | sent handleOps, success true |
| The same operation again | simulation failed, not sent: AA25 invalid account nonce |
The cells students fill in are left blank in this preview.
A common mistake
Warning
Many people think a bundler can change what the user asked for. It cannot. The signature covers every field, so any change makes validation fail with AA24, and the account never acts.
Paying the bundler back
Before execution the EntryPoint takes the most the operation could cost: every gas limit added up, times the highest fee. After execution it charges what was really used and leaves the rest in the account's deposit.
preVerificationGas pays the bundler for work the EntryPoint cannot measure. Set too low, the bundler loses: in the lab it ended 0.000018331 ETH down.
Try it: the most it could cost
GWEI = 10 ** 9
call_gas = 100000
verify_gas = 100000
pre_gas = 21000
max_fee = 1 * GWEI
most = (call_gas + verify_gas + pre_gas) * max_fee
used = 114672 * GWEI
print("taken first:", most, "wei")
print("really used:", used, "wei")
print("left in the deposit:", most - used, "wei")
# Change call_gas to 50000. What is taken first now?
The lab's EntryPoint is a teaching model
The real EntryPoint, version 0.7 or 0.8, packs its gas fields, allows several nonce sequences and can call a paymaster again after execution. Its validation rules, ERC-7562, stop an operation that passes a simulation and fails on chain.
The lab keeps the shape and leaves those out. Its bundler is a shell function that simulates, then sends. Read its error codes.
List the EntryPoint's error codes
docker exec chain grep -n "AA[0-9]" src/EntryPoint.solShown here, not run. Press Start lab to type it into your own lab’s terminal.