zk-credits 0.2.11 → 0.2.14

package/README.md

@@ -32,6 +32,8 @@ private: anyone with it can spend your credits.
 | `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 codex --task-evidence` | Run a coding task and show its aggregate payment evidence on exit |
+| `zk-credits investigate --chain base <transaction-hash>` | Investigate a failed Base transaction using prepaid inference |
 | `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 |
@@ -82,3 +84,47 @@ Your credential stays on your device. Proofs are sent to authorize each spend. T
 can observe traffic metadata. This does not hide your IP address.
 
 Base Sepolia test credits only. The circuit is not independently audited.
+
+### Coding-task evidence (0.2.14 candidate)
+
+After setup, `zk-credits codex --task-evidence` launches Codex against a fresh,
+dedicated local sidecar and prints aggregate payment counters when Codex exits.
+The provider and profile are fixed for attribution. The summary contains no
+prompts, bearer credentials, proofs, or payment headers. `exchange_verified`
+confirms a successful agent exit and an observed settled response; inspect the
+code diff and tests separately to judge the coding task. The supported model and
+reasoning defaults are selected automatically, including with older setups:
+
+```sh
+zk-credits codex --task-evidence
+```
+
+Enter your task, review the change and tests, then exit Codex to see the summary.
+Version 0.2.12 includes this command; 0.2.11 lacks it.
+See the [indexer sample](https://github.com/mangekyou-labs/haze-api/tree/main/examples/base-usdc-indexer).
+
+### Transaction investigator (0.2.14 candidate)
+
+After closing Codex, run `zk-credits investigate --chain base <transaction-hash>`
+with the same configured credential. It fetches public execution evidence and
+uses the custom x402 `zk-prepaid` adapter for model inference. Base mainnet is
+the investigated chain; credit funding remains on Base Sepolia and consumption
+is offchain. It does not purchase external traces. Keep missing-evidence notices
+visible and distinguish observed errors from model hypotheses.
+
+Version 0.2.14 fixes the investigator's packaged payment recipient pin and refuses
+builds with missing or placeholder treasury addresses. Payment requirements must
+still match the reviewed deployment before any proof is authorized.
+
+Repeating a transaction hash recovers its existing local task without authorizing
+a new paid call. The report shows the original stopping reason and labels prior
+accounting separately from current invocation counters, including when the saved
+run authorized no credits. Upgrading does not resume a stopped investigation.
+Do not delete task journals or reset
+credential accounting to force a fresh exchange. Unknown payment outcomes must
+be reconciled before another paid task. A saved report must be labeled as a prior
+run, with its own payment summary.
+
+`challengeObserved` counts challenges presented for authorization, including
+refused terms. A challenge alone does not imply a proof or consumed credit;
+check confirmed, failed, unknown and retired counters separately.

package/circuits/manifest.json

@@ -33,6 +33,7 @@
   "deployment": {
     "chainId": 84532,
     "bondAddress": "0xcc1909dD30485d6D9a46e3d33cf04C1378b586Ab",
+    "treasuryAddress": "0xa8b9b38e748563AF7FbAA276e8a843Da417D7Bc1",
     "deploymentBlock": "47372040",
     "deploymentDomain": "84532",
     "circuitId": "private-credit-spend-bn254-dev",

package/dist/activated-credential-setup.d.ts

@@ -0,0 +1,18 @@
+import { type CredentialStore } from './credential-store.js';
+import { type ResolveSetupInputsOptions, type SetupConfig } from './setup-config.js';
+export interface ActivatedCredentialSetupOptions {
+    environment?: NodeJS.ProcessEnv;
+    homeDirectory?: string;
+    stateDirectory?: string;
+    credentialStore?: CredentialStore;
+    chooseCandidate?: ResolveSetupInputsOptions['chooseCandidate'];
+    /** The caller owns hidden terminal input for explicit legacy import. */
+    readLegacyPassword?(): Promise<string>;
+}
+/**
+ * Imports or loads the credential and prepares validated runtime configuration.
+ * Configuration is saved only after all checks pass. Credential import, artifact
+ * acquisition and witness synchronization may persist progress on failure so a
+ * retry can reuse it. Applies RPC and successful setup paths to the environment.
+ */
+export declare function setupActivatedCredential(options?: ActivatedCredentialSetupOptions): Promise<SetupConfig>;

package/dist/activated-credential-setup.js

@@ -0,0 +1,64 @@
+/** Interactive credential preparation; runtime loading and launch remain separate. */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadCircuitManifest } from './artifact-bundle.js';
+import { validateBaseCreditWitness } from './base-sidecar.js';
+import { importCredentialPath, nativeCredentialStore, readStoredCredential, } from './credential-store.js';
+import { requireGatewayKnownRoot, resolveGatewayOrigin } from './gateway-root-check.js';
+import { createPinnedBaseProofGenerator } from './proof-coordinator.js';
+import { createBaseProofMetrics } from './proof-metrics.js';
+import { applyRpcConfig, checkBaseSepoliaRpc, resolveBaseSepoliaRpc } from './rpc-config.js';
+import { applySetupConfig, readSetupConfig, resolveSetupInputs, writeSetupConfig, } from './setup-config.js';
+import { witnessProviderForSource } from './sidecar-runtime.js';
+/**
+ * Imports or loads the credential and prepares validated runtime configuration.
+ * Configuration is saved only after all checks pass. Credential import, artifact
+ * acquisition and witness synchronization may persist progress on failure so a
+ * retry can reuse it. Applies RPC and successful setup paths to the environment.
+ */
+export async function setupActivatedCredential(options = {}) {
+    const environment = options.environment ?? process.env;
+    const homeDirectory = options.homeDirectory ?? homedir();
+    const stateDirectory = options.stateDirectory ?? (environment.ZK_CREDITS_HOME || join(homeDirectory, '.zk-credits'));
+    const configPath = join(stateDirectory, 'config.json');
+    const credentialStore = options.credentialStore ?? nativeCredentialStore(stateDirectory);
+    await applyRpcConfig(environment, stateDirectory);
+    const saved = await readSetupConfig(configPath);
+    const rpc = resolveBaseSepoliaRpc(environment, saved?.witness.kind === 'base-events' ? saved.witness.rpcUrl : undefined);
+    await checkBaseSepoliaRpc(rpc);
+    environment.BASE_RPC_URL = rpc;
+    const credentialPath = environment.ZK_CREDITS_CREDENTIAL_PATH;
+    const legacyPassword = await options.readLegacyPassword?.();
+    const credential = credentialPath
+        ? await importCredentialPath(credentialPath, credentialStore, legacyPassword)
+        : await readStoredCredential(credentialStore);
+    const manifest = await loadCircuitManifest();
+    const config = await resolveSetupInputs({
+        environment,
+        homeDirectory,
+        stateDirectory,
+        configPath,
+        manifest,
+        validateWitness: async (source) => {
+            const provider = await witnessProviderForSource(source, join(stateDirectory, 'base-event-sync.json'));
+            const witness = validateBaseCreditWitness(await provider.witnessForCredential(credential));
+            if (manifest.deployment)
+                await requireGatewayKnownRoot(witness.root, resolveGatewayOrigin(environment));
+        },
+        chooseCandidate: options.chooseCandidate,
+    });
+    try {
+        await createPinnedBaseProofGenerator({
+            artifactDirectory: config.artifactDirectory,
+            metrics: createBaseProofMetrics(),
+        });
+    }
+    catch (error) {
+        if (error instanceof Error)
+            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(configPath, config);
+    applySetupConfig(environment, config);
+    return config;
+}

package/dist/base-event-sync.js

@@ -13,6 +13,7 @@ import { baseSepolia } from 'viem/chains';
 import { createPublicClient, http, parseAbi } from 'viem';
 import { BASE_MEMBERSHIP_TREE_CAPACITY, BN254_FIELD_ORDER, computeCreditLeaf, deriveSparseCreditWitness, } from '@zk-credits/shared/base';
 import { RPC_GUIDANCE } from './rpc-config.js';
+import { rpcFetch } from './rpc-transport.js';
 const BUNDLE_FUNDED_ABI = parseAbi([
     'event BundleFunded(bytes32 indexed commitment, uint8 indexed tierId, uint64 expiry, uint256 leafIndex, uint256 bondAmount, bytes32 root)',
 ]);
@@ -82,12 +83,15 @@ function serializeLeaves(leaves) {
 }
 /** Creates a witness provider that syncs finalized BundleFunded events. */
 export function createBaseEventWitnessProvider(options) {
-    const client = options.client ?? createPublicClient({ chain: baseSepolia, transport: http(options.rpcUrl) });
+    const client = options.client ?? createPublicClient({ chain: baseSepolia,
+        transport: http(options.rpcUrl, { fetchFn: rpcFetch, retryCount: 0, timeout: 30_000 }),
+    });
     const contract = address(options.contractAddress);
     const confirmations = options.confirmations ?? 3n;
     const maxBlockRange = options.maxBlockRange ?? 2000n;
     let cache;
     let leaves = new Map();
+    let pendingSync;
     async function rpcCall(operation) {
         try {
             return await operation;
@@ -150,7 +154,8 @@ export function createBaseEventWitnessProvider(options) {
     }
     return {
         async witnessForCredential(credential) {
-            await synchronize();
+            pendingSync ??= synchronize().finally(() => { pendingSync = undefined; });
+            await pendingSync;
             const commitment = field(credential.commitment, 'credential commitment');
             const entry = [...leaves.entries()].find(([, value]) => value.commitment === commitment);
             if (!entry)

package/dist/base-sidecar.d.ts

@@ -65,6 +65,28 @@ export interface BasePrepaidClientOptions {
      * a public signal, or a credential identifier.
      */
     lifecycle?: ZkPrepaidLifecycleObserver;
+    /** Caller-owned durable policy and accounting boundary; failures propagate. */
+    authorization?: BaseAuthorizationBridge;
+}
+export interface BaseAuthorizationRequest extends BasePaymentContext {
+    attemptId: string;
+    body: Uint8Array;
+}
+export type BaseUsageObservation = {
+    attemptId: string;
+    slot: number;
+} & ({
+    type: 'provisional' | 'released' | 'retired';
+} | {
+    type: 'settlement';
+    outcome: 'confirmed' | 'failed' | 'unknown';
+    reservationId?: string;
+});
+export interface BaseAuthorizationBridge {
+    /** Persist reservation and validate actual terms before any fresh proof. */
+    beforeProof(request: BaseAuthorizationRequest): Promise<void>;
+    /** Contains no request content, credential, proof, signature or replay key. */
+    observe(event: BaseUsageObservation): Promise<void>;
 }
 export interface BasePrepaidClient {
     client: ZkPrepaidClient;
@@ -80,6 +102,8 @@ export interface BasePaymentContext {
 export interface BasePreparedPayment {
     payment: PaymentPayload;
     responsePrivateKey: string;
+    attemptId: string;
+    slot: number;
 }
 export declare function validateBaseCreditWitness(witness: BaseCreditWitness): BaseCreditWitness;
 /** Creates the shared local proof factory used by both client transports. */

package/dist/base-sidecar.js

@@ -7,7 +7,7 @@
  *
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-import { createDecipheriv, generateKeyPair as generateKeyPairCallback, privateDecrypt, randomBytes } from 'node:crypto';
+import { createDecipheriv, generateKeyPair as generateKeyPairCallback, privateDecrypt, randomBytes, randomUUID } from 'node:crypto';
 import { promisify } from 'node:util';
 import { BASE_MEMBERSHIP_TREE_CAPACITY, canonicalizeBaseJson, computeCreditLeaf, computeNullifier, computeShare, computeSlotBlinding, deriveRequestSignal, deriveSparseCreditWitness, secretFromBase64Url, secretToField, } from '@zk-credits/shared/base';
 import { buildPaymentPayload, createZkPrepaidClient, decodeHeader, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, } from '@zk-credits/x402-zk-prepaid';
@@ -77,8 +77,13 @@ export function createBasePaymentFactory(options) {
         const slotLedger = options.slotLedger;
         if (!slotLedger)
             throw new Error('A durable slot ledger is required for the Base pilot');
+        const attemptId = randomUUID();
+        const bytes = new Uint8Array(requestBodyBytes(body));
+        await options.authorization?.beforeProof({ attemptId, method, url, body: bytes, requirements: structuredClone(requirements) });
         const selectedSlot = slotLedger.allocateProvisional();
+        let retired = false;
         try {
+            await options.authorization?.observe({ type: 'provisional', attemptId, slot: selectedSlot });
             const nonce = randomNonce();
             const responseKeys = await responseKey();
             const requestSignal = await deriveRequestSignal({
@@ -128,6 +133,8 @@ export function createBasePaymentFactory(options) {
                 throw new Error('Proof public signals do not match the canonical statement');
             }
             await slotLedger.commit(selectedSlot);
+            retired = true;
+            await options.authorization?.observe({ type: 'retired', attemptId, slot: selectedSlot });
             const payment = buildPaymentPayload({
                 requirements,
                 proof: proofForPayment(proof.proof),
@@ -135,10 +142,13 @@ export function createBasePaymentFactory(options) {
                 nonce,
                 responseKey: responseKeys.publicKey,
             });
-            return { payment, responsePrivateKey: responseKeys.privateKey };
+            return { payment, responsePrivateKey: responseKeys.privateKey, attemptId, slot: selectedSlot };
         }
         catch (error) {
-            slotLedger.release(selectedSlot);
+            if (!retired) {
+                slotLedger.release(selectedSlot);
+                await options.authorization?.observe({ type: 'released', attemptId, slot: selectedSlot });
+            }
             throw error;
         }
     };
@@ -266,9 +276,49 @@ export function createBasePrepaidClient(options) {
             headers: new Headers(response.headers),
         });
     };
+    const observeSettlement = async (response, init) => {
+        const header = new Headers(init?.headers).get(PAYMENT_SIGNATURE_HEADER);
+        if (!header || !options.authorization)
+            return;
+        let payment;
+        try {
+            payment = decodeHeader(header);
+        }
+        catch {
+            return;
+        }
+        const key = pendingByNonce.get(payment.payload.nonce);
+        const pending = key ? pendingPayments.get(key) : undefined;
+        if (!pending)
+            return;
+        let outcome = 'unknown';
+        let reservationId;
+        try {
+            const encoded = response.headers.get(PAYMENT_RESPONSE_HEADER);
+            const result = encoded ? decodeHeader(encoded) : undefined;
+            if (result && result.network === pending.payment.accepted.network && result.transaction === ''
+                && (result.reservationId === undefined || (typeof result.reservationId === 'string' && result.reservationId.length > 0 && result.reservationId.length <= 256))
+                && typeof result.success === 'boolean' && !('payer' in result)) {
+                // A failed response can describe an ambiguous ready/commit failure.
+                outcome = result.success ? 'confirmed' : 'unknown';
+                reservationId = result.reservationId;
+            }
+        }
+        catch { /* Missing or malformed settlement leaves consumption unknown. */ }
+        await options.authorization.observe({ type: 'settlement', attemptId: pending.attemptId, slot: pending.slot, outcome,
+            ...(reservationId === undefined ? {} : { reservationId }) });
+    };
     const fetchWithReplay = async (input, init) => {
         prunePending();
-        const response = await fetcher(input, init);
+        let response;
+        try {
+            response = await fetcher(input, { ...init, redirect: 'error' });
+        }
+        catch (error) {
+            await observeSettlement(new Response(null, { status: 503 }), init);
+            throw error;
+        }
+        await observeSettlement(response, init);
         if (response.status !== 409)
             return trackPaymentResponse(response, init);
         let replayAvailable = false;
@@ -343,7 +393,7 @@ export function createBasePrepaidClient(options) {
                 const nonce = payment.payload.nonce;
                 const expiresAt = Date.now() + REPLAY_TTL_MS;
                 replayKeys.set(nonce, { privateKey: prepared.responsePrivateKey, expiresAt });
-                pendingPayments.set(key, { payment, expiresAt });
+                pendingPayments.set(key, { payment, expiresAt, attemptId: prepared.attemptId, slot: prepared.slot });
                 pendingByNonce.set(nonce, key);
                 prunePending();
                 return payment;
@@ -358,7 +408,25 @@ export function createBasePrepaidClient(options) {
             }
         },
     });
-    return { client, committedSlots: () => options.slotLedger?.committedSlots() ?? [] };
+    return {
+        client: {
+            clearRequirements: client.clearRequirements,
+            async fetch(input, init) {
+                const source = input instanceof Request ? input : undefined;
+                const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+                const body = init?.body ?? (source?.body ? new Uint8Array(await source.clone().arrayBuffer()) : undefined);
+                const snapshot = body instanceof ArrayBuffer ? new Uint8Array(body.slice(0))
+                    : body instanceof Uint8Array ? new Uint8Array(body) : body;
+                return client.fetch(url, {
+                    ...(source ? { method: source.method, headers: new Headers(source.headers), signal: source.signal } : {}),
+                    ...init,
+                    headers: new Headers(init?.headers ?? source?.headers),
+                    ...(snapshot === undefined ? {} : { body: snapshot }),
+                });
+            },
+        },
+        committedSlots: () => options.slotLedger?.committedSlots() ?? [],
+    };
 }
 function parsePublicTreeArtifact(value) {
     if (!value || typeof value !== 'object')