@flayerlabs/gamemode-client 0.4.3 → 0.5.0

package/src/live.ts

@@ -26,6 +26,7 @@ import {
   type PresenceState,
   type Reaction,
   type RoundTerms,
+  type SpendToken,
   type WireEconomyBalance,
   type WireMarketState,
   type WireRoundTerms,
@@ -64,7 +65,7 @@ export interface Host {
     authorisation: Authorisation,
     progress?: (event: HostBuyProgress) => void,
     signal?: AbortSignal,
-  ): Promise<{ spentWei: bigint } | { failed: BuyResult }>;
+  ): Promise<{ spent: bigint } | { failed: BuyResult }>;
 }
 
 /** The host reports only what it uniquely knows; LiveRoom owns the terminal result. */
@@ -377,7 +378,7 @@ class LiveRoom<PublicView, PlayerView, Action> implements Room<PublicView, Playe
   readonly economy: Economy = {
     current: () => this.economySignal.current(),
     subscribe: (listener) => this.economySignal.subscribe(listener),
-    available: () => this.economySignal.current().availableWei,
+    available: () => this.economySignal.current().available,
     buy: (maxSpendWei) => this.buy(maxSpendWei),
   };
 
@@ -411,9 +412,9 @@ class LiveRoom<PublicView, PlayerView, Action> implements Room<PublicView, Playe
       return this.failBuy(attempt, 'try-again');
     }
 
-    let spendWei: bigint;
+    let spend: bigint;
     try {
-      spendWei = BigInt(authorisation.maxSpendWei);
+      spend = BigInt(authorisation.maxSpendWei);
     } catch {
       return this.failBuy(attempt, 'try-again');
     }
@@ -424,11 +425,11 @@ class LiveRoom<PublicView, PlayerView, Action> implements Room<PublicView, Playe
       ...before,
       ...(this.balanceRevision === balanceRevision
         ? {
-            heldWei: before.heldWei + spendWei,
-            availableWei: before.availableWei > spendWei ? before.availableWei - spendWei : 0n,
+            held: before.held + spend,
+            available: before.available > spend ? before.available - spend : 0n,
           }
         : {}),
-      buy: { state: 'signing', spendWei },
+      buy: { state: 'signing', spend },
     });
 
     let transactionHash: string | undefined;
@@ -443,8 +444,8 @@ class LiveRoom<PublicView, PlayerView, Action> implements Room<PublicView, Playe
         this.economySignal.set({
           ...current,
           buy: transactionHash === undefined
-            ? { state: 'pending', spendWei }
-            : { state: 'pending', spendWei, transactionHash },
+            ? { state: 'pending', spend }
+            : { state: 'pending', spend, transactionHash },
         });
       });
       hostSettled = true;
@@ -466,11 +467,11 @@ class LiveRoom<PublicView, PlayerView, Action> implements Room<PublicView, Playe
 
     const current = this.economySignal.current();
     const confirmed: BuyProgress = transactionHash === undefined
-      ? { state: 'confirmed', spentWei: result.spentWei }
-      : { state: 'confirmed', spentWei: result.spentWei, transactionHash };
+      ? { state: 'confirmed', spent: result.spent }
+      : { state: 'confirmed', spent: result.spent, transactionHash };
     // The signed allowance remains held until the gate observes chain settlement or it expires.
     this.economySignal.set({ ...current, buy: confirmed });
-    return { bought: true, spentWei: result.spentWei };
+    return { bought: true, spent: result.spent };
   }
 
   readonly social: Social = {
@@ -567,11 +568,11 @@ class LiveRoom<PublicView, PlayerView, Action> implements Room<PublicView, Playe
 
 function emptyEconomy(): EconomyState {
   return {
-    weiPerPoint: 0n,
-    earnedWei: 0n,
-    heldWei: 0n,
-    spentWei: 0n,
-    availableWei: 0n,
+    unitsPerPoint: 0n,
+    earned: 0n,
+    held: 0n,
+    spent: 0n,
+    available: 0n,
     holdExpiresAt: null,
     buy: null,
   };
@@ -582,13 +583,13 @@ function economyFrom(input: unknown): Omit<EconomyState, 'buy'> | null {
   const value = input as Partial<WireEconomyBalance>;
   try {
     const amounts = {
-      weiPerPoint: BigInt(value.weiPerPoint ?? '0'),
-      earnedWei: BigInt(value.earnedWei ?? '-1'),
-      heldWei: BigInt(value.heldWei ?? '-1'),
-      spentWei: BigInt(value.spentWei ?? '-1'),
-      availableWei: BigInt(value.availableWei ?? '-1'),
+      unitsPerPoint: BigInt(value.unitsPerPoint ?? '0'),
+      earned: BigInt(value.earned ?? '-1'),
+      held: BigInt(value.held ?? '-1'),
+      spent: BigInt(value.spent ?? '-1'),
+      available: BigInt(value.available ?? '-1'),
     };
-    if (amounts.weiPerPoint <= 0n || Object.values(amounts).some((amount) => amount < 0n)) return null;
+    if (amounts.unitsPerPoint <= 0n || Object.values(amounts).some((amount) => amount < 0n)) return null;
 
     // A deadline is either a whole millisecond timestamp or absent. Anything else — a string, a
     // fraction, Infinity — is a malformed frame, and a countdown drawn from one would run to a
@@ -614,38 +615,77 @@ export function termsFrom(input: unknown): RoundTerms | null {
   const value = input as Partial<WireRoundTerms>;
   const decimal = /^(0|[1-9][0-9]*)$/;
   if (
-    typeof value.walletCapWei !== 'string' ||
-    !decimal.test(value.walletCapWei) ||
-    typeof value.weiPerPoint !== 'string' ||
-    !decimal.test(value.weiPerPoint)
+    typeof value.walletCap !== 'string' ||
+    !decimal.test(value.walletCap) ||
+    typeof value.unitsPerPoint !== 'string' ||
+    !decimal.test(value.unitsPerPoint)
   ) return null;
   try {
-    const walletCapWei = BigInt(value.walletCapWei);
-    const weiPerPoint = BigInt(value.weiPerPoint);
-    const { maxPointsPerPlayer, pointsPerDollar, usdPerEth } = value;
+    const walletCap = BigInt(value.walletCap);
+    const unitsPerPoint = BigInt(value.unitsPerPoint);
+    const { maxPointsPerPlayer, pointsPerDollar, usdPerSpendToken } = value;
     if (
-      walletCapWei <= 0n ||
-      weiPerPoint <= 0n ||
+      walletCap <= 0n ||
+      unitsPerPoint <= 0n ||
       typeof maxPointsPerPlayer !== 'number' ||
       !Number.isSafeInteger(maxPointsPerPlayer) ||
       maxPointsPerPlayer <= 0 ||
       // Prices, not counts, so these are finite rather than integral. Both are still positive: a
-      // round priced at zero dollars an ETH is a round whose rate cannot mean anything.
+      // round priced at zero dollars a token is a round whose rate cannot mean anything.
       typeof pointsPerDollar !== 'number' ||
       !Number.isFinite(pointsPerDollar) ||
       pointsPerDollar <= 0 ||
-      typeof usdPerEth !== 'number' ||
-      !Number.isFinite(usdPerEth) ||
-      usdPerEth <= 0
+      typeof usdPerSpendToken !== 'number' ||
+      !Number.isFinite(usdPerSpendToken) ||
+      usdPerSpendToken <= 0
     ) {
       return null;
     }
-    return Object.freeze({ maxPointsPerPlayer, walletCapWei, weiPerPoint, pointsPerDollar, usdPerEth });
+    // The token is required: every amount in these terms is in its base units, so terms without it
+    // cannot be displayed or spent against. A gate that does not send one is not one this client
+    // can play against, and refusing here says so at the snapshot rather than in the arithmetic.
+    const spendToken = spendTokenFrom((value as { spendToken?: unknown }).spendToken);
+    if (!spendToken) return null;
+    return Object.freeze({
+      maxPointsPerPlayer,
+      walletCap,
+      unitsPerPoint,
+      pointsPerDollar,
+      usdPerSpendToken,
+      spendToken,
+    });
   } catch {
     return null;
   }
 }
 
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+
+function spendTokenFrom(input: unknown): SpendToken | null {
+  if (typeof input !== 'object' || input === null) return null;
+  const value = input as Partial<SpendToken>;
+  if (
+    typeof value.address !== 'string' ||
+    !ADDRESS.test(value.address) ||
+    typeof value.symbol !== 'string' ||
+    value.symbol.length === 0 ||
+    value.symbol.length > 64 ||
+    typeof value.decimals !== 'number' ||
+    !Number.isSafeInteger(value.decimals) ||
+    value.decimals < 0 ||
+    value.decimals > 36 ||
+    typeof value.isNative !== 'boolean'
+  ) {
+    return null;
+  }
+  return Object.freeze({
+    address: value.address,
+    symbol: value.symbol,
+    decimals: value.decimals,
+    isNative: value.isNative,
+  });
+}
+
 function presenceFrom(input: unknown): PresenceState | null {
   if (typeof input !== 'object' || input === null) return null;
   const value = input as Partial<PresenceState>;
@@ -707,14 +747,14 @@ export function marketFrom(input: unknown): MarketState | null {
         (trade.side !== 'buy' && trade.side !== 'sell') ||
         (trade.priceEth !== null && (typeof trade.priceEth !== 'number' || !Number.isFinite(trade.priceEth)))
       ) return [];
-      const spendWei = BigInt(trade.spendWei);
-      if (spendWei < 0n) return [];
+      const spend = BigInt(trade.spend);
+      if (spend < 0n) return [];
       return [{
         id: trade.id,
         at: trade.at,
         player: trade.player,
         side: trade.side,
-        spendWei,
+        spend,
         priceEth: trade.priceEth,
         ...(typeof trade.transactionHash === 'string' ? { transactionHash: trade.transactionHash } : {}),
       }];

package/src/mock.ts

@@ -2,6 +2,7 @@ import { Round } from '@flayerlabs/gamemode-spec/round';
 import { isRefusal, type GameModule, type PlayerId } from '@flayerlabs/gamemode-spec';
 import type { BuyProgress, BuyResult, Economy, EconomyState, MockOptions, Room, SendResult, Snapshot, Social } from './index.js';
 import {
+  ETH_SPEND_TOKEN,
   isReactionId,
   type ConnectionState,
   type LaunchContext,
@@ -16,8 +17,6 @@ import { CachedIdentityResolver } from './identity.js';
 /** How often the mock looks for a deadline that has fallen due. */
 const TICK_MS = 100;
 
-const WEI_PER_ETH = 1_000_000_000_000_000_000n;
-
 /** Long enough to see a spinner, short enough not to be annoying while building. */
 const FAKE_SIGN_MS = 150;
 const FAKE_PENDING_MS = 250;
@@ -29,13 +28,13 @@ export class MockRoom<Config, State, Event, Action, PublicView, PlayerView>
 {
   private readonly round: Round<Config, State, Event, Action, PublicView, PlayerView>;
   private readonly player: PlayerId;
-  private readonly weiPerPoint: bigint;
+  private readonly unitsPerPoint: bigint;
   private readonly allowedReactions: ReadonlySet<string>;
   private readonly listeners = new Set<(s: Snapshot<PublicView, PlayerView>) => void>();
   private readonly reactionListeners = new Set<(r: Reaction) => void>();
   private readonly timer: ReturnType<typeof setInterval>;
-  private spentWei = 0n;
-  private heldWei = 0n;
+  private spent = 0n;
+  private held = 0n;
   /** Mirrors the gate's five-minute hold, so a game can build the countdown against the mock. */
   private holdExpiresAt: number | null = null;
   private buyProgress: BuyProgress | null = null;
@@ -53,7 +52,7 @@ export class MockRoom<Config, State, Event, Action, PublicView, PlayerView>
   ) {
     const opensAt = Date.now() + (options.lobbyMs ?? 3_000);
     this.player = options.player ?? '0xyou';
-    this.weiPerPoint = options.weiPerPoint ?? 10_000_000_000_000n;
+    this.unitsPerPoint = options.unitsPerPoint ?? 10_000_000_000_000n;
     this.allowedReactions = new Set(options.reactionIds ?? []);
     if ([...this.allowedReactions].some((id) => !isReactionId(id))) {
       throw new RangeError('reactionIds must contain only valid reaction identifiers');
@@ -79,10 +78,10 @@ export class MockRoom<Config, State, Event, Action, PublicView, PlayerView>
     // may spend. Defaulting the cap to exactly that payout, and refusing anything under it, keeps
     // the mock from letting a game pass locally on numbers the gate would reject.
     const maxPointsPerPlayer = game.rewardBounds(options.config).maxPointsPerPlayer;
-    const flawlessRoundWei = BigInt(maxPointsPerPlayer) * this.weiPerPoint;
-    const walletCapWei = options.walletCapWei ?? flawlessRoundWei;
-    if (walletCapWei < flawlessRoundWei) {
-      throw new RangeError('walletCapWei must cover a flawless round, or the gate would refuse this launch');
+    const flawlessRoundWei = BigInt(maxPointsPerPlayer) * this.unitsPerPoint;
+    const walletCap = options.walletCap ?? flawlessRoundWei;
+    if (walletCap < flawlessRoundWei) {
+      throw new RangeError('walletCap must cover a flawless round, or the gate would refuse this launch');
     }
     // The gate derives its rate from these two, so the mock runs the identity backwards from
     // whatever rate it was given. Reporting three numbers that do not agree would let a menu built
@@ -91,17 +90,33 @@ export class MockRoom<Config, State, Event, Action, PublicView, PlayerView>
     if (!Number.isFinite(pointsPerDollar) || pointsPerDollar <= 0) {
       throw new RangeError('pointsPerDollar must be a positive finite number');
     }
-    const pointsPerEth = WEI_PER_ETH / this.weiPerPoint;
-    if (pointsPerEth <= 0n || pointsPerEth > BigInt(Number.MAX_SAFE_INTEGER)) {
-      throw new RangeError('weiPerPoint does not produce representable round terms');
+    // In the spend token's own base units — wei unless a token was given. The gate's identity is
+    // `unitsPerPoint = units / round(usdPerSpendToken × pointsPerDollar)`, so the mock runs it
+    // backwards and reports exactly the three numbers a live round would agree on.
+    const spendToken = options.spendToken ?? ETH_SPEND_TOKEN;
+    const decimals = spendToken.decimals;
+    if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > 36) {
+      throw new RangeError('spendToken.decimals must be an integer between 0 and 36');
+    }
+    const units = 10n ** BigInt(decimals);
+    const pointsPerToken = units / this.unitsPerPoint;
+    if (pointsPerToken <= 0n || pointsPerToken > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new RangeError('unitsPerPoint does not produce representable round terms');
     }
-    const usdPerEth = Number(pointsPerEth) / pointsPerDollar;
-    const roundTrip = WEI_PER_ETH / BigInt(Math.round(usdPerEth * pointsPerDollar));
-    if (roundTrip !== this.weiPerPoint) {
-      throw new RangeError('weiPerPoint must round-trip through gate pricing terms');
+    const usdPerSpendToken = Number(pointsPerToken) / pointsPerDollar;
+    const roundTrip = units / BigInt(Math.round(usdPerSpendToken * pointsPerDollar));
+    if (roundTrip !== this.unitsPerPoint) {
+      throw new RangeError('unitsPerPoint must round-trip through gate pricing terms');
     }
     this.termsSignal = new Signal<RoundTerms>(
-      Object.freeze({ maxPointsPerPlayer, walletCapWei, weiPerPoint: this.weiPerPoint, pointsPerDollar, usdPerEth }),
+      Object.freeze({
+        maxPointsPerPlayer,
+        walletCap,
+        unitsPerPoint: this.unitsPerPoint,
+        pointsPerDollar,
+        usdPerSpendToken,
+        spendToken: Object.freeze({ ...spendToken }),
+      }),
     );
     this.marketSignal = new Signal(
       options.platform?.market?.current() ?? { status: 'unavailable', prices: [], trades: [], marketCapUsd: null },
@@ -180,25 +195,25 @@ export class MockRoom<Config, State, Event, Action, PublicView, PlayerView>
   };
 
   private economyState(): EconomyState {
-    const earnedWei = BigInt(this.round.pointsFor(this.player)) * this.weiPerPoint;
-    const availableWei = earnedWei - this.spentWei - this.heldWei;
+    const earned = BigInt(this.round.pointsFor(this.player)) * this.unitsPerPoint;
+    const available = earned - this.spent - this.held;
     return {
-      weiPerPoint: this.weiPerPoint,
-      earnedWei,
-      heldWei: this.heldWei,
-      spentWei: this.spentWei,
-      availableWei: availableWei > 0n ? availableWei : 0n,
-      holdExpiresAt: this.heldWei > 0n ? this.holdExpiresAt : null,
+      unitsPerPoint: this.unitsPerPoint,
+      earned,
+      held: this.held,
+      spent: this.spent,
+      available: available > 0n ? available : 0n,
+      holdExpiresAt: this.held > 0n ? this.holdExpiresAt : null,
       buy: this.buyProgress,
     };
   }
 
   private readonly economySignal = new Signal<EconomyState>({
-    weiPerPoint: 0n,
-    earnedWei: 0n,
-    heldWei: 0n,
-    spentWei: 0n,
-    availableWei: 0n,
+    unitsPerPoint: 0n,
+    earned: 0n,
+    held: 0n,
+    spent: 0n,
+    available: 0n,
     holdExpiresAt: null,
     buy: null,
   });
@@ -210,7 +225,7 @@ export class MockRoom<Config, State, Event, Action, PublicView, PlayerView>
   readonly economy: Economy = {
     current: () => this.economyState(),
     subscribe: (listener) => this.economySignal.subscribe(listener),
-    available: () => this.economyState().availableWei,
+    available: () => this.economyState().available,
     buy: async (maxSpendWei: bigint): Promise<BuyResult> => {
       if (maxSpendWei <= 0n) {
         this.buyProgress = { state: 'failed', reason: 'nothing-to-spend' };
@@ -228,34 +243,34 @@ export class MockRoom<Config, State, Event, Action, PublicView, PlayerView>
       }
 
       const spend = maxSpendWei < available ? maxSpendWei : available;
-      this.heldWei += spend;
+      this.held += spend;
       this.holdExpiresAt = Date.now() + MOCK_HOLD_MS;
-      this.buyProgress = { state: 'signing', spendWei: spend };
+      this.buyProgress = { state: 'signing', spend: spend };
       this.publishEconomy();
 
       await new Promise((resolve) => setTimeout(resolve, FAKE_SIGN_MS));
       if (this.disposed) {
-        this.heldWei -= spend;
+        this.held -= spend;
         this.buyProgress = { state: 'failed', reason: 'try-again' };
         this.publishEconomy();
         return { bought: false, reason: 'try-again' };
       }
-      this.buyProgress = { state: 'pending', spendWei: spend };
+      this.buyProgress = { state: 'pending', spend: spend };
       this.publishEconomy();
 
       await new Promise((resolve) => setTimeout(resolve, FAKE_PENDING_MS));
       if (this.disposed) {
-        this.heldWei -= spend;
+        this.held -= spend;
         this.buyProgress = { state: 'failed', reason: 'try-again' };
         this.publishEconomy();
         return { bought: false, reason: 'try-again' };
       }
 
-      this.heldWei -= spend;
-      this.spentWei += spend;
-      this.buyProgress = { state: 'confirmed', spentWei: spend };
+      this.held -= spend;
+      this.spent += spend;
+      this.buyProgress = { state: 'confirmed', spent: spend };
       this.emit();
-      return { bought: true, spentWei: spend };
+      return { bought: true, spent: spend };
     },
   };
 

package/src/replay-market.ts

@@ -27,7 +27,7 @@ export interface MarketFixture {
     afterMs: number;
     player: string | null;
     side: 'buy' | 'sell';
-    spendWei: bigint;
+    spend: bigint;
     priceEth: number | null;
   }[];
   marketCapUsd?: number | null;
@@ -91,7 +91,7 @@ export function replayMarket(fixture: MarketFixture, now: () => number = Date.no
       at: startedAt + trade.afterMs,
       player: trade.player,
       side: trade.side,
-      spendWei: trade.spendWei,
+      spend: trade.spend,
       priceEth: trade.priceEth,
     }));
 
@@ -141,10 +141,10 @@ export const BUSY_LAUNCH: MarketFixture = {
     { afterMs: 18_000, priceEth: 0.000_049 },
   ],
   trades: [
-    { afterMs: 1_500, player: '0x1111111111111111111111111111111111111111', side: 'buy', spendWei: 12_000_000_000_000_000n, priceEth: 0.000_013 },
-    { afterMs: 5_200, player: '0x2222222222222222222222222222222222222222', side: 'buy', spendWei: 40_000_000_000_000_000n, priceEth: 0.000_021 },
-    { afterMs: 6_100, player: null, side: 'buy', spendWei: 8_000_000_000_000_000n, priceEth: 0.000_041 },
-    { afterMs: 9_400, player: '0x3333333333333333333333333333333333333333', side: 'sell', spendWei: 5_000_000_000_000_000n, priceEth: 0.000_039 },
-    { afterMs: 12_800, player: '0x1111111111111111111111111111111111111111', side: 'buy', spendWei: 25_000_000_000_000_000n, priceEth: 0.000_050 },
+    { afterMs: 1_500, player: '0x1111111111111111111111111111111111111111', side: 'buy', spend: 12_000_000_000_000_000n, priceEth: 0.000_013 },
+    { afterMs: 5_200, player: '0x2222222222222222222222222222222222222222', side: 'buy', spend: 40_000_000_000_000_000n, priceEth: 0.000_021 },
+    { afterMs: 6_100, player: null, side: 'buy', spend: 8_000_000_000_000_000n, priceEth: 0.000_041 },
+    { afterMs: 9_400, player: '0x3333333333333333333333333333333333333333', side: 'sell', spend: 5_000_000_000_000_000n, priceEth: 0.000_039 },
+    { afterMs: 12_800, player: '0x1111111111111111111111111111111111111111', side: 'buy', spend: 25_000_000_000_000_000n, priceEth: 0.000_050 },
   ],
 };