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

pull fernandguil wants to merge 2 commits into bitcoin:master from fernandguil:doc/zmq-notification-behavior changing 2 files +74 −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.
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.

fernandguil force-pushed on Aug 13, 2026

test: check 'sequence' notification ordering during a reorg

Cover the order in which a reorg that evicts a mempool transaction is
published on the 'sequence' topic: the disconnected block ('D'), then the
eviction ('R'), then the connected blocks ('C').

BlockDisconnected is emitted inline by DisconnectTip, the reorg eviction
by MaybeUpdateMempoolForReorg at the end of ActivateBestChainStep, and
the BlockConnected signals are batched into connected_blocks and only
emitted by ActivateBestChain once the step has returned. The ordering is
therefore a property of the reorg code path rather than a timing
accident.

6379cce4eb

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 are sent for all mempool removals except block
  inclusion, and subscribers can learn about block inclusions via rawblock
  or hashblock
- the order in which a reorg is published on the sequence topic, which the
  preceding commit covers with a functional test

This addresses part of #14278.

112a171179

fernandguil force-pushed on Aug 28, 2026

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