scanblocks怎样扫描描述符？

scanblocks 借助 blockfilterindex 按描述符寻找可能相关的区块。本文按前置检查、启动、进度、假阳性处理和裁剪节点边界组织一套可恢复的扫描流程。

scanblocks 更像“候选区块定位器”，不是钱包恢复向导。它使用区块过滤器缩小范围，输出可能与描述符相关的 blockhash；后续仍需读取区块或交易证据。把返回数组直接当余额或完整历史，是最常见的概念错误。

控制室启动前：先看索引

scanblocks按输出描述符扫描区块过滤器并返回可能相关的区块哈希，运行前要求节点启用并构建blockfilterindex。

运行前调用 getindexinfo，确认 blockfilterindex 存在、synced=true，并让 best_block_height 接近目标 stop_height。配置文件中出现 blockfilterindex=1 只能证明意图，不能证明后台构建已经完成。

start、status 与 abort 的操作顺序

start可限定start_height与stop_height，status返回近似进度和当前高度，abort用于请求中止正在运行的扫描。

1. scanblocks "start" [scanobjects] start_height stop_height
2. 另一个受控会话调用 scanblocks "status"
3. 必须中止时调用 scanblocks "abort"
4. 保存 from_height、to_height、relevant_blocks、completed

大范围任务可能持续数分钟，客户端超时应按任务设计调整。超时断开不代表服务端扫描立即停止；再次启动前先查 status，避免多个操作者误判状态。

scanobjects 怎样留存

每个对象可以是字符串描述符，也可以是带 desc 与 range 的对象。对 ranged descriptor 必须固定索引范围。日志中不要暴露不必要的 xpub；可保存描述符哈希、checksum、范围和受控密钥库引用，以便审计同时减少隐私泄露。

假阳性是设计边界

默认结果可能包含过滤器假阳性；启用filter_false_positives会更慢且可能在裁剪节点失败，返回相关区块也不等同于完整钱包交易列表。

模式	优点	代价
默认	较快、适合先定位	relevant_blocks 可能含假阳性
filter_false_positives	尝试进一步过滤	更慢，裁剪节点可能失败

真正匹配需要在候选区块里按脚本重新验证。没有 relevant_blocks 也只说明当前过滤器与范围未发现候选，不能替代对描述符、网络和起始高度的检查。

扫描失败时从哪一层回退

先检查网络与索引，再检查描述符语法和 range，最后检查裁剪边界与磁盘数据。若 completed=false，必须把已覆盖高度和中止原因写入任务记录；下一次恢复时从明确高度继续，而不是默认从零重跑。

输出证据至少包含节点版本、链头、索引高度、完整参数、进度样本和最终 blockhash 列表。当前未知项是：大范围扫描可能持续数分钟，自动化需要禁用过短RPC超时并在扫描前用getindexinfo确认索引高度。

从候选区块走向钱包历史

对每个 relevant block 读取可验证数据，匹配脚本后再生成交易级记录，最终由钱包或独立索引器核对收支。scanblocks 的价值是缩小检索空间，不是取代钱包导入、余额计算或备份恢复。

资料与关联主题

Bitcoin Core scanblocks：用于核对接口字段、返回语义和适用边界；访问于 2026 年 7 月 25 日。
Bitcoin Core getindexinfo：用于核对接口字段、返回语义和适用边界；访问于 2026 年 7 月 25 日。

可继续阅读钱包描述符是什么、BIP380语法、getdescriptorinfo检查。在真实钱包恢复前，应在隔离节点和小范围高度完成演练。

scanblocks怎样扫描描述符的复核演练

选择一个很小的高度区间和已知描述符执行完整扫描，随后故意扩大 range、启用假阳性过滤并模拟客户端超时。复核者要从 status 与最终 completed 字段区分“仍在运行、已中止、客户端断开但服务端继续”三种状态，并能从保存记录安全恢复任务。演练还要记录 blockfilterindex 高度与裁剪边界，证明失败归因不是凭感觉选择。