chainfess 0.0.0-stage → 0.1.0

package/src/replay.mjs

@@ -0,0 +1,67 @@
+// A recorded chain answering JSON-RPC from a fixture. Used by `demo` and by tests. Never touches the network.
+// world: { chainId, latest, latestTs, blockTime, nonces:{addr:n}, code:{addr:hex}, txs:[{hash,from,to,nonce,block,value,status,contractAddress}], pending:[…] }
+export function createReplay(world) {
+  const log = { requests: 0, blocksFull: [], blocksHeader: [], hashes: [], receipts: [], methods: {}, bodies: [] };
+  const blockTime = world.blockTime ?? 0.104;
+  const txByHash = new Map();
+  const byBlock = new Map();
+  for (const t of world.txs || []) {
+    txByHash.set(t.hash.toLowerCase(), t);
+    if (t.block !== null && t.block !== undefined) {
+      if (!byBlock.has(t.block)) byBlock.set(t.block, []);
+      byBlock.get(t.block).push(t);
+    }
+  }
+  const tsOf = (n) => {
+    if (world.timestampAt) return world.timestampAt(n);
+    return Math.floor(world.latestTs - (world.latest - n) * blockTime);
+  };
+  const hex = (n) => '0x' + Number(n).toString(16);
+  const rpcTx = (t) => ({
+    hash: t.hash, from: t.from, to: t.to ?? null, nonce: hex(t.nonce),
+    blockNumber: t.block === null || t.block === undefined ? null : hex(t.block),
+    value: t.value ?? '0x0', input: t.input ?? '0x',
+  });
+  const answer = (method, params) => {
+    log.methods[method] = (log.methods[method] || 0) + 1;
+    switch (method) {
+      case 'eth_chainId': return hex(world.chainId);
+      case 'eth_blockNumber': return hex(world.latest);
+      case 'eth_getTransactionCount': return hex((world.nonces || {})[String(params[0]).toLowerCase()] ?? 0);
+      case 'eth_getCode': return (world.code || {})[String(params[0]).toLowerCase()] ?? '0x';
+      case 'eth_getBlockByNumber': {
+        const n = params[0] === 'latest' ? world.latest : Number(params[0]);
+        if (world.prunedBelow !== undefined && n < world.prunedBelow) return null;
+        if (n > world.latest || n < 0) return null;
+        (params[1] ? log.blocksFull : log.blocksHeader).push(n);
+        const list = byBlock.get(n) || [];
+        return { number: hex(n), timestamp: hex(tsOf(n)), transactions: params[1] ? list.map(rpcTx) : list.map((t) => t.hash) };
+      }
+      case 'eth_getTransactionByHash': {
+        const h = String(params[0]).toLowerCase();
+        log.hashes.push(h);
+        const t = txByHash.get(h);
+        return t ? rpcTx(t) : null;
+      }
+      case 'eth_getTransactionReceipt': {
+        const h = String(params[0]).toLowerCase();
+        log.receipts.push(h);
+        const t = txByHash.get(h);
+        if (!t || t.block === null || t.block === undefined) return null;
+        return { transactionHash: t.hash, status: t.status ?? '0x1', contractAddress: t.contractAddress ?? null, blockNumber: hex(t.block) };
+      }
+      default:
+        throw new Error(`replay: no answer for ${method}`);
+    }
+  };
+  const fetchImpl = async (_url, init) => {
+    log.requests++;
+    log.bodies.push(init.body);
+    if (world.fail && world.fail(log)) return { status: 503, json: async () => ({}) };
+    const req = JSON.parse(init.body);
+    const one = (r) => ({ jsonrpc: '2.0', id: r.id, result: answer(r.method, r.params) });
+    const res = Array.isArray(req) ? req.map(one) : one(req);
+    return { status: 200, json: async () => res };
+  };
+  return { fetchImpl, log };
+}

package/src/report.mjs

@@ -0,0 +1,273 @@
+// Report JSON and text. Only whitelisted fields (BRIEF §3.5): command text, tool input and log excerpts never get here.
+import { toChecksum } from './keccak.mjs';
+import { STATUS } from './classify.mjs';
+import { DEFAULT_RPC } from './rpc.mjs';
+
+export const TOOL_VERSION = '0.1.0';
+const iso = (ms) => (ms === null || ms === undefined ? null : new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z'));
+
+export function weiToEth(wei) {
+  const w = BigInt(wei);
+  const whole = w / 10n ** 18n;
+  const frac = (w % 10n ** 18n).toString().padStart(18, '0').replace(/0+$/, '');
+  return frac ? `${whole}.${frac}` : `${whole}`;
+}
+
+const STATUS_ORDER = [STATUS.UNACCOUNTED, STATUS.FOREIGN, STATUS.PARTIAL, STATUS.ACCOUNTED, STATUS.PRE, STATUS.POST, STATUS.PENDING, STATUS.OBSERVED, STATUS.RECENT];
+
+export function buildReport(a, { demo = false, now = null } = {}) {
+  const generated = now ?? Date.now();
+  const rows = [...a.rows].sort((x, y) => STATUS_ORDER.indexOf(x.status) - STATUS_ORDER.indexOf(y.status) || (x.tx.block ?? Infinity) - (y.tx.block ?? Infinity) || x.tx.nonce - y.tx.nonce);
+  const txs = rows.map((r) => ({
+    hash: r.tx.hash,
+    status: r.status,
+    finding: r.finding,
+    from: toChecksum(r.tx.from),
+    to: r.tx.to ? toChecksum(r.tx.to) : null,
+    toLabel: r.toLabel ?? null,
+    nonce: r.tx.nonce,
+    block: r.tx.block,
+    time: r.tx.time ?? null,
+    valueWei: r.tx.valueWei,
+    valueEth: weiToEth(r.tx.valueWei),
+    reverted: r.tx.reverted ?? null,
+    contractCreation: r.tx.to === null,
+    createdAddress: r.tx.createdAddress ? toChecksum(r.tx.createdAddress) : null,
+    mentioned: r.mentioned,
+    source: r.source ? { kind: r.source.kind, line: r.source.line } : { kind: null, line: null },
+    pattern: r.pattern ?? null,
+  }));
+  const count = (s) => txs.filter((t) => t.status === s).length;
+  const mine = rows.filter((r) => a.wallets.includes(r.tx.from));
+  const mentioned = { final: 0, text: 0, none: 0 };
+  for (const r of mine) mentioned[r.mentioned]++;
+  const postDerived = a.walletRows.reduce((s, w) => s + w.uAfter, 0);
+  const findings = txs.filter((t) => t.finding).length;
+  const unscanned = a.ledger.unscannedRanges.map((r) => ({ from: r.from, to: r.to }));
+  const exitCode = demo ? 0 : unscanned.length ? 4 : findings ? 1 : 0; // the demo process exits 0 whatever its fixture holds
+  const stats = a.stats;
+  return {
+    v: 1,
+    tool: 'chainfess',
+    toolVersion: TOOL_VERSION,
+    demo,
+    generatedAt: iso(generated),
+    chainId: a.chainId,
+    logs: {
+      main: stats.main,
+      subagents: stats.subagents,
+      toolResults: stats.toolResults,
+      broadcast: stats.broadcast,
+      unreadableLines: a.sink.unreadableLines,
+      otherOverlapping: a.otherCount,
+      otherOverlappingFiles: a.otherNames,
+      includedOtherSessions: stats.includedOther ?? 0,
+      missingToolResults: stats.missingToolResults,
+      skippedToolResults: stats.skippedToolResults,
+      skippedBroadcast: stats.skippedBroadcast,
+      broadcastTruncated: stats.broadcastTruncated,
+      notLookedUp: a.candidates.notLookedUp,
+      note: unreadableOutputsNote(stats),
+    },
+    session: {
+      tStart: iso(a.tStartMs), tEnd: iso(a.tEndMs),
+      startBlock: a.startBlock, endBlock: a.endBlock, blocks: a.endBlock - a.startBlock + 1,
+      note: a.rangeNotes.length ? a.rangeNotes.join('; ') : null,
+    },
+    wallets: a.walletRows.map((w) => ({
+      address: toChecksum(w.wallet), nonce: w.nonce, inLog: w.inLog, notInLog: w.notInLog,
+      uIn: w.uIn, uOut: w.uOut, uAfter: w.uAfter, uBefore: w.uBefore, neverSent: w.neverSent,
+    })),
+    scan: {
+      plannedBlocks: a.ledger.plannedBlocks, scannedBlocks: a.ledger.scannedBlocks,
+      gaps: a.ledger.gaps.map((g) => ({ from: g.from, to: g.to })), unscanned,
+      seconds: Math.round(a.ledger.scanSeconds * 10) / 10,
+      blocksPerSec: a.ledger.scanSeconds > 0 ? Math.round(a.ledger.scannedBlocks / a.ledger.scanSeconds) : null,
+      requests: a.rpcStats.requests,
+      fallbackUsed: a.rpcStats.fallbackUsed,
+    },
+    summary: {
+      findings,
+      accounted: count(STATUS.ACCOUNTED), partial: count(STATUS.PARTIAL), unaccounted: count(STATUS.UNACCOUNTED),
+      foreignSigner: count(STATUS.FOREIGN), preSession: count(STATUS.PRE), postSession: count(STATUS.POST) + postDerived,
+      pending: count(STATUS.PENDING), recentOther: count(STATUS.RECENT), observed: count(STATUS.OBSERVED),
+      unresolvedHashes: a.ledger.unresolvedHashes,
+      localOnlyHashes: a.candidates.localOnly + a.sink.bare.size + a.candidates.notLookedUp,
+      mentioned,
+    },
+    txs,
+    exitCode,
+    verify: { rpc: a.usedDefaultRpc ? DEFAULT_RPC : null },
+  };
+}
+
+function unreadableOutputsNote(stats) {
+  const m = stats.missingToolResults;
+  const s = stats.skippedToolResults;
+  const b = stats.skippedBroadcast;
+  if (!m && !s && !b && !stats.broadcastTruncated) return null;
+  const parts = [];
+  if (m) parts.push(`${m} saved tool output${m === 1 ? '' : 's'} missing from disk`);
+  if (s) parts.push(`${s} saved tool output${s === 1 ? '' : 's'} over the 512 MB read limit`);
+  if (b) parts.push(`${b} broadcast file${b === 1 ? '' : 's'} over 5 MB or not readable`);
+  if (stats.broadcastTruncated) parts.push('broadcast search stopped at its directory limit');
+  return `This log refers to outputs that could not be read: ${parts.join(', ')}. "not in this log" lines may be explained by those unreadable outputs.`;
+}
+
+// ---------- text ----------
+
+const short = (h, a = 8, b = 6) => (h ? `${h.slice(0, a)}…${h.slice(-b)}` : '-');
+const n = (x) => Number(x).toLocaleString('en-US');
+const plural = (c, word) => `${c} ${word}${c === 1 ? '' : 's'}`;
+const hhmmss = (isoTime) => (isoTime ? `${isoTime.slice(11, 19)} UTC` : '-');
+
+function palette(color) {
+  const wrap = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+  return { bold: wrap('1'), dim: wrap('2'), red: wrap('1;31'), yellow: wrap('33'), green: wrap('32'), cyan: wrap('36'), inv: wrap('1;30;43') };
+}
+
+function span(report) {
+  const { tStart, tEnd } = report.session;
+  if (!tStart || !tEnd) return 'range set by flags';
+  const d1 = tStart.slice(0, 10);
+  const d2 = tEnd.slice(0, 10);
+  return `${d1} ${tStart.slice(11, 16)}–${d2 === d1 ? '' : d2 + ' '}${tEnd.slice(11, 16)} UTC`;
+}
+
+function target(t) {
+  if (t.contractCreation) return t.createdAddress ? `creates ${short(t.createdAddress, 6, 4)}` : 'creates a contract';
+  const label = t.toLabel && t.toLabel !== 'eoa' ? ` (${t.toLabel})` : '';
+  return `→ ${short(t.to, 6, 4)}${label}`;
+}
+
+function flags(t) {
+  const f = [];
+  if (t.reverted) f.push('reverted');
+  return f.length ? `  [${f.join(', ')}]` : '';
+}
+
+function nonceLine(w, report) {
+  if (w.neverSent) return ['nonce 0: this wallet has never sent a transaction.'];
+  const parts = [];
+  if (w.uIn) parts.push(`${w.uIn} inside this session (below)`);
+  const other = w.uOut - w.uAfter - w.uBefore;
+  if (w.uBefore) parts.push(`${w.uBefore} before it`);
+  if (w.uAfter) parts.push(`${w.uAfter} after it`);
+  if (other > 0) parts.push(report.scan.unscanned.length ? `${other} not placed (unscanned ranges remain)` : `${other} outside it`);
+  const first = `nonce ${w.nonce}: this wallet has sent ${w.nonce} tx. ${w.inLog} ${w.inLog === 1 ? 'appears' : 'appear'} in this log.`;
+  return w.notInLog ? [first, `${w.notInLog} do${w.notInLog === 1 ? 'es' : ''} not: ${parts.join(', ')}.`] : [first];
+}
+
+export function renderText(report, { color = false, quiet = false } = {}) {
+  const c = palette(color);
+  const lines = [];
+  const tag = report.demo ? `${c.inv(' DEMO — fixture data ')} ` : '';
+  const head = (s) => lines.push(tag + s);
+  head(c.bold(`CHAINFESS AUDIT — chain ${report.chainId} — ${report.generatedAt.slice(0, 10)} ${report.generatedAt.slice(11, 16)} UTC`));
+  const logBits = [];
+  if (report.logs.subagents) logBits.push(plural(report.logs.subagents, 'subagent'));
+  if (report.logs.toolResults) logBits.push(plural(report.logs.toolResults, 'saved output'));
+  if (report.logs.broadcast) logBits.push(plural(report.logs.broadcast, 'broadcast file'));
+  if (report.logs.includedOtherSessions) logBits.push(plural(report.logs.includedOtherSessions, 'other session'));
+  const walletList = report.wallets.map((w) => short(w.address, 7, 4)).join(', ');
+  head(`wallet ${walletList}   log ${report.logs.main.join(', ')}${logBits.length ? ` (+${logBits.join(', ')})` : ''}`);
+  head(`session ${span(report)} → blocks ${n(report.session.startBlock)}–${n(report.session.endBlock)} (${n(report.session.blocks)} blocks)`);
+  for (const w of report.wallets) {
+    for (const line of nonceLine(w, report)) head((report.wallets.length > 1 ? `${short(w.address, 7, 4)} ` : '') + line);
+  }
+  const gaps = report.scan.gaps.length;
+  head(report.scan.plannedBlocks
+    ? `scanned ${n(report.scan.scannedBlocks)} blocks in ${plural(gaps, 'gap')} (${report.demo ? 'recorded replies' : `${report.scan.seconds} s`})`
+    : 'scanned 0 blocks: the nonces in this log leave no gap inside the session');
+  if (report.session.note) head(c.dim(`note: ${report.session.note}`));
+  lines.push('');
+
+  const by = (s) => report.txs.filter((t) => t.status === s);
+  const findings = report.txs.filter((t) => t.finding);
+  lines.push(findings.length ? c.red(`FINDINGS (${findings.length})`) : c.green('FINDINGS (0)'));
+  for (const t of by(STATUS.UNACCOUNTED)) {
+    lines.push(`  ${c.red('not in this log')}`);
+    lines.push(`    ${t.hash}`);
+    lines.push(c.dim(`    nonce ${t.nonce}  block ${n(t.block)}  ${hhmmss(t.time)}  ${t.valueEth} ETH ${target(t)}${flags(t)}`));
+  }
+  for (const t of by(STATUS.FOREIGN)) {
+    lines.push(`  ${c.red('signed by a wallet not registered here')}`);
+    lines.push(`    ${t.hash}`);
+    lines.push(c.dim(`    from ${t.from}`));
+    lines.push(c.dim(`    pattern ${t.pattern}  ${t.source.kind} L${t.source.line}  block ${n(t.block)}  ${hhmmss(t.time)}${flags(t)}`));
+  }
+  if (!findings.length) {
+    for (const w of report.wallets) {
+      const anyMine = report.txs.some((t) => t.from === w.address && t.block !== null && t.block >= report.session.startBlock && t.block <= report.session.endBlock);
+      if (!anyMine && !w.neverSent && !report.scan.unscanned.length) {
+        lines.push(`  0 transactions from ${w.address} between blocks ${n(report.session.startBlock)}–${n(report.session.endBlock)} (${span(report)}). Nothing to reconcile.`);
+      }
+    }
+  }
+
+  const section = (title, list, row, paint = (s) => s) => {
+    if (!list.length) return;
+    lines.push(paint(`${title} (${list.length})`));
+    for (const t of list) lines.push(`  ${row(t)}`);
+  };
+  const where = (t) => (t.source && t.source.kind ? `${t.source.kind}${t.source.line ? ` L${t.source.line}` : ''}${t.pattern ? ` (${t.pattern})` : ''}` : 'no source');
+  if (!quiet) {
+    section('PARTIAL MATCH ONLY', by(STATUS.PARTIAL), (t) => `${short(t.hash)}  nonce ${t.nonce}  partial form at ${where(t)}${flags(t)}`, c.yellow);
+    section('ACCOUNTED', by(STATUS.ACCOUNTED), (t) => `${short(t.hash)}  nonce ${t.nonce}  ${where(t)}  mentioned: ${t.mentioned}${flags(t)}`, c.green);
+    section('SENT BEFORE THIS SESSION, referenced in log', by(STATUS.PRE), (t) => `${short(t.hash)}  nonce ${t.nonce}  block ${n(t.block)}`, c.dim);
+    section('SENT AFTER THIS SESSION', by(STATUS.POST), (t) => `${short(t.hash)}  nonce ${t.nonce}  block ${n(t.block)}`, c.dim);
+    section('PENDING at audit time; re-run later', by(STATUS.PENDING), (t) => `${short(t.hash)}  nonce ${t.nonce}`, c.yellow);
+    const observed = by(STATUS.OBSERVED);
+    section('OTHER WALLETS referenced (read)', observed.slice(0, 8), (t) => `${short(t.hash)}  from ${short(t.from, 7, 4)}  ${where(t)}`, c.dim);
+    if (observed.length > 8) lines.push(c.dim(`  … and ${observed.length - 8} more (--json lists them)`));
+  } else if (report.summary.accounted) {
+    lines.push(`accounted: ${report.summary.accounted}`);
+  }
+  const m = report.summary.mentioned;
+  const total = m.final + m.text + m.none;
+  if (!quiet && total) lines.push(c.dim(`the agent's own words mention ${m.final + m.text} of ${total} transactions`));
+  const recent = by(STATUS.RECENT);
+  if (recent.length) lines.push(c.dim(`other wallets' txs mined during a tool call; cannot tell a read from a send: ${recent.length} (--json lists them)`));
+
+  lines.push('');
+  for (const line of footer(report)) for (const piece of wrap(line, 96)) lines.push(c.dim(piece));
+  return lines.join('\n') + '\n';
+}
+
+function wrap(line, width) {
+  const indent = line.match(/^\s*/)[0];
+  if (indent) return [line]; // commands stay whole so they can be copied
+  const out = [];
+  let cur = '';
+  for (const word of line.split(' ')) {
+    if (cur && cur.length + word.length + 1 > width) { out.push(cur); cur = word; } else cur = cur ? `${cur} ${word}` : word;
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+function footer(report) {
+  const out = [];
+  const logs = report.logs;
+  const un = report.summary.unresolvedHashes;
+  if (un) out.push(`Looked up, not a tx: ${un} ${un === 1 ? 'hash' : 'hashes'} in the log ${un === 1 ? 'is' : 'are'} not a transaction on chain ${report.chainId}.`);
+  const lo = report.summary.localOnlyHashes;
+  if (lo) out.push(`Not looked up, stays local: ${lo} 32-byte ${lo === 1 ? 'value' : 'values'} with nothing saying ${lo === 1 ? 'it is' : 'they are'} a tx hash. Never sent to the RPC; matched here against this wallet's txs found by the scan.`);
+  if (logs.unreadableLines) out.push(`${logs.unreadableLines} unreadable line${logs.unreadableLines === 1 ? '' : 's'} in the log; hex strings in them were still searched.`);
+  if (logs.note) out.push(logs.note);
+  if (report.wallets.some((w) => w.nonce > 0 && w.inLog === 0)) out.push('No hash of this wallet is in the log, so the whole audited range was scanned.');
+  if (report.scan.unscanned.length) out.push(`Unscanned block ranges: ${report.scan.unscanned.map((r) => `${r.from}–${r.to}`).join(', ')}. Txs in them are not listed; re-run.`);
+  if (report.scan.fallbackUsed) out.push('The primary RPC failed; fallback RPC was used, about 15x slower.');
+  if (report.summary.pending) out.push('Pending txs: re-run after inclusion.');
+  if (logs.otherOverlapping) out.push(`${logs.otherOverlapping} other session log${logs.otherOverlapping === 1 ? '' : 's'} overlap${logs.otherOverlapping === 1 ? 's' : ''} this range (${logs.otherOverlappingFiles.slice(0, 3).join(', ')}${logs.otherOverlappingFiles.length > 3 ? ', …' : ''}); add them with --log or --all-sessions before drawing conclusions.`);
+  if (report.summary.unaccounted) out.push('"not in this log" means exactly that. A human, a cron job or another session on the same wallet produces the same line. Chainfess does not say who sent it.');
+  if (report.summary.foreignSigner) out.push('"signed by a wallet not registered here": the hash came out of a sending command, mined during that call, from a wallet you did not pass with --wallet.');
+  out.push('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.');
+  const rpcFlag = report.verify && report.verify.rpc ? ` --rpc-url ${report.verify.rpc}` : ' --rpc-url $RPC_URL';
+  const first = report.txs.find((t) => t.finding) || report.txs.find((t) => t.block !== null);
+  const verify = [];
+  if (first) verify.push(`cast tx ${first.hash}${rpcFlag}`);
+  if (report.wallets[0]) verify.push(`cast nonce ${report.wallets[0].address}${rpcFlag}`);
+  if (verify.length) out.push('Verify:', ...verify.map((v) => `  ${v}`));
+  return out;
+}

package/src/rpc.mjs

@@ -0,0 +1,225 @@
+// JSON-RPC client (BRIEF §3.4). The only HTTP client in the audit path.
+export const DEFAULT_RPC = 'https://robinhood-rpc.publicnode.com';
+export const FALLBACK_RPC = 'https://robinhood.drpc.org';
+
+export class RpcUnavailableError extends Error {
+  constructor(message) { super(message); this.name = 'RpcUnavailableError'; }
+}
+
+const USER_AGENT = 'chainfess/0.1';
+const GROW_AFTER = 20;
+const THROTTLE_STATUS = new Set([429, 502, 503]);
+const THROTTLE_CODES = new Set([-32005, -32029, -32603]);
+const SIZE_STEPS = [100, 50, 25, 10];
+const START_IN_FLIGHT = 2;
+const MAX_IN_FLIGHT = 3;
+// publicnode, measured 05-11: about 7,500 full blocks of burst at 170/s, then a refill near 60-80/s; 429s clear within 5 s.
+// So the client paces by items per second and backs off gently: a hard back-off here drops the rate far below what the RPC allows.
+const START_RATE = 170;
+const MIN_RATE = 20;
+const FALLBACK_RATE = 6;
+const MIN_GAP_MS = 30;
+const RAISE_AFTER = 5;
+const FIRST_HOLD_MS = 3000;
+
+class Throttle extends Error {}
+
+function isThrottleError(err) {
+  if (!err || typeof err !== 'object') return false;
+  return THROTTLE_CODES.has(err.code) && /rate|limit|too many/i.test(String(err.message || ''));
+}
+
+/** origin only, so a key in a custom RPC URL path or query is never printed */
+export function safeUrl(url) {
+  try { return new URL(url).origin; } catch { return '(invalid url)'; }
+}
+
+export function createRpc({
+  url, fallbackUrl = null, chainId, fetchImpl, onRequest,
+  paceMs = 300, tries = 6, timeoutMs = 20000,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  random = Math.random,
+}) {
+  const doFetch = (...a) => (fetchImpl || globalThis.fetch)(...a);
+  const state = {
+    url, single: false, fallbackUsed: false, requests: 0, byMethod: {},
+    failedInARow: 0, id: 0,
+    maxInFlight: START_IN_FLIGHT, inFlight: 0, successes: 0, raises: 0, rate: START_RATE, nextStart: 0, waiters: [],
+    holdUntil: 0, hold: FIRST_HOLD_MS, lastThrottle: 0, throttles: 0,
+  };
+  const paced = paceMs > 0;
+
+  async function acquire(items) {
+    while (state.inFlight >= state.maxInFlight) await new Promise((r) => state.waiters.push(r));
+    state.inFlight++;
+    const now = Date.now();
+    const start = Math.max(now, state.nextStart, state.holdUntil);
+    state.nextStart = start + (paced ? Math.max(MIN_GAP_MS, (items / state.rate) * 1000) : 0);
+    if (start > now) await sleep(start - now);
+  }
+  function release() {
+    state.inFlight--;
+    const w = state.waiters.shift();
+    if (w) w();
+  }
+  function noteSuccess() {
+    state.hold = FIRST_HOLD_MS;
+    if (++state.successes >= GROW_AFTER) {
+      state.successes = 0;
+      state.maxInFlight = Math.min(MAX_IN_FLIGHT, state.maxInFlight + 1);
+    }
+    if (!state.single && ++state.raises >= RAISE_AFTER) {
+      state.raises = 0;
+      state.rate = Math.min(START_RATE, state.rate * 1.1);
+    }
+  }
+  /** One wave of 429s counts once; everything in flight waits together. */
+  function noteThrottle() {
+    state.successes = 0;
+    state.raises = 0;
+    state.throttles++;
+    const now = Date.now();
+    if (now - state.lastThrottle < 1000) return;
+    state.lastThrottle = now;
+    state.maxInFlight = 1;
+    state.rate = Math.max(state.single ? FALLBACK_RATE : MIN_RATE, state.rate * 0.75);
+    state.holdUntil = now + state.hold + random() * 500;
+    state.hold = Math.min(32000, state.hold * 1.5);
+  }
+
+  /** One HTTP POST. Returns results aligned with items; throws on any failure. */
+  async function post(items) {
+    await acquire(items.length);
+    try {
+      const reqs = items.map(([method, params]) => ({ jsonrpc: '2.0', id: ++state.id, method, params: params ?? [] }));
+      state.requests++;
+      for (const r of reqs) state.byMethod[r.method] = (state.byMethod[r.method] || 0) + 1;
+      if (onRequest) onRequest({ method: reqs[0].method, count: reqs.length });
+      const body = JSON.stringify(reqs.length === 1 ? reqs[0] : reqs);
+      const res = await doFetch(state.url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'user-agent': USER_AGENT },
+        body,
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (THROTTLE_STATUS.has(res.status)) throw new Throttle(`HTTP ${res.status}`);
+      if (res.status !== 200) throw new Error(`HTTP ${res.status}`);
+      const parsed = await res.json();
+      const arr = Array.isArray(parsed) ? parsed : [parsed];
+      if (arr.length < reqs.length) throw new Throttle('fewer results than requested');
+      const byId = new Map(arr.map((x) => [x && x.id, x]));
+      const out = [];
+      for (const r of reqs) {
+        const x = byId.get(r.id);
+        if (!x) throw new Throttle('missing result');
+        if (x.error) {
+          if (isThrottleError(x.error)) throw new Throttle('rpc rate limit');
+          throw new Error(`rpc error ${x.error.code}`);
+        }
+        out.push(x.result === undefined ? null : x.result);
+      }
+      noteSuccess();
+      return out;
+    } catch (e) {
+      if (e instanceof Throttle) noteThrottle();
+      throw e;
+    } finally {
+      release();
+    }
+  }
+
+  async function switchToFallback() {
+    if (state.single || !fallbackUrl) return false;
+    state.url = fallbackUrl;
+    state.single = true;
+    state.fallbackUsed = true;
+    state.rate = FALLBACK_RATE; // <= 6 r/s
+    state.maxInFlight = 1;
+    state.failedInARow = 0;
+    try {
+      if (chainId != null) {
+        const [got] = await post([['eth_chainId', []]]);
+        if (Number(got) !== Number(chainId)) throw new Error('fallback is on another chain');
+      }
+    } catch {
+      fallbackDead = true;
+    }
+    return !fallbackDead;
+  }
+  let fallbackDead = false;
+
+  const backoff = (k) => sleep(Math.min(32000, 1000 * 2 ** k) + random() * 500);
+
+  /** Runs items with retry and shrinking batches. Throws when out of tries. */
+  async function attempt(items, { size, nonNull, maxTries }) {
+    const results = new Array(items.length);
+    let pending = items.map((_, i) => i);
+    let failures = 0;
+    let cur = Math.min(size, Math.max(items.length, 1));
+    const limit = maxTries ?? tries;
+    while (pending.length) {
+      const chunkSize = state.single ? 1 : cur;
+      const idx = pending.slice(0, chunkSize);
+      try {
+        const got = await post(idx.map((i) => items[i]));
+        if (nonNull && got.some((x) => x === null)) {
+          for (let j = 0; j < idx.length; j++) if (got[j] !== null) results[idx[j]] = got[j];
+          pending = pending.filter((i) => results[i] === undefined || results[i] === null);
+          noteThrottle();
+          throw new Error('null in a range the chain has passed');
+        }
+        for (let j = 0; j < idx.length; j++) results[idx[j]] = got[j];
+        pending = pending.slice(idx.length);
+      } catch (e) {
+        failures++;
+        if (failures >= limit) throw e;
+        const throttled = e instanceof Throttle;
+        if (failures >= 3) {
+          const next = SIZE_STEPS.find((s) => s < cur);
+          if (next) cur = next;
+        }
+        if (!throttled) await backoff(failures - 1); // a throttle already holds every request
+      }
+    }
+    return results;
+  }
+
+  async function run(items, opts) {
+    if (!items.length) return [];
+    for (;;) {
+      if (fallbackDead) throw new RpcUnavailableError('all RPC endpoints failed');
+      try {
+        const out = await attempt(items, opts);
+        state.failedInARow = 0;
+        return out;
+      } catch (e) {
+        state.failedInARow++;
+        const quick = opts.quick || state.failedInARow >= 3;
+        if (quick && !state.single && fallbackUrl) {
+          if (await switchToFallback()) continue;
+        }
+        throw new RpcUnavailableError(e && e.message ? e.message : 'rpc failed');
+      }
+    }
+  }
+
+  return {
+    /** `quick`: used by preflight, gives up on the primary after 2 tries. */
+    async call(method, params, { quick = false } = {}) {
+      const [r] = await run([[method, params]], { size: 1, quick, maxTries: quick ? 2 : undefined });
+      return r;
+    },
+    /** nonNull: a null result counts as a failed try (block we know exists). */
+    async batch(list, { size = 50, nonNull = false, quick = false } = {}) {
+      const out = [];
+      for (let i = 0; i < list.length; i += size) {
+        const part = list.slice(i, i + size);
+        out.push(...await run(part, { size, nonNull, quick, maxTries: quick ? 2 : undefined }));
+      }
+      return out;
+    },
+    stats: () => ({ requests: state.requests, fallbackUsed: state.fallbackUsed, byMethod: { ...state.byMethod }, throttles: state.throttles, rate: state.rate }),
+    concurrency: () => state.maxInFlight,
+    pause: sleep,
+  };
+}