zk-credits 0.2.9 → 0.2.11

package/README.md

@@ -1,248 +1,84 @@
-> Release candidate `0.2.9` is prepared for owner publication. Registry commands
-> below apply after publication; the existing `0.2.8` lacks this flow.
-
 # 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 experimental Base Sepolia pilot. Product calls use
-founder-provisioned test credits and have no product payment step; the circuit
-is not independently audited. External research participants in slots A and C
-receive $25 for a 30-minute session regardless of setup success. That payment
-is not product revenue or willingness-to-pay evidence.
+API credits for Codex, Cline, and x402 agents. The local sidecar proves each
+spend and forwards your request to the gateway.
 
-```bash
-npm install --global zk-credits@0.2.9
-```
+Requires Node.js 20 or later. Runs on Base Sepolia.
 
-## Pinned pilot versions
+## Quick start
 
-The pilot supports exactly these versions. Do not substitute another, and do
-not mix versions between the sidecar, the adapter package, and the gateway:
+1. [Activate your credits](https://hazecredits.vercel.app) and download your activated credential.
+2. Install the package and configure a Base Sepolia RPC endpoint:
 
-| Package | Version |
-| --- | --- |
-| `zk-credits` (this sidecar) | `0.2.9` |
-| `@zk-credits/x402-zk-prepaid` (adapter) | `0.1.0` |
-| `@zk-credits/shared` | `0.1.0` |
-
-The pinned Base Sepolia trial version is `0.2.9`. It includes passwordless
-OS credential storage, the hash-pinned proving archive, public Base Sepolia RPC
-by default, a narrow Codex Responses bridge, and the request-aware x402 adapter.
-Setup validates the public chain witness and gateway-known root. No private
-GitHub repository access or recovery password is required for the new flow.
-
-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 provider streaming, images, files, audio, web search, model fallback,
-  client-selected routing, or unknown cost-affecting fields;
-- input capped at 128,000 UTF-8 byte units (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. Sign in at https://hazecredits.vercel.app and redeem your invite. Save and
-   reimport the passwordless recovery capsule, fund your pilot credential, then
-   download the activated credential. Anyone possessing these files can spend
-   their credits; keep them private.
-2. Import the activated file and validate setup:
-
-   ```bash
-   export ZK_CREDITS_CREDENTIAL_PATH="$HOME/Downloads/zk-credits-credential.json"
-   zk-credits setup codex
+   ```sh
+   npm install --global zk-credits
+   zk-credits config rpc
    ```
 
-   For your own x402 agent, use `zk-credits setup x402` instead. Setup installs
-   and verifies the packaged archive and artifact hashes, synchronizes public
-   Base events from the manifest-pinned bond and deployment block, and checks
-   the gateway-known root. Credentials enter OS secure storage: macOS Keychain,
-   Windows Credential Manager, or persistent Linux Secret Service. Storage
-   access approval may be needed; unavailable or denied storage fails closed.
-3. Review consent, choose your task, and run `zk-credits codex` or
-   `zk-credits x402-agent`. Subsequent launches use OS storage without a password
-   or import file. The activated download remains a private recovery backup.
-
-The RPC defaults to https://sepolia.base.org. If the public endpoint is limited,
-run `zk-credits config rpc` and enter your own Base Sepolia endpoint in the hidden
-local prompt. Saved settings stay owner-only; `BASE_RPC_URL` takes precedence.
-Provider keys must not appear in chat or evidence. No gateway admin token is
-needed for operator setup.
-
-Existing encrypted exports require `zk-credits setup codex --legacy` (or
-`setup x402 --legacy`) and their original password in a hidden local prompt.
-A missing or altered proving artifact fails closed before payment creation.
-Setup and proving stay local; no supplied witness file is accepted for the
-manifest-pinned V2 deployment.
-
-The sidecar binds `127.0.0.1:3210` only. It does not modify `~/.cline` or
-`~/.codex`.
-
-## Supported route
-
-The pilot serves one bounded upstream spend path: non-streaming
-`POST /v1/chat/completions`, either through this sidecar or through an
-x402-native agent that explicitly registers the project `zk-prepaid` adapter.
-The sidecar also accepts Codex `POST /v1/responses` requests with text input
-and function tools, translates them to that bounded chat request, and converts
-the committed result into Responses SSE events. It rejects unsupported fields
-before starting a proof. Generic x402 clients, 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 |
-| `POST /v1/responses` | local token | Codex bridge to the bounded chat spend path |
-
-The chat route rejects streaming bodies (`stream`, `stream_options`) and a
-missing `model` with a `4xx` before any proof. The Responses route requires
-`stream: true`, text-only message/function-call input, and the known Codex
-metadata fields; it rejects images, unsupported tools, and unknown controls
-before any proof. Its upstream request is always `stream: false`. Anthropic
-`/v1/messages` and 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"
-}
-```
+3. Import your credential and connect Codex:
+
+   ```sh
+   ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup codex
+   zk-credits codex
+   ```
 
-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.
+Setup stores your credential in OS secure storage. Keep your recovery file
+private: anyone with it can spend your credits.
 
 ## Commands
 
-```
-zk-credits cline [cline arguments...]
-zk-credits setup codex [--model <model>] [--legacy]
-zk-credits setup x402 [--legacy]
-zk-credits config rpc
-zk-credits codex [codex arguments...]
-zk-credits status
-zk-credits serve [--port <port>] [--internal-trial-one-proof]
-zk-credits x402-agent
-zk-credits founder-demo-agent
-zk-credits trial-registered-adapter
-eval "$(zk-credits env)"
+| Command | Purpose |
+| --- | --- |
+| `zk-credits setup codex` | Import a credential and configure Codex |
+| `zk-credits setup x402` | Prepare an x402 agent |
+| `zk-credits codex [args...]` | Start Codex with the local sidecar |
+| `zk-credits cline [args...]` | Start Cline with the local sidecar |
+| `zk-credits x402-agent` | Run the included x402 agent |
+| `zk-credits serve` | Run the sidecar in the foreground |
+| `zk-credits doctor` | Inspect the service, PID, setup, RPC source, and log location |
+| `zk-credits stop` | Stop the local sidecar |
+| `zk-credits status` | Check the Codex configuration and sidecar |
+| `zk-credits config rpc` | Save or change your Base Sepolia RPC endpoint |
+| `zk-credits --help` | Show command and troubleshooting guidance |
+
+`doctor` and `stop` are available in version 0.2.11. They work before setup.
+The default port is `3210`; set `ZK_CREDITS_SIDECAR_PORT` to select another port.
+Automatic startup logs are saved to `~/.zk-credits/sidecar.log`, or
+`$ZK_CREDITS_HOME/sidecar.log` when set.
+
+## Troubleshooting
+
+**Sidecar stopped or setup missing:** Run `zk-credits doctor`. If setup is
+missing, import your activated credential with the setup command above.
+Otherwise run `zk-credits serve` and read its output.
+
+**Port occupied or “Server is not running”:** `x402-agent` starts its own local
+server. Run `zk-credits stop` before switching from `serve` to `x402-agent`.
+For older versions, inspect the listener before stopping it:
+
+```sh
+lsof -nP -iTCP:3210 -sTCP:LISTEN
+ps -p <PID> -o pid,ppid,etime,command
+kill -TERM <PID>
 ```
 
-`serve --internal-trial-one-proof` is an opt-in maintainer mode for the
-internal Base Sepolia trial. During that process lifetime, one authenticated,
-valid spend request may reach the prepaid transport and the proof factory may
-attempt one proof. A later valid request receives HTTP 409 with
-`internal_trial_limit_reached`; ordinary `serve` behavior is unchanged without
-the flag.
-
-`trial-registered-adapter` is a maintainer-only internal trial command. It
-requires the locally recovered credential and pinned proving bundle, prompts
-for the credential password and gateway admin token without echo when they are
-not already configured, and requires an explicit confirmation before sending
-one billable request. It checks gateway readiness, authenticated admin status,
-Base root agreement, Codex profile/sidecar status, and remaining local slot
-capacity, then reports only the exchange phases and aggregate counter deltas.
-Run it only after recovery is complete and with the same `ZK_CREDITS_HOME`
-used by the sidecar; it registers `zk-prepaid` directly through the official
-x402 client adapter and reuses the durable slot ledger.
-
-Codex SDK:
-
-```ts
-import { buildCodexSdkOptions, buildCodexThreadOptions } from 'zk-credits/codex';
-```
+Check the PID and command to confirm it is your sidecar. For a foreground
+process, press Ctrl+C. `stop` authenticates the service and lets active requests
+finish before exit.
 
-`zk-credits/x402` exports `createLocalX402Agent` for an operator who is
-integrating the adapter into their own x402 agent. It loads the same local
-credential, pinned proof artifacts, public witness, proof engine, and slot
-ledger used by the sidecar. The request-aware client binds the actual method,
-URL, and body into each spend; its metrics endpoint exposes authenticated
-aggregate counters on loopback. See
-[`docs/onboarding/base-zk-credits-x402-agent.md`](../../docs/onboarding/base-zk-credits-x402-agent.md)
-for integration and measured-call steps. The included `zk-credits x402-agent`
-command is a small task-running starter for the founder demo and local
-rehearsal; external slot C uses their own agent.
-
-The credential secret is loaded from OS secure storage only into 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
-```
+**Base witness synchronization failed:** Run `zk-credits config rpc` and enter
+a Base Sepolia endpoint (chain ID `84532`). Stop and restart the sidecar, or
+retry setup if it failed. `BASE_RPC_URL` overrides the saved endpoint.
+A missing funded credential or rejected root can require activation checks;
+changing the RPC may not resolve it.
+
+## Clients and privacy
+
+Codex and Cline use the local OpenAI-compatible transport. Your own x402 agent
+must register the custom `zk-prepaid` adapter; generic x402 clients do not
+support this scheme automatically. See the [x402 integration guide](https://github.com/mangekyou-labs/haze-api/blob/main/docs/onboarding/base-zk-credits-x402-agent.md).
 
-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.
+Your credential stays on your device. Proofs are sent to authorize each spend. The gateway and model provider receive request content and
+can observe traffic metadata. This does not hide your IP address.
 
-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.
+Base Sepolia test credits only. The circuit is not independently audited.

package/dist/cli.js

@@ -15,6 +15,7 @@ import { createZkPrepaidLifecycleMetrics } from '@zk-credits/x402-zk-prepaid';
 import { BaseSlotLedger } from './slot-ledger.js';
 import { nativeCredentialStore, importCredentialPath, readStoredCredential } from './credential-store.js';
 import { applyRpcConfig, checkBaseSepoliaRpc, writeRpcConfig, RPC_GUIDANCE, resolveBaseSepoliaRpc } from './rpc-config.js';
+import { diagnoseSidecar, stopSidecar } from './sidecar-diagnostics.js';
 import { runCliCommand } from './cli-runtime.js';
 import { createNodeSidecarLifecycle } from './node-sidecar-lifecycle.js';
 import { activateSidecarServer } from './server-startup.js';
@@ -145,6 +146,8 @@ function printHelp() {
   zk-credits setup [codex|x402] [--legacy] [--model <model>]
   zk-credits codex [codex arguments...]
   zk-credits status
+  zk-credits doctor
+  zk-credits stop
   zk-credits serve [--port <port>] [--internal-trial-one-proof]
   zk-credits x402-agent
   zk-credits founder-demo-agent
@@ -159,12 +162,24 @@ the request-aware x402 adapter and local proof engine. It requires explicit
 confirmation before one billable internal exchange; the task and response are
 displayed locally and never added to activation evidence.
 "zk-credits x402-agent" is a small task-running starter for the participant's
-own x402 agent loop. It asks for tasks locally and sends each through the same
+own x402 agent loop. It starts its own metrics server on the selected sidecar port;
+stop an existing sidecar before launching it. It asks for tasks locally and sends each through the same
 request-aware adapter and local proof engine; aggregate metrics stay on the
 loopback-only authenticated endpoint.
 "zk-credits serve --internal-trial-one-proof" limits this sidecar process to
 one authenticated, valid spend request and one local proof attempt.
-Base Sepolia uses https://sepolia.base.org automatically. Public RPC endpoints
+"zk-credits doctor" reports health, authenticated PID, setup and RPC configuration
+presence, and log location without starting a server or revealing secrets.
+"zk-credits stop" gracefully drains the authenticated sidecar. For older versions,
+inspect the listener with lsof -nP -iTCP:3210 -sTCP:LISTEN, verify its PID with
+ps -p <PID> -o pid,ppid,etime,command, then kill -TERM <PID>. Foreground: Ctrl+C.
+Use ZK_CREDITS_SIDECAR_PORT for doctor, stop, status and env with a custom port.
+If serve reports missing setup, run:
+  ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup
+If the sidecar is stopped after setup, run zk-credits serve.
+For RPC witness synchronization failures, run zk-credits config rpc and then
+zk-credits stop followed by zk-credits serve. BASE_RPC_URL overrides the saved RPC.
+Base Sepolia uses the launch endpoint baked into the package automatically. RPC endpoints
 are rate-limited; run "zk-credits config rpc" to use your own endpoint.
 Provider guide: https://docs.base.org/base-chain/node-operators/node-providers
 Set ZK_CREDITS_CREDENTIAL_PATH to the activated browser download for first setup.
@@ -182,7 +197,7 @@ async function loadBaseClientRuntime() {
     const witnessPath = process.env.ZK_CREDITS_WITNESS_PATH;
     const artifactDirectory = process.env.ZK_CREDITS_ARTIFACT_DIR;
     if (!artifactDirectory) {
-        throw new Error('Set ZK_CREDITS_ARTIFACT_DIR to the directory holding the installed pinned proving bundle');
+        throw new Error('Proving bundle is not configured. Run zk-credits setup first; use ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup for first import. Run zk-credits doctor to inspect setup.');
     }
     const baseRpcUrl = process.env.BASE_RPC_URL;
     const baseContractAddress = process.env.BASE_PRIVATE_CREDIT_BOND_ADDRESS;
@@ -581,6 +596,12 @@ async function serve(args) {
         prepaidClient: prepaid.client,
         internalTrialOneProof,
         metrics: () => ({ ...proofMetrics.snapshot(), exchange: exchangeMetrics.snapshot() }),
+        onShutdown: () => {
+            void shutdown().catch((error) => {
+                console.error(error instanceof Error ? error.message : 'Sidecar shutdown failed');
+                process.exitCode = 1;
+            });
+        },
     });
     let address;
     try {
@@ -595,20 +616,33 @@ async function serve(args) {
     }
     console.log(`ZK Credits sidecar listening on ${address}/v1`);
     console.log('Run eval "$(zk-credits env)" in the client shell.');
-    const shutdown = async () => {
-        await sidecar.close();
-        process.exit(0);
+    let shutdownPromise;
+    const shutdown = () => {
+        shutdownPromise ??= sidecar.close().then(() => { process.exit(0); });
+        return shutdownPromise;
     };
     process.once('SIGINT', () => { void shutdown(); });
     process.once('SIGTERM', () => { void shutdown(); });
 }
 async function main() {
     const args = process.argv.slice(2);
-    if (args[0] === '--help' || args[0] === '-h' || !args[0]) {
+    const localHelp = ['doctor', 'stop', 'status', 'serve', 'setup', 'config'].includes(args[0] ?? '')
+        && args.slice(1).some((arg) => arg === '--help' || arg === '-h');
+    if (args[0] === '--help' || args[0] === '-h' || !args[0] || localHelp) {
         printHelp();
         return;
     }
     const sidecarHome = stateDirectory();
+    if (args[0] === 'doctor' || args[0] === 'stop') {
+        if (args.length !== 1)
+            throw new Error(`Usage: zk-credits ${args[0]} (use ZK_CREDITS_SIDECAR_PORT to select a port)`);
+        const options = { baseUrl: loopbackBaseUrl(), stateDirectory: sidecarHome, write: (line) => console.log(line) };
+        if (args[0] === 'doctor')
+            await diagnoseSidecar(options);
+        else
+            await stopSidecar(options);
+        return;
+    }
     if (args[0] === 'config' && args[1] === 'rpc' && args.length === 2) {
         console.log(RPC_GUIDANCE);
         const rpc = await checkBaseSepoliaRpc(await readHiddenValue('Base Sepolia RPC URL (hidden): '));
@@ -717,6 +751,11 @@ async function main() {
         process.exitCode = exitCode;
 }
 void main().catch((error) => {
-    console.error(error instanceof Error ? error.message : 'zk-credits failed');
+    if (error?.code === 'EADDRINUSE') {
+        console.error('The local port is already occupied. Run zk-credits doctor to identify the listener. Stop the existing sidecar with zk-credits stop (older sidecars: inspect the PID before kill -TERM <PID>), then retry. x402-agent starts its own local metrics server and does not reuse serve.');
+    }
+    else {
+        console.error(error instanceof Error ? error.message : 'zk-credits failed');
+    }
     process.exitCode = 1;
 });

package/dist/credential-store.js

@@ -46,7 +46,7 @@ export async function importStoredCredential(file, store, legacyPassword) {
 export async function readStoredCredential(store) {
     const raw = await store.read();
     if (!raw)
-        throw new Error('No credential in OS storage. Download your activated credential and run zk-credits setup first.');
+        throw new Error('No credential in OS storage. Download your activated credential and run zk-credits setup first: ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup.');
     try {
         const saved = JSON.parse(raw);
         if (saved.version !== 1 || !saved.credential)

package/dist/local-x402-agent.js

@@ -165490,7 +165490,7 @@ function nativeCredentialStore(stateDirectory) {
 async function readStoredCredential(store) {
   const raw = await store.read();
   if (!raw)
-    throw new Error("No credential in OS storage. Download your activated credential and run zk-credits setup first.");
+    throw new Error("No credential in OS storage. Download your activated credential and run zk-credits setup first: ZK_CREDITS_CREDENTIAL_PATH=/path/to/activated-credential.json zk-credits setup.");
   try {
     const saved = JSON.parse(raw);
     if (saved.version !== 1 || !saved.credential)
@@ -165511,11 +165511,14 @@ async function readStoredCredential(store) {
 // dist/rpc-config.js
 import { chmod, lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
-var DEFAULT_BASE_SEPOLIA_RPC_URL = "https://sepolia.base.org";
+var DEFAULT_BASE_SEPOLIA_RPC_URL = "https://base-sepolia.infura.io/v3/4d7561cbe56f49fe8cdf30d46f609806";
 function resolveBaseSepoliaRpc(environment, legacyRpc) {
-  return environment.BASE_RPC_URL?.trim() || legacyRpc?.trim() || DEFAULT_BASE_SEPOLIA_RPC_URL;
+  const rpc = environment.BASE_RPC_URL?.trim() || legacyRpc?.trim() || DEFAULT_BASE_SEPOLIA_RPC_URL;
+  if (rpc === "__ZK_CREDITS_RELEASE_RPC_URL__")
+    throw new Error("Release RPC has not been baked. Set BASE_RPC_URL or build the release package.");
+  return rpc;
 }
-var RPC_GUIDANCE = "The built-in public Base Sepolia endpoint is rate-limited. To use your own endpoint (chain ID 84532), run zk-credits config rpc. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
+var RPC_GUIDANCE = "The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. After changing the RPC, run zk-credits stop then zk-credits serve; retry setup if it has not completed. BASE_RPC_URL overrides the saved setting. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
 function validateRpcUrl(value) {
   try {
     const url = new URL(value.trim());
@@ -167308,6 +167311,23 @@ function createSidecarServer(options) {
       return;
     }
     const token = extractLocalToken(req);
+    if (req.method === "GET" && pathname === "/runtime" || req.method === "POST" && pathname === "/shutdown") {
+      if (token !== options.localToken) {
+        sendJson(res, 401, { error: "invalid_local_token" });
+        return;
+      }
+      if (pathname === "/runtime") {
+        sendJson(res, 200, { service: "zk-credits-sidecar", pid: process.pid });
+      } else if (options.onShutdown) {
+        res.once("finish", () => {
+          setImmediate(() => options.onShutdown());
+        });
+        sendJson(res, 202, { service: "zk-credits-sidecar", status: "stopping" });
+      } else {
+        sendJson(res, 404, { error: "shutdown_unavailable" });
+      }
+      return;
+    }
     if (req.method === "GET" && pathname === "/v1/models") {
       if (token !== options.localToken) {
         sendJson(res, 401, { error: "invalid_local_token" });
@@ -167406,6 +167426,10 @@ function createSidecarServer(options) {
         return;
       const activeServer = server;
       server = null;
+      if (!activeServer.listening) {
+        await Promise.all(inFlight);
+        return;
+      }
       await new Promise((resolve4, reject) => activeServer.close((error) => {
         if (error)
           reject(error);

package/dist/rpc-config.d.ts

@@ -1,6 +1,6 @@
-export declare const DEFAULT_BASE_SEPOLIA_RPC_URL = "https://sepolia.base.org";
+export declare const DEFAULT_BASE_SEPOLIA_RPC_URL = "__ZK_CREDITS_RELEASE_RPC_URL__";
 export declare function resolveBaseSepoliaRpc(environment: NodeJS.ProcessEnv, legacyRpc?: string): string;
-export declare const RPC_GUIDANCE = "The built-in public Base Sepolia endpoint is rate-limited. To use your own endpoint (chain ID 84532), run zk-credits config rpc. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
+export declare const RPC_GUIDANCE = "The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. After changing the RPC, run zk-credits stop then zk-credits serve; retry setup if it has not completed. BASE_RPC_URL overrides the saved setting. Providers: https://docs.base.org/base-chain/node-operators/node-providers .";
 export declare function validateRpcUrl(value: string): string;
 export declare function checkBaseSepoliaRpc(value: string, request?: typeof fetch): Promise<string>;
 export declare function readRpcConfig(directory: string): Promise<string | undefined>;

package/dist/rpc-config.js

@@ -1,11 +1,14 @@
 import { randomUUID } from 'node:crypto';
 import { chmod, lstat, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-export const DEFAULT_BASE_SEPOLIA_RPC_URL = 'https://sepolia.base.org';
+export const DEFAULT_BASE_SEPOLIA_RPC_URL = "https://base-sepolia.infura.io/v3/4d7561cbe56f49fe8cdf30d46f609806";
 export function resolveBaseSepoliaRpc(environment, legacyRpc) {
-    return environment.BASE_RPC_URL?.trim() || legacyRpc?.trim() || DEFAULT_BASE_SEPOLIA_RPC_URL;
+    const rpc = environment.BASE_RPC_URL?.trim() || legacyRpc?.trim() || DEFAULT_BASE_SEPOLIA_RPC_URL;
+    if (rpc === '__ZK_CREDITS_RELEASE_RPC_URL__')
+        throw new Error('Release RPC has not been baked. Set BASE_RPC_URL or build the release package.');
+    return rpc;
 }
-export const RPC_GUIDANCE = 'The built-in public Base Sepolia endpoint is rate-limited. To use your own endpoint (chain ID 84532), run zk-credits config rpc. Providers: https://docs.base.org/base-chain/node-operators/node-providers .';
+export const RPC_GUIDANCE = 'The package uses the release Base Sepolia endpoint by default. To use your own endpoint (chain ID 84532), run zk-credits config rpc. After changing the RPC, run zk-credits stop then zk-credits serve; retry setup if it has not completed. BASE_RPC_URL overrides the saved setting. Providers: https://docs.base.org/base-chain/node-operators/node-providers .';
 export function validateRpcUrl(value) {
     try {
         const url = new URL(value.trim());

package/dist/setup-config.js

@@ -201,7 +201,7 @@ async function resolveWitnessSource(options, saved) {
     const explicitPath = environment.ZK_CREDITS_WITNESS_PATH?.trim();
     if (explicitPath) {
         if (options.manifest.deployment) {
-            throw new Error('Base Sepolia V2 setup requires a witness synchronized from the pinned public Base events');
+            throw new Error('Base Sepolia V2 setup requires a witness synchronized from the pinned public Base events. Unset ZK_CREDITS_WITNESS_PATH, run zk-credits config rpc, and retry zk-credits setup');
         }
         const source = {
             kind: 'file',
@@ -239,7 +239,7 @@ async function resolveWitnessSource(options, saved) {
         }
     }
     if (options.manifest.deployment) {
-        throw new Error('Base Sepolia V2 setup requires BASE_RPC_URL to sync the pinned V2 bond from its deployment block');
+        throw new Error('Base Sepolia V2 setup requires BASE_RPC_URL to sync the pinned V2 bond from its deployment block. Run zk-credits config rpc, then retry zk-credits setup');
     }
     if (saved?.witness.kind === 'file') {
         try {

package/dist/sidecar-diagnostics.d.ts

@@ -0,0 +1,7 @@
+export interface DiagnosticOptions {
+    baseUrl: string;
+    stateDirectory: string;
+    write(line: string): void;
+}
+export declare function diagnoseSidecar(options: DiagnosticOptions): Promise<void>;
+export declare function stopSidecar(options: DiagnosticOptions): Promise<void>;