enigma-memory 0.1.18 → 0.1.22

package/cortex-v3/zk/witness.mjs

@@ -0,0 +1,184 @@
+// witness.mjs — buildActionWitness: client-side snarkjs input for
+// circuits/action_transition.circom — ActionTransition(D=20).
+//
+// Binding spec: cortex-v3/zk/BUILD-CONTRACT.md v3 (sovereign per-action proofs).
+// RECONCILIATION POINT: circuits/action_transition.circom did not exist when
+// this file was written; every signal name below is taken VERBATIM from
+// BUILD-CONTRACT.md v3, so no name drift is expected. If the circuit diverges,
+// this file is the single place to reconcile.
+//
+// Public signals (exact order/names): oldNoteRoot, newNoteRoot, oldNullRoot,
+//   newNullRoot, nullifier, packed.
+// Private signals: isAppend, note, ownerKey, rho, payloadCommit,
+//   notePathElements[D], notePathIndices[D],
+//   noteMemPathElements[D], noteMemPathIndices[D],
+//   predValue, predNextIndex, predNextValue,
+//   predPathElements[D], predPathIndices[D],
+//   appendPathElements[D], appendPathIndices[D].
+//
+// packed = mode * 2^60 + actionIndex, where the ON-WIRE mode is 0=append,
+// 1=revoke (NOTE the inversion vs the circuit boolean: isAppend=1 ⇔ mode=0).
+// actionIndex = note_count (append) / null_count (revoke); null_count counts
+// the IMT genesis leaf, so an untouched IMT has null_count == 1 and the first
+// revocation appends at index 1.
+//
+// All field elements are emitted as DECIMAL STRINGS (snarkjs JSON convention).
+//
+// Mutation contract: APPEND mutates noteTree (inserts the note) and leaves
+// nullifierTree untouched; REVOKE mutates nullifierTree (IMT insert) and leaves
+// noteTree untouched. The emitted old* roots are the pre-mutation roots — build
+// the witness, then submit; on stale-root rejection rebuild against fresh state.
+
+import {
+  DOMAIN_REVOCATION,
+  NoteTree,
+  NullifierIMT,
+  TREE_DEPTH,
+  poseidon,
+} from "./zk-tree.mjs";
+
+const D = TREE_DEPTH;
+const ZERO_PATH_ELEMENTS = Object.freeze(Array.from({ length: D }, () => 0n));
+const ZERO_PATH_INDICES = Object.freeze(Array.from({ length: D }, () => 0));
+
+/** Recursively convert bigints → decimal strings for snarkjs input JSON. */
+function toDec(x) {
+  if (typeof x === "bigint") return x.toString(10);
+  if (Array.isArray(x)) return x.map(toDec);
+  if (typeof x === "number") return String(x);
+  if (typeof x === "object" && x !== null) {
+    return Object.fromEntries(Object.entries(x).map(([k, v]) => [k, toDec(v)]));
+  }
+  return x;
+}
+
+function need(value, name) {
+  if (value === undefined || value === null) throw new TypeError(`buildActionWitness: missing ${name}`);
+  return BigInt(value);
+}
+
+/**
+ * Build the snarkjs input for one sovereign action.
+ *
+ * @param {object} args
+ * @param {"append"|"revoke"} args.mode
+ * @param {NoteTree} args.noteTree        note tree at the current on-chain note_root
+ * @param {NullifierIMT} args.nullifierTree  IMT at the current on-chain null_root
+ * @param {bigint|number|string} args.ownerKey     note opening
+ * @param {bigint|number|string} args.rho          note opening
+ * @param {bigint|number|string} args.payloadCommit note opening
+ * @param {bigint|number|string} [args.note]       optional; asserted equal to
+ *        Poseidon([ownerKey, rho, payloadCommit]) when given
+ * @param {number} [args.noteIndex]  REVOKE only: index of the note in noteTree
+ * @returns {object} snarkjs input JSON (all values decimal strings)
+ */
+export function buildActionWitness(args) {
+  const { mode, noteTree, nullifierTree } = args;
+  if (!(noteTree instanceof NoteTree)) throw new TypeError("noteTree must be a NoteTree");
+  if (!(nullifierTree instanceof NullifierIMT)) {
+    throw new TypeError("nullifierTree must be a NullifierIMT");
+  }
+  const ownerKey = need(args.ownerKey, "ownerKey");
+  const rho = need(args.rho, "rho");
+  const payloadCommit = need(args.payloadCommit, "payloadCommit");
+  // Note well-formedness (enforced by the circuit in BOTH modes):
+  // note === Poseidon([ownerKey, rho, payloadCommit]).
+  const note = poseidon([ownerKey, rho, payloadCommit]);
+  if (args.note !== undefined && BigInt(args.note) !== note) {
+    throw new Error("provided note does not match Poseidon([ownerKey, rho, payloadCommit])");
+  }
+
+  const oldNoteRoot = noteTree.root();
+  const oldNullRoot = nullifierTree.root();
+
+  let isAppend;
+  let packedMode;
+  let actionIndex;
+  let nullifier;
+  let newNoteRoot;
+  let newNullRoot;
+  let notePathElements = ZERO_PATH_ELEMENTS;
+  let notePathIndices = ZERO_PATH_INDICES;
+  let noteMemPathElements = ZERO_PATH_ELEMENTS;
+  let noteMemPathIndices = ZERO_PATH_INDICES;
+  let predValue = 0n;
+  let predNextIndex = 0n;
+  let predNextValue = 0n;
+  let predPathElements = ZERO_PATH_ELEMENTS;
+  let predPathIndices = ZERO_PATH_INDICES;
+  let appendPathElements = ZERO_PATH_ELEMENTS;
+  let appendPathIndices = ZERO_PATH_INDICES;
+
+  if (mode === "append") {
+    isAppend = 1;
+    packedMode = 0n;
+    nullifier = 0n;
+    // actionIndex == on-chain note_count == next sequential insert index.
+    actionIndex = BigInt(noteTree.nextIndex);
+    const ins = noteTree.insert(note); // pre-insert zero-leaf proof, then mutate
+    notePathElements = ins.pathElements;
+    notePathIndices = ins.pathIndices;
+    newNoteRoot = noteTree.root();
+    newNullRoot = oldNullRoot; // constrained equal by the circuit
+  } else if (mode === "revoke") {
+    isAppend = 0;
+    packedMode = 1n;
+    const noteIndex = args.noteIndex;
+    if (!Number.isInteger(noteIndex) || noteIndex < 0 || noteIndex >= noteTree.nextIndex) {
+      throw new RangeError(`noteIndex ${noteIndex} not present in note tree`);
+    }
+    if (noteTree.leaves[noteIndex] !== note) {
+      throw new Error("note opening does not match the leaf at noteIndex");
+    }
+    // Membership of note in the note tree vs oldNoteRoot.
+    const mem = noteTree.getProof(noteIndex);
+    noteMemPathElements = mem.pathElements;
+    noteMemPathIndices = mem.pathIndices;
+    // Deterministic, epoch-independent, domain-separated nullifier:
+    // nf = Poseidon([DOMAIN_REVOCATION, ownerKey, rho]).
+    nullifier = poseidon([DOMAIN_REVOCATION, ownerKey, rho]);
+    // actionIndex == on-chain null_count == IMT sequential append index.
+    actionIndex = BigInt(nullifierTree.appendCounter);
+    const ins = nullifierTree.insert(nullifier); // throws on duplicate nf
+    predValue = ins.predecessorLeaf.value;
+    predNextIndex = ins.predecessorLeaf.nextIndex;
+    predNextValue = ins.predecessorLeaf.nextValue;
+    predPathElements = ins.predecessorPath.pathElements;
+    predPathIndices = ins.predecessorPath.pathIndices;
+    appendPathElements = ins.appendPath.pathElements;
+    appendPathIndices = ins.appendPath.pathIndices;
+    newNoteRoot = oldNoteRoot; // constrained equal by the circuit
+    newNullRoot = nullifierTree.root();
+  } else {
+    throw new Error(`unknown mode ${JSON.stringify(mode)} (expected "append" | "revoke")`);
+  }
+
+  const packed = packedMode * (1n << 60n) + actionIndex;
+
+  return toDec({
+    // public (exact contract order/names)
+    oldNoteRoot,
+    newNoteRoot,
+    oldNullRoot,
+    newNullRoot,
+    nullifier,
+    packed,
+    // private
+    isAppend,
+    note,
+    ownerKey,
+    rho,
+    payloadCommit,
+    notePathElements,
+    notePathIndices,
+    noteMemPathElements,
+    noteMemPathIndices,
+    predValue,
+    predNextIndex,
+    predNextValue,
+    predPathElements,
+    predPathIndices,
+    appendPathElements,
+    appendPathIndices,
+  });
+}

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

@@ -0,0 +1,232 @@
+/**
+ * zk-codec.mjs — snarkjs JSON → raw big-endian byte codec for the Enigma
+ * action-transition Groth16 verifier (Solana alt_bn128).
+ *
+ * Binding spec: cortex-v3/zk/BUILD-CONTRACT.md (v3).
+ *
+ * Conventions (BINDING):
+ *  - All G1 points: 64 bytes, x||y, each a 32-byte big-endian base-field (Fq)
+ *    element. Decimal strings in snarkjs JSON → 32B BE.
+ *  - All G2 points: 128 bytes. snarkjs JSON encodes each Fq2 coordinate as
+ *    [c0, c1] (real, imaginary). The alt_bn128 / EIP-196 precompile expects
+ *    (im, re) = (c1, c0). Default output order is therefore "c1c0"; the
+ *    `g2LimbOrder: "c0c1"` option exists for empirical on-chain resolution.
+ *  - Proof point A is passed through RAW — the on-chain program negates A.
+ *    NEVER negate here.
+ *  - Public inputs: 32B BE each, MUST be canonical (< Fr). Violation throws.
+ *  - Verifying key IC length MUST equal expectedIc (default 7 = ic[0] + 6
+ *    public inputs of ActionTransition).
+ */
+
+/** BN254 scalar field modulus r (Fr). */
+export const FR_MODULUS = BigInt(
+  "0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001",
+);
+
+/** BN254 base field modulus q (Fq, curve coordinates). */
+export const FQ_MODULUS = BigInt(
+  "0x30644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd47",
+);
+
+/** Number of public inputs of the ActionTransition circuit (v3 contract). */
+export const NUM_PUBLIC_INPUTS = 6;
+
+/** Expected IC length: ic[0] + NUM_PUBLIC_INPUTS. */
+export const EXPECTED_IC_LENGTH = NUM_PUBLIC_INPUTS + 1;
+
+const G1_BYTES = 64;
+const G2_BYTES = 128;
+const SCALAR_BYTES = 32;
+
+function parseJson(maybeJson, what) {
+  if (typeof maybeJson === "string") {
+    try {
+      return JSON.parse(maybeJson);
+    } catch (err) {
+      throw new Error(`zk-codec: ${what} is not valid JSON: ${err.message}`);
+    }
+  }
+  if (maybeJson === null || typeof maybeJson !== "object") {
+    throw new Error(`zk-codec: ${what} must be a JSON object or JSON string`);
+  }
+  return maybeJson;
+}
+
+function toBigIntDecimal(value, what) {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new Error(`zk-codec: ${what} is not a non-negative safe integer`);
+    }
+    return BigInt(value);
+  }
+  if (typeof value === "string") {
+    if (!/^(0|[1-9][0-9]*)$/.test(value)) {
+      throw new Error(`zk-codec: ${what} is not a canonical decimal string: ${JSON.stringify(value)}`);
+    }
+    return BigInt(value);
+  }
+  throw new Error(`zk-codec: ${what} has unsupported type ${typeof value}`);
+}
+
+/** Field element (canonical, < modulus) → 32-byte big-endian Buffer. */
+function fieldToBytes32BE(value, modulus, what) {
+  const n = toBigIntDecimal(value, what);
+  if (n < 0n || n >= modulus) {
+    throw new Error(
+      `zk-codec: ${what} is not canonical (must satisfy 0 <= value < ${modulus}); got ${n}`,
+    );
+  }
+  const buf = Buffer.alloc(SCALAR_BYTES);
+  let v = n;
+  for (let i = SCALAR_BYTES - 1; i >= 0; i--) {
+    buf[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return buf;
+}
+
+/** Scalar-field element (< Fr) → 32B BE. Throws on non-canonical input. */
+export function frToBytes32BE(value) {
+  return fieldToBytes32BE(value, FR_MODULUS, "Fr scalar");
+}
+
+/** Base-field element (< Fq) → 32B BE. Throws on non-canonical input. */
+export function fqToBytes32BE(value) {
+  return fieldToBytes32BE(value, FQ_MODULUS, "Fq coordinate");
+}
+
+function assertG1Shape(p, what) {
+  if (!Array.isArray(p) || p.length < 2) {
+    throw new Error(`zk-codec: ${what} must be an array [x, y, ...]`);
+  }
+}
+
+function assertG2Shape(p, what) {
+  if (
+    !Array.isArray(p) ||
+    p.length < 2 ||
+    !Array.isArray(p[0]) ||
+    p[0].length < 2 ||
+    !Array.isArray(p[1]) ||
+    p[1].length < 2
+  ) {
+    throw new Error(`zk-codec: ${what} must be [[x_c0, x_c1], [y_c0, y_c1], ...]`);
+  }
+}
+
+/** snarkjs G1 [x, y, ...] → 64B BE x||y. */
+export function g1ToBytes(point, what = "G1 point") {
+  assertG1Shape(point, what);
+  return Buffer.concat([
+    fqToBytes32BE(point[0]),
+    fqToBytes32BE(point[1]),
+  ]);
+}
+
+function normalizeG2LimbOrder(order) {
+  if (order === "c1c0" || order === "c0c1") return order;
+  throw new Error(`zk-codec: g2LimbOrder must be "c1c0" or "c0c1", got ${JSON.stringify(order)}`);
+}
+
+/**
+ * snarkjs G2 [[x_c0, x_c1], [y_c0, y_c1], ...] → 128B BE.
+ * g2LimbOrder "c1c0" (default, EIP-196/alt_bn128 (im,re)):
+ *   x_c1||x_c0||y_c1||y_c0
+ * g2LimbOrder "c0c1": x_c0||x_c1||y_c0||y_c1
+ */
+export function g2ToBytes(point, g2LimbOrder = "c1c0", what = "G2 point") {
+  normalizeG2LimbOrder(g2LimbOrder);
+  assertG2Shape(point, what);
+  const [xc0, xc1] = point[0];
+  const [yc0, yc1] = point[1];
+  const limbs =
+    g2LimbOrder === "c1c0"
+      ? [xc1, xc0, yc1, yc0]
+      : [xc0, xc1, yc0, yc1];
+  return Buffer.concat(limbs.map((l) => fqToBytes32BE(l)));
+}
+
+/**
+ * snarkjs verification_key.json → raw BE verifying key bytes.
+ *
+ * @param {object|string} vkJson parsed vk or JSON string.
+ * @param {object} [opts]
+ * @param {"c1c0"|"c0c1"} [opts.g2LimbOrder="c1c0"] G2 limb order (default c1c0
+ *   = alt_bn128/EIP-196 (im,re)).
+ * @param {number} [opts.expectedIc=7] required IC length (ic[0] + 6 public
+ *   inputs for ActionTransition). Throws on mismatch.
+ * @returns {{alphaG1: Buffer, betaG2: Buffer, gammaG2: Buffer, deltaG2: Buffer, ic: Buffer[]}}
+ *   alphaG1 64B; betaG2/gammaG2/deltaG2 128B; ic = expectedIc × 64B.
+ */
+export function vkFromSnarkjs(vkJson, opts = {}) {
+  const { g2LimbOrder = "c1c0", expectedIc = EXPECTED_IC_LENGTH } = opts;
+  normalizeG2LimbOrder(g2LimbOrder);
+  if (!Number.isInteger(expectedIc) || expectedIc < 1) {
+    throw new Error(`zk-codec: expectedIc must be a positive integer, got ${expectedIc}`);
+  }
+  const vk = parseJson(vkJson, "verification key");
+  for (const k of ["vk_alpha_1", "vk_beta_2", "vk_gamma_2", "vk_delta_2", "IC"]) {
+    if (!(k in vk)) throw new Error(`zk-codec: verification key missing field "${k}"`);
+  }
+  if (!Array.isArray(vk.IC)) {
+    throw new Error("zk-codec: verification key IC must be an array");
+  }
+  if (vk.IC.length !== expectedIc) {
+    throw new Error(
+      `zk-codec: verification key IC length ${vk.IC.length} != expected ${expectedIc} ` +
+        `(ic[0] + ${expectedIc - 1} public inputs)`,
+    );
+  }
+  return {
+    alphaG1: g1ToBytes(vk.vk_alpha_1, "vk_alpha_1"),
+    betaG2: g2ToBytes(vk.vk_beta_2, g2LimbOrder, "vk_beta_2"),
+    gammaG2: g2ToBytes(vk.vk_gamma_2, g2LimbOrder, "vk_gamma_2"),
+    deltaG2: g2ToBytes(vk.vk_delta_2, g2LimbOrder, "vk_delta_2"),
+    ic: vk.IC.map((p, i) => g1ToBytes(p, `IC[${i}]`)),
+  };
+}
+
+/**
+ * snarkjs proof.json → raw BE proof bytes for settle_epoch.
+ * A is passed through RAW — the on-chain program negates A. NEVER negate here.
+ *
+ * @param {object|string} proofJson parsed proof or JSON string.
+ * @param {object} [opts]
+ * @param {"c1c0"|"c0c1"} [opts.g2LimbOrder="c1c0"]
+ * @returns {{a: Buffer, b: Buffer, c: Buffer}} a 64B, b 128B, c 64B.
+ */
+export function proofFromSnarkjs(proofJson, opts = {}) {
+  const { g2LimbOrder = "c1c0" } = opts;
+  normalizeG2LimbOrder(g2LimbOrder);
+  const proof = parseJson(proofJson, "proof");
+  for (const k of ["pi_a", "pi_b", "pi_c"]) {
+    if (!(k in proof)) throw new Error(`zk-codec: proof missing field "${k}"`);
+  }
+  return {
+    a: g1ToBytes(proof.pi_a, "pi_a"),
+    b: g2ToBytes(proof.pi_b, g2LimbOrder, "pi_b"),
+    c: g1ToBytes(proof.pi_c, "pi_c"),
+  };
+}
+
+/**
+ * snarkjs public.json (array of decimal strings) → array of 32B BE buffers.
+ * Every element MUST be canonical (< Fr = r); non-canonical values throw.
+ *
+ * @param {Array<string|number|bigint>|string} publicJson parsed array or JSON string.
+ * @returns {Buffer[]} one 32-byte BE buffer per public input.
+ */
+export function publicInputsFromSnarkjs(publicJson) {
+  const arr = parseJson(publicJson, "public inputs");
+  if (!Array.isArray(arr)) {
+    throw new Error("zk-codec: public inputs must be an array of decimal strings");
+  }
+  return arr.map((v, i) => fieldToBytes32BE(v, FR_MODULUS, `public input [${i}]`));
+}
+
+export const BYTE_LENGTHS = Object.freeze({
+  G1: G1_BYTES,
+  G2: G2_BYTES,
+  SCALAR: SCALAR_BYTES,
+});