@wafermapxyz/cli 0.4.10 → 0.4.11

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.11 (15 Nov 2026)
+
+**`wafermap statement`: a monthly statement you can check against the chains.**
+
+- `wafermap statement --month 2026-11 --out statement.json` downloads one month of this wallet's payments to Wafermap and to marketplace sellers (EVM and Solana sides together), from https://wafermap.xyz/api/statement. `--csv` gives the accounting version; without `--out` it prints the lines and the total.
+- `wafermap statement --verify statement.json` reads every transaction from its own chain, not from Wafermap: an EVM line passes only if the receipt holds a Transfer of exactly that amount of that token from the payer to the recipient; a Solana line only if the transaction succeeded and moved exactly that amount between those two owners. It also checks that the totals add up to the lines, and exits with code 2 on any mismatch, failed or missing transaction. Public RPCs by default; set `WAFERMAP_RPC_<NETWORK>` to use your own.
+- Works on statements downloaded anywhere: the Wallet page, a team owner's statement from /teams, or the API.
+- SDK: `fetchStatement`, `parseStatement`, `verifyStatement`, `verifyLine`.
+
 ## 0.4.10 (12 Nov 2026)
 
 **`wafermap discover` shows the price on every network a service accepts.**

package/README.md

@@ -33,6 +33,8 @@ wafermap discover weather
 wafermap pay https://x402.agentindex.world/weather city=Jakarta
 wafermap swap 0.01 ETH USDG
 wafermap history
+wafermap statement --month 2026-11 --out nov.json
+wafermap statement --verify nov.json
 ```
 
 Add `--yes` to skip the confirmation prompt (caps still apply), `--network base`, `arbitrum`, `polygon`, `arc`, `soneium` or `solana` to pay in USDC on that network (swaps run on `robinhood` or `base`). Set `WAFERMAP_PASSWORD` to avoid the password prompt in scripts.

package/dist/cli.js

@@ -1288,7 +1288,119 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "0.4.10";
+    VERSION = "0.4.11";
+  }
+});
+
+// src/statement.ts
+var statement_exports = {};
+__export(statement_exports, {
+  defaultClients: () => defaultClients,
+  fetchStatement: () => fetchStatement,
+  parseStatement: () => parseStatement,
+  verifyLine: () => verifyLine,
+  verifyStatement: () => verifyStatement
+});
+import { createPublicClient as createPublicClient2, getAddress as getAddress3, http as http2, isAddress as isAddress3, parseAbiItem as parseAbiItem2, toEventSelector as toEventSelector2 } from "viem";
+import { arbitrum as arbitrum2, arc as arc2, base as base2, polygon as polygon2, robinhood as robinhood2, soneium as soneium2 } from "viem/chains";
+async function fetchStatement(wallets, month, opts = {}) {
+  const url = `${(opts.baseUrl ?? "https://wafermap.xyz").replace(/\/$/, "")}/api/statement?wallet=${encodeURIComponent(wallets.join(","))}&month=${encodeURIComponent(month)}${opts.csv ? "&format=csv" : ""}`;
+  const r = await fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs ?? 6e4) });
+  if (!r.ok) {
+    const j = await r.json().catch(() => null);
+    throw new Error(j?.error?.message ?? `Statement request failed (${r.status}).`);
+  }
+  return opts.csv ? r.text() : await r.json();
+}
+function parseStatement(text2) {
+  let s;
+  try {
+    s = JSON.parse(text2);
+  } catch {
+    throw new Error("That file is not JSON. Download the JSON statement (not the CSV) to verify it.");
+  }
+  if (s?.kind !== "wafermap-statement" || !Array.isArray(s.lines)) throw new Error("That file is not a Wafermap statement.");
+  return s;
+}
+function defaultClients(env = process.env) {
+  const cache = /* @__PURE__ */ new Map();
+  return {
+    evm: (network) => {
+      const chain = EVM[network];
+      if (!chain) return null;
+      if (!cache.has(network)) cache.set(network, createPublicClient2({ chain, transport: http2(env[ENV_RPC[network]] || void 0, { timeout: 3e4 }) }));
+      return cache.get(network);
+    },
+    solana: (method, params) => solanaRpc(env.WAFERMAP_RPC_SOLANA || SOLANA_PUBLIC_RPC, method, params)
+  };
+}
+async function verifyLine(l, clients) {
+  try {
+    if (!/^\d+$/.test(l.amountUnits)) return "mismatch";
+    const want = BigInt(l.amountUnits);
+    if (l.network.startsWith("solana:")) {
+      const tx = await clients.solana("getTransaction", [l.tx, { encoding: "jsonParsed", maxSupportedTransactionVersion: 0, commitment: "finalized" }]);
+      if (!tx) return "not_found";
+      if (tx.meta?.err) return "failed";
+      const delta = (owner) => {
+        const sum = (xs) => (xs ?? []).filter((b) => b.owner === owner && b.mint === l.token).reduce((a, b) => a + BigInt(b.uiTokenAmount?.amount ?? "0"), 0n);
+        return sum(tx.meta?.postTokenBalances) - sum(tx.meta?.preTokenBalances);
+      };
+      return delta(l.from) === -want && delta(l.to) === want ? "ok" : "mismatch";
+    }
+    const client = clients.evm(l.network);
+    if (!client) return "unsupported";
+    if (!/^0x[0-9a-fA-F]{64}$/.test(l.tx) || !isAddress3(l.token) || !isAddress3(l.from) || !isAddress3(l.to)) return "mismatch";
+    const receipt = await client.getTransactionReceipt({ hash: l.tx }).catch((e) => /not.*found|could not be found/i.test(String(e?.message)) ? null : Promise.reject(e));
+    if (!receipt) return "not_found";
+    if (receipt.status !== "success") return "failed";
+    const hit = receipt.logs.some(
+      (g) => g.address.toLowerCase() === l.token.toLowerCase() && g.topics[0] === TRANSFER && topicAddr(g.topics[1]) === getAddress3(l.from) && topicAddr(g.topics[2]) === getAddress3(l.to) && BigInt(g.data) === want
+    );
+    return hit ? "ok" : "mismatch";
+  } catch {
+    return "error";
+  }
+}
+async function verifyStatement(s, clients = defaultClients(), onLine) {
+  const results = new Array(s.lines.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: 4 }, async () => {
+      while (next < s.lines.length) {
+        const i = next++;
+        results[i] = await verifyLine(s.lines[i], clients);
+        onLine?.(i, results[i]);
+      }
+    })
+  );
+  const usd = (pick) => Math.round(s.lines.reduce((a, l, i) => a + (pick(results[i]) ? Number(l.amountUsd) : 0), 0) * 1e6) / 1e6;
+  const count = (r) => results.filter((x) => x === r).length;
+  const linesUsd = usd(() => true);
+  return {
+    results,
+    lines: s.lines.length,
+    ok: count("ok"),
+    mismatch: count("mismatch"),
+    failed: count("failed"),
+    notFound: count("not_found"),
+    unsupported: count("unsupported"),
+    error: count("error"),
+    confirmedUsd: usd((r) => r === "ok"),
+    linesUsd,
+    // The totals block must add up to the lines it sits next to.
+    totalsMatch: s.totals?.calls === s.lines.length && Math.abs((s.totals?.usd ?? NaN) - linesUsd) < 1e-6
+  };
+}
+var EVM, ENV_RPC, TRANSFER, topicAddr;
+var init_statement = __esm({
+  "src/statement.ts"() {
+    "use strict";
+    init_solana();
+    EVM = { "eip155:4663": robinhood2, "eip155:8453": base2, "eip155:42161": arbitrum2, "eip155:137": polygon2, "eip155:5042": arc2, "eip155:1868": soneium2 };
+    ENV_RPC = { "eip155:4663": "WAFERMAP_RPC_ROBINHOOD", "eip155:8453": "WAFERMAP_RPC_BASE", "eip155:42161": "WAFERMAP_RPC_ARBITRUM", "eip155:137": "WAFERMAP_RPC_POLYGON", "eip155:5042": "WAFERMAP_RPC_ARC", "eip155:1868": "WAFERMAP_RPC_SONEIUM", solana: "WAFERMAP_RPC_SOLANA" };
+    TRANSFER = toEventSelector2(parseAbiItem2("event Transfer(address indexed from, address indexed to, uint256 value)"));
+    topicAddr = (t) => t ? getAddress3(`0x${t.slice(-40)}`) : null;
   }
 });
 
@@ -1844,6 +1956,8 @@ Wallet
   wafermap balance                      USDG / USDC and gas on every payment network
   wafermap limits [--per-payment 0.1] [--per-day 1] [--per-swap 25] [--network <net>] [--mcp-swaps on|off] [--mcp-confirm on|off]
   wafermap history [--days 7] [--verify]  payments and swaps from this machine; --verify checks on-chain
+  wafermap statement [--month 2026-11] [--csv] [--out file]  a month of payments to Wafermap and its sellers
+  wafermap statement --verify <file.json>  check every line of a statement against the chain
   wafermap export-key [--solana]        print the private key, or the Solana key for Phantom/Solflare
   wafermap keychain [on|off]            keep the password for \`wafermap mcp\` in the OS keychain, not in plain text
 
@@ -2080,6 +2194,60 @@ Total $${total.toFixed(4)} in ${pays.length} payments. From 0.3.3 every payment
       } else console.log("Add --verify to check on-chain which signed payments were executed.");
       return;
     }
+    case "statement": {
+      const { fetchStatement: fetchStatement2, parseStatement: parseStatement2, verifyStatement: verifyStatement2 } = await Promise.resolve().then(() => (init_statement(), statement_exports));
+      const { readFileSync: readFileSync2, writeFileSync: writeFileSync2 } = await import("node:fs");
+      if (a.flags.verify !== void 0) {
+        const file2 = typeof a.flags.verify === "string" ? a.flags.verify : a._[0];
+        if (!file2) die("Which file? wafermap statement --verify wafermap-statement-2026-11.json");
+        let text2;
+        try {
+          text2 = readFileSync2(file2, "utf8");
+        } catch {
+          die(`Cannot read ${file2}.`);
+        }
+        let st;
+        try {
+          st = parseStatement2(text2);
+        } catch (e) {
+          die(e.message);
+        }
+        console.error(`Checking ${st.lines.length} payments from ${st.month} on-chain\u2026`);
+        const r = await verifyStatement2(st);
+        st.lines.forEach((l, i) => {
+          if (r.results[i] !== "ok") console.log(`${r.results[i].toUpperCase().padEnd(11)} ${l.date.slice(0, 16).replace("T", " ")}  $${l.amountUsd.padEnd(8)} ${l.resource}  ${l.explorer ?? l.tx}`);
+        });
+        console.log(`
+${r.ok} of ${r.lines} payments confirmed on-chain, $${r.confirmedUsd} of $${r.linesUsd}.${r.totalsMatch ? " The totals match the lines." : " The totals block does NOT match the lines."}${st.truncated ? " This statement was cut at 10,000 lines." : ""}`);
+        if (r.ok !== r.lines)
+          console.log(`ok = the transaction moved exactly that amount from the payer to the recipient \xB7 mismatch = it did not \xB7 failed = the transaction reverted \xB7 not_found = no such transaction \xB7 error = the RPC did not answer, try again (set WAFERMAP_RPC_<NETWORK> to your own RPC) \xB7 unsupported = a network this CLI cannot read.`);
+        if (r.mismatch || r.failed || r.notFound || !r.totalsMatch) process.exitCode = 2;
+        return;
+      }
+      const evm = keystoreAddress() ?? die("No wallet yet. Run `wafermap init`, or check a downloaded file with --verify.");
+      const wallets = [evm, ...keystoreSolana() ? [keystoreSolana()] : []];
+      const month = typeof a.flags.month === "string" ? a.flags.month : (/* @__PURE__ */ new Date()).toISOString().slice(0, 7);
+      if (!/^20\d\d-(0[1-9]|1[0-2])$/.test(month)) die("--month must be YYYY-MM, for example 2026-11.");
+      const csv = a.flags.csv === true;
+      const out = await fetchStatement2(wallets, month, { baseUrl: process.env.WAFERMAP_URL, csv, timeoutMs: Number(process.env.WAFERMAP_TIMEOUT_MS) || void 0 });
+      const file = typeof a.flags.out === "string" ? a.flags.out : null;
+      if (typeof out === "string") {
+        if (file) writeFileSync2(file, out);
+        else process.stdout.write(out);
+        if (file) console.error(`Saved ${file}.`);
+        return;
+      }
+      if (file) {
+        writeFileSync2(file, JSON.stringify(out, null, 2) + "\n");
+        console.error(`Saved ${file}. Check it any time with: wafermap statement --verify ${file}`);
+      }
+      if (!file || a.flags.print !== void 0) {
+        for (const l of out.lines) console.log(`${l.date.slice(0, 16).replace("T", " ")}  $${l.amountUsd.padEnd(8)} ${l.network.padEnd(14).slice(0, 14)}  ${l.resource}  ${l.explorer ?? l.tx}`);
+        console.log(`
+${month}: ${out.totals.calls} paid calls, $${out.totals.usd}.${out.lines.length ? " Save it with --out statement.json, then check it with --verify." : ""}`);
+      }
+      return;
+    }
     case "resources": {
       const q = a._.join(" ").toLowerCase();
       const list = await listResources(process.env.WAFERMAP_URL, Number(process.env.WAFERMAP_TIMEOUT_MS) || void 0);

package/dist/index.js

@@ -1026,6 +1026,103 @@ var Wafermap = class {
     }
   }
 };
+
+// src/statement.ts
+import { createPublicClient as createPublicClient2, getAddress as getAddress3, http as http2, isAddress as isAddress3, parseAbiItem as parseAbiItem2, toEventSelector as toEventSelector2 } from "viem";
+import { arbitrum as arbitrum2, arc as arc2, base as base2, polygon as polygon2, robinhood as robinhood2, soneium as soneium2 } from "viem/chains";
+var EVM = { "eip155:4663": robinhood2, "eip155:8453": base2, "eip155:42161": arbitrum2, "eip155:137": polygon2, "eip155:5042": arc2, "eip155:1868": soneium2 };
+var ENV_RPC = { "eip155:4663": "WAFERMAP_RPC_ROBINHOOD", "eip155:8453": "WAFERMAP_RPC_BASE", "eip155:42161": "WAFERMAP_RPC_ARBITRUM", "eip155:137": "WAFERMAP_RPC_POLYGON", "eip155:5042": "WAFERMAP_RPC_ARC", "eip155:1868": "WAFERMAP_RPC_SONEIUM", solana: "WAFERMAP_RPC_SOLANA" };
+var TRANSFER = toEventSelector2(parseAbiItem2("event Transfer(address indexed from, address indexed to, uint256 value)"));
+var topicAddr = (t) => t ? getAddress3(`0x${t.slice(-40)}`) : null;
+async function fetchStatement(wallets, month, opts = {}) {
+  const url = `${(opts.baseUrl ?? "https://wafermap.xyz").replace(/\/$/, "")}/api/statement?wallet=${encodeURIComponent(wallets.join(","))}&month=${encodeURIComponent(month)}${opts.csv ? "&format=csv" : ""}`;
+  const r = await fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs ?? 6e4) });
+  if (!r.ok) {
+    const j = await r.json().catch(() => null);
+    throw new Error(j?.error?.message ?? `Statement request failed (${r.status}).`);
+  }
+  return opts.csv ? r.text() : await r.json();
+}
+function parseStatement(text) {
+  let s;
+  try {
+    s = JSON.parse(text);
+  } catch {
+    throw new Error("That file is not JSON. Download the JSON statement (not the CSV) to verify it.");
+  }
+  if (s?.kind !== "wafermap-statement" || !Array.isArray(s.lines)) throw new Error("That file is not a Wafermap statement.");
+  return s;
+}
+function defaultClients(env = process.env) {
+  const cache = /* @__PURE__ */ new Map();
+  return {
+    evm: (network) => {
+      const chain = EVM[network];
+      if (!chain) return null;
+      if (!cache.has(network)) cache.set(network, createPublicClient2({ chain, transport: http2(env[ENV_RPC[network]] || void 0, { timeout: 3e4 }) }));
+      return cache.get(network);
+    },
+    solana: (method, params) => solanaRpc(env.WAFERMAP_RPC_SOLANA || SOLANA_PUBLIC_RPC, method, params)
+  };
+}
+async function verifyLine(l, clients) {
+  try {
+    if (!/^\d+$/.test(l.amountUnits)) return "mismatch";
+    const want = BigInt(l.amountUnits);
+    if (l.network.startsWith("solana:")) {
+      const tx = await clients.solana("getTransaction", [l.tx, { encoding: "jsonParsed", maxSupportedTransactionVersion: 0, commitment: "finalized" }]);
+      if (!tx) return "not_found";
+      if (tx.meta?.err) return "failed";
+      const delta = (owner) => {
+        const sum = (xs) => (xs ?? []).filter((b) => b.owner === owner && b.mint === l.token).reduce((a, b) => a + BigInt(b.uiTokenAmount?.amount ?? "0"), 0n);
+        return sum(tx.meta?.postTokenBalances) - sum(tx.meta?.preTokenBalances);
+      };
+      return delta(l.from) === -want && delta(l.to) === want ? "ok" : "mismatch";
+    }
+    const client = clients.evm(l.network);
+    if (!client) return "unsupported";
+    if (!/^0x[0-9a-fA-F]{64}$/.test(l.tx) || !isAddress3(l.token) || !isAddress3(l.from) || !isAddress3(l.to)) return "mismatch";
+    const receipt = await client.getTransactionReceipt({ hash: l.tx }).catch((e) => /not.*found|could not be found/i.test(String(e?.message)) ? null : Promise.reject(e));
+    if (!receipt) return "not_found";
+    if (receipt.status !== "success") return "failed";
+    const hit = receipt.logs.some(
+      (g) => g.address.toLowerCase() === l.token.toLowerCase() && g.topics[0] === TRANSFER && topicAddr(g.topics[1]) === getAddress3(l.from) && topicAddr(g.topics[2]) === getAddress3(l.to) && BigInt(g.data) === want
+    );
+    return hit ? "ok" : "mismatch";
+  } catch {
+    return "error";
+  }
+}
+async function verifyStatement(s, clients = defaultClients(), onLine) {
+  const results = new Array(s.lines.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: 4 }, async () => {
+      while (next < s.lines.length) {
+        const i = next++;
+        results[i] = await verifyLine(s.lines[i], clients);
+        onLine?.(i, results[i]);
+      }
+    })
+  );
+  const usd = (pick) => Math.round(s.lines.reduce((a, l, i) => a + (pick(results[i]) ? Number(l.amountUsd) : 0), 0) * 1e6) / 1e6;
+  const count = (r) => results.filter((x) => x === r).length;
+  const linesUsd = usd(() => true);
+  return {
+    results,
+    lines: s.lines.length,
+    ok: count("ok"),
+    mismatch: count("mismatch"),
+    failed: count("failed"),
+    notFound: count("not_found"),
+    unsupported: count("unsupported"),
+    error: count("error"),
+    confirmedUsd: usd((r) => r === "ok"),
+    linesUsd,
+    // The totals block must add up to the lines it sits next to.
+    totalsMatch: s.totals?.calls === s.lines.length && Math.abs((s.totals?.usd ?? NaN) - linesUsd) < 1e-6
+  };
+}
 export {
   DEFAULT_LIMITS,
   DEFAULT_TIMEOUT_MS,
@@ -1048,15 +1145,19 @@ export {
   decodeSwap,
   encodePass,
   executeSwap,
+  fetchStatement,
   holderInfo,
   listResources,
   makePass,
   mergeLog,
+  parseStatement,
   passMessage,
   quoteSwap,
   readQuote,
   signPayment,
   signTokenPayment,
+  verifyLine,
+  verifyStatement,
   wafermapPriceUsd,
   x402fetch
 };

package/dist/types/src/index.d.ts

@@ -6,3 +6,5 @@ export { quoteSwap, executeSwap, decodeSwap, KYBER_ROUTER, SwapError } from "../
 export type { Requirement, Quote, Signed, SignedAuth, SignedSol, Signer } from "../shared/x402client";
 export { checkSolanaPayment, SOLANA_PUBLIC_RPC } from "../shared/solana";
 export type { SolanaCheck } from "../shared/solana";
+export { fetchStatement, parseStatement, verifyStatement, verifyLine } from "./statement.js";
+export type { Statement, StatementLine, LineCheck } from "./statement.js";

package/dist/types/src/statement.d.ts

@@ -0,0 +1,58 @@
+import { type PublicClient } from "viem";
+export type StatementLine = {
+    date: string;
+    resource: string;
+    network: string;
+    asset: string;
+    amountUsd: string;
+    token: string;
+    amountUnits: string;
+    from: string;
+    to: string;
+    tx: string;
+    explorer?: string | null;
+};
+export type Statement = {
+    kind: "wafermap-statement";
+    version: number;
+    month: string;
+    wallets: string[];
+    totals: {
+        calls: number;
+        usd: number;
+    };
+    lines: StatementLine[];
+    truncated?: boolean;
+};
+export type LineCheck = "ok" | "mismatch" | "failed" | "not_found" | "unsupported" | "error";
+/** Downloads a statement. `csv` returns the CSV text, otherwise the parsed JSON. */
+export declare function fetchStatement(wallets: string[], month: string, opts?: {
+    baseUrl?: string;
+    csv?: boolean;
+    timeoutMs?: number;
+}): Promise<Statement | string>;
+/** Reads and sanity-checks a statement file's content. Throws on anything that is not a statement. */
+export declare function parseStatement(text: string): Statement;
+type Clients = {
+    evm: (network: string) => Pick<PublicClient, "getTransactionReceipt"> | null;
+    solana: (method: string, params: unknown[]) => Promise<any>;
+};
+/** Clients from env RPCs (WAFERMAP_RPC_<NET>) or the chains' public RPCs. */
+export declare function defaultClients(env?: Record<string, string | undefined>): Clients;
+/** Checks one line against its chain. */
+export declare function verifyLine(l: StatementLine, clients: Clients): Promise<LineCheck>;
+/** Checks every line, four at a time (public RPCs refuse bursts), and adds up what the chain confirms. */
+export declare function verifyStatement(s: Statement, clients?: Clients, onLine?: (i: number, r: LineCheck) => void): Promise<{
+    results: LineCheck[];
+    lines: number;
+    ok: number;
+    mismatch: number;
+    failed: number;
+    notFound: number;
+    unsupported: number;
+    error: number;
+    confirmedUsd: number;
+    linesUsd: number;
+    totalsMatch: boolean;
+}>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wafermapxyz/cli",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "description": "Wafermap for agents: an encrypted local wallet that pays x402 resources, discovers and pays third-party x402 services (USDG on Robinhood Chain; USDC on Solana, Base, Arbitrum, Polygon, Arc, Soneium), and swaps on Robinhood Chain and Base. CLI, SDK and MCP server.",
   "type": "module",
   "bin": {