Docs

A dev picks a nest: a pad coin that migrated. The nest sets the price. If it says yes, the new coin hatches inside it: the dev's bid buys the new coin for the nest's holders, and the nest keeps a share of the new coin's fees forever.

The words

word	what it is on chain
Nest	A pad coin that migrated to PumpSwap. Its dev can open it (`open_nest`): dev price or holder vote, a price (the minimum bid, at least 0.1 SOL) and a share (5 to 30 % of every chick's creator fees). A migrated coin nobody opened is a holder-vote nest with the pad defaults (0.1 SOL, 20 %).
Egg	A dev's offer to a nest: the final name, ticker and picture of the new coin plus a bid (at least the nest's price, at most 2 SOL), escrowed with the 0.02 SOL launch fee and a 0.03 SOL rent reserve.
The asking	How a nest answers. Dev price: accepted at once, the nest dev can refuse it during the 1 h review. Holder vote: the nest's holders sign votes with their wallets for 24 h; a quorum of 10 % of the eligible weight and a simple majority accept it.
Hatch	One instruction, alone in its transaction: pump.fun creates the chick and the whole bid buys it into the escrow. Those tokens are the nest holders' airdrop. At most 3 hatches per nest in any rolling 24 h.
Chick	The coin that hatched. Its creator fees split on chain, forever: chick dev the rest, nest the nest's share, $CUCKOO 20 %, treasury 20 %. At the default 20 % nest: 40 · 20 · 20 · 20.
Nest share	Buys the nest coin and burns it (`feed_nest`), so every nest holder gains without a list.
Push it out	The nest's holders vote a chick out (quorum + two thirds of the votes cast): from then on its nest share goes to $CUCKOO.
Swap	A chick whose median market cap stays above its nest's for 24 h, checked at most 30 min apart, swaps roles: the old nest keeps 5 %, the freed part buys and burns the chick itself.
$CUCKOO	The pad token. Every coin's pad share collects in the pad vault; `buy_pad` buys $CUCKOO and burns it.

Lifecycle of an egg

state	how it gets there	what can happen next
Laid	`lay_egg` into a holder-vote nest	the vote runs until `vote_end`; the attestor posts the tally; after the 2 h veto window anyone applies it
Accepted	dev-price nest: at lay time · holder vote: a passing tally applied	dev price: the nest dev may refuse during the review · then the chick dev hatches it before `expires_at` (48 h after laying) and while the nest has a free slot
Hatched	`hatch` by the chick dev	the attestor posts the airdrop root; holders claim for 30 d; the rest is burned by `sweep_drop`
Rejected	refused by the nest dev in review, or the vote failed	`refund_egg` (anyone): the whole deposit and the egg's rent back to the chick dev
Expired	not accepted or not hatched before `expires_at`	`refund_egg` (anyone): full refund
Cancelled	`cancel_egg` by the chick dev before the hatch	full refund, egg closed

Worked example

Nest $OAK is open: dev price 0.50 SOL, share 20 %. It hatched 1 chick in the last 24 h, so it has 2 slots.
You lay an egg: bid 0.50 SOL. The escrow takes 0.50 + 0.02 (launch fee) + 0.03 (rent reserve) = 0.55 SOL. Dev price: the egg is accepted at once; the review runs 1 h.
After the review you hatch it. One instruction: pump.fun creates $CHICK with the pad's per-coin fee account as its creator and buys $CHICK with the whole 0.50 SOL into the escrow. The unused part of the rent reserve comes back to you in the same transaction; the 0.02 SOL fee is booked to the treasury.
The attestor takes the snapshot of $OAK's holders (each wallet's lowest balance over the 24 h before the hatch) and posts a merkle root whose total equals the escrowed $CHICK exactly. After the veto window each holder takes their share with the proof from the published file. A holder with 5 % of the weight gets 5 % of the $CHICK.
$CHICK trades. Say it earns 1 SOL of creator fees. collect splits it on chain: you 0.40, $OAK's share 0.20 (it buys $OAK and burns it), $CUCKOO 0.20 (buys $CUCKOO and burns it), treasury 0.20.
If $CHICK's median market cap stays above $OAK's for 24 h straight, the roles swap: $OAK keeps 5 %, the other 15 % buys and burns $CHICK itself.

Rules

Holder snapshot (votes and airdrops)

Weight of a wallet = the sum over its Token-2022 accounts of the nest coin of each account's lowest balance in the window [T − 24 h, T]. T = the hatch time for an airdrop, the end of the vote (or the early decisive moment) for a vote. A balance bought inside the window counts only from its lowest point, so a flash buy before the snapshot earns nothing. An account whose owner changed inside the window counts 0.

Not holders: owners that are not wallets (pools, curves, escrows, program vaults) and the chick's dev wallet (he pays the airdrop, and his votes about his own egg or chick do not count).

Vote

Every vote is a wallet signature over a readable text (below), not a transaction: free. The last valid signature per wallet and round received before the vote ends counts. Quorum base = the eligible weight: the total weight of every holder in the same snapshot, so buying or dumping at posting time does not move the quorum. Accept: quorum 10 % and yes > no. Push out: quorum and yes ≥ 2/3 of the votes cast; eject rounds run every 24 h from the hatch. The program computes the outcome on chain from the posted numbers. The report lists every vote with its signature and every holder weight; anyone can recount.

Airdrop

amount_i = floor(total × w_i / W); the rounding remainder goes 1 unit at a time to the largest holders; holders under 1e-6 of W are left out. Leaves: sha256(0x00 ‖ index u32 ‖ wallet ‖ amount u64), nodes sha256(0x01 ‖ min ‖ max). The total must equal the escrowed tokens exactly (checked on chain). Unclaimed after 30 d: burned. No root by 7 d after the hatch: the escrow burns after the claim window too; every lamport returns to the chick dev.

Program buys (feed the nest, feed itself, $CUCKOO)

Every buy the program makes uses the median of the last 7 price observations (spanning at least 10 minutes, each clamped to ±10 % of the running median), spends at most 0.6 % price impact, refuses if the live price is above the median, makes one program buy per coin per slot and refuses any pump or PumpSwap trade in the same transaction. The caller passes no amount.

What your wallet signs

A vote is this exact UTF-8 text, signed with your wallet's "sign message":

Cuckoo Pad vote
action: accept-egg
target: <egg account>
round: 0
choice: yes

For a push-out vote: action: eject-chick, target: <chick mint>, round: floor((now − hatch time) / vote window). It moves nothing and costs nothing.

The attestor signs reports with one key per cluster: the vote report (218 bytes: "cuckoopad:vote:v1" ‖ program ‖ kind ‖ target ‖ round ‖ nest ‖ yes ‖ no ‖ voters ‖ eligible ‖ as_of ‖ snapshot_root ‖ votes_hash) and the drop root (165 bytes: "cuckoopad:drop:v1" ‖ program ‖ chick ‖ root ‖ total ‖ leaves ‖ snapshot_at ‖ holders_hash). The program verifies the Ed25519 signature in the instruction before its own.

Parameters

Mainnet defaults and the values this preview chain runs with (read from the config account; the preview uses short windows so you can watch a whole cycle).

parameter	mainnet default	this chain

Program reference

Program id Cuc3WwPz3vca68SDVwbnwttAdKTG3gkXw95GqkLVHxy8 · Anchor 0.31.1 · every event is emitted by self-CPI.

Accounts

account	seeds	what
Config	`["config"]`	admin, treasury, attestor, guardian (+ pending keys and timelocks), pause, params, counters
PadState	`["pad"]`	$CUCKOO mint (set once), its observations, pad-vault books (sol in, sol spent, tokens burned)
pad vault	`["padvault"]`	SOL for the $CUCKOO buy and burn
buyer	`["buyer"]`	makes every program buy; ends each instruction at its rent floor
Coin	`["coin", mint]`	every pad coin: dev, kind (plain / chick), nest, split, vote and swap state, fee books, fee ring, observations
Fees	`["fees", mint]`	the coin's pump creator: creator fees land here and wait as booked shares
Nest	`["nest", nest mint]`	mode, price, share, the last 3 hatch times, SOL dropped
Egg	`["egg", nest mint, id u64]`	chick dev, metadata, bid, deposit, a copy of the terms, state, times, tally, hatch results
brood	`["brood", egg]`	the escrow: pays pump at the hatch, makes the dev-buy, holds the airdrop
chick mint	`["mint", egg, nonce u64]`	created by pump.fun inside `hatch`
Report	`["report", target, kind u8, round u32]`	an attested vote result (1 accept: target = egg; 2 eject: target = chick)
Drop	`["drop", chick mint]`	airdrop root, total, leaves, claim bitmap

Instructions

instruction	who	notes
launch	anyone, alone in its tx	a plain coin: create + dev buy; fees dev 50 / $CUCKOO 30 / treasury 20
sync_migration	anyone	curve complete + canonical pool: the coin becomes a nest
open_nest	the nest coin's dev	mode, price, share; eggs keep the terms they were laid with
lay_egg	anyone (the chick dev)	bid in [price, max bid], the terms you saw are checked
reject_egg	the nest coin's dev, during review	full refund
cancel_egg	the chick dev, before the hatch	full refund
refund_egg	anyone	rejected or expired eggs: full refund to the chick dev
hatch	the chick dev, alone in its tx	accepted, reviewed, not expired, nest has a free slot
post_accept_vote / post_eject_vote	anyone with the attestor's signature	outcome computed on chain
veto_report / veto_drop	guardian, before final	closes the report; the attestor may repost
apply_accept / apply_eject	anyone, after final
post_drop_root	anyone with the attestor's signature	total == escrow, snapshot = hatch time
claim_drop	anyone	tokens go to the leaf's wallet
sweep_drop	anyone after the claim window	burns the rest, returns every lamport
collect / unwrap_fees	anyone	pull creator fees and split them on chain
claim_dev / collect_treasury	anyone	pays only the coin's dev / the treasury
feed_nest / feed_self / buy_pad	anyone (lends 0.02 SOL headroom, returned)	guarded buy + burn
observe / observe_pad / check_swap	anyone	price observations, the swap watch

Errors

code	name	what it means

Verify on chain

Every coin's pump creator is its own ["fees", mint] account of this program: check the bonding curve's creator field.
A hatch is one transaction: pump's create and the buy into the escrow appear as inner instructions of one hatch; the Hatched event lists bid, spent and tokens.
The escrow's token account holds exactly the Drop's total until claims start (post_drop_root refuses anything else).
The drop file at /drop/<chick>.json rebuilds the root on chain; every proof checks against it.
The report at /report/accept-<egg>-0.json lists every vote with its signature; each one verifies against the text above, and the weights sum to the posted yes / no.
Fees PDA lamports = rent floor + dev + nest + self + treasury booked, after every instruction.
Pad vault lamports = floor + sol in − sol spent; every PadBought event burns what it bought (mint supply drops by exactly that).
A nest never holds more than 3 hatch times inside any 24 h window (Nest.hatch_ts).

Admin powers

can	cannot
Pause new launches, eggs and hatches (refunds, claims and fees keep working). Change future params within bounds (loosening a guard waits 3 days and the guardian can cancel it). Rotate the attestor and guardian keys with a 3-day timelock. Set the treasury.	Touch an escrow, a fee book, the pad vault or an airdrop. Change the terms of an egg already laid. Change the split of a coin already launched. Mint, freeze or move anyone's tokens.

The attestor (votes + airdrop roots) can only choose who among the nest's holders gets what part of a fixed airdrop total and how votes were weighted; it cannot change the total, the price, the shares, the 3-a-day limit or any SOL path. The guardian can only veto (delay) reports and cancel pending rotations.

Compromise, in plain words: pump.fun keeps no holder list on chain, and a signature vote over a balance snapshot can only be checked off chain. So holder snapshots and vote tallies are attested by our service and published in full; the airdrop amount, the escrow, the fee shares, the quorum and majority arithmetic, the 3-a-day limit, the swap and every buy are on chain.

If the pad ever winds down: the admin pauses new eggs and hatches; every open egg stays refundable by anyone, airdrops stay claimable until their window ends, and fees keep splitting. The pinned post and the links will point to a static page with the final transactions.

Risks

The attestor could weigh votes or airdrops wrongly. Bounds: a 2 h guardian veto, every input published, a timelocked key rotation.
If no airdrop root is ever posted, the airdrop burns after the root deadline plus the claim window: honest, and harsh for the nest's holders.
A chick dev can hold the nest from other wallets for 24 h and recover part of his own airdrop; only his launch wallet is excluded. It costs real exposure to the nest.
A dev-price nest's 3 daily slots can be taken by anyone who pays its price 3 times. The price goes to the nest's holders; the nest dev raises the price if that happens.
Observations are permissionless: a pumper who wins every observation for 10+ minutes can move the median 10 % per observation; the impact cap bounds what one program buy spends at that price.
Anyone can donate SOL to a coin's creator vault: it is split like fees (it funds the nest and $CUCKOO). Nothing pays a caller in proportion to fees he can donate.
Pots are small. The site shows what is on chain, never a projection.

FAQ

Do I need to hold anything to lay an egg?

No. Any wallet can lay an egg in any nest with room.

What happens to my bid if the nest says no?

Full refund, including the fee and the reserve. Anyone can send it back to you; the site's Mine window has the button.

Why does my vote weigh 0?

Your wallet's lowest balance of the nest coin over the last 24 h was 0: you bought inside the window, or you hold it in another wallet.

Does voting cost a fee?

No. It is a signature over the text above, not a transaction.

Can a nest stop being a nest?

No. A migrated pad coin is a nest for good; its dev can only change the terms of future eggs.

Is there a token tax?

No. The coins are plain pump.fun coins; everything here runs on the creator fees pump.fun already charges.