@flayerlabs/gamemode-spec 0.1.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@flayerlabs/gamemode-spec",
+  "version": "0.1.0",
+  "description": "Pure rules, round, scheduling, live-room and embed contracts 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/spec"
+  },
+  "bugs": {
+    "url": "https://github.com/flayerlabs/gamemode-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./round": {
+      "types": "./dist/round.d.ts",
+      "default": "./dist/round.js"
+    },
+    "./schedule": {
+      "types": "./dist/schedule.d.ts",
+      "default": "./dist/schedule.js"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "default": "./dist/live.js"
+    },
+    "./embed": {
+      "types": "./dist/embed.d.ts",
+      "default": "./dist/embed.js"
+    }
+  },
+  "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"
+  },
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/embed.ts

@@ -0,0 +1,450 @@
+import type { PlayerId } from './index.js';
+import { isLaunchContext, type BuyFailure, type LaunchContext, type PlayerIdentity, type WireMarketState } from './live.js';
+
+export const EMBED_CHANNEL = 'flaunch.game-mode' as const;
+export const EMBED_PROTOCOL_VERSION = 1 as const;
+
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const BYTES32 = /^0x[0-9a-fA-F]{64}$/;
+const HEX = /^0x(?:[0-9a-fA-F]{2})*$/;
+const DECIMAL = /^(?:0|[1-9][0-9]{0,77})$/;
+const REQUEST_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const DEPLOY_ID = /^[0-9a-f]{32}$/;
+const PUBLIC_HOSTNAME = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+
+export interface GameRegistration {
+  chainId: number;
+  coin: string;
+  gameId: string;
+  gateOrigin: string;
+  deployId: string;
+}
+
+/** Parse the central registry response into the exact browser-safe shape the parent may trust. */
+export function parseGameRegistration(input: unknown): GameRegistration | null {
+  const value = record(input);
+  if (
+    !value ||
+    !Number.isSafeInteger(value.chainId) ||
+    (value.chainId as number) <= 0 ||
+    typeof value.coin !== 'string' ||
+    !ADDRESS.test(value.coin) ||
+    value.coin !== value.coin.toLowerCase() ||
+    typeof value.gameId !== 'string' ||
+    value.gameId.length === 0 ||
+    value.gameId.length > 128 ||
+    value.gameId !== value.gameId.trim() ||
+    typeof value.deployId !== 'string' ||
+    !DEPLOY_ID.test(value.deployId) ||
+    typeof value.gateOrigin !== 'string' ||
+    value.gateOrigin.length > 253 ||
+    /[^\x20-\x7e]/.test(value.gateOrigin)
+  ) {
+    return null;
+  }
+
+  try {
+    const gate = new URL(value.gateOrigin);
+    if (
+      gate.protocol !== 'https:' ||
+      gate.origin !== value.gateOrigin ||
+      !PUBLIC_HOSTNAME.test(gate.hostname)
+    ) {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+
+  return {
+    chainId: value.chainId as number,
+    coin: value.coin,
+    gameId: value.gameId,
+    gateOrigin: value.gateOrigin,
+    deployId: value.deployId,
+  };
+}
+
+export interface SpendAuthorisation {
+  buyer: string;
+  poolId: string;
+  deadline: string;
+  maxSpendWei: string;
+  nonce: string;
+  signature: string;
+  signer: string;
+  /** Opaque proof from the gate. The parent passes it to the Flaunch SDK unchanged. */
+  hookData: `0x${string}`;
+}
+
+export interface SpendAuthorisationFields {
+  buyer: string;
+  poolId: string;
+  deadline: string | bigint;
+  maxSpendWei: string | bigint;
+  nonce: string | bigint;
+}
+
+const SPEND_AUTHORIZATION_TYPES = {
+  SpendAuthorization: [
+    { name: 'buyer', type: 'address' },
+    { name: 'poolId', type: 'bytes32' },
+    { name: 'deadline', type: 'uint256' },
+    { name: 'maxSpendWei', type: 'uint256' },
+    { name: 'nonce', type: 'uint256' },
+  ],
+} as const;
+
+function uint256(value: string | bigint, field: string): bigint {
+  if (typeof value === 'string' && !DECIMAL.test(value)) {
+    throw new RangeError(`${field} must be an unsigned decimal integer`);
+  }
+  const parsed = BigInt(value);
+  if (parsed < 0n || parsed >= 1n << 256n) throw new RangeError(`${field} must fit uint256`);
+  return parsed;
+}
+
+/** Build the one typed-data shape shared by the gate signer and trusted parent verifier. */
+export function spendAuthorisationTypedData(
+  fields: SpendAuthorisationFields,
+  chainId: number,
+  verifyingContract: string,
+) {
+  if (!ADDRESS.test(fields.buyer)) throw new TypeError('buyer must be an EVM address');
+  if (!BYTES32.test(fields.poolId)) throw new TypeError('poolId must be 32 bytes');
+  if (!Number.isSafeInteger(chainId) || chainId <= 0) throw new RangeError('chainId must be a positive safe integer');
+  if (!ADDRESS.test(verifyingContract)) throw new TypeError('verifyingContract must be an EVM address');
+
+  return {
+    domain: {
+      name: 'FlaunchSpendGate',
+      version: '1',
+      chainId,
+      verifyingContract: verifyingContract as `0x${string}`,
+    },
+    types: SPEND_AUTHORIZATION_TYPES,
+    primaryType: 'SpendAuthorization' as const,
+    message: {
+      buyer: fields.buyer as `0x${string}`,
+      poolId: fields.poolId as `0x${string}`,
+      deadline: uint256(fields.deadline, 'deadline'),
+      maxSpendWei: uint256(fields.maxSpendWei, 'maxSpendWei'),
+      nonce: uint256(fields.nonce, 'nonce'),
+    },
+  };
+}
+
+export interface EmbeddedContext {
+  gateUrl: string;
+  roundId: string;
+  launch: LaunchContext;
+}
+
+export type EmbedRequest =
+  | { method: 'address' }
+  | { method: 'sign-in'; message: string }
+  | { method: 'session-evidence' }
+  | { method: 'buy'; authorisation: SpendAuthorisation }
+  | { method: 'identity'; players: readonly PlayerId[] };
+
+export type GameToHostMessage =
+  | { channel: typeof EMBED_CHANNEL; v: typeof EMBED_PROTOCOL_VERSION; type: 'ready' }
+  | {
+      channel: typeof EMBED_CHANNEL;
+      v: typeof EMBED_PROTOCOL_VERSION;
+      type: 'request';
+      id: string;
+      request: EmbedRequest;
+    };
+
+export type EmbedFailure = BuyFailure | 'no-wallet';
+
+export type HostToGameMessage =
+  | {
+      channel: typeof EMBED_CHANNEL;
+      v: typeof EMBED_PROTOCOL_VERSION;
+      type: 'context';
+      context: EmbeddedContext;
+    }
+  | {
+      channel: typeof EMBED_CHANNEL;
+      v: typeof EMBED_PROTOCOL_VERSION;
+      type: 'response';
+      id: string;
+      ok: true;
+      value: unknown;
+    }
+  | {
+      channel: typeof EMBED_CHANNEL;
+      v: typeof EMBED_PROTOCOL_VERSION;
+      type: 'response';
+      id: string;
+      ok: false;
+      error: EmbedFailure;
+    }
+  | {
+      channel: typeof EMBED_CHANNEL;
+      v: typeof EMBED_PROTOCOL_VERSION;
+      type: 'buy-progress';
+      id: string;
+      transactionHash?: string;
+    }
+  | {
+      channel: typeof EMBED_CHANNEL;
+      v: typeof EMBED_PROTOCOL_VERSION;
+      type: 'market';
+      market: WireMarketState;
+    };
+
+function record(input: unknown): Record<string, unknown> | null {
+  return typeof input === 'object' && input !== null ? (input as Record<string, unknown>) : null;
+}
+
+function bounded(value: unknown, max: number): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= max;
+}
+
+function finite(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function isWireMarketState(input: unknown): input is WireMarketState {
+  const value = record(input);
+  if (
+    !value ||
+    typeof value.status !== 'string' ||
+    !['unavailable', 'loading', 'live', 'stale'].includes(value.status) ||
+    !Array.isArray(value.prices) ||
+    value.prices.length > 1_000 ||
+    !Array.isArray(value.trades) ||
+    value.trades.length > 500 ||
+    (value.marketCapUsd !== null && !finite(value.marketCapUsd))
+  ) {
+    return false;
+  }
+
+  for (const inputPrice of value.prices) {
+    const price = record(inputPrice);
+    if (!price || !finite(price.at) || !finite(price.priceEth) || price.priceEth <= 0) return false;
+  }
+
+  for (const inputTrade of value.trades) {
+    const trade = record(inputTrade);
+    if (
+      !trade ||
+      !bounded(trade.id, 128) ||
+      !finite(trade.at) ||
+      (trade.player !== null && !bounded(trade.player, 128)) ||
+      (trade.side !== 'buy' && trade.side !== 'sell') ||
+      typeof trade.spendWei !== 'string' ||
+      !DECIMAL.test(trade.spendWei) ||
+      (trade.priceEth !== null && !finite(trade.priceEth)) ||
+      (trade.transactionHash !== undefined && !bounded(trade.transactionHash, 128))
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function embeddedContext(input: unknown): input is EmbeddedContext {
+  const value = record(input);
+  if (!value || !bounded(value.gateUrl, 2_048) || !bounded(value.roundId, 128) || !isLaunchContext(value.launch)) {
+    return false;
+  }
+  if (value.roundId !== value.launch.roundId) return false;
+  try {
+    const gate = new URL(value.gateUrl);
+    return (gate.protocol === 'https:' || gate.protocol === 'http:') && gate.origin === value.gateUrl;
+  } catch {
+    return false;
+  }
+}
+
+export function isSpendAuthorisation(input: unknown): input is SpendAuthorisation {
+  const value = record(input);
+  return Boolean(
+    value &&
+      typeof value.buyer === 'string' &&
+      ADDRESS.test(value.buyer) &&
+      typeof value.poolId === 'string' &&
+      BYTES32.test(value.poolId) &&
+      typeof value.deadline === 'string' &&
+      DECIMAL.test(value.deadline) &&
+      typeof value.maxSpendWei === 'string' &&
+      DECIMAL.test(value.maxSpendWei) &&
+      typeof value.nonce === 'string' &&
+      DECIMAL.test(value.nonce) &&
+      typeof value.signature === 'string' &&
+      HEX.test(value.signature) &&
+      value.signature.length <= 512 &&
+      typeof value.signer === 'string' &&
+      ADDRESS.test(value.signer) &&
+      typeof value.hookData === 'string' &&
+      HEX.test(value.hookData) &&
+      value.hookData.length <= 8_194,
+  );
+}
+
+const uint256Word = (value: string): string | null => {
+  try {
+    const parsed = BigInt(value);
+    return parsed < 1n << 256n ? parsed.toString(16).padStart(64, '0') : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Require the exact ABI payload the gate emits, including its zero referrer.
+ *
+ * The calculator signature covers the spend fields but not the outer referrer. A creator iframe
+ * can therefore redirect attribution while preserving a valid signature unless the trusted
+ * bridge checks the complete canonical encoding before opening wallet UI.
+ */
+export function isCanonicalSpendHookData(input: unknown): input is SpendAuthorisation {
+  if (!isSpendAuthorisation(input)) return false;
+  const deadline = uint256Word(input.deadline);
+  const maxSpendWei = uint256Word(input.maxSpendWei);
+  const nonce = uint256Word(input.nonce);
+  if (!deadline || !maxSpendWei || !nonce) return false;
+
+  const signature = input.signature.slice(2).toLowerCase();
+  const signatureLength = uint256Word(String(signature.length / 2));
+  if (!signatureLength) return false;
+  const paddedSignature = signature.padEnd(Math.ceil(signature.length / 64) * 64, '0');
+  const expected = `0x${[
+    '0'.repeat(64),
+    uint256Word('64'),
+    input.buyer.slice(2).toLowerCase().padStart(64, '0'),
+    input.poolId.slice(2).toLowerCase(),
+    deadline,
+    maxSpendWei,
+    nonce,
+    uint256Word('192'),
+    signatureLength,
+    paddedSignature,
+  ].join('')}`;
+  return input.hookData.toLowerCase() === expected;
+}
+
+export function parseGameToHostMessage(input: unknown): GameToHostMessage | null {
+  const value = record(input);
+  if (value?.channel !== EMBED_CHANNEL || value.v !== EMBED_PROTOCOL_VERSION) return null;
+  if (value.type === 'ready') return { channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'ready' };
+  if (value.type !== 'request' || typeof value.id !== 'string' || !REQUEST_ID.test(value.id)) return null;
+  const request = record(value.request);
+  if (!request) return null;
+
+  let parsed: EmbedRequest | null = null;
+  if (request.method === 'address') parsed = { method: 'address' };
+  if (request.method === 'session-evidence') parsed = { method: 'session-evidence' };
+  if (request.method === 'sign-in' && bounded(request.message, 4_096)) {
+    parsed = { method: 'sign-in', message: request.message };
+  }
+  if (request.method === 'buy' && isSpendAuthorisation(request.authorisation)) {
+    const authorisation = request.authorisation;
+    parsed = {
+      method: 'buy',
+      authorisation: {
+        buyer: authorisation.buyer,
+        poolId: authorisation.poolId,
+        deadline: authorisation.deadline,
+        maxSpendWei: authorisation.maxSpendWei,
+        nonce: authorisation.nonce,
+        signature: authorisation.signature,
+        signer: authorisation.signer,
+        hookData: authorisation.hookData,
+      },
+    };
+  }
+  if (
+    request.method === 'identity' &&
+    Array.isArray(request.players) &&
+    request.players.length <= 100 &&
+    request.players.every((player) => typeof player === 'string' && ADDRESS.test(player))
+  ) {
+    parsed = { method: 'identity', players: [...new Set(request.players)] as PlayerId[] };
+  }
+  return parsed ? { channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'request', id: value.id, request: parsed } : null;
+}
+
+export function parseHostToGameMessage(input: unknown): HostToGameMessage | null {
+  const value = record(input);
+  if (value?.channel !== EMBED_CHANNEL || value.v !== EMBED_PROTOCOL_VERSION) return null;
+  if (value.type === 'context' && embeddedContext(value.context)) {
+    return { channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'context', context: value.context };
+  }
+  if (value.type === 'market' && isWireMarketState(value.market)) return value as unknown as HostToGameMessage;
+  if (typeof value.id !== 'string' || !REQUEST_ID.test(value.id)) return null;
+  if (value.type === 'buy-progress') {
+    if (value.transactionHash !== undefined && (typeof value.transactionHash !== 'string' || !BYTES32.test(value.transactionHash))) {
+      return null;
+    }
+    return value as unknown as HostToGameMessage;
+  }
+  if (value.type !== 'response' || typeof value.ok !== 'boolean') return null;
+  if (value.ok) return value as unknown as HostToGameMessage;
+  return ['nothing-to-spend', 'declined', 'not-enough-for-fees', 'window-closed', 'no-wallet', 'try-again'].includes(
+    String(value.error),
+  )
+    ? (value as unknown as HostToGameMessage)
+    : null;
+}
+
+/** Reject an iframe trying to turn the trusted parent into a generic signing oracle. */
+export function isSessionChallenge(
+  message: string,
+  address: string,
+  gateOrigin: string,
+  domain = 'flaunch.gg',
+): boolean {
+  if (!ADDRESS.test(address) || message.length > 4_096) return false;
+  try {
+    const gate = new URL(gateOrigin);
+    if ((gate.protocol !== 'https:' && gate.protocol !== 'http:') || gate.origin !== gateOrigin) return false;
+  } catch {
+    return false;
+  }
+  const lines = message.split('\n');
+  if (lines.length !== 7 || !lines[4]?.startsWith('Wallet: ') || !lines[6]?.startsWith('Code: ')) return false;
+  const wallet = lines[4].slice('Wallet: '.length);
+  const code = lines[6].slice('Code: '.length);
+  return (
+    wallet.toLowerCase() === address.toLowerCase() &&
+    code.length > 0 &&
+    code.length <= 2_048 &&
+    message === formatSessionChallenge(domain, wallet, gateOrigin, code)
+  );
+}
+
+/** Canonical wallet challenge shared by the gate and the trusted embedding parent. */
+export function formatSessionChallenge(domain: string, address: string, gateOrigin: string, code: string): string {
+  return [
+    `${domain} wants you to sign in with your wallet.`,
+    '',
+    'Signing proves this wallet is yours. It costs nothing and moves nothing.',
+    '',
+    `Wallet: ${address}`,
+    `Gate: ${gateOrigin}`,
+    `Code: ${code}`,
+  ].join('\n');
+}
+
+export function isPlayerIdentities(input: unknown): input is readonly PlayerIdentity[] {
+  return (
+    Array.isArray(input) &&
+    input.length <= 100 &&
+    input.every((identity) => {
+      const value = record(identity);
+      return Boolean(
+        value &&
+          typeof value.player === 'string' &&
+          ADDRESS.test(value.player) &&
+          (value.displayName === null || (typeof value.displayName === 'string' && value.displayName.length <= 256)) &&
+          (value.avatarUrl === null || (typeof value.avatarUrl === 'string' && value.avatarUrl.length <= 2_048)),
+      );
+    })
+  );
+}

package/src/index.ts

@@ -0,0 +1,133 @@
+/**
+ * The contract between a game and the platform.
+ *
+ * Nothing in this file knows what any game is about. If a concept here can be named after a
+ * particular game — a score curve, a question, a projectile — it is in the wrong file.
+ *
+ * The whole platform rests on one property: a game's rules are a PURE FUNCTION of state and a
+ * command. Everything else — durability, replay, reconnect, anti-cheat forensics, running the
+ * same rules in a browser and on a server — is a consequence of that, not an addition to it.
+ */
+
+/** A player, opaque to the platform. In practice a lowercased wallet address. */
+export type PlayerId = string;
+
+/** When a round's window opens and closes. Absolute epoch milliseconds. */
+export interface RoundWindow {
+  opensAt: number;
+  closesAt: number;
+}
+
+/**
+ * What the platform asks a game to decide on.
+ *
+ * Every command carries `at` — the authoritative time it happened. A game reads time from here
+ * and nowhere else. There is no clock in scope and no ambient randomness: `seed` is supplied so
+ * anything a game wants to randomise is derived, and therefore reproducible.
+ */
+export type Command<Action> =
+  | { kind: 'join'; player: PlayerId; seed: number; at: number }
+  | { kind: 'leave'; player: PlayerId; at: number }
+  | { kind: 'action'; player: PlayerId; action: Action; at: number }
+  /** The platform woke the round at a time the game asked for via {@link GameModule.nextWakeAt}. */
+  | { kind: 'wake'; at: number };
+
+/** Points awarded to a player. The platform converts these to spending allowance; it does not
+ *  know or care how they were earned. */
+export interface Award {
+  player: PlayerId;
+  points: number;
+}
+
+/**
+ * What a game decides in response to a command.
+ *
+ * Awards are separate from events on purpose. A game may accept an action now and pay for it
+ * later — a quiz must, or a player learns they answered correctly by watching their own balance
+ * before the reveal, and the reveal stops meaning anything.
+ */
+export interface Decision<Event> {
+  events: readonly Event[];
+  awards?: readonly Award[];
+}
+
+/**
+ * A refused command. `code` is stable and machine-readable — alerting and months of history key
+ * on it, so it is never renamed, only added to. Player-facing copy lives in the client.
+ *
+ * Never put a threshold in a code. A refusal a cheater can calibrate against is an oracle.
+ */
+export interface Refusal {
+  refuse: string;
+}
+
+export function isRefusal<E>(result: Decision<E> | Refusal): result is Refusal {
+  return 'refuse' in result;
+}
+
+/** The most a single player can earn in one round. The platform checks this against the pool's
+ *  on-chain per-wallet cap before a round is allowed to start. */
+export interface RewardBounds {
+  maxPointsPerPlayer: number;
+}
+
+/**
+ * A game.
+ *
+ * `decide` and `evolve` must be pure: same inputs, same outputs, forever. No clock, no
+ * randomness, no I/O, no module-level mutable state. This is enforced by lint rather than by
+ * review, because it is the property everything else depends on.
+ */
+export interface GameModule<Config, State, Event, Action, PublicView, PlayerView> {
+  /** Stable identifier, unique across games. */
+  readonly id: string;
+
+  /** Reject anything that is not a well-formed action, including anything oversized. Returning
+   *  null refuses the command before it reaches {@link decide}. */
+  parseAction(input: unknown): Action | null;
+
+  /** Build the starting state. Deterministic in `seed`. */
+  initRound(config: Config, seed: number, window: RoundWindow): State;
+
+  /** The trust boundary. Pure. The only thing that may award points. */
+  decide(state: State, command: Command<Action>): Decision<Event> | Refusal;
+
+  /** Apply one event. Pure. */
+  evolve(state: State, event: Event): State;
+
+  /**
+   * What everyone sees, including spectators and anyone reading the socket.
+   *
+   * A value that must stay hidden must not appear in this type. Do not return it and filter
+   * downstream — the type is the enforcement, which is what makes a leak unrenderable rather
+   * than merely unlikely.
+   */
+  publicView(state: State): PublicView;
+
+  /** What one player sees. Anything private belongs here. */
+  playerView(state: State, player: PlayerId): PlayerView;
+
+  /**
+   * When the game next needs waking, or null if it is waiting only on players. Absolute epoch
+   * milliseconds.
+   *
+   * Each wake must ask for a time strictly LATER than the one being served. A phase that ends at
+   * the instant it begins has no duration, and asking to be woken at the time it already is would
+   * spin forever. If two things must happen back to back, they are two phases with real durations —
+   * which is usually what the product wanted anyway.
+   */
+  nextWakeAt(state: State): number | null;
+
+  /** Declared up front so the platform can refuse an incoherent economy before anyone plays. */
+  rewardBounds(config: Config): RewardBounds;
+}
+
+/**
+ * Authoring entry point. Exists for type inference — writing a `GameModule` literal directly
+ * means naming six type arguments by hand.
+ */
+export function defineGame<Config, State, Event, Action, PublicView, PlayerView>(
+  game: GameModule<Config, State, Event, Action, PublicView, PlayerView>,
+): GameModule<Config, State, Event, Action, PublicView, PlayerView> {
+  return game;
+}