x402trace 0.1.0

package/dist/chain/client.js

@@ -0,0 +1,283 @@
+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 { withRetry } from "./retry.js";
+const DEFAULT_RPC_URL = "https://sepolia.base.org";
+const DEFAULT_POLL_INTERVAL_MS = 4_000;
+function isNotFoundError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const name = err.name;
+    if (name === "TransactionReceiptNotFoundError" ||
+        name === "TransactionNotFoundError" ||
+        name === "BlockNotFoundError") {
+        return true;
+    }
+    return /not\s+(be\s+)?found/i.test(err.message);
+}
+/**
+ * Build a read-only chain client for Base Sepolia. Never holds private
+ * keys; never broadcasts transactions. Only reads logs + receipts.
+ */
+export function createChainClient(opts = {}) {
+    const transport = opts.transport ??
+        http(opts.rpcUrl ?? DEFAULT_RPC_URL, { timeout: opts.rpcTimeoutMs ?? 30_000 });
+    const client = createPublicClient({ chain: baseSepolia, transport });
+    const retries = opts.retries ?? 3;
+    const subscribers = new Set();
+    async function getBlockNumber() {
+        return withRetry(() => client.getBlockNumber(), { retries });
+    }
+    function findTransferLog(logs, expectedToken) {
+        const tokenFilter = (expectedToken ?? BASE_SEPOLIA_USDC).toLowerCase();
+        for (const log of logs) {
+            if (log.address.toLowerCase() !== tokenFilter)
+                continue;
+            try {
+                const decoded = decodeEventLog({
+                    abi: [USDC_TRANSFER_EVENT],
+                    data: log.data,
+                    topics: log.topics,
+                });
+                if (decoded.eventName === "Transfer") {
+                    const args = decoded.args;
+                    return { log, ...args };
+                }
+            }
+            catch {
+                // not a Transfer log on this contract; skip
+            }
+        }
+        return null;
+    }
+    function findAuthorizationNonce(logs, expectedToken) {
+        const tokenFilter = (expectedToken ?? BASE_SEPOLIA_USDC).toLowerCase();
+        for (const log of logs) {
+            if (log.address.toLowerCase() !== tokenFilter)
+                continue;
+            try {
+                const decoded = decodeEventLog({
+                    abi: [AUTHORIZATION_USED_EVENT],
+                    data: log.data,
+                    topics: log.topics,
+                });
+                if (decoded.eventName === "AuthorizationUsed") {
+                    return decoded.args.nonce;
+                }
+            }
+            catch {
+                // not AuthorizationUsed; skip
+            }
+        }
+        return undefined;
+    }
+    async function buildTransferFromReceipt(txHash, expectedToken) {
+        let receipt;
+        try {
+            receipt = await withRetry(() => client.getTransactionReceipt({ hash: txHash }), { retries });
+        }
+        catch (err) {
+            // viem throws TransactionReceiptNotFoundError when the receipt
+            // isn't available yet (tx pending OR doesn't exist).
+            if (isNotFoundError(err))
+                return null;
+            throw err;
+        }
+        if (receipt.status !== "success")
+            return null;
+        const found = findTransferLog(receipt.logs, expectedToken);
+        if (!found) {
+            // No Transfer log on the expected token. If there are Transfer logs
+            // for a different token, surface that as a mismatch hint.
+            for (const log of receipt.logs) {
+                try {
+                    const decoded = decodeEventLog({
+                        abi: [USDC_TRANSFER_EVENT],
+                        data: log.data,
+                        topics: log.topics,
+                    });
+                    if (decoded.eventName === "Transfer") {
+                        return { mismatch: { actualToken: log.address } };
+                    }
+                }
+                catch {
+                    // skip
+                }
+            }
+            return null;
+        }
+        const nonce = findAuthorizationNonce(receipt.logs, expectedToken);
+        const block = await withRetry(() => client.getBlock({ blockHash: receipt.blockHash }), {
+            retries,
+        });
+        return {
+            txHash,
+            blockNumber: receipt.blockNumber,
+            blockTimestamp: Number(block.timestamp),
+            from: found.from,
+            to: found.to,
+            value: found.value,
+            tokenAddress: (expectedToken ?? BASE_SEPOLIA_USDC),
+            ...(nonce ? { authorizationNonce: nonce } : {}),
+        };
+    }
+    async function getTransferByTxHash(hash) {
+        const result = await buildTransferFromReceipt(hash);
+        if (!result)
+            return null;
+        if ("mismatch" in result)
+            return null;
+        return result;
+    }
+    async function verifyTransfer(opts) {
+        const expectedToken = (opts.expectedToken ?? BASE_SEPOLIA_USDC);
+        // buildTransferFromReceipt returns null for not-found / non-success
+        // receipts; only rethrows on unrecoverable RPC errors, which we let
+        // bubble up to the caller.
+        const result = await buildTransferFromReceipt(opts.txHash, expectedToken);
+        if (result && "mismatch" in result) {
+            return {
+                kind: "wrong_token",
+                txHash: opts.txHash,
+                expectedToken,
+                actualToken: result.mismatch.actualToken,
+            };
+        }
+        if (!result) {
+            // Distinguish pending from not_found vs reverted by inspecting the tx
+            // itself.
+            let tx;
+            try {
+                tx = await withRetry(() => client.getTransaction({ hash: opts.txHash }), { retries });
+            }
+            catch (err) {
+                if (isNotFoundError(err)) {
+                    return { kind: "not_found", txHash: opts.txHash };
+                }
+                throw err;
+            }
+            if (!tx)
+                return { kind: "not_found", txHash: opts.txHash };
+            if (tx.blockNumber === null)
+                return { kind: "pending", txHash: opts.txHash };
+            // Has a block but receipt was null → must be reverted.
+            return { kind: "reverted", txHash: opts.txHash };
+        }
+        const transfer = result;
+        if (opts.expectedTo && transfer.to.toLowerCase() !== opts.expectedTo.toLowerCase()) {
+            return { kind: "wrong_recipient", transfer, expectedTo: opts.expectedTo };
+        }
+        if (opts.expectedAmount !== undefined && transfer.value !== opts.expectedAmount) {
+            return { kind: "wrong_amount", transfer, expectedAmount: opts.expectedAmount };
+        }
+        if (opts.expectedFrom && transfer.from.toLowerCase() !== opts.expectedFrom.toLowerCase()) {
+            // Treat "wrong from" as a recipient-class mismatch with a different
+            // surface; future variant could split this. v0.1: bundle into
+            // wrong_recipient with the offending address — but expectedTo is
+            // semantically about the receiver. To keep the discriminant clean,
+            // we surface from-mismatches as wrong_recipient with the expected
+            // *to* echoed, since reconciliation cares about all four fields
+            // together. The downstream engine checks transfer.from separately.
+            return { kind: "wrong_recipient", transfer, expectedTo: opts.expectedTo ?? transfer.to };
+        }
+        const head = await getBlockNumber();
+        const confirmations = head >= transfer.blockNumber ? head - transfer.blockNumber + 1n : 0n;
+        return { kind: "confirmed", transfer, confirmations };
+    }
+    function subscribeUsdcTransfers(subOpts = {}) {
+        const pollMs = subOpts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        const queue = [];
+        const resolvers = [];
+        let done = false;
+        let cursor = null;
+        let stopFn = null;
+        const pumpQueue = () => {
+            while (queue.length > 0 && resolvers.length > 0) {
+                const next = queue.shift();
+                const resolve = resolvers.shift();
+                resolve({ value: next, done: false });
+            }
+        };
+        const finish = () => {
+            done = true;
+            while (resolvers.length > 0) {
+                resolvers.shift()({ value: undefined, done: true });
+            }
+            if (stopFn) {
+                const s = stopFn;
+                stopFn = null;
+                s();
+            }
+        };
+        const poll = async () => {
+            try {
+                const head = await getBlockNumber();
+                if (cursor === null) {
+                    cursor = subOpts.fromBlock ?? head;
+                }
+                if (head <= cursor)
+                    return;
+                const fromBlock = cursor + 1n;
+                const toBlock = head;
+                const logs = await withRetry(() => client.getLogs({
+                    address: BASE_SEPOLIA_USDC,
+                    event: USDC_TRANSFER_EVENT,
+                    fromBlock,
+                    toBlock,
+                    ...(subOpts.payer ? { args: { from: subOpts.payer } } : {}),
+                }), { retries });
+                // For each Transfer, fetch the receipt to enrich with the AuthorizationUsed nonce.
+                for (const log of logs) {
+                    if (!log.transactionHash)
+                        continue;
+                    const enriched = await buildTransferFromReceipt(log.transactionHash);
+                    if (!enriched || "mismatch" in enriched)
+                        continue;
+                    queue.push(enriched);
+                }
+                cursor = head;
+                pumpQueue();
+            }
+            catch {
+                // Per ARCHITECTURE.md: "mark the watch as degraded — the proxy
+                // keeps logging regardless." We swallow + retry next tick. Future
+                // versions can surface a "subscription.degraded" event.
+            }
+        };
+        const interval = setInterval(() => void poll(), pollMs);
+        // Kick off the first poll immediately so callers don't wait pollMs.
+        void poll();
+        stopFn = () => clearInterval(interval);
+        const handle = {
+            [Symbol.asyncIterator]: () => ({
+                next() {
+                    if (queue.length > 0) {
+                        return Promise.resolve({ value: queue.shift(), done: false });
+                    }
+                    if (done)
+                        return Promise.resolve({ value: undefined, done: true });
+                    return new Promise((res) => resolvers.push(res));
+                },
+                return() {
+                    finish();
+                    return Promise.resolve({ value: undefined, done: true });
+                },
+            }),
+            unsubscribe: finish,
+        };
+        subscribers.add({ stop: finish });
+        return handle;
+    }
+    async function close() {
+        for (const s of subscribers)
+            s.stop();
+        subscribers.clear();
+    }
+    return {
+        getTransferByTxHash,
+        verifyTransfer,
+        subscribeUsdcTransfers,
+        getBlockNumber,
+        close,
+    };
+}

package/dist/chain/index.d.ts

@@ -0,0 +1,4 @@
+export { createChainClient } from "./client.js";
+export { withRetry, type RetryOptions } from "./retry.js";
+export { AUTHORIZATION_USED_EVENT, BASE_SEPOLIA_USDC, USDC_TRANSFER_EVENT } from "./abi.js";
+export { type Address, type ChainClient, type ChainClientOptions, type ChainTransfer, type VerifyTransferOptions, type VerifyTransferResult, } from "./types.js";

package/dist/chain/index.js

@@ -0,0 +1,4 @@
+export { createChainClient } from "./client.js";
+export { withRetry } from "./retry.js";
+export { AUTHORIZATION_USED_EVENT, BASE_SEPOLIA_USDC, USDC_TRANSFER_EVENT } from "./abi.js";
+export {} from "./types.js";

package/dist/chain/retry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Exponential-backoff retry for transient RPC failures.
+ *
+ * Per ARCHITECTURE.md § Chain RPC client: "RPC failures retry with
+ * exponential backoff (max 3 attempts), then mark the watch as
+ * degraded — the proxy keeps logging regardless."
+ *
+ * Retry classifier defaults to "anything that isn't an instance of
+ * Error with name === 'AbortError'" — callers can override to be
+ * stricter (e.g., only retry on 5xx / connection-reset / timeout).
+ */
+export interface RetryOptions {
+    readonly retries?: number;
+    readonly baseDelayMs?: number;
+    readonly maxDelayMs?: number;
+    readonly shouldRetry?: (err: unknown, attempt: number) => boolean;
+}
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;

package/dist/chain/retry.js

@@ -0,0 +1,37 @@
+/**
+ * Exponential-backoff retry for transient RPC failures.
+ *
+ * Per ARCHITECTURE.md § Chain RPC client: "RPC failures retry with
+ * exponential backoff (max 3 attempts), then mark the watch as
+ * degraded — the proxy keeps logging regardless."
+ *
+ * Retry classifier defaults to "anything that isn't an instance of
+ * Error with name === 'AbortError'" — callers can override to be
+ * stricter (e.g., only retry on 5xx / connection-reset / timeout).
+ */
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function withRetry(fn, opts = {}) {
+    const retries = opts.retries ?? 3;
+    const base = opts.baseDelayMs ?? 200;
+    const max = opts.maxDelayMs ?? 2_000;
+    const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+    let attempt = 0;
+    // attempt 0 = initial call; retries are extra attempts after that.
+    while (true) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (attempt >= retries || !shouldRetry(err, attempt))
+                throw err;
+            const delay = Math.min(max, base * Math.pow(2, attempt));
+            await sleep(delay);
+            attempt += 1;
+        }
+    }
+}
+function defaultShouldRetry(err) {
+    if (err instanceof Error && err.name === "AbortError")
+        return false;
+    return true;
+}

package/dist/chain/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * X402-12 chain client types.
+ *
+ * `ChainTransfer` matches the shape declared in ARCHITECTURE.md §
+ * Key interfaces. `VerifyTransferResult` is the user-facing return
+ * from `verifyTransfer({txHash, expected*})` per the X402-12 ticket —
+ * 7 discriminated variants covering all four edge cases the ticket
+ * names (tx not yet mined, tx reverted, wrong recipient/amount, tx
+ * not found) plus the success case and two finer-grained mismatch
+ * variants the reconciliation engine will want to distinguish.
+ */
+import type { Hex } from "viem";
+export type Address = `0x${string}`;
+export interface ChainTransfer {
+    readonly txHash: Hex;
+    readonly blockNumber: bigint;
+    readonly blockTimestamp: number;
+    readonly from: Address;
+    readonly to: Address;
+    readonly value: bigint;
+    readonly tokenAddress: Address;
+    /** EIP-3009 `AuthorizationUsed.nonce` from the same tx, if present. */
+    readonly authorizationNonce?: Hex;
+}
+export type VerifyTransferResult = {
+    readonly kind: "confirmed";
+    readonly transfer: ChainTransfer;
+    readonly confirmations: bigint;
+} | {
+    readonly kind: "reverted";
+    readonly txHash: Hex;
+} | {
+    readonly kind: "pending";
+    readonly txHash: Hex;
+} | {
+    readonly kind: "not_found";
+    readonly txHash: Hex;
+} | {
+    readonly kind: "wrong_recipient";
+    readonly transfer: ChainTransfer;
+    readonly expectedTo: Address;
+} | {
+    readonly kind: "wrong_amount";
+    readonly transfer: ChainTransfer;
+    readonly expectedAmount: bigint;
+} | {
+    readonly kind: "wrong_token";
+    readonly txHash: Hex;
+    readonly expectedToken: Address;
+    readonly actualToken: Address;
+};
+export interface VerifyTransferOptions {
+    readonly txHash: Hex;
+    readonly expectedFrom?: Address;
+    readonly expectedTo?: Address;
+    readonly expectedAmount?: bigint;
+    /** Defaults to Base Sepolia USDC. */
+    readonly expectedToken?: Address;
+}
+export interface ChainClientOptions {
+    /** RPC URL. Default: `https://sepolia.base.org`. */
+    readonly rpcUrl?: string;
+    /** Per-RPC-call timeout in ms. Default 30_000 (matches the X402-12 ticket). */
+    readonly rpcTimeoutMs?: number;
+    /** Retry attempts on transient RPC failures. Default 3 per ARCHITECTURE.md. */
+    readonly retries?: number;
+    /**
+     * Test escape hatch: inject a custom viem `Transport`. When set, `rpcUrl`
+     * is ignored. Used by unit tests to mock RPC responses.
+     */
+    readonly transport?: any;
+}
+export interface ChainClient {
+    /** One-shot lookup. Returns null if tx not found or reverted. */
+    getTransferByTxHash(hash: Hex): Promise<ChainTransfer | null>;
+    /** Compare a tx hash against expected fields; classify into one of 7 variants. */
+    verifyTransfer(opts: VerifyTransferOptions): Promise<VerifyTransferResult>;
+    /**
+     * Live USDC `Transfer` watcher. Polls for new blocks since `fromBlock`
+     * (default: current block at subscribe time). Each emitted `ChainTransfer`
+     * is enriched with the matching `AuthorizationUsed.nonce` if present.
+     */
+    subscribeUsdcTransfers(opts?: {
+        fromBlock?: bigint;
+        payer?: Address;
+        pollIntervalMs?: number;
+    }): AsyncIterable<ChainTransfer> & {
+        unsubscribe(): void;
+    };
+    /** Current head block number. Used to compute confirmations. */
+    getBlockNumber(): Promise<bigint>;
+    /** Tear down any watchers. */
+    close(): Promise<void>;
+}

package/dist/chain/types.js

@@ -0,0 +1,12 @@
+/**
+ * X402-12 chain client types.
+ *
+ * `ChainTransfer` matches the shape declared in ARCHITECTURE.md §
+ * Key interfaces. `VerifyTransferResult` is the user-facing return
+ * from `verifyTransfer({txHash, expected*})` per the X402-12 ticket —
+ * 7 discriminated variants covering all four edge cases the ticket
+ * names (tx not yet mined, tx reverted, wrong recipient/amount, tx
+ * not found) plus the success case and two finer-grained mismatch
+ * variants the reconciliation engine will want to distinguish.
+ */
+export {};

package/dist/cli/color.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Minimal ANSI color helpers. Honours `NO_COLOR` (https://no-color.org)
+ * and TTY detection so output is clean when piped to grep / a file /
+ * `tee`. No external dependency — we render six escape codes by hand.
+ */
+declare const CODES: {
+    readonly red: "\u001B[31m";
+    readonly green: "\u001B[32m";
+    readonly yellow: "\u001B[33m";
+    readonly cyan: "\u001B[36m";
+    readonly dim: "\u001B[2m";
+    readonly bold: "\u001B[1m";
+};
+export type ColorName = keyof typeof CODES;
+export interface Colorizer {
+    readonly enabled: boolean;
+    paint(code: ColorName, text: string): string;
+}
+export interface ColorOptions {
+    /** Force-enable / force-disable. When undefined, auto-detect from TTY + NO_COLOR. */
+    readonly enabled?: boolean;
+    /** Stream to interrogate for `isTTY`. Default: `process.stdout`. */
+    readonly stream?: {
+        readonly isTTY?: boolean;
+    };
+    /** Environment to interrogate for `NO_COLOR`. Default: `process.env`. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export declare function createColorizer(opts?: ColorOptions): Colorizer;
+export {};

package/dist/cli/color.js

@@ -0,0 +1,26 @@
+/**
+ * Minimal ANSI color helpers. Honours `NO_COLOR` (https://no-color.org)
+ * and TTY detection so output is clean when piped to grep / a file /
+ * `tee`. No external dependency — we render six escape codes by hand.
+ */
+const RESET = "\x1b[0m";
+const CODES = {
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+};
+export function createColorizer(opts = {}) {
+    const stream = opts.stream ?? process.stdout;
+    const env = opts.env ?? process.env;
+    const auto = typeof stream.isTTY === "boolean" && stream.isTTY === true && !("NO_COLOR" in env);
+    const enabled = opts.enabled ?? auto;
+    return {
+        enabled,
+        paint(code, text) {
+            return enabled ? `${CODES[code]}${text}${RESET}` : text;
+        },
+    };
+}

package/dist/cli/exit-codes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * X402-14 CLI exit codes. Per the X402-14 acceptance criteria:
+ *   0 = success
+ *   1 = usage error (bad flags, missing required args)
+ *   2 = runtime error (proxy crash, log file unreadable, etc.)
+ *
+ * Centralised so subcommands and tests reference the same constants.
+ */
+export declare const EXIT_SUCCESS: 0;
+export declare const EXIT_USAGE: 1;
+export declare const EXIT_RUNTIME: 2;
+export type ExitCode = typeof EXIT_SUCCESS | typeof EXIT_USAGE | typeof EXIT_RUNTIME;

package/dist/cli/exit-codes.js

@@ -0,0 +1,11 @@
+/**
+ * X402-14 CLI exit codes. Per the X402-14 acceptance criteria:
+ *   0 = success
+ *   1 = usage error (bad flags, missing required args)
+ *   2 = runtime error (proxy crash, log file unreadable, etc.)
+ *
+ * Centralised so subcommands and tests reference the same constants.
+ */
+export const EXIT_SUCCESS = 0;
+export const EXIT_USAGE = 1;
+export const EXIT_RUNTIME = 2;

package/dist/cli/format-result.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Renders `ReconciliationResult`s for stdout. The JSONL log is the
+ * canonical record; this is the human-facing line per [SPEC.md § 3 user
+ * flow](../../SPEC.md#3-user-flow) — the `RECONCILED ⚠
+ * settled-but-server-thinks-not` headline for the canonical #1062
+ * detection.
+ *
+ * `formatJson` is `JSON.stringify(result)` so output is grep-friendly
+ * (X402-14 acceptance criterion).
+ */
+import type { ReconciliationResult } from "../reconciliation/types.js";
+import type { Colorizer } from "./color.js";
+export declare function formatResultHuman(result: ReconciliationResult, color: Colorizer): string;
+/**
+ * JSON-stringify a `ReconciliationResult`. `bigint`s in the embedded
+ * `ChainTransfer` (blockNumber, value) and the value_mismatch
+ * expected/actual are coerced to strings — JSON has no bigint and we
+ * want lossless representation downstream.
+ */
+export declare function formatResultJson(result: ReconciliationResult): string;

package/dist/cli/format-result.js

@@ -0,0 +1,58 @@
+/**
+ * Renders `ReconciliationResult`s for stdout. The JSONL log is the
+ * canonical record; this is the human-facing line per [SPEC.md § 3 user
+ * flow](../../SPEC.md#3-user-flow) — the `RECONCILED ⚠
+ * settled-but-server-thinks-not` headline for the canonical #1062
+ * detection.
+ *
+ * `formatJson` is `JSON.stringify(result)` so output is grep-friendly
+ * (X402-14 acceptance criterion).
+ */
+export function formatResultHuman(result, color) {
+    const stamp = color.paint("dim", `[${result.t}]`);
+    const id = short(result.exchangeId);
+    switch (result.kind) {
+        case "settled_on_chain": {
+            const headline = color.paint("yellow", "RECONCILED ⚠ settled-but-server-thinks-not");
+            const tx = color.paint("cyan", short(result.onChain.txHash, 10));
+            const auth = result.pending.payment.payload.authorization;
+            return `${stamp} ${headline} id=${id} tx=${tx} value=${auth.value} payer=${shortAddr(auth.from)} → payee=${shortAddr(auth.to)} gap=${result.gapMs}ms`;
+        }
+        case "not_settled": {
+            const headline = color.paint("green", "NOT_SETTLED ✓ facilitator was right");
+            const auth = result.pending.payment.payload.authorization;
+            const reason = result.pending.errorReason ? ` reason=${result.pending.errorReason}` : "";
+            return `${stamp} ${headline} id=${id} payer=${shortAddr(auth.from)} value=${auth.value} waited=${result.waitedMs}ms${reason}`;
+        }
+        case "value_mismatch": {
+            const headline = color.paint("red", "VALUE_MISMATCH ⚠ on-chain transfer differs from authorized value");
+            return `${stamp} ${headline} id=${id} tx=${short(result.onChain.txHash, 10)} expected=${result.expected} actual=${result.actual}`;
+        }
+        case "recipient_mismatch": {
+            const headline = color.paint("red", "RECIPIENT_MISMATCH ⚠ on-chain transfer paid the wrong address");
+            return `${stamp} ${headline} id=${id} tx=${short(result.onChain.txHash, 10)} expected=${shortAddr(result.expectedPayee)} actual=${shortAddr(result.actualPayee)}`;
+        }
+    }
+}
+/**
+ * JSON-stringify a `ReconciliationResult`. `bigint`s in the embedded
+ * `ChainTransfer` (blockNumber, value) and the value_mismatch
+ * expected/actual are coerced to strings — JSON has no bigint and we
+ * want lossless representation downstream.
+ */
+export function formatResultJson(result) {
+    return JSON.stringify(result, bigintReplacer);
+}
+function bigintReplacer(_key, value) {
+    return typeof value === "bigint" ? value.toString() : value;
+}
+function short(value, head = 8) {
+    if (value.length <= head + 4)
+        return value;
+    return `${value.slice(0, head)}…`;
+}
+function shortAddr(value) {
+    if (!value.startsWith("0x") || value.length < 12)
+        return value;
+    return `${value.slice(0, 6)}…${value.slice(-4)}`;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * X402-14 CLI surface. Two subcommands:
+ *
+ *   x402trace proxy --upstream <url> [--port 8402] [--log human|json] [--reconcile] …
+ *   x402trace inspect <jsonl-log-file> [--log human|json] …
+ *
+ * `commander` does the parsing; we own the wiring + exit-code
+ * discipline. See X402-14 Jira for acceptance criteria.
+ *
+ * `runCli` is the testable entry; `src/cli.ts` is the bin shim that
+ * calls it with the real `process` handles.
+ */
+import "dotenv/config";
+import { type ExitCode } from "./exit-codes.js";
+export interface CliContext {
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /**
+     * Resolves when the process should shut down (SIGINT/SIGTERM in
+     * production, immediately for many tests). Only consulted by the
+     * long-running `proxy` subcommand.
+     */
+    readonly waitForShutdown?: () => Promise<void>;
+}
+export declare function runCli(argv: readonly string[], ctx: CliContext): Promise<ExitCode>;