PureRand Wheel: draw algorithm wheel-v1
How a spin is committed, drawn and recorded. Every spin returns a receipt, and every receipt can be replayed from this page alone and checked against the public api2 hash chain.
Status: current, published September 2026. Randomness API: https://api2.purerand.com (API documentation). A change to any rule below is released as a new algorithm version; receipts name the version they used.
Introduction
PureRand Wheel picks one entry from a list of 2 to 500 entries. A spin has three steps, and each leaves a trace a third party can check:
- Commit. The browser fixes the list and sends only a SHA-256 commitment to it, with the weights. The server stores it with a timestamp.
- Draw. Only then does the server request fresh random bytes from api2, which records them as a block in its public hash chain. The winner follows from the bytes by a fixed rule, before the wheel starts to slow down.
- Record. The receipt holds the weights, the commitment and its timestamp, the api2 response and the winner. It is public at /r/<receipt_id> and downloadable as JSON.
While the draw is pending, the wheel turns at the same constant speed for every spin, starting from where it stood, so this motion carries no information; it only starts to slow down once the result is known.
To put a whole list in random order (and to make teams), see the companion algorithm shuffle-v1.
Conventions follow api2: lowercase hexadecimal for identifiers, hashes and bytes; snake_case field names; timestamps as YYYY-MM-DD HH:MM:SS.mmm; and api2's canonical JSON wherever something is hashed. All timestamps, in receipts, in api2 responses and on this page, are UTC. Receipt pages also show your local time next to the UTC value, for reading only.
Commitment
Entries are numbered from 1 in list order. Weights are integers from 1 to 1000. Labels are 1 to 100 Unicode code points, in Normalization Form C, without leading or trailing white space (as removed by ECMAScript String.prototype.trim) and without control characters U+0000–U+001F or U+007F–U+009F. The browser normalises input to NFC and trims it before committing.
The salt is 32 bytes from the browser's cryptographic random generator, written as 64 lowercase hex characters. The document committed to is:
{"algorithm":"wheel-v1","entries":[{"label":…,"slot":1,"weight":…},…],"salt":"…"}It is serialised with api2's canonical JSON, the same serialisation api2 uses for its block hashes: keys sorted in ascending order, no white space, / written as is, " and \ and \b \t \n \f \r as short escapes, and every other character below U+0020 and every non-ASCII UTF-16 code unit as \u plus four lowercase hex digits. The result is plain ASCII. For wheel documents this equals Python's json.dumps(doc, sort_keys=True, separators=(",", ":"), ensure_ascii=True).
The commitment is the lowercase hex SHA-256 of that text. Example:
{"algorithm":"wheel-v1","entries":[{"label":"Alice","slot":1,"weight":1},{"label":"Bob","slot":2,"weight":1},{"label":"Carol","slot":3,"weight":1}],"salt":"0f1e2d3c4b5a69788796a5b4c3d2e1f000112233445566778899aabbccddeeff"}
commitment = f025da1ccbaf89f5b8cae754464a5d61cfc009eca2cdc4b2ee9d35fd9f3055a4The server receives the slot count, the weights, the commitment and the interface language. It receives labels and salt only when the person spinning ticks the option to publish names; they are then sent with the spin and stored only if they reproduce the commitment.
Randomness
After the commitment is stored, the server makes one signed call to api2:
GET https://api2.purerand.com/?kind=crypto&type=challenge&bytes=16&format=hex Authorization: Bearer API_KEY X-PR-TS: <unix seconds> X-PR-Signature: <HMAC-SHA256 over METHOD|CANONICAL_PATH|API_KEY|TS>
The response carries the bytes as value (hex), value_hash (SHA-256 of that hex text), the block hash, its timestamp, a verify_url, source_alias, classification, usedQuantum and a sources breakdown. api2 stores value_hash as the block's random_data. The receipt keeps this response verbatim.
api2 chooses the source: the first available of PureRandom A, B and C, or Random, its classical CSPRNG fallback, when no quantum source can answer. The receipt records the label api2 reports. If api2 cannot be reached, nothing is drawn and the spin can be retried; there is no fallback on the wheel's side.
Where the randomness comes from
Every draw asks PureRand for fresh random values, and the receipt records which source produced them. This section is the plain-language version of what those fields mean; the fields themselves are listed under Receipt.
PureRandom A is a quantum source. The values come from a physical process measured by the provider, not from a formula. When a receipt says quantum for a set of samples, that is what the API reported for those samples, and nothing more is claimed about them here.
The CSPRNG fallback is the classical alternative. If a quantum source is unreachable, or inside its rate limit at that moment, the API uses the operating system’s cryptographic random generator rather than making the draw wait. That is still unpredictable randomness of cryptographic quality; it is simply not measured from a physical process, and the receipt says so.
A single draw can use both. The receipt lists each source with the number of samples it produced — for example thirteen of sixteen from the quantum source and three from the fallback. The counts are taken verbatim from the API response: nothing is rounded up, a fallback is never folded into the headline source, and a draw the API did not break down is shown as exactly that rather than attributed to a source it did not name.
This is deliberate. A claim about where randomness came from is worth no more than the record behind it, so the mix is written on the same receipt as the result and can be checked there.
Draw
Let B be the bytes of all api2 calls for the spin, concatenated in order (normally one call of 16 bytes), and W the sum of the weights.
limit = 2^32 − (2^32 mod W) largest multiple of W not above 2^32
for i = 0, 1, 2, …:
u = B[4i..4i+3] read as an unsigned 32-bit big-endian integer
if u < limit: r = u mod W; stop (accepted sample i)
otherwise reject u and try i + 1
if no sample is accepted: request 16 more bytes and continue (at most 4 calls)
winner = the smallest slot k with r < W1 + W2 + … + WkBecause limit is a multiple of W, each value of r from 0 to W−1 comes from exactly limit / W accepted values of u. There is no modulo bias, and slot k wins with probability Wk / W.
Animation (presentation only)
Nothing in this section is part of the draw; verification ignores it. It describes what the wheel shows.
- When Spin is pressed, before anything is drawn, the wheel starts turning at a constant 600° per second from its current position. The motion is identical for every spin and uses no randomness.
- Once the result is known, the wheel slows down over a fixed 4 seconds, starting at that same speed, and comes to rest on the drawn slot. How long api2 took does not change this part.
- Where inside the drawn slot it stops is taken from the receipt: with f = the first 8 hex digits of
randomness.draws[0].value_hashread as a number and divided by 2^32, the pointer rests at 15 % + 70 % × f of the slot's width, never near its edges. - With reduced motion, the wheel shows that resting position directly, without turning.
- If api2 fails, the wheel slows to a stop wherever it is and the error is shown; nothing is drawn.
Receipt
The JSON at /api/receipts/<receipt_id> has these fields:
| Field | Meaning |
|---|---|
receipt_id | 128 random bits, 32 hex characters |
algorithm | wheel-v1 |
session_id, sequence | The session and the spin's number in it; the session page lists every spin in order |
slot_count, weights | The list, as numbers |
commitment, committed_at | The commitment and when it was stored |
randomness.draws[] | Each api2 response, verbatim: value, value_hash, hash, timestamp, verify_url, source_alias, classification, usedQuantum, sources, provenance_version |
randomness.value | B, the concatenated bytes |
randomness.api_base | Base URL that verify_url is relative to |
result.winning_slot, result.accepted_sample_index | The winner and which sample decided it |
previous_receipt_id, link_reason | Set when this list is the previous one with its winner removed |
names | Labels and salt, only when published; removed on request or after 12 months |
signature | Reserved for a future post-quantum signature; currently null |
Verifying a receipt
- Check that
randomness.valueis the concatenation of everydraws[].value. - Replay the draw on the weights and bytes; slot and sample index must equal
result. - For each draw, SHA-256 of
valuemust equalvalue_hash. - Look up each block with the regular API:
random_datamust equalvalue_hash, and the blocktimestampmust not be earlier thancommitted_at. Equal counts as valid. - With the list and salt, the SHA-256 of the canonical document must equal
commitment.
curl -s -H "Accept: application/json" "https://api2.purerand.com/verify?hash=<draws[].hash>"
# -> { "ok": true, "hash": …, "timestamp": …, "random_data": <value_hash>, "source_alias": …, … }
python3 reference.py --online receipt.jsonWhy an equal timestamp is valid. committed_at is set by the wheel's database when the commitment is stored, and the block timestamp is set by api2 when it records the bytes. Both run on the same server and read the same system clock, with millisecond resolution. The wheel calls api2 only after the commitment is stored, so the block cannot come first; when both happen within the same millisecond, the two values are equal. Only a block timestamp strictly earlier than committed_at indicates bytes that existed before the commitment, and fails verification. If the two services ever run on separate servers, this section will state the clock tolerance that applies.
The verify page runs steps 1 to 3 and 5 in your browser with code separate from the server's, and links each block for step 4.
Test vectors and reference code
vectors.json holds canonical documents, commitments and draws, including a rejection at the limit and a draw that needs a second call. reference.py is a Python implementation using only the standard library; it generated the vectors and verifies a downloaded receipt, online with --online.
FAQ
- Which source produced my spin?
- The one api2 reports, recorded unchanged on the receipt: PureRandom A, PureRandom B or PureRandom C for a quantum source, or Random when api2 fell back to its cryptographically secure classical generator. PureRand Wheel does not choose the source and never substitutes bytes of its own. The alias catalogue and its live status are public at /sources on the API host.
- What does a quantum source say about my result?
- Where the bits came from, as api2 describes it. It is not a certification of cryptographic quality, and it is not what makes the draw fair. Fairness comes from the commitment being fixed before the bytes exist, the uniform mapping, and a record anyone can replay.
- Can the server change the list after seeing the random bytes?
- It should not be able to without detection. The commitment is stored with its timestamp before api2 is called, and api2 timestamps its block when the bytes are drawn. A receipt whose api2 block is older than its commitment fails verification, and a changed list no longer matches the commitment.
- Do I need an account or an API key to verify?
- No. The receipt, this specification and the public /verify endpoint of api2 are enough. Looking up a block needs only its hash.
- Why can a spin use more than one api2 call?
- Only when all four 32-bit samples of the first call fall in the rejected range, which for at most 500,000 total weight happens with a probability below 1 in 10^16. The receipt then lists every call in order.