@swarm-tips/client 0.1.1 → 0.2.1

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

@@ -0,0 +1,371 @@
+/**
+ * Minimal CrossChainGame ABI for client-side EVM-leg calls (viem
+ * encodeFunctionData). Vendored from the Foundry artifact
+ * (swarm-tips-repo/evm/out/CrossChainGame.sol/CrossChainGame.json) — only the
+ * functions the cross-chain match UX needs: fund (createMatch), refund
+ * (refundTimeout/refundNoCert), and the read views (stakeWei, CHAIN_TAG,
+ * matches). Settle is permissionless and operator/harness-driven, so it is not
+ * vendored here. Regenerate if the contract ABI changes.
+ */
+export const CROSS_CHAIN_GAME_ABI = [
+    {
+        "type": "function",
+        "name": "CHAIN_TAG",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "bytes32",
+                "internalType": "bytes32"
+            }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "createMatch",
+        "inputs": [
+            {
+                "name": "matchId",
+                "type": "bytes32",
+                "internalType": "bytes32"
+            },
+            {
+                "name": "sessionKey",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "counterSessionKey",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "playerIsP1",
+                "type": "bool",
+                "internalType": "bool"
+            },
+            {
+                "name": "fundDeadline",
+                "type": "uint64",
+                "internalType": "uint64"
+            },
+            {
+                "name": "matchDeadline",
+                "type": "uint64",
+                "internalType": "uint64"
+            },
+            {
+                "name": "operatorSig",
+                "type": "bytes",
+                "internalType": "bytes"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "payable"
+    },
+    {
+        "type": "function",
+        "name": "matches",
+        "inputs": [
+            {
+                "name": "",
+                "type": "bytes32",
+                "internalType": "bytes32"
+            }
+        ],
+        "outputs": [
+            {
+                "name": "status",
+                "type": "uint8",
+                "internalType": "enum CrossChainGame.Status"
+            },
+            {
+                "name": "player",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "sessionKey",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "counterSessionKey",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "playerIsP1",
+                "type": "bool",
+                "internalType": "bool"
+            },
+            {
+                "name": "localEquivocated",
+                "type": "bool",
+                "internalType": "bool"
+            },
+            {
+                "name": "counterEquivocated",
+                "type": "bool",
+                "internalType": "bool"
+            },
+            {
+                "name": "stakeWei",
+                "type": "uint128",
+                "internalType": "uint128"
+            },
+            {
+                "name": "trancheWei",
+                "type": "uint128",
+                "internalType": "uint128"
+            },
+            {
+                "name": "fundDeadline",
+                "type": "uint64",
+                "internalType": "uint64"
+            },
+            {
+                "name": "matchDeadline",
+                "type": "uint64",
+                "internalType": "uint64"
+            },
+            {
+                "name": "lockedAt",
+                "type": "uint64",
+                "internalType": "uint64"
+            },
+            {
+                "name": "claimWindowEnd",
+                "type": "uint64",
+                "internalType": "uint64"
+            },
+            {
+                "name": "matchLiveDigest",
+                "type": "bytes32",
+                "internalType": "bytes32"
+            },
+            {
+                "name": "bestStepCount",
+                "type": "uint8",
+                "internalType": "uint8"
+            },
+            {
+                "name": "bestOutcomeKind",
+                "type": "uint8",
+                "internalType": "uint8"
+            }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "refundNoCert",
+        "inputs": [
+            {
+                "name": "matchId",
+                "type": "bytes32",
+                "internalType": "bytes32"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "function",
+        "name": "refundTimeout",
+        "inputs": [
+            {
+                "name": "matchId",
+                "type": "bytes32",
+                "internalType": "bytes32"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "function",
+        "name": "stakeWei",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint128",
+                "internalType": "uint128"
+            }
+        ],
+        "stateMutability": "view"
+    }
+];
+/**
+ * Minimal CoordinationGame ABI for the same-chain EVM-vs-EVM /play flow. Vendored
+ * from swarm-tips-repo/evm/out/CoordinationGame.sol/CoordinationGame.json — only
+ * the gameplay functions the browser builds + sends itself (commitGuess,
+ * revealGuess). createGame/joinGame come pre-encoded from game-api (as
+ * create_call/join_call), so they aren't needed for client-side encoding, but
+ * are vendored for completeness/verification. Regenerate if the ABI changes.
+ */
+export const COORDINATION_GAME_ABI = [
+    {
+        "type": "function",
+        "name": "createGame",
+        "inputs": [
+            { "name": "gameId", "type": "bytes32", "internalType": "bytes32" },
+            { "name": "matchupCommitment", "type": "bytes32", "internalType": "bytes32" },
+            { "name": "operatorSig", "type": "bytes", "internalType": "bytes" },
+            { "name": "player", "type": "address", "internalType": "address" }
+        ],
+        "outputs": [],
+        "stateMutability": "payable"
+    },
+    {
+        "type": "function",
+        "name": "joinGame",
+        "inputs": [
+            { "name": "gameId", "type": "bytes32", "internalType": "bytes32" },
+            { "name": "player", "type": "address", "internalType": "address" }
+        ],
+        "outputs": [],
+        "stateMutability": "payable"
+    },
+    {
+        // Wallet-as-player: the wallet calls this ONCE to register its gas-only
+        // session key AND fund it (msg.value = gas + stake buffer forwarded to the
+        // sessionKey EOA) — the single popup that opens a session.
+        "type": "function",
+        "name": "openSession",
+        "inputs": [
+            { "name": "sessionKey", "type": "address", "internalType": "address" },
+            { "name": "expiry", "type": "uint64", "internalType": "uint64" }
+        ],
+        "outputs": [],
+        "stateMutability": "payable"
+    },
+    {
+        // Opens the session AND escrows the stake in ONE transaction: `gasAmount`
+        // is forwarded to the session EOA, the remainder is credited to
+        // withdrawable[msg.sender] for createGame/joinGame to debit at value 0.
+        // This is the entry point the browser uses; plain openSession above is kept
+        // for grok-agent (own EOA, no session key) and any un-migrated client.
+        "type": "function",
+        "name": "openSessionAndDeposit",
+        "inputs": [
+            { "name": "sessionKey", "type": "address", "internalType": "address" },
+            { "name": "expiry", "type": "uint64", "internalType": "uint64" },
+            { "name": "gasAmount", "type": "uint256", "internalType": "uint256" }
+        ],
+        "outputs": [],
+        "stateMutability": "payable"
+    },
+    {
+        // Credit the caller's own escrow balance. Not used by the browser (which
+        // uses openSessionAndDeposit), vendored so the ledger surface is complete.
+        "type": "function",
+        "name": "deposit",
+        "inputs": [],
+        "outputs": [],
+        "stateMutability": "payable"
+    },
+    {
+        // Permissionless push of `to`'s credited winnings to `to` — the session key
+        // calls this post-resolve so the wallet is paid with no wallet popup.
+        "type": "function",
+        "name": "withdrawFor",
+        "inputs": [{ "name": "to", "type": "address", "internalType": "address" }],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "function",
+        "name": "commitGuess",
+        "inputs": [
+            { "name": "gameId", "type": "bytes32", "internalType": "bytes32" },
+            { "name": "commitment", "type": "bytes32", "internalType": "bytes32" }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "function",
+        "name": "revealGuess",
+        "inputs": [
+            { "name": "gameId", "type": "bytes32", "internalType": "bytes32" },
+            { "name": "r", "type": "bytes32", "internalType": "bytes32" },
+            { "name": "rMatchup", "type": "bytes32", "internalType": "bytes32" }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "function",
+        "name": "withdrawable",
+        "inputs": [{ "name": "", "type": "address", "internalType": "address" }],
+        "outputs": [{ "name": "", "type": "uint256", "internalType": "uint256" }],
+        "stateMutability": "view"
+    },
+    {
+        // The on-chain session registration for a wallet. `_actsFor` requires
+        // `sessionKey == msg.sender && block.timestamp < expiry`, so this is the
+        // only way a client can tell whether its session is still VALID as opposed
+        // to merely funded. Its absence from this ABI is why setupEvmSessionIfNeeded
+        // inferred registration from the session key's balance — and why an expired
+        // session locked a wallet out with no way to recover.
+        "type": "function",
+        "name": "sessions",
+        "inputs": [{ "name": "", "type": "address", "internalType": "address" }],
+        "outputs": [
+            { "name": "sessionKey", "type": "address", "internalType": "address" },
+            { "name": "expiry", "type": "uint64", "internalType": "uint64" }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "withdraw",
+        "inputs": [],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        // Auto-getter for `mapping(bytes32 => Game) public games`. Read to learn
+        // whether the matchup is already bound (matchupType != 255) so the reveal
+        // knows if it is the FIRST revealer (bind with rMatchup) or the SECOND
+        // (must pass the zero sentinel), and to compute the timeout deadline from
+        // the stage anchor + window. Field order matches CoordinationGame.sol Game.
+        "type": "function",
+        "name": "games",
+        "inputs": [{ "name": "", "type": "bytes32", "internalType": "bytes32" }],
+        "outputs": [
+            { "name": "status", "type": "uint8", "internalType": "uint8" },
+            { "name": "player1", "type": "address", "internalType": "address" },
+            { "name": "player2", "type": "address", "internalType": "address" },
+            { "name": "p1Guess", "type": "uint8", "internalType": "uint8" },
+            { "name": "p2Guess", "type": "uint8", "internalType": "uint8" },
+            { "name": "firstCommitter", "type": "uint8", "internalType": "uint8" },
+            { "name": "matchupType", "type": "uint8", "internalType": "uint8" },
+            { "name": "stakeWei", "type": "uint128", "internalType": "uint128" },
+            { "name": "matchupCommitment", "type": "bytes32", "internalType": "bytes32" },
+            { "name": "p1Commit", "type": "bytes32", "internalType": "bytes32" },
+            { "name": "p2Commit", "type": "bytes32", "internalType": "bytes32" },
+            { "name": "activatedAt", "type": "uint64", "internalType": "uint64" },
+            { "name": "firstCommitAt", "type": "uint64", "internalType": "uint64" },
+            { "name": "bothCommitAt", "type": "uint64", "internalType": "uint64" },
+            { "name": "createdAt", "type": "uint64", "internalType": "uint64" },
+            { "name": "commitWindowSecs", "type": "uint32", "internalType": "uint32" },
+            { "name": "revealWindowSecs", "type": "uint32", "internalType": "uint32" }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        // Permissionless timeout resolution: when the opponent stalls past the stage
+        // window (Active/Committing → commitWindow, Revealing → revealWindow), anyone
+        // can crank this to resolve the game so the honest player's stake isn't
+        // stranded. Reverts (Elapsed check) if the window hasn't passed yet.
+        "type": "function",
+        "name": "resolveTimeout",
+        "inputs": [{ "name": "gameId", "type": "bytes32", "internalType": "bytes32" }],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    }
+];

package/dist/coordination-game/evm/cross-chain.d.ts

@@ -0,0 +1,33 @@
+import { type Hex } from "viem";
+import type { CoordinationGameApiClient, XMatchPayload } from "../api.js";
+export declare function unpadAddress(word: string): Hex;
+export interface CrossChainMatchResult {
+    match: XMatchPayload;
+    handle: string | undefined;
+}
+export declare function findCrossChainMatch(api: CoordinationGameApiClient, input: {
+    wallet: string;
+    sessionKeyAddress: string;
+    tournamentId: number;
+    chain: string;
+}, options?: {
+    pollMs?: number;
+    maxPolls?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<CrossChainMatchResult>;
+export interface EvmFundCall {
+    to: Hex;
+    data: Hex;
+    value: bigint;
+}
+export interface EvmFundPin {
+    contract: Hex;
+    stakeWei: bigint;
+}
+export declare function buildEvmFundCall(match: XMatchPayload, pin: EvmFundPin): EvmFundCall;
+export interface FundTargetReader {
+    stakeWei(contract: Hex): Promise<bigint>;
+    matchStatus(contract: Hex, matchId: Hex): Promise<number>;
+}
+export declare function verifyEvmFundTarget(match: XMatchPayload, pin: EvmFundPin, readers: FundTargetReader[]): Promise<void>;
+export declare function rpcFundTargetReaders(rpcUrls: string[]): FundTargetReader[];

package/dist/coordination-game/evm/cross-chain.js

@@ -0,0 +1,76 @@
+import { createPublicClient, encodeFunctionData, http } from "viem";
+import { CROSS_CHAIN_GAME_ABI } from "./abi.js";
+export function unpadAddress(word) {
+    const hex = word.startsWith("0x") ? word.slice(2) : word;
+    return `0x${hex.slice(-40)}`;
+}
+export async function findCrossChainMatch(api, input, options = {}) {
+    const joined = await api.joinCrossChainQueue({
+        wallet: input.wallet,
+        chain: input.chain,
+        session_key: input.sessionKeyAddress,
+        tournament_id: input.tournamentId,
+    });
+    const handle = joined.poll_handle;
+    if (joined.status === "matched" && joined.match)
+        return { match: joined.match, handle };
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => globalThis.setTimeout(resolve, ms)));
+    for (let index = 0; index < (options.maxPolls ?? 60); index += 1) {
+        await sleep(options.pollMs ?? 4_000);
+        const next = await api.crossChainStatus(handle ? { handle } : { wallet: input.wallet });
+        if (next.status === "matched" && next.match)
+            return { match: next.match, handle };
+    }
+    throw new Error("no opponent found before timeout");
+}
+export function buildEvmFundCall(match, pin) {
+    const to = unpadAddress(match.leg_b.contract);
+    if (to.toLowerCase() !== pin.contract.toLowerCase()) {
+        throw new Error(`relay leg_b.contract ${to} != pinned CrossChainGame ${pin.contract}`);
+    }
+    const value = BigInt(match.leg_b.stake_base_units);
+    if (value !== pin.stakeWei) {
+        throw new Error(`relay leg_b.stake ${value} != pinned stake ${pin.stakeWei}`);
+    }
+    const data = encodeFunctionData({
+        abi: CROSS_CHAIN_GAME_ABI,
+        functionName: "createMatch",
+        args: [
+            match.match_id,
+            unpadAddress(match.leg_b.session_key),
+            unpadAddress(match.leg_a.session_key),
+            match.a_is_p1 === 0,
+            BigInt(match.fund_deadline),
+            BigInt(match.match_deadline),
+            match.create_match_operator_sig,
+        ],
+    });
+    return { to, data, value };
+}
+export async function verifyEvmFundTarget(match, pin, readers) {
+    if (readers.length < 2)
+        throw new Error(`need >=2 RPCs for a pre-fund quorum read, got ${readers.length}`);
+    const matchId = match.match_id;
+    const stakes = await Promise.all(readers.map((reader) => reader.stakeWei(pin.contract)));
+    const statuses = await Promise.all(readers.map((reader) => reader.matchStatus(pin.contract, matchId)));
+    if (!stakes.every((stake) => stake === stakes[0]))
+        throw new Error(`RPCs disagree on stakeWei (${stakes.join(", ")}); refusing to fund`);
+    if (!statuses.every((status) => status === statuses[0]))
+        throw new Error(`RPCs disagree on match status (${statuses.join(", ")}); refusing to fund`);
+    if (stakes[0] !== pin.stakeWei)
+        throw new Error(`on-chain stakeWei ${stakes[0]} != pinned ${pin.stakeWei}; refusing to fund`);
+    if (statuses[0] !== 0)
+        throw new Error(`matchId ${matchId} already has status ${statuses[0]}; not a fundable slot`);
+}
+export function rpcFundTargetReaders(rpcUrls) {
+    return rpcUrls.map((url) => {
+        const client = createPublicClient({ transport: http(url) });
+        return {
+            stakeWei: (contract) => client.readContract({ address: contract, abi: CROSS_CHAIN_GAME_ABI, functionName: "stakeWei" }),
+            matchStatus: async (contract, matchId) => {
+                const result = await client.readContract({ address: contract, abi: CROSS_CHAIN_GAME_ABI, functionName: "matches", args: [matchId] });
+                return Number(result[0]);
+            },
+        };
+    });
+}

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

@@ -0,0 +1,6 @@
+export * from "./abi.js";
+export * from "./rules.js";
+export * from "./session.js";
+export * from "./session-funding.js";
+export * from "./transactions.js";
+export * from "./cross-chain.js";

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

@@ -0,0 +1,6 @@
+export * from "./abi.js";
+export * from "./rules.js";
+export * from "./session.js";
+export * from "./session-funding.js";
+export * from "./transactions.js";
+export * from "./cross-chain.js";

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

@@ -0,0 +1,112 @@
+/**
+ * Pure decision rules for the same-chain EVM game, extracted from `useEvmGame`
+ * so the two paths that previously shipped bugs — reveal ordering and timeout
+ * recovery — are locked by deterministic unit tests instead of relying on a
+ * live e2e that only ever exercises the happy path.
+ *
+ * Mirrors CoordinationGame.sol exactly; keep in lockstep with the contract.
+ */
+import type { Hex } from "viem";
+/** games().matchupType before any reveal binds it. */
+export declare const MATCHUP_UNSET = 255;
+/** games().pNGuess before that player reveals. */
+export declare const UNREVEALED = 255;
+/** The 32-byte zero sentinel the SECOND revealer must pass for rMatchup. */
+export declare const ZERO_BYTES32: Hex;
+/**
+ * The `rMatchup` argument for revealGuess, chosen from ON-CHAIN state (never the
+ * creator/joiner role). The FIRST revealer binds the matchup with the real
+ * r_matchup; the SECOND — matchup already bound on-chain — MUST pass the zero
+ * sentinel, or the contract reverts CertMismatch (the reveal-order bug). Returns
+ * null only when we're the first revealer but don't yet hold r_matchup (both
+ * players haven't committed), which the caller surfaces as "not ready".
+ */
+export declare function revealMatchupArg(onChainMatchupType: number, rMatchup: Hex | null): Hex | null;
+export declare const STATUS_ACTIVE = 2;
+export declare const STATUS_COMMITTING = 3;
+export declare const STATUS_REVEALING = 4;
+export interface EvmGameTimes {
+    status: number;
+    activatedAt: bigint;
+    firstCommitAt: bigint;
+    bothCommitAt: bigint;
+    commitWindowSecs: bigint;
+    revealWindowSecs: bigint;
+}
+/**
+ * The unix second at which an opponent's stall becomes resolvable via
+ * resolveTimeout, or null when the status has no timeout (not Active/Committing/
+ * Revealing). Anchors mirror CoordinationGame.resolveTimeout: Active/Committing
+ * time out on the commit window (from join / first-commit); Revealing on the
+ * reveal window (from both-commit).
+ */
+export declare function timeoutDeadline(g: EvmGameTimes): bigint | null;
+/** Whether the opponent's stall is resolvable at `nowSecs`. */
+export declare function timeoutClaimableAt(g: EvmGameTimes, nowSecs: bigint): boolean;
+/** The on-chain Game fields needed to resume a game after a page reload. */
+export interface EvmResumeGame {
+    status: number;
+    player1: string;
+    player2: string;
+    p1Commit: Hex;
+    p2Commit: Hex;
+    p1Guess: number;
+    p2Guess: number;
+}
+export interface EvmResumeState {
+    phase: "chat" | "committed";
+    bothCommitted: boolean;
+}
+/**
+ * Is this match on the chain the wallet is currently connected to?
+ *
+ * The resume path takes the contract address from the MATCH record but reads it
+ * through the CONNECTED chain's client. Those are independent, and when they
+ * disagree it queries an address that means nothing on that chain. Observed on
+ * both mainnet e2e runs (2026-08-13): connected to eip155:1, it read the Base
+ * Sepolia proxy 0x4fbbceb9… and logged `"games" returned no data ("0x")`.
+ *
+ * Exact string equality on the CAIP-2 id, deliberately: no prefix matching (so
+ * `eip155:1` can never satisfy chain 11), and a missing/malformed/non-EVM value
+ * returns false rather than defaulting to allow — the boundary rejects rather
+ * than guesses.
+ */
+export declare function matchIsOnConnectedChain(matchChain: string | undefined, connectedChainId: number): boolean;
+/**
+ * The local phase to resume into after a page reload, derived purely from the
+ * on-chain game + our session address — EVM's `/evmplay` has no gameId in the
+ * URL, so a refresh otherwise strands a committed player who can no longer
+ * reveal. Returns null (stay idle) when there is nothing to resume: no
+ * in-progress game (Pending/Resolved/None), not a participant, or we already
+ * revealed (the game will resolve and auto-sweep on its own).
+ */
+export declare function deriveResumeState(g: EvmResumeGame, myAddr: string): EvmResumeState | null;
+/** The resolved-game fields needed to describe an outcome to the player. */
+export interface EvmResolvedGame {
+    player1: string;
+    player2: string;
+    p1Guess: number;
+    p2Guess: number;
+    matchupType: number;
+    firstCommitter: number;
+}
+/**
+ * Turn a resolved on-chain EVM game into the same player-relative shape the
+ * Solana side uses, so `outcomeLabel`/`shareText` can describe it identically.
+ *
+ * The EVM end-screen said only "Revealed — the game settles on-chain and your
+ * winnings return to your wallet automatically": no win/loss, no explorer link,
+ * no share. Solana has told players the outcome all along. The payoff matrix is
+ * the same on both chains (homogeneous by design), so the difference was purely
+ * that nobody built the panel — not a missing concept.
+ *
+ * Returns null when the game has no bound matchup or an unrevealed guess, i.e.
+ * there is not yet a truthful outcome to state.
+ */
+export declare function evmGameResult(g: EvmResolvedGame, myAddr: string): {
+    myGuess: 0 | 1;
+    opponentGuess: 0 | 1;
+    matchupType: 0 | 1;
+    iAmP1: boolean;
+    firstCommitter: number;
+} | null;