Struct ChainstateManagerBuilder 

pub struct ChainstateManagerBuilder { /* private fields */ }

Builder for configuring and creating a ChainstateManager.

Provides a fluent interface for configuring how the chainstate manager will initialize and operate. Options control database locations, in-memory operation, worker thread allocation, and database initialization behavior.

Usage

Create a builder using ChainstateManager::builder, configure options by chaining method calls, then call build to create the chainstate manager.

Example

use bitcoinkernel::{ChainType, ChainstateManager, ContextBuilder, KernelError};

let context = ContextBuilder::new()
    .chain_type(ChainType::Regtest)
    .build()?;

let chainman = ChainstateManager::builder(&context, "/data", "/blocks")?
    .worker_threads(4)
    .chainstate_db_in_memory(true)
    .block_tree_db_in_memory(true)
    .build()?;

Implementations

impl ChainstateManagerBuilder

pub fn new( context: &Context, data_dir: &str, blocks_dir: &str, ) -> Result<Self, KernelError>

Creates a new chainstate manager builder.

This is typically called via ChainstateManager::builder rather than directly.

Arguments

• context - The Context that configures chain parameters and notification callbacks. It is recommended to keep the context in scope for the lifetime of the ChainstateManager.
• data_dir - Path to the directory where chainstate data will be stored. This includes the UTXO set database and other chain state information.
• blocks_dir - Path to the directory where block data will be stored. This includes the raw block files and the block index database.

Errors

Returns KernelError if:

• The paths contain null bytes (invalid C strings)
• The underlying C++ library fails to create the builder

pub fn worker_threads(self, worker_threads: i32) -> Self

Sets the number of worker threads for validation.

Block validation can be parallelized across multiple threads to improve performance. More threads generally result in faster validation, but with diminishing returns beyond the number of available CPU cores.

Arguments

• worker_threads - Number of worker threads to use for validation. Valid range is 0-15 (values outside this range are clamped). When set to 0, no parallel verification is performed.

pub fn wipe_db( self, wipe_block_tree: bool, wipe_chainstate: bool, ) -> Result<Self, KernelError>

Configures database wiping behavior.

When enabled, this will delete and recreate the specified databases on initialization. After wiping, ChainstateManager::import_blocks will trigger a reindex to rebuild the databases from the block files.

Arguments

• wipe_block_tree - If true, wipe the block tree database (block index). Must be false if wipe_chainstate is false.
• wipe_chainstate - If true, wipe the chainstate database (UTXO set)

Reindex Behavior

• Wiping both databases triggers a full reindex
• Wiping only the chainstate triggers a chainstate-only reindex

Errors

Returns KernelError::InvalidOptions if wipe_block_tree is true but wipe_chainstate is false, as this combination is currently unsupported.

Examples

// Wipe both databases for a full reindex
let chainman = ChainstateManager::builder(&context, "/data", "/blocks")?
    .wipe_db(true, true)?
    .build()?;

// Only wipe chainstate (e.g., to rebuild UTXO set)
let chainman = ChainstateManager::builder(&context, "/data", "/blocks")?
    .wipe_db(false, true)?
    .build()?;

pub fn block_tree_db_in_memory(self, block_tree_db_in_memory: bool) -> Self

Configures the block tree database to run entirely in memory.

When enabled, the block tree database (which stores the block index and metadata about all known blocks) will be stored in RAM rather than on disk. This can improve performance but requires sufficient memory and means the database will be lost when the process exits.

Arguments

• block_tree_db_in_memory - If true, run the block tree database in memory

pub fn chainstate_db_in_memory(self, chainstate_db_in_memory: bool) -> Self

Configures the chainstate database to run entirely in memory.

When enabled, the chainstate database (which stores the current UTXO set) will be stored in RAM rather than on disk. This can significantly improve performance but requires substantial memory (several gigabytes for mainnet) and means the database will be lost when the process exits.

Arguments

• chainstate_db_in_memory - If true, run the chainstate database in memory

Example

// Use in-memory chainstate for fast testing
let chainman = ChainstateManager::builder(&context, "/data", "/blocks")?
    .chainstate_db_in_memory(true)
    .build()?;

pub fn build(self) -> Result<ChainstateManager, KernelError>

Builds the ChainstateManager with the configured options.

Consumes the builder and creates a new chainstate manager instance.

Errors

Returns KernelError::Internal if the underlying C++ library fails to create the chainstate manager.

Trait Implementations

impl Drop for ChainstateManagerBuilder

fn drop(&mut self)

Executes the destructor for this type.