Quantum Raffle

Quantum Raffle is a high-stakes onchain social game with two exciting dynamic prize pools to tap into: the Grand Prize Pool and the Virality Prize Pool. The prize pools build up as players enter Quantum Raffle, and a raffle ends when 5 minutes pass without a ticket sold.

The Grand Prize goes to the final entrant and a few other lucky ticket numbers, calculated trustlessly by the contract. The Virality Bonus is split amongst all entrants based on when they entered.

The prize math is centered around logarithms.

Put simply:

• The earlier you enter and the more you enter, the more you earn from the Virality Prize Pool.
• If your ticket lands in any one of the Power Slots, you split the Grand Prize equally.

That's the whole game. The rest of these docs explain exactly how each pool pays out and how anyone — a player, a wallet, a bot, or an agent — can interact with the contract directly.

Two pools, two ways to win

Grand Prize Pool — land a Power Slot

When a raffle ends, the contract walks back from the final ticket and marks a handful of Power Slots at logarithmic positions from the end. The last ticket always wins, and the further back you go the rarer the slots become. Every Power Slot splits the Grand Prize Pool equally — no oracle, no randomness, just a deterministic rule anyone can verify on-chain.

→ Power Slots

Virality Prize Pool — get in early, bring people in

Every entry feeds the Virality Prize Pool, which pays out to everyone who entered before you keep coming. Players are grouped into cohorts by entry order, and each cohort only earns once the next cohort arrives. So the earlier you enter — and the more tickets you hold — the more of this pool flows your way as the game grows. It rewards you for showing up early and for pulling new players in.

→ Virality Bonus & Cohorts

How a round works

1. A host opens a game; players enter by sending ETH in multiples of the entry amount.
2. Every entry grows both pools and resets the 5-minute inactivity countdown — so there's always pressure to send "one more ticket."
3. When 5 minutes pass with no new ticket, the game ends. (The countdown length and an optional minimum-ticket floor are set per game by the host.)
4. Power Slot holders claim their share of the Grand Prize; every earlier entrant claims their share of the Virality Prize.

→ Game Lifecycle

Building on Quantum Raffle

The contract is designed to be interacted with directly — by frontends, bots, and autonomous agents. Entering is just sending ETH; everything else is plain view functions and explicit claims.

• Enter a game — send ETH via receive(), or use the 20-byte fallback() path to route prizes to a cold wallet. See Cold-Wallet Prize Routing.
• Read game state — entrantCount, isWinner, getNumWinners, pool balances, and the locked game config are all public. See the Public Interface.
• Claim prizes — claimPrize for Power Slots, batchClaimAdoptionBonusPrize / claimAdoptionBonusPrize for the Virality Prize. See Events & Errors for everything you can watch and react to.
• Automate entries — there's a reference auto-entry bot you can crib from. See the Auto-Entry Bot.

At a glance

Where to go next

• New to the game? Read How It Works and Game Lifecycle, then Power Slots and the Virality Bonus.
• Building a UI, bot, or agent? Start with the Public Interface and Events & Errors.
• Want the exact math? See the Prize Math Specification and Worked Examples.