NoctaFair

Provably fair random number generator for gaming applications using NoctaHash.

Overview

NoctaFair provides cryptographically secure, provably fair random number generation for games and applications. It uses NoctaHash (a memory-hard hashing algorithm) to ensure that random outcomes cannot be predicted or manipulated.

Key Features

• Provably Fair: All random outcomes can be verified using cryptographic proofs
• Memory-Hard: Resistant to GPU/ASIC optimizations
• Deterministic: Same seed produces same sequence (for testing/replay)
• Gaming-Ready: Built-in functions for dice, cards, loot boxes, and more
• Verifiable: Anyone can verify the fairness of any random outcome

Installation

npm install noctafair

Note: Requires noctahash package (already published on npm).

Quick Start

const FairRandom = require('noctafair');

// Create a random number generator
const rng = new FairRandom();

// Generate random numbers
const random = rng.random();           // 0.0 to 1.0
const dice = rng.randomInt(1, 6);     // 1 to 6
const float = rng.randomFloat(5, 10); // 5.0 to 10.0

// Choose from array
const item = rng.choice(['sword', 'shield', 'potion']);

// Shuffle array
const deck = rng.shuffle([1, 2, 3, 4, 5]);

Usage Examples

Dice Game

const FairRandom = require('noctafair');
const rng = new FairRandom();

// Roll a 6-sided die
const roll = rng.randomInt(1, 6);
console.log(`You rolled: ${roll}`);

Card Shuffle

const deck = ['A♠', 'K♠', 'Q♠', 'J♠', '10♠'];
const shuffled = rng.shuffle(deck);
console.log('Shuffled deck:', shuffled);

Loot Box with Weights

const lootTable = [
  { name: 'Common', weight: 50 },
  { name: 'Rare', weight: 30 },
  { name: 'Epic', weight: 15 },
  { name: 'Legendary', weight: 5 }
];

const weights = lootTable.map(item => item.weight);
const index = rng.weightedChoice(weights);
const reward = lootTable[index];
console.log(`You got: ${reward.name}`);

Provably Fair Gaming

// Generate proof for a game outcome
const gameState = 'player-123-game-456';
const proof = rng.getProof(gameState);

// Later, anyone can verify this outcome
const roll = rng.randomInt(1, 100);
const isValid = rng.verify(
  proof.seed,
  proof.gameState,
  proof.counter,
  proof.hash
);

console.log(`Roll: ${roll}, Verified: ${isValid}`);

API Reference

Constructor

const rng = new FairRandom(seed, options);

• seed (optional): Initial seed (Uint8Array or hex string). If not provided, a random seed is generated.
• options (optional): Configuration object:
  • memory_cost: Memory cost in KB (default: 16384)
  • time_cost: Time cost (default: 2)
  • parallelism: Parallelism factor (default: 2)

Methods

random()

Returns a random float between 0.0 (inclusive) and 1.0 (exclusive).

const value = rng.random(); // 0.0 to 1.0

randomInt(min, max)

Returns a random integer between min (inclusive) and max (inclusive).

const dice = rng.randomInt(1, 6); // 1, 2, 3, 4, 5, or 6

randomFloat(min, max)

Returns a random float between min (inclusive) and max (exclusive).

const price = rng.randomFloat(10.5, 99.9);

choice(array)

Returns a random element from an array.

const item = rng.choice(['sword', 'shield', 'potion']);

shuffle(array)

Returns a shuffled copy of an array (Fisher-Yates algorithm).

const shuffled = rng.shuffle([1, 2, 3, 4, 5]);

weightedChoice(weights)

Returns an index based on weighted probabilities.

const weights = [10, 20, 30, 40]; // 10%, 20%, 30%, 40%
const index = rng.weightedChoice(weights);

getProof(gameState)

Generates a cryptographic proof for a game state.

const proof = rng.getProof('game-123');
// Returns: { seed, gameState, counter, hash, options }

verify(seed, gameState, counter, expectedHash)

Verifies a cryptographic proof.

const isValid = rng.verify(seed, gameState, counter, hash);

setSeed(seed)

Sets a new seed (resets state).

rng.setSeed('my-seed-123');

getSeed()

Returns the current seed as a hex string.

const seed = rng.getSeed();

Examples

See the examples/ directory for complete examples:

• dice-game.js - Simple dice rolling
• card-shuffle.js - Card deck shuffling
• loot-box.js - Weighted loot box system
• slot-machine.js - Slot machine simulation

Run examples:

npm run example
# or
node examples/dice-game.js

Testing

npm test

How It Works

1. Seed Generation: A cryptographically secure seed is generated (or provided)
2. State Management: Each random call updates the internal state
3. Hash Generation: NoctaHash is used to generate deterministic, unpredictable hashes
4. Number Extraction: Hash values are converted to random numbers
5. Proof Generation: Cryptographic proofs allow verification of fairness

Security Considerations

• Memory-Hard: NoctaHash is designed to resist GPU/ASIC optimizations
• Deterministic: Same seed + same sequence = same results (for verification)
• Unpredictable: Without the seed, future outcomes cannot be predicted
• Verifiable: All outcomes can be cryptographically verified

Use Cases

• Online Casinos: Provably fair dice, roulette, slots
• Gaming: Loot boxes, random drops, procedural generation
• Blockchain: Fair random number generation for smart contracts
• Lotteries: Transparent, verifiable random selection
• Cryptography: Secure random number generation

License

MIT

Author

Tuna4L (@Tuna4LL)

Related Projects

• NoctaHash - Memory-hard password hashing
• SafeCrypt - Triple-layer password hashing