{
 "number": 35480,
 "repo": "bitcoin/bitcoin",
 "url": "https://github.com/bitcoin/bitcoin/pull/35480",
 "title": "doc: document ZMQ notification behavior during reorgs and evictions",
 "author": "fernandguil",
 "author_association": "CONTRIBUTOR",
 "created_at": "2026-06-07T18:06:54Z",
 "updated_at": "2026-08-28T03:43:31Z",
 "age_days": 101,
 "draft": false,
 "labels": [
  "Docs"
 ],
 "milestone": null,
 "base": "master",
 "head_sha": "112a171179956c376428fec480f24cb97955b0ca",
 "head_ref": "doc/zmq-notification-behavior",
 "head_repo": "fernandguil/bitcoin",
 "head_history": [
  {
   "t": "2026-07-23T19:03:56Z",
   "sha": "f928735284dc76fdefa0af8d3d9613a5f88f1816"
  },
  {
   "t": "2026-08-13T00:37:40Z",
   "sha": "1af2626698b2fad9309223c2597f537fc9770c7a"
  },
  {
   "t": "2026-08-28T03:43:31Z",
   "sha": "112a171179956c376428fec480f24cb97955b0ca"
  }
 ],
 "additions": 74,
 "deletions": 0,
 "changed_files": 2,
 "commit_count": 2,
 "size_bucket": "S",
 "mergeable_state": "blocked",
 "bot": {
  "drahtbot": {
   "present": true,
   "reviews": {},
   "conflicts": []
  }
 },
 "acks_parsed": {},
 "acks_tally": {
  "ack": 0,
  "stale_ack": 0,
  "concept_ack": 0,
  "approach_ack": 0,
  "nack": 0,
  "concept_nack": 0,
  "approach_nack": 0
 },
 "reviews": {
  "approved": 0,
  "changes_requested": 0,
  "distinct_reviewers": [
   "sedited"
  ]
 },
 "signals": {
  "needs_rebase": false,
  "ci_failed": false,
  "mergeable_state": "blocked",
  "last_author_activity": "2026-08-28T03:43:31Z",
  "last_reviewer_activity": "2026-07-24T10:24:13Z",
  "last_reviewer": "sedited",
  "author_silent_days": 20,
  "waiting_on_author_days": 0,
  "days_since_update": 20
 },
 "refs": {
  "mentioned": [
   14278
  ],
  "depends_on": [],
  "fixes": [],
  "linked_issues": [],
  "references": [
   {
    "number": 14278,
    "type": "issue",
    "state": "open",
    "merged": false,
    "merged_at": null,
    "title": "Callback/notification documentation and cleanup"
   }
  ],
  "conflicts": []
 },
 "stack": {
  "shares_commits_with": [],
  "based_on": [],
  "base_for": []
 },
 "review_paths": [
  "doc/zmq.md"
 ],
 "body": "Partially addresses #14278.\n\nExpands `doc/zmq.md` to document notification behavior that is implemented\nin the source but not described anywhere in the docs:\n\n**`rawtx` / `hashtx`**\n- These topics re-publish transactions from disconnected blocks during a reorg\n- They are suppressed for historical blocks connected to the assumeutxo\n  background validation chainstate (consistent with `rawblock`/`hashblock`)\n\n**`sequence` (`R` removals)**\n- Clarify that `R` covers *all* mempool removal reasons except block inclusion:\n  `EXPIRY`, `SIZELIMIT`, `REORG`, `CONFLICT`, `REPLACED` (RBF)\n- Explicitly note that block-inclusion removals are not reported via `R`;\n  subscribers should use `rawblock`/`hashblock` for those\n\n**Reorg ordering**\n- Document the sequence of events during a reorg:\n  `D` (block disconnected) \u2192 `R` (evicted mempool txs) \u2192 `C` (block connected)\n\nAll behavior described here is derived directly from\n`src/zmq/zmqnotificationinterface.cpp` and `src/txmempool.cpp`.",
 "commits": [
  {
   "sha": "6379cce4eb406bf3f2107524d0b151c20735057c",
   "date": "2026-08-28T03:37:19Z",
   "message": "test: check 'sequence' notification ordering during a reorg\n\nCover the order in which a reorg that evicts a mempool transaction is\npublished on the 'sequence' topic: the disconnected block ('D'), then the\neviction ('R'), then the connected blocks ('C').\n\nBlockDisconnected is emitted inline by DisconnectTip, the reorg eviction\nby MaybeUpdateMempoolForReorg at the end of ActivateBestChainStep, and\nthe BlockConnected signals are batched into connected_blocks and only\nemitted by ActivateBestChain once the step has returned. The ordering is\ntherefore a property of the reorg code path rather than a timing\naccident."
  },
  {
   "sha": "112a171179956c376428fec480f24cb97955b0ca",
   "date": "2026-08-28T03:37:19Z",
   "message": "doc: document ZMQ notification behavior during reorgs and evictions\n\nExpand zmq.md to describe:\n- rawtx/hashtx are re-published for transactions in disconnected blocks\n  during a reorg, and suppressed for assumeutxo background chainstate blocks\n- sequence 'R' notifications are sent for all mempool removals except block\n  inclusion, and subscribers can learn about block inclusions via rawblock\n  or hashblock\n- the order in which a reorg is published on the sequence topic, which the\n  preceding commit covers with a functional test\n\nThis addresses part of #14278."
  }
 ],
 "timeline": [
  {
   "t": "2026-07-23T19:03:56Z",
   "kind": "force_push",
   "who": "fernandguil",
   "commit": "f928735284dc76fdefa0af8d3d9613a5f88f1816"
  },
  {
   "t": "2026-07-24T10:15:47Z",
   "kind": "review_comment",
   "who": "sedited",
   "assoc": "CONTRIBUTOR",
   "path": "doc/zmq.md",
   "commit": "f928735284dc76fdefa0af8d3d9613a5f88f1816",
   "in_reply_to": null,
   "text": "I would suggest collapsing this into:\n\n```\nA transaction removal notification (`R`) is sent for all removals **except** block\ninclusion. Subscribers can learn about those via the `rawblock` or `hashblock` topics.\n```"
  },
  {
   "t": "2026-07-24T10:24:13Z",
   "kind": "review_comment",
   "who": "sedited",
   "assoc": "CONTRIBUTOR",
   "path": "doc/zmq.md",
   "commit": "f928735284dc76fdefa0af8d3d9613a5f88f1816",
   "in_reply_to": null,
   "text": "I would only claim this in the docs, if there is a corresponding functional test exercising this."
  },
  {
   "t": "2026-08-13T00:37:40Z",
   "kind": "force_push",
   "who": "fernandguil",
   "commit": "1af2626698b2fad9309223c2597f537fc9770c7a"
  },
  {
   "t": "2026-08-28T03:43:31Z",
   "kind": "force_push",
   "who": "fernandguil",
   "commit": "112a171179956c376428fec480f24cb97955b0ca"
  }
 ],
 "labels_log": [
  {
   "t": "2026-06-07T18:06:57Z",
   "action": "labeled",
   "label": "Docs",
   "who": "DrahtBot"
  }
 ],
 "state_log": [],
 "text_chars": 2550,
 "text_tokens_estimate": 637,
 "changed_paths": [
  "doc/zmq.md",
  "test/functional/interface_zmq.py"
 ],
 "files": [
  {
   "path": "doc/zmq.md",
   "add": 15,
   "del": 0
  },
  {
   "path": "test/functional/interface_zmq.py",
   "add": 59,
   "del": 0
  }
 ],
 "test_lines": 59,
 "git": {
  "head": "112a171179956c376428fec480f24cb97955b0ca",
  "head_matches_backup": true,
  "base": "ea7d459ac08b05521021e3d273625424e1b9b19e",
  "commits": [
   {
    "sha": "6379cce4eb",
    "subject": "test: check 'sequence' notification ordering during a reorg",
    "files": 1,
    "add": 59,
    "del": 0
   },
   {
    "sha": "112a171179",
    "subject": "doc: document ZMQ notification behavior during reorgs and evictions",
    "files": 1,
    "add": 15,
    "del": 0
   }
  ],
  "patch_truncated": false
 },
 "input_hash": "0548f29352c3455a",
 "extracted_at": "2026-09-17T16:15:31+00:00"
}