Bitcoin Core 28.99.0
P2P Digital Currency
Public Types | Public Member Functions | Public Attributes | Private Member Functions | Private Attributes | List of all members
ChainstateManager Class Reference

Provides an interface for creating and interacting with one or two chainstates: an IBD chainstate generated by downloading blocks, and an optional snapshot chainstate loaded from a UTXO snapshot. More...

#include <validation.h>

Inheritance diagram for ChainstateManager:
[legend]
Collaboration diagram for ChainstateManager:
[legend]

Public Types

using Options = kernel::ChainstateManagerOpts
 

Public Member Functions

 ChainstateManager (const util::SignalInterrupt &interrupt, Options options, node::BlockManager::Options blockman_options)
 
const CChainParamsGetParams () const
 
const Consensus::ParamsGetConsensus () const
 
bool ShouldCheckBlockIndex () const
 
const arith_uint256MinimumChainWork () const
 
const uint256AssumedValidBlock () const
 
kernel::NotificationsGetNotifications () const
 
void CheckBlockIndex ()
 Make various assertions about the state of the block index. More...
 
RecursiveMutexGetMutex () const LOCK_RETURNED(
 Alias for cs_main. More...
 
int32_t nBlockSequenceId GUARDED_BY (::cs_main)
 Every received block is assigned a unique and increasing identifier, so we know which one to give priority in case of a fork. More...
 
void ResetBlockSequenceCounters () EXCLUSIVE_LOCKS_REQUIRED(
 
CBlockIndex *m_best_header GUARDED_BY (::cs_main)
 Best header we've seen so far (used for getheaders queries' starting points). More...
 
util::Result< CBlockIndex * > ActivateSnapshot (AutoFile &coins_file, const node::SnapshotMetadata &metadata, bool in_memory)
 Construct and activate a Chainstate on the basis of UTXO snapshot data. More...
 
CChainActiveChain () const EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
 
int ActiveHeight () const EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
 
CBlockIndexActiveTip () const EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
 
bool BackgroundSyncInProgress () const EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
 The state of a background sync (for net processing) More...
 
const CBlockIndexGetBackgroundSyncTip () const EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
 The tip of the background sync chain. More...
 
node::BlockMapBlockIndex () EXCLUSIVE_LOCKS_REQUIRED(
 
bool IsSnapshotActive () const
 
std::optional< uint256SnapshotBlockhash () const
 
bool IsSnapshotValidated () const EXCLUSIVE_LOCKS_REQUIRED(
 Is there a snapshot in use and has it been fully validated? More...
 
bool IsInitialBlockDownload () const
 Check whether we are doing an initial block download (synchronizing from disk or network) More...
 
void LoadExternalBlockFile (AutoFile &file_in, FlatFilePos *dbp=nullptr, std::multimap< uint256, FlatFilePos > *blocks_with_unknown_parent=nullptr)
 Import blocks from an external file. More...
 
bool ProcessNewBlock (const std::shared_ptr< const CBlock > &block, bool force_processing, bool min_pow_checked, bool *new_block) LOCKS_EXCLUDED(cs_main)
 Process an incoming block. More...
 
bool ProcessNewBlockHeaders (std::span< const CBlockHeader > headers, bool min_pow_checked, BlockValidationState &state, const CBlockIndex **ppindex=nullptr) LOCKS_EXCLUDED(cs_main)
 Process incoming block headers. More...
 
bool AcceptBlock (const std::shared_ptr< const CBlock > &pblock, BlockValidationState &state, CBlockIndex **ppindex, bool fRequested, const FlatFilePos *dbp, bool *fNewBlock, bool min_pow_checked) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Sufficiently validate a block for disk storage (and store on disk). More...
 
void ReceivedBlockTransactions (const CBlock &block, CBlockIndex *pindexNew, const FlatFilePos &pos) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Mark a block as having its data received and checked (up to BLOCK_VALID_TRANSACTIONS). More...
 
MempoolAcceptResult ProcessTransaction (const CTransactionRef &tx, bool test_accept=false) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Try to add a transaction to the memory pool. More...
 
bool LoadBlockIndex () EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Load the block tree and coins database from disk, initializing state if we're running with -reindex. More...
 
void MaybeRebalanceCaches() EXCLUSIVE_LOCKS_REQUIRED(void UpdateUncommittedBlockStructures (CBlock &block, const CBlockIndex *pindexPrev) const
 Check to see if caches are out of balance and if so, call ResizeCoinsCaches() as needed. More...
 
std::vector< unsigned char > GenerateCoinbaseCommitment (CBlock &block, const CBlockIndex *pindexPrev) const
 Produce the necessary coinbase commitment for a block (modifies the hash, don't call for mined blocks). More...
 
void ReportHeadersPresync (const arith_uint256 &work, int64_t height, int64_t timestamp)
 This is used by net_processing to report pre-synchronization progress of headers, as headers are not yet fed to validation during that time, but validation is (for now) responsible for logging and signalling through NotifyHeaderTip, so it needs this information. More...
 
 ~ChainstateManager ()
 

Public Attributes

std::function< void()> snapshot_download_completed = std::function<void()>()
 Function to restart active indexes; set dynamically to avoid a circular dependency on base/index.cpp. More...
 
const util::SignalInterruptm_interrupt
 
const Options m_options
 
node::BlockManager m_blockman
 A single BlockManager instance is shared across each constructed chainstate to avoid duplicating block metadata. More...
 
ValidationCache m_validation_cache
 
std::atomic< bool > m_cached_finished_ibd {false}
 Whether initial block download has ended and IsInitialBlockDownload should return false from now on. More...
 
int32_t nBlockReverseSequenceId = -1
 Decreasing counter (used by subsequent preciousblock calls). More...
 
arith_uint256 nLastPreciousChainwork = 0
 chainwork for the last block that preciousblock has been applied to. More...
 
std::set< CBlockIndex * > m_failed_blocks
 In order to efficiently track invalidity of headers, we keep the set of blocks which we tried to connect and found to be invalid here (ie which were set to BLOCK_FAILED_VALID since the last restart). More...
 
int64_t m_total_coinstip_cache {0}
 The total number of bytes available for us to use across all in-memory coins caches. More...
 
int64_t m_total_coinsdb_cache {0}
 The total number of bytes available for us to use across all leveldb coins databases. More...
 
Chainstate &InitializeChainstate(CTxMemPool *mempool) EXCLUSIVE_LOCKS_REQUIRED(std::vector< ChainstateGetAll )()
 Instantiate a new chainstate. More...
 
SnapshotCompletionResult MaybeCompleteSnapshotValidation() EXCLUSIVE_LOCKS_REQUIRED(const CBlockIndex *GetSnapshotBaseBlock() const EXCLUSIVE_LOCKS_REQUIRED(Chainstate ActiveChainstate )() const
 Once the background validation chainstate has reached the height which is the base of the UTXO snapshot in use, compare its coins to ensure they match those expected by the snapshot. More...
 
VersionBitsCache m_versionbitscache
 Track versionbit status. More...
 
bool DetectSnapshotChainstate() EXCLUSIVE_LOCKS_REQUIRED(void ResetChainstates() EXCLUSIVE_LOCKS_REQUIRED(bool DeleteSnapshotChainstate() EXCLUSIVE_LOCKS_REQUIRED(Chainstate &ActivateExistingSnapshot(uint256 base_blockhash) EXCLUSIVE_LOCKS_REQUIRED(bool ValidatedSnapshotCleanup() EXCLUSIVE_LOCKS_REQUIRED(Chainstate &GetChainstateForIndexing() EXCLUSIVE_LOCKS_REQUIRED(std::pair< int, int > GetPruneRange(const Chainstate &chainstate, int last_height_can_prune) EXCLUSIVE_LOCKS_REQUIRED(std::optional< int > GetSnapshotBaseHeight() const EXCLUSIVE_LOCKS_REQUIRED(void RecalculateBestHeader() EXCLUSIVE_LOCKS_REQUIRED(CCheckQueue< CScriptCheck > & GetCheckQueue ()
 When starting up, search the datadir for a chainstate based on a UTXO snapshot that is in the process of being validated. More...
 

Private Member Functions

std::unique_ptr< Chainstate > m_ibd_chainstate GUARDED_BY (::cs_main)
 The chainstate used under normal operation (i.e. More...
 
std::unique_ptr< Chainstate > m_snapshot_chainstate GUARDED_BY (::cs_main)
 A chainstate initialized on the basis of a UTXO snapshot. More...
 
Chainstate *m_active_chainstate GUARDED_BY (::cs_main)
 Points to either the ibd or snapshot chainstate; indicates our most-work chain. More...
 
CBlockIndex *m_best_invalid GUARDED_BY (::cs_main)
 
CBlockIndex *m_last_notified_header GUARDED_BY (GetMutex())
 The last header for which a headerTip notification was issued. More...
 
bool NotifyHeaderTip () LOCKS_EXCLUDED(GetMutex())
 
util::Result< void > PopulateAndValidateSnapshot (Chainstate &snapshot_chainstate, AutoFile &coins_file, const node::SnapshotMetadata &metadata)
 Internal helper for ActivateSnapshot(). More...
 
bool AcceptBlockHeader (const CBlockHeader &block, BlockValidationState &state, CBlockIndex **ppindex, bool min_pow_checked) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 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. More...
 
std::chrono::time_point< std::chrono::steady_clock > m_last_presync_update GUARDED_BY (::cs_main)
 Most recent headers presync progress update, for rate-limiting. More...
 
std::array< ThresholdConditionCache, VERSIONBITS_NUM_BITS > m_warningcache GUARDED_BY (::cs_main)
 
bool IsUsable (const Chainstate *const cs) const EXCLUSIVE_LOCKS_REQUIRED(
 Return true if a chainstate is considered usable. More...
 
SteadyClock::duration GUARDED_BY (::cs_main) time_check
 Timers and counters used for benchmarking validation in both background and active chainstates. More...
 
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
 
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
 

Private Attributes

friend Chainstate
 
CCheckQueue< CScriptCheckm_script_check_queue
 A queue for script verifications that have to be performed by worker threads. More...
 

Detailed Description

Provides an interface for creating and interacting with one or two chainstates: an IBD chainstate generated by downloading blocks, and an optional snapshot chainstate loaded from a UTXO snapshot.

Managed chainstates can be maintained at different heights simultaneously.

This class provides abstractions that allow the retrieval of the current most-work chainstate ("Active") as well as chainstates which may be in background use to validate UTXO snapshots.

Definitions:

IBD chainstate: a chainstate whose current state has been "fully" validated by the initial block download process.

Snapshot chainstate: a chainstate populated by loading in an assumeutxo UTXO snapshot.

Active chainstate: the chainstate containing the current most-work chain. Consulted by most parts of the system (net_processing, wallet) as a reflection of the current chain and UTXO set. This may either be an IBD chainstate or a snapshot chainstate.

Background IBD chainstate: an IBD chainstate for which the IBD process is happening in the background while use of the active (snapshot) chainstate allows the rest of the system to function.

Definition at line 868 of file validation.h.

Member Typedef Documentation

◆ Options

Definition at line 971 of file validation.h.

Constructor & Destructor Documentation

◆ ChainstateManager()

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

Definition at line 6296 of file validation.cpp.

◆ ~ChainstateManager()

ChainstateManager::~ChainstateManager ( )

Definition at line 6305 of file validation.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ AcceptBlock()

bool ChainstateManager::AcceptBlock ( const std::shared_ptr< const CBlock > &  pblock,
BlockValidationState state,
CBlockIndex **  ppindex,
bool  fRequested,
const FlatFilePos dbp,
bool *  fNewBlock,
bool  min_pow_checked 
)

Sufficiently validate a block for disk storage (and store on disk).

Store block on disk.

Parameters
[in]pblockThe block we want to process.
[in]fRequestedWhether we requested this block from a peer.
[in]dbpThe location on disk, if we are importing this block from prior storage.
[in]min_pow_checkedTrue if proof-of-work anti-DoS checks have been done by caller for headers chain
[out]stateThe state of the block validation.
[out]ppindexOptional return parameter to get the CBlockIndex pointer for this block.
[out]fNewBlockOptional return parameter to indicate if the block is new to our storage.
Returns
False if the block or header is invalid, or if saving to disk fails (likely a fatal error); true otherwise.

If dbp is non-nullptr, the file is known to already reside on disk

Definition at line 4486 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ AcceptBlockHeader()

bool ChainstateManager::AcceptBlockHeader ( const CBlockHeader block,
BlockValidationState state,
CBlockIndex **  ppindex,
bool  min_pow_checked 
)
private

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).

Definition at line 4319 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ActivateSnapshot()

util::Result< CBlockIndex * > ChainstateManager::ActivateSnapshot ( AutoFile coins_file,
const node::SnapshotMetadata metadata,
bool  in_memory 
)

Construct and activate a Chainstate on the basis of UTXO snapshot data.

Steps:

  • Initialize an unused Chainstate.
  • Load its CoinsViews contents from coins_file.
  • Verify that the hash of the resulting coinsdb matches the expected hash per assumeutxo chain parameters.
  • Wait for our headers chain to include the base block of the snapshot.
  • "Fast forward" the tip of the new chainstate to the base of the snapshot.
  • Move the new chainstate to m_snapshot_chainstate and make it our ChainstateActive().

Definition at line 5703 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ActiveChain()

CChain & ChainstateManager::ActiveChain ( ) const
inline

Definition at line 1114 of file validation.h.

Here is the caller graph for this function:

◆ ActiveHeight()

int ChainstateManager::ActiveHeight ( ) const
inline

Definition at line 1115 of file validation.h.

Here is the caller graph for this function:

◆ ActiveTip()

CBlockIndex * ChainstateManager::ActiveTip ( ) const
inline

Definition at line 1116 of file validation.h.

Here is the caller graph for this function:

◆ AssumedValidBlock()

const uint256 & ChainstateManager::AssumedValidBlock ( ) const
inline

Definition at line 983 of file validation.h.

Here is the caller graph for this function:

◆ BackgroundSyncInProgress()

bool ChainstateManager::BackgroundSyncInProgress ( ) const
inline

The state of a background sync (for net processing)

Definition at line 1119 of file validation.h.

Here is the caller graph for this function:

◆ BlockIndex()

node::BlockMap & ChainstateManager::BlockIndex ( )
inline

Definition at line 1128 of file validation.h.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ CheckBlockIndex()

void ChainstateManager::CheckBlockIndex ( )

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.

Definition at line 5254 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GenerateCoinbaseCommitment()

std::vector< unsigned char > ChainstateManager::GenerateCoinbaseCommitment ( CBlock block,
const CBlockIndex pindexPrev 
) const

Produce the necessary coinbase commitment for a block (modifies the hash, don't call for mined blocks).

Definition at line 4118 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GetBackgroundSyncTip()

const CBlockIndex * ChainstateManager::GetBackgroundSyncTip ( ) const
inline

The tip of the background sync chain.

Definition at line 1124 of file validation.h.

◆ GetConsensus()

const Consensus::Params & ChainstateManager::GetConsensus ( ) const
inline

Definition at line 980 of file validation.h.

Here is the caller graph for this function:

◆ GetMutex()

RecursiveMutex & ChainstateManager::GetMutex ( ) const
inline

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.

Definition at line 1004 of file validation.h.

Here is the caller graph for this function:

◆ GetNotifications()

kernel::Notifications & ChainstateManager::GetNotifications ( ) const
inline

Definition at line 984 of file validation.h.

Here is the caller graph for this function:

◆ GetParams()

const CChainParams & ChainstateManager::GetParams ( ) const
inline

Definition at line 979 of file validation.h.

Here is the caller graph for this function:

◆ GUARDED_BY() [1/21]

std::unique_ptr< Chainstate > m_ibd_chainstate ChainstateManager::GUARDED_BY ( ::cs_main  )
private

The chainstate used under normal operation (i.e.

"regular" IBD) or, if a snapshot is in use, for background validation.

Its contents (including on-disk data) will be deleted upon shutdown after background validation of the snapshot has completed. We do not free the chainstate contents immediately after it finishes validation to cautiously avoid a case where some other part of the system is still using this pointer (e.g. net_processing).

Once this pointer is set to a corresponding chainstate, it will not be reset until init.cpp:Shutdown().

It is important for the pointer to not be deleted until shutdown, because cs_main is not always held when the pointer is accessed, for example when calling ActivateBestChain, so there's no way you could prevent code from using the pointer while deleting it.

◆ GUARDED_BY() [2/21]

std::unique_ptr< Chainstate > m_snapshot_chainstate ChainstateManager::GUARDED_BY ( ::cs_main  )
private

A chainstate initialized on the basis of a UTXO snapshot.

If this is non-null, it is always our active chainstate.

Once this pointer is set to a corresponding chainstate, it will not be reset until init.cpp:Shutdown().

It is important for the pointer to not be deleted until shutdown, because cs_main is not always held when the pointer is accessed, for example when calling ActivateBestChain, so there's no way you could prevent code from using the pointer while deleting it.

◆ GUARDED_BY() [3/21]

Chainstate *m_active_chainstate ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Points to either the ibd or snapshot chainstate; indicates our most-work chain.

Definition at line 903 of file validation.h.

◆ GUARDED_BY() [4/21]

CBlockIndex *m_best_invalid ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 905 of file validation.h.

◆ GUARDED_BY() [5/21]

std::chrono::time_point< std::chrono::steady_clock > m_last_presync_update ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

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

Definition at line 939 of file validation.h.

◆ GUARDED_BY() [6/21]

std::array< ThresholdConditionCache, VERSIONBITS_NUM_BITS > m_warningcache ChainstateManager::GUARDED_BY ( ::cs_main  )
private

◆ GUARDED_BY() [7/21]

int32_t nBlockSequenceId ChainstateManager::GUARDED_BY ( ::cs_main  )

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 0, so start the counter at 1.

◆ GUARDED_BY() [8/21]

CBlockIndex *m_best_header ChainstateManager::GUARDED_BY ( ::cs_main  )
inline

Best header we've seen so far (used for getheaders queries' starting points).

Definition at line 1066 of file validation.h.

◆ GUARDED_BY() [9/21]

int64_t ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 964 of file validation.h.

◆ GUARDED_BY() [10/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 967 of file validation.h.

◆ GUARDED_BY() [11/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Timers and counters used for benchmarking validation in both background and active chainstates.

Definition at line 957 of file validation.h.

◆ GUARDED_BY() [12/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 959 of file validation.h.

◆ GUARDED_BY() [13/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 965 of file validation.h.

◆ GUARDED_BY() [14/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 966 of file validation.h.

◆ GUARDED_BY() [15/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 958 of file validation.h.

◆ GUARDED_BY() [16/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 962 of file validation.h.

◆ GUARDED_BY() [17/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 968 of file validation.h.

◆ GUARDED_BY() [18/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 963 of file validation.h.

◆ GUARDED_BY() [19/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 961 of file validation.h.

◆ GUARDED_BY() [20/21]

SteadyClock::duration ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

Definition at line 960 of file validation.h.

◆ GUARDED_BY() [21/21]

CBlockIndex *m_last_notified_header ChainstateManager::GUARDED_BY ( GetMutex()  )
inlineprivate

The last header for which a headerTip notification was issued.

Definition at line 908 of file validation.h.

◆ IsInitialBlockDownload()

bool ChainstateManager::IsInitialBlockDownload ( ) const

Check whether we are doing an initial block download (synchronizing from disk or network)

Definition at line 2014 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ IsSnapshotActive()

bool ChainstateManager::IsSnapshotActive ( ) const
Returns
true if a snapshot-based chainstate is in use. Also implies that a background validation chainstate is also in use.

Definition at line 6234 of file validation.cpp.

Here is the caller graph for this function:

◆ IsSnapshotValidated()

bool ChainstateManager::IsSnapshotValidated ( ) const
inline

Is there a snapshot in use and has it been fully validated?

Definition at line 1146 of file validation.h.

Here is the caller graph for this function:

◆ IsUsable()

bool ChainstateManager::IsUsable ( const Chainstate *const  cs) const
inlineprivate

Return true if a chainstate is considered usable.

This is false when a background validation chainstate has completed its validation of an assumed-valid chainstate, or when a snapshot chainstate has been found to be invalid.

Definition at line 948 of file validation.h.

◆ LoadBlockIndex()

bool ChainstateManager::LoadBlockIndex ( )

Load the block tree and coins database from disk, initializing state if we're running with -reindex.

Definition at line 4999 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ LoadExternalBlockFile()

void ChainstateManager::LoadExternalBlockFile ( AutoFile file_in,
FlatFilePos dbp = nullptr,
std::multimap< uint256, FlatFilePos > *  blocks_with_unknown_parent = nullptr 
)

Import blocks from an external file.

During reindexing, this function is called for each block file (datadir/blocks/blk?????.dat). It reads all blocks contained in the given file and attempts to process them (add them to the block index). The blocks may be out of order within each file and across files. Often this function reads a block but finds that its parent hasn't been read yet, so the block can't be processed yet. The function will add an entry to the blocks_with_unknown_parent map (which is passed as an argument), so that when the block's parent is later read and processed, this function can re-read the child block from disk and process it.

Because a block's parent may be in a later file, not just later in the same file, the blocks_with_unknown_parent map must be passed in and out with each call. It's a multimap, rather than just a map, because multiple blocks may have the same parent (when chain splits or stale blocks exist). It maps from parent-hash to child-disk-position.

This function can also be used to read blocks from user-specified block files using the -loadblock= option. There's no unknown-parent tracking, so the last two arguments are omitted.

Parameters
[in]file_inFile containing blocks to read
[in]dbp(optional) Disk block position (only for reindex)
[in,out]blocks_with_unknown_parent(optional) Map of disk positions for blocks with unknown parent, key is parent block hash (only used for reindex)

Definition at line 5068 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ MinimumChainWork()

const arith_uint256 & ChainstateManager::MinimumChainWork ( ) const
inline

Definition at line 982 of file validation.h.

Here is the caller graph for this function:

◆ NotifyHeaderTip()

bool ChainstateManager::NotifyHeaderTip ( )
private

Definition at line 3441 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ PopulateAndValidateSnapshot()

util::Result< void > ChainstateManager::PopulateAndValidateSnapshot ( Chainstate snapshot_chainstate,
AutoFile coins_file,
const node::SnapshotMetadata metadata 
)
private

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.

Definition at line 5879 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ProcessNewBlock()

bool ChainstateManager::ProcessNewBlock ( const std::shared_ptr< const CBlock > &  block,
bool  force_processing,
bool  min_pow_checked,
bool *  new_block 
)

Process an incoming block.

This only returns after the best known valid block is made active. Note that it does not, however, guarantee that the specific block passed to it has been checked for validity!

If you want to possibly get feedback on whether block is valid, you must install a CValidationInterface (see validationinterface.h) - this will have its BlockChecked method called whenever any block completes validation.

Note that we guarantee that either the proof-of-work is valid on block, or (and possibly also) BlockChecked will have been called.

May not be called in a validationinterface callback.

Parameters
[in]blockThe block we want to process.
[in]force_processingProcess this block even if unrequested; used for non-network block sources.
[in]min_pow_checkedTrue if proof-of-work anti-DoS checks have been done by caller for headers chain (note: only affects headers acceptance; if block header is already present in block index then this parameter has no effect)
[out]new_blockA boolean which is set to indicate if the block was first received via this call
Returns
If the block was processed, independently of block validity

Definition at line 4587 of file validation.cpp.

Here is the call graph for this function:

◆ ProcessNewBlockHeaders()

bool ChainstateManager::ProcessNewBlockHeaders ( std::span< const CBlockHeader headers,
bool  min_pow_checked,
BlockValidationState state,
const CBlockIndex **  ppindex = nullptr 
)

Process incoming block headers.

May not be called in a validationinterface callback.

Parameters
[in]headersThe block headers themselves
[in]min_pow_checkedTrue if proof-of-work anti-DoS checks have been done by caller for headers chain
[out]stateThis may be set to an Error state if any error occurred processing them
[out]ppindexIf set, the pointer will be set to point to the last new block index object for the given headers

Definition at line 4430 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ProcessTransaction()

MempoolAcceptResult ChainstateManager::ProcessTransaction ( const CTransactionRef tx,
bool  test_accept = false 
)

Try to add a transaction to the memory pool.

Parameters
[in]txThe transaction to submit for mempool acceptance.
[in]test_acceptWhen true, run validation checks but don't submit to mempool.

Definition at line 4637 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ReceivedBlockTransactions()

void ChainstateManager::ReceivedBlockTransactions ( const CBlock block,
CBlockIndex pindexNew,
const FlatFilePos pos 
)

Mark a block as having its data received and checked (up to BLOCK_VALID_TRANSACTIONS).

Definition at line 3888 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ReportHeadersPresync()

void ChainstateManager::ReportHeadersPresync ( const arith_uint256 work,
int64_t  height,
int64_t  timestamp 
)

This is used by net_processing to report pre-synchronization progress of headers, as headers are not yet fed to validation during that time, but validation is (for now) responsible for logging and signalling through NotifyHeaderTip, so it needs this information.

Definition at line 4460 of file validation.cpp.

Here is the call graph for this function:

◆ ResetBlockSequenceCounters()

void ChainstateManager::ResetBlockSequenceCounters ( )
inline

Definition at line 1036 of file validation.h.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ShouldCheckBlockIndex()

bool ChainstateManager::ShouldCheckBlockIndex ( ) const

Definition at line 5246 of file validation.cpp.

Here is the caller graph for this function:

◆ SnapshotBlockhash()

std::optional< uint256 > ChainstateManager::SnapshotBlockhash ( ) const

Definition at line 5630 of file validation.cpp.

Here is the caller graph for this function:

◆ UpdateUncommittedBlockStructures()

void ChainstateManager::UpdateUncommittedBlockStructures ( CBlock block,
const CBlockIndex pindexPrev 
) const

Check to see if caches are out of balance and if so, call ResizeCoinsCaches() as needed.

Update uncommitted block structures (currently: only the witness reserved value). This is safe for submitted blocks.

Definition at line 4106 of file validation.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

Member Data Documentation

◆ ActiveChainstate

Chainstate & ChainstateManager::ActiveChainstate

Once the background validation chainstate has reached the height which is the base of the UTXO snapshot in use, compare its coins to ensure they match those expected by the snapshot.

If the coins match (expected), then mark the validation chainstate for deletion and continue using the snapshot chainstate as active. Otherwise, revert to using the ibd chainstate and shutdown. Returns nullptr if no snapshot has been loaded. The most-work chain.

Definition at line 1113 of file validation.h.

◆ Chainstate

friend ChainstateManager::Chainstate
private

Definition at line 936 of file validation.h.

◆ GetAll

std::vector< Chainstate * > ChainstateManager::GetAll

Instantiate a new chainstate.

Parameters
[in]mempoolThe mempool to pass to the chainstate Get all chainstates currently being used.

Definition at line 1083 of file validation.h.

◆ GetCheckQueue

bool DetectSnapshotChainstate() EXCLUSIVE_LOCKS_REQUIRED(void ResetChainstates() EXCLUSIVE_LOCKS_REQUIRED(bool DeleteSnapshotChainstate() EXCLUSIVE_LOCKS_REQUIRED(Chainstate &ActivateExistingSnapshot(uint256 base_blockhash) EXCLUSIVE_LOCKS_REQUIRED(bool ValidatedSnapshotCleanup() EXCLUSIVE_LOCKS_REQUIRED(Chainstate &GetChainstateForIndexing() EXCLUSIVE_LOCKS_REQUIRED(std::pair< int, int > GetPruneRange(const Chainstate &chainstate, int last_height_can_prune) EXCLUSIVE_LOCKS_REQUIRED(std::optional< int > GetSnapshotBaseHeight() const EXCLUSIVE_LOCKS_REQUIRED(void RecalculateBestHeader() EXCLUSIVE_LOCKS_REQUIRED(CCheckQueue< CScriptCheck > & ChainstateManager::GetCheckQueue()
inline

When starting up, search the datadir for a chainstate based on a UTXO snapshot that is in the process of being validated.

Remove the snapshot-based chainstate and all on-disk artifacts. Used when reindex{-chainstate} is called during snapshot use. Switch the active chainstate to one based on a UTXO snapshot that was loaded previously. If we have validated a snapshot chain during this runtime, copy its chainstate directory over to the main chainstate location, completing validation of the snapshot.

If the cleanup succeeds, the caller will need to ensure chainstates are reinitialized, since ResetChainstates() will be called before leveldb directories are moved or deleted.

See also
node/chainstate:LoadChainstate()
Returns
the chainstate that indexes should consult when ensuring that an index is synced with a chain where we can expect block index entries to have BLOCK_HAVE_DATA beneath the tip.

In other words, give us the chainstate for which we can reasonably expect that all blocks beneath the tip have been indexed. In practice this means when using an assumed-valid chainstate based upon a snapshot, return only the fully validated chain. Return the [start, end] (inclusive) of block heights we can prune.

start > end is possible, meaning no blocks can be pruned. Return the height of the base block of the snapshot in use, if one exists, else nullopt. If, due to invalidation / reconsideration of blocks, the previous best header is no longer valid / guaranteed to be the most-work header in our block-index not known to be invalid, recalculate it.

Definition at line 1325 of file validation.h.

◆ m_blockman

node::BlockManager ChainstateManager::m_blockman

A single BlockManager instance is shared across each constructed chainstate to avoid duplicating block metadata.

Definition at line 1010 of file validation.h.

◆ m_cached_finished_ibd

std::atomic<bool> ChainstateManager::m_cached_finished_ibd {false}
mutable

Whether initial block download has ended and IsInitialBlockDownload should return false from now on.

Mutable because we need to be able to mark IsInitialBlockDownload() const, which latches this for caching purposes.

Definition at line 1021 of file validation.h.

◆ m_failed_blocks

std::set<CBlockIndex*> ChainstateManager::m_failed_blocks

In order to efficiently track invalidity of headers, we keep the set of blocks which we tried to connect and found to be invalid here (ie which were set to BLOCK_FAILED_VALID since the last restart).

We can then walk this set and check if a new header is a descendant of something in this set, preventing us from having to walk m_block_index when we try to connect a bad block and fail.

While this is more complicated than marking everything which descends from an invalid block as invalid at the time we discover it to be invalid, doing so would require walking all of m_block_index to find all descendants. Since this case should be very rare, keeping track of all BLOCK_FAILED_VALID blocks in a set should be just fine and work just as well.

Because we already walk m_block_index in height-order at startup, we go ahead and mark descendants of invalid blocks as FAILED_CHILD at that time, instead of putting things in this set.

Definition at line 1063 of file validation.h.

◆ m_interrupt

const util::SignalInterrupt& ChainstateManager::m_interrupt

Definition at line 1006 of file validation.h.

◆ m_options

const Options ChainstateManager::m_options

Definition at line 1007 of file validation.h.

◆ m_script_check_queue

CCheckQueue<CScriptCheck> ChainstateManager::m_script_check_queue
private

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

Definition at line 953 of file validation.h.

◆ m_total_coinsdb_cache

int64_t ChainstateManager::m_total_coinsdb_cache {0}

The total number of bytes available for us to use across all leveldb coins databases.

This will be split somehow across chainstates.

Definition at line 1074 of file validation.h.

◆ m_total_coinstip_cache

int64_t ChainstateManager::m_total_coinstip_cache {0}

The total number of bytes available for us to use across all in-memory coins caches.

This will be split somehow across chainstates.

Definition at line 1070 of file validation.h.

◆ m_validation_cache

ValidationCache ChainstateManager::m_validation_cache

Definition at line 1012 of file validation.h.

◆ m_versionbitscache

VersionBitsCache ChainstateManager::m_versionbitscache
mutable

Track versionbit status.

Definition at line 1137 of file validation.h.

◆ nBlockReverseSequenceId

int32_t ChainstateManager::nBlockReverseSequenceId = -1

Decreasing counter (used by subsequent preciousblock calls).

Definition at line 1030 of file validation.h.

◆ nLastPreciousChainwork

arith_uint256 ChainstateManager::nLastPreciousChainwork = 0

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

Definition at line 1032 of file validation.h.

◆ snapshot_download_completed

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

Function to restart active indexes; set dynamically to avoid a circular dependency on base/index.cpp.

Definition at line 977 of file validation.h.


The documentation for this class was generated from the following files: