@octane-rgs/rng

Provably fair RNG for Octane RGS. Pure HMAC-SHA256 float generation with zero dependencies beyond Node crypto.

This package contains only the derivation algorithm — no database, no HTTP, no side effects. It is shared between the RGS (which manages seed lifecycle) and maths engines (which generate floats locally from seed material).

Most maths engines should install @octane-rgs/engine instead, which re-exports everything from this package plus the settlement and round data client.

Install

npm install @octane-rgs/rng

Quick Start

import { createFloatGenerator, verify, hashSeed } from "@octane-rgs/rng";

// Create a generator from seed material
const gen = createFloatGenerator(serverSeed, clientSeed, nonce);

// Generate floats on demand — no limit, cursors auto-advance
const float = gen.generateFloat();        // single float in [0, 1)
const floats = gen.generateFloats(100);   // batch of 100 floats

// Also accepts a Seed object
const gen2 = createFloatGenerator({ serverSeed, clientSeed, nonce });

// Verify game outcomes (reproduce floats + get seed hash)
const { values, serverSeedHash } = verify(serverSeed, clientSeed, nonce, 10);

// Hash a server seed for commitment
const hash = hashSeed(serverSeed);

How it works

Each float is derived from HMAC-SHA256:

1. Compute HMAC-SHA256(serverSeed, clientSeed:nonce:cursor) → 32 bytes
2. Split into 8 chunks of 4 bytes, each read as a big-endian unsigned 32-bit integer
3. Divide by 2^32 to produce a uniform float in [0, 1)
4. Advance to the next cursor when all 8 floats from a digest are consumed

This produces a deterministic, unlimited stream of independent pseudo-random floats from a single seed.

API

| Function | Description | |----------|-------------| | createFloatGenerator(serverSeed, clientSeed, nonce) | Create a stateful generator yielding floats in [0, 1) | | createFloatGenerator(seed) | Same, accepts a Seed object | | verify(serverSeed, clientSeed, nonce, count) | Reproduce N floats + server seed hash for verification | | hashSeed(serverSeed) | SHA-256 hash of a server seed |

Types

| Type | Description | |------|-------------| | Seed | { serverSeed: string, clientSeed: string, nonce: number } | | FloatGenerator | { generateFloat(): number, generateFloats(count: number): number[] } | | VerifyResult | { values: number[], serverSeedHash: string } |