Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

How ERC-4337 works: UserOperations and bundlers

After this lesson: I can follow one UserOperation from signing to the EntryPoint's event.

70 min lesson3 commandsAccount abstraction lab: smart accounts, ERC-4337, paymasters and EIP-7702 on a local chain

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

WordWhat it means
UserOperationa signed request for what a smart account should do
Bundlera server that sends UserOperations to the chain
EntryPointthe one contract that checks and runs UserOperations
Validationthe phase where the account says yes or no
Executionthe phase where the account makes its call
DepositETH 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

  1. The user signs a UserOperation for their smart account.
  2. A bundler collects UserOperations and sends them to the EntryPoint in one ordinary transaction, calling handleOps.
  3. The EntryPoint asks each account to validate its operation.
  4. 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

Command
docker exec chain ./steps/userop.sh

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: what the lab printed

StepWhat the lab printed
Count before0
Nonce in the EntryPoint0
Hash Alex signed0x8806a321... (64 hex digits)
handleOps transactiongas used 133003
UserOperationEventsuccess true, gas 114672, cost 0.000114672 ETH
Count after1

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

Command
docker exec chain ./steps/refused.sh

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Three tries, three answers

TryWhat the bundler printed
Signed by Mallory, not Alexsimulation failed, not sent: AA24 signature error
Signed by Alexsent handleOps, success true
The same operation againsimulation 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

Code: python
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

Command
docker exec chain grep -n "AA[0-9]" src/EntryPoint.sol

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

About this lab and its source: Account abstraction lab: smart accounts, ERC-4337, paymasters and EIP-7702 on a local chain

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.