IBD UTXO engine

Overview

During parallel initial block download (IBD), the node validates blocks in height order while downloading from one or more peers. By default, UTXO updates use the legacy in-process store. When enabled, an age-tiered UTXO engine holds live UTXOs in memory and on disk under storage/ibd_engine/, with mid-sync checkpoints for crash-safe resume.

Enable the engine only when you understand checkpoint storage and disk use. The release mainnet IBD example config does not turn it on.

Code: ibd_engine/, parallel_ibd/validation_loop.rs

Enable

Set before starting sync:

export BLVM_IBD_ENGINE=1

Optional environment variables:

VariablePurpose
BLVM_IBD_ENGINE_PATHDirectory for engine table files (default: temp dir per process)
BLVM_IBD_CHECKPOINT_INTERVALFixed block interval for mid-IBD checkpoint export (engine mode)
BLVM_IBD_DEFER_CHECKPOINT_INTERVALRAM-tier default override for deferred checkpoint spacing
BLVM_IBD_EXPORT_HEIGHT_OVERRIDEForce resume/export from a specific height (recovery / tests)

Download scheduling still uses parallel IBD ([ibd].mode = "parallel"). The engine replaces how validated blocks apply UTXO changes during that pipeline.

Architecture

  1. Index and table — Age-tiered structures track live UTXOs and support fast spend lookups during validation.
  2. Spend session — Batches spend/create operations per block and feeds the engine from the validation loop.
  3. Checkpoint export — Periodic snapshots of engine state allow resume after interruption without re-downloading from genesis.
  4. Import / seed — On restart, the node seeds validation from the last exported checkpoint height when present.

Code: ibd_engine/mod.rs, spend_session.rs, export.rs

Operator notes

  • Use the same storage.data_dir on every run; do not delete rocksdb/ mid-sync.
  • Assume-valid skips signature verification below a configured height; block structure, Merkle roots, and proof-of-work are still checked.
  • For tarball mainnet sync, follow Mainnet initial sync. Tune [ibd] in config or BLVM_IBD_* overrides only when you need explicit peer or mode control.

Configuration

See IBD Configuration for [ibd] keys and BLVM_IBD_* environment variables shared with parallel download.

See Also