@zktable/coup-lite 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,328 @@
+import * as _zktable_core from '@zktable/core';
+import { PlayerId, PlayerView, Move, Match } from '@zktable/core';
+
+/** 5 character ids, matching the `card_membership` circuit's small-int domain. */
+declare const CHARACTERS: readonly [0, 1, 2, 3, 4];
+declare const CHARACTER_NAMES: readonly ["Duke", "Assassin", "Captain", "Contessa", "Ambassador"];
+declare const HAND_SIZE = 2;
+declare const START_INFLUENCE = 2;
+/** The player range supported end-to-end (defineGame AND the on-chain referee). */
+declare const MIN_PLAYERS = 2;
+declare const MAX_PLAYERS = 4;
+/** Default seat count for the demos/runner (override with COUP_PLAYERS / opts.players). */
+declare const N_PLAYERS = 2;
+type Hand = [number, number];
+type ClaimEntry = {
+    player: PlayerId;
+    character: number;
+};
+/** Per-match config, passed as `MatchOptions.config.coupLite`. */
+type CoupLiteConfig = {
+    /**
+     * The REAL dealt hand per player. Required for the on-chain runner (the
+     * semi-honestly dealt, `card_membership`-provable hand); if omitted,
+     * `setup` derives a deterministic seeded hand from `MatchOptions.seed` so
+     * pure local tests don't need the prover pipeline.
+     */
+    handsByPlayer?: Record<PlayerId, Hand>;
+};
+/** Deterministic (seeded) hand of 2 DISTINCT characters, used only when no real dealt hand is supplied. */
+declare function seededHand(seed: string): Hand;
+declare const coupLite: _zktable_core.Game;
+
+/** Deterministically pick one element of `items`, keyed by `seed`. Throws on an empty array. */
+declare function pickSeeded<T>(items: readonly T[], seed: string): T;
+/**
+ * Decide whether to challenge the standing claim (`view.legalMoves` already
+ * confirms a `challenge` is legal here) or let it stand and make a new claim
+ * instead. Suspicion is higher when this player's own hand does NOT contain
+ * the claimed character (the only legitimate signal available), lower when
+ * it does.
+ */
+declare function chooseMove(view: PlayerView, seed: string): Move;
+
+type CardProof = {
+    proof: Uint8Array;
+    publicInputs: Uint8Array;
+    claimed: bigint;
+    commitmentsHex: [string, string];
+};
+/** The seed-forced shuffled deck plus its `valid_shuffle` proof (M8.3). */
+type ShuffleProof = {
+    proof: Uint8Array;
+    publicInputs: Uint8Array;
+    seedHex: string;
+    /** Card value (0-4) at each of the 15 deck positions — dealer-visible only. */
+    cards: number[];
+    /** Salt (decimal string) at each deck position. */
+    salts: string[];
+    /** Poseidon2(card, salt) leaf commitment (hex) at each deck position. */
+    leavesHex: string[];
+};
+type CardProverOptions = {
+    circuitDir?: string;
+    shuffleCircuitDir?: string;
+    graphToolsBin?: string;
+    nargoBin?: string;
+    bbBin?: string;
+    workDir?: string;
+};
+declare class CardProver {
+    private readonly circuitDir;
+    private readonly shuffleCircuitDir;
+    private readonly graphToolsBin;
+    private readonly nargoBin;
+    private readonly bbBin;
+    private readonly workDir;
+    private readonly env;
+    constructor(opts?: CardProverOptions);
+    private get targetDir();
+    private get bytecodePath();
+    private get vkPath();
+    private get shuffleTargetDir();
+    private get shuffleBytecodePath();
+    private get shuffleVkPath();
+    /** Compile the circuit once if `target/card_membership.json` is missing. */
+    ensureCompiled(): Promise<void>;
+    /** Generate the verification key once if `target/vk` is missing. */
+    ensureVk(): Promise<void>;
+    /** Compile `valid_shuffle` once if its bytecode is missing. */
+    ensureShuffleCompiled(): Promise<void>;
+    /** Generate the `valid_shuffle` verification key once if missing. */
+    ensureShuffleVk(): Promise<void>;
+    private writeVk;
+    /**
+     * Poseidon2(value, salt) via `zktable-graph commit` — used for the seed
+     * commit-reveal nonces (`hash2(nonce, 0)`), byte-identical to the referee.
+     */
+    commit(value: bigint, salt: bigint): Promise<string>;
+    /** The joint commit-reveal seed: left-fold of hash2 over the nonces (player-index order). */
+    seed(nonces: bigint[]): Promise<string>;
+    /**
+     * Full `valid_shuffle` pipeline (M8.3): derive the UNIQUE seed-forced
+     * permutation of the canonical 15-card deck via `zktable-graph
+     * shuffle-witness`, then `nargo execute` -> `bb prove`. The returned
+     * `cards`/`salts` are the dealer's private view (handed to each player
+     * off-chain); `leavesHex` + `proof` go on-chain via `submit_shuffle`.
+     */
+    proveShuffle(seedHex: string, salts: bigint[]): Promise<ShuffleProof>;
+    /**
+     * Full pipeline for one "prove-hold" claim: `zktable-graph card-witness` ->
+     * `nargo execute` -> `bb prove`. Runs entirely inside an isolated temp dir;
+     * never touches `card_membership/Prover.toml` or `card_membership/target/`
+     * (besides the shared, idempotent compiled bytecode).
+     */
+    proveHold(claimed: bigint, cards: [bigint, bigint], salts: [bigint, bigint], heldIndex: 0 | 1): Promise<CardProof>;
+    /** Off-chain check via `bb verify`, useful for sanity-checking a proof before spending a testnet tx. */
+    verifyLocally(proof: Uint8Array, publicInputs: Uint8Array): Promise<boolean>;
+    /** Off-chain `bb verify` of a `valid_shuffle` proof against ITS verification key. */
+    shuffleLocalVerify(proof: Uint8Array, publicInputs: Uint8Array): Promise<boolean>;
+    private bbVerify;
+}
+
+declare class RefereeCliError extends Error {
+    readonly args: string[];
+    readonly stderr: string;
+    readonly contractErrorCode: number | null;
+    readonly contractErrorName: string | null;
+    constructor(args: string[], stderr: string);
+}
+type Phase = 'SeedCommit' | 'SeedReveal' | 'Shuffle' | 'Playing' | 'AwaitingResponse' | 'AwaitingReveal' | 'Finished';
+type ChainPlayer = {
+    seed_committed: boolean;
+    seed_revealed: boolean;
+    dealt: boolean;
+    commitments: string[];
+    dead: boolean[];
+    influence: number;
+    alive: boolean;
+};
+type ChainGameState = {
+    phase: Phase;
+    n_players: number;
+    seed: string | null;
+    deck: string[];
+    players: ChainPlayer[];
+    turn: number;
+    last_claim_player: number | null;
+    last_claim_character: number | null;
+    challenger: number | null;
+    target: number | null;
+    pending_loser: number | null;
+    outcome: number | null;
+};
+type CliRefereeClientOptions = {
+    network?: string;
+    source?: string;
+    stellarBin?: string;
+    /** Bounded retry for transient (non-contract) CLI/network failures. */
+    retries?: number;
+    retryDelayMs?: number;
+    /**
+     * CLI identity name per seat index. When a per-seat mutating call is made
+     * for seat i, the transaction is signed by `sourceForSeat[i]` (falling
+     * back to `source`) so the referee's `require_auth()` sees the seat
+     * owner's signature. Deploys always use `source`.
+     */
+    sourceForSeat?: Record<number, string>;
+};
+/** Strips a leading `0x` from a hex string (Bytes/BytesN CLI args are hex WITHOUT `0x`). */
+declare function stripHexPrefix(hex: string): string;
+/** Big-endian 32-byte hex encoding of a non-negative bigint (no `0x` prefix). */
+declare function toBe32Hex(value: bigint): string;
+declare class CliRefereeClient {
+    private readonly network;
+    private readonly source;
+    private readonly stellarBin;
+    private readonly retries;
+    private readonly retryDelayMs;
+    private readonly sourceForSeat;
+    constructor(opts?: CliRefereeClientOptions);
+    /** `stellar contract deploy` for the `card_membership` verifier. Returns the deployed contract id. */
+    deployVerifier(wasmPath: string, vkHex: string): Promise<string>;
+    /**
+     * `stellar contract deploy` for the coup referee. Returns the deployed
+     * contract id. `playerAddresses[i]` becomes seat i's owner — every seat-i
+     * action must then be signed by that address (require_auth). `verifier`
+     * holds the `card_membership` VK; `shuffleVerifier` the `valid_shuffle`
+     * VK (M8.3).
+     */
+    deployReferee(wasmPath: string, opts: {
+        verifier: string;
+        shuffleVerifier: string;
+        playerAddresses: string[];
+    }): Promise<string>;
+    commitSeedNonce(refereeId: string, opts: {
+        player: number;
+        commitmentHex: string;
+    }): Promise<string | null>;
+    revealSeedNonce(refereeId: string, opts: {
+        player: number;
+        nonceHex: string;
+    }): Promise<string | null>;
+    /** Submits the 15 shuffle-proven deck leaves + the `valid_shuffle` proof (permissionless — the proof is the trust anchor). */
+    submitShuffle(refereeId: string, opts: {
+        leavesHex: string[];
+        proofHex: string;
+    }): Promise<string | null>;
+    claim(refereeId: string, opts: {
+        player: number;
+        character: number;
+    }): Promise<string | null>;
+    challenge(refereeId: string, opts: {
+        challenger: number;
+        target: number;
+    }): Promise<string | null>;
+    proveHold(refereeId: string, opts: {
+        target: number;
+        claimed: number;
+        proofHex: string;
+    }): Promise<string | null>;
+    revealCard(refereeId: string, opts: {
+        player: number;
+        slot: number;
+        card: number;
+        saltHex: string;
+    }): Promise<string | null>;
+    gameState(refereeId: string): Promise<ChainGameState>;
+    private runDeploy;
+    /**
+     * Mutating call (`--send=yes`). When `seat` is given, signs with that
+     * seat's identity (`sourceForSeat[seat]`, falling back to `source`) so
+     * the referee's per-seat `require_auth()` is satisfied.
+     */
+    private invoke;
+    /** Read-only call (no `--send`). */
+    private runReadOnly;
+    private execWithRetry;
+}
+
+type Roster = Array<{
+    id: PlayerId;
+}>;
+/** Roster of `count` seats (defaults to the 2-player demo; the referee + engine support 2-4). */
+declare function buildRoster(count?: number): Roster;
+/** Creates a local `Match` mirroring what the on-chain referee will enforce. */
+declare function createLocalMatch(roster: Roster, config: CoupLiteConfig, seed: string): Match;
+type LocalStep = {
+    playerId: PlayerId;
+    move: {
+        type: 'claim';
+        character: number;
+    };
+} | {
+    playerId: PlayerId;
+    move: {
+        type: 'challenge';
+    };
+};
+/** Advances the local match by exactly one move using the seeded strategy. */
+declare function stepLocalMatch(match: Match, seed: string): LocalStep;
+/** Plays a full LOCAL game (no chain) to a natural end, guarded against runaway loops. */
+declare function playLocalMatch(roster: Roster, config: CoupLiteConfig, seed: string, opts?: {
+    maxSteps?: number;
+}): {
+    match: Match;
+    steps: LocalStep[];
+};
+type PlayCoupLiteOptions = {
+    network?: string;
+    source?: string;
+    seed?: string;
+    verifierWasmPath?: string;
+    refereeWasmPath?: string;
+    vkPath?: string;
+    shuffleVkPath?: string;
+    log?: (line: string) => void;
+    /**
+     * When true, provisions one funded testnet identity per seat
+     * (`<source>-seat<i>`) and signs each seat's moves with its own key,
+     * demonstrating genuine multi-wallet play against require_auth().
+     * Default: every seat is owned and signed by `source`.
+     */
+    multiSeat?: boolean;
+    /** Seat count, 2-4 (referee-enforced). Defaults to 2. */
+    players?: number;
+};
+type Transcript = {
+    verifierContractId: string;
+    refereeContractId: string;
+    roster: Roster;
+    handsByPlayer: Record<PlayerId, Hand>;
+    moves: Array<{
+        kind: 'claim';
+        player: PlayerId;
+        playerIndex: number;
+        character: number;
+    } | {
+        kind: 'challenge';
+        challenger: PlayerId;
+        challengerIndex: number;
+        target: PlayerId;
+        targetIndex: number;
+        claim: ClaimEntry;
+        claimWasTrue: boolean;
+        loser: PlayerId;
+    }>;
+    finalState: ChainGameState;
+    outcome: PlayerId | null;
+};
+declare function ensureContractWasms(log: (line: string) => void): Promise<void>;
+/**
+ * Plays a COMPLETE game of Coup-lite on live Stellar testnet: deploys the
+ * `card_membership` verifier and the coup-referee, deals both players'
+ * semi-honestly committed hands, then claims/challenges per the seeded
+ * strategy - resolving each challenge with a REAL `card_membership` proof
+ * (when the claim was true) or a direct `reveal_card` decline (when it was a
+ * bluff) - to a real on-chain outcome.
+ */
+declare function playCoupLite(opts?: PlayCoupLiteOptions): Promise<Transcript>;
+
+declare const DEFAULT_VERIFIER_WASM: string;
+declare const DEFAULT_COUP_REFEREE_WASM: string;
+declare const DEFAULT_VK_PATH: string;
+declare const DEFAULT_SHUFFLE_VK_PATH: string;
+/** `child_process` env with `~/.nargo/bin` and `~/.bb/bin` prepended to PATH. */
+declare function toolEnv(): NodeJS.ProcessEnv;
+
+export { CHARACTERS, CHARACTER_NAMES, type CardProof, CardProver, type CardProverOptions, type ChainGameState, type ChainPlayer, type ClaimEntry, CliRefereeClient, type CoupLiteConfig, DEFAULT_COUP_REFEREE_WASM, DEFAULT_SHUFFLE_VK_PATH, DEFAULT_VERIFIER_WASM, DEFAULT_VK_PATH, HAND_SIZE, type Hand, type LocalStep, MAX_PLAYERS, MIN_PLAYERS, N_PLAYERS, type Phase, type PlayCoupLiteOptions, RefereeCliError, type Roster, START_INFLUENCE, type ShuffleProof, type Transcript, buildRoster, chooseMove, coupLite, createLocalMatch, ensureContractWasms, pickSeeded, playCoupLite, playLocalMatch, seededHand, stepLocalMatch, stripHexPrefix, toBe32Hex, toolEnv };

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+import * as _zktable_core from '@zktable/core';
+import { PlayerId, PlayerView, Move, Match } from '@zktable/core';
+
+/** 5 character ids, matching the `card_membership` circuit's small-int domain. */
+declare const CHARACTERS: readonly [0, 1, 2, 3, 4];
+declare const CHARACTER_NAMES: readonly ["Duke", "Assassin", "Captain", "Contessa", "Ambassador"];
+declare const HAND_SIZE = 2;
+declare const START_INFLUENCE = 2;
+/** The player range supported end-to-end (defineGame AND the on-chain referee). */
+declare const MIN_PLAYERS = 2;
+declare const MAX_PLAYERS = 4;
+/** Default seat count for the demos/runner (override with COUP_PLAYERS / opts.players). */
+declare const N_PLAYERS = 2;
+type Hand = [number, number];
+type ClaimEntry = {
+    player: PlayerId;
+    character: number;
+};
+/** Per-match config, passed as `MatchOptions.config.coupLite`. */
+type CoupLiteConfig = {
+    /**
+     * The REAL dealt hand per player. Required for the on-chain runner (the
+     * semi-honestly dealt, `card_membership`-provable hand); if omitted,
+     * `setup` derives a deterministic seeded hand from `MatchOptions.seed` so
+     * pure local tests don't need the prover pipeline.
+     */
+    handsByPlayer?: Record<PlayerId, Hand>;
+};
+/** Deterministic (seeded) hand of 2 DISTINCT characters, used only when no real dealt hand is supplied. */
+declare function seededHand(seed: string): Hand;
+declare const coupLite: _zktable_core.Game;
+
+/** Deterministically pick one element of `items`, keyed by `seed`. Throws on an empty array. */
+declare function pickSeeded<T>(items: readonly T[], seed: string): T;
+/**
+ * Decide whether to challenge the standing claim (`view.legalMoves` already
+ * confirms a `challenge` is legal here) or let it stand and make a new claim
+ * instead. Suspicion is higher when this player's own hand does NOT contain
+ * the claimed character (the only legitimate signal available), lower when
+ * it does.
+ */
+declare function chooseMove(view: PlayerView, seed: string): Move;
+
+type CardProof = {
+    proof: Uint8Array;
+    publicInputs: Uint8Array;
+    claimed: bigint;
+    commitmentsHex: [string, string];
+};
+/** The seed-forced shuffled deck plus its `valid_shuffle` proof (M8.3). */
+type ShuffleProof = {
+    proof: Uint8Array;
+    publicInputs: Uint8Array;
+    seedHex: string;
+    /** Card value (0-4) at each of the 15 deck positions — dealer-visible only. */
+    cards: number[];
+    /** Salt (decimal string) at each deck position. */
+    salts: string[];
+    /** Poseidon2(card, salt) leaf commitment (hex) at each deck position. */
+    leavesHex: string[];
+};
+type CardProverOptions = {
+    circuitDir?: string;
+    shuffleCircuitDir?: string;
+    graphToolsBin?: string;
+    nargoBin?: string;
+    bbBin?: string;
+    workDir?: string;
+};
+declare class CardProver {
+    private readonly circuitDir;
+    private readonly shuffleCircuitDir;
+    private readonly graphToolsBin;
+    private readonly nargoBin;
+    private readonly bbBin;
+    private readonly workDir;
+    private readonly env;
+    constructor(opts?: CardProverOptions);
+    private get targetDir();
+    private get bytecodePath();
+    private get vkPath();
+    private get shuffleTargetDir();
+    private get shuffleBytecodePath();
+    private get shuffleVkPath();
+    /** Compile the circuit once if `target/card_membership.json` is missing. */
+    ensureCompiled(): Promise<void>;
+    /** Generate the verification key once if `target/vk` is missing. */
+    ensureVk(): Promise<void>;
+    /** Compile `valid_shuffle` once if its bytecode is missing. */
+    ensureShuffleCompiled(): Promise<void>;
+    /** Generate the `valid_shuffle` verification key once if missing. */
+    ensureShuffleVk(): Promise<void>;
+    private writeVk;
+    /**
+     * Poseidon2(value, salt) via `zktable-graph commit` — used for the seed
+     * commit-reveal nonces (`hash2(nonce, 0)`), byte-identical to the referee.
+     */
+    commit(value: bigint, salt: bigint): Promise<string>;
+    /** The joint commit-reveal seed: left-fold of hash2 over the nonces (player-index order). */
+    seed(nonces: bigint[]): Promise<string>;
+    /**
+     * Full `valid_shuffle` pipeline (M8.3): derive the UNIQUE seed-forced
+     * permutation of the canonical 15-card deck via `zktable-graph
+     * shuffle-witness`, then `nargo execute` -> `bb prove`. The returned
+     * `cards`/`salts` are the dealer's private view (handed to each player
+     * off-chain); `leavesHex` + `proof` go on-chain via `submit_shuffle`.
+     */
+    proveShuffle(seedHex: string, salts: bigint[]): Promise<ShuffleProof>;
+    /**
+     * Full pipeline for one "prove-hold" claim: `zktable-graph card-witness` ->
+     * `nargo execute` -> `bb prove`. Runs entirely inside an isolated temp dir;
+     * never touches `card_membership/Prover.toml` or `card_membership/target/`
+     * (besides the shared, idempotent compiled bytecode).
+     */
+    proveHold(claimed: bigint, cards: [bigint, bigint], salts: [bigint, bigint], heldIndex: 0 | 1): Promise<CardProof>;
+    /** Off-chain check via `bb verify`, useful for sanity-checking a proof before spending a testnet tx. */
+    verifyLocally(proof: Uint8Array, publicInputs: Uint8Array): Promise<boolean>;
+    /** Off-chain `bb verify` of a `valid_shuffle` proof against ITS verification key. */
+    shuffleLocalVerify(proof: Uint8Array, publicInputs: Uint8Array): Promise<boolean>;
+    private bbVerify;
+}
+
+declare class RefereeCliError extends Error {
+    readonly args: string[];
+    readonly stderr: string;
+    readonly contractErrorCode: number | null;
+    readonly contractErrorName: string | null;
+    constructor(args: string[], stderr: string);
+}
+type Phase = 'SeedCommit' | 'SeedReveal' | 'Shuffle' | 'Playing' | 'AwaitingResponse' | 'AwaitingReveal' | 'Finished';
+type ChainPlayer = {
+    seed_committed: boolean;
+    seed_revealed: boolean;
+    dealt: boolean;
+    commitments: string[];
+    dead: boolean[];
+    influence: number;
+    alive: boolean;
+};
+type ChainGameState = {
+    phase: Phase;
+    n_players: number;
+    seed: string | null;
+    deck: string[];
+    players: ChainPlayer[];
+    turn: number;
+    last_claim_player: number | null;
+    last_claim_character: number | null;
+    challenger: number | null;
+    target: number | null;
+    pending_loser: number | null;
+    outcome: number | null;
+};
+type CliRefereeClientOptions = {
+    network?: string;
+    source?: string;
+    stellarBin?: string;
+    /** Bounded retry for transient (non-contract) CLI/network failures. */
+    retries?: number;
+    retryDelayMs?: number;
+    /**
+     * CLI identity name per seat index. When a per-seat mutating call is made
+     * for seat i, the transaction is signed by `sourceForSeat[i]` (falling
+     * back to `source`) so the referee's `require_auth()` sees the seat
+     * owner's signature. Deploys always use `source`.
+     */
+    sourceForSeat?: Record<number, string>;
+};
+/** Strips a leading `0x` from a hex string (Bytes/BytesN CLI args are hex WITHOUT `0x`). */
+declare function stripHexPrefix(hex: string): string;
+/** Big-endian 32-byte hex encoding of a non-negative bigint (no `0x` prefix). */
+declare function toBe32Hex(value: bigint): string;
+declare class CliRefereeClient {
+    private readonly network;
+    private readonly source;
+    private readonly stellarBin;
+    private readonly retries;
+    private readonly retryDelayMs;
+    private readonly sourceForSeat;
+    constructor(opts?: CliRefereeClientOptions);
+    /** `stellar contract deploy` for the `card_membership` verifier. Returns the deployed contract id. */
+    deployVerifier(wasmPath: string, vkHex: string): Promise<string>;
+    /**
+     * `stellar contract deploy` for the coup referee. Returns the deployed
+     * contract id. `playerAddresses[i]` becomes seat i's owner — every seat-i
+     * action must then be signed by that address (require_auth). `verifier`
+     * holds the `card_membership` VK; `shuffleVerifier` the `valid_shuffle`
+     * VK (M8.3).
+     */
+    deployReferee(wasmPath: string, opts: {
+        verifier: string;
+        shuffleVerifier: string;
+        playerAddresses: string[];
+    }): Promise<string>;
+    commitSeedNonce(refereeId: string, opts: {
+        player: number;
+        commitmentHex: string;
+    }): Promise<string | null>;
+    revealSeedNonce(refereeId: string, opts: {
+        player: number;
+        nonceHex: string;
+    }): Promise<string | null>;
+    /** Submits the 15 shuffle-proven deck leaves + the `valid_shuffle` proof (permissionless — the proof is the trust anchor). */
+    submitShuffle(refereeId: string, opts: {
+        leavesHex: string[];
+        proofHex: string;
+    }): Promise<string | null>;
+    claim(refereeId: string, opts: {
+        player: number;
+        character: number;
+    }): Promise<string | null>;
+    challenge(refereeId: string, opts: {
+        challenger: number;
+        target: number;
+    }): Promise<string | null>;
+    proveHold(refereeId: string, opts: {
+        target: number;
+        claimed: number;
+        proofHex: string;
+    }): Promise<string | null>;
+    revealCard(refereeId: string, opts: {
+        player: number;
+        slot: number;
+        card: number;
+        saltHex: string;
+    }): Promise<string | null>;
+    gameState(refereeId: string): Promise<ChainGameState>;
+    private runDeploy;
+    /**
+     * Mutating call (`--send=yes`). When `seat` is given, signs with that
+     * seat's identity (`sourceForSeat[seat]`, falling back to `source`) so
+     * the referee's per-seat `require_auth()` is satisfied.
+     */
+    private invoke;
+    /** Read-only call (no `--send`). */
+    private runReadOnly;
+    private execWithRetry;
+}
+
+type Roster = Array<{
+    id: PlayerId;
+}>;
+/** Roster of `count` seats (defaults to the 2-player demo; the referee + engine support 2-4). */
+declare function buildRoster(count?: number): Roster;
+/** Creates a local `Match` mirroring what the on-chain referee will enforce. */
+declare function createLocalMatch(roster: Roster, config: CoupLiteConfig, seed: string): Match;
+type LocalStep = {
+    playerId: PlayerId;
+    move: {
+        type: 'claim';
+        character: number;
+    };
+} | {
+    playerId: PlayerId;
+    move: {
+        type: 'challenge';
+    };
+};
+/** Advances the local match by exactly one move using the seeded strategy. */
+declare function stepLocalMatch(match: Match, seed: string): LocalStep;
+/** Plays a full LOCAL game (no chain) to a natural end, guarded against runaway loops. */
+declare function playLocalMatch(roster: Roster, config: CoupLiteConfig, seed: string, opts?: {
+    maxSteps?: number;
+}): {
+    match: Match;
+    steps: LocalStep[];
+};
+type PlayCoupLiteOptions = {
+    network?: string;
+    source?: string;
+    seed?: string;
+    verifierWasmPath?: string;
+    refereeWasmPath?: string;
+    vkPath?: string;
+    shuffleVkPath?: string;
+    log?: (line: string) => void;
+    /**
+     * When true, provisions one funded testnet identity per seat
+     * (`<source>-seat<i>`) and signs each seat's moves with its own key,
+     * demonstrating genuine multi-wallet play against require_auth().
+     * Default: every seat is owned and signed by `source`.
+     */
+    multiSeat?: boolean;
+    /** Seat count, 2-4 (referee-enforced). Defaults to 2. */
+    players?: number;
+};
+type Transcript = {
+    verifierContractId: string;
+    refereeContractId: string;
+    roster: Roster;
+    handsByPlayer: Record<PlayerId, Hand>;
+    moves: Array<{
+        kind: 'claim';
+        player: PlayerId;
+        playerIndex: number;
+        character: number;
+    } | {
+        kind: 'challenge';
+        challenger: PlayerId;
+        challengerIndex: number;
+        target: PlayerId;
+        targetIndex: number;
+        claim: ClaimEntry;
+        claimWasTrue: boolean;
+        loser: PlayerId;
+    }>;
+    finalState: ChainGameState;
+    outcome: PlayerId | null;
+};
+declare function ensureContractWasms(log: (line: string) => void): Promise<void>;
+/**
+ * Plays a COMPLETE game of Coup-lite on live Stellar testnet: deploys the
+ * `card_membership` verifier and the coup-referee, deals both players'
+ * semi-honestly committed hands, then claims/challenges per the seeded
+ * strategy - resolving each challenge with a REAL `card_membership` proof
+ * (when the claim was true) or a direct `reveal_card` decline (when it was a
+ * bluff) - to a real on-chain outcome.
+ */
+declare function playCoupLite(opts?: PlayCoupLiteOptions): Promise<Transcript>;
+
+declare const DEFAULT_VERIFIER_WASM: string;
+declare const DEFAULT_COUP_REFEREE_WASM: string;
+declare const DEFAULT_VK_PATH: string;
+declare const DEFAULT_SHUFFLE_VK_PATH: string;
+/** `child_process` env with `~/.nargo/bin` and `~/.bb/bin` prepended to PATH. */
+declare function toolEnv(): NodeJS.ProcessEnv;
+
+export { CHARACTERS, CHARACTER_NAMES, type CardProof, CardProver, type CardProverOptions, type ChainGameState, type ChainPlayer, type ClaimEntry, CliRefereeClient, type CoupLiteConfig, DEFAULT_COUP_REFEREE_WASM, DEFAULT_SHUFFLE_VK_PATH, DEFAULT_VERIFIER_WASM, DEFAULT_VK_PATH, HAND_SIZE, type Hand, type LocalStep, MAX_PLAYERS, MIN_PLAYERS, N_PLAYERS, type Phase, type PlayCoupLiteOptions, RefereeCliError, type Roster, START_INFLUENCE, type ShuffleProof, type Transcript, buildRoster, chooseMove, coupLite, createLocalMatch, ensureContractWasms, pickSeeded, playCoupLite, playLocalMatch, seededHand, stepLocalMatch, stripHexPrefix, toBe32Hex, toolEnv };