probably-fair

Provably fair gaming module for casino platforms. Shared NPM package for server seed, client seed, nonce (custom, EOS block height, or BSC block height), deterministic random number generation, and verification.

Important: Never log or expose the server seed. Only its hash is shown before the round; the seed is revealed after settlement for verification.

Install

npm install probably-fair

Algorithm (summary)

1. Commit: Before the round, show getServerSeedHash(serverSeed) to the user.
2. Message: HMAC-SHA256 uses server seed as key and clientSeed:nonce[:A:B:...] as message (optional extra params A, B, …).
3. Result: The 32-byte HMAC is converted to float(s) in [0,1] and optionally scaled to a range (e.g. dice 1–6).
4. Verify: After the round, reveal the server seed; the user checks that hash(serverSeed) equals the committed hash and that recomputing with the same client seed, nonce, and extra params yields the same result.

API

Core (no network)

• getServerSeedHash(serverSeed: string): string
  Returns SHA-256 hash of the server seed (pre-commitment).

• getClientSeed(): string
  Returns the current client seed from the optional in-memory store.

• setClientSeed(seed: string): void
  Sets the client seed in the optional in-memory store. You can also pass the client seed explicitly into other functions.

• getNonce(options: NonceSource): number
  Returns the numeric nonce. Options:

  • { type: 'custom', value: number }
  • { type: 'eos', blockHeight: number }
  • { type: 'bsc', blockHeight: number }

• generateRandomNumber(serverSeed, clientSeed, nonce, extraParams?, options?): number | number[]
  Deterministic random number(s).

  • nonce: NonceSource object or a number.
  • extraParams: optional [A, B, ...] (string or number) included in the HMAC message so the result is bound to these parameters.
  • options: optional { min, max, count, integer } to scale and shape the output (defaults: one float in [0,1]).

• verifyFairness(serverSeed, clientSeed, nonce, committedServerSeedHash, expectedResult, extraParams?, options?): VerifyResult
  Recomputes the result and checks that the server seed hash matches.
  Pass the same extraParams and options you used when generating the result.

Optional block fetchers (network)

Use when the nonce is EOS or BSC block height and you want to fetch it from RPC:

import { getEosBlockHeight, getBscBlockHeight } from 'probably-fair/block-fetchers';

const eosBlock = await getEosBlockHeight(); // default RPC or pass URL
const bscBlock = await getBscBlockHeight();
// Then: getNonce({ type: 'eos', blockHeight: eosBlock }) or type: 'bsc', blockHeight: bscBlock

You can also obtain block height from your own backend and pass it into getNonce without using these fetchers.

Usage examples

const {
  getServerSeedHash,
  setClientSeed,
  getNonce,
  generateRandomNumber,
  verifyFairness,
} = require('probably-fair');

const serverSeed = 'my-secret-server-seed';
const clientSeed = 'user-client-seed';
const nonce = getNonce({ type: 'custom', value: 0 });

// Before round: show only the hash
const committedHash = getServerSeedHash(serverSeed);

// Generate result (e.g. dice 1–6)
const roll = generateRandomNumber(serverSeed, clientSeed, nonce, undefined, {
  min: 1,
  max: 6,
  integer: true,
});

// With extra parameters [A, B, ...]
const custom = generateRandomNumber(serverSeed, clientSeed, nonce, [10, 20], {
  min: 0,
  max: 99,
  integer: true,
});

// After round: verify
const verification = verifyFairness(
  serverSeed,
  clientSeed,
  nonce,
  committedHash,
  roll
);
console.log(verification.isFair); // true

Types

• NonceSource – { type: 'custom', value } | { type: 'eos', blockHeight } | { type: 'bsc', blockHeight }
• VerifyResult – { resultMatches, serverSeedHashMatches, isFair, computedResult? }
• RandomNumberOptions – { min?, max?, count?, integer? }

Tests

npm test

License

MIT