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:

  1. 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.
  2. 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.
  3. 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 = f025da1ccbaf89f5b8cae754464a5d61cfc009eca2cdc4b2ee9d35fd9f3055a4

The 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 + … + Wk

Because 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.

Receipt

The JSON at /api/receipts/<receipt_id> has these fields:

FieldMeaning
receipt_id128 random bits, 32 hex characters
algorithmwheel-v1
session_id, sequenceThe session and the spin's number in it; the session page lists every spin in order
slot_count, weightsThe list, as numbers
commitment, committed_atThe 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.valueB, the concatenated bytes
randomness.api_baseBase URL that verify_url is relative to
result.winning_slot, result.accepted_sample_indexThe winner and which sample decided it
previous_receipt_id, link_reasonSet when this list is the previous one with its winner removed
namesLabels and salt, only when published; removed on request or after 12 months
signatureReserved for a future post-quantum signature; currently null

Verifying a receipt

  1. Check that randomness.value is the concatenation of every draws[].value.
  2. Replay the draw on the weights and bytes; slot and sample index must equal result.
  3. For each draw, SHA-256 of value must equal value_hash.
  4. Look up each block with the regular API: random_data must equal value_hash, and the block timestamp must not be earlier than committed_at. Equal counts as valid.
  5. 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.json

Why 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.