@flayerlabs/gamemode-gate 0.5.4 → 0.5.6

package/src/chain/registry-prices.ts

@@ -0,0 +1,194 @@
+import { formatUnits, parseAbi, type PublicClient } from 'viem';
+import type { SpendToken } from '@flayerlabs/gamemode-spec/live';
+import type { AnnouncedSpendToken, PriceFor } from '../server.js';
+import { resolveEconomy, unitsPerToken } from '../economy.js';
+
+/**
+ * Prices for any paired token the chain itself has approved, so a gate runs rounds on every
+ * pairing the protocol allows without anyone listing it first.
+ *
+ * A v1.3 PositionManager names its `PairedTokenRegistry`, and the registry names the price
+ * calculator each approved token was registered with — the same quote a launch uses to size a
+ * coin's starting price. That calculator answers "how many tokens is one ETH", and the operator's
+ * `USD_PER_ETH` turns that into dollars. Nothing here is typed by a person: an unapproved token has
+ * no calculator and is refused, exactly as the launch itself would be.
+ *
+ * Quotes are cached briefly. Adoption happens once per launch, so the cache protects the RPC from a
+ * burst of `/config/spend-tokens` reads by launch tooling, not from adoption itself. A quote that
+ * cannot be read throws, and the server answers adoption with 503 rather than a made-up price.
+ */
+
+const managerAbi = parseAbi(['function pairedTokenRegistry() view returns (address)']);
+const registryAbi = parseAbi([
+  'function isApproved(address token) view returns (bool)',
+  'function tokenConfig(address token) view returns ((bool approved, uint8 tokenType, uint8 decimals, address underlying, address feeEscrow, address priceCalculator, uint256 minDistribute, uint256 bidWallThreshold))',
+]);
+const calculatorAbi = parseAbi(['function ethToPairedToken(uint256 ethAmount) view returns (uint256)']);
+const erc20Abi = parseAbi(['function symbol() view returns (string)', 'function decimals() view returns (uint8)']);
+
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+
+/** The subset of a viem public client this module needs, so tests can script it. */
+export type RegistryReader = Pick<PublicClient, 'readContract'>;
+
+export interface RegistryPricesOptions {
+  /** The manager whose registry decides which pairings exist. */
+  positionManager: `0x${string}`;
+  /** The chain's flETH wrapper, priced as ETH and never asked of the registry. */
+  fleth?: `0x${string}`;
+  /** Dollars per ETH; every registry quote is in ETH. */
+  usdPerEth: number;
+  /** How long a quote is reused, in milliseconds. */
+  ttlMs?: number;
+  /** Injectable for tests. */
+  now?: () => number;
+}
+
+export interface RegistryQuote {
+  /** Dollars per whole token, to eight significant digits. */
+  usdPerToken: number;
+  /** Whole tokens per ETH as the registry's calculator quoted them. */
+  tokensPerEth: number;
+  priceCalculator: `0x${string}`;
+}
+
+/** What `/config/spend-tokens/:address` needs to size a launch's cap. */
+export interface AnnounceOptions {
+  maxPointsPerPlayer: number;
+  pointsPerDollar: number;
+  /** Percent added over the smallest cap a flawless round fits under. */
+  headroomPercent: number;
+}
+
+export class RegistryPrices {
+  private registry: Promise<`0x${string}` | null> | undefined;
+  private readonly quotes = new Map<string, { quote: RegistryQuote | null; at: number }>();
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+
+  constructor(
+    private readonly client: RegistryReader,
+    private readonly options: RegistryPricesOptions,
+  ) {
+    this.ttlMs = options.ttlMs ?? 60_000;
+    this.now = options.now ?? Date.now;
+  }
+
+  /**
+   * The registry the manager names, or null for a manager that predates paired tokens. Read once:
+   * the address is immutable on chain, and a gate serves exactly one manager.
+   */
+  registryAddress(): Promise<`0x${string}` | null> {
+    this.registry ??= this.client
+      .readContract({ address: this.options.positionManager, abi: managerAbi, functionName: 'pairedTokenRegistry' })
+      .then((address) => (address.toLowerCase() === ZERO_ADDRESS ? null : address))
+      .catch(() => null);
+    return this.registry;
+  }
+
+  /** ETH by any name is the operator's `USD_PER_ETH`; it is never asked of the registry. */
+  private isEthEquivalent(address: string): boolean {
+    const lower = address.toLowerCase();
+    return lower === ZERO_ADDRESS || (this.options.fleth !== undefined && lower === this.options.fleth.toLowerCase());
+  }
+
+  /**
+   * The registry's quote for a token, or null when it is not approved or has no calculator.
+   * Throws when the chain cannot be read, so a caller refuses for now rather than for good.
+   */
+  async quote(address: string): Promise<RegistryQuote | null> {
+    const key = address.toLowerCase();
+    const cached = this.quotes.get(key);
+    if (cached && this.now() - cached.at < this.ttlMs) return cached.quote;
+    const quote = await this.read(address as `0x${string}`);
+    this.quotes.set(key, { quote, at: this.now() });
+    return quote;
+  }
+
+  private async read(token: `0x${string}`): Promise<RegistryQuote | null> {
+    const registry = await this.registryAddress();
+    if (!registry) return null;
+    const approved = await this.client.readContract({ address: registry, abi: registryAbi, functionName: 'isApproved', args: [token] });
+    if (!approved) return null;
+    const config = await this.client.readContract({ address: registry, abi: registryAbi, functionName: 'tokenConfig', args: [token] });
+    const priceCalculator = config.priceCalculator;
+    if (!priceCalculator || priceCalculator.toLowerCase() === ZERO_ADDRESS) return null;
+    const decimals = Number(config.decimals);
+    const perEth = await this.client.readContract({
+      address: priceCalculator,
+      abi: calculatorAbi,
+      functionName: 'ethToPairedToken',
+      args: [unitsPerToken(18)],
+    });
+    if (perEth <= 0n) return null;
+    // String-based division: no binary float noise in a whole-token quote.
+    const tokensPerEth = Number(formatUnits(perEth, decimals));
+    if (!Number.isFinite(tokensPerEth) || tokensPerEth <= 0) return null;
+    const usdPerToken = Number((this.options.usdPerEth / tokensPerEth).toPrecision(8));
+    return { usdPerToken, tokensPerEth, priceCalculator };
+  }
+
+  /** A {@link PriceFor}: dollars per whole token for any approved pairing, null for the rest. */
+  priceFor: PriceFor = async (token: SpendToken) => {
+    if (this.isEthEquivalent(token.address)) return null;
+    const quote = await this.quote(token.address);
+    return quote?.usdPerToken ?? null;
+  };
+
+  /**
+   * The entry launch tooling needs before a coin is paid for: the token as the chain describes
+   * it, the price the gate will fix a round at, and the smallest per-wallet cap a flawless round
+   * fits under plus the operator's headroom. Null for a token the registry does not approve.
+   */
+  async announce(address: `0x${string}`, options: AnnounceOptions): Promise<AnnouncedSpendToken | null> {
+    if (this.isEthEquivalent(address)) return null;
+    const quote = await this.quote(address);
+    if (!quote) return null;
+    const [symbol, decimals] = await Promise.all([
+      this.client.readContract({ address, abi: erc20Abi, functionName: 'symbol' }),
+      this.client.readContract({ address, abi: erc20Abi, functionName: 'decimals' }).then(Number),
+    ]);
+    const walletCap = minimumWalletCap(quote.usdPerToken, decimals, options);
+    if (walletCap === null) return null;
+    return {
+      address,
+      symbol,
+      decimals,
+      usdPerToken: quote.usdPerToken,
+      walletCap: withHeadroom(walletCap, options.headroomPercent).toString(),
+    };
+  }
+}
+
+/**
+ * The smallest per-wallet cap under which a flawless round fits, in the token's base units, or
+ * null when no cap makes the economy work at this price. Checked against {@link resolveEconomy}
+ * rather than trusted, because that function is the one place the rule is written down.
+ */
+export function minimumWalletCap(
+  usdPerToken: number,
+  decimals: number,
+  options: Pick<AnnounceOptions, 'maxPointsPerPlayer' | 'pointsPerDollar'>,
+): bigint | null {
+  const pointsPerToken = Math.round(usdPerToken * options.pointsPerDollar);
+  if (pointsPerToken <= 0) return null;
+  const unitsPerPoint = unitsPerToken(decimals) / BigInt(pointsPerToken);
+  if (unitsPerPoint <= 0n) return null;
+  const minimum = BigInt(Math.floor(options.maxPointsPerPlayer)) * unitsPerPoint;
+  const fit = resolveEconomy({
+    maxPointsPerPlayer: options.maxPointsPerPlayer,
+    walletCap: minimum,
+    pointsPerDollar: options.pointsPerDollar,
+    usdPerSpendToken: usdPerToken,
+    decimals,
+  });
+  return fit.ok ? minimum : null;
+}
+
+/** A cap with the operator's percentage headroom, rounded down to base units. */
+export function withHeadroom(cap: bigint, headroomPercent: number): bigint {
+  if (!Number.isSafeInteger(headroomPercent) || headroomPercent < 0) {
+    throw new Error('headroom percent must be a non-negative integer');
+  }
+  return (cap * BigInt(100 + headroomPercent)) / 100n;
+}

package/src/economy.ts

@@ -81,6 +81,16 @@ function resolveInputs(input: EconomyInput): { usdPerSpendToken: number; decimal
  * goes and reads this file.
  */
 export function resolveEconomy(input: EconomyInput): EconomyResult {
+  return evaluate(input, true);
+}
+
+/**
+ * The check itself. `suggest` is false while {@link minimumPointsPerDollar} is probing candidates:
+ * a refusal there must not go looking for a suggestion of its own, or a cap one unit short of
+ * fitting recurses until the stack gives out — which is how this function once took a gate down at
+ * boot instead of printing the number that fixes it.
+ */
+function evaluate(input: EconomyInput, suggest: boolean): EconomyResult {
   const { maxPointsPerPlayer, walletCap, pointsPerDollar } = input;
   const { usdPerSpendToken, decimals } = resolveInputs(input);
 
@@ -125,7 +135,7 @@ export function resolveEconomy(input: EconomyInput): EconomyResult {
     return {
       ok: false,
       problem: 'one point would be worth more than a whole spend token, which cannot be what was meant',
-      suggestedPointsPerDollar: minimumPointsPerDollar(input),
+      suggestedPointsPerDollar: suggest ? minimumPointsPerDollar(input) : pointsPerDollar,
     };
   }
 
@@ -144,7 +154,7 @@ export function resolveEconomy(input: EconomyInput): EconomyResult {
     return {
       ok: false,
       problem: 'a perfect round would earn more than this launch lets one wallet spend',
-      suggestedPointsPerDollar: minimumPointsPerDollar(input),
+      suggestedPointsPerDollar: suggest ? minimumPointsPerDollar(input) : pointsPerDollar,
     };
   }
 
@@ -179,7 +189,7 @@ function minimumPointsPerDollar(input: EconomyInput): number {
     Number.isSafeInteger(decimals) && decimals >= 0 && decimals <= 36 ? unitsPerToken(decimals) : WEI_PER_ETH;
   let candidate = Math.ceil(Number(units / maxUnitsPerPoint) / usdPerSpendToken);
   for (let i = 0; i < 3; i++) {
-    const result = resolveEconomy({ ...input, pointsPerDollar: candidate });
+    const result = evaluate({ ...input, pointsPerDollar: candidate }, false);
     if (result.ok) return candidate;
     candidate += 1;
   }

package/src/index.ts

@@ -66,11 +66,14 @@ export type { VerifiedPlayerJoin, VerifyPlayerJoinTicketOptions } from './player
  */
 export { startGate, resolveGateEnv } from './main.js';
 export type { ResolvedGateConfig, SpendTokenPricing, StartedGate, StartGateOverrides } from './main.js';
-export type { GateAnnouncement } from './server.js';
+export type { GateAnnouncement, ServedGateAnnouncement } from './server.js';
+export { GATE_MARKER, GATE_VERSION } from './version.js';
 export { NotSignedIn } from './sessions.js';
 export { DEPLOYMENTS, PAIRED_DEPLOYMENTS, deploymentFor } from './chain/chains.js';
 export type { FlaunchVariant, GateDeployment } from './chain/chains.js';
 export { POSITION_MANAGER_ROLE, assertSecureConfig } from './chain/secure.js';
+export { RegistryPrices, minimumWalletCap, withHeadroom } from './chain/registry-prices.js';
+export type { AnnounceOptions, RegistryPricesOptions, RegistryQuote, RegistryReader } from './chain/registry-prices.js';
 
 export { createGateReadiness } from './readiness.js';
 export type { GateReadinessOptions } from './readiness.js';

package/src/main.ts

@@ -15,6 +15,7 @@ import { migrate } from './store.js';
 import { resolveEconomy } from './economy.js';
 import { deploymentFor, type GateDeployment } from './chain/chains.js';
 import { assertSecureConfig } from './chain/secure.js';
+import { RegistryPrices } from './chain/registry-prices.js';
 
 /**
  * A production gate from an environment, assembled and checked.
@@ -59,6 +60,12 @@ export interface ResolvedGateConfig {
    * refused at adoption — the gate does not guess a token's price.
    */
   spendTokens: ReadonlyMap<string, SpendTokenPricing>;
+  /**
+   * Percent added over the smallest cap a flawless round fits under when the gate sizes a cap for a
+   * registry-priced pairing (`/config/spend-tokens/:address`). Prices move between the quote and the
+   * launch; this is the room left for that.
+   */
+  pairedTokenCapHeadroomPercent: number;
   /** May lift the gate early or rotate the signer on-chain. Defaults to the signing key's address. */
   settler: `0x${string}` | null;
 }
@@ -167,7 +174,10 @@ function address(env: Env, name: string): `0x${string}` | null {
  *   POINTS_PER_DOLLAR        default 100
  *   USD_PER_ETH              default 3000; fractional allowed
  *   SPEND_TOKENS             optional JSON array of { address, usdPerToken, walletCap } — the non-ETH
- *                            paired tokens this gate runs rounds on. Unlisted tokens are refused.
+ *                            paired tokens this gate runs rounds on. Pins a price the registry
+ *                            would otherwise quote; tokens neither here nor approved on the
+ *                            manager's PairedTokenRegistry are refused.
+ *   PAIRED_TOKEN_CAP_HEADROOM_PERCENT  default 25; headroom on caps sized for registry-priced pairings
  */
 export function resolveGateEnv(env: Env): ResolvedGateConfig {
   const chainId = Number(required(env, 'CHAIN_ID'));
@@ -247,6 +257,7 @@ export function resolveGateEnv(env: Env): ResolvedGateConfig {
     pointsPerDollar: integer(env, 'POINTS_PER_DOLLAR', 100),
     usdPerEth: positiveNumber(env, 'USD_PER_ETH', 3_000),
     spendTokens: spendTokens(env),
+    pairedTokenCapHeadroomPercent: integer(env, 'PAIRED_TOKEN_CAP_HEADROOM_PERCENT', 25),
     settler: address(env, 'SETTLER'),
   };
 }
@@ -262,9 +273,11 @@ function isEthEquivalent(token: SpendToken, fleth: `0x${string}` | undefined): b
  * The price list a running gate answers adoption with.
  *
  * An override (an oracle, a test) is asked first; the env map second; ETH and its wrapper are the
- * operator's `USD_PER_ETH`; anything else is unpriced and the launch is refused.
+ * operator's `USD_PER_ETH`; then the manager's own PairedTokenRegistry, which prices every token the
+ * protocol has approved through the calculator it was registered with. Only a token none of them
+ * know is unpriced, and that launch is refused — it could not have been launched either.
  */
-function priceList(config: ResolvedGateConfig, override: PriceFor | undefined): PriceFor {
+function priceList(config: ResolvedGateConfig, override: PriceFor | undefined, registry: RegistryPrices): PriceFor {
   return async (token) => {
     if (override) {
       const quoted = await override(token);
@@ -273,7 +286,7 @@ function priceList(config: ResolvedGateConfig, override: PriceFor | undefined):
     const listed = config.spendTokens.get(token.address.toLowerCase());
     if (listed) return listed.usdPerToken;
     if (isEthEquivalent(token, config.deployment.fleth)) return config.usdPerEth;
-    return null;
+    return registry.priceFor(token);
   };
 }
 
@@ -365,6 +378,16 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
     });
   }
 
+  // Every pairing the protocol approves, priced by the calculator it was registered with. The
+  // registry is read from the manager, so nothing is configured and nothing goes stale when a new
+  // token is approved: the next launch on it is adopted like any other.
+  const registryPrices = new RegistryPrices(client, {
+    positionManager: config.deployment.positionManager,
+    ...(config.deployment.fleth ? { fleth: config.deployment.fleth } : {}),
+    usdPerEth: config.usdPerEth,
+  });
+  const pairedTokenRegistry = await registryPrices.registryAddress();
+
   const pool = new pg.Pool({ connectionString: config.databaseUrl });
   await migrate(pool);
 
@@ -387,6 +410,7 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
     gateEndsAtGraceS: config.gateEndsAtGraceS,
     flaunchVariant: config.deployment.flaunchVariant,
     ...(announcedSpendTokens.length > 0 ? { spendTokens: announcedSpendTokens } : {}),
+    ...(pairedTokenRegistry ? { pairedTokenRegistry } : {}),
     requiresEoa: false,
     accepting: true,
     publicLaunchesOpen: true,
@@ -399,7 +423,17 @@ export async function startGate<Config, State, Event, Action, PublicView, Player
     config: gameConfig,
     pointsPerDollar: config.pointsPerDollar,
     usdPerEth: config.usdPerEth,
-    priceFor: priceList(config, overrides.priceProvider),
+    priceFor: priceList(config, overrides.priceProvider, registryPrices),
+    announceSpendToken: async (address) => {
+      // An operator-pinned token is announced exactly as pinned; anything else is the registry's word.
+      const pinned = announcedSpendTokens.find((entry) => entry.address.toLowerCase() === address.toLowerCase());
+      if (pinned) return pinned;
+      return registryPrices.announce(address, {
+        maxPointsPerPlayer,
+        pointsPerDollar: config.pointsPerDollar,
+        headroomPercent: config.pairedTokenCapHeadroomPercent,
+      });
+    },
     sessions: new Sessions(config.sessionSecret, config.signInDomain, config.gateOrigin),
     claims: new Claims(pool, ledger, signer),
     discovery: new Discovery(client, {

package/src/play-sessions.ts

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+import type { Pool } from 'pg';
+
+export function playSessionId(roundId: string, player: string): string {
+  return createHash('sha256').update(JSON.stringify([roundId, player.toLowerCase()])).digest('hex');
+}
+export async function recordPlaySession(pool: Pool, roundId: string, player: string, at = Date.now()): Promise<void> {
+  // One accepted start per wallet and launch. Reconnects and repeated joins retain the first time.
+  await pool.query('insert into play_sessions (id, round_id, started_at) values ($1, $2, $3) on conflict do nothing', [playSessionId(roundId, player), roundId, at]);
+}
+export function parsePlayCursor(value: unknown): { at: number; id: string } | null {
+  if (value === undefined) return { at: 0, id: '' };
+  if (typeof value !== 'string' || value.length > 100) return null;
+  const match = /^(\d{1,16}):([a-f0-9]{64})$/.exec(value);
+  if (!match || !Number.isSafeInteger(Number(match[1]))) return null;
+  return { at: Number(match[1]), id: match[2]! };
+}
+export async function readPlaySessions(pool: Pool, cursor: { at: number; id: string }) {
+  const [events, coverage] = await Promise.all([
+    pool.query<{ id: string; coin: string; started_at: string }>(`select p.id, r.coin_address as coin, p.started_at from play_sessions p join rounds r on r.id = p.round_id where r.coin_address is not null and (p.started_at, p.id) > ($1::bigint, $2::text) order by p.started_at, p.id limit 250`, [cursor.at, cursor.id]),
+    pool.query<{ started_at: string }>('select started_at from play_tracking where id = true'),
+  ]);
+  const last = events.rows.at(-1);
+  return { trackingSince: Number(coverage.rows[0]?.started_at ?? Date.now()), sessions: events.rows.map(r => ({ id: r.id, coin: r.coin, startedAt: Number(r.started_at) })), nextCursor: events.rows.length === 250 && last ? `${last.started_at}:${last.id}` : null };
+}

package/src/server.ts

@@ -1,6 +1,7 @@
 import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest } from 'fastify';
 import websocket from '@fastify/websocket';
 import cors from '@fastify/cors';
+import { isAddress } from 'viem';
 import type { Pool } from 'pg';
 import type { Command, GameModule, PlayerId } from '@flayerlabs/gamemode-spec';
 import { isRefusal } from '@flayerlabs/gamemode-spec';
@@ -20,6 +21,7 @@ import { Room, type ScoreAuthority } from './room.js';
 import { Standings } from './standings.js';
 import { CLAIM_AUTHORIZATION_TTL_MS, Claims, isClaimAmount, isClaimRequestId } from './claims.js';
 import { NotSignedIn, Sessions } from './sessions.js';
+import { parsePlayCursor, readPlaySessions, recordPlaySession } from './play-sessions.js';
 import type { Discovery, Launch, PoolKey } from './chain/discover.js';
 import type { Settlement } from './settlement.js';
 import { resolveEconomy } from './economy.js';
@@ -28,6 +30,7 @@ import { hasBearerToken } from './bearer.js';
 import { GameServerAwards, type GameServerAwardRequest } from './game-server-awards.js';
 import { issuePlayerJoinTicket } from './player-join-tickets.js';
 import { gameServerOrigins } from './registry.js';
+import { GATE_VERSION } from './version.js';
 
 /**
  * The gate's door.
@@ -56,6 +59,13 @@ interface GateBaseOptions {
    * refused: a gate that guessed a price would be authorising real money on a made-up number.
    */
   priceFor?: PriceFor;
+  /**
+   * Serves `GET /config/spend-tokens/:address`: the announced entry for one paired token — price,
+   * symbol, decimals and the per-wallet cap a launch on it should write — or null to answer 404 for
+   * a token this gate will not run rounds on. Lets launch tooling check any pairing before a coin
+   * is paid for, without the gate having listed it in `/config` up front.
+   */
+  announceSpendToken?: (address: `0x${string}`) => Promise<AnnouncedSpendToken | null>;
   /** Verifies from the chain that a coin really is a game launch. */
   discovery?: Discovery;
   /** Keeps the ledger's view of spending level with the chain's. */
@@ -166,6 +176,12 @@ export interface GateAnnouncement {
    * listed here, which is the fail-closed answer for a gate that has not been told the token's price.
    */
   spendTokens?: AnnouncedSpendToken[];
+  /**
+   * The manager's PairedTokenRegistry, when it has one. Its presence means this gate prices every
+   * token the registry approves, not only `spendTokens`: ask `/config/spend-tokens/:address` for the
+   * entry of any pairing before building a launch on it.
+   */
+  pairedTokenRegistry?: `0x${string}`;
   requiresEoa: boolean;
   accepting: boolean;
   /**
@@ -179,6 +195,15 @@ export interface GateAnnouncement {
   privateLaunches: boolean;
 }
 
+/**
+ * What `GET /config` actually serves: the operator's {@link GateAnnouncement} plus the version of
+ * `@flayerlabs/gamemode-gate` answering, so the platform can tell whether a gate runs a current SDK.
+ */
+export interface ServedGateAnnouncement extends GateAnnouncement {
+  /** The SemVer of the `@flayerlabs/gamemode-gate` build serving this route. */
+  gateVersion: string;
+}
+
 /** Where an admission check is being made. Enough to tell a sign-in from a spend. */
 export interface AdmissionRequest {
   /** `session` on sign-in, `action` on gameplay, `claim` when allowance is about to be committed. */
@@ -627,9 +652,24 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
         total: row.total,
       })),
       lastRoundAt: totals.last_round_at === null ? null : Number(totals.last_round_at),
+      // The same version `/config` reports, so a dashboard already reading stats needs no second call.
+      gateVersion: GATE_VERSION,
     };
   });
 
+  /**
+   * Accepted play sessions, for the same dashboard: one row per wallet and round, so a per-game
+   * play count survives the room ending. Wallets are hashed into the row ID and never returned.
+   * Rounds without a coin (practice and mock rooms) are left out. Keyset-paginated at 250 rows on
+   * `(started_at, id)`; the cursor is `${startedAt}:${id}` and a malformed one is a 400.
+   */
+  app.get('/stats/plays', async (request, reply) => {
+    void reply.header('access-control-allow-origin', '*');
+    const cursor = parsePlayCursor((request.query as { cursor?: unknown }).cursor);
+    if (!cursor) return reply.code(400).send({ message: 'invalid play cursor' });
+    return readPlaySessions(pool, cursor);
+  });
+
   /**
    * How a coin's round stands: every wallet that scored, ranked, with what the chain says each
    * spent. This is what the coin page shows once the game is over — and during it, as the running
@@ -655,8 +695,27 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
       // allowlist names only the game's origins; the launch page is a different origin and every
       // fact here is public (a launch publishes them on chain), so `*` is honest rather than lax.
       void reply.header('access-control-allow-origin', '*');
-      return announce();
+      // `gateVersion` is added here rather than asked of `announce()`: the library knows what it is
+      // and an operator's announcement should not be able to misreport it.
+      const served: ServedGateAnnouncement = { ...announce(), gateVersion: GATE_VERSION };
+      return served;
     });
+    if (options.announceSpendToken) {
+      const announceSpendToken = options.announceSpendToken;
+      app.get<{ Params: { address: string } }>('/config/spend-tokens/:address', async (request, reply) => {
+        void reply.header('access-control-allow-origin', '*');
+        // A quote moves with the market and an approval can be revoked; nothing here may be cached
+        // past the response.
+        void reply.header('cache-control', 'no-store');
+        const { address } = request.params;
+        if (!isAddress(address, { strict: false })) {
+          return reply.code(400).send({ message: 'not a token address' });
+        }
+        const entry = await announceSpendToken(address as `0x${string}`);
+        if (!entry) return reply.code(404).send({ message: 'this gate does not run rounds on that token' });
+        return entry;
+      });
+    }
   }
 
   app.post('/session/challenge', async (request) => {
@@ -742,6 +801,7 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
       if (typeof audience !== 'string' || !awardEndpoint.ticketAudiences.has(audience)) {
         return reply.code(400).send({ message: 'that game server is not registered' });
       }
+      await recordPlaySession(pool, id, who);
       return issuePlayerJoinTicket({
         awardToken: awardEndpoint.token,
         player: who,
@@ -838,7 +898,9 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
 
     const id = (request.params as { id: string }).id;
     if (scoreAuthority === 'external-server') {
-      player(request);
+      const who = player(request);
+      if (Date.now() >= room.window.closesAt) return reply.code(409).send({ message: 'that game has ended' });
+      await recordPlaySession(pool, id, who);
       return { joined: true };
     }
     const before = room.sequence();
@@ -850,7 +912,9 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
       at: Date.now(),
     });
     if (room.sequence() !== before) announce(id);
-    return isRefusal(result) ? reply.code(409).send({ message: 'you cannot join right now' }) : { joined: true };
+    if (isRefusal(result)) return reply.code(409).send({ message: 'you cannot join right now' });
+    await recordPlaySession(pool, id, player(request));
+    return { joined: true };
   });
 
   app.post('/rounds/:id/actions', async (request, reply) => {

package/src/store.ts

@@ -147,6 +147,21 @@ create table if not exists registrations (
   primary key (chain_id, coin)
 );
 
+-- Accepted play sessions: one row per wallet and round, keyed by a hash of both so a wallet is never
+-- stored in the clear. Independent of scoring and of websocket reconnects. play_tracking records
+-- when this gate began counting, so a dashboard can tell "no plays" from "not yet tracked".
+create table if not exists play_sessions (
+  id text primary key,
+  round_id text not null references rounds(id) on delete cascade,
+  started_at bigint not null
+);
+create index if not exists play_sessions_started_id_idx on play_sessions(started_at, id);
+create table if not exists play_tracking (
+  id boolean primary key default true check (id),
+  started_at bigint not null
+);
+insert into play_tracking(id, started_at) values (true, (extract(epoch from clock_timestamp()) * 1000)::bigint) on conflict do nothing;
+
 -- What actually happened, in order. Not used to rebuild state — the snapshot does that — but it is
 -- the record of why a state looks the way it does, which is what an incident needs.
 create table if not exists commands (

package/src/version.ts

@@ -0,0 +1,5 @@
+// Generated by scripts/write-version.mjs from package.json at build time. Do not edit.
+/** The published version of @flayerlabs/gamemode-gate, as a literal so it survives any bundler. */
+export const GATE_VERSION: string = "0.5.6";
+/** `@flayerlabs/gamemode-gate@<version>`: the text a build of this package can be searched for. */
+export const GATE_MARKER: string = "@flayerlabs/gamemode-gate@0.5.6";