@swarm-tips/client 0.0.0 → 0.1.1

package/dist/contracts/index.d.ts

@@ -0,0 +1,33 @@
+import * as anchor from "@coral-xyz/anchor";
+import type { Idl } from "@coral-xyz/anchor";
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import { Buffer } from "buffer";
+declare const BN: typeof anchor.BN;
+export type { CoordinationGame } from "./generated/coordination_game.js";
+export type { Shillbot } from "./generated/shillbot.js";
+/** Canonical raw Anchor IDLs used for runtime instruction encoding. */
+export declare const COORDINATION_GAME_IDL: Idl;
+export declare const SHILLBOT_IDL: Idl;
+export declare const COORDINATION_GAME_PROGRAM_ID: anchor.web3.PublicKey;
+export declare const SHILLBOT_PROGRAM_ID: anchor.web3.PublicKey;
+export { BN };
+export type PublicKeyInput = PublicKey | string;
+export interface BuildShillbotInstructionRequest {
+    /** Snake-case instruction name from the canonical raw Anchor IDL. */
+    name: string;
+    /** Account names from the IDL mapped to their concrete public keys. */
+    accounts: Readonly<Record<string, PublicKeyInput>>;
+    /** Anchor/Borsh arguments. Integer values wider than u32 must be BN values. */
+    args?: Readonly<Record<string, unknown>>;
+}
+export declare function shillbotInstructionDiscriminator(name: string): Buffer;
+/**
+ * Encode a Shillbot instruction using the generated IDL as the ABI authority.
+ * Account order, signer/writable flags, discriminators, and argument encoding
+ * therefore cannot drift independently in downstream clients.
+ */
+export declare function buildShillbotInstruction(request: BuildShillbotInstructionRequest): TransactionInstruction;
+export declare function globalStatePda(): PublicKey;
+export declare function taskPda(nonce: bigint, client: PublicKey): PublicKey;
+export declare function clientStatePda(client: PublicKey): PublicKey;
+export declare function agentStatePda(agent: PublicKey): PublicKey;

package/dist/contracts/index.js

@@ -0,0 +1,84 @@
+import * as anchor from "@coral-xyz/anchor";
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import { Buffer } from "buffer";
+import coordinationGameIdl from "./idl/coordination_game.json" with { type: "json" };
+import shillbotIdl from "./idl/shillbot.json" with { type: "json" };
+const anchorRuntime = Reflect.get(anchor, "default") ?? anchor;
+const { BN, BorshInstructionCoder } = anchorRuntime;
+/** Canonical raw Anchor IDLs used for runtime instruction encoding. */
+export const COORDINATION_GAME_IDL = coordinationGameIdl;
+export const SHILLBOT_IDL = shillbotIdl;
+export const COORDINATION_GAME_PROGRAM_ID = new PublicKey(COORDINATION_GAME_IDL.address);
+export const SHILLBOT_PROGRAM_ID = new PublicKey(SHILLBOT_IDL.address);
+export { BN };
+const shillbotCoder = new BorshInstructionCoder(SHILLBOT_IDL);
+export function shillbotInstructionDiscriminator(name) {
+    const definition = SHILLBOT_IDL.instructions.find((instruction) => instruction.name === name);
+    if (!definition)
+        throw new Error(`unknown Shillbot instruction: ${name}`);
+    return Buffer.from(definition.discriminator);
+}
+function flattenAccounts(items) {
+    return items.flatMap((item) => item.accounts ? flattenAccounts(item.accounts) : [item]);
+}
+/**
+ * Encode a Shillbot instruction using the generated IDL as the ABI authority.
+ * Account order, signer/writable flags, discriminators, and argument encoding
+ * therefore cannot drift independently in downstream clients.
+ */
+export function buildShillbotInstruction(request) {
+    const definition = SHILLBOT_IDL.instructions.find((instruction) => instruction.name === request.name);
+    if (!definition) {
+        throw new Error(`unknown Shillbot instruction: ${request.name}`);
+    }
+    const accountDefinitions = flattenAccounts(definition.accounts);
+    const knownAccounts = new Set(accountDefinitions.map((account) => account.name));
+    const unknownAccount = Object.keys(request.accounts).find((name) => !knownAccounts.has(name));
+    if (unknownAccount) {
+        throw new Error(`unknown account ${unknownAccount} for Shillbot instruction ${request.name}`);
+    }
+    const expectedArguments = new Set(definition.args.map((argument) => argument.name));
+    const suppliedArguments = Object.keys(request.args ?? {});
+    const unknownArgument = suppliedArguments.find((name) => !expectedArguments.has(name));
+    if (unknownArgument) {
+        throw new Error(`unknown argument ${unknownArgument} for Shillbot instruction ${request.name}`);
+    }
+    const missingArgument = definition.args.find((argument) => !(argument.name in (request.args ?? {})));
+    if (missingArgument) {
+        throw new Error(`missing argument ${missingArgument.name} for Shillbot instruction ${request.name}`);
+    }
+    const keys = accountDefinitions.map((account) => {
+        const supplied = request.accounts[account.name];
+        const value = supplied ?? account.address;
+        if (!value) {
+            throw new Error(`missing account ${account.name} for Shillbot instruction ${request.name}`);
+        }
+        return {
+            pubkey: new PublicKey(value),
+            isSigner: account.signer === true,
+            isWritable: account.writable === true,
+        };
+    });
+    return new TransactionInstruction({
+        programId: SHILLBOT_PROGRAM_ID,
+        keys,
+        data: shillbotCoder.encode(request.name, request.args ?? {}),
+    });
+}
+function u64(value) {
+    const out = Buffer.alloc(8);
+    out.writeBigUInt64LE(value);
+    return out;
+}
+export function globalStatePda() {
+    return PublicKey.findProgramAddressSync([Buffer.from("shillbot_global")], SHILLBOT_PROGRAM_ID)[0];
+}
+export function taskPda(nonce, client) {
+    return PublicKey.findProgramAddressSync([Buffer.from("task"), u64(nonce), client.toBuffer()], SHILLBOT_PROGRAM_ID)[0];
+}
+export function clientStatePda(client) {
+    return PublicKey.findProgramAddressSync([Buffer.from("client_state"), client.toBuffer()], SHILLBOT_PROGRAM_ID)[0];
+}
+export function agentStatePda(agent) {
+    return PublicKey.findProgramAddressSync([Buffer.from("agent_state"), agent.toBuffer()], SHILLBOT_PROGRAM_ID)[0];
+}

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

@@ -0,0 +1,40 @@
+import { OutcomeKind, Transcript as OracleInput } from "./outcome-oracle.js";
+/** A realized same-chain game, decoded from the on-chain Game account. */
+export interface RealizedGame {
+    matchupType: number;
+    p1Guess: number;
+    p2Guess: number;
+    firstCommitter: number;
+    p1Return: bigint;
+    p2Return: bigint;
+    tournamentGain: bigint;
+    stake: bigint;
+}
+/** The oracle input a fully-revealed (terminal) realized game represents.
+ *  Rejects non-terminal games up front: a 255 sentinel in matchupType/guesses
+ *  (unrevealed) or a firstCommitter outside {1,2} means the game has NOT fully
+ *  resolved, and feeding it to the oracle would produce a nonsense verdict
+ *  instead of a clear error. */
+export declare function realizedTranscript(g: RealizedGame): OracleInput;
+/**
+ * (1) Oracle-from-realized-transcript: the on-chain settlement
+ * (p1_return / p2_return / tournament_gain) must equal what the shared oracle
+ * derives from the realized transcript. The outcome is computed from what
+ * actually happened, never assumed — so a variable end state is fine. Returns
+ * the derived OutcomeKind.
+ */
+export declare function assertPayoffMatchesChain(g: RealizedGame): OutcomeKind;
+/** (2) Conservation: stake is never created or destroyed. */
+export declare function assertConservation(g: RealizedGame): void;
+/**
+ * (3) Cross-layer: the outcome OBSERVED on a surface (UI text / MCP get_result)
+ * must equal the outcome the chain + oracle agree on — catches a surface that
+ * reports a result the chain didn't actually produce.
+ */
+export declare function assertOutcomeAgrees(g: RealizedGame, observed: OutcomeKind): void;
+/**
+ * Full same-chain verdict in one call: conservation + payoff-from-transcript,
+ * plus optional cross-layer if a surface outcome was observed. Returns the
+ * derived OutcomeKind so callers can compare runs (metamorphic).
+ */
+export declare function verifyRealizedGame(g: RealizedGame, observed?: OutcomeKind): OutcomeKind;

package/dist/coordination-game/battery.js

@@ -0,0 +1,82 @@
+// Portable property battery for the coordination game — the path-independent
+// checks over the REALIZED result, shipped in @swarm-tips/client so
+// any e2e (on-chain, Playwright, MCP) verifies the same way. Pure: NO chai, no
+// chain deps — throws plain Errors so it runs anywhere.
+//
+// The point: at the browser/MCP layer the end state is genuinely variable — the
+// matchmaker hides matchup_type and the opponent (grok / another player) picks
+// its own guess. So you don't assert a fixed outcome; you read the realized game
+// from chain after resolution and verify properties that hold for ANY transcript.
+import { OutcomeKind, deriveClaimOutcome, resolvePayoff, TERMINAL_STEP_COUNT, } from "./outcome-oracle.js";
+function fail(msg) {
+    throw new Error(`battery: ${msg}`);
+}
+/** The oracle input a fully-revealed (terminal) realized game represents.
+ *  Rejects non-terminal games up front: a 255 sentinel in matchupType/guesses
+ *  (unrevealed) or a firstCommitter outside {1,2} means the game has NOT fully
+ *  resolved, and feeding it to the oracle would produce a nonsense verdict
+ *  instead of a clear error. */
+export function realizedTranscript(g) {
+    if (g.matchupType !== 0 && g.matchupType !== 1)
+        fail(`not terminal: matchupType ${g.matchupType} (unset sentinel?)`);
+    if (g.p1Guess !== 0 && g.p1Guess !== 1)
+        fail(`not terminal: p1Guess ${g.p1Guess} (unrevealed sentinel?)`);
+    if (g.p2Guess !== 0 && g.p2Guess !== 1)
+        fail(`not terminal: p2Guess ${g.p2Guess} (unrevealed sentinel?)`);
+    if (g.firstCommitter !== 1 && g.firstCommitter !== 2)
+        fail(`not terminal: firstCommitter ${g.firstCommitter} (expected 1 or 2)`);
+    return {
+        stepCount: TERMINAL_STEP_COUNT,
+        matchupType: g.matchupType,
+        p1Guess: g.p1Guess,
+        p2Guess: g.p2Guess,
+        firstCommitter: g.firstCommitter,
+    };
+}
+/**
+ * (1) Oracle-from-realized-transcript: the on-chain settlement
+ * (p1_return / p2_return / tournament_gain) must equal what the shared oracle
+ * derives from the realized transcript. The outcome is computed from what
+ * actually happened, never assumed — so a variable end state is fine. Returns
+ * the derived OutcomeKind.
+ */
+export function assertPayoffMatchesChain(g) {
+    const t = realizedTranscript(g);
+    const p = resolvePayoff({ ...t, stake: g.stake });
+    if (g.p1Return !== p.p1Return)
+        fail(`p1_return ${g.p1Return} != oracle ${p.p1Return}`);
+    if (g.p2Return !== p.p2Return)
+        fail(`p2_return ${g.p2Return} != oracle ${p.p2Return}`);
+    if (g.tournamentGain !== p.tournamentGain)
+        fail(`tournament_gain ${g.tournamentGain} != oracle ${p.tournamentGain}`);
+    return deriveClaimOutcome(t);
+}
+/** (2) Conservation: stake is never created or destroyed. */
+export function assertConservation(g) {
+    const total = g.p1Return + g.p2Return + g.tournamentGain;
+    const expected = g.stake * 2n;
+    if (total !== expected)
+        fail(`conservation: ${total} != 2*stake ${expected}`);
+}
+/**
+ * (3) Cross-layer: the outcome OBSERVED on a surface (UI text / MCP get_result)
+ * must equal the outcome the chain + oracle agree on — catches a surface that
+ * reports a result the chain didn't actually produce.
+ */
+export function assertOutcomeAgrees(g, observed) {
+    const expected = deriveClaimOutcome(realizedTranscript(g));
+    if (observed !== expected)
+        fail(`cross-layer: surface ${OutcomeKind[observed]} != chain/oracle ${OutcomeKind[expected]}`);
+}
+/**
+ * Full same-chain verdict in one call: conservation + payoff-from-transcript,
+ * plus optional cross-layer if a surface outcome was observed. Returns the
+ * derived OutcomeKind so callers can compare runs (metamorphic).
+ */
+export function verifyRealizedGame(g, observed) {
+    assertConservation(g);
+    const outcome = assertPayoffMatchesChain(g);
+    if (observed !== undefined)
+        assertOutcomeAgrees(g, observed);
+    return outcome;
+}

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

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

package/dist/coordination-game/index.js

@@ -0,0 +1,3 @@
+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";

package/dist/coordination-game/outcome-oracle.d.ts

@@ -0,0 +1,53 @@
+export declare const GUESS_SAME_TEAM = 0;
+export declare const GUESS_DIFF_TEAM = 1;
+export declare const UNREVEALED = 255;
+export declare const TERMINAL_STEP_COUNT = 4;
+/** Wire-format outcome kinds (0..=8), identical to cert_schema.rs `OutcomeKind`. */
+export declare enum OutcomeKind {
+    HomogBothCorrect = 0,
+    HomogP1Correct = 1,
+    HomogP2Correct = 2,
+    BothWrong = 3,
+    HeteroP1Wins = 4,
+    HeteroP2Wins = 5,
+    TimeoutP1Wins = 6,
+    TimeoutP2Wins = 7,
+    TimeoutBothForfeit = 8
+}
+export interface Transcript {
+    /** 0..=4 (TERMINAL_STEP_COUNT), or anything else for a malformed transcript. */
+    stepCount: number;
+    matchupType: number;
+    p1Guess: number;
+    p2Guess: number;
+    firstCommitter: number;
+}
+/** Mirrors `cert_schema.rs::derive_terminal_outcome` / `CertLib.deriveTerminalOutcome`. */
+export declare function deriveTerminalOutcome(t: Transcript): OutcomeKind;
+/** Mirrors `cert_schema.rs::derive_outcome_kind` / `CertLib.deriveClaimOutcome` (terminal + timeouts). */
+export declare function deriveClaimOutcome(t: Transcript): OutcomeKind;
+export interface Payoff {
+    p1Return: bigint;
+    p2Return: bigint;
+    tournamentGain: bigint;
+}
+/**
+ * Mirrors `programs/coordination-game/src/payoff.rs::resolve_game` — the
+ * same-chain settlement amounts (lamports). `firstCommitter` must be 1 or 2 in
+ * the heterogeneous both-correct case. Conserves stake: the three returns sum to
+ * `2 * stake`.
+ */
+export declare function resolvePayoff(t: Transcript & {
+    stake: bigint;
+}): Payoff;
+/**
+ * Split a forfeited tournament gain into (treasury, prize-pool) shares the way
+ * the program does at resolution: treasury gets `gain * bps / 10_000` (floored),
+ * the prize pool gets the remainder. Bps is bounded to [2000, 8000] on-chain.
+ */
+export declare function splitTournamentGain(gain: bigint, treasurySplitBps: number): {
+    treasuryGain: bigint;
+    prizeGain: bigint;
+};
+/** Matchup type encoded in the last bit of the 32-byte preimage (R_matchup[31] & 1). */
+export declare function matchupTypeFromR(r: Uint8Array | number[]): number;

package/dist/coordination-game/outcome-oracle.js

@@ -0,0 +1,136 @@
+// Outcome oracle — the canonical coordination-game payoff matrix, in TypeScript.
+//
+// This is the off-chain test/tooling mirror of the on-chain derivation logic
+// that three implementations already agree on (pinned by the golden vectors in
+// tests/fixtures/cert-vectors.json):
+//
+//   - crates/chain-core/src/cert_schema.rs   `Checkpoint::derive_outcome_kind`
+//   - evm/src/CertLib.sol                     `deriveClaimOutcome`
+//   - programs/coordination-game/src/payoff.rs `resolve_game`
+//
+// The harness uses it as the single source of truth for "what SHOULD this game
+// resolve to" so every scenario — same-chain Solana, same-chain EVM, cross-chain
+// — asserts on-chain reality against ONE expectation, instead of re-deriving the
+// matrix per test. If this drifts from the on-chain encoders, the combinatorial
+// integration tests (which compare on-chain resolution to this oracle) fail.
+export const GUESS_SAME_TEAM = 0;
+export const GUESS_DIFF_TEAM = 1;
+export const UNREVEALED = 255;
+export const TERMINAL_STEP_COUNT = 4;
+/** Wire-format outcome kinds (0..=8), identical to cert_schema.rs `OutcomeKind`. */
+export var OutcomeKind;
+(function (OutcomeKind) {
+    OutcomeKind[OutcomeKind["HomogBothCorrect"] = 0] = "HomogBothCorrect";
+    OutcomeKind[OutcomeKind["HomogP1Correct"] = 1] = "HomogP1Correct";
+    OutcomeKind[OutcomeKind["HomogP2Correct"] = 2] = "HomogP2Correct";
+    OutcomeKind[OutcomeKind["BothWrong"] = 3] = "BothWrong";
+    OutcomeKind[OutcomeKind["HeteroP1Wins"] = 4] = "HeteroP1Wins";
+    OutcomeKind[OutcomeKind["HeteroP2Wins"] = 5] = "HeteroP2Wins";
+    OutcomeKind[OutcomeKind["TimeoutP1Wins"] = 6] = "TimeoutP1Wins";
+    OutcomeKind[OutcomeKind["TimeoutP2Wins"] = 7] = "TimeoutP2Wins";
+    OutcomeKind[OutcomeKind["TimeoutBothForfeit"] = 8] = "TimeoutBothForfeit";
+})(OutcomeKind || (OutcomeKind = {}));
+/** Mirrors `cert_schema.rs::derive_terminal_outcome` / `CertLib.deriveTerminalOutcome`. */
+export function deriveTerminalOutcome(t) {
+    const p1Correct = t.p1Guess === t.matchupType;
+    const p2Correct = t.p2Guess === t.matchupType;
+    if (t.matchupType === 0) {
+        if (p1Correct && p2Correct)
+            return OutcomeKind.HomogBothCorrect;
+        if (p1Correct)
+            return OutcomeKind.HomogP1Correct;
+        if (p2Correct)
+            return OutcomeKind.HomogP2Correct;
+        return OutcomeKind.BothWrong;
+    }
+    // Heterogeneous: winner takes both stakes; ties break to the first committer.
+    if (!p1Correct && !p2Correct)
+        return OutcomeKind.BothWrong;
+    if (p1Correct === p2Correct) {
+        return t.firstCommitter === 1
+            ? OutcomeKind.HeteroP1Wins
+            : OutcomeKind.HeteroP2Wins;
+    }
+    return p1Correct ? OutcomeKind.HeteroP1Wins : OutcomeKind.HeteroP2Wins;
+}
+/** Mirrors `cert_schema.rs::derive_outcome_kind` / `CertLib.deriveClaimOutcome` (terminal + timeouts). */
+export function deriveClaimOutcome(t) {
+    if (t.stepCount === TERMINAL_STEP_COUNT)
+        return deriveTerminalOutcome(t);
+    if (t.stepCount === 1) {
+        // One commit landed; the committer wins. Inconsistent committer → both forfeit.
+        if (t.firstCommitter === 1)
+            return OutcomeKind.TimeoutP1Wins;
+        if (t.firstCommitter === 2)
+            return OutcomeKind.TimeoutP2Wins;
+        return OutcomeKind.TimeoutBothForfeit;
+    }
+    if (t.stepCount === 3) {
+        // Both committed, exactly one revealed: the revealer wins. Both-set or
+        // both-unset is inconsistent → both forfeit.
+        const p1Revealed = t.p1Guess !== UNREVEALED;
+        const p2Revealed = t.p2Guess !== UNREVEALED;
+        if (p1Revealed === p2Revealed)
+            return OutcomeKind.TimeoutBothForfeit;
+        return p1Revealed ? OutcomeKind.TimeoutP1Wins : OutcomeKind.TimeoutP2Wins;
+    }
+    // step 0 (nobody committed) / step 2 (both committed, none revealed).
+    return OutcomeKind.TimeoutBothForfeit;
+}
+/**
+ * Mirrors `programs/coordination-game/src/payoff.rs::resolve_game` — the
+ * same-chain settlement amounts (lamports). `firstCommitter` must be 1 or 2 in
+ * the heterogeneous both-correct case. Conserves stake: the three returns sum to
+ * `2 * stake`.
+ */
+export function resolvePayoff(t) {
+    if (t.stake <= 0n)
+        throw new Error("stake must be positive");
+    const two = t.stake * 2n;
+    const half = t.stake / 2n;
+    const payoff = t.matchupType === 0
+        ? resolveHomogeneous(t.p1Guess, t.p2Guess, t.stake, half, two)
+        : resolveHeterogeneous(t.p1Guess, t.p2Guess, t.firstCommitter, two);
+    const total = payoff.p1Return + payoff.p2Return + payoff.tournamentGain;
+    if (total !== two) {
+        throw new Error(`lamport conservation broken: ${total} != ${two}`);
+    }
+    return payoff;
+}
+function resolveHomogeneous(p1Guess, p2Guess, stake, half, two) {
+    const p1Correct = p1Guess === GUESS_SAME_TEAM;
+    const p2Correct = p2Guess === GUESS_SAME_TEAM;
+    if (p1Correct && p2Correct)
+        return { p1Return: stake, p2Return: stake, tournamentGain: 0n };
+    if (p1Correct)
+        return { p1Return: half, p2Return: 0n, tournamentGain: two - half };
+    if (p2Correct)
+        return { p1Return: 0n, p2Return: half, tournamentGain: two - half };
+    return { p1Return: 0n, p2Return: 0n, tournamentGain: two };
+}
+function resolveHeterogeneous(p1Guess, p2Guess, firstCommitter, two) {
+    const p1Correct = p1Guess === GUESS_DIFF_TEAM;
+    const p2Correct = p2Guess === GUESS_DIFF_TEAM;
+    if (!p1Correct && !p2Correct)
+        return { p1Return: 0n, p2Return: 0n, tournamentGain: two };
+    if (firstCommitter !== 1 && firstCommitter !== 2) {
+        throw new Error("first_committer must be 1 or 2");
+    }
+    const p1Wins = p1Correct === p2Correct ? firstCommitter === 1 : p1Correct;
+    return p1Wins
+        ? { p1Return: two, p2Return: 0n, tournamentGain: 0n }
+        : { p1Return: 0n, p2Return: two, tournamentGain: 0n };
+}
+/**
+ * Split a forfeited tournament gain into (treasury, prize-pool) shares the way
+ * the program does at resolution: treasury gets `gain * bps / 10_000` (floored),
+ * the prize pool gets the remainder. Bps is bounded to [2000, 8000] on-chain.
+ */
+export function splitTournamentGain(gain, treasurySplitBps) {
+    const treasuryGain = (gain * BigInt(treasurySplitBps)) / 10000n;
+    return { treasuryGain, prizeGain: gain - treasuryGain };
+}
+/** Matchup type encoded in the last bit of the 32-byte preimage (R_matchup[31] & 1). */
+export function matchupTypeFromR(r) {
+    return r[31] & 1;
+}

package/dist/evm/index.d.ts

@@ -0,0 +1,3 @@
+export { signDigestForRelay } from "./sign.js";
+export { sendUnsignedCall, sendContractCall, type UnsignedEvmCall, type CallSender, } from "./tx.js";
+export { buildWagmiConfig, getEvmTestWalletKey, getEvmRpcOverride, type ChainWithRpcs, type WagmiConfigOpts, } from "./wallet.js";

package/dist/evm/index.js

@@ -0,0 +1,6 @@
+// Product-agnostic EVM frontend primitives shared across
+// Swarm Tips frontends (coordination-game today; a future shillbot EVM flow
+// just adds this package as a dependency + brings its own ABI/flow).
+export { signDigestForRelay } from "./sign.js";
+export { sendUnsignedCall, sendContractCall, } from "./tx.js";
+export { buildWagmiConfig, getEvmTestWalletKey, getEvmRpcOverride, } from "./wallet.js";

package/dist/evm/sign.d.ts

@@ -0,0 +1,12 @@
+import type { Hex } from "viem";
+/**
+ * Sign a `0x` 32-byte digest with an EVM private key, returning a `0x` 65-byte
+ * `[r||s||v]` secp256k1 signature with `v = 0 | 1`. viem's `sign` emits the EVM
+ * `ecrecover` convention `v = 27 | 28`; this normalizes it to the k256
+ * `recover_address` form the game-api relay (and the Solana program) verify.
+ *
+ * NOTE: this is the OFF-CHAIN relay direction (27/28 → 0/1). For a signature an
+ * EVM CONTRACT verifies, do NOT normalize — viem's 27/28 is already correct
+ * (the inverse axis; see chain-core `sign_digest_eth` / `evm_operator_sig_v_convention`).
+ */
+export declare function signDigestForRelay(privateKey: Hex, digestHex: Hex): Promise<Hex>;

package/dist/evm/sign.js

@@ -0,0 +1,23 @@
+import { sign } from "viem/accounts";
+/**
+ * Sign a `0x` 32-byte digest with an EVM private key, returning a `0x` 65-byte
+ * `[r||s||v]` secp256k1 signature with `v = 0 | 1`. viem's `sign` emits the EVM
+ * `ecrecover` convention `v = 27 | 28`; this normalizes it to the k256
+ * `recover_address` form the game-api relay (and the Solana program) verify.
+ *
+ * NOTE: this is the OFF-CHAIN relay direction (27/28 → 0/1). For a signature an
+ * EVM CONTRACT verifies, do NOT normalize — viem's 27/28 is already correct
+ * (the inverse axis; see chain-core `sign_digest_eth` / `evm_operator_sig_v_convention`).
+ */
+export async function signDigestForRelay(privateKey, digestHex) {
+    const serialized = await sign({ hash: digestHex, privateKey, to: "hex" });
+    const body = serialized.slice(2); // 130 hex chars: r(64) || s(64) || v(2)
+    if (body.length !== 130) {
+        throw new Error(`unexpected signature length: ${serialized}`);
+    }
+    const rs = body.slice(0, 128);
+    let v = parseInt(body.slice(128, 130), 16);
+    if (v >= 27)
+        v -= 27; // 27|28 -> 0|1 for the relay's k256 recover_address
+    return `0x${rs}${v.toString(16).padStart(2, "0")}`;
+}

package/dist/evm/testing.d.ts

@@ -0,0 +1,21 @@
+/**
+ * localStorage key that opts a page into the E2E test connectors. The
+ * `?evmTestWallet=`/`?evmRpc=` query params are honored ONLY when this key is
+ * set to "1". A query param alone can't activate the test path — see
+ * `e2eTestModeEnabled` for why this closes the prod-phishing hole.
+ */
+export declare const E2E_TEST_MODE_KEY = "swarm_e2e_test_mode";
+/**
+ * Is this page running under the E2E harness?
+ *
+ * The deployed prod bundle is the SAME bundle the Playwright e2e drives against
+ * coordination.game, so `import.meta.env.DEV` is false in both and can't gate
+ * the test connectors. We instead require an explicit localStorage opt-in that
+ * ONLY the harness can set: Playwright's `addInitScript` runs on the page origin
+ * before any page script, so it can seed `localStorage[E2E_TEST_MODE_KEY]`. A
+ * phishing link can carry `?evmTestWallet=` query params but CANNOT write to a
+ * victim's coordination.game localStorage (it's origin-scoped, not URL-settable),
+ * so a real user clicking such a link never activates the private-key connector
+ * or the RPC override. Fail-closed: any localStorage access error → disabled.
+ */
+export declare function e2eTestModeEnabled(): boolean;

package/dist/evm/testing.js

@@ -0,0 +1,34 @@
+// E2E test-mode gate — intentionally dependency-free (only `window.localStorage`)
+// so the Playwright harness can import the flag key via the
+// `@swarm-tips/client/evm/testing`
+// subpath WITHOUT pulling wagmi/viem into the test package.
+/**
+ * localStorage key that opts a page into the E2E test connectors. The
+ * `?evmTestWallet=`/`?evmRpc=` query params are honored ONLY when this key is
+ * set to "1". A query param alone can't activate the test path — see
+ * `e2eTestModeEnabled` for why this closes the prod-phishing hole.
+ */
+export const E2E_TEST_MODE_KEY = "swarm_e2e_test_mode";
+/**
+ * Is this page running under the E2E harness?
+ *
+ * The deployed prod bundle is the SAME bundle the Playwright e2e drives against
+ * coordination.game, so `import.meta.env.DEV` is false in both and can't gate
+ * the test connectors. We instead require an explicit localStorage opt-in that
+ * ONLY the harness can set: Playwright's `addInitScript` runs on the page origin
+ * before any page script, so it can seed `localStorage[E2E_TEST_MODE_KEY]`. A
+ * phishing link can carry `?evmTestWallet=` query params but CANNOT write to a
+ * victim's coordination.game localStorage (it's origin-scoped, not URL-settable),
+ * so a real user clicking such a link never activates the private-key connector
+ * or the RPC override. Fail-closed: any localStorage access error → disabled.
+ */
+export function e2eTestModeEnabled() {
+    if (typeof window === "undefined")
+        return false;
+    try {
+        return window.localStorage.getItem(E2E_TEST_MODE_KEY) === "1";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/evm/tx.d.ts

@@ -0,0 +1,27 @@
+import { type Abi, type Hex } from "viem";
+/** An unsigned EVM call the connected wallet signs + submits. */
+export interface UnsignedEvmCall {
+    to: Hex;
+    data: Hex;
+    /** Native value in wei; defaults to 0. */
+    value?: bigint;
+}
+/**
+ * Any wallet able to submit a prepared transaction — structurally satisfied by a
+ * wagmi / viem `WalletClient` (whose `sendTransaction` accepts a superset of
+ * these fields). Loosely typed on the argument so the kit doesn't depend on
+ * wagmi's full generic `SendTransactionParameters`.
+ */
+export interface CallSender {
+    sendTransaction: (args: any) => Promise<Hex>;
+}
+/** Submit an unsigned `{to,data,value}` call via the connected wallet. */
+export declare function sendUnsignedCall(wallet: CallSender, call: UnsignedEvmCall): Promise<Hex>;
+/** Encode a contract call (viem `encodeFunctionData`) and submit it. */
+export declare function sendContractCall(wallet: CallSender, args: {
+    abi: Abi;
+    functionName: string;
+    args: readonly unknown[];
+    to: Hex;
+    value?: bigint;
+}): Promise<Hex>;

package/dist/evm/tx.js

@@ -0,0 +1,18 @@
+import { encodeFunctionData } from "viem";
+/** Submit an unsigned `{to,data,value}` call via the connected wallet. */
+export function sendUnsignedCall(wallet, call) {
+    return wallet.sendTransaction({
+        to: call.to,
+        data: call.data,
+        value: call.value ?? 0n,
+    });
+}
+/** Encode a contract call (viem `encodeFunctionData`) and submit it. */
+export function sendContractCall(wallet, args) {
+    const data = encodeFunctionData({
+        abi: args.abi,
+        functionName: args.functionName,
+        args: args.args,
+    });
+    return sendUnsignedCall(wallet, { to: args.to, data, value: args.value });
+}

package/dist/evm/wallet.d.ts

@@ -0,0 +1,58 @@
+import { type Config, type CreateConnectorFn } from "wagmi";
+import { type Chain, type Hex } from "viem";
+/**
+ * Read an E2E test private key from a `?<param>=<0x-hex>` query param, if
+ * present (default param `evmTestWallet`). Mirrors the Solana `?testWallet=`
+ * pattern so Playwright can drive the EVM path headlessly. Returns null off the
+ * happy path (no window, missing/malformed param) AND whenever the page isn't
+ * in E2E test mode — so a crafted prod link can't activate the connector.
+ */
+export declare function getEvmTestWalletKey(param?: string): Hex | null;
+/**
+ * Read an E2E RPC override from `?evmRpc=<https-url>`. Lets Playwright point the
+ * page at a reliable provider (e.g. QuickNode) WITHOUT baking the key into the
+ * public bundle. Caller gates this to test mode (test wallet present) so a
+ * crafted link can't redirect a real user's wallet to a hostile RPC. Only https
+ * URLs are accepted. Also gated on E2E test mode (defense in depth — its only
+ * caller already requires a test wallet, which is itself test-mode-gated).
+ */
+export declare function getEvmRpcOverride(param?: string): string | null;
+export interface WagmiConfigOpts {
+    /** Reown/WalletConnect projectId. When set (and not in test mode) the
+     *  WalletConnect connector is added alongside `injected`, so mobile + hardware
+     *  + QR wallets can connect. Omit → injected-only (browser extensions still
+     *  work via EIP-6963). It is a public client id, safe to ship in the bundle.
+     *
+     *  NOTE: registering the raw wagmi connector is NOT sufficient for a
+     *  RainbowKit UI — RainbowKit's modal renders its own wallet registry and
+     *  ignores connectors it did not create, so a WalletConnect connector added
+     *  here never appears as an option. Apps with a RainbowKit modal must pass
+     *  `connectors` below instead. */
+    walletConnectProjectId?: string;
+    /** Connectors supplied by the app, used when NOT in test mode. This is how a
+     *  RainbowKit app injects `connectorsForWallets(...)` output so its modal and
+     *  the wagmi config agree on the wallet list. Keeping it an opaque array lets
+     *  evm-kit stay free of any RainbowKit dependency. */
+    connectors?: CreateConnectorFn[];
+}
+/**
+ * Choose the connector set for a config. Pure, so the precedence rule is
+ * unit-testable: the E2E test connector always wins (a live sweep must never be
+ * hijacked by a real wallet), then app-supplied connectors, then the built-in
+ * injected/WalletConnect pair.
+ */
+export declare function selectConnectors<T>(testConnector: T | null, appConnectors: T[] | undefined, builtIn: T[]): T[];
+/** One chain in a multi-chain config, with its own failover RPCs. */
+export interface ChainWithRpcs {
+    chain: Chain;
+    rpcUrls?: string[];
+}
+/**
+ * Build a wagmi config for one or several EVM chains. Multi-chain lets the
+ * wallet switch chains (e.g. Base Sepolia ↔ Ethereum Sepolia) so the same site
+ * plays each — each chain gets its own resilient transport. The `injected`
+ * connector serves humans; the private-key test connector serves E2E when the
+ * test-wallet query param is present (bound to the `?evmChain=<caip2>` chain,
+ * or the first listed chain).
+ */
+export declare function buildWagmiConfig(chains: ChainWithRpcs[], opts?: WagmiConfigOpts): Config;