@swarm-tips/client 0.1.1 → 0.2.1

package/dist/coordination-game/evm/session.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Ephemeral EVM session key — the Base-game analog of the Solana session
+ * keypair (`session.ts`). One main-wallet popup funds the session address with
+ * stake + gas; the session key then signs createGame/joinGame/commitGuess/
+ * revealGuess locally.
+ *
+ * Under the shipped v3 WALLET-AS-PLAYER design the session key is a gas-only
+ * DELEGATE, not the player: the wallet is `game.player1/2` on-chain, and the
+ * payout is credited to the wallet and realized with `withdrawFor`. There is
+ * therefore NO sweep, and no `evm-sweep.ts` — that file never existed under v3.
+ *
+ * The private key lives in sessionStorage (cleared on tab close) bound to the
+ * main wallet, with a 24h TTL — same guards as the Solana session. Only gas
+ * dust ever sits on the session address.
+ */
+import { type Chain, type Hex, type PublicClient, type WalletClient } from "viem";
+export interface SessionStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Generate a fresh ephemeral secp256k1 private key for session signing. */
+export declare function generateEvmSessionKey(): Hex;
+/**
+ * Read the session key from sessionStorage. Returns null if no session
+ * exists, the session has expired (24h TTL), or it belongs to a different
+ * main wallet. Any invalid stored value is removed.
+ */
+export declare function getStoredEvmSession(storage: SessionStorageLike, walletAddress?: string, now?: () => number): Hex | null;
+/** Persist the session key in sessionStorage, bound to the main wallet. */
+export declare function storeEvmSession(storage: SessionStorageLike, privateKey: Hex, walletAddress: string, now?: () => number): void;
+/** Remove the session key from sessionStorage. */
+export declare function clearEvmSession(storage: SessionStorageLike): void;
+/** Persist the committed guess preimage for `gameId` so a reload can still reveal. */
+export declare function persistEvmGuess(storage: SessionStorageLike, gameId: string, r: Uint8Array): void;
+/** The persisted preimage for `gameId`, or null (missing / different game /
+ *  unreadable). A mismatched gameId guards against revealing a stale guess. */
+export declare function loadEvmGuess(storage: SessionStorageLike, gameId: string): Uint8Array | null;
+/** Drop the persisted guess once the game is done. */
+export declare function clearEvmGuess(storage: SessionStorageLike): void;
+/** 0x address of a session private key. */
+export declare function evmSessionAddress(privateKey: Hex): Hex;
+/**
+ * A viem WalletClient signing with the session key against the SELECTED chain's
+ * failover RPCs. Structurally a `CallSender`, so it drops into the existing
+ * `sendUnsignedCall` / `sendContractCall` exactly where the wagmi wallet
+ * client used to go — the EVM analog of Solana's `getSessionProgram`. The chain
+ * is passed in (from the picker's selectedChain) so game txs land on the chain
+ * the player actually chose, not a hardcoded default.
+ */
+export declare function evmSessionClient(privateKey: Hex, chain: Chain, rpcUrls: string[]): WalletClient;
+/** Read-only client for the selected chain (balances, receipts). */
+export declare function evmReadClient(chain: Chain, rpcUrls: string[]): PublicClient;
+/**
+ * Sign a message with the session key locally (EIP-191 personal_sign) — used
+ * for the silent auth handshake and the funding-tx binding proof. No popup.
+ */
+export declare function signWithEvmSession(privateKey: Hex, message: string): Promise<Hex>;

package/dist/coordination-game/evm/session.js

@@ -0,0 +1,165 @@
+/**
+ * Ephemeral EVM session key — the Base-game analog of the Solana session
+ * keypair (`session.ts`). One main-wallet popup funds the session address with
+ * stake + gas; the session key then signs createGame/joinGame/commitGuess/
+ * revealGuess locally.
+ *
+ * Under the shipped v3 WALLET-AS-PLAYER design the session key is a gas-only
+ * DELEGATE, not the player: the wallet is `game.player1/2` on-chain, and the
+ * payout is credited to the wallet and realized with `withdrawFor`. There is
+ * therefore NO sweep, and no `evm-sweep.ts` — that file never existed under v3.
+ *
+ * The private key lives in sessionStorage (cleared on tab close) bound to the
+ * main wallet, with a 24h TTL — same guards as the Solana session. Only gas
+ * dust ever sits on the session address.
+ */
+import { bytesToHex, createPublicClient, createWalletClient, fallback, hexToBytes, http, } from "viem";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+const SESSION_KEY = "coordination-evm-session";
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const PRIVATE_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
+/** Generate a fresh ephemeral secp256k1 private key for session signing. */
+export function generateEvmSessionKey() {
+    return generatePrivateKey();
+}
+/**
+ * Read the session key from sessionStorage. Returns null if no session
+ * exists, the session has expired (24h TTL), or it belongs to a different
+ * main wallet. Any invalid stored value is removed.
+ */
+export function getStoredEvmSession(storage, walletAddress, now = Date.now) {
+    const raw = storage.getItem(SESSION_KEY);
+    if (raw === null)
+        return null;
+    let stored;
+    try {
+        stored = JSON.parse(raw);
+    }
+    catch {
+        storage.removeItem(SESSION_KEY);
+        return null;
+    }
+    if (typeof stored.privateKey !== "string" ||
+        !PRIVATE_KEY_RE.test(stored.privateKey) ||
+        typeof stored.createdAt !== "number" ||
+        typeof stored.wallet !== "string") {
+        storage.removeItem(SESSION_KEY);
+        return null;
+    }
+    if (walletAddress &&
+        stored.wallet.toLowerCase() !== walletAddress.toLowerCase()) {
+        storage.removeItem(SESSION_KEY);
+        return null;
+    }
+    if (now() - stored.createdAt > SESSION_TTL_MS) {
+        storage.removeItem(SESSION_KEY);
+        return null;
+    }
+    return stored.privateKey;
+}
+/** Persist the session key in sessionStorage, bound to the main wallet. */
+export function storeEvmSession(storage, privateKey, walletAddress, now = Date.now) {
+    const stored = {
+        privateKey,
+        createdAt: now(),
+        wallet: walletAddress,
+    };
+    storage.setItem(SESSION_KEY, JSON.stringify(stored));
+}
+/** Remove the session key from sessionStorage. */
+export function clearEvmSession(storage) {
+    storage.removeItem(SESSION_KEY);
+}
+// --- Committed-guess preimage persistence (the EVM analog of the Solana
+//     pendingR store). The preimage R is generated at commit and needed again at
+//     reveal; keeping it only in a React ref means a page reload mid-game strands
+//     the reveal. Persist it (keyed by gameId so a stale one from a prior game is
+//     never reused) in sessionStorage — same tab lifetime as the session key,
+//     and it never leaves the browser, so the commit-reveal anonymity barrier
+//     holds. ---
+const PENDING_GUESS_KEY = "coordination-evm-pending-guess";
+/** Persist the committed guess preimage for `gameId` so a reload can still reveal. */
+export function persistEvmGuess(storage, gameId, r) {
+    try {
+        storage.setItem(PENDING_GUESS_KEY, JSON.stringify({ gameId, r: bytesToHex(r) }));
+    }
+    catch (e) {
+        console.warn("[evm-session] guess persist failed (in-memory only)", e);
+    }
+}
+/** The persisted preimage for `gameId`, or null (missing / different game /
+ *  unreadable). A mismatched gameId guards against revealing a stale guess. */
+export function loadEvmGuess(storage, gameId) {
+    try {
+        const raw = storage.getItem(PENDING_GUESS_KEY);
+        if (raw === null)
+            return null;
+        const stored = JSON.parse(raw);
+        if (stored.gameId !== gameId || typeof stored.r !== "string")
+            return null;
+        return hexToBytes(stored.r);
+    }
+    catch (e) {
+        console.warn("[evm-session] guess load failed", e);
+        return null;
+    }
+}
+/** Drop the persisted guess once the game is done. */
+export function clearEvmGuess(storage) {
+    try {
+        storage.removeItem(PENDING_GUESS_KEY);
+    }
+    catch (e) {
+        console.debug("[evm-session] guess clear failed", e);
+    }
+}
+/** 0x address of a session private key. */
+export function evmSessionAddress(privateKey) {
+    return privateKeyToAccount(privateKey).address;
+}
+/**
+ * A viem WalletClient signing with the session key against the SELECTED chain's
+ * failover RPCs. Structurally a `CallSender`, so it drops into the existing
+ * `sendUnsignedCall` / `sendContractCall` exactly where the wagmi wallet
+ * client used to go — the EVM analog of Solana's `getSessionProgram`. The chain
+ * is passed in (from the picker's selectedChain) so game txs land on the chain
+ * the player actually chose, not a hardcoded default.
+ */
+export function evmSessionClient(privateKey, chain, rpcUrls) {
+    // No viem nonceManager: its counter advances optimistically and never rolls
+    // back, so a DROPPED Base Sepolia tx leaves a nonce GAP that stalls every
+    // later send ("creator's createGame timed out"). Nonce consistency + drop
+    // recovery are handled at the send site instead — see sendConfirmedTx: it
+    // reads the nonce from a single PINNED RPC (consistent, no stale-low race) and
+    // resubmits with the freed nonce if a tx drops.
+    const account = privateKeyToAccount(privateKey);
+    // Name the SIGNER. Game failures surface as "the total cost ... exceeds the
+    // balance of the account" labelled with the PLAYER's address, which is not the
+    // account that pays — the session key is. Without this line the two are
+    // indistinguishable in a log, and a session funded at one address while
+    // signing from another looks identical to a session that was never funded.
+    console.info("[evm-session] signing client", {
+        sessionAddr: account.address,
+        chainId: chain.id,
+        rpcCount: rpcUrls.length,
+    });
+    return createWalletClient({
+        account,
+        chain,
+        transport: fallback(rpcUrls.map((u) => http(u))),
+    });
+}
+/** Read-only client for the selected chain (balances, receipts). */
+export function evmReadClient(chain, rpcUrls) {
+    return createPublicClient({
+        chain,
+        transport: fallback(rpcUrls.map((u) => http(u))),
+    });
+}
+/**
+ * Sign a message with the session key locally (EIP-191 personal_sign) — used
+ * for the silent auth handshake and the funding-tx binding proof. No popup.
+ */
+export function signWithEvmSession(privateKey, message) {
+    return privateKeyToAccount(privateKey).signMessage({ message });
+}

package/dist/coordination-game/evm/transactions.d.ts

@@ -0,0 +1,137 @@
+import { type Abi, type Chain, type Hex, type PublicClient, type TransactionReceipt } from "viem";
+/** What sendConfirmedTx needs from a signer — the session wallet client satisfies
+ *  it; tests pass a mock. */
+export interface TxSender {
+    account: {
+        address: Hex;
+    };
+    sendTransaction: (args: Record<string, unknown>) => Promise<Hex>;
+}
+/** What sendConfirmedTx needs from a read client PINNED to one RPC (so nonce
+ *  reads are monotonic — the fallback set's pending-nonce views disagree). */
+export interface PinnedReader {
+    getTransactionCount: (args: {
+        address: Hex;
+        blockTag: "pending";
+    }) => Promise<number>;
+    getTransactionReceipt: (args: {
+        hash: Hex;
+    }) => Promise<TransactionReceipt>;
+    estimateFeesPerGas: () => Promise<{
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    }>;
+}
+/** A read client over ALL rpcUrls (viem `fallback`) used ONLY for an authoritative
+ *  receipt re-check when the pinned poll lags — the receipt is chain state, so any
+ *  RPC that has it is correct (unlike the nonce, which must stay pinned). */
+export interface FallbackReader {
+    getTransactionReceipt: (args: {
+        hash: Hex;
+    }) => Promise<TransactionReceipt>;
+}
+/** A read client pinned to a SINGLE rpc — never the fallback set, whose rotation
+ *  between nodes with disagreeing pending-nonce views is what produces stale-low
+ *  "nonce lower than current" reverts. */
+export declare function pinnedGameReader(chain: Chain, rpcUrls: string[]): PublicClient;
+/**
+ * Send a game tx (session-key signed) and CONFIRM it, resilient to Base Sepolia's
+ * two testnet flakes with NO test-level retry — the real system handling the load:
+ *
+ *  - INCONSISTENT NONCE: the session wallet's `fallback` transport reads the nonce
+ *    from whichever RPC it lands on, and their pending-nonce views disagree → a
+ *    stale-LOW read reverts "nonce lower than the current nonce". We read the
+ *    nonce ONCE from a single pinned reader and reuse it for every resubmit, so it
+ *    is consistent and every resubmit REPLACES the same intent (never a second
+ *    game). (viem's nonceManager can't be used: its counter advances optimistically
+ *    and never rolls back, so a dropped tx leaves a permanent gap.)
+ *  - DROPPED TX: Base Sepolia silently drops txs; a single send then never mines
+ *    and the game stalls ("creator's createGame timed out"). If the tx is not
+ *    included within `confirmMs`, resubmit at the SAME nonce with bumped fees — a
+ *    replacement that fills the freed slot (dropped) or supersedes it (stuck).
+ *  - LAGGY PINNED RECEIPT RPC (mainnet): the pinned nonce reader is a single RPC
+ *    (`rpcUrls[0]`), and on mainnet that one endpoint rate-limits / lags on
+ *    `getTransactionReceipt` — so a tx that MINED (createGame/commit/reveal all
+ *    succeeded on-chain) still times out the pinned poll and the game stalls. The
+ *    receipt is chain state, not nonce state, so before declaring failure we do
+ *    ONE authoritative re-check over `fallbackReader` (all rpcUrls); a success
+ *    there means the tx landed and we return it instead of a false failure.
+ *
+ * Returns the successful receipt; throws on a real revert or after `attempts`.
+ */
+export declare function sendConfirmedTx(wallet: TxSender, pinned: PinnedReader, chain: Chain, call: {
+    to: Hex;
+    data: Hex;
+    value: bigint;
+}, label: string, { attempts, confirmMs, pollMs, }?: {
+    attempts?: number;
+    confirmMs?: number;
+    pollMs?: number;
+}, fallbackReader?: FallbackReader): Promise<TransactionReceipt>;
+/** Convenience: build the session wallet + pinned reader for a game and confirm a
+ *  raw {to,data,value} call. */
+export declare function sendConfirmedGameTx(sessionKey: Hex, chain: Chain, rpcUrls: string[], call: {
+    to: Hex;
+    data: Hex;
+    value: bigint;
+}, label: string): Promise<TransactionReceipt>;
+/** CoordinationGame.sol Status enum: None=0, Pending=1, Active=2, Committing=3,
+ *  Revealing=4, Resolved=5. Any value >= 1 means the game EXISTS on-chain. */
+export declare function gameStatusExists(status: number): boolean;
+/**
+ * Whether the "matched" phase should auto-fire `fund()` (create/join) with no
+ * manual button. The stake is ALREADY escrowed at the queue's one popup, so
+ * create/join is popup-less — there is nothing for the player to confirm and a
+ * "Create game"/"Join game" button is pure friction (mirrors Solana, where P1
+ * now creates silently via the session key). Fires exactly once per game:
+ *  - only at "matched" (before it, there is no game to fund; after, it is done),
+ *  - only once every precondition the tx needs is present (wallet/session ready),
+ *  - only if this game_id hasn't already been auto-funded (guards React
+ *    re-renders + strict-mode double-invoke; a NEW match re-arms it).
+ * Pure so the gating is unit-testable without a wallet or chain.
+ */
+export declare function shouldAutoFund(args: {
+    phase: string;
+    gameId: string | undefined;
+    ready: boolean;
+    lastFundedGameId: string | null;
+}): boolean;
+/**
+ * Whether the game already EXISTS on-chain — reads `games(gameId).status` over
+ * the chain's RPC fallbacks (the same read path the hook uses elsewhere) and
+ * decodes status >= 1. This verifies the on-chain EFFECT of createGame, which is
+ * authoritative when the receipt poll is not: on mainnet the createGame tx can
+ * MINE (game created + joinable) while the RPC lags on returning its receipt, so
+ * a receipt-poll timeout does NOT mean the game wasn't created.
+ */
+export declare function gameExistsOnChain(contract: Hex, gameId: Hex, chain: Chain, rpcUrls: string[]): Promise<boolean>;
+/**
+ * Send createGame and CONFIRM its on-chain EFFECT, not just its receipt.
+ *
+ * WHY: mainnet RPC receipt-fetch lag makes sendConfirmedTx's receipt poll time
+ * out ("createGame did not confirm after N attempts") even though the tx MINED
+ * and the game is created + joinable on-chain. Trusting only the receipt strands
+ * the browser before chat (chat-input never enables). Verifying the on-chain
+ * effect is authoritative. This supersedes the reverted selector-matching
+ * approach, which couldn't see the selector once sendConfirmedTx flattened the
+ * error to a message string.
+ *
+ * Both deps are injected so the send/detect decision is unit-testable with no
+ * chain: `send` performs the tx (throws on a receipt-poll timeout OR a real
+ * failure), `gameExists` reads games(gameId).status. Returns "sent" on a normal
+ * confirm, "recovered" when the send threw but the game exists on-chain (proceed
+ * anyway); re-throws only when the send threw AND the game is not on-chain.
+ */
+export declare function sendCreateGameConfirmingEffect(send: () => Promise<unknown>, gameExists: () => Promise<boolean>): Promise<"sent" | "recovered">;
+/**
+ * Send a game CONTRACT call (session-key signed) and CONFIRM it. Encodes the call
+ * and routes through sendConfirmedTx, so every game tx — createGame, joinGame,
+ * commitGuess, revealGuess, resolveTimeout — gets the same confirm-or-replace
+ * resilience instead of a fire-and-wait that stranded games on Base Sepolia.
+ */
+export declare function sendAndConfirm(sessionKey: Hex, chain: Chain, rpcUrls: string[], call: {
+    abi: Abi;
+    functionName: string;
+    args: readonly unknown[];
+    to: Hex;
+}, label: string): Promise<void>;

package/dist/coordination-game/evm/transactions.js

@@ -0,0 +1,211 @@
+import { createPublicClient, encodeFunctionData, http, } from "viem";
+import { evmReadClient, evmSessionClient } from "./session.js";
+import { COORDINATION_GAME_ABI } from "./abi.js";
+/** A read client pinned to a SINGLE rpc — never the fallback set, whose rotation
+ *  between nodes with disagreeing pending-nonce views is what produces stale-low
+ *  "nonce lower than current" reverts. */
+export function pinnedGameReader(chain, rpcUrls) {
+    return createPublicClient({ chain, transport: http(rpcUrls[0]) });
+}
+async function bumpedFees(pinned, attempt) {
+    const { maxFeePerGas, maxPriorityFeePerGas } = await pinned.estimateFeesPerGas();
+    // +25% per resubmit — viem rejects a same-nonce replacement at equal fees.
+    const mul = BigInt(100 + 25 * attempt);
+    return {
+        maxFeePerGas: maxFeePerGas ? (maxFeePerGas * mul) / 100n : undefined,
+        maxPriorityFeePerGas: maxPriorityFeePerGas
+            ? (maxPriorityFeePerGas * mul) / 100n
+            : undefined,
+    };
+}
+async function pollReceipt(pinned, hash, confirmMs, pollMs) {
+    for (let i = 0; i < Math.ceil(confirmMs / pollMs); i++) {
+        try {
+            return await pinned.getTransactionReceipt({ hash });
+        }
+        catch {
+            // not mined yet
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    return null;
+}
+/**
+ * Send a game tx (session-key signed) and CONFIRM it, resilient to Base Sepolia's
+ * two testnet flakes with NO test-level retry — the real system handling the load:
+ *
+ *  - INCONSISTENT NONCE: the session wallet's `fallback` transport reads the nonce
+ *    from whichever RPC it lands on, and their pending-nonce views disagree → a
+ *    stale-LOW read reverts "nonce lower than the current nonce". We read the
+ *    nonce ONCE from a single pinned reader and reuse it for every resubmit, so it
+ *    is consistent and every resubmit REPLACES the same intent (never a second
+ *    game). (viem's nonceManager can't be used: its counter advances optimistically
+ *    and never rolls back, so a dropped tx leaves a permanent gap.)
+ *  - DROPPED TX: Base Sepolia silently drops txs; a single send then never mines
+ *    and the game stalls ("creator's createGame timed out"). If the tx is not
+ *    included within `confirmMs`, resubmit at the SAME nonce with bumped fees — a
+ *    replacement that fills the freed slot (dropped) or supersedes it (stuck).
+ *  - LAGGY PINNED RECEIPT RPC (mainnet): the pinned nonce reader is a single RPC
+ *    (`rpcUrls[0]`), and on mainnet that one endpoint rate-limits / lags on
+ *    `getTransactionReceipt` — so a tx that MINED (createGame/commit/reveal all
+ *    succeeded on-chain) still times out the pinned poll and the game stalls. The
+ *    receipt is chain state, not nonce state, so before declaring failure we do
+ *    ONE authoritative re-check over `fallbackReader` (all rpcUrls); a success
+ *    there means the tx landed and we return it instead of a false failure.
+ *
+ * Returns the successful receipt; throws on a real revert or after `attempts`.
+ */
+export async function sendConfirmedTx(wallet, pinned, chain, call, label, { attempts = 4, confirmMs = 30_000, pollMs = 3_000, } = {}, fallbackReader) {
+    const address = wallet.account.address;
+    // ONE nonce for all attempts — reusing it makes every resubmit a replacement of
+    // the same intent, never a second on-chain action.
+    const nonce = await pinned.getTransactionCount({ address, blockTag: "pending" });
+    let lastHash;
+    let lastErr;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            lastHash = await wallet.sendTransaction({
+                ...call,
+                chain,
+                nonce,
+                ...(i > 0 ? await bumpedFees(pinned, i) : {}),
+            });
+        }
+        catch (e) {
+            // A resubmit can bounce with "nonce too low" (the prior send already mined)
+            // or "already known" / "replacement underpriced" (in flight). None is
+            // terminal — poll the hash we already have instead of failing.
+            lastErr = e;
+            if (!lastHash)
+                throw e;
+        }
+        const receipt = await pollReceipt(pinned, lastHash, confirmMs, pollMs);
+        if (receipt) {
+            if (receipt.status !== "success") {
+                throw new Error(`${label} tx ${lastHash} reverted on-chain`);
+            }
+            return receipt;
+        }
+        console.warn(`[evm-tx] ${label} not mined in ${confirmMs}ms (attempt ${i + 1}/${attempts}) — resubmitting at nonce ${nonce} with bumped fees`, { hash: lastHash });
+    }
+    // The pinned poll (single rpcUrls[0]) exhausted every attempt — but on mainnet
+    // that one RPC lags on receipts, so the tx may have MINED. Do one authoritative
+    // re-check over the fallback set before declaring failure.
+    if (lastHash && fallbackReader) {
+        const receipt = await fallbackReader
+            .getTransactionReceipt({ hash: lastHash })
+            .catch(() => null);
+        if (receipt) {
+            if (receipt.status !== "success") {
+                throw new Error(`${label} tx ${lastHash} reverted on-chain`);
+            }
+            console.info("[evm-tx] " + label + " confirmed via fallback receipt read after pinned poll lag", {
+                hash: lastHash,
+            });
+            return receipt;
+        }
+    }
+    throw new Error(`${label} did not confirm after ${attempts} attempts (last tx ${lastHash ?? "none"})` +
+        (lastErr ? `: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}` : ""));
+}
+/** Convenience: build the session wallet + pinned reader for a game and confirm a
+ *  raw {to,data,value} call. */
+export function sendConfirmedGameTx(sessionKey, chain, rpcUrls, call, label) {
+    return sendConfirmedTx(evmSessionClient(sessionKey, chain, rpcUrls), pinnedGameReader(chain, rpcUrls), chain, call, label, undefined, 
+    // Fallback over ALL rpcUrls — authoritative receipt re-check when the single
+    // pinned rpc lags. The nonce stays pinned; only the final receipt is fallback.
+    evmReadClient(chain, rpcUrls));
+}
+/** CoordinationGame.sol Status enum: None=0, Pending=1, Active=2, Committing=3,
+ *  Revealing=4, Resolved=5. Any value >= 1 means the game EXISTS on-chain. */
+export function gameStatusExists(status) {
+    return status >= 1;
+}
+/**
+ * Whether the "matched" phase should auto-fire `fund()` (create/join) with no
+ * manual button. The stake is ALREADY escrowed at the queue's one popup, so
+ * create/join is popup-less — there is nothing for the player to confirm and a
+ * "Create game"/"Join game" button is pure friction (mirrors Solana, where P1
+ * now creates silently via the session key). Fires exactly once per game:
+ *  - only at "matched" (before it, there is no game to fund; after, it is done),
+ *  - only once every precondition the tx needs is present (wallet/session ready),
+ *  - only if this game_id hasn't already been auto-funded (guards React
+ *    re-renders + strict-mode double-invoke; a NEW match re-arms it).
+ * Pure so the gating is unit-testable without a wallet or chain.
+ */
+export function shouldAutoFund(args) {
+    return (args.phase === "matched" &&
+        !!args.gameId &&
+        args.ready &&
+        args.lastFundedGameId !== args.gameId);
+}
+/**
+ * Whether the game already EXISTS on-chain — reads `games(gameId).status` over
+ * the chain's RPC fallbacks (the same read path the hook uses elsewhere) and
+ * decodes status >= 1. This verifies the on-chain EFFECT of createGame, which is
+ * authoritative when the receipt poll is not: on mainnet the createGame tx can
+ * MINE (game created + joinable) while the RPC lags on returning its receipt, so
+ * a receipt-poll timeout does NOT mean the game wasn't created.
+ */
+export async function gameExistsOnChain(contract, gameId, chain, rpcUrls) {
+    const game = (await evmReadClient(chain, rpcUrls).readContract({
+        address: contract,
+        abi: COORDINATION_GAME_ABI,
+        functionName: "games",
+        args: [gameId],
+    }));
+    return gameStatusExists(Number(game[0]));
+}
+/**
+ * Send createGame and CONFIRM its on-chain EFFECT, not just its receipt.
+ *
+ * WHY: mainnet RPC receipt-fetch lag makes sendConfirmedTx's receipt poll time
+ * out ("createGame did not confirm after N attempts") even though the tx MINED
+ * and the game is created + joinable on-chain. Trusting only the receipt strands
+ * the browser before chat (chat-input never enables). Verifying the on-chain
+ * effect is authoritative. This supersedes the reverted selector-matching
+ * approach, which couldn't see the selector once sendConfirmedTx flattened the
+ * error to a message string.
+ *
+ * Both deps are injected so the send/detect decision is unit-testable with no
+ * chain: `send` performs the tx (throws on a receipt-poll timeout OR a real
+ * failure), `gameExists` reads games(gameId).status. Returns "sent" on a normal
+ * confirm, "recovered" when the send threw but the game exists on-chain (proceed
+ * anyway); re-throws only when the send threw AND the game is not on-chain.
+ */
+export async function sendCreateGameConfirmingEffect(send, gameExists) {
+    try {
+        await send();
+        return "sent";
+    }
+    catch (e) {
+        // gameExists() reads games() over the RPC fallback, which can transiently
+        // revert on a lagging node. A read failure must NOT mask the REAL createGame
+        // error (that turned a plain revert into a confusing "games() reverted" that
+        // hid the actual cause): default to "not confirmed" and re-throw the original.
+        let exists = false;
+        try {
+            exists = await gameExists();
+        }
+        catch {
+            exists = false;
+        }
+        if (exists)
+            return "recovered";
+        throw e;
+    }
+}
+/**
+ * Send a game CONTRACT call (session-key signed) and CONFIRM it. Encodes the call
+ * and routes through sendConfirmedTx, so every game tx — createGame, joinGame,
+ * commitGuess, revealGuess, resolveTimeout — gets the same confirm-or-replace
+ * resilience instead of a fire-and-wait that stranded games on Base Sepolia.
+ */
+export async function sendAndConfirm(sessionKey, chain, rpcUrls, call, label) {
+    const data = encodeFunctionData({
+        abi: call.abi,
+        functionName: call.functionName,
+        args: call.args,
+    });
+    await sendConfirmedGameTx(sessionKey, chain, rpcUrls, { to: call.to, data, value: 0n }, label);
+}

package/dist/coordination-game/index.d.ts

@@ -2,3 +2,4 @@ export { COORDINATION_GAME_IDL, COORDINATION_GAME_IDL as IDL, COORDINATION_GAME_
 export type { CoordinationGame } from "../contracts/index.js";
 export * from "./outcome-oracle.js";
 export * from "./battery.js";
+export * from "./protocol.js";

package/dist/coordination-game/index.js

@@ -1,3 +1,4 @@
 export { COORDINATION_GAME_IDL, COORDINATION_GAME_IDL as IDL, COORDINATION_GAME_PROGRAM_ID, } from "../contracts/index.js";
 export * from "./outcome-oracle.js";
 export * from "./battery.js";
+export * from "./protocol.js";

package/dist/coordination-game/protocol.d.ts

@@ -0,0 +1,58 @@
+import { PublicKey } from "@solana/web3.js";
+export declare const COORDINATION_GAME_TOURNAMENT_ID = 1n;
+export declare const GUESS_UNREVEALED = 255;
+export declare const REVEAL_TIMEOUT_SLOTS = 14400n;
+export declare function toGuessBit(value: number): 0 | 1;
+export declare function u64LE(value: bigint): Uint8Array;
+export declare function globalConfigPda(id?: PublicKey | string): [PublicKey, number];
+export declare function gameCounterPda(id?: PublicKey | string): [PublicKey, number];
+export declare function gamePda(gameId: bigint, id?: PublicKey | string): [PublicKey, number];
+export declare function tournamentPda(tournamentId: bigint, id?: PublicKey | string): [PublicKey, number];
+export declare function playerProfilePda(tournamentId: bigint, wallet: PublicKey, id?: PublicKey | string): [PublicKey, number];
+export declare function escrowPda(tournamentId: bigint, wallet: PublicKey, id?: PublicKey | string): [PublicKey, number];
+export declare function playerSessionPda(wallet: PublicKey, session: PublicKey, id?: PublicKey | string): [PublicKey, number];
+export interface GlobalConfigData {
+    authority: PublicKey;
+    matchmaker: PublicKey;
+    treasury: PublicKey;
+    treasurySplitBps: number;
+    stakeLamports: bigint;
+}
+export interface TournamentData {
+    tournamentId: bigint;
+    startTime: bigint;
+    endTime: bigint;
+    prizeLamports: bigint;
+    gameCount: bigint;
+    finalized: boolean;
+}
+export declare function decodeGlobalConfig(data: Uint8Array): GlobalConfigData;
+export declare function decodeTournament(data: Uint8Array): TournamentData;
+export declare function decodeTournamentStats(data: Uint8Array): {
+    gameCount: number;
+    prizeLamports: bigint;
+};
+export interface SolanaResumeGame {
+    state: string;
+    playerOne: string;
+    playerTwo: string;
+    p1Commit: readonly number[] | Uint8Array;
+    p2Commit: readonly number[] | Uint8Array;
+    p1Guess: number;
+    p2Guess: number;
+}
+export interface SolanaResumeState {
+    phase: "active" | "committing" | "revealing";
+    iAmP1: boolean;
+    bothCommitted: boolean;
+}
+export declare function deriveSolanaResumeState(game: SolanaResumeGame, wallet: string): SolanaResumeState | null;
+export interface SolanaGameTimes {
+    state: string;
+    activatedAtSlot: bigint;
+    p1CommitSlot: bigint;
+    p2CommitSlot: bigint;
+    commitTimeoutSlots: bigint;
+}
+export declare function timeoutDeadlineSlot(game: SolanaGameTimes): bigint | null;
+export declare function timeoutClaimableAtSlot(game: SolanaGameTimes, currentSlot: bigint): boolean;