init: point out -stopatheight may be imprecise #33993

1. 
   brunoerg commented at 6:27 am on December 2, 2025: contributor

   -stopatheight is used to stop running bitcoind after reaching a given height. However, this feature is imprecise since some blocks can still be processed during the shutdown.

   There are some previous discussions around it in #13713, #13490 and #13477. However, I’m not sure if it will get fixed since it’s undesirable to burden the validation code further with this and we can bypass this behavior by using invalidateblock to wind back. Anyway, since at this moment its behavior is imprecise I think worth mentioning it in documentation.

2. 
   DrahtBot commented at 6:27 am on December 2, 2025: 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/33993.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   ACK	rkrux, stickies-v, pablomartin4btc, jaonoctus

   If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.

   Conflicts

   No conflicts as of last run.

3. brunoerg force-pushed on Dec 2, 2025
4. DrahtBot added the label CI failed on Dec 2, 2025
5. DrahtBot removed the label CI failed on Dec 2, 2025
6. in src/init.cpp:635 in b661a551ab outdated

   631@@ -632,7 +632,7 @@ void SetupServerArgs(ArgsManager& argsman, bool can_listen_ipc)
   632     argsman.AddArg("-checkpoints", "", ArgsManager::ALLOW_ANY, OptionsCategory::HIDDEN);
   633     argsman.AddArg("-deprecatedrpc=<method>", "Allows deprecated RPC method(s) to be used", ArgsManager::ALLOW_ANY | ArgsManager::DEBUG_ONLY, OptionsCategory::DEBUG_TEST);
   634     argsman.AddArg("-stopafterblockimport", strprintf("Stop running after importing blocks from disk (default: %u)", DEFAULT_STOPAFTERBLOCKIMPORT), ArgsManager::ALLOW_ANY | ArgsManager::DEBUG_ONLY, OptionsCategory::DEBUG_TEST);
   635-    argsman.AddArg("-stopatheight", strprintf("Stop running after reaching the given height in the main chain (default: %u)", DEFAULT_STOPATHEIGHT), ArgsManager::ALLOW_ANY | ArgsManager::DEBUG_ONLY, OptionsCategory::DEBUG_TEST);
   636+    argsman.AddArg("-stopatheight", strprintf("Stop running after reaching the given height in the main chain (default: %u). It may be imprecise as shutdown is triggered at this height but additional blocks may be processed.", DEFAULT_STOPATHEIGHT), ArgsManager::ALLOW_ANY | ArgsManager::DEBUG_ONLY, OptionsCategory::DEBUG_TEST);
   

   ---

   ---

   

   l0rinc commented at 7:55 am on December 2, 2025:

   Wouldn’t it suffice to just hint that it’s not exact?

   0    argsman.AddArg("-stopatheight", strprintf("Stop running after reaching the approximate height in the main chain (default: %u). It may be imprecise as shutdown is triggered at this height but additional blocks may be processed.", DEFAULT_STOPATHEIGHT), ArgsManager::ALLOW_ANY | ArgsManager::DEBUG_ONLY, OptionsCategory::DEBUG_TEST);
   

   nit: if we’re doing this, we could adjust the code comment as well: https://github.com/bitcoin/bitcoin/blob/75d9b72475708ee0da13fb23ef65dcced805b6af/src/node/kernel_notifications.h#L52

   ---

   

   brunoerg commented at 8:51 am on December 2, 2025:

   Happy to address it if others like it but I personally don’t like “approximate” because it’s kinda subjective (could mean before or after the height) and do not reflect the goal of it. Also, this issue doesn’t happen when it’s in IBD.

   ---

   

   stickies-v commented at 11:56 am on December 2, 2025:

   “Blocks after target height may be processed during shutdown.” is a bit more concise and has my preference.
7. DrahtBot added the label Needs rebase on Dec 2, 2025
8. brunoerg force-pushed on Dec 2, 2025
9. 
   brunoerg commented at 11:48 am on December 2, 2025: contributor

   Rebased
10. stickies-v approved
11. 
    stickies-v commented at 11:56 am on December 2, 2025: contributor

    ACK e4703863655135856d0d6ad54a7021d3326bf071
12. DrahtBot removed the label Needs rebase on Dec 2, 2025
13. rkrux approved
14. 
    rkrux commented at 9:48 am on December 3, 2025: contributor

    crACK e4703863655135856d0d6ad54a7021d3326bf071

    Helpful note.

15. 
    jaonoctus commented at 9:18 pm on December 3, 2025: none

    tACK e4703863655135856d0d6ad54a7021d3326bf071

    I would love to fix the issue #13477 mentioned tho. It got closed but the issue still exists

    Updating the description is a good start tho

16. pablomartin4btc approved
17. 
    pablomartin4btc commented at 9:32 pm on December 3, 2025: member

    utACK e4703863655135856d0d6ad54a7021d3326bf071

    I’d also go with @stickies-v’s version if you have to retouch.

18. init: point out -stopatheight may be imprecise ff06e2468a
19. brunoerg force-pushed on Dec 4, 2025
20. 
    brunoerg commented at 5:53 am on December 4, 2025: contributor

    I just addressed @stickies-v’s suggestion: #33993 (review).
21. rkrux approved
22. 
    rkrux commented at 8:34 am on December 4, 2025: contributor

    re-ACK ff06e2468a5d3eeebeffe781904c34c9d1b44385
23. DrahtBot requested review from pablomartin4btc on Dec 4, 2025
24. DrahtBot requested review from stickies-v on Dec 4, 2025
25. stickies-v approved
26. 
    stickies-v commented at 11:13 am on December 4, 2025: contributor

    ACK ff06e2468a5d3eeebeffe781904c34c9d1b44385
27. pablomartin4btc approved
28. 
    pablomartin4btc commented at 12:44 pm on December 4, 2025: member

    ACK ff06e2468a5d3eeebeffe781904c34c9d1b44385
29. 
    jaonoctus commented at 5:44 pm on December 4, 2025: none

    re-ACK ff06e2468a5d3eeebeffe781904c34c9d1b44385

Contributors
brunoerg DrahtBot l0rinc stickies-v rkrux jaonoctus pablomartin4btc