@flayerlabs/gamemode-gate 0.1.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@flayerlabs/gamemode-gate",
+  "version": "0.1.0",
+  "description": "Server-authoritative rooms, economy, admission and registry for Flaunch Game Modes",
+  "license": "MIT",
+  "author": "Flayer Labs",
+  "homepage": "https://github.com/flayerlabs/gamemode-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flayerlabs/gamemode-sdk.git",
+    "directory": "packages/gate"
+  },
+  "bugs": {
+    "url": "https://github.com/flayerlabs/gamemode-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "db": "docker run -d --rm --name gamemode-pg -e POSTGRES_PASSWORD=gamemode -e POSTGRES_DB=gamemode -p 55439:5432 postgres:16-alpine"
+  },
+  "dependencies": {
+    "@flayerlabs/gamemode-spec": "^0.1.0",
+    "@fastify/cors": "^11.3.0",
+    "@fastify/websocket": "^11.3.0",
+    "@types/node": "^22.10.2",
+    "@types/pg": "^8.21.0",
+    "fastify": "^5.11.3",
+    "pg": "^8.23.0",
+    "viem": "^2.21.54"
+  }
+}

package/src/chain/discover.ts

@@ -0,0 +1,243 @@
+import { encodeAbiParameters, keccak256, parseAbi, type PublicClient } from 'viem';
+
+/**
+ * All this needs of a client: the ability to read a contract.
+ *
+ * Naming the one method rather than taking a whole `PublicClient` also sidesteps viem's chain
+ * generics, which make a client built for one chain structurally incompatible with the general
+ * type over unrelated methods like `getBlock`.
+ */
+export type ChainReader = Pick<PublicClient, 'readContract'>;
+
+/**
+ * Asking the chain whether a coin is really a game launch, and on what terms.
+ *
+ * This is what makes rooms exist because a LAUNCH exists rather than because somebody asked for
+ * one. A room used to be minted on demand, which on a public URL means anyone can invent as many
+ * as they like.
+ *
+ * The authorisation is already on chain: a launch that wants a game names its signer in the
+ * launch's own gate parameters, and that is public state the creator paid to write and nobody else
+ * can forge. So adoption needs no API key and no allowlist — anyone may ask, and the chain decides.
+ * That single property is what makes third-party games permissionless.
+ */
+
+const poolKeyComponents = [
+  { name: 'currency0', type: 'address' },
+  { name: 'currency1', type: 'address' },
+  { name: 'fee', type: 'uint24' },
+  { name: 'tickSpacing', type: 'int24' },
+  { name: 'hooks', type: 'address' },
+] as const;
+
+export const positionManagerAbi = [
+  {
+    type: 'function',
+    name: 'poolKey',
+    stateMutability: 'view',
+    inputs: [{ name: '_token', type: 'address' }],
+    outputs: [{ name: '', type: 'tuple', components: poolKeyComponents }],
+  },
+  // The scheduled open of the buy window; 0 once the pool is tradeable.
+  ...parseAbi(['function flaunchesAt(bytes32 _poolId) view returns (uint256)']),
+] as const;
+
+export const spendGatedAbi = parseAbi([
+  // Four fields. Decoding a four-word return against a shorter ABI is how a check quietly reads the
+  // wrong value, so this must match the DEPLOYED calculator rather than the newest source.
+  'function spendGateSettings(bytes32 _poolId) view returns (bool enabled, uint256 walletCapWei, address settler, uint256 endsAt)',
+  'function trustedPoolKeySigner(bytes32 _poolId) view returns (address signer, bool enabled)',
+]);
+
+const erc20 = parseAbi(['function name() view returns (string)', 'function symbol() view returns (string)']);
+
+export interface PoolKey {
+  currency0: `0x${string}`;
+  currency1: `0x${string}`;
+  fee: number;
+  tickSpacing: number;
+  hooks: `0x${string}`;
+}
+
+export interface Launch {
+  coinAddress: `0x${string}`;
+  poolId: `0x${string}`;
+  poolKey: PoolKey;
+  /** When buying opens, in epoch ms. */
+  opensAt: number;
+  /** When the gate stops enforcing on chain, in epoch ms. */
+  closesAt: number;
+  walletCapWei: bigint;
+  signer: `0x${string}`;
+  name: string;
+  symbol: string;
+  imageUrl?: string | null;
+}
+
+/**
+ * A refusal, with the one distinction that matters.
+ *
+ * `retryable` separates "the chain has not caught up yet" from "this coin is not a game launch".
+ * Collapsing the two once cost a real launch its whole window: a coin page loaded the instant a
+ * launch was submitted, asked before the pool was readable, was told "not a game launch", and both
+ * ends cached that answer for thirty seconds each — against a ninety-second window.
+ */
+export interface Refused {
+  ok: false;
+  code: string;
+  retryable: boolean;
+}
+
+export type LaunchCheck = ({ ok: true } & Launch) | Refused;
+
+export interface Deployment {
+  positionManager: `0x${string}`;
+  spendGatedCalculator: `0x${string}`;
+  /** The signer this gate holds. A launch naming anyone else is not ours to run. */
+  signer: `0x${string}`;
+}
+
+export function poolIdOf(key: PoolKey): `0x${string}` {
+  return keccak256(
+    encodeAbiParameters(
+      [{ type: 'address' }, { type: 'address' }, { type: 'uint24' }, { type: 'int24' }, { type: 'address' }],
+      [key.currency0, key.currency1, key.fee, key.tickSpacing, key.hooks],
+    ),
+  );
+}
+
+const refuse = (code: string, retryable: boolean): Refused => ({ ok: false, code, retryable });
+
+/**
+ * Verify a coin, from the chain.
+ *
+ * Every read is wrapped, because an RPC failure is not a statement about the token. Treating one as
+ * "not a game launch" is exactly the mistake described on {@link Refused}.
+ */
+export async function verifyLaunch(
+  client: ChainReader,
+  deployment: Deployment,
+  memecoin: `0x${string}`,
+): Promise<LaunchCheck> {
+  let poolKey: PoolKey;
+  try {
+    poolKey = (await client.readContract({
+      address: deployment.positionManager,
+      abi: positionManagerAbi,
+      functionName: 'poolKey',
+      args: [memecoin],
+    })) as PoolKey;
+  } catch {
+    return refuse('launch.unreadable', true);
+  }
+
+  // A coin the protocol has never heard of returns an empty key rather than throwing.
+  if (!poolKey || poolKey.hooks === '0x0000000000000000000000000000000000000000') {
+    return refuse('launch.not_flaunched', true);
+  }
+
+  const poolId = poolIdOf(poolKey);
+
+  let settings: readonly [boolean, bigint, `0x${string}`, bigint];
+  let trusted: readonly [`0x${string}`, boolean];
+  let flaunchesAt: bigint;
+  try {
+    [settings, trusted, flaunchesAt] = (await Promise.all([
+      client.readContract({
+        address: deployment.spendGatedCalculator,
+        abi: spendGatedAbi,
+        functionName: 'spendGateSettings',
+        args: [poolId],
+      }),
+      client.readContract({
+        address: deployment.spendGatedCalculator,
+        abi: spendGatedAbi,
+        functionName: 'trustedPoolKeySigner',
+        args: [poolId],
+      }),
+      client.readContract({
+        address: deployment.positionManager,
+        abi: positionManagerAbi,
+        functionName: 'flaunchesAt',
+        args: [poolId],
+      }),
+    ])) as [typeof settings, typeof trusted, bigint];
+  } catch {
+    return refuse('launch.unreadable', true);
+  }
+
+  const [enabled, walletCapWei, , endsAt] = settings;
+  const [signer, signerEnabled] = trusted;
+
+  if (!enabled) return refuse('launch.not_a_game', false);
+  // Not ours to run. Permanent: another gate holds that key, and no amount of waiting changes it.
+  if (!signerEnabled || signer.toLowerCase() !== deployment.signer.toLowerCase()) {
+    return refuse('launch.another_signer', false);
+  }
+  if (walletCapWei <= 0n) return refuse('launch.no_spending_cap', false);
+
+  const opensAt = Number(flaunchesAt) * 1000;
+  const closesAt = Number(endsAt) * 1000;
+  if (closesAt <= Date.now()) return refuse('launch.already_over', false);
+
+  let name = '';
+  let symbol = '';
+  try {
+    [name, symbol] = (await Promise.all([
+      client.readContract({ address: memecoin, abi: erc20, functionName: 'name' }),
+      client.readContract({ address: memecoin, abi: erc20, functionName: 'symbol' }),
+    ])) as [string, string];
+  } catch {
+    // Cosmetic. A coin with an unreadable name is still a valid launch, and refusing one over a
+    // display string would be refusing a round for no reason anyone could act on.
+  }
+
+  return { ok: true, coinAddress: memecoin, poolId, poolKey, opensAt, closesAt, walletCapWei, signer, name, symbol };
+}
+
+/**
+ * Verification with a memory, because every coin-page view asks.
+ *
+ * Unmemoised, each call costs five chain reads against one endpoint from one address — which is a
+ * free denial-of-service lever, and public endpoints rate-limit long before a launch does.
+ *
+ * A positive verdict is cached until the window closes, because a launch that qualifies cannot
+ * un-qualify while it is open. A retryable refusal is cached only briefly, and a permanent one for
+ * longer — the whole point of the distinction is that "not yet" must not be remembered like "no".
+ */
+export class Discovery {
+  private readonly verdicts = new Map<string, { verdict: LaunchCheck; until: number }>();
+  private readonly inFlight = new Map<string, Promise<LaunchCheck>>();
+
+  constructor(
+    private readonly client: ChainReader,
+    private readonly deployment: Deployment,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  async verify(memecoin: `0x${string}`): Promise<LaunchCheck> {
+    const key = memecoin.toLowerCase();
+    const cached = this.verdicts.get(key);
+    if (cached && cached.until > this.now()) return cached.verdict;
+
+    // One flight per coin: a burst of coin-page views is one caller as far as the chain is
+    // concerned, and without this the first launch of the day is its own thundering herd.
+    const existing = this.inFlight.get(key);
+    if (existing) return existing;
+
+    const flight = verifyLaunch(this.client, this.deployment, memecoin)
+      .then((verdict) => {
+        this.verdicts.set(key, { verdict, until: this.now() + this.holdFor(verdict) });
+        return verdict;
+      })
+      .finally(() => this.inFlight.delete(key));
+
+    this.inFlight.set(key, flight);
+    return flight;
+  }
+
+  private holdFor(verdict: LaunchCheck): number {
+    if (verdict.ok) return Math.max(0, verdict.closesAt - this.now());
+    return verdict.retryable ? 3_000 : 60_000;
+  }
+}

package/src/chain/signer.ts

@@ -0,0 +1,118 @@
+import { encodeAbiParameters, hashTypedData, zeroAddress } from 'viem';
+import { privateKeyToAccount, type PrivateKeyAccount } from 'viem/accounts';
+import { spendAuthorisationTypedData } from '@flayerlabs/gamemode-spec/embed';
+
+/**
+ * Issues the signed authorizations SpendGatedSignerFeeCalculator.trackSwap verifies.
+ *
+ * EIP-712, over the `SpendAuthorization` struct the calculator declares. It used to be an
+ * EIP-191 personal-sign over `keccak256(abi.encodePacked(...))`, which committed to the five
+ * fields and nothing else — no chain id, no verifying contract. An audit flagged that as the
+ * same defect already raised against the parent calculator (M-6, remediated there in the
+ * EIP-712 PR but never ported to this fork): the protocol deploys deterministically across
+ * chains, so the same poolId genuinely recurs, and one signing key shared between two
+ * environments made an authorization issued for one valid on the other. The domain closes it.
+ *
+ * The digest MUST match `hashSpendAuthorization` on the calculator exactly. That function is
+ * public for this reason — a domain drift is otherwise a silent `InvalidSigner` at swap time
+ * rather than a loud failure at signing time. Parity is pinned by test/signer-parity.test.ts
+ * against vectors generated with Foundry.
+ */
+export interface SignedPayload {
+  buyer: `0x${string}`;
+  poolId: `0x${string}`;
+  deadline: bigint;
+  maxSpendWei: bigint;
+  nonce: bigint;
+  signature: `0x${string}`;
+  signer: `0x${string}`;
+}
+
+export class PayloadSigner {
+  private readonly account: PrivateKeyAccount;
+
+  /**
+   * @param verifyingContract The calculator that will validate these signatures. Binding it is
+   * half the point of the domain. Unit tests may use a placeholder because they have no deployment.
+   * A production operator must pass the calculator that chain discovery also verifies.
+   */
+  constructor(
+    privateKey: `0x${string}`,
+    private readonly chainId: number,
+    private readonly verifyingContract: `0x${string}`,
+  ) {
+    this.account = privateKeyToAccount(privateKey);
+  }
+
+  get address(): `0x${string}` {
+    return this.account.address;
+  }
+
+  /** The digest the calculator reconstructs; mirrors its `hashSpendAuthorization`. */
+  messageHash(
+    buyer: `0x${string}`,
+    poolId: `0x${string}`,
+    deadline: bigint,
+    maxSpendWei: bigint,
+    nonce: bigint,
+  ): `0x${string}` {
+    return hashTypedData(
+      spendAuthorisationTypedData(
+        { buyer, poolId, deadline, maxSpendWei, nonce },
+        this.chainId,
+        this.verifyingContract,
+      ),
+    );
+  }
+
+  async sign(
+    buyer: `0x${string}`,
+    poolId: `0x${string}`,
+    deadline: bigint,
+    maxSpendWei: bigint,
+    nonce: bigint,
+  ): Promise<SignedPayload> {
+    const signature = await this.account.signTypedData(
+      spendAuthorisationTypedData(
+        { buyer, poolId, deadline, maxSpendWei, nonce },
+        this.chainId,
+        this.verifyingContract,
+      ),
+    );
+    return { buyer, poolId, deadline, maxSpendWei, nonce, signature, signer: this.account.address };
+  }
+}
+
+/**
+ * Encodes a signed payload as the hookData the swap must carry:
+ * `abi.encode(address referrer, SignedMessage{buyer, poolId, deadline, maxSpendWei, nonce, signature})`
+ */
+export function encodeHookData(payload: SignedPayload): `0x${string}` {
+  return encodeAbiParameters(
+    [
+      { type: 'address' },
+      {
+        type: 'tuple',
+        components: [
+          { name: 'buyer', type: 'address' },
+          { name: 'poolId', type: 'bytes32' },
+          { name: 'deadline', type: 'uint256' },
+          { name: 'maxSpendWei', type: 'uint256' },
+          { name: 'nonce', type: 'uint256' },
+          { name: 'signature', type: 'bytes' },
+        ],
+      },
+    ],
+    [
+      zeroAddress,
+      {
+        buyer: payload.buyer,
+        poolId: payload.poolId,
+        deadline: payload.deadline,
+        maxSpendWei: payload.maxSpendWei,
+        nonce: payload.nonce,
+        signature: payload.signature,
+      },
+    ],
+  );
+}

package/src/claims.ts

@@ -0,0 +1,140 @@
+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 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.
+ *
+ * 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.
+ */
+
+/** 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. */
+export function isClaimRequestId(value: unknown): value is string {
+  return typeof value === 'string' && REQUEST_ID.test(value);
+}
+
+/** The signed message carries uint256, while JavaScript's bigint has no upper bound. */
+export function isClaimAmount(value: unknown): value is bigint {
+  return typeof value === 'bigint' && value > 0n && value <= maxUint256;
+}
+
+export type Authorisation =
+  | { ok: true; payload: SignedPayload }
+  | { ok: false; refuse: string };
+
+export class Claims {
+  constructor(
+    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.
+   *
+   * 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.
+   */
+  async authorise(roundId: string, player: PlayerId, upToWei: 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' };
+
+    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' };
+
+    // 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 };
+
+    // 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);
+  }
+
+  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;
+    }
+  }
+
+  /** Give back every authorisation that expired unspent. */
+  releaseExpired(): Promise<BalanceKey[]> {
+    return this.ledger.releaseExpired(Math.floor(this.now() / 1000));
+  }
+
+  /** What this player could spend right now. */
+  availableWei(roundId: string, player: PlayerId): Promise<bigint> {
+    return this.ledger.availableWei(roundId, player);
+  }
+
+  /** Full authoritative balance for live snapshots. */
+  economyBalance(roundId: string, player: PlayerId): Promise<EconomyBalance> {
+    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,
+  };
+}