@flayerlabs/gamemode-gate 0.1.0

package/src/demo.ts

@@ -0,0 +1,149 @@
+import pg from 'pg';
+import { privateKeyToAccount } from 'viem/accounts';
+import type { FastifyInstance } from 'fastify';
+import type { GameModule } from '@flayerlabs/gamemode-spec';
+import { createGate } from './server.js';
+import { Room } from './room.js';
+import { Ledger } from './ledger.js';
+import { Claims } from './claims.js';
+import { Sessions } from './sessions.js';
+import { PayloadSigner } from './chain/signer.js';
+import { migrate } from './store.js';
+import { resolveEconomy } from './economy.js';
+
+/**
+ * A whole gate on a laptop, with the chain taken out.
+ *
+ * Real gate, real database, real socket, real EIP-712 signatures. What is faked is the one thing a
+ * laptop cannot provide: a chain. The wallet is a throwaway key and the purchase is recorded rather
+ * than submitted, so every step up to and including the signature is the genuine one — which is
+ * what makes this a playtest rather than a mock-up.
+ *
+ * This lived inside the quiz example, where no other game could reach it. Nothing about it was ever
+ * quiz-specific.
+ *
+ * Not for production, and it refuses to pretend otherwise: the signing key is a constant, the pool
+ * id is invented, and no chain is ever consulted.
+ */
+
+/** A key nobody should ever fund. Constant so a restart does not change who you are. */
+const DEMO_SIGNING_KEY = `0x${'11'.repeat(32)}` as const;
+const DEMO_WALLET_KEY = `0x${'77'.repeat(32)}` as const;
+const DEMO_POOL_ID = `0x${'ab'.repeat(32)}` as const;
+const DEMO_CALCULATOR = `0x${'cd'.repeat(20)}` as const;
+
+export interface DemoOptions<Config, State, Event, Action, PublicView, PlayerView> {
+  game: GameModule<Config, State, Event, Action, PublicView, PlayerView>;
+  config: Config;
+  /** Default `postgres://postgres:gamemode@127.0.0.1:55439/gamemode`, or `DATABASE_URL`. */
+  databaseUrl?: string;
+  /** How long before the round opens. Short, because someone is waiting. */
+  lobbyMs?: number;
+  roundMs?: number;
+  /** The cap a wallet may spend, as a real launch would set on chain. Default 0.025 ETH. */
+  walletCapWei?: bigint;
+  pointsPerDollar?: number;
+  usdPerEth?: number;
+  roundId?: string;
+  /** Exact origin where this demo gate will listen. Default `http://127.0.0.1:4000`. */
+  gateOrigin?: string;
+}
+
+export interface Demo {
+  app: FastifyInstance;
+  roundId: string;
+  opensAt: number;
+  /** 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 }[];
+  pool: pg.Pool;
+}
+
+const ETH = 1_000_000_000_000_000_000n;
+
+/**
+ * Boot a gate, a round and a stand-in wallet.
+ *
+ * The caller owns serving their own game's files and calling `listen`, because how a game is built
+ * is the one part of this that genuinely differs between games.
+ */
+export async function createDemoGate<Config, State, Event, Action, PublicView, PlayerView>(
+  options: DemoOptions<Config, State, Event, Action, PublicView, PlayerView>,
+): Promise<Demo> {
+  const {
+    game,
+    config,
+    databaseUrl = process.env.DATABASE_URL ?? 'postgres://postgres:gamemode@127.0.0.1:55439/gamemode',
+    lobbyMs = 8_000,
+    roundMs = 10 * 60_000,
+    walletCapWei = ETH / 40n,
+    pointsPerDollar = 100,
+    usdPerEth = 3_000,
+    roundId = 'dev',
+    gateOrigin = 'http://127.0.0.1:4000',
+  } = options;
+
+  // The same check the real gate runs at boot. A demo that silently used an impossible economy
+  // would teach a builder that their numbers work when they do not.
+  const economy = resolveEconomy({
+    maxPointsPerPlayer: game.rewardBounds(config).maxPointsPerPlayer,
+    walletCapWei,
+    pointsPerDollar,
+    usdPerEth,
+  });
+  if (!economy.ok) {
+    throw new Error(
+      `That economy does not work: ${economy.problem}. Try ${economy.suggestedPointsPerDollar} points per dollar.`,
+    );
+  }
+
+  const pool = new pg.Pool({ connectionString: databaseUrl });
+  await migrate(pool);
+  // Same round id every run, so a reload is the same game rather than an accumulating pile.
+  await pool.query('delete from rounds where id = $1', [roundId]);
+
+  const opensAt = Date.now() + lobbyMs;
+  await Room.create(pool, game, {
+    id: roundId,
+    config,
+    seed: Math.floor(Math.random() * 1_000_000),
+    window: { opensAt, closesAt: opensAt + roundMs },
+    weiPerPoint: economy.economy.weiPerPoint,
+    walletCapWei,
+    poolId: DEMO_POOL_ID,
+  });
+
+  const app = createGate({
+    pool,
+    game,
+    config,
+    pointsPerDollar,
+    usdPerEth,
+    sessions: new Sessions(
+      process.env.SESSION_SECRET ?? 'dev-secret-that-is-long-enough-to-pass',
+      'localhost',
+      gateOrigin,
+    ),
+    claims: new Claims(pool, new Ledger(pool), new PayloadSigner(DEMO_SIGNING_KEY, 8453, DEMO_CALCULATOR)),
+    // Anything, because this is a laptop and the browser is on some port nobody can predict.
+    allowedOrigins: true as unknown as string[],
+  });
+
+  const wallet = privateKeyToAccount(DEMO_WALLET_KEY);
+  const purchases: { maxSpendWei: 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.
+  app.get('/dev/wallet', () => ({ address: wallet.address }));
+  app.post('/dev/wallet/sign', async (request) => ({
+    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 { spentWei: maxSpendWei };
+  });
+
+  return { app, roundId, opensAt, walletAddress: wallet.address, purchases, pool };
+}

package/src/economy.ts

@@ -0,0 +1,126 @@
+/**
+ * Turning points into money, and refusing a round whose sums do not work.
+ *
+ * This file exists because of a real incident. A gate ran with a per-wallet cap twenty times the
+ * value its own deployment guide prescribed, and over 48 hours roughly 2 ETH went to wallets whose
+ * scores were in the bot range. Nothing was broken: every detector worked. One number in an
+ * environment variable was wrong, and no code was in a position to notice.
+ *
+ * So the arithmetic lives here, runs at round creation with the actual values, and refuses. A
+ * creator sets one human number — how many points a dollar is worth — and never sees wei.
+ */
+
+/** 1 ETH in wei. */
+const WEI_PER_ETH = 1_000_000_000_000_000_000n;
+
+export interface EconomyInput {
+  /** The most one player can earn, declared by the game itself via `rewardBounds`. */
+  maxPointsPerPlayer: number;
+  /** The pool's on-chain per-wallet ceiling. The chain enforces this whatever we do. */
+  walletCapWei: bigint;
+  /** The creator's one knob. 100 means 100 points is worth a dollar. */
+  pointsPerDollar: number;
+  usdPerEth: number;
+}
+
+export interface Economy {
+  weiPerPoint: bigint;
+  /** What a flawless round pays. Always at or under `walletCapWei`, or this would not exist. */
+  maxPayoutWei: bigint;
+}
+
+export type EconomyResult =
+  | { ok: true; economy: Economy }
+  | { ok: false; problem: string; suggestedPointsPerDollar: number };
+
+/**
+ * Resolve the rate for one round, or refuse with the number that fixes it.
+ *
+ * The rule is single and total: **a flawless round must fit under the wallet cap.** If it does not,
+ * a player earns points the chain will not let them spend — the game shows a reward and the buy
+ * refuses it, which is the worst failure available because it looks like theft.
+ *
+ * Refusals carry the corrected `pointsPerDollar` rather than a diagnosis. An operator reading
+ * "raise it to 250" fixes this in one step; an operator reading "the cap binds below the ceiling"
+ * goes and reads this file.
+ */
+export function resolveEconomy(input: EconomyInput): EconomyResult {
+  const { maxPointsPerPlayer, walletCapWei, pointsPerDollar, usdPerEth } = input;
+
+  if (!Number.isFinite(pointsPerDollar) || pointsPerDollar <= 0) {
+    return { ok: false, problem: 'points per dollar must be a positive number', suggestedPointsPerDollar: 100 };
+  }
+  if (!Number.isFinite(usdPerEth) || usdPerEth <= 0) {
+    return { ok: false, problem: 'the ETH price must be a positive number', suggestedPointsPerDollar: pointsPerDollar };
+  }
+  if (!Number.isFinite(maxPointsPerPlayer) || maxPointsPerPlayer <= 0) {
+    return {
+      ok: false,
+      problem: 'the game says a player can earn at most 0 points, so there is nothing to pay',
+      suggestedPointsPerDollar: pointsPerDollar,
+    };
+  }
+  if (walletCapWei <= 0n) {
+    return {
+      ok: false,
+      problem: 'this launch has no per-wallet spending cap, so nothing can be authorised',
+      suggestedPointsPerDollar: pointsPerDollar,
+    };
+  }
+
+  // How many points one ETH buys. Checked before it becomes a divisor: `pointsPerDollar` is
+  // guarded as positive above, but a small enough positive value still rounds this product to
+  // zero — and dividing by it threw `Division by zero` out of the one function whose entire job is
+  // to refuse a bad economy with a sentence an operator can act on.
+  const pointsPerEth = Math.round(usdPerEth * pointsPerDollar);
+  if (pointsPerEth <= 0) {
+    return {
+      ok: false,
+      problem: 'one point would be worth more than a whole ETH, which cannot be what was meant',
+      suggestedPointsPerDollar: minimumPointsPerDollar(input),
+    };
+  }
+
+  const weiPerPoint = WEI_PER_ETH / BigInt(pointsPerEth);
+  if (weiPerPoint <= 0n) {
+    return {
+      ok: false,
+      problem: 'each point would be worth less than the smallest unit of ETH',
+      suggestedPointsPerDollar: Math.max(1, Math.floor(pointsPerDollar / 1000)),
+      };
+  }
+
+  const maxPayoutWei = BigInt(Math.floor(maxPointsPerPlayer)) * weiPerPoint;
+  if (maxPayoutWei > walletCapWei) {
+    return {
+      ok: false,
+      problem: 'a perfect round would earn more than this launch lets one wallet spend',
+      suggestedPointsPerDollar: minimumPointsPerDollar(input),
+    };
+  }
+
+  return { ok: true, economy: { weiPerPoint, maxPayoutWei } };
+}
+
+/**
+ * The smallest `pointsPerDollar` that keeps a flawless round inside the cap.
+ *
+ * Rounded up, then nudged until it actually passes: the division that produces it floors, and a
+ * value that is correct to the last wei but fails the check is worse than useless in an error
+ * message. Two steps is enough for any input — the loop is a guard against an off-by-one in the
+ * rounding, not an iterative search.
+ */
+function minimumPointsPerDollar(input: EconomyInput): number {
+  const { maxPointsPerPlayer, walletCapWei, usdPerEth } = input;
+  const points = BigInt(Math.floor(maxPointsPerPlayer));
+  const maxWeiPerPoint = walletCapWei / points;
+  if (maxWeiPerPoint <= 0n) return Math.ceil(maxPointsPerPlayer);
+
+  let candidate = Math.ceil(Number(WEI_PER_ETH / maxWeiPerPoint) / usdPerEth);
+  for (let i = 0; i < 3; i++) {
+    const result = resolveEconomy({ ...input, pointsPerDollar: candidate });
+    if (result.ok) return candidate;
+    candidate += 1;
+  }
+  return candidate;
+}

package/src/game-registry.ts

@@ -0,0 +1,107 @@
+import Fastify, { type FastifyInstance } from 'fastify';
+import cors from '@fastify/cors';
+import { createHash, timingSafeEqual } from 'node:crypto';
+import type { Pool } from 'pg';
+import { isAddress } from 'viem';
+import {
+  InvalidRegistration,
+  RegistrationConflict,
+  disableGameRegistration,
+  pinGameRegistration,
+  resolveGameRegistration,
+} from './registry.js';
+
+export interface GameRegistryOptions {
+  pool: Pool;
+  /** The flaunch.gg origins allowed to resolve registrations in a browser. */
+  allowedOrigins: readonly string[];
+  /** Server-to-server bearer token held only by the Flaunch launch backend. */
+  writerToken: string;
+}
+
+const authorised = (header: string | undefined, token: string): boolean => {
+  const supplied = header?.startsWith('Bearer ') ? header.slice('Bearer '.length) : '';
+  const digest = (value: string): Buffer => createHash('sha256').update(value).digest();
+  return timingSafeEqual(digest(supplied), digest(token));
+};
+
+const routeChainId = (value: string): number | null => {
+  if (!/^[1-9][0-9]*$/.test(value)) return null;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : null;
+};
+
+const internalRoute = (
+  request: { headers: { authorization?: string | undefined }; params: unknown },
+  token: string,
+) => {
+  if (!authorised(request.headers.authorization, token)) {
+    return { ok: false as const, status: 401 as const, message: 'registry writer authentication failed' };
+  }
+  const { chainId: rawChainId, coin } = request.params as { chainId: string; coin: string };
+  const chainId = routeChainId(rawChainId);
+  return chainId === null
+    ? { ok: false as const, status: 400 as const, message: 'that is not a chain id' }
+    : { ok: true as const, chainId, coin };
+};
+
+/**
+ * The stable, Flaunch-owned public read service for chain + coin → game discovery.
+ *
+ * Creator gates cannot host this route: a page needs the registration to discover which creator
+ * gate to call. Registration writes remain a trusted launch-backend operation against the store.
+ */
+export function createGameRegistry(options: GameRegistryOptions): FastifyInstance {
+  if (options.writerToken.length < 32) throw new RangeError('registry writer token must be at least 32 characters');
+  const app = Fastify({ bodyLimit: 1_024 });
+  void app.register(cors, { origin: [...options.allowedOrigins], methods: ['GET'] });
+
+  app.get('/games/:chainId/:coin', async (request, reply) => {
+    const { chainId: rawChainId, coin } = request.params as { chainId: string; coin: string };
+    const chainId = routeChainId(rawChainId);
+    if (chainId === null) {
+      return reply.code(400).send({ message: 'that is not a chain id' });
+    }
+    if (!isAddress(coin, { strict: false })) {
+      return reply.code(400).send({ message: 'that is not a coin address' });
+    }
+    const registration = await resolveGameRegistration(options.pool, chainId, coin);
+    return registration ?? reply.code(404).send({ message: 'that coin has no registered game' });
+  });
+
+  app.put('/internal/games/:chainId/:coin', async (request, reply) => {
+    const route = internalRoute(request, options.writerToken);
+    if (!route.ok) return reply.code(route.status).send({ message: route.message });
+    const body = (request.body ?? {}) as { gameId?: unknown; gateOrigin?: unknown; deployId?: unknown };
+    try {
+      const registration = await pinGameRegistration(options.pool, {
+        chainId: route.chainId,
+        coin: route.coin,
+        gameId: body.gameId as string,
+        gateOrigin: body.gateOrigin as string,
+        deployId: body.deployId as string,
+      });
+      return reply.send(registration);
+    } catch (error) {
+      if (error instanceof InvalidRegistration) return reply.code(400).send({ message: error.message });
+      if (error instanceof RegistrationConflict) {
+        return reply.code(409).send({ message: 'that coin already has a different game' });
+      }
+      throw error;
+    }
+  });
+
+  app.delete('/internal/games/:chainId/:coin', async (request, reply) => {
+    const route = internalRoute(request, options.writerToken);
+    if (!route.ok) return reply.code(route.status).send({ message: route.message });
+    try {
+      await disableGameRegistration(options.pool, route.chainId, route.coin);
+      return reply.code(204).send();
+    } catch (error) {
+      if (error instanceof InvalidRegistration) return reply.code(400).send({ message: error.message });
+      throw error;
+    }
+  });
+
+  return app;
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/** Public server-side surface for a production Game Mode gate. */
+export {
+  Claims,
+  DEFAULT_SETTLEMENT_TAIL_MS,
+  Room,
+  Sessions,
+  createGate,
+} from './server.js';
+export type {
+  Admission,
+  AdmissionRequest,
+  Admit,
+  ConfigForLaunch,
+  GateOptions,
+  VerifiedLaunch,
+} from './server.js';
+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 { 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 { Settlement } from './settlement.js';
+export { resolveEconomy } from './economy.js';
+export type { Economy, EconomyInput, EconomyResult } from './economy.js';
+export { migrate } from './store.js';
+export { createDemoGate } from './demo.js';
+export type { Demo, DemoOptions } from './demo.js';
+export {
+  InvalidRegistration,
+  RegistrationConflict,
+  checkRegistration,
+  disableGameRegistration,
+  gateOrigin,
+  pinGameRegistration,
+  resolveGameRegistration,
+  securityProfile,
+} from './registry.js';
+export type { Registration, SecurityProfile } from './registry.js';
+export { createGameRegistry } from './game-registry.js';
+export type { GameRegistryOptions } from './game-registry.js';