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, the age-tiered UTXO engine holds live UTXOs in memory and on disk under <data_dir>/ibd_engine/, with mid-sync checkpoints for crash-safe resume. The legacy in-process store remains available as an opt-out.

Enable (default)

The engine is on by default. Stable table path: <data_dir>/ibd_engine/utxo_table.bin (override with BLVM_IBD_ENGINE_PATH).

Opt-out:

export BLVM_IBD_ENGINE=0

[ibd] utxo_engine = false does the same. BLVM_IBD_ENGINE wins over the file.

Optional environment variables:

VariablePurpose
BLVM_IBD_ENGINE_PATHPath to the engine flat table (default: <data_dir>/ibd_engine/utxo_table.bin)
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 height only when it is at least the stored export height. An override below that height is ignored. start-ibd-mainnet.sh strips an inherited override unless BLVM_ALLOW_EXPORT_HEIGHT_OVERRIDE=1.

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 the configured height when the hash is set and chainwork meets the minimum. The mainnet seed sets that hash at height 912683. 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