Chain State Management

When running an EVM-based blockchain (C-Chain or Subnet-EVM L1s), your node stores blockchain state on disk. Understanding the difference between active state and archive state is crucial for managing disk space and choosing the right sync method.

Active State vs Archive State

Active State

The active state represents the current state of the blockchain—all account balances, contract storage, and code as of the latest block. This is what your node needs to validate new transactions and participate in consensus.

Archive State (Total State)

The archive state includes the complete history of all state changes since genesis. This allows querying historical state at any block height (e.g., "What was this account's balance at block 1,000,000?").

Why State Grows Over Time

Even if you start with just the active state, your node's disk usage will grow over time:

1. New blocks: Each block adds new state changes
2. State trie overhead: The Merkle Patricia Trie structure stores intermediate nodes
3. Deleted state retention: Old trie nodes aren't automatically removed

This means a node that started with 500 GB via state sync might grow to 1 TB+ over months of operation, even though the "current" active state is still ~500 GB.

State Growth Visualization

Understanding the Chart:

• Total State (solid red line): Grows faster over time as historical state data accumulates

  • Includes both current state and all historical intermediate trie nodes
  • Always larger than active state due to storage overhead

• Active State (solid blue line): Grows at a slower, steady rate

  • Represents only the current blockchain state needed for validation

• Total State After Pruning / Resync (dotted red line): Shows state growth after performing maintenance

  • Starts fresh from active state level after pruning or resync
  • Continues to grow at the same rate as total state

• Resync/Offline Pruning (vertical grey dotted line): The maintenance operation that reduces disk usage

  • Removes accumulated historical data
  • Brings total state back down close to active state level

Managing Disk Usage

Option 1: State Sync (Re-sync)

The simplest way to reclaim disk space is to delete your node's data and re-sync using state sync. Instead of replaying the entire blockchain history to reconstruct the current state, state sync allows nodes to download only the current state directly from network peers. This shortens the bootstrap process from multiple days to just a couple of hours.

State sync is ideal for:

• Validator nodes that don't need full transaction history
• RPC nodes focused on current state queries
• Any node where historical data queries are not required

Configuring State Sync

State sync is enabled by default for the C-Chain. For Avalanche L1s, you can configure it per-chain:

• C-Chain configuration: See C-Chain Config
• Avalanche L1 configuration: See Subnet-EVM Config

# Stop your node first
sudo systemctl stop avalanchego

# Remove the database (adjust path as needed)
rm -rf ~/.avalanchego/db

# Restart - node will state sync automatically
sudo systemctl start avalanchego

Option 2: Offline Pruning

Offline pruning removes old state trie nodes while keeping your node's database intact. This is faster than a full re-sync but requires temporary additional disk space.

See the Reduce Disk Usage guide for detailed instructions.

Choosing the Right Approach

Monitoring Disk Usage

Track your node's disk usage over time to plan maintenance:

# Check database size
du -sh ~/.avalanchego/db

# Check available disk space
df -h /

Consider setting up alerts when disk usage exceeds 80% to give yourself time to plan maintenance.

P-Chain and X-Chain State

The P-Chain and X-Chain have significantly smaller state footprints compared to the C-Chain:

• P-Chain: Stores validator metadata, Avalanche L1 definitions, and staking transactions. State size is typically < 10 GB and grows very slowly.
• X-Chain: Handles AVAX transfers using the UTXO model. State size is typically < 50 GB and grows slowly.

Important limitations:

• State sync is not available for P-Chain or X-Chain
• These chains always sync from genesis by replaying all transactions
• Bootstrap time is faster than C-Chain despite no state sync due to much smaller state size (typically < 1 hour)
• Disk space management is rarely needed for these chains

L1-Specific Considerations

For Avalanche L1s running Subnet-EVM:

• State size scales with usage: High-throughput chains accumulate state faster
• Same pruning tools apply: Offline pruning works identically to C-Chain
• State sync available: Configure via Subnet-EVM chain config
• Plan storage accordingly: Reference the system requirements for your throughput tier