Bitcoin Core  24.99.0
P2P Digital Currency
util.h
Go to the documentation of this file.
1 // Copyright (c) 2017-2022 The Bitcoin Core developers
2 // Distributed under the MIT software license, see the accompanying
3 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
4 
5 #ifndef BITCOIN_RPC_UTIL_H
6 #define BITCOIN_RPC_UTIL_H
7 
8 #include <node/transaction.h>
9 #include <outputtype.h>
10 #include <protocol.h>
11 #include <pubkey.h>
12 #include <rpc/protocol.h>
13 #include <rpc/request.h>
14 #include <script/script.h>
15 #include <script/sign.h>
16 #include <script/standard.h>
17 #include <univalue.h>
18 #include <util/check.h>
19 
20 #include <string>
21 #include <variant>
22 #include <vector>
23 
24 static constexpr bool DEFAULT_RPC_DOC_CHECK{
25 #ifdef RPC_DOC_CHECK
26  true
27 #else
28  false
29 #endif
30 };
31 
36 extern const std::string UNIX_EPOCH_TIME;
37 
42 extern const std::string EXAMPLE_ADDRESS[2];
43 
45 class CPubKey;
46 class CScript;
47 struct Sections;
48 
54 std::string GetAllOutputTypes();
55 
58 struct UniValueType {
59  UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
60  UniValueType() : typeAny(true) {}
61  bool typeAny;
63 };
64 
65 /*
66  Check for expected keys/value types in an Object.
67 */
68 void RPCTypeCheckObj(const UniValue& o,
69  const std::map<std::string, UniValueType>& typesExpected,
70  bool fAllowNull = false,
71  bool fStrict = false);
72 
77 uint256 ParseHashV(const UniValue& v, std::string strName);
78 uint256 ParseHashO(const UniValue& o, std::string strKey);
79 std::vector<unsigned char> ParseHexV(const UniValue& v, std::string strName);
80 std::vector<unsigned char> ParseHexO(const UniValue& o, std::string strKey);
81 
89 CAmount AmountFromValue(const UniValue& value, int decimals = 8);
90 
91 using RPCArgList = std::vector<std::pair<std::string, UniValue>>;
92 std::string HelpExampleCli(const std::string& methodname, const std::string& args);
93 std::string HelpExampleCliNamed(const std::string& methodname, const RPCArgList& args);
94 std::string HelpExampleRpc(const std::string& methodname, const std::string& args);
95 std::string HelpExampleRpcNamed(const std::string& methodname, const RPCArgList& args);
96 
97 CPubKey HexToPubKey(const std::string& hex_in);
98 CPubKey AddrToPubKey(const FillableSigningProvider& keystore, const std::string& addr_in);
99 CTxDestination AddAndGetMultisigDestination(const int required, const std::vector<CPubKey>& pubkeys, OutputType type, FillableSigningProvider& keystore, CScript& script_out);
100 
102 
104 unsigned int ParseConfirmTarget(const UniValue& value, unsigned int max_target);
105 
107 UniValue JSONRPCTransactionError(TransactionError terr, const std::string& err_string = "");
108 
110 std::pair<int64_t, int64_t> ParseDescriptorRange(const UniValue& value);
111 
113 std::vector<CScript> EvalDescriptorStringOrObject(const UniValue& scanobject, FlatSigningProvider& provider);
114 
117 
122 enum class OuterType {
123  ARR,
124  OBJ,
125  NONE, // Only set on first recursion
126 };
127 
129  bool skip_type_check{false};
130  std::string oneline_description{};
131  std::vector<std::string> type_str{};
132  bool hidden{false};
133 };
134 
135 struct RPCArg {
136  enum class Type {
137  OBJ,
138  ARR,
139  STR,
140  NUM,
141  BOOL,
142  OBJ_USER_KEYS,
143  AMOUNT,
144  STR_HEX,
145  RANGE,
146  };
147 
148  enum class Optional {
150  NO,
159  OMITTED,
160  };
162  using DefaultHint = std::string;
164  using Default = UniValue;
165  using Fallback = std::variant<Optional, DefaultHint, Default>;
166 
167  const std::string m_names;
168  const Type m_type;
169  const std::vector<RPCArg> m_inner;
171  const std::string m_description;
173 
175  std::string name,
176  Type type,
177  Fallback fallback,
178  std::string description,
179  RPCArgOptions opts = {})
180  : m_names{std::move(name)},
181  m_type{std::move(type)},
182  m_fallback{std::move(fallback)},
183  m_description{std::move(description)},
184  m_opts{std::move(opts)}
185  {
186  CHECK_NONFATAL(type != Type::ARR && type != Type::OBJ && type != Type::OBJ_USER_KEYS);
187  }
188 
190  std::string name,
191  Type type,
192  Fallback fallback,
193  std::string description,
194  std::vector<RPCArg> inner,
195  RPCArgOptions opts = {})
196  : m_names{std::move(name)},
197  m_type{std::move(type)},
198  m_inner{std::move(inner)},
199  m_fallback{std::move(fallback)},
200  m_description{std::move(description)},
201  m_opts{std::move(opts)}
202  {
203  CHECK_NONFATAL(type == Type::ARR || type == Type::OBJ || type == Type::OBJ_USER_KEYS);
204  }
205 
206  bool IsOptional() const;
207 
212  UniValue MatchesType(const UniValue& request) const;
213 
215  std::string GetFirstName() const;
216 
218  std::string GetName() const;
219 
224  std::string ToString(bool oneline) const;
229  std::string ToStringObj(bool oneline) const;
234  std::string ToDescriptionString(bool is_named_arg) const;
235 };
236 
237 struct RPCResult {
238  enum class Type {
239  OBJ,
240  ARR,
241  STR,
242  NUM,
243  BOOL,
244  NONE,
245  ANY,
246  STR_AMOUNT,
247  STR_HEX,
248  OBJ_DYN,
249  ARR_FIXED,
250  NUM_TIME,
251  ELISION,
252  };
253 
254  const Type m_type;
255  const std::string m_key_name;
256  const std::vector<RPCResult> m_inner;
257  const bool m_optional;
258  const bool m_skip_type_check;
259  const std::string m_description;
260  const std::string m_cond;
261 
263  std::string cond,
264  Type type,
265  std::string m_key_name,
266  bool optional,
267  std::string description,
268  std::vector<RPCResult> inner = {})
269  : m_type{std::move(type)},
270  m_key_name{std::move(m_key_name)},
271  m_inner{std::move(inner)},
272  m_optional{optional},
273  m_skip_type_check{false},
274  m_description{std::move(description)},
275  m_cond{std::move(cond)}
276  {
277  CHECK_NONFATAL(!m_cond.empty());
278  CheckInnerDoc();
279  }
280 
282  std::string cond,
283  Type type,
284  std::string m_key_name,
285  std::string description,
286  std::vector<RPCResult> inner = {})
287  : RPCResult{std::move(cond), type, std::move(m_key_name), /*optional=*/false, std::move(description), std::move(inner)} {}
288 
290  Type type,
291  std::string m_key_name,
292  bool optional,
293  std::string description,
294  std::vector<RPCResult> inner = {},
295  bool skip_type_check = false)
296  : m_type{std::move(type)},
297  m_key_name{std::move(m_key_name)},
298  m_inner{std::move(inner)},
299  m_optional{optional},
300  m_skip_type_check{skip_type_check},
301  m_description{std::move(description)},
302  m_cond{}
303  {
304  CheckInnerDoc();
305  }
306 
308  Type type,
309  std::string m_key_name,
310  std::string description,
311  std::vector<RPCResult> inner = {},
312  bool skip_type_check = false)
313  : RPCResult{type, std::move(m_key_name), /*optional=*/false, std::move(description), std::move(inner), skip_type_check} {}
314 
316  void ToSections(Sections& sections, OuterType outer_type = OuterType::NONE, const int current_indent = 0) const;
318  std::string ToStringObj() const;
320  std::string ToDescriptionString() const;
324  UniValue MatchesType(const UniValue& result) const;
325 
326 private:
327  void CheckInnerDoc() const;
328 };
329 
330 struct RPCResults {
331  const std::vector<RPCResult> m_results;
332 
334  : m_results{{result}}
335  {
336  }
337 
338  RPCResults(std::initializer_list<RPCResult> results)
339  : m_results{results}
340  {
341  }
342 
346  std::string ToDescriptionString() const;
347 };
348 
349 struct RPCExamples {
350  const std::string m_examples;
351  explicit RPCExamples(
352  std::string examples)
353  : m_examples(std::move(examples))
354  {
355  }
356  std::string ToDescriptionString() const;
357 };
358 
360 {
361 public:
362  RPCHelpMan(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples);
363  using RPCMethodImpl = std::function<UniValue(const RPCHelpMan&, const JSONRPCRequest&)>;
364  RPCHelpMan(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples, RPCMethodImpl fun);
365 
366  UniValue HandleRequest(const JSONRPCRequest& request) const;
367  std::string ToString() const;
369  UniValue GetArgMap() const;
371  bool IsValidNumArgs(size_t num_args) const;
372  std::vector<std::string> GetArgNames() const;
373 
374  const std::string m_name;
375 
376 private:
378  const std::string m_description;
379  const std::vector<RPCArg> m_args;
382 };
383 
384 #endif // BITCOIN_RPC_UTIL_H
int64_t CAmount
Amount in satoshis (Can be negative)
Definition: amount.h:12
#define CHECK_NONFATAL(condition)
Identity function.
Definition: check.h:46
An encapsulated public key.
Definition: pubkey.h:34
Serialized script, used inside transaction inputs and outputs.
Definition: script.h:411
Fillable signing provider that keeps keys in an address->secret map.
std::function< UniValue(const RPCHelpMan &, const JSONRPCRequest &)> RPCMethodImpl
Definition: util.h:363
const RPCExamples m_examples
Definition: util.h:381
std::vector< std::string > GetArgNames() const
Definition: util.cpp:608
RPCHelpMan(std::string name, std::string description, std::vector< RPCArg > args, RPCResults results, RPCExamples examples)
Definition: util.cpp:477
const std::string m_description
Definition: util.h:378
bool IsValidNumArgs(size_t num_args) const
If the supplied number of args is neither too small nor too high.
Definition: util.cpp:596
const RPCMethodImpl m_fun
Definition: util.h:377
const std::string m_name
Definition: util.h:374
const RPCResults m_results
Definition: util.h:380
const std::vector< RPCArg > m_args
Definition: util.h:379
std::string ToString() const
Definition: util.cpp:617
UniValue GetArgMap() const
Return the named args that need to be converted from string to another JSON type.
Definition: util.cpp:668
UniValue HandleRequest(const JSONRPCRequest &request) const
Definition: util.cpp:547
256-bit opaque blob.
Definition: uint256.h:105
TransactionError
Definition: error.h:22
ArgsManager args
OutputType
Definition: outputtype.h:17
ServiceFlags
nServices flags
Definition: protocol.h:273
const char * name
Definition: rest.cpp:46
RPCErrorCode
Bitcoin RPC error codes.
Definition: protocol.h:24
std::pair< int64_t, int64_t > ParseDescriptorRange(const UniValue &value)
Parse a JSON range specified as int64, or [int64, int64].
Definition: util.cpp:1112
std::vector< unsigned char > ParseHexV(const UniValue &v, std::string strName)
Definition: util.cpp:86
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
Definition: util.cpp:139
std::vector< std::pair< std::string, UniValue > > RPCArgList
Definition: util.h:91
UniValue GetServicesNames(ServiceFlags services)
Returns, given services flags, a list of humanly readable (known) network services.
Definition: util.cpp:1166
CTxDestination AddAndGetMultisigDestination(const int required, const std::vector< CPubKey > &pubkeys, OutputType type, FillableSigningProvider &keystore, CScript &script_out)
Definition: util.cpp:209
std::string HelpExampleRpcNamed(const std::string &methodname, const RPCArgList &args)
Definition: util.cpp:163
UniValue JSONRPCTransactionError(TransactionError terr, const std::string &err_string="")
Definition: util.cpp:342
static constexpr bool DEFAULT_RPC_DOC_CHECK
Definition: util.h:24
RPCErrorCode RPCErrorFromTransactionError(TransactionError terr)
Definition: util.cpp:323
OuterType
Serializing JSON objects depends on the outer type.
Definition: util.h:122
std::vector< CScript > EvalDescriptorStringOrObject(const UniValue &scanobject, FlatSigningProvider &provider)
Evaluate a descriptor given as a string, or as a {"desc":...,"range":...} object, with default range ...
Definition: util.cpp:1128
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
Definition: util.cpp:157
CAmount AmountFromValue(const UniValue &value, int decimals=8)
Validate and return a CAmount from a UniValue number or string.
Definition: util.cpp:61
const std::string UNIX_EPOCH_TIME
String used to describe UNIX epoch time in documentation, factored out to a constant for consistency.
Definition: util.cpp:21
void RPCTypeCheckObj(const UniValue &o, const std::map< std::string, UniValueType > &typesExpected, bool fAllowNull=false, bool fStrict=false)
Definition: util.cpp:34
std::string GetAllOutputTypes()
Gets all existing output types formatted for RPC help sections.
Definition: util.cpp:24
CPubKey HexToPubKey(const std::string &hex_in)
Definition: util.cpp:175
uint256 ParseHashO(const UniValue &o, std::string strKey)
Definition: util.cpp:82
std::vector< unsigned char > ParseHexO(const UniValue &o, std::string strKey)
Definition: util.cpp:95
uint256 ParseHashV(const UniValue &v, std::string strName)
Utilities: convert hex-encoded Values (throws error if not hex).
Definition: util.cpp:73
const std::string EXAMPLE_ADDRESS[2]
Example bech32 addresses for the RPCExamples help documentation.
Definition: util.cpp:22
unsigned int ParseConfirmTarget(const UniValue &value, unsigned int max_target)
Parse a confirm target option and raise an RPC error if it is invalid.
Definition: util.cpp:313
std::string HelpExampleCliNamed(const std::string &methodname, const RPCArgList &args)
Definition: util.cpp:144
CPubKey AddrToPubKey(const FillableSigningProvider &keystore, const std::string &addr_in)
Definition: util.cpp:188
UniValue DescribeAddress(const CTxDestination &dest)
Definition: util.cpp:308
std::variant< CNoDestination, PKHash, ScriptHash, WitnessV0ScriptHash, WitnessV0KeyHash, WitnessV1Taproot, WitnessUnknown > CTxDestination
A txout script template with a specific destination.
Definition: standard.h:149
Definition: util.h:135
Type
Definition: util.h:136
@ RANGE
Special type that is a NUM or [NUM,NUM].
@ OBJ_USER_KEYS
Special type where the user must set the keys e.g. to define multiple addresses; as opposed to e....
@ STR_HEX
Special type that is a STR with only hex chars.
@ AMOUNT
Special type representing a floating point amount (can be either NUM or STR)
const std::vector< RPCArg > m_inner
Only used for arrays or dicts.
Definition: util.h:169
const RPCArgOptions m_opts
Definition: util.h:172
const std::string m_names
The name of the arg (can be empty for inner args, can contain multiple aliases separated by | for nam...
Definition: util.h:167
const Fallback m_fallback
Definition: util.h:170
std::string ToString(bool oneline) const
Return the type string of the argument.
Definition: util.cpp:1063
RPCArg(std::string name, Type type, Fallback fallback, std::string description, RPCArgOptions opts={})
Definition: util.h:174
UniValue MatchesType(const UniValue &request) const
Check whether the request JSON type matches.
Definition: util.cpp:720
const std::string m_description
Definition: util.h:171
std::string DefaultHint
Hint for default value.
Definition: util.h:162
bool IsOptional() const
Definition: util.cpp:744
std::variant< Optional, DefaultHint, Default > Fallback
Definition: util.h:165
std::string ToDescriptionString(bool is_named_arg) const
Return the description string, including the argument type and whether the argument is required.
Definition: util.cpp:753
const Type m_type
Definition: util.h:168
RPCArg(std::string name, Type type, Fallback fallback, std::string description, std::vector< RPCArg > inner, RPCArgOptions opts={})
Definition: util.h:189
std::string GetName() const
Return the name, throws when there are aliases.
Definition: util.cpp:738
std::string GetFirstName() const
Return the first of all aliases.
Definition: util.cpp:733
std::string ToStringObj(bool oneline) const
Return the type string of the argument when it is in an object (dict).
Definition: util.cpp:1026
Optional
Definition: util.h:148
@ OMITTED
Optional argument for which the default value is omitted from help text for one of two reasons:
@ NO
Required arg.
bool hidden
For testing only.
Definition: util.h:132
std::vector< std::string > type_str
Should be empty unless it is supposed to override the auto-generated type strings....
Definition: util.h:131
std::string oneline_description
Should be empty unless it is supposed to override the auto-generated summary line.
Definition: util.h:130
bool skip_type_check
Definition: util.h:129
std::string ToDescriptionString() const
Definition: util.cpp:542
RPCExamples(std::string examples)
Definition: util.h:351
const std::string m_examples
Definition: util.h:350
const std::string m_description
Definition: util.h:259
void ToSections(Sections &sections, OuterType outer_type=OuterType::NONE, const int current_indent=0) const
Append the sections of the result.
Definition: util.cpp:815
@ ELISION
Special type to denote elision (...)
@ NUM_TIME
Special numeric to denote unix epoch time.
@ ANY
Special type to disable type checks (for testing only)
@ ARR_FIXED
Special array that has a fixed number of entries.
@ OBJ_DYN
Special dictionary with keys that are not literals.
@ STR_HEX
Special string with only hex chars.
@ STR_AMOUNT
Special string to represent a floating point amount.
const std::vector< RPCResult > m_inner
Only used for arrays or dicts.
Definition: util.h:256
RPCResult(Type type, std::string m_key_name, bool optional, std::string description, std::vector< RPCResult > inner={}, bool skip_type_check=false)
Definition: util.h:289
RPCResult(Type type, std::string m_key_name, std::string description, std::vector< RPCResult > inner={}, bool skip_type_check=false)
Definition: util.h:307
const std::string m_cond
Definition: util.h:260
UniValue MatchesType(const UniValue &result) const
Check whether the result JSON type matches.
Definition: util.cpp:948
std::string ToDescriptionString() const
Return the description string, including the result type.
std::string ToStringObj() const
Return the type string of the result when it is in an object (dict).
void CheckInnerDoc() const
Definition: util.cpp:1015
const bool m_optional
Definition: util.h:257
RPCResult(std::string cond, Type type, std::string m_key_name, std::string description, std::vector< RPCResult > inner={})
Definition: util.h:281
RPCResult(std::string cond, Type type, std::string m_key_name, bool optional, std::string description, std::vector< RPCResult > inner={})
Definition: util.h:262
const std::string m_key_name
Only used for dicts.
Definition: util.h:255
const Type m_type
Definition: util.h:254
const bool m_skip_type_check
Definition: util.h:258
RPCResults(RPCResult result)
Definition: util.h:333
const std::vector< RPCResult > m_results
Definition: util.h:331
RPCResults(std::initializer_list< RPCResult > results)
Definition: util.h:338
Keeps track of RPCArgs by transforming them into sections for the purpose of serializing everything t...
Definition: util.cpp:366
Wrapper for UniValue::VType, which includes typeAny: Used to denote don't care type.
Definition: util.h:58
bool typeAny
Definition: util.h:61
UniValueType(UniValue::VType _type)
Definition: util.h:59
UniValue::VType type
Definition: util.h:62
UniValueType()
Definition: util.h:60