Migrating from Geth

How to perform a smooth and quick transition from Geth or another Execution Layer (Nethermind, Reth, Besu) to Erigon.

Migration Paths: Choosing Your Erigon Setup

When moving from another Execution Layer (EL) such as Geth, Nethermind, Reth or Besu to Erigon, node runners have a primary choice regarding their Consensus Layer (CL) setup:

• Erigon with Caplin: This is the highly efficient, all-in-one setup, utilizing Erigon's embedded CL client, Caplin. It's an excellent choice for simplicity and performance for all node types and usage.

• Erigon with an External Consensus Client: This is the traditional setup, allowing to reuse an existing external CL client (like Prysm or Lighthouse).

The most secure and reliable method for all users involves running and syncing an Erigon node alongside your existing Execution Layer (EL) client (like Geth). This parallel process allows for full functional verification, thorough testing, and ensures a smooth transition with zero downtime. Since Erigon requires significantly less disk space than many other clients, this parallel sync approach is practical and highly recommended for all migrations.

Choosing Your Migration Strategy

• Option 1: In case you run a highly critical process and have enough disk space, syncing Erigon alongside Geth or any other EL is the highly recommended choice for all users, and is essential for validators and RPC providers.

  • If disk space is limited and downtime is not an option, consider syncing Erigon on a separate machine.

• Option 2: If you are a home user or standard node runner (not running a validator), and the disk space is limited and downtime is acceptable, choose this option to remove your EL and the existing CL first.

Node Runner Type	Recommended Path (If Disk Space Allows)	Rationale
Validators	Option 1: Sync Alongside Geth or any EL	Ensures minimal downtime and prevents slashing risk.
Public RPC Providers	Option 1: Sync Alongside Geth or any EL	Guarantees zero service interruption for users.
Home Users / Standard Node Runners with no critical utilization	Option 2: Remove Geth or any EL and Sync Erigon	The fastest method if downtime is accepted.

Option 1: Sync Erigon Alongside Geth and its CL

You can choose whether to migrate to Erigon + Caplin (the simplest setup) or continue using your existing CL.

Migrate to Erigon + Caplin (Internal CL)

This path offers the simplest validator configuration by using Erigon's embedded consensus client, Caplin. You will no longer need your external Consensus Layer (CL) client or a JWT secret for CL-EL communication.

Steps for Minimal Downtime

1. Preparation: Install Erigon.

2. Configuration Check (No Conflict): Ensure Erigon's standard ports (JSON-RPC, P2P) are different from Geth's. These ports are configured via command-line options: --port <port> and --p2p.listen-addr <IP:port>. For example:

   erigon \
     --datadir=/data/erigon \
     --chain=mainnet \
     --port: 30304 \
     --p2p.allowed-ports: 30310, 30311, 30312, 30313, 30314, 30315, 30316

3. Synchronization: Start syncing Erigon. Monitor the sync status using the eth_syncing JSON-RPC method or a health check.

4. Validator Swap: Once Erigon is fully synced, shut down Geth and the external CL client.

5. Reconfiguration and Restart:

   • To restart Erigon, there's no need to specify --port or --P2P.allowed-ports. Refer to this guide for additional Erigon + Caplin configuration recommendations.

   • Crucially, reconfigure your validator keys manager to point directly to the Erigon Beacon API, as Erigon/Caplin now handles both layers internally).

6. Decommission Old Setup: Verify Erigon/Caplin is proposing and attesting blocks correctly. If confirmed, safely remove Geth, the external CL client, and all their data, including the old JWT secret.

Migrate to Erigon + External CL

Option 2: Remove Old EL and Sync Erigon (Downtime Accepted)

This is the simplest option as it requires no configuration adjustments. However, the node will be down until Erigon finishes syncing.

Erigon + Caplin (Fastest Sync)

This path is the fastest way to get Erigon running. It utilizes Erigon's embedded consensus client, Caplin, requiring no external CL client or JWT secret. This is ideal for home users with limited disk space and no critical uptime requirements.

Steps for Quickest Start

1. Decommission Old Setup: Shut down and remove your old EL client (Geth, etc.) and its data. If you were using an external CL client, you can shut it down as well.

2. Installation: Install Erigon.

3. Configuration: Erigon requires no special configuration; it uses default ports and settings. The basic setup is sufficient for most situations.

4. Synchronization: Start syncing Erigon with the default Caplin configuration (Caplin does not use the Engine API).

5. Final Setup: Once Erigon is fully synced, your node is online.

6. Monitoring: Monitor the sync progress using eth_syncing or the health check, and ensure no errors appear in Erigon's logs.

Erigon + External CL (Reuse Existing CL)

---

See Basic Usage and Configuring Erigon for more details on available options.