Skip to content

csnode, csdb: pruned storage - #22

Merged
EnzinoBB merged 4 commits into
masterfrom
feat/pruned-storage
Oct 11, 2026
Merged

EnzinoBB merged 4 commits into
masterfrom
feat/pruned-storage

Conversation

@EnzinoBB

Copy link
Copy Markdown
Collaborator

What this adds

A node can keep only the blocks it needs. The option is [storage] prune_keep_blocks=N, off by default (0); nodes without it behave exactly as before.

The quick-start checkpoint already holds the whole state: balances, delegations and contracts. Validating and applying a new block then needs only the recent blocks; contracts refer back at most 100 rounds. So after each periodic checkpoint C, the node removes the blocks before C - checkpoint_every - N. This keeps the previous checkpoint usable, plus a margin of N blocks.

  • csdb
    • Storage::pool_prune removes an old block: the block record and its hash index.
    • Storage::first_sequence reports the oldest block still stored.
    • Storage::compact gives the freed pages back to the file system (DB->compact with DB_FREE_SPACE). The new Database::compact defaults to a no-op.
  • Scheduling. BlockChain schedules the pruning after a periodic checkpoint. It carries it out 64 blocks at a time after each block applied live, then compacts. While the storage is read at start-up it only schedules, because a cursor is walking the file.
  • No slow start on a pruned storage. A pruned storage starts after block 0. A slow start would replay the remaining blocks onto empty caches, so Storage::rescan refuses it and asks for a quick-start checkpoint instead.
  • Contracts. After a quick start, a contract state whose block was pruned is kept and counted as unverifiable, instead of being invalidated.
  • Config checks. Pruning requires checkpoint_every. It raises checkpoint_keep to at least 2 and prune_keep_blocks to at least 200.

A pruned node takes the Trusted role like any other node. An earlier version refused it, and the test network showed why that cannot work: the pruned node was in the initial trusted set, round 1 waited for its stages, and no block was ever written.

Limits (follow-ups)

  • A pruned node cannot serve old blocks to syncing peers; it skips them, as for any missing block. Nor can it serve the full transaction history through the API.
  • The transaction index and the sequence→hash table (LMDB) still grow with the history; they are the next step.
  • Rolling back a block that changed a contract's state replays that contract's history, which a pruned node may not have.
  • Checkpoints that already exist on mainnet nodes are unaffected; pruning starts at the first periodic checkpoint written with the option on.

Verification

  • nodetests: 134/134 pass.

  • Private 7-node network (testnet/prune-check = this branch + the prune_node scenario). n7 runs pruned, with a checkpoint every 1,000 blocks and prune_keep_blocks=300, and is restarted at block ~2,520.

    • Run 38066244096, to 4,200 blocks:
      • n7 removed the blocks before 700, 1,700 and 2,700, compacting each time;
      • it restarted from the pruned storage ("oldest block stored is 700") with a quick start;
      • all 7 nodes reported identical state digests. PASS.
    • Run 38069311587, to 3,200 blocks:
      • n7's blockchain.db is 1,608 KB, against 4,420 KB on a full node;
      • its whole DB directory is 6.5 MB, against 14 MB;
      • the digests match. PASS.

    Test-network blocks are nearly empty, so the BerkeleyDB log files weigh as much as the data there.

🤖 Generated with Claude Code

EnzinoBB and others added 3 commits October 10, 2026 15:55
A node can now keep only the blocks it needs. With [storage] prune_keep_blocks=N (0, the
default, keeps every block), after each periodic checkpoint C the blocks before
C - checkpoint_every - N are removed: the previous checkpoint stays usable, and N keeps a margin
above the 100 rounds contracts refer back to. The quick-start checkpoint already holds the whole
state, so these blocks are no longer needed to validate or apply new ones.

- csdb: Storage::pool_prune removes an old block (block record and hash index),
  Storage::first_sequence reports the oldest block stored, and Storage::compact gives the freed
  pages back to the file system (DB->compact with DB_FREE_SPACE; a no-op default in Database).
- BlockChain schedules the pruning after a periodic checkpoint and carries it out 64 blocks at a
  time after each block applied live, then compacts. While the storage is read at start-up it
  only schedules, as a cursor is walking the file.
- A pruned storage starts after block 0, so Storage::rescan refuses a slow start on it (it would
  replay the remaining blocks onto empty caches) and asks for a quick-start checkpoint instead.
- After a quick start, a contract state whose block was pruned is kept as unverifiable instead
  of being invalidated.
- A pruned node does not take the Trusted role for now.

The config needs checkpoint_every, raises checkpoint_keep to 2 and prune_keep_blocks to 200 at
least. Nodes without prune_keep_blocks behave as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refusing the role once the network has picked the node does not make it an observer: the round
waits for its stages. On the test network, with the pruned node in the initial trusted set,
round 1 never completed and no block was written. A pruned node has the whole state (its
checkpoint) and the recent blocks, which is what validating and building blocks needs, so it
now takes the role as any other node.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The LMDB transaction index (one entry per address per block) and the sequence/hash tables of
BlockHashes still grew with the whole history on a pruned node. pruneStep now loads each block
before removing it, drops its transaction index entries (TransactionsIndex::onPruneBlock) and
its BlockHashes entries.

Neither is needed for blocks before the pruning point:
- the transaction index serves the API's walk back through an address's history, which now
  ends at the oldest block stored: getPrevTransBlock answers kWrongSequence for a missing entry,
  as for an address's first transaction, without flagging the index as inconsistent;
- consensus reads block hashes of recent blocks only (the contract seed of the current block,
  the previous round in stage 3, checkpoint heads); the random old block GetSeed picks for
  getters, outside consensus, now hashes an empty value.

LMDB reuses the freed pages, so both stop growing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@EnzinoBB

Copy link
Copy Markdown
Collaborator Author

Update: the transaction index and the BlockHashes tables are now pruned too (commit csnode: prune the transaction index and block hashes too).

The test network found a crash: the pruned node segfaulted as soon as a joining node asked it for blocks it had pruned. The cause is not in this PR. The csmeta(cslog) << "unable to load block " line in Node::getBlockRequest reads past the end of a string with GCC 13. #24 fixes that, so this PR should be merged together with or after #24.

With #24, run 38104614549 passed. It combined pruned n7, restarted at block ~2,500, with n8 joining from block 0 at block 3,526 and requesting pruned blocks from its peers. All 8 nodes report identical digests to block 4,600.

full node pruned n7
blockchain.db 6,308 KB 1,988 KB
seqdb 520 KB 232 KB
hashdb 392 KB 200 KB

Generated by Claude Code

@EnzinoBB
EnzinoBB merged commit 55cd176 into master Oct 11, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant