Branch data Line data Source code
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 <addresstype.h>
9 : : #include <consensus/amount.h>
10 : : #include <node/transaction.h>
11 : : #include <outputtype.h>
12 : : #include <protocol.h>
13 : : #include <pubkey.h>
14 : : #include <rpc/protocol.h>
15 : : #include <rpc/request.h>
16 : : #include <script/script.h>
17 : : #include <script/sign.h>
18 : : #include <uint256.h>
19 : : #include <univalue.h>
20 : : #include <util/check.h>
21 : :
22 : : #include <cstddef>
23 : : #include <cstdint>
24 : : #include <functional>
25 : : #include <initializer_list>
26 : : #include <map>
27 : : #include <optional>
28 : : #include <string>
29 : : #include <string_view>
30 : : #include <type_traits>
31 : : #include <utility>
32 : : #include <variant>
33 : : #include <vector>
34 : :
35 : : class JSONRPCRequest;
36 : : enum ServiceFlags : uint64_t;
37 : : enum class OutputType;
38 : : enum class TransactionError;
39 : : struct FlatSigningProvider;
40 : : struct bilingual_str;
41 : :
42 : : static constexpr bool DEFAULT_RPC_DOC_CHECK{
43 : : #ifdef RPC_DOC_CHECK
44 : : true
45 : : #else
46 : : false
47 : : #endif
48 : : };
49 : :
50 : : /**
51 : : * String used to describe UNIX epoch time in documentation, factored out to a
52 : : * constant for consistency.
53 : : */
54 : : extern const std::string UNIX_EPOCH_TIME;
55 : :
56 : : /**
57 : : * Example bech32 addresses for the RPCExamples help documentation. They are intentionally
58 : : * invalid to prevent accidental transactions by users.
59 : : */
60 : : extern const std::string EXAMPLE_ADDRESS[2];
61 : :
62 : : class FillableSigningProvider;
63 : : class CPubKey;
64 : : class CScript;
65 : : struct Sections;
66 : :
67 : : /**
68 : : * Gets all existing output types formatted for RPC help sections.
69 : : *
70 : : * @return Comma separated string representing output type names.
71 : : */
72 : : std::string GetAllOutputTypes();
73 : :
74 : : /** Wrapper for UniValue::VType, which includes typeAny:
75 : : * Used to denote don't care type. */
76 : : struct UniValueType {
77 : 0 : UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
78 : 0 : UniValueType() : typeAny(true) {}
79 : : bool typeAny;
80 : : UniValue::VType type;
81 : : };
82 : :
83 : : /*
84 : : Check for expected keys/value types in an Object.
85 : : */
86 : : void RPCTypeCheckObj(const UniValue& o,
87 : : const std::map<std::string, UniValueType>& typesExpected,
88 : : bool fAllowNull = false,
89 : : bool fStrict = false);
90 : :
91 : : /**
92 : : * Utilities: convert hex-encoded Values
93 : : * (throws error if not hex).
94 : : */
95 : : uint256 ParseHashV(const UniValue& v, std::string_view name);
96 : : uint256 ParseHashO(const UniValue& o, std::string_view strKey);
97 : : std::vector<unsigned char> ParseHexV(const UniValue& v, std::string_view name);
98 : : std::vector<unsigned char> ParseHexO(const UniValue& o, std::string_view strKey);
99 : :
100 : : /**
101 : : * Validate and return a CAmount from a UniValue number or string.
102 : : *
103 : : * @param[in] value UniValue number or string to parse.
104 : : * @param[in] decimals Number of significant digits (default: 8).
105 : : * @returns a CAmount if the various checks pass.
106 : : */
107 : : CAmount AmountFromValue(const UniValue& value, int decimals = 8);
108 : :
109 : : using RPCArgList = std::vector<std::pair<std::string, UniValue>>;
110 : : std::string HelpExampleCli(const std::string& methodname, const std::string& args);
111 : : std::string HelpExampleCliNamed(const std::string& methodname, const RPCArgList& args);
112 : : std::string HelpExampleRpc(const std::string& methodname, const std::string& args);
113 : : std::string HelpExampleRpcNamed(const std::string& methodname, const RPCArgList& args);
114 : :
115 : : CPubKey HexToPubKey(const std::string& hex_in);
116 : : CPubKey AddrToPubKey(const FillableSigningProvider& keystore, const std::string& addr_in);
117 : : CTxDestination AddAndGetMultisigDestination(const int required, const std::vector<CPubKey>& pubkeys, OutputType type, FillableSigningProvider& keystore, CScript& script_out);
118 : :
119 : : UniValue DescribeAddress(const CTxDestination& dest);
120 : :
121 : : /** Parse a sighash string representation and raise an RPC error if it is invalid. */
122 : : int ParseSighashString(const UniValue& sighash);
123 : :
124 : : //! Parse a confirm target option and raise an RPC error if it is invalid.
125 : : unsigned int ParseConfirmTarget(const UniValue& value, unsigned int max_target);
126 : :
127 : : RPCErrorCode RPCErrorFromTransactionError(TransactionError terr);
128 : : UniValue JSONRPCTransactionError(TransactionError terr, const std::string& err_string = "");
129 : :
130 : : //! Parse a JSON range specified as int64, or [int64, int64]
131 : : std::pair<int64_t, int64_t> ParseDescriptorRange(const UniValue& value);
132 : :
133 : : /** Evaluate a descriptor given as a string, or as a {"desc":...,"range":...} object, with default range of 1000. */
134 : : std::vector<CScript> EvalDescriptorStringOrObject(const UniValue& scanobject, FlatSigningProvider& provider, const bool expand_priv = false);
135 : :
136 : : /** Returns, given services flags, a list of humanly readable (known) network services */
137 : : UniValue GetServicesNames(ServiceFlags services);
138 : :
139 : : /**
140 : : * Serializing JSON objects depends on the outer type. Only arrays and
141 : : * dictionaries can be nested in json. The top-level outer type is "NONE".
142 : : */
143 : : enum class OuterType {
144 : : ARR,
145 : : OBJ,
146 : : NONE, // Only set on first recursion
147 : : };
148 : :
149 : 700 : struct RPCArgOptions {
150 : : bool skip_type_check{false};
151 : : std::string oneline_description{}; //!< Should be empty unless it is supposed to override the auto-generated summary line
152 : : std::vector<std::string> type_str{}; //!< Should be empty unless it is supposed to override the auto-generated type strings. Vector length is either 0 or 2, m_opts.type_str.at(0) will override the type of the value in a key-value pair, m_opts.type_str.at(1) will override the type in the argument description.
153 : : bool hidden{false}; //!< For testing only
154 : : bool also_positional{false}; //!< If set allows a named-parameter field in an OBJ_NAMED_PARAM options object
155 : : //!< to have the same name as a top-level parameter. By default the RPC
156 : : //!< framework disallows this, because if an RPC request passes the value by
157 : : //!< name, it is assigned to top-level parameter position, not to the options
158 : : //!< position, defeating the purpose of using OBJ_NAMED_PARAMS instead OBJ for
159 : : //!< that option. But sometimes it makes sense to allow less-commonly used
160 : : //!< options to be passed by name only, and more commonly used options to be
161 : : //!< passed by name or position, so the RPC framework allows this as long as
162 : : //!< methods set the also_positional flag and read values from both positions.
163 : : };
164 : :
165 [ + - ][ + - ]: 700 : struct RPCArg {
[ - + ][ # # ]
[ # # ][ # # ]
166 : : enum class Type {
167 : : OBJ,
168 : : ARR,
169 : : STR,
170 : : NUM,
171 : : BOOL,
172 : : OBJ_NAMED_PARAMS, //!< Special type that behaves almost exactly like
173 : : //!< OBJ, defining an options object with a list of
174 : : //!< pre-defined keys. The only difference between OBJ
175 : : //!< and OBJ_NAMED_PARAMS is that OBJ_NAMED_PARMS
176 : : //!< also allows the keys to be passed as top-level
177 : : //!< named parameters, as a more convenient way to pass
178 : : //!< options to the RPC method without nesting them.
179 : : OBJ_USER_KEYS, //!< Special type where the user must set the keys e.g. to define multiple addresses; as opposed to e.g. an options object where the keys are predefined
180 : : AMOUNT, //!< Special type representing a floating point amount (can be either NUM or STR)
181 : : STR_HEX, //!< Special type that is a STR with only hex chars
182 : : RANGE, //!< Special type that is a NUM or [NUM,NUM]
183 : : };
184 : :
185 : : enum class Optional {
186 : : /** Required arg */
187 : : NO,
188 : : /**
189 : : * Optional argument for which the default value is omitted from
190 : : * help text for one of two reasons:
191 : : * - It's a named argument and has a default value of `null`.
192 : : * - Its default value is implicitly clear. That is, elements in an
193 : : * array may not exist by default.
194 : : * When possible, the default value should be specified.
195 : : */
196 : : OMITTED,
197 : : };
198 : : /** Hint for default value */
199 : : using DefaultHint = std::string;
200 : : /** Default constant value */
201 : : using Default = UniValue;
202 : : using Fallback = std::variant<Optional, DefaultHint, Default>;
203 : :
204 : : const std::string m_names; //!< The name of the arg (can be empty for inner args, can contain multiple aliases separated by | for named request arguments)
205 : : const Type m_type;
206 : : const std::vector<RPCArg> m_inner; //!< Only used for arrays or dicts
207 : : const Fallback m_fallback;
208 : : const std::string m_description;
209 : : const RPCArgOptions m_opts;
210 : :
211 : 820 : RPCArg(
212 : : std::string name,
213 : : Type type,
214 : : Fallback fallback,
215 : : std::string description,
216 : : RPCArgOptions opts = {})
217 : 410 : : m_names{std::move(name)},
218 : 410 : m_type{std::move(type)},
219 : 410 : m_fallback{std::move(fallback)},
220 : 410 : m_description{std::move(description)},
221 : 410 : m_opts{std::move(opts)}
222 : : {
223 [ + - ][ + - ]: 410 : CHECK_NONFATAL(type != Type::ARR && type != Type::OBJ && type != Type::OBJ_NAMED_PARAMS && type != Type::OBJ_USER_KEYS);
[ - + ][ + - ]
224 : 410 : }
225 : :
226 : 74 : RPCArg(
227 : : std::string name,
228 : : Type type,
229 : : Fallback fallback,
230 : : std::string description,
231 : : std::vector<RPCArg> inner,
232 : : RPCArgOptions opts = {})
233 : 74 : : m_names{std::move(name)},
234 : 74 : m_type{std::move(type)},
235 : 74 : m_inner{std::move(inner)},
236 : 74 : m_fallback{std::move(fallback)},
237 : 74 : m_description{std::move(description)},
238 : 74 : m_opts{std::move(opts)}
239 : : {
240 [ + + ][ + + ]: 74 : CHECK_NONFATAL(type == Type::ARR || type == Type::OBJ || type == Type::OBJ_NAMED_PARAMS || type == Type::OBJ_USER_KEYS);
[ + + ][ + - ]
241 : 74 : }
242 : :
243 : : bool IsOptional() const;
244 : :
245 : : /**
246 : : * Check whether the request JSON type matches.
247 : : * Returns true if type matches, or object describing error(s) if not.
248 : : */
249 : : UniValue MatchesType(const UniValue& request) const;
250 : :
251 : : /** Return the first of all aliases */
252 : : std::string GetFirstName() const;
253 : :
254 : : /** Return the name, throws when there are aliases */
255 : : std::string GetName() const;
256 : :
257 : : /**
258 : : * Return the type string of the argument.
259 : : * Set oneline to allow it to be overridden by a custom oneline type string (m_opts.oneline_description).
260 : : */
261 : : std::string ToString(bool oneline) const;
262 : : /**
263 : : * Return the type string of the argument when it is in an object (dict).
264 : : * Set oneline to get the oneline representation (less whitespace)
265 : : */
266 : : std::string ToStringObj(bool oneline) const;
267 : : /**
268 : : * Return the description string, including the argument type and whether
269 : : * the argument is required.
270 : : */
271 : : std::string ToDescriptionString(bool is_named_arg) const;
272 : : };
273 : :
274 [ + - ][ - + ]: 9326 : struct RPCResult {
[ + - ][ - + ]
275 : : enum class Type {
276 : : OBJ,
277 : : ARR,
278 : : STR,
279 : : NUM,
280 : : BOOL,
281 : : NONE,
282 : : ANY, //!< Special type to disable type checks (for testing only)
283 : : STR_AMOUNT, //!< Special string to represent a floating point amount
284 : : STR_HEX, //!< Special string with only hex chars
285 : : OBJ_DYN, //!< Special dictionary with keys that are not literals
286 : : ARR_FIXED, //!< Special array that has a fixed number of entries
287 : : NUM_TIME, //!< Special numeric to denote unix epoch time
288 : : ELISION, //!< Special type to denote elision (...)
289 : : };
290 : :
291 : : const Type m_type;
292 : : const std::string m_key_name; //!< Only used for dicts
293 : : const std::vector<RPCResult> m_inner; //!< Only used for arrays or dicts
294 : : const bool m_optional;
295 : : const bool m_skip_type_check;
296 : : const std::string m_description;
297 : : const std::string m_cond;
298 : :
299 : 62 : RPCResult(
300 : : std::string cond,
301 : : Type type,
302 : : std::string m_key_name,
303 : : bool optional,
304 : : std::string description,
305 : : std::vector<RPCResult> inner = {})
306 : 62 : : m_type{std::move(type)},
307 : 62 : m_key_name{std::move(m_key_name)},
308 : 62 : m_inner{std::move(inner)},
309 : 62 : m_optional{optional},
310 : 62 : m_skip_type_check{false},
311 : 62 : m_description{std::move(description)},
312 : 62 : m_cond{std::move(cond)}
313 : : {
314 [ + - ]: 62 : CHECK_NONFATAL(!m_cond.empty());
315 [ + - ]: 62 : CheckInnerDoc();
316 : 62 : }
317 : :
318 : 62 : RPCResult(
319 : : std::string cond,
320 : : Type type,
321 : : std::string m_key_name,
322 : : std::string description,
323 : : std::vector<RPCResult> inner = {})
324 [ + - ]: 62 : : RPCResult{std::move(cond), type, std::move(m_key_name), /*optional=*/false, std::move(description), std::move(inner)} {}
325 : :
326 : 1926 : RPCResult(
327 : : Type type,
328 : : std::string m_key_name,
329 : : bool optional,
330 : : std::string description,
331 : : std::vector<RPCResult> inner = {},
332 : : bool skip_type_check = false)
333 : 1926 : : m_type{std::move(type)},
334 : 1926 : m_key_name{std::move(m_key_name)},
335 : 1926 : m_inner{std::move(inner)},
336 : 1926 : m_optional{optional},
337 : 1926 : m_skip_type_check{skip_type_check},
338 : 1926 : m_description{std::move(description)},
339 : 1926 : m_cond{}
340 : : {
341 [ + - ]: 1926 : CheckInnerDoc();
342 : 1926 : }
343 : :
344 : 1582 : RPCResult(
345 : : Type type,
346 : : std::string m_key_name,
347 : : std::string description,
348 : : std::vector<RPCResult> inner = {},
349 : : bool skip_type_check = false)
350 [ + - ]: 1582 : : RPCResult{type, std::move(m_key_name), /*optional=*/false, std::move(description), std::move(inner), skip_type_check} {}
351 : :
352 : : /** Append the sections of the result. */
353 : : void ToSections(Sections& sections, OuterType outer_type = OuterType::NONE, const int current_indent = 0) const;
354 : : /** Return the type string of the result when it is in an object (dict). */
355 : : std::string ToStringObj() const;
356 : : /** Return the description string, including the result type. */
357 : : std::string ToDescriptionString() const;
358 : : /** Check whether the result JSON type matches.
359 : : * Returns true if type matches, or object describing error(s) if not.
360 : : */
361 : : UniValue MatchesType(const UniValue& result) const;
362 : :
363 : : private:
364 : : void CheckInnerDoc() const;
365 : : };
366 : :
367 : 0 : struct RPCResults {
368 : : const std::vector<RPCResult> m_results;
369 : :
370 : 190 : RPCResults(RPCResult result)
371 [ + - ][ + - ]: 190 : : m_results{{result}}
372 : : {
373 : 190 : }
374 : :
375 : 30 : RPCResults(std::initializer_list<RPCResult> results)
376 [ + - ]: 30 : : m_results{results}
377 : : {
378 : 30 : }
379 : :
380 : : /**
381 : : * Return the description string.
382 : : */
383 : : std::string ToDescriptionString() const;
384 : : };
385 : :
386 : 0 : struct RPCExamples {
387 : : const std::string m_examples;
388 : 220 : explicit RPCExamples(
389 : : std::string examples)
390 : 220 : : m_examples(std::move(examples))
391 : : {
392 : 220 : }
393 : : std::string ToDescriptionString() const;
394 : : };
395 : :
396 : 0 : class RPCHelpMan
397 : : {
398 : : public:
399 : : RPCHelpMan(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples);
400 : : using RPCMethodImpl = std::function<UniValue(const RPCHelpMan&, const JSONRPCRequest&)>;
401 : : RPCHelpMan(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples, RPCMethodImpl fun);
402 : :
403 : : UniValue HandleRequest(const JSONRPCRequest& request) const;
404 : : /**
405 : : * Helper to get a request argument.
406 : : * This function only works during m_fun(), i.e. it should only be used in
407 : : * RPC method implementations. The helper internally checks whether the
408 : : * user-passed argument isNull() and parses (from JSON) and returns the
409 : : * user-passed argument, or the default value derived from the RPCArg
410 : : * documention, or a falsy value if no default was given.
411 : : *
412 : : * Use Arg<Type>(i) to get the argument or its default value. Otherwise,
413 : : * use MaybeArg<Type>(i) to get the optional argument or a falsy value.
414 : : *
415 : : * The Type passed to this helper must match the corresponding
416 : : * RPCArg::Type.
417 : : */
418 : : template <typename R>
419 : 0 : auto Arg(size_t i) const
420 : : {
421 : : // Return argument (required or with default value).
422 : : if constexpr (std::is_integral_v<R> || std::is_floating_point_v<R>) {
423 : : // Return numbers by value.
424 : 0 : return ArgValue<R>(i);
425 : : } else {
426 : : // Return everything else by reference.
427 : 0 : return ArgValue<const R&>(i);
428 : : }
429 : : }
430 : : template <typename R>
431 : 0 : auto MaybeArg(size_t i) const
432 : : {
433 : : // Return optional argument (without default).
434 : : if constexpr (std::is_integral_v<R> || std::is_floating_point_v<R>) {
435 : : // Return numbers by value, wrapped in optional.
436 : 0 : return ArgValue<std::optional<R>>(i);
437 : : } else {
438 : : // Return other types by pointer.
439 : 0 : return ArgValue<const R*>(i);
440 : : }
441 : : }
442 : : std::string ToString() const;
443 : : /** Return the named args that need to be converted from string to another JSON type */
444 : : UniValue GetArgMap() const;
445 : : /** If the supplied number of args is neither too small nor too high */
446 : : bool IsValidNumArgs(size_t num_args) const;
447 : : //! Return list of arguments and whether they are named-only.
448 : : std::vector<std::pair<std::string, bool>> GetArgNames() const;
449 : :
450 : : const std::string m_name;
451 : :
452 : : private:
453 : : const RPCMethodImpl m_fun;
454 : : const std::string m_description;
455 : : const std::vector<RPCArg> m_args;
456 : : const RPCResults m_results;
457 : : const RPCExamples m_examples;
458 : : mutable const JSONRPCRequest* m_req{nullptr}; // A pointer to the request for the duration of m_fun()
459 : : template <typename R>
460 : : R ArgValue(size_t i) const;
461 : : };
462 : :
463 : : /**
464 : : * Push warning messages to an RPC "warnings" field as a JSON array of strings.
465 : : *
466 : : * @param[in] warnings Warning messages to push.
467 : : * @param[out] obj UniValue object to push the warnings array object to.
468 : : */
469 : : void PushWarnings(const UniValue& warnings, UniValue& obj);
470 : : void PushWarnings(const std::vector<bilingual_str>& warnings, UniValue& obj);
471 : :
472 : : #endif // BITCOIN_RPC_UTIL_H
|
