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 and AI policy for information on the review process.

Type Reviewers

ACK sedited

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.
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.

Type	Reviewers
ACK	sedited

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.
sedited approved
sedited commented at 1:06 PM on July 23, 2026: contributor

ACK 5801ce70b34b5429ed184645daf85b2fb2ab7200
sedited referenced this in commit d5e64b01e1 on Aug 27, 2026
sedited referenced this in commit da1cb4dd90 on Aug 27, 2026
sedited requested review from willcl-ark on Sep 9, 2026
willcl-ark commented at 12:00 PM on September 15, 2026: member

I will take a look here soon.

I 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

I 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...

edit: 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
sedited commented at 8:27 AM on September 16, 2026: contributor

I 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...

I'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.
willcl-ark commented at 10:18 AM on September 16, 2026: member

I'm not sure if we really want to guarantee order. It just seems like a brittle thing to be promising.

Agreed, and ordering (or really any notification legitimacy) is called out here in my branch as basically never being guaranteed:

Bitcoin Core can notify external software about node, chain, mempool, wallet, and warning events. Notifications are useful for waking up external processes, but they are not a substitute for querying the node for current state. When a notification is received, use the RPC interface to confirm the state that is relevant to the application.

The tested guarantees I was talking about are here as standalone commits.

Contributors

Review Requested
willcl-ark

Labels

Docs

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