XLayer Reth is a customized implementation of Reth optimized for the XLayer network, an Optimism-based Layer 2 solution.

This project provides a high-performance, production-ready Ethereum execution client tailored for XLayer's specific requirements. It builds upon the upstream Reth codebase with custom optimizations and features for the XLayer network.

Run a dev node | Build a node | Contribute to XLayer Reth

• Getting Started
  • Prerequisites
  • Building from Source
  • Docker Build
• Initialization
• Running a Dev Node
• Configuration
• Development
• Testing
  • End-to-end Testing
  • Flashblocks Tests
• Contributing
• License

XLayer Reth is built on top of Reth, extending it with XLayer-specific functionality:

• High Performance & Full OP Support: Leverage Reth's blazing-fast execution engine and complete Optimism feature set out of the box
• XLayer Customization: Implement XLayer-specific features and optimizations independently without impacting upstream development
• Seamless Upstream Sync: Easily integrate the latest Reth updates, improvements, and security patches
• Ecosystem Contribution: Rapidly experiment with new features and bug fixes, contributing valuable improvements back to upstream Reth

• Rust: Version 1.93 or higher
• just: Command runner (install with cargo install just)
• Docker (optional): For containerized builds

# Install just command runner
cargo install just

# List all available commands
just

# Standard release build
just build

# Maximum performance build (recommended for production)
just build-maxperf

# Install standard release build to ~/.cargo/bin
just install

# Install maximum performance build
just install-maxperf

After installation, run the node from anywhere:

xlayer-reth-node --help

Build a Docker image with the following command:

# Build Docker image (tagged with git commit hash)
just build-docker

# Build with custom suffix
just build-docker mysuffix

# The image will be tagged as:
# - op-reth:<git-hash>
# - op-reth:latest

Before running the node for the first time, you need to initialize the database with the genesis block.

xlayer-reth-node init --chain /path/to/genesis.json --datadir /data/xlayer

Note: The init command only needs to be run once before the first start. It creates the database and writes the genesis block.

For local development and testing, you can run a dev node without requiring an external sequencer or L1 connection. The dev mode automatically mines blocks at a configurable interval.

OTEL_EXPORTER_OTLP_PROTOCOL=http cargo r -p xlayer-reth-node node \
  --datadir .op-reth-ttt \
  --engine.legacy-state-root \
  --dev \
  --dev.block-time 1s \
  --builder.gaslimit 1500000000 \
  --txpool.pending-max-count 10000000 \
  --txpool.pending-max-size 10000 \
  --txpool.basefee-max-count 10000000 \
  --txpool.basefee-max-size 10000 \
  --txpool.queued-max-count 10000000 \
  --txpool.queued-max-size 10000 \
  --txpool.blobpool-max-count 10000000 \
  --txpool.blobpool-max-size 10000 \
  --txpool.max-account-slots 10000000 \
  --http \
  --http.api eth,debug,net,web3,txpool \
  --log.stdout.filter "info,engine::tree::payload_validator=debug"

Key flags:

• --dev: Enables dev mode (auto-mining, no consensus required)
• --dev.block-time 1s: Mine a new block every second
• --engine.legacy-state-root: Use legacy state root computation
• --http / --http.api: Enable HTTP RPC with the listed namespaces
• --datadir: Directory for node data (created automatically if it doesn't exist)

XLayer Reth inherits all configuration options from Reth and OP Reth. Run xlayer-reth-node --help for a complete list.

Below are the XLayer-specific configuration options:

# Legacy RPC Routing
--rpc.legacy-url <URL>               # Legacy RPC endpoint for historical data
--rpc.legacy-timeout <DUR>           # Timeout for legacy RPC requests (default: 30s)

# Run all checks (sweep-check + format + clippy + tests)
just check

# Run tests
just test

# Run tests including e2e tests
just test true

# Run flashblocks tests
just test false true

# Auto-fix formatting and clippy issues
just fix

# Watch mode - auto-run tests on file changes
just watch-test

# Watch mode - auto-run clippy on file changes
just watch-check

To run end-to-end (e2e) tests, first build xlayer-reth Docker image in this repo:

just build-docker

Next, you need to start a devnet using xlayer-toolkit. Make sure you set the following environment variables in xlayer-toolkit/devnet/example.env:

SEQ_TYPE=reth
RPC_TYPE=reth
ENABLE_INNERTX_RPC=true

After devnet is started, run the e2e test:

cargo test -p xlayer-e2e-test --test e2e_tests -- --nocapture --test-threads=1
# or
just test true

Similar to e2e tests, first build xlayer-reth Docker image in this repo:

just build-docker

Next, you need to start a devnet using xlayer-toolkit. Make sure you set the following environment variables in xlayer-toolkit/devnet/example.env:

FLASHBLOCK_ENABLED=true
FLASHBLOCK_P2P_ENABLED=true

Also, start the 2nd RPC node under xlayer-toolkit/devnet:

./scripts/run-rpc2.sh

Then, in this repo, run:

cargo test -p xlayer-e2e-test --test flashblocks_tests -- --nocapture --test-threads=1
# or
just test false true

To run all flashblocks tests (including ignored tests, also requires 2nd RPC node to be running), run:

cargo test -p xlayer-e2e-test --test flashblocks_tests -- --include-ignored --nocapture --test-threads=1

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run checks before committing (just check)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

just xlayer

This project is dual-licensed under the MIT License and the Apache License 2.0 - see the LICENSE file for details.