@flayerlabs/gamemode-gate 0.4.3 → 0.5.1

package/src/room.ts

@@ -1,7 +1,7 @@
 import type { Pool } from 'pg';
 import { Round } from '@flayerlabs/gamemode-spec/round';
 import type { Award, Command, Decision, GameModule, PlayerId, Refusal, RoundWindow } from '@flayerlabs/gamemode-spec';
-import type { LaunchContext, RoundTerms } from '@flayerlabs/gamemode-spec/live';
+import { ETH_SPEND_TOKEN, type LaunchContext, type RoundTerms, type SpendToken } from '@flayerlabs/gamemode-spec/live';
 import { isRefusal } from '@flayerlabs/gamemode-spec';
 import { inTransaction, toBigInt } from './store.js';
 
@@ -52,10 +52,13 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       config: Config;
       seed: number;
       window: RoundWindow;
-      weiPerPoint: bigint;
-      walletCapWei: bigint;
+      unitsPerPoint: bigint;
+      walletCap: bigint;
       pointsPerDollar: number;
-      usdPerEth: number;
+      /** The token spend is measured in. Defaults to ETH — a flETH- or ETH-paired round. */
+      spendToken?: SpendToken;
+      /** The market price of one whole spend token, in dollars, at adoption. */
+      usdPerSpendToken: number;
       maxPointsPerPlayer: number;
       scoreAuthority: ScoreAuthority;
       poolId: string;
@@ -86,28 +89,39 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       closesAt: round.window.closesAt,
       booksCloseAt,
     });
+    const spendToken: SpendToken = Object.freeze({ ...(round.spendToken ?? ETH_SPEND_TOKEN) });
     const terms: RoundTerms = Object.freeze({
       maxPointsPerPlayer: round.maxPointsPerPlayer,
-      walletCapWei: round.walletCapWei,
-      weiPerPoint: round.weiPerPoint,
+      walletCap: round.walletCap,
+      unitsPerPoint: round.unitsPerPoint,
       pointsPerDollar: round.pointsPerDollar,
-      usdPerEth: round.usdPerEth,
+      usdPerSpendToken: round.usdPerSpendToken,
+      spendToken,
     });
     const started = Round.start(game, round.config, round.seed, round.window);
+    // The columns keep their original wei-flavoured names while the API does not. Renaming them
+    // would be a migration with no reader outside this file, so the divergence is deliberate:
+    // wei_per_point is unitsPerPoint, wallet_cap_wei is walletCap, and usd_per_spend_token is
+    // usdPerSpendToken. usd_per_eth is a legacy column, written for provenance only.
     await pool.query(
       `insert into rounds (
          id, game_id, wei_per_point, wallet_cap_wei, points_per_dollar, usd_per_eth,
+         spend_token, spend_symbol, spend_decimals, usd_per_spend_token,
          max_points_per_player, score_authority,
          pool_id, opens_at, closes_at, books_close_at,
          coin_address, coin_name, coin_symbol, coin_image_url, state, seq
-       ) values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, 0)`,
+       ) values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, 0)`,
       [
         round.id,
         game.id,
-        round.weiPerPoint.toString(),
-        round.walletCapWei.toString(),
+        round.unitsPerPoint.toString(),
+        round.walletCap.toString(),
         round.pointsPerDollar,
-        round.usdPerEth,
+        round.usdPerSpendToken,
+        spendToken.address.toLowerCase(),
+        spendToken.symbol,
+        spendToken.decimals,
+        round.usdPerSpendToken,
         round.maxPointsPerPlayer,
         round.scoreAuthority,
         round.poolId,
@@ -155,12 +169,17 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
       wallet_cap_wei: string;
       points_per_dollar: number;
       usd_per_eth: number;
+      spend_token: string;
+      spend_symbol: string;
+      spend_decimals: number;
+      usd_per_spend_token: number | null;
       max_points_per_player: string;
       score_authority: ScoreAuthority;
       game_id: string;
     }>(
       `select state, seq, pool_id, opens_at, closes_at, books_close_at, wei_per_point,
               wallet_cap_wei, points_per_dollar, usd_per_eth,
+              spend_token, spend_symbol, spend_decimals, usd_per_spend_token,
               max_points_per_player, score_authority, game_id,
               coin_address, coin_name, coin_symbol, coin_image_url
        from rounds where id = $1`,
@@ -183,10 +202,18 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
     });
     const terms: RoundTerms = Object.freeze({
       maxPointsPerPlayer: Number(row.max_points_per_player),
-      walletCapWei: toBigInt(row.wallet_cap_wei),
-      weiPerPoint: toBigInt(row.wei_per_point),
+      walletCap: toBigInt(row.wallet_cap_wei),
+      unitsPerPoint: toBigInt(row.wei_per_point),
       pointsPerDollar: Number(row.points_per_dollar),
-      usdPerEth: Number(row.usd_per_eth),
+      spendToken: Object.freeze({
+        address: row.spend_token,
+        symbol: row.spend_symbol,
+        decimals: Number(row.spend_decimals),
+        isNative: row.spend_token.toLowerCase() === ETH_SPEND_TOKEN.address,
+      }),
+      // usd_per_eth is the legacy column: on a row written before the spend-token columns existed
+      // it holds that round's ETH price, which is exactly its spend token's price.
+      usdPerSpendToken: row.usd_per_spend_token === null ? Number(row.usd_per_eth) : Number(row.usd_per_spend_token),
     });
     return new Room(
       pool,

package/src/server.ts

@@ -7,12 +7,17 @@ import { isRefusal } from '@flayerlabs/gamemode-spec';
 import type {
   EconomyBalance,
   PresenceState,
+  RoundStandings,
   RoundTerms,
+  SpendToken,
   WireEconomyBalance,
+  WireRoundStandings,
   WireRoundTerms,
 } from '@flayerlabs/gamemode-spec/live';
-import { isReactionId, LIVE_PROTOCOL_VERSION } from '@flayerlabs/gamemode-spec/live';
+import { ETH_SPEND_TOKEN, isReactionId, LIVE_PROTOCOL_VERSION } from '@flayerlabs/gamemode-spec/live';
+import type { FlaunchVariant } from './chain/chains.js';
 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 type { Discovery, Launch, PoolKey } from './chain/discover.js';
@@ -42,7 +47,15 @@ interface GateBaseOptions {
   claims: Claims;
   /** How many points a dollar buys. The only economic number anyone sets by hand. */
   pointsPerDollar: number;
+  /** The price of ETH — what an ETH-paired round is priced at. */
   usdPerEth: number;
+  /**
+   * The price of one whole spend token, for a round whose coin is paired with something other
+   * than ETH — or null to refuse the launch as unpriced. Consulted at adoption with the token the
+   * chain reported. Omitted, only native ETH is priced (at `usdPerEth`) and every other pairing is
+   * refused: a gate that guessed a price would be authorising real money on a made-up number.
+   */
+  priceFor?: PriceFor;
   /** 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. */
@@ -85,6 +98,20 @@ interface GateBaseOptions {
   reactionIds?: readonly string[];
 }
 
+/** A price for one whole spend token in dollars, or null when this gate has none for it. */
+export type PriceFor = (token: SpendToken) => Promise<number | null> | number | null;
+
+/** One entry of a gate's announced price list — what launch tooling checks a pairing against. */
+export interface AnnouncedSpendToken {
+  address: `0x${string}`;
+  symbol: string;
+  decimals: number;
+  /** The price this gate will fix rounds on that token at. */
+  usdPerToken: number;
+  /** The per-wallet cap the launch should write, in this token's base units. A decimal string. */
+  walletCap: string;
+}
+
 /** Resolve one immutable rules config after the launch has been verified. */
 export type VerifiedLaunch = Readonly<Omit<Launch, 'poolKey'>> & { readonly poolKey: Readonly<PoolKey> };
 export type ConfigForLaunch<Config> = (launch: VerifiedLaunch) => Promise<Config>;
@@ -118,17 +145,25 @@ export interface GateAnnouncement {
   contracts: {
     positionManager: `0x${string}`;
     spendGatedCalculator: `0x${string}`;
+    /** The approved swap router a paired-token buy goes through. Present on a `v1_3` stack. */
+    poolSwap?: `0x${string}`;
   };
   /** The address launches must name as their trusted signer for this gate to adopt them. */
   signer: `0x${string}`;
   /** May lift the gate early or rotate the signer on-chain; the launch writes it into the pool. */
   settler: `0x${string}`;
-  /** A decimal string — wei does not survive JSON as a number. */
-  walletCapWei: string;
+  /** The per-wallet cap for an ETH-paired launch, in wei. A decimal string — wei does not survive JSON as a number. */
+  walletCap: string;
   roundDurationMs: number;
   minLobbyLeadMs: number;
   gateEndsAtGraceS: number;
-  flaunchVariant: 'legacy11' | 'current9';
+  flaunchVariant: FlaunchVariant;
+  /**
+   * The non-ETH paired tokens this gate will run rounds on, each with the cap a launch on it should
+   * write. Absent or empty means ETH pairings only. Launch tooling refuses a pairing that is not
+   * listed here, which is the fail-closed answer for a gate that has not been told the token's price.
+   */
+  spendTokens?: AnnouncedSpendToken[];
   requiresEoa: boolean;
   accepting: boolean;
   /**
@@ -170,22 +205,32 @@ const ADMIT_ALL: Admit = () => ({ ok: true });
 /** What the socket says, which is only the truth when nothing is proxying in front of the gate. */
 const ipOf = (request: FastifyRequest): string | null => request.ip || null;
 
-/** Wei has no JSON form, so terms cross as decimal strings, exactly as the economy balance does. */
+/** Bigint has no JSON form, so terms cross as decimal strings, exactly as the economy balance does. */
 const wireTerms = (terms: RoundTerms): WireRoundTerms => ({
   maxPointsPerPlayer: terms.maxPointsPerPlayer,
-  walletCapWei: terms.walletCapWei.toString(),
-  weiPerPoint: terms.weiPerPoint.toString(),
+  walletCap: terms.walletCap.toString(),
+  unitsPerPoint: terms.unitsPerPoint.toString(),
   pointsPerDollar: terms.pointsPerDollar,
-  usdPerEth: terms.usdPerEth,
+  usdPerSpendToken: terms.usdPerSpendToken,
+  spendToken: terms.spendToken,
 });
 
+/** Standings leave the process the same way every other amount does: base units as a string. */
+const wireStandings = (standings: RoundStandings): WireRoundStandings => ({
+  ...standings,
+  players: standings.players.map((line) => ({ ...line, spent: line.spent.toString() })),
+});
+
+/** Only native ETH is priced without being told: everything else needs a `priceFor`. */
+const ethOnly = (usdPerEth: number): PriceFor => (token) => (token.isNative ? usdPerEth : null);
+
 /** The same encoding for the per-player balance, wherever it leaves the process. */
 const wireEconomy = (balance: EconomyBalance): WireEconomyBalance => ({
-  weiPerPoint: balance.weiPerPoint.toString(),
-  earnedWei: balance.earnedWei.toString(),
-  heldWei: balance.heldWei.toString(),
-  spentWei: balance.spentWei.toString(),
-  availableWei: balance.availableWei.toString(),
+  unitsPerPoint: balance.unitsPerPoint.toString(),
+  earned: balance.earned.toString(),
+  held: balance.held.toString(),
+  spent: balance.spent.toString(),
+  available: balance.available.toString(),
   holdExpiresAt: balance.holdExpiresAt,
 });
 
@@ -326,6 +371,7 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
   >();
 
   const playerSocketKey = (id: string, player: PlayerId): string => `${id}:${player}`;
+  const standings = new Standings(pool, game.id);
 
   void app.register(cors, { origin: options.allowedOrigins });
   void app.register(websocket, { options: { maxPayload: 1_024 } });
@@ -389,11 +435,27 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
       app.log.error(error);
       return { ok: false, status: 503, message: 'this game is still being prepared' };
     }
+    // The token the chain measures this pool's spend in decides the round's units. A launch this
+    // gate has no price for is refused rather than priced as ETH: on a six-decimal token that guess
+    // authorises a trillion times the intended spend.
+    const spendToken = launch.spendToken ?? ETH_SPEND_TOKEN;
+    let usdPerSpendToken: number | null;
+    try {
+      usdPerSpendToken = await (options.priceFor ?? ethOnly(options.usdPerEth))(spendToken);
+    } catch (error) {
+      app.log.error(error);
+      return { ok: false, status: 503, message: 'this game is still being prepared' };
+    }
+    if (usdPerSpendToken === null || !Number.isFinite(usdPerSpendToken) || usdPerSpendToken <= 0) {
+      app.log.error(`${launch.coinAddress}: no price for spend token ${spendToken.symbol} (${spendToken.address})`);
+      return { ok: false, status: 409, message: `this game is not set up for ${spendToken.symbol} yet` };
+    }
     const economy = resolveEconomy({
       maxPointsPerPlayer,
-      walletCapWei: launch.walletCapWei,
+      walletCap: launch.walletCap,
       pointsPerDollar: options.pointsPerDollar,
-      usdPerEth: options.usdPerEth,
+      usdPerSpendToken,
+      decimals: spendToken.decimals,
     });
     if (!economy.ok) {
       app.log.error(
@@ -409,10 +471,11 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
         config,
         seed: Number(BigInt(launch.poolId) % 2147483647n),
         window: { opensAt: launch.opensAt, closesAt: launch.closesAt },
-        weiPerPoint: economy.economy.weiPerPoint,
+        unitsPerPoint: economy.economy.unitsPerPoint,
         pointsPerDollar: economy.economy.pointsPerDollar,
-        usdPerEth: economy.economy.usdPerEth,
-        walletCapWei: launch.walletCapWei,
+        spendToken,
+        usdPerSpendToken: economy.economy.usdPerSpendToken,
+        walletCap: launch.walletCap,
         maxPointsPerPlayer,
         scoreAuthority,
         poolId: launch.poolId,
@@ -499,26 +562,63 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
    */
   app.get('/stats', async (_request, reply) => {
     void reply.header('access-control-allow-origin', '*');
-    const { rows } = await pool.query<{
-      rounds_total: string;
-      players_total: string;
-      spend_wei_total: string;
-      last_round_at: string | null;
-    }>(
-      `select (select count(*) from rounds)                                   as rounds_total,
-              (select count(distinct player) from balances)                   as players_total,
-              (select coalesce(sum(chain_spent_wei), 0)::text from balances)  as spend_wei_total,
-              (select max(opens_at) from rounds)                              as last_round_at`,
-    );
+    // Spend is summed per spend token: base units of two different tokens do not add. The flat
+    // `spendWeiTotal` keeps its original meaning — wei, across ETH rounds — for dashboards built
+    // against it; `spendByToken` is the honest figure for a gate that runs more than one pairing.
+    const [{ rows }, byToken] = await Promise.all([
+      pool.query<{
+        rounds_total: string;
+        players_total: string;
+        spend_wei_total: string;
+        last_round_at: string | null;
+      }>(
+        `select (select count(*) from rounds)                                   as rounds_total,
+                (select count(distinct player) from balances)                   as players_total,
+                (select coalesce(sum(b.chain_spent_wei), 0)::text
+                   from balances b join rounds r on r.id = b.round_id
+                  where r.spend_decimals = 18)                                  as spend_wei_total,
+                (select max(opens_at) from rounds)                              as last_round_at`,
+      ),
+      pool.query<{ spend_token: string; spend_symbol: string; spend_decimals: number; total: string }>(
+        `select r.spend_token, r.spend_symbol, r.spend_decimals, coalesce(sum(b.chain_spent_wei), 0)::text as total
+           from rounds r left join balances b on b.round_id = r.id
+          group by r.spend_token, r.spend_symbol, r.spend_decimals
+          order by r.spend_token`,
+      ),
+    ]);
     const totals = rows[0]!;
     return {
       roundsTotal: Number(totals.rounds_total),
       playersTotal: Number(totals.players_total),
       spendWeiTotal: totals.spend_wei_total,
+      spendByToken: byToken.rows.map((row) => ({
+        address: row.spend_token,
+        symbol: row.spend_symbol,
+        decimals: Number(row.spend_decimals),
+        total: row.total,
+      })),
       lastRoundAt: totals.last_round_at === null ? null : Number(totals.last_round_at),
     };
   });
 
+  /**
+   * 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
+   * order — so it is keyed by the one thing that page holds, the coin's address.
+   *
+   * A read, and deliberately not through `roomFor`: that resurrects rooms, advances game state and
+   * answers nothing once the books close, none of which a table should do. Public for the same
+   * reason `/stats` is — a spectator on the live socket could tally every number here — and served
+   * with the same header, because the coin page is a different origin from the game's.
+   */
+  app.get('/coins/:coin/rankings', async (request, reply) => {
+    void reply.header('access-control-allow-origin', '*');
+    const found = await standings.forCoin((request.params as { coin: string }).coin);
+    if (!found) return reply.code(404).send({ message: 'that coin has no game' });
+    // Points are monotone within a round; the spend beside them is the chain's latest word.
+    return reply.header('cache-control', 'no-store').send(wireStandings(found));
+  });
+
   if (options.announce) {
     const announce = options.announce;
     app.get('/config', (_request, reply) => {
@@ -672,7 +772,7 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
         return reply.code(result.refuse === 'award.invalid' ? 400 : 404).send({ refuse: result.refuse });
       }
 
-      // `heldWei` moves on its own when an authorisation expires, so this answer is only true at the
+      // `held` moves on its own when an authorisation expires, so this answer is only true at the
       // moment it is read. Points are monotone; the wei beside them are not.
       const balance = await claims.economyBalance(result.standing.roundId, result.standing.player);
       return reply
@@ -688,11 +788,18 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
     const before = room.sequence();
     await room.tick(Date.now());
     if (room.sequence() !== before) announce(id);
+    // Who is here rides the round read so a lobby can show its seats without a socket of its own.
+    // Connection is decided by the sockets this process holds, which is the only place it is known.
+    const { roster, rosterTotal } = await standings.rosterFor(id, (who) =>
+      activePlayerSockets.has(playerSocketKey(id, who)),
+    );
     return {
       sequence: room.sequence(),
       view: room.publicView(),
       launch: room.launch,
       terms: wireTerms(room.terms),
+      roster,
+      rosterTotal,
     };
   });
 
@@ -869,11 +976,11 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
       const balance = viewer
         ? await claims.economyBalance(id, viewer)
         : {
-            weiPerPoint: room.terms.weiPerPoint,
-            earnedWei: 0n,
-            heldWei: 0n,
-            spentWei: 0n,
-            availableWei: 0n,
+            unitsPerPoint: room.terms.unitsPerPoint,
+            earned: 0n,
+            held: 0n,
+            spent: 0n,
+            available: 0n,
             holdExpiresAt: null,
           };
       const economy = wireEconomy(balance);

package/src/standings.ts

@@ -0,0 +1,138 @@
+import type { Pool } from 'pg';
+import { isAddress } from 'viem';
+import type { PlayerId } from '@flayerlabs/gamemode-spec';
+import {
+  ETH_SPEND_TOKEN,
+  ROSTER_MAX_PLAYERS,
+  STANDINGS_MAX_PLAYERS,
+  roundPhaseAt,
+  type RoundRosterEntry,
+  type RoundStandings,
+} from '@flayerlabs/gamemode-spec/live';
+import { toBigInt } from './store.js';
+
+/**
+ * The public reads of who played a round and how they did.
+ *
+ * Reads only, and never through a Room: loading one resurrects a round, advances its state and
+ * answers nothing once the books close — none of which a spectator's table should do. Everything
+ * here comes straight from `rounds` and `balances`, the same rows the ledger writes.
+ *
+ * Scoped by game, so another game's round sharing this database reads as no round at all rather
+ * than as somebody else's standings.
+ */
+export class Standings {
+  constructor(
+    private readonly pool: Pool,
+    private readonly gameId: string,
+  ) {}
+
+  /**
+   * The standings of the latest round this gate ran for a coin, or null when it ran none.
+   *
+   * Latest by opening time: a coin can only carry one live round, and a page asking about a coin
+   * wants the round people remember, not the first one ever adopted.
+   */
+  async forCoin(coin: unknown, now: number = Date.now()): Promise<RoundStandings | null> {
+    if (typeof coin !== 'string' || !isAddress(coin, { strict: false })) return null;
+
+    const rounds = await this.pool.query<{
+      id: string;
+      pool_id: string;
+      coin_address: string | null;
+      coin_symbol: string;
+      opens_at: string;
+      closes_at: string;
+      spend_token: string;
+      spend_symbol: string;
+      spend_decimals: number;
+      usd_per_spend_token: number | null;
+      usd_per_eth: number;
+    }>(
+      `select id, pool_id, coin_address, coin_symbol, opens_at, closes_at,
+              spend_token, spend_symbol, spend_decimals, usd_per_spend_token, usd_per_eth
+         from rounds
+        where lower(coin_address) = $1 and game_id = $2
+        order by opens_at desc
+        limit 1`,
+      [coin.toLowerCase(), this.gameId],
+    );
+    const round = rounds.rows[0];
+    if (!round) return null;
+
+    // ORDER BY is qualified on purpose. A bare `points` there would bind to the OUTPUT column —
+    // the `::text` cast that shares its name — and sort as strings, ranking 99 above 100. The
+    // qualified name is the only spelling Postgres reads as the bigint underneath.
+    const [players, total] = await Promise.all([
+      this.pool.query<{ player: string; points: string; chain_spent_wei: string }>(
+        `select player, points::text, chain_spent_wei::text
+           from balances
+          where round_id = $1
+          order by balances.points desc, balances.chain_spent_wei desc, balances.player asc
+          limit $2`,
+        [round.id, STANDINGS_MAX_PLAYERS],
+      ),
+      this.pool.query<{ total: string }>(`select count(*)::text as total from balances where round_id = $1`, [
+        round.id,
+      ]),
+    ]);
+
+    const window = { opensAt: Number(round.opens_at), closesAt: Number(round.closes_at) };
+    return {
+      roundId: round.id,
+      poolId: round.pool_id,
+      coinAddress: round.coin_address,
+      symbol: round.coin_symbol,
+      phase: roundPhaseAt(window, now),
+      ...window,
+      spendToken: {
+        address: round.spend_token,
+        symbol: round.spend_symbol,
+        decimals: Number(round.spend_decimals),
+        isNative: round.spend_token.toLowerCase() === ETH_SPEND_TOKEN.address,
+      },
+      // usd_per_eth is the legacy column: on a row written before the spend-token columns existed
+      // it holds that round's ETH price, which is exactly its spend token's price.
+      usdPerSpendToken:
+        round.usd_per_spend_token === null ? Number(round.usd_per_eth) : Number(round.usd_per_spend_token),
+      players: players.rows.map((row, index) => ({
+        rank: index + 1,
+        player: row.player,
+        points: Number(row.points),
+        spent: toBigInt(row.chain_spent_wei),
+      })),
+      playersTotal: Number(total.rows[0]?.total ?? 0),
+    };
+  }
+
+  /**
+   * Who holds a seat in a round: every wallet with a balance row, best first, and whether each is
+   * connected right now. Connection is the caller's to know — it owns the sockets.
+   */
+  async rosterFor(
+    roundId: string,
+    connected: (player: PlayerId) => boolean,
+  ): Promise<{ roster: RoundRosterEntry[]; rosterTotal: number }> {
+    const [seats, total] = await Promise.all([
+      this.pool.query<{ player: string; points: string }>(
+        `select player, points::text
+           from balances
+          where round_id = $1
+          order by balances.points desc, balances.player asc
+          limit $2`,
+        [roundId, ROSTER_MAX_PLAYERS],
+      ),
+      this.pool.query<{ total: string }>(`select count(*)::text as total from balances where round_id = $1`, [
+        roundId,
+      ]),
+    ]);
+    return {
+      roster: seats.rows.map((row) => ({
+        player: row.player,
+        points: Number(row.points),
+        connected: connected(row.player),
+      })),
+      rosterTotal: Number(total.rows[0]?.total ?? 0),
+    };
+  }
+}

package/src/store.ts

@@ -18,6 +18,15 @@ create table if not exists rounds (
   -- was priced at.
   points_per_dollar double precision not null check (points_per_dollar > 0),
   usd_per_eth       double precision not null check (usd_per_eth > 0),
+  -- The token spend is measured in: the coin's paired token, in whose base units every *_wei column
+  -- of this round is denominated. Defaults describe ETH, which is what every round was before the
+  -- columns existed, so a pre-existing row reads back exactly as it was priced. usd_per_eth holds
+  -- the rate normalised to eighteen decimals (see economy.ts); usd_per_spend_token the token's own
+  -- price, null on rows that predate it (for which usd_per_eth is that price).
+  spend_token    text not null default '0x0000000000000000000000000000000000000000' check (spend_token <> ''),
+  spend_symbol   text not null default 'ETH' check (spend_symbol <> ''),
+  spend_decimals integer not null default 18 check (spend_decimals between 0 and 36),
+  usd_per_spend_token double precision check (usd_per_spend_token > 0),
   max_points_per_player bigint not null check (max_points_per_player > 0),
   score_authority text not null check (score_authority in ('rules', 'external-server')),
   pool_id        text not null,
@@ -68,6 +77,18 @@ alter table rounds alter column score_authority set not null;
 alter table rounds alter column points_per_dollar set not null;
 alter table rounds alter column usd_per_eth set not null;
 
+-- Paired-token rounds (0.5.0). Every earlier round was an ETH round, so the defaults ARE the
+-- backfill: Postgres fills a new not-null column with its default, and ETH/18 is exactly what those
+-- rows were priced in. No guard is needed — nothing here has to be guessed.
+alter table rounds
+  add column if not exists spend_token text not null default '0x0000000000000000000000000000000000000000' check (spend_token <> '');
+alter table rounds
+  add column if not exists spend_symbol text not null default 'ETH' check (spend_symbol <> '');
+alter table rounds
+  add column if not exists spend_decimals integer not null default 18 check (spend_decimals between 0 and 36);
+alter table rounds
+  add column if not exists usd_per_spend_token double precision check (usd_per_spend_token > 0);
+
 create table if not exists balances (
   round_id text not null references rounds(id) on delete cascade,
   player   text not null,