Bitcoin Core Fuzz Coverage Report

// Copyright (c) 2009-2010 Satoshi Nakamoto

// Copyright (c) 2009-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_VALIDATION_H

#define BITCOIN_VALIDATION_H

#include <arith_uint256.h>

#include <attributes.h>

#include <chain.h>

#include <checkqueue.h>

#include <coins.h>

#include <consensus/amount.h>

#include <cuckoocache.h>

#include <deploymentstatus.h>

#include <kernel/chain.h>

#include <kernel/chainparams.h>

#include <kernel/chainstatemanager_opts.h>

#include <kernel/cs_main.h> // IWYU pragma: export

#include <node/blockstorage.h>

#include <policy/feerate.h>

#include <policy/packages.h>

#include <policy/policy.h>

#include <script/script_error.h>

#include <script/sigcache.h>

#include <script/verify_flags.h>

#include <sync.h>

#include <txdb.h>

#include <txmempool.h>

#include <uint256.h>

#include <util/byte_units.h>

#include <util/check.h>

#include <util/fs.h>

#include <util/hasher.h>

#include <util/result.h>

#include <util/time.h>

#include <util/translation.h>

#include <versionbits.h>

#include <algorithm>

#include <atomic>

#include <cstdint>

#include <map>

#include <memory>

#include <optional>

#include <set>

#include <span>

#include <string>

#include <type_traits>

#include <utility>

#include <vector>

class Chainstate;

class CTxMemPool;

class ChainstateManager;

struct ChainTxData;

class DisconnectedBlockTransactions;

struct PrecomputedTransactionData;

struct LockPoints;

struct AssumeutxoData;

namespace kernel {

struct ChainstateRole;

} // namespace kernel

namespace node {

class SnapshotMetadata;

} // namespace node

namespace Consensus {

struct Params;

} // namespace Consensus

namespace util {

class SignalInterrupt;

} // namespace util

/** Block files containing a block-height within MIN_BLOCKS_TO_KEEP of ActiveChain().Tip() will not be pruned. */

static const unsigned int MIN_BLOCKS_TO_KEEP = 288;

static const signed int DEFAULT_CHECKBLOCKS = 6;

static constexpr int DEFAULT_CHECKLEVEL{3};

// Require that user allocate at least 550 MiB for block & undo files (blk???.dat and rev???.dat)

// At 1MB per block, 288 blocks = 288MB.

// Add 15% for Undo data = 331MB

// Add 20% for Orphan block rate = 397MB

// We want the low water mark after pruning to be at least 397 MB and since we prune in

// full block file chunks, we need the high water mark which triggers the prune to be

// one 128MB block file + added 15% undo data = 147MB greater for a total of 545MB

// Setting the target to >= 550 MiB will make it likely we can respect the target.

static const uint64_t MIN_DISK_SPACE_FOR_BLOCK_FILES = 550 * 1024 * 1024;

/** Maximum number of dedicated script-checking threads allowed */

static constexpr int MAX_SCRIPTCHECK_THREADS{15};

/** Current sync state passed to tip changed callbacks. */

enum class SynchronizationState {

    INIT_REINDEX,

    INIT_DOWNLOAD,

    POST_INIT

};

/** Documentation for argument 'checklevel'. */

extern const std::vector<std::string> CHECKLEVEL_DOC;

CAmount GetBlockSubsidy(int nHeight, const Consensus::Params& consensusParams);

bool FatalError(kernel::Notifications& notifications, BlockValidationState& state, const bilingual_str& message);

/** Prune block files up to a given height */

void PruneBlockFilesManual(Chainstate& active_chainstate, int nManualPruneHeight);

/**

* Validation result for a transaction evaluated by MemPoolAccept (single or package).

* Here are the expected fields and properties of a result depending on its ResultType, applicable to

* results returned from package evaluation:

*+---------------------------+----------------+-------------------+------------------+----------------+-------------------+

*| Field or property         |    VALID       |                 INVALID              |  MEMPOOL_ENTRY | DIFFERENT_WITNESS |

*|                           |                |--------------------------------------|                |                   |

*|                           |                | TX_RECONSIDERABLE |     Other        |                |                   |

*+---------------------------+----------------+-------------------+------------------+----------------+-------------------+

*| txid in mempool?          | yes            | no                | no*              | yes            | yes               |

*| wtxid in mempool?         | yes            | no                | no*              | yes            | no                |

*| m_state                   | yes, IsValid() | yes, IsInvalid()  | yes, IsInvalid() | yes, IsValid() | yes, IsValid()    |

*| m_vsize                   | yes            | no                | no               | yes            | no                |

*| m_base_fees               | yes            | no                | no               | yes            | no                |

*| m_effective_feerate       | yes            | yes               | no               | no             | no                |

*| m_wtxids_fee_calculations | yes            | yes               | no               | no             | no                |

*| m_other_wtxid             | no             | no                | no               | no             | yes               |

*+---------------------------+----------------+-------------------+------------------+----------------+-------------------+

* (*) Individual transaction acceptance doesn't return MEMPOOL_ENTRY and DIFFERENT_WITNESS. It returns

* INVALID, with the errors txn-already-in-mempool and txn-same-nonwitness-data-in-mempool

* respectively. In those cases, the txid or wtxid may be in the mempool for a TX_CONFLICT.

*/

struct MempoolAcceptResult {

    /** Used to indicate the results of mempool validation. */

    enum class ResultType {

        VALID, //!> Fully validated, valid.

        INVALID, //!> Invalid.

        MEMPOOL_ENTRY, //!> Valid, transaction was already in the mempool.

        DIFFERENT_WITNESS, //!> Not validated. A same-txid-different-witness tx (see m_other_wtxid) already exists in the mempool and was not replaced.

    };

    /** Result type. Present in all MempoolAcceptResults. */

    const ResultType m_result_type;

    /** Contains information about why the transaction failed. */

    const TxValidationState m_state;

    /** Mempool transactions replaced by the tx. */

    const std::list<CTransactionRef> m_replaced_transactions;

    /** Virtual size as used by the mempool, calculated using serialized size and sigops. */

    const std::optional<int64_t> m_vsize;

    /** Raw base fees in satoshis. */

    const std::optional<CAmount> m_base_fees;

    /** The feerate at which this transaction was considered. This includes any fee delta added

     * using prioritisetransaction (i.e. modified fees). If this transaction was submitted as a

     * package, this is the package feerate, which may also include its descendants and/or

     * ancestors (see m_wtxids_fee_calculations below).

     */

    const std::optional<CFeeRate> m_effective_feerate;

    /** Contains the wtxids of the transactions used for fee-related checks. Includes this

     * transaction's wtxid and may include others if this transaction was validated as part of a

     * package. This is not necessarily equivalent to the list of transactions passed to

     * ProcessNewPackage().

     * Only present when m_result_type = ResultType::VALID. */

    const std::optional<std::vector<Wtxid>> m_wtxids_fee_calculations;

    /** The wtxid of the transaction in the mempool which has the same txid but different witness. */

    const std::optional<Wtxid> m_other_wtxid;

    static MempoolAcceptResult Failure(TxValidationState state) {

        return MempoolAcceptResult(state);

    }

    static MempoolAcceptResult FeeFailure(TxValidationState state,

                                          CFeeRate effective_feerate,

                                          const std::vector<Wtxid>& wtxids_fee_calculations) {

        return MempoolAcceptResult(state, effective_feerate, wtxids_fee_calculations);

    }

    static MempoolAcceptResult Success(std::list<CTransactionRef>&& replaced_txns,

                                       int64_t vsize,

                                       CAmount fees,

                                       CFeeRate effective_feerate,

                                       const std::vector<Wtxid>& wtxids_fee_calculations) {

        return MempoolAcceptResult(std::move(replaced_txns), vsize, fees,

                                   effective_feerate, wtxids_fee_calculations);

    }

    static MempoolAcceptResult MempoolTx(int64_t vsize, CAmount fees) {

        return MempoolAcceptResult(vsize, fees);

    }

    static MempoolAcceptResult MempoolTxDifferentWitness(const Wtxid& other_wtxid) {

        return MempoolAcceptResult(other_wtxid);

    }

// Private constructors. Use static methods MempoolAcceptResult::Success, etc. to construct.

private:

    /** Constructor for failure case */

    explicit MempoolAcceptResult(TxValidationState state)

        : m_result_type(ResultType::INVALID), m_state(state) {

            Assume(!state.IsValid()); // Can be invalid or error

Line

Count

Source

125

0

#define Assume(val) inline_assertion_check<false>(val, std::source_location::current(), #val)

        }

    /** Constructor for success case */

    explicit MempoolAcceptResult(std::list<CTransactionRef>&& replaced_txns,

                                 int64_t vsize,

                                 CAmount fees,

                                 CFeeRate effective_feerate,

                                 const std::vector<Wtxid>& wtxids_fee_calculations)

        : m_result_type(ResultType::VALID),

        m_replaced_transactions(std::move(replaced_txns)),

        m_vsize{vsize},

        m_base_fees(fees),

        m_effective_feerate(effective_feerate),

        m_wtxids_fee_calculations(wtxids_fee_calculations) {}

    /** Constructor for fee-related failure case */

    explicit MempoolAcceptResult(TxValidationState state,

                                 CFeeRate effective_feerate,

                                 const std::vector<Wtxid>& wtxids_fee_calculations)

        : m_result_type(ResultType::INVALID),

        m_state(state),

        m_effective_feerate(effective_feerate),

        m_wtxids_fee_calculations(wtxids_fee_calculations) {}

    /** Constructor for already-in-mempool case. It wouldn't replace any transactions. */

    explicit MempoolAcceptResult(int64_t vsize, CAmount fees)

        : m_result_type(ResultType::MEMPOOL_ENTRY), m_vsize{vsize}, m_base_fees(fees) {}

    /** Constructor for witness-swapped case. */

    explicit MempoolAcceptResult(const Wtxid& other_wtxid)

        : m_result_type(ResultType::DIFFERENT_WITNESS), m_other_wtxid(other_wtxid) {}

};

/**

* Validation result for package mempool acceptance.

*/

struct PackageMempoolAcceptResult

{

    PackageValidationState m_state;

    /**

    * Map from wtxid to finished MempoolAcceptResults. The client is responsible

    * for keeping track of the transaction objects themselves. If a result is not

    * present, it means validation was unfinished for that transaction. If there

    * was a package-wide error (see result in m_state), m_tx_results will be empty.

    */

    std::map<Wtxid, MempoolAcceptResult> m_tx_results;

    explicit PackageMempoolAcceptResult(PackageValidationState state,

                                        std::map<Wtxid, MempoolAcceptResult>&& results)

        : m_state{state}, m_tx_results(std::move(results)) {}

    explicit PackageMempoolAcceptResult(PackageValidationState state, CFeeRate feerate,

                                        std::map<Wtxid, MempoolAcceptResult>&& results)

        : m_state{state}, m_tx_results(std::move(results)) {}

    /** Constructor to create a PackageMempoolAcceptResult from a single MempoolAcceptResult */

    explicit PackageMempoolAcceptResult(const Wtxid& wtxid, const MempoolAcceptResult& result)

        : m_tx_results{ {wtxid, result} } {}

};

/**

 * Try to add a transaction to the mempool. This is an internal function and is exposed only for testing.

 * Client code should use ChainstateManager::ProcessTransaction()

 *

 * @param[in]  active_chainstate  Reference to the active chainstate.

 * @param[in]  tx                 The transaction to submit for mempool acceptance.

 * @param[in]  accept_time        The timestamp for adding the transaction to the mempool.

 *                                It is also used to determine when the entry expires.

 * @param[in]  bypass_limits      When true, don't enforce mempool fee and capacity limits,

 *                                and set entry_sequence to zero.

 * @param[in]  test_accept        When true, run validation checks but don't submit to mempool.

 *

 * @returns a MempoolAcceptResult indicating whether the transaction was accepted/rejected with reason.

 */

MempoolAcceptResult AcceptToMemoryPool(Chainstate& active_chainstate, const CTransactionRef& tx,

                                       int64_t accept_time, bool bypass_limits, bool test_accept)

    EXCLUSIVE_LOCKS_REQUIRED(cs_main);

/**

* Validate (and maybe submit) a package to the mempool. See doc/policy/packages.md for full details

* on package validation rules.

* @param[in]    test_accept         When true, run validation checks but don't submit to mempool.

* @param[in]    client_maxfeerate    If exceeded by an individual transaction, rest of (sub)package evaluation is aborted.

*                                   Only for sanity checks against local submission of transactions.

* @returns a PackageMempoolAcceptResult which includes a MempoolAcceptResult for each transaction.

* If a transaction fails, validation will exit early and some results may be missing. It is also

* possible for the package to be partially submitted.

*/

PackageMempoolAcceptResult ProcessNewPackage(Chainstate& active_chainstate, CTxMemPool& pool,

                                                   const Package& txns, bool test_accept, const std::optional<CFeeRate>& client_maxfeerate)

                                                   EXCLUSIVE_LOCKS_REQUIRED(cs_main);

/* Mempool validation helper functions */

/**

 * Check if transaction will be final in the next block to be created.

 */

bool CheckFinalTxAtTip(const CBlockIndex& active_chain_tip, const CTransaction& tx) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

/**

 * Calculate LockPoints required to check if transaction will be BIP68 final in the next block

 * to be created on top of tip.

 *

 * @param[in]   tip             Chain tip for which tx sequence locks are calculated. For

 *                              example, the tip of the current active chain.

 * @param[in]   coins_view      Any CCoinsView that provides access to the relevant coins for

 *                              checking sequence locks. For example, it can be a CCoinsViewCache

 *                              that isn't connected to anything but contains all the relevant

 *                              coins, or a CCoinsViewMemPool that is connected to the

 *                              mempool and chainstate UTXO set. In the latter case, the caller

 *                              is responsible for holding the appropriate locks to ensure that

 *                              calls to GetCoin() return correct coins.

 * @param[in]   tx              The transaction being evaluated.

 *

 * @returns The resulting height and time calculated and the hash of the block needed for

 *          calculation, or std::nullopt if there is an error.

 */

std::optional<LockPoints> CalculateLockPointsAtTip(

    CBlockIndex* tip,

    const CCoinsView& coins_view,

    const CTransaction& tx);

/**

 * Check if transaction will be BIP68 final in the next block to be created on top of tip.

 * @param[in]   tip             Chain tip to check tx sequence locks against. For example,

 *                              the tip of the current active chain.

 * @param[in]   lock_points     LockPoints containing the height and time at which this

 *                              transaction is final.

 * Simulates calling SequenceLocks() with data from the tip passed in.

 * The LockPoints should not be considered valid if CheckSequenceLocksAtTip returns false.

 */

bool CheckSequenceLocksAtTip(CBlockIndex* tip,

                             const LockPoints& lock_points);

/**

 * Closure representing one script verification

 * Note that this stores references to the spending transaction

 */

class CScriptCheck

{

private:

    CTxOut m_tx_out;

    const CTransaction *ptxTo;

    unsigned int nIn;

    script_verify_flags m_flags;

    bool cacheStore;

    PrecomputedTransactionData *txdata;

    SignatureCache* m_signature_cache;

public:

    CScriptCheck(const CTxOut& outIn, const CTransaction& txToIn, SignatureCache& signature_cache, unsigned int nInIn, script_verify_flags flags, bool cacheIn, PrecomputedTransactionData* txdataIn) :

        m_tx_out(outIn), ptxTo(&txToIn), nIn(nInIn), m_flags(flags), cacheStore(cacheIn), txdata(txdataIn), m_signature_cache(&signature_cache) { }

    CScriptCheck(const CScriptCheck&) = delete;

    CScriptCheck& operator=(const CScriptCheck&) = delete;

    CScriptCheck(CScriptCheck&&) = default;

    CScriptCheck& operator=(CScriptCheck&&) = default;

    std::optional<std::pair<ScriptError, std::string>> operator()();

};

// CScriptCheck is used a lot in std::vector, make sure that's efficient

static_assert(std::is_nothrow_move_assignable_v<CScriptCheck>);

static_assert(std::is_nothrow_move_constructible_v<CScriptCheck>);

static_assert(std::is_nothrow_destructible_v<CScriptCheck>);

/**

 * Convenience class for initializing and passing the script execution cache

 * and signature cache.

 */

class ValidationCache

{

private:

    //! Pre-initialized hasher to avoid having to recreate it for every hash calculation.

    CSHA256 m_script_execution_cache_hasher;

public:

    CuckooCache::cache<uint256, SignatureCacheHasher> m_script_execution_cache;

    SignatureCache m_signature_cache;

    ValidationCache(size_t script_execution_cache_bytes, size_t signature_cache_bytes);

    ValidationCache(const ValidationCache&) = delete;

    ValidationCache& operator=(const ValidationCache&) = delete;

    //! Return a copy of the pre-initialized hasher.

    CSHA256 ScriptExecutionCacheHasher() const { return m_script_execution_cache_hasher; }

};

/** Functions for validating blocks and updating the block tree */

/** Context-independent validity checks */

bool CheckBlock(const CBlock& block, BlockValidationState& state, const Consensus::Params& consensusParams, bool fCheckPOW = true, bool fCheckMerkleRoot = true);

/**

 * Verify a block, including transactions.

 *

 * @param[in]   block       The block we want to process. Must connect to the

 *                          current tip.

 * @param[in]   chainstate  The chainstate to connect to.

 * @param[in]   check_pow   perform proof-of-work check, nBits in the header

 *                          is always checked

 * @param[in]   check_merkle_root check the merkle root

 *

 * @return Valid or Invalid state. This doesn't currently return an Error state,

 *         and shouldn't unless there is something wrong with the existing

 *         chainstate. (This is different from functions like AcceptBlock which

 *         can fail trying to save new data.)

 *

 * For signets the challenge verification is skipped when check_pow is false.

 */

BlockValidationState TestBlockValidity(

    Chainstate& chainstate,

    const CBlock& block,

    bool check_pow,

    bool check_merkle_root) EXCLUSIVE_LOCKS_REQUIRED(cs_main);

/** Check that the proof of work on each blockheader matches the value in nBits */

bool HasValidProofOfWork(std::span<const CBlockHeader> headers, const Consensus::Params& consensusParams);

/** Check if a block has been mutated (with respect to its merkle root and witness commitments). */

bool IsBlockMutated(const CBlock& block, bool check_witness_root);

/** Return the sum of the claimed work on a given set of headers. No verification of PoW is done. */

arith_uint256 CalculateClaimedHeadersWork(std::span<const CBlockHeader> headers);

enum class VerifyDBResult {

    SUCCESS,

    CORRUPTED_BLOCK_DB,

    INTERRUPTED,

    SKIPPED_L3_CHECKS,

    SKIPPED_MISSING_BLOCKS,

};

/** RAII wrapper for VerifyDB: Verify consistency of the block and coin databases */

class CVerifyDB

{

private:

    kernel::Notifications& m_notifications;

public:

    explicit CVerifyDB(kernel::Notifications& notifications);

    ~CVerifyDB();

    [[nodiscard]] VerifyDBResult VerifyDB(

        Chainstate& chainstate,

        const Consensus::Params& consensus_params,

        CCoinsView& coinsview,

        int nCheckLevel,

        int nCheckDepth) EXCLUSIVE_LOCKS_REQUIRED(cs_main);

};

enum DisconnectResult

{

    DISCONNECT_OK,      // All good.

    DISCONNECT_UNCLEAN, // Rolled back, but UTXO set was inconsistent with block.

    DISCONNECT_FAILED   // Something else went wrong.

};

struct ConnectedBlock;

/** @see Chainstate::FlushStateToDisk */

inline constexpr std::array FlushStateModeNames{"NONE", "IF_NEEDED", "PERIODIC", "FORCE_FLUSH", "FORCE_SYNC"};

enum class FlushStateMode: uint8_t {

    NONE,

    IF_NEEDED,

    PERIODIC,

    FORCE_FLUSH,

    FORCE_SYNC,

};

/**

 * A convenience class for constructing the CCoinsView* hierarchy used

 * to facilitate access to the UTXO set.

 *

 * This class consists of an arrangement of layered CCoinsView objects,

 * preferring to store and retrieve coins in memory via `m_cacheview` but

 * ultimately falling back on cache misses to the canonical store of UTXOs on

 * disk, `m_dbview`.

 */

class CoinsViews {

public:

    //! The lowest level of the CoinsViews cache hierarchy sits in a leveldb database on disk.

    //! All unspent coins reside in this store.

    CCoinsViewDB m_dbview GUARDED_BY(cs_main);

    //! This view wraps access to the leveldb instance and handles read errors gracefully.

    CCoinsViewErrorCatcher m_catcherview GUARDED_BY(cs_main);

    //! This is the top layer of the cache hierarchy - it keeps as many coins in memory as

    //! can fit per the dbcache setting.

    std::unique_ptr<CCoinsViewCache> m_cacheview GUARDED_BY(cs_main);

    //! Reused CoinsViewOverlay layered on top of m_cacheview and passed to ConnectBlock().

    //! Reset between calls and flushed only on success, so invalid blocks don't pollute the underlying cache.

    std::unique_ptr<CoinsViewOverlay> m_connect_block_view GUARDED_BY(cs_main);

    //! This constructor initializes CCoinsViewDB and CCoinsViewErrorCatcher instances, but it

    //! *does not* create a CCoinsViewCache instance by default. This is done separately because the

    //! presence of the cache has implications on whether or not we're allowed to flush the cache's

    //! state to disk, which should not be done until the health of the database is verified.

    //!

    //! All arguments forwarded onto CCoinsViewDB.

    CoinsViews(DBParams db_params, CoinsViewOptions options);

    //! Initialize the CCoinsViewCache member.

    void InitCache() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

};

enum class CoinsCacheSizeState

{

    //! The coins cache is in immediate need of a flush.

    CRITICAL = 2,

    //! The cache is at >= 90% capacity.

    LARGE = 1,

    OK = 0

};

constexpr int64_t LargeCoinsCacheThreshold(int64_t total_space) noexcept

{

    // No periodic flush needed if at least this much space is free

    constexpr int64_t MAX_BLOCK_COINSDB_USAGE_BYTES{int64_t(10_MiB)};

    return std::max((total_space * 9) / 10,

                    total_space - MAX_BLOCK_COINSDB_USAGE_BYTES);

}

//! Chainstate assumeutxo validity.

enum class Assumeutxo {

    //! Every block in the chain has been validated.

    VALIDATED,

    //! Blocks after an assumeutxo snapshot have been validated but the snapshot itself has not been validated.

    UNVALIDATED,

    //! The assumeutxo snapshot failed validation.

    INVALID,

};

/**

 * Chainstate stores and provides an API to update our local knowledge of the

 * current best chain.

 *

 * Eventually, the API here is targeted at being exposed externally as a

 * consumable library, so any functions added must only call

 * other class member functions, pure functions in other parts of the consensus

 * library, callbacks via the validation interface, or read/write-to-disk

 * functions (eventually this will also be via callbacks).

 *

 * Anything that is contingent on the current tip of the chain is stored here,

 * whereas block information and metadata independent of the current tip is

 * kept in `BlockManager`.

 */

class Chainstate

{

protected:

    /**

     * The ChainState Mutex

     * A lock that must be held when modifying this ChainState - held in ActivateBestChain() and

     * InvalidateBlock()

     */

    Mutex m_chainstate_mutex;

    //! Optional mempool that is kept in sync with the chain.

    //! Only the active chainstate has a mempool.

    CTxMemPool* m_mempool;

    //! Manages the UTXO set, which is a reflection of the contents of `m_chain`.

    std::unique_ptr<CoinsViews> m_coins_views;

    //! Cached result of LookupBlockIndex(*m_from_snapshot_blockhash)

    mutable const CBlockIndex* m_cached_snapshot_base GUARDED_BY(::cs_main){nullptr};

    //! Cached result of LookupBlockIndex(*m_target_blockhash)

    mutable const CBlockIndex* m_cached_target_block GUARDED_BY(::cs_main){nullptr};

    std::optional<const char*> m_last_script_check_reason_logged GUARDED_BY(::cs_main){};

public:

    //! Reference to a BlockManager instance which itself is shared across all

    //! Chainstate instances.

    node::BlockManager& m_blockman;

    //! The chainstate manager that owns this chainstate. The reference is

    //! necessary so that this instance can check whether it is the active

    //! chainstate within deeply nested method calls.

    ChainstateManager& m_chainman;

    explicit Chainstate(

        CTxMemPool* mempool,

        node::BlockManager& blockman,

        ChainstateManager& chainman,

        std::optional<uint256> from_snapshot_blockhash = std::nullopt);

    //! Return path to chainstate leveldb directory.

    fs::path StoragePath() const;

    //! Return the current role of the chainstate. See `ChainstateManager`

    //! documentation for a description of the different types of chainstates.

    //!

    //! @sa ChainstateRole

    kernel::ChainstateRole GetRole() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    /**

     * Initialize the CoinsViews UTXO set database management data structures. The in-memory

     * cache is initialized separately.

     *

     * All parameters forwarded to CoinsViews.

     */

    void InitCoinsDB(

        size_t cache_size_bytes,

        bool in_memory,

        bool should_wipe);

    //! Initialize the in-memory coins cache (to be done after the health of the on-disk database

    //! is verified).

    void InitCoinsCache(size_t cache_size_bytes) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    //! @returns whether or not the CoinsViews object has been fully initialized and we can

    //!          safely flush this object to disk.

    bool CanFlushToDisk() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main)

    {

        AssertLockHeld(::cs_main);

Line

Count

Source

142

0

#define AssertLockHeld(cs) AssertLockHeldInternal(#cs, __FILE__, __LINE__, &cs)

        return m_coins_views && m_coins_views->m_cacheview;

    }

    //! The current chain of blockheaders we consult and build on.

    //! @see CChain, CBlockIndex.

    CChain m_chain;

    //! Assumeutxo state indicating whether all blocks in the chain were

    //! validated, or if the chainstate is based on an assumeutxo snapshot and

    //! the snapshot has not been validated.

    Assumeutxo m_assumeutxo GUARDED_BY(::cs_main);

    /**

     * The blockhash which is the base of the snapshot this chainstate was created from.

     *

     * std::nullopt if this chainstate was not created from a snapshot.

     */

    const std::optional<uint256> m_from_snapshot_blockhash;

    //! Target block for this chainstate. If this is not set, chainstate will

    //! target the most-work, valid block. If this is set, ChainstateManager

    //! considers this a "historical" chainstate since it will only contain old

    //! blocks up to the target block, not newer blocks.

    std::optional<uint256> m_target_blockhash GUARDED_BY(::cs_main);

    //! Hash of the UTXO set at the target block, computed when the chainstate

    //! reaches the target block, and null before then.

    std::optional<AssumeutxoHash> m_target_utxohash GUARDED_BY(::cs_main);

    /**

     * The base of the snapshot this chainstate was created from.

     *

     * nullptr if this chainstate was not created from a snapshot.

     */

    const CBlockIndex* SnapshotBase() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    //! Return target block which chainstate tip is expected to reach, if this

    //! is a historic chainstate being used to validate a snapshot, or null if

    //! chainstate targets the most-work block.

    const CBlockIndex* TargetBlock() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    //! Set target block for this chainstate. If null, chainstate will target

    //! the most-work valid block. If non-null chainstate will be a historic

    //! chainstate and target the specified block.

    void SetTargetBlock(CBlockIndex* block) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    //! Set target block for this chainstate using just a block hash. Useful

    //! when the block database has not been loaded yet.

    void SetTargetBlockHash(uint256 block_hash) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    //! Return true if chainstate reached target block.

    bool ReachedTarget() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main)

    {

        const CBlockIndex* target_block{TargetBlock()};

        assert(!target_block || target_block->GetAncestor(m_chain.Height()) == m_chain.Tip());

        return target_block && target_block == m_chain.Tip();

    }

    /**

     * The set of all CBlockIndex entries that have as much work as our current

     * tip or more, and transaction data needed to be validated (with

     * BLOCK_VALID_TRANSACTIONS for each block and its parents back to the

     * genesis block or an assumeutxo snapshot block). Entries may be failed,

     * though, and pruning nodes may be missing the data for the block.

     */

    std::set<CBlockIndex*, node::CBlockIndexWorkComparator> setBlockIndexCandidates;

    //! @returns A reference to the in-memory cache of the UTXO set.

    CCoinsViewCache& CoinsTip() EXCLUSIVE_LOCKS_REQUIRED(::cs_main)

    {

        AssertLockHeld(::cs_main);

Line

Count

Source

142

0

#define AssertLockHeld(cs) AssertLockHeldInternal(#cs, __FILE__, __LINE__, &cs)

        Assert(m_coins_views);

Line

Count

Source

113

0

#define Assert(val) inline_assertion_check<true>(val, std::source_location::current(), #val)

        return *Assert(m_coins_views->m_cacheview);

Line

Count

Source

113

0

#define Assert(val) inline_assertion_check<true>(val, std::source_location::current(), #val)

    }

    //! @returns A reference to the on-disk UTXO set database.

    CCoinsViewDB& CoinsDB() EXCLUSIVE_LOCKS_REQUIRED(::cs_main)

    {

        AssertLockHeld(::cs_main);

Line

Count

Source

142

0

#define AssertLockHeld(cs) AssertLockHeldInternal(#cs, __FILE__, __LINE__, &cs)

        return Assert(m_coins_views)->m_dbview;

Line

Count

Source

113

0

#define Assert(val) inline_assertion_check<true>(val, std::source_location::current(), #val)

    }

    //! @returns A pointer to the mempool.

    CTxMemPool* GetMempool()

    {

        return m_mempool;

    }

    //! @returns A reference to a wrapped view of the in-memory UTXO set that

    //!     handles disk read errors gracefully.

    CCoinsViewErrorCatcher& CoinsErrorCatcher() EXCLUSIVE_LOCKS_REQUIRED(::cs_main)

    {

        AssertLockHeld(::cs_main);

Line

Count

Source

142

0

#define AssertLockHeld(cs) AssertLockHeldInternal(#cs, __FILE__, __LINE__, &cs)

        return Assert(m_coins_views)->m_catcherview;

Line

Count

Source

113

0

#define Assert(val) inline_assertion_check<true>(val, std::source_location::current(), #val)

    }

    //! Destructs all objects related to accessing the UTXO set.

    void ResetCoinsViews() { m_coins_views.reset(); }

    //! The cache size of the on-disk coins view.

    size_t m_coinsdb_cache_size_bytes{0};

    //! The cache size of the in-memory coins view.

    size_t m_coinstip_cache_size_bytes{0};

    //! Resize the CoinsViews caches dynamically and flush state to disk.

    //! @returns true unless an error occurred during the flush.

    bool ResizeCoinsCaches(size_t coinstip_size, size_t coinsdb_size)

        EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    /**

     * Update the on-disk chain state.

     * The caches and indexes are flushed depending on the mode we're called with

     * if they're too large, if it's been a while since the last write,

     * or always and in all cases if we're in prune mode and are deleting files.

     *

     * If FlushStateMode::NONE is used, then FlushStateToDisk(...) won't do anything

     * besides checking if we need to prune.

     *

     * @returns true unless a system error occurred

     */

    bool FlushStateToDisk(

        BlockValidationState& state,

        FlushStateMode mode,

        int nManualPruneHeight = 0);

    //! Flush all changes to disk.

    void ForceFlushStateToDisk(bool wipe_cache = true);

    //! Prune blockfiles from the disk if necessary and then flush chainstate changes

    //! if we pruned.

    void PruneAndFlush();

    /**

     * Find the best known block, and make it the tip of the block chain. The

     * result is either failure or an activated best chain. pblock is either

     * nullptr or a pointer to a block that is already loaded (to avoid loading

     * it again from disk).

     *

     * ActivateBestChain is split into steps (see ActivateBestChainStep) so that

     * we avoid holding cs_main for an extended period of time; the length of this

     * call may be quite long during reindexing or a substantial reorg.

     *

     * May not be called with cs_main held. May not be called in a

     * validationinterface callback.

     *

     * Note that if this is called while a snapshot chainstate is active, and if

     * it is called on a validated chainstate whose tip has reached the base

     * block of the snapshot, its execution will take *MINUTES* while it hashes

     * the UTXO set to verify the assumeutxo value the snapshot was activated

     * with. `cs_main` will be held during this time.

     *

     * @returns true unless a system error occurred

     */

    bool ActivateBestChain(

        BlockValidationState& state,

        std::shared_ptr<const CBlock> pblock = nullptr)

        EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex)

        LOCKS_EXCLUDED(::cs_main);

    // Block (dis)connection on a given view:

    DisconnectResult DisconnectBlock(const CBlock& block, const CBlockIndex* pindex, CCoinsViewCache& view)

        EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    bool ConnectBlock(const CBlock& block, BlockValidationState& state, CBlockIndex* pindex,

                      CCoinsViewCache& view, bool fJustCheck = false) EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    // Apply the effects of a block disconnection on the UTXO set.

    bool DisconnectTip(BlockValidationState& state, DisconnectedBlockTransactions* disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs);

    // Manual block validity manipulation:

    /** Mark a block as precious and reorganize.

     *

     * May not be called in a validationinterface callback.

     */

    bool PreciousBlock(BlockValidationState& state, CBlockIndex* pindex)

        EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex)

        LOCKS_EXCLUDED(::cs_main);

    /** Mark a block as invalid. */

    bool InvalidateBlock(BlockValidationState& state, CBlockIndex* pindex)

        EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex)

        LOCKS_EXCLUDED(::cs_main);

    /** Set invalidity status to all descendants of a block */

    void SetBlockFailureFlags(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    /** Remove invalidity status from a block, its descendants and ancestors and reconsider them for activation */

    void ResetBlockFailureFlags(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    /** Replay blocks that aren't fully applied to the database. */

    bool ReplayBlocks();

    /** Whether the chain state needs to be redownloaded due to lack of witness data */

    [[nodiscard]] bool NeedsRedownload() const EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    /** Ensures we have a genesis block in the block tree, possibly writing one to disk. */

    bool LoadGenesisBlock();

    /** Add a block to the candidate set if it has as much work as the current tip. */

    void TryAddBlockIndexCandidate(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    void PruneBlockIndexCandidates();

    void ClearBlockIndexCandidates() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    /** Populate the candidate set by calling TryAddBlockIndexCandidate on all valid block indices. */

    void PopulateBlockIndexCandidates() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    /** Find the last common block of this chain and a locator. */

    const CBlockIndex* FindForkInGlobalIndex(const CBlockLocator& locator) const EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    /** Update the chain tip based on database information, i.e. CoinsTip()'s best block. */

    bool LoadChainTip() EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    //! Dictates whether we need to flush the cache to disk or not.

    //!

    //! @return the state of the size of the coins cache.

    CoinsCacheSizeState GetCoinsCacheSizeState() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    CoinsCacheSizeState GetCoinsCacheSizeState(

        size_t max_coins_cache_size_bytes,

        size_t max_mempool_size_bytes) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    std::string ToString() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    //! Indirection necessary to make lock annotations work with an optional mempool.

    RecursiveMutex* MempoolMutex() const LOCK_RETURNED(m_mempool->cs)

    {

        return m_mempool ? &m_mempool->cs : nullptr;

    }

    //! Return the [start, end] (inclusive) of block heights we can prune.

    //!

    //! start > end is possible, meaning no blocks can be pruned.

    std::pair<int, int> GetPruneRange(int last_height_can_prune) const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

protected:

    bool ActivateBestChainStep(BlockValidationState& state, CBlockIndex* pindexMostWork, const std::shared_ptr<const CBlock>& pblock, bool& fInvalidFound, std::vector<ConnectedBlock>& connected_blocks) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs);

    bool ConnectTip(

        BlockValidationState& state,

        CBlockIndex* pindexNew,

        std::shared_ptr<const CBlock> block_to_connect,

        std::vector<ConnectedBlock>& connected_blocks,

        DisconnectedBlockTransactions& disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs);

    void InvalidBlockFound(CBlockIndex* pindex, const BlockValidationState& state) EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    CBlockIndex* FindMostWorkChain() EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    bool RollforwardBlock(const CBlockIndex* pindex, CCoinsViewCache& inputs) EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    void CheckForkWarningConditions() EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    void InvalidChainFound(CBlockIndex* pindexNew) EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    /**

     * Make mempool consistent after a reorg, by re-adding or recursively erasing

     * disconnected block transactions from the mempool, and also removing any

     * other transactions from the mempool that are no longer valid given the new

     * tip/height.

     *

     * Note: we assume that disconnectpool only contains transactions that are NOT

     * confirmed in the current chain nor already in the mempool (otherwise,

     * in-mempool descendants of such transactions would be removed).

     *

     * Passing fAddToMempool=false will skip trying to add the transactions back,

     * and instead just erase from the mempool as needed.

     */

    void MaybeUpdateMempoolForReorg(

        DisconnectedBlockTransactions& disconnectpool,

        bool fAddToMempool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs);

    /** Check warning conditions and do some notifications on new chain tip set. */

    void UpdateTip(const CBlockIndex* pindexNew)

        EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    NodeClock::time_point m_next_write{NodeClock::time_point::max()};

    /**

     * In case of an invalid snapshot, rename the coins leveldb directory so

     * that it can be examined for issue diagnosis.

     */

    [[nodiscard]] util::Result<void> InvalidateCoinsDBOnDisk() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);

    friend ChainstateManager;

};

enum class SnapshotCompletionResult {

    SUCCESS,

    SKIPPED,

    // Expected assumeutxo configuration data is not found for the height of the

    // base block.

    MISSING_CHAINPARAMS,

    // Failed to generate UTXO statistics (to check UTXO set hash) for the

    // validated chainstate.

    STATS_FAILED,

    // The UTXO set hash of the validated chainstate does not match the one

    // expected by assumeutxo chainparams.

    HASH_MISMATCH,

};

/**

 * Interface for managing multiple \ref Chainstate objects, where each

 * chainstate is associated with chainstate* subdirectory in the data directory

 * and contains a database of UTXOs existing at a different point in history.

 * (See \ref Chainstate class for more information.)

 *

 * Normally there is exactly one Chainstate, which contains the UTXO set of

 * chain tip if syncing is completed, or the UTXO set the most recent validated

 * block if the initial sync is still in progress.

 *

 * However, if an assumeutxo snapshot is loaded before syncing is completed,

 * there will be two chainstates. The original fully validated chainstate will

 * continue to exist and download new blocks in the background. But the new

 * snapshot which is loaded will become a second chainstate. The second

 * chainstate will be used as the chain tip for the wallet and RPCs even though

 * it is only assumed to be valid. When the initial chainstate catches up to the

 * snapshot height and confirms that the assumeutxo snapshot is actually valid,

 * the second chainstate will be marked validated and become the only chainstate

 * again.

 */

class ChainstateManager

{

private:

    /** The last header for which a headerTip notification was issued. */

    CBlockIndex* m_last_notified_header GUARDED_BY(GetMutex()){nullptr};

    bool NotifyHeaderTip() LOCKS_EXCLUDED(GetMutex());

    //! Internal helper for ActivateSnapshot().

    //!

    //! De-serialization of a snapshot that is created with

    //! the dumptxoutset RPC.

    //! To reduce space the serialization format of the snapshot avoids

    //! duplication of tx hashes. The code takes advantage of the guarantee by

    //! leveldb that keys are lexicographically sorted.

    [[nodiscard]] util::Result<void> PopulateAndValidateSnapshot(

        Chainstate& snapshot_chainstate,

        AutoFile& coins_file,

        const node::SnapshotMetadata& metadata);

    /**

     * If a block header hasn't already been seen, call CheckBlockHeader on it, ensure

     * that it doesn't descend from an invalid block, and then add it to m_block_index.

     * Caller must set min_pow_checked=true in order to add a new header to the

     * block index (permanent memory storage), indicating that the header is

     * known to be part of a sufficiently high-work chain (anti-dos check).

     */

    bool AcceptBlockHeader(

        const CBlockHeader& block,

        BlockValidationState& state,

        CBlockIndex** ppindex,

        bool min_pow_checked) EXCLUSIVE_LOCKS_REQUIRED(cs_main);

    friend Chainstate;

    /** Most recent headers presync progress update, for rate-limiting. */

    MockableSteadyClock::time_point m_last_presync_update GUARDED_BY(GetMutex()){};

    //! A queue for script verifications that have to be performed by worker threads.

    CCheckQueue<CScriptCheck> m_script_check_queue;

    //! Timers and counters used for benchmarking validation in both background

    //! and active chainstates.

    SteadyClock::duration GUARDED_BY(::cs_main) time_check{};

    SteadyClock::duration GUARDED_BY(::cs_main) time_forks{};

    SteadyClock::duration GUARDED_BY(::cs_main) time_connect{};

    SteadyClock::duration GUARDED_BY(::cs_main) time_verify{};

    SteadyClock::duration GUARDED_BY(::cs_main) time_undo{};

    SteadyClock::duration GUARDED_BY(::cs_main) time_index{};

    SteadyClock::duration GUARDED_BY(::cs_main) time_total{};

    int64_t GUARDED_BY(::cs_main) num_blocks_total{0};

    SteadyClock::duration GUARDED_BY(::cs_main) time_connect_total{};

    SteadyClock::duration GUARDED_BY(::cs_main) time_flush{};

    SteadyClock::duration GUARDED_BY(::cs_main) time_chainstate{};

    SteadyClock::duration GUARDED_BY(::cs_main) time_post_connect{};

protected:

    CBlockIndex* m_best_invalid GUARDED_BY(::cs_main){nullptr};

public:

    using Options = kernel::ChainstateManagerOpts;

    explicit ChainstateManager(const util::SignalInterrupt& interrupt, Options options, node::BlockManager::Options blockman_options);

    //! Function to restart active indexes; set dynamically to avoid a circular

    //! dependency on `base/index.cpp`.

    std::function<void()> snapshot_download_completed = std::function<void()>();

    const CChainParams& GetParams() const { return m_options.chainparams; }

    const Consensus::Params& GetConsensus() const { return m_options.chainparams.GetConsensus(); }

    bool ShouldCheckBlockIndex() const;

    const arith_uint256& MinimumChainWork() const { return *Assert(m_options.minimum_chain_work); }

Line

Count

Source

113

0

#define Assert(val) inline_assertion_check<true>(val, std::source_location::current(), #val)

    const uint256& AssumedValidBlock() const { return *Assert(m_options.assumed_valid_block); }

Line

Count

Source

113

0

#define Assert(val) inline_assertion_check<true>(val, std::source_location::current(), #val)

    kernel::Notifications& GetNotifications() const { return m_options.notifications; };

    /**

     * Make various assertions about the state of the block index.

     *

     * By default this only executes fully when using the Regtest chain; see: m_options.check_block_index.

     */

    void CheckBlockIndex() const;

    /**

     * Alias for ::cs_main.

     * Should be used in new code to make it easier to make ::cs_main a member

     * of this class.

     * Generally, methods of this class should be annotated to require this

     * mutex. This will make calling code more verbose, but also help to:

     * - Clarify that the method will acquire a mutex that heavily affects

     *   overall performance.

     * - Force call sites to think how long they need to acquire the mutex to

     *   get consistent results.

     */

    RecursiveMutex& GetMutex() const LOCK_RETURNED(::cs_main) { return ::cs_main; }

    const util::SignalInterrupt& m_interrupt;

    const Options m_options;

    //! A single BlockManager instance is shared across each constructed

    //! chainstate to avoid duplicating block metadata.

    node::BlockManager m_blockman;

    ValidationCache m_validation_cache;

    /**

     * Whether initial block download (IBD) is ongoing.

     *

     * This value is used for lock-free IBD checks, and latches from true to

     * false once block loading has finished and the current chain tip has

     * enough work and is recent.

     */

    std::atomic_bool m_cached_is_ibd{true};

    /**

     * Every received block is assigned a unique and increasing identifier, so we

     * know which one to give priority in case of a fork.

     */

    /** Blocks loaded from disk are assigned id SEQ_ID_INIT_FROM_DISK{1}

     * (SEQ_ID_BEST_CHAIN_FROM_DISK{0} if they belong to the best chain loaded from disk),

     * so start the counter after that. **/

    int32_t nBlockSequenceId GUARDED_BY(::cs_main) = SEQ_ID_INIT_FROM_DISK + 1;

    /** Decreasing counter (used by subsequent preciousblock calls). */

    int32_t nBlockReverseSequenceId = -1;

    /** chainwork for the last block that preciousblock has been applied to. */

    arith_uint256 nLastPreciousChainwork = 0;

    // Reset the memory-only sequence counters we use to track block arrival

    // (used by tests to reset state)

    void ResetBlockSequenceCounters() EXCLUSIVE_LOCKS_REQUIRED(::cs_main)

    {

        AssertLockHeld(::cs_main);

        nBlockSequenceId = SEQ_ID_INIT_FROM_DISK + 1;

        nBlockReverseSequenceId = -1;

    }