rpc: add cli examples, update docs #31958

1. 
   rkrux commented at 12:24 pm on February 27, 2025: contributor

   add cli example for walletcreatefundedpsbt and createpsbt RPCs

   The only example present earlier was one that creates an OP_RETURN output. This lack of examples has discouraged me earlier to use this RPC. Adding an example that creates PSBT sending bitcoin to address, a scenario that is much more common.

   rpc: update the doc for data field in outputs argument

   It was not evident to me that this field creates an OP_RETURN output until I read the code and tried it out. Thus, making the doc explicitly mention it. This affects docs of the following RPCs: bumpfee, psbtbumpfee, send, walletcreatefundedpsbt, createpsbt, and createrawtransaction

2. 
   DrahtBot commented at 12:24 pm on February 27, 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/31958.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   ACK	sipa, 1440000bytes, achow101
   Concept ACK	Chand-ra, ryanofsky
   Stale ACK	i-am-yuvi, musaHaruna

   If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

   Conflicts

   Reviewers, this pull request conflicts with the following ones:

   • #21283 (Implement BIP 370 PSBTv2 by achow101)

   If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

3. DrahtBot added the label RPC/REST/ZMQ on Feb 27, 2025
4. 
   i-am-yuvi commented at 5:00 pm on February 28, 2025: contributor

   ACK 52c66d9166b97f0a375d3accdd94eb5e9154862f
5. in src/wallet/rpc/spend.cpp:1732 in 52c66d9166 outdated

   1728@@ -1729,8 +1729,12 @@ RPCHelpMan walletcreatefundedpsbt()
   1729                     }
   1730                                 },
   1731                                 RPCExamples{
   1732-                            "\nCreate a transaction with no inputs\n"
   1733+                            "\nCreate a PSBT with a specified input and an OP_RETURN output:\n"
   

   ---

   ---

   

   luke-jr commented at 4:01 pm on March 1, 2025:

   We shouldn’t be encouraging this in the first place. Suggest replacing the example with yours.

   ---

   

   rkrux commented at 9:44 am on March 3, 2025:

   I tend to agree, updated.
6. rpc: add cli example for `walletcreatefundedpsbt` RPC

   The only example present earlier was one that creates an OP_RETURN output. This
   lack of examples has discouraged me earlier to use this RPC. Adding an example
   that creates PSBT sending bitcoin to address, a scenario that is much more common.

   8134a6b5d4
7. rkrux force-pushed on Mar 3, 2025
8. 
   rkrux commented at 9:46 am on March 3, 2025: contributor

   Updated example output of walletcreatefundedpsbt RPC:

   0Examples:
   1
   2Create a PSBT with automatically picked inputs that sends 0.5 BTC to an address and has a fee rate of 2 sat/vB:
   3> bitcoin-cli walletcreatefundedpsbt "[]" "[{\"bc1q09vm5lfy0j5reeulh4x5752q25uqqvz34hufdl\":0.5}]" 0 "{\"add_inputs\":true,\"fee_rate\":2}"
   4
   5Create the same PSBT as the above one instead using named arguments:
   6> bitcoin-cli -named walletcreatefundedpsbt outputs="[{\"bc1q09vm5lfy0j5reeulh4x5752q25uqqvz34hufdl\":0.5}]" add_inputs=true fee_rate=2
   

9. 
   1440000bytes commented at 4:20 pm on March 3, 2025: none

   ACK https://github.com/bitcoin/bitcoin/pull/31958/commits/0ad066c85a46208041f816d4edba36e8712763e9

   Related PR: https://github.com/bitcoin/bitcoin/pull/27454

10. luke-jr referenced this in commit f522476cea on Mar 5, 2025
11. luke-jr referenced this in commit 9b8ff735a9 on Mar 5, 2025
12. 
    Chand-ra commented at 4:42 pm on March 17, 2025: none

    Concept ACK 8134a6

    The proposed changes do improve the readability of the documentation.

13. rpc: update the doc for `data` field in `outputs` argument

    This affects docs of the following RPCs:
    `bumpfee`, `psbtbumpfee`, `send`, `walletcreatefundedpsbt`, `createpsbt`,
    and `createrawtransaction`
    
    It was not evident to me that this field creates an `OP_RETURN` output until
    I read the code and tried it out. Thus, making the doc explicitly mention it.

    931117a46f
14. rpc: update RPC help of `createpsbt`

    Update the example wherein the PSBT sends bitcoin to an address instead
    of creating an OP_RETURN output. Also, update the RPC description to
    reflect the fact that the created transaction is unsigned.

    32dcec269b
15. rkrux force-pushed on Mar 26, 2025
16. 
    ryanofsky commented at 2:53 pm on April 1, 2025: contributor

    Concept ACK 32dcec269bf33f7be28245d88a1d8f2889cc39ae. These seem like helpful clarifications, but I did not look into the details
17. 
    musaHaruna commented at 9:14 pm on April 9, 2025: none

    ACK 931117a

    I will test and try it out soon, But from what I understand on a conceptual level if am not wrong,

    All the mentioned RPCs—bumpfee, psbtbumpfee, send, walletcreatefundedpsbt, createpsbt, and createrawtransaction—share a common behavior for the outputs. i.e Whenever the outputs object includes a key “data”, the RPC will treat its value as hex-encoded data for an OP_RETURN output. That how those mentioned RPC’s (docs) are affected as mentioned in the PR’s description. Please correct me if am wrong.

18. 
    rkrux commented at 10:17 am on April 11, 2025: contributor

    Re: #31958#pullrequestreview-2754830624

    Yes, that’s correct.

19. 
    sipa commented at 11:41 am on April 11, 2025: member

    utACK 32dcec269bf33f7be28245d88a1d8f2889cc39ae
20. DrahtBot requested review from ryanofsky on Apr 11, 2025
21. DrahtBot requested review from musaHaruna on Apr 11, 2025
22. DrahtBot requested review from 1440000bytes on Apr 11, 2025
23. 
    1440000bytes commented at 4:28 pm on April 15, 2025: none

    utACK https://github.com/bitcoin/bitcoin/pull/31958/commits/32dcec269bf33f7be28245d88a1d8f2889cc39ae

    #31958#pullrequestreview-2654617253

24. 
    achow101 commented at 8:05 pm on April 16, 2025: member

    ACK 32dcec269bf33f7be28245d88a1d8f2889cc39ae
25. achow101 merged this on Apr 16, 2025
26. achow101 closed this on Apr 16, 2025

    ---

Contributors
rkrux DrahtBot i-am-yuvi luke-jr 1440000bytes Chand-ra ryanofsky musaHaruna sipa achow101

Review Requested
ryanofsky musaHaruna 1440000bytes

Labels
RPC/REST/ZMQ