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 +64 −0
  1. 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.

  2. doc: document -blocknotify, -walletnotify and other -*notify options
    Adds doc/notifications.md describing the shell command notification
    options (-blocknotify, -walletnotify, -alertnotify, -startupnotify,
    -shutdownnotify), including behavior that is implemented but not
    documented anywhere outside the source:
    
    - -blocknotify is suppressed during initial block download/reindex
    - per-event commands run in detached threads with no ordering guarantee
    - -walletnotify fires on mempool entry, confirmation, and conflict
    - -shutdownnotify commands run in parallel and block shutdown until done
    
    Partially addresses #14278.
    5a1e1d4a13
  3. DrahtBot added the label Docs on Jun 12, 2026
  4. DrahtBot commented at 3:27 AM on June 12, 2026: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    <!--006a51241073e994b41acfe9ec718e94-->

    Code Coverage & Benchmarks

    For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35518.

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

    See the guideline for information on the review process. A summary of reviews will appear here.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->


github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-06-13 21:30 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me