Skip to content

Commit

Permalink
doc: update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
pythonberg1997 committed Jul 15, 2024
1 parent dccf811 commit a3b4b9d
Showing 1 changed file with 215 additions and 118 deletions.
333 changes: 215 additions & 118 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,155 +1,252 @@
# reth
# BNB Chain Reth

[![CI status](https://github.com/paradigmxyz/reth/workflows/unit/badge.svg)][gh-ci]
[![cargo-deny status](https://github.com/paradigmxyz/reth/workflows/deny/badge.svg)][gh-deny]
[![Telegram Chat][tg-badge]][tg-url]
[![Discord Chat][discord-badge]][discord-url]

**Modular, contributor-friendly and blazing-fast implementation of the Ethereum protocol**
[gh-ci]: https://github.com/bnb-chain/reth/actions/workflows/unit.yml

![](./assets/reth-prod.png)
[gh-deny]: https://github.com/bnb-chain/reth/actions/workflows/deny.yml

**[Install](https://paradigmxyz.github.io/reth/installation/installation.html)**
| [User Book](https://reth.rs)
| [Developer Docs](./docs)
| [Crate Docs](https://reth.rs/docs)
[discord-badge]: https://img.shields.io/badge/discord-join%20chat-blue.svg

[gh-ci]: https://github.com/paradigmxyz/reth/actions/workflows/unit.yml
[gh-deny]: https://github.com/paradigmxyz/reth/actions/workflows/deny.yml
[tg-badge]: https://img.shields.io/endpoint?color=neon&logo=telegram&label=chat&url=https%3A%2F%2Ftg.sumanjay.workers.dev%2Fparadigm%5Freth
[discord-url]: https://discord.gg/z2VpC455eU

## What is Reth?
BNB Chain Reth is a cutting-edge rust client developed in collaboration with Paradigm, designed to provide seamless
support for [BNB Smart Chain(BSC)](https://github.com/bnb-chain/bsc) and [opBNB](https://github.com/bnb-chain/op-geth).

Reth (short for Rust Ethereum, [pronunciation](https://twitter.com/kelvinfichter/status/1597653609411268608)) 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](https://github.com/ethereum/execution-apis/tree/a0d03086564ab1838b462befbc083f873dcf0c0f/src/engine). It is originally built and driven forward by [Paradigm](https://paradigm.xyz/), and is licensed under the Apache and MIT licenses.
## Build from Source

## Goals
For prerequisites and detailed build instructions please read
the [Installation Instructions](https://paradigmxyz.github.io/reth/installation/source.html).

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.
With Rust and the dependencies installed, you're ready to build BNB Chain Reth. First, clone the repository:

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](./docs/repo/layout.md).
2. **Performance**: Reth aims to be fast, so we used Rust and the [Erigon staged-sync](https://erigon.substack.com/p/erigon-stage-sync-and-control-flows) node architecture. We also use our Ethereum libraries (including [Alloy](https://github.com/alloy-rs/alloy/) and [revm](https://github.com/bluealloy/revm/)) which we’ve battle-tested and optimized via [Foundry](https://github.com/foundry-rs/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 production ready, and suitable for usage in mission-critical environments such as staking or high-uptime services. We also 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.

More historical context below:
* We released 1.0 "production-ready" stable Reth in June 2024.
* Reth completed an audit with [Sigma Prime](https://sigmaprime.io/), the developers of [Lighthouse](https://github.com/sigp/lighthouse), the Rust Consensus Layer implementation. Find it [here](./audit/sigma_prime_audit_v2.pdf).
* Revm (the EVM used in Reth) underwent an audit with [Guido Vranken](https://twitter.com/guidovranken) (#1 [Ethereum Bug Bounty](https://ethereum.org/en/bug-bounty)). We will publish the results soon.
* We released multiple iterative beta versions, up to [beta.9](https://github.com/paradigmxyz/reth/releases/tag/v0.2.0-beta.9) on Monday June 3rd 2024 the last beta release.
* We released [beta](https://github.com/paradigmxyz/reth/releases/tag/v0.2.0-beta.1) 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](https://github.com/paradigmxyz/reth/releases/tag/v0.1.0-alpha.21).
* We [initially announced](https://www.paradigm.xyz/2023/06/reth-alpha) [0.1.0-alpha.1](https://github.com/paradigmxyz/reth/releases/tag/v0.1.0-alpha.1) in June 20th 2023.

### Database compatibility

We do not have any breaking database changes since beta.1, and do not plan any in the near future.

Reth [v0.2.0-beta.1](https://github.com/paradigmxyz/reth/releases/tag/v0.2.0-beta.1) includes
a [set of breaking database changes](https://github.com/paradigmxyz/reth/pull/5191) 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](https://paradigmxyz.github.io/reth) 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](https://paradigmxyz.github.io/reth/docs).

For a general overview of the crates, see [Project Layout](./docs/repo/layout.md).

### Contributing

If you want to contribute, or follow along with contributor discussion, you can use our [main telegram](https://t.me/paradigm_reth) to chat with us about the development of Reth!

- Our contributor guidelines can be found in [`CONTRIBUTING.md`](./CONTRIBUTING.md).
- See our [contributor docs](./docs) for more information on the project. A good starting point is [Project Layout](./docs/repo/layout.md).

### Building and testing

<!--
When updating this, also update:
- clippy.toml
- Cargo.toml
- .github/workflows/lint.yml
-->

The Minimum Supported Rust Version (MSRV) of this project is [1.79.0](https://blog.rust-lang.org/2024/06/13/Rust-1.79.0.html).
```shell
git clone https://github.com/bnb-chain/reth.git
cd reth
```

See the book for detailed instructions on how to [build from source](https://paradigmxyz.github.io/reth/installation/source.html).
In the realm of BSC, you have the option to execute the following commands to compile bsc-reth:

To fully test Reth, you will need to have [Geth installed](https://geth.ethereum.org/docs/getting-started/installing-geth), but it is possible to run a subset of tests without Geth.
```shell
make build-bsc
```

First, clone the repository:
Alternatively, you can install reth using the following command:

```sh
git clone https://github.com/paradigmxyz/reth
cd reth
```shell
make install-bsc
```

Next, run the tests:
When it comes to opBNB, you can run the following commands to compile op-reth:

```sh
# Without Geth
cargo test --workspace
```shell
make build-op
```

# With Geth
cargo test --workspace --features geth-tests
Or, opt for installing op-reth with the command:

# 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
```shell
make install-op
```

We recommend using [`cargo nextest`](https://nexte.st/) to speed up testing. With nextest installed, simply substitute `cargo test` with `cargo nextest run`.
## Run Reth for BSC

The command below is for an archive node. To run a full node, simply add the `--full` tag.

```shell
# for testnet
export network=bsc-testnet

# for mainnet
# export network=bsc

./target/release/bsc-reth node \
--datadir=./datadir \
--chain=${network} \
--http \
--http.addr=0.0.0.0 \
--http.port=8545 \
--http.api="eth, net, txpool, web3, rpc" \
--ws \
--ws.addr=0.0.0.0 \
--ws.port=8546 \
--nat=any \
--log.file.directory ./datadir/logs
```

> **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.
You can run `bsc-reth --help` for command explanations.

## Getting Help
For running bsc-reth with docker, please use the following command:

If you have any questions, first see if the answer to your question can be found in the [book][book].
```shell
# for testnet
export network=bsc-testnet

If the answer is not there:
# for mainnet
# export network=bsc

- Join the [Telegram][tg-url] to get help, or
- Open a [discussion](https://github.com/paradigmxyz/reth/discussions/new) with your question, or
- Open an issue with [the bug](https://github.com/paradigmxyz/reth/issues/new?assignees=&labels=C-bug%2CS-needs-triage&projects=&template=bug.yml)
# check this for version of the docker image, https://github.com/bnb-chain/reth/pkgs/container/bsc-reth
export version=latest

## Security
# the directory where reth data will be stored
export data_dir=/xxx/xxx

See [`SECURITY.md`](./SECURITY.md).
docker run -d -p 8545:8545 -p 8546:8546 -p 30303:30303 -p 30303:30303/udp -v ${data_dir}:/data \
--name bsc-reth ghcr.io/bnb-chain/bsc-reth:${version} node \
--datadir=/data \
--chain=${network} \
--http \
--http.addr=0.0.0.0 \
--http.port=8545 \
--http.api="eth, net, txpool, web3, rpc" \
--ws \
--ws.addr=0.0.0.0 \
--ws.port=8546 \
--nat=any \
--log.file.directory /data/logs
```

## Acknowledgements
## Run Reth for opBNB

The op-reth is an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) for
opBNB.
You need to run op-node along with op-reth to synchronize with the opBNB network.

Here is the quick command for running the op-node. For more details, refer to
the [opbnb repository](https://github.com/bnb-chain/opbnb).

```shell
git clone https://github.com/bnb-chain/opbnb
cd opbnb
make op-node

# for testnet
# it's better to replace the L1_RPC with your own BSC Testnet RPC Endpoint for stability
export network=testnet
export L1_RPC=https://bsc-testnet.bnbchain.org
export P2P_BOOTNODES="enr:-J24QGQBeMsXOaCCaLWtNFSfb2Gv50DjGOKToH2HUTAIn9yXImowlRoMDNuPNhSBZNQGCCE8eAl5O3dsONuuQp5Qix2GAYjB7KHSgmlkgnY0gmlwhDREiqaHb3BzdGFja4PrKwCJc2VjcDI1NmsxoQL4I9wpEVDcUb8bLWu6V8iPoN5w8E8q-GrS5WUCygYUQ4N0Y3CCIyuDdWRwgiMr,enr:-J24QJKXHEkIhy0tmIk2EscMZ2aRrivNsZf_YhgIU51g4ZKHWY0BxW6VedRJ1jxmneW9v7JjldPOPpLkaNSo6cXGFxqGAYpK96oCgmlkgnY0gmlwhANzx96Hb3BzdGFja4PrKwCJc2VjcDI1NmsxoQMOCzUFffz04eyDrmkbaSCrMEvLvn5O4RZaZ5k1GV4wa4N0Y3CCIyuDdWRwgiMr"

# for mainnet
# export network=mainnet
# export L1_RPC=https://bsc-dataseed.bnbchain.org
# export P2P_BOOTNODES="enr:-J24QA9sgVxbZ0KoJ7-1gx_szfc7Oexzz7xL2iHS7VMHGj2QQaLc_IQZmFthywENgJWXbApj7tw7BiouKDOZD4noWEWGAYppffmvgmlkgnY0gmlwhDbjSM6Hb3BzdGFja4PMAQCJc2VjcDI1NmsxoQKetGQX7sXd4u8hZr6uayTZgHRDvGm36YaryqZkgnidS4N0Y3CCIyuDdWRwgiMs,enr:-J24QPSZMaGw3NhO6Ll25cawknKcOFLPjUnpy72HCkwqaHBKaaR9ylr-ejx20INZ69BLLj334aEqjNHKJeWhiAdVcn-GAYv28FmZgmlkgnY0gmlwhDTDWQOHb3BzdGFja4PMAQCJc2VjcDI1NmsxoQJ-_5GZKjs7jaB4TILdgC8EwnwyL3Qip89wmjnyjvDDwoN0Y3CCIyuDdWRwgiMs"

./op-node/bin/op-node \
--l1.trustrpc \
--sequencer.l1-confs=15 \
--verifier.l1-confs=15 \
--l1.http-poll-interval 60s \
--l1.epoch-poll-interval 180s \
--l1.rpc-max-batch-size 20 \
--rollup.config=./assets/${network}/rollup.json \
--rpc.addr=0.0.0.0 \
--rpc.port=8546 \
--p2p.sync.req-resp \
--p2p.listen.ip=0.0.0.0 \
--p2p.listen.tcp=9003 \
--p2p.listen.udp=9003 \
--snapshotlog.file=./snapshot.log \
--p2p.bootnodes=$P2P_BOOTNODES \
--metrics.enabled \
--metrics.addr=0.0.0.0 \
--metrics.port=7300 \
--pprof.enabled \
--rpc.enable-admin \
--l1=${L1_RPC} \
--l2=http://localhost:8551 \
--l2.jwt-secret=./jwt.txt
```

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.
Copy the JWT file generated when running the op-node to the current workspace. Here is a quick command for running
op-reth.
The command below is for an archive node. To run a full node, simply add the `--full` tag.

```shell
# for testnet
export network=testnet
export L2_RPC=https://opbnb-testnet-rpc.bnbchain.org

# for mainnet
# export network=mainnet
# export L2_RPC=https://opbnb-mainnet-rpc.bnbchain.org

./target/release/op-reth node \
--datadir=./datadir \
--chain=opbnb-${network} \
--rollup.sequencer-http=${L2_RPC} \
--authrpc.addr="0.0.0.0" \
--authrpc.port=8551 \
--authrpc.jwtsecret=./jwt.txt \
--http \
--http.addr=0.0.0.0 \
--http.port=8545 \
--http.api="eth, net, txpool, web3, rpc" \
--ws \
--ws.addr=0.0.0.0 \
--ws.port=8546 \
--builder.gaslimit=150000000 \
--nat=any \
--log.file.directory ./datadir/logs
```

None of this would have been possible without them, so big shoutout to the teams below:
You can run `op-reth --help` for command explanations. More details on running opbnb nodes can be
found [here](https://docs.bnbchain.org/opbnb-docs/docs/tutorials/running-a-local-node/).

For running op-reth with docker, please use the following command:

```shell
# for testnet
export network=testnet
export L2_RPC=https://opbnb-testnet-rpc.bnbchain.org

# for mainnet
# export network=mainnet
# export L2_RPC=https://opbnb-mainnet-rpc.bnbchain.org

# check this for version of the docker image, https://github.com/bnb-chain/reth/pkgs/container/op-reth
export version=latest

# the directory where reth data will be stored
export data_dir=/xxx/xxx

# the directory where the jwt.txt file is stored
export jwt_dir=/xxx/xxx

docker run -d -p 8545:8545 -p 8546:8546 -p 30303:30303 -p 30303:30303/udp -v ${data_dir}:/data -v ${jwt_dir}:/jwt \
--name op-reth ghcr.io/bnb-chain/op-reth:${version} node \
--datadir=/data \
--chain=opbnb-${network} \
--rollup.sequencer-http=${L2_RPC} \
--authrpc.addr="0.0.0.0" \
--authrpc.port=8551 \
--authrpc.jwtsecret=/jwt/jwt.txt \
--http \
--http.addr=0.0.0.0 \
--http.port=8545 \
--http.api="eth, net, txpool, web3, rpc" \
--ws \
--ws.addr=0.0.0.0 \
--ws.port=8546 \
--builder.gaslimit=150000000 \
--nat=any \
--log.file.directory /data/logs
```

- [Geth](https://github.com/ethereum/go-ethereum/): 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](https://github.com/ledgerwatch/erigon) (fka Turbo-Geth): Erigon pioneered the ["Staged Sync" architecture](https://erigon.substack.com/p/erigon-stage-sync-and-control-flows) that Reth is using, as well as [introduced MDBX](https://github.com/ledgerwatch/erigon/wiki/Choice-of-storage-engine) as the database of choice. We thank Erigon for pushing the state of the art research on the performance limits of Ethereum nodes.
- [Akula](https://github.com/akula-bft/akula/): Reth uses forks of the Apache versions of Akula's [MDBX Bindings](https://github.com/paradigmxyz/reth/pull/132), [FastRLP](https://github.com/paradigmxyz/reth/pull/63) and [ECIES](https://github.com/paradigmxyz/reth/pull/80) . 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.
## Contribution

## Warning
Thank you for considering helping out with the source code! We welcome contributions
from anyone on the internet, and are grateful for even the smallest of fixes!

The `NippyJar` and `Compact` encoding formats and their implementations are designed for storing and retrieving data internally. They are not hardened to safely read potentially malicious data.
If you'd like to contribute to bnb chain reth, please fork, fix, commit and send a pull request
for the maintainers to review and merge into the main code base. If you wish to submit
more complex changes though, please check up with the core devs first
on [our discord channel](https://discord.gg/bnbchain)
to ensure those changes are in line with the general philosophy of the project and/or get
some early feedback which can make both your efforts much lighter as well as our review
and merge procedures quick and simple.

[book]: https://paradigmxyz.github.io/reth/
[tg-url]: https://t.me/paradigm_reth
Please see the [Developers' Guide](https://github.com/bnb-chain/reth/tree/develop/docs)
for more details on configuring your environment, managing project dependencies, and
testing procedures.

0 comments on commit a3b4b9d

Please sign in to comment.