shufflecom-calculations 3.3.12 → 3.3.14

package/src/games/coinflip/coinflip-rules.spec.ts

@@ -0,0 +1,193 @@
+import BigNumber from 'bignumber.js';
+import { FixedSequenceRng } from '../fixed-rng';
+import {
+  CoinflipProgressiveCashoutAction,
+  CoinflipProgressiveCoinSelectionAction,
+  CoinflipProgressiveStartAction,
+} from './coinflip-classic-progressive';
+import { CoinflipRules } from './coinflip-rules';
+import { CoinSide, MAX_FLIPS } from './constants';
+
+const EDGE_BPS = 200;
+
+describe('CoinflipRules.getFlipResults', () => {
+  it('maps 0 to heads and 1 to tails', () => {
+    const rng = new FixedSequenceRng([0, 1, 0, 1]);
+    expect(CoinflipRules.getFlipResults(rng, 4)).toEqual([CoinSide.HEADS, CoinSide.TAILS, CoinSide.HEADS, CoinSide.TAILS]);
+  });
+
+  it('returns exactly the requested number of flips', () => {
+    const rng = new FixedSequenceRng([0, 1, 0, 1, 0]);
+    expect(CoinflipRules.getFlipResults(rng, 2)).toHaveLength(2);
+  });
+
+  it('throws when count is below 1', () => {
+    const rng = new FixedSequenceRng([0]);
+    expect(() => CoinflipRules.getFlipResults(rng, 0)).toThrow();
+  });
+
+  it('throws when count exceeds MAX_FLIPS', () => {
+    const rng = new FixedSequenceRng(Array(MAX_FLIPS + 1).fill(0));
+    expect(() => CoinflipRules.getFlipResults(rng, MAX_FLIPS + 1)).toThrow();
+  });
+
+  it('throws when the generator returns fewer values than requested', () => {
+    const rng = new FixedSequenceRng([0]);
+    expect(() => CoinflipRules.getFlipResults(rng, 2)).toThrow();
+  });
+
+  it('throws when the generator returns a value outside 0 and 1', () => {
+    const rng = new FixedSequenceRng([2]);
+    expect(() => CoinflipRules.getFlipResults(rng, 1)).toThrow();
+  });
+});
+
+describe('CoinflipRules.isFlipWin', () => {
+  it('returns true when the flip matches the selected side', () => {
+    expect(CoinflipRules.isFlipWin(CoinSide.HEADS, CoinSide.HEADS)).toBe(true);
+    expect(CoinflipRules.isFlipWin(CoinSide.TAILS, CoinSide.TAILS)).toBe(true);
+  });
+
+  it('returns false when the flip does not match', () => {
+    expect(CoinflipRules.isFlipWin(CoinSide.HEADS, CoinSide.TAILS)).toBe(false);
+    expect(CoinflipRules.isFlipWin(CoinSide.TAILS, CoinSide.HEADS)).toBe(false);
+  });
+});
+
+describe('CoinflipRules.countSuccessfulFlips', () => {
+  it('counts only flips where result matches selectedSide', () => {
+    const flips = [
+      { result: CoinSide.HEADS, selectedSide: CoinSide.HEADS },
+      { result: CoinSide.TAILS, selectedSide: CoinSide.HEADS },
+      { result: CoinSide.HEADS, selectedSide: CoinSide.HEADS },
+      { result: CoinSide.HEADS, selectedSide: CoinSide.HEADS },
+    ];
+    expect(CoinflipRules.countSuccessfulFlips(flips)).toBe(3);
+  });
+
+  it('counts per-flip selectedSide independently', () => {
+    const flips = [
+      { result: CoinSide.HEADS, selectedSide: CoinSide.HEADS },
+      { result: CoinSide.TAILS, selectedSide: CoinSide.TAILS },
+      { result: CoinSide.HEADS, selectedSide: CoinSide.TAILS },
+    ];
+    expect(CoinflipRules.countSuccessfulFlips(flips)).toBe(2);
+  });
+
+  it('returns 0 for an empty list', () => {
+    expect(CoinflipRules.countSuccessfulFlips([])).toBe(0);
+  });
+});
+
+describe('CoinflipRules.calculateClassicMultiplier', () => {
+  it.each([
+    [1, 1.96],
+    [2, 3.92],
+    [3, 7.84],
+    [10, 1003.52],
+    [20, 1027604.48],
+  ])('%i successful flips pays %fx', (successfulFlips, expected) => {
+    expect(CoinflipRules.calculateClassicMultiplier(successfulFlips, EDGE_BPS).toNumber()).toBe(expected);
+  });
+
+  it('throws when successful flips is below 1', () => {
+    expect(() => CoinflipRules.calculateClassicMultiplier(0, EDGE_BPS)).toThrow();
+  });
+
+  it('throws when successful flips exceeds MAX_FLIPS', () => {
+    expect(() => CoinflipRules.calculateClassicMultiplier(MAX_FLIPS + 1, EDGE_BPS)).toThrow();
+  });
+});
+
+describe('CoinflipRules.calculateTargetMultiplier', () => {
+  it.each([
+    [1, 1, 1.96],
+    [2, 1, 1.306666667],
+    [2, 2, 3.92],
+    [3, 1, 1.12],
+    [3, 2, 1.96],
+    [4, 2, 1.425454545],
+    [5, 5, 31.36],
+    [10, 7, 5.701818182],
+    [20, 20, 1027604.48],
+  ])('%i flips needing at least %i successes pays %fx', (flips, minSuccesses, expected) => {
+    expect(CoinflipRules.calculateTargetMultiplier(flips, minSuccesses, EDGE_BPS).decimalPlaces(9).toNumber()).toBe(expected);
+  });
+
+  it('throws when flips is below 1', () => {
+    expect(() => CoinflipRules.calculateTargetMultiplier(0, 1, EDGE_BPS)).toThrow();
+  });
+
+  it('throws when flips exceeds MAX_FLIPS', () => {
+    expect(() => CoinflipRules.calculateTargetMultiplier(MAX_FLIPS + 1, 1, EDGE_BPS)).toThrow();
+  });
+
+  it('throws when minSuccesses is below 1', () => {
+    expect(() => CoinflipRules.calculateTargetMultiplier(5, 0, EDGE_BPS)).toThrow();
+  });
+
+  it('throws when minSuccesses exceeds flips', () => {
+    expect(() => CoinflipRules.calculateTargetMultiplier(5, 6, EDGE_BPS)).toThrow();
+  });
+});
+
+describe('CoinflipRules.validateActiveProgressiveClassicGame', () => {
+  const start = (): CoinflipProgressiveStartAction => ({ phase: 'START' });
+  const win = (side = CoinSide.HEADS): CoinflipProgressiveCoinSelectionAction => ({
+    phase: 'COIN_SELECTION',
+    selectedSide: side,
+    flipResult: side,
+    multiplier: new BigNumber(0),
+  });
+  const cashout = (): CoinflipProgressiveCashoutAction => ({
+    phase: 'CASHOUT',
+    multiplier: new BigNumber(1.96),
+  });
+
+  it('returns 0 for an empty action list', () => {
+    expect(CoinflipRules.validateActiveProgressiveClassicGame([])).toBe(0);
+  });
+
+  it('returns 0 for a start-only history', () => {
+    expect(CoinflipRules.validateActiveProgressiveClassicGame([start()])).toBe(0);
+  });
+
+  it('returns the number of winning selections', () => {
+    expect(CoinflipRules.validateActiveProgressiveClassicGame([start(), win(), win()])).toBe(2);
+  });
+
+  it('throws when a CASHOUT action is present', () => {
+    expect(() => CoinflipRules.validateActiveProgressiveClassicGame([start(), win(), win(), cashout()])).toThrow(
+      'An active game cannot have a CASHOUT action',
+    );
+  });
+
+  it('throws when the history contains more than MAX_FLIPS flips', () => {
+    const tooManyWins = Array.from({ length: MAX_FLIPS + 1 }, () => win());
+    expect(() => CoinflipRules.validateActiveProgressiveClassicGame([start(), ...tooManyWins])).toThrow(
+      `Reconstructed flipsRevealed (${MAX_FLIPS + 1}) exceeds MAX_FLIPS (${MAX_FLIPS})`,
+    );
+  });
+
+  it('throws when the first action is not START', () => {
+    expect(() => CoinflipRules.validateActiveProgressiveClassicGame([win()])).toThrow('First action must be START');
+  });
+
+  it('throws when a START action appears after the first position', () => {
+    expect(() => CoinflipRules.validateActiveProgressiveClassicGame([start(), win(), start()])).toThrow(
+      'START action can only appear as the first action',
+    );
+  });
+
+  it('throws when a COIN_SELECTION has mismatched flipResult', () => {
+    const badWin: CoinflipProgressiveCoinSelectionAction = {
+      phase: 'COIN_SELECTION',
+      selectedSide: CoinSide.HEADS,
+      flipResult: CoinSide.TAILS,
+      multiplier: new BigNumber(0),
+    };
+    expect(() => CoinflipRules.validateActiveProgressiveClassicGame([start(), badWin])).toThrow(
+      'COIN_SELECTION must have matching flipResult and selectedSide',
+    );
+  });
+});

package/src/games/coinflip/coinflip-rules.ts

@@ -0,0 +1,104 @@
+import BigNumber from 'bignumber.js';
+import { calculateEdgeMultiplier } from '../../utils/edge';
+import { nCr } from '../../utils/ncr';
+import { RandomNumberGenerator } from '../random-number-generator.interface';
+import type { CoinflipClassicProgressiveGameAction } from './coinflip-classic-progressive';
+import { CoinSide, MAX_FLIPS } from './constants';
+
+function rngValueToCoinSide(n: number): CoinSide {
+  if (n === 0) return CoinSide.HEADS;
+  if (n === 1) return CoinSide.TAILS;
+  throw new Error(`Random number generator returned ${n}, expected 0 or 1`);
+}
+
+export class CoinflipRules {
+  public static getFlipResults(generator: RandomNumberGenerator, count: number): CoinSide[] {
+    if (count < 1 || count > MAX_FLIPS) {
+      throw new Error(`Flip count must be between 1 and ${MAX_FLIPS}, got ${count}`);
+    }
+
+    const randomNumbers = generator.getRandomIntsWithReplacement({ min: 0, max: 1, count });
+
+    if (randomNumbers.length !== count) {
+      throw new Error(`Random number generator returned ${randomNumbers.length} values, expected ${count}`);
+    }
+
+    return randomNumbers.map(rngValueToCoinSide);
+  }
+
+  public static isFlipWin(selectedSide: CoinSide, result: CoinSide): boolean {
+    return selectedSide === result;
+  }
+
+  public static getFlipResultAtPosition(generator: RandomNumberGenerator, position: number): CoinSide {
+    const flips = CoinflipRules.getFlipResults(generator, position);
+    return flips[flips.length - 1] as CoinSide;
+  }
+
+  public static countSuccessfulFlips(flips: { result: CoinSide; selectedSide: CoinSide }[]): number {
+    return flips.filter(f => CoinflipRules.isFlipWin(f.selectedSide, f.result)).length;
+  }
+
+  public static calculateClassicWinChance(successfulFlips: number): BigNumber {
+    return BigNumber(0.5).pow(successfulFlips);
+  }
+
+  public static calculateClassicMultiplier(successfulFlips: number, edgeBps: number): BigNumber {
+    if (successfulFlips < 1 || successfulFlips > MAX_FLIPS) {
+      throw new Error(`Successful flips must be between 1 and ${MAX_FLIPS}, got ${successfulFlips}`);
+    }
+    return calculateEdgeMultiplier(edgeBps).dividedBy(CoinflipRules.calculateClassicWinChance(successfulFlips));
+  }
+
+  public static calculateTargetWinChance(flips: number, minSuccesses: number): BigNumber {
+    const fixedOutcomeProbability = BigNumber(0.5).pow(flips);
+    let cumulativeProbability = BigNumber(0);
+    for (let k = minSuccesses; k <= flips; k++) {
+      cumulativeProbability = cumulativeProbability.plus(nCr(flips, k).multipliedBy(fixedOutcomeProbability));
+    }
+    return cumulativeProbability;
+  }
+
+  public static calculateTargetMultiplier(flips: number, minSuccesses: number, edgeBps: number): BigNumber {
+    if (flips < 1 || flips > MAX_FLIPS) {
+      throw new Error(`Flips must be between 1 and ${MAX_FLIPS}, got ${flips}`);
+    }
+    if (minSuccesses < 1 || minSuccesses > flips) {
+      throw new Error(`Min successes must be between 1 and ${flips}, got ${minSuccesses}`);
+    }
+    return calculateEdgeMultiplier(edgeBps).dividedBy(CoinflipRules.calculateTargetWinChance(flips, minSuccesses));
+  }
+
+  public static validateActiveProgressiveClassicGame(gameActions: CoinflipClassicProgressiveGameAction[]): number {
+    if (gameActions.length === 0) {
+      return 0;
+    }
+
+    if (gameActions[0].phase !== 'START') {
+      throw new Error('First action must be START');
+    }
+
+    let flipsRevealed = 0;
+
+    for (let i = 1; i < gameActions.length; i++) {
+      const action = gameActions[i];
+      switch (action.phase) {
+        case 'START':
+          throw new Error('START action can only appear as the first action');
+        case 'COIN_SELECTION':
+          if (action.selectedSide !== action.flipResult) {
+            throw new Error('COIN_SELECTION must have matching flipResult and selectedSide');
+          }
+          flipsRevealed++;
+          if (flipsRevealed > MAX_FLIPS) {
+            throw new Error(`Reconstructed flipsRevealed (${flipsRevealed}) exceeds MAX_FLIPS (${MAX_FLIPS})`);
+          }
+          break;
+        case 'CASHOUT':
+          throw new Error('An active game cannot have a CASHOUT action');
+      }
+    }
+
+    return flipsRevealed;
+  }
+}

package/src/games/coinflip/coinflip-target.spec.ts

@@ -0,0 +1,73 @@
+import BigNumber from 'bignumber.js';
+import { FixedSequenceRng } from '../fixed-rng';
+import { CoinflipTarget } from './coinflip-target';
+import { CoinSide, MAX_FLIPS } from './constants';
+
+const EDGE_BPS = 200;
+
+const getCoinRngValue = (side: CoinSide) => (side === CoinSide.HEADS ? 0 : 1);
+
+describe('CoinflipTarget.resolve', () => {
+  it('wins when successes meet the minimum exactly', () => {
+    const rng = new FixedSequenceRng([getCoinRngValue(CoinSide.HEADS), getCoinRngValue(CoinSide.HEADS), getCoinRngValue(CoinSide.TAILS)]);
+
+    expect(CoinflipTarget.resolve({ selectedSide: CoinSide.HEADS, totalFlips: 3, minSuccesses: 2 }, rng, EDGE_BPS)).toMatchObject({
+      multiplier: BigNumber(1.96),
+    });
+  });
+
+  it('pays the same multiplier when successes exceed the minimum', () => {
+    const rng = new FixedSequenceRng([getCoinRngValue(CoinSide.HEADS), getCoinRngValue(CoinSide.HEADS), getCoinRngValue(CoinSide.HEADS)]);
+
+    expect(CoinflipTarget.resolve({ selectedSide: CoinSide.HEADS, totalFlips: 3, minSuccesses: 2 }, rng, EDGE_BPS)).toMatchObject({
+      multiplier: BigNumber(1.96),
+    });
+  });
+
+  it('loses when successes fall below the minimum', () => {
+    const rng = new FixedSequenceRng([getCoinRngValue(CoinSide.HEADS), getCoinRngValue(CoinSide.TAILS), getCoinRngValue(CoinSide.TAILS)]);
+
+    expect(CoinflipTarget.resolve({ selectedSide: CoinSide.HEADS, totalFlips: 3, minSuccesses: 2 }, rng, EDGE_BPS)).toMatchObject({
+      multiplier: BigNumber(0),
+    });
+  });
+
+  it('counts successes for the selected side only', () => {
+    const rng = new FixedSequenceRng([getCoinRngValue(CoinSide.TAILS), getCoinRngValue(CoinSide.TAILS), getCoinRngValue(CoinSide.HEADS)]);
+
+    expect(CoinflipTarget.resolve({ selectedSide: CoinSide.TAILS, totalFlips: 3, minSuccesses: 2 }, rng, EDGE_BPS)).toMatchObject({
+      multiplier: BigNumber(1.96),
+    });
+  });
+
+  it('a single-flip target pays the same as classic', () => {
+    const rng = new FixedSequenceRng([getCoinRngValue(CoinSide.HEADS)]);
+
+    expect(CoinflipTarget.resolve({ selectedSide: CoinSide.HEADS, totalFlips: 1, minSuccesses: 1 }, rng, EDGE_BPS)).toMatchObject({
+      multiplier: BigNumber(1.96),
+    });
+  });
+
+  it('all correct at MAX_FLIPS pays the top multiplier', () => {
+    const rng = new FixedSequenceRng(Array(MAX_FLIPS).fill(CoinSide.HEADS).map(getCoinRngValue));
+
+    expect(CoinflipTarget.resolve({ selectedSide: CoinSide.HEADS, totalFlips: MAX_FLIPS, minSuccesses: MAX_FLIPS }, rng, EDGE_BPS)).toMatchObject({
+      multiplier: BigNumber(1027604.48),
+    });
+  });
+
+  it('records the flips and config in the action', () => {
+    const rng = new FixedSequenceRng([getCoinRngValue(CoinSide.HEADS), getCoinRngValue(CoinSide.TAILS), getCoinRngValue(CoinSide.TAILS)]);
+
+    expect(CoinflipTarget.resolve({ selectedSide: CoinSide.HEADS, totalFlips: 3, minSuccesses: 2 }, rng, EDGE_BPS)).toMatchObject({
+      multiplier: BigNumber(0),
+      action: {
+        selectedSide: CoinSide.HEADS,
+        flipResults: [CoinSide.HEADS, CoinSide.TAILS, CoinSide.TAILS],
+        multiplier: BigNumber(0),
+        totalFlips: 3,
+        minSuccesses: 2,
+      },
+    });
+  });
+});

package/src/games/coinflip/coinflip-target.ts

@@ -0,0 +1,44 @@
+import BigNumber from 'bignumber.js';
+import { RandomNumberGenerator } from '../random-number-generator.interface';
+import { CoinflipRules } from './coinflip-rules';
+import { CoinSide } from './constants';
+
+export interface CoinflipTargetConfig {
+  selectedSide: CoinSide;
+  totalFlips: number;
+  minSuccesses: number;
+}
+
+export interface CoinflipTargetAction {
+  selectedSide: CoinSide;
+  flipResults: CoinSide[];
+  multiplier: BigNumber;
+  totalFlips: number;
+  minSuccesses: number;
+}
+
+export interface CoinflipTargetGameResult {
+  multiplier: BigNumber;
+  action: CoinflipTargetAction;
+}
+
+export class CoinflipTarget {
+  public static resolve(config: CoinflipTargetConfig, generator: RandomNumberGenerator, edge: number): CoinflipTargetGameResult {
+    const flips = CoinflipRules.getFlipResults(generator, config.totalFlips);
+    const successfulFlips = CoinflipRules.countSuccessfulFlips(flips.map(result => ({ result, selectedSide: config.selectedSide })));
+    const isLoss = successfulFlips < config.minSuccesses;
+
+    const multiplier = isLoss ? BigNumber(0) : CoinflipRules.calculateTargetMultiplier(config.totalFlips, config.minSuccesses, edge);
+
+    return {
+      multiplier,
+      action: {
+        selectedSide: config.selectedSide,
+        flipResults: flips,
+        multiplier,
+        totalFlips: config.totalFlips,
+        minSuccesses: config.minSuccesses,
+      },
+    };
+  }
+}

package/src/games/coinflip/constants.ts

@@ -0,0 +1,6 @@
+export const MAX_FLIPS = 20;
+
+export enum CoinSide {
+  HEADS = 'HEADS',
+  TAILS = 'TAILS',
+}

package/src/games/fixed-rng.ts

@@ -0,0 +1,25 @@
+import { RandomNumberGenerator } from './random-number-generator.interface';
+
+export class FixedSequenceRng implements RandomNumberGenerator {
+  constructor(private readonly values: number[]) {}
+
+  getRandomIntsWithReplacement({ count }: { min: number; max: number; count: number }): number[] {
+    const values = this.values.slice(0, count);
+
+    if (values.length !== count) {
+      throw new Error('Insufficient values provided in constructor');
+    }
+
+    return values;
+  }
+
+  getRandomIntsWithoutReplacement({ count }: { min: number; max: number; count: number }): number[] {
+    const values = this.values.slice(0, count);
+
+    if (values.length !== count) {
+      throw new Error('Insufficient values provided in constructor');
+    }
+
+    return values;
+  }
+}

package/src/games/random-number-generator.interface.ts

@@ -0,0 +1,4 @@
+export interface RandomNumberGenerator {
+  getRandomIntsWithReplacement(args: { min: number; max: number; count: number }): number[];
+  getRandomIntsWithoutReplacement(args: { min: number; max: number; count: number }): number[];
+}

package/src/index.ts

@@ -47,3 +47,8 @@ export { formatSelectionName } from './sports/sports-name';
 export { SportsContentWithFixturesInfo } from './sports/sports-content-fixture.types';
 export { SportsProviderMaxBet, BetradarOverrideLimitType, BETRADAR_OVERRIDE_LIMIT_TO_MAX_BET } from './sports/override-limit-max-bet';
 export { Blitz, BlitzResult, BLITZ_MIN_PICKS, BLITZ_MAX_PICKS } from './games/blitz';
+export { CoinSide, MAX_FLIPS } from './games/coinflip/constants';
+export * from './games/coinflip/coinflip-rules';
+export * from './games/coinflip/coinflip-classic';
+export * from './games/coinflip/coinflip-classic-progressive';
+export * from './games/coinflip/coinflip-target';

package/src/sports/sports-bet.types.ts

@@ -7,6 +7,7 @@ import {
   SportsBetSelectionStatus,
   SportsBetStatus,
   SportsBetType,
+  SportsCashoutFailedReason,
   SportsFixtureBannerType,
   SportsFixtureStatus,
   SportsMarketProductId,
@@ -132,7 +133,7 @@ export interface SportsBetSettlementV3 {
 
 export interface SportsBetCashoutAvailableV3 {
   canCashout: boolean;
-  reason: string | null;
+  reason: SportsCashoutFailedReason | null;
 }
 
 export interface SportsBetUserV3 {

package/src/sports/sports.types.ts

@@ -85,6 +85,17 @@ export enum SportsBetStatus {
   VOIDED = 'VOIDED',
 }
 
+export enum SportsCashoutFailedReason {
+  SPORTS_BET_IS_CLOSED = 'SPORTS_BET_IS_CLOSED',
+  SPORTS_BET_SELECTION_NOT_FOUND = 'SPORTS_BET_SELECTION_NOT_FOUND',
+  MANUAL_MARKET_NOT_ALLOWED_CASHOUT = 'MANUAL_MARKET_NOT_ALLOWED_CASHOUT',
+  SPORTS_MARKET_CASHOUT_IS_NOT_OPEN = 'SPORTS_MARKET_CASHOUT_IS_NOT_OPEN',
+  SPORTS_MARKET_NOT_FOUND = 'SPORTS_MARKET_NOT_FOUND',
+  SPORTS_FIXTURE_NOT_FOUND = 'SPORTS_FIXTURE_NOT_FOUND',
+  SPORTS_MARKET_CLOSED = 'SPORTS_MARKET_CLOSED',
+  SPORTS_MARKET_CASHOUT_NOT_ENABLED = 'SPORTS_MARKET_CASHOUT_NOT_ENABLED',
+}
+
 export enum SportsBetType {
   REGULAR = 'REGULAR',
   CUSTOM_BET = 'CUSTOM_BET',

package/src/utils/chain-currency-display.ts

@@ -2,7 +2,8 @@ import { Chain } from "./chain";
 import { Currency } from "./currency";
 
 const CURRENCY_DISPLAY_LABEL: Partial<Record<Currency, string>> = {
-  MATIC: 'POL'
+  MATIC: 'POL',
+  TON: 'GRAM',
 }
 
 // This function is used to get the display label for a currency
@@ -11,7 +12,8 @@ export const getCurrencyLabel = (currency: Partial<Currency>): string => {
 }
 
 const CHAIN_DISPLAY_LABEL: Partial<Record<Chain, string>> = {
-  MATIC_POLYGON: 'POLYGON'
+  MATIC_POLYGON: 'POLYGON',
+  TON: 'GRAM',
 }
 
 export const getChainLabel = (chain: Partial<Chain>): string => {