Bitcoin Core  23.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>

Collaboration diagram for ChainstateManager:
[legend]

Public Types

using Options = kernel::ChainstateManagerOpts
 

Public Member Functions

 ChainstateManager (const Options &opts)
 
const CChainParamsGetParams () const
 
const Consensus::ParamsGetConsensus () const
 
bool ActivateSnapshot (AutoFile &coins_file, const node::SnapshotMetadata &metadata, bool in_memory)
 Construct and activate a Chainstate on the basis of UTXO snapshot data. More...
 
CChainStateActiveChainstate () const
 The most-work chain. More...
 
CChainActiveChain () const
 
int ActiveHeight () const
 
CBlockIndexActiveTip () const
 
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 ProcessNewBlock (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 CBlockIndex **ppindex=nullptr) LOCKS_EXCLUDED(cs_main)
 Process incoming block headers. 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...
 
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...
 
 ~ChainstateManager ()
 

Public Attributes

std::thread m_load_block
 
node::BlockManager m_blockman
 A single BlockManager instance is shared across each constructed chainstate to avoid duplicating block metadata. 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...
 
CBlockIndexm_best_header = nullptr
 Best header we've seen so far (used for getheaders queries' starting points). 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...
 
CChainState &InitializeChainstate(CTxMemPool *mempool, const std::optional< uint256 > &snapshot_blockhash=std::nullopt) LIFETIMEBOUND EXCLUSIVE_LOCKS_REQUIRED(std::vector< CChainStateGetAll )()
 Instantiate a new chainstate and assign it based upon whether it is from a snapshot. More...
 
VersionBitsCache m_versionbitscache
 Track versionbit status. 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 m_snapshot_validated GUARDED_BY (::cs_main)
 If true, the assumed-valid chainstate has been fully validated by the background validation chainstate. More...
 
CBlockIndex *m_best_invalid GUARDED_BY (::cs_main)
 
bool PopulateAndValidateSnapshot (CChainState &snapshot_chainstate, AutoFile &coins_file, const node::SnapshotMetadata &metadata)
 Internal helper for ActivateSnapshot(). More...
 
bool AcceptBlockHeader (const CBlockHeader &block, BlockValidationState &state, CBlockIndex **ppindex) 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...
 

Private Attributes

const CChainParams m_chainparams
 
const std::function< int64_t()> m_adjusted_time_callback
 
friend CChainState
 

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

Member Typedef Documentation

◆ Options

Definition at line 862 of file validation.h.

Constructor & Destructor Documentation

◆ ChainstateManager()

ChainstateManager::ChainstateManager ( const Options opts)
inlineexplicit

Definition at line 864 of file validation.h.

◆ ~ChainstateManager()

ChainstateManager::~ChainstateManager ( )

Definition at line 5072 of file validation.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ AcceptBlockHeader()

bool ChainstateManager::AcceptBlockHeader ( const CBlockHeader block,
BlockValidationState state,
CBlockIndex **  ppindex 
)
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.

Definition at line 3575 of file validation.cpp.

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

◆ ActivateSnapshot()

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

Here is the call graph for this function:

◆ ActiveChain()

CChain& ChainstateManager::ActiveChain ( ) const
inline

Definition at line 941 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 5028 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 942 of file validation.h.

Here is the call graph for this function:

◆ ActiveTip()

CBlockIndex* ChainstateManager::ActiveTip ( ) const
inline

Definition at line 943 of file validation.h.

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

◆ BlockIndex()

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

Definition at line 945 of file validation.h.

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

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

◆ GetConsensus()

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

Definition at line 869 of file validation.h.

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

◆ GetParams()

const CChainParams& ChainstateManager::GetParams ( ) const
inline

Definition at line 868 of file validation.h.

Here is the caller graph for this function:

◆ GUARDED_BY() [1/5]

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/5]

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/5]

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

◆ GUARDED_BY() [4/5]

bool m_snapshot_validated ChainstateManager::GUARDED_BY ( ::cs_main  )
inlineprivate

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

Definition at line 837 of file validation.h.

◆ GUARDED_BY() [5/5]

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

Definition at line 839 of file validation.h.

◆ 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 5035 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 963 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 4149 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,
AutoFile coins_file,
const node::SnapshotMetadata metadata 
)
private

Internal helper for ActivateSnapshot().

Definition at line 4831 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 *  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.
[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 3777 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 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
[out]ppindexIf set, the pointer will be set to point to the last new block index object for the given headers

Definition at line 3664 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 3816 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 4675 of file validation.cpp.

Here is the caller graph for this function:

Member Data Documentation

◆ CChainState

friend ChainstateManager::CChainState
private

Definition at line 859 of file validation.h.

◆ GetAll

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

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

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

Definition at line 921 of file validation.h.

◆ m_adjusted_time_callback

const std::function<int64_t()> ChainstateManager::m_adjusted_time_callback
private

Definition at line 843 of file validation.h.

◆ m_best_header

CBlockIndex* ChainstateManager::m_best_header = nullptr

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

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

◆ m_chainparams

const CChainParams ChainstateManager::m_chainparams
private

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

◆ m_load_block

std::thread ChainstateManager::m_load_block

Definition at line 871 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 906 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 902 of file validation.h.

◆ m_versionbitscache

VersionBitsCache ChainstateManager::m_versionbitscache
mutable

Track versionbit status.

Definition at line 954 of file validation.h.


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