rpc: fix/add missing RPCExamples for “Util” RPCs #18448

1. 
   theStack commented at 12:57 pm on March 27, 2020: member

   Similar to #18398, this PR gives the RPCExamples in the RPC category “Util” (that currently contains createmultisig, deriveaddresses, estimatesmartfee, getdescriptorinfo, signmessagewithprivkey, validateaddress, verifymessage) some love by fixing one broken and adding three missing examples:

   • fixed HelpExampleRpc for createmultisig (disturbing escape characters and quotation marks)
   • added missing HelpExampleRpc for
     • deriveaddresses (also put descriptor in a new string constant)
     • estimatesmartfee
     • getdescriptorinfo (also put descriptor in a new string constant)

   Output for createmultisig example on the master branch:

   0$ curl --user __cookie__ --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "createmultisig", "params": [2, "[\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\",\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\"]"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
   1Enter host password for user '__cookie__':
   2{"result":null,"error":{"code":-1,"message":"JSON value is not an array as expected"},"id":"curltest"}
   

   Output for createmultisig example on the PR branch:

   0$ curl --user __cookie__ --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "createmultisig", "params": [2, ["03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd","03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626"]]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
   1Enter host password for user '__cookie__':
   2{"result":{"address":"3QsFXpFJf2ZY6GLWVoNFFd2xSDwdS713qX","redeemScript":"522103789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd2103dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a6162652ae","descriptor":"sh(multi(2,03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd,03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626))#4djp057k"},"error":null,"id":"curltest"}
   

2. fanquake added the label RPC/REST/ZMQ on Mar 27, 2020
3. in src/rpc/misc.cpp:183 in d99a24d35b outdated

   179@@ -177,6 +180,8 @@ UniValue getdescriptorinfo(const JSONRPCRequest& request)
   180 
   181 UniValue deriveaddresses(const JSONRPCRequest& request)
   182 {
   183+    const std::string EXAMPLE_DESCRIPTOR = "\"wpkh([d34db33f/84h/0h/0h]xpub6DJ2dNUysrn5Vt36jH2KLBT2i1auw1tTSSomg8PhqNiUtx8QX2SvC9nrHu81fT41fvDUnhMjEzQgXnQjKEu3oaqMSzhSrHMxyyoEAmUHQbY/0/*)#cjjspncu\"";
   

   ---

   ---

   

   MarcoFalke commented at 3:26 pm on March 27, 2020:

   This shouldn’t include the escaped “, similar to EXAMPLE_ADDRESS https://doxygen.bitcoincore.org/util_8cpp.html#adbb21c6828f59f3df79b3d25c0821635

   Reason is that the examples might be auto-generated in the future.

   ---

   

   theStack commented at 3:43 pm on March 27, 2020:

   Thanks for the hint, done.
4. theStack force-pushed on Mar 27, 2020
5. 
   laanwj commented at 12:46 pm on April 1, 2020: member

   I sometimes wonder if these couldn’t be generated from the same source data. This is a lot of repetition. In any case, LGTM ACK 55d30ac144f1c477763d7eeaba23d52c9db53b36
6. 
   MarcoFalke commented at 3:48 pm on April 1, 2020: member

   Two observations:

   • The examples should be auto-generated. In fact I have code for this, but not yet submitted.
   • The fix seems to change the format of two calls, but leaves all other calls at the same (broken?) syntax. I’d say to fix all of them, but maybe it should just wait until they are auto-generated?
7. 
   theStack commented at 4:16 pm on April 1, 2020: member

   Automatic generation of RPCExamples would definitely be nice. It should also be possible to automatically test the provided examples to some extent. Maybe I find time to come up with a script the next days to do this. @MarcoFalke: My rough plan was to divide it up to one PR per RPC category (with the categories “Blockchain”, “Control”, “Generating”, “Mining”, “Control”, “Generating”, “Mining”, “Network”, “Rawtransactions”, “Util”, “Wallet”), where in each PR all RPCExamples of one (or two, if they are small ones) category are thoroughly reviewed, tested and fixed or extended when needed. So it could also be done by different people (maybe a good first issue also?). I assumed that creating a mega-PR with changing all broken RPCExamples would be too high of a review burden, since that would likely contain dozens of fixes/additions.

   Whether it’s auto-generated or not, I think for potential users it’s annoying when provided examples just don’t work. Call me pedantic, but in doubt I’d even rather prefer to have no example than a broken one.

8. 
   DrahtBot commented at 8:07 pm on April 5, 2020: member

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

   Conflicts

   No conflicts as of last run.

9. DrahtBot added the label Needs rebase on Aug 14, 2020
10. rpc: fix/add missing RPCExamples for "Util" RPCs

    fixes HelpExampleRpc for
        - createmultisig
    
    adds missing HelpExampleRpc for
        - deriveaddresses
        - estimatesmartfee
        - getdescriptorinfo

    ea98d9c2ef
11. theStack force-pushed on Aug 14, 2020
12. 
    theStack commented at 10:24 am on August 14, 2020: member

    Rebased.
13. DrahtBot removed the label Needs rebase on Aug 14, 2020
14. 
    jonatack commented at 5:21 pm on April 18, 2021: member

    ACK ea98d9c2eff86e6537f35ac4381ac169daacde36 looked at the code, rebased to master, ran the helps, did not try running the added json-rpc examples

    before / after

    0Examples:
    1> bitcoin-cli estimatesmartfee 6
    2
    3Examples:
    4> bitcoin-cli estimatesmartfee 6
    5> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "estimatesmartfee", "params": [6]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
    

     0Examples:
     1
     2Create a multisig address from 2 public keys
     3> bitcoin-cli createmultisig 2 "[\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\",\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\"]"
     4
     5As a JSON-RPC call
     6> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "createmultisig", "params": [2, "[\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\",\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\"]"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
     7
     8
     9Examples:
    10
    11Create a multisig address from 2 public keys
    12> bitcoin-cli createmultisig 2 "[\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\",\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\"]"
    13
    14As a JSON-RPC call
    15> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "createmultisig", "params": [2, ["03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd","03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626"]]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
    

    0Examples:
    1Analyse a descriptor
    2> bitcoin-cli getdescriptorinfo "wpkh([d34db33f/84h/0h/0h]0279be667ef9dcbbac55a06295Ce870b07029Bfcdb2dce28d959f2815b16f81798)"
    3
    4Examples:
    5Analyse a descriptor
    6> bitcoin-cli getdescriptorinfo "wpkh([d34db33f/84h/0h/0h]0279be667ef9dcbbac55a06295Ce870b07029Bfcdb2dce28d959f2815b16f81798)"
    7> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getdescriptorinfo", "params": ["wpkh([d34db33f/84h/0h/0h]0279be667ef9dcbbac55a06295Ce870b07029Bfcdb2dce28d959f2815b16f81798)"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
    

    0Examples:
    1First three native segwit receive addresses
    2> bitcoin-cli deriveaddresses "wpkh([d34db33f/84h/0h/0h]xpub6DJ2dNUysrn5Vt36jH2KLBT2i1auw1tTSSomg8PhqNiUtx8QX2SvC9nrHu81fT41fvDUnhMjEzQgXnQjKEu3oaqMSzhSrHMxyyoEAmUHQbY/0/*)#cjjspncu" "[0,2]"
    3
    4Examples:
    5First three native segwit receive addresses
    6> bitcoin-cli deriveaddresses "wpkh([d34db33f/84h/0h/0h]xpub6DJ2dNUysrn5Vt36jH2KLBT2i1auw1tTSSomg8PhqNiUtx8QX2SvC9nrHu81fT41fvDUnhMjEzQgXnQjKEu3oaqMSzhSrHMxyyoEAmUHQbY/0/*)#cjjspncu" "[0,2]"
    7> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "deriveaddresses", "params": ["wpkh([d34db33f/84h/0h/0h]xpub6DJ2dNUysrn5Vt36jH2KLBT2i1auw1tTSSomg8PhqNiUtx8QX2SvC9nrHu81fT41fvDUnhMjEzQgXnQjKEu3oaqMSzhSrHMxyyoEAmUHQbY/0/*)#cjjspncu", "[0,2]"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
    

    The examples are a bit inconsistent in titles and line spacing; can also be done if auto-generating them.

15. 
    fanquake commented at 3:29 am on September 2, 2021: member

    @MarcoFalke is / should this be merged now.
16. 
    MarcoFalke commented at 4:04 pm on September 2, 2021: member

    rendered diff:

     0diff --git a/createmultisig b/createmultisig
     1index aff8a24..2552278 100644
     2--- a/createmultisig
     3+++ b/createmultisig
     4@@ -25,4 +25,4 @@ Create a multisig address from 2 public keys
     5 > bitcoin-cli createmultisig 2 "[\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\",\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\"]"
     6 
     7 As a JSON-RPC call
     8-> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "createmultisig", "params": [2, "[\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\",\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\"]"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
     9+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "createmultisig", "params": [2, ["03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd","03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626"]]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
    10diff --git a/deriveaddresses b/deriveaddresses
    11index 1920545..eedaee4 100644
    12--- a/deriveaddresses
    13+++ b/deriveaddresses
    14@@ -24,3 +24,4 @@ Result:
    15 Examples:
    16 First three native segwit receive addresses
    17 > bitcoin-cli deriveaddresses "wpkh([d34db33f/84h/0h/0h]xpub6DJ2dNUysrn5Vt36jH2KLBT2i1auw1tTSSomg8PhqNiUtx8QX2SvC9nrHu81fT41fvDUnhMjEzQgXnQjKEu3oaqMSzhSrHMxyyoEAmUHQbY/0/*)#cjjspncu" "[0,2]"
    18+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "deriveaddresses", "params": ["wpkh([d34db33f/84h/0h/0h]xpub6DJ2dNUysrn5Vt36jH2KLBT2i1auw1tTSSomg8PhqNiUtx8QX2SvC9nrHu81fT41fvDUnhMjEzQgXnQjKEu3oaqMSzhSrHMxyyoEAmUHQbY/0/*)#cjjspncu", "[0,2]"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
    19diff --git a/estimatesmartfee b/estimatesmartfee
    20index 0ac5eed..3c4d849 100644
    21--- a/estimatesmartfee
    22+++ b/estimatesmartfee
    23@@ -33,3 +33,4 @@ Result:
    24 
    25 Examples:
    26 > bitcoin-cli estimatesmartfee 6
    27+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "estimatesmartfee", "params": [6]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
    28diff --git a/getdescriptorinfo b/getdescriptorinfo
    29index d04f048..09448c5 100644
    30--- a/getdescriptorinfo
    31+++ b/getdescriptorinfo
    32@@ -17,3 +17,4 @@ Result:
    33 Examples:
    34 Analyse a descriptor
    35 > bitcoin-cli getdescriptorinfo "wpkh([d34db33f/84h/0h/0h]0279be667ef9dcbbac55a06295Ce870b07029Bfcdb2dce28d959f2815b16f81798)"
    36+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getdescriptorinfo", "params": ["wpkh([d34db33f/84h/0h/0h]0279be667ef9dcbbac55a06295Ce870b07029Bfcdb2dce28d959f2815b16f81798)"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
    

17. MarcoFalke merged this on Sep 2, 2021
18. MarcoFalke closed this on Sep 2, 2021

    ---

19. sidhujag referenced this in commit 5ce8996590 on Sep 4, 2021
20. DrahtBot locked this on Sep 2, 2022

Contributors
theStack MarcoFalke laanwj DrahtBot jonatack fanquake

Labels
RPC/REST/ZMQ