Skip to content

Commit fac5225

Browse files
author
MarcoFalke
committed
rpc: Document an RPCResult for all calls; Enforce at compile time
1 parent fadd99f commit fac5225

File tree

8 files changed

+46
-41
lines changed

8 files changed

+46
-41
lines changed

‎src/rpc/blockchain.cpp

+5-5
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

+1-1
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

+3-3
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

+16-7
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

+3-2
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

-5
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

+7-7
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\"") +

‎src/wallet/rpcwallet.cpp

+11-11
Original file line numberDiff line numberDiff line change
@@ -301,7 +301,7 @@ static UniValue setlabel(const JSONRPCRequest& request)
301301
{"address", RPCArg::Type::STR, RPCArg::Optional::NO, "The bitcoin address to be associated with a label."},
302302
{"label", RPCArg::Type::STR, RPCArg::Optional::NO, "The label to assign to the address."},
303303
},
304-
RPCResults{},
304+
RPCResult{RPCResult::Type::NONE, "", ""},
305305
RPCExamples{
306306
HelpExampleCli("setlabel", "\"" + EXAMPLE_ADDRESS[0] + "\" \"tabby\"")
307307
+ HelpExampleRpc("setlabel", "\"" + EXAMPLE_ADDRESS[0] + "\", \"tabby\"")
@@ -784,7 +784,7 @@ static UniValue getunconfirmedbalance(const JSONRPCRequest &request)
784784
RPCHelpMan{"getunconfirmedbalance",
785785
"DEPRECATED\nIdentical to getbalances().mine.untrusted_pending\n",
786786
{},
787-
RPCResults{},
787+
RPCResult{RPCResult::Type::NUM, "", "The balance"},
788788
RPCExamples{""},
789789
}.Check(request);
790790

@@ -1776,7 +1776,7 @@ static UniValue abandontransaction(const JSONRPCRequest& request)
17761776
{
17771777
{"txid", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "The transaction id"},
17781778
},
1779-
RPCResults{},
1779+
RPCResult{RPCResult::Type::NONE, "", ""},
17801780
RPCExamples{
17811781
HelpExampleCli("abandontransaction", "\"1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d\"")
17821782
+ HelpExampleRpc("abandontransaction", "\"1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d\"")
@@ -1817,7 +1817,7 @@ static UniValue backupwallet(const JSONRPCRequest& request)
18171817
{
18181818
{"destination", RPCArg::Type::STR, RPCArg::Optional::NO, "The destination directory or file"},
18191819
},
1820-
RPCResults{},
1820+
RPCResult{RPCResult::Type::NONE, "", ""},
18211821
RPCExamples{
18221822
HelpExampleCli("backupwallet", "\"backup.dat\"")
18231823
+ HelpExampleRpc("backupwallet", "\"backup.dat\"")
@@ -1855,7 +1855,7 @@ static UniValue keypoolrefill(const JSONRPCRequest& request)
18551855
{
18561856
{"newsize", RPCArg::Type::NUM, /* default */ "100", "The new keypool size"},
18571857
},
1858-
RPCResults{},
1858+
RPCResult{RPCResult::Type::NONE, "", ""},
18591859
RPCExamples{
18601860
HelpExampleCli("keypoolrefill", "")
18611861
+ HelpExampleRpc("keypoolrefill", "")
@@ -1907,7 +1907,7 @@ static UniValue walletpassphrase(const JSONRPCRequest& request)
19071907
{"passphrase", RPCArg::Type::STR, RPCArg::Optional::NO, "The wallet passphrase"},
19081908
{"timeout", RPCArg::Type::NUM, RPCArg::Optional::NO, "The time to keep the decryption key in seconds; capped at 100000000 (~3 years)."},
19091909
},
1910-
RPCResults{},
1910+
RPCResult{RPCResult::Type::NONE, "", ""},
19111911
RPCExamples{
19121912
"\nUnlock the wallet for 60 seconds\n"
19131913
+ HelpExampleCli("walletpassphrase", "\"my pass phrase\" 60") +
@@ -1987,7 +1987,7 @@ static UniValue walletpassphrasechange(const JSONRPCRequest& request)
19871987
{"oldpassphrase", RPCArg::Type::STR, RPCArg::Optional::NO, "The current passphrase"},
19881988
{"newpassphrase", RPCArg::Type::STR, RPCArg::Optional::NO, "The new passphrase"},
19891989
},
1990-
RPCResults{},
1990+
RPCResult{RPCResult::Type::NONE, "", ""},
19911991
RPCExamples{
19921992
HelpExampleCli("walletpassphrasechange", "\"old one\" \"new one\"")
19931993
+ HelpExampleRpc("walletpassphrasechange", "\"old one\", \"new one\"")
@@ -2037,7 +2037,7 @@ static UniValue walletlock(const JSONRPCRequest& request)
20372037
"After calling this method, you will need to call walletpassphrase again\n"
20382038
"before being able to call any methods which require the wallet to be unlocked.\n",
20392039
{},
2040-
RPCResults{},
2040+
RPCResult{RPCResult::Type::NONE, "", ""},
20412041
RPCExamples{
20422042
"\nSet the passphrase for 2 minutes to perform a transaction\n"
20432043
+ HelpExampleCli("walletpassphrase", "\"my pass phrase\" 120") +
@@ -2082,7 +2082,7 @@ static UniValue encryptwallet(const JSONRPCRequest& request)
20822082
{
20832083
{"passphrase", RPCArg::Type::STR, RPCArg::Optional::NO, "The pass phrase to encrypt the wallet with. It must be at least 1 character, but should be long."},
20842084
},
2085-
RPCResults{},
2085+
RPCResult{RPCResult::Type::STR, "", "A string with further instructions"},
20862086
RPCExamples{
20872087
"\nEncrypt your wallet\n"
20882088
+ HelpExampleCli("encryptwallet", "\"my pass phrase\"") +
@@ -2767,7 +2767,7 @@ static UniValue unloadwallet(const JSONRPCRequest& request)
27672767
{
27682768
{"wallet_name", RPCArg::Type::STR, /* default */ "the wallet name from the RPC request", "The name of the wallet to unload."},
27692769
},
2770-
RPCResults{},
2770+
RPCResult{RPCResult::Type::NONE, "", ""},
27712771
RPCExamples{
27722772
HelpExampleCli("unloadwallet", "wallet_name")
27732773
+ HelpExampleRpc("unloadwallet", "wallet_name")
@@ -4013,7 +4013,7 @@ UniValue sethdseed(const JSONRPCRequest& request)
40134013
{"seed", RPCArg::Type::STR, /* default */ "random seed", "The WIF private key to use as the new HD seed.\n"
40144014
" The seed value can be retrieved using the dumpwallet command. It is the private key marked hdseed=1"},
40154015
},
4016-
RPCResults{},
4016+
RPCResult{RPCResult::Type::NONE, "", ""},
40174017
RPCExamples{
40184018
HelpExampleCli("sethdseed", "")
40194019
+ HelpExampleCli("sethdseed", "false")

0 commit comments

Comments
 (0)