PureRand Wheel: shuffle algorithm shuffle-v1

How a whole list is put in random order with one verifiable draw, and how teams are dealt from it. Every shuffle returns a receipt that can be replayed from this page and checked against the public api2 hash chain.

Status: current, published September 2026. Companion to wheel-v1, whose conventions (lowercase hex, snake_case fields, UTC timestamps as YYYY-MM-DD HH:MM:SS.mmm) apply here too. Randomness API: https://api2.purerand.com.

Introduction

A shuffle has the same three steps as a spin. The browser commits to the list, the server draws fresh randomness from api2 only after the commitment is stored, and the receipt records everything needed to replay the result. The result is the complete new order of the list, not a single winner.

Commitment

Exactly as in wheel-v1, with "algorithm":"shuffle-v1" in the committed document. Labels, weights, salt and the api2 canonical JSON serialisation are the same.

Randomness

A list of n entries needs n − 1 accepted 32-bit samples. The server asks api2 for exactly the bits it still needs plus two spare samples, at most 4096 bits (api2's limit) per call:

bits = min(4096, 32 × (samples still needed + 2))
GET https://api2.purerand.com/random/<bits>/bits      (api2's two-step challenge, Bearer + HMAC)

The response carries the bits as value, a string of 0 and 1, with the block hash, its timestamp and a verify_url. For this endpoint api2 stores value itself as the block's random_data. A second call is made only if rejections use up the spares. One call carries 128 samples, so up to 127 entries fit in one call with the spares; longer lists need more calls (500 entries: at least 4). Sample k is the value of characters 32k to 32k+31 of the concatenated bits, read as a binary number.

Shuffle

A Fisher–Yates shuffle, from the last position down, with the same rejection rule as wheel-v1:

order = [1, 2, …, n]                     slot numbers
for i = n − 1 down to 1:
    m = i + 1
    limit = 2^32 − (2^32 mod m)
    take the next sample u; while u ≥ limit, take the next one
    j = u mod m
    swap order[i] and order[j]            positions counted from 0
order is the result: order[0] is the first entry of the new list

Every one of the n! orders is equally likely. Example: 3 entries and the samples 7 and 5 give [1, 3, 2].

Draw order

Draw order is shuffle-v1 used as it is: the new order of the whole list, shown as positions 1 to N. It is a use of this algorithm, not a variant of it. One commitment, one draw, one receipt, and the order on the receipt is the order that is shown.

Revealing the positions one at a time is presentation only. Every position was decided by the draw that the receipt records; walking through them asks the randomness service for nothing and cannot change what comes next. Showing them all at once yields exactly the same order.

Teams

Teams are dealt from one shuffle, in turn: the entry at position k of the new order (counting from 1) joins team ((k − 1) mod T) + 1, for T teams. Team sizes differ by at most one. The split uses no further randomness, so the shuffle receipt is the whole record.

Receipt

As in wheel-v1, with algorithm set to shuffle-v1, result.order holding the new order as slot numbers, randomness.value the concatenated bits, and each api2 response in randomness.draws with type bits and its length.

Verifying a receipt

  1. Check that randomness.value is the concatenation of every draws[].value.
  2. Replay the shuffle on the bits; the order must equal result.order.
  3. Look up each block: random_data must equal the draw's value, and its timestamp must not be earlier than committed_at (equal is valid, as in wheel-v1).
  4. With the list and salt, the SHA-256 of the canonical document must equal commitment.
python3 reference.py --online receipt.json

The verify page, reference.py and the test vectors cover both algorithms.

FAQ

Does the order of my list matter?
Not for fairness: every order of the entries is equally likely to come out, whatever order you typed them in. The order you committed to is still part of the commitment, so the receipt shows exactly which list was shuffled.
Why does a long list take longer?
Only a little. A list of n entries needs n − 1 random numbers, and one api2 call returns at most 4096 bits, so a list of 500 entries needs at least four calls. Each call fetches its bits from the source in one request, so even a list of 500 is usually done in about a second.
Do weights affect a shuffle?
No. Weights stay attached to their entries and are part of the commitment, but the order is uniform over all entries.