@zktable/circuits 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zkTable contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @zktable/circuits
+
+Pre-built, reusable Noir (UltraHonk) circuits — one per zkTable ZK primitive —
+plus TypeScript witness builders. Every game composes these; no game writes a
+circuit.
+
+## Circuits
+
+| Circuit | Module | Proves | Status |
+|---|---|---|---|
+| `simple_circuit` | — | `x != y` (M0 pipeline anchor) | ✅ built |
+| `fib_chain` | — | fibonacci chain (M0 second fixture) | ✅ built |
+| `board/move_along` | `board` | legal hidden edge move on a graph | M2 |
+| `hidden/predicate` | `hidden` | Poseidon commitment + predicate | M2 |
+| `dice/dice_valid` | `dice` | fair PRF-derived hidden roll | M6 |
+| `deck/valid_shuffle`, `deck/card_membership` | `deck` | valid shuffle + hand membership | M6 |
+| `sealed` | `sealed` | commit-reveal (Poseidon equality, no circuit needed) | M6 |
+
+## Building circuit artifacts
+
+Requires `nargo` 1.0.0-beta.9 and `bb` v0.87.0 on PATH
+(`$HOME/.nargo/bin:$HOME/.bb/bin`).
+
+```bash
+scripts/build_one.sh <circuit>     # e.g. board/move_along
+scripts/build_all.sh               # all circuits
+```
+
+Each produces under `<circuit>/target/`: `proof` (14592 B), `public_inputs`,
+`vk` (1760 B), plus `*_fields.json` variants.
+
+**Proving is fixed to `--scheme ultra_honk --oracle_hash keccak`** — the
+`keccak` oracle hash is required for the on-chain verifier. Do not change it.
+
+Built `target/` artifacts are git-ignored; regenerate with the scripts above.
+
+## Witness builders (TypeScript)
+
+`src/` exposes typed witness builders that turn a game move + player view into a
+circuit's `Prover.toml` inputs, so `@zktable/core` never hand-writes witnesses.

package/card_membership/Nargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "card_membership"
+type = "bin"
+authors = ["zkTable"]
+compiler_version = ">=1.0.0"
+
+[dependencies]
+poseidon = { tag = "v0.2.0", git = "https://github.com/noir-lang/poseidon" }

package/card_membership/src/main.nr

@@ -0,0 +1,106 @@
+// zkTable `deck` module - Coup-lite "prove-hold-or-bluff": prove a claimed
+// character card really is one of the two cards in a player's hidden hand,
+// without revealing the hand's contents (which card is which, or which slot
+// is the claimed one).
+//
+// HONEST SIMPLIFICATION (PRD SS7.2 / M6.3 brief): this is deck v1, NOT full
+// mental-poker/coSNARK dealing security. The hand is committed by a
+// semi-honest dealer/orchestrator off-chain (see the coup-referee's `deal`
+// phase and its module doc) - this circuit does not prove the deal itself
+// came from a valid shuffle (that would be a `valid_shuffle` circuit, out of
+// scope for v1, documented as future work). What IS proven, and IS
+// load-bearing: given a player's two already-committed hand cards, the
+// claimed character genuinely sits in that hand. This is exactly the "hold"
+// half of Coup's "prove-hold-or-bluff" - a player who is bluffing (the
+// claimed card is not in their hand) cannot produce a satisfying witness for
+// ANY `held_index`, so on challenge they must fall back to revealing a real
+// card instead (the referee's `reveal_card`) and lose influence.
+//
+// Hand size H = 2 (Coup: each player holds exactly 2 influence cards).
+// Per-card commitments: c_i = Poseidon2(card_i, salt_i)  (hash2), i in {0,1}.
+//
+// Public inputs (fixed order): [claimed_card, c_0, c_1]  (3 fields).
+// Private witness: card[2], salt[2], held_index (0 or 1, selects which hand
+// slot equals the public claim).
+//
+// Proves:
+//   1. BOTH hand cards open their public commitments: hash2(card[i], salt[i])
+//      == c_i for i in {0,1}. (Knowledge of the full, real hand contents -
+//      not just the claimed card - so a prover cannot fabricate a
+//      single-card "hand" that happens to match the claim.)
+//   2. held_index in {0,1} (a real slot selector, not an out-of-range value).
+//   3. The card at the selected slot equals the public claimed_card:
+//      card[held_index] == claimed_card. (Since H=2, this selection is done
+//      with a direct linear combination rather than a general selector
+//      gadget - see `select` below.)
+//
+// hash2 == Barretenberg/Noir Poseidon2 over 2 inputs, byte-identical to the
+// off-chain `zktable-graph` tool (soroban-poseidon `poseidon2_hash`) and the
+// on-chain referee's `poseidon2_hash2` - the same scheme `board`/`dice`
+// already use in production.
+use dep::poseidon::poseidon2::Poseidon2;
+
+// Fixed hand size. Public-input layout below assumes H = 2.
+global H: u32 = 2;
+
+fn hash2(a: Field, b: Field) -> Field {
+    Poseidon2::hash([a, b], 2)
+}
+
+// Linear-combination select over exactly 2 elements: held_index == 0 -> a[0],
+// held_index == 1 -> a[1]. Sound ONLY given the caller has already
+// constrained held_index * (held_index - 1) == 0 (see `main` below) - this
+// function performs no range check of its own.
+fn select2(a: [Field; H], held_index: Field) -> Field {
+    a[0] + held_index * (a[1] - a[0])
+}
+
+pub fn main(
+    claimed_card: pub Field,
+    c: pub [Field; H],
+    card: [Field; H],
+    salt: [Field; H],
+    held_index: Field,
+) {
+    // 1. Both hand cards open their public commitments - proves knowledge of
+    //    the REAL committed hand, not just a single fabricated card.
+    for i in 0..H {
+        assert(hash2(card[i], salt[i]) == c[i]);
+    }
+
+    // 2. held_index is a genuine slot selector (0 or 1), not an
+    //    out-of-range/wrapped value.
+    assert(held_index * (held_index - 1) == 0);
+
+    // 3. The selected hand slot really holds the claimed character.
+    let selected = select2(card, held_index);
+    assert(selected == claimed_card);
+}
+
+#[test]
+fn test_smoke() {
+    // Sanity: a commitment round-trips, and select2 picks the right slot.
+    let c0 = hash2(2, 11);
+    assert(c0 == hash2(2, 11));
+    assert(select2([2, 4], 0) == 2);
+    assert(select2([2, 4], 1) == 4);
+}
+
+#[test]
+fn test_hold_valid() {
+    // Hand = [Duke(=1), Assassin(=3)], held_index = 1 -> claiming Assassin.
+    let card = [1, 3];
+    let salt = [11, 22];
+    let c = [hash2(card[0], salt[0]), hash2(card[1], salt[1])];
+    main(3, c, card, salt, 1);
+}
+
+#[test(should_fail)]
+fn test_bluff_fails() {
+    // Hand does not contain the claimed character (Contessa = 4) at all -
+    // no held_index makes `select2(card, held_index) == claimed_card` hold.
+    let card = [1, 3];
+    let salt = [11, 22];
+    let c = [hash2(card[0], salt[0]), hash2(card[1], salt[1])];
+    main(4, c, card, salt, 0);
+}

package/dice_valid/Nargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "dice_valid"
+type = "bin"
+authors = ["zkTable"]
+compiler_version = ">=1.0.0"
+
+[dependencies]
+poseidon = { tag = "v0.2.0", git = "https://github.com/noir-lang/poseidon" }

package/dice_valid/src/main.nr

@@ -0,0 +1,104 @@
+// zkTable `dice` module - hidden, provably-fair dice for Liar's Dice.
+//
+// Proves a player's N=5 hidden dice are (1) committed, (2) valid faces in
+// {1,...,6}, and (3) the canonical, in-circuit-bound reduction of a per-die
+// hash derived from a PUBLIC shared seed and the player's id - so the roll is
+// unforgeable: it is fixed the moment the seed is fixed, before any die value
+// is revealed, and the circuit itself (not just an off-chain check) enforces
+// that binding.
+//
+// Commitments:  c_j = Poseidon2(d_j, salt_j)                    (hash2)
+// Per-die hash: H_j = Poseidon2(Poseidon2(seed, player_id), j)   (hash2 twice)
+// Fair value:   d_j = canonical_reduce_1_to_6(H_j)
+//
+// hash2 == Barretenberg/Noir Poseidon2 over 2 inputs, which the off-chain
+// dice tool (soroban-poseidon `poseidon2_hash`) reproduces exactly - the same
+// scheme the `board` module (move_along) already uses in production.
+use dep::poseidon::poseidon2::Poseidon2;
+
+// Fixed roll size and die sides. Public-input layout below assumes N = 5.
+global N: u32 = 5;
+global SIDES: Field = 6;
+
+// floor((p-1)/6) for the BN254 scalar field
+//   p = 21888242871839275222246405745257275088548364400416034343698204186575808495617.
+// This is the maximum possible integer value of the TRUE quotient
+// q = H_j / 6 (integer division) for any H_j in [0, p-1]. It bounds the
+// canonicality check in `constrain_fair_die` below.
+global Q_MAX: Field = 3648040478639879203707734290876212514758060733402672390616367364429301415936;
+
+// Q_MAX fits in 252 bits, and 2 * 2^252 < p (p has 254 bits), so a two-sided
+// 252-bit range check on q is sound with no field-wraparound ambiguity - see
+// `constrain_fair_die` and the report for the full argument.
+global Q_BITS: u32 = 252;
+
+fn hash2(a: Field, b: Field) -> Field {
+    Poseidon2::hash([a, b], 2)
+}
+
+// Enforce that `die` is the CANONICAL reduction of `h` into {1,...,SIDES}
+// (SIDES fixed at 6): h == q*SIDES + r as integers, 0 <= r <= SIDES-1,
+// die == r + 1. Field arithmetic alone (h == q*SIDES + r as a Field equation)
+// admits SIDES possible (q, r) solutions - one per residue r in {0..5} - since
+// SIDES is coprime to the prime field order p. Only one of those solutions has
+// q in the "true" integer-division range [0, Q_MAX]; the other SIDES-1 wrap
+// the field and land on q values that require far more than Q_BITS bits. The
+// two-sided range check below (q bounded AND Q_MAX - q bounded, both to
+// Q_BITS bits, with 2*2^Q_BITS < p) admits only the true, unwrapped solution.
+fn constrain_fair_die(h: Field, q: Field, r: Field, die: Field) {
+    // r in {0,...,5}: direct product constraint (SIDES is a small compile-time
+    // constant, so no general range gadget is needed).
+    assert(r * (r - 1) * (r - 2) * (r - 3) * (r - 4) * (r - 5) == 0);
+    // Euclidean relation h = q*6 + r (checked as a Field equation).
+    assert(h == q * SIDES + r);
+    // Canonicality: pin q into the integer range [0, Q_MAX], ruling out every
+    // field-wrapped alternative (q, r) pair.
+    q.assert_max_bit_size::<Q_BITS>();
+    (Q_MAX - q).assert_max_bit_size::<Q_BITS>();
+    // Face value.
+    assert(die == r + 1);
+}
+
+pub fn main(
+    seed: pub Field,
+    player_id: pub Field,
+    c: pub [Field; N],
+    d: [Field; N],
+    salt: [Field; N],
+    q: [Field; N],
+    r: [Field; N],
+) {
+    // Bind every per-die hash to the public (seed, player_id) pair once.
+    let seed_player = hash2(seed, player_id);
+
+    for j in 0..N {
+        let dj = d[j];
+
+        // 1. Commitment: the hidden die and salt open the public commitment.
+        assert(hash2(dj, salt[j]) == c[j]);
+
+        // 2. Valid die: dj in {1,...,6} (direct product constraint).
+        assert((dj - 1) * (dj - 2) * (dj - 3) * (dj - 4) * (dj - 5) * (dj - 6) == 0);
+
+        // 3. Fair derivation: dj is the canonical reduction into [1,6] of the
+        //    per-die hash H_j, which is itself recomputed in-circuit from the
+        //    public seed, player_id, and loop index j. This is what makes the
+        //    committed roll unforgeable: it is fully determined by (seed,
+        //    player_id, j) before any salt or commitment is chosen.
+        let h = hash2(seed_player, j as Field);
+        constrain_fair_die(h, q[j], r[j], dj);
+    }
+}
+
+#[test]
+fn test_smoke() {
+    // Sanity: a commitment round-trips, and the canonical reduction of a
+    // small concrete hash lands where expected. (Full end-to-end derivation
+    // is exercised by the Rust witness tool + `nargo execute` + `bb prove`,
+    // which control the seed and match the off-chain hash byte-for-byte.)
+    let c = hash2(7, 42);
+    assert(c == hash2(7, 42));
+
+    // h = 6*3 + 4 = 22 -> r = 4, die = 5.
+    constrain_fair_die(22, 3, 4, 5);
+}

package/dist/index.cjs

@@ -0,0 +1,304 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BoardGraph: () => BoardGraph,
+  BoardProver: () => BoardProver
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/graph.ts
+var import_node_child_process = require("child_process");
+var import_promises = require("fs/promises");
+var import_node_os2 = __toESM(require("os"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+var import_node_util = require("util");
+
+// src/paths.ts
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_node_url = require("url");
+var import_meta = {};
+var here = import_node_path.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url));
+var PACKAGE_ROOT = import_node_path.default.resolve(here, "..");
+var DEFAULT_CIRCUIT_DIR = import_node_path.default.join(PACKAGE_ROOT, "move_along");
+var CIRCUIT_PACKAGE_NAME = "move_along";
+var DEFAULT_GRAPH_TOOLS_BIN = import_node_path.default.resolve(
+  PACKAGE_ROOT,
+  "../contracts/tools/graph-tools/target/release/zktable-graph"
+);
+var DEFAULT_NARGO_BIN = "nargo";
+var DEFAULT_BB_BIN = "bb";
+function toolEnv() {
+  const home = import_node_os.default.homedir();
+  const extraDirs = [import_node_path.default.join(home, ".nargo", "bin"), import_node_path.default.join(home, ".bb", "bin")];
+  const currentPath = process.env.PATH ?? "";
+  return {
+    ...process.env,
+    PATH: [...extraDirs, currentPath].filter(Boolean).join(import_node_path.default.delimiter)
+  };
+}
+
+// src/graph.ts
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+function edgeKey(from, to, ticket) {
+  return `${from}:${to}:${ticket}`;
+}
+function canonicalEdgeSet(edges, bidirectional) {
+  const set = /* @__PURE__ */ new Set();
+  for (const e of edges) {
+    set.add(edgeKey(e.from, e.to, e.ticket));
+    if (bidirectional) {
+      set.add(edgeKey(e.to, e.from, e.ticket));
+    }
+  }
+  return set;
+}
+var BoardGraph = class {
+  data;
+  graphToolsBin;
+  edges;
+  constructor(data, opts) {
+    this.data = data;
+    this.graphToolsBin = opts?.graphToolsBin ?? DEFAULT_GRAPH_TOOLS_BIN;
+    this.edges = canonicalEdgeSet(data.edges, data.bidirectional ?? true);
+  }
+  /** Pure, local check: is (from, to, ticket) a legal edge of this graph? */
+  hasEdge(from, to, ticket) {
+    return this.edges.has(edgeKey(from, to, ticket));
+  }
+  /** Edge-tree root (hex), via `zktable-graph root`. */
+  async root() {
+    const dir = await (0, import_promises.mkdtemp)(import_node_path2.default.join(import_node_os2.default.tmpdir(), "zktable-graph-root-"));
+    try {
+      const graphPath = import_node_path2.default.join(dir, "graph.json");
+      await (0, import_promises.writeFile)(graphPath, JSON.stringify(this.data));
+      const { stdout } = await execFileAsync(this.graphToolsBin, ["root", "--graph", graphPath], {
+        env: toolEnv()
+      });
+      return stdout.trim();
+    } finally {
+      await (0, import_promises.rm)(dir, { recursive: true, force: true });
+    }
+  }
+  /** Poseidon2(node, salt) (hex), via `zktable-graph commit`. */
+  async commit(node, salt) {
+    const { stdout } = await execFileAsync(
+      this.graphToolsBin,
+      ["commit", "--node", String(node), "--salt", salt.toString()],
+      { env: toolEnv() }
+    );
+    return stdout.trim();
+  }
+};
+
+// src/prover.ts
+var import_node_child_process2 = require("child_process");
+var import_promises2 = require("fs/promises");
+var import_node_os3 = __toESM(require("os"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+var import_node_util2 = require("util");
+var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
+async function exists(p) {
+  try {
+    await (0, import_promises2.access)(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var BoardProver = class {
+  circuitDir;
+  graphToolsBin;
+  nargoBin;
+  bbBin;
+  workDir;
+  env;
+  constructor(opts = {}) {
+    this.circuitDir = opts.circuitDir ?? DEFAULT_CIRCUIT_DIR;
+    this.graphToolsBin = opts.graphToolsBin ?? DEFAULT_GRAPH_TOOLS_BIN;
+    this.nargoBin = opts.nargoBin ?? DEFAULT_NARGO_BIN;
+    this.bbBin = opts.bbBin ?? DEFAULT_BB_BIN;
+    this.workDir = opts.workDir ?? import_node_os3.default.tmpdir();
+    this.env = toolEnv();
+  }
+  get targetDir() {
+    return import_node_path3.default.join(this.circuitDir, "target");
+  }
+  get bytecodePath() {
+    return import_node_path3.default.join(this.targetDir, `${CIRCUIT_PACKAGE_NAME}.json`);
+  }
+  get vkPath() {
+    return import_node_path3.default.join(this.targetDir, "vk");
+  }
+  /** Compile the circuit once if `target/move_along.json` is missing. */
+  async ensureCompiled() {
+    if (await exists(this.bytecodePath)) return;
+    await execFileAsync2(this.nargoBin, ["compile"], { cwd: this.circuitDir, env: this.env });
+  }
+  /** Generate the verification key once if `target/vk` is missing. */
+  async ensureVk() {
+    await this.ensureCompiled();
+    if (await exists(this.vkPath)) return;
+    await execFileAsync2(
+      this.bbBin,
+      [
+        "write_vk",
+        "--scheme",
+        "ultra_honk",
+        "--oracle_hash",
+        "keccak",
+        "--bytecode_path",
+        this.bytecodePath,
+        "--output_path",
+        this.targetDir,
+        "--output_format",
+        "bytes_and_fields"
+      ],
+      { env: this.env }
+    );
+  }
+  /**
+   * Full pipeline: write graph -> `zktable-graph witness` -> `nargo execute`
+   * -> `bb prove`. Runs entirely inside an isolated temp dir; never touches
+   * `move_along/Prover.toml` or `move_along/target/`.
+   */
+  async prove(graph, move) {
+    await this.ensureCompiled();
+    const dir = await (0, import_promises2.mkdtemp)(import_node_path3.default.join(this.workDir, "zktable-prove-"));
+    try {
+      const graphPath = import_node_path3.default.join(dir, "graph.json");
+      const proverTomlPath = import_node_path3.default.join(dir, "Prover");
+      const witnessJsonPath = import_node_path3.default.join(dir, "witness.json");
+      const witnessOutPath = import_node_path3.default.join(dir, "witness");
+      await (0, import_promises2.writeFile)(graphPath, JSON.stringify(graph));
+      await execFileAsync2(
+        this.graphToolsBin,
+        [
+          "witness",
+          "--graph",
+          graphPath,
+          "--from",
+          String(move.from),
+          "--to",
+          String(move.to),
+          "--ticket",
+          String(move.ticket),
+          "--salt-old",
+          move.saltOld.toString(),
+          "--salt-new",
+          move.saltNew.toString(),
+          "--prover",
+          `${proverTomlPath}.toml`,
+          "--json",
+          witnessJsonPath
+        ],
+        { env: this.env }
+      );
+      const witness = JSON.parse(await (0, import_promises2.readFile)(witnessJsonPath, "utf8"));
+      await execFileAsync2(this.nargoBin, ["execute", "--prover-name", proverTomlPath, witnessOutPath], {
+        cwd: this.circuitDir,
+        env: this.env
+      });
+      await execFileAsync2(
+        this.bbBin,
+        [
+          "prove",
+          "--scheme",
+          "ultra_honk",
+          "--oracle_hash",
+          "keccak",
+          "--bytecode_path",
+          this.bytecodePath,
+          "--witness_path",
+          `${witnessOutPath}.gz`,
+          "--output_path",
+          dir,
+          "--output_format",
+          "bytes_and_fields"
+        ],
+        { env: this.env }
+      );
+      const proof = new Uint8Array(await (0, import_promises2.readFile)(import_node_path3.default.join(dir, "proof")));
+      const publicInputs = new Uint8Array(await (0, import_promises2.readFile)(import_node_path3.default.join(dir, "public_inputs")));
+      return {
+        proof,
+        publicInputs,
+        cOld: witness.c_old,
+        cNew: witness.c_new,
+        root: witness.root,
+        ticket: move.ticket
+      };
+    } finally {
+      await (0, import_promises2.rm)(dir, { recursive: true, force: true });
+    }
+  }
+  /** Off-chain check via `bb verify`. */
+  async verifyLocally(proof) {
+    await this.ensureVk();
+    const dir = await (0, import_promises2.mkdtemp)(import_node_path3.default.join(this.workDir, "zktable-verify-"));
+    try {
+      const proofPath = import_node_path3.default.join(dir, "proof");
+      const publicInputsPath = import_node_path3.default.join(dir, "public_inputs");
+      await (0, import_promises2.writeFile)(proofPath, proof.proof);
+      await (0, import_promises2.writeFile)(publicInputsPath, proof.publicInputs);
+      try {
+        await execFileAsync2(
+          this.bbBin,
+          [
+            "verify",
+            "--scheme",
+            "ultra_honk",
+            "--oracle_hash",
+            "keccak",
+            "--proof_path",
+            proofPath,
+            "--vk_path",
+            this.vkPath,
+            "--public_inputs_path",
+            publicInputsPath
+          ],
+          { env: this.env }
+        );
+        return true;
+      } catch {
+        return false;
+      }
+    } finally {
+      await (0, import_promises2.rm)(dir, { recursive: true, force: true });
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BoardGraph,
+  BoardProver
+});

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+type Ticket = 0 | 1 | 2;
+type GraphEdge = {
+    from: number;
+    to: number;
+    ticket: Ticket;
+};
+type GraphData = {
+    nodes: number[];
+    edges: GraphEdge[];
+    /** Expand each edge to both directions. Defaults to true. */
+    bidirectional?: boolean;
+};
+type BoardMove = {
+    from: number;
+    to: number;
+    ticket: Ticket;
+    saltOld: bigint;
+    saltNew: bigint;
+};
+type BoardProof = {
+    /** UltraHonk proof bytes (14592 bytes). */
+    proof: Uint8Array;
+    /** c_old | c_new | ticket | root, 32 bytes each = 128 bytes total. */
+    publicInputs: Uint8Array;
+    cOld: string;
+    cNew: string;
+    root: string;
+    ticket: Ticket;
+};
+
+/**
+ * A public transit graph. Wraps the `zktable-graph` Rust CLI for the
+ * hash-dependent operations (edge-tree root, Poseidon commitments) and does
+ * pure, local edge-membership checks in TS.
+ */
+declare class BoardGraph {
+    readonly data: GraphData;
+    private readonly graphToolsBin;
+    private readonly edges;
+    constructor(data: GraphData, opts?: {
+        graphToolsBin?: string;
+    });
+    /** Pure, local check: is (from, to, ticket) a legal edge of this graph? */
+    hasEdge(from: number, to: number, ticket: Ticket): boolean;
+    /** Edge-tree root (hex), via `zktable-graph root`. */
+    root(): Promise<string>;
+    /** Poseidon2(node, salt) (hex), via `zktable-graph commit`. */
+    commit(node: number, salt: bigint): Promise<string>;
+}
+
+type BoardProverOptions = {
+    circuitDir?: string;
+    graphToolsBin?: string;
+    nargoBin?: string;
+    bbBin?: string;
+    workDir?: string;
+};
+/**
+ * Orchestrates the full `board` module pipeline against real tools: writes
+ * the graph, builds the witness via `zktable-graph`, executes the circuit
+ * via `nargo`, and proves/verifies via `bb`. No mocks — every call produces
+ * or checks a real UltraHonk proof.
+ */
+declare class BoardProver {
+    private readonly circuitDir;
+    private readonly graphToolsBin;
+    private readonly nargoBin;
+    private readonly bbBin;
+    private readonly workDir;
+    private readonly env;
+    constructor(opts?: BoardProverOptions);
+    private get targetDir();
+    private get bytecodePath();
+    private get vkPath();
+    /** Compile the circuit once if `target/move_along.json` is missing. */
+    private ensureCompiled;
+    /** Generate the verification key once if `target/vk` is missing. */
+    private ensureVk;
+    /**
+     * Full pipeline: write graph -> `zktable-graph witness` -> `nargo execute`
+     * -> `bb prove`. Runs entirely inside an isolated temp dir; never touches
+     * `move_along/Prover.toml` or `move_along/target/`.
+     */
+    prove(graph: GraphData, move: BoardMove): Promise<BoardProof>;
+    /** Off-chain check via `bb verify`. */
+    verifyLocally(proof: BoardProof): Promise<boolean>;
+}
+
+export { BoardGraph, type BoardMove, type BoardProof, BoardProver, type BoardProverOptions, type GraphData, type GraphEdge, type Ticket };