shufflecom-calculations 2.2.32 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shufflecom-calculations",
-  "version": "2.2.32",
+  "version": "2.3.0",
   "description": "",
   "types": "lib/index.d.ts",
   "main": "lib/index.js",
@@ -14,5 +14,5 @@
   },
   "author": "",
   "license": "ISC",
-  "gitHead": "7df79f5b309a3e52bcb255c2341cda860b8644c2"
+  "gitHead": "337880d365f72dfd40af9bffce3e99f3ff9e9f58"
 }

package/src/games/chicken.spec.ts

@@ -0,0 +1,102 @@
+import { Chicken, ChickenDifficulty } from './chicken';
+import { GameCalculation } from './gameCalculation';
+
+const edgeBps = 200;
+
+const resultMultipliers = {
+  [ChickenDifficulty.EASY]: [1.03, 1.09, 1.15, 1.23, 1.31, 1.4, 1.51, 1.63, 1.78, 1.96, 2.18, 2.45, 2.8, 3.27, 3.92, 4.9, 6.53, 9.8, 19.6],
+  [ChickenDifficulty.MEDIUM]: [1.15, 1.37, 1.64, 2.0, 2.46, 3.07, 3.91, 5.08, 6.77, 9.31, 13.3, 19.95, 31.92, 55.86, 111.72, 279.3, 1117.2],
+  [ChickenDifficulty.HARD]: [1.31, 1.77, 2.46, 3.48, 5.06, 7.59, 11.81, 19.18, 32.89, 60.29, 120.59, 271.32, 723.52, 2532.32, 15193.92],
+  [ChickenDifficulty.EXPERT]: [1.96, 4.14, 9.31, 22.61, 60.29, 180.88, 633.08, 2743.35, 16460.08, 181060.88],
+};
+
+describe('Chicken', () => {
+  it('should calculate the correct multiplier', () => {
+    Object.keys(resultMultipliers).forEach(difficulty => {
+      const multiplierArr = resultMultipliers[difficulty as ChickenDifficulty];
+      multiplierArr.forEach((multiplier, index) => {
+        expect(Chicken.calculateMultiplierBN(difficulty as ChickenDifficulty, index, edgeBps).toFixed(2)).toBe(multiplier.toFixed(2));
+      });
+    });
+  });
+
+  it('chicken provably fair', () => {
+    const gameSeeds = [
+      {
+        serverSeed: 'da5a4cd5eca04d91d36569207265bd79d2989a19378eea897399755f2c9b83e6',
+        clientSeed: '7qkHqOhx-F',
+        nonce: '1',
+        rounds: Chicken.DIFFICULTY_TO_HEX_ROUNDS[ChickenDifficulty.EASY],
+        difficulty: ChickenDifficulty.EASY,
+        results: [1],
+      },
+      {
+        serverSeed: 'db9e7314084e5dd9335424abccd3277903e238d0160b82ea8b82439e1935c202',
+        clientSeed: '7bsnudbuu5',
+        nonce: '6',
+        rounds: Chicken.DIFFICULTY_TO_HEX_ROUNDS[ChickenDifficulty.EASY],
+        difficulty: ChickenDifficulty.EASY,
+        results: [8],
+      },
+      {
+        serverSeed: '779ddeb1e84ef941e25f495cd2d5a011b3be8a8024192a276d332aad5925175f',
+        clientSeed: '92p9csrt50',
+        nonce: '13',
+        rounds: Chicken.DIFFICULTY_TO_HEX_ROUNDS[ChickenDifficulty.MEDIUM],
+        difficulty: ChickenDifficulty.MEDIUM,
+        results: [16, 19, 17],
+      },
+      {
+        serverSeed: 'ebd3ff712ee7ed3cabe3753146f95847b017f847758ed254c531ff0d45686cea',
+        clientSeed: 'pf4jl5q97q',
+        nonce: '13',
+        rounds: Chicken.DIFFICULTY_TO_HEX_ROUNDS[ChickenDifficulty.MEDIUM],
+        difficulty: ChickenDifficulty.MEDIUM,
+        results: [9, 3, 13],
+      },
+      {
+        serverSeed: 'da5a4cd5eca04d91d36569207265bd79d2989a19378eea897399755f2c9b83e6',
+        clientSeed: '7qkHqOhxLF',
+        nonce: '27',
+        rounds: Chicken.DIFFICULTY_TO_HEX_ROUNDS[ChickenDifficulty.HARD],
+        difficulty: ChickenDifficulty.HARD,
+        results: [12, 0, 14, 17, 18],
+      },
+      {
+        serverSeed: '9b0499f7abbebf3ea889e3f958d1bc2d77c514792143d07dc66378711f7eb313',
+        clientSeed: '92p9csrt50',
+        nonce: '30',
+        rounds: Chicken.DIFFICULTY_TO_HEX_ROUNDS[ChickenDifficulty.HARD],
+        difficulty: ChickenDifficulty.HARD,
+        results: [9, 18, 16, 13, 7],
+      },
+      {
+        serverSeed: '9b0499f7abbebf3ea889e3f958d1bc2d77c514792143d07dc66378711f7eb313',
+        clientSeed: '7bsnudbuu5',
+        nonce: '35',
+        rounds: Chicken.DIFFICULTY_TO_HEX_ROUNDS[ChickenDifficulty.EXPERT],
+        difficulty: ChickenDifficulty.EXPERT,
+        results: [12, 10, 18, 14, 11, 6, 13, 15, 3, 9],
+      },
+      {
+        serverSeed: '779ddeb1e84ef941e25f495cd2d5a011b3be8a8024192a276d332aad5925175f',
+        clientSeed: 'pf4jl5q97q',
+        nonce: '40',
+        rounds: Chicken.DIFFICULTY_TO_HEX_ROUNDS[ChickenDifficulty.EXPERT],
+        difficulty: ChickenDifficulty.EXPERT,
+        results: [5, 2, 10, 18, 3, 7, 12, 19, 11, 14],
+      },
+    ];
+
+    gameSeeds.forEach(e => {
+      const resultHex = GameCalculation.generateDigestHex({
+        serverSeed: e.serverSeed,
+        clientSeed: e.clientSeed,
+        nonce: e.nonce,
+        rounds: e.rounds,
+      });
+      const results = Chicken.getResults(resultHex, e.difficulty);
+      expect(results).toEqual(e.results);
+    });
+  });
+});

package/src/games/chicken.ts

@@ -0,0 +1,59 @@
+import BigNumber from 'bignumber.js';
+import { calculateEdgeMultiplier } from '../utils/edge';
+import { nCr } from '../utils/ncr';
+import { GameCalculation } from './gameCalculation';
+
+export enum ChickenDifficulty {
+  EASY = 'EASY',
+  MEDIUM = 'MEDIUM',
+  HARD = 'HARD',
+  EXPERT = 'EXPERT',
+}
+
+export class Chicken extends GameCalculation {
+  static readonly TOTAL_LANES = 20;
+
+  static readonly DIFFICULTY_TO_VALID_LANE_COUNT: Record<ChickenDifficulty, number> = {
+    [ChickenDifficulty.EASY]: 19,
+    [ChickenDifficulty.MEDIUM]: 17,
+    [ChickenDifficulty.HARD]: 15,
+    [ChickenDifficulty.EXPERT]: 10,
+  };
+
+  static readonly DIFFICULTY_TO_HEX_ROUNDS: Record<ChickenDifficulty, number> = {
+    [ChickenDifficulty.EASY]: 1,
+    [ChickenDifficulty.MEDIUM]: 1,
+    [ChickenDifficulty.HARD]: 1,
+    [ChickenDifficulty.EXPERT]: 2,
+  };
+
+  static getResults(hexStr: string[], difficulty: ChickenDifficulty): number[] {
+    const losingLaneCount = this.TOTAL_LANES - this.DIFFICULTY_TO_VALID_LANE_COUNT[difficulty];
+
+    return this.pickUniqueNumbers(hexStr, losingLaneCount, this.TOTAL_LANES);
+  }
+
+  static calculateWinChanceBN(difficulty: ChickenDifficulty, selectedLane: number): BigNumber {
+    const validLanes = this.DIFFICULTY_TO_VALID_LANE_COUNT[difficulty];
+    const selectedLaneCount = selectedLane + 1; // selectedLane is 0-indexed
+
+    return nCr(validLanes, selectedLaneCount).dividedBy(nCr(this.TOTAL_LANES, selectedLaneCount));
+  }
+
+  static calculateMultiplierBN(difficulty: ChickenDifficulty, selectedLane: number, edgeBps: number): BigNumber {
+    const winChance = this.calculateWinChanceBN(difficulty, selectedLane);
+
+    return calculateEdgeMultiplier(edgeBps).div(winChance);
+  }
+
+  static firstDeathLane(results: number[]): number {
+    if (results.length === 0) {
+      throw new Error('Results array is empty, cannot determine first death lane.');
+    }
+    return Math.min(...results);
+  }
+
+  static isLoss(results: number[], selected: number): boolean {
+    return selected >= this.firstDeathLane(results);
+  }
+}

package/src/games/gameCalculation.ts

@@ -0,0 +1,153 @@
+import BigNumber from 'bignumber.js';
+import { hexToBytes } from '../utils/hex-to-bytes';
+import { createHmac } from 'crypto';
+
+export abstract class GameCalculation {
+  private static readonly BYTE_TOTAL = new BigNumber(256);
+  private static readonly BYTES_PER_HEX_STRING = 32;
+  private static readonly BYTES_PER_RANDOM_NUMBER = 4;
+  private static readonly NUMBERS_PER_HEX_STRING = 8;
+
+  /**
+   * Convert 4 consecutive bytes to a probability in [0, 1)
+   * This is the foundation of all randomness
+   *
+   * @param byteArray - The full byte array (Uint8Array)
+   * @param startIndex - Starting position to read 4 bytes from
+   * @returns A probability value between 0 (inclusive) and 1 (exclusive)
+   */
+  private static bytesToProbability(byteArray: Uint8Array, startIndex: number): BigNumber {
+    let probability = new BigNumber(0);
+
+    // Read 4 consecutive bytes starting at startIndex
+    for (let i = 0; i < this.BYTES_PER_RANDOM_NUMBER; i++) {
+      const byteValue = byteArray[startIndex + i];
+      probability = probability.plus(new BigNumber(byteValue).dividedBy(this.BYTE_TOTAL.pow(i + 1)));
+    }
+
+    return probability;
+  }
+
+  /**
+   * Generate a random integer in range [0, maxValue)
+   *
+   * @param byteArray - The full byte array
+   * @param startIndex - Starting position to read 4 bytes from
+   * @param maxValue - Upper bound (exclusive)
+   * @returns Random integer in [0, maxValue)
+   */
+  private static getRandomInt(byteArray: Uint8Array, startIndex: number, maxValue: number): number {
+    const probability = this.bytesToProbability(byteArray, startIndex);
+    return probability.multipliedBy(maxValue).integerValue(BigNumber.ROUND_DOWN).toNumber();
+  }
+
+  /**
+   * Pick N unique numbers from a pool (Fisher-Yates shuffle / sampling without replacement)
+   *
+   * How it works:
+   * 1. Start with pool: [0, 1, 2, ..., poolSize-1]
+   * 2. Generate random position in remaining pool
+   * 3. Pick number at that position and REMOVE it from pool
+   * 4. Repeat until we have N unique numbers
+   *
+   * @param hexStrings - Array of hex strings for randomness
+   * @param count - How many unique numbers to pick
+   * @param poolSize - Size of the pool to pick from (0 to poolSize-1)
+   * @returns Array of unique numbers
+   */
+  static pickUniqueNumbers(hexStrings: string[], count: number, poolSize: number): number[] {
+    const bytesAvailable = hexStrings.length * this.BYTES_PER_HEX_STRING;
+    const bytesNeeded = count * this.BYTES_PER_RANDOM_NUMBER;
+    if (bytesAvailable < bytesNeeded) {
+      throw new Error(`Not enough randomness: need ${bytesNeeded} bytes for ${count} numbers, only have ${bytesAvailable} bytes`);
+    }
+
+    const results: number[] = [];
+    const pool = Array.from({ length: poolSize }, (_, i) => i);
+
+    const byteArrays = hexStrings.map(hexToBytes);
+
+    for (let hexIndex = 0; hexIndex < byteArrays.length; hexIndex++) {
+      const byteArray = byteArrays[hexIndex];
+
+      // Each hex string can generate up to 8 numbers (32 bytes / 4 bytes per number)
+      for (let numberIndex = 0; numberIndex < this.NUMBERS_PER_HEX_STRING; numberIndex++) {
+        if (results.length >= count) {
+          return results;
+        }
+
+        const byteOffset = numberIndex * this.BYTES_PER_RANDOM_NUMBER;
+        const remainingPoolSize = pool.length;
+        const randomPosition = this.getRandomInt(byteArray, byteOffset, remainingPoolSize);
+
+        const pickedNumber = pool.splice(randomPosition, 1)[0];
+        results.push(pickedNumber);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Generate N independent random numbers (duplicates allowed)
+   *
+   * Each number is generated independently - the pool doesn't shrink.
+   * Same number can appear multiple times.
+   *
+   *
+   * @param hexStrings - Array of hex strings for randomness
+   * @param count - How many random numbers to generate
+   * @param maxValue - Upper bound (exclusive) for each number
+   * @returns Array of random numbers (may contain duplicates)
+   */
+  static generateIndependentNumbers(hexStrings: string[], count: number, maxValue: number): number[] {
+    const bytesAvailable = hexStrings.length * this.BYTES_PER_HEX_STRING;
+    const bytesNeeded = count * this.BYTES_PER_RANDOM_NUMBER;
+    if (bytesAvailable < bytesNeeded) {
+      throw new Error(`Not enough randomness: need ${bytesNeeded} bytes for ${count} numbers, only have ${bytesAvailable} bytes`);
+    }
+
+    const results: number[] = [];
+    const byteArrays = hexStrings.map(hexToBytes);
+
+    for (let hexIndex = 0; hexIndex < byteArrays.length; hexIndex++) {
+      const byteArray = byteArrays[hexIndex];
+
+      for (let numberIndex = 0; numberIndex < this.NUMBERS_PER_HEX_STRING; numberIndex++) {
+        if (results.length >= count) {
+          return results;
+        }
+
+        const byteOffset = numberIndex * this.BYTES_PER_RANDOM_NUMBER;
+        const randomNumber = this.getRandomInt(byteArray, byteOffset, maxValue);
+        results.push(randomNumber);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Generate provably fair random hex strings using HMAC-SHA256
+   *
+   * @param serverSeed - Secret server seed (revealed after game/rotation)
+   * @param clientSeed - Player-provided seed for transparency
+   * @param nonce - Sequential number that increments with each bet
+   * @param rounds - How many hex strings to generate (each = 32 bytes of randomness)
+   * @returns Array of hex strings, each representing 32 bytes of cryptographic randomness
+   */
+  static generateDigestHex({
+    serverSeed,
+    clientSeed,
+    nonce,
+    rounds,
+  }: { serverSeed: string; clientSeed: string; nonce: string; rounds: number }): string[] {
+    const results = Array.from(Array(rounds).keys()).map(round => {
+      const hmac = createHmac('sha256', serverSeed);
+      hmac.update(`${clientSeed}:${nonce}:${round}`);
+      return hmac.digest('hex');
+    });
+
+    return results;
+  }
+}