alethia-reth

A high-performance Rust execution client for the Taiko protocol, built on top of Reth powerful NodeBuilder API, designed to deliver the best possible developer and maintenance experience.

Getting Started

1. Clone the Repository

git clone https://github.com/taikoxyz/alethia-reth.git
cd alethia-reth

2. Build

Build by Cargo:

cargo build --release

The main binary will be located at target/release/alethia-reth.

The default build includes revmc JIT support and requires Rust 1.95 plus LLVM 22. Install versioned LLVM 22 packages and put their bin directory on PATH while building. On Ubuntu or Debian, use your distribution's llvm-22 packages or the upstream apt.llvm.org installer (neither touches the unversioned /usr/bin tools):

wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh 22 all
export PATH="/usr/lib/llvm-22/bin:$PATH"

On macOS, brew install llvm@22 and put its bin directory on PATH the same way. Do not run .github/scripts/install_llvm.sh on a developer machine: it is CI/Docker provisioning that force-overwrites the /usr/bin LLVM symlinks. To build without the LLVM toolchain dependency, disable default features:

cargo build --release -p alethia-reth-bin --no-default-features

3. Run Checks and Tests

To ensure everything is set up correctly, run the checks and tests:

just test

Running the Node

To run the compiled node:

./target/release/alethia-reth [OPTIONS]

To see available command-line options and subcommands, run:

./target/release/alethia-reth --help

(Note: Replace [OPTIONS] with the necessary configuration flags for your setup. Refer to the --help output for details.)

revmc JIT

Start the node with upstream-compatible JIT flags:

./target/release/alethia-reth node --jit [OPTIONS]

The main tuning flags are --jit.hot-threshold, --jit.worker-count, --jit.code-cache-bytes, and --jit.idle-evict-duration. When the reth RPC namespace is enabled, the upstream reth_jit method accepts enable, disable, pause, unpause, or clear at runtime.

Taiko's Unzen execution uses consensus-critical zk-gas metering that requires per-opcode interpreter hooks. JIT dispatch therefore falls back to the interpreter for Unzen blocks and for ordinary RPC call, trace, simulation, estimation, and pending-block execution. Canonical Engine execution, payload building, and block replay opt in to the shared revmc backend on pre-Unzen forks. Compiled code bakes in upstream mainnet gas and opcode semantics, so hardforks are JIT-eligible only through an explicit allowlist: new forks stay interpreter-only until they are deliberately marked JIT-safe in TaikoEvmFactory.

revmc is pinned in Cargo.toml to the exact revision the reth pin locks, which carries the upstream compiled-vs-interpreter divergence fixes revmc#394 (stack sync for diverging builtins) and revmc#400 (LOG memory operands in gas analysis) on top of revmc#391 (non-blocking runtime controls) and revmc#395 (dynamic-gas failure ordering). Keep the two pins matched when bumping reth.

Docker

1. Build the Docker Image

docker build -t alethia-reth .

2. Run the Docker Container

docker run -it --rm alethia-reth [OPTIONS]

(Note: You might need to map ports (-p), mount volumes (-v) for data persistence, or pass environment variables (-e) depending on your node's configuration needs.)

Configuration

Alethia-reth uses reth-compatible CLI options plus Taiko chain presets.

Chain Selection

Use --chain with one of the supported presets:

• mainnet
• taiko-hoodi
• devnet
• masaya

Common Runtime Flags

• --datadir <path> to set node data location.
• --http / --ws to enable RPC transports.
• --authrpc.addr <ip> and --authrpc.port <port> for Engine API auth RPC.
• --metrics <addr:port> to expose Prometheus metrics.

Use ./target/release/alethia-reth --help for the full option list and defaults.

License

This project is licensed under the MIT License. See the LICENSE file for details.