How to Configure Pruning Options for Reth on a Base Node

Configure pruning options for Reth on a Base node by setting the RETH_PRUNING_ARGS environment variable in your .env.mainnet or .env.sepolia file, which the reth/reth-entrypoint script automatically appends to the node start command.

Running a Base node with Reth requires careful storage management as the chain grows. Pruning allows you to retain only recent blockchain data, significantly reducing disk usage while maintaining full node functionality. This guide explains how to configure pruning options for Reth on a Base node using the official base/node repository configuration files.

Understanding Reth Pruning on Base

Reth implements a distance-based pruning model that removes historical data older than a specified number of blocks. When you configure pruning, you define how many blocks of history to retain for specific data categories such as receipts, transaction lookups, and account history.

The pruning logic is injected at runtime through the reth/reth-entrypoint script. At lines 49-53, the script checks for the RETH_PRUNING_ARGS environment variable and appends its value to the node's startup arguments:

# Add pruning for base

if [[ "${RETH_PRUNING_ARGS+x}" = x ]]; then
    echo "Adding pruning arguments: $RETH_PRUNING_ARGS"
    ADDITIONAL_ARGS="$ADDITIONAL_ARGS $RETH_PRUNING_ARGS"
fi

Pruning Configuration File Locations

Environment Files

Pruning configuration resides in the environment-specific .env files located in the repository root. You must edit the file corresponding to your target network:

• .env.mainnet — For Base Mainnet nodes (see lines 96-104)
• .env.sepolia — For Base Sepolia testnet nodes

These files contain commented examples showing the RETH_PRUNING_ARGS variable with sensible default distances.

How to Configure RETH_PRUNING_ARGS

Step 1: Edit the Environment File

Open the appropriate environment file for your network:

# For Mainnet

vi .env.mainnet

# For Sepolia

vi .env.sepolia

Locate the "PRUNING" section (around line 96 in .env.mainnet).

Step 2: Set Pruning Distances

Uncomment the RETH_PRUNING_ARGS line and configure your desired pruning distances. Reth supports pruning for the following data categories:

• senderrecovery — Sender recovery data
• transactionlookup — Transaction lookup indexes
• receipts — Transaction receipts
• accounthistory — Account history states
• storagehistory — Storage history states
• bodies — Block bodies

Each flag follows the pattern --prune.<category>.distance=<blocks>. The repository recommends a distance greater than 10,064 blocks to ensure proper chain reorganization handling.

A typical configuration retaining 50,000 blocks of history:

RETH_PRUNING_ARGS="\
  --prune.senderrecovery.distance=50000 \
  --prune.transactionlookup.distance=50000 \
  --prune.receipts.distance=50000 \
  --prune.accounthistory.distance=50000 \
  --prune.storagehistory.distance=50000 \
  --prune.bodies.distance=50000"

Step 3: Start the Node

After saving your changes, start the node using Docker Compose with the Reth client specified:

CLIENT=reth docker-compose up

The reth-entrypoint script will detect your pruning configuration and output a confirmation line:

Adding pruning arguments: --prune.senderrecovery.distance=50000 ...

Important Considerations for Base Node Pruning

Node Type Persistence

The node type is immutable after the initial sync. Once you start syncing as an Archive, Full, or Pruned node, you cannot switch to a different pruning mode without resyncing from genesis. The .env.mainnet file explicitly warns: "The node type that was chosen when first running a node cannot be changed after the initial sync."

Minimum Distance Requirements

The repository-provided snapshots for pruned nodes use a distance of 1,339,200 blocks (approximately 31 days). If you configure manual pruning, ensure your distance exceeds 10,064 blocks to maintain network consensus safety during chain reorganizations.

Example Configuration

Here is the complete pruning section from .env.mainnet showing the recommended format:

# PRUNING (OPTIONAL - UNCOMMENT TO ENABLE)

# NOTE: Set to any number of blocks you want, but it should be >10064

# NOTE: The node type that was chosen when first running a node cannot be changed after the initial sync.

# NOTE: The pruned snapshots provided are set with a distance of 1_339_200 (~31 days).

RETH_PRUNING_ARGS="--prune.senderrecovery.distance=30000 \
  --prune.transactionlookup.distance=30000 \
  --prune.receipts.distance=30000 \
  --prune.accounthistory.distance=30000 \
  --prune.storagehistory.distance=30000 \
  --prune.bodies.distance=30000"

Summary

• Pruning is configured via RETH_PRUNING_ARGS in your .env.mainnet or .env.sepolia file.
• The reth/reth-entrypoint script automatically appends these arguments to the Reth start command at runtime.
• Use distance-based flags (--prune.<category>.distance=<blocks>) to control how much history to retain for each data type.
• Always set distances greater than 10,064 blocks to ensure chain reorganization safety.
• Node type is permanent after the first sync—you cannot switch from Archive to Pruned without a full resync.

Frequently Asked Questions

What is the minimum pruning distance for Reth on Base?

The minimum recommended pruning distance is 10,064 blocks. This threshold ensures that your node retains sufficient history to handle chain reorganizations safely. The .env.mainnet file explicitly notes that distances should exceed this value, and the pruned snapshots provided by the repository use a much larger distance of 1,339,200 blocks (approximately 31 days).

Can I change from an archive node to a pruned node after syncing?

No, you cannot change node types after the initial sync. According to the comments in the .env.mainnet file, "the node type that was chosen when first running a node cannot be changed after the initial sync." If you initially synced as an archive node and later want to run a pruned node, you must resync from genesis with the pruning configuration enabled from the start.

Where does the Reth entrypoint script process pruning arguments?

The reth/reth-entrypoint script processes pruning arguments at lines 49-53. The script checks if the RETH_PRUNING_ARGS environment variable is set, and if so, appends its value to the ADDITIONAL_ARGS variable that gets passed to the Reth binary at startup. This logic ensures that any pruning flags defined in your .env file are automatically injected into the node start command.

Which environment file should I use for Base mainnet pruning configuration?

For Base Mainnet pruning configuration, edit the .env.mainnet file in the repository root. If you are running a Base Sepolia testnet node instead, use .env.sepolia. Both files contain a commented "PRUNING" section around lines 96-104 where you can uncomment and configure the RETH_PRUNING_ARGS variable with your desired distance values.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}