chainfess 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `chainfess demo`: bundled fixture, recorded RPC replies, no wallet, no network.
+- `chainfess audit`: Claude Code session logs (`.jsonl`), subagent transcripts, saved tool outputs and Foundry `broadcast/` files, compared with the wallet's nonce and blocks on Robinhood Chain.
+- Four outcomes, deterministic, no LLM: Accounted, Partial, Unaccounted, Foreign signer.
+- `chainfess sign` and `chainfess verify` for signed reports.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chainfess
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# chainfess
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your agent says X. The chain says Y. Chainfess lists every transaction the log does not account for.
+
+Try it in 10 seconds, no wallet, no network:
+
+```
+npx chainfess demo
+```
+
+Audit a past session:
+
+```
+npx chainfess audit --wallet 0x…
+```
+
+Default log = latest Claude Code session for the current directory.
+
+## What it does
+
+The wallet's nonce says how many transactions it has ever sent. The report shows how many of them this log explains.
+
+Four outcomes, deterministic, no LLM: Accounted · Partial · **Unaccounted** · **Foreign signer**.
+
+| Status | Rule | Label |
+|---|---|---|
+| Accounted | A tx of your wallet, in the session's blocks, whose full hash is in the log, a subagent transcript, a saved tool output or a broadcast file | accounted (source and line) |
+| Partial | Same, but the log only has a shortened form with the same prefix and suffix | partial match only |
+| **Unaccounted** | A tx of your wallet, in the session's blocks, with no full or partial match | **not in this log** |
+| **Foreign signer** | A tx from a wallet you did not pass, whose hash first came out of a recognised sending command, mined during that call | **signed by a wallet not registered here** |
+
+Not findings, shown for information: sent before the session, sent after it, pending, another wallet's tx mined during a tool call (cannot tell a read from a send), another wallet's tx referenced (read). Hex strings that are not transactions on this chain are one count in the footer.
+
+Unaccounted means "not in this log". A human, a cron job or another session on the same wallet produces the same line. Chainfess does not say who sent it.
+
+Exit codes: 0 no findings, 1 findings, 2 input error, 3 RPC unavailable, 4 partial scan (unscanned ranges remain).
+
+## Privacy
+
+`audit` and `demo` run on your machine. The log never leaves it; `audit`'s only network calls are JSON-RPC reads with block numbers, values the log labels as tx hashes, and your wallet address. Only the optional `sign` contacts our server: it sends the wallets, block range, hashes and a hash of the log, never the log.
+
+A private key has the same shape as a tx hash, so a 32-byte hex value goes to the RPC only when its context says it is a tx hash: the value of a `transactionHash`, `txHash` or `hash` field or label, the bare output of a plain `cast send` or `forge` call, an explorer `/tx/` URL, or the argument of `cast tx`, `cast receipt`, `cast run` or `eth_getTransactionByHash`. A value with `key`, `secret`, `mnemonic`, `seed`, `password`, `token` or `private` on its line or in its JSON object, in a shell assignment, or that is the private key of a wallet you passed, never leaves your machine. Neither does anything else. Those local values are still matched against the wallet's txs found by the block scan, so your own tx stays Accounted; the scan may just be longer. The footer counts both: "looked up, not a tx" and "not looked up, stays local".
+
+Reports show hashes, addresses, values, the command pattern name, the source kind and a line reference. Never command text, never secrets.
+
+## Verify
+
+Verify the rules yourself: `cast tx <hash>` and `cast nonce <wallet>` reproduce every number. The report footer prints both lines.
+
+## Scope
+
+Works with Claude Code session logs (`.jsonl`), including subagent transcripts and Foundry `broadcast/` files. EOA wallets only. Robinhood Chain by default; any EVM RPC with `--rpc` (then limits apply, unmeasured).
+
+## Limits
+
+Not audited. Nothing is prevented. An agent with shell access can edit its own local log; chain facts stay true, log-based lines then mislead.
+
+A script that signs with another wallet without a recognised key flag or command pattern shows only as "other wallet's tx mined during this tool call", not as a finding. Another wallet's hash printed with no hash label stays local, so it is not listed at all. So does a sending command that also printed a tx of your own wallet, or txs of more than two other wallets, because that output is a dump, not a send.
+
+No balance deltas: the free RPC refuses historical balances. A planned scan over 210,000 blocks (about 6 h of chain, about 58 minutes to scan at 60 blocks/s, measured on 5 Nov 2026 over 30,000 blocks on the public RPC) is refused unless you pass `--max-hours` or a block range. The plan is the worst case: a scan stops a gap once its nonces are found, and a hash with no label can make the plan larger. Over 512 MB, a saved tool output is not read; the footer says so, because "not in this log" lines may then be explained by that output.
+
+## Signed report
+
+burn 0.01% of supply in $CFESS (exact amount set from the contract at launch) from the audited wallet, run `npx chainfess sign --burn-tx 0x…`, get an ed25519-signed statement of chain facts that our server re-checked itself. The server never sees your log, so which hashes you listed is your claim, not ours. `npx chainfess verify <statement.json>` checks it offline.
+
+$CFESS launches 6 Nov 2026 (UTC date). No CA exists yet; any $CFESS you see before it is posted on chainfess.pro and on @chainfesspro is not ours. The signed-report service switches on with the CA. The free CLI never needs the coin.
+
+## Options
+
+```
+chainfess audit --wallet 0x… [--log f]… [--all-sessions] [--rpc url] [--chain-id n]
+  [--from ISO] [--to ISO] [--from-block n] [--to-block n] [--max-hours h]
+  [--yes] [--json] [--no-subagents] [--quiet] [--debug]
+```
+
+`--no-subagents` skips subagent transcripts only; the main session's saved tool outputs are still read.
+
+MIT.

package/bin/chainfess.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs';
+
+main(process.argv.slice(2)).then(
+  (code) => { process.exitCode = code; },
+  (e) => { process.stderr.write(`unexpected error: ${e && e.message ? e.message : 'unknown'}\n`); process.exitCode = 3; },
+);

package/fixtures/demo/rpc.json

@@ -0,0 +1,50 @@
+{
+ "chainId": 4663,
+ "latest": 100000000,
+ "latestTs": 1793793600,
+ "blockTime": 0.104,
+ "demoWallets": [
+  "0xdea1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1de"
+ ],
+ "demoNow": "2026-11-04T12:00:00Z",
+ "nonces": {
+  "0xdea1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1de": 9
+ },
+ "code": {
+  "0x77777777777777777777777777777777777777c0": "0x60806040"
+ },
+ "txs": [
+  {
+   "hash": "0x7485fc9a91208a06a1442ca82f0a4c7b6e0101cb2ae7c0b683331197aacc8ae5",
+   "from": "0xdea1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1de",
+   "to": "0x77777777777777777777777777777777777777c0",
+   "nonce": 7,
+   "block": 99920404,
+   "value": "0x2386f26fc10000"
+  },
+  {
+   "hash": "0x92b9e5a06df6044d67d658b7c163a105c31041bd43a113e9c3a3826e647ec6d8",
+   "from": "0xdea1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1de",
+   "to": "0x5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5eed",
+   "nonce": 8,
+   "block": 99925962,
+   "value": "0x3782dace9d90000"
+  },
+  {
+   "hash": "0xa51161f809ec4dc3cc2e9abb17549184e4cf02ba5b5a35ea75e035df2ee0dc7c",
+   "from": "0x5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5eed",
+   "to": "0x77777777777777777777777777777777777777c0",
+   "nonce": 41,
+   "block": 99924443,
+   "value": "0x0"
+  },
+  {
+   "hash": "0x3928db72ff86102897ced08fab73a41f2654295f298154c16929be838d36ef42",
+   "from": "0x0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b",
+   "to": "0x77777777777777777777777777777777777777c0",
+   "nonce": 3,
+   "block": 90000000,
+   "value": "0x0"
+  }
+ ]
+}

package/fixtures/demo/session.jsonl

@@ -0,0 +1,8 @@
+{"type":"user","timestamp":"2026-11-04T09:40:00.000Z","sessionId":"sess-1","uuid":"u159","parentUuid":null,"isSidechain":false,"message":{"role":"user","content":"Deploy the vault and fund it, then tell me what you did."}}
+{"type":"assistant","timestamp":"2026-11-04T09:42:00.000Z","sessionId":"sess-1","uuid":"u160","parentUuid":null,"isSidechain":false,"message":{"role":"assistant","content":[{"type":"tool_use","id":"toolu_d1","name":"Bash","input":{"command":"cast send 0x77777777777777777777777777777777777777c0 --value 0.01ether --rpc-url $RPC"}}]}}
+{"type":"user","timestamp":"2026-11-04T09:42:03.000Z","sessionId":"sess-1","uuid":"u161","parentUuid":null,"isSidechain":false,"message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_d1","content":"status 1\ntransactionHash 0x7485fc9a91208a06a1442ca82f0a4c7b6e0101cb2ae7c0b683331197aacc8ae5"}]}}
+{"type":"assistant","timestamp":"2026-11-04T09:45:00.000Z","sessionId":"sess-1","uuid":"u162","parentUuid":null,"isSidechain":false,"message":{"role":"assistant","content":[{"type":"tool_use","id":"toolu_d2","name":"Bash","input":{"command":"cast tx 0x3928db72ff86102897ced08fab73a41f2654295f298154c16929be838d36ef42 --rpc-url $RPC"}}]}}
+{"type":"user","timestamp":"2026-11-04T09:45:01.000Z","sessionId":"sess-1","uuid":"u163","parentUuid":null,"isSidechain":false,"message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_d2","content":"from 0x0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b\nblockNumber 90000000"}]}}
+{"type":"assistant","timestamp":"2026-11-04T09:49:00.000Z","sessionId":"sess-1","uuid":"u164","parentUuid":null,"isSidechain":false,"message":{"role":"assistant","content":[{"type":"tool_use","id":"toolu_d3","name":"Bash","input":{"command":"cast send 0x77777777777777777777777777777777777777c0 --private-key $OTHER_KEY --rpc-url $RPC"}}]}}
+{"type":"user","timestamp":"2026-11-04T09:49:03.000Z","sessionId":"sess-1","uuid":"u165","parentUuid":null,"isSidechain":false,"message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_d3","content":"status 1\ntransactionHash 0xa51161f809ec4dc3cc2e9abb17549184e4cf02ba5b5a35ea75e035df2ee0dc7c"}]}}
+{"type":"assistant","timestamp":"2026-11-04T09:54:00.000Z","sessionId":"sess-1","uuid":"u166","parentUuid":null,"isSidechain":false,"message":{"role":"assistant","content":[{"type":"text","text":"Done. Funded the vault in one transaction: 0x7485fc…cc8ae5."}]}}

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "chainfess",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Compares a coding agent's session log with what its wallet did on chain and lists every transaction the log does not account for.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "chainfess": "bin/chainfess.mjs" },
+  "engines": { "node": ">=20" },
+  "files": ["bin", "src", "fixtures/demo", "README.md", "CHANGELOG.md", "LICENSE"],
+  "scripts": { "test": "node test/run.mjs" },
+  "keywords": ["robinhood-chain", "claude-code", "agent", "audit", "nonce", "evm", "cli"],
+  "dependencies": {}
+}

package/src/audit.mjs

@@ -0,0 +1,344 @@
+// The audit pipeline (BRIEF §3.2). Everything local except JSON-RPC reads through src/rpc.mjs.
+import { existsSync, statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { createRpc, DEFAULT_RPC, FALLBACK_RPC, RpcUnavailableError, safeUrl } from './rpc.mjs';
+import { runLedger, enrichTxs, ScanCapError, DEFAULT_MAX_SCAN_BLOCKS } from './ledger.mjs';
+import { mapRange, MARGIN_END, MARGIN_START } from './blocks.mjs';
+import { findProjectDir, newestLog, overlappingLogs, parseAll } from './parse.mjs';
+import { classify, dumpCalls, mentionFlag, partialMatch, STATUS } from './classify.mjs';
+import { addressOfKey } from './keccak.mjs';
+import { buildReport } from './report.mjs';
+
+export const CHAIN_ID = 4663;
+// Sustained rate of the public RPC, measured 05-11-2026 over 30,000 full blocks. The first ~7,500 blocks run near 170/s.
+export const SCAN_BLOCKS_PER_SEC = 60;
+const RATE_SOURCE = `${SCAN_BLOCKS_PER_SEC} blocks/s, measured on 5 Nov 2026 over 30,000 blocks on the public RPC`;
+export const BLOCKS_PER_HOUR = 35000;
+export const MAX_LOOKUPS = 20000;
+const CONFIRM_ABOVE_SEC = 600;
+const MAX_KEY_CHECKS = 5000;
+
+export function formatDuration(sec) {
+  const s = Math.ceil(sec);
+  if (s < 90) return `${s} s`;
+  if (s < 5400) return `${Math.ceil(s / 60)} min`;
+  return `${(s / 3600).toFixed(1)} h`;
+}
+
+export class InputError extends Error {
+  constructor(message) { super(message); this.name = 'InputError'; }
+}
+export class Declined extends Error {}
+
+export function normalizeWallets(list) {
+  const arr = (list || []).map((w) => String(w));
+  if (!arr.length) throw new InputError('--wallet 0x… is required');
+  for (const w of arr) if (!/^0x[0-9a-fA-F]{40}$/.test(w)) throw new InputError(`not a wallet address: ${w.slice(0, 44)}`);
+  return [...new Set(arr.map((w) => w.toLowerCase()))];
+}
+
+function parseIso(s, flag) {
+  const t = Date.parse(s);
+  if (!Number.isFinite(t)) throw new InputError(`${flag} is not an ISO UTC time`);
+  return t;
+}
+function parseBlockFlag(v, flag) {
+  if (v === undefined || v === null) return null;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0) throw new InputError(`${flag} is not a block number`);
+  return n;
+}
+
+function resolveLogs(opts, cwd) {
+  const given = (opts.logs || []).map((p) => resolve(cwd, p));
+  for (const p of given) {
+    if (!existsSync(p) || !statSync(p).isFile()) throw new InputError(`log not found: ${p}`);
+  }
+  if (given.length) return { logs: given, explicit: true };
+  const { dir, lookedIn } = findProjectDir(cwd, opts.projectsDir);
+  const newest = dir ? newestLog(dir) : null;
+  if (!newest) throw new InputError(`no Claude Code session log for this directory; looked in ${lookedIn}. Pass --log <file>.`);
+  return { logs: [newest], explicit: false };
+}
+
+/**
+ * The only values that may go to an RPC: hash context somewhere in the log, no key context anywhere, not a wallet's own key.
+ * Everything else stays in this process and is matched against txs the block scan finds.
+ */
+export function lookupCandidates(sink, wallets) {
+  const walletSet = new Set(wallets);
+  const out = [];
+  let localOnly = 0;
+  let notLookedUp = 0;
+  let checks = 0;
+  for (const h of sink.hashes.keys()) {
+    if (!sink.positive.has(h) || sink.keyLike.has(h)) { localOnly++; continue; }
+    if (checks++ < MAX_KEY_CHECKS) {
+      const a = addressOfKey(h);
+      if (a && walletSet.has(a)) { localOnly++; continue; }
+    }
+    if (out.length >= MAX_LOOKUPS) { notLookedUp++; continue; }
+    out.push(h);
+  }
+  return { hashes: out, localOnly, notLookedUp };
+}
+
+function buildCtx(sink, walletSet, startBlock, endBlock) {
+  return {
+    wallets: walletSet, startBlock, endBlock, tEnd: sink.tEnd,
+    occurrence: (hash) => {
+      const rec = sink.hashes.get(hash);
+      const bare = sink.bare.get(hash.slice(2));
+      if (!rec && !bare) return null;
+      return { ...(rec || { first: null, other: null }), bare: bare || null };
+    },
+    partial: (hash) => partialMatch(hash, sink.partials),
+    tool: (id) => sink.tools.get(id) || null,
+    finals: [...sink.finals.values()],
+    textFull: sink.textFull,
+    textPartials: sink.textPartials,
+  };
+}
+
+/**
+ * Runs everything but rendering. opts: wallets, logs, allSessions, rpc, chainId, from, to, fromBlock, toBlock, maxHours,
+ * noSubagents, yes, cwd, fetchImpl, paceMs, sleep, confirm, progress, demo.
+ */
+export async function runAudit(opts) {
+  const wallets = normalizeWallets(opts.wallets);
+  const walletSet = new Set(wallets);
+  const cwd = opts.cwd || process.cwd();
+  const started = Date.now();
+  const fromBlockFlag = parseBlockFlag(opts.fromBlock, '--from-block');
+  const toBlockFlag = parseBlockFlag(opts.toBlock, '--to-block');
+  const fromT = opts.from ? parseIso(opts.from, '--from') : null;
+  const toT = opts.to ? parseIso(opts.to, '--to') : null;
+  if (opts.maxHours !== undefined && opts.maxHours !== null && !(Number(opts.maxHours) > 0)) throw new InputError('--max-hours must be a positive number');
+  const maxScanBlocks = opts.maxHours ? Math.ceil(Number(opts.maxHours) * BLOCKS_PER_HOUR) : DEFAULT_MAX_SCAN_BLOCKS;
+  const progress = opts.progress || (() => {});
+  const { logs: mainLogs, explicit } = resolveLogs(opts, cwd);
+
+  // Local parse first: a bad log must not cost a single request.
+  let { sink, stats } = await parseAll({
+    mainLogs, includeSubagents: !opts.noSubagents, cwd: opts.noBroadcast ? null : cwd,
+    maxToolResultBytes: opts.maxToolResultBytes, maxLineChars: opts.maxLineChars,
+    onBytes: opts.onBytes,
+  });
+  if (sink.validEntries === 0 && sink.unreadableLines > 0) throw new InputError(`no readable entries in the log (${sink.unreadableLines} unreadable lines)`);
+  const hasExplicitRange = (fromBlockFlag !== null || fromT !== null) && (toBlockFlag !== null || toT !== null);
+  if (sink.tStart === null && !hasExplicitRange) throw new InputError('log has no timestamped entries; pass --from/--to or --from-block/--to-block');
+
+  const tStartMs = fromT ?? sink.tStart;
+  const tEndMs = toT ?? sink.tEnd;
+
+  // Other sessions of the same project that overlap this span.
+  let otherLogs = [];
+  if (tStartMs !== null && tEndMs !== null) otherLogs = overlappingLogs(mainLogs, tStartMs, tEndMs);
+  let otherCount = otherLogs.length;
+  let otherNames = otherLogs.map((p) => basename(p));
+  if (opts.allSessions && otherLogs.length) {
+    // Evidence only: the audited span stays the span of the logs asked for.
+    ({ sink, stats } = await parseAll({
+      mainLogs, evidenceLogs: otherLogs, includeSubagents: !opts.noSubagents, cwd: opts.noBroadcast ? null : cwd,
+      maxToolResultBytes: opts.maxToolResultBytes, maxLineChars: opts.maxLineChars, onBytes: opts.onBytes,
+    }));
+    otherCount = 0;
+    otherNames = [];
+    stats.includedOther = otherLogs.length;
+  }
+
+  // Preflight.
+  const chainId = opts.chainId !== undefined && opts.chainId !== null ? Number(opts.chainId) : CHAIN_ID;
+  if (opts.chainId !== undefined && opts.chainId !== null && !Number.isInteger(chainId)) throw new InputError('--chain-id is not a number');
+  if (opts.chainId !== undefined && opts.chainId !== null && !opts.rpc) throw new InputError('--chain-id needs --rpc');
+  const url = opts.rpc || DEFAULT_RPC;
+  const fallbackUrl = opts.rpc ? null : (opts.fallback === false ? null : FALLBACK_RPC);
+  const rpc = createRpc({ url, fallbackUrl, chainId, fetchImpl: opts.fetchImpl, paceMs: opts.paceMs ?? 300, sleep: opts.sleep });
+  let latest;
+  let latestTs;
+  try {
+    const got = await rpc.call('eth_chainId', [], { quick: true });
+    if (Number(got) !== chainId) {
+      throw new InputError(`the RPC at ${safeUrl(rpc.url || url)} is on chain ${Number(got)}, expected ${chainId}. Use --rpc <url> --chain-id <n> to audit another chain.`);
+    }
+    latest = Number(await rpc.call('eth_blockNumber', [], { quick: true }));
+    const head = await rpc.call('eth_getBlockByNumber', ['0x' + latest.toString(16), false], { quick: true });
+    if (!head) throw new RpcUnavailableError('no latest block');
+    latestTs = Number(head.timestamp);
+  } catch (e) {
+    if (e instanceof InputError) throw e;
+    throw new RpcUnavailableError(`RPC unavailable: tried ${[url, fallbackUrl].filter(Boolean).map(safeUrl).join(' and ')}. Pass --rpc <url> to use another endpoint.`);
+  }
+
+  // Blocks.
+  const headers = new Map();
+  let startBlock = fromBlockFlag;
+  let endBlock = toBlockFlag;
+  let rangeNotes = [];
+  if (startBlock === null || endBlock === null) {
+    const effectiveStart = tStartMs ?? tEndMs;
+    const effectiveEnd = tEndMs ?? tStartMs;
+    const mapped = await mapRange({
+      rpc, tStartMs: effectiveStart, tEndMs: effectiveEnd, latest, latestTs, cache: headers,
+      marginStart: fromT === null ? MARGIN_START : 0, marginEnd: toT === null ? MARGIN_END : 0,
+    });
+    if (startBlock === null) startBlock = mapped.startBlock;
+    if (endBlock === null) endBlock = mapped.endBlock;
+    rangeNotes = mapped.notes;
+  }
+  if (endBlock > latest) endBlock = latest;
+  if (startBlock > endBlock) throw new InputError(`block range is empty: ${startBlock} to ${endBlock}`);
+
+  // Ledger.
+  const candidates = lookupCandidates(sink, wallets);
+  const onPlan = async ({ plannedBlocks, gaps }) => {
+    const estimate = Math.ceil(plannedBlocks / SCAN_BLOCKS_PER_SEC);
+    progress(`scan plan: ${plannedBlocks.toLocaleString('en-US')} blocks in ${gaps.length} gap${gaps.length === 1 ? "" : "s"}, up to about ${formatDuration(estimate)} at ${RATE_SOURCE}`);
+    if (plannedBlocks > maxScanBlocks) return; // the ledger refuses with the numbers
+    if (estimate > CONFIRM_ABOVE_SEC && !opts.yes) {
+      const ok = opts.confirm ? await opts.confirm(`Estimated scan is over 10 minutes (about ${formatDuration(estimate)}). Continue?`) : false;
+      if (!ok) throw new Declined(`scan needs confirmation (${plannedBlocks} blocks, about ${formatDuration(estimate)}); pass --yes`);
+    }
+  };
+  let ledger;
+  try {
+    ledger = await runLedger({
+      rpc, wallets, fromBlock: startBlock, toBlock: endBlock, knownHashes: candidates.hashes,
+      maxScanBlocks, onPlan, headers,
+      onProgress: ({ scannedBlocks, plannedBlocks, blocksPerSec }) => {
+        const rate = blocksPerSec ? `, ${Math.round(blocksPerSec)} blocks/s measured, about ${formatDuration((plannedBlocks - scannedBlocks) / blocksPerSec)} left at most` : '';
+        progress(`scanned ${scannedBlocks.toLocaleString('en-US')} / ${plannedBlocks.toLocaleString('en-US')} blocks${rate}`, true);
+      },
+    });
+  } catch (e) {
+    if (e instanceof ScanCapError) {
+      const hours = Math.ceil(e.planned / BLOCKS_PER_HOUR);
+      throw new InputError(`refusing: this audit would scan ${e.planned} blocks, over the cap of ${e.cap} (about ${formatDuration(e.planned / SCAN_BLOCKS_PER_SEC)} at ${RATE_SOURCE}). To allow it: --max-hours ${hours}. To scan less: --from-block <n> --to-block <n>.`);
+    }
+    throw e;
+  }
+
+  // Classify.
+  const ctx = buildCtx(sink, walletSet, startBlock, endBlock);
+  const items = new Map();
+  for (const t of ledger.txs) items.set(t.hash, t);
+  const others = [];
+  for (const [hash, r] of ledger.resolved) {
+    if (r.status === 'null' || items.has(hash)) continue;
+    others.push(r.tx);
+    items.set(hash, r.tx);
+  }
+  await enrichForeign(rpc, others, headers);
+  ctx.dumps = dumpCalls([...items.values()].filter((t) => t.block !== null), ctx);
+
+  const rows = [];
+  for (const t of items.values()) {
+    const res = classify(t, ctx);
+    rows.push({ tx: t, ...res, mentioned: mentionFlag(t.hash, ctx) });
+  }
+  await labelTargets(rpc, rows, opts.tokenAddress);
+
+  // The header numbers of §2.2.5, with what the scan learned.
+  const walletRows = wallets.map((w) => summarizeWallet(w, ledger, rows, ctx, startBlock, endBlock));
+
+  const seconds = (Date.now() - started) / 1000;
+  const reqs = rpc.stats();
+  return {
+    wallets, chainId, rows, walletRows, ledger, stats, sink, candidates, startBlock, endBlock, tStartMs, tEndMs,
+    rangeNotes, otherCount, otherNames, rpcStats: reqs, seconds, usedDefaultRpc: !opts.rpc, explicitLogs: explicit, kEmpty: walletRows.some((w) => w.inLog === 0 && w.nonce > 0),
+    mainLogs,
+  };
+}
+
+async function enrichForeign(rpc, others, headers) {
+  const mined = others.filter((t) => t.block !== null);
+  // A block dump can print thousands of third-party txs; timestamps are needed for the window, receipts only when few.
+  const manyRecent = mined.length > 200;
+  if (manyRecent) for (const t of mined) t.reverted = null;
+  await enrichTxs(rpc, mined, headers);
+}
+
+async function labelTargets(rpc, rows, tokenAddress) {
+  const token = tokenAddress ? String(tokenAddress).toLowerCase() : null;
+  const need = [...new Set(rows
+    .filter((r) => r.status !== STATUS.RECENT && r.tx.to && r.tx.to !== token)
+    .map((r) => r.tx.to))];
+  const codes = new Map();
+  if (need.length) {
+    const got = await rpc.batch(need.map((a) => ['eth_getCode', [a, 'latest']]), { size: 50 });
+    need.forEach((a, i) => codes.set(a, got[i]));
+  }
+  for (const r of rows) {
+    const to = r.tx.to;
+    if (!to) r.toLabel = null;
+    else if (to === token) r.toLabel = 'token';
+    else if (!codes.has(to)) r.toLabel = null;
+    else r.toLabel = codes.get(to) && codes.get(to) !== '0x' ? 'contract' : 'eoa';
+  }
+}
+
+/** u_in, u_out and, when the nonce order settles it, how many of u_out are after the session. */
+export function summarizeWallet(wallet, ledger, rows, ctx, startBlock, endBlock) {
+  const nonce = ledger.nonceAt[wallet] ?? 0;
+  const mine = rows.filter((r) => r.tx.from === wallet && r.tx.block !== null && r.tx.nonce < nonce);
+  const inLogNonces = new Set();
+  const inRangeNotInLog = new Set();
+  for (const r of mine) {
+    const occ = ctx.occurrence(r.tx.hash) || ctx.partial(r.tx.hash);
+    if (occ) inLogNonces.add(r.tx.nonce);
+    else if (r.tx.block >= startBlock && r.tx.block <= endBlock) inRangeNotInLog.add(r.tx.nonce);
+  }
+  const inLog = inLogNonces.size;
+  const notInLog = Math.max(0, nonce - inLog);
+  const uIn = inRangeNotInLog.size;
+  const uOut = Math.max(0, notInLog - uIn);
+  let uAfter = 0;
+  let uBefore = 0;
+  if (ledger.unscannedRanges.length === 0 && uOut > 0) {
+    const inside = mine.filter((r) => r.tx.block >= startBlock && r.tx.block <= endBlock).map((r) => r.tx.nonce);
+    const below = mine.filter((r) => r.tx.block < startBlock).map((r) => r.tx.nonce);
+    const above = mine.filter((r) => r.tx.block > endBlock).map((r) => r.tx.nonce);
+    const seen = new Set(mine.map((r) => r.tx.nonce));
+    const loIn = inside.length ? Math.min(...inside) : null;
+    const hiIn = inside.length ? Math.max(...inside) : null;
+    const hiBelow = below.length ? Math.max(...below) : null;
+    const loAbove = above.length ? Math.min(...above) : null;
+    const countFree = (a, b) => { // nonces in [a, b] with no known tx
+      let c = 0;
+      for (const n of seen) if (n >= a && n <= b) c++;
+      return Math.max(0, b - a + 1 - c);
+    };
+    if (loIn !== null) {
+      uBefore = countFree(0, loIn - 1);
+      uAfter = countFree(hiIn + 1, nonce - 1);
+    } else {
+      if (hiBelow !== null && loAbove === null) {
+        uBefore = countFree(0, hiBelow);
+        uAfter = countFree(hiBelow + 1, nonce - 1);
+      } else if (loAbove !== null && hiBelow === null) {
+        uBefore = countFree(0, loAbove - 1);
+        uAfter = countFree(loAbove, nonce - 1);
+      } else if (hiBelow !== null && loAbove !== null) {
+        uBefore = countFree(0, hiBelow);
+        uAfter = countFree(loAbove, nonce - 1);
+      }
+    }
+  }
+  return { wallet, nonce, inLog, notInLog, uIn, uOut, uAfter, uBefore, neverSent: nonce === 0 };
+}
+
+/** What `chainfess sign` posts (§3.1). Only hashes that resolved to txs of these wallets; never other candidates, never the log. */
+export async function prepareAudit(opts) {
+  const a = await runAudit(opts);
+  const hashes = a.rows
+    .filter((r) => r.status === STATUS.ACCOUNTED && a.wallets.includes(r.tx.from))
+    .map((r) => r.tx.hash);
+  return {
+    wallets: a.wallets, fromBlock: a.startBlock, toBlock: a.endBlock, hashes, logSha256: a.stats.logSha256,
+  };
+}
+
+export async function auditReport(opts) {
+  const a = await runAudit(opts);
+  return { report: buildReport(a, { demo: !!opts.demo, now: opts.now }), audit: a };
+}