Skip to content

Commit a0d8681

Browse files
laanwjlaanwj
committed
Merge #14726: Use RPCHelpMan for all RPCs
fa5e045 rpc: Documentation fixups (MarcoFalke) fa91e8e Use RPCHelpMan for all RPCs (MarcoFalke) fa520e7 lint: Must use RPCHelpMan to generate the RPC docs (MarcoFalke) Pull request description: The resulting documentation should not change unless the type in the oneline-summary was previously incorrect. (E.g. string vs bool) Tree-SHA512: 4ff355b6a53178f02781e97a7aca7ee1d0d97ff348b6bf5a01caa1c96904ee33c704465fae54c2cd7445097427fd04c71ad3779bb7a7ed886055ef36c1b5a1d0
2 parents d7fbe7d + fa5e045 commit a0d8681

File tree

12 files changed

+1032
-426
lines changed

12 files changed

+1032
-426
lines changed

‎src/rpc/blockchain.cpp

Lines changed: 194 additions & 81 deletions
Large diffs are not rendered by default.

‎src/rpc/mining.cpp

Lines changed: 92 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -87,10 +87,15 @@ static UniValue getnetworkhashps(const JSONRPCRequest& request)
8787
{
8888
if (request.fHelp || request.params.size() > 2)
8989
throw std::runtime_error(
90-
"getnetworkhashps ( nblocks height )\n"
91-
"\nReturns the estimated network hashes per second based on the last n blocks.\n"
92-
"Pass in [blocks] to override # of blocks, -1 specifies since last difficulty change.\n"
93-
"Pass in [height] to estimate the network speed at the time when a certain block was found.\n"
90+
RPCHelpMan{"getnetworkhashps",
91+
"\nReturns the estimated network hashes per second based on the last n blocks.\n"
92+
"Pass in [blocks] to override # of blocks, -1 specifies since last difficulty change.\n"
93+
"Pass in [height] to estimate the network speed at the time when a certain block was found.\n",
94+
{
95+
{"nblocks", RPCArg::Type::NUM, true},
96+
{"height", RPCArg::Type::NUM, true},
97+
}}
98+
.ToString() +
9499
"\nArguments:\n"
95100
"1. nblocks (numeric, optional, default=120) The number of blocks, or -1 for blocks since last difficulty change.\n"
96101
"2. height (numeric, optional, default=-1) To estimate at the time of the given height.\n"
@@ -157,8 +162,14 @@ static UniValue generatetoaddress(const JSONRPCRequest& request)
157162
{
158163
if (request.fHelp || request.params.size() < 2 || request.params.size() > 3)
159164
throw std::runtime_error(
160-
"generatetoaddress nblocks address (maxtries)\n"
161-
"\nMine blocks immediately to a specified address (before the RPC call returns)\n"
165+
RPCHelpMan{"generatetoaddress",
166+
"\nMine blocks immediately to a specified address (before the RPC call returns)\n",
167+
{
168+
{"nblocks", RPCArg::Type::NUM, false},
169+
{"address", RPCArg::Type::STR, false},
170+
{"maxtries", RPCArg::Type::NUM, true},
171+
}}
172+
.ToString() +
162173
"\nArguments:\n"
163174
"1. nblocks (numeric, required) How many blocks are generated immediately.\n"
164175
"2. address (string, required) The address to send the newly generated bitcoin to.\n"
@@ -193,8 +204,9 @@ static UniValue getmininginfo(const JSONRPCRequest& request)
193204
{
194205
if (request.fHelp || request.params.size() != 0)
195206
throw std::runtime_error(
196-
"getmininginfo\n"
197-
"\nReturns a json object containing mining-related information."
207+
RPCHelpMan{"getmininginfo",
208+
"\nReturns a json object containing mining-related information.", {}}
209+
.ToString() +
198210
"\nResult:\n"
199211
"{\n"
200212
" \"blocks\": nnn, (numeric) The current block\n"
@@ -232,8 +244,14 @@ static UniValue prioritisetransaction(const JSONRPCRequest& request)
232244
{
233245
if (request.fHelp || request.params.size() != 3)
234246
throw std::runtime_error(
235-
"prioritisetransaction \"txid\" dummy fee_delta\n"
236-
"Accepts the transaction into mined blocks at a higher (or lower) priority\n"
247+
RPCHelpMan{"prioritisetransaction",
248+
"Accepts the transaction into mined blocks at a higher (or lower) priority\n",
249+
{
250+
{"txid", RPCArg::Type::STR, false},
251+
{"dummy", RPCArg::Type::NUM, false},
252+
{"fee_delta", RPCArg::Type::NUM, false},
253+
}}
254+
.ToString() +
237255
"\nArguments:\n"
238256
"1. \"txid\" (string, required) The transaction id.\n"
239257
"2. dummy (numeric, optional) API-Compatibility for previous API. Must be zero or null.\n"
@@ -295,15 +313,32 @@ static UniValue getblocktemplate(const JSONRPCRequest& request)
295313
{
296314
if (request.fHelp || request.params.size() > 1)
297315
throw std::runtime_error(
298-
"getblocktemplate ( \"template_request\" )\n"
299-
"\nIf the request parameters include a 'mode' key, that is used to explicitly select between the default 'template' request or a 'proposal'.\n"
300-
"It returns data needed to construct a block to work on.\n"
301-
"For full specification, see BIPs 22, 23, 9, and 145:\n"
302-
" https://github.com/bitcoin/bips/blob/master/bip-0022.mediawiki\n"
303-
" https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki\n"
304-
" https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki#getblocktemplate_changes\n"
305-
" https://github.com/bitcoin/bips/blob/master/bip-0145.mediawiki\n"
306-
316+
RPCHelpMan{"getblocktemplate",
317+
"\nIf the request parameters include a 'mode' key, that is used to explicitly select between the default 'template' request or a 'proposal'.\n"
318+
"It returns data needed to construct a block to work on.\n"
319+
"For full specification, see BIPs 22, 23, 9, and 145:\n"
320+
" https://github.com/bitcoin/bips/blob/master/bip-0022.mediawiki\n"
321+
" https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki\n"
322+
" https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki#getblocktemplate_changes\n"
323+
" https://github.com/bitcoin/bips/blob/master/bip-0145.mediawiki\n",
324+
{
325+
{"template_request", RPCArg::Type::OBJ,
326+
{
327+
{"mode", RPCArg::Type::STR, true},
328+
{"capabilities", RPCArg::Type::ARR,
329+
{
330+
{"support", RPCArg::Type::STR, true},
331+
},
332+
true},
333+
{"rules", RPCArg::Type::ARR,
334+
{
335+
{"support", RPCArg::Type::STR, true},
336+
},
337+
true},
338+
},
339+
true, "\"template_request\""},
340+
}}
341+
.ToString() +
307342
"\nArguments:\n"
308343
"1. template_request (json object, optional) A json object in the following spec\n"
309344
" {\n"
@@ -703,10 +738,14 @@ static UniValue submitblock(const JSONRPCRequest& request)
703738
// We allow 2 arguments for compliance with BIP22. Argument 2 is ignored.
704739
if (request.fHelp || request.params.size() < 1 || request.params.size() > 2) {
705740
throw std::runtime_error(
706-
"submitblock \"hexdata\" ( \"dummy\" )\n"
707-
"\nAttempts to submit new block to network.\n"
708-
"See https://en.bitcoin.it/wiki/BIP_0022 for full specification.\n"
709-
741+
RPCHelpMan{"submitblock",
742+
"\nAttempts to submit new block to network.\n"
743+
"See https://en.bitcoin.it/wiki/BIP_0022 for full specification.\n",
744+
{
745+
{"hexdata", RPCArg::Type::STR_HEX, false},
746+
{"dummy", RPCArg::Type::STR, true},
747+
}}
748+
.ToString() +
710749
"\nArguments\n"
711750
"1. \"hexdata\" (string, required) the hex-encoded block data to submit\n"
712751
"2. \"dummy\" (optional) dummy value, for compatibility with BIP22. This value is ignored.\n"
@@ -767,9 +806,13 @@ static UniValue submitheader(const JSONRPCRequest& request)
767806
{
768807
if (request.fHelp || request.params.size() != 1) {
769808
throw std::runtime_error(
770-
"submitheader \"hexdata\"\n"
771-
"\nDecode the given hexdata as a header and submit it as a candidate chain tip if valid."
772-
"\nThrows when the header is invalid.\n"
809+
RPCHelpMan{"submitheader",
810+
"\nDecode the given hexdata as a header and submit it as a candidate chain tip if valid."
811+
"\nThrows when the header is invalid.\n",
812+
{
813+
{"hexdata", RPCArg::Type::STR_HEX, false},
814+
}}
815+
.ToString() +
773816
"\nArguments\n"
774817
"1. \"hexdata\" (string, required) the hex-encoded block header data\n"
775818
"\nResult:\n"
@@ -803,11 +846,16 @@ static UniValue estimatesmartfee(const JSONRPCRequest& request)
803846
{
804847
if (request.fHelp || request.params.size() < 1 || request.params.size() > 2)
805848
throw std::runtime_error(
806-
"estimatesmartfee conf_target (\"estimate_mode\")\n"
807-
"\nEstimates the approximate fee per kilobyte needed for a transaction to begin\n"
808-
"confirmation within conf_target blocks if possible and return the number of blocks\n"
809-
"for which the estimate is valid. Uses virtual transaction size as defined\n"
810-
"in BIP 141 (witness data is discounted).\n"
849+
RPCHelpMan{"estimatesmartfee",
850+
"\nEstimates the approximate fee per kilobyte needed for a transaction to begin\n"
851+
"confirmation within conf_target blocks if possible and return the number of blocks\n"
852+
"for which the estimate is valid. Uses virtual transaction size as defined\n"
853+
"in BIP 141 (witness data is discounted).\n",
854+
{
855+
{"conf_target", RPCArg::Type::NUM, false},
856+
{"estimate_mode", RPCArg::Type::STR, true},
857+
}}
858+
.ToString() +
811859
"\nArguments:\n"
812860
"1. conf_target (numeric) Confirmation target in blocks (1 - 1008)\n"
813861
"2. \"estimate_mode\" (string, optional, default=CONSERVATIVE) The fee estimate mode.\n"
@@ -864,14 +912,19 @@ static UniValue estimaterawfee(const JSONRPCRequest& request)
864912
{
865913
if (request.fHelp || request.params.size() < 1 || request.params.size() > 2)
866914
throw std::runtime_error(
867-
"estimaterawfee conf_target (threshold)\n"
868-
"\nWARNING: This interface is unstable and may disappear or change!\n"
869-
"\nWARNING: This is an advanced API call that is tightly coupled to the specific\n"
870-
" implementation of fee estimation. The parameters it can be called with\n"
871-
" and the results it returns will change if the internal implementation changes.\n"
872-
"\nEstimates the approximate fee per kilobyte needed for a transaction to begin\n"
873-
"confirmation within conf_target blocks if possible. Uses virtual transaction size as\n"
874-
"defined in BIP 141 (witness data is discounted).\n"
915+
RPCHelpMan{"estimaterawfee",
916+
"\nWARNING: This interface is unstable and may disappear or change!\n"
917+
"\nWARNING: This is an advanced API call that is tightly coupled to the specific\n"
918+
" implementation of fee estimation. The parameters it can be called with\n"
919+
" and the results it returns will change if the internal implementation changes.\n"
920+
"\nEstimates the approximate fee per kilobyte needed for a transaction to begin\n"
921+
"confirmation within conf_target blocks if possible. Uses virtual transaction size as\n"
922+
"defined in BIP 141 (witness data is discounted).\n",
923+
{
924+
{"conf_target", RPCArg::Type::NUM, false},
925+
{"threshold", RPCArg::Type::NUM, true},
926+
}}
927+
.ToString() +
875928
"\nArguments:\n"
876929
"1. conf_target (numeric) Confirmation target in blocks (1 - 1008)\n"
877930
"2. threshold (numeric, optional) The proportion of transactions in a given feerate range that must have been\n"

‎src/rpc/misc.cpp

Lines changed: 51 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,16 @@ static UniValue validateaddress(const JSONRPCRequest& request)
3232
{
3333
if (request.fHelp || request.params.size() != 1)
3434
throw std::runtime_error(
35-
"validateaddress \"address\"\n"
36-
"\nReturn information about the given bitcoin address.\n"
37-
"DEPRECATION WARNING: Parts of this command have been deprecated and moved to getaddressinfo. Clients must\n"
38-
"transition to using getaddressinfo to access this information before upgrading to v0.18. The following deprecated\n"
39-
"fields have moved to getaddressinfo and will only be shown here with -deprecatedrpc=validateaddress: ismine, iswatchonly,\n"
40-
"script, hex, pubkeys, sigsrequired, pubkey, addresses, embedded, iscompressed, account, timestamp, hdkeypath, kdmasterkeyid.\n"
35+
RPCHelpMan{"validateaddress",
36+
"\nReturn information about the given bitcoin address.\n"
37+
"DEPRECATION WARNING: Parts of this command have been deprecated and moved to getaddressinfo. Clients must\n"
38+
"transition to using getaddressinfo to access this information before upgrading to v0.18. The following deprecated\n"
39+
"fields have moved to getaddressinfo and will only be shown here with -deprecatedrpc=validateaddress: ismine, iswatchonly,\n"
40+
"script, hex, pubkeys, sigsrequired, pubkey, addresses, embedded, iscompressed, account, timestamp, hdkeypath, kdmasterkeyid.\n",
41+
{
42+
{"address", RPCArg::Type::STR, false},
43+
}}
44+
.ToString() +
4145
"\nArguments:\n"
4246
"1. \"address\" (string, required) The bitcoin address to validate\n"
4347
"\nResult:\n"
@@ -142,8 +146,14 @@ static UniValue verifymessage(const JSONRPCRequest& request)
142146
{
143147
if (request.fHelp || request.params.size() != 3)
144148
throw std::runtime_error(
145-
"verifymessage \"address\" \"signature\" \"message\"\n"
146-
"\nVerify a signed message\n"
149+
RPCHelpMan{"verifymessage",
150+
"\nVerify a signed message\n",
151+
{
152+
{"address", RPCArg::Type::STR, false},
153+
{"signature", RPCArg::Type::STR, false},
154+
{"message", RPCArg::Type::STR, false},
155+
}}
156+
.ToString() +
147157
"\nArguments:\n"
148158
"1. \"address\" (string, required) The bitcoin address to use for the signature.\n"
149159
"2. \"signature\" (string, required) The signature provided by the signer in base 64 encoding (see signmessage).\n"
@@ -198,8 +208,13 @@ static UniValue signmessagewithprivkey(const JSONRPCRequest& request)
198208
{
199209
if (request.fHelp || request.params.size() != 2)
200210
throw std::runtime_error(
201-
"signmessagewithprivkey \"privkey\" \"message\"\n"
202-
"\nSign a message with the private key of an address\n"
211+
RPCHelpMan{"signmessagewithprivkey",
212+
"\nSign a message with the private key of an address\n",
213+
{
214+
{"privkey", RPCArg::Type::STR, false},
215+
{"message", RPCArg::Type::STR, false},
216+
}}
217+
.ToString() +
203218
"\nArguments:\n"
204219
"1. \"privkey\" (string, required) The private key to sign the message with.\n"
205220
"2. \"message\" (string, required) The message to create a signature of.\n"
@@ -237,8 +252,12 @@ static UniValue setmocktime(const JSONRPCRequest& request)
237252
{
238253
if (request.fHelp || request.params.size() != 1)
239254
throw std::runtime_error(
240-
"setmocktime timestamp\n"
241-
"\nSet the local time to given timestamp (-regtest only)\n"
255+
RPCHelpMan{"setmocktime",
256+
"\nSet the local time to given timestamp (-regtest only)\n",
257+
{
258+
{"timestamp", RPCArg::Type::NUM, false},
259+
}}
260+
.ToString() +
242261
"\nArguments:\n"
243262
"1. timestamp (integer, required) Unix seconds-since-epoch timestamp\n"
244263
" Pass 0 to go back to using the system time."
@@ -299,8 +318,12 @@ static UniValue getmemoryinfo(const JSONRPCRequest& request)
299318
*/
300319
if (request.fHelp || request.params.size() > 1)
301320
throw std::runtime_error(
302-
"getmemoryinfo (\"mode\")\n"
303-
"Returns an object containing information about memory usage.\n"
321+
RPCHelpMan{"getmemoryinfo",
322+
"Returns an object containing information about memory usage.\n",
323+
{
324+
{"mode", RPCArg::Type::STR, true},
325+
}}
326+
.ToString() +
304327
"Arguments:\n"
305328
"1. \"mode\" determines what kind of information is returned. This argument is optional, the default mode is \"stats\".\n"
306329
" - \"stats\" returns general statistics about memory usage in the daemon.\n"
@@ -361,7 +384,7 @@ UniValue logging(const JSONRPCRequest& request)
361384
{
362385
if (request.fHelp || request.params.size() > 2) {
363386
throw std::runtime_error(
364-
"logging ( <include> <exclude> )\n"
387+
RPCHelpMan{"logging",
365388
"Gets and sets the logging configuration.\n"
366389
"When called without an argument, returns the list of categories with status that are currently being debug logged or not.\n"
367390
"When called with arguments, adds or removes categories from debug logging and return the lists above.\n"
@@ -371,6 +394,12 @@ UniValue logging(const JSONRPCRequest& request)
371394
"In addition, the following are available as category names with special meanings:\n"
372395
" - \"all\", \"1\" : represent all logging categories.\n"
373396
" - \"none\", \"0\" : even if other logging categories are specified, ignore all of them.\n"
397+
,
398+
{
399+
{"include", RPCArg::Type::STR, true},
400+
{"exclude", RPCArg::Type::STR, true},
401+
}}
402+
.ToString() +
374403
"\nArguments:\n"
375404
"1. \"include\" (array of strings, optional) A json array of categories to add debug logging\n"
376405
" [\n"
@@ -430,11 +459,13 @@ static UniValue echo(const JSONRPCRequest& request)
430459
{
431460
if (request.fHelp)
432461
throw std::runtime_error(
433-
"echo|echojson \"message\" ...\n"
434-
"\nSimply echo back the input arguments. This command is for testing.\n"
435-
"\nThe difference between echo and echojson is that echojson has argument conversion enabled in the client-side table in"
436-
"bitcoin-cli and the GUI. There is no server-side difference."
437-
);
462+
RPCHelpMan{"echo|echojson ...",
463+
"\nSimply echo back the input arguments. This command is for testing.\n"
464+
"\nThe difference between echo and echojson is that echojson has argument conversion enabled in the client-side table in "
465+
"bitcoin-cli and the GUI. There is no server-side difference.",
466+
{}}
467+
.ToString() +
468+
"");
438469

439470
return request.params;
440471
}

0 commit comments

Comments
 (0)