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