/rest/blockfilter 与 blockfilterheaders：用 HTTP 取回 BIP157 过滤器的两条路

轻客户端问”这个块里有没有我的地址”，靠的不是整块数据，而是每块几十到几百字节的区块过滤器。BIP157 定义了 basic 过滤器，BIP158 定义了它的构造，而比特币核心把这类数据开放给外部消费的不止 getblockfilter 一条 RPC——REST 面上还有一对端点：/rest/blockfilter/ 与 /rest/blockfilterheaders/。本文按 v31.0 源码的 rest.cpp 讲清两条路的形状与门槛。

前提：先有索引，后有端点

过滤器不是从区块文件现算的：节点要带 -blockfilterindex=1 启动，索引层会把每块的过滤器与一条链式头存进索引库，逐块追平链尖。没开索引的节点上，这两个端点无从应答——它们与 getblockfilter RPC 共享同一个后端。索引默认关闭的原因在启动成本：额外磁盘与同步期开销，v31 时代它仍是显式选择而非默认。

单块取回：/rest/blockfilter/<filtertype>/<blockhash>

URL 按斜杠拆成两段：过滤器类型与区块哈希。类型参数当前只有 basic 一种合法值，写别的会报错；区块哈希必须按显示顺序写成十六进制——与区块头哈希一贯”反着写”的字节序约定相同，直接拿链上原始字节序来填会查无此块。寻址成功后，过滤器可以按 bin 形态作为二进制体返回，也可以按 hex 形态作为文本返回，两种粒度分别喂脚本与喂人眼。

连续段取回：/rest/blockfilterheaders/<filtertype>/<blockhash>?count=N

过滤器的链式头（每块过滤器的哈希承诺，串成一条独立小链）走这个端点。v31 的请求面有两种写法：新式把数量放进查询参数，/rest/blockfilterheaders/basic/<hash>.json?count=2000；旧式把数量放在路径里的 /count/<hash> 形态仍被兼容解析。count 的闸门是一个独立常量：REST 面专用的批次上限为 2000，小于 1 或大于 2000 都会被 400 拒绝——与 P2P headers 消息的单包上限恰好同数，但是两条独立实现里各自的常量。返回格式支持 bin、hex、json 三种，json 形态给的是承诺哈希的数组。

这两条路各自适合谁

单块端点适合事件驱动的对账：钱包收到一笔可疑入账，先取那块的过滤器验一次”里面确实（不）含目标脚本元素”，再决定要不要拉整块。链头端点适合周期性体检：轻客户端每轮同步本来就按段拉过滤器与链头做默克尔包含验证，把一段连续区块的链头一次拉满 2000 格，是给自己节点写审计脚本时最省往返的取法。两条路都是纯读，不动钱也不动节点状态。

三条边界提醒

第一，端点同样没有鉴权，REST 面对网络里所有能连上你 HTTP 端口的人开放，监听范围与反代策略要按同样的纪律收紧。第二，过滤器回答的是”可能没有”而非”一定没有”的单向问题——哈希误判方向永远朝”假阳性”一侧，端点返回的字节再合法也不改变这个语义。第三，索引构建进度会滞后于链尖，刚同步起来的节点上取最新块的过滤器，先查索引追平了没有，否则拿到落后结果还以为链在骗你。

一次手工核验的完整动线

拿主网一个已知区块做一次全流程演练，能把上面所有碎片串起来：先在浏览器里抄下该块的显示顺序哈希；用 -blockfilterindex=1 启动的节点上请求 /rest/blockfilter/basic/<哈希>.json 形态的单块过滤器，把返回的字节与 BIP158 工具库算出的结果对一遍；再请求 /rest/blockfilterheaders/basic/<上一块哈希>.json?count=10，验证返回的第一条承诺哈希与本地索引库记录一致。三步全对上，说明你的节点从索引到端点的整条供给链是健康的；任何一步错位，问题一定出在哈希书写顺序、类型参数拼写或索引进度三个环节之一——这张排错清单比它看起来值钱，因为过滤器相关的疑难九成落在这三格里。

风险提示：本文以比特币核心 v31.0 源码为基准，端点与格式可能随版本调整，请以实际运行版本为准。内容为技术说明，不构成任何投资建议。