{
 "number": 35518,
 "repo": "bitcoin/bitcoin",
 "url": "https://github.com/bitcoin/bitcoin/pull/35518",
 "title": "doc: document -blocknotify, -walletnotify and other -*notify options",
 "author": "fernandguil",
 "author_association": "CONTRIBUTOR",
 "created_at": "2026-06-12T03:27:33Z",
 "updated_at": "2026-09-16T10:18:12Z",
 "age_days": 97,
 "draft": false,
 "labels": [
  "Docs"
 ],
 "milestone": null,
 "base": "master",
 "head_sha": "5801ce70b34b5429ed184645daf85b2fb2ab7200",
 "head_ref": "doc/notify-options",
 "head_repo": "fernandguil/bitcoin",
 "head_history": [
  {
   "t": "2026-06-23T02:06:41Z",
   "sha": "e205284b7109f687d56365c8a6d72d66251ba567"
  },
  {
   "t": "2026-06-30T01:19:20Z",
   "sha": "5801ce70b34b5429ed184645daf85b2fb2ab7200"
  }
 ],
 "additions": 21,
 "deletions": 0,
 "changed_files": 2,
 "commit_count": 1,
 "size_bucket": "S",
 "mergeable_state": "clean",
 "bot": {
  "drahtbot": {
   "present": true,
   "reviews": {
    "ack": [
     {
      "login": "sedited",
      "url": "https://github.com/bitcoin/bitcoin/pull/35518#pullrequestreview-4764304499"
     }
    ]
   },
   "conflicts": []
  }
 },
 "acks_parsed": {
  "sedited": {
   "kind": "ack",
   "hash": "5801ce70b34b5429ed184645daf85b2fb2ab7200",
   "t": "2026-07-23T13:06:00Z",
   "stale": false
  }
 },
 "acks_tally": {
  "ack": 1,
  "stale_ack": 0,
  "concept_ack": 0,
  "approach_ack": 0,
  "nack": 0,
  "concept_nack": 0,
  "approach_nack": 0
 },
 "reviews": {
  "approved": 1,
  "changes_requested": 0,
  "distinct_reviewers": [
   "sedited",
   "willcl-ark"
  ]
 },
 "signals": {
  "needs_rebase": false,
  "ci_failed": false,
  "mergeable_state": "clean",
  "last_author_activity": "2026-06-30T01:21:13Z",
  "last_reviewer_activity": "2026-09-16T10:18:12Z",
  "last_reviewer": "willcl-ark",
  "author_silent_days": 79,
  "waiting_on_author_days": 1,
  "days_since_update": 1
 },
 "refs": {
  "mentioned": [
   14275,
   14278,
   35586
  ],
  "depends_on": [],
  "fixes": [],
  "linked_issues": [],
  "references": [
   {
    "number": 14278,
    "type": "issue",
    "state": "open",
    "merged": false,
    "merged_at": null,
    "title": "Callback/notification documentation and cleanup"
   },
   {
    "number": 14275,
    "type": "pull",
    "state": "closed",
    "merged": true,
    "merged_at": "2018-09-25",
    "title": "tests: Write the notification message to different files to avoid race condition in feature_notifications.py"
   },
   {
    "number": 35586,
    "type": "pull",
    "state": "closed",
    "merged": true,
    "merged_at": "2026-08-27",
    "title": "doc: note -blocknotify is not run during IBD/reindex in help text"
   }
  ],
  "conflicts": []
 },
 "stack": {
  "shares_commits_with": [],
  "based_on": [],
  "base_for": []
 },
 "review_paths": [
  "doc/notifications.md"
 ],
 "body": "Partially addresses #14278, which asks for documentation of the user-facing `-*notify` behaviors. The five shell-command notification options currently have no documentation outside of `--help` text, and several behaviors are only discoverable by reading the source.\n\nAdds `doc/notifications.md` (indexed in `doc/README.md`) covering:\n\n**`-blocknotify`**\n- Suppressed during initial block download and reindex \u2014 only fires once the node reaches the post-init sync state (`src/init.cpp`, `NotifyBlockTip_connect` handler)\n- Each event runs the command in a detached thread, so **there is no ordering guarantee** between successive notifications \u2014 this directly documents the behavior behind the ordering question raised in #14278 and the test discrepancy noted in #14275\n\n**`-walletnotify`**\n- Fires on mempool entry, confirmation, and when a transaction returns to unconfirmed due to a conflict with a newly connected block (`CWallet::transactionRemovedFromMempool`)\n- Documents all four substitutions (`%s`, `%b`, `%h`, `%w`) and the Windows limitation for `%w`\n\n**`-alertnotify`**\n- Fires once per distinct warning condition; message is sanitized and single-quoted before substitution (`src/node/kernel_notifications.cpp`)\n\n**`-startupnotify` / `-shutdownnotify`**\n- Startup command does not block initialization; shutdown commands may be specified multiple times, run in parallel, and shutdown waits for them to complete (`src/init.cpp`)\n\nAll described behavior is derived directly from the source.",
 "commits": [
  {
   "sha": "5801ce70b34b5429ed184645daf85b2fb2ab7200",
   "date": "2026-06-30T01:19:18Z",
   "message": "doc: document -blocknotify, -walletnotify and other -*notify options\n\nAdds doc/notifications.md describing the shell command notification\noptions (-blocknotify, -walletnotify, -alertnotify, -startupnotify,\n-shutdownnotify), focusing on the cross-cutting threading and ordering\nbehavior that is not described in the per-option help output, plus a\nlist of the available options. Per-option details remain in --help.\n\nPartially addresses #14278."
  }
 ],
 "timeline": [
  {
   "t": "2026-06-21T19:40:50Z",
   "kind": "comment",
   "who": "sedited",
   "assoc": "MEMBER",
   "text": "I don't think exhaustively documenting every command here is useful, and would prefer that the command-level docs continue to live in the help output / man page. Some of the documentation there could be expanded a bit, for example with the behaviour during IBD described here. The doc introduced here could be distilled down to a single paragraph explaining threading and ordering behaviour plus a list of the commands."
  },
  {
   "t": "2026-06-23T02:06:41Z",
   "kind": "force_push",
   "who": "fernandguil",
   "commit": "e205284b7109f687d56365c8a6d72d66251ba567"
  },
  {
   "t": "2026-06-23T02:11:55Z",
   "kind": "comment",
   "who": "fernandguil",
   "assoc": "CONTRIBUTOR",
   "text": "Thanks for the feedback. I've distilled the doc down to a single paragraph on the threading/ordering behavior plus a list of the options, leaving the per-option details in `--help`. I've also opened #35586 to add the IBD/reindex note to the `-blocknotify` help text, per your suggestion."
  },
  {
   "t": "2026-06-29T19:49:12Z",
   "kind": "review_comment",
   "who": "sedited",
   "assoc": "MEMBER",
   "path": "doc/notifications.md",
   "commit": "e205284b7109f687d56365c8a6d72d66251ba567",
   "in_reply_to": null,
   "text": "I would drop this entire sentence about zmq. This is obvious for developers that know what zmq is."
  },
  {
   "t": "2026-06-29T19:51:16Z",
   "kind": "review_comment",
   "who": "sedited",
   "assoc": "MEMBER",
   "path": "doc/notifications.md",
   "commit": "e205284b7109f687d56365c8a6d72d66251ba567",
   "in_reply_to": null,
   "text": "nit: Skip the em dash. Just make this two sentences."
  },
  {
   "t": "2026-06-29T19:54:22Z",
   "kind": "review_comment",
   "who": "sedited",
   "assoc": "MEMBER",
   "path": "doc/notifications.md",
   "commit": "e205284b7109f687d56365c8a6d72d66251ba567",
   "in_reply_to": null,
   "text": "I'm not sure I agree with this last sentence. It is already qualified that events may fire out of order, but internally they seem consistent to me. I would drop this sentence too."
  },
  {
   "t": "2026-06-30T01:19:20Z",
   "kind": "force_push",
   "who": "fernandguil",
   "commit": "5801ce70b34b5429ed184645daf85b2fb2ab7200"
  },
  {
   "t": "2026-06-30T01:21:13Z",
   "kind": "comment",
   "who": "fernandguil",
   "assoc": "CONTRIBUTOR",
   "text": "Thanks, all good points. Done: dropped the ZMQ comparison and the `-shutdownnotify` \"return quickly\" sentence, and split the em-dash sentence in two."
  },
  {
   "t": "2026-07-23T13:06:00Z",
   "kind": "review",
   "who": "sedited",
   "assoc": "MEMBER",
   "state": "APPROVED",
   "commit": "5801ce70b34b5429ed184645daf85b2fb2ab7200",
   "text": "ACK 5801ce70b34b5429ed184645daf85b2fb2ab7200"
  },
  {
   "t": "2026-09-15T12:00:57Z",
   "kind": "comment",
   "who": "willcl-ark",
   "assoc": "MEMBER",
   "text": "I will take a look here soon.\n\nI did once have a got at correcting this myself with the intention of closing out #14278 in one go, but the branch may be outdated now: https://github.com/willcl-ark/bitcoin/tree/callback-docs-cleanup\n\nI remember adding a few tests for guarantees I we were giving but were untested (see commits in the branch), that may be something we want to do here too, if it makes sense...\n\nedit: yeah re-reading my old branch I don't feel that happy with it now, I have now updated it and will compare with this branch soon"
  },
  {
   "t": "2026-09-16T08:27:14Z",
   "kind": "comment",
   "who": "sedited",
   "assoc": "MEMBER",
   "text": "[quoted text omitted]\n\nI'm not sure if we really want to guarantee order. It just seems like a brittle thing to be promising. The tests might also not fully capture the ordering guarantee. A test exercising ordering between e.g. rpc and zmq might not catch something in a different component, or in some edge case that we didn't happen to think of. Has anybody complained about this since the original issue was opened? I can also see an argument for it though: We implicitly guarantee order and unwittingly changing something might break somebody's deployment."
  },
  {
   "t": "2026-09-16T10:18:12Z",
   "kind": "comment",
   "who": "willcl-ark",
   "assoc": "MEMBER",
   "text": "[quoted text omitted]\n\nAgreed, and ordering (or really any notification legitimacy) is called out [here](https://github.com/bitcoin/bitcoin/compare/master...willcl-ark:bitcoin:callback-docs-cleanup#diff-4ed99d7ef56e26c306806d3e87483f669177e0af8c63d4bb88c63b0df327f762R3-R7) in my branch as basically never being guaranteed:\n\n[quoted text omitted]\nand warning events. Notifications are useful for waking up external processes,\nbut they are not a substitute for querying the node for current state. When a\nnotification is received, use the RPC interface to confirm the state that is\nrelevant to the application.\n\nThe tested guarantees I was talking about are [here](https://github.com/bitcoin/bitcoin/compare/master...willcl-ark:bitcoin:callback-docs-cleanup) as standalone commits."
  }
 ],
 "labels_log": [
  {
   "t": "2026-06-12T03:27:37Z",
   "action": "labeled",
   "label": "Docs",
   "who": "DrahtBot"
  }
 ],
 "state_log": [],
 "text_chars": 5136,
 "text_tokens_estimate": 1284,
 "changed_paths": [
  "doc/README.md",
  "doc/notifications.md"
 ],
 "files": [
  {
   "path": "doc/README.md",
   "add": 1,
   "del": 0
  },
  {
   "path": "doc/notifications.md",
   "add": 20,
   "del": 0
  }
 ],
 "test_lines": 0,
 "git": {
  "head": "5801ce70b34b5429ed184645daf85b2fb2ab7200",
  "head_matches_backup": true,
  "base": "e7d647388c28ffc1ebd2eab10ba67cf8e37138ed",
  "commits": [
   {
    "sha": "5801ce70b3",
    "subject": "doc: document -blocknotify, -walletnotify and other -*notify options",
    "files": 2,
    "add": 21,
    "del": 0
   }
  ],
  "patch_truncated": false
 },
 "input_hash": "d24d801eddde6b2f",
 "extracted_at": "2026-09-17T16:15:31+00:00"
}