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

Free lesson

Paymasters: when someone else pays the gas

After this lesson: I can work out what a paymaster pays for an operation and when it should refuse.

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

A new user with nothing to pay with

A paymaster is a contract that pays the gas for somebody else's UserOperation. It lets an app sponsor its users, so a new account with no ETH can still act.

It is also money anybody might try to spend, so a paymaster needs rules about whom it pays and how much.

By the end of this lesson

Note

I can work out what a paymaster pays for an operation and when it should refuse.

Key words

WordWhat it means
Paymastera contract that pays gas for other accounts
Sponsorto pay for somebody else's operation
Allow-listthe accounts a paymaster agrees to pay for
Capthe most a paymaster pays for one operation
Griefingmaking somebody waste money with nothing gained

The cells students fill in are left blank in this preview.

How a paymaster pays

A UserOperation can name a paymaster. During validation the EntryPoint asks the paymaster whether it will pay. It then takes the most the operation could cost from the paymaster's deposit, not the account's.

After execution the EntryPoint charges what was used and gives the rest back to the paymaster. The account itself pays nothing.

Sponsor an account that holds no ETH

Command
docker exec chain ./steps/paymaster.sh

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

Worked example: what the lab printed

WhatBeforeAfter
Nia's smart account0 ETH, 0 depositedstill 0 ETH, count 1
The paymaster's deposit1 ETH0.999901392 ETH
The operationsponsoredgas 98608, cost 0.000098608 ETH

The cells students fill in are left blank in this preview.

A paymaster says no on purpose

The lab's paymaster pays only for accounts on its allow-list, and never more than 0.001 ETH for one operation. Alex is not on the list, so it refused with AA34.

Nia then asked for ten times the gas. The most it could cost passed the cap, so the paymaster refused that too. The bundler saw both refusals in its simulation and sent nothing.

Read the paymaster's two refusals

Command
docker exec chain grep -n "return 1" src/Paymaster.sol

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

What can go wrong with a paymaster

Draining: anybody can send operations naming a generous paymaster, so it pays for strangers unless it checks who is asking.

Griefing: an operation can pass validation and then fail in execution. The paymaster still pays for the gas used.

Running dry: when the deposit is too low, every sponsored operation fails with AA31 until somebody tops it up.

A common mistake

Warning

Many people think a sponsored operation is free. Somebody still pays the gas: the paymaster, from its deposit. Every rule it skips is money a stranger can make it spend.

Try it: what one sponsored operation costs

Code: python
GWEI = 10 ** 9
deposit = 10 ** 18          # 1 ETH, in wei
gas_used = 98608            # what the lab printed
price = 1 * GWEI

cost = gas_used * price
print("one operation:", cost, "wei")
print("deposit after one:", deposit - cost, "wei")
print("operations the deposit covers:", deposit // cost)
# Change price to 20 * GWEI. How many operations now?

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.