x402trace 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -11,6 +11,28 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 —
 
+## [0.2.0] — 2026-05-12
+
+The v0.2 pre/post-payment debugger. v0.1 owned mid-flight (proxy) + post-settlement (reconcile); v0.2 adds pre-flight (`validate`) and offline failure diagnosis (`explain`), sharing a new pure rule engine in `src/diagnose/`. Closes pain ranks #3 (generic 402 with no error reason) and #4 (wallet-state pre-flight gap) from the X402-6 ranking. 278 tests, same Base Sepolia / `exact` EVM scope as v0.1 per [ADR-002](./DECISIONS.md#adr-002-v02-feature-pick--validate-primary--explain-paired). Apache-2.0.
+
+### Added
+
+- **`x402trace validate <wallet> <service-url>` (X402-21)** — read-only pre-flight before signing. Fetches the 402 challenge, queries on-chain USDC balance + EIP-3009 nonce status + wallet kind (EOA vs Smart Wallet via `getCode`), synthesises a hypothetical `PaymentPayload`, runs the diagnose engine, renders a plain-English report. Exits `0` for `would-succeed`, `2` for `would-fail`, `0` for `uncertain` (or `2` with `--strict`).
+- **`x402trace explain <jsonl-log-file>` (X402-21)** — read a JSONL log produced by `proxy --reconcile`, find every exchange where `reconcile.result.kind != 'settled_on_chain'` plus every `decoder.error`, run the same rule engine against captured state, print per-failure prose with actionable fixes. CI-friendly: exits `2` if any failures rendered, `0` if log was clean.
+- **`src/diagnose/` (X402-21)** — pure rule engine (no I/O, no `Date.now`). 10 rules covering network match, scheme match, recipient match, value sufficiency, `validBefore` / `validAfter` window, payer USDC balance, EIP-3009 nonce freshness, wallet kind (EOA + Smart Wallet; ERC-6492 deferred to v0.3 per ADR-002), and Base Sepolia USDC asset address. Each rule returns `pass` / `fail` / `skip`; `skip` means the context lacked the data (e.g. `explain` doesn't have live wallet state). Top-level status is `would-succeed` / `would-fail` / `uncertain` (the latter when the two critical chain-state rules are skipped).
+- **Chain client extensions (X402-21)** — `getUsdcBalance(wallet)`, `isNonceConsumed(authorizer, nonce)`, `detectWalletKind(wallet)` read-only methods on `ChainClient`, plus a narrow `USDC_READ_ABI` (just `balanceOf` + `authorizationState`). Used by `validate`; reusable by future v0.3 features.
+- **v0.2 feature pick (X402-20)** — ADR-002 records the decision + 4 rejected alternatives. SPEC.md § 5 flipped from "v0.2 stretch (deferred)" to "v0.2 scope" with a new v0.3 stretch list catching the deferrals. CLAUDE.md current-focus flipped to v0.2.
+- **CI release workflow `contents: write` fix** — release.yml's `Create GitHub Release` step had failed on the v0.1.0 cut with HTTP 403 because the job had `contents: read`. Promoted to `write` so v0.2.0+ tag-pushes self-create the GitHub Release without manual intervention.
+
+### Tests
+
+- 278 total (+63 from v0.1.0's 215). New: 36 unit tests for `diagnose-rules`, 14 for `validate-command`, 9 for `explain-command`, +4 for `cli-dispatcher` covering the new subcommands.
+
+### Notes
+
+- `package.json` bin layout unchanged from v0.1.0 — `x402trace` resolves to four subcommands (`proxy`, `inspect`, `validate`, `explain`).
+- `tsconfig.build.json` is still the published-bundle config; tarball stays ~62 files / ~156 KB.
+
 ## [0.1.0] — 2026-05-12
 
 The v0.1 wedge: a local proxy + timeout-reconciliation engine that catches the canonical [coinbase/x402#1062](https://github.com/coinbase/x402/issues/1062) symptom — buyer is debited on-chain but the facilitator/server thinks the payment failed. Verified end-to-end on real Base Sepolia + the live `x402.org/facilitator` (tx [`0x116ccf73…ba52`](https://sepolia.basescan.org/tx/0x116ccf73fa77eda19aea149606042f1e848e8afe2f719a0d2890dd2b2ff0ba52)). 215 tests, GitHub Actions CI on Node 20 + 22, Apache-2.0.
@@ -38,7 +60,7 @@ The v0.1 wedge: a local proxy + timeout-reconciliation engine that catches the c
 - **GitHub Actions CI (X402-18)** — `.github/workflows/ci.yml` runs `pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm build` on every PR + push to `v1` / `staging` / `main`. **Node 20 + 22 matrix**, pnpm-store cached via `actions/setup-node@v4`, 10-min job timeout, in-progress runs cancelled when a fresher commit lands on the same ref. `pnpm test` auto-skips `tests/e2e/chain-live.test.ts` (gated on `X402_E2E=1`), so the live-Base-Sepolia suite never burns testnet funds in CI. Companion `.github/workflows/release.yml` is the X402-19 substrate: tag-triggered (`v*.*.*`), runs the same quality bar, builds, and has the npm-publish step commented out until [X402-19](https://vahdatfardin.atlassian.net/browse/X402-19) wires the `NPM_TOKEN` secret. The CI badge in `README.md` (placeholder since X402-16) lights up on the first run.
 - **Unit-test coverage hardening (X402-17)** — Week-4 risk-reduction pass on the decoder, reconciliation, and CLI. Per the ticket spec ("chase risk reduction, not coverage targets"), targeted the gaps that break silently: (a) the streaming decoder's dispatch logic (`createDecoder().decode()`) had zero direct tests — new `tests/unit/decoder-decoder.test.ts` (11 tests) covers settlement-header parse errors, the `outcome.rawPaymentResponseHeader` fallback path, and `proxy.error` passthrough; (b) base64 + unicode edge cases on `parsePaymentHeader` / `parseChallengeBody` / `parseSettlementHeader` mirroring the [coinbase/x402#865](https://github.com/coinbase/x402/issues/865) surface area — CJK + emoji in `description` and `extra.name` round-trip, padding-stripped base64 tolerated, JSON primitives rejected, URL-safe base64 contract documented; (c) reconciliation `extractErrorReason` paths (non-JSON rawBody, JSON without `error`, missing rawBody), the `unknown` proxy outcome branch the X402-15 demo relies on, chain-transfer race conditions (arrival before pending join, duplicate transfers after match); (d) `x402trace proxy` env-var-vs-flag precedence — extracted `resolveProxyConfig(opts, env)` as a pure function from `proxy-command.ts` (small refactor for testability), then pinned the contract from [ARCHITECTURE.md § Configuration](./ARCHITECTURE.md#configuration) with 28 unit tests across `X402TRACE_UPSTREAM`, `X402TRACE_PORT`, `X402TRACE_LOG`, `X402TRACE_RECONCILE` (including non-truthy strings), `BASE_RPC_URL`, `X402TRACE_WATCH_TIMEOUT_MS`, `X402TRACE_UPSTREAM_TIMEOUT_MS`. Pipeline: **215 tests / 4 e2e skipped** (+57 vs the X402-16 baseline). Coverage: reconciliation **97% → 100%** lines/branches/funcs, decoder **79% → 90%**, src/cli **80.8% → 82%**.
 - **README rewrite (X402-16)**: replaced the pre-release skeleton with a 115-line README that hits all seven X402-16 required sections — elevator pitch, the problem (with the verbatim 502 the buyer sees), 30-second quickstart (`git clone` → `pnpm install` → `cp .env.example .env` → `./examples/e2e-timeout-reconciliation.sh`), how-it-works (4 bullets + ASCII flow diagram of proxy → server → facilitator → chain → engine), CLI reference (links to `--help` rather than duplicating), v0.2 roadmap pulled from [SPEC.md § 5](./SPEC.md#5-v02-stretch-deferred-not-killed), differentiation, contributing, license. Three badges added: Apache-2.0 license (live), GitHub Actions CI (placeholder — wires up automatically when [X402-18](https://vahdatfardin.atlassian.net/browse/X402-18) lands the workflow), npm version (placeholder — wires up automatically when [X402-19](https://vahdatfardin.atlassian.net/browse/X402-19) publishes `x402trace@0.1.0`). The captured X402-15 settlement tx [`0x116ccf73…ba52`](https://sepolia.basescan.org/tx/0x116ccf73fa77eda19aea149606042f1e848e8afe2f719a0d2890dd2b2ff0ba52) is linked from the quickstart's "what success looks like" output block; the asciinema cast is referenced by relative path for local `asciinema play` until [X402-23](https://vahdatfardin.atlassian.net/browse/X402-23) uploads it for an embeddable URL.
-- **End-to-end testnet demo (X402-15)** in `examples/e2e-timeout-reconciliation.sh` + `examples/README.md` + recorded asciinema cast at `examples/cast/e2e-timeout-reconciliation.cast`. The flagship reproduction of the canonical [#1062](https://github.com/coinbase/x402/issues/1062) scenario, runnable against real Base Sepolia + the real `x402.org/facilitator`. Choreography: dogfood server with new `DEMO_SLEEP_MS=10000` knob sleeps 10s *during* the x402-hono paymentMiddleware's protected handler — x402-hono verifies before the handler and settles after, so the post-handler /settle still broadcasts on-chain even though the proxy in front gave up at 5s. `x402trace proxy --reconcile --upstream-timeout-ms 5000` returns 502 to the client (the canonical "I thought it failed" signal), pends the exchange, watches Base Sepolia via the chain client's `subscribeUsdcTransfers`, matches the EIP-3009 nonce, and emits `RECONCILED ⚠ settled-but-server-thinks-not` with the live tx hash. **Verified end-to-end on Base Sepolia 2026-05-12** with on-chain settlement tx [`0x116ccf73…ba52`](https://sepolia.basescan.org/tx/0x116ccf73fa77eda19aea149606042f1e848e8afe2f719a0d2890dd2b2ff0ba52) (block 41402768) — captured in the committed asciinema cast; reconcile gap from proxy timeout to chain-detected was **11.9 seconds**. New `--upstream-timeout-ms` CLI flag on `x402trace proxy` exposes `ProxyOptions.upstreamTimeoutMs` to the surface. New `demoSleepMs` / `demoFailAfterSleep` fields on `DogfoodConfig` plus `DEMO_SLEEP_MS` / `DEMO_FAIL_AFTER_SLEEP` env wiring in `loadServerConfig` (`demoFailAfterSleep` is documented but NOT used in the canonical demo because x402-hono skips /settle on 5xx responses). 9 new tests — 8 unit tests covering env validation (positive/negative/zero/non-numeric) and CLI help inclusion, plus 1 hermetic integration test (`tests/integration/demo-timeout-reconciliation.test.ts`) that reproduces the full demo storyline against the mock facilitator with a synthetic `ChainTransfer`. Pipeline: 158 tests / 4 e2e skipped, typecheck + lint clean. README rewritten with a quick-demo hero section.
+- **End-to-end testnet demo (X402-15)** in `examples/e2e-timeout-reconciliation.sh` + `examples/README.md` + recorded asciinema cast at `examples/cast/e2e-timeout-reconciliation.cast`. The flagship reproduction of the canonical [#1062](https://github.com/coinbase/x402/issues/1062) scenario, runnable against real Base Sepolia + the real `x402.org/facilitator`. Choreography: dogfood server with new `DEMO_SLEEP_MS=10000` knob sleeps 10s _during_ the x402-hono paymentMiddleware's protected handler — x402-hono verifies before the handler and settles after, so the post-handler /settle still broadcasts on-chain even though the proxy in front gave up at 5s. `x402trace proxy --reconcile --upstream-timeout-ms 5000` returns 502 to the client (the canonical "I thought it failed" signal), pends the exchange, watches Base Sepolia via the chain client's `subscribeUsdcTransfers`, matches the EIP-3009 nonce, and emits `RECONCILED ⚠ settled-but-server-thinks-not` with the live tx hash. **Verified end-to-end on Base Sepolia 2026-05-12** with on-chain settlement tx [`0x116ccf73…ba52`](https://sepolia.basescan.org/tx/0x116ccf73fa77eda19aea149606042f1e848e8afe2f719a0d2890dd2b2ff0ba52) (block 41402768) — captured in the committed asciinema cast; reconcile gap from proxy timeout to chain-detected was **11.9 seconds**. New `--upstream-timeout-ms` CLI flag on `x402trace proxy` exposes `ProxyOptions.upstreamTimeoutMs` to the surface. New `demoSleepMs` / `demoFailAfterSleep` fields on `DogfoodConfig` plus `DEMO_SLEEP_MS` / `DEMO_FAIL_AFTER_SLEEP` env wiring in `loadServerConfig` (`demoFailAfterSleep` is documented but NOT used in the canonical demo because x402-hono skips /settle on 5xx responses). 9 new tests — 8 unit tests covering env validation (positive/negative/zero/non-numeric) and CLI help inclusion, plus 1 hermetic integration test (`tests/integration/demo-timeout-reconciliation.test.ts`) that reproduces the full demo storyline against the mock facilitator with a synthetic `ChainTransfer`. Pipeline: 158 tests / 4 e2e skipped, typecheck + lint clean. README rewritten with a quick-demo hero section.
 - **CLI binary (X402-14)** in `src/cli/` + `src/cli.ts`: the user-facing surface for v0.1, composing the four substrates (Proxy / Decoder / Chain / Reconciliation) into a single `x402trace` command. Two subcommands — `x402trace proxy --upstream <url> [--port 8402] [--log human|json] [--log-file <path>] [--log-secrets] [--reconcile] [--rpc-url <url>] [--watch-timeout-ms <n>]` runs the live pipeline; `x402trace inspect <jsonl-log-file> [--log human|json] [--watch-timeout-ms <n>]` replays a captured log and re-runs reconciliation offline. Built on `commander@14`. Modules — `index.ts` (commander dispatch + `runCli` testable entry), `proxy-command.ts` (live pipeline wiring; opens a second `JsonlSink` against the same log path for `chain.transfer` and `reconcile.result` records — **closes the X402-13 deferred acceptance bullet** "All reconciliation events written to a local JSONL log file"), `inspect-command.ts` (offline replay), `replay.ts` (JSONL reader driving a virtual-clock engine via the new `engine.tick()` sweep method), `format-result.ts` (human + JSON renderers for `ReconciliationResult` — the canonical `RECONCILED ⚠ settled-but-server-thinks-not` headline per [SPEC.md § 3](./SPEC.md#3-user-flow)), `color.ts` (TTY + `NO_COLOR`-aware ANSI helpers; no `chalk` dep), `exit-codes.ts` (0 success / 1 usage / 2 runtime per the X402-14 ticket). 28 new unit tests + 1 smoke test that drives the full proxy + decoder + JSONL pipeline against the dogfood rig and replays the captured log through `inspect`. Pipeline: 149 tests / 4 e2e skipped, typecheck + lint clean. `scripts/proxy.ts` is now a thin shim that defers to `runCli`; `pnpm proxy` and `pnpm x402trace` both work, and `npx x402trace` will work once published.
 - **Timeout reconciliation engine (X402-13)** in `src/reconciliation/`: the headline feature of the v0.1 wedge. Four modules — `types.ts` (`PendingExchange` + `ReconciliationResult` 4-variant discriminated union: `settled_on_chain` / `not_settled` / `value_mismatch` / `recipient_mismatch`), `match.ts` (pure `matchPendingAgainstTransfer` checking `(payer, payee, value, nonce)` exact-equality; case-insensitive on addresses + nonce), `engine.ts` (`createReconciliationEngine({watchTimeoutMs?, sweepIntervalMs?, now?}) → Engine` with three ingest methods for proxy / decoder / chain streams, in-memory pending-set with two-half-join semantics, periodic sweep for `not_settled` after `watchTimeoutMs` (default 60_000), injectable clock for tests), `index.ts`. 17 unit tests covering the match function + engine lifecycle (rejected outcomes flag, paid outcomes don't, settled_on_chain emit, not_settled timeout, value/recipient mismatch, arrival-order independence) + 2-test integration that **reproduces the canonical [#1062](https://github.com/coinbase/x402/issues/1062) scenario** end-to-end: mock facilitator rejects → engine emits `settled_on_chain` when matching ChainTransfer arrives. Pipeline: 120 tests / 4 e2e skipped, no new deps.
 - Local mock x402 facilitator (X402-3) at `src/dogfood/mock-facilitator.ts` implementing v1 `POST /verify` and `POST /settle` with canned-success responses. Unblocks integration testing without on-chain USDC and provides the test harness `TESTING.md` calls for. `scripts/mock-facilitator.ts` is the standalone entry; `tests/integration/dogfood-paid-flow.test.ts` asserts the full 402 → signed retry → 200 + `X-PAYMENT-RESPONSE` flow against it.
@@ -67,5 +89,6 @@ The v0.1 wedge: a local proxy + timeout-reconciliation engine that catches the c
 
 ---
 
-[Unreleased]: https://github.com/fardinvahdat/x402trace/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/fardinvahdat/x402trace/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/fardinvahdat/x402trace/releases/tag/v0.2.0
 [0.1.0]: https://github.com/fardinvahdat/x402trace/releases/tag/v0.1.0

package/README.md

@@ -84,25 +84,37 @@ Full architecture: [ARCHITECTURE.md](./ARCHITECTURE.md). Wedge rationale: [DECIS
 ## CLI
 
 ```bash
-x402trace proxy   --upstream <url> [--reconcile] [--log human|json] …
-x402trace inspect <jsonl-log-file> [--log human|json] …
+# v0.1 — during/after payment
+x402trace proxy    --upstream <url> [--reconcile] [--log human|json] …
+x402trace inspect  <jsonl-log-file> [--log human|json] …
+
+# v0.2 — before/explaining payment
+x402trace validate <wallet> <service-url> [--strict] [--log human|json]
+x402trace explain  <jsonl-log-file> [--log human|json]
 ```
 
-The authoritative flag list is `x402trace --help` / `x402trace proxy --help` / `x402trace inspect --help` — they're the source of truth and are wired into the unit tests. See also [`pnpm x402trace --help`](./src/cli/index.ts) directly in the repo.
+The full pre/during/post-payment debugger:
+
+- **`validate <wallet> <service>`** — read-only pre-flight before signing. Fetches the 402, queries USDC balance + EIP-3009 nonce + wallet kind, runs 10 diagnostic rules, prints a plain-English report. Exits 0 if the payment would succeed, 2 if it would fail. Closes [pain rank #4](./dogfood-notes.md#top-painful-moments-synthesized---x402-6) (wallet-state pre-flight gap).
+- **`explain <jsonl-log>`** — read a JSONL log produced by `proxy --reconcile`, find every exchange that didn't `settled_on_chain`, run the same rule engine against the captured state, print per-failure prose with actionable fixes. CI-friendly: exits 2 if any failures, 0 if clean. Closes [pain rank #3](./dogfood-notes.md#top-painful-moments-synthesized---x402-6) (generic 402 with no error reason).
+
+The authoritative flag list is `x402trace --help` (or per-subcommand `--help`) — they're the source of truth and are wired into the unit tests.
 
 ## Roadmap
 
-**v0.1** (current, ~6 weeks from project start) — local proxy + timeout reconciliation + structured logs. Base Sepolia, `x402.org/facilitator`, `exact` EVM scheme only. Detect-and-notify, no auto-refund. Wedge accepted in [ADR-001](./DECISIONS.md).
+**v0.1.0** (shipped 2026-05-12 as [`x402trace@0.1.0`](https://www.npmjs.com/package/x402trace)) — local proxy + timeout reconciliation + structured logs. Base Sepolia, `x402.org/facilitator`, `exact` EVM scheme only. Detect-and-notify, no auto-refund. Wedge accepted in [ADR-001](./DECISIONS.md#adr-001-v01-wedge). Verified by three independent live Base Sepolia settlements.
+
+**v0.2** (current) — `validate` (pre-flight) + `explain` (offline 402 diagnosis), sharing a new `src/diagnose/` rule engine. Same scope tightening as v0.1: Base Sepolia, single facilitator, `exact` EVM, read-only. Decision: [ADR-002](./DECISIONS.md#adr-002-v02-feature-pick--validate-primary--explain-paired).
 
-**v0.2 stretch** (from [SPEC.md § 5](./SPEC.md#5-v02-stretch-deferred-not-killed), ordered by ranked dogfood pain):
+**v0.3 stretch** (kept, not killed — full list in [SPEC.md § 5](./SPEC.md#5-v02-scope-picked-in-adr-002)):
 
 - Mainnet (after ≥1 week of clean testnet traffic)
-- `x402trace inspect <captured-402.json>` — pure-function offline 402 decode
-- `x402trace doctor <wallet> <service>` — pre-flight wallet/service check
+- ERC-6492 wallet-kind support in `validate`
+- `x402trace diff` — cross-facilitator behavior comparison
 - `x402trace bazaar-check` — Bazaar indexing diagnostics
-- `x402trace versions` — SDK-skew audit across `x402`, `x402-fetch`, facilitator
-- Multi-facilitator support (CDP, PayAI, x402-rs)
-- Reconciliation **actions** beyond JSONL (webhook, structured remediation)
+- `x402trace versions` — SDK-skew audit
+- `--watch` daemon mode with alerting integrations
+- Reconciliation actions beyond JSONL (webhook, optional auto-retry)
 
 ## Differentiation
 

package/dist/chain/abi.d.ts

@@ -46,3 +46,38 @@ export declare const AUTHORIZATION_USED_EVENT: {
         readonly type: "bytes32";
     }];
 };
+/**
+ * Read-only USDC functions used by `validate` (X402-21). `balanceOf`
+ * and EIP-3009's `authorizationState` give us pre-flight visibility
+ * without signing anything. Kept narrow — we only declare the
+ * functions we actually call, so importing this ABI subset doesn't
+ * advertise capabilities x402trace doesn't use.
+ */
+export declare const USDC_READ_ABI: readonly [{
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly name: "balanceOf";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly name: "authorizationState";
+    readonly inputs: readonly [{
+        readonly name: "authorizer";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}];

package/dist/chain/abi.js

@@ -32,3 +32,32 @@ export const AUTHORIZATION_USED_EVENT = {
         { indexed: true, name: "nonce", type: "bytes32" },
     ],
 };
+/**
+ * Read-only USDC functions used by `validate` (X402-21). `balanceOf`
+ * and EIP-3009's `authorizationState` give us pre-flight visibility
+ * without signing anything. Kept narrow — we only declare the
+ * functions we actually call, so importing this ABI subset doesn't
+ * advertise capabilities x402trace doesn't use.
+ */
+export const USDC_READ_ABI = [
+    {
+        type: "function",
+        stateMutability: "view",
+        name: "balanceOf",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        // EIP-3009: returns true iff the nonce was already consumed for
+        // this authorizer. `transferWithAuthorization` flips this from
+        // false to true atomically with the Transfer.
+        type: "function",
+        stateMutability: "view",
+        name: "authorizationState",
+        inputs: [
+            { name: "authorizer", type: "address" },
+            { name: "nonce", type: "bytes32" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+    },
+];

package/dist/chain/client.js

@@ -1,6 +1,6 @@
 import { createPublicClient, decodeEventLog, http } from "viem";
 import { baseSepolia } from "viem/chains";
-import { AUTHORIZATION_USED_EVENT, BASE_SEPOLIA_USDC, USDC_TRANSFER_EVENT } from "./abi.js";
+import { AUTHORIZATION_USED_EVENT, BASE_SEPOLIA_USDC, USDC_READ_ABI, USDC_TRANSFER_EVENT, } from "./abi.js";
 import { withRetry } from "./retry.js";
 const DEFAULT_RPC_URL = "https://sepolia.base.org";
 const DEFAULT_POLL_INTERVAL_MS = 4_000;
@@ -273,11 +273,44 @@ export function createChainClient(opts = {}) {
             s.stop();
         subscribers.clear();
     }
+    // ─── X402-21 v0.2 read-only pre-flight helpers ─────────────────
+    // Used by `validate`. All three are pure reads; never broadcast.
+    async function getUsdcBalance(wallet) {
+        return withRetry(() => client.readContract({
+            address: BASE_SEPOLIA_USDC,
+            abi: USDC_READ_ABI,
+            functionName: "balanceOf",
+            args: [wallet],
+        }), { retries });
+    }
+    async function isNonceConsumed(authorizer, nonce) {
+        return withRetry(() => client.readContract({
+            address: BASE_SEPOLIA_USDC,
+            abi: USDC_READ_ABI,
+            functionName: "authorizationState",
+            args: [authorizer, nonce],
+        }), { retries });
+    }
+    async function detectWalletKind(wallet) {
+        try {
+            const code = await withRetry(() => client.getCode({ address: wallet }), { retries });
+            // viem returns undefined for accounts with no code (EOA).
+            if (code === undefined || code === "0x")
+                return "eoa";
+            return "smart-wallet";
+        }
+        catch {
+            return "unknown";
+        }
+    }
     return {
         getTransferByTxHash,
         verifyTransfer,
         subscribeUsdcTransfers,
         getBlockNumber,
+        getUsdcBalance,
+        isNonceConsumed,
+        detectWalletKind,
         close,
     };
 }

package/dist/chain/types.d.ts

@@ -89,6 +89,30 @@ export interface ChainClient {
     };
     /** Current head block number. Used to compute confirmations. */
     getBlockNumber(): Promise<bigint>;
+    /**
+     * X402-21 v0.2: read-only USDC balance for `validate`'s pre-flight
+     * check. Returns the raw token amount (no decimals applied) so the
+     * diagnose engine compares as bigints.
+     */
+    getUsdcBalance(wallet: Address): Promise<bigint>;
+    /**
+     * X402-21 v0.2: EIP-3009 nonce status. Returns true iff
+     * `(authorizer, nonce)` has already been consumed on the USDC
+     * contract. Used by the `nonce-fresh` diagnostic rule.
+     */
+    isNonceConsumed(authorizer: Address, nonce: Hex): Promise<boolean>;
+    /**
+     * X402-21 v0.2: best-effort wallet kind classification.
+     * - `eoa` if the address has no contract code
+     * - `smart-wallet` if it does
+     * - `unknown` if the chain call errored
+     *
+     * v0.2 doesn't distinguish ERC-6492 (undeployed Smart Wallet) — that's
+     * a v0.3 gap per ADR-002. A real ERC-6492 wallet that's never been
+     * deployed shows up here as `eoa` (no code), which the diagnose
+     * engine surfaces as a soft warning rather than a hard pass.
+     */
+    detectWalletKind(wallet: Address): Promise<"eoa" | "smart-wallet" | "unknown">;
     /** Tear down any watchers. */
     close(): Promise<void>;
 }

package/dist/cli/explain-command.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `x402trace explain <jsonl-log-file>` — offline plain-English
+ * diagnosis (X402-21 v0.2 per [ADR-002](../../DECISIONS.md#adr-002-v02-feature-pick--validate-primary--explain-paired)).
+ *
+ * Pure-offline: never opens an HTTP server, never makes an RPC call.
+ * Reads the JSONL log a `proxy --reconcile` run produced, walks it
+ * once to build a per-exchange index, then renders a diagnose report
+ * for every exchange whose reconcile outcome wasn't `settled_on_chain`
+ * plus every standalone `decoder.error` event.
+ *
+ * Distinct from `inspect` (X402-14):
+ *   - `inspect` re-runs the reconciliation match logic; output is
+ *     reconcile-engine-shaped (`settled_on_chain` / `not_settled` / …).
+ *   - `explain` re-runs the diagnose rule engine; output is
+ *     per-failure prose with actionable fixes.
+ *
+ * The two are complementary — `inspect` says "the match logic still
+ * says 12 of your 50 exchanges failed reconciliation"; `explain` says
+ * "the recipient address on exchange `94c15089` doesn't match the
+ * challenge's payTo, fix with …".
+ */
+import type { LogFormat } from "../decoder/types.js";
+import { type Colorizer } from "./color.js";
+import { type ExitCode } from "./exit-codes.js";
+export interface ExplainCommandOptions {
+    readonly logFile?: string;
+    readonly log?: LogFormat;
+}
+export interface ExplainRunContext {
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly color?: Colorizer;
+    /** Injectable clock for deterministic tests. */
+    readonly now?: () => Date;
+}
+export declare function runExplainCommand(opts: ExplainCommandOptions, ctx: ExplainRunContext): Promise<ExitCode>;

package/dist/cli/explain-command.js

@@ -0,0 +1,162 @@
+/**
+ * `x402trace explain <jsonl-log-file>` — offline plain-English
+ * diagnosis (X402-21 v0.2 per [ADR-002](../../DECISIONS.md#adr-002-v02-feature-pick--validate-primary--explain-paired)).
+ *
+ * Pure-offline: never opens an HTTP server, never makes an RPC call.
+ * Reads the JSONL log a `proxy --reconcile` run produced, walks it
+ * once to build a per-exchange index, then renders a diagnose report
+ * for every exchange whose reconcile outcome wasn't `settled_on_chain`
+ * plus every standalone `decoder.error` event.
+ *
+ * Distinct from `inspect` (X402-14):
+ *   - `inspect` re-runs the reconciliation match logic; output is
+ *     reconcile-engine-shaped (`settled_on_chain` / `not_settled` / …).
+ *   - `explain` re-runs the diagnose rule engine; output is
+ *     per-failure prose with actionable fixes.
+ *
+ * The two are complementary — `inspect` says "the match logic still
+ * says 12 of your 50 exchanges failed reconciliation"; `explain` says
+ * "the recipient address on exchange `94c15089` doesn't match the
+ * challenge's payTo, fix with …".
+ */
+import { readFile, stat } from "node:fs/promises";
+import { diagnose, formatReportHuman, formatReportJson } from "../diagnose/index.js";
+import { createColorizer } from "./color.js";
+import { EXIT_RUNTIME, EXIT_SUCCESS, EXIT_USAGE } from "./exit-codes.js";
+export async function runExplainCommand(opts, ctx) {
+    const logFile = opts.logFile;
+    if (!logFile) {
+        ctx.stderr.write("error: <jsonl-log-file> argument is required\n");
+        return EXIT_USAGE;
+    }
+    try {
+        const s = await stat(logFile);
+        if (!s.isFile()) {
+            ctx.stderr.write(`error: ${logFile} is not a file\n`);
+            return EXIT_USAGE;
+        }
+    }
+    catch {
+        ctx.stderr.write(`error: cannot read ${logFile}\n`);
+        return EXIT_USAGE;
+    }
+    const format = opts.log ?? "human";
+    const color = ctx.color ?? createColorizer({ stream: ctx.stdout });
+    const now = (ctx.now ?? (() => new Date()))();
+    // ─── Walk the log once, indexing by exchange id ────────────────
+    // For each exchange we need the challenge (requirements), the
+    // payment (authorization), and the reconcile.result if any. We
+    // *don't* need walletState — the log doesn't capture it.
+    const challenges = new Map();
+    const payments = new Map();
+    const reconcileResults = new Map();
+    const decoderErrors = [];
+    const raw = await readFile(logFile, "utf8");
+    let lineNum = 0;
+    for (const line of raw.split("\n")) {
+        lineNum += 1;
+        if (!line.trim())
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            // Bad line — skip silently. `inspect` already covers this surface
+            // (it logs counts.linesSkipped); duplicate the count handling here.
+            continue;
+        }
+        if (!rec || typeof rec !== "object")
+            continue;
+        const r = rec;
+        const event = typeof r.event === "string" ? r.event : null;
+        const id = typeof r.id === "string" ? r.id : null;
+        if (event === "exchange.challenge" && id && typeof r.challenge === "object") {
+            challenges.set(id, r.challenge);
+        }
+        else if (event === "exchange.payment" && id && typeof r.payment === "object") {
+            payments.set(id, r.payment);
+        }
+        else if (event === "reconcile.result" && typeof r.exchangeId === "string") {
+            reconcileResults.set(r.exchangeId, {
+                kind: typeof r.kind === "string" ? r.kind : "unknown",
+                ts: typeof r.t === "string" ? r.t : "",
+            });
+        }
+        else if (event === "decoder.error") {
+            decoderErrors.push({
+                ts: typeof r.t === "string" ? r.t : "",
+                ...(id ? { id } : {}),
+                stage: typeof r.stage === "string" ? r.stage : "unknown",
+                message: typeof r.message === "string" ? r.message : "",
+            });
+        }
+    }
+    // ─── Filter: which exchanges deserve an "explain" block? ───────
+    // - Any reconcile.result whose kind != settled_on_chain → that exchange failed.
+    // - Any decoder.error → render its message + the exchange context (if id available).
+    const explainableExchangeIds = new Set();
+    for (const [id, result] of reconcileResults) {
+        if (result.kind !== "settled_on_chain")
+            explainableExchangeIds.add(id);
+    }
+    // ─── Render ────────────────────────────────────────────────────
+    const counts = {
+        linesTotal: lineNum,
+        explained: 0,
+        decoderErrors: decoderErrors.length,
+    };
+    if (format === "human") {
+        ctx.stdout.write(`${color.paint("bold", `explain ${logFile}`)}  ${color.paint("dim", `(${challenges.size} exchanges captured, ${reconcileResults.size} reconciled)`)}\n\n`);
+    }
+    for (const id of explainableExchangeIds) {
+        const requirements = challenges.get(id);
+        const payment = payments.get(id);
+        const result = reconcileResults.get(id);
+        if (!requirements) {
+            // Can't diagnose without a challenge to compare against.
+            if (format === "human") {
+                ctx.stdout.write(`${color.paint("yellow", "⚠")} exchange ${color.paint("bold", id.slice(0, 8))}…: reconcile said ${result?.kind} but no challenge in log — skipping\n`);
+            }
+            continue;
+        }
+        const diagCtx = {
+            requirements,
+            ...(payment ? { payment } : {}),
+            now,
+        };
+        const report = diagnose(diagCtx);
+        counts.explained += 1;
+        if (format === "human") {
+            ctx.stdout.write(`${color.paint("bold", `─── exchange ${id.slice(0, 8)}… ${result?.kind} at ${result?.ts} ───`)}\n`);
+            ctx.stdout.write(`${formatReportHuman(report, color)}\n\n`);
+        }
+        else {
+            ctx.stdout.write(`${JSON.stringify({ event: "explain.exchange", exchangeId: id, reconcileKind: result?.kind, ts: result?.ts })}\n`);
+            ctx.stdout.write(`${formatReportJson(report)}\n`);
+        }
+    }
+    // Standalone decoder errors (no diagnose run — just surface them).
+    for (const err of decoderErrors) {
+        if (format === "human") {
+            const idLabel = err.id ? `${err.id.slice(0, 8)}…` : "(no id)";
+            ctx.stdout.write(`${color.paint("red", "✗")} decoder.error ${color.paint("bold", idLabel)} stage=${err.stage}: ${err.message}\n`);
+        }
+        else {
+            ctx.stdout.write(`${JSON.stringify({ event: "explain.decoder-error", ...err })}\n`);
+        }
+    }
+    // Trailer counts so downstream tools can sanity-check.
+    if (format === "human") {
+        ctx.stdout.write(`\n${color.paint("dim", `explained ${counts.explained} failed exchange(s), ${counts.decoderErrors} decoder error(s) from ${counts.linesTotal} lines`)}\n`);
+    }
+    else {
+        ctx.stdout.write(`${JSON.stringify({ event: "explain.summary", ...counts })}\n`);
+    }
+    // Exit code: 2 if any exchange or decoder error was rendered; 0 if
+    // the log was clean. This makes `explain` usable in CI to gate
+    // "no reconciliation failures since last deploy".
+    if (counts.explained > 0 || counts.decoderErrors > 0)
+        return EXIT_RUNTIME;
+    return EXIT_SUCCESS;
+}

package/dist/cli/index.d.ts

@@ -1,11 +1,13 @@
 /**
- * X402-14 CLI surface. Two subcommands:
+ * CLI surface. Four subcommands:
  *
- *   x402trace proxy --upstream <url> [--port 8402] [--log human|json] [--reconcile] …
- *   x402trace inspect <jsonl-log-file> [--log human|json] …
+ *   x402trace proxy    --upstream <url> [--reconcile] [--log human|json] …    (X402-14)
+ *   x402trace inspect  <jsonl-log-file> [--log human|json] …                  (X402-14)
+ *   x402trace validate <wallet> <service-url> [--strict] [--log human|json]   (X402-21 v0.2)
+ *   x402trace explain  <jsonl-log-file> [--log human|json]                    (X402-21 v0.2)
  *
  * `commander` does the parsing; we own the wiring + exit-code
- * discipline. See X402-14 Jira for acceptance criteria.
+ * discipline.
  *
  * `runCli` is the testable entry; `src/cli.ts` is the bin shim that
  * calls it with the real `process` handles.

package/dist/cli/index.js

@@ -1,19 +1,23 @@
 /**
- * X402-14 CLI surface. Two subcommands:
+ * CLI surface. Four subcommands:
  *
- *   x402trace proxy --upstream <url> [--port 8402] [--log human|json] [--reconcile] …
- *   x402trace inspect <jsonl-log-file> [--log human|json] …
+ *   x402trace proxy    --upstream <url> [--reconcile] [--log human|json] …    (X402-14)
+ *   x402trace inspect  <jsonl-log-file> [--log human|json] …                  (X402-14)
+ *   x402trace validate <wallet> <service-url> [--strict] [--log human|json]   (X402-21 v0.2)
+ *   x402trace explain  <jsonl-log-file> [--log human|json]                    (X402-21 v0.2)
  *
  * `commander` does the parsing; we own the wiring + exit-code
- * discipline. See X402-14 Jira for acceptance criteria.
+ * discipline.
  *
  * `runCli` is the testable entry; `src/cli.ts` is the bin shim that
  * calls it with the real `process` handles.
  */
 import "dotenv/config";
 import { Command } from "commander";
+import { runExplainCommand } from "./explain-command.js";
 import { runInspectCommand } from "./inspect-command.js";
 import { runProxyCommand } from "./proxy-command.js";
+import { runValidateCommand } from "./validate-command.js";
 import { EXIT_SUCCESS, EXIT_USAGE } from "./exit-codes.js";
 // Keep in sync with package.json `version`. A runtime read from
 // package.json would be more durable but requires JSON-module
@@ -21,7 +25,7 @@ import { EXIT_SUCCESS, EXIT_USAGE } from "./exit-codes.js";
 // both `tsx src/cli.ts` (dev) and `dist/cli.js` (published) — folding
 // that into a follow-up cleanup. Until then, the X402-19 release
 // checklist + the changelog-cut step are the guards against drift.
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 export async function runCli(argv, ctx) {
     const program = new Command();
     program
@@ -88,6 +92,36 @@ export async function runCli(argv, ctx) {
                 : {}),
         }, { stdout: ctx.stdout, stderr: ctx.stderr });
     });
+    program
+        .command("validate")
+        .description("Pre-flight check: would <wallet> succeed paying <service-url>? Read-only, no signing.")
+        .argument("<wallet>", "Payer wallet address (0x-prefixed, 20 bytes)")
+        .argument("<service-url>", "Service URL that responds 402 with an x402 challenge")
+        .option("--log <human|json>", "Stdout format (default 'human')", validateLogFormat)
+        .option("--rpc-url <url>", "Base Sepolia RPC URL (env BASE_RPC_URL)")
+        .option("--strict", "Treat `uncertain` (key chain checks skipped) as a failure — exit 2 instead of 0")
+        .action(async (wallet, service, flags) => {
+        const log = flags.log;
+        exit = await runValidateCommand({
+            wallet,
+            service,
+            ...(log !== undefined ? { log } : {}),
+            ...(flags.rpcUrl !== undefined ? { rpcUrl: flags.rpcUrl } : {}),
+            ...(flags.strict !== undefined ? { strict: flags.strict } : {}),
+        }, { stdout: ctx.stdout, stderr: ctx.stderr, env: ctx.env });
+    });
+    program
+        .command("explain")
+        .description("Plain-English diagnosis of every failed exchange in a captured JSONL log. Offline.")
+        .argument("<jsonl-log-file>", "Path to a JSONL log written by `x402trace proxy --reconcile`")
+        .option("--log <human|json>", "Stdout format (default 'human')", validateLogFormat)
+        .action(async (logFile, flags) => {
+        const log = flags.log;
+        exit = await runExplainCommand({
+            logFile,
+            ...(log !== undefined ? { log } : {}),
+        }, { stdout: ctx.stdout, stderr: ctx.stderr });
+    });
     try {
         await program.parseAsync([...argv], { from: "user" });
     }

package/dist/cli/validate-command.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `x402trace validate <wallet> <service-url>` — pre-flight check
+ * (X402-21 v0.2, per [ADR-002](../../DECISIONS.md#adr-002-v02-feature-pick--validate-primary--explain-paired)).
+ *
+ * Reads a service's 402 challenge, queries the wallet's on-chain state,
+ * builds a `DiagnosticContext`, and runs the `diagnose()` engine. No
+ * signing, no broadcasting — wallet provided is just the address.
+ *
+ * Exit codes match the v0.1 convention:
+ *   0 = would succeed (or uncertain — see --strict)
+ *   1 = usage error
+ *   2 = would fail OR runtime error
+ *
+ * Flow:
+ *   1. GET <service-url> (no X-PAYMENT) → expect 402 + challenge body
+ *   2. Decode challenge via the v0.1 `parseChallengeBody`
+ *   3. Synthesise a `PaymentPayload` that would satisfy the challenge
+ *      (so payment-side rules can sanity-check the requirements
+ *      *themselves* — e.g. invalid asset, weird scheme — before we
+ *      worry about wallet state).
+ *   4. Query: USDC balance, EIP-3009 nonce state for the synthesised
+ *      nonce, wallet kind.
+ *   5. Build context + run engine + render.
+ */
+import { type ChainClient } from "../chain/index.js";
+import type { LogFormat } from "../decoder/types.js";
+import { type Colorizer } from "./color.js";
+import { type ExitCode } from "./exit-codes.js";
+export interface ValidateCommandOptions {
+    readonly wallet?: string;
+    readonly service?: string;
+    readonly log?: LogFormat;
+    readonly rpcUrl?: string;
+    /**
+     * When true, the "uncertain" overall status (key chain checks
+     * skipped) exits 2 instead of 0. Default false — `uncertain` is a
+     * warning, not a failure, since the user might have an RPC outage.
+     */
+    readonly strict?: boolean;
+}
+export interface ValidateRunContext {
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly color?: Colorizer;
+    /**
+     * Injectable chain-client factory so tests can mock without standing
+     * up a real Base Sepolia RPC. Defaults to `createChainClient`.
+     */
+    readonly chainFactory?: (rpcUrl?: string) => ChainClient;
+    /** Injectable fetch for the 402 GET. Defaults to global `fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Injectable clock for deterministic tests. */
+    readonly now?: () => Date;
+}
+export declare function runValidateCommand(opts: ValidateCommandOptions, ctx: ValidateRunContext): Promise<ExitCode>;