Docs / Programs

Programs

How a token can pay its holders from trading fees, by rules fixed at launch. What the programs are, how a cycle runs, and what you have to trust.

A creator can fund programs when launching a token on Clanker v4, or on Clanker v5 with the ETH pair. Part of the vault's share of the fee goes to a pool for that token instead of a treasury. The pool pays holders by rules the creator picked at launch. Nobody buys anything to take part: eligibility comes from holding the token.

How the money moves

Trading fees reach the token's vault, as described in Fees and vaults.
When programs are on, the Treasury line of the vault's split is paid into the token's pool, as ETH. The launch form calls this line Reward programs. The default is 20% of the vault's share.
Each cycle, Revvy reads holder balances from the chain, applies the rules and publishes the result.
Holders receive their share: a prize sent to the winner's wallet, or a dividend the holder claims.

One to three programs

Each program takes a share of the pot. Shares are equal unless the creator sets them.
A token runs at most one game next to its dividends.
The rules are written as a plain list of steps and hashed. The hash is stored in the pool contract, so the rules cannot change after launch. The token page shows them in words.
The creator can stop new funding at any time. What the pool already holds is still paid out under the same rules.

Games and dividends

	Games	Dividends
What it is	A draw. Winners are picked from a ticket list.	A pot shared among holders by a filter and a weight.
How often	Weekly	Daily, or weekly with a game on the token
How you receive it	The prize is sent to the winner's wallet.	You claim your share on the token page and pay the network gas.
Details	Games	Dividends

A token runs all its programs on one cadence, and the launch form picks the slowest of the programs chosen. So with a game in the mix, the dividends also run weekly, whatever the Cadence column below says for them on their own.

The programs
Program	Cadence	Who gets paid	Weighted by	Holding floor	Per-wallet cap	Wallets needed
Holder lottery	Weekly	1 winner	Average balance over the cycle	$10 for 24 h	n/a	n/a
Multi raffle	Weekly	6 winners	Average balance over the cycle	$10 for 24 h	n/a	n/a
Diamond hands	Weekly	1 winner	Hold streak: odds grow up to 3x	$10 for 24 h	n/a	n/a
Diamond hands (strict)	Weekly	1 winner	Hold streak: odds grow up to 5x	$10 for 72 h	n/a	n/a
Whale club	Daily	The top 100 holders	Average balance over the cycle	$10 for 24 h	5% of a cycle’s pot	20+
Flat dividend	Daily	Every eligible holder	Equal shares	$25 for 24 h	2% of a cycle’s pot	50+
Shrimp fund	Daily	The smallest 30% of holders	Equal shares	$25 for 24 h	2% of a cycle’s pot	50+
Jeet jail	Daily	Holders who have not sold	Balance at the end of the cycle	$10 for 24 h	5% of a cycle’s pot	20+
Midcurve	Daily	The middle of the pack	Square root of the balance	$25 for 24 h	3% of a cycle’s pot	34+
Whale tax	Daily	The smallest 50% of holders, if they did not sell	Square root of the balance	$25 for 24 h	3% of a cycle’s pot	34+
Gas money	Daily	Wallets that just started holding	Equal shares	$25 for 24 h	1% of a cycle’s pot	100+

The programs page shows each one in more detail, with the exact rules in words.

How a cycle runs

A cycle lasts one day or one week, counted from the hour the token's pool was created. The token page shows the cycles that have run.

Snapshot. Revvy reads holder balances from the chain through the cycle, every 30 minutes.
List. Shortly after the cycle ends, Revvy publishes the result: a ticket list for a game, or a list of what each wallet is owed, with a proof for each, for a dividend. Revvy's committer key builds each list.
Commitment. Revvy writes the list's hash and root on chain.
Wait (dividends). A new dividend list waits 12 hours before claims open, so a mistake can be caught. During that time Revvy can cancel it. After that, it cannot be cancelled or replaced.
Random number (games). Chainlink VRF provides a random number after the commitment, and winners are picked from the published list.
Payment. Dividends can be claimed for 365 days after the last list. Prizes not settled within 30 days of the draw return to the pot.

If the pot is under $20, the cycle is not paid and the pot rolls into the next one. A dividend with a per-wallet cap also rolls when too few wallets qualify; see Choosing programs.

Closing a pool that nobody runs

If a pool has had no claim, new list or roll for 90 days, and 365 days have passed since its last dividend list (a pool with games only needs just the 90 days), anyone can end it. What is not owed to a holder then goes to Revvy's treasury, not to holders or the creator. Amounts already owed to a holder, and prizes already drawn, stay claimable and are not sent to Revvy.