#35480 doc: document ZMQ notification behavior during reorgs and evictions

ReviewabilityReviewsAgreementSize
#35480 fernandguil doc: document ZMQ notification behavior during reorgs and evictionsWaiting on author0Neutral15 + 59 tests
  • Document ZMQ notification behavior during chain reorganizations and mempool evictions
  • Gives external client developers clear notification guarantees without reading C++ internals
  • Ready to review
  • No review verdicts recorded
  • Nobody has spoken directly in favor yet, while earlier objections were settled
  • Suggests condensing the explanation of transaction removal notifications (sedited)
  • Suggests dropping the new reorg functional test since existing tests cover ordering (sedited)
  • 15 lines added or modified outside tests
  • 59 lines added or modified in tests
  • 0 lines removed in total
  • 2 files, 2 commits
Documentation#5 of 9
P3 · cleanup
  • P3 because it documents existing ZMQ reorg and mempool eviction behavior for downstream developers
  • The benefit is targeted specifically at external clients relying on ZMQ notifications
Ranking notes
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

Expands `doc/zmq.md` to document ZMQ notification behavior during chain reorganizations and mempool evictions, including re-publication on `rawtx`/`hashtx`, suppression under assumeutxo background validation, and mempool removal reasons under `sequence`. It also adds a functional test verifying the ordering of `D`, `R`, and `C` events on the `sequence` topic during a reorg.

Problem: ZMQ behavior during chain reorganizations and mempool evictions was implemented in the source code but undocumented, forcing external client developers to deduce notification guarantees directly from C++ internals.

Reviewability

Paused · Waiting on author

Open objections from sedited with no author reply for 23 days; review would repeat what has been asked.

Waiting on (from the thread read):

  • author: respond to sedited's suggestion to drop the reorg test 2026-10-09

Agreement

Neutral

objections settled, nobody has spoken for the PR

Thread notes: sedited dropped the requirement for a reorg test upon reviewing it, noting existing sequence tests already verify that 'R' arrives before 'C', and suggested dropping the newly added test.

Objections, suggestions, and questions:

ReviewerTypeHarm, request, or questionStatusMust beAuthor repliedQuote
sedited (member)suggestion, stylecollapse and condense the explanation of transaction removal notificationsopenansweredno2026-07-24: 'I would suggest collapsing this into:'
sedited (member)objection, correctnessdocumenting notification ordering guarantees without automated test coverage to ensure the behavior holdsaccepted · fix pushed · sedited dropped the requirement for a new reorg test, noting existing tests already check that 'R' arrives before 'C'changedno2026-07-24: 'I would only claim this in the docs, if there is a corresponding functional test exercising this.'
Status from: 2026-10-09: sedited: 'I don't think this happening during a re-org is different enough to warrant a test. Maybe this should be dropped again?'
sedited (member)suggestion, approachdrop the reorg functional test since existing sequence tests already check that 'R' arrives before 'C'openansweredno2026-10-09: 'I don't think this happening during a re-org is different enough to warrant a test. Maybe this should be dropped again?'

Participants:

  • sedited (member, objection, 3 statements 2026-07-24 to 2026-10-09): objected to documenting ordering without tests (later dropped); suggested simpler wording and dropping the reorg test

Files

59 lines under test/bench/ci.

  • test/functional/interface_zmq.py +59/-0
  • doc/zmq.md +15/-0

Card

The short text the ranking pass compares across PRs.

This PR expands doc/zmq.md to explain node notification behavior during chain reorgs and mempool evictions, and adds a functional test in test/functional/interface_zmq.py to verify reorg event ordering on the sequence topic. It clarifies that rawtx and hashtx re-publish transactions from disconnected blocks, suppresses them for assumeutxo background validation, and documents the D-R-C notification order. The documentation addresses part of open issue #14278. Review is ready, with the author having pushed the test requested by sedited.

Data

dossier JSON · extract JSON · model ledger, generated 2026-10-10T01:21, confidence high, input hash e3ff43052e07cd71
thread read through 2026-10-09 (3 statements), head 112a171179
labels: Docs

Categories

Documentation

P3 · cleanup

The PR documents previously undocumented ZMQ notification semantics during chain reorganizations and mempool evictions in doc/zmq.md and adds functional test verification. External client developers previously had to deduce notification guarantees directly from C++ source code, providing clear and worthwhile value for downstream integrations.

Membership: Labeled Docs and updates doc/zmq.md with documentation of ZMQ reorg and mempool eviction behavior.

Factors: security/stability 0, bug 0, performance 0, user value 1, leverage 0