enigma-memory 0.1.18 → 0.1.22

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

@@ -0,0 +1,784 @@
+// sale-witness.test.mjs — tests for zk/sale-witness.mjs, the client-side
+// witness builder for circuits/sealed_sale_release.circom (the ZKCP
+// "Sealed Sale" release proof, private-sale path).
+//
+// Legs:
+//   1. Byte/chunk round-trip — LE 31-byte limbs, every chunk < 2^248 < r;
+//      arbitrary bytes (incl. trailing 0x00, 0xFF-filled, 0/1/31/32/992
+//      bytes) round-trip exactly; >992 bytes rejected.
+//   2. Poseidon-CTR encrypt/decrypt round-trip + tamper diffusion.
+//   3. Poseidon-CTR KAT — pinned keystream/ciphertext/fold values, plus a
+//      fully independent recomputation (raw circomlibjs Poseidon + explicit
+//      mod-r field add; no module code).
+//   4. BabyJubJub buyer keys — generated keys validate; encode/decode
+//      round-trip; small-order (identity, order-2, order-8) and off-curve
+//      and non-canonical points REJECTED with the circuit's exact rule
+//      (on-curve ∧ (8·B).x ≠ 0).
+//   5. THIRD-PARTY CANNOT DECRYPT — buyer B's secret on buyer A's envelope
+//      yields the wrong DEK; digest assertion fails.
+//   6. saleTermsHash — KAT + independent recomputation; limb/range guards.
+//   7. buildSaleWitness — full witness shape, exact signal names (per the
+//      SaleCircuit contract), decimal strings, public-signal order; envelope
+//      artifacts self-consistent; client-side rejections throw.
+//   8. Signal-name reconciliation vs circuits/sealed_sale_release.circom
+//      (when the file exists): every `signal input` name in the main
+//      template must match exactly, public order must match.
+//   9. WASM-gated (polls up to 20 min for SaleCircuit build artifacts;
+//      override with SALE_WITNESS_POLL_MS=0 to skip immediately):
+//      valid witness satisfies the compiled circuit; a junk-ciphertext
+//      witness is REJECTED by the witness calculator.
+//
+// Run: node --test cortex-v3/zk/sale-witness.test.mjs
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+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 { buildBabyjub, buildPoseidon } from "circomlibjs";
+import bs58 from "bs58";
+
+import { FIELD_R, NoteTree } from "./zk-tree.mjs";
+import {
+  CHUNK_BYTES,
+  CHUNK_COUNT,
+  DOMAIN_SALE,
+  NOTE_DEPTH,
+  PAYLOAD_CAPACITY,
+  SALE_PUBLIC_SIGNALS,
+  buildSaleDemoFixture,
+  buildSaleWitness,
+  bytesToChunks,
+  bytesToBigIntLE,
+  chunksFromBytes,
+  chunksToBytes,
+  computeKeyCommit,
+  computeSaleNote,
+  DOMAIN_PSALT,
+  computeSaleTermsHash,
+  decryptPayload,
+  deriveSharedSecret,
+  encodePoint,
+  decodePoint,
+  encryptPayload,
+  foldChunks,
+  foldChunksBlind,
+  generateBuyerKeyPair,
+  keystreamChunk,
+  openAndVerifySale,
+  openSaleEnvelope,
+  validateBuyerPublicKey,
+} from "./sale-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", "sealed_sale_release.circom");
+const R1CS = join(BUILD, "sealed_sale_release.r1cs");
+const WASM = join(BUILD, "sealed_sale_release_js", "sealed_sale_release.wasm");
+const WITNESS_CALC = join(BUILD, "sealed_sale_release_js", "witness_calculator.js");
+
+const require = createRequire(import.meta.url);
+
+// ---------------------------------------------------------------------------
+// Independent machinery (raw circomlibjs — shares no code with the module)
+// ---------------------------------------------------------------------------
+const poseidonC = await buildPoseidon();
+const F = poseidonC.F;
+const R = FIELD_R;
+const independentPoseidon = (xs) => F.toObject(poseidonC(xs.map((x) => F.e(BigInt(x)))));
+
+const babyJub = await buildBabyjub();
+const JF = babyJub.F;
+
+/** 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;
+}
+
+// ---------------------------------------------------------------------------
+// Fixed test fixture
+// ---------------------------------------------------------------------------
+const PLAINTEXT = new TextEncoder().encode(
+  "Enigma sealed-sale demo memory: the cortex remembers what the chain never sees.",
+); // 79 bytes
+const DEK_LO = 0x0de0b6b3a7640000f1f2f3f4f5f6f7f8n;
+const DEK_HI = 0x00112233445566778899aabbccddeeffn;
+const NONCE = 424242424242n;
+const ESK = 0x1f1e1d1c1b1a191817161514131211100f0e0d0c0b0a09080706050403n;
+const OWNER_KEY = 11111111111111111111111111111111111111111111111111n;
+const RHO = 22222222222222222222222222222222222222222222222222n;
+const SELLER = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"; // USDC mint addr as seller
+const MINT = "So11111111111111111111111111111111111111112"; // wSOL mint
+const PRICE = 2_000_000_000n;
+const EXPIRY_SLOT = 300_000_000n;
+
+// Pinned by the independent recomputation below (raw circomlibjs Poseidon,
+// explicit mod-r field add — computed once, then frozen here).
+const KAT = Object.freeze({
+  domainSale: 122622912455040968075340901n,
+  ks0: 3589178275523291951363275889201219803941083386281678158752858657278878496187n,
+  ks1: 14540676613757474377696583013418111239504349028389538056672046070098961572735n,
+  ks31: 19323069819120820054275317198827642037090427957986178685749720135057254853371n,
+  p0: 103315326233695364645767690488868881140320643153680381253010726472875863621n,
+  c0: 3692493601756987316009043579690088685081404029435358540005869383751754359808n,
+  payloadCommitPos: 8764819824630054939208652781887457096300910414137815727281144740307113585380n, // DEK-blinded fold
+  keyCommit: 12602673196205851515633971187412354398057859532683823173342270131645853115010n,
+});
+
+/** Deterministic buyer key pair (fixed secret, < subOrder). */
+function demoBuyer() {
+  const secret = 0x0a0b0c0d0e0f101112131415161718191a1b1c1d1e1f2021222324252n %
+    BigInt(babyJub.subOrder.toString());
+  const P = babyJub.mulPointEscalar(babyJub.Base8, secret);
+  return { secret, publicKey: { x: JF.toObject(P[0]), y: JF.toObject(P[1]) } };
+}
+
+/** Build the standard valid fixture: note tree + witness args. */
+function makeFixture() {
+  const buyer = demoBuyer();
+  const plaintextChunks = bytesToChunks(PLAINTEXT);
+  const payloadCommitPos = foldChunksBlind(plaintextChunks, DEK_LO, DEK_HI);
+  const noteTree = new NoteTree();
+  noteTree.insert(555n); // filler at index 0
+  noteTree.insert(computeSaleNote(OWNER_KEY, RHO, payloadCommitPos)); // index 1
+  return {
+    buyer,
+    noteTree,
+    args: {
+      noteTree,
+      noteIndex: 1,
+      ownerKey: OWNER_KEY,
+      rho: RHO,
+      plaintextBytes: PLAINTEXT,
+      dekLo: DEK_LO,
+      dekHi: DEK_HI,
+      nonce: NONCE,
+      buyerPub: buyer.publicKey,
+      sellerPubkey: SELLER,
+      mint: MINT,
+      priceLamports: PRICE,
+      expirySlot: EXPIRY_SLOT,
+      esk: ESK,
+    },
+  };
+}
+
+const EXPECTED_SIGNALS = Object.freeze([
+  ...SALE_PUBLIC_SIGNALS,
+  "ownerKey",
+  "rho",
+  "notePathElements",
+  "notePathIndices",
+  "plaintext",
+  "ciphertext",
+  "nonce",
+  "dekLo",
+  "dekHi",
+  "buyerPubX",
+  "buyerPubY",
+  "esk",
+  "sellerLo",
+  "sellerHi",
+  "mintLo",
+  "mintHi",
+  "price",
+  "expirySlot",
+  "payloadLen",
+]);
+
+// ---------------------------------------------------------------------------
+// 1. Byte/chunk round-trip
+// ---------------------------------------------------------------------------
+test("bytesToChunks/chunksToBytes round-trip arbitrary bytes", () => {
+  const cases = [
+    new Uint8Array(0),
+    new Uint8Array([0x42]),
+    new Uint8Array([0, 0, 0]), // all zeros
+    new Uint8Array(randomBytes(1)),
+    new Uint8Array(randomBytes(CHUNK_BYTES)), // exactly one chunk
+    new Uint8Array(randomBytes(CHUNK_BYTES + 1)), // crosses a chunk boundary
+    new Uint8Array(randomBytes(PAYLOAD_CAPACITY)), // full capacity
+    (() => {
+      const b = new Uint8Array(randomBytes(100));
+      b.fill(0, 90); // trailing zero bytes MUST round-trip
+      return b;
+    })(),
+    new Uint8Array(PAYLOAD_CAPACITY).fill(0xff), // max-entropy limbs
+  ];
+  for (const bytes of cases) {
+    const chunks = bytesToChunks(bytes);
+    assert.equal(chunks.length, CHUNK_COUNT);
+    for (const c of chunks) {
+      assert.ok(c >= 0n && c < 1n << 248n, `chunk ${c} outside [0, 2^248)`);
+      assert.ok(c < R, `chunk ${c} not canonical mod r`);
+    }
+    const back = chunksToBytes(chunks, bytes.length);
+    assert.deepEqual(back, bytes, `round-trip failed for ${bytes.length} bytes`);
+    // aliases must agree
+    assert.deepEqual(chunksFromBytes(bytes), chunks);
+  }
+  // default length = full capacity
+  const full = chunksToBytes(bytesToChunks(new Uint8Array([7])));
+  assert.equal(full.length, PAYLOAD_CAPACITY);
+  assert.equal(full[0], 7);
+  assert.ok(full.subarray(1).every((b) => b === 0));
+  // over-capacity payload rejected
+  assert.throws(() => bytesToChunks(new Uint8Array(PAYLOAD_CAPACITY + 1)), /too large/);
+  // out-of-range chunk rejected on decode
+  const bad = new Array(CHUNK_COUNT).fill(0n);
+  bad[3] = 1n << 248n;
+  assert.throws(() => chunksToBytes(bad), /outside \[0, 2\^248\)/);
+});
+
+// ---------------------------------------------------------------------------
+// 2. Poseidon-CTR round-trip
+// ---------------------------------------------------------------------------
+test("encryptPayload/decryptPayload round-trip; wrong key/nonce garbles", () => {
+  const chunks = bytesToChunks(new Uint8Array(randomBytes(500)));
+  const dekLo = bytesToBigIntLE(randomBytes(16));
+  const dekHi = bytesToBigIntLE(randomBytes(16));
+  const nonce = bytesToBigIntLE(randomBytes(16));
+
+  const ct = encryptPayload(chunks, dekLo, dekHi, nonce);
+  assert.equal(ct.length, CHUNK_COUNT);
+  for (const c of ct) assert.ok(c >= 0n && c < R, "ciphertext chunk not canonical");
+  assert.notDeepEqual(ct, chunks, "ciphertext must differ from plaintext");
+  assert.deepEqual(decryptPayload(ct, dekLo, dekHi, nonce), chunks);
+
+  // field-add cipher: c_i - p_i === ks_i (mod r) — the circuit constraint
+  const ks0 = keystreamChunk(dekLo, dekHi, nonce, 0);
+  assert.equal((ct[0] - chunks[0] + R) % R, ks0);
+
+  // wrong DEK → wrong plaintext → different fold
+  const wrong = decryptPayload(ct, dekLo ^ 1n, dekHi, nonce);
+  assert.notDeepEqual(wrong, chunks);
+  assert.notEqual(foldChunks(wrong), foldChunks(chunks));
+  // wrong nonce → same
+  const wrongN = decryptPayload(ct, dekLo, dekHi, nonce + 1n);
+  assert.notDeepEqual(wrongN, chunks);
+});
+
+// ---------------------------------------------------------------------------
+// 3. Poseidon-CTR KAT (pinned + independent recomputation)
+// ---------------------------------------------------------------------------
+test("Poseidon-CTR matches pinned KAT and independent recomputation", () => {
+  assert.equal(DOMAIN_SALE, KAT.domainSale, "DOMAIN_SALE drifted");
+
+  // pinned keystream values
+  assert.equal(keystreamChunk(DEK_LO, DEK_HI, NONCE, 0), KAT.ks0);
+  assert.equal(keystreamChunk(DEK_LO, DEK_HI, NONCE, 1), KAT.ks1);
+  assert.equal(keystreamChunk(DEK_LO, DEK_HI, NONCE, 31), KAT.ks31);
+
+  // independent keystream recomputation (raw circomlibjs)
+  for (const [i, pinned] of [[0n, KAT.ks0], [1n, KAT.ks1], [31n, KAT.ks31]]) {
+    assert.equal(
+      independentPoseidon([DEK_LO, DEK_HI, NONCE, i]),
+      pinned,
+      `independent Poseidon4 recomputation disagrees at i=${i}`,
+    );
+  }
+
+  // independent chunk derivation + encryption of the fixture plaintext
+  const p0 = leBytes(Buffer.from(PLAINTEXT.subarray(0, 31)));
+  assert.equal(p0, KAT.p0);
+  const c0 = (p0 + independentPoseidon([DEK_LO, DEK_HI, NONCE, 0n])) % R;
+  assert.equal(c0, KAT.c0, "independent field-add encryption disagrees");
+
+  const chunks = bytesToChunks(PLAINTEXT);
+  assert.equal(chunks[0], KAT.p0);
+  assert.equal(encryptPayload(chunks, DEK_LO, DEK_HI, NONCE)[0], KAT.c0);
+
+  // fold KAT (payloadCommitPos of the fixture plaintext — DEK-blinded fold)
+  let acc = independentPoseidon([DOMAIN_PSALT, DEK_LO, DEK_HI]);
+  for (const c of chunks) acc = independentPoseidon([acc, c]);
+  assert.equal(acc, KAT.payloadCommitPos);
+  assert.equal(foldChunksBlind(chunks, DEK_LO, DEK_HI), KAT.payloadCommitPos);
+  // a different DEK seeds a different commitment (dictionary-defense property)
+  assert.notEqual(foldChunksBlind(chunks, DEK_LO + 1n, DEK_HI), KAT.payloadCommitPos);
+
+  // keyCommit KAT
+  assert.equal(computeKeyCommit(DEK_LO, DEK_HI), KAT.keyCommit);
+  assert.equal(independentPoseidon([DEK_LO, DEK_HI]), KAT.keyCommit);
+});
+
+// ---------------------------------------------------------------------------
+// 4. BabyJubJub buyer keys
+// ---------------------------------------------------------------------------
+test("buyer key generation, encode/decode, and validation (circuit-exact rule)", () => {
+  const kp = generateBuyerKeyPair();
+  assert.ok(kp.secret > 0n && kp.secret < BigInt(babyJub.subOrder.toString()));
+  // on-curve per raw circomlibjs
+  assert.ok(babyJub.inCurve([JF.e(kp.publicKey.x), JF.e(kp.publicKey.y)]));
+  // validateBuyerPublicKey accepts and returns canonical bigints
+  assert.deepEqual(validateBuyerPublicKey(kp.publicKey), [kp.publicKey.x, kp.publicKey.y]);
+
+  // point encode/decode round-trip (decimal strings)
+  const enc = encodePoint(kp.publicKey);
+  assert.match(enc.x, /^\d+$/);
+  assert.match(enc.y, /^\d+$/);
+  assert.deepEqual(decodePoint(enc), [kp.publicKey.x, kp.publicKey.y]);
+  assert.deepEqual(validateBuyerPublicKey(enc), [kp.publicKey.x, kp.publicKey.y]);
+
+  // Base8 itself is a valid recipient key
+  assert.deepEqual(validateBuyerPublicKey(encodePoint(babyJub.Base8)), [
+    JF.toObject(babyJub.Base8[0]),
+    JF.toObject(babyJub.Base8[1]),
+  ]);
+});
+
+test("small-order, off-curve, and non-canonical buyer keys are rejected", () => {
+  // identity (0, 1) — order 1
+  assert.throws(() => validateBuyerPublicKey({ x: 0n, y: 1n }), /small-order/);
+  // order-2 point (0, -1) = (0, r-1)
+  assert.throws(() => validateBuyerPublicKey({ x: 0n, y: R - 1n }), /small-order/);
+  // order-8 point: subOrder · Generator (Generator spans the full group, so
+  // multiplying by the prime cofactor quotient lands in the 8-torsion; it has
+  // x ≠ 0, so this exercises the 8·B x-check and not the on-curve equation).
+  const torsion = babyJub.mulPointEscalar(babyJub.Generator, babyJub.subOrder);
+  const t8 = babyJub.mulPointEscalar(torsion, 8n);
+  assert.ok(JF.isZero(t8[0]), "test premise: chosen point must be 8-torsion");
+  assert.ok(babyJub.inCurve(torsion));
+  assert.throws(
+    () => validateBuyerPublicKey({ x: JF.toObject(torsion[0]), y: JF.toObject(torsion[1]) }),
+    /small-order/,
+  );
+  // off-curve point
+  assert.throws(() => validateBuyerPublicKey({ x: 1n, y: 1n }), /not on the BabyJubJub curve/);
+  // non-canonical coordinates (>= r) — must never reach the curve check
+  assert.throws(() => validateBuyerPublicKey({ x: R, y: 1n }), /canonical/);
+  assert.throws(() => validateBuyerPublicKey({ x: 1n, y: R + 5n }), /canonical/);
+  // malformed shape
+  assert.throws(() => validateBuyerPublicKey({}), /expected \{x, y\}/);
+});
+
+// ---------------------------------------------------------------------------
+// 5. Third-party cannot decrypt
+// ---------------------------------------------------------------------------
+test("third party cannot decrypt: wrong buyer secret fails the digest assert", () => {
+  const { args, buyer } = makeFixture();
+  const result = buildSaleWitness(args);
+
+  // intended buyer opens the envelope and the digest checks out
+  const opened = openAndVerifySale({
+    buyerSecret: buyer.secret,
+    epk: result.epk,
+    encDEK_lo: result.encDEK_lo,
+    encDEK_hi: result.encDEK_hi,
+    ciphertext: result.ciphertextChunks,
+    cipherCommit: result.cipherCommit,
+    nonce: NONCE,
+    payloadCommitPos: result.payloadCommitPos,
+  });
+  assert.equal(opened.cipherCommit, result.cipherCommit);
+  assert.equal(opened.dekLo, DEK_LO);
+  assert.equal(opened.dekHi, DEK_HI);
+  assert.deepEqual(opened.plaintextChunks, result.plaintextChunks);
+
+  // a third party (buyer B) derives a different shared secret → wrong DEK
+  const mallory = generateBuyerKeyPair();
+  const stolen = openSaleEnvelope(
+    mallory.secret,
+    result.epk,
+    result.encDEK_lo,
+    result.encDEK_hi,
+  );
+  assert.notEqual(stolen.dekLo, DEK_LO, "third party must NOT recover the DEK");
+  assert.notEqual(stolen.dekHi, DEK_HI);
+
+  // ...and the digest assertion rejects the garbage plaintext
+  assert.throws(
+    () =>
+      openAndVerifySale({
+        buyerSecret: mallory.secret,
+        epk: result.epk,
+        encDEK_lo: result.encDEK_lo,
+        encDEK_hi: result.encDEK_hi,
+        ciphertext: result.ciphertextChunks,
+        cipherCommit: result.cipherCommit,
+        nonce: NONCE,
+        payloadCommitPos: result.payloadCommitPos,
+      }),
+    /digest mismatch/,
+  );
+
+  // junk delivery: ciphertext that does NOT fold to the public cipherCommit
+  // is rejected before any decryption — this is the pre-payment defense.
+  const junk = [...result.ciphertextChunks];
+  junk[0] = (junk[0] + 1n) % R;
+  assert.throws(
+    () =>
+      openAndVerifySale({
+        buyerSecret: buyer.secret,
+        epk: result.epk,
+        encDEK_lo: result.encDEK_lo,
+        encDEK_hi: result.encDEK_hi,
+        ciphertext: junk,
+        cipherCommit: result.cipherCommit,
+        nonce: NONCE,
+        payloadCommitPos: result.payloadCommitPos,
+      }),
+    /junk delivery/,
+  );
+  // cipherCommit is mandatory (it is the public, on-chain commitment)
+  assert.throws(
+    () =>
+      openAndVerifySale({
+        buyerSecret: buyer.secret,
+        epk: result.epk,
+        encDEK_lo: result.encDEK_lo,
+        encDEK_hi: result.encDEK_hi,
+        ciphertext: result.ciphertextChunks,
+        nonce: NONCE,
+        payloadCommitPos: result.payloadCommitPos,
+      }),
+    /missing cipherCommit/,
+  );
+
+  // sanity: both parties agree on ss only when the secret matches
+  const sellerSide = deriveSharedSecret(ESK, buyer.publicKey);
+  const buyerSide = deriveSharedSecret(buyer.secret, result.epk);
+  assert.equal(sellerSide.ss, buyerSide.ss, "ECDH must agree for the intended pair");
+  const mallorySide = deriveSharedSecret(mallory.secret, result.epk);
+  assert.notEqual(mallorySide.ss, buyerSide.ss);
+});
+
+// ---------------------------------------------------------------------------
+// 6. saleTermsHash
+// ---------------------------------------------------------------------------
+test("computeSaleTermsHash matches independent recomputation; guards ranges", () => {
+  const buyer = demoBuyer();
+  const out = computeSaleTermsHash({
+    sellerPubkey: SELLER,
+    buyerPub: buyer.publicKey,
+    mint: MINT,
+    payloadLen: 79n,
+    priceLamports: PRICE,
+    expirySlot: EXPIRY_SLOT,
+  });
+  const s = bs58.decode(SELLER);
+  const m = bs58.decode(MINT);
+  assert.equal(out.sellerLo, leBytes(s.subarray(0, 16)));
+  assert.equal(out.sellerHi, leBytes(s.subarray(16, 32)));
+  assert.equal(out.mintLo, leBytes(m.subarray(0, 16)));
+  assert.equal(out.mintHi, leBytes(m.subarray(16, 32)));
+  for (const limb of [out.sellerLo, out.sellerHi, out.mintLo, out.mintHi]) {
+    assert.ok(limb < 1n << 128n);
+  }
+  assert.equal(out.buyerPubX, buyer.publicKey.x);
+  assert.equal(out.buyerPubY, buyer.publicKey.y);
+  // Poseidon10: buyer pubkey limbs sit between sellerHi and mintLo; payloadLen last
+  assert.equal(
+    out.saleTermsHash,
+    independentPoseidon([
+      DOMAIN_SALE,
+      out.sellerLo,
+      out.sellerHi,
+      buyer.publicKey.x,
+      buyer.publicKey.y,
+      out.mintLo,
+      out.mintHi,
+      PRICE,
+      EXPIRY_SLOT,
+      79n,
+    ]),
+  );
+
+  // collusion defense: a different buyer key MUST change the terms hash, so a
+  // receipt wrapped to a colluder can never match an honest buyer's escrow.
+  const colluder = generateBuyerKeyPair();
+  const colluderTerms = computeSaleTermsHash({
+    sellerPubkey: SELLER,
+    buyerPub: colluder.publicKey,
+    mint: MINT,
+    payloadLen: 79n,
+    priceLamports: PRICE,
+    expirySlot: EXPIRY_SLOT,
+  });
+  assert.notEqual(colluderTerms.saleTermsHash, out.saleTermsHash);
+
+  assert.throws(
+    () => computeSaleTermsHash({ sellerPubkey: "1111", buyerPub: buyer.publicKey, mint: MINT, priceLamports: PRICE, expirySlot: EXPIRY_SLOT, payloadLen: 79n }),
+    /32 bytes/,
+  );
+  assert.throws(
+    () => computeSaleTermsHash({ sellerPubkey: SELLER, buyerPub: { x: 0n, y: 1n }, mint: MINT, priceLamports: PRICE, expirySlot: EXPIRY_SLOT, payloadLen: 79n }),
+    /small-order/,
+  );
+  assert.throws(
+    () => computeSaleTermsHash({ sellerPubkey: SELLER, buyerPub: buyer.publicKey, mint: MINT, priceLamports: 1n << 64n, expirySlot: EXPIRY_SLOT, payloadLen: 79n }),
+    /u64/,
+  );
+  assert.throws(
+    () => computeSaleTermsHash({ sellerPubkey: SELLER, buyerPub: buyer.publicKey, mint: MINT, priceLamports: PRICE, expirySlot: 1n << 48n, payloadLen: 79n }),
+    /48-bit/,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 7. buildSaleWitness
+// ---------------------------------------------------------------------------
+test("buildSaleWitness emits exact signal names, decimal strings, public order", () => {
+  const { args, noteTree, buyer } = makeFixture();
+  const r = buildSaleWitness(args);
+  const w = r.input;
+
+  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.plaintext.length, CHUNK_COUNT);
+  assert.equal(w.ciphertext.length, CHUNK_COUNT);
+
+  // public values (exact order contract — 6 publics, cipherCommit at index 2)
+  assert.deepEqual(
+    SALE_PUBLIC_SIGNALS,
+    ["noteRoot", "payloadCommitPos", "cipherCommit", "keyCommit", "saleTermsHash", "envelopeCommit"],
+  );
+  assert.equal(w.cipherCommit, foldChunks(r.ciphertextChunks).toString());
+  assert.equal(w.noteRoot, noteTree.root().toString());
+  assert.equal(w.payloadCommitPos, KAT.payloadCommitPos.toString());
+  assert.equal(w.keyCommit, KAT.keyCommit.toString());
+  assert.equal(
+    w.saleTermsHash,
+    computeSaleTermsHash({
+      sellerPubkey: SELLER,
+      buyerPub: buyer.publicKey,
+      mint: MINT,
+      payloadLen: 79n,
+      priceLamports: PRICE,
+      expirySlot: EXPIRY_SLOT,
+    }).saleTermsHash.toString(),
+  );
+  // buyer-bound terms: the witness buyerPubX/Y feed the terms hash
+  assert.equal(w.saleTermsHash, r.saleTermsHash.toString());
+  assert.equal(r.buyerPubX, buyer.publicKey.x);
+  assert.equal(r.buyerPubY, buyer.publicKey.y);
+
+  // envelope self-consistency (independent recomputation from raw signals)
+  const epkP = babyJub.mulPointEscalar(babyJub.Base8, ESK);
+  assert.deepEqual(r.epk, { x: JF.toObject(epkP[0]), y: JF.toObject(epkP[1]) });
+  const sharedP = babyJub.mulPointEscalar([JF.e(buyer.publicKey.x), JF.e(buyer.publicKey.y)], ESK);
+  const ss = independentPoseidon([JF.toObject(sharedP[0]), JF.toObject(sharedP[1])]);
+  assert.equal(r.encDEK_lo, (DEK_LO + independentPoseidon([ss, 0n])) % R);
+  assert.equal(r.encDEK_hi, (DEK_HI + independentPoseidon([ss, 1n])) % R);
+  assert.equal(
+    r.envelopeCommit,
+    independentPoseidon([r.epk.x, r.epk.y, r.encDEK_lo, r.encDEK_hi, NONCE]),
+  );
+  assert.equal(w.envelopeCommit, r.envelopeCommit.toString());
+
+  // private consistency
+  assert.equal(w.dekLo, DEK_LO.toString());
+  assert.equal(w.dekHi, DEK_HI.toString());
+  assert.equal(w.nonce, NONCE.toString());
+  assert.equal(w.esk, ESK.toString());
+  assert.equal(w.buyerPubX, buyer.publicKey.x.toString());
+  assert.equal(w.buyerPubY, buyer.publicKey.y.toString());
+  assert.equal(w.cipherCommit, foldChunks(r.ciphertextChunks).toString());
+  assert.equal(BigInt(w.plaintext[0]), KAT.p0);
+  assert.equal(BigInt(w.ciphertext[0]), KAT.c0);
+});
+
+test("buildSaleWitness rejects malformed sales client-side", () => {
+  const { args } = makeFixture();
+  // note opening mismatch
+  assert.throws(() => buildSaleWitness({ ...args, rho: RHO + 1n }), /does not match the leaf/);
+  // stale noteIndex
+  assert.throws(() => buildSaleWitness({ ...args, noteIndex: 9 }), /not present/);
+  // DEK limb overflow
+  assert.throws(() => buildSaleWitness({ ...args, dekLo: 1n << 128n }), /2\^128/);
+  // small-order buyer key
+  assert.throws(() => buildSaleWitness({ ...args, buyerPub: { x: 0n, y: 1n } }), /small-order/);
+  // off-curve buyer key
+  assert.throws(() => buildSaleWitness({ ...args, buyerPub: { x: 1n, y: 1n } }), /not on/);
+  // esk out of Num2Bits(253) range
+  assert.throws(() => buildSaleWitness({ ...args, esk: 1n << 253n }), /253/);
+  // oversize plaintext
+  assert.throws(
+    () => buildSaleWitness({ ...args, plaintextBytes: new Uint8Array(PAYLOAD_CAPACITY + 1) }),
+    /out of range|too large/,
+  );
+  // random esk path (no esk supplied) still yields a valid witness
+  const { args: args2 } = makeFixture();
+  delete args2.esk;
+  const r2 = buildSaleWitness(args2);
+  assert.ok(BigInt(r2.input.esk) < 1n << 253n);
+});
+
+// ---------------------------------------------------------------------------
+// 7b. Demo fixture contract (consumed by zk/setup-sale.mjs proof-of-life)
+// ---------------------------------------------------------------------------
+test("buildSaleDemoFixture returns input + expectedPublic in circuit order", async () => {
+  const fx = await buildSaleDemoFixture();
+  assert.deepEqual(Object.keys(fx.input).sort(), [...EXPECTED_SIGNALS].sort());
+  assert.equal(fx.expectedPublic.length, 6);
+  assert.deepEqual(
+    fx.expectedPublic,
+    SALE_PUBLIC_SIGNALS.map((n) => fx.input[n]),
+  );
+  for (const v of fx.expectedPublic) assert.match(v, /^\d+$/);
+  // buyer can open the demo envelope
+  const opened = openAndVerifySale({
+    buyerSecret: fx.buyerSecret,
+    epk: fx.artifacts.epk,
+    encDEK_lo: fx.artifacts.encDEK_lo,
+    encDEK_hi: fx.artifacts.encDEK_hi,
+    ciphertext: fx.artifacts.ciphertextChunks,
+    cipherCommit: fx.artifacts.cipherCommit,
+    nonce: fx.input.nonce,
+    payloadCommitPos: fx.artifacts.payloadCommitPos,
+  });
+  assert.deepEqual(
+    chunksToBytes(opened.plaintextChunks, fx.plaintextBytes.length),
+    fx.plaintextBytes,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 8. Signal-name reconciliation vs the .circom source (when present)
+// ---------------------------------------------------------------------------
+test("signal names reconcile with circuits/sealed_sale_release.circom", (t) => {
+  if (!existsSync(CIRCUIT_SRC)) {
+    t.skip("circuits/sealed_sale_release.circom not present yet (SaleCircuit in flight)");
+    return;
+  }
+  const src = readFileSync(CIRCUIT_SRC, "utf8").replace(/\/\/[^\n]*/g, "");
+  // Scope to the main template body: helper templates (DualMux/PoseidonN/
+  // chunk fold) declare their own generic `signal input`s that are not part
+  // of the witness contract. The main template is the last one before
+  // `component main`.
+  const mainIdx = src.indexOf("component main");
+  assert.ok(mainIdx !== -1, "component main not found");
+  const tplStart = src.lastIndexOf("template ", mainIdx);
+  assert.ok(tplStart !== -1, "main template not found");
+  const tpl = src.slice(tplStart, mainIdx);
+  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 sale-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, [...SALE_PUBLIC_SIGNALS], "public input order diverges");
+});
+
+// ---------------------------------------------------------------------------
+// 9. WASM-gated circuit satisfaction legs
+// ---------------------------------------------------------------------------
+const POLL_MS = Number(process.env.SALE_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(
+    `[sale-witness] sealed_sale_release 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 sale witness", async (t) => {
+  if (!wasmReady) {
+    t.skip("sealed_sale_release wasm absent (see log above); nothing to check against");
+    return;
+  }
+  const tmp = mkdtempSync(join(tmpdir(), "enigma-sale-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  const { args } = makeFixture();
+  const { input } = buildSaleWitness(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, "sale.wtns");
+  writeFileSync(wtnsPath, bin);
+
+  if (existsSync(R1CS)) {
+    assert.ok(wtnsCheck(wtnsPath), "valid sale witness must satisfy the R1CS");
+  }
+});
+
+test("compiled circuit rejects a junk-ciphertext witness", async (t) => {
+  if (!wasmReady) {
+    t.skip("sealed_sale_release wasm absent (see log above); nothing to check against");
+    return;
+  }
+  const { args } = makeFixture();
+  const { input } = buildSaleWitness(args);
+  const buildCalc = require(WITNESS_CALC);
+  const calc = await buildCalc(readFileSync(WASM));
+
+  // Tamper one ciphertext chunk WITHOUT touching the plaintext: the circuit
+  // constraint c_i - ks_i === p_i (and the cipherCommit fold) must fail —
+  // exactly what a seller would try if delivering junk bytes while claiming
+  // the listed payloadCommitPos.
+  const junk = { ...input };
+  junk.ciphertext = [...input.ciphertext];
+  junk.ciphertext[0] = ((BigInt(input.ciphertext[0]) + 1n) % R).toString();
+  await assert.rejects(
+    () => calc.calculateWTNSBin(junk, true),
+    /Assert Failed|Error/,
+    "circuit must reject ciphertext inconsistent with the committed plaintext",
+  );
+
+  // And the honest plaintext fold bound into the note must match the listed
+  // payloadCommitPos: tampering the plaintext breaks BOTH the note opening
+  // and the encryption-consistency legs.
+  const junkPt = { ...input };
+  junkPt.plaintext = [...input.plaintext];
+  junkPt.plaintext[0] = ((BigInt(input.plaintext[0]) + 1n) % R).toString();
+  await assert.rejects(
+    () => calc.calculateWTNSBin(junkPt, true),
+    /Assert Failed|Error/,
+    "circuit must reject plaintext inconsistent with the note/ciphertext",
+  );
+});