脚本监控区块别再每秒轮询：waitforblockheight 的等待语义

一、脚本不想每秒轮询

写自动化脚本监控比特币节点时，最笨也最常见的写法是循环调用区块高度接口、每隔几秒问一次”到第几块了”。轮询的问题一层套一层：多数时候答案没变，白问；间隔设得比出块节奏短，浪费调用；设得比业务容忍的延迟长，反应又太慢。比特币核心的 RPC 提供了一条更经济的路线：waitforblockheight，把”高度达到某值再通知我”挂给节点，进程安静睡觉，达标瞬间返回。

同族还有按新区块等待的命令，分工有细微差别：按高度等待适合”至少要 N 个确认”这类条件判断，按新区块等待适合事件驱动。名字容易记混，以各版本官方 RPC 文档的命令签名与返回字段为准。

二、它怎么做到不打扰也不失联

机制上这是一次长连接挂起：RPC 请求带一个目标高度参数进节点，节点把这次调用登记进区块处理管道的回调名单，连接保持但不占 CPU。当链尖推进到满足条件的高度，管道触发回调，挂起的调用携带当前高度与区块哈希返回。参数上通常有一个超时上限——超过时限节点返回当前实际进度而不是报错，因此正确用法是一个小循环：算出目标高度，发起等待，检查返回值里的当前高度与超时标记，未达标就继续等。

需要警惕的是它的返回语义：区块高度达标不等于你关心的那笔交易达标。脚本常见漏洞是把”链尖过了某个高度”当成”某交易有了若干确认”——重组随时可能把那个高度上的交易请出主链。严谨写法是等待返回后再查一次交易自身的确认数，把高度当触发器而不是结论。

三、和轮询的成本对账

轮询的真实成本要放在部署环境里算：对单节点偶尔对账，轮询完全没问题，几 KB 的 RPC 开销不值得优化。两种场景下等待模式才有明显收益。其一，对账服务要同时盯很多笔交易的确认进度：轮询让每个任务各扫各的，等待模式把它们折叠成共享的区块事件流，配合推送通知机制，可以做到区块一到、所有监听任务同步醒。其二，云端部署且 RPC 走公网链路时：空转请求除了节点开销，还有真实流量费，长连接等待把这些固定成本摊薄到每个区块一次。

还有一条常被误读：长时间挂起的等待调用会出现在节点的在途请求列表里，这是正常形态而不是卡死。监控面板若把 RPC 在途数当健康指标，记得给等待类调用开个例外，否则误报会让你误重启本来健康的进程。同样的道理也适用于防火墙与负载均衡：把 RPC 空闲超时设得比等待上限短的中间层，会在每个安静的十分钟里准时掐断你的连接——排查”等待偶尔无故返回”时，先量一遍链路上每一跳的空闲超时参数，多数锅其实在这条中间层上。

四、验收清单与三条禁忌

验收很简单：手工推进 regtest 区块，观察脚本是否恰好一块一醒；断网模拟一次，确认超时分支能返回而不是永久悬挂；跑一次重组测试，确认脚本不会因为高度短暂回退就重复执行同一批动作。

三条禁忌。第一禁忌：用等待替代对账。它只报告链的进度，不替你核验交易在不在主链上。第二禁忌：拿默认超时当无限等待写生产脚本，超时语义处理不好，进程会在重组或停滞时集体沉默。第三禁忌：把等待目标高度算错——业务目标是六确认时，等待锚点应该是交易首次进块的高度加六，不是链尖加六，两字之差，轻则多等六个块，重则脚本逻辑永远差一块。

风险提示：本文仅为节点自动化机制科普，不构成任何投资建议。