@flayerlabs/gamemode-gate 0.3.1 → 0.4.0

package/src/main.ts

@@ -0,0 +1,256 @@
+import pg from 'pg';
+import { createPublicClient, http, isAddress, type PublicClient } from 'viem';
+import type { FastifyInstance } from 'fastify';
+import type { GameModule } from '@flayerlabs/gamemode-spec';
+import { createGate, type GateAnnouncement } from './server.js';
+import { Ledger } from './ledger.js';
+import { Claims } from './claims.js';
+import { Sessions } from './sessions.js';
+import { PayloadSigner } from './chain/signer.js';
+import { Discovery } from './chain/discover.js';
+import { Settlement } from './settlement.js';
+import { migrate } from './store.js';
+import { resolveEconomy } from './economy.js';
+import { deploymentFor, type GateDeployment } from './chain/chains.js';
+import { assertSecureConfig } from './chain/secure.js';
+
+/**
+ * A production gate from an environment, assembled and checked.
+ *
+ * Until this file, every component existed and nothing joined them: the only `createGate` call
+ * sites were tests and the chain-free demo, so "run a gate against a real chain" meant writing this
+ * bootstrap yourself. A gate is still your game's own server — your repo imports your rules module
+ * and calls {@link startGate} — but the wiring, the address book and the refusals are the same for
+ * everyone, so they live here.
+ *
+ * Configuration is refused loudly rather than defaulted quietly. The failure mode this guards
+ * against is not a crash but a gate that boots, adopts nothing, and signs authorizations nothing
+ * accepts — see {@link assertSecureConfig} and the address-book note in chain/chains.ts.
+ */
+
+type Env = Record<string, string | undefined>;
+
+export interface ResolvedGateConfig {
+  chainId: number;
+  rpcUrl: string;
+  signerPrivateKey: `0x${string}`;
+  databaseUrl: string;
+  sessionSecret: string;
+  /** The page the player is looking at — the embedding site, not the game or this gate. */
+  signInDomain: string;
+  /** This gate's own public origin — the SIWE audience. Configured, never derived from a header. */
+  gateOrigin: string;
+  allowedOrigins: (string | RegExp)[];
+  port: number;
+  deployment: GateDeployment;
+  /** Announced to launch tooling; the creator's launch writes it into the pool. */
+  walletCapWei: bigint;
+  roundDurationMs: number;
+  minLobbyLeadMs: number;
+  gateEndsAtGraceS: number;
+  pointsPerDollar: number;
+  usdPerEth: number;
+  /** May lift the gate early or rotate the signer on-chain. Defaults to the signing key's address. */
+  settler: `0x${string}` | null;
+}
+
+function required(env: Env, name: string): string {
+  const value = env[name];
+  if (!value) throw new Error(`${name} is not set — the gate refuses to guess it`);
+  return value;
+}
+
+function integer(env: Env, name: string, fallback: number): number {
+  const raw = env[name];
+  if (raw === undefined || raw === '') return fallback;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${name} must be a non-negative integer`);
+  return value;
+}
+
+function address(env: Env, name: string): `0x${string}` | null {
+  const raw = env[name];
+  if (raw === undefined || raw === '') return null;
+  if (!isAddress(raw)) throw new Error(`${name} is not an address`);
+  return raw;
+}
+
+/**
+ * Read and validate the environment, pure so a test can feed it a plain object.
+ *
+ * The contract, all read here and nowhere else:
+ *   CHAIN_ID                 required; must have an address-book entry unless both overrides are set
+ *   RPC_URL                  required
+ *   SIGNER_PRIVATE_KEY       required; this gate's own key, never shared between environments
+ *   DATABASE_URL             required
+ *   SESSION_SECRET           required, at least 32 characters, not the demo fallback
+ *   SIGN_IN_DOMAIN           required; the embedding page the player sees (e.g. flaunch.gg)
+ *   GATE_ORIGIN              required; this gate's own public https origin (the SIWE audience)
+ *   ALLOWED_ORIGINS          required; comma-separated origins that may call this gate
+ *   PORT                     default 8790
+ *   POSITION_MANAGER         optional address-book override
+ *   SPEND_GATED_CALCULATOR   optional address-book override
+ *   FLAUNCH_VARIANT          optional; only meaningful alongside the overrides
+ *   SETTLER                  optional; defaults to the signing key's own address
+ *   WALLET_CAP_WEI           default 0.025 ETH
+ *   ROUND_MS                 default 90000
+ *   MIN_LOBBY_LEAD_MS        default 60000
+ *   GATE_ENDS_AT_GRACE_S     default 10
+ *   POINTS_PER_DOLLAR        default 100
+ *   USD_PER_ETH              default 3000
+ */
+export function resolveGateEnv(env: Env): ResolvedGateConfig {
+  const chainId = Number(required(env, 'CHAIN_ID'));
+  if (!Number.isSafeInteger(chainId) || chainId <= 0) throw new Error('CHAIN_ID must be a positive integer');
+
+  const recorded = deploymentFor(chainId);
+  const positionManager = address(env, 'POSITION_MANAGER') ?? recorded?.positionManager ?? null;
+  const spendGatedCalculator = address(env, 'SPEND_GATED_CALCULATOR') ?? recorded?.spendGatedCalculator ?? null;
+  if (!positionManager || !spendGatedCalculator) {
+    throw new Error(
+      `chain ${chainId} has no recorded deployment — set POSITION_MANAGER and SPEND_GATED_CALCULATOR ` +
+        `with addresses read back from that chain, or use a chain from the address book`,
+    );
+  }
+  const variantOverride = env['FLAUNCH_VARIANT'];
+  if (variantOverride !== undefined && variantOverride !== 'legacy11' && variantOverride !== 'current9') {
+    throw new Error(`FLAUNCH_VARIANT must be legacy11 or current9, not ${variantOverride}`);
+  }
+  const flaunchVariant = variantOverride ?? recorded?.flaunchVariant ?? 'legacy11';
+
+  const signerPrivateKey = required(env, 'SIGNER_PRIVATE_KEY');
+  if (!/^0x[0-9a-fA-F]{64}$/.test(signerPrivateKey)) {
+    throw new Error('SIGNER_PRIVATE_KEY must be a 32-byte hex key');
+  }
+
+  /**
+   * An entry may carry one `*` in its host — `https://*.flayer.dev` — because preview deployments
+   * mint a fresh subdomain per deploy, and a gate that names only yesterday's refuses today's
+   * embed with a CORS failure the page can only report as "stuck". The wildcard spans exactly one
+   * label: it must not make `https://*.dev` mean the whole internet by accident.
+   */
+  const allowedOrigins: (string | RegExp)[] = required(env, 'ALLOWED_ORIGINS')
+    .split(',')
+    .map((origin) => origin.trim())
+    .filter((origin) => origin.length > 0)
+    .map((origin) =>
+      origin.includes('*')
+        ? new RegExp(`^${origin.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[a-z0-9-]+')}$`)
+        : origin,
+    );
+  if (allowedOrigins.length === 0) throw new Error('ALLOWED_ORIGINS names no origins');
+
+  return {
+    chainId,
+    rpcUrl: required(env, 'RPC_URL'),
+    signerPrivateKey: signerPrivateKey as `0x${string}`,
+    databaseUrl: required(env, 'DATABASE_URL'),
+    sessionSecret: required(env, 'SESSION_SECRET'),
+    signInDomain: required(env, 'SIGN_IN_DOMAIN'),
+    gateOrigin: required(env, 'GATE_ORIGIN'),
+    allowedOrigins,
+    port: integer(env, 'PORT', 8790),
+    deployment: { positionManager, spendGatedCalculator, flaunchVariant },
+    walletCapWei: BigInt(env['WALLET_CAP_WEI'] ?? 25_000_000_000_000_000n.toString()),
+    roundDurationMs: integer(env, 'ROUND_MS', 90_000),
+    minLobbyLeadMs: integer(env, 'MIN_LOBBY_LEAD_MS', 60_000),
+    gateEndsAtGraceS: integer(env, 'GATE_ENDS_AT_GRACE_S', 10),
+    pointsPerDollar: integer(env, 'POINTS_PER_DOLLAR', 100),
+    usdPerEth: integer(env, 'USD_PER_ETH', 3_000),
+    settler: address(env, 'SETTLER'),
+  };
+}
+
+export interface StartedGate {
+  app: FastifyInstance;
+  port: number;
+  /** The address launches must name as their trusted signer for this gate to adopt them. */
+  signer: `0x${string}`;
+  pool: pg.Pool;
+}
+
+export interface StartGateOverrides {
+  env?: Env;
+  /** Injectable for tests; a real boot builds its own from RPC_URL. */
+  client?: PublicClient;
+  /** False builds and checks everything but never binds a port. */
+  listen?: boolean;
+}
+
+export async function startGate<Config, State, Event, Action, PublicView, PlayerView>(
+  game: GameModule<Config, State, Event, Action, PublicView, PlayerView>,
+  gameConfig: Config,
+  overrides: StartGateOverrides = {},
+): Promise<StartedGate> {
+  const config = resolveGateEnv(overrides.env ?? process.env);
+
+  // The same refusal the demo makes: an economy that cannot pay out is caught before anyone plays.
+  const economy = resolveEconomy({
+    maxPointsPerPlayer: game.rewardBounds(gameConfig).maxPointsPerPlayer,
+    walletCapWei: config.walletCapWei,
+    pointsPerDollar: config.pointsPerDollar,
+    usdPerEth: config.usdPerEth,
+  });
+  if (!economy.ok) {
+    throw new Error(
+      `That economy does not work: ${economy.problem}. Try ${economy.suggestedPointsPerDollar} points per dollar.`,
+    );
+  }
+
+  const client = overrides.client ?? createPublicClient({ transport: http(config.rpcUrl) });
+  await assertSecureConfig(client, {
+    chainId: config.chainId,
+    signerPrivateKey: config.signerPrivateKey,
+    spendGatedCalculator: config.deployment.spendGatedCalculator,
+    sessionSecret: config.sessionSecret,
+  });
+
+  const pool = new pg.Pool({ connectionString: config.databaseUrl });
+  await migrate(pool);
+
+  const ledger = new Ledger(pool);
+  const signer = new PayloadSigner(config.signerPrivateKey, config.chainId, config.deployment.spendGatedCalculator);
+  const settler = config.settler ?? signer.address;
+
+  const announce = (): GateAnnouncement => ({
+    chainId: config.chainId,
+    contracts: {
+      positionManager: config.deployment.positionManager,
+      spendGatedCalculator: config.deployment.spendGatedCalculator,
+    },
+    signer: signer.address,
+    settler,
+    walletCapWei: config.walletCapWei.toString(),
+    roundDurationMs: config.roundDurationMs,
+    minLobbyLeadMs: config.minLobbyLeadMs,
+    gateEndsAtGraceS: config.gateEndsAtGraceS,
+    flaunchVariant: config.deployment.flaunchVariant,
+    requiresEoa: false,
+    accepting: true,
+    publicLaunchesOpen: true,
+    privateLaunches: false,
+  });
+
+  const app = createGate({
+    pool,
+    game,
+    config: gameConfig,
+    pointsPerDollar: config.pointsPerDollar,
+    usdPerEth: config.usdPerEth,
+    sessions: new Sessions(config.sessionSecret, config.signInDomain, config.gateOrigin),
+    claims: new Claims(pool, ledger, signer),
+    discovery: new Discovery(client, {
+      positionManager: config.deployment.positionManager,
+      spendGatedCalculator: config.deployment.spendGatedCalculator,
+      signer: signer.address,
+    }),
+    settlement: new Settlement(pool, ledger, client, config.deployment.spendGatedCalculator),
+    allowedOrigins: config.allowedOrigins,
+    announce,
+  });
+
+  if (overrides.listen !== false) {
+    await app.listen({ port: config.port, host: '0.0.0.0' });
+  }
+  return { app, port: config.port, signer: signer.address, pool };
+}

package/src/server.ts

@@ -49,8 +49,23 @@ interface GateBaseOptions {
   settlement?: Settlement;
   /** How long charts and final spend reconciliation remain live after gameplay closes. */
   settlementTailMs?: number;
-  /** Origins allowed to call this gate: the game's own, and nothing else. */
-  allowedOrigins: string[];
+  /**
+   * Origins allowed to call this gate: the game's own and the pages that embed it, and nothing
+   * else. Regular expressions are for hosts that exist in families — preview deployments get a
+   * fresh subdomain per deploy, and an allowlist that names only yesterday's is a gate that
+   * silently refuses today's embed.
+   */
+  allowedOrigins: (string | RegExp)[];
+  /**
+   * What this gate tells launch tooling about itself, served at `GET /config` when present.
+   *
+   * A launch gates its pool by writing this gate's signer (and the rest of these facts) into its
+   * own on-chain parameters, so whoever builds that launch has to be able to ask. The flaunch
+   * create page is the caller — a different origin from the game's — which is why the route is
+   * served with a permissive CORS header rather than the gate-wide allowlist: everything in it is
+   * public by definition, since a launch publishes it on chain.
+   */
+  announce?: () => GateAnnouncement;
   /**
    * Decide whether a caller may open a session or spend a request, or refuse them.
    *
@@ -94,6 +109,39 @@ export interface GameServerGateOptions extends GateBaseOptions {
   gameServerOrigins?: readonly string[];
 }
 
+/**
+ * The gate's public identity, in the exact shape the flaunch frontend's `GateServerConfig` already
+ * parses — served this way so the page that builds launches needs no second config type.
+ */
+export interface GateAnnouncement {
+  chainId: number;
+  contracts: {
+    positionManager: `0x${string}`;
+    spendGatedCalculator: `0x${string}`;
+  };
+  /** The address launches must name as their trusted signer for this gate to adopt them. */
+  signer: `0x${string}`;
+  /** May lift the gate early or rotate the signer on-chain; the launch writes it into the pool. */
+  settler: `0x${string}`;
+  /** A decimal string — wei does not survive JSON as a number. */
+  walletCapWei: string;
+  roundDurationMs: number;
+  minLobbyLeadMs: number;
+  gateEndsAtGraceS: number;
+  flaunchVariant: 'legacy11' | 'current9';
+  requiresEoa: boolean;
+  accepting: boolean;
+  /**
+   * Always true for a gate built from this library: launching through it is permissionless by
+   * design — the chain itself authorizes a round (the launch names this gate's signer in public
+   * state), so there is no allowlist for this flag to guard. The field exists because the
+   * embedding page fails CLOSED without it.
+   */
+  publicLaunchesOpen: boolean;
+  /** This library has no private-lobby registrar; announced false so no page offers the toggle. */
+  privateLaunches: boolean;
+}
+
 /** 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. */
@@ -437,6 +485,51 @@ function createGateRuntime<Config, State, Event, Action, PublicView, PlayerView>
   app.after(() => {
   app.get('/health', () => ({ ok: true }));
 
+  /**
+   * Lifetime usage totals, for the platform's developer dashboard.
+   *
+   * Served by every gate rather than behind an option, because the numbers already exist in the
+   * gate's own tables and this is the only place they exist at all — the platform never sees a
+   * play. Spend is `chain_spent_wei`, the chain-reconciled figure, not claims: an expired hold is
+   * not a purchase. `spendWeiTotal` is a decimal string because wei does not survive JSON as a
+   * number, and `lastRoundAt` is milliseconds, matching every timestamp a round carries.
+   *
+   * The permissive CORS header mirrors `/config`: the dashboard is a different origin from the
+   * game's, and every figure here is an aggregate a spectator could tally themselves.
+   */
+  app.get('/stats', async (_request, reply) => {
+    void reply.header('access-control-allow-origin', '*');
+    const { rows } = await pool.query<{
+      rounds_total: string;
+      players_total: string;
+      spend_wei_total: string;
+      last_round_at: string | null;
+    }>(
+      `select (select count(*) from rounds)                                   as rounds_total,
+              (select count(distinct player) from balances)                   as players_total,
+              (select coalesce(sum(chain_spent_wei), 0)::text from balances)  as spend_wei_total,
+              (select max(opens_at) from rounds)                              as last_round_at`,
+    );
+    const totals = rows[0]!;
+    return {
+      roundsTotal: Number(totals.rounds_total),
+      playersTotal: Number(totals.players_total),
+      spendWeiTotal: totals.spend_wei_total,
+      lastRoundAt: totals.last_round_at === null ? null : Number(totals.last_round_at),
+    };
+  });
+
+  if (options.announce) {
+    const announce = options.announce;
+    app.get('/config', (_request, reply) => {
+      // Simple GET, so this header alone is enough — no preflight to satisfy. The gate-wide CORS
+      // 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();
+    });
+  }
+
   app.post('/session/challenge', async (request) => {
     const { address } = request.body as { address?: string };
     if (typeof address !== 'string') throw new NotSignedIn('a wallet address is required');