Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.optimism.io/llms.txt

Use this file to discover all available pages before exploring further.

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