Ancient Store and Data Lifecycle

Purpose and Scope

This document describes the ancient store subsystem (commonly referred to as the “freezer”) in go-stablenet and how it manages the storage lifecycle of historical blockchain data. The ancient store is an append-only archive storage layer that separates and preserves old block data in order to optimize performance and disk usage of the active database. This page covers:

Ancient store architecture and its separation of roles from the active database
Data migration flow from the active store to the ancient store
Ancient store operations (read, write, truncate)
Chain rewind handling when frozen data exists
Importing and exporting historical data using the Era1 format

For the active database layer and trie storage, see Database Layer and Merkle Patricia Trie.
For caching and snapshots, see Caching and Snapshots.

Ancient Store Architecture

The ancient store is a dedicated storage for historical blockchain data that has become immutable.
This layer is designed to improve performance and disk efficiency with the following characteristics:

Append-only write model
Sequential access by block number
Physical and logical separation from the active key-value database
Minimized random-access cost for old data

Storage Layers

Blockchain data is divided into two main layers:

Active Database
Recent blocks, state (tries), headers, transaction indices, and other data
that require frequent random access and writes
Ancient Store
Blocks, receipts, and total difficulty data that are sufficiently old and no longer mutable

Database Interface

The ethdb.Database interface provides a unified access point for both the active and ancient stores:

Method	Description	Storage Layer
`Ancients()`	Returns the number of frozen blocks	Ancient store
`TruncateHead(n)`	Removes ancient data after block `n`	Ancient store
`Get(key)` / `Put(key, val)`	Key-value read/write	Active database
`NewBatch()`	Create a batch write	Active database

Although accessed via the same DB handle, the ancient store uses a separate internal implementation optimized for sequential, immutable data.

Data Lifecycle and Migration

Block Data States

Blockchain data transitions through the following stages depending on block age and state availability:

Active State
Recent blocks that must support state (trie) access and rewinds
Transitional State
State is no longer needed, but data has not yet moved to the ancient store
Frozen State
State access is no longer required; data is considered immutable and stored in the ancient store

Freezer Threshold

The freezer threshold defines the point at which blocks are migrated to the ancient store.
Blocks below this threshold are considered ineligible for state recovery during rewinds. Key considerations:

State availability
Blocks requiring state (tries) must remain in the active database
TriesInMemory constant
Typically, the most recent ~128 blocks are kept in the active DB
Snap synchronization
During snap sync, the pivot block may affect the freezer boundary
Full synchronization
Once state is no longer required, old blocks are migrated sequentially

Ancient Store Operations

Reading Ancient Data

When accessing old blocks, the BlockChain logic transparently reads data from the ancient store. From the perspective of higher layers, there is no need to explicitly distinguish whether data resides in the active DB or the ancient store.

Writing and Truncation

Modifications to the ancient store occur only in limited scenarios:

Chain rewind (SetHead)
When rewinding below the frozen threshold
Historical data import
When injecting past data via Era1 archives

TruncateHead removes data after a given block number from the ancient store.

Chain Rewind with Ancient Data

Rewind Process

When rewinding the chain (SetHead, SetHeadWithTimestamp),
special handling is required for frozen data.

Scenario	Active DB Action	Ancient Store Action
Target above freezer threshold	Delete active blocks/headers	None
Target below freezer threshold	Delete all active blocks	Truncate ancient store
Rewind to genesis	Reset active DB	Remove all ancient data

This logic is implemented in the setHeadBeyondRoot flow.

Handling Missing State

During rewind, the system must locate a block with available state:

Check HasState(root) or stateRecoverable(root)
If state is missing, move to the parent block
Rewinds below the snap pivot are prohibited
If recoverable, attempt triedb.Recover(root)

Safety of Ancient Truncation

Ancient truncation follows strict safety rules:

Executed via a single TruncateHead call
Active DB cleanup performed first
Hash/number mappings of removed blocks deleted
Chain head markers updated atomically

Importing and Exporting Historical Data

Era1 Archive Format

go-stablenet uses the Era1 format to bundle historical blockchain data.

Component	Content	Purpose
Era Archive	~8192 blocks	Sequential storage unit
Block Data	Header, Body, Tx	Block reconstruction
Receipts	Transaction receipts	Execution result verification
Total Difficulty	Cumulative difficulty	Chain weight calculation
Root Hash	Era Merkle root	Integrity verification

Import Process

ImportHistory writes Era1 archives directly into the ancient store.
Since the active DB is bypassed, this enables fast bootstrapping.

Export Process

ExportHistory packages existing chain data into the Era1 format for external storage or distribution.

Direct Ancient Store Initialization

When attaching an external ancient store to an empty node, automatic initialization is performed at startup. This is useful for:

Fast initialization from a trusted archive
Physical separation of ancient and active data
Disaster recovery setups

Integration with BlockChain

BlockChain Structure Fields

type BlockChain struct {
	db ethdb.Database
	triedb *triedb.Database
	stateCache state.Database
	currentBlock atomic.Pointer[types.Header]
	currentSnapBlock atomic.Pointer[types.Header]
	bodyCache *lru.Cache[common.Hash, *types.Body]
	receiptsCache *lru.Cache[common.Hash, []*types.Receipt]
	blockCache *lru.Cache[common.Hash, *types.Block]
}

Ancient Store Query Patterns

Operation	Implementation	Ancient Check
Get block by number	Branch on `Ancients()`	Yes
Header lookup	Active → ancient fallback	Implicit
Chain continuity check	Verify ancient boundary	Yes
State availability check	Ancient blocks have no state	Yes

Interaction with Snap Synchronization

Snap pivot block may lie at the ancient boundary
Receipt chains are filled via InsertReceiptChain
currentSnapBlock and currentBlock may diverge
Snap insertion below the boundary is prohibited

Maintenance Operations

Disk Space Management

Because the ancient store can occupy a large portion of disk space, block count and disk usage should be continuously monitored.

Database Corruption Recovery

Possible causes:

Abnormal shutdown during truncation
Filesystem errors
Manual file modification

Recovery procedure:

Verify ancient count and head at startup
Automatically truncate on mismatch
Manually recover using SetHead if necessary

Best Practices

Operational Guidelines

The ancient store can be backed up while running
Consider placing it on a separate disk for I/O isolation
Monitor ancient block count and disk usage separately
Ancient data is immutable and removed only via truncation

Performance Considerations

Aspect	Recommendation	Rationale
Ancient location	Disk with strong sequential read performance	Append-only access pattern
Active DB	Disk with strong random I/O performance	Frequent reads/writes
Memory	Minimal caching	Low access frequency
Synchronization	Full sync fills naturally	Snap requires separate receipts

StableNet Overview

Getting Started

Core Architecture

Consensus and Block Production

Governance System

Transaction Processing

Networking

RPC and APIs

Storage Architecture

Development Tools

Operations Guide

​Purpose and Scope

​Ancient Store Architecture

​Storage Layers

​Database Interface

​Data Lifecycle and Migration

​Block Data States

​Freezer Threshold

​Ancient Store Operations

​Reading Ancient Data

​Writing and Truncation

​Chain Rewind with Ancient Data

​Rewind Process

​Handling Missing State

​Safety of Ancient Truncation

​Importing and Exporting Historical Data

​Era1 Archive Format

​Import Process

​Export Process

​Direct Ancient Store Initialization

​Integration with BlockChain

​BlockChain Structure Fields

​Ancient Store Query Patterns

​Interaction with Snap Synchronization

​Maintenance Operations

​Disk Space Management

​Database Corruption Recovery

​Best Practices

​Operational Guidelines

​Performance Considerations