enigma-memory 0.1.18 → 0.1.22

package/cortex-v3/zk/settlement-evidence.mjs

@@ -0,0 +1,722 @@
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  sign,
+  verify,
+} from 'node:crypto';
+import { fork } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const GROTH16_CHILD_PATH = fileURLToPath(new URL('./groth16-verify-child.mjs', import.meta.url));
+
+export const ZK_SETTLEMENT_EVIDENCE_SCHEMA = 'enigma.zk_settlement_evidence.v1';
+export const ZK_SETTLEMENT_EVIDENCE_VERSION = 1;
+
+export const ZK_CIRCUIT_CONSTRAINTS = Object.freeze({
+  action_transition: 90_897,
+  sealed_sale_release: 87_422,
+});
+export const ZK_R1CS_PINS = Object.freeze({
+  action_transition: '558b99519e36fe94a0c7ffaed2cd5bb7865fc7387de42895e70dabba434c9656',
+  sealed_sale_release: '46e3d6846000005db1a11559604dcf5efbcefa263eed78b0aef7702de91b6830',
+});
+export const ZK_VERIFICATION_KEY_PINS = Object.freeze({
+  action_transition: Object.freeze({
+    path: fileURLToPath(new URL('./action-transition-vk.json', import.meta.url)),
+    sha256: 'eb5101b47236848b8e47b52a6f737888dbed86314ecc01767ef2faa7c4be6fff',
+  }),
+  sealed_sale_release: Object.freeze({
+    path: fileURLToPath(new URL('./sealed-sale-release-vk.json', import.meta.url)),
+    sha256: '3a4ec2fac884177960b3acec73941d23c16ca0d7f917edf598fbff1146f2c711',
+  }),
+});
+
+const EVENT_CIRCUITS = Object.freeze({
+  'action.append': 'action_transition',
+  'action.revoke': 'action_transition',
+  'sale.list': 'sealed_sale_release',
+  'sale.claim': null,
+  'sale.open': null,
+});
+
+const TX_EVENTS = new Set(['action.append', 'action.revoke', 'sale.list', 'sale.claim']);
+const PROOF_EVENTS = new Set(['action.append', 'action.revoke', 'sale.list']);
+const HEX_32_RE = /^[a-f0-9]{64}$/;
+const RECEIPT_REF_RE = /^zksettle_[a-f0-9]{64}$/;
+const PRIVATE_KEY_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+const PUBLIC_KEY_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const FORBIDDEN_KEY_RE = /(?:^|_)(?:witness|owner_key|ownerkey|rho|dek|buyer_secret|recipient_secret|secret_key|private_key|plaintext|content|prompt)(?:$|_)/iu;
+
+function canonicalize(value) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new TypeError('evidence numbers must be finite');
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new TypeError('evidence values must be JSON objects, arrays, or primitives');
+  }
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    if (value[key] === undefined) throw new TypeError(`evidence field ${key} must not be undefined`);
+    out[key] = canonicalize(value[key]);
+  }
+  return out;
+}
+
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function assertPublicSafe(value, path = 'evidence') {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertPublicSafe(entry, `${path}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  for (const [key, entry] of Object.entries(value)) {
+    const normalizedKey = key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+    if (FORBIDDEN_KEY_RE.test(normalizedKey)) {
+      throw new TypeError(`${path}.${key} is private witness material and cannot appear in public settlement evidence`);
+    }
+    assertPublicSafe(entry, `${path}.${key}`);
+  }
+}
+
+function hex(value, field, expectedBytes) {
+  const bytes = Buffer.isBuffer(value) || value instanceof Uint8Array
+    ? Buffer.from(value)
+    : typeof value === 'string' && /^(?:0x)?[a-f0-9]+$/i.test(value)
+      ? Buffer.from(value.replace(/^0x/i, ''), 'hex')
+      : null;
+  if (!bytes || bytes.length !== expectedBytes) {
+    throw new TypeError(`${field} must be exactly ${expectedBytes} bytes`);
+  }
+  return bytes.toString('hex');
+}
+
+function normalizeProof(proofBytes, publicInputs, circuit) {
+  if (!proofBytes) return null;
+  const proof = {
+    a: hex(proofBytes.a, 'proof.a', 64),
+    b: hex(proofBytes.b, 'proof.b', 128),
+    c: hex(proofBytes.c, 'proof.c', 64),
+  };
+  if (!Array.isArray(publicInputs)) throw new TypeError('publicInputs must be an array');
+  const publicInputsHex = publicInputs.map((value, index) => hex(value, `publicInputs[${index}]`, 32));
+  return {
+    algorithm: 'groth16-bn254',
+    encoding: 'enigma.groth16_raw_be.c1c0.v1',
+    a: proof.a,
+    b: proof.b,
+    c: proof.c,
+    digest: `sha256:${sha256(canonicalJson(proof))}`,
+    public_inputs: publicInputsHex,
+    circuit_artifact: {
+      r1cs_sha256: `sha256:${ZK_R1CS_PINS[circuit]}`,
+    },
+    verification_key: {
+      sha256: `sha256:${ZK_VERIFICATION_KEY_PINS[circuit].sha256}`,
+    },
+  };
+}
+
+function signingKeys(signerSecret) {
+  if (signerSecret === undefined || signerSecret === null || signerSecret === '') {
+    throw new TypeError('signerSecret is required');
+  }
+  const material = Buffer.isBuffer(signerSecret) || signerSecret instanceof Uint8Array
+    ? Buffer.from(signerSecret)
+    : Buffer.from(String(signerSecret), 'utf8');
+  const seed = createHash('sha256')
+    .update('enigma.zk.settlement.signer.v1\0', 'utf8')
+    .update(material)
+    .digest();
+  const privateKey = createPrivateKey({ key: Buffer.concat([PRIVATE_KEY_PREFIX, seed]), format: 'der', type: 'pkcs8' });
+  const publicDer = createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
+  const publicRaw = Buffer.from(publicDer).subarray(-32);
+  seed.fill(0);
+  material.fill(0);
+  return { privateKey, publicRaw };
+}
+
+function makeError(code, message) {
+  return { code, message };
+}
+
+function signerIsTrusted(signer, trustedSigners) {
+  const entries = trustedSigners instanceof Set
+    ? [...trustedSigners]
+    : Array.isArray(trustedSigners)
+      ? trustedSigners
+      : [];
+  return entries.some((entry) => {
+    if (typeof entry === 'string') {
+      return entry === signer?.public_key || entry === signer?.key_id || entry === signer?.signer_id;
+    }
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return false;
+    const anchors = [
+      ['public_key', signer?.public_key],
+      ['key_id', signer?.key_id],
+      ['signer_id', signer?.signer_id],
+    ].filter(([key]) => typeof entry[key] === 'string' && entry[key]);
+    return anchors.length > 0 && anchors.every(([key, value]) => entry[key] === value);
+  });
+}
+
+function finalizedCheckpointMatches(evidence, checkpoints) {
+  if (!Array.isArray(checkpoints)) return false;
+  return checkpoints.some((checkpoint) => (
+    checkpoint
+    && checkpoint.receipt_ref === evidence?.receipt_ref
+    && checkpoint.status === 'finalized'
+    && checkpoint.transaction_signature === (evidence?.transaction?.signature ?? null)
+    && checkpoint.program_id === evidence?.program_id
+    && checkpoint.cluster === evidence?.cluster
+    && checkpoint.state?.note_root === evidence?.state?.note_root
+    && checkpoint.state?.null_root === evidence?.state?.null_root
+    && checkpoint.state?.note_count === evidence?.state?.note_count
+    && checkpoint.state?.null_count === evidence?.state?.null_count
+  ));
+}
+
+export function createZkSettlementEvidence({
+  event,
+  programId,
+  cluster,
+  transactionSignature = null,
+  explorerUrl = null,
+  proofBytes = null,
+  publicInputs = [],
+  state,
+  signerSecret,
+  signerId = null,
+  predecessorRefs = [],
+  createdAt = new Date().toISOString(),
+}) {
+  if (!Object.hasOwn(EVENT_CIRCUITS, event)) throw new TypeError(`unsupported ZK settlement event: ${event}`);
+  if (typeof programId !== 'string' || !programId.trim()) throw new TypeError('programId is required');
+  if (typeof cluster !== 'string' || !cluster.trim()) throw new TypeError('cluster is required');
+  if (!state || typeof state !== 'object' || Array.isArray(state)) throw new TypeError('state must be a public JSON object');
+  assertPublicSafe(state, 'state');
+  if (!Array.isArray(predecessorRefs) || predecessorRefs.some((ref) => typeof ref !== 'string' || !RECEIPT_REF_RE.test(ref))) {
+    throw new TypeError('predecessorRefs must contain canonical ZK settlement receipt refs');
+  }
+  if (TX_EVENTS.has(event) && (typeof transactionSignature !== 'string' || !transactionSignature.trim())) {
+    throw new TypeError(`${event} evidence requires a transaction signature`);
+  }
+  const circuit = EVENT_CIRCUITS[event];
+  const proof = normalizeProof(proofBytes, publicInputs, circuit);
+  if (PROOF_EVENTS.has(event) && !proof) throw new TypeError(`${event} evidence requires proof bytes and public inputs`);
+  if (!PROOF_EVENTS.has(event) && proof) throw new TypeError(`${event} evidence must bind its proof through predecessor refs, not duplicate a witness-stage proof`);
+  if (proof && proof.public_inputs.length !== 6) throw new TypeError(`${event} evidence requires exactly 6 public inputs`);
+
+  const { privateKey, publicRaw } = signingKeys(signerSecret);
+  const body = {
+    schema: ZK_SETTLEMENT_EVIDENCE_SCHEMA,
+    version: ZK_SETTLEMENT_EVIDENCE_VERSION,
+    event,
+    circuit,
+    constraint_count: circuit ? ZK_CIRCUIT_CONSTRAINTS[circuit] : null,
+    program_id: programId.trim(),
+    cluster: cluster.trim(),
+    transaction: transactionSignature ? {
+      signature: transactionSignature.trim(),
+      explorer_url: typeof explorerUrl === 'string' && explorerUrl ? explorerUrl : null,
+    } : null,
+    proof,
+    state: canonicalize(state),
+    predecessor_refs: [...new Set(predecessorRefs)].sort(),
+    created_at: new Date(createdAt).toISOString(),
+    signer: {
+      algorithm: 'Ed25519',
+      public_key: publicRaw.toString('base64'),
+      key_id: `sha256:${sha256(publicRaw)}`,
+      signer_id: typeof signerId === 'string' && signerId ? signerId : null,
+      signer_domain: `${programId.trim()}:${cluster.trim()}`,
+    },
+  };
+  const signedBytes = Buffer.from(canonicalJson(body), 'utf8');
+  const receiptRef = `zksettle_${sha256(signedBytes)}`;
+  return {
+    ...body,
+    receipt_ref: receiptRef,
+    signature: sign(null, signedBytes, privateKey).toString('base64'),
+  };
+}
+function proofToSnarkjs(proof) {
+  const limb = (value, offset) => BigInt(`0x${value.slice(offset, offset + 64)}`).toString(10);
+  return {
+    pi_a: [limb(proof.a, 0), limb(proof.a, 64), '1'],
+    pi_b: [
+      [limb(proof.b, 64), limb(proof.b, 0)],
+      [limb(proof.b, 192), limb(proof.b, 128)],
+      ['1', '0'],
+    ],
+    pi_c: [limb(proof.c, 0), limb(proof.c, 64), '1'],
+    protocol: 'groth16',
+    curve: 'bn128',
+  };
+}
+
+async function loadPinnedVerificationKey(circuit, expectedHash, options) {
+  const pin = ZK_VERIFICATION_KEY_PINS[circuit];
+  if (!pin) throw new Error(`no pinned verification key for circuit ${circuit}`);
+  const path = options.verificationKeyPaths?.[circuit] ?? pin.path;
+  const raw = await readFile(path);
+  const actualHash = sha256(raw);
+  if (actualHash !== pin.sha256 || expectedHash !== `sha256:${pin.sha256}`) {
+    throw new Error(`verification key hash mismatch for ${circuit}: expected sha256:${pin.sha256}, got sha256:${actualHash}`);
+  }
+  const key = JSON.parse(raw.toString('utf8'));
+  if (key.protocol !== 'groth16' || key.curve !== 'bn128' || key.nPublic !== 6) {
+    throw new Error(`pinned verification key for ${circuit} has an invalid Groth16 contract`);
+  }
+  return key;
+}
+
+async function verifyGroth16Binding(evidence, options) {
+  const proof = evidence.proof;
+  const verificationKey = await loadPinnedVerificationKey(
+    evidence.circuit,
+    proof.verification_key?.sha256,
+    options,
+  );
+  const publicSignals = proof.public_inputs.map((value) => BigInt(`0x${value}`).toString(10));
+  const timeoutMs = Number.isSafeInteger(options.groth16TimeoutMs) && options.groth16TimeoutMs > 0
+    ? options.groth16TimeoutMs
+    : 30_000;
+  const child = fork(GROTH16_CHILD_PATH, [], {
+    stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+  });
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill();
+      fn(value);
+    };
+    const timer = setTimeout(
+      () => finish(reject, new Error(`snarkjs verification exceeded ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    child.once('message', (message) => {
+      if (message?.error) finish(reject, new Error(message.error));
+      else finish(resolve, message?.verified === true);
+    });
+    child.once('error', (error) => finish(reject, error));
+    child.once('exit', (code) => {
+      if (!settled) finish(reject, new Error(`snarkjs verifier child exited before returning a verdict (code ${code})`));
+    });
+    child.send({
+      verificationKey,
+      publicSignals,
+      proof: proofToSnarkjs(proof),
+    });
+  });
+}
+
+export { proofToSnarkjs };
+
+
+export async function verifyZkSettlementEvidence(evidence, options = {}) {
+  let proofValid = PROOF_EVENTS.has(evidence?.event) ? false : null;
+  const errors = [];
+  if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence)) {
+    return { ok: false, verified: false, proof_valid: null, settlement_verified: false, receipt_ref: null, event: null, errors: [makeError('ZK_EVIDENCE_INVALID', 'Evidence must be a JSON object.')] };
+  }
+  try {
+    assertPublicSafe(evidence, 'evidence');
+    if (evidence.schema !== ZK_SETTLEMENT_EVIDENCE_SCHEMA || evidence.version !== ZK_SETTLEMENT_EVIDENCE_VERSION) {
+      errors.push(makeError('ZK_EVIDENCE_SCHEMA_INVALID', 'Unsupported ZK settlement evidence schema or version.'));
+    }
+    if (!Object.hasOwn(EVENT_CIRCUITS, evidence.event)) {
+      errors.push(makeError('ZK_EVIDENCE_EVENT_INVALID', 'Unsupported ZK settlement event.'));
+    } else {
+      const circuit = EVENT_CIRCUITS[evidence.event];
+      if (evidence.circuit !== circuit || evidence.constraint_count !== (circuit ? ZK_CIRCUIT_CONSTRAINTS[circuit] : null)) {
+        errors.push(makeError('ZK_EVIDENCE_CIRCUIT_INVALID', 'Circuit or constraint label does not match the settlement event.'));
+      }
+      if (TX_EVENTS.has(evidence.event) && !evidence.transaction?.signature) {
+        errors.push(makeError('ZK_EVIDENCE_TX_MISSING', 'Settlement transaction signature is missing.'));
+      }
+      if (PROOF_EVENTS.has(evidence.event)) {
+        const rawProof = {
+          a: evidence.proof?.a,
+          b: evidence.proof?.b,
+          c: evidence.proof?.c,
+        };
+        const rawProofValid = /^[a-f0-9]{128}$/.test(rawProof.a ?? '')
+          && /^[a-f0-9]{256}$/.test(rawProof.b ?? '')
+          && /^[a-f0-9]{128}$/.test(rawProof.c ?? '');
+        const digestValid = rawProofValid
+          && evidence.proof?.digest === `sha256:${sha256(canonicalJson(rawProof))}`;
+        const pin = ZK_VERIFICATION_KEY_PINS[circuit];
+        if (
+          evidence.proof?.algorithm !== 'groth16-bn254'
+          || evidence.proof?.encoding !== 'enigma.groth16_raw_be.c1c0.v1'
+          || !digestValid
+          || evidence.proof?.verification_key?.sha256 !== `sha256:${pin?.sha256 ?? ''}`
+          || !Array.isArray(evidence.proof?.public_inputs)
+          || evidence.proof.public_inputs.length !== 6
+          || evidence.proof.public_inputs.some((value) => !HEX_32_RE.test(value))
+          || evidence.proof?.circuit_artifact?.r1cs_sha256 !== `sha256:${ZK_R1CS_PINS[circuit] ?? ''}`
+        ) {
+          errors.push(makeError('ZK_EVIDENCE_PROOF_INVALID', 'Canonical Groth16 proof, verification-key pin, or public inputs are invalid.'));
+        }
+      } else if (evidence.proof !== null) {
+        errors.push(makeError('ZK_EVIDENCE_PROOF_UNEXPECTED', 'Non-proving lifecycle events must reference predecessor evidence instead of embedding a proof binding.'));
+      }
+    }
+    if (typeof options.expectedProgramId !== 'string' || !options.expectedProgramId) {
+      errors.push(makeError('ZK_EVIDENCE_TRUST_REQUIRED', 'Verification requires an expectedProgramId trust anchor.'));
+    } else if (evidence.program_id !== options.expectedProgramId) {
+      errors.push(makeError('ZK_EVIDENCE_PROGRAM_MISMATCH', 'Evidence program_id does not match the trusted program.'));
+    }
+    if (typeof options.expectedCluster !== 'string' || !options.expectedCluster) {
+      errors.push(makeError('ZK_EVIDENCE_TRUST_REQUIRED', 'Verification requires an expectedCluster trust anchor.'));
+    } else if (evidence.cluster !== options.expectedCluster) {
+      errors.push(makeError('ZK_EVIDENCE_CLUSTER_MISMATCH', 'Evidence cluster does not match the trusted cluster.'));
+    }
+    if (!signerIsTrusted(evidence.signer, options.trustedSigners)) {
+      errors.push(makeError('ZK_EVIDENCE_SIGNER_UNTRUSTED', 'Evidence signer is not present in the trusted signer registry.'));
+    }
+    if (evidence.signer?.signer_domain !== `${evidence.program_id}:${evidence.cluster}`) {
+      errors.push(makeError('ZK_EVIDENCE_SIGNER_DOMAIN_INVALID', 'Evidence signer domain is not bound to program_id and cluster.'));
+    }
+    if (!finalizedCheckpointMatches(evidence, options.finalizedCheckpoints)) {
+      errors.push(makeError('ZK_EVIDENCE_FINALITY_UNTRUSTED', 'Evidence is not bound to a trusted finalized checkpoint.'));
+    }
+    if (!evidence.state || !HEX_32_RE.test(evidence.state.note_root ?? '') || !HEX_32_RE.test(evidence.state.null_root ?? '')) {
+      errors.push(makeError('ZK_EVIDENCE_STATE_INVALID', 'Evidence must bind canonical 32-byte note_root and null_root values.'));
+    }
+    const inputs = evidence.proof?.public_inputs;
+    if (Array.isArray(inputs) && inputs.length === 6) {
+      if (evidence.event === 'action.append' || evidence.event === 'action.revoke') {
+        const append = evidence.event === 'action.append';
+        const packed = HEX_32_RE.test(inputs[5] ?? '') ? BigInt(`0x${inputs[5]}`) : -1n;
+        const mode = packed >= 0n ? Number(packed >> 60n) : -1;
+        const state = evidence.state ?? {};
+        const countFieldsValid = [
+          state.note_count,
+          state.null_count,
+          state.previous_note_count,
+          state.previous_null_count,
+        ].every((value) => Number.isSafeInteger(value) && value >= 0);
+        const rootsValid = state.note_root === inputs[1]
+          && state.null_root === inputs[3]
+          && state.previous_note_root === inputs[0]
+          && state.previous_null_root === inputs[2];
+        const modeValid = mode === (append ? 0 : 1);
+        const nullifierValid = append
+          ? inputs[4] === '0'.repeat(64)
+          : HEX_32_RE.test(inputs[4] ?? '') && inputs[4] !== '0'.repeat(64);
+        const invariantValid = append
+          ? inputs[2] === inputs[3]
+            && state.note_count === state.previous_note_count + 1
+            && state.null_count === state.previous_null_count
+          : inputs[0] === inputs[1]
+            && state.note_count === state.previous_note_count
+            && state.null_count === state.previous_null_count + 1;
+        if (!rootsValid || !modeValid || !nullifierValid || !countFieldsValid || !invariantValid) {
+          errors.push(makeError('ZK_EVIDENCE_ACTION_TRANSITION_INVALID', 'Action label, packed mode, roots, or count transition is inconsistent with the proof public inputs.'));
+        }
+      } else if (evidence.event === 'sale.list') {
+        const saleBindings = [
+          ['note_root', 0],
+          ['payload_commit_pos', 1],
+          ['cipher_commit', 2],
+          ['key_commit', 3],
+          ['sale_terms_hash', 4],
+          ['envelope_commit', 5],
+        ];
+        if (saleBindings.some(([field, index]) => evidence.state?.[field] !== inputs[index])) {
+          errors.push(makeError('ZK_EVIDENCE_STATE_BINDING_INVALID', 'Sale state commitments do not match the proof public inputs.'));
+        }
+      }
+    }
+    if (!Array.isArray(evidence.predecessor_refs) || evidence.predecessor_refs.some((ref) => !RECEIPT_REF_RE.test(ref))) {
+      errors.push(makeError('ZK_EVIDENCE_PREDECESSOR_INVALID', 'predecessor_refs contains an invalid receipt reference.'));
+    }
+
+    const { receipt_ref: receiptRef, signature, ...body } = evidence;
+    const signedBytes = Buffer.from(canonicalJson(body), 'utf8');
+    const expectedRef = `zksettle_${sha256(signedBytes)}`;
+    if (!RECEIPT_REF_RE.test(receiptRef ?? '') || receiptRef !== expectedRef) {
+      errors.push(makeError('ZK_EVIDENCE_REF_INVALID', 'receipt_ref does not match the canonical signed evidence body.'));
+    }
+    const publicRaw = Buffer.from(evidence.signer?.public_key ?? '', 'base64');
+    if (evidence.signer?.algorithm !== 'Ed25519' || publicRaw.length !== 32 || evidence.signer?.key_id !== `sha256:${sha256(publicRaw)}`) {
+      errors.push(makeError('ZK_EVIDENCE_SIGNER_INVALID', 'Evidence signer metadata is invalid.'));
+    } else {
+      const publicKey = createPublicKey({ key: Buffer.concat([PUBLIC_KEY_PREFIX, publicRaw]), format: 'der', type: 'spki' });
+      let signatureBytes = null;
+      try {
+        signatureBytes = Buffer.from(signature, 'base64');
+      } catch { /* handled below */ }
+      if (!signatureBytes || signatureBytes.length !== 64 || !verify(null, signedBytes, publicKey, signatureBytes)) {
+        errors.push(makeError('ZK_EVIDENCE_SIGNATURE_INVALID', 'Ed25519 evidence signature did not verify.'));
+      }
+    }
+    if (
+      PROOF_EVENTS.has(evidence.event)
+      && !errors.some((error) => error.code === 'ZK_EVIDENCE_PROOF_INVALID')
+    ) {
+      try {
+        const proofVerified = await verifyGroth16Binding(evidence, options);
+        proofValid = proofVerified === true;
+        if (!proofVerified) {
+          errors.push(makeError('ZK_EVIDENCE_GROTH16_INVALID', 'snarkjs rejected the Groth16 proof against the pinned verification key.'));
+        }
+      } catch (error) {
+        proofValid = false;
+        errors.push(makeError('ZK_EVIDENCE_GROTH16_INVALID', `Offline Groth16 verification failed closed: ${error.message}`));
+      }
+    }
+    if (errors.length === 0 && options.seenRefs instanceof Set) {
+      if (options.seenRefs.has(receiptRef)) {
+        errors.push(makeError('ZK_EVIDENCE_REPLAY', `Receipt ${receiptRef} was already verified in this replay domain.`));
+      } else {
+        options.seenRefs.add(receiptRef);
+      }
+    }
+  } catch (error) {
+    errors.push(makeError('ZK_EVIDENCE_INVALID', error.message));
+  }
+  const settlementVerified = errors.length === 0;
+  return {
+    ok: settlementVerified,
+    verified: settlementVerified,
+    proof_valid: proofValid,
+    settlement_verified: settlementVerified,
+    receipt_ref: typeof evidence.receipt_ref === 'string' ? evidence.receipt_ref : null,
+    event: typeof evidence.event === 'string' ? evidence.event : null,
+    errors,
+  };
+}
+
+export function validateZkSettlementEvidence(evidence, options = {}) {
+  const errors = [];
+  if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence)) {
+    return { ok: false, preflight_valid: false, proof_valid: null, settlement_verified: false, receipt_ref: null, event: null, errors: [makeError('ZK_EVIDENCE_INVALID', 'Evidence must be a JSON object.')] };
+  }
+  try {
+    assertPublicSafe(evidence, 'evidence');
+    const circuit = EVENT_CIRCUITS[evidence.event];
+    if (evidence.schema !== ZK_SETTLEMENT_EVIDENCE_SCHEMA || evidence.version !== ZK_SETTLEMENT_EVIDENCE_VERSION) {
+      errors.push(makeError('ZK_EVIDENCE_SCHEMA_INVALID', 'Unsupported ZK settlement evidence schema or version.'));
+    }
+    if (!Object.hasOwn(EVENT_CIRCUITS, evidence.event)) {
+      errors.push(makeError('ZK_EVIDENCE_EVENT_INVALID', 'Unsupported ZK settlement event.'));
+    } else if (evidence.circuit !== circuit || evidence.constraint_count !== (circuit ? ZK_CIRCUIT_CONSTRAINTS[circuit] : null)) {
+      errors.push(makeError('ZK_EVIDENCE_CIRCUIT_INVALID', 'Circuit or constraint label does not match the settlement event.'));
+    }
+    if (TX_EVENTS.has(evidence.event) && !evidence.transaction?.signature) {
+      errors.push(makeError('ZK_EVIDENCE_TX_MISSING', 'Settlement transaction signature is missing.'));
+    }
+    const inputs = evidence.proof?.public_inputs;
+    if (PROOF_EVENTS.has(evidence.event)) {
+      const rawProof = { a: evidence.proof?.a, b: evidence.proof?.b, c: evidence.proof?.c };
+      const rawProofValid = /^[a-f0-9]{128}$/.test(rawProof.a ?? '')
+        && /^[a-f0-9]{256}$/.test(rawProof.b ?? '')
+        && /^[a-f0-9]{128}$/.test(rawProof.c ?? '');
+      const pin = ZK_VERIFICATION_KEY_PINS[circuit];
+      if (
+        evidence.proof?.algorithm !== 'groth16-bn254'
+        || evidence.proof?.encoding !== 'enigma.groth16_raw_be.c1c0.v1'
+        || !rawProofValid
+        || evidence.proof?.digest !== `sha256:${sha256(canonicalJson(rawProof))}`
+        || evidence.proof?.verification_key?.sha256 !== `sha256:${pin?.sha256 ?? ''}`
+        || evidence.proof?.circuit_artifact?.r1cs_sha256 !== `sha256:${ZK_R1CS_PINS[circuit] ?? ''}`
+        || !Array.isArray(inputs)
+        || inputs.length !== 6
+        || inputs.some((value) => !HEX_32_RE.test(value))
+      ) {
+        errors.push(makeError('ZK_EVIDENCE_PROOF_INVALID', 'Canonical Groth16 proof, verification-key pin, or public inputs are invalid.'));
+      }
+    } else if (evidence.proof !== null) {
+      errors.push(makeError('ZK_EVIDENCE_PROOF_UNEXPECTED', 'Non-proving lifecycle events must reference predecessor evidence.'));
+    }
+    if (!options.expectedProgramId) {
+      errors.push(makeError('ZK_EVIDENCE_TRUST_REQUIRED', 'Verification requires an expectedProgramId trust anchor.'));
+    } else if (evidence.program_id !== options.expectedProgramId) {
+      errors.push(makeError('ZK_EVIDENCE_PROGRAM_MISMATCH', 'Evidence program_id does not match the trusted program.'));
+    }
+    if (!options.expectedCluster) {
+      errors.push(makeError('ZK_EVIDENCE_TRUST_REQUIRED', 'Verification requires an expectedCluster trust anchor.'));
+    } else if (evidence.cluster !== options.expectedCluster) {
+      errors.push(makeError('ZK_EVIDENCE_CLUSTER_MISMATCH', 'Evidence cluster does not match the trusted cluster.'));
+    }
+    if (!signerIsTrusted(evidence.signer, options.trustedSigners)) {
+      errors.push(makeError('ZK_EVIDENCE_SIGNER_UNTRUSTED', 'Evidence signer is not present in the trusted signer registry.'));
+    }
+    if (evidence.signer?.signer_domain !== `${evidence.program_id}:${evidence.cluster}`) {
+      errors.push(makeError('ZK_EVIDENCE_SIGNER_DOMAIN_INVALID', 'Evidence signer domain is not bound to program_id and cluster.'));
+    }
+    if (!finalizedCheckpointMatches(evidence, options.finalizedCheckpoints)) {
+      errors.push(makeError('ZK_EVIDENCE_FINALITY_UNTRUSTED', 'Evidence is not bound to a trusted finalized checkpoint.'));
+    }
+    if (!evidence.state || !HEX_32_RE.test(evidence.state.note_root ?? '') || !HEX_32_RE.test(evidence.state.null_root ?? '')) {
+      errors.push(makeError('ZK_EVIDENCE_STATE_INVALID', 'Evidence must bind canonical note_root and null_root values.'));
+    }
+    if (Array.isArray(inputs) && inputs.length === 6 && (evidence.event === 'action.append' || evidence.event === 'action.revoke')) {
+      const append = evidence.event === 'action.append';
+      const state = evidence.state ?? {};
+      const mode = Number(BigInt(`0x${inputs[5]}`) >> 60n);
+      const countsValid = [state.note_count, state.null_count, state.previous_note_count, state.previous_null_count]
+        .every((value) => Number.isSafeInteger(value) && value >= 0);
+      const transitionValid = state.note_root === inputs[1]
+        && state.null_root === inputs[3]
+        && state.previous_note_root === inputs[0]
+        && state.previous_null_root === inputs[2]
+        && mode === (append ? 0 : 1)
+        && (append ? inputs[4] === '0'.repeat(64) : inputs[4] !== '0'.repeat(64))
+        && (append
+          ? inputs[2] === inputs[3] && state.note_count === state.previous_note_count + 1 && state.null_count === state.previous_null_count
+          : inputs[0] === inputs[1] && state.note_count === state.previous_note_count && state.null_count === state.previous_null_count + 1);
+      if (!countsValid || !transitionValid) {
+        errors.push(makeError('ZK_EVIDENCE_ACTION_TRANSITION_INVALID', 'Action label, packed mode, nullifier, roots, or count transition is invalid.'));
+      }
+    } else if (Array.isArray(inputs) && inputs.length === 6 && evidence.event === 'sale.list') {
+      const bindings = [['note_root', 0], ['payload_commit_pos', 1], ['cipher_commit', 2], ['key_commit', 3], ['sale_terms_hash', 4], ['envelope_commit', 5]];
+      if (bindings.some(([field, index]) => evidence.state?.[field] !== inputs[index])) {
+        errors.push(makeError('ZK_EVIDENCE_STATE_BINDING_INVALID', 'Sale state commitments do not match proof public inputs.'));
+      }
+    }
+    if (!Array.isArray(evidence.predecessor_refs) || evidence.predecessor_refs.some((ref) => !RECEIPT_REF_RE.test(ref))) {
+      errors.push(makeError('ZK_EVIDENCE_PREDECESSOR_INVALID', 'predecessor_refs contains an invalid receipt reference.'));
+    }
+    const { receipt_ref: receiptRef, signature, ...body } = evidence;
+    const signedBytes = Buffer.from(canonicalJson(body), 'utf8');
+    if (receiptRef !== `zksettle_${sha256(signedBytes)}`) {
+      errors.push(makeError('ZK_EVIDENCE_REF_INVALID', 'receipt_ref does not match the canonical signed body.'));
+    }
+    const publicRaw = Buffer.from(evidence.signer?.public_key ?? '', 'base64');
+    if (
+      evidence.signer?.algorithm !== 'Ed25519'
+      || publicRaw.length !== 32
+      || evidence.signer?.key_id !== `sha256:${sha256(publicRaw)}`
+    ) {
+      errors.push(makeError('ZK_EVIDENCE_SIGNER_INVALID', 'Evidence signer metadata is invalid.'));
+    } else {
+      const publicKey = createPublicKey({ key: Buffer.concat([PUBLIC_KEY_PREFIX, publicRaw]), format: 'der', type: 'spki' });
+      const signatureBytes = Buffer.from(signature ?? '', 'base64');
+      if (signatureBytes.length !== 64 || !verify(null, signedBytes, publicKey, signatureBytes)) {
+        errors.push(makeError('ZK_EVIDENCE_SIGNATURE_INVALID', 'Ed25519 evidence signature did not verify.'));
+      }
+    }
+  } catch (error) {
+    errors.push(makeError('ZK_EVIDENCE_INVALID', error.message));
+  }
+  const valid = errors.length === 0;
+  return {
+    ok: valid,
+    preflight_valid: valid,
+    proof_valid: null,
+    settlement_verified: false,
+    receipt_ref: evidence.receipt_ref ?? null,
+    event: evidence.event ?? null,
+    errors,
+  };
+}
+
+export function validateZkSettlementEvidenceGraph(receipts) {
+  const errors = [];
+  if (!Array.isArray(receipts)) {
+    return { ok: false, errors: [makeError('ZK_GRAPH_INVALID', 'Settlement evidence graph must be an ordered array.')] };
+  }
+  const earlier = new Map();
+  const transactionKeys = new Set();
+  const proofKeys = new Set();
+  const requiredPredecessor = {
+    'sale.list': 'action.append',
+    'sale.claim': 'sale.list',
+    'sale.open': 'sale.claim',
+  };
+  const stateFields = ['note_root', 'null_root', 'note_count', 'null_count'];
+  const saleFields = ['sale_terms_hash', 'key_commit', 'envelope_commit', 'sale_receipt_pda'];
+
+  for (const evidence of receipts) {
+    const ref = evidence?.receipt_ref;
+    if (typeof ref !== 'string' || earlier.has(ref)) {
+      errors.push(makeError('ZK_GRAPH_DUPLICATE_REF', `Duplicate or invalid receipt_ref ${String(ref)}.`));
+      continue;
+    }
+    const transactionKey = evidence.transaction?.signature;
+    if (transactionKey) {
+      if (transactionKeys.has(transactionKey)) {
+        errors.push(makeError('ZK_GRAPH_TRANSACTION_REPLAY', `Transaction signature ${transactionKey} is reused.`));
+      }
+      transactionKeys.add(transactionKey);
+    }
+    if (evidence.proof) {
+      const proofKey = canonicalJson({
+        circuit: evidence.circuit,
+        digest: evidence.proof.digest,
+        public_inputs: evidence.proof.public_inputs,
+      });
+      if (proofKeys.has(proofKey)) {
+        errors.push(makeError('ZK_GRAPH_PROOF_REPLAY', `Circuit/proof/public-input tuple is reused by ${ref}.`));
+      }
+      proofKeys.add(proofKey);
+    }
+
+    const refs = Array.isArray(evidence.predecessor_refs) ? evidence.predecessor_refs : [];
+    const expectedEvent = requiredPredecessor[evidence.event];
+    if (expectedEvent && refs.length !== 1) {
+      errors.push(makeError('ZK_GRAPH_LINEAGE_REQUIRED', `${evidence.event} requires exactly one ${expectedEvent} predecessor.`));
+    } else if ((evidence.event === 'action.append' || evidence.event === 'action.revoke') && refs.length > 1) {
+      errors.push(makeError('ZK_GRAPH_LINEAGE_INVALID', `${evidence.event} accepts at most one prior action predecessor.`));
+    }
+
+    for (const predecessorRef of refs) {
+      const predecessor = earlier.get(predecessorRef);
+      if (!predecessor) {
+        errors.push(makeError('ZK_GRAPH_PREDECESSOR_ORDER', `Predecessor ${predecessorRef} is missing or does not appear earlier.`));
+        continue;
+      }
+      const compatible = expectedEvent
+        ? predecessor.event === expectedEvent
+        : (evidence.event === 'action.append' || evidence.event === 'action.revoke')
+          && (predecessor.event === 'action.append' || predecessor.event === 'action.revoke');
+      if (!compatible) {
+        errors.push(makeError('ZK_GRAPH_EVENT_INVALID', `${evidence.event} cannot descend from ${predecessor.event}.`));
+      }
+      if (
+        evidence.program_id !== predecessor.program_id
+        || evidence.cluster !== predecessor.cluster
+        || evidence.signer?.signer_domain !== predecessor.signer?.signer_domain
+      ) {
+        errors.push(makeError('ZK_GRAPH_DOMAIN_MISMATCH', 'Lineage must remain in one program, cluster, and signer trust domain.'));
+      }
+      if (evidence.event === 'action.append' || evidence.event === 'action.revoke') {
+        const continuous = predecessor.state?.note_root === evidence.state?.previous_note_root
+          && predecessor.state?.null_root === evidence.state?.previous_null_root
+          && predecessor.state?.note_count === evidence.state?.previous_note_count
+          && predecessor.state?.null_count === evidence.state?.previous_null_count;
+        if (!continuous) errors.push(makeError('ZK_GRAPH_STATE_MISMATCH', 'Action predecessor does not reach the child input state.'));
+      } else {
+        if (!stateFields.every((field) => predecessor.state?.[field] === evidence.state?.[field])) {
+          errors.push(makeError('ZK_GRAPH_STATE_MISMATCH', `${predecessor.event} state does not continue into ${evidence.event}.`));
+        }
+        if (
+          (evidence.event === 'sale.claim' || evidence.event === 'sale.open')
+          && !saleFields.every((field) => predecessor.state?.[field] === evidence.state?.[field])
+        ) {
+          errors.push(makeError('ZK_GRAPH_SALE_MISMATCH', `Sale commitments changed between ${predecessor.event} and ${evidence.event}.`));
+        }
+      }
+    }
+    earlier.set(ref, evidence);
+  }
+  return { ok: errors.length === 0, errors };
+}