shufflecom-calculations 4.2.4 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shufflecom-calculations",
-  "version": "4.2.4",
+  "version": "4.3.0",
   "description": "",
   "types": "lib/index.d.ts",
   "main": "lib/index.js",
@@ -14,5 +14,5 @@
   },
   "author": "",
   "license": "ISC",
-  "gitHead": "8ccea4c69581b221ba1ab1c2bcb4c465f2c53254"
+  "gitHead": "6ab5874d4c58fdc438fa41165b12626a72143af6"
 }

package/src/games/baccarat.spec.ts

@@ -887,7 +887,13 @@ describe('Baccarat', () => {
         const card = ci('4', Suits.CLUBS);
         const result = mockResult([card, card], [ci('3', Suits.CLUBS), ci('2', Suits.DIAMONDS)], 8, 5, BaccaratOutcome.PLAYER_WIN);
         expect(Baccarat.getWinningBetTypes(result)).toEqual(
-          expect.arrayContaining([BaccaratBetType.PLAYER, BaccaratBetType.PLAYER_PAIR, BaccaratBetType.EITHER_PAIR, BaccaratBetType.PERFECT_PAIR, BaccaratBetType.PLAYER_BONUS]),
+          expect.arrayContaining([
+            BaccaratBetType.PLAYER,
+            BaccaratBetType.PLAYER_PAIR,
+            BaccaratBetType.EITHER_PAIR,
+            BaccaratBetType.PERFECT_PAIR,
+            BaccaratBetType.PLAYER_BONUS,
+          ]),
         );
       });
 
@@ -895,7 +901,13 @@ describe('Baccarat', () => {
         const card = ci('K', Suits.DIAMONDS);
         const result = mockResult([ci('3', Suits.CLUBS), ci('2', Suits.DIAMONDS)], [card, card], 5, 0, BaccaratOutcome.PLAYER_WIN);
         expect(Baccarat.getWinningBetTypes(result)).toEqual(
-          expect.arrayContaining([BaccaratBetType.PLAYER, BaccaratBetType.BANKER_PAIR, BaccaratBetType.EITHER_PAIR, BaccaratBetType.PERFECT_PAIR, BaccaratBetType.PLAYER_BONUS]),
+          expect.arrayContaining([
+            BaccaratBetType.PLAYER,
+            BaccaratBetType.BANKER_PAIR,
+            BaccaratBetType.EITHER_PAIR,
+            BaccaratBetType.PERFECT_PAIR,
+            BaccaratBetType.PLAYER_BONUS,
+          ]),
         );
       });
 
@@ -1001,9 +1013,7 @@ describe('Baccarat', () => {
           8,
           BaccaratOutcome.TIE,
         );
-        expect(Baccarat.getWinningBetTypes(result)).toEqual(
-          expect.arrayContaining([BaccaratBetType.TIE]),
-        );
+        expect(Baccarat.getWinningBetTypes(result)).toEqual(expect.arrayContaining([BaccaratBetType.TIE]));
       });
 
       it('returns neither bonus on non-natural tie', () => {
@@ -1028,4 +1038,49 @@ describe('Baccarat', () => {
       expect(multiplier.toNumber()).toBe(1.95);
     });
   });
+
+  describe('getMaxMultiplier', () => {
+    it.each<[BaccaratBetType, number]>([
+      [BaccaratBetType.PLAYER, 2], // 1:1
+      [BaccaratBetType.BANKER, 1.95], // 0.95:1 (commission)
+      [BaccaratBetType.TIE, 9], // 8:1
+      [BaccaratBetType.PLAYER_PAIR, 12], // 11:1
+      [BaccaratBetType.BANKER_PAIR, 12], // 11:1
+      [BaccaratBetType.PERFECT_PAIR, 26], // 25:1 (one hand)
+      [BaccaratBetType.EITHER_PAIR, 6], // 5:1
+      [BaccaratBetType.PLAYER_BONUS, 31], // 30:1 (non-natural win by 9)
+      [BaccaratBetType.BANKER_BONUS, 31], // 30:1 (non-natural win by 9)
+    ])('a single %s bet caps at its own max multiplier (%f)', (type, expected) => {
+      expect(Baccarat.getMaxMultiplier([bet(type, 10)]).toNumber()).toBe(expected);
+    });
+
+    it.each([
+      { label: 'stake-heavy on PLAYER', bets: [bet(BaccaratBetType.PLAYER, 30), bet(BaccaratBetType.TIE, 10)], expected: 3.75 },
+      { label: 'stake-heavy on TIE', bets: [bet(BaccaratBetType.PLAYER, 10), bet(BaccaratBetType.TIE, 30)], expected: 7.25 },
+    ])('blends per-type maxes weighted by stake ($label)', ({ bets, expected }) => {
+      expect(Baccarat.getMaxMultiplier(bets).toNumber()).toBe(expected);
+    });
+
+    it('sums per-type maxes across a full side-bet spread', () => {
+      const bets = [
+        bet(BaccaratBetType.PLAYER, 10),
+        bet(BaccaratBetType.PERFECT_PAIR, 10),
+        bet(BaccaratBetType.BANKER_PAIR, 10),
+        bet(BaccaratBetType.PLAYER_BONUS, 10),
+      ];
+      expect(Baccarat.getMaxMultiplier(bets).toNumber()).toBe(17.75);
+    });
+
+    it('accumulates repeated bets of the same type', () => {
+      const bets = [bet(BaccaratBetType.BANKER, 25), bet(BaccaratBetType.BANKER, 75)];
+      expect(Baccarat.getMaxMultiplier(bets).toNumber()).toBe(1.95);
+    });
+
+    it.each([
+      { label: 'no bets', bets: [] as ReturnType<typeof bet>[] },
+      { label: 'only zero-amount bets', bets: [bet(BaccaratBetType.PLAYER, 0), bet(BaccaratBetType.TIE, 0)] },
+    ])('returns 0 when the total stake is 0 ($label)', ({ bets }) => {
+      expect(Baccarat.getMaxMultiplier(bets).toNumber()).toBe(0);
+    });
+  });
 });

package/src/games/baccarat.ts

@@ -57,6 +57,26 @@ const BONUS_NON_NATURAL_PAYOUT: Record<number, BigNumber> = {
 };
 
 export class Baccarat {
+  static getMaxMultiplier(bets: BaccaratBet[]): BigNumber {
+    const MAX_BY_TYPE: Record<BaccaratBetType, BigNumber> = {
+      [BaccaratBetType.PLAYER]: PLAYER_WIN_MULTIPLIER,
+      [BaccaratBetType.BANKER]: BANKER_WIN_MULTIPLIER,
+      [BaccaratBetType.TIE]: TIE_MULTIPLIER,
+      [BaccaratBetType.PLAYER_PAIR]: PAIR_MULTIPLIER,
+      [BaccaratBetType.BANKER_PAIR]: PAIR_MULTIPLIER,
+      [BaccaratBetType.PERFECT_PAIR]: PERFECT_PAIR_ONE_HAND_MULTIPLIER,
+      [BaccaratBetType.EITHER_PAIR]: EITHER_PAIR_MULTIPLIER,
+      [BaccaratBetType.PLAYER_BONUS]: new BigNumber(31),
+      [BaccaratBetType.BANKER_BONUS]: new BigNumber(31),
+    };
+    const totalBet = bets.reduce((sum, bet) => sum.plus(bet.amount), new BigNumber(0));
+    if (totalBet.isZero()) {
+      return new BigNumber(0);
+    }
+    const maxPayout = bets.reduce((sum, bet) => sum.plus(bet.amount.multipliedBy(MAX_BY_TYPE[bet.type])), new BigNumber(0));
+    return maxPayout.dividedBy(totalBet);
+  }
+
   static getBaccaratCardValue(cardIndex: number): number {
     const { value } = CardGames.getCardDetails(cardIndex);
     if (value === '10' || value === 'J' || value === 'Q' || value === 'K') {
@@ -224,7 +244,7 @@ export class Baccarat {
     if (outcome === BaccaratOutcome.PLAYER_WIN && (playerIsNatural || (!playerIsNatural && playerHandValue - bankerHandValue >= 4))) {
       winning.push(BaccaratBetType.PLAYER_BONUS);
     }
-    if  (outcome === BaccaratOutcome.BANKER_WIN && (bankerIsNatural || (!bankerIsNatural && bankerHandValue - playerHandValue >= 4))) {
+    if (outcome === BaccaratOutcome.BANKER_WIN && (bankerIsNatural || (!bankerIsNatural && bankerHandValue - playerHandValue >= 4))) {
       winning.push(BaccaratBetType.BANKER_BONUS);
     }
 

package/src/games/blackjack.spec.ts

@@ -1521,3 +1521,103 @@ describe('Blackjack', () => {
      */
   });
 });
+
+describe('Blackjack.getMaxPotentialPayout', () => {
+  it('is the natural 2.5x main bet plus sidebet ceilings (26x perfect pair, 101x 21+3)', () => {
+    const payout = Blackjack.getMaxPotentialPayout({
+      mainBetAmount: new BigNumber(10),
+      perfectPairAmount: new BigNumber(2),
+      twentyOnePlusThreeAmount: new BigNumber(3),
+    });
+    // 2.5*10 + 26*2 + 101*3 = 25 + 52 + 303 = 380
+    expect(payout.toNumber()).toBe(380);
+  });
+
+  it('is 2.5x main bet when there are no sidebets', () => {
+    const payout = Blackjack.getMaxPotentialPayout({
+      mainBetAmount: new BigNumber(100),
+      perfectPairAmount: new BigNumber(0),
+      twentyOnePlusThreeAmount: new BigNumber(0),
+    });
+    expect(payout.toNumber()).toBe(250);
+  });
+});
+
+describe('Blackjack.getMaxRemainingPayout', () => {
+  const noSidebets = {
+    perfectPairAmount: new BigNumber(0),
+    twentyOnePlusThreeAmount: new BigNumber(0),
+  };
+
+  it('is 2x the main-hand stake with no split and no double', () => {
+    const payout = Blackjack.getMaxRemainingPayout({
+      originalMainBetAmount: new BigNumber(10),
+      mainPlayerActions: [BlackjackAction.HIT],
+      splitPlayerHand: [],
+      splitPlayerActions: [],
+      ...noSidebets,
+    });
+    expect(payout.toNumber()).toBe(20);
+  });
+
+  it('doubles the stake on a double-down (2 * 2x main bet)', () => {
+    const payout = Blackjack.getMaxRemainingPayout({
+      originalMainBetAmount: new BigNumber(10),
+      mainPlayerActions: [BlackjackAction.DOUBLE_DOWN],
+      splitPlayerHand: [],
+      splitPlayerActions: [],
+      ...noSidebets,
+    });
+    expect(payout.toNumber()).toBe(40);
+  });
+
+  it('covers both hands after a split (2 * (main + split) stake)', () => {
+    const payout = Blackjack.getMaxRemainingPayout({
+      originalMainBetAmount: new BigNumber(10),
+      mainPlayerActions: [BlackjackAction.SPLIT],
+      splitPlayerHand: [getIndex('8'), getIndex('9')],
+      splitPlayerActions: [BlackjackAction.SPLIT],
+      ...noSidebets,
+    });
+    expect(payout.toNumber()).toBe(40);
+  });
+
+  it('reaches 8x main bet when split and both hands double down', () => {
+    const payout = Blackjack.getMaxRemainingPayout({
+      originalMainBetAmount: new BigNumber(10),
+      mainPlayerActions: [BlackjackAction.SPLIT, BlackjackAction.DOUBLE_DOWN],
+      splitPlayerHand: [getIndex('8'), getIndex('9')],
+      splitPlayerActions: [BlackjackAction.SPLIT, BlackjackAction.DOUBLE_DOWN],
+      ...noSidebets,
+    });
+    expect(payout.toNumber()).toBe(80);
+  });
+
+  it('adds resolved sidebet winnings on top of the hand stakes', () => {
+    const payout = Blackjack.getMaxRemainingPayout({
+      originalMainBetAmount: new BigNumber(10),
+      mainPlayerActions: [BlackjackAction.DOUBLE_DOWN],
+      splitPlayerHand: [],
+      splitPlayerActions: [],
+      perfectPairWin: PerfectPairType.PERFECT_PAIR, // 26x
+      perfectPairAmount: new BigNumber(2),
+      twentyOnePlusThreeWin: TwentyOnePlusThreeType.STRAIGHT, // 11x
+      twentyOnePlusThreeAmount: new BigNumber(1),
+    });
+    // 2*(2*10) + 26*2 + 11*1 = 40 + 52 + 11 = 103
+    expect(payout.toNumber()).toBe(103);
+  });
+
+  it('ignores a sidebet win when its amount is zero', () => {
+    const payout = Blackjack.getMaxRemainingPayout({
+      originalMainBetAmount: new BigNumber(10),
+      mainPlayerActions: [],
+      splitPlayerHand: [],
+      splitPlayerActions: [],
+      perfectPairWin: PerfectPairType.PERFECT_PAIR,
+      perfectPairAmount: new BigNumber(0),
+      twentyOnePlusThreeAmount: new BigNumber(0),
+    });
+    expect(payout.toNumber()).toBe(20);
+  });
+});

package/src/games/blackjack.ts

@@ -93,6 +93,52 @@ const suitColorMap: Record<Suits, SuitColor> = {
 };
 
 export class Blackjack {
+  // A natural blackjack (3:2) is the best the main bet can do at deal time
+  static readonly NATURAL_MAIN_BET_MULTIPLIER = new BigNumber(2.5);
+
+  static getMaxPotentialPayout(params: {
+    mainBetAmount: BigNumber;
+    perfectPairAmount: BigNumber;
+    twentyOnePlusThreeAmount: BigNumber;
+  }): BigNumber {
+    const maxPerfectPair = BigNumber.max(...Object.values(perfectPairPayout));
+    const maxTwentyOnePlusThree = BigNumber.max(...Object.values(twentyOnePlusThreePayout));
+    return params.mainBetAmount
+      .multipliedBy(Blackjack.NATURAL_MAIN_BET_MULTIPLIER)
+      .plus(params.perfectPairAmount.multipliedBy(maxPerfectPair))
+      .plus(params.twentyOnePlusThreeAmount.multipliedBy(maxTwentyOnePlusThree));
+  }
+
+  static getMaxRemainingPayout(action: {
+    originalMainBetAmount: BigNumber;
+    mainPlayerActions: BlackjackAction[];
+    splitPlayerHand: readonly number[];
+    splitPlayerActions: BlackjackAction[];
+    perfectPairWin?: PerfectPairType;
+    twentyOnePlusThreeWin?: TwentyOnePlusThreeType;
+    perfectPairAmount: BigNumber;
+    twentyOnePlusThreeAmount: BigNumber;
+  }): BigNumber {
+    const mainBet = new BigNumber(action.originalMainBetAmount);
+    const hasSplit = action.splitPlayerHand.length > 0;
+
+    const mainHandStake = mainBet.multipliedBy(action.mainPlayerActions.includes(BlackjackAction.DOUBLE_DOWN) ? 2 : 1);
+    const splitHandStake = hasSplit
+      ? mainBet.multipliedBy(action.splitPlayerActions.includes(BlackjackAction.DOUBLE_DOWN) ? 2 : 1)
+      : new BigNumber(0);
+
+    const perfectPairAmount = new BigNumber(action.perfectPairAmount);
+    const twentyOnePlusThreeAmount = new BigNumber(action.twentyOnePlusThreeAmount);
+    const perfectPairPayoutAmt =
+      action.perfectPairWin && perfectPairAmount.gt(0) ? perfectPairAmount.multipliedBy(perfectPairPayout[action.perfectPairWin]) : new BigNumber(0);
+    const twentyOnePlusThreePayoutAmt =
+      action.twentyOnePlusThreeWin && twentyOnePlusThreeAmount.gt(0)
+        ? twentyOnePlusThreeAmount.multipliedBy(twentyOnePlusThreePayout[action.twentyOnePlusThreeWin])
+        : new BigNumber(0);
+
+    return mainHandStake.plus(splitHandStake).multipliedBy(2).plus(perfectPairPayoutAmt).plus(twentyOnePlusThreePayoutAmt);
+  }
+
   static availableNextActions(
     currentPlayerHand: readonly number[],
     dealerCards: [number],
@@ -156,7 +202,11 @@ export class Blackjack {
     return true;
   }
 
-  static getHandOutcome(dealerCards: readonly number[], playerCards: readonly number[], hasSplit: boolean): { multiplier: BigNumber; outcome: HandOutcome } {
+  static getHandOutcome(
+    dealerCards: readonly number[],
+    playerCards: readonly number[],
+    hasSplit: boolean,
+  ): { multiplier: BigNumber; outcome: HandOutcome } {
     const dealerBlackjack = this.isBlackjack(dealerCards);
     const playerBlackjack = this.isBlackjack(playerCards);
 
@@ -194,7 +244,10 @@ export class Blackjack {
     }
   }
 
-  static calcSideBetWins(dealerUpCard: number, playerCards: readonly number[]): { perfectPair?: PerfectPairType; twentyOnePlusThree?: TwentyOnePlusThreeType } {
+  static calcSideBetWins(
+    dealerUpCard: number,
+    playerCards: readonly number[],
+  ): { perfectPair?: PerfectPairType; twentyOnePlusThree?: TwentyOnePlusThreeType } {
     const results: { perfectPair?: PerfectPairType; twentyOnePlusThree?: TwentyOnePlusThreeType } = {};
     const dealerCardDetails = CardGames.getCardDetails(dealerUpCard);
     const playerCard0 = CardGames.getCardDetails(playerCards[0]);
@@ -230,7 +283,9 @@ export class Blackjack {
       A: [14, 1],
     };
 
-    const cardValues = [...cardValueMap[playerCard0.value], ...cardValueMap[playerCard1.value], ...cardValueMap[dealerCardDetails.value]].sort((a, b) => a - b);
+    const cardValues = [...cardValueMap[playerCard0.value], ...cardValueMap[playerCard1.value], ...cardValueMap[dealerCardDetails.value]].sort(
+      (a, b) => a - b,
+    );
 
     const isFlush = dealerCardDetails.suit === playerCard0.suit && playerCard0.suit === playerCard1.suit;
     const firstThreeCards = cardValues.slice(0, 3) as [number, number, number];
@@ -275,7 +330,7 @@ export class Blackjack {
       K: 10,
     };
 
-    let aceCount = CardGames.getCardDetailsArr(cards).filter((card) => card.value === 'A').length;
+    let aceCount = CardGames.getCardDetailsArr(cards).filter(card => card.value === 'A').length;
     let cardSum = CardGames.getCardDetailsArr(cards).reduce((acc, cur) => acc + cardValueMap[cur.value], 0);
 
     if (aceCount === 0) {
@@ -345,7 +400,12 @@ export class Blackjack {
    * Called after bet ends. Players can still win insurance or sidebets even if they lose the main bet
    * @returns total payout amount
    */
-  static getGameOutcome(data: SettleBetVars): { payout: BigNumber; multiplier: BigNumber; mainHandOutcome: HandOutcome; splitHandOutcome: HandOutcome } {
+  static getGameOutcome(data: SettleBetVars): {
+    payout: BigNumber;
+    multiplier: BigNumber;
+    mainHandOutcome: HandOutcome;
+    splitHandOutcome: HandOutcome;
+  } {
     if (data.dealerHand.length < 2) {
       throw new Error('Dealer hole card is missing');
     }
@@ -360,9 +420,15 @@ export class Blackjack {
     let perfectPairPayoutAmt = new BigNumber(0);
     let twentyOnePlusThreePayoutAmt = new BigNumber(0);
 
-    const { mainHandOutcome, payout: mainBetPayout, splitHandOutcome } = Blackjack.getMainBetPayout({ ...data, mainHandBetAmount, splitHandBetAmount });
+    const {
+      mainHandOutcome,
+      payout: mainBetPayout,
+      splitHandOutcome,
+    } = Blackjack.getMainBetPayout({ ...data, mainHandBetAmount, splitHandBetAmount });
 
-    const playerHand: [number, number] = data.hasSplit ? [data.mainPlayerHand[0], data.splitPlayerHand[0]] : [data.mainPlayerHand[0], data.mainPlayerHand[1]];
+    const playerHand: [number, number] = data.hasSplit
+      ? [data.mainPlayerHand[0], data.splitPlayerHand[0]]
+      : [data.mainPlayerHand[0], data.mainPlayerHand[1]];
 
     const { perfectPair, twentyOnePlusThree } = Blackjack.calcSideBetWins(data.dealerHand[0], playerHand);
 
@@ -376,7 +442,11 @@ export class Blackjack {
 
     const payout = mainBetPayout.plus(perfectPairPayoutAmt).plus(twentyOnePlusThreePayoutAmt);
     const insuranceCost = data.boughtInsurance ? data.mainBetAmount.dividedBy(2) : new BigNumber(0); // insurance costs half of the main bet
-    const totalBetAmount = mainHandBetAmount.plus(splitHandBetAmount).plus(data.perfectPairAmount).plus(data.twentyOnePlusThreeAmount).plus(insuranceCost);
+    const totalBetAmount = mainHandBetAmount
+      .plus(splitHandBetAmount)
+      .plus(data.perfectPairAmount)
+      .plus(data.twentyOnePlusThreeAmount)
+      .plus(insuranceCost);
 
     let multiplier = payout.dividedBy(totalBetAmount);
 

package/src/games/coinflip/coinflip-classic-progressive.spec.ts

@@ -6,6 +6,7 @@ import {
   CoinflipProgressiveCoinSelectionAction,
   CoinflipProgressiveStartAction,
 } from './coinflip-classic-progressive';
+import { CoinflipRules } from './coinflip-rules';
 import { CoinSide, MAX_FLIPS } from './constants';
 
 const EDGE_BPS = 200;
@@ -260,3 +261,11 @@ describe('CoinflipClassicProgressive.autobet', () => {
     expect(flipResults).toHaveLength(MAX_FLIPS);
   });
 });
+
+describe('CoinflipClassicProgressive.getNextWinMultiplier', () => {
+  it('is the classic multiplier for one more successful flip', () => {
+    const edge = 100;
+    const game = CoinflipClassicProgressive.fromActions([{ phase: 'START' }]); // flipsRevealed = 0
+    expect(game.getNextWinMultiplier(edge).toString()).toBe(CoinflipRules.calculateClassicMultiplier(1, edge).toString());
+  });
+});

package/src/games/coinflip/coinflip-classic-progressive.ts

@@ -93,6 +93,11 @@ export class CoinflipClassicProgressive {
     return { multiplier, selectedSides, flipResults: pairs.map(p => p.result) };
   }
 
+  public getNextWinMultiplier(edge: number): BigNumber {
+    const revealedAfter = Math.min(this.flipsRevealed + 1, MAX_FLIPS);
+    return CoinflipRules.calculateClassicMultiplier(revealedAfter, edge);
+  }
+
   public cashout(edge: number): CoinflipClassicProgressiveGameResult {
     if (!this.canCashout()) {
       throw new Error('cashout called with no flips revealed');

package/src/games/hilo.spec.ts

@@ -1,5 +1,5 @@
 import BigNumber from 'bignumber.js';
-import { Hilo, HiloGuess } from './hilo';
+import { Hilo, HiloAction, HiloGuess } from './hilo';
 
 describe('HiLo', () => {
   it('can check that a guess is correct', () => {
@@ -42,6 +42,59 @@ describe('HiLo', () => {
     });
   });
 
+  describe('calculateNextPotentialMultiplierBN', () => {
+    const EDGE = 100;
+    const action = (overrides: Partial<HiloAction> = {}): HiloAction => ({
+      card: null,
+      guess: null,
+      winMultiplier: null,
+      ...overrides,
+    });
+
+    it('returns 0 when there are no actions yet', () => {
+      expect(Hilo.calculateNextPotentialMultiplierBN([], HiloGuess.SAME_OR_ABOVE, EDGE).toString()).toEqual('0');
+    });
+
+    it('returns the last recorded winMultiplier when skipping', () => {
+      const actions = [action({ card: 20, winMultiplier: new BigNumber('2.5') })];
+      expect(Hilo.calculateNextPotentialMultiplierBN(actions, HiloGuess.SKIP, EDGE).toString()).toEqual('2.5');
+    });
+
+    it('returns 0 when skipping and no winMultiplier has been recorded', () => {
+      const actions = [action({ card: 20, winMultiplier: null })];
+      expect(Hilo.calculateNextPotentialMultiplierBN(actions, HiloGuess.SKIP, EDGE).toString()).toEqual('0');
+    });
+
+    it('returns 0 when the most recent card is unknown', () => {
+      const actions = [action({ card: 20 }), action({ card: null, winMultiplier: new BigNumber('2') })];
+      expect(Hilo.calculateNextPotentialMultiplierBN(actions, HiloGuess.SAME_OR_ABOVE, EDGE).toString()).toEqual('0');
+    });
+
+    it('computes the multiplier for the pending guess against the only (start) card', () => {
+      const actions = [action({ card: 20 })];
+      const expected = Hilo.calculateTotalMultiplierBN([{ lastCard: 20, guess: HiloGuess.SAME_OR_ABOVE }], EDGE);
+      expect(Hilo.calculateNextPotentialMultiplierBN(actions, HiloGuess.SAME_OR_ABOVE, EDGE).toString()).toEqual(expected.toString());
+    });
+
+    it('compounds the historical guesses and skips SKIP actions when building the sequence', () => {
+      const actions = [
+        action({ card: 20 }), // start card
+        action({ card: 8, guess: HiloGuess.SAME_OR_BELOW }), // guessed below from card 20
+        action({ card: 8, guess: HiloGuess.SKIP }), // skip -> excluded from the sequence
+        action({ card: 40, guess: HiloGuess.SAME_OR_ABOVE }), // guessed above from card 8
+      ];
+      const expected = Hilo.calculateTotalMultiplierBN(
+        [
+          { lastCard: 20, guess: HiloGuess.SAME_OR_BELOW },
+          { lastCard: 8, guess: HiloGuess.SAME_OR_ABOVE },
+          { lastCard: 40, guess: HiloGuess.SAME_OR_ABOVE }, // most recent card + pending guess
+        ],
+        EDGE,
+      );
+      expect(Hilo.calculateNextPotentialMultiplierBN(actions, HiloGuess.SAME_OR_ABOVE, EDGE).toString()).toEqual(expected.toString());
+    });
+  });
+
   it('calculates multiplier correctly', () => {
     // ace and same or above
     expect(Hilo.calculateWinChanceBN(HiloGuess.SAME_OR_ABOVE, 51).toString()).toEqual(new BigNumber(12).dividedBy(13).toString());

package/src/games/hilo.ts

@@ -28,6 +28,12 @@ export enum Suits {
   CLUBS = 'CLUBS',
 }
 
+export type HiloAction = {
+  card: number | null;
+  guess: HiloGuess | null;
+  winMultiplier: BigNumber | number | null;
+};
+
 export class Hilo {
   static isGuessCorrect(previousCard: number, guess: HiloGuess, result: number) {
     const previousCardValue = CardGames.toComparableNo(previousCard);
@@ -61,7 +67,7 @@ export class Hilo {
 
   static calculateTotalMultiplierBN(actions: { guess: HiloGuess; lastCard: number }[], edgeBps: number) {
     const totalWinChance = actions
-      .map((action) => this.calculateWinChanceBN(action.guess, action.lastCard))
+      .map(action => this.calculateWinChanceBN(action.guess, action.lastCard))
       .reduce((prev, curr) => prev.multipliedBy(curr), BigNumber(1));
 
     if (totalWinChance.isZero()) {
@@ -70,6 +76,34 @@ export class Hilo {
     return calculateEdgeMultiplier(edgeBps).div(totalWinChance).decimalPlaces(4);
   }
 
+  static calculateNextPotentialMultiplierBN(hiloActions: HiloAction[], guess: HiloGuess, edgeBps: number): BigNumber {
+    if (hiloActions.length === 0) {
+      return new BigNumber(0);
+    }
+
+    if (guess === HiloGuess.SKIP) {
+      const last = hiloActions[hiloActions.length - 1];
+      return new BigNumber(last?.winMultiplier ?? 0);
+    }
+
+    const lastCardAndGuessActions: { lastCard: number; guess: HiloGuess }[] = [];
+    for (let i = 0; i < hiloActions.length - 1; i++) {
+      const current = hiloActions[i];
+      const next = hiloActions[i + 1];
+      if (current && next && next.guess !== HiloGuess.SKIP && next.guess !== null && current.card !== null) {
+        lastCardAndGuessActions.push({ lastCard: current.card, guess: next.guess });
+      }
+    }
+
+    const lastHiloAction = hiloActions[hiloActions.length - 1];
+    if (!lastHiloAction || lastHiloAction.card === null) {
+      return new BigNumber(0);
+    }
+    lastCardAndGuessActions.push({ lastCard: lastHiloAction.card, guess });
+
+    return this.calculateTotalMultiplierBN(lastCardAndGuessActions, edgeBps);
+  }
+
   static calculateMultiplier(guess: HiloGuess, previousCard: number, edgeBps: number): number {
     const result = this.calculateMultiplierBN(guess, previousCard, edgeBps);
 

package/src/games/keno.spec.ts

@@ -1,5 +1,5 @@
 import { createHmac } from 'crypto';
-import { Keno } from './keno';
+import { Keno, KenoRiskLevel } from './keno';
 
 describe('Keno', () => {
   it('be able to provably result', () => {
@@ -86,3 +86,22 @@ test('should contain the same length for each config', () => {
   });
 });
 
+describe('Keno.getMaxMultiplier', () => {
+  it('returns the largest payout for the given tiles/risk across every config', () => {
+    Keno.configs().forEach((config) => {
+      (Object.keys(config.payout) as KenoRiskLevel[]).forEach((risk) => {
+        const max = Keno.getMaxMultiplier(risk, config.tiles);
+        expect(max.toNumber()).toBe(Math.max(...config.payout[risk]));
+      });
+    });
+  });
+
+  it('picks a concrete known maximum (10 tiles, high risk)', () => {
+    expect(Keno.getMaxMultiplier(KenoRiskLevel.HIGH_RISK, 10).toNumber()).toBe(1000);
+  });
+
+  it('throws when no configuration exists for the tile count', () => {
+    expect(() => Keno.getMaxMultiplier(KenoRiskLevel.CLASSIC, 11)).toThrow('No configuration found for 11 tiles');
+  });
+});
+

package/src/games/keno.ts

@@ -116,6 +116,14 @@ export class Keno {
     return kenoConfigs;
   }
 
+  static getMaxMultiplier(risk: KenoRiskLevel, tiles: number): BigNumber {
+    const config = this.configs().find(config => config.tiles === tiles);
+    if (!config) {
+      throw new Error(`No configuration found for ${tiles} tiles`);
+    }
+    return BigNumber.max(...config.payout[risk].map(v => new BigNumber(v)));
+  }
+
   static calculateMultiplier(risk: KenoRiskLevel, selectedTiles: number[], results: number[]) {
     const matchedTiles = results.filter(result => selectedTiles.includes(result));
     const config = this.configs().find(config => config.tiles === selectedTiles.length);

package/src/games/plinko.spec.ts

@@ -78,6 +78,25 @@ describe('Plinko', () => {
   }
 });
 
+describe('Plinko.getMaxMultiplier', () => {
+  it('returns the largest payout for the given rows/risk across every config', () => {
+    Plinko.configs().forEach((config) => {
+      (Object.keys(config.payout) as PlinkoRiskLevel[]).forEach((risk) => {
+        const max = Plinko.getMaxMultiplier(risk, config.rows);
+        expect(max.toNumber()).toBe(Math.max(...config.payout[risk]));
+      });
+    });
+  });
+
+  it('picks a concrete known maximum (16 rows, high risk)', () => {
+    expect(Plinko.getMaxMultiplier(PlinkoRiskLevel.HIGH_RISK, 16).toNumber()).toBe(1000);
+  });
+
+  it('throws when no configuration exists for the row count', () => {
+    expect(() => Plinko.getMaxMultiplier(PlinkoRiskLevel.LOW_RISK, 7)).toThrow('No configuration found for 7 rows');
+  });
+});
+
 function generateDigestHex({
   serverSeed,
   clientSeed,

package/src/games/plinko.ts

@@ -122,6 +122,14 @@ export class Plinko {
     );
   }
 
+  static getMaxMultiplier(risk: PlinkoRiskLevel, rows: number): BigNumber {
+    const config = this.configs().find(config => config.rows === rows);
+    if (!config) {
+      throw new Error(`No configuration found for ${rows} rows`);
+    }
+    return BigNumber.max(...config.payout[risk].map(v => new BigNumber(v)));
+  }
+
   static calculateMultiplier(risk: PlinkoRiskLevel, rows: number, results: number[]) {
     const position = results.reduce((sum, result) => sum + result, 0);
     const config = this.configs().find(config => config.rows === rows);