Erigon v3 performance tuning: the critical role of prune distance and 8k page size

This article explores the core mechanisms within the Erigon v3 Ethereum client that govern performance and stability, focusing on the configuration parameters prune.distance and db.pagesize. Proper tuning of these settings is essential for maintaining a stable, production-grade node, particularly under heavy load.

The asynchronous commit window in Erigon v3

Erigon v3 operates on a highly optimised, asynchronous pipeline composed of three main systems [1]:

• Executor — runs blocks and mutates the state of the EVM.
• Committer — flushes the newly executed state changes into the underlying MDBX database.
• Pruner — deletes old state data that falls outside the defined prune horizon.

These three systems do not operate in lockstep. The pipeline maintains a sequential flow of data and state:

HEAD
  ↓
Executed (by Executor)
  ↓
Committed (by Committer)
  ↓
Prune Horizon (managed by Pruner)

A gap naturally exists between the execution, commit and prune stages. This gap is dynamic and can grow significantly due to factors such as batch size, RPC pressure, snapshot activity, WAL flushes, and random I/O latency.

Understanding prune.distance

The --prune.distance flag is often misunderstood as a measure of how far a node can lag behind the network tip. In reality its function is more critical:

--prune.distance defines the maximum amount of committed state history Erigon is allowed to keep alive. [1]

This value is expressed in the number of blocks. It sets a safety buffer for the node's internal operations. If the prune horizon — the point at which the Pruner is actively deleting old state — advances past the last successfully committed state, a critical failure occurs.

Specifically, if the prune_horizon exceeds the last_committed_state, the Pruner will delete trie nodes that were never safely flushed to the database. The node will continue to run, but the necessary anchor trie root is lost. Upon restart, Erigon will be forced to replay a massive portion of the chain history, resulting in a multi-day recovery process.

Therefore, the only rule that ensures stability is to set the prune distance large enough to absorb all potential internal lag:

Prune Distance > (Max Commit Lag + Prune Lag + Safety Window)

The necessity of 8k MDBX pages

Ethereum's state is characterised by millions of small data objects, typically tens to hundreds of bytes, which represent the state of accounts and storage slots. The MDBX database, which Erigon uses for storage, operates with a fixed page size — the smallest unit of I/O [1].

The choice of page size directly impacts write amplification, a key metric for database performance and SSD longevity.

An interesting snippet from the erigon help command, which is not present in the online docs at docs.erigon.tech:

--db.pagesize value

DB is split into pages. Can be ... Must be a power of 2 and ...
Default: equal to Operating System page size.

Bigger pageSize causes:
1. More writes to disk during commit
2. Smaller b-tree height
3. Less fragmentation
4. Less overhead on ...
5. If expecting DB size > 8 Tb, set pageSize >= 8 Kb (default: "16KB")

The notable detail here: the default is taken from the operating system's page size, which by default is 4K — at least on a default Ubuntu 22.04 installation.

How page size plays against pruning and write amplification:

• Large (16k–32k). Deleting a small trie node (e.g. 200 bytes) can force a rewrite of the entire 16 KB or 32 KB page, producing heavy write amplification. Prune falls behind commit, increasing the risk of pipeline instability and data loss.
• 8k (recommended). Aligns with trie locality and the size distribution of state objects, minimising dead space within pages. It keeps the Pruner light and allows the Committer to stay close to the chain head, ensuring a stable pipeline.

The use of 8k pages is a fundamental design choice in Erigon v3 to optimise storage and I/O for the specific nature of the Ethereum state tree [2].

Practical tuning profiles for a full-prune Erigon v3

The following are safe, production-grade starting points for configuring a full-prune Erigon node. Increase prune.distance when the node experiences higher-than-average RPC or batch processing pressure.

1. ARM / light-RPC profile (e.g. 16 vCPU, 32–64 GB RAM, NVMe)

Suitable for nodes with moderate read-heavy traffic (e.g. eth_call, filters) which can still churn the trie via reads.

--prune.mode=full          Standard full-prune mode
--prune.distance=131072    ~18 days of state history — a wide safety buffer
--db.pagesize=8k           Minimises write amplification
--batchSize=256mb          Moderate batch size for balanced performance
--state.cache=3-6GB        Adequate cache for hot state data

2. x86 / heavy-RPC or fast-sync profile (e.g. 32–64 vCPU, 128 GB RAM, NVMe)

Designed for high-throughput environments where large batches, torrent syncs or high WAL spikes can create significant commit lag.

--prune.mode=full          Standard full-prune mode
--prune.distance=256000    ~35 days of state history — Pruner safely behind the Committer
--db.pagesize=8k           Minimises write amplification
--batchSize=1GB            Large batch size to amortise write costs
--state.cache=8-16GB       Large cache to handle high state access

3. Minimal compute profile (e.g. 8 vCPU, 32 GB RAM, NVMe)

The minimum recommended configuration for a stable full-prune node.

--prune.mode=full          Standard full-prune mode
--prune.distance=65536     ~9 days of state history — the minimum sane safety window
--db.pagesize=8k           Minimises write amplification
--batchSize=128-256mb      Smaller batches reduce lag on lower-spec hardware
--state.cache=2-4GB        Minimal cache size

4. Archive node configuration (no pruning)

An archive node retains all historical state, so the Pruner is effectively disabled. This eliminates the prune race condition, at the cost of substantially higher I/O and disk requirements.

--prune.mode=archive       Disables all state deletion
--db.pagesize=8k           Still crucial to minimise write amplification during sync/compaction
--batchSize=1GB            Large batch size to amortise massive historical writes
--state.cache=8-32GB       Keep frequently accessed historical state in RAM

Archive nodes require multi-terabyte disk capacity but provide full historical state access for complex queries like trace and getLogs over long ranges.

Disk sizing formulas

The following formulas provide a reliable estimate for the extra disk space required by a given prune window on Ethereum mainnet, based on Erigon v3 full-prune best practice [3].

The rule of thumb for state history growth:

State history per block ≈ 300 KB/block

This figure is used for safe planning, accounting for a range of 250–350 KB/block.

Extra disk space from prune.distance. The total extra disk space required (in GB) to accommodate the specified prune.distance:

Extra Disk (GB) ≈ (prune.distance × 300 KB) / 1024 / 1024

For the common settings:

prune.distance | approx. time | extra disk (GB)
---------------+--------------+-----------------
65,536         | ≈ 9 days     | ≈ 19 GB
131,072        | ≈ 18 days    | ≈ 38 GB
256,000        | ≈ 35 days    | ≈ 73 GB
512,000        | ≈ 70 days    | ≈ 146 GB

Total database size estimate. The total disk space required for the Erigon database:

DB Total ≈ Base Pruned DB + Extra Disk from Prune + Safety Margin

• Base pruned DB: the size of the database at minimal pruning — typically 1.2–1.4 TB on mainnet as of January 2026.
• Safety margin: an additional 5–10% for WAL, snapshots and compaction overhead.

For a node configured with a prune.distance of 256,000:

1.30 TB (base) + 0.07 TB (prune) + 0.10 TB (margin) ≈ 1.47 TB

This small investment in disk space buys significant crash tolerance. A 70 GB increase in disk capacity can prevent a multi-day chain replay and massive, unnecessary SSD write amplification.

Conclusion: crash tolerance, not just tuning

The fundamental takeaway is that prune distance is a measure of crash tolerance, not merely a disk tuning parameter. It must be chosen to be larger than your worst-case internal pipeline lag.

By coupling a sufficiently large prune.distance with the optimised 8k page size, Erigon is transformed from a system vulnerable to internal race conditions into a stable, high-performance, production-grade Ethereum node.

References

1. CLI Reference | Erigon 3
2. Erigon v3.3: Introducing the Historical Proofs Data Model
3. Erigon v3 performance tuning best practices, derived from running production full-prune and archive nodes on mainnet.