Skip to content

Commit 25424cf

Browse files
laanwjlaanwj
committed
Merge #18346: rpc: Document an RPCResult for all calls; Enforce at compile time
fac5225 rpc: Document an RPCResult for all calls; Enforce at compile time (MarcoFalke) fadd99f rpc: Add missing newline in RPCResult description (MarcoFalke) Pull request description: This documents the RPC Result (type and description, if applicable) everywhere it was missing. The patch can be reviewed with the `git diff` option `-W`/`--function-context`. Also, code won't compile without having an RPCResult documented. ACKs for top commit: laanwj: Lightly tested ACK fac5225 promag: Tested ACK fac5225, built and verified listunspent help output. Tree-SHA512: af2c1af1432beb944993776026c320814bfaecaf202f47359f5758849096ca7051ec6560395a2cc6678dcc111e7c9cf4917d0f0b221bdcf3ed1642e14d0e5b3c
2 parents 8662387 + fac5225 commit 25424cf

File tree

8 files changed

+49
-44
lines changed

8 files changed

+49
-44
lines changed

‎src/rpc/blockchain.cpp

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -345,7 +345,7 @@ static UniValue syncwithvalidationinterfacequeue(const JSONRPCRequest& request)
345345
RPCHelpMan{"syncwithvalidationinterfacequeue",
346346
"\nWaits for the validation interface queue to catch up on everything that was there when we entered this function.\n",
347347
{},
348-
RPCResults{},
348+
RPCResult{RPCResult::Type::NONE, "", ""},
349349
RPCExamples{
350350
HelpExampleCli("syncwithvalidationinterfacequeue","")
351351
+ HelpExampleRpc("syncwithvalidationinterfacequeue","")
@@ -1435,7 +1435,7 @@ static UniValue preciousblock(const JSONRPCRequest& request)
14351435
{
14361436
{"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hash of the block to mark as precious"},
14371437
},
1438-
RPCResults{},
1438+
RPCResult{RPCResult::Type::NONE, "", ""},
14391439
RPCExamples{
14401440
HelpExampleCli("preciousblock", "\"blockhash\"")
14411441
+ HelpExampleRpc("preciousblock", "\"blockhash\"")
@@ -1470,7 +1470,7 @@ static UniValue invalidateblock(const JSONRPCRequest& request)
14701470
{
14711471
{"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hash of the block to mark as invalid"},
14721472
},
1473-
RPCResults{},
1473+
RPCResult{RPCResult::Type::NONE, "", ""},
14741474
RPCExamples{
14751475
HelpExampleCli("invalidateblock", "\"blockhash\"")
14761476
+ HelpExampleRpc("invalidateblock", "\"blockhash\"")
@@ -1509,7 +1509,7 @@ static UniValue reconsiderblock(const JSONRPCRequest& request)
15091509
{
15101510
{"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hash of the block to reconsider"},
15111511
},
1512-
RPCResults{},
1512+
RPCResult{RPCResult::Type::NONE, "", ""},
15131513
RPCExamples{
15141514
HelpExampleCli("reconsiderblock", "\"blockhash\"")
15151515
+ HelpExampleRpc("reconsiderblock", "\"blockhash\"")
@@ -1933,7 +1933,7 @@ static UniValue savemempool(const JSONRPCRequest& request)
19331933
RPCHelpMan{"savemempool",
19341934
"\nDumps the mempool to disk. It will fail until the previous dump is fully loaded.\n",
19351935
{},
1936-
RPCResults{},
1936+
RPCResult{RPCResult::Type::NONE, "", ""},
19371937
RPCExamples{
19381938
HelpExampleCli("savemempool", "")
19391939
+ HelpExampleRpc("savemempool", "")

‎src/rpc/mining.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -751,7 +751,7 @@ static UniValue submitblock(const JSONRPCRequest& request)
751751
{"hexdata", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hex-encoded block data to submit"},
752752
{"dummy", RPCArg::Type::STR, /* default */ "ignored", "dummy value, for compatibility with BIP22. This value is ignored."},
753753
},
754-
RPCResults{},
754+
RPCResult{RPCResult::Type::NONE, "", "Returns JSON Null when valid, a string according to BIP22 otherwise"},
755755
RPCExamples{
756756
HelpExampleCli("submitblock", "\"mydata\"")
757757
+ HelpExampleRpc("submitblock", "\"mydata\"")

‎src/rpc/misc.cpp

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -347,7 +347,7 @@ static UniValue setmocktime(const JSONRPCRequest& request)
347347
{"timestamp", RPCArg::Type::NUM, RPCArg::Optional::NO, UNIX_EPOCH_TIME + "\n"
348348
" Pass 0 to go back to using the system time."},
349349
},
350-
RPCResults{},
350+
RPCResult{RPCResult::Type::NONE, "", ""},
351351
RPCExamples{""},
352352
}.Check(request);
353353

@@ -375,7 +375,7 @@ static UniValue mockscheduler(const JSONRPCRequest& request)
375375
{
376376
{"delta_time", RPCArg::Type::NUM, RPCArg::Optional::NO, "Number of seconds to forward the scheduler into the future." },
377377
},
378-
RPCResults{},
378+
RPCResult{RPCResult::Type::NONE, "", ""},
379379
RPCExamples{""},
380380
}.Check(request);
381381

@@ -579,7 +579,7 @@ static UniValue echo(const JSONRPCRequest& request)
579579
"\nThe difference between echo and echojson is that echojson has argument conversion enabled in the client-side table in "
580580
"bitcoin-cli and the GUI. There is no server-side difference.",
581581
{},
582-
RPCResults{},
582+
RPCResult{RPCResult::Type::NONE, "", "Returns whatever was passed in"},
583583
RPCExamples{""},
584584
}.ToString()
585585
);

‎src/rpc/net.cpp

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ static UniValue ping(const JSONRPCRequest& request)
5454
"Results provided in getpeerinfo, pingtime and pingwait fields are decimal seconds.\n"
5555
"Ping command is handled in queue with all other commands, so it measures processing backlog, not just network ping.\n",
5656
{},
57-
RPCResults{},
57+
RPCResult{RPCResult::Type::NONE, "", ""},
5858
RPCExamples{
5959
HelpExampleCli("ping", "")
6060
+ HelpExampleRpc("ping", "")
@@ -240,7 +240,7 @@ static UniValue addnode(const JSONRPCRequest& request)
240240
{"node", RPCArg::Type::STR, RPCArg::Optional::NO, "The node (see getpeerinfo for nodes)"},
241241
{"command", RPCArg::Type::STR, RPCArg::Optional::NO, "'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"},
242242
},
243-
RPCResults{},
243+
RPCResult{RPCResult::Type::NONE, "", ""},
244244
RPCExamples{
245245
HelpExampleCli("addnode", "\"192.168.0.6:8333\" \"onetry\"")
246246
+ HelpExampleRpc("addnode", "\"192.168.0.6:8333\", \"onetry\"")
@@ -283,7 +283,7 @@ static UniValue disconnectnode(const JSONRPCRequest& request)
283283
{"address", RPCArg::Type::STR, /* default */ "fallback to nodeid", "The IP address/port of the node"},
284284
{"nodeid", RPCArg::Type::NUM, /* default */ "fallback to address", "The node ID (see getpeerinfo for node IDs)"},
285285
},
286-
RPCResults{},
286+
RPCResult{RPCResult::Type::NONE, "", ""},
287287
RPCExamples{
288288
HelpExampleCli("disconnectnode", "\"192.168.0.6:8333\"")
289289
+ HelpExampleCli("disconnectnode", "\"\" 1")
@@ -553,7 +553,7 @@ static UniValue setban(const JSONRPCRequest& request)
553553
{"bantime", RPCArg::Type::NUM, /* default */ "0", "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)"},
554554
{"absolute", RPCArg::Type::BOOL, /* default */ "false", "If set, the bantime must be an absolute timestamp expressed in " + UNIX_EPOCH_TIME},
555555
},
556-
RPCResults{},
556+
RPCResult{RPCResult::Type::NONE, "", ""},
557557
RPCExamples{
558558
HelpExampleCli("setban", "\"192.168.0.6\" \"add\" 86400")
559559
+ HelpExampleCli("setban", "\"192.168.0.0/24\" \"add\"")
@@ -628,7 +628,16 @@ static UniValue listbanned(const JSONRPCRequest& request)
628628
RPCHelpMan{"listbanned",
629629
"\nList all banned IPs/Subnets.\n",
630630
{},
631-
RPCResults{},
631+
RPCResult{RPCResult::Type::ARR, "", "",
632+
{
633+
{RPCResult::Type::OBJ, "", "",
634+
{
635+
{RPCResult::Type::STR, "address", ""},
636+
{RPCResult::Type::NUM_TIME, "banned_until", ""},
637+
{RPCResult::Type::NUM_TIME, "ban_created", ""},
638+
{RPCResult::Type::STR, "ban_reason", ""},
639+
}},
640+
}},
632641
RPCExamples{
633642
HelpExampleCli("listbanned", "")
634643
+ HelpExampleRpc("listbanned", "")
@@ -663,7 +672,7 @@ static UniValue clearbanned(const JSONRPCRequest& request)
663672
RPCHelpMan{"clearbanned",
664673
"\nClear all banned IPs.\n",
665674
{},
666-
RPCResults{},
675+
RPCResult{RPCResult::Type::NONE, "", ""},
667676
RPCExamples{
668677
HelpExampleCli("clearbanned", "")
669678
+ HelpExampleRpc("clearbanned", "")
@@ -685,7 +694,7 @@ static UniValue setnetworkactive(const JSONRPCRequest& request)
685694
{
686695
{"state", RPCArg::Type::BOOL, RPCArg::Optional::NO, "true to enable networking, false to disable"},
687696
},
688-
RPCResults{},
697+
RPCResult{RPCResult::Type::BOOL, "", "The value that was passed in"},
689698
RPCExamples{""},
690699
}.Check(request);
691700

‎src/rpc/server.cpp

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@ UniValue help(const JSONRPCRequest& jsonRequest)
153153

154154
UniValue stop(const JSONRPCRequest& jsonRequest)
155155
{
156+
static const std::string RESULT{PACKAGE_NAME " stopping"};
156157
// Accept the deprecated and ignored 'detach' boolean argument
157158
// Also accept the hidden 'wait' integer argument (milliseconds)
158159
// For instance, 'stop 1000' makes the call wait 1 second before returning
@@ -162,7 +163,7 @@ UniValue stop(const JSONRPCRequest& jsonRequest)
162163
RPCHelpMan{"stop",
163164
"\nRequest a graceful shutdown of " PACKAGE_NAME ".",
164165
{},
165-
RPCResults{},
166+
RPCResult{RPCResult::Type::STR, "", "A string with the content '" + RESULT + "'"},
166167
RPCExamples{""},
167168
}.ToString());
168169
// Event loop will exit after current HTTP requests have been handled, so
@@ -171,7 +172,7 @@ UniValue stop(const JSONRPCRequest& jsonRequest)
171172
if (jsonRequest.params[0].isNum()) {
172173
UninterruptibleSleep(std::chrono::milliseconds{jsonRequest.params[0].get_int()});
173174
}
174-
return PACKAGE_NAME " stopping";
175+
return RESULT;
175176
}
176177

177178
static UniValue uptime(const JSONRPCRequest& jsonRequest)

‎src/rpc/util.h

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -290,11 +290,6 @@ struct RPCResult {
290290
struct RPCResults {
291291
const std::vector<RPCResult> m_results;
292292

293-
RPCResults()
294-
: m_results{}
295-
{
296-
}
297-
298293
RPCResults(RPCResult result)
299294
: m_results{{result}}
300295
{

‎src/wallet/rpcdump.cpp

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ UniValue importprivkey(const JSONRPCRequest& request)
106106
{"label", RPCArg::Type::STR, /* default */ "current label if address exists, otherwise \"\"", "An optional label"},
107107
{"rescan", RPCArg::Type::BOOL, /* default */ "true", "Rescan the wallet for transactions"},
108108
},
109-
RPCResults{},
109+
RPCResult{RPCResult::Type::NONE, "", ""},
110110
RPCExamples{
111111
"\nDump a private key\n"
112112
+ HelpExampleCli("dumpprivkey", "\"myaddress\"") +
@@ -203,7 +203,7 @@ UniValue abortrescan(const JSONRPCRequest& request)
203203
"\nStops current wallet rescan triggered by an RPC call, e.g. by an importprivkey call.\n"
204204
"Note: Use \"getwalletinfo\" to query the scanning progress.\n",
205205
{},
206-
RPCResults{},
206+
RPCResult{RPCResult::Type::BOOL, "", "Whether the abort was successful"},
207207
RPCExamples{
208208
"\nImport a private key\n"
209209
+ HelpExampleCli("importprivkey", "\"mykey\"") +
@@ -242,7 +242,7 @@ UniValue importaddress(const JSONRPCRequest& request)
242242
{"rescan", RPCArg::Type::BOOL, /* default */ "true", "Rescan the wallet for transactions"},
243243
{"p2sh", RPCArg::Type::BOOL, /* default */ "false", "Add the P2SH version of the script as well"},
244244
},
245-
RPCResults{},
245+
RPCResult{RPCResult::Type::NONE, "", ""},
246246
RPCExamples{
247247
"\nImport an address with rescan\n"
248248
+ HelpExampleCli("importaddress", "\"myaddress\"") +
@@ -337,7 +337,7 @@ UniValue importprunedfunds(const JSONRPCRequest& request)
337337
{"rawtransaction", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "A raw transaction in hex funding an already-existing address in wallet"},
338338
{"txoutproof", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "The hex output from gettxoutproof that contains the transaction"},
339339
},
340-
RPCResults{},
340+
RPCResult{RPCResult::Type::NONE, "", ""},
341341
RPCExamples{""},
342342
}.Check(request);
343343

@@ -397,7 +397,7 @@ UniValue removeprunedfunds(const JSONRPCRequest& request)
397397
{
398398
{"txid", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "The hex-encoded id of the transaction you are deleting"},
399399
},
400-
RPCResults{},
400+
RPCResult{RPCResult::Type::NONE, "", ""},
401401
RPCExamples{
402402
HelpExampleCli("removeprunedfunds", "\"a8d0c0184dde994a09ec054286f1ce581bebf46446a512166eae7628734ea0a5\"") +
403403
"\nAs a JSON-RPC call\n"
@@ -443,7 +443,7 @@ UniValue importpubkey(const JSONRPCRequest& request)
443443
{"label", RPCArg::Type::STR, /* default */ "\"\"", "An optional label"},
444444
{"rescan", RPCArg::Type::BOOL, /* default */ "true", "Rescan the wallet for transactions"},
445445
},
446-
RPCResults{},
446+
RPCResult{RPCResult::Type::NONE, "", ""},
447447
RPCExamples{
448448
"\nImport a public key with rescan\n"
449449
+ HelpExampleCli("importpubkey", "\"mypubkey\"") +
@@ -527,7 +527,7 @@ UniValue importwallet(const JSONRPCRequest& request)
527527
{
528528
{"filename", RPCArg::Type::STR, RPCArg::Optional::NO, "The wallet file"},
529529
},
530-
RPCResults{},
530+
RPCResult{RPCResult::Type::NONE, "", ""},
531531
RPCExamples{
532532
"\nDump the wallet\n"
533533
+ HelpExampleCli("dumpwallet", "\"test\"") +

0 commit comments

Comments
 (0)