reth

Modular, contributor-friendly and blazing-fast implementation of the Ethereum protocol

Install | User Book | Developer Docs | Crate Docs

The project is still work in progress, see the disclaimer below.

What is Reth?

Reth (short for Rust Ethereum, pronunciation) is a new Ethereum full node implementation that is focused on being user-friendly, highly modular, as well as being fast and efficient. Reth is an Execution Layer (EL) and is compatible with all Ethereum Consensus Layer (CL) implementations that support the Engine API. It is originally built and driven forward by Paradigm, and is licensed under the Apache and MIT licenses.

Goals

As a full Ethereum node, Reth allows users to connect to the Ethereum network and interact with the Ethereum blockchain. This includes sending and receiving transactions/logs/traces, as well as accessing and interacting with smart contracts. Building a successful Ethereum node requires creating a high-quality implementation that is both secure and efficient, as well as being easy to use on consumer hardware. It also requires building a strong community of contributors who can help support and improve the software.

More concretely, our goals are:

1. Modularity: Every component of Reth is built to be used as a library: well-tested, heavily documented and benchmarked. We envision that developers will import the node's crates, mix and match, and innovate on top of them. Examples of such usage include but are not limited to spinning up standalone P2P networks, talking directly to a node's database, or "unbundling" the node into the components you need. To achieve that, we are licensing Reth under the Apache/MIT permissive license. You can learn more about the project's components here.
2. Performance: Reth aims to be fast, so we used Rust and the Erigon staged-sync node architecture. We also use our Ethereum libraries (including Alloy and revm) which we’ve battle-tested and optimized via Foundry.
3. Free for anyone to use any way they want: Reth is free open source software, built for the community, by the community. By licensing the software under the Apache/MIT license, we want developers to use it without being bound by business licenses, or having to think about the implications of GPL-like licenses.
4. Client Diversity: The Ethereum protocol becomes more antifragile when no node implementation dominates. This ensures that if there's a software bug, the network does not finalize a bad block. By building a new client, we hope to contribute to Ethereum's antifragility.
5. Support as many EVM chains as possible: We aspire that Reth can full-sync not only Ethereum, but also other chains like Optimism, Polygon, BNB Smart Chain, and more. If you're working on any of these projects, please reach out.
6. Configurability: We want to solve for node operators that care about fast historical queries, but also for hobbyists who cannot operate on large hardware. We also want to support teams and individuals who want both sync from genesis and via "fast sync". We envision that Reth will be configurable enough and provide configurable "profiles" for the tradeoffs that each team faces.

Status

Reth is performant, feature-complete, Cancun-ready, and OP Stack Ecotone compatible via the OP Reth binary.

We actively recommend professional node operators to switch to Reth in production for performance and cost reasons in use cases where high performance with great margins is required such as RPC, MEV, Indexing, Simulations, and P2P activities.

While we are aware of parties running Reth staking nodes in production, we do not encourage usage in production staking environments by non-professionals until our audits are done, and the 1.0 version of Reth is released, but we are available to support without warranty or liability.

More historical context below:

• We are releasing 1.0 "production-ready" stable Reth once our Reth & Revm audits are done. ETA ~May 2024.
  • Reth is currently undergoing an audit with Sigma Prime, the developers of Lighthouse, the Rust Consensus Layer implementation.
  • Revm (the EVM used in Reth) is undergoing an audit with Guido Vranken (#1 Ethereum Bug Bounty).
• We are releasing beta on Monday March 4th 2024, our first breaking change to the database model, providing faster query speed, smaller database footprint, and allowing "history" to be mounted on separate drives.
• We shipped iterative improvements until the last alpha release on February 28th 2024, 0.1.0-alpha.21.
• We initially announced 0.1.0-alpha.1 in June 20th 2023.

We will be updating the documentation with the completion status of each component, as well as include more contributing guidelines (design docs, architecture diagrams, repository layouts) and "good first issues".

We appreciate your patience until we get there. Until then, we are happy to answer all questions in the Telegram link above.

Database compatibility

Reth v0.2.0-beta.1 includes a set of breaking database changes that makes it impossible to use database files produced by earlier versions.

If you had a database produced by alpha versions of Reth, you need to drop it with reth db drop (using the same arguments such as --config or --datadir that you passed to reth node), and resync using the same reth node command you've used before.

For Users

See the Reth Book for instructions on how to install and run Reth.

For Developers

Using reth as a library

You can use individual crates of reth in your project.

The crate docs can be found here.

For a general overview of the crates, see Project Layout.

Contributing

If you want to contribute, or follow along with contributor discussion, you can use our main telegram to chat with us about the development of Reth!

• Our contributor guidelines can be found in CONTRIBUTING.md.
• See our contributor docs for more information on the project. A good starting point is Project Layout.

Building and testing

The Minimum Supported Rust Version (MSRV) of this project is 1.76.0.

See the book for detailed instructions on how to build from source.

To fully test Reth, you will need to have Geth installed, but it is possible to run a subset of tests without Geth.

First, clone the repository:

git clone https://github.com/paradigmxyz/reth
cd reth

Next, run the tests:

# Without Geth
cargo test --workspace

# With Geth
cargo test --workspace --features geth-tests

# With Ethereum Foundation tests
#
# Note: Requires cloning https://github.com/ethereum/tests
#
#   cd testing/ef-tests && git clone https://github.com/ethereum/tests ethereum-tests
cargo test -p ef-tests --features ef-tests

We recommend using cargo nextest to speed up testing. With nextest installed, simply substitute cargo test with cargo nextest run.

Note

Some tests use random number generators to generate test data. If you want to use a deterministic seed, you can set the SEED environment variable.

Getting Help

If you have any questions, first see if the answer to your question can be found in the book.

If the answer is not there:

• Join the Telegram to get help, or
• Open a discussion with your question, or
• Open an issue with the bug

Security

See SECURITY.md.

Acknowledgements

Reth is a new implementation of the Ethereum protocol. In the process of developing the node we investigated the design decisions other nodes have made to understand what is done well, what is not, and where we can improve the status quo.

None of this would have been possible without them, so big shoutout to the teams below:

• Geth: We would like to express our heartfelt gratitude to the go-ethereum team for their outstanding contributions to Ethereum over the years. Their tireless efforts and dedication have helped to shape the Ethereum ecosystem and make it the vibrant and innovative community it is today. Thank you for your hard work and commitment to the project.
• Erigon (fka Turbo-Geth): Erigon pioneered the "Staged Sync" architecture that Reth is using, as well as introduced MDBX as the database of choice. We thank Erigon for pushing the state of the art research on the performance limits of Ethereum nodes.
• Akula: Reth uses forks of the Apache versions of Akula's MDBX Bindings, FastRLP and ECIES . Given that these packages were already released under the Apache License, and they implement standardized solutions, we decided not to reimplement them to iterate faster. We thank the Akula team for their contributions to the Rust Ethereum ecosystem and for publishing these packages.