enigma-memory 0.1.18 → 0.1.22

package/apps/verifier/bin/enigma-verify.mjs

@@ -1,13 +1,24 @@
 #!/usr/bin/env node
+import { fork } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
 import { realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
   verifyReceipt,
   verifyReceiptChain,
   verifyCheckpoint,
 } from '../../../packages/core/src/index.js';
-
+import { verifyMemoryReceipt } from '../../../packages/vault/src/receipt.js';
+import {
+  ZK_SETTLEMENT_EVIDENCE_SCHEMA,
+  ZK_VERIFICATION_KEY_PINS,
+  proofToSnarkjs,
+  validateZkSettlementEvidence,
+  validateZkSettlementEvidenceGraph,
+  verifyZkSettlementEvidence,
+} from '../../../cortex-v3/zk/settlement-evidence.mjs';
 function json(value) {
   return JSON.stringify(value, null, 2);
 }
@@ -123,12 +134,184 @@ function compareCommittedSequence(receipts, committed, errors) {
     }));
   }
 }
+function zkReceiptsFromBundle(bundle) {
+  return asArray(
+    bundle?.zk_receipts
+      ?? bundle?.zkSettlementReceipts
+      ?? bundle?.settlementReceipts
+      ?? (bundle?.settlementReceipt ? [bundle.settlementReceipt] : []),
+  );
+}
+
+// A bundle is an offline artifact, not a streaming proof service. Capping it at
+// 64 receipts bounds CPU time, child-process lifetime, replay state, and parsed
+// verification-key retention while remaining well above normal lifecycle size.
+export const MAX_ZK_SETTLEMENT_RECEIPTS = 64;
+
+const GROTH16_PROOF_EVENTS = new Set(['action.append', 'action.revoke', 'sale.list']);
+const verificationKeyCache = new Map();
+const MAX_VERIFICATION_KEY_CACHE_ITEMS = 16;
+const GROTH16_WORKER_ARG = '--enigma-groth16-worker';
+const IS_GROTH16_WORKER = process.argv[2] === GROTH16_WORKER_ARG;
+
+function emitInstrumentation(options, event, details = {}) {
+  const callback = options?.instrumentation?.[event];
+  if (typeof callback === 'function') callback(details);
+}
+
+async function loadVerificationKey(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 cacheKey = `${circuit}\0${String(path)}`;
+  let pending = verificationKeyCache.get(cacheKey);
+  if (!pending) {
+    pending = (async () => {
+      emitInstrumentation(options, 'verificationKeyLoad', { circuit, path: String(path) });
+      const raw = await readFile(path);
+      const actualHash = createHash('sha256').update(raw).digest('hex');
+      if (actualHash !== 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;
+    })();
+    if (verificationKeyCache.size >= MAX_VERIFICATION_KEY_CACHE_ITEMS) {
+      verificationKeyCache.delete(verificationKeyCache.keys().next().value);
+    }
+    verificationKeyCache.set(cacheKey, pending);
+    pending.catch(() => {
+      if (verificationKeyCache.get(cacheKey) === pending) verificationKeyCache.delete(cacheKey);
+    });
+  }
+  const key = await pending;
+  if (expectedHash !== `sha256:${pin.sha256}`) {
+    throw new Error(`verification key pin mismatch for ${circuit}`);
+  }
+  return key;
+}
+
+class Groth16VerifierWorker {
+  constructor(options) {
+    this.options = options;
+    this.child = null;
+    this.pending = null;
+    this.nextRequestId = 1;
+    this.closed = false;
+  }
 
+  ensureChild() {
+    if (this.closed) throw new Error('Groth16 verifier worker is closed');
+    if (this.child) return;
+    const child = fork(fileURLToPath(import.meta.url), [GROTH16_WORKER_ARG], {
+      stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+    });
+    this.child = child;
+    emitInstrumentation(this.options, 'workerSpawn', {});
+    child.on('message', (message) => {
+      if (!this.pending || message?.id !== this.pending.id) return;
+      if (message.error) this.finishPending(new Error(message.error));
+      else this.finishPending(null, message.verified === true);
+    });
+    child.on('error', (error) => this.failChild(error));
+    child.on('exit', (code, signal) => {
+      if (this.child === child) this.child = null;
+      if (this.pending) {
+        this.finishPending(new Error(`snarkjs verifier child exited before returning a verdict (code ${code}, signal ${signal ?? 'none'})`));
+      }
+    });
+  }
+
+  finishPending(error, result) {
+    const pending = this.pending;
+    if (!pending) return;
+    this.pending = null;
+    clearTimeout(pending.timer);
+    if (error) pending.reject(error);
+    else pending.resolve(result);
+  }
+
+  failChild(error) {
+    const child = this.child;
+    this.child = null;
+    if (child && !child.killed) child.kill('SIGKILL');
+    this.finishPending(error);
+  }
+
+  async verify(request, timeoutMs) {
+    if (this.pending) throw new Error('Groth16 verifier worker received overlapping requests');
+    this.ensureChild();
+    const id = this.nextRequestId++;
+    emitInstrumentation(this.options, 'proofCheck', { circuit: request.circuit, receiptRef: request.receiptRef });
+    return await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const error = new Error(`snarkjs verification exceeded ${timeoutMs}ms`);
+        this.failChild(error);
+      }, timeoutMs);
+      this.pending = { id, timer, resolve, reject };
+      this.child.send({
+        id,
+        verificationKey: request.verificationKey,
+        publicSignals: request.publicSignals,
+        proof: request.proof,
+      }, (error) => {
+        if (error) this.failChild(error);
+      });
+    });
+  }
 
+  async close() {
+    this.closed = true;
+    const child = this.child;
+    this.child = null;
+    if (!child) return;
+    if (this.pending) this.finishPending(new Error('Groth16 verifier worker closed with a pending request'));
+    await new Promise((resolve) => {
+      let settled = false;
+      let forceTimer;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(forceTimer);
+        resolve();
+      };
+      forceTimer = setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch {}
+        finish();
+      }, 1_000);
+      child.once('exit', finish);
+      child.kill();
+    });
+  }
+}
 
+function startGroth16Worker() {
+  const require = createRequire(import.meta.url);
+  const snarkjs = require('snarkjs');
+  let queue = Promise.resolve();
+  process.on('message', (request) => {
+    queue = queue.then(async () => {
+      try {
+        const verified = await snarkjs.groth16.verify(
+          request.verificationKey,
+          request.publicSignals,
+          request.proof,
+        );
+        process.send?.({ id: request.id, verified });
+      } catch (error) {
+        process.send?.({ id: request.id, error: error.message });
+      }
+    });
+  });
+  process.once('disconnect', () => process.exit(0));
+}
 
-export function verifyBundle(bundle) {
+export function verifyBundle(bundle, options = {}) {
   const receipts = asArray(bundle?.receipts);
+  const zkReceipts = zkReceiptsFromBundle(bundle);
   const checkpoints = asArray(bundle?.checkpoints ?? bundle?.passport?.checkpoints);
   const publicKey = publicKeyFromBundle(bundle);
   const errors = [];
@@ -138,10 +321,10 @@ export function verifyBundle(bundle) {
   if (!bundle || typeof bundle !== 'object') {
     return { ok: false, errors: [makeError('BUNDLE_INVALID', 'Bundle must be a JSON object.')] };
   }
-  if (receipts.length === 0) {
-    errors.push(makeError('RECEIPTS_MISSING', 'Bundle does not contain receipts.'));
+  if (receipts.length === 0 && zkReceipts.length === 0) {
+    errors.push(makeError('RECEIPTS_MISSING', 'Bundle does not contain memory or ZK settlement receipts.'));
   }
-  if (!publicKey) {
+  if (receipts.length > 0 && !publicKey) {
     errors.push(makeError('PUBLIC_KEY_MISSING', 'Bundle does not contain an offline verifier public key.'));
   }
 
@@ -172,8 +355,14 @@ export function verifyBundle(bundle) {
     }
   }
 
-  compareCommittedSequence(receipts, committed, errors);
+  if (zkReceipts.length > 0 && options.skipZk !== true) {
+    errors.push(makeError(
+      'ZK_ASYNC_VERIFICATION_REQUIRED',
+      'ZK settlement receipts require verifyBundleWithZk() or the enigma-verify CLI so snarkjs can verify Groth16 proofs.',
+    ));
+  }
 
+  compareCommittedSequence(receipts, committed, errors);
   if (receipts.length > 0 && checkpoints.length > 0 && publicKey) {
     const lastReceipt = receipts.at(-1);
     const lastCheckpoint = checkpoints.at(-1);
@@ -202,6 +391,84 @@ export function verifyBundle(bundle) {
     checked_at: new Date().toISOString(),
     receipt_count: receipts.length,
     checkpoint_count: checkpoints.length,
+    zk_receipt_count: zkReceipts.length,
+    errors,
+  };
+}
+
+export async function verifyBundleWithZk(bundle, options = {}) {
+  const report = verifyBundle(bundle, { skipZk: true });
+  const receipts = zkReceiptsFromBundle(bundle);
+  const errors = [...report.errors];
+  const hasProofBearingReceipts = receipts.some((receipt) => GROTH16_PROOF_EVENTS.has(receipt?.event));
+  if (receipts.length > MAX_ZK_SETTLEMENT_RECEIPTS) {
+    errors.push(makeError(
+      'ZK_SETTLEMENT_RECEIPT_LIMIT',
+      `Bundle contains ${receipts.length} ZK settlement receipts; the safe maximum is ${MAX_ZK_SETTLEMENT_RECEIPTS}.`,
+    ));
+    return { ...report, ok: false, proof_valid: null, settlement_verified: false, errors };
+  }
+
+  const graphVerdict = validateZkSettlementEvidenceGraph(receipts);
+  if (!graphVerdict.ok) errors.push(...graphVerdict.errors.map((error) => verifierError(
+    error,
+    'ZK_SETTLEMENT_GRAPH_INVALID',
+    'ZK settlement receipt graph did not verify.',
+  )));
+
+  for (const receipt of receipts) {
+    const verdict = validateZkSettlementEvidence(receipt, options);
+    if (!verdict.ok) {
+      errors.push(...verdict.errors.map((error) => verifierError(
+        error,
+        'ZK_SETTLEMENT_EVIDENCE_INVALID',
+        `ZK settlement receipt ${receipt?.receipt_ref ?? '<unknown>'} did not verify.`,
+      )));
+    }
+  }
+
+  // No Groth16 work is launched unless every cheap bundle, trust, signature,
+  // state-transition, lineage, transaction, and replay check has succeeded.
+  if (errors.length > 0) {
+    return { ...report, ok: false, proof_valid: null, settlement_verified: false, errors };
+  }
+
+  const worker = new Groth16VerifierWorker(options);
+  const timeoutMs = Number.isSafeInteger(options.groth16TimeoutMs) && options.groth16TimeoutMs > 0
+    ? options.groth16TimeoutMs
+    : 30_000;
+  try {
+    for (const receipt of receipts) {
+      if (!GROTH16_PROOF_EVENTS.has(receipt.event)) continue;
+      try {
+        const verificationKey = await loadVerificationKey(
+          receipt.circuit,
+          receipt.proof.verification_key?.sha256,
+          options,
+        );
+        const verified = await worker.verify({
+          circuit: receipt.circuit,
+          receiptRef: receipt.receipt_ref,
+          verificationKey,
+          publicSignals: receipt.proof.public_inputs.map((value) => BigInt(`0x${value}`).toString(10)),
+          proof: proofToSnarkjs(receipt.proof),
+        }, timeoutMs);
+        if (!verified) {
+          errors.push(makeError('ZK_EVIDENCE_GROTH16_INVALID', 'snarkjs rejected the Groth16 proof against the pinned verification key.'));
+        }
+      } catch (error) {
+        errors.push(makeError('ZK_EVIDENCE_GROTH16_INVALID', `Offline Groth16 verification failed closed: ${error.message}`));
+      }
+    }
+  } finally {
+    await worker.close();
+  }
+  const ok = errors.length === 0;
+  return {
+    ...report,
+    ok,
+    proof_valid: hasProofBearingReceipts ? ok : null,
+    settlement_verified: ok,
     errors,
   };
 }
@@ -210,14 +477,61 @@ export async function readBundle(path) {
   return JSON.parse(await readFile(path, 'utf8'));
 }
 
+function optionValue(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+}
+
+async function loadZkTrustOptions(argv) {
+  const trustPath = optionValue(argv, '--trust');
+  if (!trustPath) {
+    throw new Error('ZK settlement verification requires --trust <trust-registry.json>.');
+  }
+  const trust = await readBundle(trustPath);
+  if (
+    !trust
+    || !Array.isArray(trust.trusted_signers)
+    || trust.trusted_signers.length === 0
+    || typeof trust.program_id !== 'string'
+    || !trust.program_id
+    || typeof trust.cluster !== 'string'
+    || !trust.cluster
+    || !Array.isArray(trust.finalized_checkpoints)
+    || trust.finalized_checkpoints.length === 0
+  ) {
+    throw new Error('trust registry must contain non-empty trusted_signers, program_id, cluster, and finalized_checkpoints');
+  }
+  return {
+    trustedSigners: trust.trusted_signers,
+    expectedProgramId: trust.program_id,
+    expectedCluster: trust.cluster,
+    finalizedCheckpoints: trust.finalized_checkpoints,
+  };
+}
+
 export async function main(argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
-  const file = argv.find((arg) => !arg.startsWith('-'));
+  const file = argv.find((arg, index) => !arg.startsWith('-') && argv[index - 1] !== '--trust');
   if (!file || argv.includes('--help') || argv.includes('-h')) {
-    io.stdout.write(`${json({ usage: 'enigma-verify <exported-bundle.json>', output: 'JSON verification report' })}\n`);
+    io.stdout.write(`${json({ usage: 'enigma-verify <bundle-or-receipt.json> [--trust zk-trust-registry.json]', zk_trust_registry: { trusted_signers: ['base64-public-key or key-id'], program_id: 'expected program', cluster: 'expected cluster', finalized_checkpoints: ['receipt-bound finalized checkpoint objects'] }, output: 'JSON verification report' })}\n`);
     return 0;
   }
   try {
-    const report = verifyBundle(await readBundle(file));
+    const data = await readBundle(file);
+    if (data?.schema === ZK_SETTLEMENT_EVIDENCE_SCHEMA) {
+      const trustOptions = await loadZkTrustOptions(argv);
+      const report = await verifyZkSettlementEvidence(data, { ...trustOptions, seenRefs: new Set() });
+      io.stdout.write(`${json({ ...report, schema: 'enigma.zk_settlement_verification_report.v1' })}\n`);
+      return report.ok ? 0 : 1;
+    }
+    if (data && (data.schema === 'enigma.memory_receipt.v2' || (data.commitment && data.agent_pubkey && data.signature))) {
+      const report = verifyMemoryReceipt(data);
+      io.stdout.write(`${json({ ok: report.ok, verified: report.verified, schema: 'enigma.receipt_verification_report.v2', report })}\n`);
+      return report.ok ? 0 : 1;
+    }
+    const hasZkReceipts = zkReceiptsFromBundle(data).length > 0;
+    const report = hasZkReceipts
+      ? await verifyBundleWithZk(data, await loadZkTrustOptions(argv))
+      : verifyBundle(data);
     io.stdout.write(`${json(report)}\n`);
     return report.ok ? 0 : 1;
   } catch (error) {
@@ -235,6 +549,8 @@ function isMainModule(metaUrl) {
 }
 
 
-if (isMainModule(import.meta.url)) {
+if (IS_GROTH16_WORKER) {
+  startGroth16Worker();
+} else if (isMainModule(import.meta.url)) {
   process.exitCode = await main();
 }

package/cortex-v3/circuits/build/intent_vk_bytes.json

@@ -0,0 +1,35 @@
+{
+  "format": "raw-be-hex-v1",
+  "curve": "bn128",
+  "g2LimbOrder": "c1c0",
+  "proofNote": "pi_a is raw — the on-chain program negates A",
+  "circuit": "intent_attestation",
+  "circuitVersion": 2,
+  "numPublicInputs": 4,
+  "icCount": 5,
+  "icPaddedTo": 7,
+  "alphaG1": "2d4d9aa7e302d9df41749d5507949d05dbea33fbb16c643b22f599a2be6df2e214bedd503c37ceb061d8ec60209fe345ce89830a19230301f076caff004d1926",
+  "betaG2": "0967032fcbf776d1afc985f88877f182d38480a653f2decaa9794cbc3bf3060c0e187847ad4c798374d0d6732bf501847dd68bc0e071241e0213bc7fc13db7ab304cfbd1e08a704a99f5e847d93f8c3caafddec46b7a0d379da69a4d112346a71739c1b1a457a8c7313123d24d2f9192f896b7c63eea05a9d57f06547ad0cec8",
+  "gammaG2": "198e9393920d483a7260bfb731fb5d25f1aa493335a9e71297e485b7aef312c21800deef121f1e76426a00665e5c4479674322d4f75edadd46debd5cd992f6ed090689d0585ff075ec9e99ad690c3395bc4b313370b38ef355acdadcd122975b12c85ea5db8c6deb4aab71808dcb408fe3d1e7690c43d37b4ce6cc0166fa7daa",
+  "deltaG2": "2c80382a4d2011a8047aa6712fb7998f63aaac9d904fe46fda37c705453f5d55011153e8b44da8dea7ff23cfc54402bd8dda85b6fd5b6e8c311ac04a24be81961ec087bc02f5a629cdad62683f7fd085693d8d9efd4331f680454072b55e3c120ed38191e3494aff5760cbb6f6a69296dcdbfca684dabc15f877e3dba3d92e46",
+  "ic": [
+    "24f95d74e34ded414c3e53f386722cf7635e3cb9dc3120b3bbc8110608b11d35283eed3710f3680588265308925d58ac23935f90f1448de5d2c76d8b7812778f",
+    "0daa93c2b8773b1b45a73d1032cecbc39dd38b4b726f0e6816f0cdc9eb64b59a277174ab8f322ece1e035389d0f486880ca9d656e087eb1b946582691e42b138",
+    "0d6d39d085f4470bdb472f8c2abcdfc8de0520b1f9a5632f3dd504e93f6fe9ee1a19eb6ed785a5fb2236d89c260be061a84645fe1eab6cc958d78d1ba63706e4",
+    "1f91d72d148fcd918eb093681b0b62ddb8afa8763fd99e97c208c22650c703c7202a4f5cee6f9a2e0103c08eb21cf7f49568de0f4b4c004efe763dfa8de2130f",
+    "2a37257d7820013d370539ad680c98346801a569015c545c61a818e8cd77326620723e84dc1c6a34d830001605339f25993e7990e41ad2b0219cc67dc70f4509",
+    "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+    "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
+  ],
+  "ceremony": "development single-party",
+  "ceremonyDetail": {
+    "ptau": "reused repo-local file (no download)",
+    "ptauBytes": 302072984,
+    "ptauPower": 18,
+    "r1csSha256": "c485c9bb702d9db158ffeffa023ca24dd425764cdc876fadfbc63da5d8efef5d",
+    "constraintCount": 22702,
+    "contribution": "enigma-intent-dev-1 (random entropy) + random beacon (10 iterations)"
+  },
+  "source": "intent_verification_key.json",
+  "createdAt": "2026-08-23T07:05:55.037Z"
+}

package/cortex-v3/circuits/build/sale_vk_bytes.json

@@ -0,0 +1,35 @@
+{
+  "format": "raw-be-hex-v1",
+  "curve": "bn128",
+  "g2LimbOrder": "c1c0",
+  "proofNote": "pi_a is raw — the on-chain program negates A",
+  "circuit": "sealed_sale_release",
+  "circuitVersion": 3,
+  "numPublicInputs": 6,
+  "icCount": 7,
+  "icPaddedTo": 7,
+  "alphaG1": "2d4d9aa7e302d9df41749d5507949d05dbea33fbb16c643b22f599a2be6df2e214bedd503c37ceb061d8ec60209fe345ce89830a19230301f076caff004d1926",
+  "betaG2": "0967032fcbf776d1afc985f88877f182d38480a653f2decaa9794cbc3bf3060c0e187847ad4c798374d0d6732bf501847dd68bc0e071241e0213bc7fc13db7ab304cfbd1e08a704a99f5e847d93f8c3caafddec46b7a0d379da69a4d112346a71739c1b1a457a8c7313123d24d2f9192f896b7c63eea05a9d57f06547ad0cec8",
+  "gammaG2": "198e9393920d483a7260bfb731fb5d25f1aa493335a9e71297e485b7aef312c21800deef121f1e76426a00665e5c4479674322d4f75edadd46debd5cd992f6ed090689d0585ff075ec9e99ad690c3395bc4b313370b38ef355acdadcd122975b12c85ea5db8c6deb4aab71808dcb408fe3d1e7690c43d37b4ce6cc0166fa7daa",
+  "deltaG2": "01cfc0c27e91936f3bbb83ecd7fda692ef101106289c5c2910e586a061ccdb8315d7e50fb73168a797d4e963a5058f077dc4fef911e3523d29b55ca9b1ee164d2d629f03e5937dd21c883966c212cf1de3cdc79da0d2a5e0bf8fe5041942536a17e1d560c080c3346087cb5d9aafdd7703c875a11bf7f2cdd44b64f83be65fe4",
+  "ic": [
+    "01ad96b8d94557fb0e599d74d6efacf2aa4b79eb95154bee16ecc2bb341300df0f2883242d52531e840e8b036d967118e46c7ae3b404771bc1f69a6744615f64",
+    "1eb5ce743d6e739b818dd89359c5f17de32a271a09a1f3ba83597e00621ed59f12f55c4b6d18bd4b42f1cd723045f238df1bca7852dba436b71cf0f21b1e2b6e",
+    "0440cfcbe09c27825d061222b7638c00d5696cd668ea597ab4a15674206b9b9e22f77b706aa53bf12a78e862e98ed83083787797acb28c52322b066964bf5ab4",
+    "22fdb5a3d9234f4440b8d8cbb8a9117348d0618139e2f1d5df3d9c6238d4eab62dff5fa539ee290fb5bdf76dd82817cdd034693023e775dad4688ab035088120",
+    "2eb22cc64a4848f0107b9bfc4b108d2a04fdf220fd4a42c0ea5d6f2cc9c9e24e1785dee6079cf7ec0b7f1963c98d3608b8f81900b96b061c036e23660adb1f85",
+    "0a4be75124046bca09901816bbb38a7815816ef4ea531057ebce60ee839cb72e20201653d9ebca2e691206c18611111280a17a0f6fab835d35ffd6b723ff3c37",
+    "009c32b9067eb596b86320cdeb35e459313b19b0505ec7aac01c57944dd648df151b97fbacf6a664070a10794502aaac1c5211e07a83d465194b5cbe90b016a9"
+  ],
+  "ceremony": "development single-party",
+  "ceremonyDetail": {
+    "ptau": "reused repo-local file (no download)",
+    "ptauBytes": 302072984,
+    "ptauPower": 18,
+    "r1csSha256": "46e3d6846000005db1a11559604dcf5efbcefa263eed78b0aef7702de91b6830",
+    "constraintCount": 87422,
+    "contribution": "enigma-sale-dev-1 (random entropy) + random beacon (10 iterations)"
+  },
+  "source": "sale_verification_key.json",
+  "createdAt": "2026-08-23T07:06:19.059Z"
+}

package/cortex-v3/circuits/build/vk_bytes.json

@@ -0,0 +1,32 @@
+{
+  "format": "raw-be-hex-v1",
+  "curve": "bn128",
+  "g2LimbOrder": "c1c0",
+  "proofNote": "pi_a is raw — the on-chain program negates A",
+  "numPublicInputs": 6,
+  "icCount": 7,
+  "alphaG1": "2d4d9aa7e302d9df41749d5507949d05dbea33fbb16c643b22f599a2be6df2e214bedd503c37ceb061d8ec60209fe345ce89830a19230301f076caff004d1926",
+  "betaG2": "0967032fcbf776d1afc985f88877f182d38480a653f2decaa9794cbc3bf3060c0e187847ad4c798374d0d6732bf501847dd68bc0e071241e0213bc7fc13db7ab304cfbd1e08a704a99f5e847d93f8c3caafddec46b7a0d379da69a4d112346a71739c1b1a457a8c7313123d24d2f9192f896b7c63eea05a9d57f06547ad0cec8",
+  "gammaG2": "198e9393920d483a7260bfb731fb5d25f1aa493335a9e71297e485b7aef312c21800deef121f1e76426a00665e5c4479674322d4f75edadd46debd5cd992f6ed090689d0585ff075ec9e99ad690c3395bc4b313370b38ef355acdadcd122975b12c85ea5db8c6deb4aab71808dcb408fe3d1e7690c43d37b4ce6cc0166fa7daa",
+  "deltaG2": "091a85f20ac1f736ee31f97959685e8bd82ce0339ccfe72019b5966a1403f2991e5f3dcb18f308d4d546cfb0dcff42243a1b86329133565ea25c6f40a8adfe0620fbbb95e8fc21ae9c782ddb84189c406ba096b31e148fc8764690bf9288022a1b812a8b2155480b2e69b506eabb0c4f340ada0473ea711a0299abdb47da907e",
+  "ic": [
+    "2634587402f69103e89eab1748090987058ee27f71a2edfd2d7f5176aa81ac0805e814cb2ceb8751885f2860ca8f011b05a5db7f157b83662020d6d3be103698",
+    "06155bbf16ad4f3d5f57dc918444386a096c845bceef38336e7372225bc1b37b245257b11f5a3a7ac5b8400505cf29a0e68c7a2d50a2c9e60c2ba67ecad098f8",
+    "22582647eedd69991be9f13e3da959f9c39e209c8f173ea8c9a68b8d585415032ba3bbf4fdf5de4241231954c4632f484cea61b1b0471f078a22145ce8403914",
+    "2e3fb4f50e18ffcd44a1f469482338430d966156f08e63f2ead4c882be8f437704f308855af1ae4d41ff894f949c4b622f9ba7ebae461384f1514d9c9afa78df",
+    "2ab15cd0f9ff27527b9a5d405cc34ae38dbb3173819a867d5c924fd92d91288c2b283f34ca1cff31b47c684bb2002ca9361fc8d1e69902d9cf8ca4109652c547",
+    "06a396bcc77f20e5309a81c49dd3fc1bb458c377500319c80149a7c7e06f0e6d18f0871baaa62a63e2c4628c3e0584ce2d0610dbb77c72a7d3a8068dd6041281",
+    "084973788eda5f9a243f990e9429380d7869c680ef49e3986f1132470080388f046a01cf1d208c633c2102df3b5a2da26abb9e82b0b705e5f9150e6749bc7f90"
+  ],
+  "ceremony": {
+    "type": "single-party local (DEVELOPMENT ONLY — production needs a multi-party ceremony)",
+    "ptau": "reused existing file",
+    "ptauBytes": 302072984,
+    "r1csSha256": "558b99519e36fe94a0c7ffaed2cd5bb7865fc7387de42895e70dabba434c9656",
+    "constraintCount": 90897,
+    "powerOfTau": 18,
+    "contribution": "enigma-dev-1 (random entropy) + random beacon (10 iterations)"
+  },
+  "source": "verification_key.json",
+  "createdAt": "2026-08-23T07:05:43.317Z"
+}

package/cortex-v3/proving-assets.json

@@ -0,0 +1,64 @@
+{
+  "version": 1,
+  "ceremony": "single-party development ceremony (2026-08-23) \u2014 production requires MPC",
+  "releaseBase": "https://github.com/Enigma-Memory/enigma-cortex-enterprise/releases/download/zk-assets-v1",
+  "circuits": {
+    "action_transition": {
+      "circuitVersion": 1,
+      "wasm": {
+        "file": "action_transition.wasm",
+        "sha256": "0e7abc6e4dcdf5869ccbc60f977e73bb24551a5004283ea6e96b22a43c9b6225",
+        "bytes": 2608957
+      },
+      "zkey": {
+        "file": "action_transition.zkey",
+        "sha256": "1b54596df69450c3b69128b10103188ccc9061a869fd7018cc939c68d7c1080c",
+        "bytes": 41534018
+      },
+      "r1csSha256": "558b99519e36fe94a0c7ffaed2cd5bb7865fc7387de42895e70dabba434c9656",
+      "vkBytes": {
+        "file": "vk_bytes.json",
+        "sha256": "e84987d4b4a0645214ef8b2cc91a883a922cdda7df9b9d435b745a3e0dce441c",
+        "bytes": 2595
+      }
+    },
+    "intent_attestation": {
+      "circuitVersion": 2,
+      "wasm": {
+        "file": "intent_attestation.wasm",
+        "sha256": "2c680fdf5c9503825612cb5ef8629e7a9316881cb83705dbf3b37cd05e5ea233",
+        "bytes": 4039469
+      },
+      "zkey": {
+        "file": "intent_attestation.zkey",
+        "sha256": "53927073b2b41bae6f817929779758cbe5869e6a6a455aab6a5f1e7475e019dd",
+        "bytes": 10335105
+      },
+      "r1csSha256": "c485c9bb702d9db158ffeffa023ca24dd425764cdc876fadfbc63da5d8efef5d",
+      "vkBytes": {
+        "file": "intent_vk_bytes.json",
+        "sha256": "851f6d898e8b1877ff3081dcbfab61ca76ad72d2747e9d7648f6d9e4a06420d4",
+        "bytes": 2652
+      }
+    },
+    "sealed_sale_release": {
+      "circuitVersion": 3,
+      "wasm": {
+        "file": "sealed_sale_release.wasm",
+        "sha256": "98c204a8fb9ab507d84962331c9c01b37f53d454699dcfd1e063f157962e9d79",
+        "bytes": 5568152
+      },
+      "zkey": {
+        "file": "sealed_sale_release.zkey",
+        "sha256": "8c577a3dfaa64477440397ace1ed61f817a3d533307d236abbe4251c76666ff2",
+        "bytes": 41163791
+      },
+      "r1csSha256": "46e3d6846000005db1a11559604dcf5efbcefa263eed78b0aef7702de91b6830",
+      "vkBytes": {
+        "file": "sale_vk_bytes.json",
+        "sha256": "a746456055c2f9521bb6cc2b3b569eea5ff2170662b73643bb3954fc774dfbe2",
+        "bytes": 2649
+      }
+    }
+  }
+}

package/cortex-v3/zk/BUILD-CONTRACT.md

@@ -0,0 +1,87 @@
+# Enigma ZK End-to-End Build Contract v3 (binding; supersedes v2)
+
+## Architecture: sovereign per-action ZK proofs (single layer)
+Every shared-state transition is a client-generated Groth16 proof. User secrets
+(ownerKey, rho, payload openings, Merkle paths) NEVER leave the client — no
+sequencer/relayer ever sees a witness. Relayers submit only proof + public inputs.
+On-chain Poseidon does not exist, so BOTH appends and revocations are proven.
+
+Design note (recorded decision): a two-layer admission(PendingAction)+epoch-batch
+split was evaluated and rejected — binding admitted nullifiers into an epoch proof
+requires either on-chain Poseidon (unavailable) or in-circuit SHA-256 (~400k extra
+constraints). Client-side proving of the full IMT transition is 5-15s WASM —
+affordable — so the single-layer design preserves sovereignty without the binding
+hole. Batch/recursive aggregation remains a documented future optimization.
+
+## On-chain contract (main agent implementing; DO NOT touch program source)
+- SharedState PDA [b"shared_state"]: authority, note_root, null_root,
+  note_count u64, null_count u64, created_at.
+- initialize_shared_state(genesis_note_root, genesis_null_root) — governance
+  (live upgrade-authority check). Genesis values from the JS zero-chain/IMT genesis.
+- settle_action(proof{a[64],b[128],c[64]} raw BE — program negates A internally,
+  public_inputs[[u8;32];6]) — permissionless (relayer-friendly; any payer).
+  Program: canonicality (< r) on all 6; continuity old roots == stored roots;
+  unpack packed = mode*2^60 + action_index; mode 0 (append): nullifier MUST be 0,
+  action_index == note_count → note_count++; mode 1 (revoke): action_index ==
+  null_count → null_count++; Groth16 verify vs pinned VK (IC len 7); store new roots;
+  emit ActionSettled. Stale roots → tx fails → client regenerates within ~2 slots
+  (documented contention model, ~70-85 settles/block/account CU ceiling).
+- KEEP: initialize_registry, register_commitment, record_revocation (non-ZK
+  owner-signed path), initialize_circuit_verifying_key (IC len now 7).
+- REMOVE: RootIndex/RootShard/register_zk_root/verify_zk_memory_proof (wave-1 dead).
+
+## 6 public inputs, exact order (canonical BE < r = 0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001)
+[0] oldNoteRoot  [1] newNoteRoot  [2] oldNullRoot  [3] newNullRoot
+[4] nullifier    (0 for append; nf for revoke)
+[5] packed = mode * 2^60 + actionIndex   (mode ∈ {0,1}; actionIndex < 2^60)
+
+## Circuit: cortex-v3/circuits/action_transition.circom — ActionTransition(D=20)
+Poseidon (circomlib), BN254. Public signal names/order exactly as above.
+Private: isAppend (boolean-constrained), note, ownerKey, rho, payloadCommit,
+notePathElements[D], notePathIndices[D] (LSB-first bits),
+noteMemPathElements[D], noteMemPathIndices[D],
+predValue, predNextIndex, predNextValue, predPathElements[D], predPathIndices[D],
+appendPathElements[D], appendPathIndices[D].
+
+### APPEND mode (isAppend=1; packed mode=0)
+- zeros[0]=0, zeros[i+1]=Poseidon(zeros[i],zeros[i]) in-circuit.
+- Verify zero-leaf (zeros[D]) path at actionIndex against oldNoteRoot.
+- newNoteRoot = root with leaf=note inserted at actionIndex.
+- Constrain newNullRoot == oldNullRoot; nullifier === 0.
+- Note well-formedness in BOTH modes: note === Poseidon([ownerKey, rho, payloadCommit])
+  so an appended note is always bound to its owner's key.
+
+### REVOKE mode (isAppend=0)
+- Membership: note path vs oldNoteRoot. newNoteRoot == oldNoteRoot.
+- nf = Poseidon([DOMAIN_REVOCATION, ownerKey, rho]); nullifier === nf.
+  DOMAIN_REVOCATION = 0x656e69676d615f7265766f6b65 ("enigma_revoke") field constant.
+- IMT (Aztec-style): leaf hash = Poseidon([value, nextIndex, nextValue]); genesis
+  index 0 = {0, 0, r-1}; prove predecessor path vs oldNullRoot; strict
+  predValue < nf < predNextValue (bit-decomposition comparisons); updated predecessor
+  = {predValue, actionIndex, nf} → intermediate root; append new leaf
+  {nf, predNextIndex, predNextValue} at actionIndex (zero-leaf path vs intermediate
+  root) → newNullRoot.
+
+Constraint target 60-120k → ptau 2^18 (powersOfTau28_hez_final_18.ptau).
+
+## Toolchain
+- circom: iden3/circom release binary → cargo install --locked fallback → WSL.
+- snarkjs, circomlib, circomlibjs via npm -D in cortex-v3.
+- Setup: single-party DEV ceremony (groth16 setup + contribute + beacon) — docs MUST
+  state production needs multi-party ceremony.
+
+## File ownership
+- Main agent: programs/enigma_nullifier/**, idl/**, tests/enigma_nullifier.ts,
+  scripts/test-governance-localnet.mjs, this contract.
+- CircuitBuild: circuits/** (+ circomlib devDep).
+- CodecSetup: zk/zk-codec.mjs, zk/zk-codec.test.mjs, zk/setup.mjs, ptau/**,
+  circuits/build/** outputs (verification_key.json + vk_bytes.json COMMITTABLE;
+  gitignore ptau/, *.zkey, *.r1cs, wasm). IC length MUST be 7.
+- TreeWitness: zk/zk-tree.mjs, zk/witness.mjs (buildActionWitness), zk/zk-tree.test.mjs
+  (+ circomlibjs devDep).
+
+## Claim boundaries (hard)
+- Dev ceremony ≠ production trusted setup. Nullifiers = protocol non-use, never
+  deletion. No "first on Solana" until publicly reproducible end-to-end.
+- Sovereignty invariant: no private witness material in ANY network-facing payload;
+  test-zk-e2e MUST assert the submitted tx contains only proof + public inputs.