shufflecom-calculations 1.2.0 → 1.2.2

package/src/games/blackjack.ts

@@ -0,0 +1,408 @@
+import BigNumber from 'bignumber.js';
+import { CardGames, CardValue, Suits } from './cardGames';
+
+export enum BlackjackAction {
+  HIT = 'HIT',
+  STAND = 'STAND',
+  DOUBLE_DOWN = 'DOUBLE_DOWN',
+  SPLIT = 'SPLIT',
+  // player has to select one or the other before they can continue
+  BUY_INSURANCE = 'BUY_INSURANCE',
+  REJECT_INSURANCE = 'REJECT_INSURANCE',
+}
+
+export enum HandOutcome {
+  WIN = 'WIN', // refers to a win that pays out 2:1. Blackjacks after splits are still considered a HandOutcome.WIN and not HandOutcome.BLACKJACK as the payout is 2:1
+  LOSS = 'LOSS',
+  PUSH = 'PUSH',
+  BLACKJACK = 'BLACKJACK', // split hand can NEVER have a HandOutcome.BLACKJACK as the payout is 2:1 so it's a HandOutcome.WIN
+  PENDING = 'PENDING',
+  NONE = 'NONE', // for split player hand if the user has not split
+}
+
+export enum PerfectPairType {
+  PERFECT_PAIR = 'PERFECT_PAIR',
+  COLORED_PAIR = 'COLORED_PAIR',
+  MIXED_PAIR = 'MIXED_PAIR',
+}
+export enum TwentyOnePlusThreeType {
+  SUITED_TRIPS = 'SUITED_TRIPS',
+  STRAIGHT_FLUSH = 'STRAIGHT_FLUSH',
+  STRAIGHT = 'STRAIGHT',
+  THREE_OF_A_KIND = 'THREE_OF_A_KIND',
+  FLUSH = 'FLUSH',
+}
+
+export enum InsuranceStatus {
+  INELIGIBLE = 'INELIGIBLE',
+  BOUGHT_PAYS_OUT = 'BOUGHT_PAYS_OUT',
+  BOUGHT_DOES_NOT_PAY_OUT = 'BOUGHT_DOES_NOT_PAY_OUT',
+  REJECTED = 'REJECTED',
+  // if in eligible stage, user must choose to buy or not buy
+  ELIGIBLE = 'ELIGIBLE',
+}
+
+export interface SettleBetVars {
+  mainPlayerHand: number[];
+  splitPlayerHand: number[];
+  dealerHand: number[];
+  mainBetAmount: BigNumber; // the amount that the user entered when they placed the main bet
+  twentyOnePlusThreeAmount: BigNumber;
+  perfectPairAmount: BigNumber;
+  boughtInsurance: boolean;
+  hasSplit: boolean;
+  mainHandDoubleDown: boolean;
+  splitHandDoubleDown: boolean;
+}
+
+interface MainBetPayoutVars {
+  mainPlayerHand: number[];
+  splitPlayerHand: number[];
+  dealerHand: number[];
+  mainHandBetAmount: BigNumber;
+  splitHandBetAmount: BigNumber;
+  boughtInsurance: boolean;
+  hasSplit: boolean;
+}
+
+// Since the values are payout and not profit, it's the profit multiple + 1
+export const perfectPairPayout: Record<PerfectPairType, BigNumber> = {
+  [PerfectPairType.PERFECT_PAIR]: new BigNumber(26),
+  [PerfectPairType.COLORED_PAIR]: new BigNumber(13),
+  [PerfectPairType.MIXED_PAIR]: new BigNumber(7),
+};
+
+export const twentyOnePlusThreePayout: Record<TwentyOnePlusThreeType, BigNumber> = {
+  [TwentyOnePlusThreeType.SUITED_TRIPS]: new BigNumber(101),
+  [TwentyOnePlusThreeType.STRAIGHT_FLUSH]: new BigNumber(41),
+  [TwentyOnePlusThreeType.THREE_OF_A_KIND]: new BigNumber(31),
+  [TwentyOnePlusThreeType.STRAIGHT]: new BigNumber(11),
+  [TwentyOnePlusThreeType.FLUSH]: new BigNumber(6),
+};
+
+enum SuitColor {
+  RED = 'RED',
+  BLACK = 'BLACK',
+}
+const suitColorMap: Record<Suits, SuitColor> = {
+  [Suits.DIAMONDS]: SuitColor.RED,
+  [Suits.HEARTS]: SuitColor.RED,
+  [Suits.SPADES]: SuitColor.BLACK,
+  [Suits.CLUBS]: SuitColor.BLACK,
+};
+
+export class Blackjack {
+  static availableNextActions(
+    currentPlayerHand: number[],
+    dealerCards: number[],
+    insuranceStatus: InsuranceStatus,
+    atMainHandAndHasNotSplit: boolean,
+  ): BlackjackAction[] {
+    // User has to choose either one before they can continue
+    if (this.canBuyInsurance(dealerCards) && insuranceStatus === InsuranceStatus.ELIGIBLE) {
+      return [BlackjackAction.BUY_INSURANCE, BlackjackAction.REJECT_INSURANCE];
+    }
+
+    if (this.calcHandValue(currentPlayerHand) >= 21) {
+      return [];
+    }
+
+    const actions: BlackjackAction[] = [BlackjackAction.HIT, BlackjackAction.STAND];
+
+    if (this.canDoubleDown(currentPlayerHand)) {
+      actions.push(BlackjackAction.DOUBLE_DOWN);
+    }
+
+    if (this.canSplit(currentPlayerHand) && atMainHandAndHasNotSplit) {
+      actions.push(BlackjackAction.SPLIT);
+    }
+
+    return actions;
+  }
+
+  static playingMainHand(
+    mainPlayerCards: number[],
+    splitPlayerCards: number[],
+    mainPlayerActions: BlackjackAction[],
+    splitPlayerActions: BlackjackAction[],
+  ): boolean {
+    // still on main hand if main hand < 21 and user has not chosen to double down or stand (as these are the 2 actions that will end the main hand)
+    if (
+      this.calcHandValue(mainPlayerCards) < 21 &&
+      !mainPlayerActions.includes(BlackjackAction.DOUBLE_DOWN) &&
+      !mainPlayerActions.includes(BlackjackAction.STAND)
+    ) {
+      return true;
+    }
+
+    // on split hand if player has split and split hand is not yet over
+    if (
+      splitPlayerCards.length > 0 &&
+      this.calcHandValue(splitPlayerCards) < 21 &&
+      !splitPlayerActions.includes(BlackjackAction.DOUBLE_DOWN) &&
+      !splitPlayerActions.includes(BlackjackAction.STAND)
+    ) {
+      return false;
+    }
+
+    // player blackjack and dealer upcard A, so user is choosing whether to buy insurance in this case, and will end immediately after this action
+    if (mainPlayerCards.length === 2 && this.calcHandValue(mainPlayerCards) === 21 && splitPlayerCards.length === 0) {
+      return true;
+    }
+
+    // main hand busted/ended and no split hand
+    // OR main hand busted and split hand busted/ended
+    throw new Error('No available action');
+  }
+
+  static getHandOutcome(dealerCards: number[], playerCards: number[], hasSplit: boolean): { multiplier: BigNumber; outcome: HandOutcome } {
+    const dealerBlackjack = this.isBlackjack(dealerCards);
+    const playerBlackjack = this.isBlackjack(playerCards);
+
+    if (playerBlackjack && !dealerBlackjack && !hasSplit) {
+      return { multiplier: new BigNumber(2.5), outcome: HandOutcome.BLACKJACK };
+    }
+
+    if (dealerBlackjack && !playerBlackjack) {
+      return { multiplier: new BigNumber(0), outcome: HandOutcome.LOSS };
+    }
+
+    if (dealerBlackjack && playerBlackjack) {
+      return { multiplier: new BigNumber(1), outcome: HandOutcome.PUSH };
+    }
+
+    // If it reaches here, neither player nor dealer has blackjack
+    // if player busted, dealer auto wins
+    if (this.hasBusted(playerCards)) {
+      return { multiplier: new BigNumber(0), outcome: HandOutcome.LOSS };
+    }
+
+    if (this.hasBusted(dealerCards)) {
+      return { multiplier: new BigNumber(2), outcome: HandOutcome.WIN };
+    }
+
+    // Both did not bust, so compare the sum of cards
+    const playerSum = this.calcHandValue(playerCards);
+    const dealerSum = this.calcHandValue(dealerCards);
+    if (playerSum > dealerSum) {
+      return { multiplier: new BigNumber(2), outcome: HandOutcome.WIN };
+    } else if (playerSum < dealerSum) {
+      return { multiplier: new BigNumber(0), outcome: HandOutcome.LOSS };
+    } else {
+      return { multiplier: new BigNumber(1), outcome: HandOutcome.PUSH };
+    }
+  }
+
+  static calcSideBetWins(dealerUpCard: number, playerCards: number[]): { perfectPair?: PerfectPairType; twentyOnePlusThree?: TwentyOnePlusThreeType } {
+    const results: { perfectPair?: PerfectPairType; twentyOnePlusThree?: TwentyOnePlusThreeType } = {};
+    const dealerCardDetails = CardGames.getCardDetails(dealerUpCard);
+    const playerCard0 = CardGames.getCardDetails(playerCards[0]);
+    const playerCard1 = CardGames.getCardDetails(playerCards[1]);
+
+    // Perfect pairs
+    if (playerCard0.value === playerCard1.value) {
+      const cardSuits = [playerCard0.suit, playerCard1.suit] as const;
+
+      if (playerCards[0] === playerCards[1]) {
+        results.perfectPair = PerfectPairType.PERFECT_PAIR;
+      } else if (suitColorMap[cardSuits[0]] === suitColorMap[cardSuits[1]]) {
+        results.perfectPair = PerfectPairType.COLORED_PAIR;
+      } else {
+        results.perfectPair = PerfectPairType.MIXED_PAIR;
+      }
+    }
+
+    // 21+3
+    const cardValueMap: Record<CardValue, number[]> = {
+      '2': [2],
+      '3': [3],
+      '4': [4],
+      '5': [5],
+      '6': [6],
+      '7': [7],
+      '8': [8],
+      '9': [9],
+      '10': [10],
+      J: [11],
+      Q: [12],
+      K: [13],
+      A: [14, 1],
+    };
+
+    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];
+    const lastThreeCards = cardValues.slice(-3) as [number, number, number];
+
+    // this is done to account for ace being 1 or 14
+    const isStraight =
+      (firstThreeCards[0] + 1 === firstThreeCards[1] && firstThreeCards[1] + 1 === firstThreeCards[2]) ||
+      (lastThreeCards[0] + 1 === lastThreeCards[1] && lastThreeCards[1] + 1 === lastThreeCards[2]);
+    const threeOfAKind = dealerCardDetails.value === playerCard0.value && playerCard0.value === playerCard1.value;
+
+    if (dealerUpCard === playerCards[0] && playerCards[0] === playerCards[1]) {
+      results.twentyOnePlusThree = TwentyOnePlusThreeType.SUITED_TRIPS;
+    } else if (isFlush && isStraight) {
+      results.twentyOnePlusThree = TwentyOnePlusThreeType.STRAIGHT_FLUSH;
+    } else if (threeOfAKind) {
+      results.twentyOnePlusThree = TwentyOnePlusThreeType.THREE_OF_A_KIND;
+    } else if (isStraight) {
+      results.twentyOnePlusThree = TwentyOnePlusThreeType.STRAIGHT;
+    } else if (isFlush) {
+      results.twentyOnePlusThree = TwentyOnePlusThreeType.FLUSH;
+    }
+
+    return results;
+  }
+
+  static calcHandValue(cards: number[]): number {
+    // taking Ace as 11 here
+    const cardValueMap: Record<CardValue, number> = {
+      '2': 2,
+      '3': 3,
+      '4': 4,
+      '5': 5,
+      '6': 6,
+      '7': 7,
+      '8': 8,
+      '9': 9,
+      '10': 10,
+      A: 11,
+      J: 10,
+      Q: 10,
+      K: 10,
+    };
+
+    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) {
+      return cardSum;
+    }
+
+    // if there are aces, we need to consider the value of aces. If the sum is > 21, we need to consider the value of aces as 1
+    // Has aces and sum > 21
+    while (aceCount > 0 && cardSum > 21) {
+      cardSum -= 10;
+      aceCount--;
+    }
+
+    return cardSum;
+  }
+
+  static canBuyInsurance(dealerCards: number[]): boolean {
+    // player can only buy insurance if dealer's first card(upcard) is an ace
+    return CardGames.getCardDetails(dealerCards[0]).value === 'A';
+  }
+
+  // Dealer does NOT hit on soft 17 (for our implementation)
+  static shouldDealerHit(dealerCards: number[]): boolean {
+    return this.calcHandValue(dealerCards) < 17;
+  }
+
+  static hasBusted(cards: number[]): boolean {
+    return this.calcHandValue(cards) > 21;
+  }
+
+  static canSplit(mainHand: number[]): boolean {
+    if (mainHand.length !== 2) {
+      return false;
+    }
+    const cardActions = CardGames.getCardDetailsArr(mainHand);
+    return cardActions[0].value === cardActions[1].value;
+  }
+
+  static canDoubleDown(playerCards: number[]): boolean {
+    return playerCards.length === 2;
+  }
+
+  static isBlackjack(cards: number[]): boolean {
+    if (cards.length !== 2) {
+      return false;
+    }
+
+    return this.calcHandValue(cards) === 21;
+  }
+
+  /**
+   *
+   * 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 } {
+    // calculate main bet payout for main and split hand
+    const mainHandBetAmount = data.mainHandDoubleDown ? data.mainBetAmount.times(2) : data.mainBetAmount;
+    let splitHandBetAmount = new BigNumber(0);
+    if (data.hasSplit) {
+      splitHandBetAmount = data.splitHandDoubleDown ? data.mainBetAmount.times(2) : data.mainBetAmount;
+    }
+
+    // calculate sidebet payouts
+    let perfectPairPayoutAmt = new BigNumber(0);
+    let twentyOnePlusThreePayoutAmt = new BigNumber(0);
+
+    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 { perfectPair, twentyOnePlusThree } = Blackjack.calcSideBetWins(data.dealerHand[0], playerHand);
+
+    if (perfectPairPayout[perfectPair] && data.perfectPairAmount.gt(0)) {
+      perfectPairPayoutAmt = data.perfectPairAmount.times(perfectPairPayout[perfectPair]);
+    }
+
+    if (twentyOnePlusThreePayout[twentyOnePlusThree] && data.twentyOnePlusThreeAmount.gt(0)) {
+      twentyOnePlusThreePayoutAmt = data.twentyOnePlusThreeAmount.times(twentyOnePlusThreePayout[twentyOnePlusThree]);
+    }
+
+    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);
+
+    let multiplier = payout.dividedBy(totalBetAmount);
+
+    // when the user bets $0, assume an initial bet of $1 to calculate the multiplier
+    if (totalBetAmount.isZero()) {
+      const mainHandBetAmount = data.mainHandDoubleDown ? new BigNumber(2) : new BigNumber(1);
+      let splitHandBetAmount = new BigNumber(0);
+      if (data.hasSplit) {
+        splitHandBetAmount = data.splitHandDoubleDown ? new BigNumber(2) : new BigNumber(1);
+      }
+
+      const insuranceCost = data.boughtInsurance ? new BigNumber(0.5) : new BigNumber(0); // insurance costs half of the main bet
+      const totalBetAmount = mainHandBetAmount.plus(splitHandBetAmount).plus(insuranceCost);
+
+      multiplier = Blackjack.getMainBetPayout({ ...data, mainHandBetAmount, splitHandBetAmount }).payout.dividedBy(totalBetAmount);
+    }
+
+    return { payout, multiplier, mainHandOutcome, splitHandOutcome };
+  }
+
+  private static getMainBetPayout({
+    mainPlayerHand,
+    splitPlayerHand,
+    dealerHand,
+    mainHandBetAmount,
+    splitHandBetAmount,
+    boughtInsurance,
+    hasSplit,
+  }: MainBetPayoutVars) {
+    const { multiplier: mainHandMultiplier, outcome: mainHandOutcome } = Blackjack.getHandOutcome(dealerHand, mainPlayerHand, hasSplit);
+    const mainHandPayout = mainHandMultiplier.times(mainHandBetAmount);
+
+    const { multiplier: splitHandMultiplier, outcome: splitHandOutcome } = Blackjack.getHandOutcome(dealerHand, splitPlayerHand, hasSplit);
+
+    const splitHandPayout = splitPlayerHand.length > 0 ? splitHandMultiplier.times(splitHandBetAmount) : new BigNumber(0);
+
+    // calculate insurance payout (insurance payout is 3:1)
+    // insurance won't be claimed if double down occurs, so double downs won't affect insurance payout even though it doubles the mainHandBetAmount
+    const insurancePayout = boughtInsurance && Blackjack.isBlackjack(dealerHand) ? mainHandBetAmount.dividedBy(2).times(3) : new BigNumber(0);
+
+    return {
+      mainHandOutcome,
+      splitHandOutcome: hasSplit ? splitHandOutcome : HandOutcome.NONE,
+      payout: mainHandPayout.plus(splitHandPayout).plus(insurancePayout),
+    };
+  }
+}

package/src/games/cardGames.spec.ts

@@ -0,0 +1,94 @@
+import { createHmac } from 'crypto';
+import { CardGames, Suits } from './cardGames';
+
+describe('Card Games', () => {
+  it('be able to provably generate result', () => {
+    const gameSeeds = [
+      {
+        serverSeed: 'ebd3ff712ee7ed3cabe3753146f95847b017f847758ed254c531ff0d45686cea',
+        clientSeed: 'pf4jl5q97q',
+        nonce: '2',
+        results: [
+          0, 28, 45, 20, 35, 44, 40, 7, 10, 49, 3, 9, 7, 36, 50, 36, 43, 34, 17, 39, 43, 14, 43, 4, 20, 23, 15, 8, 15, 49, 40, 16, 25, 42, 27, 44, 17, 27, 36,
+          14, 33, 14, 29, 21, 13, 13, 11, 40, 46, 25, 38, 20,
+        ],
+      },
+      {
+        serverSeed: 'ebd3ff712ee7ed3cabe3753146f95847b017f847758ed254c531ff0d45686cea',
+        clientSeed: 'pf4jl5q97q',
+        nonce: '3',
+        results: [
+          17, 48, 16, 47, 3, 32, 48, 7, 33, 43, 23, 11, 7, 38, 34, 49, 47, 51, 44, 9, 21, 19, 49, 22, 9, 45, 34, 13, 35, 12, 30, 1, 38, 42, 19, 2, 12, 50, 21,
+          9, 40, 26, 27, 29, 34, 43, 11, 42, 5, 1, 34, 3,
+        ],
+      },
+      {
+        serverSeed: 'ebd3ff712ee7ed3cabe3753146f95847b017f847758ed254c531ff0d45686cea',
+        clientSeed: 'pf4jl5q97q',
+        nonce: '4',
+        results: [
+          4, 37, 25, 49, 8, 4, 47, 48, 12, 25, 41, 17, 48, 24, 49, 14, 33, 48, 39, 42, 21, 32, 46, 21, 1, 9, 19, 44, 3, 29, 23, 11, 24, 35, 51, 38, 10, 44, 15,
+          47, 49, 21, 22, 15, 16, 12, 9, 6, 2, 49, 21, 26,
+        ],
+      },
+      {
+        serverSeed: '652fb02cbce322c4232a9032d905ca580c77ed9cf4850ba6ce9990527d37949f',
+        clientSeed: 'l5sgv5cutr',
+        nonce: '2476',
+        results: [
+          14, 39, 3, 13, 28, 19, 20, 6, 30, 25, 22, 34, 35, 11, 2, 39, 11, 4, 23, 44, 36, 12, 20, 10, 20, 45, 2, 48, 21, 42, 13, 42, 41, 51, 2, 15, 33, 49, 32,
+          0, 41, 21, 12, 31, 39, 6, 16, 51, 34, 20, 48, 16,
+        ],
+      },
+    ];
+    gameSeeds.forEach((e) => {
+      const resultHex = generateDigestHex(e);
+      const results = CardGames.getResults(resultHex);
+      expect(results.slice(0, 52)).toEqual(e.results);
+    });
+  });
+
+  it('can give the right card details', () => {
+    expect(CardGames.getCardDetails(48).suit).toEqual(Suits.DIAMONDS);
+    expect(CardGames.getCardDetails(48).value).toEqual('A');
+    expect(CardGames.getCardDetails(49).suit).toEqual(Suits.HEARTS);
+    expect(CardGames.getCardDetails(49).value).toEqual('A');
+    expect(CardGames.getCardDetails(50).suit).toEqual(Suits.SPADES);
+    expect(CardGames.getCardDetails(50).value).toEqual('A');
+    expect(CardGames.getCardDetails(51).suit).toEqual(Suits.CLUBS);
+    expect(CardGames.getCardDetails(51).value).toEqual('A');
+
+    expect(CardGames.getCardDetails(47).value).toEqual('K');
+    expect(CardGames.getCardDetails(43).value).toEqual('Q');
+    expect(CardGames.getCardDetails(39).value).toEqual('J');
+    expect(CardGames.getCardDetails(27).value).toEqual('8');
+  });
+
+  it('can give the right card index', () => {
+    const zeroToFiftyOne = Array.from(Array(52).keys());
+    const cardDetails = zeroToFiftyOne.map((val) => CardGames.getCardDetails(val));
+    const indexes = cardDetails.map((val) => CardGames.getCardIndexFromDetails(val));
+    expect(indexes).toEqual(expect.arrayContaining(zeroToFiftyOne));
+    expect(zeroToFiftyOne).toEqual(expect.arrayContaining(indexes));
+  });
+});
+
+function generateDigestHex({
+  serverSeed,
+  clientSeed,
+  nonce,
+  rounds = 7,
+}: {
+  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;
+}

package/src/games/cardGames.ts

@@ -0,0 +1,162 @@
+import BigNumber from 'bignumber.js';
+import { hexToBytes } from '../utils';
+
+const BYTE_TOTAL = new BigNumber(256);
+
+const CARD_MAP: Record<string, 'A' | 'J' | 'Q' | 'K'> = {
+  '1': 'A',
+  '11': 'J',
+  '12': 'Q',
+  '13': 'K',
+};
+
+export enum Suits {
+  DIAMONDS = 'DIAMONDS',
+  HEARTS = 'HEARTS',
+  SPADES = 'SPADES',
+  CLUBS = 'CLUBS',
+}
+
+export const suitsArr = [Suits.DIAMONDS, Suits.HEARTS, Suits.SPADES, Suits.CLUBS];
+
+export type CardValue = '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | 'J' | 'Q' | 'K' | 'A';
+
+export interface CardDetail {
+  suit: Suits;
+  value: CardValue;
+}
+
+// contains generic card game util functions
+export class CardGames {
+  static toComparableNo(result: number) {
+    const comparableNo = Math.trunc(result / 4) + 2;
+
+    if (comparableNo === 14) {
+      return 1;
+    } else {
+      return comparableNo;
+    }
+  }
+
+  static getCardDetails(cardNum: number): CardDetail {
+    if (cardNum > 51 || cardNum < 0 || !Number.isInteger(cardNum)) {
+      throw 'out of bounds';
+    }
+    const suit = suitsArr[cardNum % 4];
+    let value = this.toComparableNo(cardNum).toString();
+
+    if (CARD_MAP[value]) {
+      value = CARD_MAP[value];
+    }
+
+    return { suit, value: value as CardValue };
+  }
+
+  static getCardDetailsArr(cardNums: number[]): CardDetail[] {
+    return cardNums.map((cardNum) => this.getCardDetails(cardNum));
+  }
+
+  static getResult(hexStr: string, cardNo: number): number {
+    const bytePosition = cardNo % 8;
+    const bytes = hexToBytes(hexStr);
+    let result = new BigNumber(0);
+    for (let j = 0; j < 4; j++) {
+      const value = bytes[4 * bytePosition + j];
+      result = result.plus(new BigNumber(value).dividedBy(BYTE_TOTAL.pow(j + 1)));
+    }
+    return result.multipliedBy(52).integerValue(BigNumber.ROUND_FLOOR).toNumber();
+  }
+
+  static getResults(hexStr: string[]): number[] {
+    const results: number[] = [];
+    for (let i = 0; i < hexStr.length * 8; i++) {
+      const hexNo = Math.trunc(i / 8);
+      results.push(this.getResult(hexStr[hexNo], i));
+    }
+    return results;
+  }
+
+  // TODO: Test this
+  static getCardIndexFromDetails(card: CardDetail): number {
+    const suitIncrement = suitsArr.indexOf(card.suit);
+
+    if (card.value === 'J') {
+      return 9 * 4 + suitIncrement;
+    } else if (card.value === 'Q') {
+      return 10 * 4 + suitIncrement;
+    } else if (card.value === 'K') {
+      return 11 * 4 + suitIncrement;
+    } else if (card.value === 'A') {
+      return 12 * 4 + suitIncrement;
+    } else {
+      return (Number(card.value) - 2) * 4 + suitIncrement;
+    }
+  }
+}
+
+// Index of 0 to 51 : ♦2 to ♣A
+// [
+// ♦2, ♥2, ♠2, ♣2, ♦3, ♥3, ♠3, ♣3, ♦4, ♥4,
+// ♠4, ♣4, ♦5, ♥5, ♠5, ♣5, ♦6, ♥6, ♠6, ♣6,
+// ♦7, ♥7, ♠7, ♣7, ♦8, ♥8, ♠8, ♣8, ♦9, ♥9,
+// ♠9, ♣9, ♦10, ♥10, ♠10, ♣10, ♦J, ♥J, ♠J,
+// ♣J, ♦Q, ♥Q, ♠Q, ♣Q, ♦K, ♥K, ♠K, ♣K, ♦A,
+// ♥A, ♠A, ♣A
+// ]
+
+// A = 1, 2 = 2 ,...10 = 10, J = 11, Q = 12, K = 13
+/**
+ * 0: ♦2
+ * 1: ♥2
+ * 2: ♠2
+ * 3: ♣2
+ * 4: ♦3
+ * 5: ♥3
+ * 6: ♠3
+ * 7: ♣3
+ * 8: ♦4
+ * 9: ♥4
+ * 10: ♠4
+ * 11: ♣4
+ * 12: ♦5
+ * 13: ♥5
+ * 14: ♠5
+ * 15: ♣5
+ * 16: ♦6
+ * 17: ♥6
+ * 18: ♠6
+ * 19: ♣6
+ * 20: ♦7
+ * 21: ♥7
+ * 22: ♠7
+ * 23: ♣7
+ * 24: ♦8
+ * 25: ♥8
+ * 26: ♠8
+ * 27: ♣8
+ * 28: ♦9
+ * 29: ♥9
+ * 30: ♠9
+ * 31: ♣9
+ * 32: ♦10
+ * 33: ♥10
+ * 34: ♠10
+ * 35: ♣10
+ * 36: ♦J
+ * 37: ♥J
+ * 38: ♠J
+ * 39: ♣J
+ * 40: ♦Q
+ * 41: ♥Q
+ * 42: ♠Q
+ * 43: ♣Q
+ * 44: ♦K
+ * 45: ♥K
+ * 46: ♠K
+ * 47: ♣K
+ * 48: ♦A
+ * 49: ♥A
+ * 50: ♠A
+ * 51: ♣A
+ *
+ */