blocknotify 与 walletnotify：给比特币节点装上事件回调的铃铛

两条钩子挂在配置的哪个抽屉

比特币核心有两个通知选项。-blocknotify 挂在主程序配置里：当一个新区块成为当前最佳区块，节点执行你指定的命令，命令里的 %s 会被替换成该区块哈希。-walletnotify 挂在钱包侧配置里：当钱包里任何交易的状态发生变化——新到账、被打包进块、在重组中被退回——都会触发，替换规则更丰富：%s 是交易编号，%w 是钱包名，%b 是包含它的区块哈希（未打包时写为字符串 unconfirmed），%h 是区块高度，未确认时写 -1。官方说明特别标注 %w 在 Windows 上目前没有实现，且所有占位符都经由 shell 转义拼进命令行，写脚本时不要对参数再加引号，会破坏转义。

它替你省掉的轮询

没有这两条钩子时，一切自动化都靠轮询：脚本每隔几秒调用一次 RPC 问”有新块吗""这笔到账了吗”。轮询有三个毛病——延迟上限就是你的轮询间隔；每次轮询都是一次 RPC 往返；状态语义还得自己在两次快照之间推断。通知钩子把方向反过来：事件发生的那一刻，节点主动把参数塞进你的可执行文件，钱包通知甚至自带确认深度信息，%b 从 unconfirmed 变成区块哈希，就是”进块”这一跃迁的直接信号。对账、监控面板、支付回调这类场景，事件驱动明显优于轮询。

你的脚本是节点身份的一部分

必须清醒的一点：这两个命令以节点进程同样的用户权限运行。脚本文件本身的写权限就等于系统的写权限，配置文件里写的命令行会被 shell 解析，参数来自链上数据。因此三条纪律：脚本所在目录的权限收紧，别放全局可写路径；对 %s 传入的值永远当外部输入对待，先做十六进制长度校验再进任何查询；执行逻辑要幂等——重组会让同一笔交易反复触发通知，脚本重复跑十次也得保持结果一致。此外，钱包通知在节点重启补齐状态时可能集中爆发，消费端要有队列而不是现场处理。

调试路径

上线前先最小化：把钩子命令写成往日志文件追加一行的形式，观察一周的触发频率、参数格式和高峰时段行为，确认没有风暴，再逐步接入真实系统。排障时对照两个来源：节点日志里的通知执行记录，和你自己脚本的运行日志，两边时间戳对齐，问题多半出在权限、转义和重复触发这三件事上。

修剪与权限组合出的坑

两条钩子各自还会和别的配置咬合。开了修剪模式的节点依然触发 blocknotify，但你的脚本若依赖回查完整区块数据，就会在旧块上撞墙；钱包通知在多个钱包同时加载时都会触发，参数里没有钱包名时——Windows 下没有——多钱包的账会搅进同一串交易编号里，需要按钱包分派处理。还有一个隐蔽边界：blocknotify 只在”最佳区块改变”时触发，节点长时间空转或节点重启补齐期间，触发语义与你的直觉可能有偏差，处理逻辑要按状态机写而不是按计数写。最后，通知命令执行失败不会在节点界面报错，只留下日志里一行痕迹——上线第一天就去把通知脚本的退出码写进你自己的日志，否则第一次故障就是一段没有线索的黑箱。

本文仅讲解软件配置，不构成任何投资建议；自动化脚本与权限配置失误可能导致信息泄露或服务异常，生产启用前请在测试网完整演练。