CChainState Class Reference

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

#include <validation.h>

Collaboration diagram for CChainState:

Public Member Functions
	CChainState (CTxMemPool &mempool, BlockManager &blockman, uint256 from_snapshot_blockhash=uint256())
void	InitCoinsDB (size_t cache_size_bytes, bool in_memory, bool should_wipe, std::string leveldb_name="chainstate")
	Initialize the CoinsViews UTXO set database management data structures. More...
CCoinsViewCache &	CoinsTip () EXCLUSIVE_LOCKS_REQUIRED(cs_main)
CCoinsViewDB &	CoinsDB () EXCLUSIVE_LOCKS_REQUIRED(cs_main)
CCoinsViewErrorCatcher &	CoinsErrorCatcher () EXCLUSIVE_LOCKS_REQUIRED(cs_main)
void	ResetCoinsViews ()
	Destructs all objects related to accessing the UTXO set. 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	ActivateBestChain (BlockValidationState &state, const CChainParams &chainparams, std::shared_ptr< const CBlock > pblock) LOCKS_EXCLUDED(cs_main)
	Make the best chain active, in multiple steps. More...
bool	AcceptBlock (const std::shared_ptr< const CBlock > &pblock, BlockValidationState &state, const CChainParams &chainparams, CBlockIndex **ppindex, bool fRequested, const FlatFilePos *dbp, bool *fNewBlock) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
	Store block on disk. More...
DisconnectResult	DisconnectBlock (const CBlock &block, const CBlockIndex *pindex, CCoinsViewCache &view)
	Undo the effects of this block (with given index) on the UTXO set represented by coins. More...
bool	ConnectBlock (const CBlock &block, BlockValidationState &state, CBlockIndex *pindex, CCoinsViewCache &view, const CChainParams &chainparams, bool fJustCheck=false) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
	Apply the effects of this block (with given index) on the UTXO set represented by coins. More...
bool	DisconnectTip (BlockValidationState &state, const CChainParams &chainparams, DisconnectedBlockTransactions *disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main
	Disconnect m_chain's tip. More...
bool	PreciousBlock (BlockValidationState &state, const CChainParams &params, CBlockIndex *pindex) LOCKS_EXCLUDED(cs_main)
bool	InvalidateBlock (BlockValidationState &state, const CChainParams &chainparams, CBlockIndex *pindex) LOCKS_EXCLUDED(cs_main)
void	ResetBlockFailureFlags (CBlockIndex *pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
bool	ReplayBlocks (const CChainParams &params)
	Replay blocks that aren't fully applied to the database. More...
bool	RewindBlockIndex (const CChainParams &params) LOCKS_EXCLUDED(cs_main)
bool	LoadGenesisBlock (const CChainParams &chainparams)
void	PruneBlockIndexCandidates ()
	Delete all entries in setBlockIndexCandidates that are worse than the current tip. More...
void	UnloadBlockIndex ()
bool	IsInitialBlockDownload () const
	Check whether we are doing an initial block download (synchronizing from disk or network) More...
void	CheckBlockIndex (const Consensus::Params &consensusParams)
	Make various assertions about the state of the block index. More...
void	LoadMempool (const ArgsManager &args)
	Load the persisted mempool from disk. More...
bool	LoadChainTip (const CChainParams &chainparams) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
	Update the chain tip based on database information, i.e. More...

Public Attributes
CChain	m_chain
	The current chain of blockheaders we consult and build on. More...
const uint256	m_from_snapshot_blockhash {}
	The blockhash which is the base of the snapshot this chainstate was created from. More...
std::set< CBlockIndex *, CBlockIndexWorkComparator >	setBlockIndexCandidates
	The set of all CBlockIndex entries with BLOCK_VALID_TRANSACTIONS (for itself and all ancestors) and as good as our current tip or better. 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 m_mempool	cs

Protected Attributes
RecursiveMutex	cs_nBlockSequenceId
	Every received block is assigned a unique and increasing identifier, so we know which one to give priority in case of a fork. More...
int32_t	nBlockSequenceId = 1
	Blocks loaded from disk are assigned id 0, so start the counter at 1. 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...
RecursiveMutex	m_cs_chainstate
	the ChainState CriticalSection A lock that must be held when modifying this ChainState - held in ActivateBestChain() More...
std::atomic< bool >	m_cached_finished_ibd {false}
	Whether this chainstate is undergoing initial block download. More...
BlockManager &	m_blockman
	Reference to a BlockManager instance which itself is shared across all CChainState instances. More...
CTxMemPool &	m_mempool
	mempool that is kept in sync with the chain More...
std::unique_ptr< CoinsViews >	m_coins_views
	Manages the UTXO set, which is a reflection of the contents of m_chain. More...

Private Member Functions
bool	ActivateBestChainStep (BlockValidationState &state, const CChainParams &chainparams, CBlockIndex *pindexMostWork, const std::shared_ptr< const CBlock > &pblock, bool &fInvalidFound, ConnectTrace &connectTrace) EXCLUSIVE_LOCKS_REQUIRED(cs_main
	Dictates whether we need to flush the cache to disk or not. More...
bool	ConnectTip (BlockValidationState &state, const CChainParams &chainparams, 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)
CBlockIndex *	FindMostWorkChain () 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...
void	ReceivedBlockTransactions (const CBlock &block, CBlockIndex *pindexNew, const FlatFilePos &pos, const Consensus::Params &consensusParams) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
	Mark a block as having its data received and checked (up to BLOCK_VALID_TRANSACTIONS). More...
bool	RollforwardBlock (const CBlockIndex *pindex, CCoinsViewCache &inputs, const CChainParams &params) 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	EraseBlockData (CBlockIndex *index) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
	Mark a block as not having block data. More...

Private Attributes
friend	ChainstateManager

Detailed Description

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

Definition at line 506 of file validation.h.

Constructor & Destructor Documentation

CChainState::CChainState ( CTxMemPool &  mempool, BlockManager &  blockman, uint256  from_snapshot_blockhash = uint256()  )

explicit

Definition at line 1262 of file validation.cpp.

Member Function Documentation

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

Store block on disk.

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

Definition at line 3761 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

bool CChainState::ActivateBestChain	(	BlockValidationState &	state,
		const CChainParams &	chainparams,
		std::shared_ptr< const CBlock >	pblock
	)

Make the best chain active, in multiple steps.

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.

Returns

true unless a system error occurred

Definition at line 2870 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

bool CChainState::ActivateBestChainStep ( BlockValidationState &  state, const CChainParams &  chainparams, CBlockIndex *  pindexMostWork, const std::shared_ptr< const CBlock > &  pblock, bool &  fInvalidFound, ConnectTrace &  connectTrace  )

private

Dictates whether we need to flush the cache to disk or not.

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

Returns

the state of the size of the coins cache.

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

Returns

true unless a system error occurred

Definition at line 2744 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::CheckBlockIndex

(

const Consensus::Params &

consensusParams

)

Make various assertions about the state of the block index.

By default this only executes fully when using the Regtest chain; see: fCheckBlockIndex.

Definition at line 4791 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

CCoinsViewDB& CChainState::CoinsDB ( )

inline

Returns

A reference to the on-disk UTXO set database.

Definition at line 597 of file validation.h.

Here is the caller graph for this function:

CCoinsViewErrorCatcher& CChainState::CoinsErrorCatcher ( )

inline

Returns

A reference to a wrapped view of the in-memory UTXO set that handles disk read errors gracefully.

Definition at line 604 of file validation.h.

CCoinsViewCache& CChainState::CoinsTip ( )

inline

Returns

A reference to the in-memory cache of the UTXO set.

Definition at line 590 of file validation.h.

Here is the caller graph for this function:

bool CChainState::ConnectBlock	(	const CBlock &	block,
		BlockValidationState &	state,
		CBlockIndex *	pindex,
		CCoinsViewCache &	view,
		const CChainParams &	chainparams,
		bool	fJustCheck = false
	)

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

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

Here is the call graph for this function:

Here is the caller graph for this function:

bool CChainState::ConnectTip ( BlockValidationState &  state, const CChainParams &  chainparams, 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 2608 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

DisconnectResult CChainState::DisconnectBlock	(	const CBlock &	block,
		const CBlockIndex *	pindex,
		CCoinsViewCache &	view
	)

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

When FAILED is returned, view is left in an indeterminate state.

Definition at line 1715 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

bool CChainState::DisconnectTip	(	BlockValidationState &	state,
		const CChainParams &	chainparams,
		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 UpdateMempoolForReorg. 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 2507 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::EraseBlockData ( CBlockIndex *  index )

private

Mark a block as not having block data.

Helper for CChainState::RewindBlockIndex.

Definition at line 4455 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

CBlockIndex * CChainState::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 2671 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::ForceFlushStateToDisk

(

)

Unconditionally flush all changes to disk.

Definition at line 2411 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::InitCoinsDB	(	size_t	cache_size_bytes,
		bool	in_memory,
		bool	should_wipe,
		std::string	leveldb_name = "chainstate"
	)

Initialize the CoinsViews UTXO set database management data structures.

The in-memory cache is initialized separately.

All parameters forwarded to CoinsViews.

Definition at line 1267 of file validation.cpp.

Here is the call graph for this function:

bool CChainState::InvalidateBlock	(	BlockValidationState &	state,
		const CChainParams &	chainparams,
		CBlockIndex *	pindex
	)

Definition at line 3004 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::InvalidBlockFound ( CBlockIndex *  pindex, const BlockValidationState &  state  )

private

Definition at line 1433 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

bool CChainState::IsInitialBlockDownload

(

)

const

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

Definition at line 1293 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

bool CChainState::LoadChainTip

(

const CChainParams &

chainparams

)

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

CoinsTip()'s best block.

Definition at line 4230 of file validation.cpp.

Here is the call graph for this function:

bool CChainState::LoadGenesisBlock

(

const CChainParams &

chainparams

)

Definition at line 4642 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::LoadMempool

(

const ArgsManager &

args

)

Load the persisted mempool from disk.

Definition at line 4222 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

bool CChainState::PreciousBlock	(	BlockValidationState &	state,
		const CChainParams &	params,
		CBlockIndex *	pindex
	)

Definition at line 2972 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::PruneAndFlush

(

)

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

Definition at line 2419 of file validation.cpp.

Here is the call graph for this function:

void CChainState::PruneBlockIndexCandidates

(

)

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

Definition at line 2727 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::ReceivedBlockTransactions ( const CBlock &  block, CBlockIndex *  pindexNew, const FlatFilePos &  pos, const Consensus::Params &  consensusParams  )

private

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

Definition at line 3219 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

bool CChainState::ReplayBlocks

(

const CChainParams &

params

)

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

Definition at line 4387 of file validation.cpp.

Here is the call graph for this function:

void CChainState::ResetBlockFailureFlags

(

CBlockIndex *

pindex

)

Definition at line 3144 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::ResetCoinsViews ( )

inline

Destructs all objects related to accessing the UTXO set.

Definition at line 610 of file validation.h.

bool CChainState::RewindBlockIndex

(

const CChainParams &

params

)

Definition at line 4490 of file validation.cpp.

Here is the call graph for this function:

bool CChainState::RollforwardBlock ( const CBlockIndex *  pindex, CCoinsViewCache &  inputs, const CChainParams &  params  )

private

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

Definition at line 4367 of file validation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

void CChainState::UnloadBlockIndex

(

)

Definition at line 4593 of file validation.cpp.

Member Data Documentation

friend CChainState::ChainstateManager

private

Definition at line 732 of file validation.h.

bool m_mempool CChainState::cs

Definition at line 674 of file validation.h.

RecursiveMutex CChainState::cs_nBlockSequenceId

protected

Every received block is assigned a unique and increasing identifier, so we know which one to give priority in case of a fork.

Definition at line 513 of file validation.h.

BlockManager& CChainState::m_blockman

protected

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

Keeping a local reference allows us to test more easily as opposed to referencing a global.

Definition at line 538 of file validation.h.

std::atomic<bool> CChainState::m_cached_finished_ibd {false}

mutableprotected

Whether this chainstate is undergoing initial block download.

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

Definition at line 533 of file validation.h.

CChain CChainState::m_chain

The current chain of blockheaders we consult and build on.

See also

CChain, CBlockIndex.

Definition at line 573 of file validation.h.

std::unique_ptr<CoinsViews> CChainState::m_coins_views

protected

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

Definition at line 544 of file validation.h.

size_t CChainState::m_coinsdb_cache_size_bytes {0}

The cache size of the on-disk coins view.

Definition at line 613 of file validation.h.

size_t CChainState::m_coinstip_cache_size_bytes {0}

The cache size of the in-memory coins view.

Definition at line 616 of file validation.h.

RecursiveMutex CChainState::m_cs_chainstate

protected

the ChainState CriticalSection A lock that must be held when modifying this ChainState - held in ActivateBestChain()

Definition at line 525 of file validation.h.

const uint256 CChainState::m_from_snapshot_blockhash {}

The blockhash which is the base of the snapshot this chainstate was created from.

IsNull() if this chainstate was not created from a snapshot.

Definition at line 580 of file validation.h.

CTxMemPool& CChainState::m_mempool

protected

mempool that is kept in sync with the chain

Definition at line 541 of file validation.h.

int32_t CChainState::nBlockReverseSequenceId = -1

protected

Decreasing counter (used by subsequent preciousblock calls).

Definition at line 517 of file validation.h.

int32_t CChainState::nBlockSequenceId = 1

protected

Blocks loaded from disk are assigned id 0, so start the counter at 1.

Definition at line 515 of file validation.h.

arith_uint256 CChainState::nLastPreciousChainwork = 0

protected

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

Definition at line 519 of file validation.h.

std::set<CBlockIndex*, CBlockIndexWorkComparator> CChainState::setBlockIndexCandidates

The set of all CBlockIndex entries with BLOCK_VALID_TRANSACTIONS (for itself and all ancestors) 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 587 of file validation.h.

---

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

• src/validation.h
• src/validation.cpp