Struct StoreConfig 

pub struct StoreConfig {

    pub data_dir: PathBuf,
    pub shards_count: Option<usize>,
    pub initial_capacity: Option<usize>,
    pub thread_count: usize,
    pub durability_mode: DurabilityMode,
    pub snapshot_interval: Duration,
    pub max_snapshot_interval: Duration,
    pub compress_journal: bool,
    pub journal_compression_level: i32,
    pub journal_chunk_size_bytes: u64,
    pub lmdb_map_size: usize,
    pub enable_server: bool,
    pub remote_server: Option<RemoteServerSettings>,
    pub min_rollback_window: BlockId,
    pub prune_interval: Duration,
    pub bootstrap_block_profile: u64,
}

Configuration for initializing the store (including the embedded remote server).

Fields

data_dir: PathBuf

Base directory for all store data

shards_count: Option<usize>

Number of shards for the state engine (required when creating a new store)

initial_capacity: Option<usize>

Initial capacity of each shard (required when creating a new store)

thread_count: usize

Number of threads for parallelism (if > 1, uses parallel mode)

durability_mode: DurabilityMode

Durability mode for persistence (synchronous vs async)

snapshot_interval: Duration

Interval between automatic snapshots when async durability is enabled

max_snapshot_interval: Duration

Maximum time allowed between snapshots (forces a snapshot when exceeded)

compress_journal: bool

Whether to compress journal payloads on disk

journal_compression_level: i32

Compression level for zstd (when compression enabled)

journal_chunk_size_bytes: u64

Maximum size of a single journal chunk before rotation.

lmdb_map_size: usize

LMDB map size in bytes (default: 2GB, sufficient for Bitcoin and testnets)

enable_server: bool

Whether to launch the embedded remote server managed by the facade.

remote_server: Option<RemoteServerSettings>

Optional remote server configuration (paired with enable_server).

min_rollback_window: BlockId

Minimum rollback window retained on disk. BlockId::MAX disables pruning.

prune_interval: Duration

Interval between background pruning passes.

bootstrap_block_profile: u64

Bootstrap estimate of blocks per chunk before history accumulates.

Implementations

impl StoreConfig

pub fn new( data_dir: impl AsRef<Path>, shards_count: usize, initial_capacity: usize, thread_count: usize, use_compression: bool, ) -> StoreResult<Self>

Creates a new store configuration for initializing a fresh data directory.

Arguments

• data_dir - Base directory for all store data (metadata, journal, snapshots)
• shards_count - Number of shards for parallel processing (recommended: 4-16)
• initial_capacity - Initial capacity per shard (should account for expected entries)
• thread_count - Number of threads for parallelism (1 = sequential, >1 = parallel)
• use_compression - Whether to compress journal payloads (default: false)

Durability

New configurations default to DurabilityMode::Async { max_pending_blocks: 1024 }, which acknowledges blocks as soon as they enter the persistence queue. Call StoreConfig::with_durability_mode with DurabilityMode::Synchronous (or invoke crate::facade::SimpleStoreFacade::disable_relaxed_mode at runtime) if you require an fsync after every block.

Errors

Returns StoreError::InvalidConfiguration if:

• shards_count is 0
• initial_capacity is 0
• thread_count is 0

Examples

use rollblock::StoreConfig;

// Basic configuration
let config = StoreConfig::new("./data", 4, 1000, 1, false)?;

// High-performance configuration
let config = StoreConfig::new("./data", 16, 1_000_000, 8, false)?;

pub fn existing(data_dir: impl AsRef<Path>) -> Self

Creates a store configuration for opening an existing data directory.

Shard layout information will be loaded from metadata. You may call StoreConfig::with_shard_layout if you need to override the detected values.

pub fn existing_with_lmdb_map_size( data_dir: impl AsRef<Path>, map_size: usize, ) -> Self

Creates a store configuration for an existing data directory with a custom LMDB map size.

This avoids temporarily expanding the LMDB file to the default 2 GiB before the recorded map size is loaded, which is particularly helpful in tests that rely on small temp dirs.

pub fn with_shard_layout( self, shards_count: usize, initial_capacity: usize, ) -> StoreResult<Self>

Provides explicit shard layout information. Useful when opening older stores that were created before shard layout metadata was persisted.

Errors

Returns StoreError::InvalidConfiguration if shards_count or initial_capacity is 0.

pub fn with_durability_mode(self, mode: DurabilityMode) -> Self

pub fn with_snapshot_interval(self, interval: Duration) -> Self

pub fn with_max_snapshot_interval(self, interval: Duration) -> Self

Sets the maximum lag allowed between snapshots. Setting this to zero disables the forced snapshot safeguard.

pub fn with_journal_compression(self, enabled: bool) -> Self

pub fn with_journal_compression_level(self, level: i32) -> Self

pub fn with_journal_chunk_size(self, bytes: u64) -> Self

Sets the maximum on-disk size for a single journal chunk before rotation.

Values below the size of a single entry (header + minimal payload) are clamped when the journal is initialized, so tests may supply tiny values to stress rotation.

pub fn with_min_rollback_window(self, window: BlockId) -> StoreResult<Self>

pub fn with_prune_interval(self, interval: Duration) -> StoreResult<Self>

pub fn with_bootstrap_block_profile( self, blocks_per_chunk: u64, ) -> StoreResult<Self>

pub fn with_async_max_pending(self, max_pending_blocks: usize) -> Self

pub fn with_async_relaxed( self, max_pending_blocks: usize, sync_every_n_blocks: usize, ) -> Self

Configures the store to use relaxed async durability.

This mode syncs to disk every sync_every_n_blocks blocks instead of every block, significantly improving throughput at the cost of increased data loss window.

Arguments

• max_pending_blocks - Maximum blocks that can be queued for persistence
• sync_every_n_blocks - Number of blocks between fsync calls

Example

let config = StoreConfig::new("./data", 4, 1000, 1, false)?
    .with_async_relaxed(1024, 100); // Sync every 100 blocks

pub fn with_lmdb_map_size(self, size: usize) -> Self

Sets the LMDB map size in bytes.

The map size determines the maximum size of the metadata database. Default is 2GB which is sufficient for Bitcoin and all its testnets.

Examples

// For high-frequency blockchains (e.g., Polygon)
let config = StoreConfig::new("./data", 4, 1000, 1, false)?
    .with_lmdb_map_size(10 << 30); // 10GB

pub fn with_remote_server(self, settings: RemoteServerSettings) -> Self

Enables or customizes the embedded remote server that SimpleStoreFacade::new manages automatically. Calling this method also flips StoreConfig::enable_server to true.

pub fn enable_remote_server(self) -> StoreResult<Self>

Enables the embedded remote server using the current settings.

Returns an error if the remote server settings were previously removed with StoreConfig::without_remote_server.

pub fn disable_remote_server(self) -> Self

Disables the embedded remote server but keeps the settings in place.

pub fn without_remote_server(self) -> Self

Disables the embedded remote server entirely (useful for tests or standalone benchmarking binaries) and removes all stored settings.

pub fn remote_server(&self) -> Option<&RemoteServerSettings>

Returns the remote server settings, if configured.

pub fn metadata_dir(&self) -> PathBuf

Returns the path to the metadata directory.

pub fn journal_dir(&self) -> PathBuf

Returns the path to the journal directory.

pub fn snapshots_dir(&self) -> PathBuf

Returns the path to the snapshots directory.

Trait Implementations

impl Clone for StoreConfig

fn clone(&self) -> StoreConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StoreConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.