enigma-memory 0.1.18 → 0.1.22

package/cortex-v3/zk/zk-tree.mjs

@@ -0,0 +1,256 @@
+// zk-tree.mjs — Poseidon Merkle trees for the Enigma per-action ZK circuit.
+// Implements the shared conventions of cortex-v3/zk/BUILD-CONTRACT.md v3:
+//   - BN254 Poseidon (circomlibjs), field
+//     r = 21888242871839275222246405745257275088548364400416034343698204186575808495617
+//   - zeros[0] = 0, zeros[i+1] = Poseidon([zeros[i], zeros[i]])
+//   - path index bits are LSB-first (bit at level l = (index >> l) & 1)
+//   - field elements are bigint everywhere in JS; decimal-string JSON emission
+//     happens in witness.mjs.
+//
+// NoteTree: append-only incremental Merkle tree (D=20), shared note tree.
+// NullifierIMT: Aztec-style indexed Merkle tree (D=20) over
+//   { value, nextIndex, nextValue } leaves hashed Poseidon([value, nextIndex, nextValue]),
+//   genesis leaf index 0 = { 0, 0, r - 1 } (sentinel infinity = r - 1).
+
+import { buildPoseidon } from "circomlibjs";
+
+const poseidonC = await buildPoseidon();
+const F = poseidonC.F;
+
+/** BN254 scalar field order r. */
+export const FIELD_R = F.p;
+/** Tree depth fixed by the circuit (ActionTransition(D=20)). */
+export const TREE_DEPTH = 20;
+/** Maximum number of leaves in a D=20 tree. */
+export const MAX_LEAVES = 2 ** TREE_DEPTH;
+
+/**
+ * DOMAIN_REVOCATION = 0x656e69676d615f7265766f6b65 ("enigma_revoke" ASCII),
+ * decimal 8036215190653564882703377984357. Epoch-independent, deterministic
+ * nullifier domain separator: nf = Poseidon([DOMAIN_REVOCATION, ownerKey, rho]).
+ */
+export const DOMAIN_REVOCATION = BigInt("0x656e69676d615f7265766f6b65");
+
+/** Poseidon hash over an array of bigint field elements → bigint. */
+export function poseidon(inputs) {
+  return F.toObject(poseidonC(inputs.map((x) => F.e(BigInt(x)))));
+}
+
+/** Zero chain: zeros[0] = 0n, zeros[i+1] = Poseidon([zeros[i], zeros[i]]). */
+export function buildZeros(depth = TREE_DEPTH) {
+  const zeros = [0n];
+  for (let i = 0; i < depth; i++) zeros.push(poseidon([zeros[i], zeros[i]]));
+  return zeros;
+}
+
+/** Shared zero chain for D=20. */
+export const ZEROS = buildZeros(TREE_DEPTH);
+
+// ---------------------------------------------------------------------------
+// Shared sparse-Merkle machinery (append-only: only the filled prefix exists,
+// every node past leafHashes.length at level l is zeros[l]).
+// ---------------------------------------------------------------------------
+
+/** Root of the append-only Merkle tree whose filled leaves are `leafHashes`. */
+export function computeRoot(leafHashes, zeros = ZEROS, depth = TREE_DEPTH) {
+  if (leafHashes.length === 0) return zeros[depth];
+  let level = leafHashes.slice();
+  for (let l = 0; l < depth; l++) {
+    const next = [];
+    for (let i = 0; i < level.length; i += 2) {
+      const right = i + 1 < level.length ? level[i + 1] : zeros[l];
+      next.push(poseidon([level[i], right]));
+    }
+    level = next;
+  }
+  return level[0];
+}
+
+/**
+ * Merkle proof for `index` (filled or not) against the current state.
+ * Returns { pathElements, pathIndices } with LSB-first index bits.
+ */
+export function computeProof(leafHashes, index, zeros = ZEROS, depth = TREE_DEPTH) {
+  if (!Number.isInteger(index) || index < 0 || index >= 2 ** depth) {
+    throw new RangeError(`leaf index ${index} out of range for depth ${depth}`);
+  }
+  const pathElements = [];
+  const pathIndices = [];
+  let level = leafHashes.slice();
+  let idx = index;
+  for (let l = 0; l < depth; l++) {
+    const sib = idx ^ 1;
+    pathElements.push(sib < level.length ? level[sib] : zeros[l]);
+    pathIndices.push(idx & 1);
+    const next = [];
+    for (let i = 0; i < level.length; i += 2) {
+      const right = i + 1 < level.length ? level[i + 1] : zeros[l];
+      next.push(poseidon([level[i], right]));
+    }
+    level = next;
+    idx >>= 1;
+  }
+  return { pathElements, pathIndices };
+}
+
+/** Fold a proof: leaf + LSB-first bits + siblings → root equality check. */
+export function verifyMerkleProof(leaf, pathElements, pathIndices, root, depth = TREE_DEPTH) {
+  if (pathElements.length !== depth || pathIndices.length !== depth) return false;
+  let node = BigInt(leaf);
+  for (let l = 0; l < depth; l++) {
+    const bit = pathIndices[l];
+    if (bit !== 0 && bit !== 1) return false;
+    node = bit === 1 ? poseidon([pathElements[l], node]) : poseidon([node, pathElements[l]]);
+  }
+  return node === BigInt(root);
+}
+
+// ---------------------------------------------------------------------------
+// NoteTree — append-only incremental Merkle tree of Poseidon notes (D=20).
+// ---------------------------------------------------------------------------
+
+export class NoteTree {
+  constructor(depth = TREE_DEPTH, leaves = []) {
+    this.depth = depth;
+    this.zeros = buildZeros(depth);
+    this.leaves = leaves.map((l) => BigInt(l));
+  }
+
+  /** Non-mutating copy (used to snapshot pre-action state). */
+  clone() {
+    return new NoteTree(this.depth, this.leaves);
+  }
+
+  /** Index the next insert will occupy. */
+  get nextIndex() {
+    return this.leaves.length;
+  }
+
+  root() {
+    return computeRoot(this.leaves, this.zeros, this.depth);
+  }
+
+  /** Proof for any index (filled leaf or zero slot) against the current root. */
+  getProof(index) {
+    return computeProof(this.leaves, index, this.zeros, this.depth);
+  }
+
+  /**
+   * Append `leaf`. Returns { index, pathElements, pathIndices } — the proof of
+   * the PRE-insert zero leaf (zeros[0] = 0) at `index` against the pre-insert
+   * root, exactly what the APPEND mode of the circuit consumes.
+   */
+  insert(leaf) {
+    const index = this.leaves.length;
+    if (index >= 2 ** this.depth) throw new RangeError("note tree full");
+    const { pathElements, pathIndices } = this.getProof(index);
+    this.leaves.push(BigInt(leaf));
+    return { index, pathElements, pathIndices };
+  }
+
+  verifyProof(leaf, pathElements, pathIndices, root = this.root()) {
+    return verifyMerkleProof(leaf, pathElements, pathIndices, root, this.depth);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// NullifierIMT — indexed Merkle tree (D=20) for nullifier non-membership.
+// Leaves { value, nextIndex, nextValue }, hashed Poseidon([value, nextIndex, nextValue]).
+// Sorted linked list: leaf.next* points at the leaf with the next larger value.
+// Genesis: index 0 = { 0n, 0n, r - 1n }.
+// ---------------------------------------------------------------------------
+
+export class NullifierIMT {
+  constructor(depth = TREE_DEPTH) {
+    this.depth = depth;
+    this.zeros = buildZeros(depth);
+    this.leaves = [{ value: 0n, nextIndex: 0n, nextValue: FIELD_R - 1n }];
+  }
+
+  /** Next append index == on-chain null_count (genesis leaf counts as index 0). */
+  get appendCounter() {
+    return this.leaves.length;
+  }
+
+  leafHash(leaf) {
+    return poseidon([leaf.value, leaf.nextIndex, leaf.nextValue]);
+  }
+
+  leafHashes() {
+    return this.leaves.map((l) => this.leafHash(l));
+  }
+
+  root() {
+    return computeRoot(this.leafHashes(), this.zeros, this.depth);
+  }
+
+  /** Proof for any index (filled leaf or zero slot) against the current root. */
+  getProof(index) {
+    return computeProof(this.leafHashes(), index, this.zeros, this.depth);
+  }
+
+  /** Largest stored value strictly < nf. Throws if none (nf <= 0). */
+  findPredecessor(nf) {
+    nf = BigInt(nf);
+    let best = -1;
+    for (let i = 0; i < this.leaves.length; i++) {
+      const v = this.leaves[i].value;
+      if (v < nf && (best === -1 || v > this.leaves[best].value)) best = i;
+    }
+    if (best === -1) throw new Error(`no predecessor for nullifier ${nf}`);
+    return { index: best, leaf: { ...this.leaves[best] } };
+  }
+
+  /**
+   * IMT non-membership insert of `nf` (contract v3 REVOKE step):
+   *   1. predecessor = largest value < nf; require strict nf < pred.nextValue
+   *      (rejects duplicates: if nf is already a leaf value, its predecessor's
+   *      nextValue === nf and the strict inequality fails);
+   *   2. predecessorPath = proof of the OLD predecessor leaf vs current root;
+   *   3. predecessor updated in place → { predValue, newLeafIndex, nf };
+   *   4. appendPath = proof of the zero slot at newLeafIndex vs the updated
+   *      (intermediate) root;
+   *   5. append { nf, oldPredNextIndex, oldPredNextValue } at newLeafIndex.
+   * Returns { predecessorPath, predecessorLeaf (OLD), newLeafIndex, appendPath }.
+   */
+  insert(nf) {
+    nf = BigInt(nf);
+    if (nf <= 0n || nf >= FIELD_R) {
+      throw new RangeError(`nullifier ${nf} out of field range (0, r)`);
+    }
+    const pred = this.findPredecessor(nf);
+    if (!(nf < pred.leaf.nextValue)) {
+      throw new Error(
+        `nullifier ${nf} violates strict inequality (duplicate or unsorted predecessor)`,
+      );
+    }
+    const predecessorLeaf = pred.leaf; // OLD values { value, nextIndex, nextValue }
+    const predecessorPath = this.getProof(pred.index);
+    const newLeafIndex = this.leaves.length;
+    // 1. predecessor update → intermediate root
+    this.leaves[pred.index] = {
+      value: predecessorLeaf.value,
+      nextIndex: BigInt(newLeafIndex),
+      nextValue: nf,
+    };
+    // 2. zero-leaf proof at newLeafIndex against the intermediate root
+    const appendPath = this.getProof(newLeafIndex);
+    // 3. append new leaf inheriting the predecessor's OLD next-pointer
+    this.leaves.push({
+      value: nf,
+      nextIndex: predecessorLeaf.nextIndex,
+      nextValue: predecessorLeaf.nextValue,
+    });
+    return { predecessorPath, predecessorLeaf, newLeafIndex, appendPath };
+  }
+
+  /** `leaf` may be a { value, nextIndex, nextValue } object or a raw leaf hash. */
+  verifyProof(leaf, pathElements, pathIndices, root = this.root()) {
+    const h = typeof leaf === "object" && leaf !== null ? this.leafHash(leaf) : BigInt(leaf);
+    return verifyMerkleProof(h, pathElements, pathIndices, root, this.depth);
+  }
+
+  contains(nf) {
+    return this.leaves.some((l) => l.value === BigInt(nf));
+  }
+}

package/cortex-v3/zk/zk-tree.test.mjs

@@ -0,0 +1,419 @@
+// zk-tree.test.mjs — node:test suite for zk-tree.mjs + witness.mjs
+// (BUILD-CONTRACT.md v3: sovereign per-action proofs, ActionTransition(D=20)).
+// Run: node --test cortex-v3/zk/zk-tree.test.mjs
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  DOMAIN_REVOCATION,
+  FIELD_R,
+  NoteTree,
+  NullifierIMT,
+  TREE_DEPTH,
+  ZEROS,
+  poseidon,
+  verifyMerkleProof,
+} from "./zk-tree.mjs";
+import { buildActionWitness } from "./witness.mjs";
+
+const D = TREE_DEPTH;
+
+// Fixed sample openings (deterministic tests, arbitrary field elements).
+const OWNER_KEY = 1111111111111111111111111111111111111111111111111111111111111111n;
+const RHO = 2222222222222222222222222222222222222222222222222222222222222222n;
+const PAYLOAD = 3333333333333333333333333333333333333333333333333333333333333333n;
+const OWNER_KEY2 = 4444444444444444444444444444444444444444444444444444444444444444n;
+const RHO2 = 5555555555555555555555555555555555555555555555555555555555555555n;
+const PAYLOAD2 = 6666666666666666666666666666666666666666666666666666666666666666n;
+
+function unpack(packed) {
+  const p = BigInt(packed);
+  return { mode: p >> 60n, actionIndex: p % (1n << 60n) };
+}
+
+test("zero chain matches the contract rule", () => {
+  assert.equal(ZEROS[0], 0n);
+  for (let i = 0; i < D; i++) {
+    assert.equal(ZEROS[i + 1], poseidon([ZEROS[i], ZEROS[i]]));
+  }
+  // Empty note tree root is zeros[D].
+  assert.equal(new NoteTree().root(), ZEROS[D]);
+});
+
+test("NoteTree: insert changes root; pre-insert zero proof and post-insert leaf proof verify", () => {
+  const tree = new NoteTree();
+  const note = poseidon([OWNER_KEY, RHO, PAYLOAD]);
+  const preRoot = tree.root();
+
+  const ins = tree.insert(note);
+  assert.equal(ins.index, 0);
+  assert.equal(ins.pathElements.length, D);
+  assert.equal(ins.pathIndices.length, D);
+
+  // Returned proof is the PRE-insert zero-leaf proof: zeros[0]=0 at index 0 vs preRoot.
+  assert.ok(verifyMerkleProof(ZEROS[0], ins.pathElements, ins.pathIndices, preRoot));
+  // LSB-first bits of index 0 are all zero.
+  assert.ok(ins.pathIndices.every((b) => b === 0));
+
+  const postRoot = tree.root();
+  assert.notEqual(postRoot, preRoot);
+  // Post-insert membership proof of the actual leaf verifies vs postRoot.
+  const mem = tree.getProof(0);
+  assert.ok(verifyMerkleProof(note, mem.pathElements, mem.pathIndices, postRoot));
+  // ...and NOT vs the stale root (replay protection shape).
+  assert.ok(!verifyMerkleProof(note, mem.pathElements, mem.pathIndices, preRoot));
+
+  // Second insert at index 1: sibling at level 0 is the first leaf.
+  const note2 = poseidon([OWNER_KEY2, RHO2, PAYLOAD2]);
+  const pre2 = tree.root();
+  const ins2 = tree.insert(note2);
+  assert.equal(ins2.index, 1);
+  assert.equal(ins2.pathElements[0], note); // level-0 sibling
+  assert.equal(ins2.pathIndices[0], 1); // LSB of index 1
+  assert.ok(verifyMerkleProof(ZEROS[0], ins2.pathElements, ins2.pathIndices, pre2));
+  assert.notEqual(tree.root(), pre2);
+});
+
+test("NoteTree: inserting a zero leaf at a zero position is a root no-op", () => {
+  const tree = new NoteTree();
+  const r0 = tree.root();
+  tree.insert(0n);
+  assert.equal(tree.root(), r0);
+  // Still a no-op above a non-zero leaf: zero subtree paths stay the zero chain.
+  const tree2 = new NoteTree();
+  tree2.insert(poseidon([1n, 2n, 3n]));
+  const before = tree2.root();
+  tree2.insert(0n);
+  tree2.insert(0n);
+  assert.equal(tree2.root(), before);
+});
+
+test("NullifierIMT: genesis shape and root", () => {
+  const imt = new NullifierIMT();
+  assert.equal(imt.appendCounter, 1); // genesis leaf occupies index 0
+  assert.deepEqual(imt.leaves[0], { value: 0n, nextIndex: 0n, nextValue: FIELD_R - 1n });
+  const genesisHash = poseidon([0n, 0n, FIELD_R - 1n]);
+  assert.equal(imt.leafHashes()[0], genesisHash);
+  // Genesis root = Merkle root of the single genesis leaf.
+  const proof = imt.getProof(0);
+  assert.ok(imt.verifyProof(imt.leaves[0], proof.pathElements, proof.pathIndices, imt.root()));
+});
+
+test("NullifierIMT: insert updates predecessor 0, appends new leaf, changes root", () => {
+  const imt = new NullifierIMT();
+  const nf = poseidon([DOMAIN_REVOCATION, OWNER_KEY, RHO]);
+  const oldRoot = imt.root();
+
+  const res = imt.insert(nf);
+  assert.equal(res.newLeafIndex, 1);
+  assert.deepEqual(res.predecessorLeaf, { value: 0n, nextIndex: 0n, nextValue: FIELD_R - 1n });
+
+  // Predecessor path proves the OLD genesis leaf vs the OLD root.
+  assert.ok(
+    imt.verifyProof(
+      res.predecessorLeaf,
+      res.predecessorPath.pathElements,
+      res.predecessorPath.pathIndices,
+      oldRoot,
+    ),
+  );
+
+  // Intermediate state = predecessor updated, nothing appended yet.
+  const intermediate = new NullifierIMT();
+  intermediate.leaves[0] = { value: 0n, nextIndex: 1n, nextValue: nf };
+  const intermediateRoot = intermediate.root();
+  // appendPath is the zero-leaf proof at newLeafIndex vs the intermediate root.
+  assert.ok(
+    verifyMerkleProof(ZEROS[0], res.appendPath.pathElements, res.appendPath.pathIndices, intermediateRoot),
+  );
+
+  // Final state: predecessor points at the new leaf; new leaf inherits old pointer.
+  assert.deepEqual(imt.leaves[0], { value: 0n, nextIndex: 1n, nextValue: nf });
+  assert.deepEqual(imt.leaves[1], { value: nf, nextIndex: 0n, nextValue: FIELD_R - 1n });
+  intermediate.leaves.push({ value: nf, nextIndex: 0n, nextValue: FIELD_R - 1n });
+  assert.equal(imt.root(), intermediate.root());
+  assert.notEqual(imt.root(), oldRoot);
+  assert.notEqual(imt.root(), intermediateRoot);
+
+  // New leaf membership verifies vs the new root.
+  const mem = imt.getProof(1);
+  assert.ok(imt.verifyProof(imt.leaves[1], mem.pathElements, mem.pathIndices, imt.root()));
+});
+
+test("NullifierIMT: second insert picks the correct predecessor (above and below)", () => {
+  const imt = new NullifierIMT();
+  const nf1 = poseidon([DOMAIN_REVOCATION, OWNER_KEY, RHO]);
+  const nf2 = poseidon([DOMAIN_REVOCATION, OWNER_KEY2, RHO2]);
+  assert.notEqual(nf1, nf2);
+  const [lo, hi] = nf1 < nf2 ? [nf1, nf2] : [nf2, nf1];
+
+  imt.insert(hi); // index 1
+  // Insert above hi: predecessor must be the hi leaf (index 1), not genesis.
+  const above = hi + 1n < FIELD_R ? hi + 1n : hi - 1n;
+  const resAbove = imt.insert(above);
+  assert.equal(resAbove.predecessorLeaf.value, hi);
+  assert.equal(resAbove.newLeafIndex, 2);
+  // Insert between genesis and lo... use lo itself inserted below hi first.
+  const resLo = imt.insert(lo);
+  assert.equal(resLo.predecessorLeaf.value, 0n); // genesis is the largest value < lo
+  assert.equal(resLo.newLeafIndex, 3);
+  // And a mid value between lo and hi picks lo.
+  const mid = lo + (hi - lo) / 2n;
+  const resMid = imt.insert(mid);
+  assert.equal(resMid.predecessorLeaf.value, lo);
+  assert.equal(resMid.newLeafIndex, 4);
+});
+
+test("NullifierIMT: duplicate nullifier rejected by strict inequality", () => {
+  const imt = new NullifierIMT();
+  const nf = poseidon([DOMAIN_REVOCATION, OWNER_KEY, RHO]);
+  imt.insert(nf);
+  assert.throws(() => imt.insert(nf), /strict inequality|duplicate/);
+  // State untouched after rejection.
+  assert.equal(imt.appendCounter, 2);
+  assert.equal(imt.leaves.filter((l) => l.value === nf).length, 1);
+  // Out-of-field nullifiers rejected too.
+  assert.throws(() => imt.insert(0n), RangeError);
+  assert.throws(() => imt.insert(FIELD_R), RangeError);
+});
+
+test("witness APPEND: roots, packed KAT, zero-leaf path, unused signals zeroed", () => {
+  const noteTree = new NoteTree();
+  const imt = new NullifierIMT();
+  const note = poseidon([OWNER_KEY, RHO, PAYLOAD]);
+  const oldNoteRoot = noteTree.root();
+  const oldNullRoot = imt.root();
+
+  const w = buildActionWitness({
+    mode: "append",
+    noteTree,
+    nullifierTree: imt,
+    ownerKey: OWNER_KEY,
+    rho: RHO,
+    payloadCommit: PAYLOAD,
+  });
+
+  // Public signals — hand-computed expectations.
+  assert.equal(w.oldNoteRoot, oldNoteRoot.toString());
+  assert.equal(w.oldNullRoot, oldNullRoot.toString());
+  assert.equal(w.newNullRoot, oldNullRoot.toString()); // constrained equal
+  assert.equal(w.nullifier, "0");
+  // packed KAT: mode 0 * 2^60 + actionIndex 0 = 0 for the very first append.
+  assert.equal(w.packed, "0");
+  assert.deepEqual(unpack(w.packed), { mode: 0n, actionIndex: 0n });
+  // newNoteRoot = independently recomputed root of [note].
+  assert.equal(BigInt(w.newNoteRoot), new NoteTree(20, [note]).root());
+  assert.equal(BigInt(w.newNoteRoot), noteTree.root()); // tree mutated in place
+
+  // Private signals.
+  assert.equal(w.isAppend, "1");
+  assert.equal(w.note, note.toString());
+  assert.equal(w.ownerKey, OWNER_KEY.toString());
+  assert.equal(w.rho, RHO.toString());
+  assert.equal(w.payloadCommit, PAYLOAD.toString());
+  // notePath* = pre-insert zero-leaf proof vs oldNoteRoot.
+  assert.equal(w.notePathElements.length, D);
+  assert.ok(
+    verifyMerkleProof(
+      ZEROS[0],
+      w.notePathElements.map(BigInt),
+      w.notePathIndices.map(Number),
+      oldNoteRoot,
+    ),
+  );
+  // Unused revocation signals are zero paths / zero scalars (fixed shape).
+  for (const k of ["noteMemPathElements", "predPathElements", "appendPathElements"]) {
+    assert.ok(w[k].every((x) => x === "0"), `${k} must be all zeros in append mode`);
+  }
+  for (const k of ["noteMemPathIndices", "predPathIndices", "appendPathIndices"]) {
+    assert.ok(w[k].every((x) => x === "0"), `${k} must be all zeros in append mode`);
+  }
+  assert.equal(w.predValue, "0");
+  assert.equal(w.predNextIndex, "0");
+  assert.equal(w.predNextValue, "0");
+
+  // Second append: packed = actionIndex 1 (still mode 0).
+  const w2 = buildActionWitness({
+    mode: "append",
+    noteTree,
+    nullifierTree: imt,
+    ownerKey: OWNER_KEY2,
+    rho: RHO2,
+    payloadCommit: PAYLOAD2,
+  });
+  assert.deepEqual(unpack(w2.packed), { mode: 0n, actionIndex: 1n });
+  assert.equal(BigInt(w2.oldNoteRoot), BigInt(w.newNoteRoot)); // continuity
+});
+
+test("witness REVOKE: membership, nullifier, IMT transition, packed KAT", () => {
+  const noteTree = new NoteTree();
+  const imt = new NullifierIMT();
+  // Two prior appends so membership happens above the bottom row.
+  buildActionWitness({
+    mode: "append",
+    noteTree,
+    nullifierTree: imt,
+    ownerKey: OWNER_KEY2,
+    rho: RHO2,
+    payloadCommit: PAYLOAD2,
+  });
+  buildActionWitness({
+    mode: "append",
+    noteTree,
+    nullifierTree: imt,
+    ownerKey: OWNER_KEY,
+    rho: RHO,
+    payloadCommit: PAYLOAD,
+  });
+  const note = poseidon([OWNER_KEY, RHO, PAYLOAD]);
+  const nf = poseidon([DOMAIN_REVOCATION, OWNER_KEY, RHO]);
+  const oldNoteRoot = noteTree.root();
+  const oldNullRoot = imt.root();
+
+  const w = buildActionWitness({
+    mode: "revoke",
+    noteTree,
+    nullifierTree: imt,
+    ownerKey: OWNER_KEY,
+    rho: RHO,
+    payloadCommit: PAYLOAD,
+    noteIndex: 1,
+  });
+
+  // Public signals — hand-computed expectations.
+  assert.equal(w.oldNoteRoot, oldNoteRoot.toString());
+  assert.equal(w.newNoteRoot, oldNoteRoot.toString()); // constrained equal
+  assert.equal(w.oldNullRoot, oldNullRoot.toString());
+  assert.equal(w.nullifier, nf.toString());
+  // packed KAT: first revoke → mode 1 * 2^60 + actionIndex 1 (genesis counts).
+  assert.equal(BigInt(w.packed), (1n << 60n) + 1n);
+  assert.deepEqual(unpack(w.packed), { mode: 1n, actionIndex: 1n });
+  assert.notEqual(w.newNullRoot, oldNullRoot.toString());
+  assert.equal(BigInt(w.newNullRoot), imt.root()); // IMT mutated in place
+
+  // Private signals.
+  assert.equal(w.isAppend, "0");
+  assert.equal(w.note, note.toString());
+  // Membership path proves the note vs oldNoteRoot.
+  assert.ok(
+    verifyMerkleProof(
+      note,
+      w.noteMemPathElements.map(BigInt),
+      w.noteMemPathIndices.map(Number),
+      oldNoteRoot,
+    ),
+  );
+  // LSB-first bits reconstruct noteIndex = 1.
+  const bits = w.noteMemPathIndices.map(Number);
+  assert.equal(bits.reduce((acc, b, l) => acc + BigInt(b) * (1n << BigInt(l)), 0n), 1n);
+  // Predecessor signals are the OLD genesis leaf.
+  assert.equal(w.predValue, "0");
+  assert.equal(w.predNextIndex, "0");
+  assert.equal(w.predNextValue, (FIELD_R - 1n).toString());
+  const genesisHash = poseidon([0n, 0n, FIELD_R - 1n]);
+  assert.ok(
+    verifyMerkleProof(
+      genesisHash,
+      w.predPathElements.map(BigInt),
+      w.predPathIndices.map(Number),
+      oldNullRoot,
+    ),
+  );
+  // appendPath: zero leaf at index 1 vs the intermediate root.
+  const intermediate = new NullifierIMT();
+  intermediate.leaves[0] = { value: 0n, nextIndex: 1n, nextValue: nf };
+  assert.ok(
+    verifyMerkleProof(
+      ZEROS[0],
+      w.appendPathElements.map(BigInt),
+      w.appendPathIndices.map(Number),
+      intermediate.root(),
+    ),
+  );
+  // Unused note-insert path is all zeros in revoke mode.
+  assert.ok(w.notePathElements.every((x) => x === "0"));
+  assert.ok(w.notePathIndices.every((x) => x === "0"));
+
+  // Double revoke of the same note → duplicate nullifier rejected.
+  assert.throws(
+    () =>
+      buildActionWitness({
+        mode: "revoke",
+        noteTree,
+        nullifierTree: imt,
+        ownerKey: OWNER_KEY,
+        rho: RHO,
+        payloadCommit: PAYLOAD,
+        noteIndex: 1,
+      }),
+    /strict inequality|duplicate/,
+  );
+
+  // Second distinct revoke continues the sequential append counter.
+  const w2 = buildActionWitness({
+    mode: "revoke",
+    noteTree,
+    nullifierTree: imt,
+    ownerKey: OWNER_KEY2,
+    rho: RHO2,
+    payloadCommit: PAYLOAD2,
+    noteIndex: 0,
+  });
+  assert.deepEqual(unpack(w2.packed), { mode: 1n, actionIndex: 2n });
+  assert.equal(BigInt(w2.oldNullRoot), BigInt(w.newNullRoot)); // continuity
+});
+
+test("witness input validation", () => {
+  const noteTree = new NoteTree();
+  const imt = new NullifierIMT();
+  assert.throws(
+    () => buildActionWitness({ mode: "append", noteTree, nullifierTree: imt, ownerKey: 1n, rho: 2n }),
+    /missing payloadCommit/,
+  );
+  assert.throws(
+    () =>
+      buildActionWitness({
+        mode: "explode",
+        noteTree,
+        nullifierTree: imt,
+        ownerKey: 1n,
+        rho: 2n,
+        payloadCommit: 3n,
+      }),
+    /unknown mode/,
+  );
+  // Mismatched explicit note rejected (circuit constrains note = Poseidon(opening)).
+  assert.throws(
+    () =>
+      buildActionWitness({
+        mode: "append",
+        noteTree,
+        nullifierTree: imt,
+        ownerKey: 1n,
+        rho: 2n,
+        payloadCommit: 3n,
+        note: 999n,
+      }),
+    /does not match/,
+  );
+  // noteIndex must point at a leaf matching the opening.
+  assert.throws(
+    () =>
+      buildActionWitness({
+        mode: "revoke",
+        noteTree,
+        nullifierTree: imt,
+        ownerKey: 1n,
+        rho: 2n,
+        payloadCommit: 3n,
+        noteIndex: 0,
+      }),
+    RangeError,
+  );
+});
+
+test("DOMAIN_REVOCATION is the contract constant", () => {
+  assert.equal(DOMAIN_REVOCATION, BigInt("0x656e69676d615f7265766f6b65"));
+  assert.equal(DOMAIN_REVOCATION.toString(), "8036215190653564882703377984357");
+  assert.ok(DOMAIN_REVOCATION < FIELD_R);
+});