Merge pull request #421 from Anthony-19/create-release-bundle

Add deployment preflight checks that compare target pool VK metadata …

Author: ANAVHEOBA

docs/zk_artifacts_layout.md

@@ -21,6 +21,8 @@ artifacts/
         │       └── merkle.json        # Compiled circuit (ACIR + ABI)
         ├── manifests/                 # Circuit metadata and checksums
         │   └── manifest.json          # Global manifest for all circuits
+        ├── bundles/                   # Releasable bundle metadata
+        │   └── release-bundle.json    # Bundle tying manifest, schema, and contract metadata together
         ├── fixtures/                  # Test vectors and golden inputs
         │   ├── commitment/
         │   │   └── test_vectors.json  # Test vectors for commitment circuit
@@ -63,6 +65,10 @@ Artifact versions are tracked via the `version` field in `sdk/src/artifacts.ts`.
   - Circuit metadata (paths, checksums, configuration)
   - Root depth for Merkle trees
 
+### Release Bundles (`bundles/`)
+
+- **`release-bundle.json`**: Deterministic release envelope containing the manifest hash, verifier schema, and contract-facing metadata for a single coherent ZK release.
+
 ### Fixtures (`fixtures/`)
 
 - **`test_vectors.json`**: Golden test vectors and inputs for circuit testing. Used by SDK tests to verify circuit behavior.

scripts/generate_commitment_vectors.mjs

@@ -5,6 +5,8 @@ import { createRequire } from 'node:module';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, '..');
+const zkVersion = process.argv[2] || '1';
+const versionedArtifactsDir = path.join(repoRoot, 'artifacts', 'zk', `v${zkVersion}`);
 const requireFromSdk = createRequire(path.join(repoRoot, 'sdk', 'package.json'));
 const { poseidon2Hash } = requireFromSdk('@zkpassport/poseidon2');
 
@@ -13,6 +15,8 @@ const FIELD_MODULUS =
 const NOTE_SCALAR_BYTE_LENGTH = 31;
 const FIELD_BYTE_LENGTH = 32;
 
+const jsonPath = path.join(repoRoot, 'artifacts', 'zk', 'commitment_vectors.json');
+const versionedJsonPath = path.join(versionedArtifactsDir, 'commitment_vectors.json');
 // ZK-086: Accept version parameter for versioned artifact layout
 const zkVersion = process.argv[2] || '1';
 const jsonPath = path.join(repoRoot, 'artifacts', 'zk', `v${zkVersion}`, 'commitment_vectors.json');
@@ -187,11 +191,17 @@ pub fn fixture_cv_004() -> (Field, Field, Field, Field) {
 }
 `;
 
+if (!fs.existsSync(versionedArtifactsDir)) {
+  fs.mkdirSync(versionedArtifactsDir, { recursive: true });
+}
+
 if (!fs.existsSync(path.dirname(jsonPath))) {
   fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
 }
 fs.writeFileSync(jsonPath, JSON.stringify(fixtureJson, null, 2) + '\n');
+fs.writeFileSync(versionedJsonPath, JSON.stringify(fixtureJson, null, 2) + '\n');
 fs.writeFileSync(noirFixturesPath, noirFixtures);
 
 console.log(`Wrote ${path.relative(repoRoot, jsonPath)}`);
+console.log(`Wrote ${path.relative(repoRoot, versionedJsonPath)}`);
 console.log(`Wrote ${path.relative(repoRoot, noirFixturesPath)}`);

scripts/rebuild-zk.sh

@@ -44,6 +44,11 @@ echo "📦 Compiling circuits..."
 for pkg in commitment withdraw merkle; do
   echo "  → Building $pkg..."
   (cd "circuits" && nargo compile --package "$pkg")
+  cp "circuits/target/$pkg.json" "$ARTIFACTS_DIR/circuits/$pkg/$pkg.json"
+  cp "circuits/target/$pkg.json" "artifacts/zk/$pkg.json"
+done
+
+echo "🧪 Regenerating shared commitment vectors..."
   # ZK-086: Align with versioned layout contract
   cp "circuits/target/$pkg.json" "$ARTIFACTS_DIR/circuits/$pkg/$pkg.json"
 done

scripts/refresh_manifest.mjs

@@ -10,9 +10,10 @@ const repoRoot = path.resolve(__dirname, '..');
 // ZK-041: Accept version parameter for versioned artifact layout
 const zkVersion = process.argv[2] || '1';
 const artifactsDir = path.join(repoRoot, 'artifacts', 'zk', `v${zkVersion}`);
-const manifestPath = path.join(artifactsDir, 'manifests', 'manifest.json');
+const versionedManifestPath = path.join(artifactsDir, 'manifests', 'manifest.json');
+const legacyManifestPath = path.join(repoRoot, 'artifacts', 'zk', 'manifest.json');
+const releaseBundlePath = path.join(artifactsDir, 'bundles', 'release-bundle.json');
 const PRODUCTION_MERKLE_ROOT_DEPTH = 20;
-const CIRCUIT_ORDER = ['withdraw', 'commitment'];
 const WITHDRAW_PUBLIC_INPUT_SCHEMA = [
   'pool_id',
   'root',
@@ -22,6 +23,7 @@ const WITHDRAW_PUBLIC_INPUT_SCHEMA = [
   'relayer',
   'fee',
 ];
+const CONTRACT_PUBLIC_INPUT_SCHEMA = WITHDRAW_PUBLIC_INPUT_SCHEMA.slice(1);
 const EXTRA_FILES = {
   commitment_vectors: {
     path: 'commitment_vectors.json',
@@ -66,10 +68,36 @@ function commandOutput(command, args = ['--version']) {
   return result.stdout;
 }
 
-function readJson(filePath) {
-  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+function detectBackendVersions() {
+  try {
+    return {
+      nargo_version: commandOutput('nargo', ['--version']).trim(),
+      noirc_version: commandOutput('noirc', ['--version']).trim(),
+    };
+  } catch {
+    return {
+      nargo_version: 'unknown',
+      noirc_version: 'unknown',
+    };
+  }
 }
 
+function normalizeBackend(backend) {
+  const versions = detectBackendVersions();
+  if (backend && typeof backend === 'object') {
+    return {
+      name: backend.name ?? 'nargo/noir',
+      nargo_version: backend.nargo_version ?? versions.nargo_version,
+      noirc_version: backend.noirc_version ?? versions.noirc_version,
+    };
+  }
+
+  return {
+    name: typeof backend === 'string' && backend.length > 0 ? backend : 'nargo/noir',
+    nargo_version: versions.nargo_version,
+    noirc_version: versions.noirc_version,
+  };
+}
 
 
 function buildExtraFileEntries() {
@@ -92,6 +120,36 @@ function buildExtraFileEntries() {
   );
 }
 
+function buildReleaseBundle(manifest) {
+  const withdraw = manifest.circuits.withdraw;
+  if (!withdraw || !withdraw.public_input_schema) {
+    throw new Error('Withdrawal circuit manifest entry is required to build the release bundle');
+  }
+
+  const manifestSha256 = sha256Hex(stableStringify(manifest));
+  const verifierSchema = {
+    circuit_id: withdraw.circuit_id,
+    public_input_schema: withdraw.public_input_schema,
+    public_input_arity: withdraw.public_input_schema.length,
+    contract_public_input_schema: CONTRACT_PUBLIC_INPUT_SCHEMA,
+    contract_public_input_arity: CONTRACT_PUBLIC_INPUT_SCHEMA.length,
+    schema_version: 1,
+  };
+
+  return {
+    version: 1,
+    artifact_version: zkVersion,
+    manifest_sha256: manifestSha256,
+    manifest,
+    verifier_schema,
+    contract_metadata: {
+      contract_name: 'privacy_pool',
+      target_circuit_id: withdraw.circuit_id,
+      manifest_sha256: manifestSha256,
+      public_input_arity: CONTRACT_PUBLIC_INPUT_SCHEMA.length,
+      schema_version: 1,
+      verifier_key_storage: 'DataKey::VerifyingKey',
+    },
 function computeChecksums(raw, artifact) {
   return {
     artifact_sha256: sha256Hex(raw),
@@ -103,16 +161,20 @@ function computeChecksums(raw, artifact) {
 function main() {
   console.log(`Refreshing ZK manifest for version ${zkVersion}...`);
 
-  // ZK-041: Create manifests directory if it doesn't exist
-  if (!fs.existsSync(path.dirname(manifestPath))) {
-    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  if (!fs.existsSync(path.dirname(versionedManifestPath))) {
+    fs.mkdirSync(path.dirname(versionedManifestPath), { recursive: true });
+  }
+  if (!fs.existsSync(path.dirname(releaseBundlePath))) {
+    fs.mkdirSync(path.dirname(releaseBundlePath), { recursive: true });
   }
 
-  // ZK-041: Initialize manifest structure if it doesn't exist
   let manifest;
-  if (fs.existsSync(manifestPath)) {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  if (fs.existsSync(versionedManifestPath)) {
+    manifest = JSON.parse(fs.readFileSync(versionedManifestPath, 'utf8'));
+  } else if (fs.existsSync(legacyManifestPath)) {
+    manifest = JSON.parse(fs.readFileSync(legacyManifestPath, 'utf8'));
   } else {
+    throw new Error('No manifest found to refresh. Run the rebuild pipeline first.');
     manifest = {
       version: zkVersion,
       backend: {
@@ -124,10 +186,13 @@ function main() {
     };
   }
 
-  // ZK-041: Update circuits list to include merkle
+  manifest.version = Number.parseInt(zkVersion, 10);
+  manifest.backend = normalizeBackend(manifest.backend);
+
   const circuits = ['withdraw', 'commitment', 'merkle'];
 
   for (const name of circuits) {
+    const filePath = path.join(artifactsDir, 'circuits', name, `${name}.json`);
     // ZK-041: Look for circuits in versioned directory structure
     const circuitFile = `circuits/${name}/${name}.json`;
     const filePath = path.join(artifactsDir, circuitFile);
@@ -139,6 +204,35 @@ function main() {
 
     const raw = fs.readFileSync(filePath);
     const artifact = JSON.parse(raw.toString('utf8'));
+    const circuitEntry = manifest.circuits[name] ?? (manifest.circuits[name] = {});
+    circuitEntry.circuit_id = name;
+    circuitEntry.path = `circuits/${name}/${name}.json`;
+    circuitEntry.artifact_sha256 = sha256Hex(raw);
+    circuitEntry.bytecode_sha256 = sha256Hex(String(artifact.bytecode ?? ''));
+    circuitEntry.abi_sha256 = sha256Hex(stableStringify(artifact.abi ?? null));
+    circuitEntry.name = artifact.name ?? name;
+    circuitEntry.backend = 'nargo/noir';
+
+    if (name === 'withdraw') {
+      circuitEntry.root_depth = PRODUCTION_MERKLE_ROOT_DEPTH;
+      circuitEntry.public_input_schema = WITHDRAW_PUBLIC_INPUT_SCHEMA;
+    }
+  }
+
+  const extraFiles = buildExtraFileEntries();
+  manifest.files = extraFiles;
+
+  const manifestText = JSON.stringify(manifest, null, 2) + '\n';
+  const releaseBundle = buildReleaseBundle(manifest);
+  const releaseBundleText = JSON.stringify(releaseBundle, null, 2) + '\n';
+
+  fs.writeFileSync(versionedManifestPath, manifestText);
+  fs.writeFileSync(legacyManifestPath, manifestText);
+  fs.writeFileSync(releaseBundlePath, releaseBundleText);
+
+  console.log(`Manifest updated at ${versionedManifestPath}`);
+  console.log(`Legacy manifest updated at ${legacyManifestPath}`);
+  console.log(`Release bundle updated at ${releaseBundlePath}`);
     const checksums = computeChecksums(raw, artifact);
 
     if (!manifest.circuits[name]) {

scripts/zk_release_preflight.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const options = {
+    version: '1',
+    bundlePath: '',
+    targetMetadataPath: '',
+    targetMetadataJson: '',
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--version') {
+      options.version = argv[++i] ?? '1';
+    } else if (arg === '--bundle-path') {
+      options.bundlePath = argv[++i] ?? '';
+    } else if (arg === '--target-metadata-path') {
+      options.targetMetadataPath = argv[++i] ?? '';
+    } else if (arg === '--target-metadata-json') {
+      options.targetMetadataJson = argv[++i] ?? '';
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else {
+      fail(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log([
+    'Usage:',
+    '  node scripts/zk_release_preflight.mjs --version 1 --target-metadata-path pool-config.json',
+    '  node scripts/zk_release_preflight.mjs --bundle-path artifacts/zk/v1/bundles/release-bundle.json --target-metadata-json "{...}"',
+    '',
+    'Target metadata must contain:',
+    '  circuit_id, manifest_sha256, public_input_arity',
+    '',
+    'Optional target metadata field:',
+    '  schema_version',
+  ].join('\n'));
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function resolveBundlePath(options) {
+  if (options.bundlePath) {
+    return path.isAbsolute(options.bundlePath)
+      ? options.bundlePath
+      : path.join(repoRoot, options.bundlePath);
+  }
+
+  return path.join(repoRoot, 'artifacts', 'zk', `v${options.version}`, 'bundles', 'release-bundle.json');
+}
+
+function loadBundle(bundlePath) {
+  if (!fs.existsSync(bundlePath)) {
+    fail(`Release bundle not found: ${bundlePath}`);
+  }
+
+  return readJson(bundlePath);
+}
+
+function loadTargetMetadata(options) {
+  if (options.targetMetadataJson) {
+    return JSON.parse(options.targetMetadataJson);
+  }
+
+  if (options.targetMetadataPath) {
+    const targetPath = path.isAbsolute(options.targetMetadataPath)
+      ? options.targetMetadataPath
+      : path.join(repoRoot, options.targetMetadataPath);
+
+    if (!fs.existsSync(targetPath)) {
+      fail(`Target metadata file not found: ${targetPath}`);
+    }
+
+    return readJson(targetPath);
+  }
+
+  fail('Provide either --target-metadata-path or --target-metadata-json.');
+}
+
+function compareBundleToTarget(bundle, target) {
+  const expected = bundle.verifier_schema ?? {};
+  const contractMetadata = bundle.contract_metadata ?? {};
+  const mismatches = [];
+
+  if (target.circuit_id !== expected.circuit_id) {
+    mismatches.push({ field: 'circuit_id', expected: expected.circuit_id, actual: target.circuit_id });
+  }
+
+  if (target.manifest_sha256 !== contractMetadata.manifest_sha256) {
+    mismatches.push({ field: 'manifest_sha256', expected: contractMetadata.manifest_sha256, actual: target.manifest_sha256 });
+  }
+
+  if (target.public_input_arity !== expected.contract_public_input_arity) {
+    mismatches.push({ field: 'public_input_arity', expected: expected.contract_public_input_arity, actual: target.public_input_arity });
+  }
+
+  if (
+    typeof target.schema_version === 'number' &&
+    target.schema_version !== expected.schema_version
+  ) {
+    mismatches.push({ field: 'schema_version', expected: expected.schema_version, actual: target.schema_version });
+  }
+
+  return mismatches;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const bundlePath = resolveBundlePath(options);
+  const bundle = loadBundle(bundlePath);
+  const target = loadTargetMetadata(options);
+
+  const mismatches = compareBundleToTarget(bundle, target);
+  console.log(`Release bundle: ${bundlePath}`);
+  console.log(`Target circuit: ${target.circuit_id}`);
+
+  if (mismatches.length > 0) {
+    console.error('Release preflight failed:');
+    for (const mismatch of mismatches) {
+      console.error(`- ${mismatch.field}: expected ${mismatch.expected}, got ${mismatch.actual}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('Release preflight passed.');
+}
+
+main();