Bitcoin Core  0.19.99
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 <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 <vector>
22 
23 #include <boost/variant.hpp>
24 
29 extern const std::string UNIX_EPOCH_TIME;
30 
32 class CPubKey;
33 class CScript;
34 
37 struct UniValueType {
38  UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
39  UniValueType() : typeAny(true) {}
40  bool typeAny;
42 };
43 
48 void RPCTypeCheck(const UniValue& params,
49  const std::list<UniValueType>& typesExpected, bool fAllowNull=false);
50 
54 void RPCTypeCheckArgument(const UniValue& value, const UniValueType& typeExpected);
55 
56 /*
57  Check for expected keys/value types in an Object.
58 */
59 void RPCTypeCheckObj(const UniValue& o,
60  const std::map<std::string, UniValueType>& typesExpected,
61  bool fAllowNull = false,
62  bool fStrict = false);
63 
68 extern uint256 ParseHashV(const UniValue& v, std::string strName);
69 extern uint256 ParseHashO(const UniValue& o, std::string strKey);
70 extern std::vector<unsigned char> ParseHexV(const UniValue& v, std::string strName);
71 extern std::vector<unsigned char> ParseHexO(const UniValue& o, std::string strKey);
72 
73 extern CAmount AmountFromValue(const UniValue& value);
74 extern std::string HelpExampleCli(const std::string& methodname, const std::string& args);
75 extern std::string HelpExampleRpc(const std::string& methodname, const std::string& args);
76 
77 CPubKey HexToPubKey(const std::string& hex_in);
78 CPubKey AddrToPubKey(const FillableSigningProvider& keystore, const std::string& addr_in);
79 CTxDestination AddAndGetMultisigDestination(const int required, const std::vector<CPubKey>& pubkeys, OutputType type, FillableSigningProvider& keystore, CScript& script_out);
80 
82 
84 unsigned int ParseConfirmTarget(const UniValue& value, unsigned int max_target);
85 
87 UniValue JSONRPCTransactionError(TransactionError terr, const std::string& err_string = "");
88 
90 std::pair<int64_t, int64_t> ParseDescriptorRange(const UniValue& value);
91 
93 std::vector<CScript> EvalDescriptorStringOrObject(const UniValue& scanobject, FlatSigningProvider& provider);
94 
97 
98 struct RPCArg {
99  enum class Type {
100  OBJ,
101  ARR,
102  STR,
103  NUM,
104  BOOL,
105  OBJ_USER_KEYS,
106  AMOUNT,
107  STR_HEX,
108  RANGE,
109  };
110 
111  enum class Optional {
113  NO,
118  OMITTED_NAMED_ARG,
125  OMITTED,
126  };
127  using Fallback = boost::variant<Optional, /* default value for optional args */ std::string>;
128  const std::string m_name;
129  const Type m_type;
130  const std::vector<RPCArg> m_inner;
132  const std::string m_description;
133  const std::string m_oneline_description;
134  const std::vector<std::string> m_type_str;
135 
137  const std::string& name,
138  const Type& type,
139  const Fallback& fallback,
140  const std::string& description,
141  const std::string& oneline_description = "",
142  const std::vector<std::string>& type_str = {})
143  : m_name{name},
144  m_type{type},
145  m_fallback{fallback},
146  m_description{description},
147  m_oneline_description{oneline_description},
148  m_type_str{type_str}
149  {
150  CHECK_NONFATAL(type != Type::ARR && type != Type::OBJ);
151  }
152 
154  const std::string& name,
155  const Type& type,
156  const Fallback& fallback,
157  const std::string& description,
158  const std::vector<RPCArg>& inner,
159  const std::string& oneline_description = "",
160  const std::vector<std::string>& type_str = {})
161  : m_name{name},
162  m_type{type},
163  m_inner{inner},
164  m_fallback{fallback},
165  m_description{description},
166  m_oneline_description{oneline_description},
167  m_type_str{type_str}
168  {
169  CHECK_NONFATAL(type == Type::ARR || type == Type::OBJ);
170  }
171 
172  bool IsOptional() const;
173 
178  std::string ToString(bool oneline) const;
183  std::string ToStringObj(bool oneline) const;
188  std::string ToDescriptionString() const;
189 };
190 
191 struct RPCResult {
192  const std::string m_cond;
193  const std::string m_result;
194 
195  explicit RPCResult(std::string result)
196  : m_cond{}, m_result{std::move(result)}
197  {
198  CHECK_NONFATAL(!m_result.empty());
199  }
200 
201  RPCResult(std::string cond, std::string result)
202  : m_cond{std::move(cond)}, m_result{std::move(result)}
203  {
204  CHECK_NONFATAL(!m_cond.empty());
205  CHECK_NONFATAL(!m_result.empty());
206  }
207 };
208 
209 struct RPCResults {
210  const std::vector<RPCResult> m_results;
211 
213  : m_results{}
214  {
215  }
216 
218  : m_results{{result}}
219  {
220  }
221 
222  RPCResults(std::initializer_list<RPCResult> results)
223  : m_results{results}
224  {
225  }
226 
230  std::string ToDescriptionString() const;
231 };
232 
233 struct RPCExamples {
234  const std::string m_examples;
235  explicit RPCExamples(
236  std::string examples)
237  : m_examples(std::move(examples))
238  {
239  }
240  std::string ToDescriptionString() const;
241 };
242 
244 {
245 public:
246  RPCHelpMan(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples);
247 
248  std::string ToString() const;
250  bool IsValidNumArgs(size_t num_args) const;
255  inline void Check(const JSONRPCRequest& request) const {
256  if (request.fHelp || !IsValidNumArgs(request.params.size())) {
257  throw std::runtime_error(ToString());
258  }
259  }
260 
261 private:
262  const std::string m_name;
263  const std::string m_description;
264  const std::vector<RPCArg> m_args;
267 };
268 
269 #endif // BITCOIN_RPC_UTIL_H
UniValue DescribeAddress(const CTxDestination &dest)
Definition: util.cpp:246
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
Definition: util.cpp:111
UniValueType(UniValue::VType _type)
Definition: util.h:38
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:18
uint256 ParseHashV(const UniValue &v, std::string strName)
Utilities: convert hex-encoded Values (throws error if not hex).
Definition: util.cpp:84
std::vector< unsigned char > ParseHexV(const UniValue &v, std::string strName)
Definition: util.cpp:97
Type
Definition: util.h:99
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:699
const Fallback m_fallback
Definition: util.h:131
ServiceFlags
nServices flags
Definition: protocol.h:239
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:136
uint256 ParseHashO(const UniValue &o, std::string strKey)
Definition: util.cpp:93
const std::string m_oneline_description
Should be empty unless it is supposed to override the auto-generated summary line.
Definition: util.h:133
const std::string m_name
The name of the arg (can be empty for inner args)
Definition: util.h:128
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:16
bool typeAny
Definition: util.h:40
CPubKey AddrToPubKey(const FillableSigningProvider &keystore, const std::string &addr_in)
Definition: util.cpp:136
CPubKey HexToPubKey(const std::string &hex_in)
Definition: util.cpp:123
RPCResult(std::string result)
Definition: util.h:195
#define CHECK_NONFATAL(condition)
Throw a NonFatalCheckError when the condition evaluates to false.
Definition: check.h:28
CAmount AmountFromValue(const UniValue &value)
Definition: util.cpp:72
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:153
const RPCExamples m_examples
Definition: util.h:266
boost::variant< Optional, std::string > Fallback
Definition: util.h:127
RPCResults()
Definition: util.h:212
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:255
const std::vector< RPCArg > m_inner
Only used for arrays or dicts.
Definition: util.h:130
OutputType
Definition: outputtype.h:17
const std::string m_cond
Definition: util.h:192
void RPCTypeCheckArgument(const UniValue &value, const UniValueType &typeExpected)
Type-check one argument; throws JSONRPCError if wrong type given.
Definition: util.cpp:35
RPCErrorCode RPCErrorFromTransactionError(TransactionError terr)
Definition: util.cpp:260
UniValue::VType type
Definition: util.h:41
const std::string m_description
Definition: util.h:263
int64_t CAmount
Amount in satoshis (Can be negative)
Definition: amount.h:12
void RPCTypeCheckObj(const UniValue &o, const std::map< std::string, UniValueType > &typesExpected, bool fAllowNull=false, bool fStrict=false)
Definition: util.cpp:42
Definition: util.h:98
CTxDestination AddAndGetMultisigDestination(const int required, const std::vector< CPubKey > &pubkeys, OutputType type, FillableSigningProvider &keystore, CScript &script_out)
Definition: util.cpp:157
UniValue params
Definition: request.h:32
const char * name
Definition: rest.cpp:40
RPCResults(std::initializer_list< RPCResult > results)
Definition: util.h:222
An encapsulated public key.
Definition: pubkey.h:30
Fillable signing provider that keeps keys in an address->secret map.
UniValue GetServicesNames(ServiceFlags services)
Returns, given services flags, a list of humanly readable (known) network services.
Definition: util.cpp:737
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:251
const std::vector< RPCResult > m_results
Definition: util.h:210
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
Definition: util.cpp:116
const std::vector< RPCArg > m_args
Definition: util.h:264
const std::string m_description
Definition: util.h:132
UniValue JSONRPCTransactionError(TransactionError terr, const std::string &err_string="")
Definition: util.cpp:279
const std::string m_examples
Definition: util.h:234
const std::vector< std::string > m_type_str
Should be empty unless it is supposed to override the auto-generated type strings. Vector length is either 0 or 2, m_type_str.at(0) will override the type of the value in a key-value pair, m_type_str.at(1) will override the type in the argument description.
Definition: util.h:134
const RPCResults m_results
Definition: util.h:265
bool fHelp
Definition: request.h:33
256-bit opaque blob.
Definition: uint256.h:120
const std::string m_result
Definition: util.h:193
UniValueType()
Definition: util.h:39
Serialized script, used inside transaction inputs and outputs.
Definition: script.h:390
Optional
Definition: util.h:111
TransactionError
Definition: error.h:22
RPCResults(RPCResult result)
Definition: util.h:217
const Type m_type
Definition: util.h:129
RPCExamples(std::string examples)
Definition: util.h:235
size_t size() const
Definition: univalue.h:68
boost::optional< T > Optional
Substitute for C++17 std::optional.
Definition: optional.h:14
const std::string m_name
Definition: util.h:262
RPCErrorCode
Bitcoin RPC error codes.
Definition: protocol.h:23
boost::variant< CNoDestination, PKHash, ScriptHash, WitnessV0ScriptHash, WitnessV0KeyHash, WitnessUnknown > CTxDestination
A txout script template with a specific destination.
Definition: standard.h:143
RPCResult(std::string cond, std::string result)
Definition: util.h:201
std::pair< int64_t, int64_t > ParseDescriptorRange(const UniValue &value)
Parse a JSON range specified as int64, or [int64, int64].
Definition: util.cpp:683
Wrapper for UniValue::VType, which includes typeAny: Used to denote don&#39;t care type.
Definition: util.h:37
std::vector< unsigned char > ParseHexO(const UniValue &o, std::string strKey)
Definition: util.cpp:106