@flayerlabs/gamemode-gate 0.5.6 → 0.7.0

package/src/claims.ts

@@ -2,26 +2,23 @@ import type { Pool } from 'pg';
 import type { PlayerId } from '@flayerlabs/gamemode-spec';
 import type { EconomyBalance } from '@flayerlabs/gamemode-spec/live';
 import { maxUint256 } from 'viem';
-import { Ledger, type BalanceKey, type Claim } from './ledger.js';
+import { Ledger, type Authorisation as StoredAuthorisation } from './ledger.js';
 import type { PayloadSigner, SignedPayload } from './chain/signer.js';
 
 /**
  * Turning points into something a player can actually spend.
  *
  * Two parties have to agree before a buy can happen, and they check different things. The ledger
- * knows what this player earned and what they have already been authorised for. The signer knows
- * whether it is willing to vouch for this pool at all. Only when both say yes does an
- * authorisation exist.
+ * knows what this player earned and what the chain says they have spent. The signer knows whether
+ * it is willing to vouch for this pool at all. Only when both say yes does an authorisation exist.
  *
- * The order matters and is not interchangeable: the hold is recorded first, then signed. A
- * signature that exists without a hold is spending nobody is tracking; a hold without a signature
- * is a refund waiting to happen. Only one of those costs money.
+ * What gets signed is a ceiling, not a purchase: the most this wallet may ever have spent on the
+ * pool. The calculator compares it against its own running total, so the gate reserves nothing
+ * and a signature that is never used costs nobody anything. The one thing this file must get
+ * right is idempotency — a retried request must receive the same bytes — and that is a primary
+ * key, not a lock.
  */
 
-/** How long an authorisation stays valid. Long enough to approve in a wallet, short enough that an
- *  abandoned one does not sit around spendable. */
-export const CLAIM_AUTHORIZATION_TTL_MS = 5 * 60_000;
-const DEADLINE_SECONDS = CLAIM_AUTHORIZATION_TTL_MS / 1_000;
 const REQUEST_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 
 /** Request ids cross an unauthenticated parser before they reach Postgres, so bound them here too. */
@@ -35,7 +32,7 @@ export function isClaimAmount(value: unknown): value is bigint {
 }
 
 export type Authorisation =
-  | { ok: true; payload: SignedPayload }
+  | { ok: true; payload: SignedPayload; /** Exact-in amount for this buy, clamped to what was available. */ spend: bigint }
   | { ok: false; refuse: string };
 
 export class Claims {
@@ -43,76 +40,68 @@ export class Claims {
     private readonly pool: Pool,
     private readonly ledger: Ledger,
     private readonly signer: PayloadSigner,
-    /** Called when a hold could neither be signed nor released, and needs a human. */
-    private readonly onStrandedHold?: (nonce: bigint, error: unknown) => void,
     /** An internal seam for exact window-boundary tests. Production uses the process clock. */
     private readonly now: () => number = Date.now,
   ) {}
 
   /**
-   * Authorise a player to spend up to `upToWei`, or explain why not.
+   * Authorise a player to spend up to `spendWei`, or explain why not.
    *
-   * The ledger's ceiling is a conservative mirror of the chain's: the contract tracks
-   * `walletSpentWei` per pool per wallet and enforces it whatever we believe. Being ahead of the
-   * chain is safe — we simply authorise less than we could. Being behind it would mean issuing a
-   * signature that reverts at the swap, which to a player is indistinguishable from being robbed.
+   * 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 ceiling in the signature is the
+   * same either way — it is what they have earned, not what they asked for.
+   *
+   * The ledger's view of spend is a conservative mirror of the chain's. Being behind it means
+   * signing a ceiling the calculator will refuse at the swap, which to a player is
+   * indistinguishable from being robbed; settlement keeps the gap to one reconciliation pass.
    */
-  async authorise(roundId: string, player: PlayerId, upToWei: bigint, requestId: string): Promise<Authorisation> {
+  async authorise(roundId: string, player: PlayerId, spendWei: bigint, requestId: string): Promise<Authorisation> {
     if (!isClaimRequestId(requestId)) return { ok: false, refuse: 'claim.request_invalid' };
-    if (!isClaimAmount(upToWei)) return { ok: false, refuse: 'claim.amount_invalid' };
+    if (!isClaimAmount(spendWei)) return { ok: false, refuse: 'claim.amount_invalid' };
 
     const round = await this.pool.query<{ pool_id: string }>(`select pool_id from rounds where id = $1`, [roundId]);
     const row = round.rows[0];
     if (!row) return { ok: false, refuse: 'claim.no_such_round' };
+    const poolId = row.pool_id as `0x${string}`;
 
-    // The deadline is decided before the hold so both agree on when it stops being spendable.
-    const now = this.now();
-    const deadline = BigInt(Math.floor(now / 1000) + DEADLINE_SECONDS);
-    // Idempotency and the clock are decided under the same player lock. If an accepted request is
-    // still committing at the buzzer, a retry waits for it and recovers it rather than observing
-    // no row outside the transaction and being refused as a new, late request.
-    const held = await this.ledger.claim(roundId, player, upToWei, requestId, deadline, now);
-    if (!held.ok) return { ok: false, refuse: held.refuse };
+    // An existing request deliberately wins over the clock and the current balance: it was issued
+    // under the earlier call's window, and a retry must get the same answer.
+    const existing = await this.ledger.findAuthorisation(roundId, player, requestId);
+    if (existing) return this.answer(poolId, existing, spendWei);
 
-    // Another replica may have completed the request while this one waited for the balance lock.
-    if (held.claim.signature && held.claim.signer) {
-      return { ok: true, payload: payload(row.pool_id, held.claim) };
-    }
-    if (held.claim.status === 'released') return { ok: false, refuse: 'claim.request_released' };
-    return this.finish(row.pool_id, held.claim);
-  }
+    const quote = await this.ledger.quote(roundId, player, this.now());
+    if (!quote.ok) return { ok: false, refuse: quote.refuse };
 
-  private async finish(poolId: string, claim: Claim): Promise<Authorisation> {
-    try {
-      const candidate = await this.signer.sign(
-        claim.player as `0x${string}`,
-        poolId as `0x${string}`,
-        claim.deadline,
-        claim.wei,
-        claim.nonce,
-      );
-      // Never return bytes that were not durably recorded. Concurrent signers both return the one
-      // stored winner, so retries stay byte-identical even if an implementation signs randomly.
-      const completed = await this.ledger.completeClaim(claim.nonce, candidate.signature, candidate.signer);
-      if (!completed?.signature || !completed.signer) throw new Error('claim could not be completed');
-      return { ok: true, payload: payload(poolId, completed) };
-    } catch (error) {
-      // The hold was taken and nothing will ever be spent against it, so it goes back. Without
-      // this, a signer outage quietly eats a player's allowance for the rest of the round.
-      //
-      // If the release ALSO fails, the original error still wins. Replacing it with a database
-      // error would hide the reason and leave the nonce nowhere in the logs — so it is named here,
-      // because that number is what a person needs to give the allowance back by hand.
-      await this.ledger.releaseUnsigned(claim.nonce).catch((releaseError: unknown) => {
-        this.onStrandedHold?.(claim.nonce, releaseError);
-      });
-      throw error;
-    }
+    const spend = spendWei < quote.available ? spendWei : quote.available;
+    const signed = await this.signer.sign(player as `0x${string}`, poolId, quote.deadlineSeconds, quote.ceiling);
+    const stored = await this.ledger.storeAuthorisation(roundId, {
+      player,
+      requestId,
+      requestedWei: spendWei,
+      spendCeilingWei: signed.spendCeilingWei,
+      spendWei: spend,
+      deadline: signed.deadline,
+      signature: signed.signature,
+      signer: signed.signer,
+    });
+    return this.answer(poolId, stored, spendWei);
   }
 
-  /** Give back every authorisation that expired unspent. */
-  releaseExpired(): Promise<BalanceKey[]> {
-    return this.ledger.releaseExpired(Math.floor(this.now() / 1000));
+  private answer(poolId: `0x${string}`, stored: StoredAuthorisation, requestedWei: bigint): Authorisation {
+    if (stored.requestedWei !== requestedWei) return { ok: false, refuse: 'claim.request_mismatch' };
+    return {
+      ok: true,
+      payload: {
+        buyer: stored.player as `0x${string}`,
+        poolId,
+        deadline: stored.deadline,
+        spendCeilingWei: stored.spendCeilingWei,
+        signature: stored.signature,
+        signer: stored.signer,
+      },
+      spend: stored.spendWei,
+    };
   }
 
   /** What this player could spend right now. */
@@ -125,16 +114,3 @@ export class Claims {
     return this.ledger.economyBalance(roundId, player);
   }
 }
-
-function payload(poolId: string, claim: Claim): SignedPayload {
-  if (!claim.signature || !claim.signer) throw new Error('claim is not signed');
-  return {
-    buyer: claim.player as `0x${string}`,
-    poolId: poolId as `0x${string}`,
-    deadline: claim.deadline,
-    maxSpendWei: claim.wei,
-    nonce: claim.nonce,
-    signature: claim.signature,
-    signer: claim.signer,
-  };
-}

package/src/demo.ts

@@ -62,7 +62,7 @@ export interface Demo {
   /** The throwaway wallet standing in for the player's real one. */
   walletAddress: `0x${string}`;
   /** Everything the fake wallet was asked to buy, in order. Empty until somebody buys. */
-  purchases: { maxSpendWei: string; at: number }[];
+  purchases: { spend: string; at: number }[];
   pool: pg.Pool;
 }
 
@@ -160,7 +160,7 @@ export async function createDemoGate<Config, State, Event, Action, PublicView, P
   });
 
   const wallet = privateKeyToAccount(DEMO_WALLET_KEY);
-  const purchases: { maxSpendWei: string; at: number }[] = [];
+  const purchases: { spend: string; at: number }[] = [];
 
   // Standing in for the page a game is embedded in. In production this is flaunch.gg holding the
   // player's real wallet; here the signature is real and the purchase is only written down.
@@ -169,9 +169,9 @@ export async function createDemoGate<Config, State, Event, Action, PublicView, P
     signature: await wallet.signMessage({ message: (request.body as { message: string }).message }),
   }));
   app.post('/dev/wallet/buy', (request) => {
-    const { maxSpendWei } = request.body as { maxSpendWei: string };
-    purchases.push({ maxSpendWei, at: Date.now() });
-    return { spent: maxSpendWei };
+    const { spend } = request.body as { spend: string };
+    purchases.push({ spend, at: Date.now() });
+    return { spent: spend };
   });
 
   return { app, roundId, opensAt, walletAddress: wallet.address, purchases, pool };

package/src/index.ts

@@ -23,12 +23,11 @@ export { createTurnstileAdmit } from './turnstile.js';
 export type { TurnstileAdmitOptions } from './turnstile.js';
 
 export { Ledger } from './ledger.js';
-export type { BalanceKey, Claim, ClaimResult } from './ledger.js';
-export { CLAIM_AUTHORIZATION_TTL_MS } from './claims.js';
+export type { Authorisation, Quote } from './ledger.js';
 export { PayloadSigner, encodeHookData } from './chain/signer.js';
 export type { SignedPayload } from './chain/signer.js';
-export { Discovery, poolIdOf, verifyLaunch } from './chain/discover.js';
-export type { ChainReader, Deployment, Launch, LaunchCheck, PoolKey, Refused } from './chain/discover.js';
+export { Discovery, WiringCache, poolIdOf, resolvePositionManager, verifyLaunch } from './chain/discover.js';
+export type { ChainReader, Deployment, Launch, LaunchCheck, PoolKey, Refused, WiringCheck } from './chain/discover.js';
 export { Settlement } from './settlement.js';
 export { Standings } from './standings.js';
 export { ETH_DECIMALS, resolveEconomy, unitsPerToken } from './economy.js';
@@ -66,12 +65,13 @@ export type { VerifiedPlayerJoin, VerifyPlayerJoinTicketOptions } from './player
  */
 export { startGate, resolveGateEnv } from './main.js';
 export type { ResolvedGateConfig, SpendTokenPricing, StartedGate, StartGateOverrides } from './main.js';
-export type { GateAnnouncement, ServedGateAnnouncement } from './server.js';
+export type { GateAnnouncement, PositionManagerPolicy, ServedGateAnnouncement } from './server.js';
 export { GATE_MARKER, GATE_VERSION } from './version.js';
 export { NotSignedIn } from './sessions.js';
 export { DEPLOYMENTS, PAIRED_DEPLOYMENTS, deploymentFor } from './chain/chains.js';
 export type { FlaunchVariant, GateDeployment } from './chain/chains.js';
-export { POSITION_MANAGER_ROLE, assertSecureConfig } from './chain/secure.js';
+export { POSITION_MANAGER_ROLE, assertSecureConfig, checkPositionManagerWiring } from './chain/secure.js';
+export type { PositionManagerWiring } from './chain/secure.js';
 export { RegistryPrices, minimumWalletCap, withHeadroom } from './chain/registry-prices.js';
 export type { AnnounceOptions, RegistryPricesOptions, RegistryQuote, RegistryReader } from './chain/registry-prices.js';