@bolloon/bolloon-agent 0.4.31 → 0.4.33

package/dist/agents/chain/chain-settlement.js

@@ -0,0 +1,284 @@
+/**
+ * chain-settlement.ts — 「链上到底结算了没有」的唯一判定 (P3, 修 F5)
+ *
+ * 真问题 F5 (原样引):
+ *   `chainSettled = !!txHash` —— 拿到 txHash 就判链上结算, 从不读 receipt/事件/确认数。
+ *
+ * 本文件的规矩 (硬规则, 不许放宽):
+ *   ① 只有 receipt.status == 1 **且** 确认数 >= 配置门槛 **且** 事件对得上 → 才 `chainSettled: true`
+ *   ② 拿不到 RPC / receipt 读不到 / 确认数不够 → 一律如实回「未结算 / 不确定」, `chainSettled: false`
+ *   ③ 已经被认过的交易「不见了」或「换了块」→ 判重组 (`reorged`), **不是**已结算
+ *   ④ `local-dev` 永远进不来这里 (这里只认链上事实)
+ *
+ * 判定只看链上原始事实 (receipt / logs / 合约状态), 不看谁说的。
+ */
+import { Interface } from 'ethers';
+import { EscrowClient, } from './escrow-client.js';
+import { loadChainConfig, DEFAULT_CONFIRMATIONS, } from './chain-config.js';
+/** ERC20 Transfer 事件 topic0 */
+export const ERC20_TRANSFER_TOPIC0 = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+const ERC20_IFACE = new Interface(['event Transfer(address indexed from, address indexed to, uint256 value)']);
+const ZERO32 = '0x0000000000000000000000000000000000000000000000000000000000000000';
+function base(partial) {
+    return {
+        chainSettled: false,
+        confirmationsRequired: 0,
+        requiredGate: 'confirmed',
+        rpcAvailable: true,
+        checkedAt: Date.now(),
+        evidence: {},
+        ...partial,
+    };
+}
+/**
+ * ★ 唯一判定入口。
+ * 只用链上原始事实; 任何一步读不到 → `chainSettled: false` + 说明为什么。
+ */
+export async function verifyChainSettlement(client, opts) {
+    const cfgConf = opts.confirmations || client.confirmations || DEFAULT_CONFIRMATIONS;
+    const gate = opts.gate || 'confirmed';
+    const required = gate === 'finalized' ? cfgConf.finalized : cfgConf.confirmed;
+    const expect = opts.expect || { kind: 'none' };
+    const txHash = opts.txHash ? String(opts.txHash) : '';
+    // ① 没 txHash: 从来没发过链上交易
+    if (!txHash) {
+        return base({
+            status: 'not_attempted',
+            reason: '没有 txHash: 这不是一笔链上交易, 不能判链上结算',
+            confirmationsRequired: required, requiredGate: gate,
+        });
+    }
+    // ② receipt (读不到 = rpcAvailable false, 不是"没结算")
+    let rc;
+    try {
+        rc = await client.getReceipt(txHash);
+    }
+    catch (e) {
+        return base({
+            status: 'unknown',
+            reason: `读 receipt 失败 (RPC 不可用?): ${String(e?.message || e).slice(0, 160)} —— 付款状态未知, 不等于失败, 也不等于已结算`,
+            txHash, confirmationsRequired: required, requiredGate: gate,
+            rpcAvailable: false, evidence: { receiptError: String(e?.message || e).slice(0, 200) },
+        });
+    }
+    if (!rc) {
+        // 链上没有这笔了 —— 如果之前认过它, 那就是重组
+        if (opts.recorded && opts.recorded.blockNumber != null) {
+            return base({
+                status: 'reorged',
+                reason: `曾记在块 ${opts.recorded.blockNumber} 的交易现在链上查不到 (重组?), 不可信, 不能当已结算`,
+                txHash, confirmationsRequired: required, requiredGate: gate,
+                eventMatched: null, evidence: { recorded: opts.recorded },
+            });
+        }
+        return base({
+            status: 'unknown',
+            reason: 'receipt 为空: 交易还没被打包 (或在内存池里) —— 未结算, 也不等于失败',
+            txHash, confirmationsRequired: required, requiredGate: gate,
+            evidence: { receipt: null },
+        });
+    }
+    const blockNumber = Number(rc.blockNumber);
+    // ③ latestBlock (数确认数要用; 读不到 = 不知道)
+    let latestBlock;
+    try {
+        latestBlock = await client.getLatestBlockNumber();
+    }
+    catch (e) {
+        return base({
+            status: 'unknown',
+            reason: `读不到最新块高, 无法数确认数: ${String(e?.message || e).slice(0, 160)}`,
+            txHash, blockNumber, confirmationsRequired: required, requiredGate: gate,
+            rpcAvailable: false, evidence: { receiptStatus: Number(rc.status) },
+        });
+    }
+    const confirmations = latestBlock - blockNumber + 1;
+    // ④ receipt status: 0 = 明确失败, 钱一定没动
+    if (Number(rc.status) !== 1) {
+        return base({
+            status: 'reverted',
+            reason: `receipt.status = ${Number(rc.status)}: 交易回滚了, 链上没结算 (钱没动)`,
+            txHash, blockNumber, confirmations, latestBlock,
+            confirmationsRequired: required, requiredGate: gate,
+            evidence: { receiptStatus: Number(rc.status) },
+        });
+    }
+    // ⑤ 重组检测: 同一 txHash 出现在**另一个**块里
+    if (opts.recorded && opts.recorded.blockNumber != null && Number(opts.recorded.blockNumber) !== blockNumber) {
+        return base({
+            status: 'reorged',
+            reason: `重组: 同一 txHash 上次记在块 ${opts.recorded.blockNumber}, 现在是块 ${blockNumber} —— 链被重排过, 旧确认不可信`,
+            txHash, blockNumber, confirmations, latestBlock,
+            confirmationsRequired: required, requiredGate: gate,
+            evidence: { recordedBlock: opts.recorded.blockNumber, currentBlock: blockNumber },
+        });
+    }
+    // ⑥ 事件核对 (按预期类型)
+    const logs = (rc.logs || []).map((l) => ({ address: l.address, topics: l.topics, data: l.data, blockNumber: l.blockNumber, index: l.index }));
+    let eventMatched = null;
+    let matchedEvent;
+    let escrowState = null;
+    const evEvidence = { logCount: logs.length };
+    if (expect.kind === 'escrow') {
+        if (!expect.taskKey) {
+            return base({
+                status: 'event_mismatch',
+                reason: '要求核对 escrow 事件但没给 taskKey → 核不了, 不敢判已结算',
+                txHash, blockNumber, confirmations, latestBlock,
+                confirmationsRequired: required, requiredGate: gate, eventMatched: false,
+            });
+        }
+        const decoded = client.decodeV2Events({ txHash, blockNumber, gasUsed: null, status: 1, reverted: false, logs, broadcast: true });
+        const wanted = expect.eventName ? decoded.filter((d) => d.name === expect.eventName) : decoded;
+        const hit = wanted.find((d) => {
+            const tk = String(d.args.taskKey || '').toLowerCase();
+            if (tk !== String(expect.taskKey).toLowerCase())
+                return false;
+            if (expect.resultHash) {
+                const rh = String(d.args.resultHash || '').toLowerCase();
+                if (rh !== String(expect.resultHash).toLowerCase())
+                    return false;
+            }
+            return true;
+        });
+        eventMatched = !!hit;
+        matchedEvent = hit?.name;
+        evEvidence.decodedEvents = decoded.map((d) => d.name);
+        evEvidence.expectedTaskKey = expect.taskKey;
+        // 读合约里这条 escrow 的真实状态
+        try {
+            const e = await client.getEscrow(expect.taskKey);
+            escrowState = e ? e.stateName : null;
+            evEvidence.escrowPresent = !!e;
+            if (e)
+                evEvidence.escrowState = e.stateName;
+        }
+        catch (e) {
+            evEvidence.escrowReadError = String(e?.message || e).slice(0, 160);
+        }
+        if (!hit) {
+            return base({
+                status: 'event_mismatch',
+                reason: `receipt 里有 ${decoded.length} 条本合约事件, 但没有一条 taskKey=${expect.taskKey}` +
+                    (expect.eventName ? ` 且事件=${expect.eventName}` : '') +
+                    (expect.resultHash ? ` 且 resultHash=${expect.resultHash}` : '') + ' —— 这不是我们要的那笔, 不能当已结算',
+                txHash, blockNumber, confirmations, latestBlock,
+                confirmationsRequired: required, requiredGate: gate,
+                taskKey: expect.taskKey, resultHash: expect.resultHash,
+                eventMatched, matchedEvent, escrowState, evidence: evEvidence,
+            });
+        }
+        if (expect.expectEscrowState && escrowState !== expect.expectEscrowState) {
+            return base({
+                status: 'event_mismatch',
+                reason: `事件对得上但合约状态是 ${escrowState ?? '(读不到)'}, 期望 ${expect.expectEscrowState}`,
+                txHash, blockNumber, confirmations, latestBlock,
+                confirmationsRequired: required, requiredGate: gate,
+                taskKey: expect.taskKey, eventMatched, matchedEvent, escrowState, evidence: evEvidence,
+            });
+        }
+    }
+    else if (expect.kind === 'erc20_transfer') {
+        if (!expect.tokenAddress) {
+            return base({
+                status: 'unknown',
+                reason: '要核对 ERC20 Transfer 但没给 tokenAddress → 核不了, 不能判已结算',
+                txHash, blockNumber, confirmations, latestBlock,
+                confirmationsRequired: required, requiredGate: gate, eventMatched: null,
+            });
+        }
+        const transfers = logs.filter((l) => String(l.address).toLowerCase() === String(expect.tokenAddress).toLowerCase() &&
+            String(l.topics?.[0] || '').toLowerCase() === ERC20_TRANSFER_TOPIC0);
+        const match = transfers.find((l) => {
+            try {
+                const p = ERC20_IFACE.parseLog({ topics: [...l.topics], data: l.data });
+                if (!p)
+                    return false;
+                const from = String(p.args.from).toLowerCase();
+                const to = String(p.args.to).toLowerCase();
+                const value = BigInt(p.args.value);
+                if (expect.to && to !== String(expect.to).toLowerCase())
+                    return false;
+                if (expect.from && from !== String(expect.from).toLowerCase())
+                    return false;
+                if (expect.minAmount != null && value < expect.minAmount)
+                    return false;
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        eventMatched = !!match;
+        matchedEvent = match ? 'Transfer' : undefined;
+        evEvidence.transferLogs = transfers.length;
+        if (!match) {
+            return base({
+                status: 'event_mismatch',
+                reason: `receipt 里没有匹配的 ERC20 Transfer (token=${expect.tokenAddress}, 收了 ${transfers.length} 条 Transfer) —— 不是这笔付款, 不能当已结算`,
+                txHash, blockNumber, confirmations, latestBlock,
+                confirmationsRequired: required, requiredGate: gate, eventMatched, evidence: evEvidence,
+            });
+        }
+    }
+    else {
+        eventMatched = null; // 没要求核对事件
+    }
+    // ⑦ 确认数门槛: 不够 → pending (明确"还没到", 不是"已结算")
+    if (confirmations < required) {
+        return base({
+            status: 'pending',
+            reason: `确认数 ${confirmations} < 门槛 ${required} (${gate}) → 还没到可以判结算的程度`,
+            txHash, blockNumber, confirmations, latestBlock,
+            confirmationsRequired: required, requiredGate: gate,
+            taskKey: expect.taskKey, resultHash: expect.resultHash,
+            eventMatched, matchedEvent, escrowState, evidence: evEvidence,
+        });
+    }
+    // ⑧ 全过 → 结算成立
+    const status = confirmations >= cfgConf.finalized ? 'finalized' : 'confirmed';
+    return base({
+        chainSettled: true,
+        status,
+        reason: `receipt.status=1, 确认数 ${confirmations} >= ${required} (${gate})` +
+            (matchedEvent ? `, 事件 ${matchedEvent} 对得上` : '') + ` → 链上结算成立`,
+        txHash, blockNumber, confirmations, latestBlock,
+        confirmationsRequired: required, requiredGate: gate,
+        taskKey: expect.taskKey, resultHash: expect.resultHash,
+        eventMatched, matchedEvent, escrowState, evidence: evEvidence,
+    });
+}
+/** 用现成 client 造验证器 */
+export function createChainSettlementVerifier(client, defaults = {}) {
+    return (req) => verifyChainSettlement(client, { ...req, gate: req.gate || defaults.gate || 'confirmed' });
+}
+/**
+ * 缺省验证器: 用本机配置 (env → ~/.bolloon/chain.json → 报错) 造 client。
+ * 配置取不到 → **不抛** (付款路径不能被配置问题炸掉), 而是返回一个永远
+ * `chainSettled: false` + `config_unavailable` 的诚实判定:
+ *   「我没法验证 → 不能宣称链上已验证」。
+ */
+export function createDefaultChainSettlementVerifier(opts = {}) {
+    let client = null;
+    let loadError = null;
+    try {
+        const cfg = loadChainConfig({ home: opts.home, env: opts.env });
+        client = opts.clientFactory ? opts.clientFactory(cfg) : new EscrowClient({ config: cfg });
+    }
+    catch (e) {
+        loadError = String(e?.message || e).slice(0, 300);
+    }
+    if (!client) {
+        const err = loadError;
+        return async (req) => base({
+            status: 'config_unavailable',
+            reason: `链配置取不到, 无法做真链验证 → 不能判链上结算: ${err}`,
+            txHash: req.txHash,
+            confirmationsRequired: 0, requiredGate: req.gate || 'confirmed',
+            rpcAvailable: false,
+            taskKey: req.expect?.taskKey,
+            evidence: { configError: err },
+        });
+    }
+    return createChainSettlementVerifier(client, { gate: opts.gate });
+}

package/dist/agents/chain/chain-state-store.js

@@ -0,0 +1,245 @@
+/**
+ * chain-state-store.ts — 链上状态的持久化 / 重启恢复 / 重组对账 (P3, ④)
+ *
+ * 为什么必须有:
+ *   进程会被杀, 会重启, 会被 rollback。重启后必须能回答:
+ *     「哪些交易已上链 / 待确认 / 已确认 / 被重组」—— 而不是靠内存里的对象猜。
+ *
+ * 落盘位置: `~/.bolloon/chain/chain-state.json` (原子写: tmp + rename)。
+ * 每条记录必须带的**关键状态**:
+ *   链上 escrow 地址 · txHash · taskKey · 确认数 · 最后检查块 · 判定状态 · 是否不可信
+ *
+ * 重组的两条检出路径 (都**不**静默当已结算):
+ *   ① 同一 txHash 出现在另一个块号 (或链上查不到了) → `reorged` + suspect=true
+ *   ② 之前核上的事件在链上"消失" (logs 里没了) → `event_mismatch` + suspect=true
+ *
+ * 本模块只负责"记"和"对账", 判定本身仍只由 chain-settlement.ts 给。
+ */
+import * as fs from 'fs';
+import * as fsp from 'fs/promises';
+import * as path from 'path';
+import { bolloonHome } from './chain-config.js';
+import { verifyChainSettlement } from './chain-settlement.js';
+export const CHAIN_STATE_SCHEMA_VERSION = 1;
+/**
+ * ★ 对账之后「仍然已结算」的 requestId 集合 = 本轮重算为 confirmed/finalized 的
+ * **加上** 已 finalized 被按设计跳过的。
+ *
+ * 存在的理由: `skipFinalized` 是省 RPC 的优化, 但它的副作用是让 `confirmed` 少了人 ——
+ * 用它来判断「这条还没对账 / 没结算」就会得出**错的**结论。这个函数把两种事实合起来,
+ * 让「跳过」不可能被误读成「没结算」。
+ */
+export function reconciledSettledIds(report) {
+    return Array.from(new Set([
+        ...report.confirmed.map((r) => r.requestId),
+        ...report.skippedFinalized.map((r) => r.requestId),
+    ]));
+}
+export function chainStateDir(home) {
+    return path.join(bolloonHome(home), 'chain');
+}
+export function chainStatePath(home) {
+    return path.join(chainStateDir(home), 'chain-state.json');
+}
+export function emptyChainState() {
+    return { schemaVersion: CHAIN_STATE_SCHEMA_VERSION, updatedAt: Date.now(), escrowAddresses: [], records: {} };
+}
+export function loadChainState(home) {
+    const p = chainStatePath(home);
+    try {
+        const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+        if (j && typeof j === 'object' && j.records && typeof j.records === 'object') {
+            return {
+                schemaVersion: Number(j.schemaVersion) || CHAIN_STATE_SCHEMA_VERSION,
+                updatedAt: Number(j.updatedAt) || 0,
+                escrowAddresses: Array.isArray(j.escrowAddresses) ? j.escrowAddresses.map(String) : [],
+                records: j.records,
+            };
+        }
+    }
+    catch { /* 没有 / 坏了 → 空状态 (不猜) */ }
+    return emptyChainState();
+}
+export async function saveChainState(state, home) {
+    const dir = chainStateDir(home);
+    await fsp.mkdir(dir, { recursive: true });
+    const p = chainStatePath(home);
+    const tmp = `${p}.tmp`;
+    const out = { ...state, updatedAt: Date.now() };
+    // escrowAddresses 从记录里重建 (别让两份真相漂开)
+    out.escrowAddresses = Array.from(new Set(Object.values(out.records).map((r) => r.escrowAddress))).filter(Boolean);
+    await fsp.writeFile(tmp, JSON.stringify(out, null, 2), 'utf8');
+    await fsp.rename(tmp, p);
+}
+/** 落盘一条记录 (幂等 upsert; 追加 history) */
+export async function upsertChainTx(rec, home) {
+    const state = loadChainState(home);
+    const prev = state.records[rec.requestId];
+    const now = Date.now();
+    const merged = {
+        ...(prev || {}),
+        ...rec,
+        suspect: rec.suspect ?? prev?.suspect ?? false,
+        firstSeenAt: prev?.firstSeenAt ?? rec.firstSeenAt ?? now,
+        updatedAt: now,
+        history: [
+            ...(prev?.history || rec.history || []),
+            { at: now, status: rec.status, txHash: rec.txHash, blockNumber: rec.blockNumber, confirmations: rec.confirmations, reason: rec.reason },
+        ],
+    };
+    state.records[rec.requestId] = merged;
+    await saveChainState(state, home);
+    return merged;
+}
+/** 把一次判定落盘 (verdict → record) */
+export async function recordVerdict(base, verdict, home) {
+    const suspectStatuses = ['reorged'];
+    const prev = loadChainState(home).records[base.requestId];
+    const suspect = suspectStatuses.includes(verdict.status)
+        ? true
+        : (prev?.suspect || false);
+    return upsertChainTx({
+        ...base,
+        resultHash: base.resultHash ?? prev?.resultHash,
+        confirmations: verdict.confirmations ?? 0,
+        lastCheckedBlock: verdict.latestBlock ?? prev?.lastCheckedBlock ?? null,
+        // ★ 新判定没带块号时, **保留旧事实里的块号** —— "这笔曾记在哪个块"是重组复核的唯一证据;
+        //   判定成 reorged 时判定器不带块号, 若这里覆盖成 null, 下一次对账就只能报 unknown
+        //   (说不出"它是被回滚的"), 重组证据被自己抹掉。
+        blockNumber: verdict.blockNumber ?? prev?.blockNumber ?? null,
+        status: verdict.status,
+        suspect,
+        suspectReason: verdict.status === 'reorged' ? verdict.reason : prev?.suspectReason,
+        reason: verdict.reason,
+        eventMatched: verdict.eventMatched ?? null,
+        matchedEvent: verdict.matchedEvent,
+        escrowState: verdict.escrowState ?? null,
+    }, home);
+}
+/**
+ * 从**持久记录**重建状态 (进程重启后第一步就该调它)。
+ * 不联网: 只用落盘的事实。`suspect` 记录一律不算 settled。
+ */
+export function recoverChainState(home) {
+    const state = loadChainState(home);
+    const all = Object.values(state.records);
+    const settled = all.filter((r) => (r.status === 'confirmed' || r.status === 'finalized') && !r.suspect);
+    const byStatus = (s) => all.filter((r) => r.status === s);
+    return {
+        total: all.length,
+        settled,
+        pending: byStatus('pending'),
+        reorged: byStatus('reorged'),
+        unknown: byStatus('unknown').concat(byStatus('config_unavailable')),
+        reverted: byStatus('reverted'),
+        eventMismatch: byStatus('event_mismatch'),
+        suspect: all.filter((r) => r.suspect),
+        escrowAddresses: state.escrowAddresses,
+        lastCheckedBlock: all.reduce((acc, r) => (r.lastCheckedBlock != null && (acc == null || r.lastCheckedBlock > acc) ? r.lastCheckedBlock : acc), null),
+    };
+}
+/**
+ * ★ 对账: 把每条记录的**旧事实** (blockNumber/confirmations/eventMatched)
+ * 交给唯一判定器重算一遍, 并按结果落盘。
+ *
+ * 报告**不许静默丢记录**: 范围内的每条记录要么进 `scanned` 的判定结果, 要么进
+ * `skippedFinalized` (不变式: `considered === scanned + skippedFinalized.length`)。
+ *
+ * 重组两条路径都在这里显式检出:
+ *   · 块号变了 / 链上查不到了 → verdict.status = 'reorged' → suspect = true
+ *   · 事件"消失"了 (之前 eventMatched=true, 现在 false) → suspect = true
+ */
+export async function reconcileChainState(client, opts = {}) {
+    const state = loadChainState(opts.home);
+    const report = {
+        checkedAt: Date.now(), considered: 0, scanned: 0,
+        confirmed: [], skippedFinalized: [], pending: [], reorged: [], unknown: [], reverted: [], newlySuspect: [], rpcErrors: 0,
+    };
+    const gate = opts.gate || 'confirmed';
+    const shouldSkipFinalized = opts.skipFinalized !== false;
+    for (const rec of Object.values(state.records)) {
+        if (opts.only && !opts.only.includes(rec.requestId))
+            continue;
+        report.considered++;
+        const isFinalized = rec.status === 'finalized' && !rec.suspect;
+        if (shouldSkipFinalized && isFinalized) {
+            // ★ 显式记账: 「跳过」必须被说出来。否则报告会把「已最终确定」表达成「查不到这条」,
+            //   调用方 (账单/验收) 就会把已结算当成没对账 —— 那是会撒谎的门。
+            report.skippedFinalized.push({
+                requestId: rec.requestId, taskKey: rec.taskKey, txHash: rec.txHash,
+                status: rec.status, confirmations: rec.confirmations,
+                reason: `已是 finalized 且未被标可疑 → 按设计跳过复核 (skipFinalized=true)。它仍是已结算, 只是本轮没重算`,
+            });
+            continue;
+        }
+        report.scanned++;
+        const verdict = await verifyChainSettlement(client, {
+            txHash: rec.txHash,
+            gate,
+            expect: rec.taskKey ? { kind: 'escrow', taskKey: rec.taskKey, resultHash: rec.resultHash } : undefined,
+            recorded: { blockNumber: rec.blockNumber, confirmations: rec.confirmations, status: rec.status },
+        });
+        // 事件"消失" = 重组 (旧判定说对得上, 现在对不上)
+        const eventVanished = rec.eventMatched === true && verdict.eventMatched === false && verdict.status === 'event_mismatch';
+        const prevSuspect = rec.suspect;
+        const effective = eventVanished
+            ? { ...verdict, status: 'reorged', chainSettled: false, reason: `重组: 之前核上的事件 ${rec.matchedEvent || ''} 在链上消失了 (${verdict.reason})` }
+            : verdict;
+        const after = await recordVerdict({ requestId: rec.requestId, method: rec.method, taskKey: rec.taskKey, escrowAddress: rec.escrowAddress, chainId: rec.chainId, txHash: rec.txHash, resultHash: rec.resultHash }, effective, opts.home);
+        // 事件消失也要显式标不可信 (recordVerdict 只对 'reorged' 自动标)
+        if (eventVanished && !after.suspect) {
+            const st = loadChainState(opts.home);
+            if (st.records[rec.requestId]) {
+                st.records[rec.requestId].suspect = true;
+                st.records[rec.requestId].suspectReason = '事件在链上消失 (重组)';
+                await saveChainState(st, opts.home);
+            }
+        }
+        const now = loadChainState(opts.home).records[rec.requestId] || rec;
+        if (now.suspect && !prevSuspect)
+            report.newlySuspect.push(rec.requestId);
+        if (!effective.rpcAvailable)
+            report.rpcErrors++;
+        const item = { requestId: rec.requestId, taskKey: rec.taskKey, txHash: rec.txHash };
+        switch (effective.status) {
+            case 'reorged':
+                report.reorged.push({ ...item, reason: effective.reason });
+                break;
+            case 'reverted':
+                report.reverted.push({ ...item, reason: effective.reason });
+                break;
+            case 'pending':
+                report.pending.push({ ...item, confirmations: effective.confirmations ?? 0, required: effective.confirmationsRequired });
+                break;
+            case 'confirmed':
+            case 'finalized':
+                report.confirmed.push({ ...item, status: effective.status, confirmations: effective.confirmations ?? 0 });
+                break;
+            default:
+                // unknown / config_unavailable / event_mismatch / not_attempted → 一律进 unknown (诚实: 不知道)
+                report.unknown.push({ ...item, reason: effective.reason });
+                break;
+        }
+    }
+    return report;
+}
+/** 人工/程序显式标不可信 (绝不静默) */
+export async function markSuspect(requestId, reason, home) {
+    const state = loadChainState(home);
+    const rec = state.records[requestId];
+    if (!rec)
+        return null;
+    rec.suspect = true;
+    rec.suspectReason = reason;
+    rec.updatedAt = Date.now();
+    rec.history.push({ at: rec.updatedAt, status: rec.status, txHash: rec.txHash, blockNumber: rec.blockNumber, confirmations: rec.confirmations, reason: `标记不可信: ${reason}` });
+    await saveChainState(state, home);
+    return rec;
+}
+export function getChainTxRecord(requestId, home) {
+    return loadChainState(home).records[requestId] || null;
+}
+export function findByTxHash(txHash, home) {
+    const h = String(txHash || '').toLowerCase();
+    return Object.values(loadChainState(home).records).find((r) => String(r.txHash).toLowerCase() === h) || null;
+}