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>

Collaboration diagram for ChainstateManager:

[legend]

Public Member Functions
BlockManager m_blockman	GUARDED_BY (::cs_main)
	A single BlockManager instance is shared across each constructed chainstate to avoid duplicating block metadata. More...

bool	ActivateSnapshot (CAutoFile &coins_file, const SnapshotMetadata &metadata, bool in_memory)
	Construct and activate a Chainstate on the basis of UTXO snapshot data. More...

CChainState &	ActiveChainstate () const
	The most-work chain. More...

CChain &	ActiveChain () const

int	ActiveHeight () const

CBlockIndex *	ActiveTip () const

BlockMap &	BlockIndex () EXCLUSIVE_LOCKS_REQUIRED(

bool	IsSnapshotActive () const

std::optional< uint256 >	SnapshotBlockhash () const

bool	IsSnapshotValidated () const
	Is there a snapshot in use and has it been fully validated? More...

bool	IsBackgroundIBD (CChainState *chainstate) const

CChainState &	ValidatedChainstate () const
	Return the most-work chainstate that has been fully validated. More...

CChain &	ValidatedChain () const

CBlockIndex *	ValidatedTip () const

bool	ProcessNewBlock (const CChainParams &chainparams, const std::shared_ptr< const CBlock > &block, bool force_processing, bool *new_block) LOCKS_EXCLUDED(cs_main)
	Process an incoming block. More...

bool	ProcessNewBlockHeaders (const std::vector< CBlockHeader > &block, BlockValidationState &state, const CChainParams &chainparams, const CBlockIndex **ppindex=nullptr) LOCKS_EXCLUDED(cs_main)
	Process incoming block headers. 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(	~ChainstateManager ()
	Check to see if caches are out of balance and if so, call ResizeCoinsCaches() as needed. More...

Public Attributes
std::thread	m_load_block

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

CChainState &InitializeChainstate(CTxMemPool mempool, const std::optional< uint256 > &snapshot_blockhash=std::nullopt) EXCLUSIVE_LOCKS_REQUIRED(std::vector< CChainState	GetAll )()
	Instantiate a new chainstate and assign it based upon whether it is from a snapshot. More...

Private Member Functions
std::unique_ptr< CChainState > m_ibd_chainstate	GUARDED_BY (::cs_main)
	The chainstate used under normal operation (i.e. More...

std::unique_ptr< CChainState > m_snapshot_chainstate	GUARDED_BY (::cs_main)
	A chainstate initialized on the basis of a UTXO snapshot. More...

CChainState *m_active_chainstate	GUARDED_BY (::cs_main)
	Points to either the ibd or snapshot chainstate; indicates our most-work chain. More...

bool	PopulateAndValidateSnapshot (CChainState &snapshot_chainstate, CAutoFile &coins_file, const SnapshotMetadata &metadata)
	Internal helper for ActivateSnapshot(). More...

Private Attributes
bool	m_snapshot_validated {false}
	If true, the assumed-valid chainstate has been fully validated by the background validation chainstate. 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.

Validated chainstate: the most-work chainstate which has been validated locally via initial block download. This will be the snapshot chainstate if a snapshot was loaded and all blocks up to the snapshot starting point have been downloaded and validated (via background validation), otherwise it will be the IBD chainstate.

Definition at line 855 of file validation.h.

Constructor & Destructor Documentation

◆ ~ChainstateManager()

void MaybeRebalanceCaches () EXCLUSIVE_LOCKS_REQUIRED( ChainstateManager::~ChainstateManager ( )

inline

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

Definition at line 1032 of file validation.h.

Here is the call graph for this function:

Member Function Documentation

◆ ActivateSnapshot()

bool ChainstateManager::ActivateSnapshot	(	CAutoFile &	coins_file,
		const SnapshotMetadata &	metadata,
		bool	in_memory
	)

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

Steps:

Initialize an unused CChainState.
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, faking nTx* block index data along the way.
Move the new chainstate to m_snapshot_chainstate and make it our ChainstateActive().

Definition at line 4701 of file validation.cpp.

Here is the call graph for this function:

◆ ActiveChain()

CChain& ChainstateManager::ActiveChain ( ) const

inline

Definition at line 954 of file validation.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ActiveChainstate()

CChainState & ChainstateManager::ActiveChainstate ( ) const

The most-work chain.

Definition at line 4965 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ActiveHeight()

int ChainstateManager::ActiveHeight ( ) const

inline

Definition at line 955 of file validation.h.

Here is the call graph for this function:

◆ ActiveTip()

CBlockIndex* ChainstateManager::ActiveTip ( ) const

inline

Definition at line 956 of file validation.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ BlockIndex()

BlockMap& ChainstateManager::BlockIndex ( )

inline

Definition at line 958 of file validation.h.

Here is the caller graph for this function:

◆ GUARDED_BY() [1/4]

std::unique_ptr<CChainState> 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().

This is especially important when, e.g., calling ActivateBestChain() on all chainstates because we are not able to hold cs_main going into that call.

◆ GUARDED_BY() [2/4]

std::unique_ptr<CChainState> 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().

This is especially important when, e.g., calling ActivateBestChain() on all chainstates because we are not able to hold cs_main going into that call.

◆ GUARDED_BY() [3/4]

CChainState* m_active_chainstate ChainstateManager::GUARDED_BY ( ::cs_main )

inlineprivate

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

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

This is especially important when, e.g., calling ActivateBestChain() on all chainstates because we are not able to hold cs_main going into that call.

Definition at line 895 of file validation.h.

◆ GUARDED_BY() [4/4]

BlockManager m_blockman ChainstateManager::GUARDED_BY ( ::cs_main )

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

◆ IsBackgroundIBD()

bool ChainstateManager::IsBackgroundIBD ( CChainState * chainstate ) const

Returns: true if this chainstate is being used to validate an active snapshot in the background.

Definition at line 4988 of file validation.cpp.

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 4972 of file validation.cpp.

◆ IsSnapshotValidated()

bool ChainstateManager::IsSnapshotValidated ( ) const

inline

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

Definition at line 970 of file validation.h.

Here is the caller graph for this function:

◆ LoadBlockIndex()

bool ChainstateManager::LoadBlockIndex ( )

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

Definition at line 4085 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ PopulateAndValidateSnapshot()

bool ChainstateManager::PopulateAndValidateSnapshot	(	CChainState &	snapshot_chainstate,
		CAutoFile &	coins_file,
		const SnapshotMetadata &	metadata
	)

private

Internal helper for ActivateSnapshot().

Definition at line 4783 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 CChainParams &	chainparams,
		const std::shared_ptr< const CBlock > &	block,
		bool	force_processing,
		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]	block	The block we want to process.
[in]	force_processing	Process this block even if unrequested; used for non-network block sources.
[out]	new_block	A 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 3454 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ProcessNewBlockHeaders()

bool ChainstateManager::ProcessNewBlockHeaders	(	const std::vector< CBlockHeader > &	block,
		BlockValidationState &	state,
		const CChainParams &	chainparams,
		const CBlockIndex **	ppindex = `nullptr`
	)

Process incoming block headers.

May not be called in a validationinterface callback.

Parameters

[in]	block	The block headers themselves
[out]	state	This may be set to an Error state if any error occurred processing them
[in]	chainparams	The params for the chain we want to connect to
[out]	ppindex	If set, the pointer will be set to point to the last new block index object for the given headers

Definition at line 3344 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SnapshotBlockhash()

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

Definition at line 4640 of file validation.cpp.

Here is the caller graph for this function:

◆ ValidatedChain()

CChain& ChainstateManager::ValidatedChain ( ) const

inline

Definition at line 982 of file validation.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ValidatedChainstate()

CChainState & ChainstateManager::ValidatedChainstate ( ) const

Return the most-work chainstate that has been fully validated.

During background validation of a snapshot, this is the IBD chain. After background validation has completed, this is the snapshot chain.

Definition at line 4978 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ValidatedTip()

CBlockIndex* ChainstateManager::ValidatedTip ( ) const

inline

Definition at line 983 of file validation.h.

Here is the call graph for this function:

Member Data Documentation

◆ GetAll

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

Instantiate a new chainstate and assign it based upon whether it is from a snapshot.

Parameters

[in]	mempool	The mempool to pass to the chainstate
[in]	snapshot_blockhash	If given, signify that this chainstate is based on a snapshot. Get all chainstates currently being used.

Definition at line 934 of file validation.h.

◆ m_load_block

std::thread ChainstateManager::m_load_block

Definition at line 908 of file validation.h.

◆ m_snapshot_validated

bool ChainstateManager::m_snapshot_validated {false}

private

If true, the assumed-valid chainstate has been fully validated by the background validation chainstate.

Definition at line 899 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 919 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 915 of file validation.h.

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

src/validation.h
src/validation.cpp

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~ChainstateManager()

Member Function Documentation

◆ ActivateSnapshot()

◆ ActiveChain()

◆ ActiveChainstate()

◆ ActiveHeight()

◆ ActiveTip()

◆ BlockIndex()

◆ GUARDED_BY() [1/4]

◆ GUARDED_BY() [2/4]

◆ GUARDED_BY() [3/4]

◆ GUARDED_BY() [4/4]

◆ IsBackgroundIBD()

◆ IsSnapshotActive()

◆ IsSnapshotValidated()

◆ LoadBlockIndex()

◆ PopulateAndValidateSnapshot()

◆ ProcessNewBlock()

◆ ProcessNewBlockHeaders()

◆ SnapshotBlockhash()

◆ ValidatedChain()

◆ ValidatedChainstate()

◆ ValidatedTip()

Member Data Documentation

◆ GetAll

◆ m_load_block

◆ m_snapshot_validated

◆ m_total_coinsdb_cache

◆ m_total_coinstip_cache