@flayerlabs/gamemode-spec 0.3.0 → 0.4.0

package/dist/frame.d.ts

@@ -0,0 +1,127 @@
+import type { LaunchContext } from './live.js';
+/**
+ * The wire contract between a game iframe and the page embedding it.
+ *
+ * A game and its embedding page are different origins, so the `Host` object the client needs
+ * cannot be handed across directly — it is reconstructed over `postMessage` using these frames.
+ * The shapes live in spec because BOTH ends must agree while sharing no runtime: the game side is
+ * `@flayerlabs/gamemode-client`, and an embedding page may implement the parent side from these
+ * definitions alone.
+ *
+ * Two ground rules, both inherited from the live-socket protocol:
+ * - every frame carries `v`, and an end that sees a version it does not speak ignores the frame;
+ * - bigints cross as decimal strings, because they do not survive JSON and structured clone is not
+ *   guaranteed by every path a frame may take.
+ *
+ * The trust story is deliberately asymmetric. The game learns exactly one thing from its URL — the
+ * embedding page's origin, `?parentOrigin=` — because it needs that BEFORE any message can be
+ * trusted. Everything else (which gate, which round, which coin) arrives in `gm:context`, so there
+ * is one source of truth and it is the page the player is actually looking at.
+ */
+export declare const FRAME_PROTOCOL_VERSION: 1;
+/**
+ * Why a buy did not happen, in terms a player can be told about.
+ *
+ * Deliberately a short list of plain outcomes rather than anything from the chain. A game should
+ * never render a revert string or an error code at a player: the client maps each of these to its
+ * own copy, and the copy is free to change without the meaning moving.
+ *
+ * Lives here rather than in the client because the embedding page produces these values and the
+ * game consumes them — the one enum both ends of the frame protocol must share.
+ */
+import type { BuyFailure } from './live.js';
+export type { BuyFailure };
+/** Everything a game needs to join its round, told to it by the page rather than its URL. */
+export interface EmbedContext {
+    readonly gateUrl: string;
+    readonly roundId: string;
+    readonly coinAddress: string;
+    readonly chainId: number;
+    /** Optional — a live gate sends it in the first snapshot anyway. */
+    readonly launch?: LaunchContext;
+}
+/** Exactly what the gate signed, all strings because bigints do not survive JSON. */
+export interface WireAuthorisation {
+    buyer: string;
+    poolId: string;
+    deadline: string;
+    maxSpendWei: string;
+    nonce: string;
+    signature: string;
+    signer: string;
+    /** Opaque proof the page passes to the Flaunch buy call. Never calldata. */
+    hookData?: `0x${string}`;
+}
+export type HostCall = {
+    method: 'address';
+} | {
+    method: 'signIn';
+    message: string;
+} | {
+    method: 'buy';
+    authorisation: WireAuthorisation;
+};
+export type GameToHostFrame = {
+    v: typeof FRAME_PROTOCOL_VERSION;
+    type: 'gm:hello';
+} | {
+    v: typeof FRAME_PROTOCOL_VERSION;
+    type: 'gm:req';
+    id: string;
+    call: HostCall;
+};
+/**
+ * What a refusal means to the game: `declined` and `no-wallet` are player states a game can name;
+ * `not-allowed` is a call the page refuses to service; `failed` is everything else.
+ */
+export type HostErrorCode = 'declined' | 'no-wallet' | 'not-allowed' | 'failed';
+export type WireHostResult = {
+    method: 'address';
+    address: string | null;
+} | {
+    method: 'signIn';
+    signature: `0x${string}`;
+} | {
+    method: 'buy';
+    outcome: {
+        spentWei: string;
+    } | {
+        failed: {
+            bought: false;
+            reason: BuyFailure;
+        };
+    };
+};
+export type HostToGameFrame = {
+    v: typeof FRAME_PROTOCOL_VERSION;
+    type: 'gm:context';
+    context: EmbedContext;
+} | {
+    v: typeof FRAME_PROTOCOL_VERSION;
+    type: 'gm:progress';
+    id: string;
+    progress: {
+        state: 'pending';
+        transactionHash?: string;
+    };
+} | {
+    v: typeof FRAME_PROTOCOL_VERSION;
+    type: 'gm:res';
+    id: string;
+    ok: true;
+    result: WireHostResult;
+} | {
+    v: typeof FRAME_PROTOCOL_VERSION;
+    type: 'gm:res';
+    id: string;
+    ok: false;
+    error: {
+        code: HostErrorCode;
+        message: string;
+    };
+};
+/** A frame from the game, or null for anything malformed or from another protocol version. */
+export declare function gameFrameFrom(input: unknown): GameToHostFrame | null;
+/** A frame from the page, or null for anything malformed or from another protocol version. */
+export declare function hostFrameFrom(input: unknown): HostToGameFrame | null;
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"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"}

package/dist/frame.js

@@ -0,0 +1,175 @@
+/**
+ * The wire contract between a game iframe and the page embedding it.
+ *
+ * A game and its embedding page are different origins, so the `Host` object the client needs
+ * cannot be handed across directly — it is reconstructed over `postMessage` using these frames.
+ * The shapes live in spec because BOTH ends must agree while sharing no runtime: the game side is
+ * `@flayerlabs/gamemode-client`, and an embedding page may implement the parent side from these
+ * definitions alone.
+ *
+ * Two ground rules, both inherited from the live-socket protocol:
+ * - every frame carries `v`, and an end that sees a version it does not speak ignores the frame;
+ * - bigints cross as decimal strings, because they do not survive JSON and structured clone is not
+ *   guaranteed by every path a frame may take.
+ *
+ * The trust story is deliberately asymmetric. The game learns exactly one thing from its URL — the
+ * embedding page's origin, `?parentOrigin=` — because it needs that BEFORE any message can be
+ * trusted. Everything else (which gate, which round, which coin) arrives in `gm:context`, so there
+ * is one source of truth and it is the page the player is actually looking at.
+ */
+export const FRAME_PROTOCOL_VERSION = 1;
+const BUY_FAILURES = [
+    'nothing-to-spend',
+    'declined',
+    'not-enough-for-fees',
+    'window-closed',
+    'try-again',
+];
+const HOST_ERROR_CODES = ['declined', 'no-wallet', 'not-allowed', 'failed'];
+const isRecord = (value) => typeof value === 'object' && value !== null;
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+function authorisationFrom(value) {
+    if (!isRecord(value))
+        return null;
+    const { buyer, poolId, deadline, maxSpendWei, nonce, signature, signer, hookData } = value;
+    for (const field of [buyer, poolId, deadline, maxSpendWei, nonce, signature, signer]) {
+        if (!isNonEmptyString(field))
+            return null;
+    }
+    if (hookData !== undefined && !(typeof hookData === 'string' && hookData.startsWith('0x')))
+        return null;
+    return {
+        buyer: buyer,
+        poolId: poolId,
+        deadline: deadline,
+        maxSpendWei: maxSpendWei,
+        nonce: nonce,
+        signature: signature,
+        signer: signer,
+        ...(hookData !== undefined ? { hookData: hookData } : {}),
+    };
+}
+function callFrom(value) {
+    if (!isRecord(value))
+        return null;
+    if (value.method === 'address')
+        return { method: 'address' };
+    if (value.method === 'signIn') {
+        return isNonEmptyString(value.message) ? { method: 'signIn', message: value.message } : null;
+    }
+    if (value.method === 'buy') {
+        const authorisation = authorisationFrom(value.authorisation);
+        return authorisation ? { method: 'buy', authorisation } : null;
+    }
+    return null;
+}
+/** A frame from the game, or null for anything malformed or from another protocol version. */
+export function gameFrameFrom(input) {
+    if (!isRecord(input) || input.v !== FRAME_PROTOCOL_VERSION)
+        return null;
+    if (input.type === 'gm:hello')
+        return { v: FRAME_PROTOCOL_VERSION, type: 'gm:hello' };
+    if (input.type === 'gm:req') {
+        if (!isNonEmptyString(input.id))
+            return null;
+        const call = callFrom(input.call);
+        return call ? { v: FRAME_PROTOCOL_VERSION, type: 'gm:req', id: input.id, call } : null;
+    }
+    return null;
+}
+function contextFrom(value) {
+    if (!isRecord(value))
+        return null;
+    const { gateUrl, roundId, coinAddress, chainId, launch } = value;
+    if (!isNonEmptyString(gateUrl) || !isNonEmptyString(roundId) || !isNonEmptyString(coinAddress))
+        return null;
+    if (typeof chainId !== 'number' || !Number.isSafeInteger(chainId) || chainId <= 0)
+        return null;
+    // Launch context is validated shallowly: it is display data a live gate re-sends authoritatively
+    // in its first snapshot, so a malformed one costs a blank header, not a wrong decision.
+    if (launch !== undefined && !isRecord(launch))
+        return null;
+    return {
+        gateUrl,
+        roundId,
+        coinAddress,
+        chainId,
+        ...(launch !== undefined ? { launch: launch } : {}),
+    };
+}
+function resultFrom(value) {
+    if (!isRecord(value))
+        return null;
+    if (value.method === 'address') {
+        return value.address === null || isNonEmptyString(value.address)
+            ? { method: 'address', address: value.address }
+            : null;
+    }
+    if (value.method === 'signIn') {
+        return typeof value.signature === 'string' && value.signature.startsWith('0x')
+            ? { method: 'signIn', signature: value.signature }
+            : null;
+    }
+    if (value.method === 'buy') {
+        const outcome = value.outcome;
+        if (!isRecord(outcome))
+            return null;
+        if (isNonEmptyString(outcome.spentWei))
+            return { method: 'buy', outcome: { spentWei: outcome.spentWei } };
+        const failed = outcome.failed;
+        if (isRecord(failed) && failed.bought === false && BUY_FAILURES.includes(failed.reason)) {
+            return { method: 'buy', outcome: { failed: { bought: false, reason: failed.reason } } };
+        }
+        return null;
+    }
+    return null;
+}
+/** A frame from the page, or null for anything malformed or from another protocol version. */
+export function hostFrameFrom(input) {
+    if (!isRecord(input) || input.v !== FRAME_PROTOCOL_VERSION)
+        return null;
+    if (input.type === 'gm:context') {
+        const context = contextFrom(input.context);
+        return context ? { v: FRAME_PROTOCOL_VERSION, type: 'gm:context', context } : null;
+    }
+    if (input.type === 'gm:progress') {
+        if (!isNonEmptyString(input.id) || !isRecord(input.progress))
+            return null;
+        const { state, transactionHash } = input.progress;
+        if (state !== 'pending')
+            return null;
+        if (transactionHash !== undefined && !isNonEmptyString(transactionHash))
+            return null;
+        return {
+            v: FRAME_PROTOCOL_VERSION,
+            type: 'gm:progress',
+            id: input.id,
+            progress: { state: 'pending', ...(transactionHash !== undefined ? { transactionHash } : {}) },
+        };
+    }
+    if (input.type === 'gm:res') {
+        if (!isNonEmptyString(input.id))
+            return null;
+        if (input.ok === true) {
+            const result = resultFrom(input.result);
+            return result ? { v: FRAME_PROTOCOL_VERSION, type: 'gm:res', id: input.id, ok: true, result } : null;
+        }
+        if (input.ok === false) {
+            const error = input.error;
+            if (!isRecord(error))
+                return null;
+            if (!HOST_ERROR_CODES.includes(error.code) || typeof error.message !== 'string')
+                return null;
+            return {
+                v: FRAME_PROTOCOL_VERSION,
+                type: 'gm:res',
+                id: input.id,
+                ok: false,
+                error: { code: error.code, message: error.message },
+            };
+        }
+        return null;
+    }
+    return null;
+}
+//# sourceMappingURL=frame.js.map

package/dist/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flayerlabs/gamemode-spec",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pure rules, round, scheduling, live-room and embed contracts for Flaunch Game Modes",
   "license": "MIT",
   "author": "Flayer Labs",
@@ -36,6 +36,10 @@
       "types": "./dist/live.d.ts",
       "default": "./dist/live.js"
     },
+    "./frame": {
+      "types": "./dist/frame.d.ts",
+      "default": "./dist/frame.js"
+    },
     "./embed": {
       "types": "./dist/embed.d.ts",
       "default": "./dist/embed.js"

package/src/frame.ts

@@ -0,0 +1,244 @@
+import type { LaunchContext } from './live.js';
+
+/**
+ * The wire contract between a game iframe and the page embedding it.
+ *
+ * A game and its embedding page are different origins, so the `Host` object the client needs
+ * cannot be handed across directly — it is reconstructed over `postMessage` using these frames.
+ * The shapes live in spec because BOTH ends must agree while sharing no runtime: the game side is
+ * `@flayerlabs/gamemode-client`, and an embedding page may implement the parent side from these
+ * definitions alone.
+ *
+ * Two ground rules, both inherited from the live-socket protocol:
+ * - every frame carries `v`, and an end that sees a version it does not speak ignores the frame;
+ * - bigints cross as decimal strings, because they do not survive JSON and structured clone is not
+ *   guaranteed by every path a frame may take.
+ *
+ * The trust story is deliberately asymmetric. The game learns exactly one thing from its URL — the
+ * embedding page's origin, `?parentOrigin=` — because it needs that BEFORE any message can be
+ * trusted. Everything else (which gate, which round, which coin) arrives in `gm:context`, so there
+ * is one source of truth and it is the page the player is actually looking at.
+ */
+
+export const FRAME_PROTOCOL_VERSION = 1 as const;
+
+/**
+ * Why a buy did not happen, in terms a player can be told about.
+ *
+ * Deliberately a short list of plain outcomes rather than anything from the chain. A game should
+ * never render a revert string or an error code at a player: the client maps each of these to its
+ * own copy, and the copy is free to change without the meaning moving.
+ *
+ * Lives here rather than in the client because the embedding page produces these values and the
+ * game consumes them — the one enum both ends of the frame protocol must share.
+ */
+// One definition for every end: the live room owns BuyFailure, the frame re-exports it.
+import type { BuyFailure } from './live.js';
+export type { BuyFailure };
+
+/** Everything a game needs to join its round, told to it by the page rather than its URL. */
+export interface EmbedContext {
+  readonly gateUrl: string;
+  readonly roundId: string;
+  readonly coinAddress: string;
+  readonly chainId: number;
+  /** Optional — a live gate sends it in the first snapshot anyway. */
+  readonly launch?: LaunchContext;
+}
+
+/** Exactly what the gate signed, all strings because bigints do not survive JSON. */
+export interface WireAuthorisation {
+  buyer: string;
+  poolId: string;
+  deadline: string;
+  maxSpendWei: string;
+  nonce: string;
+  signature: string;
+  signer: string;
+  /** Opaque proof the page passes to the Flaunch buy call. Never calldata. */
+  hookData?: `0x${string}`;
+}
+
+export type HostCall =
+  | { method: 'address' }
+  | { method: 'signIn'; message: string }
+  | { method: 'buy'; authorisation: WireAuthorisation };
+
+export type GameToHostFrame =
+  | { v: typeof FRAME_PROTOCOL_VERSION; type: 'gm:hello' }
+  | { v: typeof FRAME_PROTOCOL_VERSION; type: 'gm:req'; id: string; call: HostCall };
+
+/**
+ * What a refusal means to the game: `declined` and `no-wallet` are player states a game can name;
+ * `not-allowed` is a call the page refuses to service; `failed` is everything else.
+ */
+export type HostErrorCode = 'declined' | 'no-wallet' | 'not-allowed' | 'failed';
+
+export type WireHostResult =
+  | { method: 'address'; address: string | null }
+  | { method: 'signIn'; signature: `0x${string}` }
+  | { method: 'buy'; outcome: { spentWei: string } | { failed: { bought: false; reason: BuyFailure } } };
+
+export type HostToGameFrame =
+  | { v: typeof FRAME_PROTOCOL_VERSION; type: 'gm:context'; context: EmbedContext }
+  | {
+      v: typeof FRAME_PROTOCOL_VERSION;
+      type: 'gm:progress';
+      id: string;
+      progress: { state: 'pending'; transactionHash?: string };
+    }
+  | { v: typeof FRAME_PROTOCOL_VERSION; type: 'gm:res'; id: string; ok: true; result: WireHostResult }
+  | {
+      v: typeof FRAME_PROTOCOL_VERSION;
+      type: 'gm:res';
+      id: string;
+      ok: false;
+      error: { code: HostErrorCode; message: string };
+    };
+
+const BUY_FAILURES: readonly BuyFailure[] = [
+  'nothing-to-spend',
+  'declined',
+  'not-enough-for-fees',
+  'window-closed',
+  'try-again',
+];
+
+const HOST_ERROR_CODES: readonly HostErrorCode[] = ['declined', 'no-wallet', 'not-allowed', 'failed'];
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const isNonEmptyString = (value: unknown): value is string => typeof value === 'string' && value.length > 0;
+
+function authorisationFrom(value: unknown): WireAuthorisation | null {
+  if (!isRecord(value)) return null;
+  const { buyer, poolId, deadline, maxSpendWei, nonce, signature, signer, hookData } = value;
+  for (const field of [buyer, poolId, deadline, maxSpendWei, nonce, signature, signer]) {
+    if (!isNonEmptyString(field)) return null;
+  }
+  if (hookData !== undefined && !(typeof hookData === 'string' && hookData.startsWith('0x'))) return null;
+  return {
+    buyer: buyer as string,
+    poolId: poolId as string,
+    deadline: deadline as string,
+    maxSpendWei: maxSpendWei as string,
+    nonce: nonce as string,
+    signature: signature as string,
+    signer: signer as string,
+    ...(hookData !== undefined ? { hookData: hookData as `0x${string}` } : {}),
+  };
+}
+
+function callFrom(value: unknown): HostCall | null {
+  if (!isRecord(value)) return null;
+  if (value.method === 'address') return { method: 'address' };
+  if (value.method === 'signIn') {
+    return isNonEmptyString(value.message) ? { method: 'signIn', message: value.message } : null;
+  }
+  if (value.method === 'buy') {
+    const authorisation = authorisationFrom(value.authorisation);
+    return authorisation ? { method: 'buy', authorisation } : null;
+  }
+  return null;
+}
+
+/** A frame from the game, or null for anything malformed or from another protocol version. */
+export function gameFrameFrom(input: unknown): GameToHostFrame | null {
+  if (!isRecord(input) || input.v !== FRAME_PROTOCOL_VERSION) return null;
+  if (input.type === 'gm:hello') return { v: FRAME_PROTOCOL_VERSION, type: 'gm:hello' };
+  if (input.type === 'gm:req') {
+    if (!isNonEmptyString(input.id)) return null;
+    const call = callFrom(input.call);
+    return call ? { v: FRAME_PROTOCOL_VERSION, type: 'gm:req', id: input.id, call } : null;
+  }
+  return null;
+}
+
+function contextFrom(value: unknown): EmbedContext | null {
+  if (!isRecord(value)) return null;
+  const { gateUrl, roundId, coinAddress, chainId, launch } = value;
+  if (!isNonEmptyString(gateUrl) || !isNonEmptyString(roundId) || !isNonEmptyString(coinAddress)) return null;
+  if (typeof chainId !== 'number' || !Number.isSafeInteger(chainId) || chainId <= 0) return null;
+  // Launch context is validated shallowly: it is display data a live gate re-sends authoritatively
+  // in its first snapshot, so a malformed one costs a blank header, not a wrong decision.
+  if (launch !== undefined && !isRecord(launch)) return null;
+  return {
+    gateUrl,
+    roundId,
+    coinAddress,
+    chainId,
+    ...(launch !== undefined ? { launch: launch as unknown as LaunchContext } : {}),
+  };
+}
+
+function resultFrom(value: unknown): WireHostResult | null {
+  if (!isRecord(value)) return null;
+  if (value.method === 'address') {
+    return value.address === null || isNonEmptyString(value.address)
+      ? { method: 'address', address: value.address as string | null }
+      : null;
+  }
+  if (value.method === 'signIn') {
+    return typeof value.signature === 'string' && value.signature.startsWith('0x')
+      ? { method: 'signIn', signature: value.signature as `0x${string}` }
+      : null;
+  }
+  if (value.method === 'buy') {
+    const outcome = value.outcome;
+    if (!isRecord(outcome)) return null;
+    if (isNonEmptyString(outcome.spentWei)) return { method: 'buy', outcome: { spentWei: outcome.spentWei } };
+    const failed = outcome.failed;
+    if (isRecord(failed) && failed.bought === false && BUY_FAILURES.includes(failed.reason as BuyFailure)) {
+      return { method: 'buy', outcome: { failed: { bought: false, reason: failed.reason as BuyFailure } } };
+    }
+    return null;
+  }
+  return null;
+}
+
+/** A frame from the page, or null for anything malformed or from another protocol version. */
+export function hostFrameFrom(input: unknown): HostToGameFrame | null {
+  if (!isRecord(input) || input.v !== FRAME_PROTOCOL_VERSION) return null;
+
+  if (input.type === 'gm:context') {
+    const context = contextFrom(input.context);
+    return context ? { v: FRAME_PROTOCOL_VERSION, type: 'gm:context', context } : null;
+  }
+
+  if (input.type === 'gm:progress') {
+    if (!isNonEmptyString(input.id) || !isRecord(input.progress)) return null;
+    const { state, transactionHash } = input.progress;
+    if (state !== 'pending') return null;
+    if (transactionHash !== undefined && !isNonEmptyString(transactionHash)) return null;
+    return {
+      v: FRAME_PROTOCOL_VERSION,
+      type: 'gm:progress',
+      id: input.id,
+      progress: { state: 'pending', ...(transactionHash !== undefined ? { transactionHash } : {}) },
+    };
+  }
+
+  if (input.type === 'gm:res') {
+    if (!isNonEmptyString(input.id)) return null;
+    if (input.ok === true) {
+      const result = resultFrom(input.result);
+      return result ? { v: FRAME_PROTOCOL_VERSION, type: 'gm:res', id: input.id, ok: true, result } : null;
+    }
+    if (input.ok === false) {
+      const error = input.error;
+      if (!isRecord(error)) return null;
+      if (!HOST_ERROR_CODES.includes(error.code as HostErrorCode) || typeof error.message !== 'string') return null;
+      return {
+        v: FRAME_PROTOCOL_VERSION,
+        type: 'gm:res',
+        id: input.id,
+        ok: false,
+        error: { code: error.code as HostErrorCode, message: error.message },
+      };
+    }
+    return null;
+  }
+
+  return null;
+}