zk-credits 0.2.11 → 0.2.12

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,36 @@ 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.12 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 is prepared for owner publication; 0.2.11 lacks this command.
+See the [indexer sample](https://github.com/mangekyou-labs/haze-api/tree/main/examples/base-usdc-indexer).
+
+### Transaction investigator (0.2.12 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.
+
+Repeating a transaction hash recovers its existing local task; it need not make
+a new paid call or return a complete report. 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.

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')