Bitcoin Core  0.20.99
P2P Digital Currency
Public Member Functions | Public Attributes | Private Attributes | Friends | 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>

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...
 
CChainActiveChain () const
 The most-work chain. More...
 
int ActiveHeight () const
 
CBlockIndexActiveTip () const
 
BlockMapBlockIndex () EXCLUSIVE_LOCKS_REQUIRED(
 
bool IsSnapshotActive () const
 
Optional< uint256SnapshotBlockhash () const
 
bool IsSnapshotValidated () const
 Is there a snapshot in use and has it been fully validated? More...
 
bool IsBackgroundIBD (CChainState *chainstate) const
 
CChainStateValidatedChainstate () const
 Return the most-work chainstate that has been fully validated. More...
 
CChainValidatedChain () const
 
CBlockIndexValidatedTip () const
 
bool ProcessNewBlock (const CChainParams &chainparams, const std::shared_ptr< const CBlock > pblock, bool fForceProcessing, bool *fNewBlock) 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...
 
void PruneOneBlockFile (const int fileNumber) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Mark one block file as pruned (modify associated database entries) More...
 
bool LoadBlockIndex (const CChainParams &chainparams) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Load the block tree and coins database from disk, initializing state if we're running with -reindex. More...
 

Public Attributes

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

Private Attributes

std::unique_ptr< CChainStatem_ibd_chainstate
 The chainstate used under normal operation (i.e. More...
 
std::unique_ptr< CChainStatem_snapshot_chainstate
 A chainstate initialized on the basis of a UTXO snapshot. More...
 
CChainStatem_active_chainstate {nullptr}
 Points to either the ibd or snapshot chainstate; indicates our most-work chain. More...
 
bool m_snapshot_validated {false}
 If true, the assumed-valid chainstate has been fully validated by the background validation chainstate. More...
 

Friends

CChainStateChainstateActive ()
 
CChainChainActive ()
 

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 726 of file validation.h.

Member Function Documentation

◆ ActiveChain()

CChain & ChainstateManager::ActiveChain ( ) const

The most-work chain.

Definition at line 5225 of file validation.cpp.

◆ ActiveHeight()

int ChainstateManager::ActiveHeight ( ) const
inline

Definition at line 800 of file validation.h.

◆ ActiveTip()

CBlockIndex* ChainstateManager::ActiveTip ( ) const
inline

Definition at line 801 of file validation.h.

◆ BlockIndex()

BlockMap& ChainstateManager::BlockIndex ( )
inline

Definition at line 803 of file validation.h.

Here is the caller graph for this function:

◆ GUARDED_BY()

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

Here is the call graph for this function:

◆ IsSnapshotActive()

bool ChainstateManager::IsSnapshotActive ( ) const

Definition at line 5231 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 813 of file validation.h.

◆ LoadBlockIndex()

bool ChainstateManager::LoadBlockIndex ( const CChainParams chainparams)

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

Definition at line 4603 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 pblock,
bool  fForceProcessing,
bool *  fNewBlock 
)

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 pblock 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 pblock, or (and possibly also) BlockChecked will have been called.

May not be called in a validationinterface callback.

Parameters
[in]pblockThe block we want to process.
[in]fForceProcessingProcess this block even if unrequested; used for non-network block sources and whitelisted peers.
[out]fNewBlockA 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 3823 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]blockThe block headers themselves
[out]stateThis may be set to an Error state if any error occurred processing them
[in]chainparamsThe params for the chain we want to connect to
[out]ppindexIf set, the pointer will be set to point to the last new block index object for the given headers

Definition at line 3694 of file validation.cpp.

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

◆ PruneOneBlockFile()

void ChainstateManager::PruneOneBlockFile ( const int  fileNumber)

Mark one block file as pruned (modify associated database entries)

Definition at line 3899 of file validation.cpp.

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

◆ SnapshotBlockhash()

Optional< uint256 > ChainstateManager::SnapshotBlockhash ( ) const

Definition at line 5179 of file validation.cpp.

Here is the call graph for this function:

◆ ValidatedChain()

CChain& ChainstateManager::ValidatedChain ( ) const
inline

Definition at line 825 of file validation.h.

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

◆ ValidatedTip()

CBlockIndex* ChainstateManager::ValidatedTip ( ) const
inline

Definition at line 826 of file validation.h.

Here is the call graph for this function:

Friends And Related Function Documentation

◆ ChainActive

CChain& ChainActive ( )
friend
Returns
the most-work chain.

Definition at line 108 of file validation.cpp.

◆ ChainstateActive

CChainState& ChainstateActive ( )
friend
Returns
the most-work valid chainstate.

Definition at line 101 of file validation.cpp.

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]snapshot_blockhashIf given, signify that this chainstate is based on a snapshot. Get all chainstates currently being used.

Definition at line 796 of file validation.h.

◆ m_active_chainstate

CChainState* ChainstateManager::m_active_chainstate {nullptr}
private

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 means it is safe to acquire the contents of this pointer with cs_main held, release the lock, and then use the reference without concern of it being deconstructed.

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 772 of file validation.h.

◆ m_ibd_chainstate

std::unique_ptr<CChainState> ChainstateManager::m_ibd_chainstate
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 means it is safe to acquire the contents of this pointer with cs_main held, release the lock, and then use the reference without concern of it being deconstructed.

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 746 of file validation.h.

◆ m_snapshot_chainstate

std::unique_ptr<CChainState> ChainstateManager::m_snapshot_chainstate
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 means it is safe to acquire the contents of this pointer with cs_main held, release the lock, and then use the reference without concern of it being deconstructed.

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 759 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 776 of file validation.h.


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