Merge bitcoin/bitcoin#36415: rpc: clarify preciousblock help text
What the developer wrote
Authored by merge-script
Merge bitcoin/bitcoin#36415: rpc: clarify preciousblock help text
15d092639957242d443a680d380f8df1def2bd4e rpc: clarify preciousblock help text (ViniciusCestarii)
Pull request description:
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](https://github.com/bitcoin/bitcoin/blob/69142eacd1374925cc9e4ea736c21fcec16307d0/src/validation.cpp#L3504-L3507))
- 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](https://github.com/bitcoin/bitcoin/blob/69142eacd1374925cc9e4ea736c21fcec16307d0/src/node/blockstorage.cpp#L174-L182))
This adds both points to the help text and doesn't change any behavior.
ACKs for top commit:
instagibbs:
ACK https://github.com/bitcoin/bitcoin/pull/36415/commits/15d092639957242d443a680d380f8df1def2bd4e
maflcko:
lgtm ACK 15d092639957242d443a680d380f8df1def2bd4e
Tree-SHA512: cc2bc740bb0e9ebc442b35b31b59b6f5ec56da23a555352e1491d98684d1722617e18072e05807e95be23b8a14ddd20aed01d67fae42c45cb2c788b1f999dc8a
What changed, and why it matters
This change only updates the help text shown by the preciousblock RPC command to explain more clearly when it has no effect and that it does not permanently lock the chain. No code behavior was changed.
No security action needed; this is a documentation-only clarification.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The commit adds three sentences to the preciousblock RPC help string in src/rpc/blockchain.cpp. It clarifies that the command only breaks ties between equal-work chains, has no effect if the specified block has less work than the current tip (including ancestors of the tip), and does not prevent the node from switching to a later higher-work chain. The commit message explicitly states ‘doesn’t change any behavior.’
Changed components
src/rpc/blockchain.cppInspect captured patch +3 / −0
### src/rpc/blockchain.cpp
@@ -1713,6 +1713,9 @@ static RPCMethod preciousblock()
return RPCMethod{
"preciousblock",
"Treats a block as if it were received before others with the same work.\n"
+ "\nThis only breaks ties between chains with equal work. If the specified block has the same work as the current tip, "
+ "the node switches its active chain to it. If the specified block has less work than the current tip (including any "
+ "ancestor of the tip), the call has no effect. If another chain later gains more work, the node switches to it as usual.\n"
"\nA later preciousblock call can override the effect of an earlier one.\n"
"\nThe effects of preciousblock are not retained across restarts.\n",
{Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.