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 <pubkey.h>
10 #include <rpc/protocol.h>
11 #include <script/standard.h>
12 #include <univalue.h>
13 
14 #include <string>
15 #include <vector>
16 
17 #include <boost/variant.hpp>
18 
19 class CKeyStore;
20 class CPubKey;
21 class CScript;
22 struct InitInterfaces;
23 
28 
31 struct UniValueType {
32  UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
33  UniValueType() : typeAny(true) {}
34  bool typeAny;
36 };
37 
42 void RPCTypeCheck(const UniValue& params,
43  const std::list<UniValueType>& typesExpected, bool fAllowNull=false);
44 
48 void RPCTypeCheckArgument(const UniValue& value, const UniValueType& typeExpected);
49 
50 /*
51  Check for expected keys/value types in an Object.
52 */
53 void RPCTypeCheckObj(const UniValue& o,
54  const std::map<std::string, UniValueType>& typesExpected,
55  bool fAllowNull = false,
56  bool fStrict = false);
57 
62 extern uint256 ParseHashV(const UniValue& v, std::string strName);
63 extern uint256 ParseHashO(const UniValue& o, std::string strKey);
64 extern std::vector<unsigned char> ParseHexV(const UniValue& v, std::string strName);
65 extern std::vector<unsigned char> ParseHexO(const UniValue& o, std::string strKey);
66 
67 extern CAmount AmountFromValue(const UniValue& value);
68 extern std::string HelpExampleCli(const std::string& methodname, const std::string& args);
69 extern std::string HelpExampleRpc(const std::string& methodname, const std::string& args);
70 
71 CPubKey HexToPubKey(const std::string& hex_in);
72 CPubKey AddrToPubKey(CKeyStore* const keystore, const std::string& addr_in);
73 CScript CreateMultisigRedeemscript(const int required, const std::vector<CPubKey>& pubkeys);
74 
76 
78 unsigned int ParseConfirmTarget(const UniValue& value, unsigned int max_target);
79 
81 UniValue JSONRPCTransactionError(TransactionError terr, const std::string& err_string = "");
82 
84 std::pair<int64_t, int64_t> ParseDescriptorRange(const UniValue& value);
85 
86 struct RPCArg {
87  enum class Type {
88  OBJ,
89  ARR,
90  STR,
91  NUM,
92  BOOL,
93  OBJ_USER_KEYS,
94  AMOUNT,
95  STR_HEX,
96  RANGE,
97  };
98 
99  enum class Optional {
101  NO,
106  OMITTED_NAMED_ARG,
113  OMITTED,
114  };
115  using Fallback = boost::variant<Optional, /* default value for optional args */ std::string>;
116  const std::string m_name;
117  const Type m_type;
118  const std::vector<RPCArg> m_inner;
120  const std::string m_description;
121  const std::string m_oneline_description;
122  const std::vector<std::string> m_type_str;
123 
125  const std::string& name,
126  const Type& type,
127  const Fallback& fallback,
128  const std::string& description,
129  const std::string& oneline_description = "",
130  const std::vector<std::string>& type_str = {})
131  : m_name{name},
132  m_type{type},
133  m_fallback{fallback},
134  m_description{description},
135  m_oneline_description{oneline_description},
136  m_type_str{type_str}
137  {
138  assert(type != Type::ARR && type != Type::OBJ);
139  }
140 
142  const std::string& name,
143  const Type& type,
144  const Fallback& fallback,
145  const std::string& description,
146  const std::vector<RPCArg>& inner,
147  const std::string& oneline_description = "",
148  const std::vector<std::string>& type_str = {})
149  : m_name{name},
150  m_type{type},
151  m_inner{inner},
152  m_fallback{fallback},
153  m_description{description},
154  m_oneline_description{oneline_description},
155  m_type_str{type_str}
156  {
157  assert(type == Type::ARR || type == Type::OBJ);
158  }
159 
160  bool IsOptional() const;
161 
166  std::string ToString(bool oneline) const;
171  std::string ToStringObj(bool oneline) const;
176  std::string ToDescriptionString() const;
177 };
178 
179 struct RPCResult {
180  const std::string m_cond;
181  const std::string m_result;
182 
183  explicit RPCResult(std::string result)
184  : m_cond{}, m_result{std::move(result)}
185  {
186  assert(!m_result.empty());
187  }
188 
189  RPCResult(std::string cond, std::string result)
190  : m_cond{std::move(cond)}, m_result{std::move(result)}
191  {
192  assert(!m_cond.empty());
193  assert(!m_result.empty());
194  }
195 };
196 
197 struct RPCResults {
198  const std::vector<RPCResult> m_results;
199 
201  : m_results{}
202  {
203  }
204 
206  : m_results{{result}}
207  {
208  }
209 
210  RPCResults(std::initializer_list<RPCResult> results)
211  : m_results{results}
212  {
213  }
214 
218  std::string ToDescriptionString() const;
219 };
220 
221 struct RPCExamples {
222  const std::string m_examples;
224  std::string examples)
225  : m_examples(std::move(examples))
226  {
227  }
228  std::string ToDescriptionString() const;
229 };
230 
232 {
233 public:
234  RPCHelpMan(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples);
235 
236  std::string ToString() const;
238  bool IsValidNumArgs(size_t num_args) const;
239 
240 private:
241  const std::string m_name;
242  const std::string m_description;
243  const std::vector<RPCArg> m_args;
246 };
247 
248 #endif // BITCOIN_RPC_UTIL_H
UniValue DescribeAddress(const CTxDestination &dest)
Definition: util.cpp:232
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
Definition: util.cpp:108
UniValueType(UniValue::VType _type)
Definition: util.h:32
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:15
uint256 ParseHashV(const UniValue &v, std::string strName)
Utilities: convert hex-encoded Values (throws error if not hex).
Definition: util.cpp:81
std::vector< unsigned char > ParseHexV(const UniValue &v, std::string strName)
Definition: util.cpp:94
Type
Definition: util.h:87
const Fallback m_fallback
Definition: util.h:119
CPubKey AddrToPubKey(CKeyStore *const keystore, const std::string &addr_in)
Definition: util.cpp:133
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:124
uint256 ParseHashO(const UniValue &o, std::string strKey)
Definition: util.cpp:90
const std::string m_oneline_description
Should be empty unless it is supposed to override the auto-generated summary line.
Definition: util.h:121
const std::string m_name
The name of the arg (can be empty for inner args)
Definition: util.h:116
bool typeAny
Definition: util.h:34
CPubKey HexToPubKey(const std::string &hex_in)
Definition: util.cpp:120
RPCResult(std::string result)
Definition: util.h:183
CAmount AmountFromValue(const UniValue &value)
Definition: util.cpp:69
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:141
const RPCExamples m_examples
Definition: util.h:245
boost::variant< Optional, std::string > Fallback
Definition: util.h:115
RPCResults()
Definition: util.h:200
const std::vector< RPCArg > m_inner
Only used for arrays or dicts.
Definition: util.h:118
const std::string m_cond
Definition: util.h:180
void RPCTypeCheckArgument(const UniValue &value, const UniValueType &typeExpected)
Type-check one argument; throws JSONRPCError if wrong type given.
Definition: util.cpp:32
RPCErrorCode RPCErrorFromTransactionError(TransactionError terr)
Definition: util.cpp:246
UniValue::VType type
Definition: util.h:35
const std::string m_description
Definition: util.h:242
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:39
Definition: util.h:86
const char * name
Definition: rest.cpp:38
RPCResults(std::initializer_list< RPCResult > results)
Definition: util.h:210
An encapsulated public key.
Definition: pubkey.h:30
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:237
const std::vector< RPCResult > m_results
Definition: util.h:198
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
Definition: util.cpp:113
const std::vector< RPCArg > m_args
Definition: util.h:243
const std::string m_description
Definition: util.h:120
UniValue JSONRPCTransactionError(TransactionError terr, const std::string &err_string="")
Definition: util.cpp:265
const std::string m_examples
Definition: util.h:222
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:122
const RPCResults m_results
Definition: util.h:244
256-bit opaque blob.
Definition: uint256.h:121
const std::string m_result
Definition: util.h:181
UniValueType()
Definition: util.h:33
Serialized script, used inside transaction inputs and outputs.
Definition: script.h:390
Optional
Definition: util.h:99
A virtual base class for key stores.
Definition: keystore.h:19
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:205
const Type m_type
Definition: util.h:117
RPCExamples(std::string examples)
Definition: util.h:223
CScript CreateMultisigRedeemscript(const int required, const std::vector< CPubKey > &pubkeys)
Definition: util.cpp:154
InitInterfaces * g_rpc_interfaces
Pointers to interfaces that need to be accessible from RPC methods.
Definition: util.cpp:13
boost::optional< T > Optional
Substitute for C++17 std::optional.
Definition: optional.h:14
const std::string m_name
Definition: util.h:241
RPCErrorCode
Bitcoin RPC error codes.
Definition: protocol.h:32
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:189
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:673
Wrapper for UniValue::VType, which includes typeAny: Used to denote don&#39;t care type.
Definition: util.h:31
std::vector< unsigned char > ParseHexO(const UniValue &o, std::string strKey)
Definition: util.cpp:103