Legacy Geth configuration

Learn how to configure Legacy Geth for serving historical execution traces on upgraded OP Stack networks.

Legacy Geth (l2geth) is the old pre-Bedrock OVM client running against a preconfigured data directory. It is required only for upgraded networks like OP Mainnet to serve historical execution traces from before the Bedrock upgrade. If you’re running a node that had a chain genesis after the Bedrock upgrade, you do not need Legacy Geth.

Legacy Geth (l2geth) is the pre-Bedrock OVM client and is unrelated to op-geth’s deprecation. l2geth is required on OP Mainnet archive nodes regardless of which post-Bedrock execution client you run (op-reth or op-geth).

If you need state proofs for post-Bedrock blocks (for example, for withdrawal proving), see the historical proofs config — that’s a different feature.

Do you need Legacy Geth?

Only requests for historical execution — RPC methods that need to execute pre-Bedrock transactions rather than just read data from the database, such as eth_call and the debug_trace* methods — are routed to Legacy Geth. Your execution client serves everything else directly. If you do not need these RPC methods for pre-Bedrock blocks, then you do not need to run Legacy Geth at all.

For the exact lists of which RPC methods are routed to Legacy Geth and which are served by your execution client, see the Legacy Geth configuration reference.

Setup

1. Download the preconfigured data directory

Download and extract the Legacy Geth data directory, which is available at datadirs.optimism.io.

# Download the data directory
curl -o legacy-geth-datadir.tar -sL <URL-to-legacy-datadir>

# Extract it
tar -xvf legacy-geth-datadir.tar -C /data/legacy-geth

2. Configure Legacy Geth

Run Legacy Geth with the minimum required configuration:

USING_OVM=true \
  ETH1_SYNC_SERVICE_ENABLE=false \
  RPC_API=eth,rollup,net,web3,debug \
  RPC_ADDR=0.0.0.0 \
  RPC_CORS_DOMAIN=* \
  RPC_ENABLE=true \
  RPC_PORT=8545 \
  RPC_VHOSTS=* \
  geth --datadir /data/legacy-geth

It is imperative that you specify the USING_OVM=true environment variable. Failing to specify this will cause l2geth to return invalid execution traces or panic at startup.

The full set of environment variables Legacy Geth accepts, with defaults, is catalogued in the Legacy Geth configuration reference.

3. Configure your execution client to route to Legacy Geth

Point your execution client at Legacy Geth with the --rollup.historicalrpc flag; op-reth and op-geth accept the same flag (see the routing-flag reference).

op-reth

op-reth node \
  --datadir=/data/optimism \
  --rollup.historicalrpc=http://localhost:8545 \
  # ... other flags

op-geth

op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain. Migrate to op-reth, the primary supported execution client. See the op-geth deprecation notice for the full migration plan.

geth \
  --datadir=/data/optimism \
  --rollup.historicalrpc=http://localhost:8545 \
  # ... other flags

Troubleshooting

l2geth is based on an old version of geth where trace functionality is unstable. It is no longer maintained and will not be updated.

Legacy Geth won’t start

Problem: l2geth panics or returns errors on startup

Solution: Ensure USING_OVM=true is set in your environment variables

Invalid execution traces

Problem: Legacy Geth returns invalid or incorrect trace data

Solution: Verify that USING_OVM=true is set and the data directory is complete and uncorrupted

Execution client not routing to Legacy Geth

Problem: Historical execution requests are not being routed to Legacy Geth

Solution: Check that --rollup.historicalrpc is set on your execution client (op-reth or op-geth) with the correct URL to Legacy Geth