zk-credits 0.2.2 → 0.2.3

package/README.md

@@ -7,7 +7,7 @@ are founder-provisioned test credits, and the circuit is not independently
 audited.
 
 ```bash
-npm install --global zk-credits@latest
+npm install --global zk-credits@0.2.3
 ```
 
 ## Pinned pilot versions
@@ -17,19 +17,17 @@ not mix versions between the sidecar, the adapter package, and the gateway:
 
 | Package | Version |
 | --- | --- |
-| `zk-credits` (this sidecar) | `0.2.1` |
+| `zk-credits` (this sidecar) | `0.2.3` |
 | `@zk-credits/x402-zk-prepaid` (adapter) | `0.1.0` |
 | `@zk-credits/shared` | `0.1.0` |
 
-`zk-credits@0.2.1` is the currently published Base Sepolia pilot version. It
-uses the non-streaming `POST /v1/chat/completions` path below and includes the
-loopback Responses bridge for Codex. The local `0.2.2` candidate adds local
-discovery of the pinned proving bundle and witness, validates them against the
-activated credential, and saves their paths for later runs. It is not yet
-published or part of the pinned pilot set. Neither version carries a Stellar
-or evaluation path. The proving artifacts
-(`private-credit-spend-bn254-dev-sepolia-v1`) are delivered directly through
-the invite channel, never from a public host.
+The pinned Base Sepolia trial version is `0.2.3`. It uses the non-streaming
+`POST /v1/chat/completions` path below, includes the loopback Responses bridge
+for Codex, and acquires the pinned private proving bundle through the local
+GitHub CLI session. It also synchronizes V2 Base events and checks the gateway
+known root before local setup completes. Neither this version nor the adapter
+supports a Stellar or evaluation path. The proving artifacts are available
+only from the private immutable release pinned by `circuits/manifest.json`.
 
 Verify the shipped artifacts before your first prove. The package's
 `circuits/manifest.json` fixes the SHA-256 of the frozen
@@ -59,46 +57,45 @@ still receives the class. A rejected request consumes no credit.
 
 ## First run
 
-1. Redeem an invite and download the encrypted credential. Credits are
-   founder-provisioned test credits; there is no payment step.
-2. Install `zk-credits` and ask your pilot contact for the pinned proving
-   bundle and public Base tree file. Put them in
-   `~/.zk-credits/artifacts/base-sepolia` and `~/.zk-credits/witnesses`, or
-   place them in `~/Downloads`. The package ships
-   `circuits/manifest.json`, which fixes the SHA-256 of the frozen
-   `private_credit_spend.wasm`, `private_credit_spend.zkey`, and
-   `verification_key_private_credit.json`. The sidecar never fetches proving
-   material at runtime. Set the credential and gateway:
+1. Redeem an invite and download the encrypted V2 credential export. Credits
+   are founder-provisioned test credits; there is no payment step.
+2. Ask the pilot contact for read access to the private bundle repository
+   `mangekyou-labs/zk-credits-base-sepolia-v2-bundle`, then authenticate the
+   GitHub CLI on this machine with `gh auth login`. The sidecar uses that local
+   GitHub CLI session to read the immutable release identified in
+   `circuits/manifest.json`; it never receives or stores your GitHub token.
+   Set the credential, gateway, and Base Sepolia RPC endpoint:
 
    ```bash
    export ZK_CREDITS_CREDENTIAL_PATH="$HOME/Downloads/zk-credits-credential.json"
    export ZK_CREDITS_GATEWAY_URL="https://zk-credits-gateway.onrender.com"
+   export BASE_RPC_URL="https://sepolia.base.org"
    ```
 
-   `zk-credits setup codex` searches those local folders, validates the bundle
-   hashes and witness for the activated credential, then saves the selected
-   local paths in `~/.zk-credits/config.json`. Set
-   `ZK_CREDITS_ARTIFACT_DIR` or `ZK_CREDITS_WITNESS_PATH` to select explicit
-   paths. Alternatively, set `BASE_RPC_URL` and
-   `BASE_PRIVATE_CREDIT_BOND_ADDRESS` (and optionally
-   `BASE_DEPLOYMENT_BLOCK`) to derive a witness from public Base events. Event
-   sync requires RPC access and is validated locally before setup completes.
-   The config file is owner-readable only and never stores the credential
-   password. If an RPC URL contains a provider key, it remains in that local
-   config file.
+   `zk-credits setup codex` searches the standard local folders first. If it
+   finds no valid bundle, it downloads the pinned release, verifies the
+   release id, tag, immutability, archive digest, and all three file digests,
+   then atomically installs the bundle under `~/.zk-credits/artifacts` with
+   owner-only permissions. Missing GitHub access or any mismatch stops setup.
+   It syncs public Base events from the pinned V2 bond and deployment block,
+   validates that the resulting witness resolves the activated credential,
+   and asks the gateway whether the resulting root is known. The witness and
+   event cache remain local. The package does not accept a supplied witness
+   file for this V2 deployment.
+
+   The package ships `circuits/manifest.json`, which fixes the immutable
+   release identity, the SHA-256 of the archive and each proving artifact, and
+   the V2 Base deployment pins. `BASE_PRIVATE_CREDIT_BOND_ADDRESS` and
+   `BASE_DEPLOYMENT_BLOCK` are optional checks; if set, they must match the
+   manifest. V2 setup rejects `ZK_CREDITS_WITNESS_PATH` because it builds the
+   witness from the pinned public Base events. The local setup config is
+   owner-readable only and never stores the credential password. If the RPC
+   URL contains a provider key, it remains in that local config file.
 
    A missing, relocated, symlinked-out, or altered artifact fails closed
    before the first prove. A hash mismatch is a proof failure: no payment
-   leaves, and the local slot stays reusable.
-
-   An explicit `ZK_CREDITS_WITNESS_PATH` points to a local witness artifact —
-   either a prepared witness (`root`, `pathElements`, `pathIndices`) or a
-   public tree (`leaves: [{ index, leaf, expiry? }]`, optional `root`) from
-   which the sidecar derives the depth-20 path — or configure `BASE_RPC_URL`,
-   `BASE_PRIVATE_CREDIT_BOND_ADDRESS`, and optionally `BASE_DEPLOYMENT_BLOCK`
-   so the sidecar synchronizes public `BundleFunded` events and builds a local
-   Merkle witness. The gateway never serves a path for a named leaf or
-   commitment.
+   leaves, and the local slot stays reusable. The gateway never serves a path
+   for a named leaf or commitment.
 
 3. Start setup. It verifies the credential, pinned artifact hashes, and
    witness locally, then prompts for the backup password without echo:

package/circuits/manifest.json

@@ -16,13 +16,30 @@
     },
     {
       "file": "private_credit_spend.zkey",
-      "sha256": "3afb378d832d646a7d207b7eecbbd33cf3b041b99274cb074bbe314ac0b79291"
+      "sha256": "7cc83e6df3f0c805d8b49d4063ee56a93123ff19acd49d639ff263588ef7a144"
     },
     {
       "file": "verification_key_private_credit.json",
-      "sha256": "eb0068396ae6a859e95af001589936b6a1cbcdf18947dccdbade6af0099487c2"
+      "sha256": "4844820509c32722c0c867f028a713df8a1b6478ff7376a80861e7dcbc9c51fc"
     }
   ],
+  "release": {
+    "repository": "mangekyou-labs/zk-credits-base-sepolia-v2-bundle",
+    "tag": "v2.0.0",
+    "releaseId": 397705951,
+    "assetName": "base-sepolia-v2.tar.gz",
+    "sha256": "dc60b3109b3d907e2b9e8c4253fb52e77400d763eb443968e8de3af6b7e0b709"
+  },
+  "deployment": {
+    "chainId": 84532,
+    "bondAddress": "0xcc1909dD30485d6D9a46e3d33cf04C1378b586Ab",
+    "deploymentBlock": "47372040",
+    "deploymentDomain": "84532",
+    "circuitId": "private-credit-spend-bn254-dev",
+    "verifyingKeyId": "private-credit-spend-vk-dev-sepolia-v2",
+    "spendVerifierAddress": "0x37663bC461AB8EccD3b7D69Bde7eeF13D489723e",
+    "groth16VerifierAddress": "0x5870117EA7ACb28B3f36fb64284b77c4eD2B7148"
+  },
   "publicSignals": ["root", "timestamp", "domain", "requestSignal", "nullifier", "share"],
-  "provingMaterial": "Development-only Sepolia artifacts. Complete an external production ceremony before mainnet."
+  "provingMaterial": "Development-only Sepolia artifacts, with one local phase-2 contribution. Complete an external production ceremony before mainnet."
 }

package/dist/artifact-bundle.d.ts

@@ -19,6 +19,23 @@ export interface PinnedArtifact {
     file: string;
     sha256: string;
 }
+export interface PinnedArtifactRelease {
+    repository: string;
+    tag: string;
+    releaseId: number;
+    assetName: string;
+    sha256: string;
+}
+export interface PinnedDeployment {
+    chainId: number;
+    bondAddress: string;
+    deploymentBlock: string;
+    deploymentDomain: string;
+    circuitId: string;
+    verifyingKeyId: string;
+    spendVerifierAddress: string;
+    groth16VerifierAddress: string;
+}
 export interface CircuitManifest {
     version: number;
     scheme: string;
@@ -31,6 +48,8 @@ export interface CircuitManifest {
         verificationKey: string;
     };
     artifacts: PinnedArtifact[];
+    release?: PinnedArtifactRelease;
+    deployment?: PinnedDeployment;
 }
 export interface PinnedArtifactBundle {
     directory: string;

package/dist/artifact-bundle.js

@@ -26,6 +26,8 @@ const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
 /** A pinned artifact is a bare file name, never a path or a remote location. */
 const SAFE_FILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
 const REMOTE_PATTERN = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//u;
+const ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/u;
+const RELEASE_REPOSITORY_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u;
 function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -51,6 +53,7 @@ export function parseCircuitManifest(value) {
     if (!isRecord(value.circuit))
         throw new ArtifactBundleError('artifact_manifest_malformed', 'Circuit manifest is missing the circuit block');
     const circuit = value.circuit;
+    const network = requiredString(value, 'network');
     const depth = circuit.depth;
     if (!Number.isSafeInteger(depth) || depth <= 0) {
         throw new ArtifactBundleError('artifact_manifest_malformed', 'Circuit depth must be a positive integer');
@@ -73,7 +76,7 @@ export function parseCircuitManifest(value) {
     const resolved = {
         version: 1,
         scheme: requiredString(value, 'scheme'),
-        network: requiredString(value, 'network'),
+        network,
         circuit: {
             id: requiredString(circuit, 'id'),
             depth: depth,
@@ -82,7 +85,12 @@ export function parseCircuitManifest(value) {
             verificationKey: pinnedFile(circuit.verificationKey, 'verificationKey'),
         },
         artifacts,
+        ...(value.release === undefined ? {} : { release: parseRelease(value.release) }),
+        ...(value.deployment === undefined ? {} : { deployment: parseDeployment(value.deployment, requiredString(circuit, 'id')) }),
     };
+    if (resolved.deployment && network !== 'eip155:84532') {
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Pinned V2 deployment must use Base Sepolia');
+    }
     const pinned = new Set(artifacts.map((artifact) => artifact.file));
     for (const role of ARTIFACT_HASHES) {
         const file = resolved.circuit[role];
@@ -92,6 +100,58 @@ export function parseCircuitManifest(value) {
     }
     return resolved;
 }
+function parseRelease(value) {
+    if (!isRecord(value)
+        || typeof value.repository !== 'string'
+        || !RELEASE_REPOSITORY_PATTERN.test(value.repository)
+        || typeof value.tag !== 'string'
+        || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(value.tag)
+        || !Number.isSafeInteger(value.releaseId)
+        || value.releaseId <= 0
+        || typeof value.assetName !== 'string'
+        || !SAFE_FILE_PATTERN.test(value.assetName)
+        || value.assetName.includes('..')
+        || typeof value.sha256 !== 'string'
+        || !SHA256_PATTERN.test(value.sha256)) {
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Circuit manifest release pin is malformed');
+    }
+    return {
+        repository: value.repository,
+        tag: value.tag,
+        releaseId: value.releaseId,
+        assetName: value.assetName,
+        sha256: value.sha256,
+    };
+}
+function parseDeployment(value, circuitId) {
+    if (!isRecord(value)
+        || value.chainId !== 84532
+        || typeof value.bondAddress !== 'string'
+        || !ADDRESS_PATTERN.test(value.bondAddress)
+        || typeof value.deploymentBlock !== 'string'
+        || !/^\d+$/u.test(value.deploymentBlock)
+        || typeof value.deploymentDomain !== 'string'
+        || value.deploymentDomain !== '84532'
+        || value.circuitId !== circuitId
+        || typeof value.verifyingKeyId !== 'string'
+        || value.verifyingKeyId.length === 0
+        || typeof value.spendVerifierAddress !== 'string'
+        || !ADDRESS_PATTERN.test(value.spendVerifierAddress)
+        || typeof value.groth16VerifierAddress !== 'string'
+        || !ADDRESS_PATTERN.test(value.groth16VerifierAddress)) {
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Circuit manifest V2 deployment pin is malformed');
+    }
+    return {
+        chainId: 84532,
+        bondAddress: value.bondAddress,
+        deploymentBlock: value.deploymentBlock,
+        deploymentDomain: value.deploymentDomain,
+        circuitId,
+        verifyingKeyId: value.verifyingKeyId,
+        spendVerifierAddress: value.spendVerifierAddress,
+        groth16VerifierAddress: value.groth16VerifierAddress,
+    };
+}
 /** Loads the manifest shipped inside this package unless the caller supplies one. */
 export async function loadCircuitManifest(manifestPath) {
     const path = manifestPath ?? resolve(dirname(fileURLToPath(import.meta.url)), '..', 'circuits', 'manifest.json');

package/dist/artifact-release.d.ts

@@ -0,0 +1,10 @@
+/** Authenticated, immutable-release acquisition for local proving material. */
+import type { CircuitManifest } from './artifact-bundle.js';
+export type GithubCommand = (arguments_: readonly string[]) => Promise<string>;
+export interface AcquirePinnedBundleOptions {
+    manifest: CircuitManifest;
+    targetDirectory: string;
+    runGithubCommand?: GithubCommand;
+}
+/** Fetches a pinned private GitHub release and atomically installs its safe USTAR bundle. */
+export declare function acquirePinnedArtifactBundle(options: AcquirePinnedBundleOptions): Promise<string>;

package/dist/artifact-release.js

@@ -0,0 +1,243 @@
+/** Authenticated, immutable-release acquisition for local proving material. */
+import { createHash, randomUUID } from 'node:crypto';
+import { execFile as nodeExecFile } from 'node:child_process';
+import { gunzipSync } from 'node:zlib';
+import { promisify } from 'node:util';
+import { chmod, lstat, mkdir, open, readFile, rename, rm, } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { resolvePinnedArtifactBundle } from './artifact-bundle.js';
+const execFile = promisify(nodeExecFile);
+const MAX_COMPRESSED_BYTES = 20 * 1024 * 1024;
+const MAX_EXPANDED_BYTES = 32 * 1024 * 1024;
+const BLOCK_BYTES = 512;
+const SAFE_TAR_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+function digest(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function zeroBlock(block) {
+    return block.every((byte) => byte === 0);
+}
+function tarText(header, start, length, label) {
+    const bytes = header.subarray(start, start + length);
+    const terminator = bytes.indexOf(0);
+    const value = bytes.subarray(0, terminator < 0 ? bytes.length : terminator);
+    if (!value.every((byte) => byte >= 0x20 && byte <= 0x7e)) {
+        throw new Error('Pinned proving bundle archive contains an invalid ' + label);
+    }
+    return value.toString('ascii');
+}
+function tarOctal(header, start, length, label) {
+    const value = tarText(header, start, length, label).trim();
+    if (!value)
+        return 0;
+    if (!/^[0-7]+$/u.test(value))
+        throw new Error('Pinned proving bundle archive has an invalid ' + label);
+    const parsed = Number.parseInt(value, 8);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        throw new Error('Pinned proving bundle archive has an invalid ' + label);
+    return parsed;
+}
+function parseTar(archive, allowedNames) {
+    if (archive.length === 0 || archive.length > MAX_EXPANDED_BYTES || archive.length % BLOCK_BYTES !== 0) {
+        throw new Error('Pinned proving bundle archive has an invalid size');
+    }
+    const files = new Map();
+    let offset = 0;
+    let endBlocks = 0;
+    while (offset + BLOCK_BYTES <= archive.length) {
+        const header = archive.subarray(offset, offset + BLOCK_BYTES);
+        if (zeroBlock(header)) {
+            endBlocks += 1;
+            offset += BLOCK_BYTES;
+            if (endBlocks === 2)
+                break;
+            continue;
+        }
+        if (endBlocks > 0)
+            throw new Error('Pinned proving bundle archive has a malformed end marker');
+        const recordedChecksum = tarOctal(header, 148, 8, 'header checksum');
+        const checksumHeader = Buffer.from(header);
+        checksumHeader.fill(0x20, 148, 156);
+        const actualChecksum = checksumHeader.reduce((sum, byte) => sum + byte, 0);
+        if (recordedChecksum !== actualChecksum)
+            throw new Error('Pinned proving bundle archive failed its header checksum');
+        const magic = header.subarray(257, 263).toString('ascii');
+        if (magic !== 'ustar\0' && magic !== 'ustar ') {
+            throw new Error('Pinned proving bundle archive must use the USTAR format');
+        }
+        const name = tarText(header, 0, 100, 'entry name');
+        const prefix = tarText(header, 345, 155, 'entry prefix');
+        if (!name || prefix || !SAFE_TAR_NAME.test(name) || name.includes('..') || !allowedNames.has(name)) {
+            throw new Error('Pinned proving bundle archive contains an unexpected entry');
+        }
+        const type = header[156];
+        if (type !== 0 && type !== 0x30)
+            throw new Error('Pinned proving bundle archive contains a non-file entry');
+        if (tarText(header, 157, 100, 'link target'))
+            throw new Error('Pinned proving bundle archive contains a link');
+        if (files.has(name))
+            throw new Error('Pinned proving bundle archive contains a duplicate entry');
+        const size = tarOctal(header, 124, 12, 'entry size');
+        const dataStart = offset + BLOCK_BYTES;
+        const dataEnd = dataStart + size;
+        const paddedEnd = dataStart + Math.ceil(size / BLOCK_BYTES) * BLOCK_BYTES;
+        if (size <= 0 || dataEnd > archive.length || paddedEnd > archive.length) {
+            throw new Error('Pinned proving bundle archive entry exceeds its bounds');
+        }
+        if (!zeroBlock(archive.subarray(dataEnd, paddedEnd))) {
+            throw new Error('Pinned proving bundle archive has invalid entry padding');
+        }
+        files.set(name, Buffer.from(archive.subarray(dataStart, dataEnd)));
+        offset = paddedEnd;
+    }
+    if (endBlocks !== 2)
+        throw new Error('Pinned proving bundle archive is missing its end marker');
+    if (!zeroBlock(archive.subarray(offset)))
+        throw new Error('Pinned proving bundle archive has trailing data');
+    if (files.size !== allowedNames.size || [...allowedNames].some((name) => !files.has(name))) {
+        throw new Error('Pinned proving bundle archive is incomplete');
+    }
+    return files;
+}
+async function defaultGithubCommand(arguments_) {
+    try {
+        const { stdout } = await execFile('gh', [...arguments_], {
+            encoding: 'utf8',
+            timeout: 60_000,
+            maxBuffer: 2 * 1024 * 1024,
+            windowsHide: true,
+        });
+        return stdout;
+    }
+    catch {
+        throw new Error('Pinned proving release could not be read; authenticate with gh and confirm repository access.');
+    }
+}
+function pinnedAsset(release, raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Pinned proving release metadata is invalid');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Pinned proving release metadata is invalid');
+    }
+    const record = value;
+    const assets = Array.isArray(record.assets) ? record.assets : [];
+    const asset = assets.find((entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+        && entry.name === release.assetName);
+    if (record.id !== release.releaseId
+        || record.tag_name !== release.tag
+        || record.draft !== false
+        || record.immutable !== true
+        || !asset
+        || (typeof asset.digest === 'string' && asset.digest !== 'sha256:' + release.sha256)) {
+        throw new Error('Pinned proving release identity or immutability check failed');
+    }
+}
+async function writeBundleFile(directory, name, bytes) {
+    const file = await open(join(directory, name), 'wx', 0o600);
+    try {
+        await file.writeFile(bytes);
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+}
+async function replaceDirectoryAtomically(stage, target) {
+    const parent = dirname(target);
+    await mkdir(parent, { recursive: true, mode: 0o700 });
+    const backup = join(parent, '.base-sepolia-old-' + randomUUID());
+    let movedOld = false;
+    try {
+        try {
+            const existing = await lstat(target);
+            if (existing.isSymbolicLink() || !existing.isDirectory()) {
+                throw new Error('Local proving bundle destination must be a regular directory');
+            }
+            await rename(target, backup);
+            movedOld = true;
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+                // No previous bundle is a normal first-run case.
+            }
+            else {
+                throw error;
+            }
+        }
+        try {
+            await rename(stage, target);
+            await chmod(target, 0o700);
+        }
+        catch (error) {
+            if (movedOld)
+                await rename(backup, target);
+            throw error;
+        }
+        if (movedOld)
+            await rm(backup, { recursive: true, force: true }).catch(() => undefined);
+    }
+    finally {
+        await rm(stage, { recursive: true, force: true });
+    }
+}
+/** Fetches a pinned private GitHub release and atomically installs its safe USTAR bundle. */
+export async function acquirePinnedArtifactBundle(options) {
+    const release = options.manifest.release;
+    if (!release)
+        throw new Error('This sidecar manifest has no pinned artifact release');
+    const names = new Set(options.manifest.artifacts.map((artifact) => artifact.file));
+    const command = options.runGithubCommand ?? defaultGithubCommand;
+    const parent = dirname(resolve(options.targetDirectory));
+    const tempDirectory = join(parent, '.base-sepolia-download-' + randomUUID());
+    const stage = join(parent, '.base-sepolia-stage-' + randomUUID());
+    try {
+        await mkdir(parent, { recursive: true, mode: 0o700 });
+        await mkdir(tempDirectory, { recursive: false, mode: 0o700 });
+        await mkdir(stage, { recursive: false, mode: 0o700 });
+        const releaseJson = await command(['api', `repos/${release.repository}/releases/${release.releaseId}`]);
+        pinnedAsset(release, releaseJson);
+        await command([
+            'release', 'download', release.tag,
+            '--repo', release.repository,
+            '--dir', tempDirectory,
+            '--pattern', release.assetName,
+        ]);
+        const archivePath = join(tempDirectory, release.assetName);
+        const archiveInfo = await lstat(archivePath);
+        if (archiveInfo.isSymbolicLink() || !archiveInfo.isFile() || archiveInfo.size > MAX_COMPRESSED_BYTES) {
+            throw new Error('Pinned proving bundle archive is missing or too large');
+        }
+        const compressed = await readFile(archivePath);
+        if (digest(compressed) !== release.sha256)
+            throw new Error('Pinned proving bundle archive failed its SHA-256 check');
+        let expanded;
+        try {
+            expanded = gunzipSync(compressed, { maxOutputLength: MAX_EXPANDED_BYTES });
+        }
+        catch {
+            throw new Error('Pinned proving bundle archive is not a bounded gzip tarball');
+        }
+        const files = parseTar(expanded, names);
+        for (const [name, bytes] of files)
+            await writeBundleFile(stage, name, bytes);
+        await chmod(stage, 0o700);
+        await resolvePinnedArtifactBundle({ artifactDirectory: stage, manifest: options.manifest });
+        await replaceDirectoryAtomically(stage, resolve(options.targetDirectory));
+        await resolvePinnedArtifactBundle({ artifactDirectory: resolve(options.targetDirectory), manifest: options.manifest });
+        return resolve(options.targetDirectory);
+    }
+    catch (error) {
+        if (error instanceof Error && /^(Pinned proving|This sidecar manifest|Local proving bundle)/u.test(error.message))
+            throw error;
+        throw new Error('Pinned proving bundle acquisition failed; verify gh access and the published release pin.');
+    }
+    finally {
+        await rm(tempDirectory, { recursive: true, force: true });
+        await rm(stage, { recursive: true, force: true });
+    }
+}

package/dist/cli.js

@@ -173,10 +173,11 @@ non-streaming POST /v1/chat/completions; Codex Responses requests pass through
 the sidecar's bounded local compatibility bridge.
 "zk-credits trial-registered-adapter" runs one confirmed, billable internal
 trial request through the directly registered official x402 client adapter.
-Set ZK_CREDITS_CREDENTIAL_PATH before setup. The wizard searches Downloads and
-~/.zk-credits for the pinned bundle and local Base witness, validates both,
-then saves their paths locally. Alternatively, set ZK_CREDITS_ARTIFACT_DIR and
-ZK_CREDITS_WITNESS_PATH explicitly. Setup prompts for the credential password
+Set ZK_CREDITS_CREDENTIAL_PATH and BASE_RPC_URL before setup. For Base Sepolia
+V2, setup can download the immutable bundle pinned by the package manifest by
+using this machine's authenticated GitHub CLI session, then synchronizes the
+witness from the pinned public Base events and checks the resulting root with
+the gateway. It saves local paths and prompts for the credential password
 without echo; the encrypted export is decrypted only in local memory.`);
 }
 /** Loads the same credential, witness, proof, and durable ledger used by serve. */
@@ -258,6 +259,38 @@ async function readGatewayJson(url, headers) {
         return { status: null };
     }
 }
+async function requireGatewayKnownRoot(root) {
+    const origin = gatewayOrigin();
+    const token = process.env.BILLING_INTERNAL_TOKEN?.trim() || await readHiddenValue('Gateway admin token: ');
+    if (!token)
+        throw new Error('Base Sepolia V2 setup requires gateway admin access to check the activated credential root');
+    let response;
+    try {
+        response = await fetch(new URL('/v1/admin/root-known', origin), {
+            method: 'POST',
+            headers: {
+                accept: 'application/json',
+                authorization: `Bearer ${token}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ root }),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch {
+        throw new Error('The gateway could not confirm that the activated credential root is known');
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = undefined;
+    }
+    if (response.status !== 200 || !isRecord(body) || body.known !== true) {
+        throw new Error('The activated credential root is not in the gateway known-root set; stop setup and reconcile the V2 activation');
+    }
+}
 async function gatewayReadiness(origin) {
     const response = await readGatewayJson(new URL('/ready', origin), { accept: 'application/json' });
     const report = isRecord(response.body) ? response.body : undefined;
@@ -589,7 +622,9 @@ async function main() {
                 manifest,
                 validateWitness: async (source) => {
                     const provider = await witnessProviderForSource(source, join(stateDirectory(), 'base-event-sync.json'));
-                    validateBaseCreditWitness(await provider.witnessForCredential(credential));
+                    const witness = validateBaseCreditWitness(await provider.witnessForCredential(credential));
+                    if (manifest.deployment)
+                        await requireGatewayKnownRoot(witness.root);
                 },
                 chooseCandidate: chooseSetupCandidate,
             });

package/dist/setup-config.d.ts

@@ -24,6 +24,8 @@ export interface ResolveSetupInputsOptions {
     validateWitness(source: SetupWitnessSource): Promise<void>;
     /** Called only when more than one valid local candidate exists. */
     chooseCandidate?(kind: 'proving bundle' | 'witness file', candidates: readonly string[]): Promise<string>;
+    /** Test seam for clean-install acquisition; production uses gh-authenticated release download. */
+    acquireArtifactBundle?(targetDirectory: string, manifest: CircuitManifest): Promise<void>;
     workingDirectory?: string;
 }
 /** Finds only known local locations and validates both sources before setup continues. */