@flayerlabs/gamemode-gate 0.5.3 → 0.5.5

package/dist/settlement.d.ts

@@ -1,3 +1,4 @@
+import { type PublicClient } from 'viem';
 import type { Pool } from 'pg';
 import type { PlayerId } from '@flayerlabs/gamemode-spec';
 import type { Ledger } from './ledger.js';
@@ -7,7 +8,10 @@ export declare class Settlement {
     private readonly ledger;
     private readonly client;
     private readonly calculator;
-    constructor(pool: Pool, ledger: Ledger, client: ChainReader, calculator: `0x${string}`);
+    constructor(pool: Pool, ledger: Ledger, client: ChainReader & Partial<Pick<PublicClient, 'getBlock'>>, calculator: `0x${string}`);
+    /** Expiry must use the same confirmed chain snapshot as spend when snapshot reads are available. */
+    get usesConfirmedSnapshots(): boolean;
+    hasPendingClaims(roundId: string): Promise<boolean>;
     /**
      * Bring one round's view of spending up to date with the chain.
      *

package/dist/settlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../src/settlement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAmBvD,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAHV,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,KAAK,MAAM,EAAE;IAG5C;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;CAiCjG"}
+{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../src/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AACnD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAoBvD,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAHV,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,EAC7D,UAAU,EAAE,KAAK,MAAM,EAAE;IAG5C,oGAAoG;IACpG,IAAI,sBAAsB,IAAI,OAAO,CAAuD;IAEtF,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOzD;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;CA2DjG"}

package/dist/settlement.js

@@ -7,12 +7,13 @@ import { parseAbi } from 'viem';
  * and the amount but not the nonce, and a wallet can submit through a relay, so correlating them is
  * guesswork.
  *
- * The contract already keeps the number that matters. `walletSpentWei(poolId, wallet)` is what it
- * enforces against, so reading it is reading the truth rather than inferring it. No matching, no
- * event log to replay, and nothing to get subtly wrong.
+ * 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.
  */
 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 {
     pool;
@@ -25,6 +26,12 @@ export class Settlement {
         this.client = client;
         this.calculator = calculator;
     }
+    /** Expiry must use the same confirmed chain snapshot as spend when snapshot reads are available. */
+    get usesConfirmedSnapshots() { return typeof this.client.getBlock === 'function'; }
+    async hasPendingClaims(roundId) {
+        const result = await this.pool.query(`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.
      *
@@ -45,13 +52,47 @@ export class Settlement {
         const changed = [];
         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.
+                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 } : {};
                 const spent = (await this.client.readContract({
                     address: this.calculator,
                     abi: spendGatedAbi,
                     functionName: 'walletSpentWei',
                     args: [poolId, player],
+                    ...atBlock,
                 }));
-                if (spent > 0n && await this.ledger.recordChainSpend(roundId, player, spent))
+                if (typeof spent !== 'bigint' || spent < 0n)
+                    throw new Error('Invalid chain spend');
+                const consumed = [];
+                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, poolId, 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);
                 read += 1;
             }

package/dist/settlement.js.map

@@ -1 +1 @@
-{"version":3,"file":"settlement.js","sourceRoot":"","sources":["../src/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAMhC;;;;;;;;;;;GAWG;AAEH,MAAM,aAAa,GAAG,QAAQ,CAAC;IAC7B,kFAAkF;CACnF,CAAC,CAAC;AAEH,MAAM,OAAO,UAAU;IAEF;IACA;IACA;IACA;IAJnB,YACmB,IAAU,EACV,MAAc,EACd,MAAmB,EACnB,UAAyB;QAHzB,SAAI,GAAJ,IAAI,CAAM;QACV,WAAM,GAAN,MAAM,CAAQ;QACd,WAAM,GAAN,MAAM,CAAa;QACnB,eAAU,GAAV,UAAU,CAAe;IACzC,CAAC;IAEJ;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,CAAC,OAAe;QAC7B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAsB,0CAA0C,EAAE;YACnG,OAAO;SACR,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;QACtC,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAExD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACrD,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,MAAM,OAAO,GAAe,EAAE,CAAC;QAE/B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;oBAC5C,OAAO,EAAE,IAAI,CAAC,UAAU;oBACxB,GAAG,EAAE,aAAa;oBAClB,YAAY,EAAE,gBAAgB;oBAC9B,IAAI,EAAE,CAAC,MAAuB,EAAE,MAAuB,CAAC;iBACzD,CAAC,CAAW,CAAC;gBAEd,IAAI,KAAK,GAAG,EAAE,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC;oBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACnG,IAAI,IAAI,CAAC,CAAC;YACZ,CAAC;YAAC,MAAM,CAAC;gBACP,uFAAuF;gBACvF,0FAA0F;gBAC1F,sFAAsF;gBACtF,gBAAgB;gBAChB,MAAM,IAAI,CAAC,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACnC,CAAC;CACF"}
+{"version":3,"file":"settlement.js","sourceRoot":"","sources":["../src/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAqB,MAAM,MAAM,CAAC;AAMnD;;;;;;;;;;GAUG;AAEH,MAAM,aAAa,GAAG,QAAQ,CAAC;IAC7B,kFAAkF;IAClF,iGAAiG;IACjG,2DAA2D;CAC5D,CAAC,CAAC;AAEH,MAAM,OAAO,UAAU;IAEF;IACA;IACA;IACA;IAJnB,YACmB,IAAU,EACV,MAAc,EACd,MAA6D,EAC7D,UAAyB;QAHzB,SAAI,GAAJ,IAAI,CAAM;QACV,WAAM,GAAN,MAAM,CAAQ;QACd,WAAM,GAAN,MAAM,CAAuD;QAC7D,eAAU,GAAV,UAAU,CAAe;IACzC,CAAC;IAEJ,oGAAoG;IACpG,IAAI,sBAAsB,KAAc,OAAO,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC;IAE5F,KAAK,CAAC,gBAAgB,CAAC,OAAe;QACpC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAClC,wFAAwF,EAAE,CAAC,OAAO,CAAC,CACpG,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,KAAK,CAAC;IAC1C,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,CAAC,OAAe;QAC7B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAsB,0CAA0C,EAAE;YACnG,OAAO;SACR,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;QACtC,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAExD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACrD,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,MAAM,OAAO,GAAe,EAAE,CAAC;QAE/B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACH,wFAAwF;gBACxF,oFAAoF;gBACpF,yFAAyF;gBACzF,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC9F,MAAM,KAAK,GAAG,IAAI,EAAE,MAAM,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,EAAE;oBACrD,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAS,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC1E,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,IAAK,CAAC,MAAO,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;gBACjK,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,MAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5D,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;oBAC5C,OAAO,EAAE,IAAI,CAAC,UAAU;oBACxB,GAAG,EAAE,aAAa;oBAClB,YAAY,EAAE,gBAAgB;oBAC9B,IAAI,EAAE,CAAC,MAAuB,EAAE,MAAuB,CAAC;oBACxD,GAAG,OAAO;iBACX,CAAC,CAAW,CAAC;gBACd,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,EAAE;oBAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;gBACpF,MAAM,QAAQ,GAAa,EAAE,CAAC;gBAC9B,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;oBACzE,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;wBAChC,IAAI,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,SAAS;4BAAE,SAAS;wBAC/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,aAAa;4BAC1F,YAAY,EAAE,wBAAwB;4BACtC,IAAI,EAAE,CAAC,MAAuB,EAAE,MAAuB,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;wBAClH,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC;4BAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;wBACzG,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,aAAa;4BACxF,YAAY,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;wBACrE,IAAI,OAAO,IAAI,KAAK,SAAS;4BAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;wBAC5E,IAAI,IAAI;4BAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;oBACvC,CAAC;oBACD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAS,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,MAAO,EAAE,CAAC,CAAC;oBAC9E,IAAI,SAAS,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;wBAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;gBACjF,CAAC;gBACD,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC;oBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC/G,IAAI,IAAI,CAAC,CAAC;YACZ,CAAC;YAAC,MAAM,CAAC;gBACP,uFAAuF;gBACvF,0FAA0F;gBAC1F,sFAAsF;gBACtF,gBAAgB;gBAChB,MAAM,IAAI,CAAC,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACnC,CAAC;CACF"}

package/dist/store.d.ts

@@ -6,7 +6,7 @@ import type { Pool, PoolClient } from 'pg';
  * table is how a schema drifts: one adds a column, the other's migration never runs, and the
  * failure appears somewhere neither of them looks.
  */
-export declare const SCHEMA = "\ncreate table if not exists rounds (\n  id             text primary key,\n  game_id        text not null check (game_id <> ''),\n  wei_per_point  numeric(78,0) not null check (wei_per_point > 0),\n  wallet_cap_wei numeric(78,0) not null check (wallet_cap_wei > 0),\n  -- The two settings that produced wei_per_point, frozen beside it. They are gate-process config,\n  -- so an operator who restarts with a new ETH price must not retroactively change what a round\n  -- was priced at.\n  points_per_dollar double precision not null check (points_per_dollar > 0),\n  usd_per_eth       double precision not null check (usd_per_eth > 0),\n  -- The token spend is measured in: the coin's paired token, in whose base units every *_wei column\n  -- of this round is denominated. Defaults describe ETH, which is what every round was before the\n  -- columns existed, so a pre-existing row reads back exactly as it was priced. usd_per_eth holds\n  -- the rate normalised to eighteen decimals (see economy.ts); usd_per_spend_token the token's own\n  -- price, null on rows that predate it (for which usd_per_eth is that price).\n  spend_token    text not null default '0x0000000000000000000000000000000000000000' check (spend_token <> ''),\n  spend_symbol   text not null default 'ETH' check (spend_symbol <> ''),\n  spend_decimals integer not null default 18 check (spend_decimals between 0 and 36),\n  usd_per_spend_token double precision check (usd_per_spend_token > 0),\n  max_points_per_player bigint not null check (max_points_per_player > 0),\n  score_authority text not null check (score_authority in ('rules', 'external-server')),\n  pool_id        text not null,\n  opens_at       bigint not null,\n  closes_at      bigint not null,\n  books_close_at bigint not null,\n  coin_address   text,\n  coin_name      text not null,\n  coin_symbol    text not null,\n  coin_image_url text,\n  -- The game's own state, opaque to the platform. Written after every command, so a restart\n  -- resumes from here rather than replaying history.\n  state          jsonb not null,\n  -- Commands applied so far. Doubles as the cursor a reconnecting client resumes from.\n  seq            integer not null default 0 check (seq >= 0),\n  constraint rounds_window check (opens_at < closes_at),\n  constraint rounds_books_tail check (books_close_at >= closes_at)\n);\n\n-- A developer may already have run the first published schema without creating any rounds. Add\n-- the new authority fields in place for that empty setup. Existing round data needs a deliberate\n-- reset because its original reward bound cannot be reconstructed safely.\nalter table rounds\n  add column if not exists game_id text check (game_id <> '');\nalter table rounds\n  add column if not exists max_points_per_player bigint check (max_points_per_player > 0);\nalter table rounds\n  add column if not exists score_authority text check (score_authority in ('rules', 'external-server'));\nalter table rounds\n  add column if not exists points_per_dollar double precision check (points_per_dollar > 0);\nalter table rounds\n  add column if not exists usd_per_eth double precision check (usd_per_eth > 0);\ndo $$\nbegin\n  if exists (\n    select 1 from rounds\n    where game_id is null or max_points_per_player is null or score_authority is null\n       or points_per_dollar is null or usd_per_eth is null\n  ) then\n    raise exception 'pre-release round rows cannot be upgraded safely'\n      using hint = 'Delete the pre-release round data, then run migrate(pool) again.';\n  end if;\nend\n$$;\nalter table rounds alter column game_id set not null;\nalter table rounds alter column max_points_per_player set not null;\nalter table rounds alter column score_authority set not null;\nalter table rounds alter column points_per_dollar set not null;\nalter table rounds alter column usd_per_eth set not null;\n\n-- Paired-token rounds (0.5.0). Every earlier round was an ETH round, so the defaults ARE the\n-- backfill: Postgres fills a new not-null column with its default, and ETH/18 is exactly what those\n-- rows were priced in. No guard is needed \u2014 nothing here has to be guessed.\nalter table rounds\n  add column if not exists spend_token text not null default '0x0000000000000000000000000000000000000000' check (spend_token <> '');\nalter table rounds\n  add column if not exists spend_symbol text not null default 'ETH' check (spend_symbol <> '');\nalter table rounds\n  add column if not exists spend_decimals integer not null default 18 check (spend_decimals between 0 and 36);\nalter table rounds\n  add column if not exists usd_per_spend_token double precision check (usd_per_spend_token > 0);\n\ncreate table if not exists balances (\n  round_id text not null references rounds(id) on delete cascade,\n  player   text not null,\n  points   bigint not null default 0 check (points >= 0),\n  -- What the chain says this wallet has already spent on this pool. The contract keeps this and\n  -- enforces it whatever we believe, so it is the only figure that is actually true.\n  chain_spent_wei numeric(78,0) not null default 0 check (chain_spent_wei >= 0),\n  primary key (round_id, player)\n);\n\n-- One row per authorisation ever issued. Nothing is deleted: a signature that exists in the world\n-- cannot be un-issued, so the ledger records its fate instead of forgetting it.\ncreate table if not exists claims (\n  nonce         bigint generated always as identity primary key,\n  round_id      text not null references rounds(id) on delete cascade,\n  player        text not null,\n  request_id    varchar(128) not null check (request_id <> ''),\n  requested_wei numeric(78,0) not null check (requested_wei > 0),\n  wei           numeric(78,0) not null check (wei > 0 and wei <= requested_wei),\n  -- Held or released, and nothing else. Whether a swap LANDED is the chain's to say, not ours.\n  status        text not null check (status in ('held', 'released')),\n  deadline      bigint not null,\n  -- Persisted before a payload leaves the gate. Until signing completes, both values are null.\n  signature     text,\n  signer        text,\n  created_at    timestamptz not null default now(),\n  constraint claims_by_request unique (round_id, player, request_id),\n  constraint claims_signature_pair check ((signature is null) = (signer is null))\n);\n\ncreate index if not exists claims_by_player on claims (round_id, player) where status = 'held';\n\n-- Trusted creator servers use one stable event id for every score increment. The event and the\n-- balance update commit together, so a retry can recover the first result without paying twice.\ncreate table if not exists award_events (\n  round_id  text not null references rounds(id) on delete cascade,\n  event_id  varchar(128) not null check (event_id <> ''),\n  player    text not null,\n  points    bigint not null check (points > 0),\n  total_points bigint not null check (total_points >= points),\n  created_at timestamptz not null default now(),\n  primary key (round_id, event_id)\n);\n\n-- Which game a coin plays. Addresses are chain-local, so the pin is one row per (chain, coin).\ncreate table if not exists registrations (\n  chain_id    bigint not null check (chain_id > 0),\n  coin        text not null check (coin <> ''),\n  game_id     text not null check (game_id <> ''),\n  gate_origin text not null check (gate_origin <> ''),\n  deploy_id   text not null check (deploy_id <> ''),\n  game_server_origins text[] not null default '{}'::text[],\n  disabled_at timestamptz,\n  updated_at  timestamptz not null default now(),\n  constraint registrations_game_server_origins_bounded check (cardinality(game_server_origins) <= 4),\n  primary key (chain_id, coin)\n);\n\n-- What actually happened, in order. Not used to rebuild state \u2014 the snapshot does that \u2014 but it is\n-- the record of why a state looks the way it does, which is what an incident needs.\ncreate table if not exists commands (\n  round_id text not null references rounds(id) on delete cascade,\n  seq      integer not null check (seq > 0),\n  command  jsonb not null,\n  primary key (round_id, seq)\n);\n";
+export declare const SCHEMA = "\ncreate table if not exists rounds (\n  id             text primary key,\n  game_id        text not null check (game_id <> ''),\n  wei_per_point  numeric(78,0) not null check (wei_per_point > 0),\n  wallet_cap_wei numeric(78,0) not null check (wallet_cap_wei > 0),\n  -- The two settings that produced wei_per_point, frozen beside it. They are gate-process config,\n  -- so an operator who restarts with a new ETH price must not retroactively change what a round\n  -- was priced at.\n  points_per_dollar double precision not null check (points_per_dollar > 0),\n  usd_per_eth       double precision not null check (usd_per_eth > 0),\n  -- The token spend is measured in: the coin's paired token, in whose base units every *_wei column\n  -- of this round is denominated. Defaults describe ETH, which is what every round was before the\n  -- columns existed, so a pre-existing row reads back exactly as it was priced. usd_per_eth holds\n  -- the rate normalised to eighteen decimals (see economy.ts); usd_per_spend_token the token's own\n  -- price, null on rows that predate it (for which usd_per_eth is that price).\n  spend_token    text not null default '0x0000000000000000000000000000000000000000' check (spend_token <> ''),\n  spend_symbol   text not null default 'ETH' check (spend_symbol <> ''),\n  spend_decimals integer not null default 18 check (spend_decimals between 0 and 36),\n  usd_per_spend_token double precision check (usd_per_spend_token > 0),\n  max_points_per_player bigint not null check (max_points_per_player > 0),\n  score_authority text not null check (score_authority in ('rules', 'external-server')),\n  pool_id        text not null,\n  opens_at       bigint not null,\n  closes_at      bigint not null,\n  books_close_at bigint not null,\n  coin_address   text,\n  coin_name      text not null,\n  coin_symbol    text not null,\n  coin_image_url text,\n  -- The game's own state, opaque to the platform. Written after every command, so a restart\n  -- resumes from here rather than replaying history.\n  state          jsonb not null,\n  -- Commands applied so far. Doubles as the cursor a reconnecting client resumes from.\n  seq            integer not null default 0 check (seq >= 0),\n  constraint rounds_window check (opens_at < closes_at),\n  constraint rounds_books_tail check (books_close_at >= closes_at)\n);\n\n-- A developer may already have run the first published schema without creating any rounds. Add\n-- the new authority fields in place for that empty setup. Existing round data needs a deliberate\n-- reset because its original reward bound cannot be reconstructed safely.\nalter table rounds\n  add column if not exists game_id text check (game_id <> '');\nalter table rounds\n  add column if not exists max_points_per_player bigint check (max_points_per_player > 0);\nalter table rounds\n  add column if not exists score_authority text check (score_authority in ('rules', 'external-server'));\nalter table rounds\n  add column if not exists points_per_dollar double precision check (points_per_dollar > 0);\nalter table rounds\n  add column if not exists usd_per_eth double precision check (usd_per_eth > 0);\ndo $$\nbegin\n  if exists (\n    select 1 from rounds\n    where game_id is null or max_points_per_player is null or score_authority is null\n       or points_per_dollar is null or usd_per_eth is null\n  ) then\n    raise exception 'pre-release round rows cannot be upgraded safely'\n      using hint = 'Delete the pre-release round data, then run migrate(pool) again.';\n  end if;\nend\n$$;\nalter table rounds alter column game_id set not null;\nalter table rounds alter column max_points_per_player set not null;\nalter table rounds alter column score_authority set not null;\nalter table rounds alter column points_per_dollar set not null;\nalter table rounds alter column usd_per_eth set not null;\n\n-- Paired-token rounds (0.5.0). Every earlier round was an ETH round, so the defaults ARE the\n-- backfill: Postgres fills a new not-null column with its default, and ETH/18 is exactly what those\n-- rows were priced in. No guard is needed \u2014 nothing here has to be guessed.\nalter table rounds\n  add column if not exists spend_token text not null default '0x0000000000000000000000000000000000000000' check (spend_token <> '');\nalter table rounds\n  add column if not exists spend_symbol text not null default 'ETH' check (spend_symbol <> '');\nalter table rounds\n  add column if not exists spend_decimals integer not null default 18 check (spend_decimals between 0 and 36);\nalter table rounds\n  add column if not exists usd_per_spend_token double precision check (usd_per_spend_token > 0);\n\ncreate table if not exists balances (\n  round_id text not null references rounds(id) on delete cascade,\n  player   text not null,\n  points   bigint not null default 0 check (points >= 0),\n  -- What the chain says this wallet has already spent on this pool. The contract keeps this and\n  -- enforces it whatever we believe, so it is the only figure that is actually true.\n  chain_spent_wei numeric(78,0) not null default 0 check (chain_spent_wei >= 0),\n  primary key (round_id, player)\n);\n\n-- One row per authorisation ever issued. Nothing is deleted: a signature that exists in the world\n-- cannot be un-issued, so the ledger records its fate instead of forgetting it.\ncreate table if not exists claims (\n  nonce         bigint generated always as identity primary key,\n  round_id      text not null references rounds(id) on delete cascade,\n  player        text not null,\n  request_id    varchar(128) not null check (request_id <> ''),\n  requested_wei numeric(78,0) not null check (requested_wei > 0),\n  wei           numeric(78,0) not null check (wei > 0 and wei <= requested_wei),\n  -- Held or released, and nothing else. Whether a swap LANDED is the chain's to say, not ours.\n  status        text not null check (status in ('held', 'released')),\n  deadline      bigint not null,\n  -- Persisted before a payload leaves the gate. Until signing completes, both values are null.\n  signature     text,\n  signer        text,\n  created_at    timestamptz not null default now(),\n  constraint claims_by_request unique (round_id, player, request_id),\n  constraint claims_signature_pair check ((signature is null) = (signer is null))\n);\n\ncreate index if not exists claims_by_player on claims (round_id, player) where status = 'held';\n\n-- Trusted creator servers use one stable event id for every score increment. The event and the\n-- balance update commit together, so a retry can recover the first result without paying twice.\ncreate table if not exists award_events (\n  round_id  text not null references rounds(id) on delete cascade,\n  event_id  varchar(128) not null check (event_id <> ''),\n  player    text not null,\n  points    bigint not null check (points > 0),\n  total_points bigint not null check (total_points >= points),\n  created_at timestamptz not null default now(),\n  primary key (round_id, event_id)\n);\n\n-- Which game a coin plays. Addresses are chain-local, so the pin is one row per (chain, coin).\ncreate table if not exists registrations (\n  chain_id    bigint not null check (chain_id > 0),\n  coin        text not null check (coin <> ''),\n  game_id     text not null check (game_id <> ''),\n  gate_origin text not null check (gate_origin <> ''),\n  deploy_id   text not null check (deploy_id <> ''),\n  game_server_origins text[] not null default '{}'::text[],\n  disabled_at timestamptz,\n  updated_at  timestamptz not null default now(),\n  constraint registrations_game_server_origins_bounded check (cardinality(game_server_origins) <= 4),\n  primary key (chain_id, coin)\n);\n\n-- Accepted play sessions: one row per wallet and round, keyed by a hash of both so a wallet is never\n-- stored in the clear. Independent of scoring and of websocket reconnects. play_tracking records\n-- when this gate began counting, so a dashboard can tell \"no plays\" from \"not yet tracked\".\ncreate table if not exists play_sessions (\n  id text primary key,\n  round_id text not null references rounds(id) on delete cascade,\n  started_at bigint not null\n);\ncreate index if not exists play_sessions_started_id_idx on play_sessions(started_at, id);\ncreate table if not exists play_tracking (\n  id boolean primary key default true check (id),\n  started_at bigint not null\n);\ninsert into play_tracking(id, started_at) values (true, (extract(epoch from clock_timestamp()) * 1000)::bigint) on conflict do nothing;\n\n-- What actually happened, in order. Not used to rebuild state \u2014 the snapshot does that \u2014 but it is\n-- the record of why a state looks the way it does, which is what an incident needs.\ncreate table if not exists commands (\n  round_id text not null references rounds(id) on delete cascade,\n  seq      integer not null check (seq > 0),\n  command  jsonb not null,\n  primary key (round_id, seq)\n);\n";
 /**
  * Run `fn` inside a transaction, committing on success and rolling back on failure.
  *

package/dist/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,k8PAoJlB,CAAC;AAMF;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAiBjG;AAED,sGAAsG;AACtG,wBAAsB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvD;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAA4B,CAAC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,8vRAmKlB,CAAC;AAMF;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAiBjG;AAED,sGAAsG;AACtG,wBAAsB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvD;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAA4B,CAAC"}

package/dist/store.js

@@ -145,6 +145,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/dist/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoJrB,CAAC;AAEF,MAAM,cAAc,GAAG;;EAErB,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,IAAU,EAAE,EAAkC;IACnF,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5B,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,OAAO,EAAE,CAAC;IACf,CAAC;AACH,CAAC;AAED,sGAAsG;AACtG,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAU;IACtC,MAAM,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QACrC,MAAM,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC/B,MAAM,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAyC,EAAU,EAAE,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmKrB,CAAC;AAEF,MAAM,cAAc,GAAG;;EAErB,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,IAAU,EAAE,EAAkC;IACnF,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5B,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,OAAO,EAAE,CAAC;IACf,CAAC;AACH,CAAC;AAED,sGAAsG;AACtG,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAU;IACtC,MAAM,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QACrC,MAAM,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC/B,MAAM,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAyC,EAAU,EAAE,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/** The published version of @flayerlabs/gamemode-gate, as a literal so it survives any bundler. */
+export declare const GATE_VERSION: string;
+/** `@flayerlabs/gamemode-gate@<version>`: the text a build of this package can be searched for. */
+export declare const GATE_MARKER: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,mGAAmG;AACnG,eAAO,MAAM,YAAY,EAAE,MAAgB,CAAC;AAC5C,mGAAmG;AACnG,eAAO,MAAM,WAAW,EAAE,MAA0C,CAAC"}

package/dist/version.js

@@ -0,0 +1,6 @@
+// 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 = "0.5.5";
+/** `@flayerlabs/gamemode-gate@<version>`: the text a build of this package can be searched for. */
+export const GATE_MARKER = "@flayerlabs/gamemode-gate@0.5.5";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,mGAAmG;AACnG,MAAM,CAAC,MAAM,YAAY,GAAW,OAAO,CAAC;AAC5C,mGAAmG;AACnG,MAAM,CAAC,MAAM,WAAW,GAAW,iCAAiC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flayerlabs/gamemode-gate",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Server-authoritative rooms, economy, admission and registry for Flaunch Game Modes",
   "license": "MIT",
   "author": "Flayer Labs",
@@ -35,7 +35,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "prebuild": "node ../../scripts/write-version.mjs && node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "tsc -p tsconfig.build.json",
     "prepack": "pnpm build",
     "typecheck": "tsc --noEmit",
@@ -45,7 +45,7 @@
   "dependencies": {
     "@fastify/cors": "^11.3.0",
     "@fastify/websocket": "^11.3.0",
-    "@flayerlabs/gamemode-spec": "^0.5.3",
+    "@flayerlabs/gamemode-spec": "^0.5.5",
     "@types/node": "^22.10.2",
     "@types/pg": "^8.21.0",
     "fastify": "^5.11.3",

package/src/index.ts

@@ -66,7 +66,8 @@ 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';

package/src/ledger.ts

@@ -72,8 +72,8 @@ function availableFrom({ points, unitsPerPoint, capWei, held, chainSpentWei }: L
   // authorisations, and the surplus does not overspend, it reverts at the swap, which to a player
   // is indistinguishable from being robbed.
   //
-  // Adding them double-counts a hold whose swap has already landed, until that hold expires. That
-  // errs towards authorising too little, which is the direction that costs nobody anything.
+  // Settlement removes proven-consumed authorisations in the same transaction as recording spend.
+  // Unverified authorisations remain held; never guess overlap from equal amounts.
   const available = ceiling - (chainSpentWei + held);
   return available > 0n ? available : 0n;
 }
@@ -195,6 +195,39 @@ export class Ledger {
     return result.rowCount === 1;
   }
 
+  /** Signed claims whose consumption still needs chain proof. Bounded per reconciliation pass. */
+  async outstandingClaims(roundId: string, player: PlayerId): Promise<Claim[]> {
+    const result = await this.pool.query<ClaimRow>(
+      `select nonce::text, player, request_id, requested_wei::text, wei::text, deadline::text,
+              status, signature, signer from claims
+       where round_id = $1 and player = $2 and status = 'held' and signature is not null
+       order by nonce limit 100`, [roundId, player],
+    );
+    return result.rows.map(claimFrom);
+  }
+
+  /** Caller supplies consumed nonces and cumulative spend from one verified chain snapshot. */
+  async reconcileSpend(roundId: string, player: PlayerId, spent: bigint, consumed: bigint[], expiredBeforeSeconds?: bigint): Promise<boolean> {
+    return inTransaction(this.pool, async tx => {
+      const balance = await tx.query<{ chain_spent_wei: string }>(
+        `select chain_spent_wei from balances where round_id = $1 and player = $2 for update`,
+        [roundId, player],
+      );
+      if (!balance.rows[0] || spent < toBigInt(balance.rows[0].chain_spent_wei)) return false;
+      const updated = await tx.query(
+        `update balances set chain_spent_wei = $3 where round_id = $1 and player = $2 and chain_spent_wei < $3`,
+        [roundId, player, spent.toString()],
+      );
+      const released = await tx.query(
+        `update claims set status = 'released' where round_id = $1 and player = $2
+         and status = 'held' and ((signature is not null and nonce = any($3::bigint[]))
+           or deadline < $4::numeric)`,
+        [roundId, player, consumed.map(String), expiredBeforeSeconds?.toString() ?? null],
+      );
+      return (updated.rowCount ?? 0) > 0 || (released.rowCount ?? 0) > 0;
+    });
+  }
+
   /** Everyone with a balance in this round, for the reconciler to ask the chain about. */
   async playersIn(roundId: string): Promise<PlayerId[]> {
     const result = await this.pool.query<{ player: string }>(
@@ -233,7 +266,11 @@ export class Ledger {
 
   /** The authoritative balance snapshot, derived from the same state and ceiling as `claim`. */
   async economyBalance(roundId: string, player: PlayerId): Promise<EconomyBalance> {
-    const state = await this.readState(this.pool, roundId, player);
+    // The balance and outstanding claims must be read from one database snapshot.
+    const state = await inTransaction(this.pool, async tx => {
+      await tx.query('set transaction isolation level repeatable read, read only');
+      return this.readState(tx, roundId, player);
+    });
     if (!state) {
       return { unitsPerPoint: 0n, earned: 0n, held: 0n, spent: 0n, available: 0n, holdExpiresAt: null };
     }

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

@@ -20,6 +20,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 +29,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.
@@ -179,6 +181,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. */
@@ -381,7 +392,7 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
   /** One Room per round in this process — the optimistic lock assumes a single writer. */
   async function roomFor(id: string) {
     const existing = rooms.get(id);
-    if (existing) return existing;
+    if (existing) return Date.now() <= existing.launch.booksCloseAt ? existing : null;
     const loaded = await Room.load(pool, game, id);
     if (loaded && loaded.scoreAuthority !== scoreAuthority) {
       app.log.error(`${id}: round belongs to ${loaded.scoreAuthority}, not ${scoreAuthority}`);
@@ -627,9 +638,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,7 +681,10 @@ 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;
     });
   }
 
@@ -742,6 +771,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 +868,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 +882,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) => {
@@ -1202,7 +1236,9 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
         const now = Date.now();
         const sweeping = Boolean(settlement && now - reconciledAt >= RECONCILE_MS);
         // Authorisations nobody spent come back to the player who earned them.
-        const released = await claims.releaseExpired().catch((error) => {
+        // 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 [];
         });
@@ -1213,6 +1249,9 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
           // 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;
             try {
               if (room.nextWakeAt() !== null) await room.tick(Math.min(now, room.window.closesAt));
             } catch (error) {
@@ -1224,6 +1263,8 @@ 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;
             }
             for (const watcher of watchers.get(id) ?? []) {
               if (

package/src/settlement.ts

@@ -1,4 +1,4 @@
-import { parseAbi } from 'viem';
+import { parseAbi, type PublicClient } from 'viem';
 import type { Pool } from 'pg';
 import type { PlayerId } from '@flayerlabs/gamemode-spec';
 import type { Ledger } from './ledger.js';
@@ -12,23 +12,34 @@ import type { ChainReader } from './chain/discover.js';
  * and the amount but not the nonce, and a wallet can submit through a relay, so correlating them is
  * guesswork.
  *
- * The contract already keeps the number that matters. `walletSpentWei(poolId, wallet)` is what it
- * enforces against, so reading it is reading the truth rather than inferring it. No matching, no
- * event log to replay, and nothing to get subtly wrong.
+ * 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.
  */
 
 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 {
   constructor(
     private readonly pool: Pool,
     private readonly ledger: Ledger,
-    private readonly client: ChainReader,
+    private readonly client: ChainReader & Partial<Pick<PublicClient, 'getBlock'>>,
     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.
    *
@@ -50,14 +61,40 @@ 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.
+        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! } : {};
         const spent = (await this.client.readContract({
           address: this.calculator,
           abi: spendGatedAbi,
           functionName: 'walletSpentWei',
           args: [poolId as `0x${string}`, player as `0x${string}`],
+          ...atBlock,
         })) as bigint;
-
-        if (spent > 0n && await this.ledger.recordChainSpend(roundId, player, spent)) changed.push(player);
+        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);
         read += 1;
       } catch {
         // One unreachable read is not a reason to stop the round, but it is counted. Swallowed

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.5";
+/** `@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.5";