waitforblock超时后返回什么？

waitforblock适合等待一个已经知道哈希的特定Bitcoin区块。它看似是一条阻塞命令，真正的工程难点却在返回判定：请求没有报错，不等于目标区块已经出现。方法超时、节点退出和目标命中都可能给出结构相似的hash与height。

先把状态机写出来

waitforblock必填目标blockhash，可选timeout以毫秒计；timeout=0表示不设置方法超时。参数一是目标blockhash，参数二是毫秒级timeout；timeout=0表示方法不主动超时。调用开始后，程序处于“等待目标”状态。收到响应后必须比较result.hash与输入哈希：相等才是目标命中，不等则按当前链尖快照处理。

发起等待(target, timeout)
  ├─ 返回hash == target → 目标出现，记录height后进入验证
  ├─ 返回hash != target → 方法超时或退出路径，重新评估链状态
  ├─ 传输错误 → 客户端/代理/节点故障，不能推断链上结果
  └─ 调用取消 → 保存最后已知状态，再决定是否重启等待

目标出现时返回hash和height；方法超时或节点退出时也会返回当前区块，因此调用方必须比较返回hash而不能只看HTTP成功。官方明确写明：超时或退出时返回当前区块。这意味着脚本若只判断HTTP 200或JSON-RPC没有error，会制造假阳性。最小正确条件是返回哈希与目标相等；进一步还应核对返回height、活动链归属和需要的确认深度。

两个timeout属于不同层

方法timeout决定节点最多等待多少毫秒；bitcoin-cli的rpcclienttimeout决定客户端连接愿意等多久。官方文档提醒长等待时使用无RPC客户端超时；方法自身timeout与bitcoin-cli的rpcclienttimeout是两个不同层次。官方提醒长等待使用-rpcclienttimeout=0，原因是客户端若先断开，节点侧方法可能仍在等待，而调用方只看到传输层超时。

反向配置也会产生问题：方法timeout很短、客户端timeout很长时，程序会频繁得到当前链尖并立刻重连，形成没有价值的轮询压力。合理做法是让方法超时成为可预测的心跳窗口，客户端超时比它略长，或者双方都采用明确的取消与重连策略。

现象	先检查	不应推断
返回非目标hash	方法超时、节点退出、链尖	目标已出现
客户端连接断开	代理、网络、rpcclienttimeout	目标未出现
返回目标hash	活动链与确认状态	永不重组
多实例结果不同	请求落到哪台节点	任一节点恶意

目标出现后还要做链视图核验

比特币区块可以在链重组中离开活动链。waitforblock命中说明节点观察到了目标，并不提供“永远不会回滚”的保证。命中后用getblockheader或getblock确认区块数据，再结合getchaintips、当前链高和业务确认数跟踪。

如果目标哈希来自不可信上游，先确认格式与网络，再决定是否长时间等待。等待一个根本不属于该网络或已经确定不会进入活动链的哈希，会永久占用连接。应用应设置业务级截止时间，并把“未观察到”与“确认目标无效”分成不同状态。

多实例与负载均衡要固定会话

负载均衡后的两个节点可能处于不同高度、连接不同对等节点。长轮询若在重试时随机切换实例，日志会混合不同视图。至少记录节点实例标识；更稳妥的是让单次等待固定到一台节点，并用另一故障域节点做独立核对。

不要为了可用性同时让几十个请求等待同一哈希。进程内可以把一条节点等待结果分发给多个订阅者，并设置并发上限、取消传播和指数退避。节点重启后，由协调器恢复等待，而不是所有消费者一起冲击RPC。

与waitfornewblock怎样分工

waitfornewblock关注调用之后出现的新链尖，适合通用新区块监听；waitforblock关注给定哈希，适合任务依赖、回放和特定区块到达检查。两者都需要检查返回值，但目标条件不同。选择接口应由业务问题决定，不要因为名字相近就互换。

监控面板可显示“目标命中”“窗口超时”“传输失败”“节点退出”“目标已观察但未达确认数”。这些状态比一个绿色成功率更诚实，也能让值班人员知道下一步是重试、切节点、查重组还是停止等待。

成功响应也必须检查目标哈希

记录目标哈希、方法超时、客户端超时、返回哈希、高度和节点实例。只要返回哈希不等于目标，就不能把这次调用记为目标区块到达。