Bitcoin Core  0.18.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 <pubkey.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>
16 #include <univalue.h>
17 
18 #include <string>
19 #include <vector>
20 
21 #include <boost/variant.hpp>
22 
24 class CPubKey;
25 class CScript;
26 struct InitInterfaces;
27 
32 
35 struct UniValueType {
36  UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
37  UniValueType() : typeAny(true) {}
38  bool typeAny;
40 };
41 
46 void RPCTypeCheck(const UniValue& params,
47  const std::list<UniValueType>& typesExpected, bool fAllowNull=false);
48 
52 void RPCTypeCheckArgument(const UniValue& value, const UniValueType& typeExpected);
53 
54 /*
55  Check for expected keys/value types in an Object.
56 */
57 void RPCTypeCheckObj(const UniValue& o,
58  const std::map<std::string, UniValueType>& typesExpected,
59  bool fAllowNull = false,
60  bool fStrict = false);
61 
66 extern uint256 ParseHashV(const UniValue& v, std::string strName);
67 extern uint256 ParseHashO(const UniValue& o, std::string strKey);
68 extern std::vector<unsigned char> ParseHexV(const UniValue& v, std::string strName);
69 extern std::vector<unsigned char> ParseHexO(const UniValue& o, std::string strKey);
70 
71 extern CAmount AmountFromValue(const UniValue& value);
72 extern std::string HelpExampleCli(const std::string& methodname, const std::string& args);
73 extern std::string HelpExampleRpc(const std::string& methodname, const std::string& args);
74 
75 CPubKey HexToPubKey(const std::string& hex_in);
76 CPubKey AddrToPubKey(FillableSigningProvider* const keystore, const std::string& addr_in);
77 CTxDestination AddAndGetMultisigDestination(const int required, const std::vector<CPubKey>& pubkeys, OutputType type, FillableSigningProvider& keystore, CScript& script_out);
78 
80 
82 unsigned int ParseConfirmTarget(const UniValue& value, unsigned int max_target);
83 
85 UniValue JSONRPCTransactionError(TransactionError terr, const std::string& err_string = "");
86 
88 std::pair<int64_t, int64_t> ParseDescriptorRange(const UniValue& value);
89 
91 std::vector<CScript> EvalDescriptorStringOrObject(const UniValue& scanobject, FlatSigningProvider& provider);
92 
93 struct RPCArg {
94  enum class Type {
95  OBJ,
96  ARR,
97  STR,
98  NUM,
99  BOOL,
100  OBJ_USER_KEYS,
101  AMOUNT,
102  STR_HEX,
103  RANGE,
104  };
105 
106  enum class Optional {
108  NO,
113  OMITTED_NAMED_ARG,
120  OMITTED,
121  };
122  using Fallback = boost::variant<Optional, /* default value for optional args */ std::string>;
123  const std::string m_name;
124  const Type m_type;
125  const std::vector<RPCArg> m_inner;
127  const std::string m_description;
128  const std::string m_oneline_description;
129  const std::vector<std::string> m_type_str;
130 
132  const std::string& name,
133  const Type& type,
134  const Fallback& fallback,
135  const std::string& description,
136  const std::string& oneline_description = "",
137  const std::vector<std::string>& type_str = {})
138  : m_name{name},
139  m_type{type},
140  m_fallback{fallback},
141  m_description{description},
142  m_oneline_description{oneline_description},
143  m_type_str{type_str}
144  {
145  assert(type != Type::ARR && type != Type::OBJ);
146  }
147 
149  const std::string& name,
150  const Type& type,
151  const Fallback& fallback,
152  const std::string& description,
153  const std::vector<RPCArg>& inner,
154  const std::string& oneline_description = "",
155  const std::vector<std::string>& type_str = {})
156  : m_name{name},
157  m_type{type},
158  m_inner{inner},
159  m_fallback{fallback},
160  m_description{description},
161  m_oneline_description{oneline_description},
162  m_type_str{type_str}
163  {
164  assert(type == Type::ARR || type == Type::OBJ);
165  }
166 
167  bool IsOptional() const;
168 
173  std::string ToString(bool oneline) const;
178  std::string ToStringObj(bool oneline) const;
183  std::string ToDescriptionString() const;
184 };
185 
186 struct RPCResult {
187  const std::string m_cond;
188  const std::string m_result;
189 
190  explicit RPCResult(std::string result)
191  : m_cond{}, m_result{std::move(result)}
192  {
193  assert(!m_result.empty());
194  }
195 
196  RPCResult(std::string cond, std::string result)
197  : m_cond{std::move(cond)}, m_result{std::move(result)}
198  {
199  assert(!m_cond.empty());
200  assert(!m_result.empty());
201  }
202 };
203 
204 struct RPCResults {
205  const std::vector<RPCResult> m_results;
206 
208  : m_results{}
209  {
210  }
211 
213  : m_results{{result}}
214  {
215  }
216 
217  RPCResults(std::initializer_list<RPCResult> results)
218  : m_results{results}
219  {
220  }
221 
225  std::string ToDescriptionString() const;
226 };
227 
228 struct RPCExamples {
229  const std::string m_examples;
230  explicit RPCExamples(
231  std::string examples)
232  : m_examples(std::move(examples))
233  {
234  }
235  std::string ToDescriptionString() const;
236 };
237 
239 {
240 public:
241  RPCHelpMan(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples);
242 
243  std::string ToString() const;
245  bool IsValidNumArgs(size_t num_args) const;
250  inline void Check(const JSONRPCRequest& request) const {
251  if (request.fHelp || !IsValidNumArgs(request.params.size())) {
252  throw std::runtime_error(ToString());
253  }
254  }
255 
256 private:
257  const std::string m_name;
258  const std::string m_description;
259  const std::vector<RPCArg> m_args;
262 };
263 
264 #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:36
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:94
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:126
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:131
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:128
const std::string m_name
The name of the arg (can be empty for inner args)
Definition: util.h:123
bool typeAny
Definition: util.h:38
CPubKey HexToPubKey(const std::string &hex_in)
Definition: util.cpp:123
RPCResult(std::string result)
Definition: util.h:190
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:148
const RPCExamples m_examples
Definition: util.h:261
boost::variant< Optional, std::string > Fallback
Definition: util.h:122
RPCResults()
Definition: util.h:207
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:250
const std::vector< RPCArg > m_inner
Only used for arrays or dicts.
Definition: util.h:125
OutputType
Definition: outputtype.h:16
const std::string m_cond
Definition: util.h:187
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:39
const std::string m_description
Definition: util.h:258
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:93
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:39
RPCResults(std::initializer_list< RPCResult > results)
Definition: util.h:217
An encapsulated public key.
Definition: pubkey.h:30
Fillable signing provider that keeps keys in an address->secret map.
CPubKey AddrToPubKey(FillableSigningProvider *const keystore, const std::string &addr_in)
Definition: util.cpp:136
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:205
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
Definition: util.cpp:116
const std::vector< RPCArg > m_args
Definition: util.h:259
const std::string m_description
Definition: util.h:127
UniValue JSONRPCTransactionError(TransactionError terr, const std::string &err_string="")
Definition: util.cpp:279
const std::string m_examples
Definition: util.h:229
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:129
const RPCResults m_results
Definition: util.h:260
bool fHelp
Definition: request.h:33
256-bit opaque blob.
Definition: uint256.h:121
const std::string m_result
Definition: util.h:188
UniValueType()
Definition: util.h:37
Serialized script, used inside transaction inputs and outputs.
Definition: script.h:390
Optional
Definition: util.h:106
TransactionError
util/error.h is a common place for definitions of simple error types and string functions.
Definition: error.h:20
RPCResults(RPCResult result)
Definition: util.h:212
const Type m_type
Definition: util.h:124
RPCExamples(std::string examples)
Definition: util.h:230
InitInterfaces * g_rpc_interfaces
Pointers to interfaces that need to be accessible from RPC methods.
Definition: util.cpp:16
size_t size() const
Definition: univalue.h:69
boost::optional< T > Optional
Substitute for C++17 std::optional.
Definition: optional.h:14
const std::string m_name
Definition: util.h:257
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:139
RPCResult(std::string cond, std::string result)
Definition: util.h:196
Pointers to interfaces used during init and destroyed on shutdown.
Definition: init.h:19
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:35
std::vector< unsigned char > ParseHexO(const UniValue &o, std::string strKey)
Definition: util.cpp:106