util.h
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 struct RPCResultOptions { 296 bool skip_type_check{false}; 297 /// Whether to treat this as elided in the human-readable description, and 298 /// possibly supply a description for the elision. Normally, there will be 299 /// one string on any of the elided results, for example `Same output as 300 /// verbosity = 1`, and all other elided strings will be empty. 301 /// 302 /// - If nullopt: normal display. 303 /// - If empty string: suppress from help. 304 /// - If non-empty: show "..." with this description. 305 std::optional<std::string> print_elision{std::nullopt}; 306 }; 307 // NOLINTNEXTLINE(misc-no-recursion) 308 struct RPCResult { 309 enum class Type { 310 OBJ, 311 ARR, 312 STR, 313 NUM, 314 BOOL, 315 NONE, 316 ANY, //!< Special type to disable type checks (for testing only) 317 STR_AMOUNT, //!< Special string to represent a floating point amount 318 STR_HEX, //!< Special string with only hex chars 319 OBJ_DYN, //!< Special dictionary with keys that are not literals 320 ARR_FIXED, //!< Special array that has a fixed number of entries 321 NUM_TIME, //!< Special numeric to denote unix epoch time 322 ELISION, //!< Special type to denote elision (...) 323 }; 324 325 const Type m_type; 326 const std::string m_key_name; //!< Only used for dicts 327 const std::vector<RPCResult> m_inner; //!< Only used for arrays or dicts 328 const bool m_optional; 329 const RPCResultOptions m_opts; 330 const std::string m_description; 331 const std::string m_cond; 332 333 RPCResult( 334 std::string cond, 335 Type type, 336 std::string m_key_name, 337 bool optional, 338 std::string description, 339 std::vector<RPCResult> inner = {}, 340 RPCResultOptions opts = {}) 341 : m_type{std::move(type)}, 342 m_key_name{std::move(m_key_name)}, 343 m_inner{std::move(inner)}, 344 m_optional{optional}, 345 m_opts{std::move(opts)}, 346 m_description{std::move(description)}, 347 m_cond{std::move(cond)} 348 { 349 CHECK_NONFATAL(!m_cond.empty()); 350 CheckInnerDoc(); 351 } 352 353 RPCResult( 354 std::string cond, 355 Type type, 356 std::string m_key_name, 357 std::string description, 358 std::vector<RPCResult> inner = {}, 359 RPCResultOptions opts = {}) 360 : RPCResult{std::move(cond), type, std::move(m_key_name), /*optional=*/false, std::move(description), std::move(inner), std::move(opts)} {} 361 362 RPCResult( 363 Type type, 364 std::string m_key_name, 365 bool optional, 366 std::string description, 367 std::vector<RPCResult> inner = {}, 368 RPCResultOptions opts = {}) 369 : m_type{std::move(type)}, 370 m_key_name{std::move(m_key_name)}, 371 m_inner{std::move(inner)}, 372 m_optional{optional}, 373 m_opts{std::move(opts)}, 374 m_description{std::move(description)}, 375 m_cond{} 376 { 377 CheckInnerDoc(); 378 } 379 380 RPCResult( 381 Type type, 382 std::string m_key_name, 383 std::string description, 384 std::vector<RPCResult> inner = {}, 385 RPCResultOptions opts = {}) 386 : RPCResult{type, std::move(m_key_name), /*optional=*/false, std::move(description), std::move(inner), std::move(opts)} {} 387 388 /** Append the sections of the result. */ 389 void ToSections(Sections& sections, OuterType outer_type = OuterType::NONE, int current_indent = 0) const; 390 /** Return the type string of the result when it is in an object (dict). */ 391 std::string ToStringObj() const; 392 /** Return the description string, including the result type. */ 393 std::string ToDescriptionString() const; 394 /** Check whether the result JSON type matches. 395 * Returns true if type matches, or object describing error(s) if not. 396 */ 397 UniValue MatchesType(const UniValue& result) const; 398 399 private: 400 void CheckInnerDoc() const; 401 }; 402 403 struct RPCResults { 404 const std::vector<RPCResult> m_results; 405 406 RPCResults(RPCResult result) 407 : m_results{{result}} 408 { 409 } 410 411 RPCResults(std::initializer_list<RPCResult> results) 412 : m_results{results} 413 { 414 } 415 416 /** 417 * Return the description string. 418 */ 419 std::string ToDescriptionString() const; 420 }; 421 422 struct RPCExamples { 423 const std::string m_examples; 424 explicit RPCExamples( 425 std::string examples) 426 : m_examples(std::move(examples)) 427 { 428 } 429 std::string ToDescriptionString() const; 430 }; 431 432 class RPCMethod 433 { 434 public: 435 RPCMethod(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples); 436 using RPCMethodImpl = std::function<UniValue(const RPCMethod&, const JSONRPCRequest&)>; 437 RPCMethod(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples, RPCMethodImpl fun); 438 439 UniValue HandleRequest(const JSONRPCRequest& request) const; 440 /** 441 * @brief Helper to get a required or default-valued request argument. 442 * 443 * Use this function when the argument is required or when it has a default value. If the 444 * argument is optional and may not be provided, use MaybeArg instead. 445 * 446 * This function only works during m_fun(), i.e., it should only be used in 447 * RPC method implementations. It internally checks whether the user-passed 448 * argument isNull() and parses (from JSON) and returns the user-passed argument, 449 * or the default value derived from the RPCArg documentation. 450 * 451 * The instantiation of this helper for type R must match the corresponding RPCArg::Type. 452 * 453 * @return The value of the RPC argument (or the default value) cast to type R. 454 * 455 * @see MaybeArg for handling optional arguments without default values. 456 */ 457 template <typename R> 458 auto Arg(std::string_view key) const 459 { 460 auto i{GetParamIndex(key)}; 461 // Return argument (required or with default value). 462 if constexpr (std::is_trivially_copyable_v<R>) { 463 // Return trivially copyable types by value. 464 return ArgValue<R>(i); 465 } else { 466 // Return everything else by reference. 467 return ArgValue<const R&>(i); 468 } 469 } 470 /** 471 * @brief Helper to get an optional request argument. 472 * 473 * Use this function when the argument is optional and does not have a default value. If the 474 * argument is required or has a default value, use Arg instead. 475 * 476 * This function only works during m_fun(), i.e., it should only be used in 477 * RPC method implementations. It internally checks whether the user-passed 478 * argument isNull() and parses (from JSON) and returns the user-passed argument, 479 * or a falsy value if no argument was passed. 480 * 481 * The instantiation of this helper for type R must match the corresponding RPCArg::Type. 482 * 483 * @return For trivially copyable types, a std::optional<R> is returned. 484 * For other types, a R* pointer to the argument is returned. If the 485 * argument is not provided, std::nullopt or a null pointer is returned. 486 * 487 * @see Arg for handling arguments that are required or have a default value. 488 */ 489 template <typename R> 490 auto MaybeArg(std::string_view key) const 491 { 492 auto i{GetParamIndex(key)}; 493 // Return optional argument (without default). 494 if constexpr (std::is_trivially_copyable_v<R>) { 495 // Return trivially copyable types by value, wrapped in optional. 496 return ArgValue<std::optional<R>>(i); 497 } else { 498 // Return other types by pointer. 499 return ArgValue<const R*>(i); 500 } 501 } 502 std::string ToString() const; 503 /** Return the named args that need to be converted from string to another JSON type */ 504 UniValue GetArgMap() const; 505 /** If the supplied number of args is neither too small nor too high */ 506 bool IsValidNumArgs(size_t num_args) const; 507 //! Return list of arguments and whether they are named-only. 508 std::vector<std::pair<std::string, bool>> GetArgNames() const; 509 510 const std::string m_name; 511 512 private: 513 const RPCMethodImpl m_fun; 514 const std::string m_description; 515 const std::vector<RPCArg> m_args; 516 const RPCResults m_results; 517 const RPCExamples m_examples; 518 mutable const JSONRPCRequest* m_req{nullptr}; // A pointer to the request for the duration of m_fun() 519 template <typename R> 520 R ArgValue(size_t i) const; 521 //! Return positional index of a parameter using its name as key. 522 size_t GetParamIndex(std::string_view key) const; 523 }; 524 525 /** 526 * Push warning messages to an RPC "warnings" field as a JSON array of strings. 527 * 528 * @param[in] warnings Warning messages to push. 529 * @param[out] obj UniValue object to push the warnings array object to. 530 */ 531 void PushWarnings(const UniValue& warnings, UniValue& obj); 532 void PushWarnings(const std::vector<bilingual_str>& warnings, UniValue& obj); 533 534 std::vector<RPCResult> ScriptPubKeyDoc(); 535 536 /*** 537 * Get the target for a given block index. 538 * 539 * @param[in] blockindex the block 540 * @param[in] pow_limit PoW limit (consensus parameter) 541 * 542 * @return the target 543 */ 544 uint256 GetTarget(const CBlockIndex& blockindex, uint256 pow_limit); 545 546 #endif // BITCOIN_RPC_UTIL_H