doc: document -blocknotify, -walletnotify and other -*notify options #35518

pull fernandguil wants to merge 1 commits into bitcoin:master from fernandguil:doc/notify-options changing 2 files +21 −0

fernandguil commented at 3:27 AM on June 12, 2026: contributor
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.

Adds doc/notifications.md (indexed in doc/README.md) covering:

-blocknotify
- Suppressed during initial block download and reindex — only fires once the node reaches the post-init sync state (src/init.cpp, NotifyBlockTip_connect handler)
- Each event runs the command in a detached thread, so there is no ordering guarantee between successive notifications — this directly documents the behavior behind the ordering question raised in #14278 and the test discrepancy noted in #14275
-walletnotify
- Fires on mempool entry, confirmation, and when a transaction returns to unconfirmed due to a conflict with a newly connected block (CWallet::transactionRemovedFromMempool)
- Documents all four substitutions (%s, %b, %h, %w) and the Windows limitation for %w
-alertnotify
- Fires once per distinct warning condition; message is sanitized and single-quoted before substitution (src/node/kernel_notifications.cpp)
-startupnotify / -shutdownnotify
- 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)
All described behavior is derived directly from the source.
DrahtBot added the label Docs on Jun 12, 2026
DrahtBot commented at 3:27 AM on June 12, 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/35518.



Reviews

See the guideline for information on the review process. A summary of reviews will appear here.
sedited commented at 7:40 PM on June 21, 2026: contributor

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.
fernandguil force-pushed on Jun 23, 2026
fernandguil commented at 2:11 AM on June 23, 2026: contributor

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.

in doc/notifications.md:7 in e205284b71

   0 | @@ -0,0 +1,23 @@
   1 | +# Shell Command Notifications
   2 | +
   3 | +Bitcoin Core can execute user-supplied shell commands when certain events occur,
   4 | +configured through the `-*notify` startup options. These complement the
   5 | +[ZMQ interface](zmq.md): ZMQ provides a high-volume message stream for
   6 | +programmatic consumers, while the `-*notify` options invoke an external command
   7 | +per event. They are only available on platforms built with shell command

sedited commented at 7:49 PM on June 29, 2026:

I would drop this entire sentence about zmq. This is obvious for developers that know what zmq is.

in doc/notifications.md:11 in e205284b71

   6 | +programmatic consumers, while the `-*notify` options invoke an external command
   7 | +per event. They are only available on platforms built with shell command
   8 | +support. See the `--help` output for each option's placeholders and details.
   9 | +
  10 | +Each notification (except `-shutdownnotify`) runs its command in a new detached
  11 | +thread, so commands may run concurrently and complete in any order — there is no

sedited commented at 7:51 PM on June 29, 2026:

nit: Skip the em dash. Just make this two sentences.

in doc/notifications.md:15 in e205284b71

  10 | +Each notification (except `-shutdownnotify`) runs its command in a new detached
  11 | +thread, so commands may run concurrently and complete in any order — there is no
  12 | +ordering guarantee, even within a single topic. Consumers that need consistent
  13 | +state should query the node (e.g. via RPC) rather than rely on the values passed
  14 | +to the command. `-shutdownnotify` is the exception: its commands run before
  15 | +shutdown proceeds, so they should return quickly.

sedited commented at 7:54 PM on June 29, 2026:

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.

doc: document -blocknotify, -walletnotify and other -*notify options

Adds doc/notifications.md describing the shell command notification
options (-blocknotify, -walletnotify, -alertnotify, -startupnotify,
-shutdownnotify), focusing on the cross-cutting threading and ordering
behavior that is not described in the per-option help output, plus a
list of the available options. Per-option details remain in --help.

Partially addresses #14278.

5801ce70b3

fernandguil force-pushed on Jun 30, 2026
fernandguil commented at 1:21 AM on June 30, 2026: contributor

Thanks, all good points. Done: dropped the ZMQ comparison and the -shutdownnotify "return quickly" sentence, and split the em-dash sentence in two.

Contributors

Labels

Linked (view graph)

#14275 tests: Write the notification message to different files to avoid race condition in feature_notifications.py #14278 Callback/notification documentation and cleanup #35586 doc: note -blocknotify is not run during IBD/reindex in help text

doc: document -blocknotify, -walletnotify and other -*notify options #35518

Code Coverage & Benchmarks

Reviews