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
| Word | What it means | Example |
|---|---|---|
| Session key | a limited key a smart account accepts for a while | |
| Target | the address a session key may pay or call | |
| Spending limit | the most a session key may spend in all | |
| Expiry | the time after which a session key stops working | valid until |
| Revoke | to 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
docker exec chain ./steps/session.shShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: what the lab printed
| Try | Signed by | Result |
|---|---|---|
| Payment 1, 0.004 ETH to the shop | App's session key | sent, success true |
| Payment 2, 0.004 ETH to the shop | App's session key | sent, success true |
| Payment 3, 0.004 ETH to the shop | App's session key | AA24, limit of 0.01 ETH passed |
| 0.001 ETH to Mallory | App's session key | AA24, wrong target |
| 0.004 ETH to the shop | A key that ended in 1970 | AA24, 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
docker exec chain sed -n 45,53p src/SmartAccount.solShown here, not run. Press Start lab to type it into your own lab’s terminal.
Try it: a running total against a limit
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.