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