@flayerlabs/gamemode-gate 0.6.0 → 0.7.0

package/src/server.ts

@@ -19,7 +19,7 @@ import { ETH_SPEND_TOKEN, isReactionId, LIVE_PROTOCOL_VERSION } from '@flayerlab
 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 { 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';
@@ -269,10 +269,8 @@ const ethOnly = (usdPerEth: number): PriceFor => (token) => (token.isNative ? us
 const wireEconomy = (balance: EconomyBalance): WireEconomyBalance => ({
   unitsPerPoint: balance.unitsPerPoint.toString(),
   earned: balance.earned.toString(),
-  held: balance.held.toString(),
   spent: balance.spent.toString(),
   available: balance.available.toString(),
-  holdExpiresAt: balance.holdExpiresAt,
 });
 
 /** How often each open room is nudged so a deadline nobody is watching still fires. */
@@ -295,7 +293,14 @@ const MAX_AUTHORITATIVE_BUFFERED_BYTES = 1_024 * 1_024;
 const TERMINAL_DRAIN_DEADLINE_MS = 1_000;
 /** Reactions are also bounded across a whole room, not only per sending socket. */
 const MAX_ROOM_REACTIONS_PER_SECOND = 20;
-export const DEFAULT_SETTLEMENT_TAIL_MS = CLAIM_AUTHORIZATION_TTL_MS;
+/**
+ * How long after `closesAt` the books stay open for chain reconciliation.
+ *
+ * Independent of any authorisation lifetime: a signed ceiling lasts until the books close, and a
+ * buy included in the last seconds of play still needs two confirmations and a reconcile pass to
+ * reach the standings.
+ */
+export const DEFAULT_SETTLEMENT_TAIL_MS = 5 * 60_000;
 
 type AdoptionResult<Config, State, Event, Action, PublicView, PlayerView> =
   | { ok: true; room: Room<Config, State, Event, Action, PublicView, PlayerView>; created: boolean }
@@ -390,8 +395,8 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
     throw new RangeError('reactionIds must contain only valid reaction identifiers');
   }
   const settlementTailMs = options.settlementTailMs ?? DEFAULT_SETTLEMENT_TAIL_MS;
-  if (!Number.isSafeInteger(settlementTailMs) || settlementTailMs < CLAIM_AUTHORIZATION_TTL_MS) {
-    throw new RangeError(`settlementTailMs must be at least ${CLAIM_AUTHORIZATION_TTL_MS}`);
+  if (!Number.isSafeInteger(settlementTailMs) || settlementTailMs <= 0) {
+    throw new RangeError('settlementTailMs must be a positive number of milliseconds');
   }
   // A body limit costs nothing and is the cheapest protection against an endpoint that parses.
   const app = Fastify({ logger: process.env.GATE_LOG === '1', bodyLimit: 64 * 1024 });
@@ -626,8 +631,8 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
    *
    * Served by every gate rather than behind an option, because the numbers already exist in the
    * gate's own tables and this is the only place they exist at all — the platform never sees a
-   * play. Spend is `chain_spent_wei`, the chain-reconciled figure, not claims: an expired hold is
-   * not a purchase. `spendWeiTotal` is a decimal string because wei does not survive JSON as a
+   * play. Spend is `chain_spent_wei`, the chain-reconciled figure, not authorisations: a signed
+   * ceiling is not a purchase. `spendWeiTotal` is a decimal string because wei does not survive JSON as a
    * number, and `lastRoundAt` is milliseconds, matching every timestamp a round carries.
    *
    * The permissive CORS header mirrors `/config`: the dashboard is a different origin from the
@@ -880,7 +885,7 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
         return reply.code(result.refuse === 'award.invalid' ? 400 : 404).send({ refuse: result.refuse });
       }
 
-      // `held` moves on its own when an authorisation expires, so this answer is only true at the
+      // `spent` rises whenever settlement sees a purchase land, 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
@@ -962,18 +967,17 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
     const who = player(request);
     const room = await roomFor(id);
     if (!room) return reply.code(404).send({ message: 'that game is not running' });
-    const { maxSpendWei, requestId } = request.body as { maxSpendWei?: string; requestId?: unknown };
+    const { spend, requestId } = request.body as { spend?: string; requestId?: unknown };
     let upTo: bigint;
     try {
-      upTo = BigInt(maxSpendWei ?? '0');
+      upTo = BigInt(spend ?? '0');
     } catch {
       return reply.code(400).send({ message: 'that amount was not understood' });
     }
     if (!isClaimAmount(upTo)) return reply.code(400).send({ message: 'that amount was not understood' });
     // Required, not defaulted. Minting an id here for a caller that omitted one makes every retry a
-    // fresh claim, which is precisely the double-hold idempotency exists to prevent — and it fails
-    // silently, for the one caller that needed it most. Nothing is live, so there is no old client
-    // to keep working.
+    // fresh signature, and a retry must receive the same bytes it was first given — otherwise the
+    // trusted page cannot tell a replayed request from a new one.
     if (!isClaimRequestId(requestId)) {
       return reply.code(400).send({ message: 'that request was not understood' });
     }
@@ -991,10 +995,12 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
       buyer: payload.buyer,
       poolId: payload.poolId,
       deadline: payload.deadline.toString(),
-      maxSpendWei: payload.maxSpendWei.toString(),
-      nonce: payload.nonce.toString(),
+      spendCeilingWei: payload.spendCeilingWei.toString(),
       signature: payload.signature,
       signer: payload.signer,
+      // Not signed: the exact-in amount for THIS buy, clamped to what was available. The page
+      // spends exactly this; the calculator enforces the ceiling above.
+      spend: authorised.spend.toString(),
       // The embed passes this opaque value to the Flaunch buy call. Game code never reconstructs
       // the ABI and therefore cannot accidentally sign or submit a different transaction shape.
       hookData: encodeHookData(payload),
@@ -1090,10 +1096,8 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
         : {
             unitsPerPoint: room.terms.unitsPerPoint,
             earned: 0n,
-            held: 0n,
             spent: 0n,
             available: 0n,
-            holdExpiresAt: null,
           };
       const economy = wireEconomy(balance);
       return {
@@ -1284,23 +1288,14 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
       try {
         const now = Date.now();
         const sweeping = Boolean(settlement && now - reconciledAt >= RECONCILE_MS);
-        // Authorisations nobody spent come back to the player who earned them.
-        // A chain-backed gate expires holds atomically with confirmed spend, never ahead of a
-        // lagging/failed RPC read. Demo and legacy adapters retain their existing expiry path.
-        const released = settlement?.usesConfirmedSnapshots ? [] : await claims.releaseExpired().catch((error) => {
-          app.log.error(error);
-          return [];
-        });
-        for (const balance of released) announcePlayer(balance.roundId, balance.player);
-
         for (const [id, room] of rooms) {
-          // Gameplay is over, but a buzzer-time authorisation and the chart remain honourable through
-          // the independent books tail. A process can wake for the first time after this tail (for
+          // Gameplay is over, but a buzzer-time buy and the chart remain honourable through the
+          // independent books tail. A process can wake for the first time after this tail (for
           // example after a stall or restart), so persist every due game wake before deleting it.
           if (now > room.launch.booksCloseAt) {
-            // Confirmations may trail a last-second claim's deadline. Keep background accounting
-            // alive at the normal cadence until holds settle; socket deadlines remain independent.
-            if (settlement?.usesConfirmedSnapshots && !sweeping) continue;
+            // The last reconcile must run at the normal cadence, not on every tick, and a room is
+            // torn down only after one clean pass so the final standings carry every landed buy.
+            if (settlement && !sweeping) continue;
             try {
               if (room.nextWakeAt() !== null) await room.tick(Math.min(now, room.window.closesAt));
             } catch (error) {
@@ -1312,8 +1307,18 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
             if (settlement) {
               const final = await settlement.reconcile(id).catch(() => ({ read: 0, failed: 1, changed: [] }));
               if (final.failed > 0) app.log.error(`${id}: ${final.failed} final spend reads failed`);
-              if (settlement.usesConfirmedSnapshots &&
-                  (final.failed > 0 || await settlement.hasPendingClaims(id).catch(() => true))) continue;
+              if (final.failed > 0) continue;
+            }
+            // The round is now proven final. Persist that before anything is torn down, so a page
+            // reading the standings can tell "ended, still settling" from "final" — and so the
+            // 4410 close below is never sent for a round the database still calls unsettled.
+            try {
+              await room.markSettled(now);
+            } catch (error) {
+              // Retain the room and retry: the standings would otherwise never be marked final,
+              // and the sockets would be told the round ended before the database agreed.
+              app.log.error(error);
+              continue;
             }
             for (const watcher of watchers.get(id) ?? []) {
               if (

package/src/settlement.ts

@@ -7,19 +7,17 @@ import type { ChainReader } from './chain/discover.js';
 /**
  * Keeping the ledger honest about what was actually spent.
  *
- * The obvious design is to watch for a swap and match it back to the authorisation that permitted
- * it. That turns out to be both harder and less useful than it sounds: the event carries the buyer
- * and the amount but not the nonce, and a wallet can submit through a relay, so correlating them is
- * guesswork.
+ * The calculator keeps one cumulative figure per pool per wallet, `walletSpentWei`, and it is the
+ * only figure that is true: it is what the contract itself enforces the signed ceiling against.
+ * Settlement reads it at a confirmed block and records it, never backwards. There is nothing to
+ * match back to an authorisation — a signed ceiling is not consumed, so it has no fate to prove.
  *
- * Read cumulative spend and exact authorisation consumption from the same block. Equal amounts
- * are not proof that a hold was consumed. A browser receipt is not a reason to release a hold.
+ * A buy that lands after `closesAt` still needs to be folded into `spent` for the standings, which
+ * is why reconciliation runs through `booksCloseAt` and the room waits for one clean final pass.
  */
 
 const spendGatedAbi = parseAbi([
   'function walletSpentWei(bytes32 _poolId, address _wallet) view returns (uint256)',
-  'function hashSpendAuthorization(address,bytes32,uint256,uint256,uint256) view returns (bytes32)',
-  'function isAuthorizationUsed(bytes32) view returns (bool)',
 ]);
 
 export class Settlement {
@@ -30,16 +28,6 @@ export class Settlement {
     private readonly calculator: `0x${string}`,
   ) {}
 
-  /** Expiry must use the same confirmed chain snapshot as spend when snapshot reads are available. */
-  get usesConfirmedSnapshots(): boolean { return typeof this.client.getBlock === 'function'; }
-
-  async hasPendingClaims(roundId: string): Promise<boolean> {
-    const result = await this.pool.query<{ pending: boolean }>(
-      `select exists(select 1 from claims where round_id = $1 and status = 'held') as pending`, [roundId],
-    );
-    return result.rows[0]?.pending ?? false;
-  }
-
   /**
    * Bring one round's view of spending up to date with the chain.
    *
@@ -61,14 +49,12 @@ export class Settlement {
 
     for (const player of players) {
       try {
-        // Two blocks behind the observed head, then verify that block is still canonical before
-        // committing. This follows chain confirmations, not wallet UI completion. Read-only
-        // legacy adapters retain conservative expiry-only holds until upgraded to a full client.
+        // Two blocks behind the observed head when the client can name blocks, so a reorg of the
+        // tip cannot record a spend that then vanishes. A read-only legacy adapter reads the tip;
+        // `recordChainSpend` never goes backwards, so the worst case is a figure that arrives early.
         const head = this.client.getBlock ? await this.client.getBlock({ blockTag: 'latest' }) : null;
-        const block = head?.number != null && head.number >= 2n
-          ? await this.client.getBlock!({ blockNumber: head.number - 2n }) : null;
-        if (this.client.getBlock && (block?.number !== head!.number! - 2n || !block?.hash || typeof block.timestamp !== 'bigint')) throw new Error('No confirmed block');
-        const atBlock = block ? { blockNumber: block.number! } : {};
+        if (this.client.getBlock && (head?.number == null || head.number < 2n)) throw new Error('No confirmed block');
+        const atBlock = head?.number != null ? { blockNumber: head.number - 2n } : {};
         const spent = (await this.client.readContract({
           address: this.calculator,
           abi: spendGatedAbi,
@@ -77,24 +63,7 @@ export class Settlement {
           ...atBlock,
         })) as bigint;
         if (typeof spent !== 'bigint' || spent < 0n) throw new Error('Invalid chain spend');
-        const consumed: bigint[] = [];
-        if (block) {
-          const outstanding = await this.ledger.outstandingClaims(roundId, player);
-          for (const claim of outstanding) {
-            if (claim.deadline < block.timestamp) continue;
-            const digest = await this.client.readContract({ address: this.calculator, abi: spendGatedAbi,
-              functionName: 'hashSpendAuthorization',
-              args: [player as `0x${string}`, poolId as `0x${string}`, claim.deadline, claim.wei, claim.nonce], ...atBlock });
-            if (typeof digest !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(digest)) throw new Error('Invalid digest');
-            const used = await this.client.readContract({ address: this.calculator, abi: spendGatedAbi,
-              functionName: 'isAuthorizationUsed', args: [digest], ...atBlock });
-            if (typeof used !== 'boolean') throw new Error('Invalid consumption proof');
-            if (used) consumed.push(claim.nonce);
-          }
-          const canonical = await this.client.getBlock!({ blockNumber: block.number! });
-          if (canonical.hash !== block.hash) throw new Error('Settlement block changed');
-        }
-        if (await this.ledger.reconcileSpend(roundId, player, spent, consumed, block?.timestamp)) changed.push(player);
+        if (await this.ledger.recordChainSpend(roundId, player, spent)) changed.push(player);
         read += 1;
       } catch {
         // One unreachable read is not a reason to stop the round, but it is counted. Swallowed

package/src/standings.ts

@@ -43,13 +43,15 @@ export class Standings {
       coin_symbol: string;
       opens_at: string;
       closes_at: string;
+      books_close_at: string;
+      settled_at: string | null;
       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,
+      `select id, pool_id, coin_address, coin_symbol, opens_at, closes_at, books_close_at, settled_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
@@ -78,6 +80,9 @@ export class Standings {
     ]);
 
     const window = { opensAt: Number(round.opens_at), closesAt: Number(round.closes_at) };
+    // `settled_at` is stamped by the gate's ticker after its last clean reconcile, so it is the one
+    // fact that separates "ended, still settling" from "final". The phase is clock-based and cannot.
+    const settledAt = round.settled_at === null ? null : Number(round.settled_at);
     return {
       roundId: round.id,
       poolId: round.pool_id,
@@ -85,6 +90,9 @@ export class Standings {
       symbol: round.coin_symbol,
       phase: roundPhaseAt(window, now),
       ...window,
+      booksCloseAt: Number(round.books_close_at),
+      settledAt,
+      final: settledAt !== null,
       spendToken: {
         address: round.spend_token,
         symbol: round.spend_symbol,

package/src/store.ts

@@ -95,6 +95,12 @@ alter table rounds
 alter table rounds
   add column if not exists position_manager text check (position_manager <> '');
 
+-- Round finalization (0.7.0). The moment the gate finished its last clean settlement pass past
+-- books_close_at, in ms since the epoch: from here chain_spent_wei cannot move. Null while a round is still
+-- settling, and on rounds a gate below 0.7.0 closed — nothing can reconstruct it for those.
+alter table rounds
+  add column if not exists settled_at bigint;
+
 create table if not exists balances (
   round_id text not null references rounds(id) on delete cascade,
   player   text not null,
@@ -105,27 +111,32 @@ create table if not exists balances (
   primary key (round_id, player)
 );
 
--- One row per authorisation ever issued. Nothing is deleted: a signature that exists in the world
--- cannot be un-issued, so the ledger records its fate instead of forgetting it.
-create table if not exists claims (
-  nonce         bigint generated always as identity primary key,
-  round_id      text not null references rounds(id) on delete cascade,
-  player        text not null,
-  request_id    varchar(128) not null check (request_id <> ''),
-  requested_wei numeric(78,0) not null check (requested_wei > 0),
-  wei           numeric(78,0) not null check (wei > 0 and wei <= requested_wei),
-  -- Held or released, and nothing else. Whether a swap LANDED is the chain's to say, not ours.
-  status        text not null check (status in ('held', 'released')),
-  deadline      bigint not null,
-  -- Persisted before a payload leaves the gate. Until signing completes, both values are null.
-  signature     text,
-  signer        text,
-  created_at    timestamptz not null default now(),
-  constraint claims_by_request unique (round_id, player, request_id),
-  constraint claims_signature_pair check ((signature is null) = (signer is null))
+-- One row per signed authorisation, kept only so a retried or replica-raced request returns the
+-- exact bytes already handed out. Nothing here is a reservation: the signature carries a
+-- cumulative ceiling the calculator compares against its own walletSpentWei, so an unused one
+-- costs nothing and there is no fate to record.
+create table if not exists authorisations (
+  round_id          text not null references rounds(id) on delete cascade,
+  player            text not null,
+  request_id        varchar(128) not null check (request_id <> ''),
+  -- What the caller asked for, so a retry with a different amount is refused, not silently served.
+  requested_wei     numeric(78,0) not null check (requested_wei > 0),
+  -- The signed field: min(earned, wallet cap) at issue, in the round's spend-token base units.
+  spend_ceiling_wei numeric(78,0) not null check (spend_ceiling_wei > 0),
+  -- The exact-in amount the caller intended, clamped to what was available. Echoed, not signed.
+  spend_wei         numeric(78,0) not null check (spend_wei > 0 and spend_wei <= spend_ceiling_wei),
+  deadline          bigint not null,
+  signature         text not null,
+  signer            text not null,
+  created_at        timestamptz not null default now(),
+  primary key (round_id, player, request_id)
 );
 
-create index if not exists claims_by_player on claims (round_id, player) where status = 'held';
+-- 0.7.0 hard cutover. Holds no longer exist, and every row the old table could carry was signed
+-- under the version 1 calculator domain that a 0.7.0 gate cannot serve. Dropping it is the honest
+-- migration; a gate should not be upgraded until every live round has passed its books close.
+drop index if exists claims_by_player;
+drop table if exists claims;
 
 -- Trusted creator servers use one stable event id for every score increment. The event and the
 -- balance update commit together, so a retry can recover the first result without paying twice.

package/src/version.ts

@@ -1,5 +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.6.0";
+export const GATE_VERSION: string = "0.7.0";
 /** `@flayerlabs/gamemode-gate@<version>`: the text a build of this package can be searched for. */
-export const GATE_MARKER: string = "@flayerlabs/gamemode-gate@0.6.0";
+export const GATE_MARKER: string = "@flayerlabs/gamemode-gate@0.7.0";