用描述符查一段区块的收支：getdescriptoractivity 与 scanblocks 的配合

观察钱包做对账，最常见的三连问是：这些地址在某个高度区间动过没有？哪几笔是收、哪几笔是花？金额和出处分别是什么？过去要么外接索引程序，要么在本地用 scantxoutset 加一堆脚本手工拼。v29.0 起，比特币核心自己给出了答案的两段式组合：scanblocks 找”可能相关的区块”，getdescriptoractivity 把其中的收支事件逐条拆出来。

scanblocks：先圈定嫌疑区块

scanblocks 的用法是 start 加一组扫描对象，例如：

bitcoin-cli scanblocks start '["addr(...)"]' 300000

它从指定高度起沿链检查，返回一个 relevant_blocks 数组——“可能匹配了某个扫描对象的区块”列表。关键词是可能：这个阶段的判定基于脚本层面的粗筛，列表里允许出现假阳性，它的作用只是把后续精查的范围从全链压缩到几个块。

getdescriptoractivity：把相关区块拆开数钱

拿到区块哈希列表后，getdescriptoractivity 接两个必填数组和一条开关：

bitcoin-cli getdescriptoractivity '["<blockhash>"]' '["addr(bc1q...)"]' true

参数语义按 v31.1 的帮助文本：第一组 blockhashes 是要检查的区块，顺序无所谓，但必须都在主链上——查不到报 “Block not found”，不在主链报 “Block is not in main chain”，都是硬错误。第二组 scanobjects 每项可以是描述符字符串或带选项的对象。第三个参数 include_mempool 默认 true，把内存池里的未确认活动也一并算进来。

返回的 activity 数组里是两类事件，字段结构不同。支出（type 为 spend）给出金额、花费交易的 spend_txid 与输入序号 spend_vout，以及被花掉的 prevout_txid、prevout_vout 和它的锁定脚本 prevout_spk；接收（type 为 receive）给出金额、txid、vout 与 output_spk。两类事件都带 blockhash 和 height——未确认的那几条里这两个字段直接省略，这就是”在池子里”和”已落块”在返回结构里的区分方式。金额单位是 BTC（帮助文本标注 CURRENCY_UNIT），拿它和链上脚本打交道时记得换算。

两个工程提醒

帮助文本对耗时毫不遮掩：“This call may take several minutes”——每个相关区块都要完整反序列化再扫描，块大、列表长时就是分钟级。超时报错时官方建议直接放弃客户端超时：bitcoin-cli -rpcclienttimeout=0。

另一个是成本归属：这个 RPC 不需要 txindex 之类的常驻索引，代价体现在每次调用的读盘与解析上。一次性对账很划算；高频轮询别用它，那属于该建索引的负载形态。

最后留意版本行为差异：v30.0 起 blockhashes 与 scanobjects 两个参数被标记为必填——老脚本如果靠”省略参数撞默认行为”，在新版本上会直接报参数错误，升级时值得先跑一遍回归。

一条完整的观察链路

把近几个版本加入的三条命令排在一起，就是一条不依赖外部索引的纯核心观察管线：scanblocks 找范围，给定描述符从指定高度起圈出 relevant_blocks；getdescriptoractivity 数历史，把圈出的区块逐个拆成收支事件；scantxoutset 查现在，回答这类脚本眼下还有没有未花费余额。找范围、数历史、查现在，三者各管一段，接起来就是完整对账闭环。

跑大跨度任务的节奏建议：起始高度按年份分段提交，段内让 scanblocks 一口气跑完，把每段返回的区块列表存档后再精查——分段能让失败重试的代价可控。精查阶段记住区块参数只认主链，重组掉的孤儿块哈希传进去是硬错误，档案里的区块先做一遍主链校验再喂。

事件表的读法细节

拆账前先记住几条口径：spend 条目的 amount 是被花那一笔输出的面额，同一脚本在一笔交易里花掉多个输入会拆成多条事件；receive 的 amount 是该交易新输出上聚合到这一脚本的余额。两侧金额天然不相等——差额就是手续费与流向其它脚本的找零，拿收支总额直接对不平账是正常现象。对账最稳的路子是事件流加抽样余额双轨：事件流来自 getdescriptoractivity，当下余额抽查用 scantxoutset，两边对得上的部分才写进结论。height 缺失即未确认，带 include_mempool 的返回里出现无高度条目属正常，不代表它们已进主链。

风险提示：本文所述接口行为以 v31.1 源码为准，跨大版本行为可能调整；查询结果只反映你节点可见的链上活动，不构成投资建议。