RAIN RNG — the whole chapter

Provable fairness is the headline. This document is the complete specification of the RAIN random-number ceremony: what it is, why it is built this way, how it is anchored on Arbitrum, how anyone verifies any round with nothing but a keccak tool, what it does not guarantee, and the licence terms for using it under the "Powered by RAIN RNG" badge.

Package: @rain/rng-core (zero dependencies, ESM + CJS, browser/Node/worker). Reference implementations: ChannelManagerAA 0x60743006c2a5Dd5b9907CA37e7381854ff860959, EngineV2RulesVerifier 0x5d6048AB261e6151AB44fE6053e7AEb35Cb5C1B1, GameMuxVerifier8 0xb72B38123CF3E5F2605f2EED99c53c6D8a331b25 on Arbitrum One (chain id 42161), and the engines running on playmarkets.bet and maycasino.xyz.

0. In one paragraph

Two parties — a house and a player — each commit in advance to a long list of secrets (a hash chain, 4,096 elements on-chain, 65,536 with rotation in @rain/rng-session 2.1) and to one session seed half. Both commitments are written on-chain when the session opens. Every round k consumes the next secret from both chains; the round's randomness is

r_k = keccak256(abi.encode(pRev_k, hRev_k, sessionSeed, channelId, k))

Because the house's secret for round k was fixed before the session started and the player's secret is unknown to the house until the player has already committed the bet, neither party can choose, predict or bias the outcome, and no third party is involved at all — no oracle, no VRF, no server seed you have to trust. Every field is public after the round, so anyone can recompute it.

1. Why two-party commit-reveal beats a VRF or an oracle

The key insight: randomness for money must be decided by the two parties whose money it is, and locked before either of them can act on it. A VRF gives you unpredictable numbers, but it puts a third party in the loop and does nothing about when the number is requested relative to the bet. Server seeds give you post-hoc auditing of a number the server already knew. RAIN combines a per-session seed (two-party commit-reveal, anchored on-chain) with per-round two-party hash-chain reveals, and — crucially — with an escrow whose money rules are enforced by the same contract, so "fair randomness" and "fair payment" are one system, not two.

2. The ceremony, step by step

2.1 Session open (once per login; on-chain)

1. House commits: picks a random houseSeed (32 bytes) and publishes houseSeedCommit = keccak256(abi.encode(houseSeed)) together with the session terms. Picks a chain secret and computes houseChainRoot = hashChain(secret, 4096)[0].

2. Player commits: derives playerSeed and a chain secret from wallet material (§2.4), computes playerChainRoot. Signs the EIP-712 OpenChannel(...) struct, which binds both playerSeed and houseSeedCommit — so the house cannot swap its commitment after seeing the player's seed.

3. On-chain (ChannelManagerAA.openChannel, submitted by the house, gas paid by the house): the contract checks keccak256(abi.encode(houseSeed)) == houseSeedCommit, verifies the player's signature (EOA or ERC-1271 smart account), derives

   channelId   = keccak256(abi.encode(address(manager), player, operator, uint64 openNonce, uint256 chainId))
   sessionSeed = keccak256(abi.encode(houseSeed, playerSeed, channelId))
   

   stores sessionSeed, playerChainRoot, houseChainRoot, and emits SessionSeedCommitReveal(channelId, houseSeed, playerSeed, sessionSeed). The channel is Active in the same transaction.

The player's client independently checks the commit and recomputes sessionSeed before accepting the open (crash-live-client.umd.js open()), and verifySessionSeed() in @rain/rng-core does the same from the event.

2.2 A round (every bet; off-chain, ~100 ms)

Cursor k is global per channel and shared by every game played inside it (dice, slots, Engine V2, craps…): reveals are never reused.

1. Bet: the player signs the successor channel state that moves stake from playerBal into escrow (grossAtRisk) and pins both parties' current anchors (pAnchor, hAnchor = the previous reveals, or the chain roots at k = 0). The player sends this signed BET state together with its own reveal pRev_{k+1}. The player has now committed money and secret without knowing hRev.
2. House: verifies the player's signature and keccak256(abi.encode(pRev)) == pAnchor; persists the BET state (fsync) and countersigns it → the bet is dual-signed. Only then reveals hRev_{k+1}, computes the settle state, signs it, replies with hRev + both countersignatures.
3. Player: checks keccak256(abi.encode(hRev)) == hAnchor (the house used the one and only allowed secret), recomputes the outcome locally, checks the house's SETTLE state equals its own, verifies the countersignatures, adopts the state, and acknowledges in the background. If anything mismatches, the client refuses and holds a dual-signed BET state → forceClose → HouseFault.

r_k  = keccak256(abi.encode(pRev_k, hRev_k, sessionSeed, channelId, uint256 k))        // canonical (quick games, craps)
seed = keccak256(abi.encode(pRev_k, hRev_k, sessionSeed, channelId, uint256 k, keccak256(bytes(gameId))))  // Engine V2 per-game domain
tick = keccak256(abi.encode(pRev_k, hRev_k, sessionSeed, channelId, uint32 roundId, uint32 k))             // Live Crash (per-round chains)

Reductions for the on-chain quick games are plain uint256(r) % N (dice N = 100, roulette N = 37), exactly as the Solidity verifiers do; modulo bias is < N / 2^256. New games use the v2.1 draw layer (§2.5).

2.5 The draw layer (v2.1): one RAIN seed per spin → DRBG → counter-derived draws

A slot spin needs many random values (reel stops, cascades, bonus picks). Instead of hashing per draw or truncating r to a 32-bit seed for a non-cryptographic generator, v2.1 derives all of a round's draws from r with a standard deterministic random bit generator — the layer a test lab certifies once for every game:

key       = HMAC-SHA-256(key = r, msg = "RAIN-RNG-v2.1|" + gameId)           // domain separation per game
hmac-drbg: draw(i) = HMAC_DRBG_SHA-256.Instantiate(entropy = key).Generate(32 bytes, additional_input = uint64be(i))   // SP 800-90A §10.1.2 (default)
chacha20:  draw(i) = ChaCha20Block(key, counter = i, nonce = 0^96)[0..32)                                             // RFC 8439 §2.3 (selectable)
uint32(i) = draw(i)[0..4) BE      uint53(i) = draw(i)[0..7) >> 3      float(i) = uint53(i) / 2^53
intBelow(i, n): v = uint32(i+j) for j = 0,1,…; accept the first v < 2^32 − (2^32 mod n); return v mod n     // unbiased (rejection)
shuffle(i, arr): Fisher–Yates using intBelow                                                                 // reels, decks

draw(i) is a pure function of (r, gameId, i, mechanism) — replayable by the player, the operator and the lab, in TypeScript (@rain/rng-core drbg()) or Python (rain_rng.drbg()), byte-identical (shared vectors). Known-answer tests: NIST CAVP HMAC_DRBG (32 cases), FIPS 180-4, RFC 4231, RFC 8439. Cost: ≈55 µs per HMAC-DRBG draw, ≈4.5 µs per ChaCha draw; a 3-reel spin ≈ 0.2 ms.

Reseed per round, never per session: every round k has a fresh 256-bit r_k; the DRBG state never spans rounds. Deprecated: seed32Compat(r) (r & 0xFFFFFFFF → xoshiro & co) is development-only and warns — 32 bits are not production-secure.

2.6 Latency, pipelining, rotation (@rain/rng-session 2.1)

• Pipelining: the client commits round k+1 while round k's animation plays (RainSpinClient.prefetch(); maxInFlight default 2 on both sides). The house persists in-flight commits concurrently; each pRev must chain to the previous accepted one. RNG work on the /spin critical path measured at p95 0.5 ms with a remote node at 40 ms RTT (examples/slot-spin-endpoint/loadtest.mjs).
• Chain rotation: default length 65,536; at 90 % consumed both sides run a fresh commit + reveal pair (rotateTerms → rotate → rotated), no chain transaction unless an anchoring adapter is wired in; rotation records are kept for audit and old proofs keep verifying.
• spinSeed(k): the whole ceremony for one round in one call → { r, k, proof, latencyMs, stream(gameId) }, for integrators who only want the seed. Transports: in-process, WebSocket, HTTP long-poll.

See docs/INTEGRATION-OPERATOR.md (builder guide) and docs/LAB-READINESS.md (GLI-19 §3 mapping).

2.3 Hash chains

c[n]   = keccak256(secret)                 // raw 32 bytes
c[i-1] = keccak256(abi.encode(c[i]))       // 32-byte word
root   = c[0]  (committed on-chain);  k-th reveal = c[k];  keccak256(abi.encode(c[k])) == c[k-1]

ChannelManagerAA.submitReveals enforces the same rule on-chain (BadProof otherwise) and advances cursorP / cursorH, so a party can be forced to publish its reveals: demandReveal(channelId, onPlayer, target) starts a 60 s window; silence is a fault. A 4096-chain gives 4095 rounds per channel; the bankroll layer rolls the channel (close + reopen) near exhaustion.

2.4 Player material — one wallet signature, ever

base            = keccak256(personal_sign("RAIN session key v1 for <manager> chainId <id>"))
sessionWalletPk = keccak256(base ‖ "session")               // burner key that signs channel states, cannot move funds
chainSecret_n   = keccak256(base ‖ "chain:<openNonce>")      // per channel
playerSeed_n    = keccak256(base ‖ "seed:<openNonce>")       // per channel, public half of the session seed

Deterministic (RFC-6979 signatures), so the same wallet always re-derives the same secrets on any device — the player never has to back anything up, and the house never learns base. Payouts go only to the wallet (playerOwner); the session key can only sign game states.

3. Threat model

4. On-chain anchors (what to look at on Arbiscan)

5. Verify any round yourself (no RAIN software)

You need the fairness-panel fields channelId, sessionSeed, k, pRev, hRev (and gameId for Engine V2), plus any keccak256 tool.

1. Session seed: open the channel's openChannel tx on Arbiscan → Logs → SessionSeedCommitReveal. Check keccak256(abi.encode(houseSeed, playerSeed, channelId)) == sessionSeed. (cast keccak $(cast abi-encode "f(bytes32,bytes32,bytes32)" $H $P $C))
2. House did not swap seeds: the houseSeedCommit shown in the house's terms (and in your signed OpenChannel struct) must equal keccak256(abi.encode(houseSeed)).
3. House reveal is the committed one: keccak256(abi.encode(hRev_k)) == hAnchor where hAnchor is the hRev_{k-1} from the previous round (or houseChainRoot from channels(channelId) at k = 1). Or hash hRev_k k times and compare with houseChainRoot.
4. Outcome: r = keccak256(abi.encode(pRev, hRev, sessionSeed, channelId, k)) (five 32-byte words; k is uint256). Dice: roll = r % 100 + 1. Roulette: n = r % 37. Engine V2: append keccak256("foundry") (etc.) as a sixth word and run the published engine.
5. Compare with what you were shown. Any discrepancy is a provable misreport.

With the SDK this is one call:

import { verifyRound, verifySessionSeed } from "@rain/rng-core";
verifyRound({ pRev, hRev, sessionSeed, channelId, k, N: 100, expected: roll - 1, hAnchor }).ok; // true ⇢ VERIFIED

6. Using RAIN RNG in your own product

• You run the house (@rain/rng-session): RainRngHouse keeps the chain and enforces persist-before-reveal; RainRngClient keeps the player chain and enforces decision-before-reveal. Transport is yours (WebSocket, HTTP, in-process, Nostr…). Optional RngAnchor contract to publish commitments on any EVM chain.
• You only need numbers (e.g. an AI agent or a Stake-style casino): @rain/rng-core alone — 40 lines to a provably fair dice game (examples/agent-dice).
• You run a slot server (operator = party A, RAIN node = party B): RainSpinClient.spinSeed() → drbg(r, gameId) → your math — examples/slot-spin-endpoint, docs/INTEGRATION-OPERATOR.md. Python servers: packages/rng-py.
• You want the whole casino protocol (escrow, fault compensation, fraud proofs): @rain/channels + @rain/games on the live ChannelManagerAA.

7. Limits — honest, pre-audit

1. No external smart-contract audit yet. Internal review only (rain-risk-markets/AUDIT.md). Do not run real money at scale before one.
2. Fairness is per round, not statistical. The system guarantees no party could bias any single round; it does not prove that the published RTP is what you experienced — that is a property of the (public, verifiable) payout tables and the law of large numbers, not of the RNG.
3. Hybrid games (Engine V2 slots) are hash-committed, not re-executed on-chain. Misreports are detectable by anyone with the open engine bundle and are punished via the client's refusal path, but a player using a malicious client that signs whatever the house says has no on-chain protection for that step.
4. Liveness ≠ safety. A house that goes offline cannot steal, but you must submit forceClose and wait a challenge window (10 min / 24 h) to exit.
5. Selective abort at open is possible for either party (just don't open); it gains nothing because the session seed predicts no outcome, but it is a UX nuisance a house could inflict.
6. Admin keys. ChannelManagerAA.setVerifier / setOperator / setPaused are owner-controlled on the live deployment (needed for pre-audit iteration). They cannot alter an open channel's seed or roots, but a malicious owner could pause opens or point disputes at a broken verifier. Timelock/multisig before real money.
7. The house node is not yet a packaged operator binary. @rain/rng-session gives you the ceremony; the full live house node (WebSocket protocol, WAL, bond management) is Playmarket-internal for now — see README.md § Gaps.
8. Modulo reduction, not rejection sampling, for the on-chain quick games — by design (byte-identity with the verifiers). Bias is < N / 2^256, irrelevant for any N ≤ 2^64. The v2.1 draw layer (§2.5) uses rejection sampling.
9. Not lab-certified. The draw layer uses standard mechanisms with KATs, but no test lab has evaluated it — docs/LAB-READINESS.md lists what a lab still has to do.

8. Attribution licence

@rain/rng-core, @rain/rng-session and the RNG chapter of this SDK are licensed MIT with an attribution condition (see /LICENSE). In plain words:

Any product, service, game or agent that is exposed to third parties and uses this RNG (in whole or in part, modified or not) must display the text "Powered by RAIN RNG" with a hyperlink to https://www.playmarkets.bet/fairness in a place its users can see (fairness panel, footer, about page, README of a public repo, or the model card / tool description of an AI agent). badge() in @rain/rng-core returns ready-made HTML, Markdown and SVG.

This is a licence term, not a request: use without the attribution is use outside the licence. Internal, private, or evaluation use needs no badge. You may not imply RAIN endorses your product, and you may not present the RNG as your own invention.

Reference: ChannelManagerAA.sol (V4 seed ceremony header comment), EngineV2RulesVerifier.sol, docs/whitelabel/PROVABLE-FAIRNESS.md, docs/CHANNEL-GAMES.md §1–§8, rain-risk-markets/AUDIT.md. Test vectors in packages/rng-core/test/vectors.json are generated from the live FE engines by scripts/gen-vectors.mjs; npm run test:live re-checks them against the deployed verifier and live channels on Arbitrum.