🎲 Provably Fair

A TypeScript framework designed to deterministically generate and independently verify Provably Fair game outcomes using cryptographic proofs, verifiable randomness, and deterministic replay logic to ensure transparency and auditability.

✨ Features

• ✅ Verifiable randomness generated via ECVRF ensuring cryptographic integrity
• 🔐 Robust public/private key proof system enabling independent outcome verification
• 🔁 Deterministic replay mechanism supporting reproducible game sessions
• 🔄 Generation of unique, non-repeating random numbers preventing manipulation
• 🧹 Modular and extensible architecture facilitating rigorous security reviews and compliance

📦 Installation

npm install @betorigami/provably-fair

🧠 Core Concepts

Seed Generation

A deterministic seed is generated using the following values:

• gameId: A unique identifier used to identify the game being played.
• tenantId: A unique identifier representing the tenant serving the game.
• tenantUserId: A unique identifier for the tenant's user participating in the game.
• nonce: An incrementing counter that changes with every completed game round to ensure uniqueness.
• clientSeed: A user-supplied value that introduces user-controlled entropy into the outcome.

This combination guarantees that each seed is unique and reproducible for every game session, enabling transparent and consistent randomness.

Proof Generation and Verification

• The generated seed is cryptographically signed using the server's private key to produce a proofString.
• This proof can be independently verified using the corresponding public key, ensuring the integrity of the randomness.
• The verified proof then seeds a deterministic random byte generator (hashSequence), which drives the game outcome.

📚 Standards and Cryptographic Foundations

This Provably Fair SDK adheres strictly to the Elliptic Curve Verifiable Random Function (ECVRF) specification as defined in the IETF draft draft-irtf-cfrg-vrf-15. The ECVRF protocol provides a rigorous, cryptographically secure method for generating verifiable randomness.

Key Points of the Specification

• Provable Unpredictability: The VRF output is unpredictable without the private key, ensuring fair randomness.
• Verifiability: Each random output includes a proof verifiable with the public key, preventing tampering.
• Deterministic: The VRF output is deterministic for a given input and private key, enabling reproducible audits.

Implementation Details

While this SDK itself is written in TypeScript, the core cryptographic operations leverage the fastcrypto Rust library (documented here) via NAPI-RS, which compiles Rust code into Node.js binaries:

• This integration provides a secure, high-performance ECVRF implementation.
• Rust's memory safety and fastcrypto's cryptographic rigor ensure robustness.
• Using NAPI-RS allows seamless Node.js interoperability without sacrificing security or speed.

🔒 Security Notes

• The private key must never be exposed to clients or external systems.
• Result generation using the private key should occur exclusively on secure server environments.
• The public key is safe for client-side use to independently verify game outcomes.
• All generated results are deterministic, verifiable, and tamper-proof, providing a strong audit trail and ensuring fairness.