zk-credits 0.2.1 → 0.2.2

package/README.md

@@ -17,15 +17,17 @@ not mix versions between the sidecar, the adapter package, and the gateway:
 
 | Package | Version |
 | --- | --- |
-| `zk-credits` (this sidecar) | `0.2.0` |
+| `zk-credits` (this sidecar) | `0.2.1` |
 | `@zk-credits/x402-zk-prepaid` (adapter) | `0.1.0` |
 | `@zk-credits/shared` | `0.1.0` |
 
-`zk-credits@0.2.0` is the currently published Base Sepolia pilot version. It
-uses the non-streaming `POST /v1/chat/completions` path below. The local
-`0.2.1` candidate adds a loopback Responses bridge for Codex and is reserved
-for the internal trial; it is not yet published or part of the pinned pilot
-set. Neither version carries a Stellar or evaluation path. The proving artifacts
+`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.
 
@@ -60,31 +62,43 @@ still receives the class. A rejected request consumes no credit.
 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. The package ships
+   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 paths to the downloaded files and gateway:
+   material at runtime. Set the credential and gateway:
 
    ```bash
    export ZK_CREDITS_CREDENTIAL_PATH="$HOME/Downloads/zk-credits-credential.json"
-   export ZK_CREDITS_ARTIFACT_DIR="/path/to/pinned-bundle"
-   export ZK_CREDITS_WITNESS_PATH="/path/to/base-tree.json"
    export ZK_CREDITS_GATEWAY_URL="https://zk-credits-gateway.onrender.com"
    ```
 
+   `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.
+
    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.
 
-   `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.
+   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.
 
 3. Start setup. It verifies the credential, pinned artifact hashes, and
    witness locally, then prompts for the backup password without echo:

package/dist/cli.js

@@ -17,17 +17,26 @@ import { runCliCommand } from './cli-runtime.js';
 import { createNodeSidecarLifecycle } from './node-sidecar-lifecycle.js';
 import { activateSidecarServer } from './server-startup.js';
 import { createLoopbackToken, sidecarStatePaths } from './sidecar-config.js';
+import { applySetupConfig, readSetupConfig, resolveSetupInputs, writeSetupConfig, } from './setup-config.js';
 import { ensureSidecarReady } from './sidecar-lifecycle.js';
 import { readLoopbackToken, writeLoopbackToken } from './sidecar-state.js';
 import { createSidecarServer } from './sidecar.js';
 import { runBaseRegisteredTrialExchange } from './base-registered-trial.js';
-import { setupPrerequisiteError } from './setup-preflight.js';
+import { loadCircuitManifest } from './artifact-bundle.js';
 import { BASE_SEPOLIA_NETWORK } from '@zk-credits/x402-zk-prepaid';
 const DEFAULT_GATEWAY_URL = 'https://zk-credits-gateway.onrender.com';
 const DEFAULT_PORT = 3210;
 function stateDirectory() {
     return process.env.ZK_CREDITS_HOME || join(homedir(), '.zk-credits');
 }
+function setupConfigPath(directory = stateDirectory()) {
+    return join(directory, 'config.json');
+}
+async function applySavedSetupConfig(environment, directory = stateDirectory()) {
+    const config = await readSetupConfig(setupConfigPath(directory));
+    if (config)
+        applySetupConfig(environment, config);
+}
 function loopbackBaseUrl() {
     const port = Number(process.env.ZK_CREDITS_SIDECAR_PORT || DEFAULT_PORT);
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
@@ -45,6 +54,45 @@ function readPort(args) {
     }
     return parsed;
 }
+async function chooseSetupCandidate(kind, candidates) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        const variable = kind === 'proving bundle' ? 'ZK_CREDITS_ARTIFACT_DIR' : 'ZK_CREDITS_WITNESS_PATH';
+        throw new Error('Found more than one valid local ' + kind + '. Rerun in an interactive terminal or set ' + variable + ' explicitly.');
+    }
+    const input = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log('Found multiple valid ' + kind + 's:');
+        candidates.forEach((candidate, index) => console.log('  ' + (index + 1) + ') ' + candidate));
+        const answer = await input.question('Select a number: ');
+        const index = Number(answer);
+        if (!Number.isInteger(index) || index < 1 || index > candidates.length) {
+            throw new Error('Choose one of the listed local candidates');
+        }
+        return candidates[index - 1];
+    }
+    finally {
+        input.close();
+    }
+}
+async function witnessProviderForSource(source, cachePath) {
+    if (source.kind === 'file') {
+        let value;
+        try {
+            value = JSON.parse(await readFile(source.path, 'utf8'));
+        }
+        catch {
+            throw new Error('The Base witness file could not be read as JSON');
+        }
+        return createFileWitnessProvider(value);
+    }
+    return createBaseEventWitnessProvider({
+        rpcUrl: source.rpcUrl,
+        contractAddress: source.contractAddress,
+        deploymentBlock: source.deploymentBlock === undefined ? undefined : BigInt(source.deploymentBlock),
+        confirmations: source.confirmations === undefined ? undefined : BigInt(source.confirmations),
+        cachePath,
+    });
+}
 /** Reads a password written to the private stdin pipe by the foreground CLI. */
 async function readCredentialPasswordFromStdin() {
     const chunks = [];
@@ -125,9 +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, ZK_CREDITS_ARTIFACT_DIR, and a local witness
-source before setup. Setup prompts for the credential password without echo;
-the encrypted export is decrypted only in local memory.`);
+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
+without echo; the encrypted export is decrypted only in local memory.`);
 }
 /** Loads the same credential, witness, proof, and durable ledger used by serve. */
 async function loadBaseClientRuntime(passwordInput) {
@@ -472,6 +522,10 @@ async function main() {
         printHelp();
         return;
     }
+    const sidecarHome = stateDirectory();
+    if (args[0] !== 'setup' && args[0] !== 'status' && args[0] !== 'env') {
+        await applySavedSetupConfig(process.env, sidecarHome);
+    }
     if (args[0] === 'serve') {
         const passwordFromStdin = args.includes('--credential-password-stdin')
             ? await readCredentialPasswordFromStdin()
@@ -483,19 +537,26 @@ async function main() {
         await trialRegisteredAdapter();
         return;
     }
-    const sidecarHome = stateDirectory();
     const statePaths = sidecarStatePaths(sidecarHome);
     const codexHome = resolveCodexHome(process.env, homedir());
     const cliEntryPath = process.argv[1];
     if (!cliEntryPath)
         throw new Error('Unable to resolve the zk-credits executable path');
+    let setupCredentialPassword;
     const lifecycle = createNodeSidecarLifecycle({
         loopbackBaseUrl: loopbackBaseUrl(),
         stateDirectory: sidecarHome,
         tokenPath: statePaths.tokenPath,
         logPath: statePaths.logPath,
         cliEntryPath,
-        readCredentialPassword: () => readHiddenValue('Credential backup password: '),
+        readCredentialPassword: async () => {
+            if (setupCredentialPassword !== undefined) {
+                const password = setupCredentialPassword;
+                setupCredentialPassword = undefined;
+                return password;
+            }
+            return readHiddenValue('Credential backup password: ');
+        },
     });
     const exitCode = await runCliCommand(args, {
         loopbackBaseUrl: loopbackBaseUrl(),
@@ -514,22 +575,25 @@ async function main() {
             }
         },
         validateSetupPrerequisites: async () => {
-            const prerequisiteError = setupPrerequisiteError(process.env);
-            if (prerequisiteError)
-                throw new Error(prerequisiteError);
-            const artifactDirectory = process.env.ZK_CREDITS_ARTIFACT_DIR;
-            if (!artifactDirectory?.trim())
-                throw new Error('ZK_CREDITS_ARTIFACT_DIR is required.');
-            const witnessPath = process.env.ZK_CREDITS_WITNESS_PATH;
-            if (witnessPath) {
-                try {
-                    const witnessFile = await readFile(witnessPath, 'utf8');
-                    createFileWitnessProvider(JSON.parse(witnessFile));
-                }
-                catch {
-                    throw new Error('The Base witness file could not be read. Check ZK_CREDITS_WITNESS_PATH.');
-                }
-            }
+            const credentialPath = process.env.ZK_CREDITS_CREDENTIAL_PATH;
+            if (!credentialPath?.trim())
+                throw new Error('Set ZK_CREDITS_CREDENTIAL_PATH to the encrypted browser export');
+            const password = await readHiddenValue('Credential backup password: ');
+            const credential = await readEncryptedCredential(credentialPath, password);
+            const manifest = await loadCircuitManifest();
+            const config = await resolveSetupInputs({
+                environment: process.env,
+                homeDirectory: homedir(),
+                stateDirectory: sidecarHome,
+                configPath: setupConfigPath(sidecarHome),
+                manifest,
+                validateWitness: async (source) => {
+                    const provider = await witnessProviderForSource(source, join(stateDirectory(), 'base-event-sync.json'));
+                    validateBaseCreditWitness(await provider.witnessForCredential(credential));
+                },
+                chooseCandidate: chooseSetupCandidate,
+            });
+            const artifactDirectory = config.artifactDirectory;
             try {
                 await createPinnedBaseProofGenerator({
                     artifactDirectory,
@@ -541,6 +605,11 @@ async function main() {
                     throw new Error(`Pinned proving bundle check failed: ${error.message}`);
                 throw new Error('Pinned proving bundle check failed. Reinstall the bundle from your pilot invite.');
             }
+            await writeSetupConfig(setupConfigPath(sidecarHome), config);
+            applySetupConfig(process.env, config);
+            setupCredentialPassword = password;
+            console.log('Pinned proving bundle and witness validated for this activated credential.');
+            console.log('Local setup paths saved to ' + setupConfigPath(sidecarHome));
         },
         configureCodex: async (model) => {
             await writeCodexProfile({ codexHome, loopbackBaseUrl: loopbackBaseUrl(), model });

package/dist/setup-config.d.ts

@@ -0,0 +1,36 @@
+import { type CircuitManifest } from './artifact-bundle.js';
+export type SetupWitnessSource = {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'base-events';
+    rpcUrl: string;
+    contractAddress: string;
+    deploymentBlock?: string;
+    confirmations?: string;
+};
+export interface SetupConfig {
+    version: 1;
+    artifactDirectory: string;
+    witness: SetupWitnessSource;
+}
+export interface ResolveSetupInputsOptions {
+    environment: NodeJS.ProcessEnv;
+    homeDirectory: string;
+    stateDirectory: string;
+    configPath: string;
+    manifest: CircuitManifest;
+    /** Must prove this source resolves a valid witness for the activated credential. */
+    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>;
+    workingDirectory?: string;
+}
+/** Finds only known local locations and validates both sources before setup continues. */
+export declare function resolveSetupInputs(options: ResolveSetupInputsOptions): Promise<SetupConfig>;
+/** Reads the operator-local setup config. Missing config is normal on first run. */
+export declare function readSetupConfig(path: string): Promise<SetupConfig | undefined>;
+/** Atomically writes paths and witness configuration with owner-only permissions. */
+export declare function writeSetupConfig(path: string, config: SetupConfig): Promise<void>;
+/** Applies saved paths to a process environment while preserving explicit overrides. */
+export declare function applySetupConfig(environment: NodeJS.ProcessEnv, config: SetupConfig): void;

package/dist/setup-config.js

@@ -0,0 +1,320 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { resolvePinnedArtifactBundle } from './artifact-bundle.js';
+const WITNESS_FILENAMES = new Set([
+    'base-tree.json',
+    'base-sepolia-tree.json',
+    'base-tree-artifact.json',
+    'public-tree.json',
+    'base-witness.json',
+    'zk-credits-witness.json',
+    'witness.json',
+    'tree.json',
+]);
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function absolutePath(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error('Setup configuration ' + label + ' is required');
+    }
+    return resolve(value);
+}
+function optionalUnsignedString(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !/^\d+$/u.test(value)) {
+        throw new Error('Local setup config ' + label + ' must be a non-negative integer');
+    }
+    return value;
+}
+function parseSetupConfig(value) {
+    if (!isRecord(value) || value.version !== 1 || !isRecord(value.witness)) {
+        throw new Error('Local setup config is malformed; remove ~/.zk-credits/config.json and run setup again.');
+    }
+    const artifactDirectory = absolutePath(value.artifactDirectory, 'artifactDirectory');
+    const witnessValue = value.witness;
+    let witness;
+    if (witnessValue.kind === 'file') {
+        witness = { kind: 'file', path: absolutePath(witnessValue.path, 'witness.path') };
+    }
+    else if (witnessValue.kind === 'base-events') {
+        if (typeof witnessValue.rpcUrl !== 'string' || !/^https?:\/\//u.test(witnessValue.rpcUrl)) {
+            throw new Error('Local setup config has an invalid Base RPC URL');
+        }
+        if (typeof witnessValue.contractAddress !== 'string' || !/^0x[0-9a-fA-F]{40}$/u.test(witnessValue.contractAddress)) {
+            throw new Error('Local setup config has an invalid Base bond contract address');
+        }
+        const deploymentBlock = optionalUnsignedString(witnessValue.deploymentBlock, 'deploymentBlock');
+        const confirmations = optionalUnsignedString(witnessValue.confirmations, 'confirmations');
+        witness = {
+            kind: 'base-events',
+            rpcUrl: witnessValue.rpcUrl,
+            contractAddress: witnessValue.contractAddress,
+            ...(deploymentBlock === undefined ? {} : { deploymentBlock }),
+            ...(confirmations === undefined ? {} : { confirmations }),
+        };
+    }
+    else {
+        throw new Error('Local setup config has an unknown witness source');
+    }
+    return { version: 1, artifactDirectory, witness };
+}
+function optionalEnvironmentInteger(environment, name) {
+    const value = environment[name]?.trim();
+    if (!value)
+        return undefined;
+    if (!/^\d+$/u.test(value))
+        throw new Error(name + ' must be a non-negative integer');
+    return value;
+}
+async function candidateDirectories(homeDirectory, stateDirectory) {
+    const roots = [
+        join(stateDirectory, 'artifacts', 'base-sepolia'),
+        join(homeDirectory, '.zk-credits', 'artifacts', 'base-sepolia'),
+        join(homeDirectory, 'Downloads'),
+    ];
+    const candidates = [...roots];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                candidates.push(join(root, entry.name));
+        }
+    }
+    return [...new Set(candidates.map((path) => resolve(path)))];
+}
+async function chooseOne(kind, candidates, chooseCandidate) {
+    if (candidates.length === 1)
+        return candidates[0];
+    if (!chooseCandidate) {
+        const variable = kind === 'proving bundle' ? 'ZK_CREDITS_ARTIFACT_DIR' : 'ZK_CREDITS_WITNESS_PATH';
+        throw new Error('Found more than one valid ' + kind + '; set ' + variable + ' to choose one.');
+    }
+    const selected = await chooseCandidate(kind, candidates);
+    if (!candidates.includes(resolve(selected))) {
+        throw new Error('The selected ' + kind + ' is not one of the validated local candidates');
+    }
+    return resolve(selected);
+}
+async function resolveArtifactDirectory(options, saved) {
+    const explicit = options.environment.ZK_CREDITS_ARTIFACT_DIR?.trim();
+    const candidates = explicit
+        ? [resolve(options.workingDirectory ?? process.cwd(), explicit)]
+        : [
+            ...(saved ? [saved.artifactDirectory] : []),
+            ...await candidateDirectories(options.homeDirectory, options.stateDirectory),
+        ];
+    const valid = new Map();
+    let explicitError;
+    for (const candidate of candidates) {
+        try {
+            const bundle = await resolvePinnedArtifactBundle({
+                artifactDirectory: candidate,
+                manifest: options.manifest,
+            });
+            let identity = resolve(bundle.directory);
+            try {
+                identity = await realpath(bundle.directory);
+            }
+            catch { /* resolve already validated the directory */ }
+            valid.set(identity, bundle.directory);
+        }
+        catch (error) {
+            if (explicit)
+                explicitError = error;
+        }
+    }
+    if (explicit && valid.size === 0) {
+        const reason = explicitError instanceof Error ? ' ' + explicitError.message : '';
+        throw new Error('The configured proving bundle at ' + explicit + ' failed its pinned checks.' + reason);
+    }
+    if (valid.size === 0) {
+        throw new Error('Could not find a valid pinned proving bundle. Extract the bundle from your pilot contact into ~/.zk-credits/artifacts/base-sepolia or ~/Downloads, or set ZK_CREDITS_ARTIFACT_DIR.');
+    }
+    const selected = await chooseOne('proving bundle', [...valid.values()], options.chooseCandidate);
+    return resolve(selected);
+}
+function eventSourceFromEnvironment(environment) {
+    const rpcUrl = environment.BASE_RPC_URL?.trim();
+    const contractAddress = environment.BASE_PRIVATE_CREDIT_BOND_ADDRESS?.trim();
+    if (!rpcUrl || !contractAddress)
+        return undefined;
+    const deploymentBlock = optionalEnvironmentInteger(environment, 'BASE_DEPLOYMENT_BLOCK');
+    const confirmations = optionalEnvironmentInteger(environment, 'BASE_CONFIRMATIONS');
+    return {
+        kind: 'base-events',
+        rpcUrl,
+        contractAddress,
+        ...(deploymentBlock === undefined ? {} : { deploymentBlock }),
+        ...(confirmations === undefined ? {} : { confirmations }),
+    };
+}
+function witnessCandidates(homeDirectory, stateDirectory) {
+    const roots = [
+        join(stateDirectory, 'witnesses'),
+        join(stateDirectory, 'witness'),
+        join(homeDirectory, '.zk-credits', 'witnesses'),
+        join(homeDirectory, 'Downloads'),
+    ];
+    return [...new Set(roots.flatMap((root) => [...WITNESS_FILENAMES].map((name) => resolve(root, name))))];
+}
+async function resolveWitnessSource(options, saved) {
+    const environment = options.environment;
+    const explicitPath = environment.ZK_CREDITS_WITNESS_PATH?.trim();
+    if (explicitPath) {
+        const source = {
+            kind: 'file',
+            path: resolve(options.workingDirectory ?? process.cwd(), explicitPath),
+        };
+        try {
+            await options.validateWitness(source);
+            return source;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? ' ' + error.message : '';
+            throw new Error('The configured Base witness at ' + explicitPath + ' failed validation.' + reason);
+        }
+    }
+    const environmentSource = eventSourceFromEnvironment(environment);
+    if (environmentSource) {
+        try {
+            await options.validateWitness(environmentSource);
+            return environmentSource;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? ' ' + error.message : '';
+            throw new Error('Base event witness sync failed.' + reason);
+        }
+    }
+    if (saved?.witness.kind === 'base-events') {
+        try {
+            await options.validateWitness(saved.witness);
+            return saved.witness;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? ' ' + error.message : '';
+            throw new Error('Saved Base event witness source failed validation.' + reason);
+        }
+    }
+    if (saved?.witness.kind === 'file') {
+        try {
+            await options.validateWitness(saved.witness);
+            return saved.witness;
+        }
+        catch {
+            // A saved local witness can become stale for a different activated credential.
+        }
+    }
+    const valid = [];
+    for (const path of witnessCandidates(options.homeDirectory, options.stateDirectory)) {
+        try {
+            const info = await lstat(path);
+            if (!info.isFile())
+                continue;
+            const source = { kind: 'file', path };
+            await options.validateWitness(source);
+            valid.push(path);
+        }
+        catch {
+            // Ignore absent, unrelated, and non-resolving local files while searching.
+        }
+    }
+    if (valid.length > 0) {
+        return { kind: 'file', path: await chooseOne('witness file', valid, options.chooseCandidate) };
+    }
+    throw new Error('Could not find a public Base witness for this credential. Put base-tree.json or witness.json in ~/.zk-credits/witnesses or ~/Downloads, set ZK_CREDITS_WITNESS_PATH, or configure BASE_RPC_URL and BASE_PRIVATE_CREDIT_BOND_ADDRESS.');
+}
+/** Finds only known local locations and validates both sources before setup continues. */
+export async function resolveSetupInputs(options) {
+    const saved = await readSetupConfig(options.configPath);
+    const artifactDirectory = await resolveArtifactDirectory(options, saved);
+    const witness = await resolveWitnessSource(options, saved);
+    return { version: 1, artifactDirectory, witness };
+}
+/** Reads the operator-local setup config. Missing config is normal on first run. */
+export async function readSetupConfig(path) {
+    let raw;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile())
+            throw new Error('Local setup config must be a regular file');
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        return parseSetupConfig(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error('Local setup config is not valid JSON; remove ~/.zk-credits/config.json and run setup again.');
+        }
+        throw error;
+    }
+}
+/** Atomically writes paths and witness configuration with owner-only permissions. */
+export async function writeSetupConfig(path, config) {
+    const normalized = parseSetupConfig(config);
+    const directory = dirname(resolve(path));
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const destination = resolve(path);
+    try {
+        const existing = await lstat(destination);
+        if (existing.isSymbolicLink())
+            throw new Error('Local setup config cannot be a symbolic link');
+    }
+    catch (error) {
+        if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    const temporary = join(directory, '.config-' + randomUUID() + '.tmp');
+    try {
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(normalized, null, 2) + '\n', 'utf8');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, destination);
+        await chmod(destination, 0o600);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Applies saved paths to a process environment while preserving explicit overrides. */
+export function applySetupConfig(environment, config) {
+    if (!environment.ZK_CREDITS_ARTIFACT_DIR?.trim()) {
+        environment.ZK_CREDITS_ARTIFACT_DIR = config.artifactDirectory;
+    }
+    if (config.witness.kind === 'file') {
+        if (!environment.ZK_CREDITS_WITNESS_PATH?.trim()) {
+            environment.ZK_CREDITS_WITNESS_PATH = config.witness.path;
+        }
+        return;
+    }
+    if (!environment.BASE_RPC_URL?.trim())
+        environment.BASE_RPC_URL = config.witness.rpcUrl;
+    if (!environment.BASE_PRIVATE_CREDIT_BOND_ADDRESS?.trim()) {
+        environment.BASE_PRIVATE_CREDIT_BOND_ADDRESS = config.witness.contractAddress;
+    }
+    if (!environment.BASE_DEPLOYMENT_BLOCK?.trim() && config.witness.deploymentBlock !== undefined) {
+        environment.BASE_DEPLOYMENT_BLOCK = config.witness.deploymentBlock;
+    }
+    if (!environment.BASE_CONFIRMATIONS?.trim() && config.witness.confirmations !== undefined) {
+        environment.BASE_CONFIRMATIONS = config.witness.confirmations;
+    }
+}