enigma-memory 0.1.18 → 0.1.22

package/cortex-v3/zk/setup-sale.mjs

@@ -0,0 +1,666 @@
+/**
+ * setup-sale.mjs — idempotent Groth16 ceremony driver for the Enigma
+ * ZKCP "Sealed Sale" circuit (circuits/sealed_sale_release.circom,
+ * SealedSaleRelease: note membership + Poseidon-CTR encryption consistency +
+ * key commitment + recipient-bound BabyJubJub envelope + sale-terms binding).
+ *
+ * Binding spec (private-sale path — do not drift): public inputs in exact order
+ *   [noteRoot, payloadCommitPos, cipherCommit, keyCommit, saleTermsHash, envelopeCommit]
+ *   → IC length 7.
+ * cipherCommit was promoted to a PUBLIC input (fund-loss fix): the proof now
+ * binds the ciphertext fold on-chain, so the buyer asserts
+ * fold(delivered ciphertext) == cipherCommit BEFORE paying.
+ * saleTermsHash = Poseidon9(DOMAIN_SALE, sellerLo, sellerHi, buyerPubX,
+ * buyerPubY, mintLo, mintHi, price, expirySlot) — the buyer pubkey is bound
+ * into the terms (fund-loss fix: a receipt can only claim that buyer's escrow).
+ * The on-chain VK PDA (seeds [b"verifying_key", 3u64.to_be_bytes()]) holds
+ * exactly 7 IC slots — the exported sale_vk_bytes.json fills all 7 with real
+ * points (no zero-padding).
+ *
+ * Cross-agent constant: DOMAIN_SALE = ASCII "enigma_sale"
+ * (0x656e69676d615f73616c65) as decimal = 122622912455040968075340901
+ * (87-bit; the circuit binds this exact value in saleTermsHash).
+ *
+ * Pipeline:
+ *   1. Poll (default up to 30 min) for circuits/build/sealed_sale_release.r1cs
+ *      (produced concurrently by SaleCircuit).
+ *   2. Read the constraint count from the r1cs binary header (authoritative).
+ *   3. REUSE the existing ptau/powersOfTau28_hez_final_18.ptau — NO download.
+ *      ~25-30k constraints expected; 2^18 covers it with margin and is
+ *      r1cs-independent.
+ *   4. groth16 setup → zkey contribute ("enigma-sale-dev-1", random entropy)
+ *      → zkey beacon (random 32B, 10 iterations) → export verificationkey →
+ *      circuits/build/sale_verification_key.json.
+ *   5. vkFromSnarkjs (asserts IC == 7) → circuits/build/sale_vk_bytes.json
+ *      (raw-be-hex-v1; all 7 on-chain IC slots are real points).
+ *   6. Proof-of-life: poll for zk/sale-witness.mjs (SaleWitness runs
+ *      concurrently), build the module's self-contained demo fixture
+ *      (buildSaleDemoFixture), groth16 fullProve against the final zkey +
+ *      compiled wasm, groth16 verify against the exported verification key.
+ *      Prints timings.
+ *
+ * sale_verification_key.json + sale_vk_bytes.json are COMMITTABLE;
+ * *.zkey, zk-setup-sale-state.json, ptau/ are gitignored.
+ *
+ * CLAIM BOUNDARY: single-party local setup = development only; production
+ * requires a multi-party ceremony.
+ *
+ * Usage:
+ *   node zk/setup-sale.mjs [--r1cs <path>] [--build-dir <dir>]
+ *       [--ptau-dir <dir>] [--poll-minutes <n>] [--witness-poll-minutes <n>]
+ *       [--witness <path>] [--force] [--skip-proof-of-life]
+ *
+ * Exit codes: 0 success · 3 blocked (r1cs or witness prerequisite missing) ·
+ *             4 ptau missing · 1 other failure.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { vkFromSnarkjs } from "./zk-codec.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CORTEX_V3 = path.resolve(HERE, "..");
+
+// --- Sealed-sale circuit contract (binding spec — do not drift) --------------
+const CIRCUIT_NAME = "sealed_sale_release";
+const CIRCUIT_VERSION = 3; // settle_sale VK PDA seed (3u64.to_be_bytes())
+// [noteRoot, payloadCommitPos, cipherCommit, keyCommit, saleTermsHash, envelopeCommit]
+const NUM_PUBLIC_INPUTS = 6;
+const EXPECTED_IC = 1 + NUM_PUBLIC_INPUTS; // 7
+const ONCHAIN_VK_IC_SLOTS = 7; // VK account holds 7 slots — all real, no padding
+const G1_BYTES = 64;
+const POWER = 18; // reuse ptau/powersOfTau28_hez_final_18.ptau (2^18 >> ~2^15 need)
+const PTAU_MIN_BYTES = 100 * 1024 * 1024; // size sanity floor (hez_final_18 ≈ 145MB)
+// DOMAIN_SALE documented for cross-agent consistency (bound inside the circuit
+// and the witness module — not needed by this driver itself).
+export const DOMAIN_SALE = 122622912455040968075340901n; // ASCII "enigma_sale"
+
+const DEFAULTS = {
+  r1cs: path.join(CORTEX_V3, "circuits", "build", `${CIRCUIT_NAME}.r1cs`),
+  buildDir: path.join(CORTEX_V3, "circuits", "build"),
+  ptauDir: path.join(CORTEX_V3, "ptau"),
+  witness: path.join(HERE, "sale-witness.mjs"),
+  pollMinutes: 30,
+  witnessPollMinutes: 20,
+  force: false,
+  skipProofOfLife: false,
+};
+
+const log = (msg) =>
+  console.log(`[setup-sale ${new Date().toISOString()}] ${msg}`);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+class BlockingError extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = { ...DEFAULTS };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      if (i + 1 >= argv.length) throw new Error(`missing value for ${a}`);
+      return argv[++i];
+    };
+    switch (a) {
+      case "--r1cs":
+        opts.r1cs = path.resolve(next());
+        break;
+      case "--build-dir":
+        opts.buildDir = path.resolve(next());
+        break;
+      case "--ptau-dir":
+        opts.ptauDir = path.resolve(next());
+        break;
+      case "--witness":
+        opts.witness = path.resolve(next());
+        break;
+      case "--poll-minutes":
+        opts.pollMinutes = Number(next());
+        break;
+      case "--witness-poll-minutes":
+        opts.witnessPollMinutes = Number(next());
+        break;
+      case "--force":
+        opts.force = true;
+        break;
+      case "--skip-proof-of-life":
+        opts.skipProofOfLife = true;
+        break;
+      default:
+        throw new Error(`unknown argument: ${a}`);
+    }
+  }
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// snarkjs CLI runner (no npx/.cmd shims — run the CLI entrypoint with node)
+// ---------------------------------------------------------------------------
+
+function snarkjsCliPath() {
+  const p = path.join(CORTEX_V3, "node_modules", "snarkjs", "build", "cli.cjs");
+  if (!existsSync(p)) {
+    throw new Error(
+      `snarkjs CLI not found at ${p} — run "npm install -D snarkjs" in cortex-v3`,
+    );
+  }
+  return p;
+}
+
+function snarkjs(args, { quiet = false } = {}) {
+  const fullArgs = [snarkjsCliPath(), ...args];
+  log(`$ node ${path.basename(snarkjsCliPath())} ${args.join(" ")}`);
+  const res = spawnSync(process.execPath, fullArgs, {
+    cwd: CORTEX_V3,
+    stdio: quiet ? "pipe" : "inherit",
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (res.error) throw res.error;
+  if (res.status !== 0) {
+    throw new Error(
+      `snarkjs ${args[0]} exited with code ${res.status}\n${res.stderr ?? ""}`,
+    );
+  }
+  return (res.stdout ?? "") + (res.stderr ?? "");
+}
+
+// ---------------------------------------------------------------------------
+// r1cs inspection — parse the binary header directly (authoritative)
+// ---------------------------------------------------------------------------
+
+function readR1csHeader(r1csPath) {
+  const fd = readFileSync(r1csPath);
+  if (fd.length < 12 || fd.toString("ascii", 0, 4) !== "r1cs") {
+    throw new Error(`${r1csPath} is not an r1cs file (bad magic)`);
+  }
+  const nSections = fd.readUInt32LE(8);
+  let offset = 12;
+  for (let s = 0; s < nSections; s++) {
+    const sectionType = fd.readUInt32LE(offset);
+    const sectionSize = Number(fd.readBigUInt64LE(offset + 4));
+    if (sectionType === 1) {
+      const base = offset + 12;
+      const fieldSize = fd.readUInt32LE(base);
+      let p = base + 4 + fieldSize;
+      const nWires = fd.readUInt32LE(p);
+      const nPubOut = fd.readUInt32LE(p + 4);
+      const nPubIn = fd.readUInt32LE(p + 8);
+      const nPrvIn = fd.readUInt32LE(p + 12);
+      const nLabels = Number(fd.readBigUInt64LE(p + 16));
+      const nConstraints = fd.readUInt32LE(p + 24);
+      return { nWires, nPubOut, nPubIn, nPrvIn, nLabels, nConstraints };
+    }
+    offset += 12 + sectionSize;
+  }
+  throw new Error(`${r1csPath}: header section (type 1) not found`);
+}
+
+// ---------------------------------------------------------------------------
+// ptau header — sanity-check that the reused file's power covers the circuit
+// ---------------------------------------------------------------------------
+
+function readPtauPower(ptauPath) {
+  const fd = readFileSync(ptauPath, { flag: "r" });
+  if (fd.length < 12 || fd.toString("ascii", 0, 4) !== "ptau") {
+    throw new Error(`${ptauPath} is not a ptau file (bad magic)`);
+  }
+  const nSections = fd.readUInt32LE(8);
+  let offset = 12;
+  for (let s = 0; s < nSections; s++) {
+    const sectionType = fd.readUInt32LE(offset);
+    const sectionSize = Number(fd.readBigUInt64LE(offset + 4));
+    if (sectionType === 1) {
+      const base = offset + 12;
+      const fieldSize = fd.readUInt32LE(base);
+      const power = fd.readUInt32LE(base + 4 + fieldSize);
+      return power;
+    }
+    offset += 12 + sectionSize;
+  }
+  throw new Error(`${ptauPath}: header section (type 1) not found`);
+}
+
+// ---------------------------------------------------------------------------
+// Stage 1: wait for the r1cs
+// ---------------------------------------------------------------------------
+
+async function waitForFile(filePath, pollMinutes, what, owner) {
+  if (existsSync(filePath)) {
+    log(`${what} present: ${filePath}`);
+    return;
+  }
+  log(
+    `waiting up to ${pollMinutes} min for ${filePath} (${owner} runs concurrently)...`,
+  );
+  const deadline = Date.now() + pollMinutes * 60_000;
+  while (Date.now() < deadline) {
+    if (existsSync(filePath)) {
+      // Guard against a partially-written file: size must be stable.
+      const s1 = statSync(filePath).size;
+      await sleep(2000);
+      const s2 = statSync(filePath).size;
+      if (s1 === s2 && s2 > 0) {
+        log(`${what} appeared (${s2} bytes, stable)`);
+        return;
+      }
+    }
+    await sleep(15_000);
+  }
+  throw new BlockingError(
+    `BLOCKED: ${filePath} did not appear within ${pollMinutes} minutes.\n` +
+      `Prerequisite owner: ${owner}.\n` +
+      `Re-run "node zk/setup-sale.mjs" once it exists — all completed stages are reused.`,
+    3,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Stage 2: ptau — REUSE the existing 2^18 powers-of-tau (no download)
+// ---------------------------------------------------------------------------
+
+function acquirePtau(ptauDir, nConstraints) {
+  const dest = path.join(ptauDir, `powersOfTau28_hez_final_${POWER}.ptau`);
+  if (!existsSync(dest)) {
+    throw new BlockingError(
+      `BLOCKED: required powers-of-tau not found at ${dest}.\n` +
+        `This ceremony reuses the repo-local ptau (no download). Restore it via\n` +
+        `"node zk/setup.mjs" (which acquires the same file) or copy it into ptau/.`,
+      4,
+    );
+  }
+  const size = statSync(dest).size;
+  if (size < PTAU_MIN_BYTES) {
+    throw new BlockingError(
+      `BLOCKED: ${dest} fails size sanity (${size} < ${PTAU_MIN_BYTES}) — truncated?`,
+      4,
+    );
+  }
+  const power = readPtauPower(dest);
+  if (2 ** power <= nConstraints) {
+    throw new Error(
+      `constraint count ${nConstraints} does not fit in the 2^${power} powers-of-tau at ${dest}`,
+    );
+  }
+  log(
+    `reusing existing ptau: ${dest} (${(size / 1024 / 1024).toFixed(1)}MB, ` +
+      `2^${power}; ${nConstraints} constraints fit)`,
+  );
+  return { path: dest, provenance: "reused repo-local file (no download)", size, power };
+}
+
+// ---------------------------------------------------------------------------
+// Stages 3-5: circuit-specific ceremony
+// ---------------------------------------------------------------------------
+
+function stagePaths(buildDir, r1csPath) {
+  const stem = path.basename(r1csPath).replace(/\.r1cs$/, "");
+  return {
+    zkey0: path.join(buildDir, `${stem}_0000.zkey`),
+    zkey1: path.join(buildDir, `${stem}_0001.zkey`),
+    // Final proving key name is CONTRACT: proof-of-life + Main's e2e load <stem>.zkey.
+    zkeyFinal: path.join(buildDir, `${stem}.zkey`),
+    vkJson: path.join(buildDir, "sale_verification_key.json"),
+    vkBytes: path.join(buildDir, "sale_vk_bytes.json"),
+  };
+}
+
+function runCeremony(r1csPath, ptauPath, paths, force) {
+  mkdirSync(path.dirname(paths.zkey0), { recursive: true });
+  if (force) {
+    for (const f of Object.values(paths)) rmSync(f, { force: true });
+  }
+  if (!existsSync(paths.zkey0)) {
+    snarkjs(["groth16", "setup", r1csPath, ptauPath, paths.zkey0]);
+  } else {
+    log(`reusing ${paths.zkey0}`);
+  }
+  if (!existsSync(paths.zkey1)) {
+    snarkjs([
+      "zkey", "contribute", paths.zkey0, paths.zkey1,
+      "--name=enigma-sale-dev-1",
+      `-e=${randomBytes(32).toString("hex")}`,
+    ]);
+  } else {
+    log(`reusing ${paths.zkey1}`);
+  }
+  if (!existsSync(paths.zkeyFinal)) {
+    const beacon = randomBytes(32).toString("hex");
+    snarkjs(["zkey", "beacon", paths.zkey1, paths.zkeyFinal, beacon, "10"]);
+    log(`zkey beacon applied (dev beacon ${beacon})`);
+  } else {
+    log(`reusing ${paths.zkeyFinal}`);
+  }
+  if (!existsSync(paths.vkJson)) {
+    snarkjs(["zkey", "export", "verificationkey", paths.zkeyFinal, paths.vkJson]);
+  } else {
+    log(`reusing ${paths.vkJson}`);
+  }
+}
+
+function exportVkBytes(paths, meta) {
+  const vkJson = JSON.parse(readFileSync(paths.vkJson, "utf8"));
+  // Throws unless IC == 7 (ic[0] + 6 public inputs).
+  const vk = vkFromSnarkjs(vkJson, { expectedIc: EXPECTED_IC, g2LimbOrder: "c1c0" });
+  const hex = (b) => b.toString("hex"); // plain hex strings (zk-codec convention)
+  // The on-chain VK PDA (circuit_version = 3) holds 7 IC slots; the sale
+  // circuit has exactly 7 — the pad loop below is a no-op kept for shape safety.
+  const icPadded = vk.ic.map(hex);
+  while (icPadded.length < ONCHAIN_VK_IC_SLOTS) {
+    icPadded.push(Buffer.alloc(G1_BYTES).toString("hex"));
+  }
+  if (icPadded.length !== ONCHAIN_VK_IC_SLOTS) {
+    throw new Error(`internal: ic padding overflow (${icPadded.length})`);
+  }
+  const out = {
+    format: "raw-be-hex-v1",
+    curve: "bn128",
+    g2LimbOrder: "c1c0", // alt_bn128 / EIP-196 (im,re)
+    proofNote: "pi_a is raw — the on-chain program negates A",
+    circuit: CIRCUIT_NAME,
+    circuitVersion: CIRCUIT_VERSION,
+    numPublicInputs: NUM_PUBLIC_INPUTS,
+    icCount: vk.ic.length, // 7 real IC points from the ceremony
+    icPaddedTo: ONCHAIN_VK_IC_SLOTS, // 7 — no zero-padding needed
+    alphaG1: hex(vk.alphaG1),
+    betaG2: hex(vk.betaG2),
+    gammaG2: hex(vk.gammaG2),
+    deltaG2: hex(vk.deltaG2),
+    ic: icPadded,
+    ceremony: "development single-party",
+    ceremonyDetail: meta,
+    source: path.basename(paths.vkJson),
+    createdAt: new Date().toISOString(),
+  };
+  const tmp = `${paths.vkBytes}.tmp`;
+  writeFileSync(tmp, JSON.stringify(out, null, 2) + "\n");
+  renameSync(tmp, paths.vkBytes);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// r1cs fingerprint — ceremony artifacts are only valid for the exact r1cs
+// they were derived from. If the r1cs changes (circuit recompile), every
+// circuit-specific stage MUST be redone; the ptau is r1cs-independent.
+// ---------------------------------------------------------------------------
+
+function sha256File(p) {
+  return createHash("sha256").update(readFileSync(p)).digest("hex");
+}
+
+function statePath(buildDir) {
+  // Distinct from setup.mjs's zk-setup-state.json (action-transition) and
+  // setup-intent.mjs's zk-setup-intent-state.json.
+  return path.join(buildDir, "zk-setup-sale-state.json");
+}
+
+function readState(buildDir) {
+  const p = statePath(buildDir);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeState(buildDir, state) {
+  const tmp = `${statePath(buildDir)}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n");
+  renameSync(tmp, statePath(buildDir));
+}
+
+/** Delete circuit-specific artifacts; returns list of removed paths. */
+function purgeStageArtifacts(paths) {
+  const removed = [];
+  for (const key of ["zkey0", "zkey1", "zkeyFinal", "vkJson", "vkBytes"]) {
+    if (existsSync(paths[key])) {
+      rmSync(paths[key], { force: true });
+      removed.push(paths[key]);
+    }
+  }
+  return removed;
+}
+
+// ---------------------------------------------------------------------------
+// Stage 6: proof-of-life — fullProve + verify with SaleWitness's demo fixture
+// ---------------------------------------------------------------------------
+
+// The demo fixture is owned by zk/sale-witness.mjs (SaleWitness), which knows
+// the note tree, Poseidon-CTR plaintext/ciphertext chunks, the BabyJubJub
+// buyer keypair and the ephemeral envelope — building all of that here would
+// duplicate the module under test. Contract:
+//   buildSaleDemoFixture() → { input, expectedPublic }
+//     input          — complete circom witness input (private + public signals)
+//     expectedPublic — the 5 public values in circuit order
+//   SALE_PUBLIC_SIGNALS — the 5 public signal names in the same order
+// fullProve/verify below is self-checking against both.
+
+async function proofOfLife(opts, paths) {
+  await waitForFile(
+    opts.witness,
+    opts.witnessPollMinutes,
+    "sale witness module",
+    "SaleWitness (zk/sale-witness.mjs)",
+  );
+  const wasmPath = path.join(
+    opts.buildDir,
+    `${CIRCUIT_NAME}_js`,
+    `${CIRCUIT_NAME}.wasm`,
+  );
+  if (!existsSync(wasmPath)) {
+    throw new BlockingError(
+      `BLOCKED: ${wasmPath} missing (SaleCircuit compile output).`,
+      3,
+    );
+  }
+
+  // snarkjs ESM entry has named exports only (no default).
+  const { groth16 } = await import("snarkjs");
+  const witnessMod = await import(pathToFileURL(opts.witness).href);
+  const { buildSaleDemoFixture, SALE_PUBLIC_SIGNALS } = witnessMod;
+  if (typeof buildSaleDemoFixture !== "function") {
+    throw new Error(`${opts.witness} does not export buildSaleDemoFixture`);
+  }
+  const publicSignalNames = SALE_PUBLIC_SIGNALS ?? [
+    "noteRoot",
+    "payloadCommitPos",
+    "cipherCommit",
+    "keyCommit",
+    "saleTermsHash",
+    "envelopeCommit",
+  ];
+
+  const fixture = await buildSaleDemoFixture();
+  const { input, expectedPublic } = fixture ?? {};
+  if (!input || typeof input !== "object") {
+    throw new Error("buildSaleDemoFixture() did not return { input, ... }");
+  }
+
+  const t0 = Date.now();
+  const { proof, publicSignals } = await groth16.fullProve(
+    input,
+    wasmPath,
+    paths.zkeyFinal,
+  );
+  const proveMs = Date.now() - t0;
+
+  // The builder's declared public signals MUST match what the prover emits, in
+  // the binding order [noteRoot, payloadCommitPos, cipherCommit, keyCommit,
+  // saleTermsHash, envelopeCommit].
+  if (publicSignals.length !== NUM_PUBLIC_INPUTS) {
+    throw new Error(
+      `fullProve emitted ${publicSignals.length} public signals, expected ${NUM_PUBLIC_INPUTS}`,
+    );
+  }
+  for (let i = 0; i < NUM_PUBLIC_INPUTS; i++) {
+    const declared = String(input[publicSignalNames[i]]);
+    if (declared !== String(publicSignals[i])) {
+      throw new Error(
+        `public signal ${publicSignalNames[i]} mismatch: witness ${declared} != prover ${publicSignals[i]}`,
+      );
+    }
+    if (expectedPublic && String(expectedPublic[i]) !== String(publicSignals[i])) {
+      throw new Error(
+        `public signal ${publicSignalNames[i]} mismatch: fixture expectedPublic ${expectedPublic[i]} != prover ${publicSignals[i]}`,
+      );
+    }
+  }
+
+  const t1 = Date.now();
+  const vkJsonObj = JSON.parse(readFileSync(paths.vkJson, "utf8"));
+  const ok = await groth16.verify(vkJsonObj, publicSignals, proof);
+  const verifyMs = Date.now() - t1;
+  if (!ok) {
+    throw new Error("PROOF-OF-LIFE FAILED: groth16.verify returned false");
+  }
+  log(
+    `proof-of-life OK — fullProve ${proveMs}ms, verify ${verifyMs}ms ` +
+      `(public signals [${publicSignalNames.join(", ")}] match witness)`,
+  );
+  return { proveMs, verifyMs, publicSignals };
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const paths = stagePaths(opts.buildDir, opts.r1cs);
+
+  await waitForFile(
+    opts.r1cs,
+    opts.pollMinutes,
+    "r1cs",
+    "SaleCircuit (circuits/sealed_sale_release.circom → circom compile)",
+  );
+
+  const r1csSha256 = sha256File(opts.r1cs);
+  log(`r1cs sha256: ${r1csSha256}`);
+  const priorState = readState(opts.buildDir);
+
+  if (opts.force || priorState?.r1csSha256 !== r1csSha256) {
+    const reason = opts.force
+      ? "--force"
+      : priorState
+        ? `r1cs changed (${priorState.r1csSha256} → ${r1csSha256})`
+        : "no prior setup state";
+    const removed = purgeStageArtifacts(paths);
+    if (removed.length > 0) {
+      log(
+        `${reason}: purged ${removed.length} stale circuit-specific artifact(s); ` +
+          `ptau reused (r1cs-independent)`,
+      );
+    }
+  }
+
+  const header = readR1csHeader(opts.r1cs);
+  log(
+    `r1cs: ${header.nConstraints} constraints, ${header.nWires} wires, ` +
+      `${header.nPubIn} pub-in, ${header.nPubOut} pub-out`,
+  );
+  const impliedIc = 1 + header.nPubIn + header.nPubOut;
+  if (impliedIc !== EXPECTED_IC) {
+    log(
+      `WARNING: r1cs implies IC length ${impliedIc} (1 + ${header.nPubIn} + ${header.nPubOut}) ` +
+        `but the sealed-sale contract expects ${EXPECTED_IC}; vk export will fail if the vk disagrees`,
+    );
+  }
+
+  const ptau = acquirePtau(opts.ptauDir, header.nConstraints);
+  log(`ptau provenance: ${ptau.provenance} (${(ptau.size / 1024 / 1024).toFixed(1)}MB)`);
+
+  const freshArtifacts =
+    existsSync(paths.vkJson) &&
+    existsSync(paths.vkBytes) &&
+    existsSync(paths.zkeyFinal);
+  if (!freshArtifacts) {
+    runCeremony(opts.r1cs, ptau.path, paths, opts.force);
+    exportVkBytes(paths, {
+      ptau: ptau.provenance,
+      ptauBytes: ptau.size,
+      ptauPower: ptau.power,
+      r1csSha256,
+      constraintCount: header.nConstraints,
+      contribution:
+        "enigma-sale-dev-1 (random entropy) + random beacon (10 iterations)",
+    });
+  } else {
+    log(
+      `ceremony artifacts already complete for r1cs ${r1csSha256} — reusing ` +
+        `(zkey + sale_verification_key.json + sale_vk_bytes.json)`,
+    );
+  }
+
+  // Persist the ceremony fingerprint NOW, so a proof-of-life failure does not
+  // force a ceremony redo on the next run (artifacts are already r1cs-bound).
+  writeState(opts.buildDir, {
+    r1csSha256,
+    constraintCount: header.nConstraints,
+    powerOfTau: ptau.power,
+    ptau: ptau.provenance,
+    zkeyFinal: path.basename(paths.zkeyFinal),
+    icCount: EXPECTED_IC,
+    icPaddedTo: ONCHAIN_VK_IC_SLOTS,
+    completedAt: new Date().toISOString(),
+  });
+
+  if (opts.skipProofOfLife) {
+    log("--skip-proof-of-life: ceremony complete, skipping fullProve/verify.");
+  } else {
+    const pol = await proofOfLife(opts, paths);
+    writeState(opts.buildDir, {
+      r1csSha256,
+      constraintCount: header.nConstraints,
+      powerOfTau: ptau.power,
+      ptau: ptau.provenance,
+      zkeyFinal: path.basename(paths.zkeyFinal),
+      icCount: EXPECTED_IC,
+      icPaddedTo: ONCHAIN_VK_IC_SLOTS,
+      proofOfLife: {
+        ok: true,
+        proveMs: pol.proveMs,
+        verifyMs: pol.verifyMs,
+        at: new Date().toISOString(),
+      },
+      completedAt: new Date().toISOString(),
+    });
+  }
+  log("setup-sale complete.");
+}
+
+// snarkjs's in-process JS API (proof-of-life) keeps worker threads alive;
+// exit explicitly once the driver has finished.
+main()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    if (err instanceof BlockingError) {
+      console.error(`\n${err.message}`);
+      process.exit(err.exitCode);
+    }
+    console.error(
+      `\nsetup-sale.mjs FAILED: ${err.stack ?? err.message ?? err}`,
+    );
+    process.exit(1);
+  });