Bitcoin Core  26.99.0
P2P Digital Currency
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | Private Member Functions | Private Attributes | List of all members
Chainstate Class Reference

Chainstate stores and provides an API to update our local knowledge of the current best chain. More...

#include <validation.h>

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

Public Member Functions

 Chainstate (CTxMemPool *mempool, node::BlockManager &blockman, ChainstateManager &chainman, std::optional< uint256 > from_snapshot_blockhash=std::nullopt)
 
CCoinsViewCacheCoinsTip () EXCLUSIVE_LOCKS_REQUIRED(
 
CCoinsViewDBCoinsDB () EXCLUSIVE_LOCKS_REQUIRED(
 
CTxMemPoolGetMempool ()
 
CCoinsViewErrorCatcherCoinsErrorCatcher () EXCLUSIVE_LOCKS_REQUIRED(
 
void ResetCoinsViews ()
 Destructs all objects related to accessing the UTXO set. More...
 
bool HasCoinsViews () const
 Does this chainstate have a UTXO set attached? More...
 
void ForceFlushStateToDisk ()
 Unconditionally flush all changes to disk. More...
 
void PruneAndFlush ()
 Prune blockfiles from the disk if necessary and then flush chainstate changes if we pruned. More...
 
bool DisconnectTip (BlockValidationState &state, DisconnectedBlockTransactions *disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main
 Disconnect m_chain's tip. More...
 
bool ReplayBlocks ()
 Replay blocks that aren't fully applied to the database. More...
 
bool NeedsRedownload () const EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Whether the chain state needs to be redownloaded due to lack of witness data. More...
 
bool LoadGenesisBlock ()
 Ensures we have a genesis block in the block tree, possibly writing one to disk. More...
 
void TryAddBlockIndexCandidate (CBlockIndex *pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 
void PruneBlockIndexCandidates ()
 Delete all entries in setBlockIndexCandidates that are worse than the current tip. More...
 
bool LoadChainTip () EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Update the chain tip based on database information, i.e. More...
 

Public Attributes

node::BlockManagerm_blockman
 Reference to a BlockManager instance which itself is shared across all Chainstate instances. More...
 
ChainstateManagerm_chainman
 The chainstate manager that owns this chainstate. More...
 
CChain m_chain
 The current chain of blockheaders we consult and build on. More...
 
const std::optional< uint256m_from_snapshot_blockhash
 The blockhash which is the base of the snapshot this chainstate was created from. More...
 
const CBlockIndex *SnapshotBase() EXCLUSIVE_LOCKS_REQUIRED(std::set< CBlockIndex *, node::CBlockIndexWorkComparatorsetBlockIndexCandidates
 The base of the snapshot this chainstate was created from. More...
 
size_t m_coinsdb_cache_size_bytes {0}
 The cache size of the on-disk coins view. More...
 
size_t m_coinstip_cache_size_bytes {0}
 The cache size of the in-memory coins view. More...
 
bool ActivateBestChain(BlockValidationState &state, std::shared_ptr< const CBlock > pblock=nullptr) LOCKS_EXCLUDED(DisconnectResult DisconnectBlock(const CBlock &block, const CBlockIndex *pindex, CCoinsViewCache &view) EXCLUSIVE_LOCKS_REQUIRED(boo ConnectBlock )(const CBlock &block, BlockValidationState &state, CBlockIndex *pindex, CCoinsViewCache &view, bool fJustCheck=false) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Find the best known block, and make it the tip of the block chain. More...
 
bool m_mempool cs
 
bool PreciousBlock(BlockValidationState &state, CBlockIndex *pindex) LOCKS_EXCLUDED(bool InvalidateBlock(BlockValidationState &state, CBlockIndex *pindex) LOCKS_EXCLUDED(voi ResetBlockFailureFlags )(CBlockIndex *pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Mark a block as precious and reorganize. More...
 

Protected Member Functions

bool m_disabled GUARDED_BY (::cs_main)
 This toggle exists for use when doing background validation for UTXO snapshots. More...
 
const CBlockIndex *m_cached_snapshot_base GUARDED_BY (::cs_main)
 Cached result of LookupBlockIndex(*m_from_snapshot_blockhash) More...
 

Protected Attributes

Mutex m_chainstate_mutex
 The ChainState Mutex A lock that must be held when modifying this ChainState - held in ActivateBestChain() and InvalidateBlock() More...
 
CTxMemPoolm_mempool
 Optional mempool that is kept in sync with the chain. More...
 
std::unique_ptr< CoinsViewsm_coins_views
 Manages the UTXO set, which is a reflection of the contents of m_chain. More...
 

Private Member Functions

bool ActivateBestChainStep (BlockValidationState &state, CBlockIndex *pindexMostWork, const std::shared_ptr< const CBlock > &pblock, bool &fInvalidFound, ConnectTrace &connectTrace) EXCLUSIVE_LOCKS_REQUIRED(cs_main
 Try to make some progress towards making pindexMostWork the active block. More...
 
bool ConnectTip (BlockValidationState &state, CBlockIndex *pindexNew, const std::shared_ptr< const CBlock > &pblock, ConnectTrace &connectTrace, DisconnectedBlockTransactions &disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main
 Connect a new block to m_chain. More...
 
void InvalidBlockFound (CBlockIndex *pindex, const BlockValidationState &state) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 
CBlockIndexFindMostWorkChain () EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Return the tip of the chain with the most work in it, that isn't known to be invalid (it's however far from certain to be valid). More...
 
bool RollforwardBlock (const CBlockIndex *pindex, CCoinsViewCache &inputs) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 Apply the effects of a block on the utxo cache, ignoring that it may already have been applied. More...
 
void CheckForkWarningConditions () EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 
void InvalidChainFound (CBlockIndex *pindexNew) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
 
void MaybeUpdateMempoolForReorg (DisconnectedBlockTransactions &disconnectpool, bool fAddToMempool) 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. More...
 

Private Attributes

void m_mempool cs
 
void UpdateTip(const CBlockIndex *pindexNew) EXCLUSIVE_LOCKS_REQUIRED(SteadyClock::time_poin m_last_write ) {}
 Check warning conditions and do some notifications on new chain tip set. More...
 
SteadyClock::time_point m_last_flush {}
 
util::Result< void > InvalidateCoinsDBOnDisk() EXCLUSIVE_LOCKS_REQUIRED(friend ChainstateManager
 In case of an invalid snapshot, rename the coins leveldb directory so that it can be examined for issue diagnosis. More...
 

Detailed Description

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

Definition at line 488 of file validation.h.

Constructor & Destructor Documentation

◆ Chainstate()

Chainstate::Chainstate ( CTxMemPool mempool,
node::BlockManager blockman,
ChainstateManager chainman,
std::optional< uint256 from_snapshot_blockhash = std::nullopt 
)
explicit

Definition at line 1714 of file validation.cpp.

Member Function Documentation

◆ ActivateBestChainStep()

bool Chainstate::ActivateBestChainStep ( BlockValidationState state,
CBlockIndex pindexMostWork,
const std::shared_ptr< const CBlock > &  pblock,
bool &  fInvalidFound,
ConnectTrace connectTrace 
)
private

Try to make some progress towards making pindexMostWork the active block.

pblock is either nullptr or a pointer to a CBlock corresponding to pindexMostWork.

Returns
true unless a system error occurred

Definition at line 3098 of file validation.cpp.

Here is the call graph for this function:

◆ CheckForkWarningConditions()

void Chainstate::CheckForkWarningConditions ( )
private

Definition at line 1792 of file validation.cpp.

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

◆ CoinsDB()

CCoinsViewDB& Chainstate::CoinsDB ( )
inline
Returns
A reference to the on-disk UTXO set database.

Definition at line 602 of file validation.h.

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

◆ CoinsErrorCatcher()

CCoinsViewErrorCatcher& Chainstate::CoinsErrorCatcher ( )
inline
Returns
A reference to a wrapped view of the in-memory UTXO set that handles disk read errors gracefully.

Definition at line 616 of file validation.h.

Here is the call graph for this function:

◆ CoinsTip()

CCoinsViewCache& Chainstate::CoinsTip ( )
inline
Returns
A reference to the in-memory cache of the UTXO set.

Definition at line 594 of file validation.h.

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

◆ ConnectTip()

bool Chainstate::ConnectTip ( BlockValidationState state,
CBlockIndex pindexNew,
const std::shared_ptr< const CBlock > &  pblock,
ConnectTrace connectTrace,
DisconnectedBlockTransactions disconnectpool 
)
private

Connect a new block to m_chain.

pblock is either nullptr or a pointer to a CBlock corresponding to pindexNew, to bypass loading it again from disk.

The block is added to connectTrace if connection succeeds.

Definition at line 2922 of file validation.cpp.

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

◆ DisconnectTip()

bool Chainstate::DisconnectTip ( BlockValidationState state,
DisconnectedBlockTransactions disconnectpool 
)

Disconnect m_chain's tip.

After calling, the mempool will be in an inconsistent state, with transactions from disconnected blocks being added to disconnectpool. You should make the mempool consistent again by calling MaybeUpdateMempoolForReorg. with cs_main held.

If disconnectpool is nullptr, then no disconnected transactions are added to disconnectpool (note that the caller is responsible for mempool consistency in any case).

Definition at line 2811 of file validation.cpp.

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

◆ FindMostWorkChain()

CBlockIndex * Chainstate::FindMostWorkChain ( )
private

Return the tip of the chain with the most work in it, that isn't known to be invalid (it's however far from certain to be valid).

Definition at line 3021 of file validation.cpp.

Here is the call graph for this function:

◆ ForceFlushStateToDisk()

void Chainstate::ForceFlushStateToDisk ( )

Unconditionally flush all changes to disk.

Definition at line 2708 of file validation.cpp.

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

◆ GetMempool()

CTxMemPool* Chainstate::GetMempool ( )
inline
Returns
A pointer to the mempool.

Definition at line 609 of file validation.h.

Here is the caller graph for this function:

◆ GUARDED_BY() [1/2]

bool m_disabled Chainstate::GUARDED_BY ( ::cs_main  )
inlineprotected

This toggle exists for use when doing background validation for UTXO snapshots.

In the expected case, it is set once the background validation chain reaches the same height as the base of the snapshot and its UTXO set is found to hash to the expected assumeutxo value. It signals that we should no longer connect blocks to the background chainstate. When set on the background validation chainstate, it signifies that we have fully validated the snapshot chainstate.

In the unlikely case that the snapshot chainstate is found to be invalid, this is set to true on the snapshot chainstate.

Definition at line 516 of file validation.h.

◆ GUARDED_BY() [2/2]

const CBlockIndex* m_cached_snapshot_base Chainstate::GUARDED_BY ( ::cs_main  )
inlineprotected

Cached result of LookupBlockIndex(*m_from_snapshot_blockhash)

Definition at line 519 of file validation.h.

◆ HasCoinsViews()

bool Chainstate::HasCoinsViews ( ) const
inline

Does this chainstate have a UTXO set attached?

Definition at line 626 of file validation.h.

◆ InvalidBlockFound()

void Chainstate::InvalidBlockFound ( CBlockIndex pindex,
const BlockValidationState state 
)
private

Definition at line 1834 of file validation.cpp.

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

◆ InvalidChainFound()

void Chainstate::InvalidChainFound ( CBlockIndex pindexNew)
private

Definition at line 1811 of file validation.cpp.

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

◆ LoadChainTip()

bool Chainstate::LoadChainTip ( )

Update the chain tip based on database information, i.e.

CoinsTip()'s best block.

Definition at line 4371 of file validation.cpp.

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

◆ LoadGenesisBlock()

bool Chainstate::LoadGenesisBlock ( )

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

Definition at line 4715 of file validation.cpp.

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

◆ MaybeUpdateMempoolForReorg()

void Chainstate::MaybeUpdateMempoolForReorg ( DisconnectedBlockTransactions disconnectpool,
bool  fAddToMempool 
)
private

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.

Definition at line 296 of file validation.cpp.

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

◆ NeedsRedownload()

bool Chainstate::NeedsRedownload ( ) const

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

Definition at line 4639 of file validation.cpp.

Here is the call graph for this function:

◆ PruneAndFlush()

void Chainstate::PruneAndFlush ( )

Prune blockfiles from the disk if necessary and then flush chainstate changes if we pruned.

Definition at line 2716 of file validation.cpp.

Here is the call graph for this function:

◆ PruneBlockIndexCandidates()

void Chainstate::PruneBlockIndexCandidates ( )

Delete all entries in setBlockIndexCandidates that are worse than the current tip.

Definition at line 3081 of file validation.cpp.

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

◆ ReplayBlocks()

bool Chainstate::ReplayBlocks ( )

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

Definition at line 4571 of file validation.cpp.

Here is the call graph for this function:

◆ ResetCoinsViews()

void Chainstate::ResetCoinsViews ( )
inline

Destructs all objects related to accessing the UTXO set.

Definition at line 623 of file validation.h.

◆ RollforwardBlock()

bool Chainstate::RollforwardBlock ( const CBlockIndex pindex,
CCoinsViewCache inputs 
)
private

Apply the effects of a block on the utxo cache, ignoring that it may already have been applied.

Definition at line 4550 of file validation.cpp.

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

◆ TryAddBlockIndexCandidate()

void Chainstate::TryAddBlockIndexCandidate ( CBlockIndex pindex)

Definition at line 3586 of file validation.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ ChainstateManager

util::Result<void> InvalidateCoinsDBOnDisk () EXCLUSIVE_LOCKS_REQUIRED( friend Chainstate::ChainstateManager
private

In case of an invalid snapshot, rename the coins leveldb directory so that it can be examined for issue diagnosis.

Definition at line 794 of file validation.h.

◆ ConnectBlock

bool Chainstate::ConnectBlock

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

Apply the effects of this block (with given index) on the UTXO set represented by coins.

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 background chainstate whose tip has reached the base block of the snapshot, its execution will take MINUTES while it hashes the background 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

Validity checks that depend on the UTXO set are also done; ConnectBlock() can fail if those validity checks fail (among other reasons).

Definition at line 692 of file validation.h.

◆ cs [1/2]

bool m_mempool Chainstate::cs

Definition at line 696 of file validation.h.

◆ cs [2/2]

void m_mempool Chainstate::cs
private

Definition at line 779 of file validation.h.

◆ m_blockman

node::BlockManager& Chainstate::m_blockman

Reference to a BlockManager instance which itself is shared across all Chainstate instances.

Definition at line 524 of file validation.h.

◆ m_chain

CChain Chainstate::m_chain

The current chain of blockheaders we consult and build on.

See also
CChain, CBlockIndex.

Definition at line 569 of file validation.h.

◆ m_chainman

ChainstateManager& Chainstate::m_chainman

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.

Definition at line 529 of file validation.h.

◆ m_chainstate_mutex

Mutex Chainstate::m_chainstate_mutex
protected

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

Definition at line 496 of file validation.h.

◆ m_coins_views

std::unique_ptr<CoinsViews> Chainstate::m_coins_views
protected

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

Definition at line 503 of file validation.h.

◆ m_coinsdb_cache_size_bytes

size_t Chainstate::m_coinsdb_cache_size_bytes {0}

The cache size of the on-disk coins view.

Definition at line 629 of file validation.h.

◆ m_coinstip_cache_size_bytes

size_t Chainstate::m_coinstip_cache_size_bytes {0}

The cache size of the in-memory coins view.

Definition at line 632 of file validation.h.

◆ m_from_snapshot_blockhash

const std::optional<uint256> Chainstate::m_from_snapshot_blockhash

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.

Definition at line 576 of file validation.h.

◆ m_last_flush

SteadyClock::time_point Chainstate::m_last_flush {}
private

Definition at line 786 of file validation.h.

◆ m_last_write

void UpdateTip (const CBlockIndex* pindexNew) EXCLUSIVE_LOCKS_REQUIRED( SteadyClock::time_poin Chainstate::m_last_write) {}
private

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

Definition at line 785 of file validation.h.

◆ m_mempool

CTxMemPool* Chainstate::m_mempool
protected

Optional mempool that is kept in sync with the chain.

Only the active chainstate has a mempool.

Definition at line 500 of file validation.h.

◆ ResetBlockFailureFlags

void Chainstate::ResetBlockFailureFlags

Mark a block as precious and reorganize.

May not be called in a validationinterface callback. Mark a block as invalid. Remove invalidity status from a block and its descendants.

Definition at line 713 of file validation.h.

◆ setBlockIndexCandidates

const CBlockIndex* SnapshotBase () EXCLUSIVE_LOCKS_REQUIRED( std::set<CBlockIndex*, node::CBlockIndexWorkComparator> Chainstate::setBlockIndexCandidates

The base of the snapshot this chainstate was created from.

nullptr if this chainstate was not created from a snapshot. The set of all CBlockIndex entries with either BLOCK_VALID_TRANSACTIONS (for itself and all ancestors) or BLOCK_ASSUMED_VALID (if using background chainstates) and as good as our current tip or better. Entries may be failed, though, and pruning nodes may be missing the data for the block.

Definition at line 591 of file validation.h.


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