Merge #20556: rpc: Properly document return values (submitblock, gettxout, getblocktemplate, scantxoutset)

fa7ff0790ec21d187f1a32310918b0c8d66e5266 rpc: Properly document submitblock return value (MarcoFalke)
fae542c28b269d4a8a39f48ef829734b1241dd4f rpc: Properly document getblocktemplate return value (MarcoFalke)
fabaccf031cfac718bf05b140f1901d93ee8be67 rpc: Properly document scantxoutset return value (MarcoFalke)
faa2059547389e342991ab0d9382f8694f74fce1 rpc: Properly document gettxout return value (MarcoFalke)

Pull request description:

  Currently a few return values are undocumented. This is causing confusion at the least. See for example #18476

ACKs for top commit:
  fjahr:
    utACK fa7ff0790ec21d187f1a32310918b0c8d66e5266
  amitiuttarwar:
    tACK fa7ff0790e

Tree-SHA512: 933cb8f003163d93dbedb302d4c162514c2698ec6d58dbb9a053da8b8b9a4459b0701a3d9e830ecdabd7f278a46b7a07a3af49ec60703a80fcd75390877294ea
This commit is contained in:
fanquake 2021-03-15 15:20:19 +08:00 committed by Konstantin Akimov
parent c26722fc0e
commit aab2a665c3
No known key found for this signature in database
GPG Key ID: 2176C4A5D01EA524
2 changed files with 21 additions and 8 deletions

View File

@ -1494,9 +1494,9 @@ static RPCHelpMan gettxout()
{"n", RPCArg::Type::NUM, RPCArg::Optional::NO, "vout number"},
{"include_mempool", RPCArg::Type::BOOL, /* default */ "true", "Whether to include the mempool. Note that an unspent output that is spent in the mempool won't appear."},
},
RPCResult{
RPCResult::Type::OBJ, "", "",
{
{
RPCResult{"If the UTXO was not found", RPCResult::Type::NONE, "", ""},
RPCResult{"Otherwise", RPCResult::Type::OBJ, "", "", {
{RPCResult::Type::STR_HEX, "bestblock", "The hash of the block at the tip of the chain"},
{RPCResult::Type::NUM, "confirmations", "The number of confirmations"},
{RPCResult::Type::STR_AMOUNT, "value", "The transaction value in " + CURRENCY_UNIT},
@ -1512,6 +1512,7 @@ static RPCHelpMan gettxout()
}},
{RPCResult::Type::BOOL, "coinbase", "Coinbase or not"},
}},
},
RPCExamples{
"\nGet unspent transactions\n"
+ HelpExampleCli("listunspent", "") +
@ -2721,9 +2722,14 @@ static RPCHelpMan scantxoutset()
},
"[scanobjects,...]"},
},
RPCResult{
RPCResult::Type::OBJ, "", "",
{
RPCResult{"When action=='abort'", RPCResult::Type::BOOL, "", ""},
RPCResult{"When action=='status' and no scan is in progress", RPCResult::Type::NONE, "", ""},
RPCResult{"When action=='status' and scan is in progress", RPCResult::Type::OBJ, "", "",
{
{RPCResult::Type::NUM, "progress", "The scan progress"},
}},
RPCResult{"When action=='start'", RPCResult::Type::OBJ, "", "", {
{RPCResult::Type::BOOL, "success", "Whether the scan was completed"},
{RPCResult::Type::NUM, "txouts", "The number of unspent transaction outputs scanned"},
{RPCResult::Type::NUM, "height", "The current block height (index)"},
@ -2742,6 +2748,7 @@ static RPCHelpMan scantxoutset()
}},
{RPCResult::Type::STR_AMOUNT, "total_amount", "The total amount of all found unspent outputs in " + CURRENCY_UNIT},
}},
},
RPCExamples{""},
[&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
{

View File

@ -579,8 +579,10 @@ static RPCHelpMan getblocktemplate()
},
"\"template_request\""},
},
RPCResult{
RPCResult::Type::OBJ, "", "",
{
RPCResult{"If the proposal was accepted with mode=='proposal'", RPCResult::Type::NONE, "", ""},
RPCResult{"If the proposal was not accepted with mode=='proposal'", RPCResult::Type::STR, "", "According to BIP22"},
RPCResult{"Otherwise", RPCResult::Type::OBJ, "", "",
{
{RPCResult::Type::ARR, "capabilities", "specific client side supported features",
{
@ -655,6 +657,7 @@ static RPCHelpMan getblocktemplate()
{RPCResult::Type::BOOL, "superblocks_enabled", "true, if superblock payments are enabled"},
{RPCResult::Type::STR_HEX, "coinbase_payload", "coinbase transaction payload data encoded in hexadecimal"},
}},
},
RPCExamples{
HelpExampleCli("getblocktemplate", "")
+ HelpExampleRpc("getblocktemplate", "")
@ -1019,7 +1022,10 @@ static RPCHelpMan submitblock()
{"hexdata", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hex-encoded block data to submit"},
{"dummy", RPCArg::Type::STR, /* default */ "ignored", "dummy value, for compatibility with BIP22. This value is ignored."},
},
RPCResult{RPCResult::Type::NONE, "", "Returns JSON Null when valid, a string according to BIP22 otherwise"},
{
RPCResult{"If the block was accepted", RPCResult::Type::NONE, "", ""},
RPCResult{"Otherwise", RPCResult::Type::STR, "", "According to BIP22"},
},
RPCExamples{
HelpExampleCli("submitblock", "\"mydata\"")
+ HelpExampleRpc("submitblock", "\"mydata\"")