doc: document ZMQ notification asynchrony and RPC synchronization #36110

pull fernandguil wants to merge 1 commits into bitcoin:master from fernandguil:doc/zmq-rpc-synchronization changing 1 files +10 −0
  1. fernandguil commented at 3:21 AM on August 28, 2026: contributor

    doc/zmq.md describes each topic and the per-topic sequence numbers, but says nothing about when notifications are delivered relative to the node's own state. This trips up clients that treat a notification as a snapshot: ZMQ messages are queued on the SerialTaskRunner (src/scheduler.h) that backs ValidationSignals and dispatched from the scheduler thread after the block or mempool change is already applied, so a subscriber that reacts to hashblock by calling getbestblockhash can legitimately get a later block than the one it was just told about.

    This adds a paragraph to the Remarks section stating that:

    • notifications are dispatched asynchronously, after the state change,
    • a notification should be used as a trigger to re-query rather than as a snapshot of current state,
    • ordering is preserved within a topic, but not across the ZMQ, -*notify and RPC interfaces, which run independently (-blocknotify, for instance, runs its command on a detached thread in src/init.cpp).

    Documentation only; no behaviour change.

    This addresses part of #14278.

  2. doc: document ZMQ notification asynchrony and RPC synchronization
    Note in zmq.md that notifications are dispatched asynchronously after the
    node's state is updated, so a subscriber may observe the node ahead of a
    notification it just received (e.g. getbestblockhash returning a later block
    than the one announced via hashblock). Advise treating notifications as a
    trigger to re-query the node, and clarify that message ordering is guaranteed
    only within a topic, not across the ZMQ, -*notify, and RPC interfaces.
    
    This addresses part of #14278.
    3fbb310576
  3. DrahtBot added the label Docs on Aug 28, 2026
  4. DrahtBot commented at 3:22 AM on August 28, 2026: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    <!--006a51241073e994b41acfe9ec718e94-->

    Code Coverage & Benchmarks

    For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/36110.

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

    See the guideline and AI policy for information on the review process. A summary of reviews will appear here.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->

  5. in doc/zmq.md:218 in 3fbb310576
     213 | +it just received. For example, `getbestblockhash` may already return a block
     214 | +later than the one announced by `hashblock`. Notifications should be treated
     215 | +as a trigger to re-query the node rather than as a synchronous snapshot of its
     216 | +current state. Message ordering is preserved within a topic, but there is no
     217 | +ordering guarantee across the ZMQ, `-*notify`, and RPC interfaces, which
     218 | +operate independently.
    


    maflcko commented at 6:47 AM on August 28, 2026:

    Not sure what this is trying to say. ZMQ being async is pretty obvious and pointless to say? The next sentence seems wrong, because ordering across subscribers (src/validationinterface.h:38) does not exist. E.g a mempool ZMQ notification doesn't guarantee the wallet is up to date...

    Also, I am not sure why -*notify and RPC docs are placed in doc/zmq.md

  6. maflcko changes_requested
  7. maflcko commented at 6:49 AM on August 28, 2026: member

    Was this LLM generated?

    Please note that contributors are required to fully understand their authored commit themselves. Also, LLM generated content is not allowed in comments/communications.

    See https://github.com/bitcoin/bitcoin/blob/master/doc/AI_POLICY.md

  8. sedited commented at 7:01 AM on August 28, 2026: contributor

    Yeah, a user of zmq should be well aware of this. I don't think this needs any additional documentation. I've never experienced a user being confused about this.

  9. sedited commented at 8:25 AM on August 29, 2026: contributor

    Closing this again. I think your other two pull requests are enough to address the issue you are trying to work through here.

  10. sedited closed this on Aug 29, 2026


github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-09-06 08:51 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me