Skip to content

Commit

Permalink
docs: book pass + rpc chapter (paradigmxyz#3070)
Browse files Browse the repository at this point in the history
  • Loading branch information
@onbjerg
onbjerg authored Jun 12, 2023
1 parent b19e123 commit d65032e
Show file tree
Hide file tree
Showing 23 changed files with 1,091 additions and 158 deletions.
43 changes: 23 additions & 20 deletions book/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,30 @@

1. [Introduction](./intro.md)
1. [Installation](./installation/installation.md)
1. [Pre-Built Binaries](./installation/binaries.md)
1. [Docker](./installation/docker.md)
1. [Build from Source](./installation/source.md)
1. [Update Priorities](./installation/priorities.md)
1. [Pre-Built Binaries](./installation/binaries.md)
1. [Docker](./installation/docker.md)
1. [Build from Source](./installation/source.md)
1. [Update Priorities](./installation/priorities.md)
1. [Run a Node](./run/run-a-node.md)
1. [Mainnet or official Testnets](./run/mainnet.md)
1. [Local Testnet](./run/local_testnet.md)
1. [Observability with Prometheus & Grafana](./run/observability.md)
1. [Configuring reth.toml](./run/config.md)
1. [Mainnet or official testnets](./run/mainnet.md)
1. [Metrics](./run/observability.md)
1. [Configuring Reth](./run/config.md)
1. [Interacting with Reth over JSON-RPC](./jsonrpc/intro.md)
1. [admin](./jsonrpc/admin.md)
1. [eth](./jsonrpc/eth.md)
1. [engine](./jsonrpc/engine.md)
1. [tracing](./jsonrpc/tracing.md)
1. [eth](./jsonrpc/eth.md)
1. [web3](./jsonrpc/web3.md)
1. [net](./jsonrpc/net.md)
1. [txpool](./jsonrpc/txpool.md)
1. [debug](./jsonrpc/debug.md)
1. [trace](./jsonrpc/trace.md)
1. [admin](./jsonrpc/admin.md)
1. [rpc](./jsonrpc/rpc.md)
1. [CLI Reference](./cli/cli.md)
1. [reth node](./cli/node.md) -->
1. [reth db](./cli/db.md)
1. [reth p2p](./cli/p2p.md)
1. [reth stage](./cli/stage.md)
1. [reth dump-stage](./cli/dump-stage.md)
1. [reth drop-stage](./cli/drop-stage.md)
1. [reth node](./cli/node.md) -->
1. [reth db](./cli/db.md)
1. [reth p2p](./cli/p2p.md)
1. [reth stage](./cli/stage.md)
1. [reth dump-stage](./cli/dump-stage.md)
1. [reth drop-stage](./cli/drop-stage.md)
1. [Developers](./developers/developers.md)
1. [Contribute](./developers/contribute.md)
1. [Architecture](./developers/architecture.md)
1. [Contribute](./developers/contribute.md)
1. [Architecture](./developers/architecture.md)
1 change: 0 additions & 1 deletion book/faq/README.md
View file

This file was deleted.

65 changes: 18 additions & 47 deletions book/installation/binaries.md
View file
Original file line number Diff line number Diff line change
@@ -1,57 +1,28 @@
# Binaries

Precompiled binaries are available from the [GitHub releases page](https://github.com/paradigmxyz/reth/releases).
These are better managed by using [rethup](#using-rethup).

## Rethup
Binaries are supplied for 5 platforms:

rethup is the Reth installer. It is a wrapper around the GitHub releases page, and allows you to install Reth from a specific branch, commit, or pull request from your terminal, easily.
- Linux x86_64: AMD and Intel 64-bit processors (most desktops, laptops, and servers)
- Linux ARM64: 64-bit arm processors
- macOS x86_64: macOS with Intel chips
- macOS ARM64: macOS with Apple Silicon
- Windows x86_64: AMD and Intel 64-bit processors

Open your terminal and run the following command:
Each binary is contained in a tarball.

```sh
curl -L https://reth.paradigm.xyz | bash
```
As an example, you could install the Linux x86_64 version like so:

This will install rethup, then simply follow the instructions on-screen,
which will make the `rethup` command available in your CLI.
1. Go to the [Releases](https://github.com/paradigmxyz/reth/releases) page and select the latest release.
1. Download the `reth-${VERSION}-x86_64-unknown-linux-gnu.tar.gz` tarball.

Running `rethup` by itself will install the latest (nightly) precompiled binary for `reth`.
See `rethup --help` for more options, like installing from a specific version or commit.

> ℹ️ **Note**
>
> If you're on Windows, you will need to install and use [Git BASH](https://gitforwindows.org/) or [WSL](https://learn.microsoft.com/en-us/windows/wsl/install),
> as your terminal, since rethup currently does not support Powershell or Cmd.
You can use the different rethup flags to install reth from a specific branch, pull request, or path.

```sh
rethup --branch master
rethup --path path/to/reth
rethup --pr 1234
```

## From Github Releases

Alternatively, you can download the binaries from the [GitHub releases page](https://github.com/paradigmxyz/reth/releases).

Binaries are supplied for four platforms:

- `x86_64-unknown-linux-gnu`: AMD/Intel 64-bit processors (most desktops, laptops, servers)
- `x86_64-apple-darwin`: macOS with Intel chips
- `aarch64-unknown-linux-gnu`: 64-bit ARM processors (Raspberry Pi 4)
- `x86_64-windows`: Windows with 64-bit processors

Each binary is contained in a `.tar.gz` archive. For this example, lets assume the user needs
a `x86_64` binary:
1. Go to the [Releases](https://github.com/paradigmxyz/reth/releases) page and
select the latest release.
1. Download the `reth-${VERSION}-x86_64-unknown-linux-gnu.tar.gz` binary. For example, to obtain the binary file for v0.0.1 (the latest version at the time of writing), a user can run the following commands in a linux terminal:
```bash
cd ~
curl -LO https://github.com/paradigmxyz/reth/releases/download/v0.0.1-alpha/reth-v0.0.1-alpha-x86_64-unknown-linux-gnu.tar.gz
tar -xvf reth-v0.0.1-alpha-x86_64-unknown-linux-gnu.tar.gz
```
For example, to obtain the binary file for v0.0.1-alpha, you can run the following commands in a Linux terminal:
```bash
cd ~
curl -LO https://github.com/paradigmxyz/reth/releases/download/v0.0.1-alpha/reth-v0.0.1-alpha-x86_64-unknown-linux-gnu.tar.gz
tar -xvf reth-v0.0.1-alpha-x86_64-unknown-linux-gnu.tar.gz
```
1. Test the binary with `./reth --version` (it should print the version).
1. (Optional) Move the `reth` binary to a location in your `PATH`, so the `reth` command can be called from anywhere. For example, to copy `reth` from the current directory to `usr/bin`, run `sudo cp reth /usr/bin`.
2. (Optional) Move the `reth` binary to a location in your `PATH`, so the `reth` command can be called from anywhere.
For most Linux distros, you can move the binary to `/usr/local/bin`: `sudo cp ./reth /usr/local/bin`.
38 changes: 19 additions & 19 deletions book/installation/docker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,36 +2,39 @@

There are two ways to obtain a Reth Docker image:

1. [Docker Hub](#docker-hub), or
2. By [building a Docker image from source](#building-the-docker-image).
1. [GitHub](#github)
2. [Building it from source](#building-the-docker-image)

Once you have obtained the docker image via one of these methods, proceed to [Using the Docker
Once you have obtained the Docker image, proceed to [Using the Docker
image](#using-the-docker-image).

## Docker Hub
## GitHub

Reth maintains the [paradigmxyz/reth][docker_hub] Docker Hub repository which provides an easy
way to run Reth without building the image yourself.
Reth docker images for both x86_64 and ARM64 machines are published with every release of reth on GitHub Container Registry.

Obtain the latest image with:
You can obtain the latest image with:

```bash
docker pull paradigmxyz/reth
docker pull ghcr.io/paradigmxyz/reth
```

Download and test the image with:
Or a specific version (e.g. v0.0.1) with:

```bash
docker run paradigmxyz/reth reth --version
docker pull ghcr.io/paradigmxyz/reth:v0.0.1
```

If you can see the latest [Reth release](https://github.com/paradigmxyz/reth/releases) version
(see example below), then you've successfully installed Reth via Docker.
You can test the image with:

## Building the Docker Image
```bash
docker run --rm ghcr.io/paradigmxyz/reth reth --version
```

If you can see the latest [Reth release](https://github.com/paradigmxyz/reth/releases) version, then you've successfully installed Reth via Docker.

To build the image from source, navigate to
the root of the repository and run:
## Building the Docker image

To build the image from source, navigate to the root of the repository and run:

```bash
docker build . -t reth:local
Expand All @@ -40,8 +43,5 @@ docker build . -t reth:local
The build will likely take several minutes. Once it's built, test it with:

```bash
docker run reth:local reth --help
docker run reth:local reth --version
```

[docker_hub]: https://hub.docker.com/repository/docker/paradigmxyz/reth/

30 changes: 22 additions & 8 deletions book/installation/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,34 +3,48 @@
Reth runs on Linux and macOS (Windows tracked).

There are three core methods to obtain Reth:
* [Pre-built binaries](./binaries.md).
* [Docker images](./docker.md).
* [Building from source.](./source.md).

* [Pre-built binaries](./binaries.md)
* [Docker images](./docker.md)
* [Building from source.](./source.md)

## Hardware Requirements

The hardware requirements for running Reth depend on the node configuration and can change over time as the network grows or new features are implemented. The most important requirement is by far the disk, whereas CPU and RAM requirements are relatively flexible.
The hardware requirements for running Reth depend on the node configuration and can change over time as the network grows or new features are implemented.

The most important requirement is by far the disk, whereas CPU and RAM requirements are relatively flexible.

| | Archive Node | Full Node |
|-----------|------------------------------------|-------------------------------------|
| Disk | At least 2TB (NVMe recommended) | TBD |
| Memory | 8GB+ | 8GB+ |
| CPU | Higher clock speed over core count | Higher clock speeds over core count |
| Bandwidth | Stable 24Mbps+ | Stable 24Mbps+ |

### Disk

There are multiple types of disks to sync Reth, with varying size requirements, depending on the [syncing mode](../run/sync-modes.md):

* Archive Node: At least 2.5TB is required to store
* Archive Node: At least 2TB is required to store
* Full Node: TBD

The time to sync also varies depending on the node type. NVMe drives are recommended for the best performance, however they can get expensive. SSDs are a good alternative, and HDDs are the cheapest option, but they will take the longest to sync.
NVMe drives are recommended for the best performance, with SSDs being a cheaper alternative. HDDs are the cheapest option, but they will take the longest to sync, and are not recommended.

At the time of writing, syncing an Ethereum mainnet node to block 17.4M on NVMe drives takes about 50 hours, while on a GCP "Persistent SSD" it takes around 5 days.

### CPU

Most of the time in Ethereum is spent executing transactions, which is a single-threaded operation due to potential state dependencies of a transaction on previous ones. As a result, the number of cores matters less, but in general higher clock speeds are better. More cores are better for parallelizable [stages, like Senders Recovery, or Bodies](../developers/architecture.md), but these stages are not the bottleneck for syncing.
Most of the time during syncing is spent executing transactions, which is a single-threaded operation due to potential state dependencies of a transaction on previous ones.

As a result, the number of cores matters less, but in general higher clock speeds are better. More cores are better for parallelizable [stages](../developers/architecture.md) (like sender recovery or bodies downloading), but these stages are not the primary bottleneck for syncing.

### Memory

It is recommended to use at least 8GB of RAM.

Most of Reth's components tend to consume a low amount of memory, unless you are under heavy RPC load, so this should matter less than the other requirements.

Higher memory is generally better as it allows for better caching and less stress on the disk.
Higher memory is generally better as it allows for better caching, resulting in less stress on the disk.

### Bandwidth

Expand Down
47 changes: 28 additions & 19 deletions book/installation/source.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

You can build Reth on Linux, macOS, and Windows WSL.

# Dependencies
## Dependencies

First, **install Rust** using [rustup](https://rustup.rs/)：

Expand All @@ -12,7 +12,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

The rustup installer provides an easy way to update the Rust compiler, and works on all platforms.

> Tips:
> **Tips**
>
> - During installation, when prompted, enter `1` for the default installation.
> - After Rust installation completes, try running `cargo version` . If it cannot
Expand All @@ -25,7 +25,9 @@ operating system:
- **Ubuntu**: `apt-get install libclang-dev pkg-config build-essential`
- **macOS**: `brew install llvm pkg-config`

# Build Reth
These are needed to build bindings for Reth's database.

## Build Reth

With Rust and the dependencies installed, you're ready to build Reth. First, clone the repository:

Expand All @@ -34,7 +36,7 @@ git clone https://github.com/paradigmxyz/reth
cd reth
```

Then, install Reth into your path directly via:
Then, install Reth into your `PATH` directly via:

```bash
cargo install --locked --path bin/reth --bin reth
Expand All @@ -50,22 +52,16 @@ cargo build --release

This will place the reth binary under `./target/release/reth`, and you can copy it to your directory of preference after that.

You can also build Reth with the following rustflags for utilizing faster CPU instructions available on your machine:
Compilation may take around 10 minutes. Installation was successful if `reth --help` displays the [command-line documentation](../cli/cli.md).

```bash
RUSTFLAGS="-C target-cpu=native" cargo build --release
```
If you run into any issues, please check the [Troubleshooting](#troubleshooting) section, or reach out to us on [Telegram](https://t.me/paradigm_reth).

Compilation may take around 10 minutes. Installation was successful if `reth --help` displays
the [command-line documentation](../cli/cli.md).
## Update Reth

If you run into any issues, please check the [Troubleshooting](#troubleshooting) section.
out to us on [Telegram](https://t.me/paradigm_reth).
You can update Reth to a specific version by running the commands below.

## Update Reth
The `reth` directory will be the location you cloned reth to during the installation process.

You can update Reth to a specific version by running the commands below. The `reth`
directory will be the location you cloned reth to during the installation process.
`${VERSION}` will be the version you wish to build in the format `vX.X.X`.

```bash
Expand All @@ -75,32 +71,45 @@ git checkout ${VERSION}
cargo build --release
```

## Compilation Profiles
## Optimizations

**Profiles**

You can customise the compiler settings used to compile Reth via
[Cargo profiles](https://doc.rust-lang.org/cargo/reference/profiles.html).

Reth includes several profiles which can be selected via the `--profile` cargo parameter.
Reth includes several profiles which can be selected via the Cargo flag `--profile`.

* `release`: default for source builds, enables most optimisations while not taking too long to
compile.
* `maxperf`: default for binary releases, enables aggressive optimisations including full LTO.
Although compiling with this profile improves some benchmarks by around 20% compared to `release`,
it imposes a _significant_ cost at compile time and is only recommended if you have a fast CPU.

**Rust compiler flags**

You can also use `RUSTFLAGS="-C target-cpu=native"` to enable CPU-specific optimisations. In order to get
the highest performance out of your build:

```bash
RUSTFLAGS="-C target-cpu=native" cargo build --profile maxperf
```

**Features**

Finally, some features may improve performance on your system, most notably `jemalloc`, which replaces the default memory allocator used by reth.

You can enable features by passing them to the `--features` Cargo flag.

> **Note**
>
> The `jemalloc` feature is unstable on Windows due to jemallocator itself.
## Troubleshooting

### Command is not found

Reth will be installed to `CARGO_HOME` or `$HOME/.cargo`. This directory
needs to be on your `PATH` before you can run `$ reth`.
Reth will be installed to `CARGO_HOME` or `$HOME/.cargo`. This directory needs to be on your `PATH` before you can run `$ reth`.

See ["Configuring the `PATH` environment variable"](https://www.rust-lang.org/tools/install) for more information.

Expand Down
Loading

0 comments on commit d65032e

Please sign in to comment.