util.h

Go to the documentation of this file.

// Copyright (c) 2017-2021 The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
#ifndef BITCOIN_RPC_UTIL_H
#define BITCOIN_RPC_UTIL_H
 
#include <consensus/amount.h>
#include <node/transaction.h>
#include <outputtype.h>
#include <protocol.h>
#include <rpc/protocol.h>
#include <rpc/request.h>
#include <script/script.h>
#include <script/sign.h>
#include <script/standard.h> // For CTxDestination
#include <uint256.h>
#include <univalue.h>
#include <util/check.h>
 
#include <cstddef>
#include <cstdint>
#include <functional>
#include <initializer_list>
#include <map>
#include <optional>
#include <string>
#include <type_traits>
#include <utility>
#include <variant>
#include <vector>
 
class CChainParams;
class FillableSigningProvider;
class CPubKey;
class CScript;
class JSONRPCRequest;
struct FlatSigningProvider;
enum class OutputType;
struct Sections;
enum ServiceFlags : uint64_t;
enum class TransactionError;
 
static constexpr bool DEFAULT_RPC_DOC_CHECK{false};
 
extern const std::string UNIX_EPOCH_TIME;
 
extern const std::string EXAMPLE_ADDRESS;
 
struct UniValueType {
    UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
    UniValueType() : typeAny(true) {}
    bool typeAny;
    UniValue::VType type;
};
 
void RPCTypeCheckObj(const UniValue &o,
                     const std::map<std::string, UniValueType> &typesExpected,
                     bool fAllowNull = false, bool fStrict = false);
 
extern uint256 ParseHashV(const UniValue &v, std::string strName);
extern uint256 ParseHashO(const UniValue &o, std::string strKey);
extern std::vector<uint8_t> ParseHexV(const UniValue &v, std::string strName);
extern std::vector<uint8_t> ParseHexO(const UniValue &o, std::string strKey);
 
extern Amount AmountFromValue(const UniValue &value);
 
using RPCArgList = std::vector<std::pair<std::string, UniValue>>;
extern std::string HelpExampleCli(const std::string &methodname,
                                  const std::string &args);
extern std::string HelpExampleCliNamed(const std::string &methodname,
                                       const RPCArgList &args);
extern std::string HelpExampleRpc(const std::string &methodname,
                                  const std::string &args);
extern std::string HelpExampleRpcNamed(const std::string &methodname,
                                       const RPCArgList &args);
 
CPubKey HexToPubKey(const std::string &hex_in);
CPubKey AddrToPubKey(const CChainParams &chainparams,
                     const FillableSigningProvider &keystore,
                     const std::string &addr_in);
CTxDestination AddAndGetMultisigDestination(const int required,
                                            const std::vector<CPubKey> &pubkeys,
                                            OutputType type,
                                            FillableSigningProvider &keystore,
                                            CScript &script_out);
 
UniValue DescribeAddress(const CTxDestination &dest);
std::string GetAllOutputTypes();
 
RPCErrorCode RPCErrorFromTransactionError(TransactionError terr);
UniValue JSONRPCTransactionError(TransactionError terr,
                                 const std::string &err_string = "");
 
std::pair<int64_t, int64_t> ParseDescriptorRange(const UniValue &value);
 
std::vector<CScript>
EvalDescriptorStringOrObject(const UniValue &scanobject,
                             FlatSigningProvider &provider);
 
UniValue GetServicesNames(ServiceFlags services);
 
enum class OuterType {
    ARR,
    OBJ,
    NONE, // Only set on first recursion
};
 
struct RPCArgOptions {
    bool skip_type_check{false};
    std::string oneline_description{};
    std::vector<std::string> type_str{};
    bool hidden{false};
    bool also_positional{false};
};
 
struct RPCArg {
    enum class Type {
        OBJ,
        ARR,
        STR,
        NUM,
        BOOL,
        OBJ_NAMED_PARAMS,
        OBJ_USER_KEYS,
        AMOUNT,
        STR_HEX,
        RANGE,
    };
 
    enum class Optional {
        NO,
        OMITTED,
    };
    using DefaultHint = std::string;
    using Default = UniValue;
    using Fallback = std::variant<Optional, DefaultHint, Default>;
 
    const std::string m_names;
    const Type m_type;
    const std::vector<RPCArg> m_inner;
    const Fallback m_fallback;
    const std::string m_description;
    const RPCArgOptions m_opts;
 
    RPCArg(std::string name, Type type, Fallback fallback,
           std::string description, RPCArgOptions opts = {})
        : m_names{std::move(name)}, m_type{std::move(type)},
          m_fallback{std::move(fallback)},
          m_description{std::move(description)}, m_opts{std::move(opts)} {
        CHECK_NONFATAL(type != Type::ARR && type != Type::OBJ &&
                       type != Type::OBJ_NAMED_PARAMS &&
                       type != Type::OBJ_USER_KEYS);
    }
 
    RPCArg(std::string name, Type type, Fallback fallback,
           std::string description, std::vector<RPCArg> inner,
           RPCArgOptions opts = {})
        : m_names{std::move(name)}, m_type{std::move(type)},
          m_inner{std::move(inner)}, m_fallback{std::move(fallback)},
          m_description{std::move(description)}, m_opts{std::move(opts)} {
        CHECK_NONFATAL(type == Type::ARR || type == Type::OBJ ||
                       type == Type::OBJ_NAMED_PARAMS ||
                       type == Type::OBJ_USER_KEYS);
    }
 
    bool IsOptional() const;
 
    UniValue MatchesType(const UniValue &request) const;
 
    std::string GetFirstName() const;
 
    std::string GetName() const;
 
    std::string ToString(bool oneline) const;
    std::string ToStringObj(bool oneline) const;
    std::string ToDescriptionString(bool is_named_arg) const;
};
 
struct RPCResult {
    enum class Type {
        OBJ,
        ARR,
        STR,
        NUM,
        BOOL,
        NONE,
        ANY,        
        STR_AMOUNT, 
        STR_HEX,    
        OBJ_DYN,    
        ARR_FIXED,  
        NUM_TIME,   
        ELISION,    
    };
 
    const Type m_type;
    const std::string m_key_name;         
    const std::vector<RPCResult> m_inner; 
    const bool m_optional;
    const bool m_skip_type_check;
    const std::string m_description;
    const std::string m_cond;
 
    RPCResult(std::string cond, Type type, std::string key_name, bool optional,
              std::string description, std::vector<RPCResult> inner = {})
        : m_type{std::move(type)}, m_key_name{std::move(key_name)},
          m_inner{std::move(inner)}, m_optional{optional},
          m_skip_type_check{false}, m_description{std::move(description)},
          m_cond{std::move(cond)} {
        CHECK_NONFATAL(!m_cond.empty());
        CheckInnerDoc();
    }
 
    RPCResult(std::string cond, Type type, std::string key_name,
              std::string description, std::vector<RPCResult> inner = {})
        : RPCResult{std::move(cond),        type,
                    std::move(key_name),    /*optional=*/false,
                    std::move(description), std::move(inner)} {}
 
    RPCResult(Type type, std::string key_name, bool optional,
              std::string description, std::vector<RPCResult> inner = {},
              bool skip_type_check = false)
        : m_type{std::move(type)}, m_key_name{std::move(key_name)},
          m_inner{std::move(inner)}, m_optional{optional},
          m_skip_type_check{skip_type_check},
          m_description{std::move(description)}, m_cond{} {
        CheckInnerDoc();
    }
 
    RPCResult(Type type, std::string key_name, std::string description,
              std::vector<RPCResult> inner = {}, bool skip_type_check = false)
        : RPCResult{type,
                    std::move(key_name),
                    /*optional=*/false,
                    std::move(description),
                    std::move(inner),
                    skip_type_check} {}
 
    void ToSections(Sections &sections, OuterType outer_type = OuterType::NONE,
                    const int current_indent = 0) const;
    std::string ToStringObj() const;
    std::string ToDescriptionString() const;
    UniValue MatchesType(const UniValue &result) const;
 
private:
    void CheckInnerDoc() const;
};
 
struct RPCResults {
    const std::vector<RPCResult> m_results;
 
    RPCResults(RPCResult result) : m_results{{result}} {}
 
    RPCResults(std::initializer_list<RPCResult> results) : m_results{results} {}
 
    std::string ToDescriptionString() const;
};
 
struct RPCExamples {
    const std::string m_examples;
    explicit RPCExamples(std::string examples)
        : m_examples(std::move(examples)) {}
    RPCExamples() : m_examples(std::move("")) {}
    std::string ToDescriptionString() const;
};
 
class RPCHelpMan {
public:
    RPCHelpMan(std::string name, std::string description,
               std::vector<RPCArg> args, RPCResults results,
               RPCExamples examples);
    using RPCMethodImpl = std::function<UniValue(
        const RPCHelpMan &, const Config &config, const JSONRPCRequest &)>;
    RPCHelpMan(std::string name, std::string description,
               std::vector<RPCArg> args, RPCResults results,
               RPCExamples examples, RPCMethodImpl fun);
 
    UniValue HandleRequest(const Config &config,
                           const JSONRPCRequest &request) const;
    template <typename R> auto Arg(size_t i) const {
        // Return argument (required or with default value).
        if constexpr (std::is_integral_v<R> || std::is_floating_point_v<R>) {
            // Return numbers by value.
            return ArgValue<R>(i);
        } else {
            // Return everything else by reference.
            return ArgValue<const R &>(i);
        }
    }
    template <typename R> auto Arg(std::string_view key) const {
        return Arg<R>(GetParamIndex(key));
    }
    template <typename R> auto MaybeArg(size_t i) const {
        // Return optional argument (without default).
        if constexpr (std::is_integral_v<R> || std::is_floating_point_v<R>) {
            // Return numbers by value, wrapped in optional.
            return ArgValue<std::optional<R>>(i);
        } else {
            // Return other types by pointer.
            return ArgValue<const R *>(i);
        }
    }
    template <typename R> auto MaybeArg(std::string_view key) const {
        return MaybeArg<R>(GetParamIndex(key));
    }
    std::string ToString() const;
    UniValue GetArgMap() const;
    bool IsValidNumArgs(size_t num_args) const;
    std::vector<std::pair<std::string, bool>> GetArgNames() const;
 
    const std::string m_name;
 
private:
    const RPCMethodImpl m_fun;
    const std::string m_description;
    const std::vector<RPCArg> m_args;
    const RPCResults m_results;
    const RPCExamples m_examples;
    mutable const JSONRPCRequest *m_req{nullptr};
    template <typename R> R ArgValue(size_t i) const;
    size_t GetParamIndex(std::string_view key) const;
};
 
#endif // BITCOIN_RPC_UTIL_H