shufflecom-calculations 6.12.1 → 6.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shufflecom-calculations",
-  "version": "6.12.1",
+  "version": "6.14.0",
   "description": "",
   "types": "lib/index.d.ts",
   "main": "lib/index.js",
@@ -19,5 +19,5 @@
   },
   "author": "",
   "license": "ISC",
-  "gitHead": "150cf4b9aac66f07c03577e943656c61b9daf3b3"
+  "gitHead": "bb40b80986c6a996592546bb531b86a6992fa184"
 }

package/src/games/stonks/constants.ts

@@ -33,4 +33,4 @@ export const STONKS_CHECKPOINT_INTERVAL_TICKS = 500;
 
 export const STONKS_PRICE_BAR_INTERVAL_TICKS = 5_000 / STONKS_TICK_DURATION_MS;
 
-export const STONKS_PROFIT_FEE_RATE = BigNumber(0.05);
+export const STONKS_PAYOUT_FEE_RATE = BigNumber(0.02);

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

@@ -44,15 +44,22 @@ describe('StonksRules', () => {
     it('inverts multiplierAtPrice without depending on amount', () => {
       const bet = openBet({ amount: number(0), leverage: number(10) });
 
-      const impliedPrice = StonksRules.impliedPriceForMultiplier(bet, number(1.5));
+      const impliedPrice = StonksRules.impliedPriceForMultiplier(bet, number('1.47'));
 
-      expect(StonksRules.multiplierAtPrice(bet, impliedPrice)).toBigNumberEqual(1.5);
+      expect(StonksRules.multiplierAtPrice(bet, impliedPrice)).toBigNumberEqual('1.47');
     });
 
     it('moves in the opposite price direction for DOWN bets', () => {
       const bet = openBet({ direction: StonksDirection.DOWN, leverage: number(10) });
 
-      expect(StonksRules.impliedPriceForMultiplier(bet, number(1.5))).toBigNumberEqual(95);
+      expect(StonksRules.impliedPriceForMultiplier(bet, number('1.47'))).toBigNumberEqual(95);
+    });
+
+    it('treats the multiplier as net of the fee, so 1x leverage needs more than a 100% move to reach 2x', () => {
+      const bet = openBet({ leverage: number(1) });
+
+      expect(StonksRules.impliedPriceForMultiplier(bet, number('1.96'))).toBigNumberEqual(200);
+      expect(StonksRules.impliedPriceForMultiplier(bet, number(2))).toBigNumberGreaterThan(200);
     });
   });
 
@@ -122,12 +129,22 @@ describe('StonksRules', () => {
     });
   });
 
-  describe('hasReachedTargetPrice', () => {
-    it('is inclusive of an exact match, in the direction of profit', () => {
-      expect(StonksRules.hasReachedTargetPrice(StonksDirection.UP, number(110), number(110))).toBe(true);
-      expect(StonksRules.hasReachedTargetPrice(StonksDirection.UP, number(109), number(110))).toBe(false);
-      expect(StonksRules.hasReachedTargetPrice(StonksDirection.DOWN, number(90), number(90))).toBe(true);
-      expect(StonksRules.hasReachedTargetPrice(StonksDirection.DOWN, number(91), number(90))).toBe(false);
+  describe('hasReachedTakeProfit', () => {
+    it('compares the net multiplier at the price against the take-profit, inclusive, in the direction of profit', () => {
+      const up = openBet({ direction: StonksDirection.UP, leverage: number(10) });
+      const down = openBet({ direction: StonksDirection.DOWN, leverage: number(10) });
+
+      expect(StonksRules.hasReachedTakeProfit(up, number(105), number('1.47'))).toBe(true);
+      expect(StonksRules.hasReachedTakeProfit(up, number('104.99'), number('1.47'))).toBe(false);
+      expect(StonksRules.hasReachedTakeProfit(down, number(95), number('1.47'))).toBe(true);
+      expect(StonksRules.hasReachedTakeProfit(down, number('95.01'), number('1.47'))).toBe(false);
+    });
+
+    it('needs the price to clear the fee: a 10% move at 10x reaches 1.96x, not 2x', () => {
+      const bet = openBet({ leverage: number(10) });
+
+      expect(StonksRules.hasReachedTakeProfit(bet, number(110), number('1.96'))).toBe(true);
+      expect(StonksRules.hasReachedTakeProfit(bet, number(110), number(2))).toBe(false);
     });
   });
 
@@ -141,10 +158,11 @@ describe('StonksRules', () => {
   });
 
   describe('multiplierAtPrice', () => {
-    it('is 1 at entry and floors at zero once loss would exceed the wager', () => {
+    it('is net of the fee at entry and floors at zero once loss would exceed the wager', () => {
       const bet = openBet({ entryPrice: number(100), leverage: number(10), direction: StonksDirection.UP });
 
-      expect(StonksRules.multiplierAtPrice(bet, number(100))).toBigNumberEqual(1);
+      expect(StonksRules.multiplierAtPrice(bet, number(100))).toBigNumberEqual('0.98');
+      expect(StonksRules.multiplierAtPrice(bet, number(110))).toBigNumberEqual('1.96');
       expect(StonksRules.multiplierAtPrice(bet, number(80))).toBigNumberEqual(0);
     });
   });
@@ -185,11 +203,11 @@ describe('StonksRules', () => {
       });
     });
 
-    it('fires MAX_PAYOUT once the gross payout reaches the live cap, even overshooting it', () => {
+    it('fires MAX_PAYOUT once the net payout reaches the live cap, even overshooting it', () => {
       const bet = openBet({ leverage: number(100) });
       const cap = number(150);
 
-      // At price 101 the gross payout (200) overshoots the cap (150) — MAX_PAYOUT still fires,
+      // At price 101 the net payout (196) overshoots the cap (150) — MAX_PAYOUT still fires,
       // and the caller settles at this real tick price regardless, not a price back-solved from the cap.
       expect(StonksRules.evaluateTriggers(bet, number(101), cap)).toEqual({
         fired: true,
@@ -212,7 +230,7 @@ describe('StonksRules', () => {
       const reason = { kind: StonksBetTerminalReason.MAX_PAYOUT, appliedCap: cap } as const;
 
       expect(StonksRules.evaluateTriggers(bet, impliedPrice, cap)).toEqual({ fired: true, reason });
-      expect(StonksRules.grossPayoutForReason(bet, reason, impliedPrice)).toBigNumberEqual(250);
+      expect(StonksRules.netPayoutForReason(bet, reason, impliedPrice)).toBigNumberEqual(250);
     });
 
     // The mirror of the case above, and the reason the cap cannot simply be checked before the
@@ -222,12 +240,12 @@ describe('StonksRules', () => {
       const takeProfitMultiplier = number(2);
       const bet = openBet({ takeProfitMultiplier });
       const cap = number(250);
-      // One tick jumps to 130, well past the TP-implied 110: the price-derived payout there is 400
-      // and clears the cap, but the agreed take-profit payout is only 100 × 2 = 200, under it.
+      // One tick jumps to 130, well past the TP-implied ~110.4: the price-derived net payout there
+      // is 392 and clears the cap, but the agreed take-profit payout is only 100 × 2 = 200, under it.
       const reason = { kind: StonksBetTerminalReason.TAKE_PROFIT, takeProfitMultiplier } as const;
 
       expect(StonksRules.evaluateTriggers(bet, number(130), cap)).toEqual({ fired: true, reason });
-      expect(StonksRules.grossPayoutForReason(bet, reason, number(130))).toBigNumberEqual(200);
+      expect(StonksRules.netPayoutForReason(bet, reason, number(130))).toBigNumberEqual(200);
     });
 
     it('fires TAKE_PROFIT, not MAX_PAYOUT, when the agreed take-profit payout exactly equals the live cap', () => {
@@ -254,38 +272,32 @@ describe('StonksRules', () => {
     });
   });
 
-  describe('grossPayoutForReason', () => {
+  describe('netPayoutForReason', () => {
     const bet = openBet({ leverage: number(10) });
 
     it('TAKE_PROFIT credits wager × multiplier exactly, ignoring price', () => {
       const takeProfitMultiplier = number('1.5');
 
       expect(
-        StonksRules.grossPayoutForReason(bet, { kind: StonksBetTerminalReason.TAKE_PROFIT, takeProfitMultiplier }, number(999)),
+        StonksRules.netPayoutForReason(bet, { kind: StonksBetTerminalReason.TAKE_PROFIT, takeProfitMultiplier }, number(999)),
       ).toBigNumberEqual(150);
     });
 
     it('LIQUIDATION is exact zero regardless of price', () => {
-      expect(StonksRules.grossPayoutForReason(bet, { kind: StonksBetTerminalReason.LIQUIDATION }, number(999))).toBigNumberEqual(0);
+      expect(StonksRules.netPayoutForReason(bet, { kind: StonksBetTerminalReason.LIQUIDATION }, number(999))).toBigNumberEqual(0);
     });
 
     it('MAX_PAYOUT is exactly the applied cap, ignoring price', () => {
       const appliedCap = number(150);
 
       expect(
-        StonksRules.grossPayoutForReason(bet, { kind: StonksBetTerminalReason.MAX_PAYOUT, appliedCap }, number(999)),
+        StonksRules.netPayoutForReason(bet, { kind: StonksBetTerminalReason.MAX_PAYOUT, appliedCap }, number(999)),
       ).toBigNumberEqual(150);
     });
 
-    it('CASHOUT and ROUND_END fall back to the price-derived gross payout', () => {
-      const priceDerivedPayout = StonksRules.grossPayoutAtPrice(bet, number(110));
-
-      expect(StonksRules.grossPayoutForReason(bet, { kind: StonksBetTerminalReason.CASHOUT }, number(110))).toBigNumberEqual(
-        priceDerivedPayout,
-      );
-      expect(StonksRules.grossPayoutForReason(bet, { kind: StonksBetTerminalReason.ROUND_END }, number(110))).toBigNumberEqual(
-        priceDerivedPayout,
-      );
+    it('CASHOUT and ROUND_END fall back to the price-derived payout, net of the fee', () => {
+      expect(StonksRules.netPayoutForReason(bet, { kind: StonksBetTerminalReason.CASHOUT }, number(110))).toBigNumberEqual(196);
+      expect(StonksRules.netPayoutForReason(bet, { kind: StonksBetTerminalReason.ROUND_END }, number(110))).toBigNumberEqual(196);
     });
   });
 
@@ -302,34 +314,29 @@ describe('StonksRules', () => {
     it.each([
       [StonksDirection.UP, number(101)],
       [StonksDirection.DOWN, number(99)],
-    ])('every other reason falls back to the price-derived multiplier, independently of wager (%s)', (direction, price) => {
+    ])('every other reason falls back to the price-derived net multiplier, independently of wager (%s)', (direction, price) => {
       const bet = openBet({ direction, amount: number(0) });
 
-      expect(StonksRules.multiplierForReason(bet, { kind: StonksBetTerminalReason.CASHOUT }, price)).toBigNumberEqual(1.1);
-      expect(StonksRules.multiplierForReason(bet, { kind: StonksBetTerminalReason.LIQUIDATION }, price)).toBigNumberEqual(1.1);
+      expect(StonksRules.multiplierForReason(bet, { kind: StonksBetTerminalReason.CASHOUT }, price)).toBigNumberEqual('1.078');
+      expect(StonksRules.multiplierForReason(bet, { kind: StonksBetTerminalReason.LIQUIDATION }, price)).toBigNumberEqual('1.078');
     });
   });
 
-  describe('netPayout', () => {
-    const wager = number(100);
-
-    it('passes losses and breakeven payouts through untaxed', () => {
-      expect(StonksRules.netPayout(number(90), wager)).toBigNumberEqual(90);
-      expect(StonksRules.netPayout(number(0), wager)).toBigNumberEqual(0);
-      expect(StonksRules.netPayout(wager, wager)).toBigNumberEqual(wager);
+  describe('netOfFee / grossOfFee', () => {
+    it('takes a flat 2% fee on every payout, including losses and breakeven', () => {
+      expect(StonksRules.netOfFee(number(90))).toBigNumberEqual('88.2');
+      expect(StonksRules.netOfFee(number(100))).toBigNumberEqual(98);
+      expect(StonksRules.netOfFee(number(101))).toBigNumberEqual('98.98');
+      expect(StonksRules.netOfFee(number(200))).toBigNumberEqual(196);
     });
 
-    it('taxes only the profit portion at 5%, never the wager', () => {
-      // gross 101 = wager + 1 profit; only the 1 is taxed, so net = 100 + 0.95 = 100.95
-      expect(StonksRules.netPayout(number(101), wager)).toBigNumberEqual('100.95');
-      // gross 200 = wager + 100 profit; net = 100 + 95 = 195
-      expect(StonksRules.netPayout(number(200), wager)).toBigNumberEqual(195);
+    it('leaves a liquidated payout at zero', () => {
+      expect(StonksRules.netOfFee(number(0))).toBigNumberEqual(0);
     });
 
-    it('never drops a nominal win below the wager, however small the gross profit is', () => {
-      const net = StonksRules.netPayout(number('100.01'), wager);
-
-      expect(net).toBigNumberGreaterThan(wager);
+    it('grossOfFee inverts netOfFee', () => {
+      expect(StonksRules.grossOfFee(number(98))).toBigNumberEqual(100);
+      expect(StonksRules.grossOfFee(StonksRules.netOfFee(number('123.456')))).toBigNumberEqual('123.456');
     });
   });
 });

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

@@ -4,7 +4,7 @@ import {
   STONKS_INTERNAL_PRICE_DECIMAL_PLACES,
   STONKS_MAX_STALE_CLIENT_TICKS,
   STONKS_MIN_TAKE_PROFIT_MULTIPLIER,
-  STONKS_PROFIT_FEE_RATE,
+  STONKS_PAYOUT_FEE_RATE,
   STONKS_ROUND_DURATION_MS,
   STONKS_ROUND_TICK_COUNT,
   STONKS_TICK_DURATION_MS,
@@ -38,7 +38,6 @@ export interface StonksTerminalBetState extends StonksOpenBetState {
   readonly terminalTick: number;
   readonly terminalPrice: BigNumber;
   readonly multiplier: BigNumber;
-  readonly grossPayout: BigNumber;
   readonly netPayout: BigNumber;
 }
 
@@ -67,7 +66,7 @@ export class StonksRules {
     targetMultiplier: BigNumber,
   ): BigNumber {
     const directionSign = bet.direction === StonksDirection.UP ? 1 : -1;
-    const multiplierDelta = targetMultiplier.minus(1);
+    const multiplierDelta = StonksRules.grossOfFee(targetMultiplier).minus(1);
     const priceChange = BigNumber(directionSign).multipliedBy(multiplierDelta).dividedBy(bet.leverage);
     return bet.entryPrice.multipliedBy(BigNumber(1).plus(priceChange));
   }
@@ -114,8 +113,12 @@ export class StonksRules {
     return new Date(startedAtMs + tick * STONKS_TICK_DURATION_MS);
   }
 
-  static hasReachedTargetPrice(direction: StonksDirection, currentPrice: BigNumber, targetPrice: BigNumber): boolean {
-    return direction === StonksDirection.UP ? currentPrice.isGreaterThanOrEqualTo(targetPrice) : currentPrice.isLessThanOrEqualTo(targetPrice);
+  static hasReachedTakeProfit(
+    bet: Pick<StonksOpenBetState, 'leverage' | 'entryPrice' | 'direction'>,
+    price: BigNumber,
+    takeProfitMultiplier: BigNumber,
+  ): boolean {
+    return StonksRules.multiplierAtPrice(bet, price).isGreaterThanOrEqualTo(takeProfitMultiplier);
   }
 
   static hasReachedBust(direction: StonksDirection, price: BigNumber, bustPrice: BigNumber): boolean {
@@ -127,11 +130,7 @@ export class StonksRules {
 
     if (bet.takeProfitMultiplier != null) {
       const takeProfitMultiplier = bet.takeProfitMultiplier;
-      const hitTakeProfit = StonksRules.hasReachedTargetPrice(
-        bet.direction,
-        tickPrice,
-        StonksRules.impliedPriceForMultiplier(bet, takeProfitMultiplier),
-      );
+      const hitTakeProfit = StonksRules.hasReachedTakeProfit(bet, tickPrice, takeProfitMultiplier);
       if (hitTakeProfit && hitBust) {
         throw new Error('StonksRules.evaluateTriggers: take profit and liquidation both fired');
       }
@@ -141,7 +140,7 @@ export class StonksRules {
         // A take-profit is the one reason whose payout is a fixed wager × multiplier rather than
         // something the tick price bounds, and the cap is read live every batch — so it can be
         // lowered under an already-agreed multiplier. Nothing downstream re-checks it.
-        if (StonksRules.grossPayoutForReason(bet, reason, tickPrice).isGreaterThan(liveMaxPayoutCap)) {
+        if (StonksRules.netPayoutForReason(bet, reason, tickPrice).isGreaterThan(liveMaxPayoutCap)) {
           return { fired: true, reason: { kind: StonksBetTerminalReason.MAX_PAYOUT, appliedCap: liveMaxPayoutCap } };
         }
         return { fired: true, reason };
@@ -152,19 +151,19 @@ export class StonksRules {
       return { fired: true, reason: { kind: StonksBetTerminalReason.LIQUIDATION } };
     }
 
-    if (StonksRules.grossPayoutAtPrice(bet, tickPrice).isGreaterThanOrEqualTo(liveMaxPayoutCap)) {
+    if (StonksRules.netPayoutAtPrice(bet, tickPrice).isGreaterThanOrEqualTo(liveMaxPayoutCap)) {
       return { fired: true, reason: { kind: StonksBetTerminalReason.MAX_PAYOUT, appliedCap: liveMaxPayoutCap } };
     }
     return { fired: false };
   }
 
-  static multiplierAtPrice(bet: StonksOpenBetState, price: BigNumber): BigNumber {
+  static multiplierAtPrice(bet: Pick<StonksOpenBetState, 'leverage' | 'entryPrice' | 'direction'>, price: BigNumber): BigNumber {
     const directionSign = bet.direction === StonksDirection.UP ? 1 : -1;
     const percentagePriceChange = price.minus(bet.entryPrice).dividedBy(bet.entryPrice);
     const leveragedPriceChange = BigNumber(directionSign).multipliedBy(bet.leverage).multipliedBy(percentagePriceChange);
 
-    const multiplier = BigNumber(1).plus(leveragedPriceChange);
-    return BigNumber.maximum(0, multiplier);
+    const grossMultiplier = BigNumber(1).plus(leveragedPriceChange);
+    return StonksRules.netOfFee(BigNumber.maximum(0, grossMultiplier));
   }
 
   static grossPayoutAtPrice(bet: StonksOpenBetState, price: BigNumber): BigNumber {
@@ -173,7 +172,11 @@ export class StonksRules {
     return BigNumber.maximum(0, bet.amount.plus(pnl));
   }
 
-  static grossPayoutForReason(bet: StonksOpenBetState, reason: StonksSettlementReason, price: BigNumber): BigNumber {
+  static netPayoutAtPrice(bet: StonksOpenBetState, price: BigNumber): BigNumber {
+    return StonksRules.netOfFee(StonksRules.grossPayoutAtPrice(bet, price));
+  }
+
+  static netPayoutForReason(bet: StonksOpenBetState, reason: StonksSettlementReason, price: BigNumber): BigNumber {
     switch (reason.kind) {
       case StonksBetTerminalReason.TAKE_PROFIT:
         return calculatePayoutBN(bet.amount, reason.takeProfitMultiplier);
@@ -183,10 +186,10 @@ export class StonksRules {
         return reason.appliedCap;
       case StonksBetTerminalReason.CASHOUT:
       case StonksBetTerminalReason.ROUND_END:
-        return StonksRules.grossPayoutAtPrice(bet, price);
+        return StonksRules.netPayoutAtPrice(bet, price);
       default:
         reason satisfies never;
-        throw new Error(`StonksRules.grossPayoutForReason: unhandled reason`);
+        throw new Error(`StonksRules.netPayoutForReason: unhandled reason`);
     }
   }
 
@@ -197,11 +200,11 @@ export class StonksRules {
     return StonksRules.multiplierAtPrice(bet, price);
   }
 
-  static netPayout(grossPayout: BigNumber, amount: BigNumber): BigNumber {
-    if (grossPayout.lte(amount)) {
-      return grossPayout;
-    }
-    const profit = grossPayout.minus(amount);
-    return amount.plus(profit.multipliedBy(BigNumber(1).minus(STONKS_PROFIT_FEE_RATE)));
+  static netOfFee(gross: BigNumber): BigNumber {
+    return gross.multipliedBy(BigNumber(1).minus(STONKS_PAYOUT_FEE_RATE));
+  }
+
+  static grossOfFee(net: BigNumber): BigNumber {
+    return net.dividedBy(BigNumber(1).minus(STONKS_PAYOUT_FEE_RATE));
   }
 }

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

@@ -147,6 +147,7 @@ export interface SportsBetCashoutInfoV3 {
   /** Non-null exactly when playerCashoutEnabled is ENABLED. */
   cashoutOddsDecimal: string | null;
   playerCashoutEnabled: SportsBetCashoutButtonState;
+  partialCashoutEnabled: boolean;
 }
 
 export interface CashoutSportsBetPayloadV2 {
@@ -154,7 +155,10 @@ export interface CashoutSportsBetPayloadV2 {
   currency: Currency;
   amount: string;
   status: SportsBetStatus;
-  settlement: { payoutOddsDecimal: string; payout: string };
+  // null after a partial cashout, the bet stays pending until the remaining stake is resulted
+  settlement: { payoutOddsDecimal: string; payout: string } | null;
+  partialCashoutBps: number | null;
+  partialCashoutPayout: string | null;
 }
 
 export interface SportsBetUpdatedPayloadV2 {

package/src/sports/sports.types.ts

@@ -103,6 +103,7 @@ export enum SportsCashoutFailedReason {
   SPORTS_CASHOUT_DISABLED = 'SPORTS_CASHOUT_DISABLED',
   SPORTS_MAINTENANCE = 'SPORTS_MAINTENANCE',
   CASHOUT_MARGIN_CAP_HIT = 'CASHOUT_MARGIN_CAP_HIT',
+  ALREADY_PARTIALLY_CASHED_OUT = 'ALREADY_PARTIALLY_CASHED_OUT',
 }
 
 export enum SportsBetCashoutButtonState {