zk-credits 0.2.0 → 0.2.1

package/README.md

@@ -7,7 +7,7 @@ are founder-provisioned test credits, and the circuit is not independently
 audited.
 
 ```bash
-npm install --global zk-credits
+npm install --global zk-credits@latest
 ```
 
 ## Pinned pilot versions
@@ -21,9 +21,11 @@ not mix versions between the sidecar, the adapter package, and the gateway:
 | `@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
+`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
 (`private-credit-spend-bn254-dev-sepolia-v1`) are delivered directly through
 the invite channel, never from a public host.
 
@@ -43,9 +45,9 @@ 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,
+- no provider streaming, images, files, audio, web search, model fallback,
   client-selected routing, or unknown cost-affecting fields;
-- input capped at 16,000 UTF-8 bytes (counted conservatively, never below the
+- 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.
 
@@ -55,32 +57,27 @@ 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
+1. Redeem an invite and download the encrypted credential. Credits are
    founder-provisioned test credits; there is no payment step.
-2. Install the pinned proving artifacts. The package ships
+2. Install `zk-credits` and ask your pilot contact for the pinned proving
+   bundle and public Base tree file. 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:
+   `verification_key_private_credit.json`. The sidecar never fetches proving
+   material at runtime. Set the paths to the downloaded files and gateway:
 
    ```bash
-   export ZK_CREDITS_ARTIFACT_DIR="$PWD/private-credit-bundle"
-   ls "$ZK_CREDITS_ARTIFACT_DIR"   # the three pinned files
+   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"
    ```
 
    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
+   `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`,
@@ -89,24 +86,29 @@ still receives the class. A rejected request consumes no credit.
    events and builds a local Merkle witness. The gateway never serves a path
    for a named leaf or commitment.
 
-4. Run:
+3. Start setup. It verifies the credential, pinned artifact hashes, and
+   witness locally, then prompts for the backup password without echo:
 
    ```bash
-   zk-credits cline "summarize this repository"
-   zk-credits setup codex && zk-credits codex "summarize this repository"
+   zk-credits setup codex
    ```
 
+   Then run `zk-credits codex` to open Codex with the local sidecar.
+
 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.
+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 |
 | --- | --- | --- |
@@ -114,10 +116,14 @@ unsupported; the sidecar never falls back to another rail.
 | `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
+| `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
@@ -179,9 +185,21 @@ zk-credits setup codex [--model <model>]
 zk-credits codex [codex arguments...]
 zk-credits status
 zk-credits serve [--port <port>]
+zk-credits trial-registered-adapter
 eval "$(zk-credits env)"
 ```
 
+`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

package/dist/base-registered-trial.d.ts

@@ -0,0 +1,33 @@
+/**
+ * One-shot local transport for exercising the official @x402/core adapter.
+ *
+ * @x402/core creates scheme payloads from PaymentRequired and does not pass
+ * HTTP method/body context to a scheme client. This harness captures that
+ * request context locally, then binds it into the same Base proof factory
+ * before invoking the registered `zk-prepaid` scheme. It is intended only for
+ * the internal Base Sepolia trial, not as a general HTTP client.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { type BasePrepaidClientOptions } from './base-sidecar.js';
+export type BaseRegisteredTrialFailurePhase = 'challenge_transport' | 'challenge_status' | 'challenge_header' | 'challenge_invalid' | 'challenge_unsupported' | 'challenge_request_mismatch' | 'proof_generation' | 'payment_transport' | 'payment_rejected' | 'payment_response_missing' | 'payment_response_invalid' | 'response_not_ok';
+export interface BaseRegisteredTrialResult {
+    challengeStatus: number | null;
+    challengeReceived: boolean;
+    proofPrepared: boolean;
+    paymentSignatureSent: boolean;
+    paymentStatus: number | null;
+    paymentResponseConfirmed: boolean;
+    responseStatus: number | null;
+    responseSucceeded: boolean;
+    committedSlotDelta: number;
+    failurePhase?: BaseRegisteredTrialFailurePhase;
+}
+export interface BaseRegisteredTrialOptions extends BasePrepaidClientOptions {
+    url: string;
+    body: string;
+    headers?: HeadersInit;
+    fetch?: typeof fetch;
+}
+/** Runs one POST to the pilot chat route through a directly registered adapter. */
+export declare function runBaseRegisteredTrialExchange(options: BaseRegisteredTrialOptions): Promise<BaseRegisteredTrialResult>;

package/dist/base-registered-trial.js

@@ -0,0 +1,168 @@
+/**
+ * One-shot local transport for exercising the official @x402/core adapter.
+ *
+ * @x402/core creates scheme payloads from PaymentRequired and does not pass
+ * HTTP method/body context to a scheme client. This harness captures that
+ * request context locally, then binds it into the same Base proof factory
+ * before invoking the registered `zk-prepaid` scheme. It is intended only for
+ * the internal Base Sepolia trial, not as a general HTTP client.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { x402Client } from '@x402/core/client';
+import { BASE_SEPOLIA_NETWORK, decodeHeader, encodeHeader, lifecycleFailure, lifecycleStage, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, registerZkPrepaidClient, ZK_PREPAID_SCHEME, } from '@zk-credits/x402-zk-prepaid';
+import { createBasePaymentFactory } from './base-sidecar.js';
+function observe(options, event) {
+    try {
+        options.lifecycle?.(event);
+    }
+    catch {
+        // An observer must never change an exchange.
+    }
+}
+function withFailure(options, result, startingCommittedSlots, failurePhase, failure) {
+    result.failurePhase = failurePhase;
+    if (failure)
+        observe(options, lifecycleFailure(failure));
+    result.committedSlotDelta = (options.slotLedger?.snapshot().committed ?? startingCommittedSlots) - startingCommittedSlots;
+    return result;
+}
+function requestHeaders(headers) {
+    return new Headers(headers);
+}
+/** Runs one POST to the pilot chat route through a directly registered adapter. */
+export async function runBaseRegisteredTrialExchange(options) {
+    const ledger = options.slotLedger;
+    if (!ledger)
+        throw new Error('A durable slot ledger is required for the Base pilot');
+    const startingCommittedSlots = ledger.snapshot().committed;
+    const result = {
+        challengeStatus: null,
+        challengeReceived: false,
+        proofPrepared: false,
+        paymentSignatureSent: false,
+        paymentStatus: null,
+        paymentResponseConfirmed: false,
+        responseStatus: null,
+        responseSucceeded: false,
+        committedSlotDelta: 0,
+    };
+    let target;
+    try {
+        target = new URL(options.url);
+    }
+    catch {
+        return withFailure(options, result, startingCommittedSlots, 'challenge_request_mismatch');
+    }
+    if (target.protocol !== 'https:'
+        || target.username !== ''
+        || target.password !== ''
+        || target.search !== ''
+        || target.hash !== ''
+        || target.pathname !== '/v1/chat/completions') {
+        return withFailure(options, result, startingCommittedSlots, 'challenge_request_mismatch');
+    }
+    const fetcher = options.fetch ?? fetch;
+    const requestInit = {
+        method: 'POST',
+        body: options.body,
+        headers: requestHeaders(options.headers),
+        redirect: 'error',
+    };
+    let challengeResponse;
+    try {
+        challengeResponse = await fetcher(target, requestInit);
+    }
+    catch {
+        return withFailure(options, result, startingCommittedSlots, 'challenge_transport', 'transport_failed');
+    }
+    result.challengeStatus = challengeResponse.status;
+    if (challengeResponse.status !== 402) {
+        return withFailure(options, result, startingCommittedSlots, 'challenge_status', 'payment_rejected');
+    }
+    const encodedRequired = challengeResponse.headers.get(PAYMENT_REQUIRED_HEADER);
+    if (!encodedRequired) {
+        return withFailure(options, result, startingCommittedSlots, 'challenge_header', 'challenge_unsupported');
+    }
+    let required;
+    try {
+        required = decodeHeader(encodedRequired);
+    }
+    catch {
+        return withFailure(options, result, startingCommittedSlots, 'challenge_invalid', 'challenge_unreadable');
+    }
+    if (required.x402Version !== 2
+        || !Array.isArray(required.accepts)
+        || !required.accepts.some((accepted) => accepted.scheme === ZK_PREPAID_SCHEME && accepted.network === BASE_SEPOLIA_NETWORK)) {
+        return withFailure(options, result, startingCommittedSlots, 'challenge_unsupported', 'challenge_unsupported');
+    }
+    const challengeUrl = required.resource?.url;
+    if (challengeUrl && challengeUrl !== target.toString()) {
+        return withFailure(options, result, startingCommittedSlots, 'challenge_request_mismatch', 'challenge_unsupported');
+    }
+    result.challengeReceived = true;
+    observe(options, lifecycleStage('challenge_received'));
+    const createPayment = createBasePaymentFactory(options);
+    const directAdapter = registerZkPrepaidClient(new x402Client((_version, accepts) => {
+        const selected = accepts.find((accepted) => accepted.scheme === ZK_PREPAID_SCHEME && accepted.network === BASE_SEPOLIA_NETWORK);
+        if (!selected)
+            throw new Error('zk_prepaid_challenge_missing');
+        return selected;
+    }).setSpendControls(false), async ({ requirements }) => {
+        const prepared = await createPayment({
+            url: target.toString(),
+            method: 'POST',
+            body: options.body,
+            requirements,
+        });
+        return prepared.payment;
+    });
+    let payment;
+    try {
+        payment = await directAdapter.createPaymentPayload(required);
+        result.proofPrepared = true;
+        observe(options, lifecycleStage('payment_prepared'));
+    }
+    catch {
+        return withFailure(options, result, startingCommittedSlots, 'proof_generation', 'payment_preparation_failed');
+    }
+    const headers = requestHeaders(options.headers);
+    headers.set(PAYMENT_SIGNATURE_HEADER, encodeHeader(payment));
+    result.paymentSignatureSent = true;
+    let paidResponse;
+    try {
+        paidResponse = await fetcher(target, { ...requestInit, headers });
+    }
+    catch {
+        return withFailure(options, result, startingCommittedSlots, 'payment_transport', 'transport_failed');
+    }
+    result.paymentStatus = paidResponse.status;
+    result.responseStatus = paidResponse.status;
+    if (paidResponse.status === 402) {
+        return withFailure(options, result, startingCommittedSlots, 'payment_rejected', 'payment_rejected');
+    }
+    const encodedPaymentResponse = paidResponse.headers.get(PAYMENT_RESPONSE_HEADER);
+    if (!encodedPaymentResponse) {
+        return withFailure(options, result, startingCommittedSlots, 'payment_response_missing', 'settlement_failed');
+    }
+    try {
+        const settlement = decodeHeader(encodedPaymentResponse);
+        if (settlement.success !== true
+            || settlement.network !== BASE_SEPOLIA_NETWORK
+            || settlement.transaction !== '') {
+            return withFailure(options, result, startingCommittedSlots, 'payment_response_invalid', 'settlement_failed');
+        }
+    }
+    catch {
+        return withFailure(options, result, startingCommittedSlots, 'payment_response_invalid', 'settlement_failed');
+    }
+    result.paymentResponseConfirmed = true;
+    observe(options, lifecycleStage('settlement_confirmed'));
+    if (!paidResponse.ok) {
+        return withFailure(options, result, startingCommittedSlots, 'response_not_ok', 'payment_rejected');
+    }
+    result.responseSucceeded = true;
+    observe(options, lifecycleStage('exchange_succeeded'));
+    result.committedSlotDelta = ledger.snapshot().committed - startingCommittedSlots;
+    return result;
+}

package/dist/base-sidecar.d.ts

@@ -8,7 +8,7 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 import { type CreditCredential } from '@zk-credits/shared/base';
-import { type PaymentRequirements, type ZkPrepaidClient, type ZkPrepaidLifecycleObserver } from '@zk-credits/x402-zk-prepaid';
+import { type PaymentPayload, type PaymentRequirements, type ZkPrepaidClient, type ZkPrepaidLifecycleObserver } from '@zk-credits/x402-zk-prepaid';
 import type { BaseSlotLedger } from './slot-ledger.js';
 export interface BaseCreditWitness {
     root: string;
@@ -69,6 +69,19 @@ export interface BasePrepaidClient {
     /** Slots committed locally; a committed slot is never reused. */
     committedSlots(): number[];
 }
+export interface BasePaymentContext {
+    url: string;
+    method: string;
+    body: unknown;
+    requirements: PaymentRequirements;
+}
+export interface BasePreparedPayment {
+    payment: PaymentPayload;
+    responsePrivateKey: string;
+}
+export declare function validateBaseCreditWitness(witness: BaseCreditWitness): BaseCreditWitness;
+/** Creates the shared local proof factory used by both client transports. */
+export declare function createBasePaymentFactory(options: BasePrepaidClientOptions): (context: BasePaymentContext) => Promise<BasePreparedPayment>;
 /** Builds the reusable client adapter used by the loopback proxy. */
 export declare function createBasePrepaidClient(options: BasePrepaidClientOptions): BasePrepaidClient;
 /**

package/dist/base-sidecar.js

@@ -24,7 +24,7 @@ function field(value, label) {
         throw new Error(`Invalid ${label}`);
     return parsed.toString();
 }
-function assertWitness(witness) {
+export function validateBaseCreditWitness(witness) {
     if (typeof witness.root !== 'string'
         || witness.pathElements.length !== TREE_DEPTH
         || witness.pathIndices.length !== TREE_DEPTH
@@ -60,6 +60,77 @@ function requestBodyBytes(body) {
         return new Uint8Array();
     throw new Error('The Base x402 sidecar requires the exact request-body bytes');
 }
+/** Creates the shared local proof factory used by both client transports. */
+export function createBasePaymentFactory(options) {
+    const secret = secretFromBase64Url(options.credential.secret);
+    return async ({ method, url, body, requirements }) => {
+        if (requirements.extra.deploymentDomain !== options.credential.deploymentDomain) {
+            throw new Error('Credential deployment domain does not match the gateway challenge');
+        }
+        const slotLedger = options.slotLedger;
+        if (!slotLedger)
+            throw new Error('A durable slot ledger is required for the Base pilot');
+        const selectedSlot = slotLedger.allocateProvisional();
+        try {
+            const nonce = randomNonce();
+            const responseKeys = await responseKey();
+            const requestSignal = await deriveRequestSignal({
+                method,
+                url,
+                body: requestBodyBytes(body),
+                requirements,
+                nonce,
+                responseKey: responseKeys.publicKey,
+            });
+            const witness = validateBaseCreditWitness(await options.witnessProvider.witnessForCredential(options.credential));
+            const expiry = witness.expiry ?? options.credential.expiry;
+            if (!Number.isSafeInteger(expiry) || expiry <= 0)
+                throw new Error('Invalid Base credential expiry');
+            const slotBlinding = await computeSlotBlinding(secret, selectedSlot, options.credential.deploymentDomain);
+            const nullifier = await computeNullifier(slotBlinding);
+            const share = await computeShare(secret, requestSignal.field, slotBlinding);
+            const timestamp = String(requirements.extra.issuedAt);
+            const expectedPublicSignals = [
+                witness.root,
+                timestamp,
+                options.credential.deploymentDomain,
+                requestSignal.field,
+                nullifier,
+                share,
+            ];
+            const proof = await options.prove({
+                secret: secretToField(secret),
+                tier_id: String(options.credential.tierId),
+                expiry: String(expiry),
+                slot: String(selectedSlot),
+                merkle_path_elements: witness.pathElements,
+                merkle_path_indices: witness.pathIndices.map(String),
+                root_in: witness.root,
+                timestamp_in: timestamp,
+                domain_in: options.credential.deploymentDomain,
+                request_signal_in: requestSignal.field,
+            }, { requirements, credential: options.credential, expectedPublicSignals });
+            if (!Array.isArray(proof.publicSignals)
+                || proof.publicSignals.length !== expectedPublicSignals.length
+                || !proof.publicSignals.every((value, index) => value === expectedPublicSignals[index])) {
+                throw new Error('Proof public signals do not match the canonical statement');
+            }
+            await slotLedger.commit(selectedSlot);
+            const payment = buildPaymentPayload({
+                requirements,
+                proof: proof.proof,
+                publicSignals: [...proof.publicSignals],
+                nonce,
+                responseKey: responseKeys.publicKey,
+            });
+            return { payment, responsePrivateKey: responseKeys.privateKey };
+        }
+        catch (error) {
+            slotLedger.release(selectedSlot);
+            throw error;
+        }
+    };
+}
 function decryptReplay(envelopeValue, privateKey, paymentResponse) {
     try {
         const envelope = JSON.parse(envelopeValue);
@@ -89,7 +160,7 @@ function decryptReplay(envelopeValue, privateKey, paymentResponse) {
 }
 /** Builds the reusable client adapter used by the loopback proxy. */
 export function createBasePrepaidClient(options) {
-    const secret = secretFromBase64Url(options.credential.secret);
+    const createPayment = createBasePaymentFactory(options);
     const fetcher = options.fetch ?? fetch;
     const replayKeys = new Map();
     const pendingPayments = new Map();
@@ -244,9 +315,6 @@ export function createBasePrepaidClient(options) {
         fetch: fetchWithReplay,
         ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
         createPayload: async ({ method, url, body, requirements }) => {
-            if (requirements.extra.deploymentDomain !== options.credential.deploymentDomain) {
-                throw new Error('Credential deployment domain does not match the gateway challenge');
-            }
             prunePending();
             const key = requestKey(method, url, body, requirements);
             const cached = pendingPayments.get(key);
@@ -258,73 +326,15 @@ export function createBasePrepaidClient(options) {
             if (inFlight)
                 return inFlight;
             const paymentPromise = (async () => {
-                const slotLedger = options.slotLedger;
-                if (!slotLedger)
-                    throw new Error('A durable slot ledger is required for the Base pilot');
-                const selectedSlot = slotLedger.allocateProvisional();
-                try {
-                    const nonce = randomNonce();
-                    const responseKeys = await responseKey();
-                    const requestSignal = await deriveRequestSignal({
-                        method,
-                        url,
-                        body: requestBodyBytes(body),
-                        requirements,
-                        nonce,
-                        responseKey: responseKeys.publicKey,
-                    });
-                    const witness = assertWitness(await options.witnessProvider.witnessForCredential(options.credential));
-                    const expiry = witness.expiry ?? options.credential.expiry;
-                    if (!Number.isSafeInteger(expiry) || expiry <= 0)
-                        throw new Error('Invalid Base credential expiry');
-                    const slotBlinding = await computeSlotBlinding(secret, selectedSlot, options.credential.deploymentDomain);
-                    const nullifier = await computeNullifier(slotBlinding);
-                    const share = await computeShare(secret, requestSignal.field, slotBlinding);
-                    const timestamp = String(requirements.extra.issuedAt);
-                    const expectedPublicSignals = [
-                        witness.root,
-                        timestamp,
-                        options.credential.deploymentDomain,
-                        requestSignal.field,
-                        nullifier,
-                        share,
-                    ];
-                    const proof = await options.prove({
-                        secret: secretToField(secret),
-                        tier_id: String(options.credential.tierId),
-                        expiry: String(expiry),
-                        slot: String(selectedSlot),
-                        merkle_path_elements: witness.pathElements,
-                        merkle_path_indices: witness.pathIndices.map(String),
-                        root_in: witness.root,
-                        timestamp_in: timestamp,
-                        domain_in: options.credential.deploymentDomain,
-                        request_signal_in: requestSignal.field,
-                    }, { requirements, credential: options.credential, expectedPublicSignals });
-                    if (!Array.isArray(proof.publicSignals)
-                        || proof.publicSignals.length !== expectedPublicSignals.length
-                        || !proof.publicSignals.every((value, index) => value === expectedPublicSignals[index])) {
-                        throw new Error('Proof public signals do not match the canonical statement');
-                    }
-                    await slotLedger.commit(selectedSlot);
-                    const payment = buildPaymentPayload({
-                        requirements,
-                        proof: proof.proof,
-                        publicSignals: [...proof.publicSignals],
-                        nonce,
-                        responseKey: responseKeys.publicKey,
-                    });
-                    const expiresAt = Date.now() + REPLAY_TTL_MS;
-                    replayKeys.set(nonce, { privateKey: responseKeys.privateKey, expiresAt });
-                    pendingPayments.set(key, { payment, expiresAt });
-                    pendingByNonce.set(nonce, key);
-                    prunePending();
-                    return payment;
-                }
-                catch (error) {
-                    slotLedger.release(selectedSlot);
-                    throw error;
-                }
+                const prepared = await createPayment({ method, url, body, requirements });
+                const payment = prepared.payment;
+                const nonce = payment.payload.nonce;
+                const expiresAt = Date.now() + REPLAY_TTL_MS;
+                replayKeys.set(nonce, { privateKey: prepared.responsePrivateKey, expiresAt });
+                pendingPayments.set(key, { payment, expiresAt });
+                pendingByNonce.set(nonce, key);
+                prunePending();
+                return payment;
             })();
             paymentPromises.set(key, paymentPromise);
             try {

package/dist/cli-runtime.d.ts

@@ -3,6 +3,7 @@ export interface CliCommandDependencies {
     readToken(): Promise<string>;
     write(line: string): void;
     isCredentialConfigured(): Promise<boolean>;
+    validateSetupPrerequisites(): Promise<void>;
     configureCodex(model?: string): Promise<void>;
     ensureSidecar(): Promise<string>;
     isCodexProfileInstalled(): Promise<boolean>;

package/dist/cli-runtime.js

@@ -19,8 +19,9 @@ export async function runCliCommand(args, dependencies) {
             const model = setupModel(args);
             if (!await dependencies.isCredentialConfigured())
                 throw new Error('Set ZK_CREDITS_CREDENTIAL_PATH before running zk-credits setup');
-            await dependencies.configureCodex(model);
+            await dependencies.validateSetupPrerequisites();
             await dependencies.ensureSidecar();
+            await dependencies.configureCodex(model);
             dependencies.write('ZK Credits is ready for Codex.');
             dependencies.write('Run: zk-credits codex');
             return 0;