x402trace 0.1.0

package/dist/proxy/types.js

@@ -0,0 +1,32 @@
+/**
+ * X402-10 proxy core types.
+ *
+ * The proxy is deliberately dumb: it captures raw HTTP and emits typed
+ * events. No x402 protocol parsing happens here — that's the decoder's
+ * job (X402-11). These shapes are the JSONL-on-disk format per
+ * ARCHITECTURE.md § JSONL record format; downstream readers depend on
+ * them being stable.
+ */
+/**
+ * Heuristic: is this request/response pair x402-related at all?
+ *
+ * v0.1 detection rule (pure HTTP signals, no x402 parsing):
+ * - Request has an `X-PAYMENT` or `PAYMENT-SIGNATURE` header, OR
+ * - Response has a `402` status, OR
+ * - Response has an `X-PAYMENT-RESPONSE` or `PAYMENT-RESPONSE` header.
+ *
+ * The proxy logs every request/response regardless; this heuristic is
+ * used downstream by the decoder/reconciler to skip non-x402 traffic
+ * cheaply.
+ */
+export function isLikelyX402Exchange(req, res) {
+    if (req.headers["x-payment"] || req.headers["payment-signature"])
+        return true;
+    if (!res)
+        return false;
+    if (res.status === 402)
+        return true;
+    if (res.headers["x-payment-response"] || res.headers["payment-response"])
+        return true;
+    return false;
+}

package/dist/reconciliation/engine.d.ts

@@ -0,0 +1,40 @@
+/**
+ * X402-13 reconciliation engine.
+ *
+ * Joins proxy + decoder + chain streams into a single ReconciliationResult
+ * stream. Maintains an in-memory pending set keyed by exchange id;
+ * sweeps it periodically to emit `not_settled` for entries that don't
+ * find their on-chain match within `watchTimeoutMs`.
+ *
+ * Per ARCHITECTURE.md § Reconciliation engine:
+ *
+ *   "Holds an in-memory pending set of `PaymentExchange`s whose
+ *    `outcome.kind` is `rejected` or `upstream_timeout`. … On a match:
+ *    emits a `ReconciliationResult` … and removes from pending. On no
+ *    match after `--watch-timeout-ms` (default 60000): emits
+ *    `kind: 'not_settled'` and removes from pending."
+ */
+import type { ChainTransfer } from "../chain/types.js";
+import type { DecodedEvent } from "../decoder/types.js";
+import type { ProxyEvent } from "../proxy/types.js";
+import type { EngineOptions, PendingExchange, ReconciliationResult } from "./types.js";
+export interface ReconciliationEngine {
+    ingestProxyEvent(event: ProxyEvent): void;
+    ingestDecoderEvent(event: DecodedEvent): void;
+    ingestChainTransfer(transfer: ChainTransfer): void;
+    /** Snapshot of currently-pending exchanges (for diagnostics / tests). */
+    pending(): readonly PendingExchange[];
+    /** AsyncIterable of every result emitted from now onward. */
+    results(): AsyncIterable<ReconciliationResult> & {
+        unsubscribe(): void;
+    };
+    /**
+     * Run the expiry sweep once. Useful for offline replay (X402-14
+     * `inspect`) where a virtual clock advances faster than the
+     * `sweepIntervalMs` real-time interval can catch.
+     */
+    tick(): void;
+    /** Stop sweeping; resolve any subscriber awaits. */
+    close(): Promise<void>;
+}
+export declare function createReconciliationEngine(opts?: EngineOptions): ReconciliationEngine;

package/dist/reconciliation/engine.js

@@ -0,0 +1,178 @@
+/**
+ * X402-13 reconciliation engine.
+ *
+ * Joins proxy + decoder + chain streams into a single ReconciliationResult
+ * stream. Maintains an in-memory pending set keyed by exchange id;
+ * sweeps it periodically to emit `not_settled` for entries that don't
+ * find their on-chain match within `watchTimeoutMs`.
+ *
+ * Per ARCHITECTURE.md § Reconciliation engine:
+ *
+ *   "Holds an in-memory pending set of `PaymentExchange`s whose
+ *    `outcome.kind` is `rejected` or `upstream_timeout`. … On a match:
+ *    emits a `ReconciliationResult` … and removes from pending. On no
+ *    match after `--watch-timeout-ms` (default 60000): emits
+ *    `kind: 'not_settled'` and removes from pending."
+ */
+import { createEventBus } from "../proxy/event-bus.js";
+import { matchPendingAgainstTransfer } from "./match.js";
+const DEFAULT_WATCH_TIMEOUT_MS = 60_000;
+const DEFAULT_SWEEP_INTERVAL_MS = 1_000;
+export function createReconciliationEngine(opts = {}) {
+    const watchTimeoutMs = opts.watchTimeoutMs ?? DEFAULT_WATCH_TIMEOUT_MS;
+    const sweepIntervalMs = opts.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+    const now = opts.now ?? (() => Date.now());
+    const partial = new Map();
+    const pending = new Map();
+    const resultBus = createEventBus();
+    const promote = (id) => {
+        const half = partial.get(id);
+        if (!half || !half.payment || !half.outcome)
+            return;
+        // Only flag reconcile-worthy outcomes; success/paid is fine.
+        if (half.outcome.kind === "paid") {
+            partial.delete(id);
+            return;
+        }
+        pending.set(id, {
+            id,
+            addedAt: now(),
+            payment: half.payment,
+            outcomeKind: half.outcome.kind,
+            ...(half.outcome.errorReason ? { errorReason: half.outcome.errorReason } : {}),
+        });
+        partial.delete(id);
+    };
+    const ingestProxyEvent = (event) => {
+        if (event.event === "exchange.closed") {
+            const half = partial.get(event.id) ?? {};
+            let kind;
+            switch (event.outcome.kind) {
+                case "paid":
+                    kind = { kind: "paid" };
+                    break;
+                case "rejected":
+                    kind = {
+                        kind: "rejected",
+                        ...(event.outcome.rawBody
+                            ? { errorReason: extractErrorReason(event.outcome.rawBody) }
+                            : {}),
+                    };
+                    break;
+                case "upstream_timeout":
+                    kind = { kind: "upstream_timeout" };
+                    break;
+                case "unknown":
+                default:
+                    kind = { kind: "unknown" };
+            }
+            half.outcome = kind;
+            partial.set(event.id, half);
+            promote(event.id);
+        }
+        // `exchange.opened` and `proxy.error` are observed but don't gate
+        // reconciliation — the payment + closed events are the join points.
+    };
+    const ingestDecoderEvent = (event) => {
+        if (event.event === "exchange.payment") {
+            const half = partial.get(event.id) ?? {};
+            half.payment = event.payment;
+            partial.set(event.id, half);
+            promote(event.id);
+        }
+        // `exchange.challenge` and `exchange.settlement` are not required
+        // for matching. They could be persisted in the future to enrich
+        // ReconciliationResult.pending.
+    };
+    const ingestChainTransfer = (transfer) => {
+        if (!transfer.authorizationNonce) {
+            // Without a nonce we can't safely match; ignore.
+            return;
+        }
+        for (const [id, p] of pending) {
+            const result = matchPendingAgainstTransfer(p, transfer);
+            if (result.kind === "no_match")
+                continue;
+            const t = new Date(now()).toISOString();
+            const gapMs = now() - p.addedAt;
+            if (result.kind === "exact") {
+                resultBus.emit({
+                    kind: "settled_on_chain",
+                    t,
+                    exchangeId: id,
+                    pending: p,
+                    onChain: transfer,
+                    gapMs,
+                });
+            }
+            else if (result.kind === "value_mismatch") {
+                resultBus.emit({
+                    kind: "value_mismatch",
+                    t,
+                    exchangeId: id,
+                    pending: p,
+                    onChain: transfer,
+                    expected: result.expected,
+                    actual: result.actual,
+                });
+            }
+            else if (result.kind === "recipient_mismatch") {
+                resultBus.emit({
+                    kind: "recipient_mismatch",
+                    t,
+                    exchangeId: id,
+                    pending: p,
+                    onChain: transfer,
+                    expectedPayee: p.payment.payload.authorization.to,
+                    actualPayee: transfer.to,
+                });
+            }
+            pending.delete(id);
+            return; // one match per chain transfer
+        }
+    };
+    const sweep = () => {
+        const cutoff = now() - watchTimeoutMs;
+        for (const [id, p] of pending) {
+            if (p.addedAt <= cutoff) {
+                resultBus.emit({
+                    kind: "not_settled",
+                    t: new Date(now()).toISOString(),
+                    exchangeId: id,
+                    pending: p,
+                    waitedMs: now() - p.addedAt,
+                });
+                pending.delete(id);
+            }
+        }
+    };
+    const interval = setInterval(sweep, sweepIntervalMs);
+    // Don't let the timer keep the Node event loop alive on its own.
+    interval.unref?.();
+    return {
+        ingestProxyEvent,
+        ingestDecoderEvent,
+        ingestChainTransfer,
+        pending: () => Array.from(pending.values()),
+        results: () => resultBus.subscribe(),
+        tick: sweep,
+        async close() {
+            clearInterval(interval);
+        },
+    };
+}
+/**
+ * Extract a top-level `error` string from a 402 response body if it
+ * looks like x402-shaped JSON. Returns the string or undefined.
+ */
+function extractErrorReason(rawBody) {
+    try {
+        const parsed = JSON.parse(rawBody);
+        if (typeof parsed?.error === "string")
+            return parsed.error;
+    }
+    catch {
+        // not JSON; skip
+    }
+    return undefined;
+}

package/dist/reconciliation/index.d.ts

@@ -0,0 +1,3 @@
+export { createReconciliationEngine, type ReconciliationEngine } from "./engine.js";
+export { matchPendingAgainstTransfer, type MatchResult } from "./match.js";
+export { type EngineOptions, type PendingExchange, type ReconciliationResult } from "./types.js";

package/dist/reconciliation/index.js

@@ -0,0 +1,3 @@
+export { createReconciliationEngine } from "./engine.js";
+export { matchPendingAgainstTransfer } from "./match.js";
+export {} from "./types.js";

package/dist/reconciliation/match.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure match function: does this on-chain ChainTransfer correspond to
+ * this pending PaymentExchange?
+ *
+ * Match key per ADR-001 + ARCHITECTURE.md § Reconciliation engine:
+ *
+ *   (payer, payee, value, nonce)  exact equality
+ *
+ * The EIP-3009 `nonce` is unique per (authorizer, contract) so a
+ * (payer, payee, value, nonce) tuple is collision-safe — no fuzziness
+ * needed. Addresses compared case-insensitively; bigints compared
+ * structurally.
+ *
+ * Returns a small discriminated union so the engine can decide
+ * whether to fire `settled_on_chain` / `value_mismatch` /
+ * `recipient_mismatch` / no-op.
+ */
+import type { ChainTransfer } from "../chain/types.js";
+import type { PendingExchange } from "./types.js";
+export type MatchResult = {
+    readonly kind: "no_match";
+} | {
+    readonly kind: "exact";
+} | {
+    readonly kind: "value_mismatch";
+    readonly expected: bigint;
+    readonly actual: bigint;
+} | {
+    readonly kind: "recipient_mismatch";
+};
+export declare function matchPendingAgainstTransfer(pending: PendingExchange, transfer: ChainTransfer): MatchResult;

package/dist/reconciliation/match.js

@@ -0,0 +1,39 @@
+/**
+ * Pure match function: does this on-chain ChainTransfer correspond to
+ * this pending PaymentExchange?
+ *
+ * Match key per ADR-001 + ARCHITECTURE.md § Reconciliation engine:
+ *
+ *   (payer, payee, value, nonce)  exact equality
+ *
+ * The EIP-3009 `nonce` is unique per (authorizer, contract) so a
+ * (payer, payee, value, nonce) tuple is collision-safe — no fuzziness
+ * needed. Addresses compared case-insensitively; bigints compared
+ * structurally.
+ *
+ * Returns a small discriminated union so the engine can decide
+ * whether to fire `settled_on_chain` / `value_mismatch` /
+ * `recipient_mismatch` / no-op.
+ */
+export function matchPendingAgainstTransfer(pending, transfer) {
+    const auth = pending.payment.payload.authorization;
+    const sameNonce = typeof transfer.authorizationNonce === "string" &&
+        transfer.authorizationNonce.toLowerCase() === auth.nonce.toLowerCase();
+    const samePayer = auth.from.toLowerCase() === transfer.from.toLowerCase();
+    // Nonce alone is collision-safe per (payer, contract). If both differ,
+    // it's definitely not us. If only nonce matches but payer differs,
+    // the chain client filtered to the wrong wallet or the chain emitted
+    // a malformed event — either way, not our exchange.
+    if (!sameNonce || !samePayer)
+        return { kind: "no_match" };
+    const expectedTo = auth.to.toLowerCase();
+    const actualTo = transfer.to.toLowerCase();
+    if (expectedTo !== actualTo) {
+        return { kind: "recipient_mismatch" };
+    }
+    const expectedValue = BigInt(auth.value);
+    if (expectedValue !== transfer.value) {
+        return { kind: "value_mismatch", expected: expectedValue, actual: transfer.value };
+    }
+    return { kind: "exact" };
+}

package/dist/reconciliation/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * X402-13 reconciliation engine types.
+ *
+ * The engine joins three input streams:
+ *   1. Proxy `exchange.closed` events  — tells us a request finished
+ *      with a `rejected` / `upstream_timeout` / `paid` outcome.
+ *   2. Decoder `exchange.payment` events — gives us the EIP-3009
+ *      `PaymentAuthorization` (with nonce) for that same exchange id.
+ *   3. Chain client `ChainTransfer`s — actual on-chain USDC transfers
+ *      with the matching `AuthorizationUsed.nonce`.
+ *
+ * For every exchange whose facilitator outcome was failed-but-the-
+ * underlying-tx-might-have-settled, the engine emits a
+ * `ReconciliationResult`. The headline case (`settled_on_chain`) is
+ * the canonical #1062 detection: facilitator says no, chain says yes.
+ */
+import type { Address, ChainTransfer } from "../chain/types.js";
+import type { PaymentPayload } from "../decoder/types.js";
+/** A two-half-joined exchange currently awaiting on-chain confirmation. */
+export interface PendingExchange {
+    readonly id: string;
+    /** Unix-ms timestamp when this exchange was flagged as pending. */
+    readonly addedAt: number;
+    /** Decoded payment payload from the X-PAYMENT header. */
+    readonly payment: PaymentPayload;
+    /** Why the proxy classified the response as a candidate for reconciliation. */
+    readonly outcomeKind: "rejected" | "upstream_timeout" | "unknown";
+    /** errorReason from the 402 body, if the proxy captured one. */
+    readonly errorReason?: string;
+}
+/**
+ * Output of the engine. One emitted per pending exchange that either
+ * (a) finds its on-chain match, or (b) gives up after `watchTimeoutMs`.
+ */
+export type ReconciliationResult = {
+    readonly kind: "settled_on_chain";
+    readonly t: string;
+    readonly exchangeId: string;
+    readonly pending: PendingExchange;
+    readonly onChain: ChainTransfer;
+    readonly gapMs: number;
+} | {
+    readonly kind: "not_settled";
+    readonly t: string;
+    readonly exchangeId: string;
+    readonly pending: PendingExchange;
+    readonly waitedMs: number;
+} | {
+    readonly kind: "value_mismatch";
+    readonly t: string;
+    readonly exchangeId: string;
+    readonly pending: PendingExchange;
+    readonly onChain: ChainTransfer;
+    readonly expected: bigint;
+    readonly actual: bigint;
+} | {
+    readonly kind: "recipient_mismatch";
+    readonly t: string;
+    readonly exchangeId: string;
+    readonly pending: PendingExchange;
+    readonly onChain: ChainTransfer;
+    readonly expectedPayee: Address;
+    readonly actualPayee: Address;
+};
+export interface EngineOptions {
+    /** How long to wait for an on-chain match before emitting `not_settled`. Default 60_000 ms (per ARCHITECTURE.md). */
+    readonly watchTimeoutMs?: number;
+    /** Sweep interval for expiring pending entries. Default 1_000 ms. */
+    readonly sweepIntervalMs?: number;
+    /** Injectable clock for tests. Default Date.now. */
+    readonly now?: () => number;
+}

package/dist/reconciliation/types.js

@@ -0,0 +1,17 @@
+/**
+ * X402-13 reconciliation engine types.
+ *
+ * The engine joins three input streams:
+ *   1. Proxy `exchange.closed` events  — tells us a request finished
+ *      with a `rejected` / `upstream_timeout` / `paid` outcome.
+ *   2. Decoder `exchange.payment` events — gives us the EIP-3009
+ *      `PaymentAuthorization` (with nonce) for that same exchange id.
+ *   3. Chain client `ChainTransfer`s — actual on-chain USDC transfers
+ *      with the matching `AuthorizationUsed.nonce`.
+ *
+ * For every exchange whose facilitator outcome was failed-but-the-
+ * underlying-tx-might-have-settled, the engine emits a
+ * `ReconciliationResult`. The headline case (`settled_on_chain`) is
+ * the canonical #1062 detection: facilitator says no, chain says yes.
+ */
+export {};

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "x402trace",
+  "version": "0.1.0",
+  "description": "Local CLI for debugging x402 payment flows on Base — catches timeout reconciliation failures",
+  "type": "module",
+  "bin": {
+    "x402trace": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "x402",
+    "base",
+    "usdc",
+    "payments",
+    "cli",
+    "debugging",
+    "observability",
+    "web3",
+    "ethereum"
+  ],
+  "author": "fardin vahdat",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fardinvahdat/x402trace.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fardinvahdat/x402trace/issues"
+  },
+  "homepage": "https://github.com/fardinvahdat/x402trace#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "dotenv": "^17.4.2",
+    "hono": "^4.12.18",
+    "viem": "^2.48.11",
+    "x402": "^1.2.0",
+    "x402-fetch": "^1.2.0",
+    "x402-hono": "^1.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli.ts",
+    "dogfood:server": "tsx scripts/dev-server.ts",
+    "dogfood:client": "tsx scripts/dogfood-client.ts",
+    "dogfood:mock-facilitator": "tsx scripts/mock-facilitator.ts",
+    "dogfood:failure-modes": "tsx scripts/failure-modes.ts",
+    "proxy": "tsx scripts/proxy.ts",
+    "x402trace": "tsx src/cli.ts",
+    "decoder:demo": "tsx scripts/decoder-demo.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e",
+    "test:smoke": "vitest run tests/smoke",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . && prettier --check \"{src,scripts,tests,api}/**/*.ts\" \"*.json\" \"*.js\"",
+    "lint:fix": "eslint . --fix && prettier --write \"{src,scripts,tests,api}/**/*.ts\" \"*.json\" \"*.js\"",
+    "lint:docs": "echo 'TODO: wire up markdown lint in X402-2'",
+    "lint:links": "echo 'TODO: wire up link checker in X402-2'"
+  }
+}