zk-credits 0.2.5 → 0.2.8

package/README.md

@@ -2,12 +2,14 @@
 
 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.
+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.
 
 ```bash
-npm install --global zk-credits@0.2.5
+npm install --global zk-credits@0.2.8
 ```
 
 ## Pinned pilot versions
@@ -17,17 +19,18 @@ not mix versions between the sidecar, the adapter package, and the gateway:
 
 | Package | Version |
 | --- | --- |
-| `zk-credits` (this sidecar) | `0.2.5` |
+| `zk-credits` (this sidecar) | `0.2.8` |
 | `@zk-credits/x402-zk-prepaid` (adapter) | `0.1.0` |
 | `@zk-credits/shared` | `0.1.0` |
 
-The pinned Base Sepolia trial version is `0.2.5`. It uses the non-streaming
-`POST /v1/chat/completions` path below, includes the loopback Responses bridge
-for Codex, and acquires the pinned private proving bundle through the local
-GitHub CLI session. It also synchronizes V2 Base events and checks the gateway
-known root before local setup completes. Neither this version nor the adapter
-supports a Stellar or evaluation path. The proving artifacts are available
-only from the private immutable release pinned by `circuits/manifest.json`.
+The slot A Base Sepolia trial version is `0.2.8`. It uses the non-streaming
+`POST /v1/chat/completions` path below, includes the narrow loopback Responses
+bridge for supported Codex text and function-tool requests, and includes the
+pinned proving bundle in the package. It also
+synchronizes V2 Base events and checks the gateway known root before local
+setup completes. The packaged archive is checked against the immutable release
+digest pinned by `circuits/manifest.json`. Version 0.2.8 must be published by
+the owner before inviting a slot A participant.
 
 Verify the shipped artifacts before your first prove. The package's
 `circuits/manifest.json` fixes the SHA-256 of the frozen
@@ -57,14 +60,16 @@ still receives the class. A rejected request consumes no credit.
 
 ## First run
 
-1. Redeem an invite and download the encrypted V2 credential export. Credits
-   are founder-provisioned test credits; there is no payment step.
-2. Ask the pilot contact for read access to the private bundle repository
-   `mangekyou-labs/zk-credits-base-sepolia-v2-bundle`, then authenticate the
-   GitHub CLI on this machine with `gh auth login`. The sidecar uses that local
-   GitHub CLI session to read the immutable release identified in
-   `circuits/manifest.json`; it never receives or stores your GitHub token.
-   Set the credential, gateway, and Base Sepolia RPC endpoint:
+1. Redeem the founder-prepared invite and download the encrypted V2 credential
+   export. Slot A needs no access to the proving-bundle repository.
+2. Give Codex the single setup instruction in the
+   [first-use guide](../../docs/onboarding/base-zk-credits-codex-first-use.md).
+   Codex installs this pinned release, verifies its packaged bundle, and runs setup.
+   The human signs in if needed, enters the recovery password at the hidden
+   prompt, gives consent, and chooses their own task. No product payment is
+   involved. The sidecar needs no GitHub token to install proving material.
+3. The setup command sets the credential, gateway, and Base Sepolia RPC
+   endpoint:
 
    ```bash
    export ZK_CREDITS_CREDENTIAL_PATH="$HOME/Downloads/zk-credits-credential.json"
@@ -73,10 +78,10 @@ still receives the class. A rejected request consumes no credit.
    ```
 
    `zk-credits setup codex` searches the standard local folders first. If it
-   finds no valid bundle, it downloads the pinned release, verifies the
-   release id, tag, immutability, archive digest, and all three file digests,
+   finds no valid bundle, it reads the packaged archive, verifies its pinned
+   archive digest and all three file digests,
    then atomically installs the bundle under `~/.zk-credits/artifacts` with
-   owner-only permissions. Missing GitHub access or any mismatch stops setup.
+   owner-only permissions. Any mismatch stops setup.
    It syncs public Base events from the pinned V2 bond and deployment block,
    validates that the resulting witness resolves the activated credential,
    and asks the gateway's public `POST /v1/root-known` endpoint whether the
@@ -99,7 +104,7 @@ still receives the class. A rejected request consumes no credit.
    leaves, and the local slot stays reusable. The gateway never serves a path
    for a named leaf or commitment.
 
-3. Start setup. It verifies the credential, pinned artifact hashes, and
+4. Start setup. It verifies the credential, pinned artifact hashes, and
    witness locally, then prompts for the backup password without echo:
 
    ```bash
@@ -107,7 +112,9 @@ still receives the class. A rejected request consumes no credit.
    ```
 
    No gateway admin token is required. Then run `zk-credits codex` to open
-   Codex with the local sidecar.
+   Codex with the local sidecar. A/C first-use measurement targets five
+   minutes of active human work; unattended download, proving, and provider
+   waits are measured separately. More than five minutes is a friction finding.
 
 The sidecar binds `127.0.0.1:3210` only. It does not modify `~/.cline` or
 `~/.codex`.
@@ -198,11 +205,20 @@ zk-credits cline [cline arguments...]
 zk-credits setup codex [--model <model>]
 zk-credits codex [codex arguments...]
 zk-credits status
-zk-credits serve [--port <port>]
+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)"
 ```
 
+`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
@@ -220,6 +236,17 @@ Codex SDK:
 import { buildCodexSdkOptions, buildCodexThreadOptions } from 'zk-credits/codex';
 ```
 
+`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 decrypted only in local memory. The sidecar cache
 contains public Base event leaves and never stores the secret, prompt, response,
 proof, account, or wallet.

package/dist/artifact-release.d.ts

@@ -5,6 +5,7 @@ export interface AcquirePinnedBundleOptions {
     manifest: CircuitManifest;
     targetDirectory: string;
     runGithubCommand?: GithubCommand;
+    bundledArchivePath?: string;
 }
-/** Fetches a pinned private GitHub release and atomically installs its safe USTAR bundle. */
+/** Installs the pinned package archive, or fetches the release for legacy/test callers. */
 export declare function acquirePinnedArtifactBundle(options: AcquirePinnedBundleOptions): Promise<string>;

package/dist/artifact-release.js

@@ -5,7 +5,8 @@ import { gunzipSync } from 'node:zlib';
 import { promisify } from 'node:util';
 import { chmod, lstat, mkdir, open, readFile, rename, rm, } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { resolvePinnedArtifactBundle } from './artifact-bundle.js';
+import { fileURLToPath } from 'node:url';
+import { ArtifactBundleError, resolvePinnedArtifactBundle } from './artifact-bundle.js';
 const execFile = promisify(nodeExecFile);
 const MAX_COMPRESSED_BYTES = 20 * 1024 * 1024;
 const MAX_EXPANDED_BYTES = 32 * 1024 * 1024;
@@ -126,14 +127,15 @@ function pinnedAsset(release, raw) {
     }
     const record = value;
     const assets = Array.isArray(record.assets) ? record.assets : [];
-    const asset = assets.find((entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+    const matchingAssets = assets.filter((entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
         && entry.name === release.assetName);
+    const asset = matchingAssets[0];
     if (record.id !== release.releaseId
         || record.tag_name !== release.tag
         || record.draft !== false
         || record.immutable !== true
-        || !asset
-        || (typeof asset.digest === 'string' && asset.digest !== 'sha256:' + release.sha256)) {
+        || matchingAssets.length !== 1
+        || asset.digest !== 'sha256:' + release.sha256) {
         throw new Error('Pinned proving release identity or immutability check failed');
     }
 }
@@ -185,13 +187,15 @@ async function replaceDirectoryAtomically(stage, target) {
         await rm(stage, { recursive: true, force: true });
     }
 }
-/** Fetches a pinned private GitHub release and atomically installs its safe USTAR bundle. */
+/** Installs the pinned package archive, or fetches the release for legacy/test callers. */
 export async function acquirePinnedArtifactBundle(options) {
     const release = options.manifest.release;
     if (!release)
         throw new Error('This sidecar manifest has no pinned artifact release');
     const names = new Set(options.manifest.artifacts.map((artifact) => artifact.file));
     const command = options.runGithubCommand ?? defaultGithubCommand;
+    const bundledArchivePath = options.bundledArchivePath
+        ?? (!options.runGithubCommand ? fileURLToPath(new URL('../circuits/base-sepolia-v2.tar.gz', import.meta.url)) : undefined);
     const parent = dirname(resolve(options.targetDirectory));
     const tempDirectory = join(parent, '.base-sepolia-download-' + randomUUID());
     const stage = join(parent, '.base-sepolia-stage-' + randomUUID());
@@ -199,16 +203,49 @@ export async function acquirePinnedArtifactBundle(options) {
         await mkdir(parent, { recursive: true, mode: 0o700 });
         await mkdir(tempDirectory, { recursive: false, mode: 0o700 });
         await mkdir(stage, { recursive: false, mode: 0o700 });
-        const releaseJson = await command(['api', `repos/${release.repository}/releases/${release.releaseId}`]);
-        pinnedAsset(release, releaseJson);
-        await command([
-            'release', 'download', release.tag,
-            '--repo', release.repository,
-            '--dir', tempDirectory,
-            '--pattern', release.assetName,
-        ]);
-        const archivePath = join(tempDirectory, release.assetName);
-        const archiveInfo = await lstat(archivePath);
+        if (!bundledArchivePath) {
+            try {
+                await command(['auth', 'status']);
+            }
+            catch {
+                throw new Error('GitHub CLI authentication is required; run gh auth login locally before downloading the pinned proving bundle.');
+            }
+            try {
+                const repositoryJson = await command(['api', `repos/${release.repository}`]);
+                const repository = JSON.parse(repositoryJson);
+                if (repository.full_name !== release.repository)
+                    throw new Error('Repository identity mismatch');
+            }
+            catch {
+                throw new Error(`Pinned proving bundle requires read access to ${release.repository}; ask the founder to grant access to your signed-in GitHub account.`);
+            }
+            let releaseJson;
+            try {
+                releaseJson = await command(['api', `repos/${release.repository}/releases/${release.releaseId}`]);
+            }
+            catch {
+                throw new Error('Pinned proving release metadata could not be read; ask the founder to verify the published release with an authorized account. A 404 does not distinguish a missing release from insufficient access.');
+            }
+            pinnedAsset(release, releaseJson);
+            try {
+                await command([
+                    'release', 'download', release.tag,
+                    '--repo', release.repository,
+                    '--dir', tempDirectory,
+                    '--pattern', release.assetName,
+                ]);
+            }
+            catch {
+                throw new Error('Pinned proving bundle download failed; verify gh access and the published release asset.');
+            }
+        }
+        const archivePath = bundledArchivePath ?? join(tempDirectory, release.assetName);
+        const archiveInfo = await lstat(archivePath).catch((error) => {
+            if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+                throw new Error('Pinned proving bundle archive is missing or too large');
+            }
+            throw error;
+        });
         if (archiveInfo.isSymbolicLink() || !archiveInfo.isFile() || archiveInfo.size > MAX_COMPRESSED_BYTES) {
             throw new Error('Pinned proving bundle archive is missing or too large');
         }
@@ -226,15 +263,23 @@ export async function acquirePinnedArtifactBundle(options) {
         for (const [name, bytes] of files)
             await writeBundleFile(stage, name, bytes);
         await chmod(stage, 0o700);
-        await resolvePinnedArtifactBundle({ artifactDirectory: stage, manifest: options.manifest });
+        try {
+            await resolvePinnedArtifactBundle({ artifactDirectory: stage, manifest: options.manifest });
+        }
+        catch (error) {
+            if (error instanceof ArtifactBundleError && error.category === 'artifact_hash_mismatch') {
+                throw new Error(`Pinned proving bundle file SHA-256 check failed: ${error.message}`, { cause: error });
+            }
+            throw error;
+        }
         await replaceDirectoryAtomically(stage, resolve(options.targetDirectory));
         await resolvePinnedArtifactBundle({ artifactDirectory: resolve(options.targetDirectory), manifest: options.manifest });
         return resolve(options.targetDirectory);
     }
     catch (error) {
-        if (error instanceof Error && /^(Pinned proving|This sidecar manifest|Local proving bundle)/u.test(error.message))
+        if (error instanceof Error && /^(Pinned proving|This sidecar manifest|Local proving bundle|GitHub CLI authentication)/u.test(error.message))
             throw error;
-        throw new Error('Pinned proving bundle acquisition failed; verify gh access and the published release pin.');
+        throw new Error('Pinned proving bundle acquisition failed; verify the packaged archive and manifest pins.');
     }
     finally {
         await rm(tempDirectory, { recursive: true, force: true });

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

@@ -1,11 +1,11 @@
 /**
- * One-shot local transport for exercising the official @x402/core adapter.
+ * One-shot local transport for the founder's task-running x402 demo agent.
  *
  * @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.
+ * the internal Base Sepolia founder demo, not as a general HTTP client.
  *
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
@@ -28,6 +28,10 @@ export interface BaseRegisteredTrialOptions extends BasePrepaidClientOptions {
     body: string;
     headers?: HeadersInit;
     fetch?: typeof fetch;
+    /** The response can be shown locally to the operator; it is never retained by metrics. */
+    onResponse?: (response: Response) => void | Promise<void>;
 }
+/** A bounded, single-task request for the founder's internal x402 demo. */
+export declare function buildBaseRegisteredTrialRequestBody(task?: string): string;
 /** 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

@@ -1,17 +1,27 @@
 /**
- * One-shot local transport for exercising the official @x402/core adapter.
+ * One-shot local transport for the founder's task-running x402 demo agent.
  *
  * @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.
+ * the internal Base Sepolia founder demo, 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';
+/** A bounded, single-task request for the founder's internal x402 demo. */
+export function buildBaseRegisteredTrialRequestBody(task = 'Reply with exactly: internal trial complete.') {
+    if (typeof task !== 'string' || task.trim().length === 0 || task.length > 4_000) {
+        throw new Error('Task must contain between 1 and 4000 characters');
+    }
+    return JSON.stringify({
+        model: 'deepseek/deepseek-v4-flash',
+        messages: [{ role: 'user', content: task }],
+    });
+}
 function observe(options, event) {
     try {
         options.lifecycle?.(event);
@@ -163,6 +173,12 @@ export async function runBaseRegisteredTrialExchange(options) {
     }
     result.responseSucceeded = true;
     observe(options, lifecycleStage('exchange_succeeded'));
+    try {
+        await options.onResponse?.(paidResponse.clone());
+    }
+    catch {
+        // Displaying a completed response is local convenience, not settlement.
+    }
     result.committedSlotDelta = ledger.snapshot().committed - startingCommittedSlots;
     return result;
 }

package/dist/base-sidecar.d.ts

@@ -50,6 +50,8 @@ export interface BasePrepaidClientOptions {
     credential: CreditCredential;
     witnessProvider: BaseWitnessProvider;
     prove: BaseProofGenerator;
+    /** Limits this local client to one proof attempt for a single internal trial. */
+    internalTrialOneProof?: boolean;
     fetch?: typeof fetch;
     /**
      * Durable local slot ledger. A slot is provisional until the proof passes

package/dist/base-sidecar.js

@@ -16,6 +16,12 @@ const TREE_DEPTH = 20;
 const FIELD_ORDER = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
 const REPLAY_TTL_MS = 24 * 60 * 60 * 1000;
 const MAX_PENDING_PAYMENTS = 64;
+const PAYMENT_PROOF_FIELDS = ['pi_a', 'pi_b', 'pi_c'];
+function proofForPayment(proof) {
+    return Object.fromEntries(PAYMENT_PROOF_FIELDS
+        .filter((field) => Object.prototype.hasOwnProperty.call(proof, field))
+        .map((field) => [field, proof[field]]));
+}
 function field(value, label) {
     if (!/^\d+$/u.test(value))
         throw new Error(`Invalid ${label}`);
@@ -63,6 +69,7 @@ function requestBodyBytes(body) {
 /** Creates the shared local proof factory used by both client transports. */
 export function createBasePaymentFactory(options) {
     const secret = secretFromBase64Url(options.credential.secret);
+    let internalTrialProofAttempted = false;
     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');
@@ -98,6 +105,11 @@ export function createBasePaymentFactory(options) {
                 nullifier,
                 share,
             ];
+            if (options.internalTrialOneProof) {
+                if (internalTrialProofAttempted)
+                    throw new Error('internal_trial_limit_reached');
+                internalTrialProofAttempted = true;
+            }
             const proof = await options.prove({
                 secret: secretToField(secret),
                 tier_id: String(options.credential.tierId),
@@ -118,7 +130,7 @@ export function createBasePaymentFactory(options) {
             await slotLedger.commit(selectedSlot);
             const payment = buildPaymentPayload({
                 requirements,
-                proof: proof.proof,
+                proof: proofForPayment(proof.proof),
                 publicSignals: [...proof.publicSignals],
                 nonce,
                 responseKey: responseKeys.publicKey,