From 1db0096f61680d2b2a9cfe454154de3ad121a9d3 Mon Sep 17 00:00:00 2001 From: MarcoFalke Date: Fri, 23 Nov 2018 11:21:38 -0500 Subject: rpc: Pass argument descriptions to RPCHelpMan --- src/rpc/blockchain.cpp | 154 +++------- src/rpc/mining.cpp | 103 +++---- src/rpc/misc.cpp | 83 +++--- src/rpc/net.cpp | 42 +-- src/rpc/rawtransaction.cpp | 330 ++++++++------------- src/rpc/server.cpp | 11 +- src/rpc/util.cpp | 198 ++++++++++++- src/rpc/util.h | 46 ++- src/wallet/rpcdump.cpp | 136 ++++----- src/wallet/rpcwallet.cpp | 708 ++++++++++++++++----------------------------- 10 files changed, 780 insertions(+), 1031 deletions(-) diff --git a/src/rpc/blockchain.cpp b/src/rpc/blockchain.cpp index e3d9357358..0eb5c2baec 100644 --- a/src/rpc/blockchain.cpp +++ b/src/rpc/blockchain.cpp @@ -212,7 +212,7 @@ static UniValue waitfornewblock(const JSONRPCRequest& request) "\nWaits for a specific new block and returns useful info about it.\n" "\nReturns the current block on timeout or exit.\n", { - {"timeout", RPCArg::Type::NUM, true}, + {"timeout", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "", ""}, }} .ToString() + "\nArguments:\n" @@ -254,13 +254,10 @@ static UniValue waitforblock(const JSONRPCRequest& request) "\nWaits for a specific new block and returns useful info about it.\n" "\nReturns the current block on timeout or exit.\n", { - {"blockhash", RPCArg::Type::STR, false}, - {"timeout", RPCArg::Type::NUM, true}, + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "Block hash to wait for."}, + {"timeout", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "0", "Time in milliseconds to wait for a response. 0 indicates no timeout."}, }} .ToString() + - "\nArguments:\n" - "1. \"blockhash\" (required, string) Block hash to wait for.\n" - "2. timeout (int, optional, default=0) Time in milliseconds to wait for a response. 0 indicates no timeout.\n" "\nResult:\n" "{ (json object)\n" " \"hash\" : { (string) The blockhash\n" @@ -302,13 +299,10 @@ static UniValue waitforblockheight(const JSONRPCRequest& request) "of the current tip.\n" "\nReturns the current block on timeout or exit.\n", { - {"height", RPCArg::Type::NUM, false}, - {"timeout", RPCArg::Type::NUM, true}, + {"height", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "Block height to wait for."}, + {"timeout", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "0", "Time in milliseconds to wait for a response. 0 indicates no timeout."}, }} .ToString() + - "\nArguments:\n" - "1. height (int, required) Block height to wait for.\n" - "2. timeout (int, optional, default=0) Time in milliseconds to wait for a response. 0 indicates no timeout.\n" "\nResult:\n" "{ (json object)\n" " \"hash\" : { (string) The blockhash\n" @@ -496,14 +490,12 @@ static UniValue getrawmempool(const JSONRPCRequest& request) if (request.fHelp || request.params.size() > 1) throw std::runtime_error( RPCHelpMan{"getrawmempool", - "\nReturns all transaction ids in memory pool as a json array of string transaction ids.\n", + "\nReturns all transaction ids in memory pool as a json array of string transaction ids.\n" + "\nHint: use getmempoolentry to fetch a specific transaction from the mempool.\n", { - {"verbose", RPCArg::Type::BOOL, true}, + {"verbose", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "True for a json object, false for array of transaction ids"}, }} .ToString() + - "\nHint: use getmempoolentry to fetch a specific transaction from the mempool.\n" - "\nArguments:\n" - "1. verbose (boolean, optional, default=false) True for a json object, false for array of transaction ids\n" "\nResult: (for verbose = false):\n" "[ (json array of string)\n" " \"transactionid\" (string) The transaction id\n" @@ -534,13 +526,10 @@ static UniValue getmempoolancestors(const JSONRPCRequest& request) RPCHelpMan{"getmempoolancestors", "\nIf txid is in the mempool, returns all in-mempool ancestors.\n", { - {"txid", RPCArg::Type::STR_HEX, false}, - {"verbose", RPCArg::Type::BOOL, true}, + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The transaction id (must be in mempool)"}, + {"verbose", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "True for a json object, false for array of transaction ids"}, }} .ToString() + - "\nArguments:\n" - "1. \"txid\" (string, required) The transaction id (must be in mempool)\n" - "2. verbose (boolean, optional, default=false) True for a json object, false for array of transaction ids\n" "\nResult (for verbose = false):\n" "[ (json array of strings)\n" " \"transactionid\" (string) The transaction id of an in-mempool ancestor transaction\n" @@ -603,13 +592,10 @@ static UniValue getmempooldescendants(const JSONRPCRequest& request) RPCHelpMan{"getmempooldescendants", "\nIf txid is in the mempool, returns all in-mempool descendants.\n", { - {"txid", RPCArg::Type::STR_HEX, false}, - {"verbose", RPCArg::Type::BOOL, true}, + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The transaction id (must be in mempool)"}, + {"verbose", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "True for a json object, false for array of transaction ids"}, }} .ToString() + - "\nArguments:\n" - "1. \"txid\" (string, required) The transaction id (must be in mempool)\n" - "2. verbose (boolean, optional, default=false) True for a json object, false for array of transaction ids\n" "\nResult (for verbose = false):\n" "[ (json array of strings)\n" " \"transactionid\" (string) The transaction id of an in-mempool descendant transaction\n" @@ -672,11 +658,9 @@ static UniValue getmempoolentry(const JSONRPCRequest& request) RPCHelpMan{"getmempoolentry", "\nReturns mempool data for given transaction\n", { - {"txid", RPCArg::Type::STR_HEX, false}, + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The transaction id (must be in mempool)"}, }} .ToString() + - "\nArguments:\n" - "1. \"txid\" (string, required) The transaction id (must be in mempool)\n" "\nResult:\n" "{ (json object)\n" + EntryDescriptionString() @@ -709,11 +693,9 @@ static UniValue getblockhash(const JSONRPCRequest& request) RPCHelpMan{"getblockhash", "\nReturns hash of block in best-block-chain at height provided.\n", { - {"height", RPCArg::Type::NUM, false}, + {"height", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "The height index"}, }} .ToString() + - "\nArguments:\n" - "1. height (numeric, required) The height index\n" "\nResult:\n" "\"hash\" (string) The block hash\n" "\nExamples:\n" @@ -739,13 +721,10 @@ static UniValue getblockheader(const JSONRPCRequest& request) "\nIf verbose is false, returns a string that is serialized, hex-encoded data for blockheader 'hash'.\n" "If verbose is true, returns an Object with information about blockheader .\n", { - {"blockhash", RPCArg::Type::STR_HEX, false}, - {"verbose", RPCArg::Type::BOOL, true}, + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The block hash"}, + {"verbose", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "true", "true for a json object, false for the hex-encoded data"}, }} .ToString() + - "\nArguments:\n" - "1. \"blockhash\" (string, required) The block hash\n" - "2. verbose (boolean, optional, default=true) true for a json object, false for the hex-encoded data\n" "\nResult (for verbose = true):\n" "{\n" " \"hash\" : \"hash\", (string) the block hash (same as provided)\n" @@ -823,13 +802,10 @@ static UniValue getblock(const JSONRPCRequest& request) "If verbosity is 1, returns an Object with information about block .\n" "If verbosity is 2, returns an Object with information about block and information about each transaction. \n", { - {"blockhash", RPCArg::Type::STR_HEX, false}, - {"verbosity", RPCArg::Type::NUM, true}, + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The block hash"}, + {"verbosity", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "1", "0 for hex-encoded data, 1 for a json object, and 2 for json object with transaction data"}, }} .ToString() + - "\nArguments:\n" - "1. \"blockhash\" (string, required) The block hash\n" - "2. verbosity (numeric, optional, default=1) 0 for hex-encoded data, 1 for a json object, and 2 for json object with transaction data\n" "\nResult (for verbosity = 0):\n" "\"data\" (string) A string that is serialized, hex-encoded data for block 'hash'.\n" "\nResult (for verbosity = 1):\n" @@ -977,12 +953,10 @@ static UniValue pruneblockchain(const JSONRPCRequest& request) throw std::runtime_error( RPCHelpMan{"pruneblockchain", "", { - {"height", RPCArg::Type::NUM, false}, + {"height", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "The block height to prune up to. May be set to a discrete height, or a unix timestamp\n" + " to prune blocks whose block time is at least 2 hours older than the provided timestamp."}, }} .ToString() + - "\nArguments:\n" - "1. \"height\" (numeric, required) The block height to prune up to. May be set to a discrete height, or a unix timestamp\n" - " to prune blocks whose block time is at least 2 hours older than the provided timestamp.\n" "\nResult:\n" "n (numeric) Height of the last block pruned.\n" "\nExamples:\n" @@ -1075,16 +1049,11 @@ UniValue gettxout(const JSONRPCRequest& request) RPCHelpMan{"gettxout", "\nReturns details about an unspent transaction output.\n", { - {"txid", RPCArg::Type::STR, false}, - {"n", RPCArg::Type::NUM, false}, - {"include_mempool", RPCArg::Type::BOOL, true}, + {"txid", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The transaction id"}, + {"n", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "vout number"}, + {"include_mempool", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "true", "Whether to include the mempool. Note that an unspent output that is spent in the mempool won't appear."}, }} .ToString() + - "\nArguments:\n" - "1. \"txid\" (string, required) The transaction id\n" - "2. \"n\" (numeric, required) vout number\n" - "3. \"include_mempool\" (boolean, optional) Whether to include the mempool. Default: true." - " Note that an unspent output that is spent in the mempool won't appear.\n" "\nResult:\n" "{\n" " \"bestblock\": \"hash\", (string) The hash of the block at the tip of the chain\n" @@ -1161,13 +1130,10 @@ static UniValue verifychain(const JSONRPCRequest& request) RPCHelpMan{"verifychain", "\nVerifies blockchain database.\n", { - {"checklevel", RPCArg::Type::NUM, true}, - {"nblocks", RPCArg::Type::NUM, true}, + {"checklevel", RPCArg::Type::NUM, /* opt */ true, /* default_val */ strprintf("%d, range=0-4", nCheckLevel), "How thorough the block verification is."}, + {"nblocks", RPCArg::Type::NUM, /* opt */ true, /* default_val */ strprintf("%d, 0=all", nCheckDepth), "The number of blocks to check."}, }} .ToString() + - "\nArguments:\n" - "1. checklevel (numeric, optional, 0-4, default=" + strprintf("%d", nCheckLevel) + ") How thorough the block verification is.\n" - "2. nblocks (numeric, optional, default=" + strprintf("%d", nCheckDepth) + ", 0=all) The number of blocks to check.\n" "\nResult:\n" "true|false (boolean) Verified or not\n" "\nExamples:\n" @@ -1526,11 +1492,9 @@ static UniValue preciousblock(const JSONRPCRequest& request) "\nA later preciousblock call can override the effect of an earlier one.\n" "\nThe effects of preciousblock are not retained across restarts.\n", { - {"blockhash", RPCArg::Type::STR_HEX, false}, + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "the hash of the block to mark as precious"}, }} .ToString() + - "\nArguments:\n" - "1. \"blockhash\" (string, required) the hash of the block to mark as precious\n" "\nResult:\n" "\nExamples:\n" + HelpExampleCli("preciousblock", "\"blockhash\"") @@ -1565,11 +1529,9 @@ static UniValue invalidateblock(const JSONRPCRequest& request) RPCHelpMan{"invalidateblock", "\nPermanently marks a block as invalid, as if it violated a consensus rule.\n", { - {"blockhash", RPCArg::Type::STR_HEX, false}, + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "the hash of the block to mark as invalid"}, }} .ToString() + - "\nArguments:\n" - "1. \"blockhash\" (string, required) the hash of the block to mark as invalid\n" "\nResult:\n" "\nExamples:\n" + HelpExampleCli("invalidateblock", "\"blockhash\"") @@ -1608,11 +1570,9 @@ static UniValue reconsiderblock(const JSONRPCRequest& request) "\nRemoves invalidity status of a block and its descendants, reconsider them for activation.\n" "This can be used to undo the effects of invalidateblock.\n", { - {"blockhash", RPCArg::Type::STR_HEX, false}, + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "the hash of the block to reconsider"}, }} .ToString() + - "\nArguments:\n" - "1. \"blockhash\" (string, required) the hash of the block to reconsider\n" "\nResult:\n" "\nExamples:\n" + HelpExampleCli("reconsiderblock", "\"blockhash\"") @@ -1648,13 +1608,10 @@ static UniValue getchaintxstats(const JSONRPCRequest& request) RPCHelpMan{"getchaintxstats", "\nCompute statistics about the total number and rate of transactions in the chain.\n", { - {"nblocks", RPCArg::Type::NUM, true}, - {"blockhash", RPCArg::Type::STR_HEX, true}, + {"nblocks", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "one month", "Size of the window in number of blocks"}, + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ true, /* default_val */ "", "The hash of the block that ends the window."}, }} .ToString() + - "\nArguments:\n" - "1. nblocks (numeric, optional) Size of the window in number of blocks (default: one month).\n" - "2. \"blockhash\" (string, optional) The hash of the block that ends the window.\n" "\nResult:\n" "{\n" " \"time\": xxxxx, (numeric) The timestamp for the final block in the window in UNIX format.\n" @@ -1785,23 +1742,15 @@ static UniValue getblockstats(const JSONRPCRequest& request) "It won't work for some heights with pruning.\n" "It won't work without -txindex for utxo_size_inc, *fee or *feerate stats.\n", { - {"hash_or_height", RPCArg::Type::NUM, false}, - {"stats", RPCArg::Type::ARR, + {"hash_or_height", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "The block hash or height of the target block", "", {"", "string or numeric"}}, + {"stats", RPCArg::Type::ARR, /* opt */ true, /* default_val */ "", "Values to plot, by default all values (see result below)", { - {"height", RPCArg::Type::STR, true}, - {"time", RPCArg::Type::STR, true}, + {"height", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "Selected statistic"}, + {"time", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "Selected statistic"}, }, - true, "stats"}, + "stats"}, }} .ToString() + - "\nArguments:\n" - "1. \"hash_or_height\" (string or numeric, required) The block hash or height of the target block\n" - "2. \"stats\" (array, optional) Values to plot, by default all values (see result below)\n" - " [\n" - " \"height\", (string, optional) Selected statistic\n" - " \"time\", (string, optional) Selected statistic\n" - " ,...\n" - " ]\n" "\nResult:\n" "{ (json object)\n" " \"avgfee\": xxxxx, (numeric) Average fee in the block\n" @@ -2153,33 +2102,24 @@ UniValue scantxoutset(const JSONRPCRequest& request) "In the latter case, a range needs to be specified by below if different from 1000.\n" "For more information on output descriptors, see the documentation in the doc/descriptors.md file.\n", { - {"action", RPCArg::Type::STR, false}, - {"scanobjects", RPCArg::Type::ARR, + {"action", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The action to execute\n" + " \"start\" for starting a scan\n" + " \"abort\" for aborting the current scan (returns true when abort was successful)\n" + " \"status\" for progress report (in %) of the current scan"}, + {"scanobjects", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "Array of scan objects\n" + " Every scan object is either a string descriptor or an object:", { - {"descriptor", RPCArg::Type::OBJ, + {"descriptor", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "An output descriptor"}, + {"", RPCArg::Type::OBJ, /* opt */ true, /* default_val */ "", "An object with output descriptor and metadata", { - {"desc", RPCArg::Type::STR, false}, - {"range", RPCArg::Type::NUM, true}, + {"desc", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "An output descriptor"}, + {"range", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "1000", "Up to what child index HD chains should be explored"}, }, - false, "scanobjects"}, + }, }, - false}, + "[scanobjects,...]"}, }} .ToString() + - "\nArguments:\n" - "1. \"action\" (string, required) The action to execute\n" - " \"start\" for starting a scan\n" - " \"abort\" for aborting the current scan (returns true when abort was successful)\n" - " \"status\" for progress report (in %) of the current scan\n" - "2. \"scanobjects\" (array, required) Array of scan objects\n" - " [ Every scan object is either a string descriptor or an object:\n" - " \"descriptor\", (string, optional) An output descriptor\n" - " { (object, optional) An object with output descriptor and metadata\n" - " \"desc\": \"descriptor\", (string, required) An output descriptor\n" - " \"range\": n, (numeric, optional) Up to what child index HD chains should be explored (default: 1000)\n" - " },\n" - " ...\n" - " ]\n" "\nResult:\n" "{\n" " \"unspents\": [\n" diff --git a/src/rpc/mining.cpp b/src/rpc/mining.cpp index c0287ec17f..f0a7589cfb 100644 --- a/src/rpc/mining.cpp +++ b/src/rpc/mining.cpp @@ -92,13 +92,10 @@ static UniValue getnetworkhashps(const JSONRPCRequest& request) "Pass in [blocks] to override # of blocks, -1 specifies since last difficulty change.\n" "Pass in [height] to estimate the network speed at the time when a certain block was found.\n", { - {"nblocks", RPCArg::Type::NUM, true}, - {"height", RPCArg::Type::NUM, true}, + {"nblocks", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "120", "The number of blocks, or -1 for blocks since last difficulty change."}, + {"height", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "-1", "To estimate at the time of the given height."}, }} .ToString() + - "\nArguments:\n" - "1. nblocks (numeric, optional, default=120) The number of blocks, or -1 for blocks since last difficulty change.\n" - "2. height (numeric, optional, default=-1) To estimate at the time of the given height.\n" "\nResult:\n" "x (numeric) Hashes per second estimated\n" "\nExamples:\n" @@ -165,15 +162,11 @@ static UniValue generatetoaddress(const JSONRPCRequest& request) RPCHelpMan{"generatetoaddress", "\nMine blocks immediately to a specified address (before the RPC call returns)\n", { - {"nblocks", RPCArg::Type::NUM, false}, - {"address", RPCArg::Type::STR, false}, - {"maxtries", RPCArg::Type::NUM, true}, + {"nblocks", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "How many blocks are generated immediately."}, + {"address", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The address to send the newly generated bitcoin to."}, + {"maxtries", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "1000000", "How many iterations to try."}, }} .ToString() + - "\nArguments:\n" - "1. nblocks (numeric, required) How many blocks are generated immediately.\n" - "2. address (string, required) The address to send the newly generated bitcoin to.\n" - "3. maxtries (numeric, optional) How many iterations to try (default = 1000000).\n" "\nResult:\n" "[ blockhashes ] (array) hashes of blocks generated\n" "\nExamples:\n" @@ -247,19 +240,15 @@ static UniValue prioritisetransaction(const JSONRPCRequest& request) RPCHelpMan{"prioritisetransaction", "Accepts the transaction into mined blocks at a higher (or lower) priority\n", { - {"txid", RPCArg::Type::STR, false}, - {"dummy", RPCArg::Type::NUM, false}, - {"fee_delta", RPCArg::Type::NUM, false}, - }} - .ToString() + - "\nArguments:\n" - "1. \"txid\" (string, required) The transaction id.\n" - "2. dummy (numeric, optional) API-Compatibility for previous API. Must be zero or null.\n" - " DEPRECATED. For forward compatibility use named arguments and omit this parameter.\n" - "3. fee_delta (numeric, required) The fee value (in satoshis) to add (or subtract, if negative).\n" + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The transaction id."}, + {"dummy", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "API-Compatibility for previous API. Must be zero or null.\n" + " DEPRECATED. For forward compatibility use named arguments and omit this parameter."}, + {"fee_delta", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "The fee value (in satoshis) to add (or subtract, if negative).\n" " Note, that this value is not a fee rate. It is a value to modify absolute fee of the TX.\n" " The fee is not actually paid, only the algorithm for selecting transactions into a block\n" - " considers the transaction as it would have paid a higher (or lower) fee.\n" + " considers the transaction as it would have paid a higher (or lower) fee."}, + }} + .ToString() + "\nResult:\n" "true (boolean) Returns true\n" "\nExamples:\n" @@ -322,38 +311,23 @@ static UniValue getblocktemplate(const JSONRPCRequest& request) " https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki#getblocktemplate_changes\n" " https://github.com/bitcoin/bips/blob/master/bip-0145.mediawiki\n", { - {"template_request", RPCArg::Type::OBJ, + {"template_request", RPCArg::Type::OBJ, /* opt */ true, /* default_val */ "", "A json object in the following spec", { - {"mode", RPCArg::Type::STR, true}, - {"capabilities", RPCArg::Type::ARR, + {"mode", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "This must be set to \"template\", \"proposal\" (see BIP 23), or omitted"}, + {"capabilities", RPCArg::Type::ARR, /* opt */ true, /* default_val */ "", "A list of strings", { - {"support", RPCArg::Type::STR, true}, + {"support", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "client side supported feature, 'longpoll', 'coinbasetxn', 'coinbasevalue', 'proposal', 'serverlist', 'workid'"}, }, - true}, - {"rules", RPCArg::Type::ARR, + }, + {"rules", RPCArg::Type::ARR, /* opt */ true, /* default_val */ "", "A list of strings", { - {"support", RPCArg::Type::STR, true}, + {"support", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "client side supported softfork deployment"}, + }, }, - true}, }, - true, "\"template_request\""}, + "\"template_request\""}, }} .ToString() + - "\nArguments:\n" - "1. template_request (json object, optional) A json object in the following spec\n" - " {\n" - " \"mode\":\"template\" (string, optional) This must be set to \"template\", \"proposal\" (see BIP 23), or omitted\n" - " \"capabilities\":[ (array, optional) A list of strings\n" - " \"support\" (string) client side supported feature, 'longpoll', 'coinbasetxn', 'coinbasevalue', 'proposal', 'serverlist', 'workid'\n" - " ,...\n" - " ],\n" - " \"rules\":[ (array, optional) A list of strings\n" - " \"support\" (string) client side supported softfork deployment\n" - " ,...\n" - " ]\n" - " }\n" - "\n" - "\nResult:\n" "{\n" " \"version\" : n, (numeric) The preferred block version\n" @@ -742,13 +716,10 @@ static UniValue submitblock(const JSONRPCRequest& request) "\nAttempts to submit new block to network.\n" "See https://en.bitcoin.it/wiki/BIP_0022 for full specification.\n", { - {"hexdata", RPCArg::Type::STR_HEX, false}, - {"dummy", RPCArg::Type::STR, true}, + {"hexdata", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "the hex-encoded block data to submit"}, + {"dummy", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "dummy value, for compatibility with BIP22. This value is ignored."}, }} .ToString() + - "\nArguments\n" - "1. \"hexdata\" (string, required) the hex-encoded block data to submit\n" - "2. \"dummy\" (optional) dummy value, for compatibility with BIP22. This value is ignored.\n" "\nResult:\n" "\nExamples:\n" + HelpExampleCli("submitblock", "\"mydata\"") @@ -810,11 +781,9 @@ static UniValue submitheader(const JSONRPCRequest& request) "\nDecode the given hexdata as a header and submit it as a candidate chain tip if valid." "\nThrows when the header is invalid.\n", { - {"hexdata", RPCArg::Type::STR_HEX, false}, + {"hexdata", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "the hex-encoded block header data"}, }} .ToString() + - "\nArguments\n" - "1. \"hexdata\" (string, required) the hex-encoded block header data\n" "\nResult:\n" "None" "\nExamples:\n" + @@ -852,13 +821,8 @@ static UniValue estimatesmartfee(const JSONRPCRequest& request) "for which the estimate is valid. Uses virtual transaction size as defined\n" "in BIP 141 (witness data is discounted).\n", { - {"conf_target", RPCArg::Type::NUM, false}, - {"estimate_mode", RPCArg::Type::STR, true}, - }} - .ToString() + - "\nArguments:\n" - "1. conf_target (numeric) Confirmation target in blocks (1 - 1008)\n" - "2. \"estimate_mode\" (string, optional, default=CONSERVATIVE) The fee estimate mode.\n" + {"conf_target", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "Confirmation target in blocks (1 - 1008)"}, + {"estimate_mode", RPCArg::Type::STR, /* opt */ true, /* default_val */ "CONSERVATIVE", "The fee estimate mode.\n" " Whether to return a more conservative estimate which also satisfies\n" " a longer history. A conservative estimate potentially returns a\n" " higher feerate and is more likely to be sufficient for the desired\n" @@ -866,7 +830,9 @@ static UniValue estimatesmartfee(const JSONRPCRequest& request) " prevailing fee market. Must be one of:\n" " \"UNSET\"\n" " \"ECONOMICAL\"\n" - " \"CONSERVATIVE\"\n" + " \"CONSERVATIVE\""}, + }} + .ToString() + "\nResult:\n" "{\n" " \"feerate\" : x.x, (numeric, optional) estimate fee rate in " + CURRENCY_UNIT + "/kB\n" @@ -921,15 +887,12 @@ static UniValue estimaterawfee(const JSONRPCRequest& request) "confirmation within conf_target blocks if possible. Uses virtual transaction size as\n" "defined in BIP 141 (witness data is discounted).\n", { - {"conf_target", RPCArg::Type::NUM, false}, - {"threshold", RPCArg::Type::NUM, true}, + {"conf_target", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "Confirmation target in blocks (1 - 1008)"}, + {"threshold", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "", "The proportion of transactions in a given feerate range that must have been\n" + " confirmed within conf_target in order to consider those feerates as high enough and proceed to check\n" + " lower buckets. Default: 0.95"}, }} .ToString() + - "\nArguments:\n" - "1. conf_target (numeric) Confirmation target in blocks (1 - 1008)\n" - "2. threshold (numeric, optional) The proportion of transactions in a given feerate range that must have been\n" - " confirmed within conf_target in order to consider those feerates as high enough and proceed to check\n" - " lower buckets. Default: 0.95\n" "\nResult:\n" "{\n" " \"short\" : { (json object, optional) estimate for short time horizon\n" diff --git a/src/rpc/misc.cpp b/src/rpc/misc.cpp index 5543035885..71c94ae499 100644 --- a/src/rpc/misc.cpp +++ b/src/rpc/misc.cpp @@ -39,11 +39,9 @@ static UniValue validateaddress(const JSONRPCRequest& request) "fields have moved to getaddressinfo and will only be shown here with -deprecatedrpc=validateaddress: ismine, iswatchonly,\n" "script, hex, pubkeys, sigsrequired, pubkey, addresses, embedded, iscompressed, account, timestamp, hdkeypath, kdmasterkeyid.\n", { - {"address", RPCArg::Type::STR, false}, + {"address", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The bitcoin address to validate"}, }} .ToString() + - "\nArguments:\n" - "1. \"address\" (string, required) The bitcoin address to validate\n" "\nResult:\n" "{\n" " \"isvalid\" : true|false, (boolean) If the address is valid or not. If not, this is the only property returned.\n" @@ -82,18 +80,19 @@ static UniValue createmultisig(const JSONRPCRequest& request) { if (request.fHelp || request.params.size() < 2 || request.params.size() > 3) { - std::string msg = "createmultisig nrequired [\"key\",...] ( \"address_type\" )\n" - "\nCreates a multi-signature address with n signature of m keys required.\n" - "It returns a json object with the address and redeemScript.\n" - "\nArguments:\n" - "1. nrequired (numeric, required) The number of required signatures out of the n keys.\n" - "2. \"keys\" (string, required) A json array of hex-encoded public keys\n" - " [\n" - " \"key\" (string) The hex-encoded public key\n" - " ,...\n" - " ]\n" - "3. \"address_type\" (string, optional) The address type to use. Options are \"legacy\", \"p2sh-segwit\", and \"bech32\". Default is legacy.\n" - + std::string msg = + RPCHelpMan{"createmultisig", + "\nCreates a multi-signature address with n signature of m keys required.\n" + "It returns a json object with the address and redeemScript.\n", + { + {"nrequired", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "The number of required signatures out of the n keys."}, + {"keys", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "A json array of hex-encoded public keys.", + { + {"key", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The hex-encoded public key"}, + }}, + {"address_type", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "The address type to use. Options are \"legacy\", \"p2sh-segwit\", and \"bech32\". Default is legacy."}, + }} + .ToString() + "\nResult:\n" "{\n" " \"address\":\"multisigaddress\", (string) The value of the new multisig address.\n" @@ -149,15 +148,11 @@ static UniValue verifymessage(const JSONRPCRequest& request) RPCHelpMan{"verifymessage", "\nVerify a signed message\n", { - {"address", RPCArg::Type::STR, false}, - {"signature", RPCArg::Type::STR, false}, - {"message", RPCArg::Type::STR, false}, + {"address", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The bitcoin address to use for the signature."}, + {"signature", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The signature provided by the signer in base 64 encoding (see signmessage)."}, + {"message", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The message that was signed."}, }} .ToString() + - "\nArguments:\n" - "1. \"address\" (string, required) The bitcoin address to use for the signature.\n" - "2. \"signature\" (string, required) The signature provided by the signer in base 64 encoding (see signmessage).\n" - "3. \"message\" (string, required) The message that was signed.\n" "\nResult:\n" "true|false (boolean) If the signature is verified or not.\n" "\nExamples:\n" @@ -211,13 +206,10 @@ static UniValue signmessagewithprivkey(const JSONRPCRequest& request) RPCHelpMan{"signmessagewithprivkey", "\nSign a message with the private key of an address\n", { - {"privkey", RPCArg::Type::STR, false}, - {"message", RPCArg::Type::STR, false}, + {"privkey", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The private key to sign the message with."}, + {"message", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The message to create a signature of."}, }} .ToString() + - "\nArguments:\n" - "1. \"privkey\" (string, required) The private key to sign the message with.\n" - "2. \"message\" (string, required) The message to create a signature of.\n" "\nResult:\n" "\"signature\" (string) The signature of the message encoded in base 64\n" "\nExamples:\n" @@ -255,12 +247,10 @@ static UniValue setmocktime(const JSONRPCRequest& request) RPCHelpMan{"setmocktime", "\nSet the local time to given timestamp (-regtest only)\n", { - {"timestamp", RPCArg::Type::NUM, false}, + {"timestamp", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "Unix seconds-since-epoch timestamp\n" + " Pass 0 to go back to using the system time."}, }} - .ToString() + - "\nArguments:\n" - "1. timestamp (integer, required) Unix seconds-since-epoch timestamp\n" - " Pass 0 to go back to using the system time." + .ToString() ); if (!Params().MineBlocksOnDemand()) @@ -321,13 +311,11 @@ static UniValue getmemoryinfo(const JSONRPCRequest& request) RPCHelpMan{"getmemoryinfo", "Returns an object containing information about memory usage.\n", { - {"mode", RPCArg::Type::STR, true}, + {"mode", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "determines what kind of information is returned. This argument is optional, the default mode is \"stats\".\n" + " - \"stats\" returns general statistics about memory usage in the daemon.\n" + " - \"mallocinfo\" returns an XML string describing low-level heap state (only available if compiled with glibc 2.10+)."}, }} .ToString() + - "Arguments:\n" - "1. \"mode\" determines what kind of information is returned. This argument is optional, the default mode is \"stats\".\n" - " - \"stats\" returns general statistics about memory usage in the daemon.\n" - " - \"mallocinfo\" returns an XML string describing low-level heap state (only available if compiled with glibc 2.10+).\n" "\nResult (mode \"stats\"):\n" "{\n" " \"locked\": { (json object) Information about locked memory manager\n" @@ -396,21 +384,16 @@ UniValue logging(const JSONRPCRequest& request) " - \"none\", \"0\" : even if other logging categories are specified, ignore all of them.\n" , { - {"include", RPCArg::Type::STR, true}, - {"exclude", RPCArg::Type::STR, true}, + {"include", RPCArg::Type::ARR, /* opt */ true, /* default_val */ "", "A json array of categories to add debug logging", + { + {"include_category", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "the valid logging category"}, + }}, + {"exclude", RPCArg::Type::ARR, /* opt */ true, /* default_val */ "", "A json array of categories to remove debug logging", + { + {"exclude_category", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "the valid logging category"}, + }}, }} .ToString() + - "\nArguments:\n" - "1. \"include\" (array of strings, optional) A json array of categories to add debug logging\n" - " [\n" - " \"category\" (string) the valid logging category\n" - " ,...\n" - " ]\n" - "2. \"exclude\" (array of strings, optional) A json array of categories to remove debug logging\n" - " [\n" - " \"category\" (string) the valid logging category\n" - " ,...\n" - " ]\n" "\nResult:\n" "{ (json object where keys are the logging categories, and values indicates its status\n" " \"category\": 0|1, (numeric) if being debug logged or not. 0:inactive, 1:active\n" diff --git a/src/rpc/net.cpp b/src/rpc/net.cpp index 795b9b089b..f523ca835f 100644 --- a/src/rpc/net.cpp +++ b/src/rpc/net.cpp @@ -211,13 +211,10 @@ static UniValue addnode(const JSONRPCRequest& request) "Nodes added using addnode (or -connect) are protected from DoS disconnection and are not required to be\n" "full nodes/support SegWit as other outbound peers are (though such peers will not be synced from).\n", { - {"node", RPCArg::Type::STR, false}, - {"command", RPCArg::Type::STR, false}, + {"node", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The node (see getpeerinfo for nodes)"}, + {"command", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "'add' to add a node to the list, 'remove' to remove a node from the list, 'onetry' to try a connection to the node once"}, }} .ToString() + - "\nArguments:\n" - "1. \"node\" (string, required) The node (see getpeerinfo for nodes)\n" - "2. \"command\" (string, required) 'add' to add a node to the list, 'remove' to remove a node from the list, 'onetry' to try a connection to the node once\n" "\nExamples:\n" + HelpExampleCli("addnode", "\"192.168.0.6:8333\" \"onetry\"") + HelpExampleRpc("addnode", "\"192.168.0.6:8333\", \"onetry\"") @@ -258,13 +255,10 @@ static UniValue disconnectnode(const JSONRPCRequest& request) "\nStrictly one out of 'address' and 'nodeid' can be provided to identify the node.\n" "\nTo disconnect by nodeid, either set 'address' to the empty string, or call using the named 'nodeid' argument only.\n", { - {"address", RPCArg::Type::STR, true}, - {"nodeid", RPCArg::Type::NUM, true}, + {"address", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "The IP address/port of the node"}, + {"nodeid", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "", "The node ID (see getpeerinfo for node IDs)"}, }} .ToString() + - "\nArguments:\n" - "1. \"address\" (string, optional) The IP address/port of the node\n" - "2. nodeid (number, optional) The node ID (see getpeerinfo for node IDs)\n" "\nExamples:\n" + HelpExampleCli("disconnectnode", "\"192.168.0.6:8333\"") + HelpExampleCli("disconnectnode", "\"\" 1") @@ -305,11 +299,9 @@ static UniValue getaddednodeinfo(const JSONRPCRequest& request) "\nReturns information about the given added node, or all added nodes\n" "(note that onetry addnodes are not listed here)\n", { - {"node", RPCArg::Type::STR, true}, + {"node", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "If provided, return information about this specific node, otherwise all nodes are returned."}, }} .ToString() + - "\nArguments:\n" - "1. \"node\" (string, optional) If provided, return information about this specific node, otherwise all nodes are returned.\n" "\nResult:\n" "[\n" " {\n" @@ -524,17 +516,12 @@ static UniValue setban(const JSONRPCRequest& request) RPCHelpMan{"setban", "\nAttempts to add or remove an IP/Subnet from the banned list.\n", { - {"subnet", RPCArg::Type::STR, false}, - {"command", RPCArg::Type::STR, false}, - {"bantime", RPCArg::Type::NUM, true}, - {"absolute", RPCArg::Type::NUM, true}, + {"subnet", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The IP/Subnet (see getpeerinfo for nodes IP) with an optional netmask (default is /32 = single IP)"}, + {"command", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "'add' to add an IP/Subnet to the list, 'remove' to remove an IP/Subnet from the list"}, + {"bantime", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "", "time in seconds how long (or until when if [absolute] is set) the IP is banned (0 or empty means using the default time of 24h which can also be overwritten by the -bantime startup argument)"}, + {"absolute", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "", "If set, the bantime must be an absolute timestamp in seconds since epoch (Jan 1 1970 GMT)"}, }} .ToString() + - "\nArguments:\n" - "1. \"subnet\" (string, required) The IP/Subnet (see getpeerinfo for nodes IP) with an optional netmask (default is /32 = single IP)\n" - "2. \"command\" (string, required) 'add' to add an IP/Subnet to the list, 'remove' to remove an IP/Subnet from the list\n" - "3. \"bantime\" (numeric, optional) time in seconds how long (or until when if [absolute] is set) the IP is banned (0 or empty means using the default time of 24h which can also be overwritten by the -bantime startup argument)\n" - "4. \"absolute\" (boolean, optional) If set, the bantime must be an absolute timestamp in seconds since epoch (Jan 1 1970 GMT)\n" "\nExamples:\n" + HelpExampleCli("setban", "\"192.168.0.6\" \"add\" 86400") + HelpExampleCli("setban", "\"192.168.0.0/24\" \"add\"") @@ -644,11 +631,9 @@ static UniValue setnetworkactive(const JSONRPCRequest& request) RPCHelpMan{"setnetworkactive", "\nDisable/enable all p2p network activity.\n", { - {"state", RPCArg::Type::BOOL, false}, + {"state", RPCArg::Type::BOOL, /* opt */ false, /* default_val */ "", "true to enable networking, false to disable"}, }} - .ToString() + - "\nArguments:\n" - "1. \"state\" (boolean, required) true to enable networking, false to disable\n" + .ToString() ); } @@ -668,12 +653,9 @@ static UniValue getnodeaddresses(const JSONRPCRequest& request) RPCHelpMan{"getnodeaddresses", "\nReturn known addresses which can potentially be used to find new nodes in the network\n", { - {"count", RPCArg::Type::NUM, true}, + {"count", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "1", "How many addresses to return. Limited to the smaller of " + std::to_string(ADDRMAN_GETADDR_MAX) + " or " + std::to_string(ADDRMAN_GETADDR_MAX_PCT) + "% of all known addresses."}, }} .ToString() + - "\nArguments:\n" - "1. \"count\" (numeric, optional) How many addresses to return. Limited to the smaller of " + std::to_string(ADDRMAN_GETADDR_MAX) + - " or " + std::to_string(ADDRMAN_GETADDR_MAX_PCT) + "% of all known addresses. (default = 1)\n" "\nResult:\n" "[\n" " {\n" diff --git a/src/rpc/rawtransaction.cpp b/src/rpc/rawtransaction.cpp index 41f3ac6b4a..f5f6c344ea 100644 --- a/src/rpc/rawtransaction.cpp +++ b/src/rpc/rawtransaction.cpp @@ -71,24 +71,19 @@ static UniValue getrawtransaction(const JSONRPCRequest& request) "enabled, it also works for blockchain transactions. If the block which contains the transaction\n" "is known, its hash can be provided even for nodes without -txindex. Note that if a blockhash is\n" "provided, only that block will be searched and if the transaction is in the mempool or other\n" - "blocks, or if this node does not have the given block available, the transaction will not be found.\n", - { - {"txid", RPCArg::Type::STR_HEX, false}, - {"verbose", RPCArg::Type::BOOL, true}, - {"blockhash", RPCArg::Type::STR_HEX, true}, - }} - .ToString() + + "blocks, or if this node does not have the given block available, the transaction will not be found.\n" "DEPRECATED: for now, it also works for transactions with unspent outputs.\n" "\nReturn the raw transaction data.\n" "\nIf verbose is 'true', returns an Object with information about 'txid'.\n" "If verbose is 'false' or omitted, returns a string that is serialized, hex-encoded data for 'txid'.\n" - - "\nArguments:\n" - "1. \"txid\" (string, required) The transaction id\n" - "2. verbose (bool, optional, default=false) If false, return a string, otherwise return a json object\n" - "3. \"blockhash\" (string, optional) The block in which to look for the transaction\n" - + , + { + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The transaction id"}, + {"verbose", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "If false, return a string, otherwise return a json object"}, + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ true, /* default_val */ "", "The block in which to look for the transaction"}, + }} + .ToString() + "\nResult (if verbose is not set or set to false):\n" "\"data\" (string) The serialized, hex-encoded data for 'txid'\n" @@ -218,21 +213,14 @@ static UniValue gettxoutproof(const JSONRPCRequest& request) "you need to maintain a transaction index, using the -txindex command line option or\n" "specify the block in which the transaction is included manually (by blockhash).\n", { - {"txids", RPCArg::Type::ARR, + {"txids", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "A json array of txids to filter", { - {"txid", RPCArg::Type::STR_HEX, false}, + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "A transaction hash"}, }, - false}, - {"blockhash", RPCArg::Type::STR_HEX, true}, + }, + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ true, /* default_val */ "", "If specified, looks for txid in the block with this hash"}, }} .ToString() + - "\nArguments:\n" - "1. \"txids\" (string) A json array of txids to filter\n" - " [\n" - " \"txid\" (string) A transaction hash\n" - " ,...\n" - " ]\n" - "2. \"blockhash\" (string, optional) If specified, looks for txid in the block with this hash\n" "\nResult:\n" "\"data\" (string) A string that is a serialized, hex-encoded data for the proof.\n" ); @@ -316,11 +304,9 @@ static UniValue verifytxoutproof(const JSONRPCRequest& request) "\nVerifies that a proof points to a transaction in a block, returning the transaction it commits to\n" "and throwing an RPC error if the block is not in our best chain\n", { - {"proof", RPCArg::Type::STR, false}, + {"proof", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The hex-encoded proof generated by gettxoutproof"}, }} .ToString() + - "\nArguments:\n" - "1. \"proof\" (string, required) The hex-encoded proof generated by gettxoutproof\n" "\nResult:\n" "[\"txid\"] (array, strings) The txid(s) which the proof commits to, or empty array if the proof can not be validated.\n" ); @@ -462,38 +448,45 @@ static UniValue createrawtransaction(const JSONRPCRequest& request) { if (request.fHelp || request.params.size() < 2 || request.params.size() > 4) { throw std::runtime_error( - // clang-format off - "createrawtransaction [{\"txid\":\"id\",\"vout\":n},...] [{\"address\":amount},{\"data\":\"hex\"},...] ( locktime ) ( replaceable )\n" - "\nCreate a transaction spending the given inputs and creating new outputs.\n" - "Outputs can be addresses or data.\n" - "Returns hex-encoded raw transaction.\n" - "Note that the transaction's inputs are not signed, and\n" - "it is not stored in the wallet or transmitted to the network.\n" - - "\nArguments:\n" - "1. \"inputs\" (array, required) A json array of json objects\n" - " [\n" - " {\n" - " \"txid\":\"id\", (string, required) The transaction id\n" - " \"vout\":n, (numeric, required) The output number\n" - " \"sequence\":n (numeric, optional) The sequence number\n" - " } \n" - " ,...\n" - " ]\n" - "2. \"outputs\" (array, required) a json array with outputs (key-value pairs)\n" - " [\n" - " {\n" - " \"address\": x.xxx, (obj, optional) A key-value pair. The key (string) is the bitcoin address, the value (float or string) is the amount in " + CURRENCY_UNIT + "\n" - " },\n" - " {\n" - " \"data\": \"hex\" (obj, optional) A key-value pair. The key must be \"data\", the value is hex-encoded data\n" - " }\n" - " ,... More key-value pairs of the above form. For compatibility reasons, a dictionary, which holds the key-value pairs directly, is also\n" - " accepted as second parameter.\n" - " ]\n" - "3. locktime (numeric, optional, default=0) Raw locktime. Non-0 value also locktime-activates inputs\n" - "4. replaceable (boolean, optional, default=false) Marks this transaction as BIP125-replaceable.\n" - " Allows this transaction to be replaced by a transaction with higher fees. If provided, it is an error if explicit sequence numbers are incompatible.\n" + RPCHelpMan{"createrawtransaction", + "\nCreate a transaction spending the given inputs and creating new outputs.\n" + "Outputs can be addresses or data.\n" + "Returns hex-encoded raw transaction.\n" + "Note that the transaction's inputs are not signed, and\n" + "it is not stored in the wallet or transmitted to the network.\n", + { + {"inputs", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "A json array of json objects", + { + {"", RPCArg::Type::OBJ, /* opt */ false, /* default_val */ "", "", + { + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The transaction id"}, + {"vout", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "The output number"}, + {"sequence", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "", "The sequence number"}, + }, + }, + }, + }, + {"outputs", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "a json array with outputs (key-value pairs).\n" + "For compatibility reasons, a dictionary, which holds the key-value pairs directly, is also\n" + " accepted as second parameter.", + { + {"", RPCArg::Type::OBJ, /* opt */ true, /* default_val */ "", "", + { + {"address", RPCArg::Type::AMOUNT, /* opt */ false, /* default_val */ "", "A key-value pair. The key (string) is the bitcoin address, the value (float or string) is the amount in " + CURRENCY_UNIT}, + }, + }, + {"", RPCArg::Type::OBJ, /* opt */ true, /* default_val */ "", "", + { + {"data", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "A key-value pair. The key must be \"data\", the value is hex-encoded data"}, + }, + }, + }, + }, + {"locktime", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "0", "Raw locktime. Non-0 value also locktime-activates inputs"}, + {"replaceable", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "Marks this transaction as BIP125-replaceable.\n" + " Allows this transaction to be replaced by a transaction with higher fees. If provided, it is an error if explicit sequence numbers are incompatible."}, + }} + .ToString() + "\nResult:\n" "\"transaction\" (string) hex string of the transaction\n" @@ -502,7 +495,6 @@ static UniValue createrawtransaction(const JSONRPCRequest& request) + HelpExampleCli("createrawtransaction", "\"[{\\\"txid\\\":\\\"myid\\\",\\\"vout\\\":0}]\" \"[{\\\"data\\\":\\\"00010203\\\"}]\"") + HelpExampleRpc("createrawtransaction", "\"[{\\\"txid\\\":\\\"myid\\\",\\\"vout\\\":0}]\", \"[{\\\"address\\\":0.01}]\"") + HelpExampleRpc("createrawtransaction", "\"[{\\\"txid\\\":\\\"myid\\\",\\\"vout\\\":0}]\", \"[{\\\"data\\\":\\\"00010203\\\"}]\"") - // clang-format on ); } @@ -526,15 +518,11 @@ static UniValue decoderawtransaction(const JSONRPCRequest& request) RPCHelpMan{"decoderawtransaction", "\nReturn a JSON object representing the serialized, hex-encoded transaction.\n", { - {"hexstring", RPCArg::Type::STR_HEX, false}, - {"iswitness", RPCArg::Type::BOOL, true}, + {"hexstring", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The transaction hex string"}, + {"iswitness", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "", "Whether the transaction hex is a serialized witness transaction\n" + " If iswitness is not present, heuristic tests will be used in decoding"}, }} .ToString() + - "\nArguments:\n" - "1. \"hexstring\" (string, required) The transaction hex string\n" - "2. iswitness (boolean, optional) Whether the transaction hex is a serialized witness transaction\n" - " If iswitness is not present, heuristic tests will be used in decoding\n" - "\nResult:\n" "{\n" " \"txid\" : \"id\", (string) The transaction id\n" @@ -605,11 +593,9 @@ static UniValue decodescript(const JSONRPCRequest& request) RPCHelpMan{"decodescript", "\nDecode a hex-encoded script.\n", { - {"hexstring", RPCArg::Type::STR_HEX, false}, + {"hexstring", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "the hex-encoded script"}, }} .ToString() + - "\nArguments:\n" - "1. \"hexstring\" (string) the hex-encoded script\n" "\nResult:\n" "{\n" " \"asm\":\"asm\", (string) Script public key\n" @@ -706,20 +692,13 @@ static UniValue combinerawtransaction(const JSONRPCRequest& request) "The combined transaction may be another partially signed transaction or a \n" "fully signed transaction.", { - {"txs", RPCArg::Type::ARR, + {"txs", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "A json array of hex strings of partially signed transactions", { - {"hexstring", RPCArg::Type::STR_HEX, false}, + {"hexstring", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "A transaction hash"}, + }, }, - false}, }} .ToString() + - "\nArguments:\n" - "1. \"txs\" (string) A json array of hex strings of partially signed transactions\n" - " [\n" - " \"hexstring\" (string) A transaction hash\n" - " ,...\n" - " ]\n" - "\nResult:\n" "\"hex\" (string) The hex-encoded raw transaction with signature(s)\n" @@ -938,54 +917,35 @@ static UniValue signrawtransactionwithkey(const JSONRPCRequest& request) "The third 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", { - {"hexstring", RPCArg::Type::STR, false}, - {"privkeys", RPCArg::Type::ARR, + {"hexstring", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The transaction hex string"}, + {"privkeys", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "A json array of base58-encoded private keys for signing", { - {"privatekey", RPCArg::Type::STR_HEX, false}, + {"privatekey", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "private key in base58-encoding"}, }, - false}, - {"prevtxs", RPCArg::Type::ARR, + }, + {"prevtxs", RPCArg::Type::ARR, /* opt */ true, /* default_val */ "", "A json array of previous dependent transaction outputs", { - {"", RPCArg::Type::OBJ, + {"", RPCArg::Type::OBJ, /* opt */ true, /* default_val */ "", "", { - {"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}, + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The transaction id"}, + {"vout", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "The output number"}, + {"scriptPubKey", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "script key"}, + {"redeemScript", RPCArg::Type::STR_HEX, /* opt */ true, /* default_val */ "", "(required for P2SH or P2WSH) redeem script"}, + {"amount", RPCArg::Type::AMOUNT, /* opt */ false, /* default_val */ "", "The amount spent"}, + }, }, - true}, }, - true}, - {"sighashtype", RPCArg::Type::STR, true}, - }} - .ToString() + - "\nArguments:\n" - "1. \"hexstring\" (string, required) The transaction hex string\n" - "2. \"privkeys\" (string, required) A json array of base58-encoded private keys for signing\n" - " [ (json array of strings)\n" - " \"privatekey\" (string) private key in base58-encoding\n" - " ,...\n" - " ]\n" - "3. \"prevtxs\" (string, optional) An json array of previous dependent transaction outputs\n" - " [ (json array of json objects, or 'null' if none provided)\n" - " {\n" - " \"txid\":\"id\", (string, required) The transaction id\n" - " \"vout\":n, (numeric, required) The output number\n" - " \"scriptPubKey\": \"hex\", (string, required) script key\n" - " \"redeemScript\": \"hex\", (string, required for P2SH or P2WSH) redeem script\n" - " \"amount\": value (numeric, required) The amount spent\n" - " }\n" - " ,...\n" - " ]\n" - "4. \"sighashtype\" (string, optional, default=ALL) The signature hash type. Must be one of:\n" + }, + {"sighashtype", RPCArg::Type::STR, /* opt */ true, /* default_val */ "ALL", "The signature hash type. Must be one of:\n" " \"ALL\"\n" " \"NONE\"\n" " \"SINGLE\"\n" " \"ALL|ANYONECANPAY\"\n" " \"NONE|ANYONECANPAY\"\n" " \"SINGLE|ANYONECANPAY\"\n" - + }, + }} + .ToString() + "\nResult:\n" "{\n" " \"hex\" : \"value\", (string) The hex-encoded raw transaction with signature(s)\n" @@ -1044,13 +1004,10 @@ static UniValue sendrawtransaction(const JSONRPCRequest& request) "\nSubmits raw transaction (serialized, hex-encoded) to local node and network.\n" "\nAlso see createrawtransaction and signrawtransactionwithkey calls.\n", { - {"hexstring", RPCArg::Type::STR_HEX, false}, - {"allowhighfees", RPCArg::Type::BOOL, true}, + {"hexstring", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The hex string of the raw transaction"}, + {"allowhighfees", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "Allow high fees"}, }} .ToString() + - "\nArguments:\n" - "1. \"hexstring\" (string, required) The hex string of the raw transaction)\n" - "2. allowhighfees (boolean, optional, default=false) Allow high fees\n" "\nResult:\n" "\"hex\" (string) The transaction hash in hex\n" "\nExamples:\n" @@ -1140,15 +1097,20 @@ static UniValue testmempoolaccept(const JSONRPCRequest& request) { if (request.fHelp || request.params.size() < 1 || request.params.size() > 2) { throw std::runtime_error( - // clang-format off - "testmempoolaccept [\"rawtxs\"] ( allowhighfees )\n" - "\nReturns result of mempool acceptance tests indicating if raw transaction (serialized, hex-encoded) would be accepted by mempool.\n" - "\nThis checks if the transaction violates the consensus or policy rules.\n" - "\nSee sendrawtransaction call.\n" - "\nArguments:\n" - "1. [\"rawtxs\"] (array, required) An array of hex strings of raw transactions.\n" - " Length must be one for now.\n" - "2. allowhighfees (boolean, optional, default=false) Allow high fees\n" + RPCHelpMan{"testmempoolaccept", + "\nReturns result of mempool acceptance tests indicating if raw transaction (serialized, hex-encoded) would be accepted by mempool.\n" + "\nThis checks if the transaction violates the consensus or policy rules.\n" + "\nSee sendrawtransaction call.\n", + { + {"rawtxs", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "An array of hex strings of raw transactions.\n" + " Length must be one for now.", + { + {"rawtx", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", ""}, + }, + }, + {"allowhighfees", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "Allow high fees"}, + }} + .ToString() + "\nResult:\n" "[ (array) The result of the mempool acceptance test for each raw transaction in the input array.\n" " Length is exactly one for now.\n" @@ -1167,7 +1129,6 @@ static UniValue testmempoolaccept(const JSONRPCRequest& request) + HelpExampleCli("testmempoolaccept", "\"signedhex\"") + "\nAs a JSON-RPC call\n" + HelpExampleRpc("testmempoolaccept", "[\"signedhex\"]") - // clang-format on ); } @@ -1241,12 +1202,9 @@ UniValue decodepsbt(const JSONRPCRequest& request) RPCHelpMan{"decodepsbt", "\nReturn a JSON object representing the serialized, base64-encoded partially signed Bitcoin transaction.\n", { - {"psbt", RPCArg::Type::STR, false}, + {"psbt", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The PSBT base64 string"}, }} .ToString() + - "\nArguments:\n" - "1. \"psbt\" (string, required) The PSBT base64 string\n" - "\nResult:\n" "{\n" " \"tx\" : { (json object) The decoded network-serialized unsigned transaction.\n" @@ -1520,20 +1478,13 @@ UniValue combinepsbt(const JSONRPCRequest& request) "\nCombine multiple partially signed Bitcoin transactions into one transaction.\n" "Implements the Combiner role.\n", { - {"txs", RPCArg::Type::ARR, + {"txs", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "A json array of base64 strings of partially signed transactions", { - {"psbt", RPCArg::Type::STR_HEX, false}, + {"psbt", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "A base64 string of a PSBT"}, + }, }, - false}, }} .ToString() + - "\nArguments:\n" - "1. \"txs\" (string) A json array of base64 strings of partially signed transactions\n" - " [\n" - " \"psbt\" (string) A base64 string of a PSBT\n" - " ,...\n" - " ]\n" - "\nResult:\n" " \"psbt\" (string) The base64-encoded partially signed transaction\n" "\nExamples:\n" @@ -1583,15 +1534,11 @@ UniValue finalizepsbt(const JSONRPCRequest& request) "created which has the final_scriptSig and final_scriptWitness fields filled for inputs that are complete.\n" "Implements the Finalizer and Extractor roles.\n", { - {"psbt", RPCArg::Type::STR, false}, - {"extract", RPCArg::Type::BOOL, true}, + {"psbt", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "A base64 string of a PSBT"}, + {"extract", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "true", "If true and the transaction is complete,\n" + " extract and return the complete transaction in normal network serialization instead of the PSBT."}, }} .ToString() + - "\nArguments:\n" - "1. \"psbt\" (string) A base64 string of a PSBT\n" - "2. \"extract\" (boolean, optional, default=true) If true and the transaction is complete, \n" - " extract and return the complete transaction in normal network serialization instead of the PSBT.\n" - "\nResult:\n" "{\n" " \"psbt\" : \"value\", (string) The base64-encoded partially signed transaction if not extracted\n" @@ -1650,59 +1597,38 @@ UniValue createpsbt(const JSONRPCRequest& request) "\nCreates a transaction in the Partially Signed Transaction format.\n" "Implements the Creator role.\n", { - {"inputs", RPCArg::Type::ARR, + {"inputs", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "A json array of json objects", { - {"", RPCArg::Type::OBJ, + {"", RPCArg::Type::OBJ, /* opt */ false, /* default_val */ "", "", { - {"txid", RPCArg::Type::STR_HEX, false}, - {"vout", RPCArg::Type::NUM, false}, - {"sequence", RPCArg::Type::NUM, true}, + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The transaction id"}, + {"vout", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "The output number"}, + {"sequence", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "", "The sequence number"}, }, - false}, + }, + }, }, - false}, - {"outputs", RPCArg::Type::ARR, + {"outputs", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "a json array with outputs (key-value pairs).\n" + "For compatibility reasons, a dictionary, which holds the key-value pairs directly, is also\n" + " accepted as second parameter.", { - {"", RPCArg::Type::OBJ, + {"", RPCArg::Type::OBJ, /* opt */ true, /* default_val */ "", "", { - {"address", RPCArg::Type::AMOUNT, false}, + {"address", RPCArg::Type::AMOUNT, /* opt */ false, /* default_val */ "", "A key-value pair. The key (string) is the bitcoin address, the value (float or string) is the amount in " + CURRENCY_UNIT}, }, - true}, - {"", RPCArg::Type::OBJ, + }, + {"", RPCArg::Type::OBJ, /* opt */ true, /* default_val */ "", "", { - {"data", RPCArg::Type::STR_HEX, false}, + {"data", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "A key-value pair. The key must be \"data\", the value is hex-encoded data"}, + }, }, - true}, }, - false}, - {"locktime", RPCArg::Type::NUM, true}, - {"replaceable", RPCArg::Type::BOOL, true}, + }, + {"locktime", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "0", "Raw locktime. Non-0 value also locktime-activates inputs"}, + {"replaceable", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "Marks this transaction as BIP125 replaceable.\n" + " Allows this transaction to be replaced by a transaction with higher fees. If provided, it is an error if explicit sequence numbers are incompatible."}, }} .ToString() + - "\nArguments:\n" - "1. \"inputs\" (array, required) A json array of json objects\n" - " [\n" - " {\n" - " \"txid\":\"id\", (string, required) The transaction id\n" - " \"vout\":n, (numeric, required) The output number\n" - " \"sequence\":n (numeric, optional) The sequence number\n" - " } \n" - " ,...\n" - " ]\n" - "2. \"outputs\" (array, required) a json array with outputs (key-value pairs)\n" - " [\n" - " {\n" - " \"address\": x.xxx, (obj, optional) A key-value pair. The key (string) is the bitcoin address, the value (float or string) is the amount in " + CURRENCY_UNIT + "\n" - " },\n" - " {\n" - " \"data\": \"hex\" (obj, optional) A key-value pair. The key must be \"data\", the value is hex-encoded data\n" - " }\n" - " ,... More key-value pairs of the above form. For compatibility reasons, a dictionary, which holds the key-value pairs directly, is also\n" - " accepted as second parameter.\n" - " ]\n" - "3. locktime (numeric, optional, default=0) Raw locktime. Non-0 value also locktime-activates inputs\n" - "4. replaceable (boolean, optional, default=false) Marks this transaction as BIP125 replaceable.\n" - " Allows this transaction to be replaced by a transaction with higher fees. If provided, it is an error if explicit sequence numbers are incompatible.\n" "\nResult:\n" " \"psbt\" (string) The resulting raw transaction (base64-encoded string)\n" "\nExamples:\n" @@ -1745,19 +1671,15 @@ UniValue converttopsbt(const JSONRPCRequest& request) "\nConverts a network serialized transaction to a PSBT. This should be used only with createrawtransaction and fundrawtransaction\n" "createpsbt and walletcreatefundedpsbt should be used for new applications.\n", { - {"hexstring", RPCArg::Type::STR_HEX, false}, - {"permitsigdata", RPCArg::Type::BOOL, true}, - {"iswitness", RPCArg::Type::BOOL, true}, - }} - .ToString() + - "\nArguments:\n" - "1. \"hexstring\" (string, required) The hex string of a raw transaction\n" - "2. permitsigdata (boolean, optional, default=false) If true, any signatures in the input will be discarded and conversion.\n" - " will continue. If false, RPC will fail if any signatures are present.\n" - "3. iswitness (boolean, optional) Whether the transaction hex is a serialized witness transaction.\n" + {"hexstring", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The hex string of a raw transaction"}, + {"permitsigdata", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "If true, any signatures in the input will be discarded and conversion.\n" + " will continue. If false, RPC will fail if any signatures are present."}, + {"iswitness", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "", "Whether the transaction hex is a serialized witness transaction.\n" " If iswitness is not present, heuristic tests will be used in decoding. If true, only witness deserializaion\n" " will be tried. If false, only non-witness deserialization will be tried. Only has an effect if\n" - " permitsigdata is true.\n" + " permitsigdata is true."}, + }} + .ToString() + "\nResult:\n" " \"psbt\" (string) The resulting raw transaction (base64-encoded string)\n" "\nExamples:\n" diff --git a/src/rpc/server.cpp b/src/rpc/server.cpp index c565094a10..97745c62d6 100644 --- a/src/rpc/server.cpp +++ b/src/rpc/server.cpp @@ -142,10 +142,6 @@ std::vector ParseHexO(const UniValue& o, std::string strKey) return ParseHexV(find_value(o, strKey), strKey); } -/** - * Note: This interface may still be subject to change. - */ - std::string CRPCTable::help(const std::string& strCommand, const JSONRPCRequest& helpreq) const { std::string strRet; @@ -207,11 +203,9 @@ UniValue help(const JSONRPCRequest& jsonRequest) RPCHelpMan{"help", "\nList all commands, or get help for a specified command.\n", { - {"command", RPCArg::Type::STR, true}, + {"command", RPCArg::Type::STR, /* opt */ true, /* default_val */ "", "The command to get help on"}, }} .ToString() + - "\nArguments:\n" - "1. \"command\" (string, optional) The command to get help on\n" "\nResult:\n" "\"text\" (string) The help text\n" ); @@ -256,9 +250,6 @@ static UniValue uptime(const JSONRPCRequest& jsonRequest) } // clang-format off -/** - * Call Table - */ static const CRPCCommand vRPCCommands[] = { // category name actor (function) argNames // --------------------- ------------------------ ----------------------- ---------- diff --git a/src/rpc/util.cpp b/src/rpc/util.cpp index 0b6bbcb1dc..a1c0134146 100644 --- a/src/rpc/util.cpp +++ b/src/rpc/util.cpp @@ -129,10 +129,124 @@ UniValue DescribeAddress(const CTxDestination& dest) return boost::apply_visitor(DescribeAddressVisitor(), dest); } +struct Section { + Section(const std::string& left, const std::string& right) + : m_left{left}, m_right{right} {} + const std::string m_left; + const std::string m_right; +}; + +struct Sections { + std::vector
m_sections; + size_t m_max_pad{0}; + + void PushSection(const Section& s) + { + m_max_pad = std::max(m_max_pad, s.m_left.size()); + m_sections.push_back(s); + } + + enum class OuterType { + ARR, + OBJ, + NAMED_ARG, // Only set on first recursion + }; + + void Push(const RPCArg& arg, const size_t current_indent = 5, const OuterType outer_type = OuterType::NAMED_ARG) + { + const auto indent = std::string(current_indent, ' '); + const auto indent_next = std::string(current_indent + 2, ' '); + switch (arg.m_type) { + case RPCArg::Type::STR_HEX: + case RPCArg::Type::STR: + case RPCArg::Type::NUM: + case RPCArg::Type::AMOUNT: + case RPCArg::Type::BOOL: { + if (outer_type == OuterType::NAMED_ARG) return; // Nothing more to do for non-recursive types on first recursion + auto left = indent; + if (arg.m_type_str.size() != 0 && outer_type == OuterType::OBJ) { + left += "\"" + arg.m_name + "\":" + arg.m_type_str.at(0); + } else { + left += outer_type == OuterType::OBJ ? arg.ToStringObj() : arg.ToString(); + } + left += ","; + PushSection({left, arg.ToDescriptionString(/* implicitly_required */ outer_type == OuterType::ARR)}); + break; + } + case RPCArg::Type::OBJ: + case RPCArg::Type::OBJ_USER_KEYS: { + const auto right = outer_type == OuterType::NAMED_ARG ? "" : arg.ToDescriptionString(/* implicitly_required */ outer_type == OuterType::ARR); + PushSection({indent + "{", right}); + for (const auto& arg_inner : arg.m_inner) { + Push(arg_inner, current_indent + 2, OuterType::OBJ); + } + if (arg.m_type != RPCArg::Type::OBJ) { + PushSection({indent_next + "...", ""}); + } + PushSection({indent + "}" + (outer_type != OuterType::NAMED_ARG ? "," : ""), ""}); + break; + } + case RPCArg::Type::ARR: { + auto left = indent; + left += outer_type == OuterType::OBJ ? "\"" + arg.m_name + "\":" : ""; + left += "["; + const auto right = outer_type == OuterType::NAMED_ARG ? "" : arg.ToDescriptionString(/* implicitly_required */ outer_type == OuterType::ARR); + PushSection({left, right}); + for (const auto& arg_inner : arg.m_inner) { + Push(arg_inner, current_indent + 2, OuterType::ARR); + } + PushSection({indent_next + "...", ""}); + PushSection({indent + "]" + (outer_type != OuterType::NAMED_ARG ? "," : ""), ""}); + break; + } + + // no default case, so the compiler can warn about missing cases + } + } + + std::string ToString() const + { + std::string ret; + const size_t pad = m_max_pad + 4; + for (const auto& s : m_sections) { + if (s.m_right.empty()) { + ret += s.m_left; + ret += "\n"; + continue; + } + + std::string left = s.m_left; + left.resize(pad, ' '); + ret += left; + + // Properly pad after newlines + std::string right; + size_t begin = 0; + size_t new_line_pos = s.m_right.find_first_of('\n'); + while (true) { + right += s.m_right.substr(begin, new_line_pos - begin); + if (new_line_pos == std::string::npos) { + break; //No new line + } + right += "\n" + std::string(pad, ' '); + begin = s.m_right.find_first_not_of(' ', new_line_pos + 1); + if (begin == std::string::npos) { + break; // Empty line + } + new_line_pos = s.m_right.find_first_of('\n', begin + 1); + } + ret += right; + ret += "\n"; + } + return ret; + } +}; + std::string RPCHelpMan::ToString() const { std::string ret; + // Oneline summary ret += m_name; bool is_optional{false}; for (const auto& arg : m_args) { @@ -145,13 +259,89 @@ std::string RPCHelpMan::ToString() const // If support for positional arguments is deprecated in the future, remove this line assert(!is_optional); } - ret += arg.ToString(); + ret += arg.ToString(/* oneline */ true); } if (is_optional) ret += " )"; ret += "\n"; + // Description ret += m_description; + // Arguments + Sections sections; + for (size_t i{0}; i < m_args.size(); ++i) { + const auto& arg = m_args.at(i); + + if (i == 0) ret += "\nArguments:\n"; + + // Push named argument name and description + const auto str_wrapper = (arg.m_type == RPCArg::Type::STR || arg.m_type == RPCArg::Type::STR_HEX) ? "\"" : ""; + sections.m_sections.emplace_back(std::to_string(i + 1) + ". " + str_wrapper + arg.m_name + str_wrapper, arg.ToDescriptionString()); + sections.m_max_pad = std::max(sections.m_max_pad, sections.m_sections.back().m_left.size()); + + // Recursively push nested args + sections.Push(arg); + } + ret += sections.ToString(); + + return ret; +} + +std::string RPCArg::ToDescriptionString(const bool implicitly_required) const +{ + std::string ret; + ret += "("; + if (m_type_str.size() != 0) { + ret += m_type_str.at(1); + } else { + switch (m_type) { + case Type::STR_HEX: + case Type::STR: { + ret += "string"; + break; + } + case Type::NUM: { + ret += "numeric"; + break; + } + case Type::AMOUNT: { + ret += "numeric or string"; + break; + } + case Type::BOOL: { + ret += "boolean"; + break; + } + case Type::OBJ: + case Type::OBJ_USER_KEYS: { + ret += "json object"; + break; + } + case Type::ARR: { + ret += "json array"; + break; + } + + // no default case, so the compiler can warn about missing cases + } + } + if (!implicitly_required) { + ret += ", "; + if (m_optional) { + ret += "optional"; + if (!m_default_value.empty()) { + ret += ", default=" + m_default_value; + } else { + // TODO enable this assert, when all optional parameters have their default value documented + //assert(false); + } + } else { + ret += "required"; + assert(m_default_value.empty()); // Default value is ignored, and must not be present + } + } + ret += ")"; + ret += m_description.empty() ? "" : " " + m_description; return ret; } @@ -185,9 +375,9 @@ std::string RPCArg::ToStringObj() const assert(false); } -std::string RPCArg::ToString() const +std::string RPCArg::ToString(const bool oneline) const { - if (!m_oneline_description.empty()) return m_oneline_description; + if (oneline && !m_oneline_description.empty()) return m_oneline_description; switch (m_type) { case Type::STR_HEX: @@ -215,7 +405,7 @@ std::string RPCArg::ToString() const case Type::ARR: { std::string res; for (const auto& i : m_inner) { - res += i.ToString() + ","; + res += i.ToString(oneline) + ","; } return "[" + res + "...]"; } diff --git a/src/rpc/util.h b/src/rpc/util.h index b1ab64247c..11238ce9f7 100644 --- a/src/rpc/util.h +++ b/src/rpc/util.h @@ -43,24 +43,54 @@ struct RPCArg { const Type m_type; const std::vector m_inner; //!< Only used for arrays or dicts const bool m_optional; + const std::string m_default_value; //!< Only used for optional args + const std::string m_description; const std::string m_oneline_description; //!< Should be empty unless it is supposed to override the auto-generated summary line - - RPCArg(const std::string& name, const Type& type, const bool optional, const std::string& oneline_description = "") - : m_name{name}, m_type{type}, m_optional{optional}, m_oneline_description{oneline_description} + const std::vector m_type_str; //!< Should be empty unless it is supposed to override the auto-generated type strings. Vector length is either 0 or 2, m_type_str.at(0) will override the type of the value in a key-value pair, m_type_str.at(1) will override the type in the argument description. + + RPCArg( + const std::string& name, + const Type& type, + const bool opt, + const std::string& default_val, + const std::string& description, + const std::string& oneline_description = "", + const std::vector& type_str = {}) + : m_name{name}, + m_type{type}, + m_optional{opt}, + m_default_value{default_val}, + m_description{description}, + m_oneline_description{oneline_description}, + m_type_str{type_str} { assert(type != Type::ARR && type != Type::OBJ); } - RPCArg(const std::string& name, const Type& type, const std::vector& inner, const bool optional, const std::string& oneline_description = "") - : m_name{name}, m_type{type}, m_inner{inner}, m_optional{optional}, m_oneline_description{oneline_description} + RPCArg( + const std::string& name, + const Type& type, + const bool opt, + const std::string& default_val, + const std::string& description, + const std::vector& inner, + const std::string& oneline_description = "", + const std::vector& type_str = {}) + : m_name{name}, + m_type{type}, + m_inner{inner}, + m_optional{opt}, + m_default_value{default_val}, + m_description{description}, + m_oneline_description{oneline_description}, + m_type_str{type_str} { assert(type == Type::ARR || type == Type::OBJ); } - std::string ToString() const; - -private: + std::string ToString(bool oneline = false) const; std::string ToStringObj() const; + std::string ToDescriptionString(bool implicitly_required = false) const; }; class RPCHelpMan diff --git a/src/wallet/rpcdump.cpp b/src/wallet/rpcdump.cpp index fa1e209bf2..0ecfcc1776 100644 --- a/src/wallet/rpcdump.cpp +++ b/src/wallet/rpcdump.cpp @@ -110,18 +110,14 @@ UniValue importprivkey(const JSONRPCRequest& request) if (request.fHelp || request.params.size() < 1 || request.params.size() > 3) throw std::runtime_error( RPCHelpMan{"importprivkey", - "\nAdds a private key (as returned by dumpprivkey) to your wallet. Requires a new wallet backup.\n", + "\nAdds a private key (as returned by dumpprivkey) to your wallet. Requires a new wallet backup.\n" + "Hint: use importmulti to import more than one private key.\n", { - {"privkey", RPCArg::Type::STR, false}, - {"label", RPCArg::Type::STR, true}, - {"rescan", RPCArg::Type::BOOL, true}, + {"privkey", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The private key (see dumpprivkey)"}, + {"label", RPCArg::Type::STR, /* opt */ true, /* default_val */ "current label if address exists, otherwise \"\"", "An optional label"}, + {"rescan", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "true", "Rescan the wallet for transactions"}, }} .ToString() + - "Hint: use importmulti to import more than one private key.\n" - "\nArguments:\n" - "1. \"privkey\" (string, required) The private key (see dumpprivkey)\n" - "2. \"label\" (string, optional, default=current label if address exists, otherwise \"\") An optional label\n" - "3. rescan (boolean, optional, default=true) Rescan the wallet for transactions\n" "\nNote: This call can take over an hour to complete if rescan is true, during that time, other rpc calls\n" "may report that the imported key exists but related transactions are still missing, leading to temporarily incorrect/bogus balances and unspent outputs until rescan completes.\n" "\nExamples:\n" @@ -278,17 +274,12 @@ UniValue importaddress(const JSONRPCRequest& request) RPCHelpMan{"importaddress", "\nAdds an address or script (in hex) that can be watched as if it were in your wallet but cannot be used to spend. Requires a new wallet backup.\n", { - {"address", RPCArg::Type::STR, false}, - {"label", RPCArg::Type::STR, true}, - {"rescan", RPCArg::Type::BOOL, true}, - {"p2sh", RPCArg::Type::BOOL, true}, + {"address", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The Bitcoin address (or hex-encoded script)"}, + {"label", RPCArg::Type::STR, /* opt */ true, /* default_val */ "\"\"", "An optional label"}, + {"rescan", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "true", "Rescan the wallet for transactions"}, + {"p2sh", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "Add the P2SH version of the script as well"}, }} .ToString() + - "\nArguments:\n" - "1. \"address\" (string, required) The Bitcoin address (or hex-encoded script)\n" - "2. \"label\" (string, optional, default=\"\") An optional label\n" - "3. rescan (boolean, optional, default=true) Rescan the wallet for transactions\n" - "4. p2sh (boolean, optional, default=false) Add the P2SH version of the script as well\n" "\nNote: This call can take over an hour to complete if rescan is true, during that time, other rpc calls\n" "may report that the imported address exists but related transactions are still missing, leading to temporarily incorrect/bogus balances and unspent outputs until rescan completes.\n" "If you have the full public key, you should call importpubkey instead of this.\n" @@ -365,13 +356,10 @@ UniValue importprunedfunds(const JSONRPCRequest& request) RPCHelpMan{"importprunedfunds", "\nImports funds without rescan. Corresponding address or script must previously be included in wallet. Aimed towards pruned wallets. The end-user is responsible to import additional transactions that subsequently spend the imported outputs or rescan after the point in the blockchain the transaction is included.\n", { - {"rawtransaction", RPCArg::Type::STR_HEX, false}, - {"txoutproof", RPCArg::Type::STR_HEX, false}, + {"rawtransaction", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "A raw transaction in hex funding an already-existing address in wallet"}, + {"txoutproof", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The hex output from gettxoutproof that contains the transaction"}, }} - .ToString() + - "\nArguments:\n" - "1. \"rawtransaction\" (string, required) A raw transaction in hex funding an already-existing address in wallet\n" - "2. \"txoutproof\" (string, required) The hex output from gettxoutproof that contains the transaction\n" + .ToString() ); CMutableTransaction tx; @@ -434,11 +422,9 @@ UniValue removeprunedfunds(const JSONRPCRequest& request) RPCHelpMan{"removeprunedfunds", "\nDeletes the specified transaction from the wallet. Meant for use with pruned wallets and as a companion to importprunedfunds. This will affect wallet balances.\n", { - {"txid", RPCArg::Type::STR_HEX, false}, + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, /* default_val */ "", "The hex-encoded id of the transaction you are deleting"}, }} .ToString() + - "\nArguments:\n" - "1. \"txid\" (string, required) The hex-encoded id of the transaction you are deleting\n" "\nExamples:\n" + HelpExampleCli("removeprunedfunds", "\"a8d0c0184dde994a09ec054286f1ce581bebf46446a512166eae7628734ea0a5\"") + "\nAs a JSON-RPC call\n" @@ -477,15 +463,11 @@ UniValue importpubkey(const JSONRPCRequest& request) RPCHelpMan{"importpubkey", "\nAdds a public key (in hex) that can be watched as if it were in your wallet but cannot be used to spend. Requires a new wallet backup.\n", { - {"pubkey", RPCArg::Type::STR, false}, - {"label", RPCArg::Type::STR, true}, - {"rescan", RPCArg::Type::BOOL, true}, + {"pubkey", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The hex-encoded public key"}, + {"label", RPCArg::Type::STR, /* opt */ true, /* default_val */ "\"\"", "An optional label"}, + {"rescan", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "true", "Rescan the wallet for transactions"}, }} .ToString() + - "\nArguments:\n" - "1. \"pubkey\" (string, required) The hex-encoded public key\n" - "2. \"label\" (string, optional, default=\"\") An optional label\n" - "3. rescan (boolean, optional, default=true) Rescan the wallet for transactions\n" "\nNote: This call can take over an hour to complete if rescan is true, during that time, other rpc calls\n" "may report that the imported pubkey exists but related transactions are still missing, leading to temporarily incorrect/bogus balances and unspent outputs until rescan completes.\n" "\nExamples:\n" @@ -555,11 +537,9 @@ UniValue importwallet(const JSONRPCRequest& request) RPCHelpMan{"importwallet", "\nImports keys from a wallet dump file (see dumpwallet). Requires a new wallet backup to include imported keys.\n", { - {"filename", RPCArg::Type::STR, false}, + {"filename", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The wallet file"}, }} .ToString() + - "\nArguments:\n" - "1. \"filename\" (string, required) The wallet file\n" "\nExamples:\n" "\nDump the wallet\n" + HelpExampleCli("dumpwallet", "\"test\"") + @@ -690,11 +670,9 @@ UniValue dumpprivkey(const JSONRPCRequest& request) "\nReveals the private key corresponding to 'address'.\n" "Then the importprivkey can be used with this output\n", { - {"address", RPCArg::Type::STR, false}, + {"address", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The bitcoin address for the private key"}, }} .ToString() + - "\nArguments:\n" - "1. \"address\" (string, required) The bitcoin address for the private key\n" "\nResult:\n" "\"key\" (string) The private key\n" "\nExamples:\n" @@ -741,11 +719,9 @@ UniValue dumpwallet(const JSONRPCRequest& request) "Note that if your wallet contains keys which are not derived from your HD seed (e.g. imported keys), these are not covered by\n" "only backing up the seed itself, and must be backed up too (e.g. ensure you back up the whole dumpfile).\n", { - {"filename", RPCArg::Type::STR, false}, + {"filename", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "The filename with path (either absolute or relative to bitcoind)"}, }} .ToString() + - "\nArguments:\n" - "1. \"filename\" (string, required) The filename with path (either absolute or relative to bitcoind)\n" "\nResult:\n" "{ (json object)\n" " \"filename\" : { (string) The filename with full absolute path\n" @@ -1127,57 +1103,49 @@ UniValue importmulti(const JSONRPCRequest& mainRequest) if (mainRequest.fHelp || mainRequest.params.size() < 1 || mainRequest.params.size() > 2) throw std::runtime_error( RPCHelpMan{"importmulti", - "\nImport addresses/scripts (with private or public keys, redeem script (P2SH)), rescanning all addresses in one-shot-only (rescan can be disabled via options). Requires a new wallet backup.\n\n", + "\nImport addresses/scripts (with private or public keys, redeem script (P2SH)), rescanning all addresses in one-shot-only (rescan can be disabled via options). Requires a new wallet backup.\n", { - {"requests", RPCArg::Type::ARR, + {"requests", RPCArg::Type::ARR, /* opt */ false, /* default_val */ "", "Data to be imported", { - {"", RPCArg::Type::OBJ, + {"", RPCArg::Type::OBJ, /* opt */ false, /* default_val */ "", "", { - { - {"scriptPubKey", RPCArg::Type::STR, false}, - {"timestamp", RPCArg::Type::NUM, false}, - {"redeemscript", RPCArg::Type::STR, true}, - {"witnessscript", RPCArg::Type::STR, true}, - {"internal", RPCArg::Type::BOOL, true}, - {"watchonly", RPCArg::Type::BOOL, true}, - {"label", RPCArg::Type::STR, true}, + {"scriptPubKey", RPCArg::Type::STR, /* opt */ false, /* default_val */ "", "Type of scriptPubKey (string for script, json for address)", + /* oneline_description */ "", {"\"