Skip to content

Running a raffle

tilttek/raffle

Stakes and sources

StakeSeeded byWhy
Stake::Prize: something of value is wonSeedSource::Beacon, alwaysAn organiser who held the seed could draw again until a friend wins, before committing to it
Stake::None: who speaks first, who brings the snacksSeedSource::CommitReveal by default, SeedSource::Beacon on requestNothing to gain by cheating; no network needed

open() refuses a prize seeded by its organiser, and a beacon raffle when no beacon is configured.

$raffles->open('door-prize', Stake::Prize, winners: 3, alternates: 2);
$raffles->open('first-speaker', Stake::None);                          // commit-reveal
$raffles->open('pizza-topping', Stake::None, source: SeedSource::Beacon);

A raffle draws 1 to 1 000 winners and 0 to 1 000 alternates. A raffle seeded by commit-reveal draws its seed — 32 bytes from the secure randomizer — when it opens, and its commitment, the SHA-256 of the seed's 64 hexadecimal digits, is in the raffle and in the announcement from then on.

Entries: one chance per entrant

$raffles->enter('door-prize', 'member:1042');

An entrant is an opaque reference of 1 to 128 letters, digits, dots, colons, underscores, tildes or hyphens: a member or a ticket identifier, published in the proof, so never an address nor a name — the @ of an address is refused. An entrant enters once: a second entry is refused, nothing in the API takes a number of chances, and the draw is uniform among the distinct entrants. A raffle takes up to 100 000 entrants, and no entry once it is sealed.

Sealing

$announcement = $raffles->seal('door-prize');
$announcement->toArray();     // raffle, stake, source, winners, alternates, entrants, entrants_hash, sealed_at,
                              // commitment, chain, round, drawable_at

seal() refuses a raffle without entrants, lists the entrants in byte order, hashes them, and, for a beacon, reads the chain and fixes the first round published strictly after the closing plus the margin — 30 seconds by default, room for the clocks of the server and of the beacon to differ. Publish the announcement at once, where the entrants see it: the hash proves no entrant was added or removed afterwards; the round, announced before it exists, proves the organiser could not choose it. announcement() gives it again later.

Drawing

$proof = $raffles->draw('door-prize');
$proof->winnerList();         // the winners, in the order drawn
$proof->alternateList();      // the alternates, in the order they replace a winner

A beacon raffle is drawn once its round is published: before drawableAt(), draw() refuses and fetches nothing. The round fetched must be the round announced. A commit-reveal raffle is drawn at once, its seed revealed in the proof. When there are fewer entrants than winners and alternates, every entrant is drawn, in a random order.

A raffle is drawn once: a winner who does not claim the prize is replaced by the next alternate, never by a new draw, so that the order of replacement is fixed by the same seed and in the proof. proof() gives the proof again later.

The event

Once the raffle is kept as drawn, Raffles dispatches Event\RaffleDrawn, which carries the raffle's identifier only. A listener reads the proof to announce the winners, push them to a screen, or play a celebration — confetti on the stream overlay —; the library itself shows nothing.