LCOV - code coverage report
Current view: top level - src/rpc - util.h (source / functions) Coverage Total Hit
Test: test_bitcoin_coverage.info Lines: 98.4 % 63 62
Test Date: 2025-06-01 05:54:06 Functions: 86.7 % 15 13
Branches: 17.2 % 227 39

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

Generated by: LCOV version 2.0-1