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

Free lesson

Session keys and spending limits

After this lesson: I can check whether a session key may make a payment under its limits.

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

Letting a game spend a little, not everything

A session key is a second, weaker key that a smart account accepts for a short time and a narrow job. A game can pay for small things without asking you to sign each time, and without ever holding your main key.

If the session key leaks, the damage stops at its limit.

By the end of this lesson

Note

I can check whether a session key may make a payment under its limits.

Key words

WordWhat it meansExample
Session keya limited key a smart account accepts for a while
Targetthe address a session key may pay or call
Spending limitthe most a session key may spend in all
Expirythe time after which a session key stops workingvalid until
Revoketo take a key's permission away

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

A session key is a key with rules

The owner adds a session key to the account with its rules: which address it may pay, how much in all, and until when. The account stores the rules and the amount spent so far.

When a UserOperation is signed by a session key rather than the owner, validateUserOp checks those rules. If any rule fails, validation fails and nothing runs.

Pay a shop with a session key

Command
docker exec chain ./steps/session.sh

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

Worked example: what the lab printed

TrySigned byResult
Payment 1, 0.004 ETH to the shopApp's session keysent, success true
Payment 2, 0.004 ETH to the shopApp's session keysent, success true
Payment 3, 0.004 ETH to the shopApp's session keyAA24, limit of 0.01 ETH passed
0.001 ETH to MalloryApp's session keyAA24, wrong target
0.004 ETH to the shopA key that ended in 1970AA24, expired

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

The checks, one by one

Read checkSession in the lab. It refuses when the time is past validUntil or the call is not execute. It also refuses when the target is not the one allowed, or when spent plus this payment passes the limit.

Only when every check passes does it add the payment to spent and answer 0, which means yes.

Read the session key check

Command
docker exec chain sed -n 45,53p src/SmartAccount.sol

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

Try it: a running total against a limit

Code: python
limit = 10            # in thousandths of an ETH
spent = 0
payments = [4, 4, 4, 1]

for amount in payments:
    if spent + amount > limit:
        print(amount, "refused, spent stays at", spent)
    else:
        spent = spent + amount
        print(amount, "allowed, spent now", spent)
# Add a payment of 2 at the end. Is it allowed?

A common mistake

Warning

Many people check each payment against the limit on its own. Three payments of 0.004 ETH each look fine against 0.01 ETH. The limit is on the total, so the account must remember what was spent.

Choosing safe session rules

Give each session key the narrowest rules that do the job: one target, a small limit, a short expiry. A cap on each single payment adds a second line of defence.

Let the owner revoke a key at any time. Real accounts use modules for this, such as ERC-7579 permission modules, with the same idea as the lab's simple version.

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.