x402trace 0.1.0 → 0.2.0

package/dist/diagnose/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * X402-21 v0.2 diagnose engine — shared types.
+ *
+ * The diagnose engine is the substrate behind two subcommands per
+ * [ADR-002](../../DECISIONS.md#adr-002-v02-feature-pick--validate-primary--explain-paired):
+ *
+ *   - `x402trace validate <wallet> <service>` — pre-flight check. The
+ *     wallet hasn't signed anything yet; live chain state is queried
+ *     and a *simulated* authorization is checked against the live 402
+ *     challenge.
+ *   - `x402trace explain <jsonl-log>` — offline diagnosis. The
+ *     authorization is captured (the user already signed); we explain
+ *     why it failed by running the same rules against the captured
+ *     state.
+ *
+ * Same engine, different input populations — `validate` runs with full
+ * `walletState` and a synthetic `payment`; `explain` runs with a real
+ * `payment` and potentially no `walletState` (the log doesn't capture
+ * balance/allowance at the time the request was made).
+ *
+ * Rules MUST be pure functions of the context — no I/O, no Date.now().
+ * The current time enters via `ctx.now`. This lets `explain` reproduce
+ * a diagnosis deterministically from a JSONL log.
+ */
+import type { PaymentPayload, PaymentRequirements } from "../decoder/types.js";
+/**
+ * Snapshot of the on-chain state needed to diagnose a payment. All
+ * fields are optional: `validate` populates them from live RPC,
+ * `explain` runs without them (since v0.1 logs don't capture chain
+ * state at the moment of failure).
+ */
+export interface WalletState {
+    /** Wallet's current USDC balance, in raw token units (no decimals applied). */
+    readonly usdcBalance?: bigint;
+    /**
+     * Whether the authorization's nonce has already been consumed. EIP-3009
+     * nonces are unique per `(authorizer, contract)`; a "true" here means
+     * the wallet has already used this nonce on the USDC contract.
+     */
+    readonly nonceConsumed?: boolean;
+    /**
+     * Loose classification of the wallet behind the address. v0.2 supports
+     * `eoa` and `smart-wallet`; `unknown` means we couldn't decide (treat
+     * as a warning rather than a failure).
+     */
+    readonly walletKind?: "eoa" | "smart-wallet" | "unknown";
+}
+export interface DiagnosticContext {
+    readonly requirements: PaymentRequirements;
+    /**
+     * Either a captured `PaymentPayload` (from `explain`) or a simulated
+     * one (from `validate`, constructed from the wallet address +
+     * requirements). When undefined, payment-side rules skip.
+     */
+    readonly payment?: PaymentPayload;
+    readonly walletState?: WalletState;
+    /**
+     * The instant the diagnosis runs. Used for `validBefore` window
+     * checks. Injected explicitly so the rule engine stays pure.
+     */
+    readonly now: Date;
+}
+export type DiagnosticStatus = "pass" | "fail" | "skip";
+export interface DiagnosticResult {
+    /** Stable identifier; downstream tools can grep / filter on this. */
+    readonly rule: string;
+    readonly status: DiagnosticStatus;
+    /**
+     * One-line human-readable description. On `pass` it states what was
+     * verified; on `fail` it states what was wrong; on `skip` it says
+     * what's missing from the context to run this check.
+     */
+    readonly message: string;
+    /** Plain-English actionable fix. Only present when `status === "fail"`. */
+    readonly fix?: string;
+}
+/**
+ * Top-level conclusion. Distinct from the per-rule statuses because a
+ * diagnosis with only `skip`s is meaningfully different from one with
+ * all `pass`es.
+ */
+export type OverallStatus = 
+/** Every applicable rule passed — the payment would (or did) succeed. */
+"would-succeed"
+/** At least one rule failed. */
+ | "would-fail"
+/** Some rules ran (no fails) but key checks were skipped — we can't be sure. */
+ | "uncertain";
+export interface DiagnosticReport {
+    readonly results: readonly DiagnosticResult[];
+    readonly overallStatus: OverallStatus;
+}
+/**
+ * A rule is a pure function from context to result. The `name` is the
+ * stable identifier surfaced in `DiagnosticResult.rule`.
+ */
+export interface DiagnosticRule {
+    readonly name: string;
+    readonly run: (ctx: DiagnosticContext) => DiagnosticResult;
+}

package/dist/diagnose/types.js

@@ -0,0 +1,25 @@
+/**
+ * X402-21 v0.2 diagnose engine — shared types.
+ *
+ * The diagnose engine is the substrate behind two subcommands per
+ * [ADR-002](../../DECISIONS.md#adr-002-v02-feature-pick--validate-primary--explain-paired):
+ *
+ *   - `x402trace validate <wallet> <service>` — pre-flight check. The
+ *     wallet hasn't signed anything yet; live chain state is queried
+ *     and a *simulated* authorization is checked against the live 402
+ *     challenge.
+ *   - `x402trace explain <jsonl-log>` — offline diagnosis. The
+ *     authorization is captured (the user already signed); we explain
+ *     why it failed by running the same rules against the captured
+ *     state.
+ *
+ * Same engine, different input populations — `validate` runs with full
+ * `walletState` and a synthetic `payment`; `explain` runs with a real
+ * `payment` and potentially no `walletState` (the log doesn't capture
+ * balance/allowance at the time the request was made).
+ *
+ * Rules MUST be pure functions of the context — no I/O, no Date.now().
+ * The current time enters via `ctx.now`. This lets `explain` reproduce
+ * a diagnosis deterministically from a JSONL log.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402trace",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local CLI for debugging x402 payment flows on Base — catches timeout reconciliation failures",
   "type": "module",
   "bin": {