Bitcoin ABC  0.22.12
P2P Digital Currency
util.h
Go to the documentation of this file.
1 // Copyright (c) 2017-2019 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 <rpc/protocol.h>
12 #include <rpc/request.h>
13 #include <script/script.h>
14 #include <script/sign.h>
15 #include <script/standard.h> // For CTxDestination
16 #include <univalue.h>
17 #include <util/check.h>
18 
19 #include <boost/variant.hpp>
20 
21 #include <string>
22 #include <vector>
23 
24 class CChainParams;
26 class CPubKey;
27 class CScript;
28 struct Sections;
29 
34 extern const std::string UNIX_EPOCH_TIME;
35 
39 extern const std::string EXAMPLE_ADDRESS;
40 
45 struct UniValueType {
46  UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
47  UniValueType() : typeAny(true) {}
48  bool typeAny;
50 };
51 
57 void RPCTypeCheck(const UniValue &params,
58  const std::list<UniValueType> &typesExpected,
59  bool fAllowNull = false);
60 
64 void RPCTypeCheckArgument(const UniValue &value,
65  const UniValueType &typeExpected);
66 
70 void RPCTypeCheckObj(const UniValue &o,
71  const std::map<std::string, UniValueType> &typesExpected,
72  bool fAllowNull = false, bool fStrict = false);
73 
77 extern uint256 ParseHashV(const UniValue &v, std::string strName);
78 extern uint256 ParseHashO(const UniValue &o, std::string strKey);
79 extern std::vector<uint8_t> ParseHexV(const UniValue &v, std::string strName);
80 extern std::vector<uint8_t> ParseHexO(const UniValue &o, std::string strKey);
81 
82 extern Amount AmountFromValue(const UniValue &value);
83 extern std::string HelpExampleCli(const std::string &methodname,
84  const std::string &args);
85 extern std::string HelpExampleRpc(const std::string &methodname,
86  const std::string &args);
87 
88 CPubKey HexToPubKey(const std::string &hex_in);
89 CPubKey AddrToPubKey(const CChainParams &chainparams,
90  const FillableSigningProvider &keystore,
91  const std::string &addr_in);
93  const std::vector<CPubKey> &pubkeys,
95  FillableSigningProvider &keystore,
96  CScript &script_out);
97 
99 
102  const std::string &err_string = "");
103 
105 std::pair<int64_t, int64_t> ParseDescriptorRange(const UniValue &value);
106 
111 std::vector<CScript>
112 EvalDescriptorStringOrObject(const UniValue &scanobject,
113  FlatSigningProvider &provider);
114 
120 
125 enum class OuterType {
126  ARR,
127  OBJ,
128  NONE, // Only set on first recursion
129 };
130 
131 struct RPCArg {
132  enum class Type {
133  OBJ,
134  ARR,
135  STR,
136  NUM,
137  BOOL,
141  OBJ_USER_KEYS,
144  AMOUNT,
146  STR_HEX,
148  RANGE,
149  };
150 
151  enum class Optional {
153  NO,
158  OMITTED_NAMED_ARG,
165  OMITTED,
166  };
167  using Fallback =
168  boost::variant<Optional,
169  /* default value for optional args */ std::string>;
170 
173  const std::string m_names;
174  const Type m_type;
176  const std::vector<RPCArg> m_inner;
178  const std::string m_description;
181  const std::string m_oneline_description;
182 
188  const std::vector<std::string> m_type_str;
189 
190  RPCArg(const std::string name, const Type type, const Fallback fallback,
191  const std::string description,
192  const std::string oneline_description = "",
193  const std::vector<std::string> type_str = {})
194  : m_names{std::move(name)}, m_type{std::move(type)},
195  m_fallback{std::move(fallback)}, m_description{std::move(
196  description)},
197  m_oneline_description{std::move(oneline_description)},
198  m_type_str{std::move(type_str)} {
199  CHECK_NONFATAL(type != Type::ARR && type != Type::OBJ);
200  }
201 
202  RPCArg(const std::string name, const Type type, const Fallback fallback,
203  const std::string description, const std::vector<RPCArg> inner,
204  const std::string oneline_description = "",
205  const std::vector<std::string> type_str = {})
206  : m_names{std::move(name)}, m_type{std::move(type)}, m_inner{std::move(
207  inner)},
208  m_fallback{std::move(fallback)}, m_description{std::move(
209  description)},
210  m_oneline_description{std::move(oneline_description)},
211  m_type_str{std::move(type_str)} {
212  CHECK_NONFATAL(type == Type::ARR || type == Type::OBJ);
213  }
214 
215  bool IsOptional() const;
216 
218  std::string GetFirstName() const;
219 
221  std::string GetName() const;
222 
228  std::string ToString(bool oneline) const;
233  std::string ToStringObj(bool oneline) const;
238  std::string ToDescriptionString() const;
239 };
240 
241 struct RPCResult {
242  enum class Type {
243  OBJ,
244  ARR,
245  STR,
246  NUM,
247  BOOL,
248  NONE,
249  STR_AMOUNT,
250  STR_HEX,
251  OBJ_DYN,
252  ARR_FIXED,
253  NUM_TIME,
254  ELISION,
255  };
256 
257  const Type m_type;
258  const std::string m_key_name;
259  const std::vector<RPCResult> m_inner;
260  const bool m_optional;
261  const std::string m_description;
262  const std::string m_cond;
263 
264  RPCResult(const std::string cond, const Type type,
265  const std::string key_name, const bool optional,
266  const std::string description,
267  const std::vector<RPCResult> inner = {})
268  : m_type{std::move(type)}, m_key_name{std::move(key_name)},
269  m_inner{std::move(inner)}, m_optional{optional},
270  m_description{std::move(description)}, m_cond{std::move(cond)} {
271  CHECK_NONFATAL(!m_cond.empty());
272  const bool inner_needed{type == Type::ARR || type == Type::ARR_FIXED ||
273  type == Type::OBJ || type == Type::OBJ_DYN};
274  CHECK_NONFATAL(inner_needed != inner.empty());
275  }
276 
277  RPCResult(const std::string cond, const Type type,
278  const std::string key_name, const std::string description,
279  const std::vector<RPCResult> inner = {})
280  : RPCResult{cond, type, key_name, false, description, inner} {}
281 
282  RPCResult(const Type type, const std::string key_name, const bool optional,
283  const std::string description,
284  const std::vector<RPCResult> inner = {})
285  : m_type{std::move(type)}, m_key_name{std::move(key_name)},
286  m_inner{std::move(inner)}, m_optional{optional},
287  m_description{std::move(description)}, m_cond{} {
288  const bool inner_needed{type == Type::ARR || type == Type::ARR_FIXED ||
289  type == Type::OBJ || type == Type::OBJ_DYN};
290  CHECK_NONFATAL(inner_needed != inner.empty());
291  }
292 
293  RPCResult(const Type type, const std::string key_name,
294  const std::string description,
295  const std::vector<RPCResult> inner = {})
296  : RPCResult{type, key_name, false, description, inner} {}
297 
299  void ToSections(Sections &sections, OuterType outer_type = OuterType::NONE,
300  const int current_indent = 0) const;
302  std::string ToStringObj() const;
304  std::string ToDescriptionString() const;
305 };
306 
307 struct RPCResults {
308  const std::vector<RPCResult> m_results;
309 
310  RPCResults(RPCResult result) : m_results{{result}} {}
311 
312  RPCResults(std::initializer_list<RPCResult> results) : m_results{results} {}
313 
317  std::string ToDescriptionString() const;
318 };
319 
320 struct RPCExamples {
321  const std::string m_examples;
322  explicit RPCExamples(std::string examples)
323  : m_examples(std::move(examples)) {}
324  RPCExamples() : m_examples(std::move("")) {}
325  std::string ToDescriptionString() const;
326 };
327 
328 class RPCHelpMan {
329 public:
330  RPCHelpMan(std::string name, std::string description,
331  std::vector<RPCArg> args, RPCResults results,
332  RPCExamples examples);
333 
334  std::string ToString() const;
336  bool IsValidNumArgs(size_t num_args) const;
341  inline void Check(const JSONRPCRequest &request) const {
342  if (request.fHelp || !IsValidNumArgs(request.params.size())) {
343  throw std::runtime_error(ToString());
344  }
345  }
346 
347 private:
348  const std::string m_name;
349  const std::string m_description;
350  const std::vector<RPCArg> m_args;
353 };
354 
355 #endif // BITCOIN_RPC_UTIL_H
UniValue DescribeAddress(const CTxDestination &dest)
Definition: util.cpp:263
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
Definition: util.cpp:138
UniValueType(UniValue::VType _type)
Definition: util.h:46
void RPCTypeCheck(const UniValue &params, const std::list< UniValueType > &typesExpected, bool fAllowNull=false)
Type-check arguments; throws JSONRPCError if wrong type given.
Definition: util.cpp:25
uint256 ParseHashV(const UniValue &v, std::string strName)
Utilities: convert hex-encoded values (throws error if not hex).
Definition: util.cpp:99
const std::vector< RPCResult > m_inner
Only used for arrays or dicts.
Definition: util.h:259
std::vector< uint8_t > ParseHexV(const UniValue &v, std::string strName)
Definition: util.cpp:120
Type
Definition: util.h:132
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:849
const Fallback m_fallback
Definition: util.h:177
ServiceFlags
nServices flags.
Definition: protocol.h:320
uint256 ParseHashO(const UniValue &o, std::string strKey)
Definition: util.cpp:116
Keeps track of RPCArgs by transforming them into sections for the purpose of serializing everything t...
Definition: util.cpp:311
const std::string m_oneline_description
Should be empty unless it is supposed to override the auto-generated summary line.
Definition: util.h:181
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
bool typeAny
Definition: util.h:48
CPubKey HexToPubKey(const std::string &hex_in)
Definition: util.cpp:153
#define CHECK_NONFATAL(condition)
Throw a NonFatalCheckError when the condition evaluates to false.
Definition: check.h:34
const std::string m_key_name
Only used for dicts.
Definition: util.h:258
Definition: amount.h:17
const RPCExamples m_examples
Definition: util.h:352
CChainParams defines various tweakable parameters of a given instance of the Bitcoin system...
Definition: chainparams.h:47
boost::variant< Optional, std::string > Fallback
Definition: util.h:169
void Check(const JSONRPCRequest &request) const
Check if the given request is valid according to this command or if the user is asking for help infor...
Definition: util.h:341
const std::vector< RPCArg > m_inner
Only used for arrays or dicts.
Definition: util.h:176
OutputType
Definition: outputtype.h:17
std::vector< uint8_t > ParseHexO(const UniValue &o, std::string strKey)
Definition: util.cpp:134
const std::string m_cond
Definition: util.h:262
void RPCTypeCheckArgument(const UniValue &value, const UniValueType &typeExpected)
Type-check one argument; throws JSONRPCError if wrong type given.
Definition: util.cpp:42
RPCErrorCode RPCErrorFromTransactionError(TransactionError terr)
Definition: util.cpp:267
const Type m_type
Definition: util.h:257
UniValue::VType type
Definition: util.h:49
const std::string m_description
Definition: util.h:349
void RPCTypeCheckObj(const UniValue &o, const std::map< std::string, UniValueType > &typesExpected, bool fAllowNull=false, bool fStrict=false)
Check for expected keys/value types in an Object.
Definition: util.cpp:52
Amount AmountFromValue(const UniValue &value)
Definition: util.cpp:81
std::string ToString(const T &t)
Locale-independent version of std::to_string.
Definition: string.h:67
RPCResult(const std::string cond, const Type type, const std::string key_name, const std::string description, const std::vector< RPCResult > inner={})
Definition: util.h:277
Definition: util.h:131
CTxDestination AddAndGetMultisigDestination(const int required, const std::vector< CPubKey > &pubkeys, OutputType type, FillableSigningProvider &keystore, CScript &script_out)
Definition: util.cpp:195
UniValue params
Definition: request.h:37
const char * name
Definition: rest.cpp:43
RPCArg(const std::string name, const Type type, const Fallback fallback, const std::string description, const std::string oneline_description="", const std::vector< std::string > type_str={})
Definition: util.h:190
RPCResults(std::initializer_list< RPCResult > results)
Definition: util.h:312
An encapsulated public key.
Definition: pubkey.h:31
Fillable signing provider that keeps keys in an address->secret map.
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:173
UniValue GetServicesNames(ServiceFlags services)
Returns, given services flags, a list of humanly readable (known) network services.
Definition: util.cpp:896
const std::vector< RPCResult > m_results
Definition: util.h:308
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
Definition: util.cpp:143
const std::vector< RPCArg > m_args
Definition: util.h:350
RPCResult(const std::string cond, const Type type, const std::string key_name, const bool optional, const std::string description, const std::vector< RPCResult > inner={})
Definition: util.h:264
const std::string m_description
Definition: util.h:178
UniValue JSONRPCTransactionError(TransactionError terr, const std::string &err_string="")
Definition: util.cpp:286
const std::string m_examples
Definition: util.h:321
const std::vector< std::string > m_type_str
Should be empty unless it is supposed to override the auto-generated type strings.
Definition: util.h:188
const RPCResults m_results
Definition: util.h:351
bool fHelp
Definition: request.h:38
OuterType
Serializing JSON objects depends on the outer type.
Definition: util.h:125
256-bit opaque blob.
Definition: uint256.h:120
UniValueType()
Definition: util.h:47
Serialized script, used inside transaction inputs and outputs.
Definition: script.h:429
Optional
Definition: util.h:151
const std::string m_description
Definition: util.h:261
CPubKey AddrToPubKey(const CChainParams &chainparams, const FillableSigningProvider &keystore, const std::string &addr_in)
Definition: util.cpp:167
RPCExamples()
Definition: util.h:324
TransactionError
Definition: error.h:22
RPCResult(const Type type, const std::string key_name, const std::string description, const std::vector< RPCResult > inner={})
Definition: util.h:293
const std::string EXAMPLE_ADDRESS
Example CashAddr address used in multiple RPCExamples.
Definition: util.cpp:22
RPCResults(RPCResult result)
Definition: util.h:310
const Type m_type
Definition: util.h:174
RPCArg(const std::string name, const Type type, const Fallback fallback, const std::string description, const std::vector< RPCArg > inner, const std::string oneline_description="", const std::vector< std::string > type_str={})
Definition: util.h:202
RPCExamples(std::string examples)
Definition: util.h:322
const bool m_optional
Definition: util.h:260
size_t size() const
Definition: univalue.h:80
const std::string m_name
Definition: util.h:348
RPCErrorCode
Bitcoin RPC error codes.
Definition: protocol.h:22
std::pair< int64_t, int64_t > ParseDescriptorRange(const UniValue &value)
Parse a JSON range specified as int64, or [int64, int64].
Definition: util.cpp:832
Wrapper for UniValue::VType, which includes typeAny: used to denote don&#39;t care type.
Definition: util.h:45
boost::variant< CNoDestination, PKHash, ScriptHash > CTxDestination
A txout script template with a specific destination.
Definition: standard.h:87
RPCResult(const Type type, const std::string key_name, const bool optional, const std::string description, const std::vector< RPCResult > inner={})
Definition: util.h:282