diff --git a/src/rpc/abc.cpp b/src/rpc/abc.cpp --- a/src/rpc/abc.cpp +++ b/src/rpc/abc.cpp @@ -40,14 +40,12 @@ "used in the active chain or relayed. This discourages the " "propagation of blocks that you consider excessively large.", { - {"blockSize", RPCArg::Type::NUM, false}, + {"blockSize", RPCArg::Type::NUM, /* opt */ false, + /* default_value */ "", + "Excessive block size in bytes. Must be greater than " + + std::to_string(LEGACY_MAX_BLOCK_SIZE) + "."}, }} .ToString() + - "\nArguments\n" - "1. blockSize (integer, required) Excessive block size in bytes. " - "Must be greater than " + - std::to_string(LEGACY_MAX_BLOCK_SIZE) + - ".\n" "\nResult\n" " blockSize (integer) excessive block size in bytes\n" "\nExamples:\n" + diff --git a/src/rpc/blockchain.cpp b/src/rpc/blockchain.cpp --- a/src/rpc/blockchain.cpp +++ b/src/rpc/blockchain.cpp @@ -229,13 +229,12 @@ "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 */ "0", + "Time in milliseconds to wait for a response. 0 " + "indicates no timeout."}, }} .ToString() + - "\nArguments:\n" - "1. 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" @@ -285,14 +284,14 @@ "info about it.\n" "\nReturns the current block on timeout or exit.\n", { - {"blockhash", RPCArg::Type::STR_HEX, 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" @@ -347,14 +346,14 @@ "height and hash\nof 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 (int)\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" @@ -563,16 +562,16 @@ throw std::runtime_error( RPCHelpMan{"getrawmempool", "\nReturns all transaction ids in memory pool as a json " - "array of string transaction ids.\n", + "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" @@ -606,15 +605,15 @@ "\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 " @@ -682,15 +681,15 @@ "\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 " @@ -755,12 +754,11 @@ 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() + @@ -794,11 +792,10 @@ "\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" + @@ -822,20 +819,20 @@ if (request.fHelp || request.params.size() < 1 || request.params.size() > 2) { throw std::runtime_error( - RPCHelpMan{"getblockheader", - "\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}, - }} + RPCHelpMan{ + "getblockheader", + "\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, /* 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 " @@ -936,15 +933,14 @@ "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" @@ -1108,17 +1104,18 @@ const JSONRPCRequest &request) { if (request.fHelp || request.params.size() != 1) { throw std::runtime_error( - RPCHelpMan{"pruneblockchain", - "", - { - {"height", RPCArg::Type::NUM, false}, - }} + RPCHelpMan{ + "pruneblockchain", + "", + { + {"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 2hours older than the provided timestamp.\n"}, + }} .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" + @@ -1229,18 +1226,16 @@ "gettxout", "\nReturns details about an unspent transaction output.\n", { - {"txid", RPCArg::Type::STR_HEX, false}, - {"n", RPCArg::Type::NUM, false}, - {"include_mempool", RPCArg::Type::BOOL, true}, + {"txid", RPCArg::Type::STR_HEX, /* 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 block hash\n" @@ -1321,20 +1316,18 @@ int nCheckDepth = gArgs.GetArg("-checkblocks", DEFAULT_CHECKBLOCKS); if (request.fHelp || request.params.size() > 2) { throw std::runtime_error( - RPCHelpMan{"verifychain", - "\nVerifies blockchain database.\n", - { - {"checklevel", RPCArg::Type::NUM, true}, - {"nblocks", RPCArg::Type::NUM, true}, - }} + RPCHelpMan{ + "verifychain", + "\nVerifies blockchain database.\n", + { + {"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" + @@ -1752,12 +1745,11 @@ "\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\"") + @@ -1795,7 +1787,9 @@ "work chain, it can effectively PUTS YOU OUT OF CONSENSUS.\n" "USE WITH CAUTION!\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() + "\nResult:\n" @@ -1837,12 +1831,11 @@ "\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\"") + @@ -1876,15 +1869,14 @@ UniValue parkblock(const Config &config, const JSONRPCRequest &request) { if (request.fHelp || request.params.size() != 1) { throw std::runtime_error( - RPCHelpMan{"parkblock", - "\nMarks a block as parked.\n", - { - {"blockhash", RPCArg::Type::STR_HEX, false}, - }} + RPCHelpMan{ + "parkblock", + "\nMarks a block as parked.\n", + { + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ false, + /* default_val */ "", "the hash of the block to park"}, + }} .ToString() + - "\nArguments:\n" - "1. \"blockhash\" (string, required) the " - "hash of the block to park\n" "\nResult:\n" "\nExamples:\n" + HelpExampleCli("parkblock", "\"blockhash\"") + @@ -1927,12 +1919,11 @@ "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\"") + @@ -1964,17 +1955,16 @@ UniValue unparkblock(const Config &config, const JSONRPCRequest &request) { if (request.fHelp || request.params.size() != 1) { throw std::runtime_error( - RPCHelpMan{"unparkblock", - "\nRemoves parked status of a block and its " - "descendants, reconsider them for activation.\n" - "This can be used to undo the effects of parkblock.\n", - { - {"blockhash", RPCArg::Type::STR_HEX, false}, - }} + RPCHelpMan{ + "unparkblock", + "\nRemoves parked status of a block and its descendants, " + "reconsider them for activation.\n" + "This can be used to undo the effects of parkblock.\n", + { + {"blockhash", RPCArg::Type::STR_HEX, /* opt */ false, + /* default_val */ "", "the hash of the block to unpark"}, + }} .ToString() + - "\nArguments:\n" - "1. \"blockhash\" (string, required) the hash of the block to " - "unpark\n" "\nResult:\n" "\nExamples:\n" + HelpExampleCli("unparkblock", "\"blockhash\"") + @@ -2012,15 +2002,14 @@ "\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 " @@ -2148,27 +2137,27 @@ "It won't work without -txindex for utxo_size_inc, *fee or " "*feerate stats.\n", { - {"hash_or_height", RPCArg::Type::NUM, false}, + {"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"}, }} .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\": x.xxx, (numeric) Average fee in the block\n" @@ -2531,75 +2520,75 @@ if (request.fHelp || request.params.size() < 1 || request.params.size() > 2) { throw std::runtime_error( - RPCHelpMan{"scantxoutset", - "\nEXPERIMENTAL warning: this call may be removed or " - "changed in future releases.\n" - "\nScans the unspent transaction output set for entries " - "that match certain output descriptors.\n" - "Examples of output descriptors are:\n" - " addr(
) Outputs whose " - "scriptPubKey corresponds to the specified address " - "(does not include P2PK)\n" - " raw() Outputs whose " - "scriptPubKey equals the specified hex scripts\n" - " combo() P2PK and " - "P2PKH outputs for the given pubkey\n" - " pkh() P2PKH outputs " - "for the given pubkey\n" - " sh(multi(,,,...)) P2SH-multisig " - "outputs for the given threshold and pubkeys\n" - "\nIn the above, either refers to a fixed " - "public key in hexadecimal notation, or to an xpub/xprv " - "optionally followed by one\n" - "or more path elements separated by \"/\", and " - "optionally ending in \"/*\" (unhardened), or \"/*'\" " - "or \"/*h\" (hardened) to specify all\n" - "unhardened or hardened child keys.\n" - "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, - { - {"descriptor", - RPCArg::Type::OBJ, - { - {"desc", RPCArg::Type::STR, false}, - {"range", RPCArg::Type::NUM, true}, - }, - false, - "scanobjects"}, - }, - false}, - }} + RPCHelpMan{ + "scantxoutset", + "\nEXPERIMENTAL warning: this call may be removed or changed " + "in future releases.\n" + "\nScans the unspent transaction output set for entries that " + "match certain output descriptors.\n" + "Examples of output descriptors are:\n" + " addr(
) Outputs whose " + "scriptPubKey corresponds to the specified address does not " + "include P2PK)\n" + " raw() Outputs whose " + "scriptPubKey equals the specified hex scripts\n" + " combo() P2PK and P2PKH " + "outputs for the given pubkey\n" + " pkh() P2PKH outputs for " + "the given pubkey\n" + " sh(multi(,,,...)) P2SH-multisig " + "outputs for the given threshold and pubkeys\n" + "\nIn the above, either refers to a fixed public key " + "in hexadecimal notation, or to an xpub/xprv optionally " + "followed by one\n" + "or more path elements separated by \"/\", and optionally " + "ending in \"/*\" (unhardened), or \"/*'\" or \"/*h\" " + "(hardened) to specify all\n" + "unhardened or hardened child keys.\n" + "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, /* 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::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, /* 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"}, + }, + }, + }, + "[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 --- a/src/rpc/mining.cpp +++ b/src/rpc/mining.cpp @@ -96,15 +96,15 @@ "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" + @@ -190,22 +190,22 @@ if (request.fHelp || request.params.size() < 2 || request.params.size() > 3) { throw std::runtime_error( - 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}, - }} + RPCHelpMan{ + "generatetoaddress", + "\nMine blocks immediately to a specified address before the " + "RPC call returns)\n", + { + {"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" @@ -283,27 +283,33 @@ const JSONRPCRequest &request) { if (request.fHelp || request.params.size() != 3) { throw std::runtime_error( - RPCHelpMan{"prioritisetransaction", - "Accepts the transaction into mined blocks at a higher " - "(or lower) priority\n", - { - {"txid", RPCArg::Type::STR_HEX, false}, - {"dummy", RPCArg::Type::NUM, false}, - {"fee_delta", RPCArg::Type::NUM, false}, - }} + RPCHelpMan{ + "prioritisetransaction", + "Accepts the transaction into mined blocks at a higher " + "(or lower) priority\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."}, + }} .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" - " 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" "\nResult:\n" "true (boolean) Returns true\n" "\nExamples:\n" + @@ -374,35 +380,32 @@ { {"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, - { - {"support", RPCArg::Type::STR, true}, - }, - true}, + {"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, /* opt */ true, + /* default_val */ "", + "client side supported feature, 'longpoll', " + "'coinbasetxn', 'coinbasevalue', 'proposal', " + "'serverlist', 'workid'"}, + }, + }, }, - true, "\"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" - " }\n" - "\n" - "\nResult:\n" "{\n" " \"version\" : n, (numeric) The preferred " @@ -739,15 +742,15 @@ "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\"") + @@ -806,17 +809,16 @@ const JSONRPCRequest &request) { if (request.fHelp || request.params.size() != 1) { throw std::runtime_error( - RPCHelpMan{"submitheader", - "\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}, - }} + RPCHelpMan{ + "submitheader", + "\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, /* 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" + diff --git a/src/rpc/misc.cpp b/src/rpc/misc.cpp --- a/src/rpc/misc.cpp +++ b/src/rpc/misc.cpp @@ -37,12 +37,10 @@ "validateaddress", "\nReturn information about the given bitcoin address.\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 " @@ -89,20 +87,26 @@ if (request.fHelp || request.params.size() < 2 || request.params.size() > 2) { std::string msg = - "createmultisig nrequired [\"key\",...]\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" - + 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"}, + }}, + }} + .ToString() + "\nResult:\n" "{\n" " \"address\":\"multisigaddress\", (string) The value of the new " @@ -167,21 +171,21 @@ const JSONRPCRequest &request) { if (request.fHelp || request.params.size() != 3) { throw std::runtime_error( - RPCHelpMan{"verifymessage", - "\nVerify a signed message\n", - { - {"address", RPCArg::Type::STR, false}, - {"signature", RPCArg::Type::STR, false}, - {"message", RPCArg::Type::STR, false}, - }} + RPCHelpMan{ + "verifymessage", + "\nVerify a signed message\n", + { + {"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" @@ -245,15 +249,14 @@ 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" @@ -293,18 +296,15 @@ static UniValue setmocktime(const Config &config, const JSONRPCRequest &request) { if (request.fHelp || request.params.size() != 1) { - throw std::runtime_error( - RPCHelpMan{ - "setmocktime", - "\nSet the local time to given timestamp (-regtest only)\n", - { - {"timestamp", RPCArg::Type::NUM, false}, - }} - .ToString() + - "\nArguments:\n" - "1. timestamp (integer, required) Unix seconds-since-epoch " - "timestamp\n" - " Pass 0 to go back to using the system time."); + throw std::runtime_error(RPCHelpMan{ + "setmocktime", + "\nSet the local time to given timestamp (-regtest only)\n", + { + {"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()); } if (!config.GetChainParams().MineBlocksOnDemand()) { @@ -362,20 +362,22 @@ */ if (request.fHelp || request.params.size() > 1) { throw std::runtime_error( - RPCHelpMan{"getmemoryinfo", - "Returns an object containing information about memory " - "usage.\n", - { - {"mode", RPCArg::Type::STR, true}, - }} + RPCHelpMan{ + "getmemoryinfo", + "Returns an object containing information about memory " + "usage.\n", + { + {"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 " @@ -462,23 +464,28 @@ " - \"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" diff --git a/src/rpc/net.cpp b/src/rpc/net.cpp --- a/src/rpc/net.cpp +++ b/src/rpc/net.cpp @@ -264,16 +264,16 @@ "full nodes 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\"")); @@ -319,15 +319,13 @@ "\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") + @@ -377,12 +375,12 @@ "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" @@ -650,29 +648,31 @@ if (request.fHelp || request.params.size() < 2 || (strCommand != "add" && strCommand != "remove")) { throw std::runtime_error( - 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::BOOL, true}, - }} + RPCHelpMan{ + "setban", + "\nAttempts to add or remove an IP/Subnet from the " + "banned list.\n", + { + {"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\"") + @@ -800,16 +800,14 @@ static UniValue setnetworkactive(const Config &config, const JSONRPCRequest &request) { if (request.fHelp || request.params.size() != 1) { - throw std::runtime_error( - RPCHelpMan{"setnetworkactive", - "\nDisable/enable all p2p network activity.\n", - { - {"state", RPCArg::Type::BOOL, false}, - }} - .ToString() + - "\nArguments:\n" - "1. \"state\" (boolean, required) true to " - "enable networking, false to disable\n"); + throw std::runtime_error(RPCHelpMan{ + "setnetworkactive", + "\nDisable/enable all p2p network activity.\n", + { + {"state", RPCArg::Type::BOOL, /* opt */ false, + /* default_val */ "", + "true to enable networking, false to disable"}, + }}.ToString()); } if (!g_connman) { @@ -831,15 +829,15 @@ "\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 --- a/src/rpc/rawtransaction.cpp +++ b/src/rpc/rawtransaction.cpp @@ -67,39 +67,38 @@ if (request.fHelp || request.params.size() < 1 || request.params.size() > 3) { throw std::runtime_error( - RPCHelpMan{"getrawtransaction", - "\nNOTE: By default this function only works for " - "mempool transactions. If the -txindex option is\n" - "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}, - }} + RPCHelpMan{ + "getrawtransaction", + "\nNOTE: By default this function only works for " + "mempool transactions. If the -txindex option is\n" + "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" + "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", + { + {"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() + - "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" - "\nResult (if verbose is not set or set to false):\n" "\"data\" (string) The serialized, hex-encoded data for " "'txid'\n" @@ -247,35 +246,36 @@ if (request.fHelp || (request.params.size() != 1 && request.params.size() != 2)) { throw std::runtime_error( - RPCHelpMan{"gettxoutproof", - "\nReturns a hex-encoded proof that \"txid\" was " - "included in a block.\n" - "\nNOTE: By default this function only works sometimes. " - "This is when there is an\n" - "unspent output in the utxo for this transaction. To " - "make it always work,\n" - "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, - { - {"txid", RPCArg::Type::STR_HEX, false}, - }, - false}, - {"blockhash", RPCArg::Type::STR_HEX, true}, - }} + RPCHelpMan{ + "gettxoutproof", + "\nReturns a hex-encoded proof that \"txid\" was " + "included in a block.\n" + "\nNOTE: By default this function only works sometimes. " + "This is when there is an\n" + "unspent output in the utxo for this transaction. To " + "make it always work,\n" + "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, + /* opt */ false, + /* default_val */ "", + "A json array of txids to filter", + { + {"txid", RPCArg::Type::STR_HEX, /* opt */ false, + /* default_val */ "", "A transaction hash"}, + }, + }, + {"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"); @@ -380,12 +380,11 @@ "and throwing an RPC error if the block is not in our " "best chain\n", { - {"proof", RPCArg::Type::STR_HEX, 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"); @@ -552,47 +551,106 @@ if (request.fHelp || request.params.size() < 2 || request.params.size() > 3) { throw std::runtime_error( - // clang-format off - "createrawtransaction [{\"txid\":\"id\",\"vout\":n},...] [{\"address\":amount},{\"data\":\"hex\"},...] ( locktime )\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" + 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"}, + }} + .ToString() + "\nResult:\n" - "\"transaction\" (string) hex string of the transaction\n" + "\"transaction\" (string) hex string of the " + "transaction\n" - "\nExamples:\n" - + HelpExampleCli("createrawtransaction", "\"[{\\\"txid\\\":\\\"myid\\\",\\\"vout\\\":0}]\" \"[{\\\"address\\\":0.01}]\"") - + 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 - ); + "\nExamples:\n" + + HelpExampleCli("createrawtransaction", + "\"[{\\\"txid\\\":\\\"myid\\\",\\\"vout\\\":0}]\" " + "\"[{\\\"address\\\":0.01}]\"") + + 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\\\"}]\"")); } RPCTypeCheck(request.params, @@ -616,13 +674,10 @@ "\nReturn a JSON object representing the serialized, " "hex-encoded transaction.\n", { - {"hexstring", RPCArg::Type::STR_HEX, false}, + {"hexstring", RPCArg::Type::STR_HEX, /* opt */ false, + /* default_val */ "", "The transaction hex string"}, }} .ToString() + - "\nArguments:\n" - "1. \"hexstring\" (string, required) The transaction hex " - "string\n" - "\nResult:\n" "{\n" " \"txid\" : \"id\", (string) The transaction id\n" @@ -692,11 +747,10 @@ 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" @@ -768,23 +822,21 @@ "signed transaction or a \n" "fully signed transaction.", { - {"txs", - RPCArg::Type::ARR, - { - {"hexstring", RPCArg::Type::STR_HEX, false}, - }, - false}, + { + "txs", + RPCArg::Type::ARR, + /* opt */ false, + /* default_val */ "", + "A json array of hex strings of partially " + "signed transactions", + { + {"hexstring", RPCArg::Type::STR_HEX, + /* opt */ false, /* default_val */ "", + "A transaction hash"}, + }, + }, }} .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" @@ -1052,69 +1104,65 @@ "this transaction depends on but may not yet be in the block " "chain.\n", { - {"hexstring", RPCArg::Type::STR_HEX, false}, - {"privkyes", - RPCArg::Type::ARR, - { - {"privatekey", RPCArg::Type::STR_HEX, false}, - }, - false}, - {"prevtxs", - RPCArg::Type::ARR, - { - {"", - RPCArg::Type::OBJ, - { - {"txid", RPCArg::Type::STR_HEX, false}, - {"vout", RPCArg::Type::NUM, false}, - {"scriptPubKey", RPCArg::Type::STR_HEX, false}, - {"redeemScript", RPCArg::Type::STR_HEX, false}, - {"amount", RPCArg::Type::AMOUNT, false}, - }, - true}, - }, - true}, - {"sighashtype", RPCArg::Type::STR, true}, + {"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, + /* opt */ false, /* default_val */ "", + "private key in base58-encoding"}, + }, + }, + { + "prevtxs", + RPCArg::Type::ARR, + /* opt */ true, + /* default_val */ "", + "A json array of previous dependent transaction " + "outputs", + { + { + "", + RPCArg::Type::OBJ, + /* opt */ true, + /* 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"}, + {"scriptPubKey", RPCArg::Type::STR_HEX, + /* opt */ false, /* default_val */ "", + "script key"}, + {"redeemScript", RPCArg::Type::STR_HEX, + /* opt */ true, /* default_val */ "", + "(required for P2SH) redeem script"}, + {"amount", RPCArg::Type::AMOUNT, + /* opt */ false, /* default_val */ "", + "The amount spent"}, + }, + }, + }, + }, + {"sighashtype", RPCArg::Type::STR, /* opt */ true, + /* default_val */ "ALL|FORKID", + "The signature hash type. Must be one of:\n" + " \"ALL|FORKID\"\n" + " \"NONE|FORKID\"\n" + " \"SINGLE|FORKID\"\n" + " \"ALL|FORKID|ANYONECANPAY\"\n" + " \"NONE|FORKID|ANYONECANPAY\"\n" + " \"SINGLE|FORKID|ANYONECANPAY\"\n"}, }} .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) redeem script\n" - " \"amount\": value (numeric, required) The " - "amount spent\n" - " }\n" - " ,...\n" - " ]\n" - "4. \"sighashtype\" (string, optional, " - "default=ALL|FORKID) The signature hash type. Must be one of:\n" - " \"ALL|FORKID\"\n" - " \"NONE|FORKID\"\n" - " \"SINGLE|FORKID\"\n" - " \"ALL|FORKID|ANYONECANPAY\"\n" - " \"NONE|FORKID|ANYONECANPAY\"\n" - " \"SINGLE|FORKID|ANYONECANPAY\"\n" - "\nResult:\n" "{\n" " \"hex\" : \"value\", (string) The hex-encoded " @@ -1180,15 +1228,13 @@ "\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" @@ -1290,35 +1336,54 @@ if (request.fHelp || request.params.size() < 1 || request.params.size() > 2) { throw std::runtime_error( - // clang-format off - "testmempoolaccept [\"rawtxs\"] ( allowhighfees )\n" - "\nReturns 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 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" + "[ (array) The result of the mempool acceptance " + "test for each raw transaction in the input array.\n" " Length is exactly one for now.\n" " {\n" " \"txid\" (string) The transaction hash in hex\n" - " \"allowed\" (boolean) If the mempool allows this tx to be inserted\n" - " \"reject-reason\" (string) Rejection string (only present when 'allowed' is false)\n" + " \"allowed\" (boolean) If the mempool allows this tx to " + "be inserted\n" + " \"reject-reason\" (string) Rejection string (only present when " + "'allowed' is false)\n" " }\n" "]\n" "\nExamples:\n" - "\nCreate a transaction\n" - + HelpExampleCli("createrawtransaction", "\"[{\\\"txid\\\" : \\\"mytxid\\\",\\\"vout\\\":0}]\" \"{\\\"myaddress\\\":0.01}\"") + - "Sign the transaction, and get back the hex\n" - + HelpExampleCli("signrawtransactionwithwallet", "\"myhex\"") + - "\nTest acceptance of the transaction (signed hex)\n" - + HelpExampleCli("testmempoolaccept", "\"signedhex\"") + - "\nAs a JSON-RPC call\n" - + HelpExampleRpc("testmempoolaccept", "[\"signedhex\"]") - // clang-format on - ); + "\nCreate a transaction\n" + + HelpExampleCli( + "createrawtransaction", + "\"[{\\\"txid\\\" : \\\"mytxid\\\",\\\"vout\\\":0}]\" " + "\"{\\\"myaddress\\\":0.01}\"") + + "Sign the transaction, and get back the hex\n" + + HelpExampleCli("signrawtransactionwithwallet", "\"myhex\"") + + "\nTest acceptance of the transaction (signed hex)\n" + + HelpExampleCli("testmempoolaccept", "\"signedhex\"") + + "\nAs a JSON-RPC call\n" + + HelpExampleRpc("testmempoolaccept", "[\"signedhex\"]")); } RPCTypeCheck(request.params, {UniValue::VARR, UniValue::VBOOL}); @@ -1396,12 +1461,10 @@ "\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 " @@ -1672,27 +1735,26 @@ const JSONRPCRequest &request) { if (request.fHelp || request.params.size() != 1) { throw std::runtime_error( - RPCHelpMan{"combinepsbt", - "\nCombine multiple partially signed Bitcoin " - "transactions into one transaction.\n" - "Implements the Combiner role.\n", - { - {"txs", - RPCArg::Type::ARR, - { - {"psbt", RPCArg::Type::STR, false}, - }, - false}, - }} + RPCHelpMan{ + "combinepsbt", + "\nCombine multiple partially signed Bitcoin transactions into " + "one transaction.\n" + "Implements the Combiner role.\n", + { + { + "txs", + RPCArg::Type::ARR, + /* opt */ false, + /* default_val */ "", + "A json array of base64 strings of partially signed " + "transactions", + { + {"psbt", RPCArg::Type::STR, /* opt */ false, + /* default_val */ "", "A base64 string of a PSBT"}, + }, + }, + }} .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" @@ -1752,17 +1814,16 @@ "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 " @@ -1823,79 +1884,85 @@ if (request.fHelp || request.params.size() < 2 || request.params.size() > 3) { throw std::runtime_error( - RPCHelpMan{"createpsbt", - "\nCreates a transaction in the Partially Signed " - "Transaction format.\n" - "Implements the Creator role.\n", - { - {"inputs", - RPCArg::Type::ARR, + RPCHelpMan{ + "createpsbt", + "\nCreates a transaction in the Partially Signed " + "Transaction format.\n" + "Implements the Creator role.\n", + { + { + "inputs", + RPCArg::Type::ARR, + /* opt */ false, + /* default_val */ "", + "A json array of json objects", + { { - {"", - RPCArg::Type::OBJ, - { - {"txid", RPCArg::Type::STR_HEX, false}, - {"vout", RPCArg::Type::NUM, false}, - {"sequence", RPCArg::Type::NUM, true}, - }, - false}, + "", + 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"}, + }, }, - 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, - { - {"address", RPCArg::Type::AMOUNT, false}, - }, - true}, - {"", - RPCArg::Type::OBJ, - { - {"data", RPCArg::Type::STR_HEX, false}, - }, - true}, + "", + 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}, + }, }, - false}, - {"locktime", RPCArg::Type::NUM, true}, - }} + { + "", + 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"}, + }} .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" "\nResult:\n" " \"psbt\" (string) The resulting raw transaction " "(base64-encoded string)\n" @@ -1939,25 +2006,25 @@ if (request.fHelp || request.params.size() < 1 || request.params.size() > 2) { throw std::runtime_error( - RPCHelpMan{"converttopsbt", - "\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}, - }} + RPCHelpMan{ + "converttopsbt", + "\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, /* 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."}, + }} .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" "\nResult:\n" " \"psbt\" (string) The resulting raw transaction " "(base64-encoded string)\n" diff --git a/src/rpc/server.cpp b/src/rpc/server.cpp --- a/src/rpc/server.cpp +++ b/src/rpc/server.cpp @@ -222,9 +222,6 @@ return ParseHexV(find_value(o, strKey), strKey); } -/** - * Note: This interface may still be subject to change. - */ std::string CRPCTable::help(Config &config, const std::string &strCommand, const JSONRPCRequest &helpreq) const { std::string strRet; @@ -291,11 +288,10 @@ "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"); } @@ -369,9 +365,6 @@ return result; } -/** - * Call Table - */ // clang-format off static const ContextFreeRPCCommand vRPCCommands[] = { // category name actor (function) argNames diff --git a/src/rpc/util.h b/src/rpc/util.h --- a/src/rpc/util.h +++ b/src/rpc/util.h @@ -53,29 +53,58 @@ //! Only used for arrays or dicts const std::vector m_inner; const bool m_optional; + const std::string m_default_value; //!< Only used for optional args + const std::string m_description; //! Should be empty unless it is supposed to override the auto-generated //! summary line const std::string m_oneline_description; - 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} { + //! 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. + const std::vector m_type_str; + + 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 ToStringObj() const; + /** + * Return the type string of the argument. + * Set oneline to allow it to be overrided by a custom oneline type string + * (m_oneline_description). + */ + std::string ToString(bool oneline) const; + /** + * Return the type string of the argument when it is in an object (dict). + * Set oneline to get the oneline representation (less whitespace) + */ + std::string ToStringObj(bool oneline) const; + /** + * Return the description string, including the argument type and whether + * the argument is required. + * implicitly_required is set for arguments in an array, which are neither + * optional nor required. + */ + std::string ToDescriptionString(bool implicitly_required = false) const; }; class RPCHelpMan { diff --git a/src/rpc/util.cpp b/src/rpc/util.cpp --- a/src/rpc/util.cpp +++ b/src/rpc/util.cpp @@ -115,9 +115,149 @@ 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, + // Only set on first recursion + NAMED_ARG, + }; + + 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: { + // Nothing more to do for non-recursive types on first recursion + if (outer_type == OuterType::NAMED_ARG) { + return; + } + 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(/* oneline */ false) + : arg.ToString(/* oneline */ false); + } + 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) { + // No new line + break; + } + 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) { @@ -134,20 +274,113 @@ // 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"; + // Default value is ignored, and must not be present + assert(m_default_value.empty()); + } + } + ret += ")"; + ret += m_description.empty() ? "" : " " + m_description; return ret; } -std::string RPCArg::ToStringObj() const { - std::string res = "\"" + m_name + "\":"; +std::string RPCArg::ToStringObj(const bool oneline) const { + std::string res; + res += "\""; + res += m_name; + if (oneline) { + res += "\":"; + } else { + res += "\": "; + } switch (m_type) { case Type::STR: return res + "\"str\""; @@ -162,7 +395,7 @@ case Type::ARR: res += "["; for (const auto &i : m_inner) { - res += i.ToString() + ","; + res += i.ToString(oneline) + ","; } return res + "...]"; case Type::OBJ: @@ -175,8 +408,8 @@ assert(false); } -std::string RPCArg::ToString() const { - if (!m_oneline_description.empty()) { +std::string RPCArg::ToString(const bool oneline) const { + if (oneline && !m_oneline_description.empty()) { return m_oneline_description; } @@ -194,7 +427,7 @@ case Type::OBJ_USER_KEYS: { std::string res; for (size_t i = 0; i < m_inner.size();) { - res += m_inner[i].ToStringObj(); + res += m_inner[i].ToStringObj(oneline); if (++i < m_inner.size()) { res += ","; } @@ -208,7 +441,7 @@ 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/wallet/rpcdump.cpp b/src/wallet/rpcdump.cpp --- a/src/wallet/rpcdump.cpp +++ b/src/wallet/rpcdump.cpp @@ -101,23 +101,23 @@ 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", - { - {"privkey", RPCArg::Type::STR, false}, - {"label", RPCArg::Type::STR, true}, - {"rescan", RPCArg::Type::BOOL, true}, - }} + RPCHelpMan{ + "importprivkey", + "\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, /* 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=\"\") An " - "optional label\n" - "3. rescan (boolean, optional, default=true) Rescan " - "the wallet for transactions\n" "\nNote: This call can take minutes to complete if rescan is true, " "during that time, other rpc calls\n" "may report that the imported key exists but related transactions " @@ -301,21 +301,19 @@ "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 minutes to complete if rescan is true, " "during that time, other rpc calls\n" "may report that the imported address exists but related " @@ -405,24 +403,24 @@ } if (request.fHelp || request.params.size() != 2) { - throw std::runtime_error( - 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}, - }} - .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"); + throw std::runtime_error(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, /* 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()); } CMutableTransaction tx; @@ -497,12 +495,11 @@ "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", "\"a8d0c0184dde994a09ec054286f1" "ce581bebf46446a512166eae762873" @@ -549,18 +546,15 @@ "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 minutes to complete if rescan is true, " "during that time, other rpc calls\n" "may report that the imported pubkey exists but related " @@ -642,11 +636,10 @@ "\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\"") + "\nImport the wallet\n" + @@ -844,12 +837,11 @@ "\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" + @@ -891,25 +883,26 @@ if (request.fHelp || request.params.size() != 1) { throw std::runtime_error( - RPCHelpMan{"dumpwallet", - "\nDumps all wallet keys in a human-readable format to " - "a server-side file. This does not allow overwriting " - "existing files.\n" - "Imported scripts are included in the dumpsfile, but " - "corresponding addresses may not be added automatically " - "by importwallet.\n" - "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}, - }} + RPCHelpMan{ + "dumpwallet", + "\nDumps all wallet keys in a human-readable format to " + "a server-side file. This does not allow overwriting " + "existing files.\n" + "Imported scripts are included in the dumpsfile, but " + "corresponding addresses may not be added automatically " + "by importwallet.\n" + "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, /* 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 " @@ -1443,101 +1436,118 @@ "\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", + "a new wallet backup.\n", { {"requests", RPCArg::Type::ARR, + /* opt */ false, + /* default_val */ "", + "Data to be imported", { - {"", - RPCArg::Type::OBJ, - { - { - {"scriptPubKey", RPCArg::Type::STR, false}, - {"timestamp", RPCArg::Type::NUM, false}, - {"redeemscript", RPCArg::Type::STR, true}, - {"pubkeys", - RPCArg::Type::ARR, - { - {"pubkey", RPCArg::Type::STR, false}, - }, - true}, - {"keys", - RPCArg::Type::ARR, - { - {"key", RPCArg::Type::STR, false}, - }, - true}, - {"internal", RPCArg::Type::BOOL, true}, - {"watchonly", RPCArg::Type::BOOL, true}, - {"label", RPCArg::Type::STR, true}, - }, - }, - false}, + { + "", + RPCArg::Type::OBJ, + /* opt */ false, + /* default_val */ "", + "", + { + {"scriptPubKey", + RPCArg::Type::STR, + /* opt */ false, + /* default_val */ "", + "Type of scriptPubKey (string for script, " + "json for address)", + /* oneline_description */ "", + {"\"