zk-credits 0.1.2 → 0.2.0

package/README.md

@@ -0,0 +1,210 @@
+# zk-credits
+
+Loopback sidecar that attaches a hash-pinned BN254 Groth16 proof to each
+coding-agent LLM request through the experimental x402 `zk-prepaid` scheme.
+Built for the invite-only, unpaid, experimental Base Sepolia pilot; credits
+are founder-provisioned test credits, and the circuit is not independently
+audited.
+
+```bash
+npm install --global zk-credits
+```
+
+## Pinned pilot versions
+
+The pilot supports exactly these versions. Do not substitute another, and do
+not mix versions between the sidecar, the adapter package, and the gateway:
+
+| Package | Version |
+| --- | --- |
+| `zk-credits` (this sidecar) | `0.2.0` |
+| `@zk-credits/x402-zk-prepaid` (adapter) | `0.1.0` |
+| `@zk-credits/shared` | `0.1.0` |
+
+`zk-credits@0.2.0` is a breaking release against the Base Sepolia pilot: it
+speaks only the non-streaming `POST /v1/chat/completions` service class below
+and carries no 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.
+
+Verify the shipped artifacts before your first prove. The package's
+`circuits/manifest.json` fixes the SHA-256 of the frozen
+`private_credit_spend.wasm`, `private_credit_spend.zkey`, and
+`verification_key_private_credit.json`; compute the digest of each delivered
+file and compare it to the manifest. A mismatch is a proof failure, and the
+sidecar refuses to prove rather than sending a payment. The founder compares
+the same digests against the delivered set before inviting you.
+
+## What one credit buys
+
+One credit buys one successfully committed response from the single service
+class `coding-deepseek-v4-flash-v1` (`deepseek/deepseek-v4-flash`). It is not
+an arbitrary API call, and the gateway enforces the class before it reserves
+the credit:
+
+- text messages, tool definitions, and tool calls, with one generated choice;
+- no streaming, images, files, audio, web plugins, model fallback,
+  client-selected routing, or unknown cost-affecting fields;
+- input capped at 16,000 UTF-8 bytes (counted conservatively, never below the
+  provider's token count), output at 4,000 tokens, request body at 256 KiB,
+  encrypted replay at 1 MiB, and upstream timeout at 120 seconds.
+
+The requested `model` field is ignored: the gateway always dispatches the
+class model, so an OpenAI-compatible client configured with any model name
+still receives the class. A rejected request consumes no credit.
+
+## First run
+
+1. Redeem an invite to the unpaid, experimental Base Sepolia pilot and
+   download the password-encrypted credential backup. Credits are
+   founder-provisioned test credits; there is no payment step.
+2. Install the pinned proving artifacts. 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 bytes are installed out of
+   band; the sidecar never fetches proving material at runtime:
+
+   ```bash
+   export ZK_CREDITS_ARTIFACT_DIR="$PWD/private-credit-bundle"
+   ls "$ZK_CREDITS_ARTIFACT_DIR"   # the three pinned files
+   ```
+
+   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.
+
+3. Configure the credential and a witness source:
+
+   ```bash
+   export ZK_CREDITS_CREDENTIAL_PATH="$PWD/credential.json"
+   export ZK_CREDITS_CREDENTIAL_PASSWORD='use-a-long-local-password'
+   ```
+
+   Set `ZK_CREDITS_WITNESS_PATH` 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.
+
+4. Run:
+
+   ```bash
+   zk-credits cline "summarize this repository"
+   zk-credits setup codex && zk-credits codex "summarize this repository"
+   ```
+
+The sidecar binds `127.0.0.1:3210` only. It does not modify `~/.cline` or
+`~/.codex`.
+
+## Supported route
+
+The pilot serves one spend path: non-streaming `POST /v1/chat/completions`
+on the loopback listener, either through this sidecar (the supported
+OpenAI-compatible client) or through an x402-native agent that explicitly
+registers the project `zk-prepaid` adapter. Generic x402 clients, unmodified
+agents, public facilitators, Bazaar, MCP, and the standard `exact` rail are
+unsupported; the sidecar never falls back to another rail.
+
+| Route | Auth | Purpose |
+| --- | --- | --- |
+| `GET /health` | none | Liveness for the local launcher |
+| `GET /v1/models` | local token | Codex model discovery |
+| `GET /metrics` | local token | Aggregate proof metrics (below) |
+| `POST /v1/chat/completions` | local token | The only proving and spend path |
+
+`/v1/responses`, Anthropic `/v1/messages`, streaming bodies (`stream`,
+`stream_options`), and a missing `model` are rejected with a `4xx` before any
+proof is attempted. Unknown paths return `404 unsupported_openai_path`. The
+sidecar never substitutes a model and never falls back to another rail.
+
+### Gateway responses and retries
+
+| Response | Meaning | What to do |
+| --- | --- | --- |
+| `402` | No usable authorization, or a stale or invalid one | Re-prove against the fresh challenge |
+| `409 claim_already_committed` | Your exact request already succeeded | Read `encryptedReplay` from the response, or fetch it from `POST /x402/replay`; do not re-prove |
+| `409 claim_commit_ambiguous` | The commit outcome is unknown | Retry the same request; never re-prove a different one |
+| `503 pilot_paused` | The operator paused the pilot | Wait. This is retryable, consumes no credit, and is not a proof failure |
+| `503 provider_spend_cap_exhausted` | The provider-spend cap paused the pilot | Wait for the operator to review. No credit was consumed |
+| `503 claim_store_unavailable` | Transient gateway fault | Retry with backoff |
+
+The gateway never asks you to re-prove for its own account. A `503` is
+retryable and free; a proof failure is local and never reaches the gateway.
+
+## Proof path
+
+- Local artifacts only, hash-pinned against the shipped manifest.
+- One prove at a time per sidecar process, in a terminable child-process
+  worker with a 10-second deadline. (snarkjs cannot run inside a Node
+  `worker_threads` worker: its `web-worker` polyfill re-enters itself there.)
+- Every proof is self-verified locally with the pinned verification key
+  before `PAYMENT-SIGNATURE` can be emitted, and its six public signals must
+  exactly match `[root, timestamp, domain, requestSignal, nullifier, share]`.
+- A failed attempt retries with the same slot, request signal, nonce,
+  response key, and gateway `issuedAt` while more than ten seconds remain in
+  the challenge window.
+- A slot is provisional during proving and recorded in the durable local
+  ledger (`$ZK_CREDITS_HOME/base-slots.json`) only after self-verification.
+  Proof misses, timeouts, hash failures, and verification failures release
+  it.
+
+## `GET /metrics`
+
+Aggregate only, authenticated with the same local token:
+
+```json
+{
+  "attempts": 12,
+  "successes": 11,
+  "failures": 1,
+  "retries": 1,
+  "failuresByCategory": { "timeout": 1, "artifact_hash_mismatch": 0, "...": 0 },
+  "hotProve": { "samples": 11, "p50Ms": 1180.4, "p95Ms": 1902.7 },
+  "updatedAt": "2026-09-20T14:00:00.000Z"
+}
+```
+
+The first prove in a process is the cold sample and is excluded from the hot
+percentiles. Proofs, public signals, nullifiers, credentials, requests, and
+any identifying label are never recorded or exposed.
+
+## Commands
+
+```
+zk-credits cline [cline arguments...]
+zk-credits setup codex [--model <model>]
+zk-credits codex [codex arguments...]
+zk-credits status
+zk-credits serve [--port <port>]
+eval "$(zk-credits env)"
+```
+
+Codex SDK:
+
+```ts
+import { buildCodexSdkOptions, buildCodexThreadOptions } from 'zk-credits/codex';
+```
+
+The credential secret is decrypted only in local memory. The sidecar cache
+contains public Base event leaves and never stores the secret, prompt, response,
+proof, account, or wallet.
+
+## Validation
+
+```bash
+npm test                                      # unit + fixture suites
+npm run build                                 # tsc + bundled CLI
+ZK_CREDITS_ARTIFACT_DIR="$PWD/circuits/artifacts" \
+  npx vitest run pinned-artifacts             # opt-in real fullProve + self-verify
+```
+
+The opt-in artifact test needs an installed bundle and the built
+`dist/proof-child.js`. CI stays deterministic through injected worker and
+crypto fixtures; the default suites stay green with no bundle installed.
+
+Base Sepolia only. The circuit is experimental and not independently audited.
+Development proving material is not suitable for mainnet; the repository's
+release gates require an audited production circuit and ceremony.

package/circuits/manifest.json

@@ -1,16 +1,28 @@
 {
+  "version": 1,
+  "scheme": "zk-prepaid",
+  "network": "eip155:84532",
+  "circuit": {
+    "id": "private-credit-spend-bn254-dev",
+    "depth": 20,
+    "wasm": "private_credit_spend.wasm",
+    "zkey": "private_credit_spend.zkey",
+    "verificationKey": "verification_key_private_credit.json"
+  },
   "artifacts": [
     {
-      "file": "rln_nullifier.wasm",
-      "sha256": "38370baebbafb76562d5c94e15354c04152c388bffe1bf85faeeb4dd221538c1"
+      "file": "private_credit_spend.wasm",
+      "sha256": "64da977cdbf3105a5948a6eb82cac610979e589558ddb1cd0419c460e7735c56"
     },
     {
-      "file": "rln_nullifier_final.zkey",
-      "sha256": "11cd9e881437283701dcebd75be469d57ec7428de3495d229268eb75f2413cc8"
+      "file": "private_credit_spend.zkey",
+      "sha256": "3afb378d832d646a7d207b7eecbbd33cf3b041b99274cb074bbe314ac0b79291"
     },
     {
-      "file": "verification_key_rln.json",
-      "sha256": "9a521e0e19dc272c281f1a41abf79571bb0094cda653c890bdd95aa5b4c5f1ee"
+      "file": "verification_key_private_credit.json",
+      "sha256": "eb0068396ae6a859e95af001589936b6a1cbcdf18947dccdbade6af0099487c2"
     }
-  ]
+  ],
+  "publicSignals": ["root", "timestamp", "domain", "requestSignal", "nullifier", "share"],
+  "provingMaterial": "Development-only Sepolia artifacts. Complete an external production ceremony before mainnet."
 }

package/dist/artifact-bundle.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Hash-pinned local proving artifacts.
+ *
+ * The sidecar never fetches proving material at runtime. The shipped manifest
+ * pins the SHA-256 of every artifact of one frozen bundle; the bytes are
+ * installed out of band next to the operator's state. A missing, relocated,
+ * swapped, or partially installed bundle fails closed before any prove.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export declare const ARTIFACT_HASHES: readonly ["wasm", "zkey", "verificationKey"];
+export type ArtifactRole = (typeof ARTIFACT_HASHES)[number];
+export type ArtifactFailure = 'artifact_remote' | 'artifact_missing' | 'artifact_escaped' | 'artifact_hash_mismatch' | 'artifact_manifest_malformed';
+export declare class ArtifactBundleError extends Error {
+    readonly category: ArtifactFailure;
+    constructor(category: ArtifactFailure, message: string);
+}
+export interface PinnedArtifact {
+    file: string;
+    sha256: string;
+}
+export interface CircuitManifest {
+    version: number;
+    scheme: string;
+    network: string;
+    circuit: {
+        id: string;
+        depth: number;
+        wasm: string;
+        zkey: string;
+        verificationKey: string;
+    };
+    artifacts: PinnedArtifact[];
+}
+export interface PinnedArtifactBundle {
+    directory: string;
+    circuitId: string;
+    depth: number;
+    wasmPath: string;
+    zkeyPath: string;
+    verificationKey: unknown;
+    artifacts: readonly PinnedArtifact[];
+}
+/** Parses the shipped manifest. Unknown pins and malformed hashes fail closed. */
+export declare function parseCircuitManifest(value: unknown): CircuitManifest;
+/** Loads the manifest shipped inside this package unless the caller supplies one. */
+export declare function loadCircuitManifest(manifestPath?: string): Promise<CircuitManifest>;
+/** The frozen verification key must describe the six-signal Groth16/BN254 ABI. */
+export declare function assertVerificationKeyShape(value: unknown, expectedPublicSignals: number): void;
+export interface ResolvePinnedBundleOptions {
+    /** Operator-installed directory that holds the frozen bytes. */
+    artifactDirectory: string;
+    manifest: CircuitManifest;
+    /** Public outputs of the circuits, checked against the verification key. */
+    expectedPublicSignals?: number;
+}
+/** Resolves one complete, hash-matching bundle or throws before any prove. */
+export declare function resolvePinnedArtifactBundle(options: ResolvePinnedBundleOptions): Promise<PinnedArtifactBundle>;

package/dist/artifact-bundle.js

@@ -0,0 +1,201 @@
+/**
+ * Hash-pinned local proving artifacts.
+ *
+ * The sidecar never fetches proving material at runtime. The shipped manifest
+ * pins the SHA-256 of every artifact of one frozen bundle; the bytes are
+ * installed out of band next to the operator's state. A missing, relocated,
+ * swapped, or partially installed bundle fails closed before any prove.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const ARTIFACT_HASHES = ['wasm', 'zkey', 'verificationKey'];
+export class ArtifactBundleError extends Error {
+    category;
+    constructor(category, message) {
+        super(message);
+        this.category = category;
+        this.name = 'ArtifactBundleError';
+    }
+}
+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;
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function requiredString(record, key) {
+    const value = record[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new ArtifactBundleError('artifact_manifest_malformed', `Circuit manifest field ${key} is required`);
+    }
+    return value;
+}
+function pinnedFile(value, label) {
+    if (typeof value !== 'string' || !SAFE_FILE_PATTERN.test(value) || value.includes('..')) {
+        throw new ArtifactBundleError('artifact_manifest_malformed', `Circuit manifest ${label} must be a bare file name`);
+    }
+    return value;
+}
+/** Parses the shipped manifest. Unknown pins and malformed hashes fail closed. */
+export function parseCircuitManifest(value) {
+    if (!isRecord(value))
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Circuit manifest must be an object');
+    if (value.version !== 1)
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Unsupported circuit manifest version');
+    if (!isRecord(value.circuit))
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Circuit manifest is missing the circuit block');
+    const circuit = value.circuit;
+    const depth = circuit.depth;
+    if (!Number.isSafeInteger(depth) || depth <= 0) {
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Circuit depth must be a positive integer');
+    }
+    if (!Array.isArray(value.artifacts) || value.artifacts.length === 0) {
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Circuit manifest must pin at least one artifact');
+    }
+    const artifacts = value.artifacts.map((artifact, index) => {
+        if (!isRecord(artifact))
+            throw new ArtifactBundleError('artifact_manifest_malformed', `Pinned artifact ${index} must be an object`);
+        const file = pinnedFile(artifact.file, `artifact ${index} file`);
+        if (typeof artifact.sha256 !== 'string' || !SHA256_PATTERN.test(artifact.sha256)) {
+            throw new ArtifactBundleError('artifact_manifest_malformed', `Pinned artifact ${file} must carry a lowercase SHA-256 digest`);
+        }
+        return { file, sha256: artifact.sha256 };
+    });
+    const unique = new Set(artifacts.map((artifact) => artifact.file));
+    if (unique.size !== artifacts.length)
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Pinned artifacts must be unique');
+    const resolved = {
+        version: 1,
+        scheme: requiredString(value, 'scheme'),
+        network: requiredString(value, 'network'),
+        circuit: {
+            id: requiredString(circuit, 'id'),
+            depth: depth,
+            wasm: pinnedFile(circuit.wasm, 'wasm'),
+            zkey: pinnedFile(circuit.zkey, 'zkey'),
+            verificationKey: pinnedFile(circuit.verificationKey, 'verificationKey'),
+        },
+        artifacts,
+    };
+    const pinned = new Set(artifacts.map((artifact) => artifact.file));
+    for (const role of ARTIFACT_HASHES) {
+        const file = resolved.circuit[role];
+        if (!pinned.has(file)) {
+            throw new ArtifactBundleError('artifact_manifest_malformed', `Circuit ${role} ${file} is not pinned with a SHA-256 digest`);
+        }
+    }
+    return resolved;
+}
+/** 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');
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        throw new ArtifactBundleError('artifact_missing', `Circuit manifest is missing at ${path}`);
+    }
+    try {
+        return parseCircuitManifest(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof ArtifactBundleError)
+            throw error;
+        throw new ArtifactBundleError('artifact_manifest_malformed', 'Circuit manifest is not valid JSON');
+    }
+}
+async function sha256File(path) {
+    const hash = createHash('sha256');
+    const stream = createReadStream(path);
+    for await (const chunk of stream)
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+/** The frozen verification key must describe the six-signal Groth16/BN254 ABI. */
+export function assertVerificationKeyShape(value, expectedPublicSignals) {
+    if (!isRecord(value))
+        throw new ArtifactBundleError('artifact_hash_mismatch', 'Verification key must be a JSON object');
+    const shape = value;
+    if (shape.protocol !== 'groth16' || shape.curve !== 'bn128' || shape.nPublic !== expectedPublicSignals) {
+        throw new ArtifactBundleError('artifact_hash_mismatch', `Verification key must be Groth16 on bn128 with ${expectedPublicSignals} public signals`);
+    }
+}
+function assertLocalDirectory(artifactDirectory) {
+    if (typeof artifactDirectory !== 'string' || artifactDirectory.length === 0) {
+        throw new ArtifactBundleError('artifact_missing', 'An artifact directory is required');
+    }
+    if (REMOTE_PATTERN.test(artifactDirectory)) {
+        throw new ArtifactBundleError('artifact_remote', 'Proving artifacts must be installed locally, never fetched');
+    }
+    if (!isAbsolute(artifactDirectory)) {
+        throw new ArtifactBundleError('artifact_missing', 'Artifact directory must be an absolute local path');
+    }
+    return resolve(artifactDirectory);
+}
+function assertWithinDirectory(directory, candidate, file) {
+    if (candidate !== directory && !candidate.startsWith(`${directory}${sep}`)) {
+        throw new ArtifactBundleError('artifact_escaped', `Artifact ${file} resolves outside the pinned artifact directory`);
+    }
+}
+/** Resolves one complete, hash-matching bundle or throws before any prove. */
+export async function resolvePinnedArtifactBundle(options) {
+    const directory = assertLocalDirectory(options.artifactDirectory);
+    const manifest = options.manifest;
+    let realDirectory;
+    try {
+        const info = await stat(directory);
+        if (!info.isDirectory())
+            throw new ArtifactBundleError('artifact_missing', 'Artifact directory is not a directory');
+        realDirectory = await realpath(directory);
+    }
+    catch (error) {
+        if (error instanceof ArtifactBundleError)
+            throw error;
+        throw new ArtifactBundleError('artifact_missing', `Artifact directory ${directory} is not installed`);
+    }
+    for (const artifact of manifest.artifacts) {
+        const path = join(directory, artifact.file);
+        let realFile;
+        try {
+            const info = await stat(path);
+            if (!info.isFile())
+                throw new ArtifactBundleError('artifact_missing', `Artifact ${artifact.file} is not a regular file`);
+            realFile = await realpath(path);
+        }
+        catch (error) {
+            if (error instanceof ArtifactBundleError)
+                throw error;
+            throw new ArtifactBundleError('artifact_missing', `Artifact ${artifact.file} is missing from the pinned bundle`);
+        }
+        assertWithinDirectory(realDirectory, realFile, artifact.file);
+        const digest = await sha256File(realFile);
+        if (digest !== artifact.sha256) {
+            throw new ArtifactBundleError('artifact_hash_mismatch', `Artifact ${artifact.file} does not match the pinned SHA-256 digest`);
+        }
+    }
+    const verificationKeyPath = join(directory, manifest.circuit.verificationKey);
+    let verificationKey;
+    try {
+        verificationKey = JSON.parse(await readFile(verificationKeyPath, 'utf8'));
+    }
+    catch {
+        throw new ArtifactBundleError('artifact_missing', `Verification key ${manifest.circuit.verificationKey} is not valid JSON`);
+    }
+    assertVerificationKeyShape(verificationKey, options.expectedPublicSignals ?? 6);
+    return {
+        directory,
+        circuitId: manifest.circuit.id,
+        depth: manifest.circuit.depth,
+        wasmPath: join(directory, manifest.circuit.wasm),
+        zkeyPath: join(directory, manifest.circuit.zkey),
+        verificationKey,
+        artifacts: manifest.artifacts,
+    };
+}

package/dist/base-event-sync.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Local Base event synchronization for sidecar Merkle witnesses.
+ *
+ * BundleFunded events are public chain data. The cache contains only indexed
+ * leaves, block continuity, and roots; credentials and request spend metadata
+ * never enter it.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { type Hex } from 'viem';
+import type { BaseWitnessProvider } from './base-sidecar.js';
+export interface BaseEventWitnessClient {
+    getBlockNumber(): Promise<bigint>;
+    getBlock(args: {
+        blockNumber: bigint;
+    }): Promise<{
+        hash?: Hex | null;
+    }>;
+    getLogs(args: unknown): Promise<readonly unknown[]>;
+}
+export interface BaseEventWitnessProviderOptions {
+    rpcUrl: string;
+    contractAddress: string;
+    deploymentBlock?: bigint;
+    confirmations?: bigint;
+    maxBlockRange?: bigint;
+    cachePath?: string;
+    /** Dependency injection for deterministic tests and embedded clients. */
+    client?: BaseEventWitnessClient;
+}
+/** Creates a witness provider that syncs finalized BundleFunded events. */
+export declare function createBaseEventWitnessProvider(options: BaseEventWitnessProviderOptions): BaseWitnessProvider;