-
Notifications
You must be signed in to change notification settings - Fork 38.7k
Use RPCHelpMan for all RPCs #14726
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Use RPCHelpMan for all RPCs #14726
Conversation
|
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers. ConflictsReviewers, this pull request conflicts with the following ones:
If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first. |
|
Concept ACK! |
test/lint/lint-rpc-help.sh
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add a description of what the linter does :-)
test/lint/lint-rpc-help.sh
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm afraid BSD grep does not support --perl-regexp and --null-data :-\
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This linter doesn't seem like very reliable. Maybe we can just keep it temporarily (add a comment to remove in 6 months)?
If we're are going to keep this, I would suggest adding a comment that describes what this regex is looking for. It seems like it just looking for std::runtime_error constructions with a specifically formatted type of multiline string, which could miss non-uses of RPCHelpMan, and also get in the way of providing detailed error messages in other cases.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps the linter can just exit 0 with an information message if BSD grep is used?
|
Concept ACK Extra credit for adding a linting which makes sure we'll never have to think about this again :-) |
|
Concept ACK. |
|
For reference the diff in the resulting rpc doc is: diff --git a/bumpfee b/bumpfee
index b47ef5b..892a1e6 100644
--- a/bumpfee
+++ b/bumpfee
@@ -1,4 +1,4 @@
-bumpfee "txid" ( options )
+bumpfee "txid" ( options )
Bumps the fee of an opt-in-RBF transaction T, replacing it with a new transaction B.
An opt-in RBF transaction with the given txid must be in the wallet.
diff --git a/estimaterawfee b/estimaterawfee
index 16f57ca..3b99c08 100644
--- a/estimaterawfee
+++ b/estimaterawfee
@@ -1,4 +1,4 @@
-estimaterawfee conf_target (threshold)
+estimaterawfee conf_target ( threshold )
WARNING: This interface is unstable and may disappear or change!
diff --git a/estimatesmartfee b/estimatesmartfee
index fc53c26..af7dd35 100644
--- a/estimatesmartfee
+++ b/estimatesmartfee
@@ -1,4 +1,4 @@
-estimatesmartfee conf_target ("estimate_mode")
+estimatesmartfee conf_target ( "estimate_mode" )
Estimates the approximate fee per kilobyte needed for a transaction to begin
confirmation within conf_target blocks if possible and return the number of blocks
diff --git a/generatetoaddress b/generatetoaddress
index 4506040..7713819 100644
--- a/generatetoaddress
+++ b/generatetoaddress
@@ -1,4 +1,4 @@
-generatetoaddress nblocks address (maxtries)
+generatetoaddress nblocks "address" ( maxtries )
Mine blocks immediately to a specified address (before the RPC call returns)
diff --git a/getblock b/getblock
index 5f94e32..a6e6654 100644
--- a/getblock
+++ b/getblock
@@ -1,4 +1,4 @@
-getblock "blockhash" ( verbosity )
+getblock "blockhash" ( verbosity )
If verbosity is 0, returns a string that is serialized, hex-encoded data for block 'hash'.
If verbosity is 1, returns an Object with information about block <hash>.
diff --git a/getmemoryinfo b/getmemoryinfo
index ab184e3..515a275 100644
--- a/getmemoryinfo
+++ b/getmemoryinfo
@@ -1,4 +1,4 @@
-getmemoryinfo ("mode")
+getmemoryinfo ( "mode" )
Returns an object containing information about memory usage.
Arguments:
1. "mode" determines what kind of information is returned. This argument is optional, the default mode is "stats".
diff --git a/getmempoolancestors b/getmempoolancestors
index 406f659..9382b12 100644
--- a/getmempoolancestors
+++ b/getmempoolancestors
@@ -1,4 +1,4 @@
-getmempoolancestors txid ( verbose )
+getmempoolancestors "txid" ( verbose )
If txid is in the mempool, returns all in-mempool ancestors.
diff --git a/getmempooldescendants b/getmempooldescendants
index 1198324..aacabbe 100644
--- a/getmempooldescendants
+++ b/getmempooldescendants
@@ -1,4 +1,4 @@
-getmempooldescendants txid ( verbose )
+getmempooldescendants "txid" ( verbose )
If txid is in the mempool, returns all in-mempool descendants.
diff --git a/getmempoolentry b/getmempoolentry
index 468470a..cf95910 100644
--- a/getmempoolentry
+++ b/getmempoolentry
@@ -1,4 +1,4 @@
-getmempoolentry txid
+getmempoolentry "txid"
Returns mempool data for given transaction
diff --git a/importprivkey b/importprivkey
index 6ee2531..cd361d5 100644
--- a/importprivkey
+++ b/importprivkey
@@ -1,4 +1,4 @@
-importprivkey "privkey" ( "label" ) ( rescan )
+importprivkey "privkey" ( "label" rescan )
Adds a private key (as returned by dumpprivkey) to your wallet. Requires a new wallet backup.
Hint: use importmulti to import more than one private key.
diff --git a/listreceivedbyaddress b/listreceivedbyaddress
index 95a4a26..baa068d 100644
--- a/listreceivedbyaddress
+++ b/listreceivedbyaddress
@@ -1,4 +1,4 @@
-listreceivedbyaddress ( minconf include_empty include_watchonly address_filter )
+listreceivedbyaddress ( minconf include_empty include_watchonly "address_filter" )
List balances by receiving address.
diff --git a/listreceivedbylabel b/listreceivedbylabel
index 23961c3..40ecc52 100644
--- a/listreceivedbylabel
+++ b/listreceivedbylabel
@@ -1,4 +1,4 @@
-listreceivedbylabel ( minconf include_empty include_watchonly)
+listreceivedbylabel ( minconf include_empty include_watchonly )
List received transactions by label.
diff --git a/listunspent b/listunspent
index bc3baf8..84235b4 100644
--- a/listunspent
+++ b/listunspent
@@ -1,4 +1,4 @@
-listunspent ( minconf maxconf ["address",...] include_unsafe {"minimumAmount":amount,"maximumAmount":amount,"maximumCount":n,"minimumSumAmount":amount} )
+listunspent ( minconf maxconf ["address",...] include_unsafe query_options )
Returns array of unspent transaction outputs
with between minconf and maxconf (inclusive) confirmations.
diff --git a/logging b/logging
index 43d6505..56bd6c5 100644
--- a/logging
+++ b/logging
@@ -1,4 +1,4 @@
-logging ( <include> <exclude> )
+logging ( "include" "exclude" )
Gets and sets the logging configuration.
When called without an argument, returns the list of categories with status that are currently being debug logged or not.
When called with arguments, adds or removes categories from debug logging and return the lists above.
diff --git a/rescanblockchain b/rescanblockchain
index 8971533..fcd8024 100644
--- a/rescanblockchain
+++ b/rescanblockchain
@@ -1,4 +1,4 @@
-rescanblockchain ("start_height") ("stop_height")
+rescanblockchain ( start_height stop_height )
Rescan the local blockchain for wallet related transactions.
diff --git a/sendmany b/sendmany
index ead3d41..79f54cb 100644
--- a/sendmany
+++ b/sendmany
@@ -1,4 +1,4 @@
-sendmany "" {"address":amount,...} ( minconf "comment" ["address",...] replaceable conf_target "estimate_mode")
+sendmany "" {"address":amount} ( minconf "comment" ["address",...] replaceable conf_target "estimate_mode" )
Send multiple times. Amounts are double-precision floating point numbers.
diff --git a/sendtoaddress b/sendtoaddress
index 5b04077..3ca8683 100644
--- a/sendtoaddress
+++ b/sendtoaddress
@@ -1,4 +1,4 @@
-sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount replaceable conf_target "estimate_mode")
+sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount replaceable conf_target "estimate_mode" )
Send an amount to a given address.
diff --git a/sethdseed b/sethdseed
index 6b4b16f..b2be7d2 100644
--- a/sethdseed
+++ b/sethdseed
@@ -1,4 +1,4 @@
-sethdseed ( "newkeypool" "seed" )
+sethdseed ( newkeypool "seed" )
Set or generate a new HD wallet seed. Non-HD wallets will not be upgraded to being a HD wallet. Wallets that are already
HD will have a new HD seed set so that new keys added to the keypool will be derived from this new seed.
diff --git a/submitblock b/submitblock
index d33307a..cdf8d0d 100644
--- a/submitblock
+++ b/submitblock
@@ -1,4 +1,4 @@
-submitblock "hexdata" ( "dummy" )
+submitblock "hexdata" ( "dummy" )
Attempts to submit new block to network.
See https://en.bitcoin.it/wiki/BIP_0022 for full specification.
diff --git a/waitforblock b/waitforblock
index 20889b4..45de4eb 100644
--- a/waitforblock
+++ b/waitforblock
@@ -1,4 +1,4 @@
-waitforblock <blockhash> (timeout)
+waitforblock "blockhash" ( timeout )
Waits for a specific new block and returns useful info about it.
diff --git a/waitfornewblock b/waitfornewblock
index ea184e3..f66d804 100644
--- a/waitfornewblock
+++ b/waitfornewblock
@@ -1,4 +1,4 @@
-waitfornewblock (timeout)
+waitfornewblock ( timeout )
Waits for a specific new block and returns useful info about it.
diff --git a/walletcreatefundedpsbt b/walletcreatefundedpsbt
index 25e77bd..2260770 100644
--- a/walletcreatefundedpsbt
+++ b/walletcreatefundedpsbt
@@ -1,4 +1,4 @@
-walletcreatefundedpsbt [{"txid":"hex","vout":n,"sequence":n},...] [{"address":amount},{"data":"hex"},...] ( locktime {"changeAddress":"hex","changePosition":n,"change_type":"str","includeWatching":bool,"lockUnspents":bool,"feeRate":n,"subtractFeeFromOutputs":[int,...],"replaceable":bool,"conf_target":n,"estimate_mode":"str"} bip32derivs )
+walletcreatefundedpsbt [{"txid":"hex","vout":n,"sequence":n},...] [{"address":amount},{"data":"hex"},...] ( locktime options bip32derivs )
Creates and funds a transaction in the Partially Signed Transaction format. Inputs will be added if supplied inputs are not enough
Implements the Creator and Updater roles. |
fa20188 to
fa520e7
Compare
src/rpc/mining.cpp
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I probably should have asked this in #14530. But is there a plan for:
{"template_request", RPCArg::Type::OBJ,
{
{"mode", RPCArg::Type::STR, true},
{"capabilities", RPCArg::Type::ARR,
{
{"support", RPCArg::Type::STR, true},
},
true},
{"rules", RPCArg::Type::ARR,
{
{"support", RPCArg::Type::STR, true},
},
true},
},
true},to not duplicate:
"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"
" \"rules\":[ (array, optional) A list of strings\n"
" \"support\" (string) client side supported softfork deployment\n"
" ,...\n"
" ]\n"
" }\n"
"\n"below?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ryanofsky You simply pass through the description string for each arg. Though the resulting diff will be larger because in the verbose description the types are not named in the same way across all docs, so I'd like to do that as a follow up pull request.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I had the same doubt as @ryanofsky. Before merging it would be great to see a POC of that @MarcoFalke.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ryanofsky @promag See the code in 92377d37cc0e59713874d5af406abfd84a7d972a, which produces
1. template_request (json object, optional, default=m_default) m_description
{ (json object)
"mode":"str" (string, optional, default=m_default) m_description
[ (json array)
"support" (string, optional, default=m_default) m_description
,...
]
[ (json array)
"support" (string, optional, default=m_default) m_description
,...
]
,...
}
Obviously needs someone to pass in the members (m_description and m_default), like I mentioned above.
|
I think in some of these cases, the previous output might be more readable than the new output. Examples: -scantxoutset "action" [scanobjects,...]
+scantxoutset "action" [{"desc":"str","range":n},...]-sendmany "" {"address":amount,...} ( minconf "comment" ["address",...] replaceable conf_target "estimate_mode")
+sendmany "dummy" {"address":amount} ( minconf "comment" ["address",...] replaceable conf_target "estimate_mode" )In the first case instead of showing name of the argument, this now shows the structure of the argument without any context that would help understand it. Losing the name also seems like an inconvenience if you want to pass named arguments. In the second case, the change goes in the opposite direction. Instead of showing the right dummy value to pass ( I don't know if these changes are desirable, but I think it would be desirable to add some basic flags or options to |
fac071d to
fa3ca45
Compare
fa3ca45 to
fa91e8e
Compare
|
Restored the inconsistencies. Resulting changes should be formatting-only. |
|
Concept ACK |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ACK fa91e8e
I dumped and diffed help with:
Code
diff --git a/src/init.cpp b/src/init.cpp
index 3ab97be329..bc119ab1ca 100644
--- a/src/init.cpp
+++ b/src/init.cpp
@@ -46,6 +46,7 @@
#include <util/system.h>
#include <util/moneystr.h>
#include <validationinterface.h>
+#include <wallet/wallet.h>
#include <warnings.h>
#include <walletinitinterface.h>
#include <stdint.h>
@@ -1240,6 +1241,29 @@ bool AppInitMain(InitInterfaces& interfaces)
for (const auto& client : interfaces.chain_clients) {
client->registerRpcs();
}
+ AddWallet(std::make_shared<CWallet>(*interfaces.chain, WalletLocation(), WalletDatabase::CreateDummy()));
+ JSONRPCRequest jreq;
+ jreq.fHelp = true;
+ for (const auto& entry : tableRPC.mapCommands) {
+ try {
+ entry.second->actor(jreq);
+ } catch (const std::exception& e) {
+ printf("===\n%s\n", e.what());
+ continue;
+ } catch (const UniValue& e) {
+ printf("===\n%s\n", e.write().c_str());
+ continue;
+ } catch (...) {
+ printf("===\n%s\n", entry.second->name.c_str());
+ fflush(stdout);
+ assert(0);
+ }
+ printf("===\n%s\n", entry.second->name.c_str());
+ fflush(stdout);
+ assert(0);
+ }
+ fflush(stdout);
+ abort();
g_rpc_interfaces = &interfaces;
#if ENABLE_ZMQ
RegisterZMQRPCCommands(tableRPC);
diff --git a/src/rpc/server.h b/src/rpc/server.h
index 2d62a76f3c..6fbb35ec57 100644
--- a/src/rpc/server.h
+++ b/src/rpc/server.h
@@ -142,7 +142,7 @@ public:
*/
class CRPCTable
{
-private:
+public:
std::map<std::string, const CRPCCommand*> mapCommands;
public:
CRPCTable();
Complete output ignoring whitespace was:
Output
@@ -263 +263 @@
-createpsbt [{"txid":"id","vout":n},...] [{"address":amount},{"data":"hex"},...] ( locktime ) ( replaceable )
+createpsbt [{"txid":"hex","vout":n,"sequence":n},...] [{"address":amount},{"data":"hex"},...] ( locktime replaceable )
@@ -2022 +2022 @@
-gettxoutproof ["txid",...] ( blockhash )
+gettxoutproof ["txid",...] ( "blockhash" )
@@ -2537 +2537 @@
-listunspent ( minconf maxconf ["addresses",...] [include_unsafe] [query_options])
+listunspent ( minconf maxconf ["address",...] include_unsafe {"minimumAmount":amount,"maximumAmount":amount,"maximumCount":n,"minimumSumAmount":amount} )
@@ -2640 +2640 @@
-lockunspent unlock ([{"txid":"txid","vout":n},...])
+lockunspent unlock ( [{"txid":"hex","vout":n},...] )
@@ -3131 +3131 @@
-signrawtransactionwithkey "hexstring" ["privatekey1",...] ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] sighashtype )
+signrawtransactionwithkey "hexstring" ["privatekey",...] ( [{"txid":"hex","vout":n,"scriptPubKey":"hex","redeemScript":"hex","amount":amount},...] "sighashtype" )
@@ -3186 +3186 @@
-signrawtransactionwithwallet "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] sighashtype )
+signrawtransactionwithwallet "hexstring" ( [{"txid":"hex","vout":n,"scriptPubKey":"hex","redeemScript":"hex","amount":amount},...] "sighashtype" )
@@ -3484 +3484 @@
-walletcreatefundedpsbt [{"txid":"id","vout":n},...] [{"address":amount},{"data":"hex"},...] ( locktime ) ( replaceable ) ( options bip32derivs )
+walletcreatefundedpsbt [{"txid":"hex","vout":n,"sequence":n},...] [{"address":amount},{"data":"hex"},...] ( locktime {"changeAddress":"hex","changePosition":n,"change_type":"str","includeWatching":bool,"lockUnspents":bool,"feeRate":n,"subtractFeeFromOutputs":[int,...],"replaceable":bool,"conf_target":n,"estimate_mode":"str"} bip32derivs )
test/lint/lint-rpc-help.sh
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This linter doesn't seem like very reliable. Maybe we can just keep it temporarily (add a comment to remove in 6 months)?
If we're are going to keep this, I would suggest adding a comment that describes what this regex is looking for. It seems like it just looking for std::runtime_error constructions with a specifically formatted type of multiline string, which could miss non-uses of RPCHelpMan, and also get in the way of providing detailed error messages in other cases.
src/rpc/misc.cpp
Outdated
| ); | ||
| RPCHelpMan{"echo|echojson ...", | ||
| "\nSimply echo back the input arguments. This command is for testing.\n" | ||
| "\nThe difference between echo and echojson is that echojson has argument conversion enabled in the client-side table in" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not directly related (space was missing previously) but maybe add space between "in" and "bitcoin-cli"
|
Added a separate commit for the documentation fixups requested by @practicalswift and @ryanofsky |
ryanofsky
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
utACK fa5e045. Only change is new commit with whitespace/comments.
|
utACK fa5e045 This is a nice step forward in the consistency of RPC help. |
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
|
Nice! Does this allow us to get rid of CRPCConvertParam, which is quite easy to forget? |
Summary: fa5e0452e875a7ca6bf6fe61fdd652d341eece40 rpc: Documentation fixups (MarcoFalke) fa91e8eda541acdb78ca481b74605639f319c108 Use RPCHelpMan for all RPCs (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 Partial backport of Core [[bitcoin/bitcoin#14726 | PR14726]] Excluded the linter commit. Reviewer note: the following RPCs have their help changed in another related PR: testmempoolaccept createrawtransaction createmultisig Depends on D5567 Test Plan: ninja ninja check ./bitcoind ./bitcoin-cli help <RPCs> Verify help is printed without error. Reviewers: O1 Bitcoin ABC, #bitcoin_abc, Fabien Reviewed By: O1 Bitcoin ABC, #bitcoin_abc, Fabien Subscribers: Fabien Differential Revision: https://reviews.bitcoinabc.org/D5548
This is a partial cherry-pick of [PR14726](bitcoin/bitcoin#14726). Some of the more difficult conflicts were skipped. Help strings for RPC calls unique to BCHN have not been converted. I kept the Core syntax styling, as 1) it will make it easier to port additional improvements to RPCHelpMan, and 2) the style inherited from previous project didn't reformat help text properly, but rather just chopped strings at 80 chars, making a big mess. Remaining methods can be incrementally converted. The task conversion task is very well defined, so perhaps using bounties? ### Test plan Observe that the help output is not changed for the worse. There are some improvements. 1. Revert this change and build bitcoind (`ninja bitcoind`) 2. Run `./gen-manpages.sh` from `contrib/devtools` 3. Commit documentation changes `git stage -u && git commit -m test`. This is the RPC documentation before the patch. 4. Revert the revert (step 1) and build bitcoind 5. Run `./gen-manpages.sh` from `contrib/devtools` 6. Run `git diff` to observe there are no changes
The resulting documentation should not change unless the type in the oneline-summary was previously incorrect. (E.g. string vs bool)