The draw and its proof
tilttek/raffleThe hashes
Every hash is the SHA-256, in 64 lower-case hexadecimal digits, of a canonical JSON: PHP's json_encode() with
JSON_UNESCAPED_SLASHES and JSON_UNESCAPED_UNICODE, no space.
| Value | Hash of |
|---|---|
| The entrants hash, announced when the entries close | ["tilttek-raffle/1", raffle, [entrants in byte order]] |
| The commitment of a commit-reveal raffle, published when it opens | the 64 hexadecimal digits of the seed |
| The seed of the draw | ["tilttek-raffle/1", raffle, entrants hash, randomness] |
The randomness is the beacon round's — the SHA-256 of its signature — or the seed the organiser revealed. Byte order
is the order of PHP's sort($entrants, SORT_STRING): B before a, 10 before 9.
The shuffle
The names drawn are the first min(winners + alternates, entrants) of a partial Fisher-Yates shuffle of the entrants
in byte order. Step i, from 0, swaps entrant i with entrant i + u, where u is drawn uniformly below the number
of entrants left, n - i:
- compute the SHA-256 of the 32 bytes of the seed followed by
iand an attempt counter, from 0, both as 4-byte big-endian numbers; - read its first 6 bytes as a big-endian whole number
v, below 2⁴⁸; - if
vis below the largest multiple ofn - ithat is at most 2⁴⁸,uisvmodulon - i; otherwise add one to the attempt counter and start again.
Rejecting the values past the last whole multiple keeps every entrant equally likely; with 100 000 entrants a value is rejected less than once in a billion draws. The names drawn are the winners first, then the alternates.
A raffle of several prizes — a podium — is one draw: the first name drawn takes the first prize, the second the second,
and so on, then the alternates in the order they replace a winner. RaffleProof::place($entrant) gives that place, 1
for the first prize, or null for an entrant not drawn. The order is part of the proof: a player who swaps two places or
drops a name breaks it.
The proof
RaffleProof::toJson() writes:
{
"version": "tilttek-raffle/1",
"raffle": "door-prize",
"stake": "prize",
"winners": 3,
"alternates": 2,
"entrants": ["member:1042", "member:1077"],
"entrants_hash": "…",
"source": {
"kind": "beacon",
"chain": {"hash": "52db9b…", "genesis": 1692803367, "period": 3, "scheme": "bls-unchained-g1-rfc9380", "public_key": "…"},
"beacon": {"round": 1234567, "randomness": "…", "signature": "…", "previous_signature": null, "verification": "relay-quorum"}
},
"seed": "…",
"drawn": ["member:1077", "member:1042"],
"sealed_at": "2026-11-12T20:00:00.000000Z",
"drawn_at": "2026-11-12T20:01:00.000000Z"
}
A commit-reveal proof has "source": {"kind": "commit-reveal", "commitment": "…", "seed": "…"}. fromJson() reads at
most 16 MiB, 8 levels deep, every field checked, and throws InvalidRaffle for anything else.
Checking a proof
RaffleVerifier::problems($proof) lists what breaks the proof, one sentence per fault; holds() is true when there is
none; problemsOfJson($json) reads the published text first, a proof that does not read being one fault. It checks:
- a raffle with a prize drew from a beacon round;
- the entrants are each listed once, in byte order, and hash to the entrants hash;
- the beacon round is the first published after the closing or a later one, or the seed revealed matches the commitment;
- the seed of the draw is the hash of the raffle, the entrants hash and the randomness;
- the shuffle from that seed gives the names drawn, in the same order.
Given a BeaconSignatureVerifier, it also verifies the round's signature against the chain's public key. Without
one, a player verifies the signature with drand's own clients: the round, its signature and the chain are in the proof.
A player also checks that the entrants hash and the round are the ones the organiser announced before the draw, and
that their own reference is among the entrants.