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_connecthandler) - 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.