chain.h

Go to the documentation of this file.

// Copyright (c) 2018-present 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_INTERFACES_CHAIN_H
#define BITCOIN_INTERFACES_CHAIN_H

#include <blockfilter.h>
#include <common/settings.h>
#include <kernel/chain.h> // IWYU pragma: export
#include <node/types.h>
#include <primitives/transaction.h>
#include <util/result.h>

#include <cstddef>
#include <cstdint>
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <string>
#include <vector>

class ArgsManager;
class CBlock;
class CBlockUndo;
class CFeeRate;
class CRPCCommand;
class CScheduler;
class Coin;
class uint256;
enum class MemPoolRemovalReason;
enum class RBFTransactionState;
struct bilingual_str;
struct CBlockLocator;
struct FeeCalculation;
namespace kernel {
struct ChainstateRole;
} // namespace kernel
namespace node {
struct NodeContext;
} // namespace node

namespace interfaces {

class Handler;
class Wallet;

class FoundBlock
{
public:
    FoundBlock& hash(uint256& hash) { m_hash = &hash; return *this; }
    FoundBlock& height(int& height) { m_height = &height; return *this; }
    FoundBlock& time(int64_t& time) { m_time = &time; return *this; }
    FoundBlock& maxTime(int64_t& max_time) { m_max_time = &max_time; return *this; }
    FoundBlock& mtpTime(int64_t& mtp_time) { m_mtp_time = &mtp_time; return *this; }
    FoundBlock& inActiveChain(bool& in_active_chain) { m_in_active_chain = &in_active_chain; return *this; }
    FoundBlock& locator(CBlockLocator& locator) { m_locator = &locator; return *this; }
    FoundBlock& nextBlock(const FoundBlock& next_block) { m_next_block = &next_block; return *this; }
    FoundBlock& data(CBlock& data) { m_data = &data; return *this; }

    uint256* m_hash = nullptr;
    int* m_height = nullptr;
    int64_t* m_time = nullptr;
    int64_t* m_max_time = nullptr;
    int64_t* m_mtp_time = nullptr;
    bool* m_in_active_chain = nullptr;
    CBlockLocator* m_locator = nullptr;
    const FoundBlock* m_next_block = nullptr;
    CBlock* m_data = nullptr;
    mutable bool found = false;
};

enum class SettingsAction {
    WRITE,
    SKIP_WRITE
};

using SettingsUpdate = std::function<std::optional<interfaces::SettingsAction>(common::SettingsValue&)>;

class Chain
{
public:
    virtual ~Chain() = default;

    virtual std::optional<int> getHeight() = 0;

    virtual uint256 getBlockHash(int height) = 0;

    virtual bool haveBlockOnDisk(int height) = 0;

    virtual std::optional<int> findLocatorFork(const CBlockLocator& locator) = 0;

    virtual bool hasBlockFilterIndex(BlockFilterType filter_type) = 0;

    virtual std::optional<bool> blockFilterMatchesAny(BlockFilterType filter_type, const uint256& block_hash, const GCSFilter::ElementSet& filter_set) = 0;

    virtual bool findBlock(const uint256& hash, const FoundBlock& block={}) = 0;

    virtual bool findFirstBlockWithTimeAndHeight(int64_t min_time, int min_height, const FoundBlock& block={}) = 0;

    virtual bool findAncestorByHeight(const uint256& block_hash, int ancestor_height, const FoundBlock& ancestor_out={}) = 0;

    virtual bool findAncestorByHash(const uint256& block_hash,
        const uint256& ancestor_hash,
        const FoundBlock& ancestor_out={}) = 0;

    virtual bool findCommonAncestor(const uint256& block_hash1,
        const uint256& block_hash2,
        const FoundBlock& ancestor_out={},
        const FoundBlock& block1_out={},
        const FoundBlock& block2_out={}) = 0;

    virtual void findCoins(std::map<COutPoint, Coin>& coins) = 0;

    virtual double guessVerificationProgress(const uint256& block_hash) = 0;

    virtual bool hasBlocks(const uint256& block_hash, int min_height = 0, std::optional<int> max_height = {}) = 0;

    virtual RBFTransactionState isRBFOptIn(const CTransaction& tx) = 0;

    virtual bool isInMempool(const Txid& txid) = 0;

    virtual bool hasDescendantsInMempool(const Txid& txid) = 0;

    virtual bool broadcastTransaction(const CTransactionRef& tx,
                                      const CAmount& max_tx_fee,
                                      node::TxBroadcast broadcast_method,
                                      std::string& err_string) = 0;

    virtual void getTransactionAncestry(const Txid& txid, size_t& ancestors, size_t& cluster_count, size_t* ancestorsize = nullptr, CAmount* ancestorfees = nullptr) = 0;

    //  feerate, including bumping its ancestors. For example, if the target feerate is 10sat/vbyte
    //  and this outpoint refers to a mempool transaction at 3sat/vbyte, the bump fee includes the
    //  cost to bump the mempool transaction to 10sat/vbyte (i.e. 7 * mempooltx.vsize). If that
    //  transaction also has, say, an unconfirmed parent with a feerate of 1sat/vbyte, the bump fee
    //  includes the cost to bump the parent (i.e. 9 * parentmempooltx.vsize).
    //
    //  If the outpoint comes from an unconfirmed transaction that is already above the target
    //  feerate or bumped by its descendant(s) already, it does not need to be bumped. Its bump fee
    //  is 0. Likewise, if any of the transaction's ancestors are already bumped by a transaction
    //  in our mempool, they are not included in the transaction's bump fee.
    //
    //  Also supported is bump-fee calculation in the case of replacements. If an outpoint
    //  conflicts with another transaction in the mempool, it is assumed that the goal is to replace
    //  that transaction. As such, the calculation will exclude the to-be-replaced transaction, but
    //  will include the fee-bumping cost. If bump fees of descendants of the to-be-replaced
    //  transaction are requested, the value will be 0. Fee-related RBF rules are not included as
    //  they are logically distinct.
    //
    //  Any outpoints that are otherwise unavailable from the mempool (e.g. UTXOs from confirmed
    //  transactions or transactions not yet broadcast by the wallet) are given a bump fee of 0.
    //
    //  If multiple outpoints come from the same transaction (which would be very rare because
    //  it means that one transaction has multiple change outputs or paid the same wallet using multiple
    //  outputs in the same transaction) or have shared ancestry, the bump fees are calculated
    //  independently, i.e. as if only one of them is spent. This may result in double-fee-bumping. This
    //  caveat can be rectified per use of the sister-function CalculateCombinedBumpFee(…).
    virtual std::map<COutPoint, CAmount> calculateIndividualBumpFees(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;

    //  as in CalculateIndividualBumpFees(…).
    //  Unlike CalculateIndividualBumpFees(…), this does not return individual
    //  bump fees per outpoint, but a single bump fee for the shared ancestry.
    //  The combined bump fee may be used to correct overestimation due to
    //  shared ancestry by multiple UTXOs after coin selection.
    virtual std::optional<CAmount> calculateCombinedBumpFee(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;

    virtual void getPackageLimits(unsigned int& limit_ancestor_count, unsigned int& limit_descendant_count) = 0;

    virtual util::Result<void> checkChainLimits(const CTransactionRef& tx) = 0;

    virtual CFeeRate estimateSmartFee(int num_blocks, bool conservative, FeeCalculation* calc = nullptr) = 0;

    virtual unsigned int estimateMaxBlocks() = 0;

    virtual CFeeRate mempoolMinFee() = 0;

    virtual CFeeRate relayMinFee() = 0;

    virtual CFeeRate relayIncrementalFee() = 0;

    virtual CFeeRate relayDustFee() = 0;

    virtual bool havePruned() = 0;

    virtual std::optional<int> getPruneHeight() = 0;

    virtual bool isReadyToBroadcast() = 0;

    virtual bool isInitialBlockDownload() = 0;

    virtual bool shutdownRequested() = 0;

    virtual void initMessage(const std::string& message) = 0;

    virtual void initWarning(const bilingual_str& message) = 0;

    virtual void initError(const bilingual_str& message) = 0;

    virtual void showProgress(const std::string& title, int progress, bool resume_possible) = 0;

    class Notifications
    {
    public:
        virtual ~Notifications() = default;
        virtual void transactionAddedToMempool(const CTransactionRef& tx) {}
        virtual void transactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason reason) {}
        virtual void blockConnected(const kernel::ChainstateRole& role, const BlockInfo& block) {}
        virtual void blockDisconnected(const BlockInfo& block) {}
        virtual void updatedBlockTip() {}
        virtual void chainStateFlushed(const kernel::ChainstateRole& role, const CBlockLocator& locator) {}
    };

    struct NotifyOptions
    {
        bool connect_undo_data = false;
        bool disconnect_data = false;
        bool disconnect_undo_data = false;
    };

    virtual std::unique_ptr<Handler> handleNotifications(std::shared_ptr<Notifications> notifications) = 0;

    virtual void waitForNotificationsIfTipChanged(const uint256& old_tip) = 0;

    virtual void waitForNotifications() = 0;

    virtual std::unique_ptr<Handler> handleRpc(const CRPCCommand& command) = 0;

    virtual bool rpcEnableDeprecated(const std::string& method) = 0;

    virtual common::SettingsValue getSetting(const std::string& arg) = 0;

    virtual std::vector<common::SettingsValue> getSettingsList(const std::string& arg) = 0;

    virtual common::SettingsValue getRwSetting(const std::string& name) = 0;

    virtual bool updateRwSetting(const std::string& name, const SettingsUpdate& update_function) = 0;

    virtual bool overwriteRwSetting(const std::string& name, common::SettingsValue value, SettingsAction action = SettingsAction::WRITE) = 0;

    virtual bool deleteRwSettings(const std::string& name, SettingsAction action = SettingsAction::WRITE) = 0;

    virtual void requestMempoolTransactions(Notifications& notifications) = 0;

    virtual bool hasAssumedValidChain() = 0;

    virtual node::NodeContext* context() { return nullptr; }
};

class ChainClient
{
public:
    virtual ~ChainClient() = default;

    virtual void registerRpcs() = 0;

    virtual bool verify() = 0;

    virtual bool load() = 0;

    virtual void start(CScheduler& scheduler) = 0;

    virtual void stop() = 0;

    virtual void setMockTime(int64_t time) = 0;

    virtual void schedulerMockForward(std::chrono::seconds delta_seconds) = 0;
};

std::unique_ptr<Chain> MakeChain(node::NodeContext& node);

} // namespace interfaces

#endif // BITCOIN_INTERFACES_CHAIN_H