Docs/How it works

A stamp replaces the funding transaction.

Two postages#

Both postages go through the same relay, the same epochs and the same policy checks. They differ in who pays and what rations them.

A prepaid stamp is e-cash for gas: bought from any wallet, it carries no trace of that wallet when it is used. Prepaid stamps covers its whole life; this page covers what the two postages share and the proof of work.

The flow#

1. Epoch. The SDK polls the relay's pow_getEpoch every 60 s in the background. An epoch (15 minutes) fixes the fee caps, gas caps, the difficulty and a random seed revealed only when the epoch starts, and whether prepaid stamps are accepted (the STAMPS flag).
2. Build. The op's gas limits come from fixed per-template profiles, its fees from the epoch, its pre-verification gas from the relay's quote. The EntryPoint nonce key is always 0. A first op carries an EIP-7702 authorization for Simple7702Account v0.9.
3. Hash. userOpHash is the EntryPoint v0.9 EIP-712 hash, which covers the 7702 delegation.
4. Attach the stamp. With a prepaid stamp, the op carries the stamp's nullifier, and the account signs at once. With a mined stamp, the proof lives in the unsigned paymasterSignature suffix, so the account signs while the miner searches for 8 nonces.
5. Relay. The relay recomputes the hash, verifies the stamp (its signature, and that it was never spent) or the proof, and every on-chain rule, reserves the op's maximum cost against the deposit, co-signs and forwards the op to its own bundler (or holds it for the delay you asked for).
6. Bundle. The bundler sends a type-4 transaction that applies the delegation and calls handleOps. The fresh address holds 0 ETH before and after.
7. Validate and account. validatePaymasterUserOp checks the co-signature, the policy and, for a mined stamp, the proof, against the epoch's write-once parameters. postOp records the cost: StampCancelled (the nullifier recorded, the cost taken from the stamp float) or OpSponsored (the epoch's spend).

paymasterAndData#

The version byte of the signed paymasterData selects the postage. Everything the relay adds sits in the EntryPoint v0.9 paymasterSignature suffix, which userOpHash excludes: the signed part only carries the version and the epoch id.

In viem terms: paymasterData = version ‖ epochId (5 bytes), and paymasterSignature = nullifier ‖ cosig (97 bytes) for a prepaid stamp or nonces ‖ cosig (129 bytes) for a mined one. viem appends the length and the magic itself. Before the relay co-signs, the SDK fills the co-signature with a 65-byte stub (and, mining, the nonces with 64 zero bytes), so the hashed length is already final.

The challenge (mined stamp)#

challenge = keccak256(abi.encode(
    CHALLENGE_TAG,        // keccak256("StampPaymaster/v1/challenge")
    block.chainid,
    address(entryPoint),
    address(this),        // the paymaster
    epochId,              // uint32
    seed,                 // uint96, revealed when the epoch starts
    userOpHash            // EntryPoint v0.9 EIP-712 hash
))
h_i = keccak256(abi.encode(challenge, uint256(nonce_i)))   // one 64-byte keccak block
accept_i  ⇔  uint256(h_i) ≤ targetPerSolution

• Bound to one op. The chain id, EntryPoint and paymaster are in the challenge, and the EntryPoint nonce inside userOpHash makes each proof usable once.
• No stockpiling. The seed is unknown until the epoch starts, ops expire 5 minutes after the next roll, and the relay refuses an old epoch's ops 2 minutes after a roll.
• 8 independent solutions. The 8 nonces must be strictly increasing and each must hash under the target.

How much work (mined stamp)#

gasSum      = verificationGasLimit + callGasLimit + paymasterVerificationGasLimit
              + paymasterPostOpGasLimit + preVerificationGas
work        = max(minWork, gasSum × refFeePerGas × workPerGwei / 1e9)   // expected total hashes
perSolution = ceil(work / 8)
target      = (2^256 − 1) / perSolution

• Priced like the gas the paymaster pays. refFeePerGas is the base fee snapshotted at the roll, so work follows fee levels, and fee headroom in maxFeePerGas costs no extra work.
• Tight limits pay off. Every client of a template uses the same published gas profile, so the work is the same for everyone.
• K = 8. With 8 sub-solutions the 95th-percentile solve time is about 1.64 × the mean (3 × with one solution), and progress can be shown honestly as x/8.
• Bounded. work ≤ 2^48 for every epoch, far inside the 64-bit nonce space.

A first op on mainnet (a token transfer with its delegation, gasSum ≈ 390,000 with the L1 data part of PVG) at the 5,000 floor and a 0.022 gwei base fee costs about 2^25.4 hashes: around 3.6 s on a mid laptop (12 MH/s) and 11 s on a mid Android phone (3.75 MH/s). At the 30,000 ceiling (6×), about 21 s and 69 s; the p95 is 1.64 × these means, about 113 s on the phone.

Validation#

Validation reads only the op's epoch (4 storage slots, written once) and, with the delegate check, the sender's 23-byte delegation designator, on both paths. It never reads a nullifier: the relay refuses a spent stamp, and the chain records every one, so a double spend is public instead of possible. It reverts only on malformed data, an unknown epoch, or a prepaid stamp in an epoch without the STAMPS flag. Every other failure is soft: all checks of the op's path run, at constant gas, and the result is SIG_VALIDATION_FAILED. The same checks are exposed as checkUserOp(), which returns the failure bits:

Ops are limited to single calls from an allowlist of templates, enforced by the relay before it co-signs, for both postages:

Epochs, difficulty and budget#

• Write-once epochs. A roll() (any EOA, once the epoch is over) creates the next epoch. Nothing validation reads ever changes afterwards, so a simulated op can't be invalidated by paymaster state, and the bundler never has a reason to ban it.
• Two lanes in one deposit. The EntryPoint deposit holds the stamp float (what sold stamps prepaid and have not spent yet) and the free lane's share. roll() tops up only deposit − float, and the free lane's budget never counts the float: free stamps can never spend what buyers paid for.
• Step controller. At each roll, utilization u of the free lane's budget sets the next difficulty: ×2 after two saturated epochs, ×1.25 above the 60% target, ×0.5 below half of it, ×1 otherwise, clamped to the configured range (6× on mainnet).
• Budget = deposit share. The free lane is topped up to its epoch budget at most once per epoch, by a direct EOA roll, and an immutable MAX_DAILY_SPEND bounds the daily outflow. The relay paces co-signing of mined stamps across the epoch; prepaid stamps are admitted against the deposit's headroom only.