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