rpc: Named argument support for bitcoin-cli

Usage e.g.:

    $ src/bitcoin-cli -testnet -named echo arg0="dfdf"
    [
    "dfdf"
    ]

Argument conversion also works, for arguments thus flagged in the table in
`src/rpc/client.cpp`.

    $ src/bitcoin-cli -testnet -named echojson arg0="[1,2,3]"
    [
      [
        1,
        2,
        3
      ]
    ]

Unknown parameter (detected server-side):

    $ src/bitcoin-cli -testnet -named getinfo arg0="dfdf"
    error code: -8
    error message:
    Unknown named parameter arg0

4 files changed, 156 insertions, 93 deletions

diff --git a/src/bitcoin-cli.cpp b/src/bitcoin-cli.cpp
index e9b530114c..1c330cf5ea 100644
--- a/src/bitcoin-cli.cpp
+++ b/src/bitcoin-cli.cpp
@@ -25,6 +25,7 @@
 
 static const char DEFAULT_RPCCONNECT[] = "127.0.0.1";
 static const int DEFAULT_HTTP_CLIENT_TIMEOUT=900;
+static const bool DEFAULT_NAMED=false;
 static const int CONTINUE_EXECUTION=-1;
 
 std::string HelpMessageCli()
@@ -35,6 +36,7 @@ std::string HelpMessageCli()
     strUsage += HelpMessageOpt("-conf=<file>", strprintf(_("Specify configuration file (default: %s)"), BITCOIN_CONF_FILENAME));
     strUsage += HelpMessageOpt("-datadir=<dir>", _("Specify data directory"));
     AppendParamsHelpMessages(strUsage);
+    strUsage += HelpMessageOpt("-named", strprintf(_("Pass named instead of positional arguments (default: %s)"), DEFAULT_NAMED));
     strUsage += HelpMessageOpt("-rpcconnect=<ip>", strprintf(_("Send commands to node running on <ip> (default: %s)"), DEFAULT_RPCCONNECT));
     strUsage += HelpMessageOpt("-rpcport=<port>", strprintf(_("Connect to JSON-RPC on <port> (default: %u or testnet: %u)"), BaseParams(CBaseChainParams::MAIN).RPCPort(), BaseParams(CBaseChainParams::TESTNET).RPCPort()));
     strUsage += HelpMessageOpt("-rpcwait", _("Wait for RPC server to start"));
@@ -80,6 +82,7 @@ static int AppInitRPC(int argc, char* argv[])
         if (!IsArgSet("-version")) {
             strUsage += "\n" + _("Usage:") + "\n" +
                   "  bitcoin-cli [options] <command> [params]  " + strprintf(_("Send command to %s"), _(PACKAGE_NAME)) + "\n" +
+                  "  bitcoin-cli [options] -named <command> [name=value] ... " + strprintf(_("Send command to %s (with named arguments)"), _(PACKAGE_NAME)) + "\n" +
                   "  bitcoin-cli [options] help                " + _("List commands") + "\n" +
                   "  bitcoin-cli [options] help <command>      " + _("Get help for a command") + "\n";
 
@@ -278,7 +281,14 @@ int CommandLineRPC(int argc, char *argv[])
         if (args.size() < 1)
             throw std::runtime_error("too few parameters (need at least command)");
         std::string strMethod = args[0];
-        UniValue params = RPCConvertValues(strMethod, std::vector<std::string>(args.begin()+1, args.end()));
+        args.erase(args.begin()); // Remove trailing method name from arguments vector
+
+        UniValue params;
+        if(GetBoolArg("-named", DEFAULT_NAMED)) {
+            params = RPCConvertNamedValues(strMethod, args);
+        } else {
+            params = RPCConvertValues(strMethod, args);
+        }
 
         // Execute and handle connection failures with -rpcwait
         const bool fWait = GetBoolArg("-rpcwait", false);
diff --git a/src/rpc/client.cpp b/src/rpc/client.cpp
index e094524bcb..17d1de6761 100644
--- a/src/rpc/client.cpp
+++ b/src/rpc/client.cpp
@@ -20,104 +20,120 @@ class CRPCConvertParam
 public:
     std::string methodName; //!< method whose params want conversion
     int paramIdx;           //!< 0-based idx of param to convert
+    std::string paramName;  //!< parameter name
 };
 
+/**
+ * Specifiy a (method, idx, name) here if the argument is a non-string RPC
+ * argument and needs to be converted from JSON.
+ *
+ * @note Parameter indexes start from 0.
+ */
 static const CRPCConvertParam vRPCConvertParams[] =
 {
-    { "stop", 0 },
-    { "setmocktime", 0 },
-    { "generate", 0 },
-    { "generate", 1 },
-    { "generatetoaddress", 0 },
-    { "generatetoaddress", 2 },
-    { "getnetworkhashps", 0 },
-    { "getnetworkhashps", 1 },
-    { "sendtoaddress", 1 },
-    { "sendtoaddress", 4 },
-    { "settxfee", 0 },
-    { "getreceivedbyaddress", 1 },
-    { "getreceivedbyaccount", 1 },
-    { "listreceivedbyaddress", 0 },
-    { "listreceivedbyaddress", 1 },
-    { "listreceivedbyaddress", 2 },
-    { "listreceivedbyaccount", 0 },
-    { "listreceivedbyaccount", 1 },
-    { "listreceivedbyaccount", 2 },
-    { "getbalance", 1 },
-    { "getbalance", 2 },
-    { "getblockhash", 0 },
-    { "waitforblockheight", 0 },
-    { "waitforblockheight", 1 },
-    { "waitforblock", 1 },
-    { "waitforblock", 2 },
-    { "waitfornewblock", 0 },
-    { "waitfornewblock", 1 },
-    { "move", 2 },
-    { "move", 3 },
-    { "sendfrom", 2 },
-    { "sendfrom", 3 },
-    { "listtransactions", 1 },
-    { "listtransactions", 2 },
-    { "listtransactions", 3 },
-    { "listaccounts", 0 },
-    { "listaccounts", 1 },
-    { "walletpassphrase", 1 },
-    { "getblocktemplate", 0 },
-    { "listsinceblock", 1 },
-    { "listsinceblock", 2 },
-    { "sendmany", 1 },
-    { "sendmany", 2 },
-    { "sendmany", 4 },
-    { "addmultisigaddress", 0 },
-    { "addmultisigaddress", 1 },
-    { "createmultisig", 0 },
-    { "createmultisig", 1 },
-    { "listunspent", 0 },
-    { "listunspent", 1 },
-    { "listunspent", 2 },
-    { "getblock", 1 },
-    { "getblockheader", 1 },
-    { "gettransaction", 1 },
-    { "getrawtransaction", 1 },
-    { "createrawtransaction", 0 },
-    { "createrawtransaction", 1 },
-    { "createrawtransaction", 2 },
-    { "signrawtransaction", 1 },
-    { "signrawtransaction", 2 },
-    { "sendrawtransaction", 1 },
-    { "fundrawtransaction", 1 },
-    { "gettxout", 1 },
-    { "gettxout", 2 },
-    { "gettxoutproof", 0 },
-    { "lockunspent", 0 },
-    { "lockunspent", 1 },
-    { "importprivkey", 2 },
-    { "importaddress", 2 },
-    { "importaddress", 3 },
-    { "importpubkey", 2 },
-    { "importmulti", 0 },
-    { "importmulti", 1 },
-    { "verifychain", 0 },
-    { "verifychain", 1 },
-    { "keypoolrefill", 0 },
-    { "getrawmempool", 0 },
-    { "estimatefee", 0 },
-    { "estimatepriority", 0 },
-    { "estimatesmartfee", 0 },
-    { "estimatesmartpriority", 0 },
-    { "prioritisetransaction", 1 },
-    { "prioritisetransaction", 2 },
-    { "setban", 2 },
-    { "setban", 3 },
-    { "setnetworkactive", 0 },
-    { "getmempoolancestors", 1 },
-    { "getmempooldescendants", 1 },
+    { "setmocktime", 0, "timestamp" },
+    { "generate", 0, "nblocks" },
+    { "generate", 1, "maxtries" },
+    { "generatetoaddress", 0, "nblocks" },
+    { "generatetoaddress", 2, "maxtries" },
+    { "getnetworkhashps", 0, "nblocks" },
+    { "getnetworkhashps", 1, "height" },
+    { "sendtoaddress", 1, "amount" },
+    { "sendtoaddress", 4, "subtractfeefromamount" },
+    { "settxfee", 0, "amount" },
+    { "getreceivedbyaddress", 1, "minconf" },
+    { "getreceivedbyaccount", 1, "minconf" },
+    { "listreceivedbyaddress", 0, "minconf" },
+    { "listreceivedbyaddress", 1, "include_empty" },
+    { "listreceivedbyaddress", 2, "include_watchonly" },
+    { "listreceivedbyaccount", 0, "minconf" },
+    { "listreceivedbyaccount", 1, "include_empty" },
+    { "listreceivedbyaccount", 2, "include_watchonly" },
+    { "getbalance", 1, "minconf" },
+    { "getbalance", 2, "include_watchonly" },
+    { "getblockhash", 0, "index" },
+    { "waitforblockheight", 0, "height" },
+    { "waitforblockheight", 1, "timeout" },
+    { "waitforblock", 1, "timeout" },
+    { "waitfornewblock", 0, "timeout" },
+    { "move", 2, "amount" },
+    { "move", 3, "minconf" },
+    { "sendfrom", 2, "amount" },
+    { "sendfrom", 3, "minconf" },
+    { "listtransactions", 1, "count" },
+    { "listtransactions", 2, "from" },
+    { "listtransactions", 3, "include_watchonly" },
+    { "listaccounts", 0, "minconf" },
+    { "listaccounts", 1, "include_watchonly" },
+    { "walletpassphrase", 1, "timeout" },
+    { "getblocktemplate", 0, "template_request" },
+    { "listsinceblock", 1, "target_confirmations" },
+    { "listsinceblock", 2, "include_watchonly" },
+    { "sendmany", 1, "amounts" },
+    { "sendmany", 2, "minconf" },
+    { "sendmany", 4, "subtractfeefrom" },
+    { "addmultisigaddress", 0, "nrequired" },
+    { "addmultisigaddress", 1, "keys" },
+    { "createmultisig", 0, "nrequired" },
+    { "createmultisig", 1, "keys" },
+    { "listunspent", 0, "minconf" },
+    { "listunspent", 1, "maxconf" },
+    { "listunspent", 2, "addresses" },
+    { "getblock", 1, "verbose" },
+    { "getblockheader", 1, "verbose" },
+    { "gettransaction", 1, "include_watchonly" },
+    { "getrawtransaction", 1, "verbose" },
+    { "createrawtransaction", 0, "transactions" },
+    { "createrawtransaction", 1, "outputs" },
+    { "createrawtransaction", 2, "locktime" },
+    { "signrawtransaction", 1, "prevtxs" },
+    { "signrawtransaction", 2, "privkeys" },
+    { "sendrawtransaction", 1, "allowhighfees" },
+    { "fundrawtransaction", 1, "options" },
+    { "gettxout", 1, "n" },
+    { "gettxout", 2, "include_mempool" },
+    { "gettxoutproof", 0, "txids" },
+    { "lockunspent", 0, "unlock" },
+    { "lockunspent", 1, "transactions" },
+    { "importprivkey", 2, "rescan" },
+    { "importaddress", 2, "rescan" },
+    { "importaddress", 3, "p2sh" },
+    { "importpubkey", 2, "rescan" },
+    { "importmulti", 0, "requests" },
+    { "importmulti", 1, "options" },
+    { "verifychain", 0, "checklevel" },
+    { "verifychain", 1, "nblocks" },
+    { "keypoolrefill", 0, "newsize" },
+    { "getrawmempool", 0, "verbose" },
+    { "estimatefee", 0, "nblocks" },
+    { "estimatepriority", 0, "nblocks" },
+    { "estimatesmartfee", 0, "nblocks" },
+    { "estimatesmartpriority", 0, "nblocks" },
+    { "prioritisetransaction", 1, "priority_delta" },
+    { "prioritisetransaction", 2, "fee_delta" },
+    { "setban", 2, "bantime" },
+    { "setban", 3, "absolute" },
+    { "setnetworkactive", 0, "state" },
+    { "getmempoolancestors", 1, "verbose" },
+    { "getmempooldescendants", 1, "verbose" },
+    // Echo with conversion (For testing only)
+    { "echojson", 0, "arg0" },
+    { "echojson", 1, "arg1" },
+    { "echojson", 2, "arg2" },
+    { "echojson", 3, "arg3" },
+    { "echojson", 4, "arg4" },
+    { "echojson", 5, "arg5" },
+    { "echojson", 6, "arg6" },
+    { "echojson", 7, "arg7" },
+    { "echojson", 8, "arg8" },
+    { "echojson", 9, "arg9" },
 };
 
 class CRPCConvertTable
 {
 private:
-    std::set<std::pair<std::string, int> > members;
+    std::set<std::pair<std::string, int>> members;
+    std::set<std::pair<std::string, std::string>> membersByName;
 
 public:
     CRPCConvertTable();
@@ -125,6 +141,9 @@ public:
     bool convert(const std::string& method, int idx) {
         return (members.count(std::make_pair(method, idx)) > 0);
     }
+    bool convert(const std::string& method, const std::string& name) {
+        return (membersByName.count(std::make_pair(method, name)) > 0);
+    }
 };
 
 CRPCConvertTable::CRPCConvertTable()
@@ -135,6 +154,8 @@ CRPCConvertTable::CRPCConvertTable()
     for (unsigned int i = 0; i < n_elem; i++) {
         members.insert(std::make_pair(vRPCConvertParams[i].methodName,
                                       vRPCConvertParams[i].paramIdx));
+        membersByName.insert(std::make_pair(vRPCConvertParams[i].methodName,
+                                            vRPCConvertParams[i].paramName));
     }
 }
 
@@ -152,7 +173,6 @@ UniValue ParseNonRFCJSONValue(const std::string& strVal)
     return jVal[0];
 }
 
-/** Convert strings to command-specific RPC representation */
 UniValue RPCConvertValues(const std::string &strMethod, const std::vector<std::string> &strParams)
 {
     UniValue params(UniValue::VARR);
@@ -171,3 +191,28 @@ UniValue RPCConvertValues(const std::string &strMethod, const std::vector<std::s
 
     return params;
 }
+
+UniValue RPCConvertNamedValues(const std::string &strMethod, const std::vector<std::string> &strParams)
+{
+    UniValue params(UniValue::VOBJ);
+
+    for (const std::string &s: strParams) {
+        size_t pos = s.find("=");
+        if (pos == std::string::npos) {
+            throw(std::runtime_error("No '=' in named argument '"+s+"', this needs to be present for every argument (even if it is empty)"));
+        }
+
+        std::string name = s.substr(0, pos);
+        std::string value = s.substr(pos+1);
+
+        if (!rpcCvtTable.convert(strMethod, name)) {
+            // insert string value directly
+            params.pushKV(name, value);
+        } else {
+            // parse string as JSON, insert bool/number/object/etc. value
+            params.pushKV(name, ParseNonRFCJSONValue(value));
+        }
+    }
+
+    return params;
+}
diff --git a/src/rpc/client.h b/src/rpc/client.h
index cb7c12b129..e7cf035d8f 100644
--- a/src/rpc/client.h
+++ b/src/rpc/client.h
@@ -8,7 +8,12 @@
 
 #include <univalue.h>
 
+/** Convert positional arguments to command-specific RPC representation */
 UniValue RPCConvertValues(const std::string& strMethod, const std::vector<std::string>& strParams);
+
+/** Convert named arguments to command-specific RPC representation */
+UniValue RPCConvertNamedValues(const std::string& strMethod, const std::vector<std::string>& strParams);
+
 /** Non-RFC4627 JSON parser, accepts internal values (such as numbers, true, false, null)
  * as well as objects and arrays.
  */
diff --git a/src/rpc/misc.cpp b/src/rpc/misc.cpp
index e95f422366..01e4dee55b 100644
--- a/src/rpc/misc.cpp
+++ b/src/rpc/misc.cpp
@@ -496,8 +496,10 @@ UniValue echo(const JSONRPCRequest& request)
 {
     if (request.fHelp)
         throw runtime_error(
-            "echo \"message\" ...\n"
-            "\nSimply echo back the input arguments\n"
+            "echo|echojson \"message\" ...\n"
+            "\nSimply echo back the input arguments. This command is for testing.\n"
+            "\nThe difference between echo and echojson is that echojson has argument conversion enabled in the client-side table in"
+            "bitcoin-cli and the GUI. There is no server-side difference."
         );
 
     return request.params;
@@ -516,6 +518,7 @@ static const CRPCCommand commands[] =
     /* Not shown in help */
     { "hidden",             "setmocktime",            &setmocktime,            true,  {"timestamp"}},
     { "hidden",             "echo",                   &echo,                   true,  {"arg0","arg1","arg2","arg3","arg4","arg5","arg6","arg7","arg8","arg9"}},
+    { "hidden",             "echojson",               &echo,                  true,  {"arg0","arg1","arg2","arg3","arg4","arg5","arg6","arg7","arg8","arg9"}},
 };
 
 void RegisterMiscRPCCommands(CRPCTable &t)