shufflecom-calculations 6.11.0 → 6.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shufflecom-calculations",
-  "version": "6.11.0",
+  "version": "6.12.0",
   "description": "",
   "types": "lib/index.d.ts",
   "main": "lib/index.js",
@@ -19,5 +19,5 @@
   },
   "author": "",
   "license": "ISC",
-  "gitHead": "7897f76b991a949e4196070e368a66cb6e93edb4"
+  "gitHead": "6656b3e0dc340fe986901432c7fdf076d838c304"
 }

package/src/games/stonks/constants.ts

@@ -0,0 +1,44 @@
+import BigNumber from 'bignumber.js';
+
+export const STONKS_MIN_TAKE_PROFIT_MULTIPLIER = BigNumber(1.05);
+
+export const STONKS_TP_MIN_PROXIMITY_TO_ENTRY = BigNumber(0.001);
+export const STONKS_TP_MIN_PROXIMITY_TO_BUST = BigNumber(0.001);
+
+// Extra decimal precision carried internally, used only to detect bust price colliding with
+// entry price at high leverage / low price.
+export const STONKS_INTERNAL_PRICE_DECIMAL_PLACES = 10;
+
+// configurable platform setting instead of a code constant.
+export const STONKS_MIN_LEVERAGE = BigNumber(1);
+export const STONKS_MAX_LEVERAGE = BigNumber(1000);
+
+export const STONKS_MAX_ACTIVE_BETS_PER_ACCOUNT = 20;
+
+export const STONKS_START_PRICE = BigNumber(1000);
+export const STONKS_VOLATILITY = 0.001;
+
+export const STONKS_PRICE_DECIMAL_PLACES = 10;
+
+export const STONKS_TICK_DURATION_MS = 500;
+
+export const STONKS_SET_TICK_RETRY_DELAY_MS = 400;
+
+export const STONKS_MAX_STALE_CLIENT_TICKS = 10;
+
+export const STONKS_ROUND_DURATION_MS = 24 * 60 * 60 * 1_000;
+export const STONKS_ROUND_TICK_COUNT = STONKS_ROUND_DURATION_MS / STONKS_TICK_DURATION_MS;
+
+// How far back stonksRecentTicks will page into history before forcing the client onto
+// stonksOhlcHistory instead. PM-approved cap, not derived from any technical constraint.
+export const STONKS_MAX_TICK_HISTORY_MS = 48 * 60 * 60 * 1_000;
+
+// price is stored in cache every 500 ticks
+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);
+
+// Keep well under 2^53: contracts cross into Redis Lua's tonumber(), which loses precision above that (unlike BigNumber here)
+export const STONKS_CONTRACT_SCALE = BigNumber(10).pow(6);

package/src/games/stonks/rng/index.ts

@@ -0,0 +1,7 @@
+export {
+  StonksPriceCalculator,
+  StonksRandomState,
+  StonksRngCheckpoint,
+  StonksRngFn,
+} from './stonks-price-calculator';
+export { shuffleStonksRng } from './shuffle-stonks-rng';

package/src/games/{rollercoaster/rng/shuffle-rollercoaster-rng.spec.ts → stonks/rng/shuffle-stonks-rng.spec.ts}

@@ -1,12 +1,12 @@
-import { RollercoasterPriceCalculator } from './rollercoaster-price-calculator';
-import { shuffleRollercoasterRng } from './shuffle-rollercoaster-rng';
+import { StonksPriceCalculator } from './stonks-price-calculator';
+import { shuffleStonksRng } from './shuffle-stonks-rng';
 
 const SERVER_SEED = '5d24abb38b513ffe8ff815e6d37b68f5e165b8dbb965f066ea92e246e2de5681';
 const BITCOIN_BLOCK_HASH = '90d543f6352a959285472a3b5a259513c38bb0baa5af3a28e59a759983da1cb2';
 
-describe('shuffleRollercoasterRng', () => {
-  function buildCalculator(serverSeed = SERVER_SEED, bitcoinBlockHash = BITCOIN_BLOCK_HASH): RollercoasterPriceCalculator {
-    return new RollercoasterPriceCalculator(shuffleRollercoasterRng(serverSeed, bitcoinBlockHash));
+describe('shuffleStonksRng', () => {
+  function buildCalculator(serverSeed = SERVER_SEED, bitcoinBlockHash = BITCOIN_BLOCK_HASH): StonksPriceCalculator {
+    return new StonksPriceCalculator(shuffleStonksRng(serverSeed, bitcoinBlockHash));
   }
 
   it('matches the first 20 prices from the golden seed and Bitcoin block hash', () => {

package/src/games/{rollercoaster/rng/shuffle-rollercoaster-rng.ts → stonks/rng/shuffle-stonks-rng.ts}

@@ -1,8 +1,8 @@
 import { createHmac } from 'crypto';
 import BigNumber from 'bignumber.js';
-import { RollercoasterRandomState, RollercoasterRngCheckpoint, RollercoasterRngFn } from './rollercoaster-price-calculator';
+import { StonksRandomState, StonksRngCheckpoint, StonksRngFn } from './stonks-price-calculator';
 
-export function shuffleRollercoasterRng(serverSeed: string, bitcoinBlockHash: string): RollercoasterRngFn {
+export function shuffleStonksRng(serverSeed: string, bitcoinBlockHash: string): StonksRngFn {
   function initialDigest(): Buffer {
     return createHmac('sha256', serverSeed).update(bitcoinBlockHash).digest();
   }
@@ -11,17 +11,17 @@ export function shuffleRollercoasterRng(serverSeed: string, bitcoinBlockHash: st
     return createHmac('sha256', digest).update(bitcoinBlockHash).digest();
   }
 
-  function digestFromCheckpoint(checkpoint: RollercoasterRngCheckpoint): Buffer {
+  function digestFromCheckpoint(checkpoint: StonksRngCheckpoint): Buffer {
     const digest = Buffer.from(checkpoint.digest, 'hex');
     if (digest.length !== 32) {
-      throw new Error('shuffleRollercoasterRng: invalid checkpoint');
+      throw new Error('shuffleStonksRng: invalid checkpoint');
     }
     return digest;
   }
 
-  return (startTickIndex: number, endTickIndex: number, checkpoint?: RollercoasterRngCheckpoint): RollercoasterRandomState[] => {
+  return (startTickIndex: number, endTickIndex: number, checkpoint?: StonksRngCheckpoint): StonksRandomState[] => {
     let digest = checkpoint ? digestFromCheckpoint(checkpoint) : initialDigest();
-    const states: RollercoasterRandomState[] = [];
+    const states: StonksRandomState[] = [];
 
     for (let tick = startTickIndex; tick <= endTickIndex; tick++) {
       states.push({

package/src/games/{rollercoaster/rng/rollercoaster-price-calculator.spec.ts → stonks/rng/stonks-price-calculator.spec.ts}

@@ -1,8 +1,8 @@
 import BigNumber from 'bignumber.js';
-import { ROLLERCOASTER_VOLATILITY } from '../constants';
-import { RollercoasterPriceCalculator, RollercoasterRngFn } from './rollercoaster-price-calculator';
+import { STONKS_VOLATILITY } from '../constants';
+import { StonksPriceCalculator, StonksRngFn } from './stonks-price-calculator';
 
-function fixedRng(randomNumbers: BigNumber[]): RollercoasterRngFn {
+function fixedRng(randomNumbers: BigNumber[]): StonksRngFn {
   return (startTickIndex, endTickIndex) =>
     randomNumbers.slice(startTickIndex, endTickIndex + 1).map((randomNumber, index) => ({
       tick: startTickIndex + index,
@@ -11,10 +11,10 @@ function fixedRng(randomNumbers: BigNumber[]): RollercoasterRngFn {
     }));
 }
 
-describe('RollercoasterPriceCalculator', () => {
+describe('StonksPriceCalculator', () => {
   it('midpoint-normalizes uint32 boundary values so the quantile input is never zero or one', () => {
     const randomNumbers = [new BigNumber(0), new BigNumber(2 ** 32 - 1), new BigNumber(2 ** 31)];
-    const prices = randomNumbers.map(randomNumber => new RollercoasterPriceCalculator(fixedRng([randomNumber, new BigNumber(0)])).getPriceAtTick(1));
+    const prices = randomNumbers.map(randomNumber => new StonksPriceCalculator(fixedRng([randomNumber, new BigNumber(0)])).getPriceAtTick(1));
 
     for (const price of prices) {
       expect(price.isFinite()).toBe(true);
@@ -26,21 +26,21 @@ describe('RollercoasterPriceCalculator', () => {
   });
 
   it.each([new BigNumber(-1), new BigNumber(2 ** 32), new BigNumber(0.5)])('rejects an invalid uint32 value: %s', randomNumber => {
-    const calculator = new RollercoasterPriceCalculator(fixedRng([randomNumber]));
+    const calculator = new StonksPriceCalculator(fixedRng([randomNumber]));
 
-    expect(() => calculator.getPriceAtTick(0)).toThrow(`RollercoasterPriceCalculator: invalid random number ${randomNumber}`);
+    expect(() => calculator.getPriceAtTick(0)).toThrow(`StonksPriceCalculator: invalid random number ${randomNumber}`);
   });
 
   it('produces the expected volatility and price-variation distribution', () => {
     const sampleCount = 16_384;
     const uint32Range = 2 ** 32;
     const randomNumbers = Array.from({ length: sampleCount }, (_, index) => new BigNumber(((index + 0.5) * uint32Range) / sampleCount));
-    const ticks = new RollercoasterPriceCalculator(fixedRng([...randomNumbers, new BigNumber(0)])).getPricesInTickRange(0, sampleCount);
+    const ticks = new StonksPriceCalculator(fixedRng([...randomNumbers, new BigNumber(0)])).getPricesInTickRange(0, sampleCount);
     const priceVariations = ticks.slice(1).map((tick, index) => tick.price.dividedBy(ticks[index]!.price).minus(1).toNumber());
     const mean = priceVariations.reduce((sum, variation) => sum + variation, 0) / sampleCount;
     const standardDeviation = Math.sqrt(priceVariations.reduce((sum, variation) => sum + (variation - mean) ** 2, 0) / sampleCount);
-    const withinOneStandardDeviation = priceVariations.filter(variation => Math.abs(variation) <= ROLLERCOASTER_VOLATILITY).length / sampleCount;
-    const withinTwoStandardDeviations = priceVariations.filter(variation => Math.abs(variation) <= 2 * ROLLERCOASTER_VOLATILITY).length / sampleCount;
+    const withinOneStandardDeviation = priceVariations.filter(variation => Math.abs(variation) <= STONKS_VOLATILITY).length / sampleCount;
+    const withinTwoStandardDeviations = priceVariations.filter(variation => Math.abs(variation) <= 2 * STONKS_VOLATILITY).length / sampleCount;
 
     for (const tick of ticks) {
       expect(tick.price.isFinite()).toBe(true);
@@ -48,13 +48,13 @@ describe('RollercoasterPriceCalculator', () => {
     }
 
     expect(mean).toBeCloseTo(0, 8);
-    expect(standardDeviation).toBeCloseTo(ROLLERCOASTER_VOLATILITY, 6);
+    expect(standardDeviation).toBeCloseTo(STONKS_VOLATILITY, 6);
     expect(withinOneStandardDeviation).toBeCloseTo(0.6827, 3);
     expect(withinTwoStandardDeviations).toBeCloseTo(0.9545, 3);
   });
 
   it('resumes from a checkpoint using its stored price', () => {
-    const calculator = new RollercoasterPriceCalculator(fixedRng([new BigNumber(1), new BigNumber(2), new BigNumber(3), new BigNumber(4)]));
+    const calculator = new StonksPriceCalculator(fixedRng([new BigNumber(1), new BigNumber(2), new BigNumber(3), new BigNumber(4)]));
     const checkpoint = calculator.getPricesInTickRange(1, 1)[0]!;
 
     expect(calculator.getPricesInTickRange(2, 3, checkpoint)).toEqual(calculator.getPricesInTickRange(2, 3));

package/src/games/{rollercoaster/rng/rollercoaster-price-calculator.ts → stonks/rng/stonks-price-calculator.ts}

@@ -1,60 +1,60 @@
 import quantile from '@stdlib/stats-base-dists-normal-quantile';
 import BigNumber from 'bignumber.js';
-import { ROLLERCOASTER_PRICE_DECIMAL_PLACES, ROLLERCOASTER_START_PRICE, ROLLERCOASTER_VOLATILITY } from '../constants';
+import { STONKS_PRICE_DECIMAL_PLACES, STONKS_START_PRICE, STONKS_VOLATILITY } from '../constants';
 
 const UINT32_RANGE = new BigNumber(2).pow(32);
 const MAX_UINT32 = UINT32_RANGE.minus(1);
 
-export type RollercoasterRngCheckpoint = {
+export type StonksRngCheckpoint = {
   tick: number;
   price: BigNumber;
   digest: string;
 };
 
-export type RollercoasterRandomState = {
+export type StonksRandomState = {
   tick: number;
   randomNumber: BigNumber;
   digest: string;
 };
 
-export type RollercoasterRngFn = (
+export type StonksRngFn = (
   startTickIndex: number,
   endTickIndex: number,
-  checkpoint?: RollercoasterRngCheckpoint,
-) => RollercoasterRandomState[];
+  checkpoint?: StonksRngCheckpoint,
+) => StonksRandomState[];
 
-export class RollercoasterPriceCalculator {
-  constructor(private readonly getRngInRange: RollercoasterRngFn) {}
+export class StonksPriceCalculator {
+  constructor(private readonly getRngInRange: StonksRngFn) {}
 
-  public getPriceAtTick(tickIndex: number, checkpoint?: RollercoasterRngCheckpoint): BigNumber {
+  public getPriceAtTick(tickIndex: number, checkpoint?: StonksRngCheckpoint): BigNumber {
     return this.getPricesInTickRange(tickIndex, tickIndex, checkpoint)[0]!.price;
   }
 
-  public getPricesInTickRange(startTickIndex: number, endTickIndex: number, checkpoint?: RollercoasterRngCheckpoint): RollercoasterRngCheckpoint[] {
+  public getPricesInTickRange(startTickIndex: number, endTickIndex: number, checkpoint?: StonksRngCheckpoint): StonksRngCheckpoint[] {
     this.validateRange(startTickIndex, endTickIndex);
 
     const calculationStartTick = checkpoint?.tick ?? 0;
     if (!Number.isInteger(calculationStartTick) || calculationStartTick < 0 || calculationStartTick > startTickIndex) {
       throw new Error(
-        `RollercoasterPriceCalculator: checkpoint at tick ${calculationStartTick} is after requested range ${startTickIndex}..${endTickIndex}`,
+        `StonksPriceCalculator: checkpoint at tick ${calculationStartTick} is after requested range ${startTickIndex}..${endTickIndex}`,
       );
     }
 
-    let price = checkpoint?.price ?? ROLLERCOASTER_START_PRICE;
-    const ticks: RollercoasterRngCheckpoint[] = [];
+    let price = checkpoint?.price ?? STONKS_START_PRICE;
+    const ticks: StonksRngCheckpoint[] = [];
     const randomStates = this.getRngInRange(calculationStartTick, endTickIndex, checkpoint);
     const expectedRandomStateCount = endTickIndex - calculationStartTick + 1;
 
     if (randomStates.length !== expectedRandomStateCount) {
       throw new Error(
-        `RollercoasterPriceCalculator: expected ${expectedRandomStateCount} random states for ${calculationStartTick}..${endTickIndex}, got ${randomStates.length}`,
+        `StonksPriceCalculator: expected ${expectedRandomStateCount} random states for ${calculationStartTick}..${endTickIndex}, got ${randomStates.length}`,
       );
     }
 
     for (const [index, { tick, randomNumber, digest }] of randomStates.entries()) {
       const expectedTick = calculationStartTick + index;
       if (tick !== expectedTick) {
-        throw new Error(`RollercoasterPriceCalculator: expected random state at tick ${expectedTick}, got ${tick}`);
+        throw new Error(`StonksPriceCalculator: expected random state at tick ${expectedTick}, got ${tick}`);
       }
 
       this.validateRandomNumber(randomNumber);
@@ -73,20 +73,20 @@ export class RollercoasterPriceCalculator {
 
   private calculateNextPrice(price: BigNumber, randomNumber: BigNumber): BigNumber {
     const unitRangeFloat = randomNumber.plus(0.5).dividedBy(UINT32_RANGE).toNumber();
-    const tickReturn = quantile(unitRangeFloat, 0, ROLLERCOASTER_VOLATILITY);
+    const tickReturn = quantile(unitRangeFloat, 0, STONKS_VOLATILITY);
 
-    return price.multipliedBy(BigNumber(1).plus(tickReturn)).decimalPlaces(ROLLERCOASTER_PRICE_DECIMAL_PLACES);
+    return price.multipliedBy(BigNumber(1).plus(tickReturn)).decimalPlaces(STONKS_PRICE_DECIMAL_PLACES);
   }
 
   private validateRandomNumber(randomNumber: BigNumber): void {
     if (!randomNumber.isInteger() || randomNumber.lt(0) || randomNumber.gt(MAX_UINT32)) {
-      throw new Error(`RollercoasterPriceCalculator: invalid random number ${randomNumber}`);
+      throw new Error(`StonksPriceCalculator: invalid random number ${randomNumber}`);
     }
   }
 
   private validateRange(startTickIndex: number, endTickIndex: number): void {
     if (!Number.isInteger(startTickIndex) || !Number.isInteger(endTickIndex) || startTickIndex < 0 || endTickIndex < startTickIndex) {
-      throw new Error(`RollercoasterPriceCalculator: invalid tick range ${startTickIndex}..${endTickIndex}`);
+      throw new Error(`StonksPriceCalculator: invalid tick range ${startTickIndex}..${endTickIndex}`);
     }
   }
 }

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

@@ -0,0 +1,348 @@
+import BigNumber from 'bignumber.js';
+import {
+  STONKS_MIN_TAKE_PROFIT_MULTIPLIER,
+  STONKS_ROUND_DURATION_MS,
+  STONKS_ROUND_TICK_COUNT,
+  STONKS_TICK_DURATION_MS,
+} from './constants';
+import { StonksBetTerminalReason, StonksDirection, StonksOpenBetState, StonksRules } from './stonks-rules';
+
+const number = (value: BigNumber.Value) => new BigNumber(value);
+
+function openBet(overrides: Partial<StonksOpenBetState> = {}): StonksOpenBetState {
+  const direction = overrides.direction ?? StonksDirection.UP;
+  const entryPrice = overrides.entryPrice ?? number(100);
+  const leverage = overrides.leverage ?? number(10);
+  return {
+    direction,
+    amount: number(100),
+    leverage,
+    entryPrice,
+    entryTick: 0,
+    bustPrice: StonksRules.bustPrice(entryPrice, leverage, direction),
+    takeProfitMultiplier: null,
+    ...overrides,
+  };
+}
+
+describe('StonksRules', () => {
+  describe('bustPrice', () => {
+    it('sits below entry for UP and above entry for DOWN, offset by entry / leverage', () => {
+      expect(StonksRules.bustPrice(number(100), number(10), StonksDirection.UP)).toBigNumberEqual(90);
+      expect(StonksRules.bustPrice(number(100), number(10), StonksDirection.DOWN)).toBigNumberEqual(110);
+    });
+  });
+
+  describe('position', () => {
+    it('is wager × leverage, negated for DOWN', () => {
+      expect(StonksRules.position(number(100), number(10), StonksDirection.UP)).toBigNumberEqual(1_000);
+      expect(StonksRules.position(number(100), number(10), StonksDirection.DOWN)).toBigNumberEqual(-1_000);
+    });
+  });
+
+  describe('impliedPriceForMultiplier', () => {
+    it('inverts multiplierAtPrice without depending on amount', () => {
+      const bet = openBet({ amount: number(0), leverage: number(10) });
+
+      const impliedPrice = StonksRules.impliedPriceForMultiplier(bet, number(1.5));
+
+      expect(StonksRules.multiplierAtPrice(bet, impliedPrice)).toBigNumberEqual(1.5);
+    });
+
+    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);
+    });
+  });
+
+  describe('isValidTakeProfitMultiplier', () => {
+    it('requires the multiplier to exceed the configured floor', () => {
+      expect(StonksRules.isValidTakeProfitMultiplier(STONKS_MIN_TAKE_PROFIT_MULTIPLIER)).toBe(false);
+      expect(StonksRules.isValidTakeProfitMultiplier(STONKS_MIN_TAKE_PROFIT_MULTIPLIER.plus('0.01'))).toBe(true);
+    });
+  });
+
+  describe('isTakeProfitFarEnoughFromEntry / isTakeProfitFarEnoughFromBust', () => {
+    it('rejects an implied price too close to entry or too close to bust', () => {
+      const entryPrice = number(100);
+      const bustPrice = number(90);
+
+      expect(StonksRules.isTakeProfitFarEnoughFromEntry(entryPrice, number('100.0001'))).toBe(false);
+      expect(StonksRules.isTakeProfitFarEnoughFromEntry(entryPrice, number(110))).toBe(true);
+
+      expect(StonksRules.isTakeProfitFarEnoughFromBust(entryPrice, bustPrice, number('90.0001'))).toBe(false);
+      expect(StonksRules.isTakeProfitFarEnoughFromBust(entryPrice, bustPrice, number(110))).toBe(true);
+    });
+  });
+
+  describe('isBustPriceDistinctFromEntry', () => {
+    it('is false only when bust collides with entry at the internal precision', () => {
+      expect(StonksRules.isBustPriceDistinctFromEntry(number(100), number(100))).toBe(false);
+      expect(StonksRules.isBustPriceDistinctFromEntry(number(100), number('99.99999999999'))).toBe(false);
+      expect(StonksRules.isBustPriceDistinctFromEntry(number(100), number(90))).toBe(true);
+    });
+  });
+
+  describe('isFinalTick', () => {
+    it('is true only once the active tick reaches the last valid index', () => {
+      expect(StonksRules.isFinalTick(STONKS_ROUND_TICK_COUNT - 2)).toBe(false);
+      expect(StonksRules.isFinalTick(STONKS_ROUND_TICK_COUNT - 1)).toBe(true);
+    });
+  });
+
+  describe('isClientTickWithinMaxLag', () => {
+    it('allows up to the max stale ticks and rejects beyond it', () => {
+      expect(StonksRules.isClientTickWithinMaxLag(100, 90)).toBe(true);
+      expect(StonksRules.isClientTickWithinMaxLag(100, 89)).toBe(false);
+    });
+  });
+
+  describe('getScheduledRoundId / getScheduledRoundStartTime', () => {
+    it('round-trips a scheduled instant back to the same round id', () => {
+      const epochMs = 0;
+      const roundId = 42;
+      const startTime = StonksRules.getScheduledRoundStartTime(roundId, epochMs);
+
+      expect(StonksRules.getScheduledRoundId(startTime, epochMs)).toBe(roundId);
+      expect(startTime.getTime()).toBe(roundId * STONKS_ROUND_DURATION_MS);
+    });
+  });
+
+  describe('tickAtOrAfter / tickBefore / tickStartTime', () => {
+    const startedAtMs = 1_000_000;
+
+    it('round-trips a tick through its start time', () => {
+      const startTime = StonksRules.tickStartTime(startedAtMs, 7);
+
+      expect(startTime.getTime()).toBe(startedAtMs + 7 * STONKS_TICK_DURATION_MS);
+      expect(StonksRules.tickAtOrAfter(startedAtMs, startTime.getTime())).toBe(7);
+      expect(StonksRules.tickBefore(startedAtMs, startTime.getTime())).toBe(6);
+    });
+
+    it('puts an exact tick boundary on the boundary tick, not the one before it', () => {
+      const boundaryMs = startedAtMs + 3 * STONKS_TICK_DURATION_MS;
+
+      expect(StonksRules.tickAtOrAfter(startedAtMs, boundaryMs)).toBe(3);
+      expect(StonksRules.tickBefore(startedAtMs, boundaryMs)).toBe(2);
+    });
+
+    it('maps an instant inside a tick window to that tick as the last tick started before it', () => {
+      const insideMs = startedAtMs + 3 * STONKS_TICK_DURATION_MS + 1;
+
+      expect(StonksRules.tickBefore(startedAtMs, insideMs)).toBe(3);
+      expect(StonksRules.tickAtOrAfter(startedAtMs, insideMs)).toBe(4);
+    });
+  });
+
+  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('hasReachedBust', () => {
+    it('is inclusive of an exact match, in the direction of loss', () => {
+      expect(StonksRules.hasReachedBust(StonksDirection.UP, number(90), number(90))).toBe(true);
+      expect(StonksRules.hasReachedBust(StonksDirection.UP, number(91), number(90))).toBe(false);
+      expect(StonksRules.hasReachedBust(StonksDirection.DOWN, number(110), number(110))).toBe(true);
+      expect(StonksRules.hasReachedBust(StonksDirection.DOWN, number(109), number(110))).toBe(false);
+    });
+  });
+
+  describe('multiplierAtPrice', () => {
+    it('is 1 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(80))).toBigNumberEqual(0);
+    });
+  });
+
+  describe('grossPayoutAtPrice', () => {
+    it('scales pnl by leverage and floors at zero, matching direction', () => {
+      const bet = openBet({ direction: StonksDirection.UP, leverage: number(10) });
+
+      expect(StonksRules.grossPayoutAtPrice(bet, number(110))).toBigNumberEqual(200);
+      expect(StonksRules.grossPayoutAtPrice(bet, number(80))).toBigNumberEqual(0);
+    });
+  });
+
+  describe('evaluateTriggers', () => {
+    it('does not fire when price stays between bust and the caps', () => {
+      const bet = openBet();
+
+      expect(StonksRules.evaluateTriggers(bet, number(100), number(1_000))).toEqual({ fired: false });
+    });
+
+    it('fires LIQUIDATION once price reaches bust', () => {
+      const bet = openBet();
+
+      expect(StonksRules.evaluateTriggers(bet, bet.bustPrice, number(1_000))).toEqual({
+        fired: true,
+        reason: { kind: StonksBetTerminalReason.LIQUIDATION },
+      });
+    });
+
+    it('fires TAKE_PROFIT once price reaches the TP-implied price', () => {
+      const takeProfitMultiplier = number('1.5');
+      const bet = openBet({ takeProfitMultiplier });
+      const impliedPrice = StonksRules.impliedPriceForMultiplier(bet, takeProfitMultiplier);
+
+      expect(StonksRules.evaluateTriggers(bet, impliedPrice, number(1_000))).toEqual({
+        fired: true,
+        reason: { kind: StonksBetTerminalReason.TAKE_PROFIT, takeProfitMultiplier },
+      });
+    });
+
+    it('fires MAX_PAYOUT once the gross 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,
+      // 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,
+        reason: { kind: StonksBetTerminalReason.MAX_PAYOUT, appliedCap: cap },
+      });
+    });
+
+    // A take-profit is the one reason whose payout is a fixed wager × multiplier rather than
+    // something derived from the tick price, so it is also the one reason that can promise more
+    // than the live cap allows. The cap is read fresh every batch, so it can be lowered under an
+    // already-agreed take-profit; nothing downstream re-checks it, making this the only place the
+    // ceiling can be enforced.
+    it('fires MAX_PAYOUT instead of TAKE_PROFIT when the agreed take-profit payout exceeds the live cap', () => {
+      const takeProfitMultiplier = number(3);
+      const bet = openBet({ takeProfitMultiplier });
+      const cap = number(250);
+      // Wager 100 × 3 = 300, above the cap of 250.
+      const impliedPrice = StonksRules.impliedPriceForMultiplier(bet, takeProfitMultiplier);
+
+      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);
+    });
+
+    // The mirror of the case above, and the reason the cap cannot simply be checked before the
+    // take-profit: MAX_PAYOUT pays exactly the cap, so firing it on a take-profit that sits under
+    // the cap would pay MORE than the multiplier the player agreed to, not less.
+    it('still fires TAKE_PROFIT when the tick price overshoots the cap but the agreed payout does not', () => {
+      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.
+      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);
+    });
+
+    it('fires TAKE_PROFIT, not MAX_PAYOUT, when the agreed take-profit payout exactly equals the live cap', () => {
+      const takeProfitMultiplier = number('1.1');
+      const bet = openBet({ takeProfitMultiplier });
+      const cap = bet.amount.multipliedBy(takeProfitMultiplier);
+      const impliedPrice = StonksRules.impliedPriceForMultiplier(bet, takeProfitMultiplier);
+
+      expect(StonksRules.evaluateTriggers(bet, impliedPrice, cap)).toEqual({
+        fired: true,
+        reason: { kind: StonksBetTerminalReason.TAKE_PROFIT, takeProfitMultiplier },
+      });
+    });
+
+    it('throws if take profit and liquidation would fire on the same tick', () => {
+      // A degenerate takeProfitMultiplier of 0 pushes the TP-implied price down to coincide
+      // exactly with bust — evaluateTriggers doesn't itself validate the multiplier, so this
+      // "unreachable" collision is only actually prevented by isValidTakeProfitMultiplier upstream.
+      const bet = openBet({ takeProfitMultiplier: number(0) });
+
+      expect(() => StonksRules.evaluateTriggers(bet, bet.bustPrice, number(1_000))).toThrow(
+        'StonksRules.evaluateTriggers: take profit and liquidation both fired',
+      );
+    });
+  });
+
+  describe('grossPayoutForReason', () => {
+    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)),
+      ).toBigNumberEqual(150);
+    });
+
+    it('LIQUIDATION is exact zero regardless of price', () => {
+      expect(StonksRules.grossPayoutForReason(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)),
+      ).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,
+      );
+    });
+  });
+
+  describe('multiplierForReason', () => {
+    it('TAKE_PROFIT returns the agreed multiplier, ignoring price', () => {
+      const bet = openBet();
+      const takeProfitMultiplier = number('1.5');
+
+      expect(
+        StonksRules.multiplierForReason(bet, { kind: StonksBetTerminalReason.TAKE_PROFIT, takeProfitMultiplier }, number(999)),
+      ).toBigNumberEqual(takeProfitMultiplier);
+    });
+
+    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) => {
+      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);
+    });
+  });
+
+  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);
+    });
+
+    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('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);
+    });
+  });
+});