ChainstateManager

Name

Description

Options

Options controlling the behavior of the chainstate manager.

Name

Description

ChainstateManager [constructor]

Construct a chainstate manager.

~ChainstateManager [destructor]

Destroy the chainstate manager and its chainstates.

AcceptBlock

Sufficiently validate a block for disk storage (and store on disk).

ActivateBestChains

Call ActivateBestChain() on every chainstate.

ActivateSnapshot

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

ActiveChain

Return the active chain of block headers.

ActiveChainstate

Alternatives to CurrentChainstate() used by older code to query latest chainstate information without locking cs_main. Newer code should avoid querying ChainstateManager and use Chainstate objects directly, or should use CurrentChainstate() instead. @{ Return the active chainstate.

ActiveHeight

Return the height of the active chain tip.

ActiveTip

Return the active chain tip.

AddChainstate

Add new chainstate.

AssumedValidBlock

Access the assumed‐valid block below which script checks may be skipped.

BlockIndex

Access the map of all known block index entries.

BlocksAheadOfTip

Returns how many blocks the best header is ahead of the current tip, or nullopt if the best header does not extend the tip.

CheckBlockIndex

Make various assertions about the state of the block index.

CurrentChainstate

Return current chainstate targeting the most‐work, network tip.

DeleteChainstate

Remove the chainstate and all on‐disk artifacts. Used when reindex{‐chainstate} is called during snapshot use.

GenerateCoinbaseCommitment

Produce the necessary coinbase commitment for a block (modifies the hash, don't call for mined blocks).

GetBackgroundVerificationProgress

Guess background verification progress in case assume‐utxo was used (as a fraction between 0.0=genesis and 1.0=snapshot blocks).

GetCheckQueue

Access the queue of pending script verifications.

GetConsensus

Access the consensus parameters in use.

GetHistoricalBlockRange

Get range of historical blocks to download.

GetMutex

Alias for ::cs_main. Should be used in new code to make it easier to make ::cs_main a member of this class. Generally, methods of this class should be annotated to require this mutex. This will make calling code more verbose, but also help to: ‐ Clarify that the method will acquire a mutex that heavily affects overall performance. ‐ Force call sites to think how long they need to acquire the mutex to get consistent results.

GetNotifications

Access the notifications sink used to surface validation events.

GetParams

Access the chain parameters in use.

GuessVerificationProgress

Guess verification progress (as a fraction between 0.0=genesis and 1.0=current tip). This is also the case in the assumeutxo context, meaning that the progress reported for the snapshot chainstate may suggest that all historical blocks have already been verified even though that may not actually be the case.

HistoricalChainstate

Return historical chainstate targeting a specific block, if any.

InitializeChainstate

Instantiate a new chainstate.

IsInitialBlockDownload

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

LoadAssumeutxoChainstate

When starting up, search the datadir for a chainstate based on a UTXO snapshot that is in the process of being validated and load it if found. Return pointer to the Chainstate if it is loaded.

LoadBlockIndex

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

LoadExternalBlockFile

Import blocks from an external file

LoadGenesisBlock

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

MaybeRebalanceCaches

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

MaybeValidateSnapshot

Try to validate an assumeutxo snapshot by using a validated historical chainstate targeted at the snapshot block. When the target block is reached, the UTXO hash is computed and saved to validated_cs.m_target_utxohash, and unvalidated_cs.m_assumeutxo will be updated from UNVALIDATED to either VALIDATED or INVALID depending on whether the hash matches. The INVALID case should not happen in practice because the software should refuse to load unrecognized snapshots, but if it does happen, it is a fatal error.

MinimumChainWork

Access the minimum chain work required to consider syncing complete.

ProcessNewBlock

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!

ProcessNewBlockHeaders

Process incoming block headers.

ProcessTransaction

Try to add a transaction to the memory pool.

RecalculateBestHeader

If, due to invalidation / reconsideration of blocks, the previous best header is no longer valid / guaranteed to be the most‐work header in our block‐index not known to be invalid, recalculate it.

ReceivedBlockTransactions

Mark that the transaction data for a block has been received and stored.

RemoveChainstate

Remove a chainstate.

ReportHeadersPresync

This is used by net_processing to report pre‐synchronization progress of headers, as headers are not yet fed to validation during that time, but validation is (for now) responsible for logging and signalling through NotifyHeaderTip, so it needs this information.

ResetBlockSequenceCounters

Reset the memory‐only sequence counters used to track block arrival (used by tests).

ResetChainstates

Destroy all chainstates managed by this instance.

ShouldCheckBlockIndex

Whether expensive block‐index consistency checks should run.

UpdateIBDStatus

Update and possibly latch the IBD status.

UpdateUncommittedBlockStructures

Update uncommitted block structures (currently: only the witness reserved value). This is safe for submitted blocks as long as they honor default_witness_commitment from the template.

ValidatedChainstate

Return fully validated chainstate that should be used for indexing, to support indexes that need to index blocks in order and can't start from the snapshot block.

ValidatedSnapshotCleanup

If we have validated a snapshot chain during this runtime, copy its chainstate directory over to the main chainstate location, completing validation of the snapshot.

Name

Description

m_best_header

Best header we've seen so far for which the block is not known to be invalid (used, among others, for getheaders queries' starting points). In case of multiple best headers with the same work, it could point to any because CBlockIndexWorkComparator tiebreaker rules are not applied.

m_blockman

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

m_cached_is_ibd

Whether initial block download (IBD) is ongoing.

m_chainstates

List of chainstates. Note: in general, it is not safe to delete Chainstate objects once they are added to this list because there is no mutex that can be locked to prevent Chainstate pointers from being used while they are deleted. (cs_main doesn't work because it is too narrow and is released in the middle of Chainstate::ActivateBestChain to let notifications be processed. m_chainstate_mutex doesn't work because it is not locked at other times when the chainstate is in use.)

m_interrupt

Signal used to observe shutdown requests during long‐running operations.

m_options

Options controlling the behavior of this chainstate manager.

m_total_coinsdb_cache

The total number of bytes available for us to use across all leveldb coins databases. This will be split somehow across chainstates.

m_total_coinstip_cache

The total number of bytes available for us to use across all in‐memory coins caches. This will be split somehow across chainstates.

m_validation_cache

Caches for script execution and signature verification results.

m_versionbitscache

Track versionbit status

nBlockReverseSequenceId

Decreasing counter (used by subsequent preciousblock calls).

nBlockSequenceId

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

nLastPreciousChainwork

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

snapshot_download_completed

Function to restart active indexes; set dynamically to avoid a circular dependency on base/index.cpp.

Name

Description

m_best_invalid

Best known invalid block, tracked to detect a longer invalid chain than the valid one.

Name

Description

Chainstate

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

Name

Description

DeploymentEnabled

Whether a deployment is enabled in the consensus rules, resolved via ChainstateManager.

EnsureAnyChainman

Get the chainstate manager from an opaque RPC context, asserting it is present.

EnsureChainman

Get the chainstate manager from a node context, asserting it is present.

node::CooldownIfHeadersAhead

Wait while the best known header extends the current chain tip AND at least one block is being added to the tip every 3 seconds. If the tip is sufficiently far behind, allow up to 20 seconds for the next tip update.

node::GetTip

Return the hash and height of the active chain tip.

node::ImportBlocks

Load blocks from the given files and activate the best chain, even if none are imported.

node::LoadChainstate

This sequence can have 4 types of outcomes:

node::SubmitBlock

Submit a block and capture the validation state via the BlockChecked callback. Returns whether the block was accepted as a new valid block.

node::VerifyLoadedChainstate

Verify a chainstate that has already been loaded.

node::WaitAndCreateNewBlock

Return a new block template when fees rise to a certain threshold or after a new tip; return nullopt if timeout is reached.

node::WaitTipChanged

Waits for the connected tip to change until timeout has elapsed. During node initialization, this will wait until the tip is connected (regardless of timeout). Returns the current tip, or nullopt if the node is shutting down or interrupt() is called.