x402trace 0.1.0 → 0.2.0

package/dist/cli/validate-command.js

@@ -0,0 +1,141 @@
+/**
+ * `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 { createChainClient } from "../chain/index.js";
+import { parseChallengeBody } from "../decoder/parse.js";
+import { diagnose, formatReportHuman, formatReportJson } from "../diagnose/index.js";
+import { createColorizer } from "./color.js";
+import { EXIT_RUNTIME, EXIT_SUCCESS, EXIT_USAGE } from "./exit-codes.js";
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+// Conservative synthesised nonce — all-zero. The nonce-fresh rule will
+// query `authorizationState` for it; an unused all-zero nonce will
+// almost certainly come back `false` (i.e. fresh), so the simulation
+// is realistic for a wallet that hasn't paid this service yet.
+const SYNTHESISED_NONCE = `0x${"0".repeat(64)}`;
+export async function runValidateCommand(opts, ctx) {
+    if (!opts.wallet || !opts.service) {
+        ctx.stderr.write("error: usage — x402trace validate <wallet> <service-url>\n");
+        return EXIT_USAGE;
+    }
+    if (!ADDRESS_RE.test(opts.wallet)) {
+        ctx.stderr.write(`error: wallet is not a valid 0x-prefixed 20-byte address: ${opts.wallet}\n`);
+        return EXIT_USAGE;
+    }
+    const wallet = opts.wallet;
+    let serviceUrl;
+    try {
+        serviceUrl = new URL(opts.service);
+    }
+    catch {
+        ctx.stderr.write(`error: service is not a valid URL: ${opts.service}\n`);
+        return EXIT_USAGE;
+    }
+    const format = opts.log ?? "human";
+    const color = ctx.color ?? createColorizer({ stream: ctx.stdout });
+    const fetchFn = ctx.fetch ?? fetch;
+    const now = (ctx.now ?? (() => new Date()))();
+    // ─── Step 1: fetch the 402 challenge ───────────────────────────
+    let challenge;
+    try {
+        const res = await fetchFn(serviceUrl.toString(), { method: "GET" });
+        if (res.status !== 402) {
+            ctx.stderr.write(`error: expected ${color.paint("bold", "402")} from ${serviceUrl}, got ${res.status} — is this an x402-protected endpoint?\n`);
+            return EXIT_RUNTIME;
+        }
+        const bodyText = await res.text();
+        const parsed = parseChallengeBody(bodyText);
+        if (!parsed.ok) {
+            ctx.stderr.write(`error: ${parsed.message}\n`);
+            return EXIT_RUNTIME;
+        }
+        challenge = parsed.value.requirements;
+    }
+    catch (err) {
+        ctx.stderr.write(`error: failed to fetch ${serviceUrl}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return EXIT_RUNTIME;
+    }
+    // ─── Step 2: synthesise a PaymentPayload the wallet WOULD sign ─
+    // Pre-flight has no real signature; we synthesise the auth so the
+    // payment-side rules can lint the challenge shape itself. The
+    // validBefore is set to (now + maxTimeoutSeconds), matching what a
+    // well-behaved client would produce.
+    const validBeforeSec = Math.floor(now.getTime() / 1000) + (challenge.maxTimeoutSeconds ?? 300);
+    const synthesised = {
+        x402Version: 1,
+        scheme: challenge.scheme,
+        network: challenge.network,
+        payload: {
+            signature: "[SIMULATED]",
+            authorization: {
+                from: wallet,
+                to: challenge.payTo,
+                value: challenge.maxAmountRequired,
+                validAfter: "0",
+                validBefore: String(validBeforeSec),
+                nonce: SYNTHESISED_NONCE,
+            },
+        },
+    };
+    // ─── Step 3: query on-chain wallet state ───────────────────────
+    const chainFactory = ctx.chainFactory ?? createChainClient;
+    const chain = chainFactory(opts.rpcUrl ?? ctx.env.BASE_RPC_URL);
+    let walletState;
+    try {
+        const [balance, nonceConsumed, walletKind] = await Promise.all([
+            chain.getUsdcBalance(wallet),
+            chain.isNonceConsumed(wallet, SYNTHESISED_NONCE),
+            chain.detectWalletKind(wallet),
+        ]);
+        walletState = { usdcBalance: balance, nonceConsumed, walletKind };
+    }
+    catch (err) {
+        ctx.stderr.write(`${color.paint("yellow", "warn:")} chain state query failed — running offline diagnosis only (${err instanceof Error ? err.message : String(err)})\n`);
+        walletState = {};
+    }
+    finally {
+        await chain.close?.();
+    }
+    // ─── Step 4: build context, run engine, render ────────────────
+    const diagCtx = {
+        requirements: challenge,
+        payment: synthesised,
+        walletState,
+        now,
+    };
+    const report = diagnose(diagCtx);
+    if (format === "human") {
+        // One-line header so users see what was checked at a glance.
+        ctx.stdout.write(`${color.paint("bold", `validate ${wallet}`)}  →  ${color.paint("dim", serviceUrl.toString())}\n`);
+        ctx.stdout.write(`${formatReportHuman(report, color)}\n`);
+    }
+    else {
+        ctx.stdout.write(`${formatReportJson(report)}\n`);
+    }
+    // ─── Step 5: exit code ─────────────────────────────────────────
+    if (report.overallStatus === "would-fail")
+        return EXIT_RUNTIME;
+    if (report.overallStatus === "uncertain" && opts.strict)
+        return EXIT_RUNTIME;
+    return EXIT_SUCCESS;
+}

package/dist/diagnose/format.d.ts

@@ -0,0 +1,23 @@
+/**
+ * X402-21 v0.2 diagnose formatters.
+ *
+ * The diagnose engine is pure; renderers live here so the engine
+ * stays testable without ANSI strings. `format-result.ts` in the CLI
+ * layer uses the same colour-aware helpers — we mirror that style so
+ * `validate` / `explain` output looks of-a-piece with `proxy` /
+ * `inspect`.
+ */
+import type { Colorizer } from "../cli/color.js";
+import type { DiagnosticReport, OverallStatus } from "./types.js";
+/**
+ * Human-readable report. One headline + one line per rule. The
+ * "fix" line for failures is indented under the rule it belongs to.
+ */
+export declare function formatReportHuman(report: DiagnosticReport, color: Colorizer): string;
+/**
+ * Machine-readable report. One JSON object per line plus a final
+ * summary line, all newline-delimited so the output is grep- and
+ * `jq`-friendly. Matches the JSONL ergonomics of `proxy --log json`.
+ */
+export declare function formatReportJson(report: DiagnosticReport): string;
+export type { OverallStatus };

package/dist/diagnose/format.js

@@ -0,0 +1,68 @@
+/**
+ * X402-21 v0.2 diagnose formatters.
+ *
+ * The diagnose engine is pure; renderers live here so the engine
+ * stays testable without ANSI strings. `format-result.ts` in the CLI
+ * layer uses the same colour-aware helpers — we mirror that style so
+ * `validate` / `explain` output looks of-a-piece with `proxy` /
+ * `inspect`.
+ */
+const STATUS_MARKERS = {
+    pass: "✓",
+    fail: "✗",
+    skip: "·",
+};
+const STATUS_COLOURS = {
+    pass: "green",
+    fail: "red",
+    skip: "dim",
+};
+const OVERALL_HEADLINE = {
+    "would-succeed": "✓ would succeed",
+    "would-fail": "✗ would fail",
+    uncertain: "⚠ uncertain (key checks skipped)",
+};
+const OVERALL_COLOURS = {
+    "would-succeed": "green",
+    "would-fail": "red",
+    uncertain: "yellow",
+};
+/**
+ * Human-readable report. One headline + one line per rule. The
+ * "fix" line for failures is indented under the rule it belongs to.
+ */
+export function formatReportHuman(report, color) {
+    const headline = color.paint(OVERALL_COLOURS[report.overallStatus], `${OVERALL_HEADLINE[report.overallStatus]}`);
+    const lines = [color.paint("bold", `diagnose: ${headline}`), ""];
+    for (const r of report.results) {
+        lines.push(`  ${color.paint(STATUS_COLOURS[r.status], STATUS_MARKERS[r.status])} ${color.paint("bold", r.rule)}: ${r.message}`);
+        if (r.status === "fail" && r.fix) {
+            lines.push(`    ${color.paint("dim", "fix:")} ${r.fix}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Machine-readable report. One JSON object per line plus a final
+ * summary line, all newline-delimited so the output is grep- and
+ * `jq`-friendly. Matches the JSONL ergonomics of `proxy --log json`.
+ */
+export function formatReportJson(report) {
+    const lines = [];
+    for (const r of report.results) {
+        lines.push(JSON.stringify({ event: "diagnose.result", ...r }));
+    }
+    lines.push(JSON.stringify({
+        event: "diagnose.summary",
+        overallStatus: report.overallStatus,
+        counts: countByStatus(report.results),
+    }));
+    return lines.join("\n");
+}
+function countByStatus(results) {
+    return {
+        pass: results.filter((r) => r.status === "pass").length,
+        fail: results.filter((r) => r.status === "fail").length,
+        skip: results.filter((r) => r.status === "skip").length,
+    };
+}

package/dist/diagnose/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * X402-21 v0.2 diagnose module — public surface.
+ *
+ * The `diagnose()` function is the heart: pure, deterministic,
+ * dependency-free. CLI subcommands `validate` and `explain` are thin
+ * adapters that build a `DiagnosticContext` from their respective
+ * inputs (live RPC vs. captured JSONL) and render the resulting
+ * `DiagnosticReport`.
+ */
+export { diagnose, ALL_RULES } from "./rules.js";
+export { formatReportHuman, formatReportJson } from "./format.js";
+export type { DiagnosticContext, DiagnosticResult, DiagnosticReport, DiagnosticRule, DiagnosticStatus, OverallStatus, WalletState, } from "./types.js";

package/dist/diagnose/index.js

@@ -0,0 +1,11 @@
+/**
+ * X402-21 v0.2 diagnose module — public surface.
+ *
+ * The `diagnose()` function is the heart: pure, deterministic,
+ * dependency-free. CLI subcommands `validate` and `explain` are thin
+ * adapters that build a `DiagnosticContext` from their respective
+ * inputs (live RPC vs. captured JSONL) and render the resulting
+ * `DiagnosticReport`.
+ */
+export { diagnose, ALL_RULES } from "./rules.js";
+export { formatReportHuman, formatReportJson } from "./format.js";

package/dist/diagnose/rules.d.ts

@@ -0,0 +1,93 @@
+/**
+ * X402-21 v0.2 diagnose rules.
+ *
+ * Each rule answers one yes/no question about a payment context.
+ * Rules are pure — no I/O, no Date.now(), no random. They return
+ * `skip` when the context lacks the data they need (which happens
+ * routinely: `validate` populates `walletState` but synthesises a
+ * `payment`, `explain` has a captured `payment` but no live
+ * `walletState`).
+ *
+ * Adding a rule:
+ *   1. Write the function below.
+ *   2. Add it to `ALL_RULES` at the bottom.
+ *   3. Add a unit test in `tests/unit/diagnose-rules.test.ts`.
+ *
+ * A rule failing should always include a `fix` field. The fix is what
+ * the user reads first when something's broken — it has to be
+ * actionable.
+ */
+import type { DiagnosticContext, DiagnosticResult, DiagnosticRule } from "./types.js";
+/**
+ * Network mismatch is the most common config-level mistake — signing
+ * for `base` instead of `base-sepolia` (or vice versa) fails verify
+ * with a generic error that doesn't name the field. We name it loudly.
+ */
+export declare const networkMatchRule: DiagnosticRule;
+/**
+ * Scheme mismatch — v0.1/v0.2 only support `exact` EVM per ADR-001.
+ * If the requirements ask for a different scheme, that's a service-
+ * side mismatch with our tool.
+ */
+export declare const schemeMatchRule: DiagnosticRule;
+/**
+ * The recipient in the EIP-3009 authorization MUST match the service's
+ * `payTo`. If not, the payment goes to the wrong address. Case-
+ * insensitive — EIP-55 addresses can come back from different sources
+ * in different casings.
+ */
+export declare const recipientMatchRule: DiagnosticRule;
+/**
+ * The signed `value` MUST cover `maxAmountRequired`. The service is
+ * free to settle less than requested, but never more than authorized.
+ */
+export declare const valueSufficientRule: DiagnosticRule;
+/**
+ * `validBefore` must be in the future at diagnosis time. Expired
+ * authorizations are a common failure when the user signs and then
+ * the facilitator/network takes too long.
+ */
+export declare const validBeforeRule: DiagnosticRule;
+/**
+ * `validAfter` must be in the past at diagnosis time. Rare in practice
+ * (most signers set it to 0), but a client signing too far in the
+ * future would fail to settle until then.
+ */
+export declare const validAfterRule: DiagnosticRule;
+/**
+ * Live wallet balance covers the signed value. This is the big
+ * pre-flight check `validate` adds — discovered live in X402-3 when
+ * our test wallet was empty.
+ */
+export declare const payerBalanceRule: DiagnosticRule;
+/**
+ * EIP-3009 nonces are single-use per `(authorizer, contract)`. A
+ * re-used nonce will fail settlement — either because the previous
+ * settlement already consumed it, or because the user is replaying.
+ */
+export declare const nonceFreshRule: DiagnosticRule;
+/**
+ * Wallet kind affects signature verification. EOAs sign with secp256k1
+ * (verifiable by ecrecover); Smart Wallets use ERC-1271 (verifiable
+ * by calling the wallet contract); ERC-6492 wraps undeployed-Smart-
+ * Wallet signatures. v0.2 supports EOA + Smart Wallet detection;
+ * ERC-6492 is a documented v0.3 gap.
+ */
+export declare const walletKindRule: DiagnosticRule;
+/**
+ * The asset address in the authorization context must match the
+ * service's required asset (USDC on Base Sepolia, `0x036C…CF7e`).
+ * v0.1's PaymentPayload doesn't carry the asset directly — it lives
+ * in the EIP-712 domain that signers attach implicitly — so this rule
+ * cross-checks via the network: a `base-sepolia` payload implicitly
+ * targets `0x036C…CF7e`.
+ *
+ * This is a documentation rule for now; once we capture the EIP-712
+ * domain in the payment payload (v0.3) we can do a hard check.
+ */
+export declare const assetAddressRule: DiagnosticRule;
+export declare const ALL_RULES: readonly DiagnosticRule[];
+export declare function diagnose(ctx: DiagnosticContext, rules?: readonly DiagnosticRule[]): {
+    results: DiagnosticResult[];
+    overallStatus: "would-succeed" | "would-fail" | "uncertain";
+};

package/dist/diagnose/rules.js

@@ -0,0 +1,276 @@
+/**
+ * X402-21 v0.2 diagnose rules.
+ *
+ * Each rule answers one yes/no question about a payment context.
+ * Rules are pure — no I/O, no Date.now(), no random. They return
+ * `skip` when the context lacks the data they need (which happens
+ * routinely: `validate` populates `walletState` but synthesises a
+ * `payment`, `explain` has a captured `payment` but no live
+ * `walletState`).
+ *
+ * Adding a rule:
+ *   1. Write the function below.
+ *   2. Add it to `ALL_RULES` at the bottom.
+ *   3. Add a unit test in `tests/unit/diagnose-rules.test.ts`.
+ *
+ * A rule failing should always include a `fix` field. The fix is what
+ * the user reads first when something's broken — it has to be
+ * actionable.
+ */
+function pass(rule, message) {
+    return { rule, status: "pass", message };
+}
+function fail(rule, message, fix) {
+    return { rule, status: "fail", message, fix };
+}
+function skip(rule, message) {
+    return { rule, status: "skip", message };
+}
+/**
+ * Network mismatch is the most common config-level mistake — signing
+ * for `base` instead of `base-sepolia` (or vice versa) fails verify
+ * with a generic error that doesn't name the field. We name it loudly.
+ */
+export const networkMatchRule = {
+    name: "network-match",
+    run(ctx) {
+        if (!ctx.payment)
+            return skip(this.name, "no payment payload to check network against");
+        if (ctx.payment.network === ctx.requirements.network) {
+            return pass(this.name, `network matches: ${ctx.requirements.network}`);
+        }
+        return fail(this.name, `payment is for ${ctx.payment.network}, but the service requires ${ctx.requirements.network}`, `re-sign the payment with network='${ctx.requirements.network}'`);
+    },
+};
+/**
+ * Scheme mismatch — v0.1/v0.2 only support `exact` EVM per ADR-001.
+ * If the requirements ask for a different scheme, that's a service-
+ * side mismatch with our tool.
+ */
+export const schemeMatchRule = {
+    name: "scheme-match",
+    run(ctx) {
+        if (!ctx.payment)
+            return skip(this.name, "no payment payload to check scheme against");
+        if (ctx.payment.scheme === ctx.requirements.scheme) {
+            return pass(this.name, `scheme matches: ${ctx.requirements.scheme}`);
+        }
+        return fail(this.name, `payment uses scheme '${ctx.payment.scheme}', service expects '${ctx.requirements.scheme}'`, `re-sign with the correct scheme; x402trace v0.2 only supports 'exact' EVM`);
+    },
+};
+/**
+ * The recipient in the EIP-3009 authorization MUST match the service's
+ * `payTo`. If not, the payment goes to the wrong address. Case-
+ * insensitive — EIP-55 addresses can come back from different sources
+ * in different casings.
+ */
+export const recipientMatchRule = {
+    name: "recipient-match",
+    run(ctx) {
+        if (!ctx.payment)
+            return skip(this.name, "no payment payload");
+        const authTo = ctx.payment.payload.authorization.to.toLowerCase();
+        const required = ctx.requirements.payTo.toLowerCase();
+        if (authTo === required) {
+            return pass(this.name, `recipient matches: ${ctx.requirements.payTo}`);
+        }
+        return fail(this.name, `authorization.to=${ctx.payment.payload.authorization.to}, requirements.payTo=${ctx.requirements.payTo}`, `re-sign with to=${ctx.requirements.payTo}`);
+    },
+};
+/**
+ * The signed `value` MUST cover `maxAmountRequired`. The service is
+ * free to settle less than requested, but never more than authorized.
+ */
+export const valueSufficientRule = {
+    name: "value-sufficient",
+    run(ctx) {
+        if (!ctx.payment)
+            return skip(this.name, "no payment payload");
+        let signed;
+        let required;
+        try {
+            signed = BigInt(ctx.payment.payload.authorization.value);
+            required = BigInt(ctx.requirements.maxAmountRequired);
+        }
+        catch {
+            return fail(this.name, `value field is not a valid integer (authorization.value=${ctx.payment.payload.authorization.value}, requirements.maxAmountRequired=${ctx.requirements.maxAmountRequired})`, `both fields must be base-unit integers as strings (no decimals, no 0x prefix)`);
+        }
+        if (signed >= required) {
+            return pass(this.name, `signed ${signed} >= required ${required}`);
+        }
+        return fail(this.name, `signed value ${signed} is less than required ${required}`, `re-sign with value >= ${required}`);
+    },
+};
+/**
+ * `validBefore` must be in the future at diagnosis time. Expired
+ * authorizations are a common failure when the user signs and then
+ * the facilitator/network takes too long.
+ */
+export const validBeforeRule = {
+    name: "valid-before",
+    run(ctx) {
+        if (!ctx.payment)
+            return skip(this.name, "no payment payload");
+        const validBeforeSec = Number(ctx.payment.payload.authorization.validBefore);
+        if (!Number.isFinite(validBeforeSec)) {
+            return fail(this.name, `validBefore is not a valid Unix timestamp: ${ctx.payment.payload.authorization.validBefore}`, `set validBefore to a Unix timestamp in seconds`);
+        }
+        const nowSec = Math.floor(ctx.now.getTime() / 1000);
+        if (nowSec < validBeforeSec) {
+            const remaining = validBeforeSec - nowSec;
+            return pass(this.name, `validBefore=${validBeforeSec} is ${remaining}s in the future`);
+        }
+        const expiredBy = nowSec - validBeforeSec;
+        return fail(this.name, `validBefore=${validBeforeSec} expired ${expiredBy}s ago (now=${nowSec})`, `re-sign the authorization with a later validBefore (typical: now + ${ctx.requirements.maxTimeoutSeconds ?? 300}s)`);
+    },
+};
+/**
+ * `validAfter` must be in the past at diagnosis time. Rare in practice
+ * (most signers set it to 0), but a client signing too far in the
+ * future would fail to settle until then.
+ */
+export const validAfterRule = {
+    name: "valid-after",
+    run(ctx) {
+        if (!ctx.payment)
+            return skip(this.name, "no payment payload");
+        const validAfterSec = Number(ctx.payment.payload.authorization.validAfter);
+        if (!Number.isFinite(validAfterSec)) {
+            return fail(this.name, `validAfter is not a valid Unix timestamp: ${ctx.payment.payload.authorization.validAfter}`, `set validAfter to a Unix timestamp in seconds (0 is the common default)`);
+        }
+        const nowSec = Math.floor(ctx.now.getTime() / 1000);
+        if (nowSec >= validAfterSec) {
+            return pass(this.name, `validAfter=${validAfterSec} (already valid)`);
+        }
+        const waitSec = validAfterSec - nowSec;
+        return fail(this.name, `validAfter=${validAfterSec} is ${waitSec}s in the future`, `re-sign with validAfter <= ${nowSec} (use 0 unless you have a specific reason)`);
+    },
+};
+/**
+ * Live wallet balance covers the signed value. This is the big
+ * pre-flight check `validate` adds — discovered live in X402-3 when
+ * our test wallet was empty.
+ */
+export const payerBalanceRule = {
+    name: "payer-balance",
+    run(ctx) {
+        if (!ctx.payment)
+            return skip(this.name, "no payment payload");
+        if (ctx.walletState?.usdcBalance === undefined) {
+            return skip(this.name, "no on-chain wallet balance in context (run `validate` for live check)");
+        }
+        let needed;
+        try {
+            needed = BigInt(ctx.payment.payload.authorization.value);
+        }
+        catch {
+            return skip(this.name, "payment value is not a parsable bigint");
+        }
+        if (ctx.walletState.usdcBalance >= needed) {
+            return pass(this.name, `wallet has ${ctx.walletState.usdcBalance} USDC (raw), needs ${needed}`);
+        }
+        const shortfall = needed - ctx.walletState.usdcBalance;
+        return fail(this.name, `wallet has ${ctx.walletState.usdcBalance} USDC (raw), needs ${needed} — short by ${shortfall}`, `fund the wallet with at least ${shortfall} more USDC (raw units)`);
+    },
+};
+/**
+ * EIP-3009 nonces are single-use per `(authorizer, contract)`. A
+ * re-used nonce will fail settlement — either because the previous
+ * settlement already consumed it, or because the user is replaying.
+ */
+export const nonceFreshRule = {
+    name: "nonce-fresh",
+    run(ctx) {
+        if (!ctx.payment)
+            return skip(this.name, "no payment payload");
+        if (ctx.walletState?.nonceConsumed === undefined) {
+            return skip(this.name, "no on-chain nonce status in context (run `validate` for live check)");
+        }
+        if (!ctx.walletState.nonceConsumed) {
+            return pass(this.name, `nonce ${ctx.payment.payload.authorization.nonce.slice(0, 10)}… is fresh`);
+        }
+        return fail(this.name, `nonce ${ctx.payment.payload.authorization.nonce} has already been consumed on this USDC contract`, `generate a fresh nonce (32 random bytes) and re-sign`);
+    },
+};
+/**
+ * Wallet kind affects signature verification. EOAs sign with secp256k1
+ * (verifiable by ecrecover); Smart Wallets use ERC-1271 (verifiable
+ * by calling the wallet contract); ERC-6492 wraps undeployed-Smart-
+ * Wallet signatures. v0.2 supports EOA + Smart Wallet detection;
+ * ERC-6492 is a documented v0.3 gap.
+ */
+export const walletKindRule = {
+    name: "wallet-kind",
+    run(ctx) {
+        if (!ctx.walletState?.walletKind) {
+            return skip(this.name, "wallet kind not detected (run `validate` against a live wallet)");
+        }
+        if (ctx.walletState.walletKind === "eoa" || ctx.walletState.walletKind === "smart-wallet") {
+            return pass(this.name, `wallet kind: ${ctx.walletState.walletKind}`);
+        }
+        return fail(this.name, "wallet kind could not be classified", "v0.2 supports EOA + Smart Wallet only; ERC-6492 / unknown kinds are a v0.3 gap");
+    },
+};
+/**
+ * The asset address in the authorization context must match the
+ * service's required asset (USDC on Base Sepolia, `0x036C…CF7e`).
+ * v0.1's PaymentPayload doesn't carry the asset directly — it lives
+ * in the EIP-712 domain that signers attach implicitly — so this rule
+ * cross-checks via the network: a `base-sepolia` payload implicitly
+ * targets `0x036C…CF7e`.
+ *
+ * This is a documentation rule for now; once we capture the EIP-712
+ * domain in the payment payload (v0.3) we can do a hard check.
+ */
+export const assetAddressRule = {
+    name: "asset-address",
+    run(ctx) {
+        // Best-effort: warn if requirements specify an unexpected asset
+        // for base-sepolia. The standard Base Sepolia USDC is well-known.
+        const BASE_SEPOLIA_USDC = "0x036cbd53842c5426634e7929541ec2318f3dcf7e";
+        if (ctx.requirements.network !== "base-sepolia") {
+            return skip(this.name, `network ${ctx.requirements.network} not validated by this rule (v0.2 covers base-sepolia only)`);
+        }
+        if (ctx.requirements.asset.toLowerCase() === BASE_SEPOLIA_USDC) {
+            return pass(this.name, "asset is canonical Base Sepolia USDC");
+        }
+        return fail(this.name, `requirements.asset=${ctx.requirements.asset}, expected Base Sepolia USDC ${BASE_SEPOLIA_USDC}`, `the service is asking for payment in a non-canonical token; verify with the service operator`);
+    },
+};
+export const ALL_RULES = [
+    networkMatchRule,
+    schemeMatchRule,
+    recipientMatchRule,
+    valueSufficientRule,
+    validBeforeRule,
+    validAfterRule,
+    payerBalanceRule,
+    nonceFreshRule,
+    walletKindRule,
+    assetAddressRule,
+];
+/**
+ * Apply every rule in `rules` to `ctx`. Returns the per-rule results
+ * in declaration order plus an overall status:
+ *
+ *   - `would-succeed`: at least one `pass`, no `fail`s, no critical `skip`s
+ *   - `would-fail`:    at least one `fail`
+ *   - `uncertain`:     no `fail`s but critical checks were skipped (e.g.
+ *     `validate` couldn't reach the chain, so balance + nonce were
+ *     skipped — we can't claim the payment would succeed)
+ *
+ * "Critical" skips are the on-chain-state rules — `payer-balance` and
+ * `nonce-fresh`. Pure-static checks skipping just means the rule
+ * doesn't apply (e.g. no payment payload to check signature against).
+ */
+const CRITICAL_RULES = new Set(["payer-balance", "nonce-fresh"]);
+export function diagnose(ctx, rules = ALL_RULES) {
+    const results = rules.map((r) => r.run(ctx));
+    const anyFail = results.some((r) => r.status === "fail");
+    if (anyFail)
+        return { results, overallStatus: "would-fail" };
+    const criticalSkipped = results.some((r) => r.status === "skip" && CRITICAL_RULES.has(r.rule));
+    if (criticalSkipped)
+        return { results, overallStatus: "uncertain" };
+    return { results, overallStatus: "would-succeed" };
+}