IBD UTXO engine

Sync tuning guide

First mainnet sync always starts from First Node Setup: Mainnet IBD (release IBD example config). For other IBD topics, use the operator IBD hub or:

TopicPage
Parallel download, pipelining, assume-validPerformance optimizations
[ibd] keys and BLVM_IBD_*Configuration reference: IBD
Serving-side bandwidth limitsIBD bandwidth protection
LAN Core / same-subnet peersLAN peering

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.

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.

Operator notes

  • Use the same storage.data_dir on every run; do not delete the active database backend directory (heed3/, rocksdb/, …) mid-sync.
  • On SIGTERM / SIGINT during parallel IBD, the node drains in-flight validation and flushes the UTXO watermark before exit when possible.
  • io_uring accelerates engine table I/O on Linux; other platforms use a pread fallback (engine still runs on Windows).
  • Assume-valid skips signature verification below a configured height; block structure, Merkle roots, and proof-of-work are still checked.
  • First mainnet sync: First Node Setup: Mainnet IBD. 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.

Source

See Also