enigma-memory 0.1.18 → 0.1.22

package/cortex-v3/zk/intent-witness.test.mjs

@@ -0,0 +1,485 @@
+// intent-witness.test.mjs — tests for zk/intent-witness.mjs, the client-side
+// witness builder for circuits/intent_attestation.circom (IntentAttestation).
+//
+// Legs:
+//   1. actionHash KAT — fixed x402 descriptor → pinned decimal digest, plus an
+//      independent recomputation (raw circomlibjs + Buffer LE limbs).
+//   2. descriptor limb derivation — base58 decode, LE split, each < 2^128.
+//   3. payloadCommit / intent nullifier — independent recomputation.
+//   4. AllowlistTree (D=16) — membership proof verifies, foreign leaf fails.
+//   5. buildIntentWitness — full valid witness shape, exact signal names,
+//      public-signal order; client-side rejections (over-cap amount,
+//      non-allowlisted recipient, time lock) throw.
+//   6. Signal-name reconciliation vs circuits/intent_attestation.circom
+//      (when the file exists): every `signal input` name must match exactly.
+//   7. WASM-gated (polls up to 20 min for IntentCircuitBuild artifacts;
+//      override with INTENT_WITNESS_POLL_MS=0 to skip immediately):
+//      valid witness satisfies the compiled circuit; tampered witnesses
+//      (amount > maxAmount, validAfterSlot > currentSlot, non-allowlisted
+//      payee limbs) are rejected by the witness calculator.
+//
+// Run: node --test cortex-v3/zk/intent-witness.test.mjs
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { buildPoseidon } from "circomlibjs";
+import bs58 from "bs58";
+
+import { NoteTree, verifyMerkleProof } from "./zk-tree.mjs";
+import {
+  ALLOW_DEPTH,
+  AllowlistTree,
+  DOMAIN_ACTION,
+  DOMAIN_ALLOW,
+  DOMAIN_INTENT_NF,
+  DOMAIN_POLICY,
+  INTENT_PUBLIC_SIGNALS,
+  NOTE_DEPTH,
+  buildIntentWitness,
+  computeActionHash,
+  computeIntentNote,
+  computeIntentNullifier,
+  computePayloadCommit,
+} from "./intent-witness.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "..");
+const BUILD = join(PKG_ROOT, "circuits", "build");
+const CIRCUIT_SRC = join(PKG_ROOT, "circuits", "intent_attestation.circom");
+const R1CS = join(BUILD, "intent_attestation.r1cs");
+const WASM = join(BUILD, "intent_attestation_js", "intent_attestation.wasm");
+const WITNESS_CALC = join(BUILD, "intent_attestation_js", "witness_calculator.js");
+
+const require = createRequire(import.meta.url);
+
+// ---------------------------------------------------------------------------
+// Fixed test fixture
+// ---------------------------------------------------------------------------
+const RECIPIENT = "So11111111111111111111111111111111111111112"; // wSOL mint addr as payee
+const MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"; // USDC mint
+const AMOUNT = 1_000_000_000n; // 1 SOL in lamports
+const NONCE = Uint8Array.from({ length: 16 }, (_, i) => i + 1);
+const OWNER_KEY = 12345678901234567890123456789012345678901234567890n;
+const RHO = 98765432109876543210987654321098765432109876543210n;
+const MAX_AMOUNT = 2_000_000_000n;
+const VALID_AFTER = 100n;
+const CURRENT_SLOT = 150n;
+
+// KAT pinned by an independent computation (raw circomlibjs poseidon over
+// limbs derived with Buffer LE reduction — see the independent leg below).
+const KAT = Object.freeze({
+  rLo: 71446497128034137124372738219197373190n,
+  rHi: 1329227996075816458295437426742117594n,
+  mintLo: 65738568574496699805876393164525992646n,
+  mintHi: 129418957939906822851699979667271629745n,
+  nonce: 21345817372864405881847059188222722561n,
+  actionHash: 11192328813738960605611739244535981126494623159630851179122912860248433917861n,
+  payeeLeaf: 7211849756294928538748674744383553675446290308714877925270988920289318996875n,
+});
+
+const poseidonC = await buildPoseidon();
+const F = poseidonC.F;
+const independentPoseidon = (xs) => F.toObject(poseidonC(xs.map((x) => F.e(BigInt(x)))));
+
+/** Independent LE reducer (Buffer-based, no shared code with the module). */
+function leBytes(buf) {
+  let v = 0n;
+  for (let i = buf.length - 1; i >= 0; i--) v = v * 256n + BigInt(buf[i]);
+  return v;
+}
+
+/** Build the standard valid fixture: note tree + allowlist + witness args. */
+function makeFixture() {
+  const allowlist = new AllowlistTree();
+  allowlist.insert(RECIPIENT);
+  const noteTree = new NoteTree();
+  noteTree.insert(111n); // filler note at index 0
+  const payloadCommit = computePayloadCommit({
+    maxAmount: MAX_AMOUNT,
+    allowlistRoot: allowlist.root(),
+    validAfterSlot: VALID_AFTER,
+  });
+  noteTree.insert(computeIntentNote(OWNER_KEY, RHO, payloadCommit)); // index 1
+  return {
+    noteTree,
+    allowlist,
+    args: {
+      noteTree,
+      noteIndex: 1,
+      ownerKey: OWNER_KEY,
+      rho: RHO,
+      maxAmount: MAX_AMOUNT,
+      allowlist,
+      validAfterSlot: VALID_AFTER,
+      recipient: RECIPIENT,
+      mint: MINT,
+      amountLamports: AMOUNT,
+      nonceBytes: NONCE,
+      currentSlot: CURRENT_SLOT,
+    },
+  };
+}
+
+const EXPECTED_SIGNALS = Object.freeze([
+  ...INTENT_PUBLIC_SIGNALS,
+  "ownerKey",
+  "rho",
+  "maxAmount",
+  "allowlistRoot",
+  "validAfterSlot",
+  "notePathElements",
+  "notePathIndices",
+  "rLo",
+  "rHi",
+  "mintLo",
+  "mintHi",
+  "amount",
+  "nonce",
+  "allowPathElements",
+  "allowPathIndices",
+]);
+
+// ---------------------------------------------------------------------------
+// 1–2. actionHash KAT + limb derivation
+// ---------------------------------------------------------------------------
+test("computeActionHash matches the pinned KAT and independent recomputation", () => {
+  const out = computeActionHash({
+    recipientPubkeyBase58: RECIPIENT,
+    mintBase58: MINT,
+    amountLamports: AMOUNT,
+    nonceBytes: NONCE,
+  });
+
+  // pinned known-answer values
+  assert.equal(out.rLo, KAT.rLo);
+  assert.equal(out.rHi, KAT.rHi);
+  assert.equal(out.mintLo, KAT.mintLo);
+  assert.equal(out.mintHi, KAT.mintHi);
+  assert.equal(out.amount, AMOUNT);
+  assert.equal(out.nonce, KAT.nonce);
+  assert.equal(out.actionHash, KAT.actionHash, "actionHash KAT drifted");
+
+  // fully independent recomputation (no module code)
+  const r = bs58.decode(RECIPIENT);
+  const m = bs58.decode(MINT);
+  assert.equal(r.length, 32);
+  assert.equal(m.length, 32);
+  const limbs = [
+    leBytes(r.subarray(0, 16)),
+    leBytes(r.subarray(16, 32)),
+    leBytes(m.subarray(0, 16)),
+    leBytes(m.subarray(16, 32)),
+    AMOUNT,
+    leBytes(NONCE),
+  ];
+  const TWO_128 = 1n << 128n;
+  for (const limb of limbs) {
+    assert.ok(limb >= 0n && limb < TWO_128, `limb ${limb} outside [0, 2^128)`);
+  }
+  assert.equal(out.rLo, limbs[0]);
+  assert.equal(out.rHi, limbs[1]);
+  assert.equal(out.mintLo, limbs[2]);
+  assert.equal(out.mintHi, limbs[3]);
+  assert.equal(out.nonce, limbs[5]);
+  assert.equal(
+    out.actionHash,
+    independentPoseidon([DOMAIN_ACTION, ...limbs]),
+    "independent Poseidon7 recomputation disagrees",
+  );
+});
+
+test("computeActionHash rejects malformed descriptors", () => {
+  assert.throws(
+    () =>
+      computeActionHash({
+        recipientPubkeyBase58: "1111", // 3 bytes, not 32
+        mintBase58: MINT,
+        amountLamports: AMOUNT,
+        nonceBytes: NONCE,
+      }),
+    /32 bytes/,
+  );
+  assert.throws(
+    () =>
+      computeActionHash({
+        recipientPubkeyBase58: RECIPIENT,
+        mintBase58: MINT,
+        amountLamports: 1n << 64n, // u64 overflow
+        nonceBytes: NONCE,
+      }),
+    /u64/,
+  );
+  assert.throws(
+    () =>
+      computeActionHash({
+        recipientPubkeyBase58: RECIPIENT,
+        mintBase58: MINT,
+        amountLamports: AMOUNT,
+        nonceBytes: new Uint8Array(8), // wrong nonce length
+      }),
+    /16 bytes/,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 3. payloadCommit + nullifier
+// ---------------------------------------------------------------------------
+test("computePayloadCommit and computeIntentNullifier match independent recomputation", () => {
+  const allowlistRoot = 42424242424242424242424242424242424242424242424242n;
+  const pc = computePayloadCommit({
+    maxAmount: MAX_AMOUNT,
+    allowlistRoot,
+    validAfterSlot: VALID_AFTER,
+  });
+  assert.equal(
+    pc,
+    independentPoseidon([DOMAIN_POLICY, MAX_AMOUNT, allowlistRoot, VALID_AFTER]),
+  );
+
+  const nf = computeIntentNullifier(OWNER_KEY, KAT.actionHash);
+  assert.equal(nf, independentPoseidon([DOMAIN_INTENT_NF, OWNER_KEY, KAT.actionHash]));
+
+  const note = computeIntentNote(OWNER_KEY, RHO, pc);
+  assert.equal(note, independentPoseidon([OWNER_KEY, RHO, pc]));
+});
+
+// ---------------------------------------------------------------------------
+// 4. AllowlistTree
+// ---------------------------------------------------------------------------
+test("AllowlistTree depth-16 membership proofs verify; foreign leaves fail", () => {
+  const tree = new AllowlistTree();
+  assert.equal(tree.depth, ALLOW_DEPTH);
+  const ins = tree.insert(RECIPIENT);
+  assert.equal(ins.index, 0);
+  assert.equal(ins.leaf, KAT.payeeLeaf, "payee leaf KAT drifted");
+  assert.equal(ins.leaf, independentPoseidon([DOMAIN_ALLOW, KAT.rLo, KAT.rHi]));
+  assert.equal(ins.pathElements.length, ALLOW_DEPTH);
+  assert.equal(ins.pathIndices.length, ALLOW_DEPTH);
+
+  assert.ok(tree.verifyProof(ins.leaf, ins.pathElements, ins.pathIndices), "own proof must verify");
+  assert.ok(
+    verifyMerkleProof(ins.leaf, ins.pathElements, ins.pathIndices, tree.root(), ALLOW_DEPTH),
+    "zk-tree verifyMerkleProof(depth=16) must verify the allowlist proof",
+  );
+
+  // a second payee; both proofs still verify against the updated root
+  const other = "11111111111111111111111111111111"; // system program (32 zero bytes)
+  const ins2 = tree.insert(other);
+  assert.equal(ins2.index, 1);
+  assert.ok(tree.verifyProof(ins.leaf, tree.getProof(0).pathElements, tree.getProof(0).pathIndices));
+  assert.ok(tree.verifyProof(ins2.leaf, ins2.pathElements, ins2.pathIndices));
+
+  // foreign leaf must not verify
+  const foreign = independentPoseidon([DOMAIN_ALLOW, 1n, 2n]);
+  assert.ok(!tree.verifyProof(foreign, ins2.pathElements, ins2.pathIndices));
+  assert.equal(tree.indexOf(1n, 2n), -1);
+  assert.equal(tree.indexOf(KAT.rLo, KAT.rHi), 0);
+});
+
+// ---------------------------------------------------------------------------
+// 5. buildIntentWitness
+// ---------------------------------------------------------------------------
+test("buildIntentWitness emits exact signal names, decimal strings, public order", () => {
+  const { args, noteTree, allowlist } = makeFixture();
+  const w = buildIntentWitness(args);
+
+  assert.deepEqual(
+    Object.keys(w).sort(),
+    [...EXPECTED_SIGNALS].sort(),
+    "witness signal-name set drifted from the circuit spec",
+  );
+  for (const [k, v] of Object.entries(w)) {
+    if (Array.isArray(v)) {
+      for (const x of v) assert.match(x, /^\d+$/, `${k} element not a decimal string`);
+    } else {
+      assert.match(v, /^\d+$/, `${k} not a decimal string`);
+    }
+  }
+
+  assert.equal(w.notePathElements.length, NOTE_DEPTH);
+  assert.equal(w.notePathIndices.length, NOTE_DEPTH);
+  assert.equal(w.allowPathElements.length, ALLOW_DEPTH);
+  assert.equal(w.allowPathIndices.length, ALLOW_DEPTH);
+
+  // public values
+  assert.equal(w.noteRoot, noteTree.root().toString());
+  assert.equal(w.actionHash, KAT.actionHash.toString());
+  assert.equal(w.nullifier, computeIntentNullifier(OWNER_KEY, KAT.actionHash).toString());
+  assert.equal(w.currentSlot, CURRENT_SLOT.toString());
+  assert.deepEqual(
+    INTENT_PUBLIC_SIGNALS,
+    ["noteRoot", "actionHash", "nullifier", "currentSlot"],
+    "public signal order must be [noteRoot, actionHash, nullifier, currentSlot]",
+  );
+
+  // private consistency
+  assert.equal(w.allowlistRoot, allowlist.root().toString());
+  assert.equal(w.rLo, KAT.rLo.toString());
+  assert.equal(w.rHi, KAT.rHi.toString());
+  assert.equal(w.mintLo, KAT.mintLo.toString());
+  assert.equal(w.mintHi, KAT.mintHi.toString());
+  assert.equal(w.amount, AMOUNT.toString());
+  assert.equal(w.nonce, KAT.nonce.toString());
+});
+
+test("buildIntentWitness rejects policy-violating intents client-side", () => {
+  const { args } = makeFixture();
+
+  // amount over the policy cap
+  assert.throws(
+    () => buildIntentWitness({ ...args, amountLamports: MAX_AMOUNT + 1n }),
+    /exceeds policy maxAmount/,
+  );
+  // time lock not yet reached
+  assert.throws(
+    () => buildIntentWitness({ ...args, currentSlot: VALID_AFTER - 1n }),
+    /not yet valid/,
+  );
+  // non-allowlisted recipient
+  assert.throws(
+    () => buildIntentWitness({ ...args, recipient: "11111111111111111111111111111111" }),
+    /not in the allowlist/,
+  );
+  // note opening does not match the leaf at noteIndex
+  assert.throws(
+    () => buildIntentWitness({ ...args, rho: RHO + 1n }),
+    /does not match the leaf/,
+  );
+  // stale noteIndex
+  assert.throws(() => buildIntentWitness({ ...args, noteIndex: 7 }), /not present/);
+});
+
+// ---------------------------------------------------------------------------
+// 6. Signal-name reconciliation vs the .circom source (when present)
+// ---------------------------------------------------------------------------
+test("signal names reconcile with circuits/intent_attestation.circom", (t) => {
+  if (!existsSync(CIRCUIT_SRC)) {
+    t.skip("circuits/intent_attestation.circom not present yet (IntentCircuitBuild in flight)");
+    return;
+  }
+  const src = readFileSync(CIRCUIT_SRC, "utf8").replace(/\/\/[^\n]*/g, "");
+  // Scope to the main template body: helper templates (DualMux/MerkleRoot/
+  // PoseidonN) declare their own generic `signal input`s that are not part
+  // of the witness contract.
+  const tplStart = src.indexOf("template IntentAttestation");
+  const tplEnd = src.indexOf("component main");
+  assert.ok(tplStart !== -1 && tplEnd > tplStart, "IntentAttestation template not found");
+  const tpl = src.slice(tplStart, tplEnd);
+  const declared = new Set();
+  for (const m of tpl.matchAll(/signal\s+input\s+(\w+)/g)) declared.add(m[1]);
+  assert.ok(declared.size > 0, "no `signal input` declarations found in the circuit");
+  assert.deepEqual(
+    [...declared].sort(),
+    [...EXPECTED_SIGNALS].sort(),
+    "circuit signal inputs diverge from intent-witness.mjs emission",
+  );
+  // public order in component main
+  const mainMatch = src.match(/component\s+main\s*\{[^}]*public\s*\[([^\]]*)\]/s);
+  assert.ok(mainMatch, "component main {public [...]} not found");
+  const pub = mainMatch[1].split(",").map((s) => s.trim());
+  assert.deepEqual(pub, [...INTENT_PUBLIC_SIGNALS], "public input order diverges");
+});
+
+// ---------------------------------------------------------------------------
+// 7. WASM-gated circuit satisfaction legs
+// ---------------------------------------------------------------------------
+const POLL_MS = Number(process.env.INTENT_WITNESS_POLL_MS ?? 20 * 60 * 1000);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+let wasmReady = existsSync(WASM) && existsSync(WITNESS_CALC);
+if (!wasmReady && POLL_MS > 0) {
+  const deadline = Date.now() + POLL_MS;
+  while (Date.now() < deadline) {
+    await sleep(15_000);
+    if (existsSync(WASM) && existsSync(WITNESS_CALC)) {
+      wasmReady = true;
+      break;
+    }
+  }
+}
+if (!wasmReady) {
+  console.log(
+    `[intent-witness] intent_attestation wasm artifacts absent after polling ` +
+      `(${WASM}); circuit-satisfaction legs will SKIP.`,
+  );
+}
+
+/** `snarkjs wtns check` → true if the witness satisfies the R1CS. */
+function wtnsCheck(wtnsPath) {
+  try {
+    execFileSync("npx", ["snarkjs", "wtns", "check", R1CS, wtnsPath], {
+      shell: true,
+      stdio: "pipe",
+      cwd: PKG_ROOT,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+test("compiled circuit accepts a valid intent witness", async (t) => {
+  if (!wasmReady) {
+    t.skip("intent_attestation wasm absent (see log above); nothing to check against");
+    return;
+  }
+  const tmp = mkdtempSync(join(tmpdir(), "enigma-intent-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  const { args } = makeFixture();
+  const input = buildIntentWitness(args);
+
+  const buildCalc = require(WITNESS_CALC);
+  const calc = await buildCalc(readFileSync(WASM));
+  // sanityCheck=true: the calculator enforces every constraint (asserts).
+  const bin = Buffer.from(await calc.calculateWTNSBin(input, true));
+  const wtnsPath = join(tmp, "intent.wtns");
+  writeFileSync(wtnsPath, bin);
+
+  if (existsSync(R1CS)) {
+    assert.ok(wtnsCheck(wtnsPath), "valid intent witness must satisfy the R1CS");
+  }
+});
+
+test("compiled circuit rejects policy-violating witnesses", async (t) => {
+  if (!wasmReady) {
+    t.skip("intent_attestation wasm absent (see log above); nothing to check against");
+    return;
+  }
+  const { args } = makeFixture();
+  const valid = buildIntentWitness(args);
+  const buildCalc = require(WITNESS_CALC);
+  const calc = await buildCalc(readFileSync(WASM));
+
+  // amount above the policy cap (bypasses the client-side guard by tampering
+  // the emitted input — exactly what a cheating prover would try).
+  const overCap = { ...valid, amount: (MAX_AMOUNT + 1n).toString() };
+  await assert.rejects(
+    () => calc.calculateWTNSBin(overCap, true),
+    /Assert Failed|Error/,
+    "circuit must reject amount > maxAmount",
+  );
+
+  // time lock violated: validAfterSlot after currentSlot.
+  const tooEarly = { ...valid, validAfterSlot: (CURRENT_SLOT + 1n).toString() };
+  await assert.rejects(
+    () => calc.calculateWTNSBin(tooEarly, true),
+    /Assert Failed|Error/,
+    "circuit must reject validAfterSlot > currentSlot",
+  );
+
+  // non-allowlisted payee limbs (membership proof no longer folds to the root).
+  const rogue = { ...valid, rLo: "1", rHi: "2" };
+  await assert.rejects(
+    () => calc.calculateWTNSBin(rogue, true),
+    /Assert Failed|Error/,
+    "circuit must reject a non-allowlisted recipient",
+  );
+});

package/cortex-v3/zk/proving-assets.mjs

@@ -0,0 +1,203 @@
+// Proving-asset resolver: locates the Groth16 wasm + zkey for a circuit by
+//   1. source checkout (cortex-v3/circuits/build/…), then
+//   2. the local download cache (~/.enigma/proving-assets/<circuit>/<file>),
+//      verified against the committed sha256 manifest, then
+//   3. a checksum-pinned download from the manifest's releaseBase.
+// Any mismatch, absence, or network failure FAILS CLOSED with a named
+// remediation — callers never prove against unverified bytes.
+//
+// Manifest: cortex-v3/proving-assets.json (committed). The zkeys are
+// gitignored (size); the manifest is the integrity anchor.
+import { createHash } from 'node:crypto';
+import { createReadStream, existsSync, mkdirSync, readFileSync, renameSync } from 'node:fs';
+import { writeFile, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SOURCE_BUILD = join(HERE, '..', 'circuits', 'build');
+const MANIFEST_PATH = join(HERE, '..', 'proving-assets.json');
+
+export class ProvingAssetError extends Error {
+  constructor(message, { code = 'PROVING_ASSET', remediation = '' } = {}) {
+    super(remediation ? `${message} — ${remediation}` : message);
+    this.name = 'ProvingAssetError';
+    this.code = code;
+  }
+}
+
+export function loadProvingAssetManifest(manifestPath = MANIFEST_PATH) {
+  if (!existsSync(manifestPath)) {
+    throw new ProvingAssetError(`proving-assets manifest missing: ${manifestPath}`, {
+      code: 'MANIFEST_MISSING',
+      remediation: 'run from a complete source checkout or reinstall the package',
+    });
+  }
+  return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+
+const sha256File = (path) => new Promise((resolve, reject) => {
+  const h = createHash('sha256');
+  createReadStream(path)
+    .on('data', (d) => h.update(d))
+    .on('end', () => resolve(h.digest('hex')))
+    .on('error', reject);
+});
+
+const cacheDir = (circuit) =>
+  join(homedir(), '.enigma', 'proving-assets', circuit);
+
+/** Resolve one asset kind ('wasm' | 'zkey') for a circuit; returns an absolute path. */
+export async function resolveProvingAsset(circuitName, kind, opts = {}) {
+  const manifest = opts.manifest ?? loadProvingAssetManifest();
+  const entry = manifest.circuits?.[circuitName]?.[kind];
+  if (!entry) {
+    throw new ProvingAssetError(`manifest has no ${kind} entry for circuit ${circuitName}`, {
+      code: 'MANIFEST_ENTRY_MISSING',
+    });
+  }
+
+  const candidates = [];
+  // 1. source checkout
+  const sourcePath = kind === 'wasm'
+    ? join(SOURCE_BUILD, `${circuitName}_js`, `${circuitName}.wasm`)
+    : join(SOURCE_BUILD, `${circuitName}.zkey`);
+  candidates.push(sourcePath);
+  // 2. download cache
+  const cachedPath = join(opts.cacheRoot ?? cacheDir(circuitName), entry.file);
+  candidates.push(cachedPath);
+
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    const actual = await sha256File(candidate);
+    if (actual === entry.sha256) return candidate;
+    if (candidate === cachedPath) {
+      // Cached but corrupt/stale — purge so a re-download can heal it.
+      await rm(cachedPath, { force: true });
+      continue;
+    }
+    throw new ProvingAssetError(
+      `${candidate} sha256 ${actual} != manifest ${entry.sha256}`, {
+        code: 'CHECKSUM_MISMATCH',
+        remediation: 'the file is corrupt or from a different ceremony; delete it or run the matching setup script',
+      });
+  }
+
+  // 3. checksum-pinned download
+  if (opts.allowDownload === false) {
+    throw new ProvingAssetError(
+      `no verified local ${kind} for ${circuitName} (download disabled for this call)`, {
+        code: 'ASSET_UNAVAILABLE',
+        remediation: 'proving assets resolve on first use, or run the matching setup script',
+      });
+  }
+  if (!manifest.releaseBase) {
+    throw new ProvingAssetError(
+      `no local ${kind} for ${circuitName} and no releaseBase configured`, {
+        code: 'ASSET_UNAVAILABLE',
+        remediation: `run cortex-v3/zk/setup*.mjs in a source checkout to generate proving keys`,
+      });
+  }
+  const url = `${manifest.releaseBase}/${entry.file}`;
+  mkdirSync(dirname(cachedPath), { recursive: true });
+  const tmp = `${cachedPath}.download`;
+  try {
+    const res = await fetch(url, { redirect: 'follow' });
+    if (!res.ok || !res.body) {
+      throw new ProvingAssetError(`download failed: HTTP ${res.status} for ${url}`, {
+        code: 'DOWNLOAD_FAILED',
+        remediation: 'check connectivity, or run the setup script in a source checkout',
+      });
+    }
+    await writeFile(tmp, Buffer.from(await res.arrayBuffer()));
+    const actual = await sha256File(tmp);
+    if (actual !== entry.sha256) {
+      throw new ProvingAssetError(
+        `downloaded ${entry.file} sha256 ${actual} != manifest ${entry.sha256} — refusing to use`, {
+          code: 'DOWNLOAD_CHECKSUM_MISMATCH',
+          remediation: 'release asset does not match the committed manifest; do not prove with it',
+        });
+    }
+    renameSync(tmp, cachedPath);
+    return cachedPath;
+  } finally {
+    await rm(tmp, { force: true }).catch(() => {});
+  }
+}
+
+/** Resolve both assets for a circuit: { wasm, zkey } absolute paths. */
+export async function resolveProvingAssets(circuitName, opts = {}) {
+  const manifest = opts.manifest ?? loadProvingAssetManifest();
+  const [wasm, zkey] = await Promise.all([
+    resolveProvingAsset(circuitName, 'wasm', { ...opts, manifest }),
+    resolveProvingAsset(circuitName, 'zkey', { ...opts, manifest }),
+  ]);
+  return { wasm, zkey };
+}
+
+/** Source-checkout path for the exported on-chain VK bytes JSON. */
+const vkSourcePath = (file) => join(SOURCE_BUILD, file);
+
+/**
+ * Resolve the on-chain verifying-key bytes JSON for a circuit: source checkout
+ * (packaged installs ship it too) → verified cache → checksum-pinned download.
+ * Returns { path, vk } with vk parsed: {alphaG1,betaG2,gammaG2,deltaG2,ic[]}.
+ */
+export async function resolveVerifyingKey(circuitName, opts = {}) {
+  const manifest = opts.manifest ?? loadProvingAssetManifest();
+  const entry = manifest.circuits?.[circuitName]?.vkBytes;
+  if (!entry) {
+    throw new ProvingAssetError(`manifest has no vkBytes entry for circuit ${circuitName}`, {
+      code: 'MANIFEST_ENTRY_MISSING',
+    });
+  }
+  const cachedPath = join(opts.cacheRoot ?? cacheDir(circuitName), entry.file);
+  const candidates = [vkSourcePath(entry.file), cachedPath];
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    const actual = await sha256File(candidate);
+    if (actual === entry.sha256) {
+      const vk = JSON.parse(readFileSync(candidate, 'utf8'));
+      return { path: candidate, vk };
+    }
+    if (candidate === cachedPath) {
+      await rm(cachedPath, { force: true });
+      continue;
+    }
+    throw new ProvingAssetError(
+      `${candidate} sha256 ${actual} != manifest ${entry.sha256}`, {
+        code: 'CHECKSUM_MISMATCH',
+        remediation: 'VK export does not match the committed manifest; rerun the matching setup script',
+      });
+  }
+  if (!manifest.releaseBase) {
+    throw new ProvingAssetError(`no local VK for ${circuitName} and no releaseBase configured`, {
+      code: 'ASSET_UNAVAILABLE',
+      remediation: 'run the matching cortex-v3/zk/setup*.mjs in a source checkout',
+    });
+  }
+  const url = `${manifest.releaseBase}/${entry.file}`;
+  mkdirSync(dirname(cachedPath), { recursive: true });
+  const tmp = `${cachedPath}.download`;
+  try {
+    const res = await fetch(url, { redirect: 'follow' });
+    if (!res.ok || !res.body) {
+      throw new ProvingAssetError(`download failed: HTTP ${res.status} for ${url}`, {
+        code: 'DOWNLOAD_FAILED',
+      });
+    }
+    await writeFile(tmp, Buffer.from(await res.arrayBuffer()));
+    const actual = await sha256File(tmp);
+    if (actual !== entry.sha256) {
+      throw new ProvingAssetError(
+        `downloaded ${entry.file} sha256 ${actual} != manifest ${entry.sha256} — refusing to use`, {
+          code: 'DOWNLOAD_CHECKSUM_MISMATCH',
+        });
+    }
+    renameSync(tmp, cachedPath);
+    return { path: cachedPath, vk: JSON.parse(readFileSync(cachedPath, 'utf8')) };
+  } finally {
+    await rm(tmp, { force: true }).catch(() => {});
+  }
+}