Reference

JS engine

The same rules in plain JavaScript, and the race model.

src/engine/cuckoo-engine.mjs has no dependency. The lab on the site runs on it, and scripts/differential.mjs proves it agrees with the real contract.

The nest

import { Nest, egg, rewardAt } from './cuckoo-engine.mjs';

const nest = new Nest();
nest.deposit(owner, 3n * 10n ** 18n);
nest.programs[curve] = (n, e) => { /* a pretend contract */ };

const e = egg({ owner, target: curve, value: 5n * 10n ** 17n, notBefore: 100, notAfter: 102, maxReward: 4n * 10n ** 17n, nonce: 1 });
nest.hatch(e, { keeper, block: 100 });     // { ok: true, reward: 400000000000000000n }
nest.hatch(e, { keeper, block: 101 });     // { ok: false, error: Used }

A failed hatch changes nothing, like a reverted transaction. The signature check is the caller's (validSignature), since the contract does it and the differential test covers it.

The race model

landOffset({ blockMs: 100, jitterMs: 170, biasMs: 0 }, rng(7))   // -1, 0, +2 ...
histogram(profile, 2000)                                          // { "-1": 310, "0": 680, ... }
race({ keepers, window: { notBefore: 0, notAfter: 2 }, maxReward: 100n })

Encoding

src/engine/cuckoo-abi.mjs (ethers v6): signEgg, eggDigest, encodeHatch, decodeError.

The keeper

src/keeper/keeper.mjs exports due(eggs, head, { lead, sent }) (a pure function, tested without a network) and the Keeper class that wraps it with a provider.