Start
How it works
The life of one egg, step by step.
1. Put ETH in escrow
deposit() credits your address inside the contract. Eggs spend from this escrow, and what is left is yours: withdraw(amount) works at any time.
2. Sign an egg
An egg names the call (target, value, data), the window (notBefore, notAfter, in the chain's own block numbers), the most a keeper may earn (maxReward) and a random nonce. You sign it with EIP-712. Nothing is sent to the chain, and nothing is spent.
3. A keeper carries it
A keeper watches the head of the chain. When the next block falls inside your window it calls hatch(egg, signature). The contract checks, in this order:
| # | Check | Refuses with |
|---|---|---|
| 1 | The window is well formed | BadWindow |
| 2 | The clock reads at least notBefore | TooEarly(current, notBefore) |
| 3 | The clock reads at most notAfter | TooLate(current, notAfter) |
| 4 | The nonce was not used or cancelled | Used |
| 5 | The signature is the owner's, over exactly this egg | BadSignature |
| 6 | The escrow covers value + reward | Insufficient(have, need) |
| 7 | The call succeeds | CallFailed(reason) |
A refused egg changes nothing: the owner loses nothing, the egg stays alive for a better attempt, and the keeper pays only its own gas.
4. The reward falls with lateness
Landing on notBefore pays the whole maxReward. Each block later pays one more slice less, down to one slice on notAfter. See Rewards.
5. Keepers race
If several keepers carry the same egg, the first one included wins and the others revert (Used). Because the reward is highest at the start of the window, every keeper wants to be first and early, and none of that is your problem.