[#node-BlockManager]
= xref:node.adoc[node]::BlockManager
:relfileprefix: ../
:mrdocs:

Maintains a tree of blocks (stored in `m_block_index`) which is consulted to determine where the most‐work tip is.

== Synopsis

Declared in `<node/blockstorage.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class BlockManager;
----

== Description

This data is used mostly in `Chainstate` ‐ information about, e.g., candidate tips is not maintained here.

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:node/BlockManager/Options.adoc[`Options`] 
| Options controlling block storage behavior.
| xref:node/BlockManager/ReadRawBlockResult.adoc[`ReadRawBlockResult`] 
| Result of a raw block read: the bytes on success, or a ReadRawError on failure.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:node/BlockManager/2constructor.adoc[`BlockManager`]         [.small]#[constructor]#
| Construct a block manager.
| xref:node/BlockManager/AddToBlockIndex.adoc[`AddToBlockIndex`] 
| Add a block header to the in‐memory block index, updating the best header.
| xref:node/BlockManager/AddUnlinkedBlock.adoc[`AddUnlinkedBlock`] 
| Record a block whose ancestor is still missing transaction data.
| xref:node/BlockManager/CalculateCurrentUsage.adoc[`CalculateCurrentUsage`] 
| Calculate the amount of disk space the block & undo files currently use
| xref:node/BlockManager/CheckBlockDataAvailability.adoc[`CheckBlockDataAvailability`] 
| Check if all blocks in the [upper_block, lower_block]range have data available as defined by the status mask. The caller is responsible for ensuring that lower_block is an ancestor of upper_block (part of the same chain).
| xref:node/BlockManager/CleanupBlockRevFiles.adoc[`CleanupBlockRevFiles`] 
| Remove leftover block and undo files that no longer belong to the block tree.
| xref:node/BlockManager/DeletePruneLock.adoc[`DeletePruneLock`] 
| Delete a prune lock identified by its name. Returns true if the lock existed.
| xref:node/BlockManager/GetAllBlockIndices.adoc[`GetAllBlockIndices`] 
| Return pointers to every block index entry currently held in memory.
| xref:node/BlockManager/GetBlockFileInfo.adoc[`GetBlockFileInfo`] 
| Get block file info entry for one block file
| xref:node/BlockManager/GetBlockPosFilename.adoc[`GetBlockPosFilename`] 
| Translation to a filesystem path
| xref:node/BlockManager/GetFirstBlock.adoc[`GetFirstBlock`] 
| Returns the earliest block with specified `status_mask` flags set after the latest block _not_ having those flags.
| xref:node/BlockManager/GetPruneTarget.adoc[`GetPruneTarget`] 
| Attempt to stay below this number of bytes of block files.
| xref:node/BlockManager/InsertBlockIndex.adoc[`InsertBlockIndex`] 
| Create a new block index entry for a given block hash
| xref:node/BlockManager/IsBlockPruned.adoc[`IsBlockPruned`] 
| Check whether the block associated with this index entry is pruned or not.
| xref:node/BlockManager/IsPruneMode.adoc[`IsPruneMode`] 
| Whether running in ‐prune mode.
| xref:node/BlockManager/LoadBlockIndexDB.adoc[`LoadBlockIndexDB`] 
| Load the block index from the database into memory.
| xref:node/BlockManager/LoadingBlocks.adoc[`LoadingBlocks`] 
| Report whether blocks are still being imported or indexed.
| xref:node/BlockManager/LookupBlockIndex-05.adoc[`LookupBlockIndex`] 
| Look up a block index entry by hash.
| xref:node/BlockManager/OpenBlockFile.adoc[`OpenBlockFile`] 
| Open a block file (blk?????.dat)
| xref:node/BlockManager/PruneOneBlockFile.adoc[`PruneOneBlockFile`] 
| Mark one block file as pruned (modify associated database entries)
| xref:node/BlockManager/ReadBlock-02.adoc[`ReadBlock`] 
| `ReadBlock` overloads
| xref:node/BlockManager/ReadBlockUndo.adoc[`ReadBlockUndo`] 
| Read a block's undo data from disk using its block index entry.
| xref:node/BlockManager/ReadRawBlock.adoc[`ReadRawBlock`] 
| Read the raw, still‐serialized bytes of a block (or a sub‐range) from disk.
| xref:node/BlockManager/ScanAndUnlinkAlreadyPrunedFiles.adoc[`ScanAndUnlinkAlreadyPrunedFiles`] 
| Remove any pruned block & undo files that are still on disk. This could happen on some systems if the file was still being read while unlinked, or if we crash before unlinking.
| xref:node/BlockManager/UnlinkPrunedFiles.adoc[`UnlinkPrunedFiles`] 
| Actually unlink the specified files
| xref:node/BlockManager/UpdateBlockInfo.adoc[`UpdateBlockInfo`] 
| Update blockfile info while processing a block during reindex. The block must be available on disk.
| xref:node/BlockManager/UpdatePruneLock.adoc[`UpdatePruneLock`] 
| Create or update a prune lock identified by its name
| xref:node/BlockManager/WriteBlock.adoc[`WriteBlock`] 
| Store block on disk and update block file statistics.
| xref:node/BlockManager/WriteBlockIndexDB.adoc[`WriteBlockIndexDB`] 
| Write the dirty block index and block‐file entries to the database.
| xref:node/BlockManager/WriteBlockUndo.adoc[`WriteBlockUndo`] 
| Write a block's undo data to disk and record it in the block index.
|===


== Data Members

[cols="1,4"]
|===
| Name| Description
| xref:node/BlockManager/m_block_index.adoc[`m_block_index`] 
| The in‐memory block tree, mapping each block hash to its index entry.
| xref:node/BlockManager/m_block_tree_db.adoc[`m_block_tree_db`] 
| Handle to the on‐disk block index database (blocks/index/).
| xref:node/BlockManager/m_blockfiles_indexed.adoc[`m_blockfiles_indexed`] 
| Whether all blockfiles have been added to the block tree database. Normally true, but set to false when a reindex is requested and the database is wiped. The value is persisted in the database across restarts and will be false until reindexing completes.
| xref:node/BlockManager/m_blocks_unlinked.adoc[`m_blocks_unlinked`] 
| All pairs A‐>B, where A (or one of its ancestors) misses transactions, but B has transactions.
| xref:node/BlockManager/m_have_pruned.adoc[`m_have_pruned`] 
| True if any block files have ever been pruned.
| xref:node/BlockManager/m_importing.adoc[`m_importing`] 
| Whether blocks are currently being imported from disk.
| xref:node/BlockManager/m_interrupt.adoc[`m_interrupt`] 
| Interrupt used to abort long‐running block‐loading operations.
| xref:node/BlockManager/m_snapshot_height.adoc[`m_snapshot_height`] 
| The height of the base block of an assumeutxo snapshot, if one is in use.
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:node/BlockManager/PRUNE_TARGET_MANUAL.adoc[`PRUNE_TARGET_MANUAL`] 
| Sentinel prune target meaning pruning is manual rather than size‐based.
|===


== Protected Data Members

[cols="1,4"]
|===
| Name| Description
| xref:node/BlockManager/m_blockfile_info.adoc[`m_blockfile_info`] 
| In‐memory statistics for each block file, indexed by file number.
| xref:node/BlockManager/m_dirty_blockindex.adoc[`m_dirty_blockindex`] 
| Dirty block index entries.
| xref:node/BlockManager/m_dirty_fileinfo.adoc[`m_dirty_fileinfo`] 
| Dirty block file entries.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:ChainstateManager.adoc[ChainstateManager]`
| Interface for managing multiple Chainstate objects, where each chainstate is associated with chainstate* subdirectory in the data directory and contains a database of UTXOs existing at a different point in history. (See the Chainstate class for more information.)
| `xref:Chainstate.adoc[Chainstate]`
| Chainstate stores and provides an API to update our local knowledge of the current best chain.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:CheckBlockDataAvailability.adoc[`::CheckBlockDataAvailability`]
| Check that a block's data (and optionally undo data) is available on disk.
| xref:GetPruneHeight.adoc[`::GetPruneHeight`]
| Return height of highest block that has been pruned, or std::nullopt if no blocks have been pruned
| xref:blockToJSON.adoc[`::blockToJSON`]
| Block description to JSON
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#