Laboratory dice verification
This specifies choice-2x2d6-hmac-sha256-v1, implemented by LaboratoryDiceSource for
issue 291. It is a separate, private
dice-source seam for the laboratory contract. Classic DiceSource,
its byte encoding and its three-dice stream are unchanged. This work enables no routes or rooms;
the authoritative room and reveal policy belong to
issue 292.
Inputs and commitment
Section titled “Inputs and commitment”Generate a fresh 32-byte server seed using a CSPRNG for each game. Publish its SHA-256 digest as 64 lowercase hex characters before collecting the client seeds. Freeze the effective white and black client seeds after the post-commit readiness gate. Recovery must use exactly those persisted values and the captured algorithm identifier; an unknown version fails closed. The dice source does not choose fallback seeds, advance the room or enforce readiness itself.
turnNumber is the zero-based macro-turn identity, the persisted current ply: 0 for White’s
first turn, 1 for Black’s first turn, and so on. It advances once after a completed turn, including
an explicit pass, and never for a roll, choice, retry, micro-move or reconnect. Version 1 accepts
0..9007199254740991, matching the exact JSON integer contract. The alternatives’ stable
offerIndex values are 0 and 1. Equal pairs retain both indices.
Client seeds are encoded as strict UTF-8, without trimming, case folding or Unicode normalization. Lengths count bytes, including any embedded NUL. Malformed Unicode is rejected, rather than silently replaced. Server seeds restore from exactly 64 ASCII hex characters (either case); errors contain no submitted seed. Constructors defensively copy the server seed.
Exact version-1 derivation
Section titled “Exact version-1 derivation”All integers below are big-endian. ++ denotes concatenation, ASCII and UTF8 denote raw bytes,
and the domain ends with exactly one zero byte, with no length prefix or newline:
domain = ASCII("choice-2x2d6-hmac-sha256-v1") ++ 0x00w = UTF8(clientSeeds.white)b = UTF8(clientSeeds.black)
base(turnNumber, offerIndex) = domain ++ uint32be(length(w)) ++ w ++ uint32be(length(b)) ++ b ++ int64be(turnNumber) ++ uint8(offerIndex)
block(k) = HMAC-SHA256(serverSeed, base ++ uint32be(k))Derive each pair independently, starting its own block counter at 0. Scan each 32-byte digest
from left to right as unsigned bytes. Reject values 252–255. Every other byte yields
(byte % 6) + 1. Take exactly the first two accepted values in generation order. If necessary,
continue with the next block, retaining any already accepted die. No mutable stream cursor is
shared between alternatives or calls; pair 2 is not a continuation of pair 1.
Each face has exactly 42 preimages in 0–251, so rejection removes modulo bias, under the usual HMAC pseudorandomness assumption. The counter range is 0–4294967295 inclusive. If that entire space is exhausted without two accepted bytes, return a deterministic error; never wrap the counter, reuse blocks or substitute biased dice. The bounded sampler therefore has an explicit failure outcome even for pathological input, rather than claiming an unconditional mathematical guarantee of successful sampling.
Only the committed server seed, frozen client seeds, turn number and offer index affect the result. The position, game identifier, wall clock, command identifier and selected pair do not. The versioned domain separates this stream from the classic three-dice stream.
Published vectors and independent verifier
Section titled “Published vectors and independent verifier”Download the JSON vectors and dependency-free Python reference into the same directory. Every seed in that fixture is deliberately public synthetic test data. Run Python 3:
python3 laboratory-dice-v1.pyThe fixture pins commitments, canonical message bytes, first HMAC blocks, both pairs and the unchanged classic three-dice result. Cases include turn/seed/offer separation, seed-boundary ambiguity, UTF-8, embedded NUL, empty seeds, equal alternatives and a rejected leading byte. The Python reference was implemented independently of the Scala source. The Scala suite consumes the same published vectors and separately forces rejection, block refill and counter exhaustion. These are deterministic checks; no frequency test is used as proof of unbiasedness.
Verify a terminal transcript
Section titled “Verify a terminal transcript”- Retain the original pre-seed commitment and the frozen client seeds when joining the game. A commitment delivered only with a terminal export proves internal consistency, not that the server committed before receiving those seeds.
- Check the laboratory variant/revision, export schema and captured
provenance.diceAlgorithm. Dispatch by that exact version; do not silently apply the latest algorithm to old games. - Require a permitted terminal reveal and non-null
fairness. Decode itsserverSeed, check SHA-256 against bothfairness.commitand the retained initial commitment, and compare the effectivefairness.clientSeedswith the originally frozen values. An active game or missing terminal evidence is not publicly verifiable. - For each completed entry, in consecutive zero-based
turnNumberorder, call the reference’sderive_offers(bytes.fromhex(server_seed_hex), white, black, turn_number)and compare both alternatives in their original order. ConfirmselectedPairIndexis 0 or 1 anddiceequals that pair. An emptymoveslist is an explicit pass, not permission to omit the offers or increment twice. - Derive the next turn at
len(turns)for an in-flightcurrentTurn. A terminal projection may instead retain the just-completed turn’s offers and choice; when it exactly matches that last verified history entry, treat it as the same completed turn, not another roll. Compare only the 0–2 offers actually revealed in that public projection and its selection, if present. Never require an unrevealed alternative to have been published while the game was active. - Report dice verification separately from move legality, clocks, command ordering and whether
the game is complete. A technically aborted export stays
incompleteeven when its permitted seed reveal makes the recorded dice verifiable. Missing evidence must never become a claim of a complete verified game.
The room must generate and persist both private alternatives before revealing pair 1. It publishes
pair 2 only after accepting RollSecond, and publishes the server seed only under the terminal
reveal policy. Repeated commands and restoration derive identical pairs; they do not authorize
new public revelation. The source has no public encoder or HTTP endpoint.