rpc: clarify preciousblock help text #36415

1. 
   ViniciusCestarii commented at 1:49 PM on October 2, 2026: contributor

   The preciousblock help says only "Treats a block as if it were received before others with the same work". This isn't wrong but could be clearer and it also leaves out cases that confuse users, including me (see discussion in #35300):

   • The call has no effect when the block has less work than the current tip, and that includes any ancestor of the tip. A successful return doesn't mean the tip changed. (code)
   • It only breaks ties between equal-work chains and doesn't pin the chain. If another chain gains more work, the node switches to it as usual. (code)

   This adds both points to the help text and doesn't change any behavior.

2. DrahtBot added the label RPC/REST/ZMQ on Oct 2, 2026
3. 
   DrahtBot commented at 1:50 PM on October 2, 2026: contributor

   <!--e57a25ab6845829454e8d69fc972939a-->

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

   <!--006a51241073e994b41acfe9ec718e94-->

   External sites

   • Code coverage & benchmarks: https://corecheck.dev/bitcoin/bitcoin/pulls/36415
   • Ralph review <img src=https://review.fish.foo/assets/bitcoin/bitcoin/36415.png alt="Ralph review status"> https://git.fish.foo/bitcoin/bitcoin/pulls/36415#author-ralph

   <!--021abf342d371248e50ceaed478a90ca-->

   Reviews

   See the guideline and AI policy for information on the review process.

   Type	Reviewers
   ACK	instagibbs, maflcko

   If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

   <!--5faf32d7da4f0f540f40219e4f7537a3-->

4. 
   maflcko commented at 2:17 PM on October 2, 2026: member

   lgtm ACK 11bd28a56796bcdabfa8644557486bef2f695529

5. rpc: clarify preciousblock help text 15d0926399
6. in src/rpc/blockchain.cpp:1716 in 11bd28a567

   1712 | @@ -1713,6 +1713,9 @@ static RPCMethod preciousblock()
   1713 |      return RPCMethod{
   1714 |          "preciousblock",
   1715 |          "Treats a block as if it were received before others with the same work.\n"
   1716 | +                "\nThis only breaks ties between chains with equal work. If the block has the same work as the current tip, "
   

   ---

   ---

   

   instagibbs commented at 5:01 PM on October 2, 2026:

   "If the submitted block"? we're talking about two blocks kinda mushed together

   ---

   

   ViniciusCestarii commented at 7:19 PM on October 2, 2026:

   Good point, Done on 15d092639957242d443a680d380f8df1def2bd4e. I used the word "specified" instead of "submitted" to avoid any confusion with submitblock.

7. ViniciusCestarii force-pushed on Oct 2, 2026
8. 
   ViniciusCestarii commented at 7:20 PM on October 2, 2026: contributor

   Thanks for the reviews. Force-pushed 15d092639957242d443a680d380f8df1def2bd4e addressing #36415 (review)

9. 
   instagibbs commented at 7:53 PM on October 2, 2026: member

   ACK https://github.com/bitcoin/bitcoin/pull/36415/commits/15d092639957242d443a680d380f8df1def2bd4e

10. DrahtBot requested review from maflcko on Oct 2, 2026
11. 
    maflcko commented at 6:58 AM on October 3, 2026: member

    lgtm ACK 15d092639957242d443a680d380f8df1def2bd4e

12. fanquake merged this on Oct 3, 2026
13. fanquake closed this on Oct 3, 2026

    ---

Contributors

ViniciusCestariiDrahtBotmaflckoinstagibbs

Review Requested
maflcko