Skip to content

Conversation

@DracoLi
Copy link
Contributor

@DracoLi DracoLi commented Nov 10, 2025

Why this should be merged

Allows EVM block data to be moved out of the key-value database into dedicated height-indexed databases that are better suited for block storage. This reduces KV usage and lowers compaction impact.

  • Headers, bodies, and receipts are stored in heightindexdb; all other data remains in the underlying KV database.
  • I observed ~20% reduction in KV (LevelDB/PebbleDB) size → fewer/smaller compactions and steadier node performance.

Part of #4491

How this works

The blockdb.Database routes block data by key prefix, while keeping non-block data on the KV store.

  • Keys for header/body/receipts are routed to height-indexed DBs when height ≥ the height-indexed DB minimum height; below that, they use the KV store.
  • Accepted blocks only: the database stores a single block per height. Writing at an occupied height overwrites the previous value. Deletes of block data are no-op.
  • During migration, reads fall back to the KV store when a block is missing in height-indexed DBs.
  • Batching: block keys bypass the KV batch and are written directly to the height-indexed DBs; non-block keys are accumulated and written via the underlying KV batch.
  • Deferred init: if allowDeferredInit is enabled, the database can be initialized when the minimum block height is known (useful with state sync). The min height is then persisted and cannot be changed without recreating the block databases.
  • Once blockdb is enabled, it should not be disabled.

Migrations

On initialization, the database starts migrating canonical block data from the KV store to the height-indexed databases in the background.

  • Migrates headers, bodies, and receipts for canonical blocks only; genesis is skipped.
  • Cleanup: When blocks are migrated, its KV entries are deleted in batches; header/body/receipt ranges are periodically compacted.
  • Periodic logs include status and ETA.
  • Migration can be paused and resumed safely.
  • If the node crashes or terminated, migration can be resumed automatically on restart.
  • Migrating 71m blocks on an archive node took ~5 hours.

How this was tested

  • Unit tests for routing and migration behaviour.
  • Multiple mainnet nodes ran with blockdb running for weeks.
  • C-Chain migrations at 1M/10M/20M/71M via re-execution and live nodes.
  • Verified identical block data from nodes with and without blockdb.

Need to be documented in RELEASES.md?

No

@DracoLi DracoLi moved this to In Progress 🏗️ in avalanchego Nov 10, 2025
@DracoLi DracoLi self-assigned this Nov 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress 🏗️

Development

Successfully merging this pull request may close these issues.

2 participants