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 <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  enum class TransactionError;
 38  struct FlatSigningProvider;
 39  struct bilingual_str;
 40  
 41  static constexpr bool DEFAULT_RPC_DOC_CHECK{
 42  #ifdef RPC_DOC_CHECK
 43      true
 44  #else
 45      false
 46  #endif
 47  };
 48  
 49  /**
 50   * String used to describe UNIX epoch time in documentation, factored out to a
 51   * constant for consistency.
 52   */
 53  extern const std::string UNIX_EPOCH_TIME;
 54  
 55  /**
 56   * Example bech32 addresses for the RPCExamples help documentation. They are intentionally
 57   * invalid to prevent accidental transactions by users.
 58   */
 59  extern const std::string EXAMPLE_ADDRESS[2];
 60  
 61  class FillableSigningProvider;
 62  class CScript;
 63  struct Sections;
 64  
 65  /**
 66   * Gets all existing output types formatted for RPC help sections.
 67   *
 68   * @return Comma separated string representing output type names.
 69   */
 70  std::string GetAllOutputTypes();
 71  
 72  /** Wrapper for UniValue::VType, which includes typeAny:
 73   * Used to denote don't care type. */
 74  struct UniValueType {
 75      UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
 76      UniValueType() : typeAny(true) {}
 77      bool typeAny;
 78      UniValue::VType type;
 79  };
 80  
 81  /*
 82    Check for expected keys/value types in an Object.
 83  */
 84  void RPCTypeCheckObj(const UniValue& o,
 85      const std::map<std::string, UniValueType>& typesExpected,
 86      bool fAllowNull = false,
 87      bool fStrict = false);
 88  
 89  /**
 90   * Utilities: convert hex-encoded Values
 91   * (throws error if not hex).
 92   */
 93  uint256 ParseHashV(const UniValue& v, std::string_view name);
 94  uint256 ParseHashO(const UniValue& o, std::string_view strKey);
 95  std::vector<unsigned char> ParseHexV(const UniValue& v, std::string_view name);
 96  std::vector<unsigned char> ParseHexO(const UniValue& o, std::string_view strKey);
 97  
 98  /**
 99   * Validate and return a CAmount from a UniValue number or string.
100   *
101   * @param[in] value     UniValue number or string to parse.
102   * @param[in] decimals  Number of significant digits (default: 8).
103   * @returns a CAmount if the various checks pass.
104   */
105  CAmount AmountFromValue(const UniValue& value, int decimals = 8);
106  /**
107   * Parse a json number or string, denoting BTC/kvB, into a CFeeRate (sat/kvB).
108   * Reject negative values or rates larger than 1BTC/kvB.
109   */
110  CFeeRate ParseFeeRate(const UniValue& json);
111  
112  using RPCArgList = std::vector<std::pair<std::string, UniValue>>;
113  std::string HelpExampleCli(const std::string& methodname, const std::string& args);
114  std::string HelpExampleCliNamed(const std::string& methodname, const RPCArgList& args);
115  std::string HelpExampleRpc(const std::string& methodname, const std::string& args);
116  std::string HelpExampleRpcNamed(const std::string& methodname, const RPCArgList& args);
117  
118  CPubKey HexToPubKey(const std::string& hex_in);
119  CPubKey AddrToPubKey(const FillableSigningProvider& keystore, const std::string& addr_in);
120  CTxDestination AddAndGetMultisigDestination(const int required, const std::vector<CPubKey>& pubkeys, OutputType type, FillableSigningProvider& keystore, CScript& script_out);
121  
122  UniValue DescribeAddress(const CTxDestination& dest);
123  
124  /** Parse a sighash string representation and raise an RPC error if it is invalid. */
125  int ParseSighashString(const UniValue& sighash);
126  
127  //! Parse a confirm target option and raise an RPC error if it is invalid.
128  unsigned int ParseConfirmTarget(const UniValue& value, unsigned int max_target);
129  
130  RPCErrorCode RPCErrorFromTransactionError(TransactionError terr);
131  UniValue JSONRPCTransactionError(TransactionError terr, const std::string& err_string = "");
132  
133  //! Parse a JSON range specified as int64, or [int64, int64]
134  std::pair<int64_t, int64_t> ParseDescriptorRange(const UniValue& value);
135  
136  /** Evaluate a descriptor given as a string, or as a {"desc":...,"range":...} object, with default range of 1000. */
137  std::vector<CScript> EvalDescriptorStringOrObject(const UniValue& scanobject, FlatSigningProvider& provider, const bool expand_priv = false);
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  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  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      RPCArg(
212          std::string name,
213          Type type,
214          Fallback fallback,
215          std::string description,
216          RPCArgOptions opts = {})
217          : m_names{std::move(name)},
218            m_type{std::move(type)},
219            m_fallback{std::move(fallback)},
220            m_description{std::move(description)},
221            m_opts{std::move(opts)}
222      {
223          CHECK_NONFATAL(type != Type::ARR && type != Type::OBJ && type != Type::OBJ_NAMED_PARAMS && type != Type::OBJ_USER_KEYS);
224      }
225  
226      RPCArg(
227          std::string name,
228          Type type,
229          Fallback fallback,
230          std::string description,
231          std::vector<RPCArg> inner,
232          RPCArgOptions opts = {})
233          : m_names{std::move(name)},
234            m_type{std::move(type)},
235            m_inner{std::move(inner)},
236            m_fallback{std::move(fallback)},
237            m_description{std::move(description)},
238            m_opts{std::move(opts)}
239      {
240          CHECK_NONFATAL(type == Type::ARR || type == Type::OBJ || type == Type::OBJ_NAMED_PARAMS || type == Type::OBJ_USER_KEYS);
241      }
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  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      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          : m_type{std::move(type)},
307            m_key_name{std::move(m_key_name)},
308            m_inner{std::move(inner)},
309            m_optional{optional},
310            m_skip_type_check{false},
311            m_description{std::move(description)},
312            m_cond{std::move(cond)}
313      {
314          CHECK_NONFATAL(!m_cond.empty());
315          CheckInnerDoc();
316      }
317  
318      RPCResult(
319          std::string cond,
320          Type type,
321          std::string m_key_name,
322          std::string description,
323          std::vector<RPCResult> inner = {})
324          : RPCResult{std::move(cond), type, std::move(m_key_name), /*optional=*/false, std::move(description), std::move(inner)} {}
325  
326      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          : m_type{std::move(type)},
334            m_key_name{std::move(m_key_name)},
335            m_inner{std::move(inner)},
336            m_optional{optional},
337            m_skip_type_check{skip_type_check},
338            m_description{std::move(description)},
339            m_cond{}
340      {
341          CheckInnerDoc();
342      }
343  
344      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          : 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  struct RPCResults {
368      const std::vector<RPCResult> m_results;
369  
370      RPCResults(RPCResult result)
371          : m_results{{result}}
372      {
373      }
374  
375      RPCResults(std::initializer_list<RPCResult> results)
376          : m_results{results}
377      {
378      }
379  
380      /**
381       * Return the description string.
382       */
383      std::string ToDescriptionString() const;
384  };
385  
386  struct RPCExamples {
387      const std::string m_examples;
388      explicit RPCExamples(
389          std::string examples)
390          : m_examples(std::move(examples))
391      {
392      }
393      std::string ToDescriptionString() const;
394  };
395  
396  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       * documentation, 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      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              return ArgValue<R>(i);
425          } else {
426              // Return everything else by reference.
427              return ArgValue<const R&>(i);
428          }
429      }
430      template <typename R>
431      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              return ArgValue<std::optional<R>>(i);
437          } else {
438              // Return other types by pointer.
439              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