From 1a1378b96f71c4ec600462184d32d3c87db6acd1 Mon Sep 17 00:00:00 2001
From: MarcoFalke <falke.marco@gmail.com>
Date: Tue, 13 Nov 2018 12:34:43 -0500
Subject: [PATCH] Merge #14530: Use RPCHelpMan to generate RPC doc strings

fa483e13b3 rpc: Add RPCHelpMan for machine-generated help (MarcoFalke)
fa0d36f712 rpc: Include rpc/util.h where needed for RPCHelpMan (MarcoFalke)

Pull request description:

  This introduces a manager for the RPC help generation and demonstrates its use of it in some RPCs.

  It is the first non-exhaustive step toward #14378 and I will create pull requests for the next steps after this one is merged.

Tree-SHA512: 86f68322443ff01cd964aaf0ebe186be63fbebe4c47676cf7a622cc2b5305fd176bd57badfd1bbf788a036812253eb0dead74ecc3b30664c3e0d9392b2248054
---
 src/rpc/blockchain.cpp     |   7 +--
 src/rpc/mining.cpp         |   1 +
 src/rpc/net.cpp            |   5 +-
 src/rpc/rawtransaction.cpp |  97 +++++++++++++++++++++++++++++----
 src/rpc/server.cpp         |   3 +-
 src/rpc/util.cpp           |  92 ++++++++++++++++++++++++++++++++
 src/rpc/util.h             |  49 +++++++++++++++++
 src/wallet/rpcdump.cpp     |   9 ++--
 src/wallet/rpcwallet.cpp   | 106 +++++++++++++++++++++++++++++++++++--
 src/zmq/zmqrpc.cpp         |   1 +
 10 files changed, 346 insertions(+), 24 deletions(-)

diff --git a/src/rpc/blockchain.cpp b/src/rpc/blockchain.cpp
index fc932a8cb4..4676ac0cbf 100644
--- a/src/rpc/blockchain.cpp
+++ b/src/rpc/blockchain.cpp
@@ -14,23 +14,24 @@
 #include <coins.h>
 #include <node/coinstats.h>
 #include <core_io.h>
+#include <hash.h>
 #include <consensus/validation.h>
 #include <key_io.h>
-#include <validation.h>
 #include <index/txindex.h>
 #include <policy/feerate.h>
 #include <policy/policy.h>
 #include <primitives/transaction.h>
 #include <rpc/server.h>
+#include <rpc/util.h>
 #include <script/descriptor.h>
 #include <streams.h>
 #include <sync.h>
 #include <txdb.h>
 #include <txmempool.h>
-#include <util/system.h>
 #include <util/strencodings.h>
 #include <util/validation.h>
-#include <hash.h>
+#include <util/system.h>
+#include <validation.h>
 #include <validationinterface.h>
 #include <warnings.h>
 
diff --git a/src/rpc/mining.cpp b/src/rpc/mining.cpp
index 329960e56d..93a05d8639 100644
--- a/src/rpc/mining.cpp
+++ b/src/rpc/mining.cpp
@@ -19,6 +19,7 @@
 #include <rpc/blockchain.h>
 #include <rpc/mining.h>
 #include <rpc/server.h>
+#include <rpc/util.h>
 #include <shutdown.h>
 #include <txmempool.h>
 #include <util/fees.h>
diff --git a/src/rpc/net.cpp b/src/rpc/net.cpp
index 8dcc50084a..073f4a28d0 100644
--- a/src/rpc/net.cpp
+++ b/src/rpc/net.cpp
@@ -9,18 +9,19 @@
 #include <chainparams.h>
 #include <clientversion.h>
 #include <core_io.h>
-#include <validation.h>
 #include <net.h>
 #include <net_processing.h>
 #include <net_permissions.h>
 #include <netbase.h>
 #include <policy/policy.h>
 #include <rpc/protocol.h>
+#include <rpc/util.h>
 #include <sync.h>
 #include <timedata.h>
 #include <ui_interface.h>
-#include <util/system.h>
 #include <util/strencodings.h>
+#include <util/system.h>
+#include <validation.h>
 #include <version.h>
 #include <warnings.h>
 
diff --git a/src/rpc/rawtransaction.cpp b/src/rpc/rawtransaction.cpp
index 40504421e9..e6e2217148 100644
--- a/src/rpc/rawtransaction.cpp
+++ b/src/rpc/rawtransaction.cpp
@@ -10,19 +10,18 @@
 #include <consensus/validation.h>
 #include <core_io.h>
 #include <index/txindex.h>
-#include <keystore.h>
-#include <validation.h>
-#include <validationinterface.h>
+#include <init.h>
 #include <key_io.h>
+#include <keystore.h>
 #include <merkleblock.h>
 #include <net.h>
 #include <node/transaction.h>
 #include <policy/policy.h>
 #include <primitives/transaction.h>
 #include <psbt.h>
-#include <rpc/util.h>
 #include <rpc/rawtransaction.h>
 #include <rpc/server.h>
+#include <rpc/util.h>
 #include <script/script.h>
 #include <script/script_error.h>
 #include <script/sign.h>
@@ -31,6 +30,8 @@
 #include <uint256.h>
 #include <util/validation.h>
 #include <util/strencodings.h>
+#include <validation.h>
+#include <validationinterface.h>
 #ifdef ENABLE_WALLET
 #include <wallet/rpcwallet.h>
 #endif
@@ -251,7 +252,16 @@ static UniValue gettxoutproof(const JSONRPCRequest& request)
 {
     if (request.fHelp || (request.params.size() != 1 && request.params.size() != 2))
         throw std::runtime_error(
-            "gettxoutproof [\"txid\",...] ( blockhash )\n"
+            RPCHelpMan{"gettxoutproof",
+                {
+                    {"txids", RPCArg::Type::ARR,
+                        {
+                            {"txid", RPCArg::Type::STR_HEX, false},
+                        },
+                        false},
+                    {"blockhash", RPCArg::Type::STR_HEX, true},
+                }}
+                .ToString() +
             "\nReturns a hex-encoded proof that \"txid\" was included in a block.\n"
             "\nNOTE: By default this function only works sometimes. This is when there is an\n"
             "unspent output in the utxo for this transaction. To make it always work,\n"
@@ -672,10 +682,17 @@ static void TxInErrorToJSON(const CTxIn& txin, UniValue& vErrorsRet, const std::
 
 static UniValue combinerawtransaction(const JSONRPCRequest& request)
 {
-
     if (request.fHelp || request.params.size() != 1)
         throw std::runtime_error(
-            "combinerawtransaction [\"hexstring\",...]\n"
+            RPCHelpMan{"combinerawtransaction",
+                {
+                    {"txs", RPCArg::Type::ARR,
+                        {
+                            {"hexstring", RPCArg::Type::STR_HEX, false},
+                        },
+                        false},
+                }}
+                .ToString() +
             "\nCombine multiple partially signed transactions into one transaction.\n"
             "The combined transaction may be another partially signed transaction or a \n"
             "fully signed transaction."
@@ -892,7 +909,30 @@ static UniValue signrawtransactionwithkey(const JSONRPCRequest& request)
 {
     if (request.fHelp || request.params.size() < 2 || request.params.size() > 4)
         throw std::runtime_error(
-            "signrawtransactionwithkey \"hexstring\" [\"privatekey1\",...] ( [{\"txid\":\"id\",\"vout\":n,\"scriptPubKey\":\"hex\",\"redeemScript\":\"hex\"},...] sighashtype )\n"
+            RPCHelpMan{"signrawtransactionwithkey",
+                {
+                    {"hexstring", RPCArg::Type::STR, false},
+                    {"privkyes", RPCArg::Type::ARR,
+                        {
+                            {"privatekey", RPCArg::Type::STR_HEX, false},
+                        },
+                        false},
+                    {"prevtxs", RPCArg::Type::ARR,
+                        {
+                            {"", RPCArg::Type::OBJ,
+                                {
+                                    {"txid", RPCArg::Type::STR_HEX, false},
+                                    {"vout", RPCArg::Type::NUM, false},
+                                    {"scriptPubKey", RPCArg::Type::STR_HEX, false},
+                                    {"redeemScript", RPCArg::Type::STR_HEX, false},
+                                    {"amount", RPCArg::Type::AMOUNT, false},
+                                },
+                                true},
+                        },
+                        true},
+                    {"sighashtype", RPCArg::Type::STR, true},
+                }}
+                .ToString() +
             "\nSign inputs for raw transaction (serialized, hex-encoded).\n"
             "The second argument is an array of base58-encoded private\n"
             "keys that will be the only keys used to sign the transaction.\n"
@@ -1445,7 +1485,15 @@ UniValue combinepsbt(const JSONRPCRequest& request)
 {
     if (request.fHelp || request.params.size() != 1)
         throw std::runtime_error(
-            "combinepsbt [\"psbt\",...]\n"
+            RPCHelpMan{"combinepsbt",
+                {
+                    {"txs", RPCArg::Type::ARR,
+                        {
+                            {"psbt", RPCArg::Type::STR_HEX, false},
+                        },
+                        false},
+                }}
+                .ToString() +
             "\nCombine multiple partially signed Dash transactions into one transaction.\n"
             "Implements the Combiner role.\n"
             "\nArguments:\n"
@@ -1551,7 +1599,36 @@ UniValue createpsbt(const JSONRPCRequest& request)
 {
     if (request.fHelp || request.params.size() < 2 || request.params.size() > 4)
         throw std::runtime_error(
-                            "createpsbt [{\"txid\":\"id\",\"vout\":n},...] [{\"address\":amount},{\"data\":\"hex\"},...] ( locktime )\n"
+            RPCHelpMan{"createpsbt",
+                {
+                    {"inputs", RPCArg::Type::ARR,
+                        {
+                            {"", RPCArg::Type::OBJ,
+                                {
+                                    {"txid", RPCArg::Type::STR_HEX, false},
+                                    {"vout", RPCArg::Type::NUM, false},
+                                    {"sequence", RPCArg::Type::NUM, true},
+                                },
+                                false},
+                        },
+                        false},
+                    {"outputs", RPCArg::Type::ARR,
+                        {
+                            {"", RPCArg::Type::OBJ,
+                                {
+                                    {"address", RPCArg::Type::AMOUNT, false},
+                                },
+                                true},
+                            {"", RPCArg::Type::OBJ,
+                                {
+                                    {"data", RPCArg::Type::STR_HEX, false},
+                                },
+                                true},
+                        },
+                        false},
+                    {"locktime", RPCArg::Type::NUM, true},
+                }}
+                .ToString() +
                             "\nCreates a transaction in the Partially Signed Transaction format.\n"
                             "Implements the Creator role.\n"
                             "\nArguments:\n"
diff --git a/src/rpc/server.cpp b/src/rpc/server.cpp
index cabef0c350..3967b134ef 100644
--- a/src/rpc/server.cpp
+++ b/src/rpc/server.cpp
@@ -9,11 +9,12 @@
 #include <fs.h>
 #include <key_io.h>
 #include <random.h>
+#include <rpc/util.h>
 #include <shutdown.h>
 #include <sync.h>
 #include <ui_interface.h>
-#include <util/system.h>
 #include <util/strencodings.h>
+#include <util/system.h>
 
 #include <boost/bind.hpp>
 #include <boost/signals2/signal.hpp>
diff --git a/src/rpc/util.cpp b/src/rpc/util.cpp
index 2c904b3ba5..fd36dd1ac1 100644
--- a/src/rpc/util.cpp
+++ b/src/rpc/util.cpp
@@ -93,6 +93,98 @@ UniValue DescribeAddress(const CTxDestination& dest)
     return boost::apply_visitor(DescribeAddressVisitor(), dest);
 }
 
+std::string RPCHelpMan::ToString() const
+{
+    std::string ret;
+
+    ret += m_name;
+    bool is_optional{false};
+    for (const auto& arg : m_args) {
+        ret += " ";
+        if (arg.m_optional) {
+            if (!is_optional) ret += "( ";
+            is_optional = true;
+        } else {
+            // Currently we still support unnamed arguments, so any argument following an optional argument must also be optional
+            // If support for positional arguments is deprecated in the future, remove this line
+            assert(!is_optional);
+        }
+        ret += arg.ToString();
+    }
+    if (is_optional) ret += " )";
+    ret += "\n";
+
+    return ret;
+}
+
+std::string RPCArg::ToStringObj() const
+{
+    std::string res = "\"" + m_name + "\":";
+    switch (m_type) {
+    case Type::STR:
+        return res + "\"str\"";
+    case Type::STR_HEX:
+        return res + "\"hex\"";
+    case Type::NUM:
+        return res + "n";
+    case Type::AMOUNT:
+        return res + "amount";
+    case Type::BOOL:
+        return res + "bool";
+    case Type::ARR:
+        res += "[";
+        for (const auto& i : m_inner) {
+            res += i.ToString() + ",";
+        }
+        return res + "...]";
+    case Type::OBJ:
+    case Type::OBJ_USER_KEYS:
+        // Currently unused, so avoid writing dead code
+        assert(false);
+
+        // no default case, so the compiler can warn about missing cases
+    }
+    assert(false);
+}
+
+std::string RPCArg::ToString() const
+{
+    switch (m_type) {
+    case Type::STR_HEX:
+    case Type::STR: {
+        return "\"" + m_name + "\"";
+    }
+    case Type::NUM:
+    case Type::AMOUNT:
+    case Type::BOOL: {
+        return m_name;
+    }
+    case Type::OBJ:
+    case Type::OBJ_USER_KEYS: {
+        std::string res;
+        for (size_t i = 0; i < m_inner.size();) {
+            res += m_inner[i].ToStringObj();
+            if (++i < m_inner.size()) res += ",";
+        }
+        if (m_type == Type::OBJ) {
+            return "{" + res + "}";
+        } else {
+            return "{" + res + ",...}";
+        }
+    }
+    case Type::ARR: {
+        std::string res;
+        for (const auto& i : m_inner) {
+            res += i.ToString() + ",";
+        }
+        return "[" + res + "...]";
+    }
+
+        // no default case, so the compiler can warn about missing cases
+    }
+    assert(false);
+}
+
 RPCErrorCode RPCErrorFromTransactionError(TransactionError terr)
 {
     switch (terr) {
diff --git a/src/rpc/util.h b/src/rpc/util.h
index cc0b305f0a..150c2f2050 100644
--- a/src/rpc/util.h
+++ b/src/rpc/util.h
@@ -25,6 +25,55 @@ CScript CreateMultisigRedeemscript(const int required, const std::vector<CPubKey
 
 UniValue DescribeAddress(const CTxDestination& dest);
 
+struct RPCArg {
+    enum class Type {
+        OBJ,
+        ARR,
+        STR,
+        NUM,
+        BOOL,
+        OBJ_USER_KEYS, //!< Special type where the user must set the keys e.g. to define multiple addresses; as opposed to e.g. an options object where the keys are predefined
+        AMOUNT,        //!< Special type representing a floating point amount (can be either NUM or STR)
+        STR_HEX,       //!< Special type that is a STR with only hex chars
+    };
+    const std::string m_name; //!< The name of the arg (can be empty for inner args)
+    const Type m_type;
+    const std::vector<RPCArg> m_inner; //!< Only used for arrays or dicts
+    const bool m_optional;
+
+    RPCArg(const std::string& name, const Type& type, const bool optional)
+        : m_name{name}, m_type{type}, m_optional{optional}
+    {
+        assert(type != Type::ARR && type != Type::OBJ);
+    }
+
+    RPCArg(const std::string& name, const Type& type, const std::vector<RPCArg>& inner, const bool optional)
+        : m_name{name}, m_type{type}, m_inner{inner}, m_optional{optional}
+    {
+        assert(type == Type::ARR || type == Type::OBJ);
+    }
+
+    std::string ToString() const;
+
+private:
+    std::string ToStringObj() const;
+};
+
+class RPCHelpMan
+{
+public:
+    RPCHelpMan(const std::string& name, const std::vector<RPCArg>& args)
+        : m_name{name}, m_args{args}
+    {
+    }
+
+    std::string ToString() const;
+
+private:
+    const std::string m_name;
+    const std::vector<RPCArg> m_args;
+};
+
 RPCErrorCode RPCErrorFromTransactionError(TransactionError terr);
 UniValue JSONRPCTransactionError(TransactionError terr, const std::string& err_string = "");
 
diff --git a/src/wallet/rpcdump.cpp b/src/wallet/rpcdump.cpp
index c35b16bb6e..dffd8291ac 100644
--- a/src/wallet/rpcdump.cpp
+++ b/src/wallet/rpcdump.cpp
@@ -4,17 +4,18 @@
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
 #include <chain.h>
-#include <rpc/server.h>
-#include <validation.h>
+#include <core_io.h>
 #include <key_io.h>
+#include <merkleblock.h>
+#include <rpc/server.h>
+#include <rpc/util.h>
 #include <script/script.h>
 #include <script/standard.h>
 #include <sync.h>
 #include <util/system.h>
 #include <util/time.h>
+#include <validation.h>
 #include <wallet/wallet.h>
-#include <merkleblock.h>
-#include <core_io.h>
 
 #include <wallet/rpcwallet.h>
 
diff --git a/src/wallet/rpcwallet.cpp b/src/wallet/rpcwallet.cpp
index 526a968382..d5a5dfbecd 100644
--- a/src/wallet/rpcwallet.cpp
+++ b/src/wallet/rpcwallet.cpp
@@ -2735,7 +2735,21 @@ static UniValue lockunspent(const JSONRPCRequest& request)
 
     if (request.fHelp || request.params.size() < 1 || request.params.size() > 2)
         throw std::runtime_error(
-            "lockunspent unlock ([{\"txid\":\"txid\",\"vout\":n},...])\n"
+            RPCHelpMan{"lockunspent",
+                {
+                    {"unlock", RPCArg::Type::BOOL, false},
+                    {"transactions", RPCArg::Type::ARR,
+                        {
+                            {"", RPCArg::Type::OBJ,
+                                {
+                                    {"txid", RPCArg::Type::STR_HEX, false},
+                                    {"vout", RPCArg::Type::NUM, false},
+                                },
+                                true},
+                        },
+                        true},
+                }}
+                .ToString() +
             "\nUpdates list of temporarily unspendable outputs.\n"
             "Temporarily lock (unlock=false) or unlock (unlock=true) specified transaction outputs.\n"
             "If no transaction outputs are specified when unlocking then all current locked transaction outputs are unlocked.\n"
@@ -3500,7 +3514,26 @@ static UniValue listunspent(const JSONRPCRequest& request)
 
     if (request.fHelp || request.params.size() > 5)
         throw std::runtime_error(
-            "listunspent ( minconf maxconf  [\"addresses\",...] [include_unsafe] [query_options])\n"
+            RPCHelpMan{"listunspent",
+                {
+                    {"minconf", RPCArg::Type::NUM, true},
+                    {"maxconf", RPCArg::Type::NUM, true},
+                    {"addresses", RPCArg::Type::ARR,
+                        {
+                            {"address", RPCArg::Type::STR_HEX, true},
+                        },
+                        true},
+                    {"include_unsafe", RPCArg::Type::BOOL, true},
+                    {"query_options", RPCArg::Type::OBJ,
+                        {
+                            {"minimumAmount", RPCArg::Type::AMOUNT, true},
+                            {"maximumAmount", RPCArg::Type::AMOUNT, true},
+                            {"maximumCount", RPCArg::Type::NUM, true},
+                            {"minimumSumAmount", RPCArg::Type::AMOUNT, true},
+                        },
+                        true},
+                }}
+                .ToString() +
             "\nReturns array of unspent transaction outputs\n"
             "with between minconf and maxconf (inclusive) confirmations.\n"
             "Optionally filter to only include txouts paid to specified addresses.\n"
@@ -3886,7 +3919,25 @@ UniValue signrawtransactionwithwallet(const JSONRPCRequest& request)
 
     if (request.fHelp || request.params.size() < 1 || request.params.size() > 3)
         throw std::runtime_error(
-            "signrawtransactionwithwallet \"hexstring\" ( [{\"txid\":\"id\",\"vout\":n,\"scriptPubKey\":\"hex\",\"redeemScript\":\"hex\"},...] sighashtype )\n"
+            RPCHelpMan{"signrawtransactionwithwallet",
+                {
+                    {"hexstring", RPCArg::Type::STR, false},
+                    {"prevtxs", RPCArg::Type::ARR,
+                        {
+                            {"", RPCArg::Type::OBJ,
+                                {
+                                    {"txid", RPCArg::Type::STR_HEX, false},
+                                    {"vout", RPCArg::Type::NUM, false},
+                                    {"scriptPubKey", RPCArg::Type::STR_HEX, false},
+                                    {"redeemScript", RPCArg::Type::STR_HEX, false},
+                                    {"amount", RPCArg::Type::AMOUNT, false},
+                                },
+                                false},
+                        },
+                        true},
+                    {"sighashtype", RPCArg::Type::STR, true},
+                }}
+                .ToString() +
             "\nSign inputs for raw transaction (serialized, hex-encoded).\n"
             "The second optional argument (may be null) is an array of previous transaction outputs that\n"
             "this transaction depends on but may not yet be in the block chain.\n"
@@ -4479,7 +4530,54 @@ UniValue walletcreatefundedpsbt(const JSONRPCRequest& request)
 
     if (request.fHelp || request.params.size() < 2 || request.params.size() > 6)
         throw std::runtime_error(
-                            "walletcreatefundedpsbt [{\"txid\":\"id\",\"vout\":n},...] [{\"address\":amount},{\"data\":\"hex\"},...] ( locktime ) ( options bip32derivs )\n"
+            RPCHelpMan{"walletcreatefundedpsbt",
+                {
+                    {"inputs", RPCArg::Type::ARR,
+                        {
+                            {"", RPCArg::Type::OBJ,
+                                {
+                                    {"txid", RPCArg::Type::STR_HEX, false},
+                                    {"vout", RPCArg::Type::NUM, false},
+                                    {"sequence", RPCArg::Type::NUM, false},
+                                },
+                                false},
+                        },
+                        false},
+                    {"outputs", RPCArg::Type::ARR,
+                        {
+                            {"", RPCArg::Type::OBJ,
+                                {
+                                    {"address", RPCArg::Type::AMOUNT, true},
+                                },
+                                true},
+                            {"", RPCArg::Type::OBJ,
+                                {
+                                    {"data", RPCArg::Type::STR_HEX, true},
+                                },
+                                true},
+                        },
+                        false},
+                    {"locktime", RPCArg::Type::NUM, true},
+                    {"options", RPCArg::Type::OBJ,
+                        {
+                            {"changeAddress", RPCArg::Type::STR_HEX, true},
+                            {"changePosition", RPCArg::Type::NUM, true},
+                            {"change_type", RPCArg::Type::STR, true},
+                            {"includeWatching", RPCArg::Type::BOOL, true},
+                            {"lockUnspents", RPCArg::Type::BOOL, true},
+                            {"feeRate", RPCArg::Type::NUM, true},
+                            {"subtractFeeFromOutputs", RPCArg::Type::ARR,
+                                {
+                                    {"int", RPCArg::Type::NUM, true},
+                                },
+                                true},
+                            {"conf_target", RPCArg::Type::NUM, true},
+                            {"estimate_mode", RPCArg::Type::STR, true},
+                        },
+                        true},
+                    {"bip32derivs", RPCArg::Type::BOOL, true},
+                }}
+                .ToString() +
                             "\nCreates and funds a transaction in the Partially Signed Transaction format. Inputs will be added if supplied inputs are not enough\n"
                             "Implements the Creator and Updater roles.\n"
                             "\nArguments:\n"
diff --git a/src/zmq/zmqrpc.cpp b/src/zmq/zmqrpc.cpp
index 4f88bf4eb9..d5f1619863 100644
--- a/src/zmq/zmqrpc.cpp
+++ b/src/zmq/zmqrpc.cpp
@@ -5,6 +5,7 @@
 #include <zmq/zmqrpc.h>
 
 #include <rpc/server.h>
+#include <rpc/util.h>
 #include <zmq/zmqabstractnotifier.h>
 #include <zmq/zmqnotificationinterface.h>