diff --git a/book/SUMMARY.md b/book/SUMMARY.md index 2aa0478a0..8acb29ac6 100644 --- a/book/SUMMARY.md +++ b/book/SUMMARY.md @@ -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) \ No newline at end of file + 1. [Contribute](./developers/contribute.md) + 1. [Architecture](./developers/architecture.md) \ No newline at end of file diff --git a/book/faq/README.md b/book/faq/README.md deleted file mode 100644 index 4514b4c10..000000000 --- a/book/faq/README.md +++ /dev/null @@ -1 +0,0 @@ -# FAQ diff --git a/book/installation/binaries.md b/book/installation/binaries.md index 32dd26e61..20348a090 100644 --- a/book/installation/binaries.md +++ b/book/installation/binaries.md @@ -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`. \ No newline at end of file +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`. \ No newline at end of file diff --git a/book/installation/docker.md b/book/installation/docker.md index 392d6d577..6fc29fd1f 100644 --- a/book/installation/docker.md +++ b/book/installation/docker.md @@ -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 +``` -To build the image from source, navigate to -the root of the repository and run: +If you can see the latest [Reth release](https://github.com/paradigmxyz/reth/releases) version, then you've successfully installed Reth via Docker. + +## 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 @@ -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/ - diff --git a/book/installation/installation.md b/book/installation/installation.md index 2023fb0d5..e3ce069af 100644 --- a/book/installation/installation.md +++ b/book/installation/installation.md @@ -3,26 +3,40 @@ 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 @@ -30,7 +44,7 @@ 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 diff --git a/book/installation/source.md b/book/installation/source.md index 02f5b2a43..63c62af59 100644 --- a/book/installation/source.md +++ b/book/installation/source.md @@ -2,7 +2,7 @@ You can build Reth on Linux, macOS, and Windows WSL. -# Dependencies +## Dependencies First, **install Rust** using [rustup](https://rustup.rs/)： @@ -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 @@ -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: @@ -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 @@ -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 -``` - -Compilation may take around 10 minutes. Installation was successful if `reth --help` displays -the [command-line documentation](../cli/cli.md). - -If you run into any issues, please check the [Troubleshooting](#troubleshooting) section. -out to us on [Telegram](https://t.me/paradigm_reth). +If you run into any issues, please check the [Troubleshooting](#troubleshooting) section, or reach out to us on [Telegram](https://t.me/paradigm_reth). ## Update Reth -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. +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 @@ -75,12 +71,14 @@ 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. @@ -88,6 +86,8 @@ Reth includes several profiles which can be selected via the `--profile` cargo p 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: @@ -95,12 +95,21 @@ the highest performance out of your build: 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. diff --git a/book/intro.md b/book/intro.md index aa9bb38c2..51090d198 100644 --- a/book/intro.md +++ b/book/intro.md @@ -1,5 +1,7 @@ # Reth Book -_Documentation for Reth users and developers._ [![Telegram Chat][tg-badge]][tg-url] +_Documentation for Reth users and developers._ + +[![Telegram Chat][tg-badge]][tg-url] Reth (short for Rust Ethereum, [pronunciation](https://twitter.com/kelvinfichter/status/1597653609411268608)) is an **Ethereum full node implementation that is focused on being user-friendly, highly modular, as well as being fast and efficient.** @@ -7,21 +9,53 @@ Reth (short for Rust Ethereum, [pronunciation](https://twitter.com/kelvinfichter -# What is this about? +## What is this about? -[Reth](https://github.com/paradigmxyz/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/59e3a719021f48c1ef5653840e3ea5750e6af693/src/engine). It is originally built and driven forward by [Paradigm](https://paradigm.xyz/), and is licensed under the Apache and MIT licenses. +[Reth](https://github.com/paradigmxyz/reth/) is an execution layer (EL) implementation that is compatible with all Ethereum consensus layer (CL) implementations that support the [Engine API](https://github.com/ethereum/execution-apis/tree/59e3a719021f48c1ef5653840e3ea5750e6af693/src/engine). -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. +It is originally built and driven forward by [Paradigm](https://paradigm.xyz/), and is licensed under the Apache and MIT licenses. -# What are the goals of Reth? +As a full Ethereum node, Reth allows users to connect to the Ethereum network and interact with the Ethereum blockchain. -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. -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 [ethers-rs](https://github.com/gakonst/ethers-rs/) 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. **Used by a wide demographic**: 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 for the tradeoffs that each team faces. +This includes sending and receiving transactions, querying logs and traces, as well as accessing and interacting with smart contracts. -# Who is this for? +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. + +## What are the goals of Reth? + +**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. + +**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 [ethers-rs](https://github.com/gakonst/ethers-rs/) 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. Used by a wide demographic** + +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 for the tradeoffs that each team faces. + +## Who is this for? Reth is a new Ethereum full node that allows users to sync and interact with the entire blockchain, including its historical state if in archive mode. - Full node: It can be used as a full node, which stores and processes the entire blockchain, validates blocks and transactions, and participates in the consensus process. @@ -29,24 +63,25 @@ Reth is a new Ethereum full node that allows users to sync and interact with the As a data engineer/analyst, or as a data indexer, you'll want to use Archive mode. For all other use cases where historical access is not needed, you can use Full mode. -# Is this secure? +## Is this secure? Reth implements the specification of Ethereum as defined in the [ethereum/execution-specs](https://github.com/ethereum/execution-specs/) repository. To make sure the node is built securelty, we run the following tests: + 1. EVM state tests are run on every [Revm Pull Request](https://github.com/bluealloy/revm/blob/main/.github/workflows/ethereum-tests.yml) -2. Hive tests are [run every 24 hours](https://github.com/paradigmxyz/reth/blob/main/.github/workflows/hive.yml) in the main Reth repository. -3. We regularly re-sync multiple nodes from scratch. -4. We operate multiple nodes at the tip of Ethereum mainnet and various testnets. -5. We extensively unit test, fuzz test and document all our code, while also restricting PRs with aggressive lint rules. +1. Hive tests are [run every 24 hours](https://github.com/paradigmxyz/reth/blob/main/.github/workflows/hive.yml) in the main Reth repository. +1. We regularly re-sync multiple nodes from scratch. +1. We operate multiple nodes at the tip of Ethereum mainnet and various testnets. +1. We extensively unit test, fuzz test and document all our code, while also restricting PRs with aggressive lint rules. We intend to also audit / fuzz the EVM & parts of the codebase. Please reach out if you're interested in collaborating on securing this codebase. -# Sections +## Sections Here are some useful sections to jump to: - Install Reth by following the [guide](./installation/installation.md). -- Sync your node on any [official network](./run/run_a_node.md), or [spin up your own testnet](./run/local_testnet.md)! -- View [statistics and metrics](./run/observability.md) about your node +- Sync your node on any [official network](./run/run_a_node.md). +- View [statistics and metrics](./run/observability.md) about your node. - Query the [JSON-RPC](./api/api.md) using Foundry's `cast` or `curl`. - Set up your [development environment and contribute](./contribute.md)! diff --git a/book/jsonrpc/admin.md b/book/jsonrpc/admin.md index 0b4cd6b1b..67b520b86 100644 --- a/book/jsonrpc/admin.md +++ b/book/jsonrpc/admin.md @@ -1 +1,136 @@ -# admin +# `admin` Namespace + +The `admin` API allows you to configure your node, including adding and removing peers. + +> **Note** +> +> As this namespace can configure your node at runtime, it is generally **not advised** to expose it publicly. + +## `admin_addPeer` + +Add the given peer to the current peer set of the node. + +The method accepts a single argument, the [`enode`][enode] URL of the remote peer to connect to, and returns a `bool` indicating whether the peer was accepted or not. + +| Client | Method invocation | +|--------|------------------------------------------------| +| RPC | `{"method": "admin_addPeer", "params": [url]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"admin_addPeer","params":["enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303"]} +{"jsonrpc":"2.0","id":1,"result":true} +``` + +## `admin_removePeer` + +Disconnects from a peer if the connection exists. Returns a `bool` indicating whether the peer was successfully removed or not. + +| Client | Method invocation | +|--------|-------------------------------------------------------| +| RPC | `{"method": "admin_removePeer", "params": [url]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"admin_removePeer","params":["enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303"]} +{"jsonrpc":"2.0","id":1,"result":true} +``` + +## `admin_addTrustedPeer` + +Adds the given peer to a list of trusted peers, which allows the peer to always connect, even if there would be no room for it otherwise. + +It returns a `bool` indicating whether the peer was added to the list or not. + +| Client | Method invocation | +|--------|-------------------------------------------------------| +| RPC | `{"method": "admin_addTrustedPeer", "params": [url]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"admin_addTrustedPeer","params":["enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303"]} +{"jsonrpc":"2.0","id":1,"result":true} +``` + +## `admin_removeTrustedPeer` + +Removes a remote node from the trusted peer set, but it does not disconnect it automatically. + +Returns true if the peer was successfully removed. + +| Client | Method invocation | +|--------|----------------------------------------------------------| +| RPC | `{"method": "admin_removeTrustedPeer", "params": [url]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"admin_removeTrustedPeer","params":["enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303"]} +{"jsonrpc":"2.0","id":1,"result":true} +``` + +## `admin_nodeInfo` + +Returns all information known about the running node. + +These include general information about the node itself, as well as what protocols it participates in, its IP and ports. + +| Client | Method invocation | +|--------|--------------------------------| +| RPC | `{"method": "admin_nodeInfo"}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"admin_nodeInfo","params":[]} +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "enode": "enode://44826a5d6a55f88a18298bca4773fca5749cdc3a5c9f308aa7d810e9b31123f3e7c5fba0b1d70aac5308426f47df2a128a6747040a3815cc7dd7167d03be320d@[::]:30303", + "id": "44826a5d6a55f88a18298bca4773fca5749cdc3a5c9f308aa7d810e9b31123f3e7c5fba0b1d70aac5308426f47df2a128a6747040a3815cc7dd7167d03be320d", + "ip": "::", + "listenAddr": "[::]:30303", + "name": "reth/v0.0.1/x86_64-unknown-linux-gnu", + "ports": { + "discovery": 30303, + "listener": 30303 + }, + "protocols": { + "eth": { + "difficulty": 17334254859343145000, + "genesis": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", + "head": "0xb83f73fbe6220c111136aefd27b160bf4a34085c65ba89f24246b3162257c36a", + "network": 1 + } + } + } +} +``` + +## `admin_peerEvents`, `admin_peerEvents_unsubscribe` + + + +Subscribe to events received by peers over the network. + +Like other subscription methods, this returns the ID of the subscription, which is then used in all events subsequently. + +To unsubscribe from peer events, call `admin_peerEvents_unsubscribe` + +| Client | Method invocation | +|--------|----------------------------------| +| RPC | `{"method": "admin_peerEvents"}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"admin_peerEvents","params":[]} +// responds with subscription ID +{"jsonrpc": "2.0", "id": 1, "result": "0xcd0c3e8af590364c09d0fa6a1210faf5"} +``` + +[enode]: https://ethereum.org/en/developers/docs/networking-layer/network-addresses/#enode \ No newline at end of file diff --git a/book/jsonrpc/debug.md b/book/jsonrpc/debug.md new file mode 100644 index 000000000..1556bd343 --- /dev/null +++ b/book/jsonrpc/debug.md @@ -0,0 +1,101 @@ +# `debug` Namespace + +The `debug` API provides several methods to inspect the Ethereum state, including Geth-style traces. + +## `debug_getRawHeader` + +Returns an RLP-encoded header. + +| Client | Method invocation | +|--------|-------------------------------------------------------| +| RPC | `{"method": "debug_getRawHeader", "params": [block]}` | + +## `debug_getRawBlock` + +Retrieves and returns the RLP encoded block by number, hash or tag. + +| Client | Method invocation | +|--------|------------------------------------------------------| +| RPC | `{"method": "debug_getRawBlock", "params": [block]}` | + +## `debug_getRawTransaction` + +Returns an EIP-2718 binary-encoded transaction. + +| Client | Method invocation | +|--------|--------------------------------------------------------------| +| RPC | `{"method": "debug_getRawTransaction", "params": [tx_hash]}` | + +## `debug_getRawReceipts` + +Returns an array of EIP-2718 binary-encoded receipts. + +| Client | Method invocation | +|--------|---------------------------------------------------------| +| RPC | `{"method": "debug_getRawReceipts", "params": [block]}` | + +## `debug_getBadBlocks` + +Returns an array of recent bad blocks that the client has seen on the network. + +| Client | Method invocation | +|--------|--------------------------------------------------| +| RPC | `{"method": "debug_getBadBlocks", "params": []}` | + +## `debug_traceChain` + +Returns the structured logs created during the execution of EVM between two blocks (excluding start) as a JSON object. + +| Client | Method invocation | +|--------|----------------------------------------------------------------------| +| RPC | `{"method": "debug_traceChain", "params": [start_block, end_block]}` | + +## `debug_traceBlock` + +The `debug_traceBlock` method will return a full stack trace of all invoked opcodes of all transaction that were included in this block. + +This expects an RLP-encoded block. + +> **Note** +> +> The parent of this block must be present, or it will fail. + +| Client | Method invocation | +|--------|---------------------------------------------------------| +| RPC | `{"method": "debug_traceBlock", "params": [rlp, opts]}` | + +## `debug_traceBlockByHash` + +Similar to [`debug_traceBlock`](#debug_traceblock), `debug_traceBlockByHash` accepts a block hash and will replay the block that is already present in the database. + +| Client | Method invocation | +|--------|----------------------------------------------------------------------| +| RPC | `{"method": "debug_traceBlockByHash", "params": [block_hash, opts]}` | + +## `debug_traceBlockByNumber` + +Similar to [`debug_traceBlockByHash`](#debug_traceblockbyhash), `debug_traceBlockByNumber` accepts a block number and will replay the block that is already present in the database. + +| Client | Method invocation | +|--------|--------------------------------------------------------------------------| +| RPC | `{"method": "debug_traceBlockByNumber", "params": [block_number, opts]}` | + +## `debug_traceTransaction` + +The `debug_traceTransaction` debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given hash. + +| Client | Method invocation | +|--------|-------------------------------------------------------------| +| RPC | `{"method": "debug_traceBlock", "params": [tx_hash, opts]}` | + +## `debug_traceCall` + +The `debug_traceCall` method lets you run an `eth_call` within the context of the given block execution using the final state of parent block as the base. + +The first argument (just as in `eth_call`) is a transaction request. + +The block can optionally be specified either by hash or by number as the second argument. + +| Client | Method invocation | +|--------|-----------------------------------------------------------------------| +| RPC | `{"method": "debug_traceCall", "params": [call, block_number, opts]}` | diff --git a/book/jsonrpc/engine.md b/book/jsonrpc/engine.md deleted file mode 100644 index 416383b13..000000000 --- a/book/jsonrpc/engine.md +++ /dev/null @@ -1 +0,0 @@ -# Configuring the Engine API diff --git a/book/jsonrpc/eth.md b/book/jsonrpc/eth.md index 4074fe760..0a3003c40 100644 --- a/book/jsonrpc/eth.md +++ b/book/jsonrpc/eth.md @@ -1 +1,3 @@ -# eth +# `eth` Namespace + +Documentation for the API methods in the `eth` namespace can be found on [ethereum.org](https://ethereum.org/en/developers/docs/apis/json-rpc/). diff --git a/book/jsonrpc/intro.md b/book/jsonrpc/intro.md index 2ff691a5d..4f3e72bb3 100644 --- a/book/jsonrpc/intro.md +++ b/book/jsonrpc/intro.md @@ -1,20 +1,112 @@ -# JSON-RPC Namespaces +# JSON-RPC -Reth supports all standard Ethereum JSON-RPC API methods. The API methods are grouped into namespaces, which are listed below: -* [admin](./admin.md): Administrative APIs for the node. DO NOT expose these APIs to the public internet. -* [eth](./eth.md): Ethereum APIs for interacting with the Ethereum blockchain. -* [tracing](./tracing.md): APIs for tracing the execution of transactions, compatible with the popular [Parity Tracing module](https://openethereum.github.io/JSONRPC-trace-module). -* [debug](./debug.md): APIs for debugging the node, originally created by Geth. - +You can interact with Reth over JSON-RPC. Reth supports all standard Ethereum JSON-RPC API methods. -One can easily interact with these APIs just like they would with any Ethereum client. You can use curl, a programming language with a low-level library, or a tool like Foundry to interact with the chain at the exposed HTTP or WS port. As a reminder, you need to run the command below to enable all of these apis: +JSON-RPC is provided on multiple transports. Reth supports HTTP, WebSocket and IPC (both UNIX sockets and Windows named pipes). Transports must be enabled through command-line flags. + +The JSON-RPC APIs are grouped into namespaces, depending on their purpose. All method names are composed of their namespace and their name, separated by an underscore. + +Each namespace must be explicitly enabled. + +## Namespaces + +The methods are grouped into namespaces, which are listed below: + +| Namespace | Description | Sensitive | +|-------------------------|--------------------------------------------------------------------------------------------------------|-----------| +| [`eth`](./eth.md) | The `eth` API allows you to interact with Ethereum. | Maybe | +| [`web3`](./web3.md) | The `web3` API provides utility functions for the web3 client. | No | +| [`net`](./net.md) | The `net` API provides access to network information of the node. | No | +| [`txpool`](./txpool.md) | The `txpool` API allows you to inspect the transaction pool. | No | +| [`debug`](./debug.md) | The `debug` API provides several methods to inspect the Ethereum state, including Geth-style traces. | No | +| [`trace`](./trace.md) | The `trace` API provides several methods to inspect the Ethereum state, including Parity-style traces. | No | +| [`admin`](./admin.md) | The `admin` API allows you to configure your node. | **Yes** | +| [`rpc`](./rpc.md) | The `rpc` API provides information about the RPC server and its modules. | No | + +Note that some APIs are sensitive, since they can be used to configure your node (`admin`), or access accounts stored on the node (`eth`). + +Generally, it is advisable to not expose any JSONRPC namespace publicly, unless you know what you are doing. + + +## Transports + +Reth supports HTTP, WebSockets and IPC. + +### HTTP + +Using the HTTP transport, clients send a request to the server and immediately get a response back. The connection is closed after the response for a given request is sent. + +Because HTTP is unidirectional, subscriptions are not supported. + +To start an HTTP server, pass `--http` to `reth node`: + +```bash +reth node --http +``` + +The default port is `8545`, and the default listen address is localhost. + +You can configure the listen address and port using `--http.addr` and `--http.port` respectively: + +```bash +reth node --http --http.addr 127.0.0.1 --http.port 12345 +``` + +To enable JSON-RPC namespaces on the HTTP server, pass each namespace separated by a comma to `--http.api`: + +```bash +reth node --http --http.api eth,net,trace +``` + +You can also restrict who can access the HTTP server by specifying a domain for Cross-Origin requests. This is important, since any application local to your node will be able to access the RPC server: + +```bash +reth node --http --http.corsdomain https://mycoolapp.rs +``` + +Alternatively, if you want to allow any domain, you can pass `*`: + +```bash +reth node --http --http.corsdomain "*" +``` + +### WebSockets + +WebSockets is a bidirectional transport protocol. Most modern browsers support WebSockets. + +A WebSocket connection is maintained until it is explicitly terminated by either the client or the node. + +Because WebSockets are bidirectional, nodes can push events to clients, which enables clients to subscribe to specific events, such as new transactions in the transaction pool, and new logs for smart contracts. + +The configuration of the WebSocket server follows the same pattern as the HTTP server: + +- Enable it using `--ws` +- Configure the server address by passing `--ws.addr` and `--ws.port` (default `8546`) +- Configure cross-origin requests using `--ws.origins` +- Enable APIs using `--ws.api` + +### IPC + +IPC is a simpler transport protocol for use in local environments where the node and the client exist on the same machine. + +The IPC transport is enabled by default and has access to all namespaces, unless explicitly disabled with `--ipcdisable`. + +Reth creates a UNIX socket on Linux and macOS at `/tmp/reth.ipc`. On Windows, IPC is provided using named pipes at `\\.\pipe\reth.ipc`. + +You can configure the IPC path using `--ipcpath`. + +## Interacting with the RPC + +One can easily interact with these APIs just like they would with any Ethereum client. + +You can use `curl`, a programming language with a low-level library, or a tool like Foundry to interact with the chain at the exposed HTTP or WS port. + +As a reminder, you need to run the command below to enable all of these APIs using an HTTP transport: ```bash RUST_LOG=info reth node --http --http.api "admin,debug,eth,net,trace,txpool,web3,rpc" ``` -> The IPC transport is also supported with `--ipc`! - This allows you to then call: ```bash diff --git a/book/jsonrpc/net.md b/book/jsonrpc/net.md new file mode 100644 index 000000000..ac40c75b2 --- /dev/null +++ b/book/jsonrpc/net.md @@ -0,0 +1,48 @@ +# `net` Namespace + +The `net` API provides information about the networking component of the node. + +## `net_listening` + +Returns a `bool` indicating whether or not the node is listening for network connections. + +| Client | Method invocation | +|--------|---------------------------------------------| +| RPC | `{"method": "net_listening", "params": []}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"net_listening","params":[]} +{"jsonrpc":"2.0","id":1,"result":true} +``` + +## `net_peerCount` + +Returns the number of peers connected to the node. + +| Client | Method invocation | +|--------|---------------------------------------------| +| RPC | `{"method": "net_peerCount", "params": []}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"net_peerCount","params":[]} +{"jsonrpc":"2.0","id":1,"result":10} +``` + +## `net_version` + +Returns the network ID (e.g. 1 for mainnet) + +| Client | Method invocation | +|--------|-------------------------------------------| +| RPC | `{"method": "net_version", "params": []}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"net_version","params":[]} +{"jsonrpc":"2.0","id":1,"result":1} +``` \ No newline at end of file diff --git a/book/jsonrpc/rpc.md b/book/jsonrpc/rpc.md new file mode 100644 index 000000000..30608cd3a --- /dev/null +++ b/book/jsonrpc/rpc.md @@ -0,0 +1,18 @@ +# `rpc` Namespace + +The `rpc` API provides methods to get information about the RPC server itself, such as the enabled namespaces. + +## `rpc_modules` + +Lists the enabled RPC namespaces and the versions of each. + +| Client | Method invocation | +|--------|-------------------------------------------| +| RPC | `{"method": "rpc_modules", "params": []}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"rpc_modules","params":[]} +{"jsonrpc":"2.0","id":1,"result":{"txpool":"1.0","eth":"1.0","rpc":"1.0"}} +``` \ No newline at end of file diff --git a/book/jsonrpc/trace.md b/book/jsonrpc/trace.md new file mode 100644 index 000000000..6a9547c61 --- /dev/null +++ b/book/jsonrpc/trace.md @@ -0,0 +1,433 @@ +# `trace` Namespace + + + +The `trace` API provides several methods to inspect the Ethereum state, including Parity-style traces. + +A similar module exists (with other debug functions) with Geth-style traces ([`debug`](./debug.md)). + +The `trace` API gives deeper insight into transaction processing. + +There are two types of methods in this API: + +- **Ad-hoc tracing APIs** for performing diagnostics on calls or transactions (historical or hypothetical). +- **Transaction-trace filtering APIs** for getting full externality traces on any transaction executed by reth. + +## Ad-hoc tracing APIs + +Ad-hoc tracing APIs allow you to perform diagnostics on calls or transactions (historical or hypothetical), including: + +- Transaction traces (`trace`) +- VM traces (`vmTrace`) +- State difference traces (`stateDiff`) + +The ad-hoc tracing APIs are: + +- [`trace_call`](#trace_call) +- [`trace_callMany`](#trace_callmany) +- [`trace_rawTransaction`](#trace_rawtransaction) +- [`trace_replayBlockTransactions`](#trace_replayblocktransactions) +- [`trace_replayTransaction`](#trace_replaytransaction) + +## Transaction-trace filtering APIs + +Transaction trace filtering APIs are similar to log filtering APIs in the `eth` namespace, except these allow you to search and filter based only upon address information. + +Information returned includes the execution of all contract creations, destructions, and calls, together with their input data, output data, gas usage, transfer amounts and success statuses. + +The transaction trace filtering APIs are: + +- [`trace_block`](#trace_block) +- [`trace_filter`](#trace_filter) +- [`trace_get`](#trace_get) +- [`trace_transaction`](#trace_transaction) + +## `trace_call` + +Executes the given call and returns a number of possible traces for it. + +The first parameter is a transaction object where the `from` field is optional and the `nonce` field is ommitted. + +The second parameter is an array of one or more trace types (`vmTrace`, `trace`, `stateDiff`). + +The third and optional parameter is a block number, block hash, or a block tag (`latest`, `finalized`, `safe`, `earliest`, `pending`). + +| Client | Method invocation | +|--------|-----------------------------------------------------------| +| RPC | `{"method": "trace_call", "params": [tx, type[], block]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"trace_call","params":[{},["trace"]} +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "output": "0x", + "stateDiff": null, + "trace": [{ + "action": { ... }, + "result": { + "gasUsed": "0x0", + "output": "0x" + }, + "subtraces": 0, + "traceAddress": [], + "type": "call" + }], + "vmTrace": null + } +} +``` + +## `trace_callMany` + +Performs multiple call traces on top of the same block, that is, transaction `n` will be executed on top of a pending block with all `n - 1` transaction applied (and traced) first. + +The first parameter is a list of call traces, where each call trace is of the form `[tx, type[]]` (see [`trace_call`](#trace_call)). + +The second and optional parameter is a block number, block hash, or a block tag (`latest`, `finalized`, `safe`, `earliest`, `pending`). + +| Client | Method invocation | +|--------|--------------------------------------------------------| +| RPC | `{"method": "trace_call", "params": [trace[], block]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"trace_callMany","params":[[[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]],[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]]],"latest"]} +{ + "id": 1, + "jsonrpc": "2.0", + "result": [ + { + "output": "0x", + "stateDiff": null, + "trace": [{ + "action": { + "callType": "call", + "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1", + "gas": "0x1dcd12f8", + "input": "0x", + "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "value": "0x186a0" + }, + "result": { + "gasUsed": "0x0", + "output": "0x" + }, + "subtraces": 0, + "traceAddress": [], + "type": "call" + }], + "vmTrace": null + }, + { + "output": "0x", + "stateDiff": null, + "trace": [{ + "action": { + "callType": "call", + "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1", + "gas": "0x1dcd12f8", + "input": "0x", + "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "value": "0x186a0" + }, + "result": { + "gasUsed": "0x0", + "output": "0x" + }, + "subtraces": 0, + "traceAddress": [], + "type": "call" + }], + "vmTrace": null + } + ] +} +``` + +## `trace_rawTransaction` + +Traces a call to `eth_sendRawTransaction` without making the call, returning the traces. + +| Client | Method invocation | +|--------|--------------------------------------------------------| +| RPC | `{"method": "trace_call", "params": [raw_tx, type[]]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"trace_rawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",["trace"]]} +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "output": "0x", + "stateDiff": null, + "trace": [{ + "action": { ... }, + "result": { + "gasUsed": "0x0", + "output": "0x" + }, + "subtraces": 0, + "traceAddress": [], + "type": "call" + }], + "vmTrace": null + } +} +``` + +## `trace_replayBlockTransactions` + +Replays all transactions in a block returning the requested traces for each transaction. + +| Client | Method invocation | +|--------|--------------------------------------------------------------------------| +| RPC | `{"method": "trace_replayBlockTransactions", "params": [block, type[]]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"trace_replayBlockTransactions","params":["0x2ed119",["trace"]]} +{ + "id": 1, + "jsonrpc": "2.0", + "result": [ + { + "output": "0x", + "stateDiff": null, + "trace": [{ + "action": { ... }, + "result": { + "gasUsed": "0x0", + "output": "0x" + }, + "subtraces": 0, + "traceAddress": [], + "type": "call" + }], + "transactionHash": "0x...", + "vmTrace": null + }, + { ... } + ] +} +``` + +## `trace_replayTransaction` + +Replays a transaction, returning the traces. + +| Client | Method invocation | +|--------|----------------------------------------------------------------------| +| RPC | `{"method": "trace_replayTransaction", "params": [tx_hash, type[]]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"trace_replayTransaction","params":["0x02d4a872e096445e80d05276ee756cefef7f3b376bcec14246469c0cd97dad8f",["trace"]]} +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "output": "0x", + "stateDiff": null, + "trace": [{ + "action": { ... }, + "result": { + "gasUsed": "0x0", + "output": "0x" + }, + "subtraces": 0, + "traceAddress": [], + "type": "call" + }], + "vmTrace": null + } +} +``` + +## `trace_block` + +Returns traces created at given block. + +| Client | Method invocation | +|--------|------------------------------------------------| +| RPC | `{"method": "trace_block", "params": [block]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"trace_block","params":["0x2ed119"]} +{ + "id": 1, + "jsonrpc": "2.0", + "result": [ + { + "action": { + "callType": "call", + "from": "0xaa7b131dc60b80d3cf5e59b5a21a666aa039c951", + "gas": "0x0", + "input": "0x", + "to": "0xd40aba8166a212d6892125f079c33e6f5ca19814", + "value": "0x4768d7effc3fbe" + }, + "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add", + "blockNumber": 3068185, + "result": { + "gasUsed": "0x0", + "output": "0x" + }, + "subtraces": 0, + "traceAddress": [], + "transactionHash": "0x07da28d752aba3b9dd7060005e554719c6205c8a3aea358599fc9b245c52f1f6", + "transactionPosition": 0, + "type": "call" + }, + ... + ] +} +``` + +## `trace_filter` + +Returns traces matching given filter. + +Filters are objects with the following properties: + +- `fromBlock`: Returns traces from the given block (a number, hash, or a tag like `latest`). +- `toBlock`: Returns traces to the given block. +- `fromAddress`: Sent from these addresses +- `toAddress`: Sent to these addresses +- `after`: The offset trace number +- `count`: The number of traces to display in a batch + +All properties are optional. + +| Client | Method invocation | +|--------|--------------------------------------------------| +| RPC | `{"method": "trace_filter", "params": [filter]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"trace_filter","params":[{"fromBlock":"0x2ed0c4","toBlock":"0x2ed128","toAddress":["0x8bbB73BCB5d553B5A556358d27625323Fd781D37"],"after":1000,"count":100}]} +{ + "id": 1, + "jsonrpc": "2.0", + "result": [ + { + "action": { + "callType": "call", + "from": "0x32be343b94f860124dc4fee278fdcbd38c102d88", + "gas": "0x4c40d", + "input": "0x", + "to": "0x8bbb73bcb5d553b5a556358d27625323fd781d37", + "value": "0x3f0650ec47fd240000" + }, + "blockHash": "0x86df301bcdd8248d982dbf039f09faf792684e1aeee99d5b58b77d620008b80f", + "blockNumber": 3068183, + "result": { + "gasUsed": "0x0", + "output": "0x" + }, + "subtraces": 0, + "traceAddress": [], + "transactionHash": "0x3321a7708b1083130bd78da0d62ead9f6683033231617c9d268e2c7e3fa6c104", + "transactionPosition": 3, + "type": "call" + }, + ... + ] +} +``` + +## `trace_get` + +Returns trace at given position. + +| Client | Method invocation | +|--------|----------------------------------------------------------| +| RPC | `{"method": "trace_get", "params": [tx_hash,indices[]]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]]} +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "action": { + "callType": "call", + "from": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750", + "gas": "0x13e99", + "input": "0x16c72721", + "to": "0x2bd2326c993dfaef84f696526064ff22eba5b362", + "value": "0x0" + }, + "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add", + "blockNumber": 3068185, + "result": { + "gasUsed": "0x183", + "output": "0x0000000000000000000000000000000000000000000000000000000000000001" + }, + "subtraces": 0, + "traceAddress": [ + 0 + ], + "transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3", + "transactionPosition": 2, + "type": "call" + } +} +``` + +## `trace_transaction` + +Returns all traces of given transaction + +| Client | Method invocation | +|--------|--------------------------------------------------------| +| RPC | `{"method": "trace_transaction", "params": [tx_hash]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"trace_transaction","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3"]} +{ + "id": 1, + "jsonrpc": "2.0", + "result": [ + { + "action": { + "callType": "call", + "from": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750", + "gas": "0x13e99", + "input": "0x16c72721", + "to": "0x2bd2326c993dfaef84f696526064ff22eba5b362", + "value": "0x0" + }, + "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add", + "blockNumber": 3068185, + "result": { + "gasUsed": "0x183", + "output": "0x0000000000000000000000000000000000000000000000000000000000000001" + }, + "subtraces": 0, + "traceAddress": [ + 0 + ], + "transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3", + "transactionPosition": 2, + "type": "call" + }, + ... + ] +} +``` \ No newline at end of file diff --git a/book/jsonrpc/tracing.md b/book/jsonrpc/tracing.md deleted file mode 100644 index fd6ce8645..000000000 --- a/book/jsonrpc/tracing.md +++ /dev/null @@ -1 +0,0 @@ -# tracing diff --git a/book/jsonrpc/txpool.md b/book/jsonrpc/txpool.md new file mode 100644 index 000000000..72fccc15f --- /dev/null +++ b/book/jsonrpc/txpool.md @@ -0,0 +1,43 @@ +# `txpool` Namespace + +The `txpool` API allows you to inspect the transaction pool. + +## `txpool_content` + +Returns the details of all transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. + +See [here](https://geth.ethereum.org/docs/rpc/ns-txpool#txpool_content) for more details + +| Client | Method invocation | +|--------|----------------------------------------------| +| RPC | `{"method": "txpool_content", "params": []}` | + +## `txpool_contentFrom` + +Retrieves the transactions contained within the txpool, returning pending as well as queued transactions of this address, grouped by nonce. + +See [here](https://geth.ethereum.org/docs/rpc/ns-txpool#txpool_contentFrom) for more details + +| Client | Method invocation | +|--------|---------------------------------------------------------| +| RPC | `{"method": "txpool_contentFrom", "params": [address]}` | + +## `txpool_inspect` + +Returns a summary of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. + +See [here](https://geth.ethereum.org/docs/rpc/ns-txpool#txpool_inspect) for more details + +| Client | Method invocation | +|--------|----------------------------------------------| +| RPC | `{"method": "txpool_inspect", "params": []}` | + +## `txpool_status` + +Returns the number of transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. + +See [here](https://geth.ethereum.org/docs/rpc/ns-txpool#txpool_status) for more details + +| Client | Method invocation | +|--------|---------------------------------------------| +| RPC | `{"method": "txpool_status", "params": []}` | \ No newline at end of file diff --git a/book/jsonrpc/web3.md b/book/jsonrpc/web3.md new file mode 100644 index 000000000..d6ab8bf33 --- /dev/null +++ b/book/jsonrpc/web3.md @@ -0,0 +1,34 @@ +# `web3` Namespace + +The `web3` API provides utility functions for the web3 client. + +## `web3_clientVersion` + +Get the web3 client version. + + +| Client | Method invocation | +|--------|------------------------------------| +| RPC | `{"method": "web3_clientVersion"}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"web3_clientVersion","params":[]} +{"jsonrpc":"2.0","id":1,"result":"reth/v0.0.1/x86_64-unknown-linux-gnu"} +``` + +## `web3_sha3` + +Get the Keccak-256 hash of the given data. + +| Client | Method invocation | +|--------|----------------------------------------------| +| RPC | `{"method": "web3_sha3", "params": [bytes]}` | + +### Example + +```js +// > {"jsonrpc":"2.0","id":1,"method":"web3_sha3","params":["rust is awesome"]} +{"jsonrpc":"2.0","id":1,"result":"0xe421b3428564a5c509ac118bad93a3b84485ec3f927e214b0c4c23076d4bc4e0"} +``` \ No newline at end of file diff --git a/book/run/config.md b/book/run/config.md index 35d8fc15b..ea29fd80e 100644 --- a/book/run/config.md +++ b/book/run/config.md @@ -1,2 +1,2 @@ -# Configuring Reth.toml +# Configuring Reth \ No newline at end of file diff --git a/book/run/local_testnet.md b/book/run/local_testnet.md deleted file mode 100644 index a93d8fd33..000000000 --- a/book/run/local_testnet.md +++ /dev/null @@ -1,3 +0,0 @@ -# Local Testnet - - \ No newline at end of file diff --git a/crates/rpc/rpc-api/src/debug.rs b/crates/rpc/rpc-api/src/debug.rs index c67f0b125..32c776338 100644 --- a/crates/rpc/rpc-api/src/debug.rs +++ b/crates/rpc/rpc-api/src/debug.rs @@ -65,7 +65,7 @@ pub trait DebugApi { opts: Option, ) -> RpcResult>; - /// Similar to `debug_traceBlockByNumber`, `debug_traceBlockByHash` accepts a block number + /// Similar to `debug_traceBlockByHash`, `debug_traceBlockByNumber` accepts a block number /// [BlockNumberOrTag] and will replay the block that is already present in the database. /// For the second parameter see [GethDebugTracingOptions]. #[method(name = "traceBlockByNumber")] @@ -86,11 +86,11 @@ pub trait DebugApi { opts: Option, ) -> RpcResult; - /// The debug_traceCall method lets you run an `eth_call` within the context of the given block - /// execution using the final state of parent block as the base. + /// The `debug_traceCall` method lets you run an `eth_call` within the context of the given + /// block execution using the final state of parent block as the base. /// - /// The first argument (just as in`eth_call`) is a transaction request. - /// The block can be specified either by hash or by number as + /// The first argument (just as in `eth_call`) is a transaction request. + /// The block can optionally be specified either by hash or by number as /// the second argument. /// The trace can be configured similar to `debug_traceTransaction`, /// see [GethDebugTracingOptions]. The method returns the same output as diff --git a/crates/rpc/rpc-api/src/net.rs b/crates/rpc/rpc-api/src/net.rs index 60cdf9378..8efa5de08 100644 --- a/crates/rpc/rpc-api/src/net.rs +++ b/crates/rpc/rpc-api/src/net.rs @@ -5,7 +5,7 @@ use reth_rpc_types::PeerCount; #[cfg_attr(not(feature = "client"), rpc(server, namespace = "net"))] #[cfg_attr(feature = "client", rpc(server, client, namespace = "net"))] pub trait NetApi { - /// Returns protocol version. + /// Returns the network ID. #[method(name = "version")] fn version(&self) -> RpcResult; diff --git a/crates/rpc/rpc-api/src/txpool.rs b/crates/rpc/rpc-api/src/txpool.rs index 429ac7d2b..550b21e26 100644 --- a/crates/rpc/rpc-api/src/txpool.rs +++ b/crates/rpc/rpc-api/src/txpool.rs @@ -9,7 +9,8 @@ use reth_rpc_types::txpool::{TxpoolContent, TxpoolContentFrom, TxpoolInspect, Tx pub trait TxPoolApi { /// Returns the number of transactions currently pending for inclusion in the next block(s), as /// well as the ones that are being scheduled for future execution only. - /// Ref: [Here](https://geth.ethereum.org/docs/rpc/ns-txpool#txpool_status) + /// + /// See [here](https://geth.ethereum.org/docs/rpc/ns-txpool#txpool_status) for more details #[method(name = "status")] async fn txpool_status(&self) -> RpcResult;