Skip to main content
Legacy Geth (l2geth) 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.

​
Historical execution vs. historical data routing

Only requests for historical execution will be routed to Legacy Geth. Everything else will be served by op-geth directly. The term historical execution refers to RPC methods that need to execute transactions prior to bedrock (not just read data from the database):
  • eth_call
  • eth_estimateGas
  • debug_traceBlockByNumber
  • debug_traceBlockByHash
  • debug_traceCall
  • debug_traceTransaction
If you do not need these RPC methods for historical data, then you do not need to run Legacy Geth at all.

​
What is Legacy Geth?

Legacy Geth is the old l2geth binary running against a preconfigured data directory. It serves historical execution data from before the Bedrock upgrade.

​
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.

​
3. Configure op-geth to route to Legacy Geth

Update your op-geth configuration to route historical requests to Legacy Geth: 
geth \
  --datadir=/data/optimism \
  --rollup.historicalrpc=http://localhost:8545 \
  # ... other flags
The --rollup.historicalrpc flag tells op-geth where to route requests for historical execution.

​
Environment variables

Legacy Geth accepts the following environment variables:
VariableDescriptionDefault
USING_OVMRequired. Enables OVM modeN/A (must be set to true)
ETH1_SYNC_SERVICE_ENABLEEnables L1 sync servicetrue (set to false for read-only)
RPC_APIEnabled RPC APIseth,net,web3
RPC_ADDRRPC listening addresslocalhost
RPC_CORS_DOMAINCORS domainslocalhost
RPC_ENABLEEnable RPC serverfalse
RPC_PORTRPC port8545
RPC_VHOSTSVirtual hostslocalhost

​
Historical execution vs. historical data

Only requests for historical execution will be routed to Legacy Geth. Everything else will be served by op-geth directly.

​
Historical execution RPC methods

These methods require transaction execution and are routed to Legacy Geth for pre-Bedrock blocks:
  • eth_call
  • eth_estimateGas
  • debug_traceBlockByNumber
  • debug_traceBlockByHash
  • debug_traceCall
  • debug_traceTransaction

​
Historical data RPC methods

These methods only read data from the database and are served by op-geth:
  • eth_getBlockByNumber
  • eth_getBlockByHash
  • eth_getTransactionByHash
  • eth_getTransactionReceipt
  • eth_getLogs

​
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

​
op-geth not routing to Legacy Geth

Problem: Historical execution requests are not being routed to Legacy Geth Solution: Check that --rollup.historicalrpc is set on op-geth with the correct URL to Legacy Geth