@bolloon/bolloon-agent 0.5.2 → 0.5.3

package/README.md

@@ -96,11 +96,11 @@ npm start
 不想在本机装 Node 与依赖, 可以直接跑容器 (多阶段镜像 · 非 root 用户 uid 1001 · 状态全部落在卷里):
 
 ```bash
-docker build -t bolloon-agent:0.5.1 .
+docker build -t bolloon-agent:local .
 docker run -d --name bolloon-agent \
   -p 127.0.0.1:54188:54188 \
   -v bolloon-data:/home/bolloon/.bolloon \
-  bolloon-agent:0.5.1 --web
+  bolloon-agent:local --web
 # → http://127.0.0.1:54188
 
 docker compose up -d                            # 同上的 compose 写法
@@ -167,9 +167,9 @@ Requires Node.js ≥ 18 and an LLM API key (`OPENAI_API_KEY` or `DEEPSEEK_API_KE
 Run it in a container instead (multi-stage image, non-root user, state in a volume):
 
 ```bash
-docker build -t bolloon-agent:0.5.1 .
+docker build -t bolloon-agent:local .
 docker run -d --name bolloon-agent -p 127.0.0.1:54188:54188 \
-  -v bolloon-data:/home/bolloon/.bolloon bolloon-agent:0.5.1 --web
+  -v bolloon-data:/home/bolloon/.bolloon bolloon-agent:local --web
 ```
 
 Copy `.env.example` to `.env.docker` (gitignored) for keys, or mount your `llm-config.json` read-only

package/dist/agents/chain/transfer-classify.js

@@ -0,0 +1,99 @@
+/**
+ * transfer-classify.ts — 转账索引的**纯**部分 (类型 + 分类 + 折算 + 汇总)
+ * =========================================================================
+ * 为什么单独一个文件: 这两半的**加载代价**完全不同 ——
+ *   · 本文件: 零依赖 (不 import ethers / 不发 RPC / 不读盘) ⇒ 公开页/快照构建可以**静态**引入;
+ *   · `transfer-index.ts`: 要 JSON-RPC provider (ethers) 与文件系统 ⇒ 只在**同步**路径上加载。
+ * 把纯函数放在这里, network-pulse 才不必为了 `formatUnits` 把 ethers 拖进网页进程。
+ *
+ * 分类口径 (leo 2026-09-29 实测拍板; **不许**只按"USDC 转到该地址"计数):
+ *   · `escrow_settlement`  from == escrow 合约 → 「escrow 退款/释放」(实测块 51685757 / 51686009
+ *                          两笔 +0.001 与那两笔 Disputed→Refunded **逐块对应**) —— 钱退回, **不是收入**;
+ *   · `self_transfer`      from ∈ 自己地址集 (可配 ownAddresses) → 「转入(非销售)」;
+ *   · `external_payment`   其余 → 「外部付款」(与卖方端点台账对上的加标「经 x402 流程」);
+ *   · `outbound`           关注地址**付出** → 不进「链上转入」计数。
+ */
+export const TRANSFER_INDEX_SCHEMA_VERSION = 1;
+/** Transfer(address indexed from, address indexed to, uint256 value) 的 topic0 */
+export const ERC20_TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+/** Base 主网 USDC (缺省 token; 也可由 chain.json 的 tokenAddress / env 覆盖) */
+export const USDC_BY_CHAIN = {
+    8453: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+    84532: '0x036cbd53842c5426634e7929541ec2318f3dcf7e',
+};
+/** 0x + 40 位十六进制 (地址形状; 与 explorer.ts 的同一套尺子) */
+export const TRANSFER_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+/** 原子单位 → 十进制字符串 (纯整数运算, 不经过浮点; 去掉末尾多余的 0) */
+export function formatUnits(atomic, decimals) {
+    const v = BigInt(typeof atomic === 'bigint' ? atomic : (String(atomic || '0').trim() || '0'));
+    const neg = v < 0n;
+    const abs = neg ? -v : v;
+    const d = Math.max(0, Math.floor(decimals));
+    const base = 10n ** BigInt(d);
+    const whole = (abs / base).toString();
+    const frac = (abs % base).toString().padStart(d, '0').replace(/0+$/, '');
+    const out = frac ? `${whole}.${frac}` : whole;
+    return neg ? `-${out}` : out;
+}
+/**
+ * 一条转账的**分类** (纯函数: 输入事实 + 配置, 输出分类)。
+ * 为什么在**读**的时候算而不是写索引时算: 分类规则 / 自己地址集是会变的
+ * (把 0xb4cb8009… 认成"自己钱包"之前, 它只是一个外部地址) ⇒ 历史行必须能被重新分类,
+ * 而不是把当时的判断固化进索引。索引里只存**链上事实** (from/to/value/块号)。
+ */
+export function classifyTransfer(e, cfg) {
+    const from = String(e.from || '').toLowerCase();
+    const to = String(e.to || '').toLowerCase();
+    const watch = new Set((cfg.watchAddresses || []).map((a) => String(a).toLowerCase()));
+    if (e.direction === 'out' || (watch.has(from) && !watch.has(to)))
+        return 'outbound';
+    const escrow = String(cfg.escrowAddress || '').toLowerCase();
+    if (escrow && from === escrow)
+        return 'escrow_settlement';
+    if ((cfg.ownAddresses || []).map((a) => String(a).toLowerCase()).includes(from))
+        return 'self_transfer';
+    return 'external_payment';
+}
+/** 已落盘转账索引 → 汇总 (纯函数; 不发网络、不读配置以外的东西) */
+export function summarizeTransfers(state, cfg) {
+    const live = (state.entries || []).filter((e) => !e.suspect);
+    const by_class = { escrow_settlement: 0, self_transfer: 0, external_payment: 0 };
+    const by_class_atomic = { escrow_settlement: '0', self_transfer: '0', external_payment: '0' };
+    let inbound = 0, inboundAtomic = 0n, outbound = 0, outboundAtomic = 0n, pending = 0;
+    for (const e of live) {
+        if (e.finality === 'observed')
+            pending++;
+        const v = BigInt(e.value || '0');
+        if (e.direction === 'out') {
+            outbound++;
+            outboundAtomic += v;
+            continue;
+        }
+        inbound++;
+        inboundAtomic += v;
+        const c = classifyTransfer(e, cfg);
+        if (c !== 'outbound') {
+            by_class[c]++;
+            by_class_atomic[c] = (BigInt(by_class_atomic[c]) + v).toString();
+        }
+    }
+    const decimals = Number.isInteger(state.tokenDecimals) ? state.tokenDecimals : (cfg.tokenDecimals ?? 6);
+    return {
+        configured: cfg.enabled !== false && !!((state.watchAddresses || cfg.watchAddresses || []).length),
+        reason: cfg.reason || '',
+        entries: live.length,
+        suspects: (state.entries || []).length - live.length,
+        inbound, inbound_atomic: inboundAtomic.toString(), inbound_display: formatUnits(inboundAtomic, decimals),
+        by_class, by_class_atomic,
+        outbound, outbound_atomic: outboundAtomic.toString(),
+        token_symbol: state.tokenSymbol || cfg.tokenSymbol || '',
+        token_decimals: decimals,
+        watch_addresses_count: (state.watchAddresses || cfg.watchAddresses || []).length,
+        own_addresses_count: (cfg.ownAddresses || []).length,
+        from_block: state.fromBlock,
+        last_synced_block: state.lastSyncedBlock,
+        last_synced_at: state.lastSyncedAt,
+        head_block: state.headBlock,
+        pending_observation: pending,
+    };
+}

package/dist/agents/chain/transfer-index.js

@@ -0,0 +1,354 @@
+/**
+ * transfer-index.ts — **关注地址集**内的 ERC-20 (USDC) 转账索引 (2026-09-29)
+ * =========================================================================
+ * 为什么需要它 (leo:「我要记录的是链上数据…网关要显示的是所有交互」):
+ *   旧索引只扫 AgentEscrow 合约日志 ⇒ 走**直付 (买方自己发 USDC 到 payTo)** 的收款
+ *   在链上**根本没有 escrow 事件** (x402 在链上没有自己的事件; 付款就是一笔普通 ERC-20
+ *   USDC 转账) ⇒ 「所有交互」在旧口径里是漏的。
+ *
+ * 干什么: 把 `tokenAddress` (缺省 = 本链 USDC) 上 **to ∈ 关注地址集 / from ∈ 关注地址集**
+ *   的 Transfer 日志扫进 `~/.bolloon/chain/transfers.json`, 让「链上转入」可核验
+ *   (每笔带 txHash / 块号 / 原子金额; from/to 只留在本机索引里, 不进公开快照)。
+ *
+ * 硬约束 (每条都能被验收脚本证伪):
+ *   ① 关注地址集来自**配置** (`~/.bolloon/chain.json` 的 `watchAddresses`), env
+ *      (`BOLLOON_WATCH_ADDRESSES`) 可覆盖 —— **不硬编码任何单个地址**;
+ *      没配 → 索引自称 `enabled:false` 且**不猜** (页面上这一格显示「未配置」, 不显示 0)。
+ *   ② 分页 eth_getLogs ≤ pageSize (默认 2000 —— 实测 mainnet.base.org 的 eth_getLogs
+ *      **单次上限 2000 块**, 3000/5000/10000 块窗口全被拒: `is limited to a 2,000 range`);
+ *      provider 报错就**对半拆**再试, 不静默漏页。
+ *   ③ 去重键 = `txHash:logIndex` (小写), 幂等重跑 0 重复。
+ *   ④ 起点 `fromBlock` 来自配置 (`transferScanFromBlock`), 缺省 = 链索引的 deploymentBlock
+ *      (即 Bolloon 在 Base 主网上的起点) —— **不是** 0, 也不是"最新块"(那会漏掉历史收款)。
+ *   ⑤ 重组: 每次同步**强制回扫**最后 `reorgDepth` (默认 32) 块, 用重扫结果**重写**该窗口内的
+ *      条目; 重扫后不再出现的键 → 标 `suspect` 并保留 (不静默丢弃)。
+ *   ⑥ 本模块**只读链** (eth_getLogs / eth_getBlockByNumber), 不签名、不发交易、不碰私钥。
+ *
+ * 与 escrow 索引的关系: **互不影响**。escrow 索引 (`chain/index.json`) 的身份门 / 重组逻辑
+ *   一行未动 —— 本模块用**另一个文件** (`chain/transfers.json`) 记自己的游标, 只做增量 + 回扫。
+ *
+ * 纯函数 (分类 / 折算 / 汇总) 在 `transfer-classify.ts` —— 这里只做 RPC + 落盘, 并把纯函数**转出**
+ * (老调用方可以只 import 本文件)。
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createJsonRpcProvider } from './escrow-client.js';
+import { bolloonHome, chainConfigPath, DEFAULT_CONFIRMATIONS } from './chain-config.js';
+import { TRANSFER_INDEX_SCHEMA_VERSION, ERC20_TRANSFER_TOPIC, USDC_BY_CHAIN, TRANSFER_ADDRESS_RE, } from './transfer-classify.js';
+export * from './transfer-classify.js';
+export function transferIndexPath(home) {
+    return path.join(bolloonHome(home), 'chain', 'transfers.json');
+}
+/** 读本机 chain.json (读不出 → 空对象; 不抛) */
+function readChainJson(home) {
+    try {
+        return JSON.parse(fs.readFileSync(chainConfigPath(home), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function resolveAddrSet(raw, source) {
+    const addresses = [];
+    const rejected = [];
+    for (const a of raw) {
+        if (TRANSFER_ADDRESS_RE.test(String(a)))
+            addresses.push(String(a).toLowerCase());
+        else
+            rejected.push(String(a));
+    }
+    return { addresses: Array.from(new Set(addresses)).sort(), source, rejected };
+}
+/**
+ * 关注地址集解析 (**唯一实现**): env `BOLLOON_WATCH_ADDRESSES` (逗号/空白分隔) 优先,
+ * 其次 `~/.bolloon/chain.json` 的 `watchAddresses[]`。非法地址**全部丢弃并如实说明**
+ * (不"猜一个像的" —— 地址猜错会把别人的流水索引成本节点的)。
+ */
+export function resolveWatchAddresses(home, env = process.env) {
+    const envRaw = String(env.BOLLOON_WATCH_ADDRESSES || '').trim();
+    if (envRaw)
+        return resolveAddrSet(envRaw.split(/[\s,]+/).filter(Boolean), 'env BOLLOON_WATCH_ADDRESSES');
+    const file = readChainJson(home);
+    const arr = Array.isArray(file?.watchAddresses) ? file.watchAddresses : [];
+    return resolveAddrSet(arr.map((x) => String(x)), arr.length ? `${chainConfigPath(home)} .watchAddresses[]` : '未配置');
+}
+/** 自己地址集解析 (env `BOLLOON_OWN_ADDRESSES` 优先, 其次 chain.json `ownAddresses[]`; 非法全丢) */
+export function resolveOwnAddresses(home, env = process.env) {
+    const envRaw = String(env.BOLLOON_OWN_ADDRESSES || '').trim();
+    if (envRaw)
+        return resolveAddrSet(envRaw.split(/[\s,]+/).filter(Boolean), 'env BOLLOON_OWN_ADDRESSES');
+    const file = readChainJson(home);
+    const arr = Array.isArray(file?.ownAddresses) ? file.ownAddresses : [];
+    return resolveAddrSet(arr.map((x) => String(x)), arr.length ? `${chainConfigPath(home)} .ownAddresses[]` : '未配置');
+}
+/** 转账索引的配置 (纯读配置, 不发 RPC) */
+export function readTransferWatchConfig(home, env = process.env) {
+    const file = readChainJson(home);
+    const chainId = Number.isInteger(Number(file?.chainId)) ? Number(file.chainId) : 0;
+    const networkName = String(file?.networkName || 'unknown');
+    const rpcUrl = String(env.BOLLOON_CHAIN_RPC_URL || file?.rpcUrl || '');
+    const tokenAddress = String(env.BOLLOON_TRANSFER_TOKEN || file?.tokenAddress || USDC_BY_CHAIN[chainId] || '').toLowerCase();
+    const tokenDecimals = Number.isInteger(Number(file?.tokenDecimals)) ? Number(file.tokenDecimals) : 6;
+    const { addresses, source, rejected } = resolveWatchAddresses(home, env);
+    const own = resolveOwnAddresses(home, env);
+    const escrowAddress = String(env.BOLLOON_ESCROW_ADDRESS || file?.escrowAddress || '').toLowerCase();
+    const envPage = Number(env.BOLLOON_INDEX_PAGE_SIZE);
+    const pageSize = Math.max(1, Math.floor(Number.isInteger(envPage) && envPage > 0 ? envPage : 2000));
+    const envDepth = Number(env.BOLLOON_INDEX_REORG_DEPTH);
+    const reorgDepth = Math.max(1, Math.floor(Number.isInteger(envDepth) && envDepth > 0 ? envDepth : 32));
+    const cfgFrom = Number(env.BOLLOON_TRANSFER_SCAN_FROM || file?.transferScanFromBlock);
+    const fromConfigured = Number.isInteger(cfgFrom) && cfgFrom > 0;
+    const missing = [];
+    if (!TRANSFER_ADDRESS_RE.test(tokenAddress))
+        missing.push('tokenAddress');
+    if (!addresses.length)
+        missing.push(rejected.length ? `关注地址集全部非法: ${rejected.join(', ')}` : '关注地址集 (watchAddresses)');
+    if (!rpcUrl)
+        missing.push('rpcUrl');
+    return {
+        enabled: missing.length === 0,
+        reason: missing.length ? `未配置/未启用: 缺 ${missing.join(' · ')} (来源: ${source})` : `关注地址集 ${addresses.length} 个 (${source})`,
+        chainId, networkName, rpcUrl,
+        tokenAddress,
+        tokenSymbol: tokenAddress === USDC_BY_CHAIN[8453] || tokenAddress === USDC_BY_CHAIN[84532] ? 'USDC' : 'ERC20',
+        tokenDecimals,
+        watchAddresses: addresses,
+        ownAddresses: own.addresses,
+        escrowAddress,
+        // 起点: 显式配置优先; 否则留给调用方用 escrow deploymentBlock 填 (见 syncTransfers 的 opts.fromBlock)
+        fromBlock: fromConfigured ? cfgFrom : 0,
+        fromBlockSource: fromConfigured ? '配置 transferScanFromBlock' : '未配置 → 由调用方给 (缺省 = escrow 部署块)',
+        confirmations: DEFAULT_CONFIRMATIONS,
+        pageSize, reorgDepth,
+    };
+}
+function emptyIndex(cfg, fromBlock) {
+    return {
+        schemaVersion: TRANSFER_INDEX_SCHEMA_VERSION,
+        chainId: cfg.chainId, networkName: cfg.networkName,
+        tokenAddress: cfg.tokenAddress, tokenSymbol: cfg.tokenSymbol, tokenDecimals: cfg.tokenDecimals,
+        watchAddresses: cfg.watchAddresses,
+        fromBlock,
+        lastSyncedBlock: fromBlock - 1,
+        lastSyncedAt: null, headBlock: null, headBlockHash: null,
+        pageSize: cfg.pageSize, reorgDepth: cfg.reorgDepth,
+        entries: [], runs: [], updatedAt: Date.now(),
+    };
+}
+export function readTransferIndex(home) {
+    const cfg = readTransferWatchConfig(home);
+    const p = transferIndexPath(home);
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return emptyIndex(cfg, cfg.fromBlock || 0);
+    }
+    if (!raw || typeof raw !== 'object' || !Array.isArray(raw.entries))
+        return emptyIndex(cfg, cfg.fromBlock || 0);
+    const dedup = new Map();
+    for (const e of raw.entries) {
+        const key = String(e?.key || '');
+        if (!key || dedup.has(key))
+            continue; // 坏文件里的重复键不许渗进来
+        dedup.set(key, e);
+    }
+    const entries = Array.from(dedup.values()).sort((a, b) => a.blockNumber - b.blockNumber || a.logIndex - b.logIndex);
+    return {
+        ...emptyIndex(cfg, Number.isInteger(raw.fromBlock) ? Number(raw.fromBlock) : cfg.fromBlock),
+        chainId: Number(raw.chainId) || cfg.chainId,
+        networkName: String(raw.networkName || cfg.networkName),
+        tokenAddress: String(raw.tokenAddress || cfg.tokenAddress).toLowerCase(),
+        tokenSymbol: String(raw.tokenSymbol || cfg.tokenSymbol),
+        tokenDecimals: Number.isInteger(raw.tokenDecimals) ? Number(raw.tokenDecimals) : cfg.tokenDecimals,
+        watchAddresses: Array.isArray(raw.watchAddresses) ? raw.watchAddresses.map((a) => String(a).toLowerCase()) : cfg.watchAddresses,
+        fromBlock: Number.isInteger(raw.fromBlock) ? Number(raw.fromBlock) : cfg.fromBlock,
+        lastSyncedBlock: Number.isInteger(raw.lastSyncedBlock) ? Number(raw.lastSyncedBlock) : cfg.fromBlock - 1,
+        lastSyncedAt: raw.lastSyncedAt ?? null,
+        headBlock: Number.isInteger(raw.headBlock) ? Number(raw.headBlock) : null,
+        headBlockHash: raw.headBlockHash ?? null,
+        pageSize: Number(raw.pageSize) || cfg.pageSize,
+        reorgDepth: Number(raw.reorgDepth) || cfg.reorgDepth,
+        entries,
+        runs: Array.isArray(raw.runs) ? raw.runs.slice(-50) : [],
+        updatedAt: Number(raw.updatedAt) || Date.now(),
+    };
+}
+/** 原子写 (tmp + rename) */
+export async function writeTransferIndex(home, state) {
+    const p = transferIndexPath(home);
+    await fs.promises.mkdir(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp-${process.pid}`;
+    state.updatedAt = Date.now();
+    state.runs = state.runs.slice(-50);
+    await fs.promises.writeFile(tmp, JSON.stringify(state, null, 2), 'utf8');
+    await fs.promises.rename(tmp, p);
+    return p;
+}
+const topicForAddress = (a) => '0x' + a.replace(/^0x/, '').padStart(64, '0');
+/**
+ * 从原始日志取 logIndex: **原始 JSON-RPC 里叫 `logIndex`, ethers v6 的 Log 对象里叫 `index`**
+ * (两个都要认 —— 只认一个的话 ethers 路径会全部拿到 undefined, 索引里全是 -1, 行会被当成非法丢弃:
+ * 2026-09-29 实测踩过, 4 笔转入一笔都没出行)。同一套兼容在 chain-indexer.ts 的 logIndexOf 里。
+ */
+function logIndexOfRaw(raw) {
+    const n = Number(raw?.logIndex ?? raw?.index);
+    return Number.isInteger(n) && n >= 0 ? n : -1;
+}
+/**
+ * 增量同步 (**唯一写入口**):
+ *   scanFrom = min(强制回扫窗口起点, lastSyncedBlock + 1); fromBlock 覆盖时取更小的那个 (补扫)
+ *   scanTo   = 当前链 head
+ * 每次同步都回扫最后 `reorgDepth` 块并把该窗口内的条目**重写**; 重扫里消失的键标 suspect 保留。
+ */
+export async function syncTransfers(opts = {}) {
+    const cfg = opts.config || readTransferWatchConfig(opts.home);
+    const log = opts.log || (() => { });
+    if (!cfg.enabled)
+        return { ok: false, skipped: cfg.reason, configuration: cfg };
+    const fromBlock = Math.max(0, Math.floor(opts.fromBlock ?? cfg.fromBlock));
+    if (!Number.isInteger(fromBlock) || fromBlock <= 0) {
+        return { ok: false, skipped: '缺扫描起点: 配置里没有 transferScanFromBlock, 调用方也没给 fromBlock (不猜 0 —— 从 0 开始扫会白扫几十万块)', configuration: cfg };
+    }
+    const t0 = Date.now();
+    const now = opts.now ?? Date.now();
+    const state = readTransferIndex(opts.home);
+    // 起点只在**首次**或**显式补扫**时生效 (不许被后续增量悄悄改大 —— 那会漏历史收款)
+    const effectiveFrom = state.entries.length === 0 && state.lastSyncedAt == null ? fromBlock : Math.min(fromBlock, state.fromBlock || fromBlock);
+    const provider = opts.provider || createJsonRpcProvider(cfg.rpcUrl);
+    const headNum = await provider.getBlockNumber();
+    const headBlock = await provider.getBlock(headNum);
+    if (!headBlock)
+        throw new Error(`读不到 head 区块 ${headNum} (RPC 异常)`);
+    const rewindFrom = Math.max(effectiveFrom, state.lastSyncedBlock - cfg.reorgDepth + 1);
+    const incremental = state.lastSyncedBlock + 1;
+    const scanFrom = Math.max(effectiveFrom, Math.min(incremental, rewindFrom));
+    if (scanFrom > headNum) {
+        return { ok: true, skipped: `已是最新 (lastSyncedBlock=${state.lastSyncedBlock} >= head=${headNum})`, configuration: cfg, lastSyncedBlock: state.lastSyncedBlock, headBlock: headNum };
+    }
+    // 逐页扫: 每个关注地址两条过滤 (from 侧 / to 侧)
+    const found = new Map();
+    let pages = 0;
+    const tryGet = async (filter, a, b) => {
+        try {
+            return await provider.getLogs({ ...filter, fromBlock: a, toBlock: b });
+        }
+        catch (e) {
+            const msg = String(e?.shortMessage || e?.message || e);
+            if (a === b)
+                throw e;
+            log(`  ⚠ eth_getLogs(${a}-${b}) 失败 (${msg.slice(0, 90)}) → 对半拆`);
+            const mid = Math.floor((a + b) / 2);
+            const left = await tryGet(filter, a, mid);
+            const right = await tryGet(filter, mid + 1, b);
+            return [...left, ...right];
+        }
+    };
+    const filters = [];
+    for (const w of cfg.watchAddresses) {
+        filters.push({ address: cfg.tokenAddress, topics: [ERC20_TRANSFER_TOPIC, topicForAddress(w)] }); // from 侧
+        filters.push({ address: cfg.tokenAddress, topics: [ERC20_TRANSFER_TOPIC, null, topicForAddress(w)] }); // to 侧
+    }
+    const watch = new Set(cfg.watchAddresses);
+    for (let a = scanFrom; a <= headNum; a += cfg.pageSize) {
+        const b = Math.min(a + cfg.pageSize - 1, headNum);
+        for (const f of filters) {
+            const logs = await tryGet(f, a, b);
+            for (const l of logs || [])
+                found.set(`${String(l.transactionHash).toLowerCase()}:${logIndexOfRaw(l)}`, l);
+        }
+        pages++;
+        log(`  · 扫 ${a}-${b} (${pages} 页, 命中 ${found.size} 条)`);
+    }
+    // 重扫窗口内的旧条目先摘出去 (下面按重扫结果重写)
+    const inWindow = (n) => n >= scanFrom && n <= headNum;
+    const kept = state.entries.filter((e) => !inWindow(e.blockNumber));
+    const removed = state.entries.filter((e) => inWindow(e.blockNumber));
+    const byKey = new Map(kept.map((e) => [e.key, e]));
+    let inserted = 0, deduped = 0, rewritten = 0;
+    const finalityOf = (conf) => (conf >= cfg.confirmations.finalized ? 'finalized' : (conf >= cfg.confirmations.confirmed ? 'confirmed' : 'observed'));
+    for (const [key, l] of found) {
+        const prev = removed.find((e) => e.key === key);
+        const topics = l.topics || [];
+        const from = '0x' + String(topics[1] || '').slice(-40);
+        const to = '0x' + String(topics[2] || '').slice(-40);
+        const block = Number(l.blockNumber);
+        const value = BigInt(l.data || '0x0').toString();
+        const direction = watch.has(to.toLowerCase()) ? 'in' : 'out';
+        const conf = Math.max(0, headNum - block + 1);
+        const entry = {
+            key,
+            blockNumber: block,
+            blockHash: String(l.blockHash || ''),
+            txHash: String(l.transactionHash).toLowerCase(),
+            txIndex: Number.isInteger(Number(l.transactionIndex)) ? Number(l.transactionIndex) : -1,
+            logIndex: logIndexOfRaw(l),
+            address: String(l.address || '').toLowerCase(),
+            from: from.toLowerCase(),
+            to: to.toLowerCase(),
+            value, direction,
+            confirmations: conf,
+            finality: finalityOf(conf),
+            firstSeenAt: prev?.firstSeenAt ?? now,
+        };
+        if (prev) {
+            rewritten++;
+            removed.splice(removed.indexOf(prev), 1);
+        }
+        else if (byKey.has(key))
+            deduped++;
+        else
+            inserted++;
+        byKey.set(key, entry);
+    }
+    // 重扫窗口内**不再出现**的旧条目: 标 suspect 保留 (不静默丢弃)
+    let markedSuspect = 0;
+    for (const e of removed) {
+        e.suspect = true;
+        e.suspectReason = `重扫 [${scanFrom}, ${headNum}] 后该日志不再出现 (链回滚 / 重组)`;
+        markedSuspect++;
+        byKey.set(e.key, e);
+    }
+    // 更新窗口外条目的确认数 (head 在长)
+    const entries = Array.from(byKey.values()).sort((x, y) => x.blockNumber - y.blockNumber || x.logIndex - y.logIndex);
+    for (const e of entries) {
+        if (inWindow(e.blockNumber))
+            continue;
+        e.confirmations = Math.max(0, headNum - e.blockNumber + 1);
+        e.finality = (e.suspect ? 'observed' : finalityOf(e.confirmations));
+    }
+    const nextState = {
+        ...state,
+        chainId: cfg.chainId || state.chainId,
+        networkName: cfg.networkName || state.networkName,
+        tokenAddress: cfg.tokenAddress, tokenSymbol: cfg.tokenSymbol, tokenDecimals: cfg.tokenDecimals,
+        watchAddresses: cfg.watchAddresses,
+        fromBlock: effectiveFrom,
+        lastSyncedBlock: Math.max(state.lastSyncedBlock, headNum),
+        lastSyncedAt: now,
+        headBlock: headNum,
+        headBlockHash: String(headBlock.hash || ''),
+        pageSize: cfg.pageSize, reorgDepth: cfg.reorgDepth,
+        entries,
+        runs: [...state.runs, {
+                at: now,
+                mode: state.lastSyncedAt == null || effectiveFrom < state.fromBlock ? 'backfill' : 'sync',
+                scanFrom, scanTo: headNum, pages,
+                blocksScanned: headNum - scanFrom + 1,
+                logsFound: found.size, inserted, deduped, rewritten, markedSuspect,
+                headBlock: headNum, durationMs: Date.now() - t0,
+            }],
+    };
+    const indexPath = await writeTransferIndex(opts.home, nextState);
+    const live = entries.filter((e) => !e.suspect && e.direction === 'in');
+    const inWindowNew = live.filter((e) => inWindow(e.blockNumber));
+    return {
+        ok: true, indexPath, configuration: cfg,
+        scanFrom, scanTo: headNum, pages,
+        logsFound: found.size, inserted, deduped, rewritten, markedSuspect,
+        entries: entries.length, lastSyncedBlock: nextState.lastSyncedBlock, headBlock: headNum,
+        received: inWindowNew.length,
+        receivedAtomic: inWindowNew.reduce((n, e) => n + BigInt(e.value), 0n).toString(),
+    };
+}