@flayerlabs/gamemode-gate 0.6.0 → 0.7.0

package/src/ledger.ts

@@ -1,39 +1,47 @@
 import type { Pool } from 'pg';
 import type { PlayerId } from '@flayerlabs/gamemode-spec';
 import type { EconomyBalance } from '@flayerlabs/gamemode-spec/live';
-import { inTransaction, migrate, toBigInt } from './store.js';
+import { migrate, toBigInt } from './store.js';
 
 /**
- * What a player has earned, what they have been authorised to spend, and what is still available.
+ * What a player has earned, what the chain says they have spent, and what is still available.
  *
  * Two ceilings bind, and they are different in kind. The first is what the game says they earned.
  * The second is the pool's on-chain per-wallet cap, which the contract enforces whatever this file
  * believes — so issuing past it does not overspend, it produces an authorisation that reverts at
- * the swap and looks to the player like theft. Both are checked here.
+ * the swap and looks to the player like theft. The smaller of the two is the CEILING, and the
+ * ceiling is what the gate signs: not the amount of one purchase, but the most this wallet may ever
+ * have spent on this pool. The calculator keeps its own `walletSpentWei` and refuses any swap that
+ * would carry the total past the ceiling it was handed.
  *
- * Every claim takes a row lock on the player's balance for the length of the transaction. Two
- * claims arriving at once therefore serialise, rather than each reading the same balance and each
- * deciding it fits. That is the whole reason this is in the database and not in a Map.
+ * Nothing is held. Two authorisations with the same ceiling cannot add up, so an unused one costs
+ * nothing, a declined wallet dialog changes nothing, and `available` moves only when the chain
+ * shows a purchase (down) or the game awards points (up). The per-request lock this file used to
+ * take is gone with the reservation it protected; idempotency is the primary key on
+ * `authorisations` instead.
+ *
+ * One round is one pool. The pool-level `walletSpentWei` is therefore the round's spent figure,
+ * recorded per (round, player) in `balances.chain_spent_wei`.
  */
 
-export interface Claim {
-  nonce: bigint;
+/** A signed ceiling the gate handed out, kept so a retry can get the same bytes back. */
+export interface Authorisation {
   player: PlayerId;
   requestId: string;
+  /** What the caller asked to spend, before clamping. */
   requestedWei: bigint;
-  wei: bigint;
+  /** The signed cumulative ceiling: min(earned, wallet cap) at issue. */
+  spendCeilingWei: bigint;
+  /** The exact-in amount for this buy, clamped to what was available. Not signed. */
+  spendWei: bigint;
   deadline: bigint;
-  status: 'held' | 'released';
-  signature: `0x${string}` | null;
-  signer: `0x${string}` | null;
+  signature: `0x${string}`;
+  signer: `0x${string}`;
 }
 
-export type ClaimResult = { ok: true; claim: Claim } | { ok: false; refuse: string };
-
-export interface BalanceKey {
-  roundId: string;
-  player: PlayerId;
-}
+export type Quote =
+  | { ok: true; ceiling: bigint; available: bigint; deadlineSeconds: bigint }
+  | { ok: false; refuse: string };
 
 interface LedgerState {
   points: bigint;
@@ -41,44 +49,23 @@ interface LedgerState {
   capWei: bigint;
   opensAt: number;
   closesAt: number;
-  /** Authorisations still outstanding: issued, not yet expired, fate unknown. */
-  held: bigint;
+  booksCloseAt: number;
   /** What the chain says has actually been spent. */
   chainSpentWei: bigint;
-  /**
-   * Deadline of the earliest outstanding hold, in epoch SECONDS, or null when nothing is held.
-   *
-   * The earliest rather than the latest, because it is the first moment any allowance comes back.
-   */
-  holdExpiresAtSeconds: number | null;
 }
 
-/**
- * The one place the ceiling rule lives.
- *
- * Two limits bind and the smaller wins: what the game says was earned, and what the pool lets one
- * wallet spend. Issuing past the second does not overspend — the chain refuses it — it mints a
- * signature that reverts at the swap, which to a player is indistinguishable from being robbed.
- */
-function availableFrom({ points, unitsPerPoint, capWei, held, chainSpentWei }: LedgerState): bigint {
+/** The one place the ceiling rule lives: the smaller of what was earned and what the pool allows. */
+function ceilingFrom({ points, unitsPerPoint, capWei }: LedgerState): bigint {
   const earned = points * unitsPerPoint;
-  const ceiling = earned < capWei ? earned : capWei;
+  return earned < capWei ? earned : capWei;
+}
 
-  // Spent-on-chain PLUS still-outstanding, never the larger of the two.
-  //
-  // Taking the larger looked safe and was not. Hold 40, spend it, let the hold expire, then hold
-  // 60: the chain has 40 gone and 60 is outstanding, so nothing remains — but `max(60, 40)` says
-  // 40 is available and a further 40 gets authorised. Against a cap of 100 that is 140 of live
-  // authorisations, and the surplus does not overspend, it reverts at the swap, which to a player
-  // is indistinguishable from being robbed.
-  //
-  // 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);
+/** What a signed ceiling would let this wallet add right now. */
+function availableFrom(state: LedgerState): bigint {
+  const available = ceilingFrom(state) - state.chainSpentWei;
   return available > 0n ? available : 0n;
 }
 
-
 export class Ledger {
   constructor(private readonly pool: Pool) {}
 
@@ -88,97 +75,69 @@ export class Ledger {
   }
 
   /**
-   * Authorise up to `upToWei`, or refuse.
+   * What the gate would sign for this player right now, or why it would not.
    *
-   * Returns the largest amount available rather than refusing an over-ask: a player pressing buy
-   * wants to spend what they have, and telling them "you asked for too much" when they asked for
-   * everything is a worse product than giving them everything.
+   * The deadline is the round's books close: nothing new is issued after `closesAt`, ceilings are
+   * monotone so a long-lived signature is never over-generous, and a cached authorisation must stay
+   * returnable for as long as a retry can arrive.
    */
-  async claim(
-    roundId: string,
-    player: PlayerId,
-    upToWei: bigint,
-    requestId: string,
-    deadline: bigint,
-    at: number = Date.now(),
-  ): Promise<ClaimResult> {
-    return inTransaction(this.pool, async (tx) => {
-      // The lock is the point. Held for the transaction, it serialises every concurrent claim by
-      // this player, so two requests cannot both read the same balance and both decide they fit.
-      //
-      // It only works because a claim needs a balance row to exist: `for update` on a row that is
-      // not there locks NOTHING, and would serialise nothing. The `points <= 0` refusal below is
-      // therefore load-bearing rather than a convenience — it is what guarantees that by the time
-      // any claim proceeds past this point, there is a row holding the lock. Do not reorder it, and
-      // do not make the ledger issue against a player it has never credited.
-      const state = await this.readState(tx, roundId, player, true);
-      if (!state) return { ok: false, refuse: 'claim.no_such_round' };
-
-      // Inside the same player lock as the balance calculation. Two replicas handling one retried
-      // HTTP request therefore converge on one reservation instead of racing an uncommitted row.
-      const existing = await this.findClaimWith(tx, roundId, player, requestId);
-      if (existing) {
-        if (existing.requestedWei !== upToWei) return { ok: false, refuse: 'claim.request_mismatch' };
-        return { ok: true, claim: existing };
-      }
-
-      // Existing requests deliberately win over the clock: they were issued under the earlier
-      // call's window. Only a genuinely new reservation is subject to the current instant.
-      if (at < state.opensAt) return { ok: false, refuse: 'claim.not_open_yet' };
-      if (at >= state.closesAt) return { ok: false, refuse: 'claim.window_closed' };
-      if (state.points <= 0n) return { ok: false, refuse: 'claim.nothing_earned' };
+  async quote(roundId: string, player: PlayerId, at: number = Date.now()): Promise<Quote> {
+    const state = await this.readState(this.pool, roundId, player);
+    if (!state) return { ok: false, refuse: 'claim.no_such_round' };
+    if (at < state.opensAt) return { ok: false, refuse: 'claim.not_open_yet' };
+    if (at >= state.closesAt) return { ok: false, refuse: 'claim.window_closed' };
+    if (state.points <= 0n) return { ok: false, refuse: 'claim.nothing_earned' };
 
-      const available = availableFrom(state);
-      if (available <= 0n) return { ok: false, refuse: 'claim.nothing_available' };
+    const available = availableFrom(state);
+    if (available <= 0n) return { ok: false, refuse: 'claim.nothing_available' };
 
-      const wei = upToWei < available ? upToWei : available;
-      if (wei <= 0n) return { ok: false, refuse: 'claim.nothing_available' };
-
-      // Record the hold BEFORE anything signs against it. A signature that exists without a hold is
-      // allowance nobody is tracking; a hold without a signature is merely a refund waiting to
-      // happen. Only one of those two failures costs money.
-      const inserted = await tx.query<ClaimRow>(
-        `insert into claims (round_id, player, request_id, requested_wei, wei, status, deadline)
-         values ($1, $2, $3, $4, $5, 'held', $6)
-         returning nonce::text, player, request_id, requested_wei::text, wei::text, deadline::text,
-                   status, signature, signer`,
-        [roundId, player, requestId, upToWei.toString(), wei.toString(), deadline.toString()],
-      );
-      const created = inserted.rows[0];
-      if (!created) throw new Error(`${roundId}: claim reservation disappeared before commit`);
-      return { ok: true, claim: claimFrom(created) };
-    });
+    return {
+      ok: true,
+      ceiling: ceilingFrom(state),
+      available,
+      deadlineSeconds: BigInt(Math.ceil(state.booksCloseAt / 1000)),
+    };
   }
 
-  /** Store exactly one signature and return the stored winner to every concurrent signer. */
-  async completeClaim(nonce: bigint, signature: `0x${string}`, signer: `0x${string}`): Promise<Claim | null> {
-    return inTransaction(this.pool, async (tx) => {
-      const current = await this.findClaimByNonce(tx, nonce, true);
-      if (!current || current.status !== 'held') return current?.signature ? current : null;
-
-      if (!current.signature) {
-        await tx.query(`update claims set signature = $2, signer = $3 where nonce = $1`, [
-          nonce.toString(),
-          signature,
-          signer,
-        ]);
-      }
-      return this.findClaimByNonce(tx, nonce);
-    });
+  /** The authorisation already issued for this request, if any. */
+  async findAuthorisation(roundId: string, player: PlayerId, requestId: string): Promise<Authorisation | null> {
+    const result = await this.pool.query<AuthorisationRow>(
+      `select player, request_id, requested_wei::text, spend_ceiling_wei::text, spend_wei::text,
+              deadline::text, signature, signer
+       from authorisations where round_id = $1 and player = $2 and request_id = $3`,
+      [roundId, player, requestId],
+    );
+    return result.rows[0] ? authorisationFrom(result.rows[0]) : null;
   }
 
   /**
-   * Release only a reservation that provably never became a bearer authorisation.
+   * Store a signed authorisation and return the one every caller sees.
    *
-   * A signed payload cannot be revoked. Releasing one because a wallet dialog was declined would
-   * let a new nonce spend the same earned allowance while the first payload remained usable.
+   * Two replicas answering one retried request both insert; the primary key lets exactly one win,
+   * and both return the winner. Never hand out bytes that were not durably recorded, or a retry
+   * could receive a different signature for the same request id.
    */
-  async releaseUnsigned(nonce: bigint): Promise<void> {
+  async storeAuthorisation(roundId: string, authorisation: Authorisation): Promise<Authorisation> {
     await this.pool.query(
-      `update claims set status = 'released'
-       where nonce = $1 and status = 'held' and signature is null`,
-      [nonce.toString()],
+      `insert into authorisations
+         (round_id, player, request_id, requested_wei, spend_ceiling_wei, spend_wei, deadline, signature, signer)
+       values ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+       on conflict (round_id, player, request_id) do nothing`,
+      [
+        roundId,
+        authorisation.player,
+        authorisation.requestId,
+        authorisation.requestedWei.toString(),
+        authorisation.spendCeilingWei.toString(),
+        authorisation.spendWei.toString(),
+        authorisation.deadline.toString(),
+        authorisation.signature,
+        authorisation.signer,
+      ],
     );
+    const stored = await this.findAuthorisation(roundId, authorisation.player, authorisation.requestId);
+    if (!stored) throw new Error(`${roundId}: authorisation disappeared before it could be read back`);
+    return stored;
   }
 
   /**
@@ -195,39 +154,6 @@ 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 }>(
@@ -237,87 +163,41 @@ export class Ledger {
     return result.rows.map((row) => row.player);
   }
 
-  /**
-   * Give back every hold whose deadline has passed.
-   *
-   * An expired authorisation cannot be spent — the contract checks the same deadline — so a hold
-   * still sitting against it is allowance the player earned, cannot use, and would never get back.
-   * A player who opens the buy dialog and wanders off would otherwise lose it for the round.
-   *
-   * Returns how many were returned, so a caller can log something worth reading.
-   */
-  async releaseExpired(nowSeconds: number): Promise<BalanceKey[]> {
-    const result = await this.pool.query<{ round_id: string; player: PlayerId }>(
-      `update claims set status = 'released'
-       where status = 'held' and deadline < $1
-       returning round_id, player`,
-      [nowSeconds],
-    );
-    const unique = new Map(result.rows.map((row) => [
-      `${row.round_id}\u0000${row.player}`,
-      { roundId: row.round_id, player: row.player },
-    ]));
-    return [...unique.values()];
-  }
-
   async available(roundId: string, player: PlayerId): Promise<bigint> {
     return (await this.economyBalance(roundId, player)).available;
   }
 
-  /** The authoritative balance snapshot, derived from the same state and ceiling as `claim`. */
+  /** The authoritative balance snapshot, derived from the same state and ceiling as `quote`. */
   async economyBalance(roundId: string, player: PlayerId): Promise<EconomyBalance> {
-    // 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 };
-    }
+    const state = await this.readState(this.pool, roundId, player);
+    if (!state) return { unitsPerPoint: 0n, earned: 0n, spent: 0n, available: 0n };
 
     return {
       unitsPerPoint: state.unitsPerPoint,
       earned: state.points * state.unitsPerPoint,
-      held: state.held,
       spent: state.chainSpentWei,
       available: availableFrom(state),
-      // Seconds on the way in, because that is what the contract checks against; milliseconds on
-      // the way out, because that is what a browser counts down with.
-      holdExpiresAt: state.holdExpiresAtSeconds === null ? null : state.holdExpiresAtSeconds * 1000,
     };
   }
 
-  private async readState(
-    q: Pick<Pool, 'query'>,
-    roundId: string,
-    player: PlayerId,
-    lock = false,
-  ): Promise<LedgerState | null> {
+  private async readState(q: Pick<Pool, 'query'>, roundId: string, player: PlayerId): Promise<LedgerState | null> {
     const round = await q.query<{
       wei_per_point: string;
       wallet_cap_wei: string;
       opens_at: string;
       closes_at: string;
+      books_close_at: string;
     }>(
-      `select wei_per_point, wallet_cap_wei, opens_at, closes_at from rounds where id = $1`,
+      `select wei_per_point, wallet_cap_wei, opens_at, closes_at, books_close_at from rounds where id = $1`,
       [roundId],
     );
     const row = round.rows[0];
     if (!row) return null;
 
     const balance = await q.query<{ points: string; chain_spent_wei: string }>(
-      `select points, chain_spent_wei from balances where round_id = $1 and player = $2${lock ? ' for update' : ''}`,
+      `select points, chain_spent_wei from balances where round_id = $1 and player = $2`,
       [roundId, player],
     );
-    // Sum and earliest deadline together: they come from the same rows, and asking twice would let
-    // a hold expire between the two reads and report a total that no deadline explains.
-    const held = await q.query<{ total: string; earliest: string | null }>(
-      `select coalesce(sum(wei), 0)::text as total, min(deadline)::text as earliest from claims
-       where round_id = $1 and player = $2 and status = 'held'`,
-      [roundId, player],
-    );
-
-    const earliest = held.rows[0]?.earliest;
 
     return {
       points: toBigInt(balance.rows[0]?.points),
@@ -326,57 +206,29 @@ export class Ledger {
       capWei: toBigInt(row.wallet_cap_wei),
       opensAt: Number(row.opens_at),
       closesAt: Number(row.closes_at),
-      held: toBigInt(held.rows[0]?.total),
-      holdExpiresAtSeconds: earliest == null ? null : Number(earliest),
+      booksCloseAt: Number(row.books_close_at),
     };
   }
-
-  private async findClaimWith(
-    q: Pick<Pool, 'query'>,
-    roundId: string,
-    player: PlayerId,
-    requestId: string,
-  ): Promise<Claim | null> {
-    const result = await q.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 request_id = $3`,
-      [roundId, player, requestId],
-    );
-    return result.rows[0] ? claimFrom(result.rows[0]) : null;
-  }
-
-  private async findClaimByNonce(q: Pick<Pool, 'query'>, nonce: bigint, lock = false): Promise<Claim | null> {
-    const result = await q.query<ClaimRow>(
-      `select nonce::text, player, request_id, requested_wei::text, wei::text, deadline::text,
-              status, signature, signer
-       from claims where nonce = $1${lock ? ' for update' : ''}`,
-      [nonce.toString()],
-    );
-    return result.rows[0] ? claimFrom(result.rows[0]) : null;
-  }
 }
 
-interface ClaimRow {
-  nonce: string;
+interface AuthorisationRow {
   player: string;
   request_id: string;
   requested_wei: string;
-  wei: string;
+  spend_ceiling_wei: string;
+  spend_wei: string;
   deadline: string;
-  status: 'held' | 'released';
-  signature: `0x${string}` | null;
-  signer: `0x${string}` | null;
+  signature: `0x${string}`;
+  signer: `0x${string}`;
 }
 
-const claimFrom = (row: ClaimRow): Claim => ({
-  nonce: BigInt(row.nonce),
+const authorisationFrom = (row: AuthorisationRow): Authorisation => ({
   player: row.player,
   requestId: row.request_id,
   requestedWei: BigInt(row.requested_wei),
-  wei: BigInt(row.wei),
+  spendCeilingWei: BigInt(row.spend_ceiling_wei),
+  spendWei: BigInt(row.spend_wei),
   deadline: BigInt(row.deadline),
-  status: row.status,
   signature: row.signature,
   signer: row.signer,
 });

package/src/room.ts

@@ -372,6 +372,21 @@ export class Room<Config, State, Event, Action, PublicView, PlayerView> {
     return this.seq;
   }
 
+  /**
+   * Record that the round is final: every landed buy is in `spent` and nothing will change again.
+   *
+   * The server calls this once, after its last clean settlement pass past `booksCloseAt`, before it
+   * closes the room's sockets. Idempotent — the first stamp wins, so a retried teardown after a
+   * failed socket close cannot move the moment. It is what `GET /coins/:coin/rankings` reads back
+   * as `settledAt`/`final`.
+   */
+  async markSettled(at: number): Promise<void> {
+    await this.pool.query(`update rounds set settled_at = $1 where id = $2 and settled_at is null`, [
+      at,
+      this.id,
+    ]);
+  }
+
 }
 
 /**