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

pull fernandguil wants to merge 1 commits into bitcoin:master from fernandguil:doc/zmq-notification-behavior changing 1 files +19 −0

fernandguil commented at 6:06 PM on June 7, 2026: contributor
Partially addresses #14278.

Expands doc/zmq.md to document notification behavior that is implemented in the source but not described anywhere in the docs:

rawtx / hashtx
- These topics re-publish transactions from disconnected blocks during a reorg
- They are suppressed for historical blocks connected to the assumeutxo background validation chainstate (consistent with rawblock/hashblock)
sequence (R removals)
- Clarify that R covers all mempool removal reasons except block inclusion: EXPIRY, SIZELIMIT, REORG, CONFLICT, REPLACED (RBF)
- Explicitly note that block-inclusion removals are not reported via R; subscribers should use rawblock/hashblock for those
Reorg ordering
- Document the sequence of events during a reorg: D (block disconnected) → R (evicted mempool txs) → C (block connected)
All behavior described here is derived directly from src/zmq/zmqnotificationinterface.cpp and src/txmempool.cpp.
DrahtBot added the label Docs on Jun 7, 2026
DrahtBot commented at 6:07 PM on June 7, 2026: contributor



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



Code Coverage & Benchmarks

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



Reviews

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

doc: document ZMQ notification behavior during reorgs and evictions

Expand zmq.md to describe:
- rawtx/hashtx are re-published for transactions in disconnected blocks
  during a reorg, and suppressed for assumeutxo background chainstate blocks
- sequence 'R' notifications cover all mempool removal reasons except block
  inclusion (EXPIRY, SIZELIMIT, REORG, CONFLICT, REPLACED)
- the ordering of sequence events during a reorg (D -> R -> C)

This addresses part of #14278.

f928735284

fernandguil force-pushed on Jul 23, 2026

in doc/zmq.md:167 in f928735284

 158 | @@ -151,6 +159,17 @@ The 8-byte LE uints correspond to _mempool sequence number_ and the types of bod
 159 |     - `R` : transaction with this hash removed from mempool for non-block inclusion reason
 160 |     - `A` : transaction with this hash added to mempool
 161 |  
 162 | +A transaction removal notification (`R`) is sent for all removals **except** block
 163 | +inclusion. This covers: expiry (`EXPIRY`), size limit eviction (`SIZELIMIT`),
 164 | +reorg eviction (`REORG`), conflict with an in-block transaction (`CONFLICT`), and
 165 | +replacement via RBF (`REPLACED`). Transactions removed because they were included
 166 | +in a block are not reported here; subscribers can learn about those via the
 167 | +`rawblock` or `hashblock` topics.

sedited commented at 10:15 AM on July 24, 2026:

I would suggest collapsing this into:

A transaction removal notification (`R`) is sent for all removals **except** block
inclusion. Subscribers can learn about those via the `rawblock` or `hashblock` topics.

in doc/zmq.md:171 in f928735284

 166 | +in a block are not reported here; subscribers can learn about those via the
 167 | +`rawblock` or `hashblock` topics.
 168 | +
 169 | +During a reorg, the sequence of events is: the disconnected block is announced (`D`),
 170 | +then any mempool transactions evicted due to the reorg receive an `R` notification,
 171 | +then the reconnected block is announced (`C`).

sedited commented at 10:24 AM on July 24, 2026:

I would only claim this in the docs, if there is a corresponding functional test exercising this.

Contributors

Labels

Linked (view graph)

#14278 Callback/notification documentation and cleanup

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

Code Coverage & Benchmarks

Reviews