llms-full.txt

# Introduction
URL: https://docs.erigon.tech/

An efficient, modular Ethereum execution layer client built for performance, low disk footprint, and flexible deployment.

## Sections

- [Get Started](https://docs.erigon.tech/get-started): Hardware requirements, installation options, and first-run guides to get your node online fast.
- [Easy Nodes](https://docs.erigon.tech/get-started/easy-nodes): One-command guided setup for Ethereum mainnet, Gnosis Chain, and Polygon nodes with sensible defaults.
- [Fundamentals](https://docs.erigon.tech/fundamentals): Pruning modes, configuration, Docker, JWT, logging, storage optimization, and day-to-day operations.
- [Modules](https://docs.erigon.tech/fundamentals/modules): Run RPC Daemon, TxPool, Sentry, and Downloader as independent processes for scalable cluster setups.
- [Staking](https://docs.erigon.tech/staking): Solo staking with Caplin (built-in consensus layer) or pair Erigon with any external consensus client.
- [Interacting with Erigon](https://docs.erigon.tech/interacting-with-erigon): JSON-RPC and gRPC API reference — eth, debug, trace, engine, TxPool, and other namespaces.
- [Why Erigon?](https://docs.erigon.tech/get-started/why-using-erigon): Architecture advantages, performance benchmarks, and disk savings — understand what sets Erigon apart from other Ethereum execution clients.

---

# Get Started
URL: https://docs.erigon.tech/get-started

Everything you need to go from zero to a running Erigon node — requirements, installation, and guided setups.

## Sections

- [Why Erigon?](https://docs.erigon.tech/get-started/why-using-erigon): Performance benchmarks, disk savings, and architecture advantages over other Ethereum clients.
- [Hardware Requirements](https://docs.erigon.tech/get-started/hardware-requirements): Minimum and recommended specs for mainnet, testnets, and archive mode.
- [Installation](https://docs.erigon.tech/get-started/installation): Binary releases, building from source, Docker images, and upgrade instructions.
- [Easy Nodes](https://docs.erigon.tech/get-started/easy-nodes): One-command guided setup for Ethereum, Gnosis Chain, and Polygon nodes with sensible defaults.
- [Migrating from Geth](https://docs.erigon.tech/get-started/migrating-from-geth): Switch from go-ethereum to Erigon — what changes, what stays the same, and how to preserve your data.
- [Interacting with Erigon](https://docs.erigon.tech/interacting-with-erigon): JSON-RPC and gRPC API reference — eth, debug, trace, engine, TxPool, and other namespaces.

---

# Why using Erigon?
URL: https://docs.erigon.tech/get-started/why-using-erigon

## Sections

- [Integrated Consensus Layer (Caplin)](../fundamentals/caplin): Built-in consensus client — no need to run and manage separate software like Lighthouse. One binary handles both execution and consensus, simplifying setup for stakers and node runners.
- [State Storage (Flat DB)](../fundamentals/optimizing-storage): Replaces the Merkle Patricia Trie with a flat key-value database. Faster reads and writes, and a smaller on-disk footprint for any node type.
- [Immutable, Decentralised Data](../fundamentals/modules/downloader): Splits data processing into specialised stages, minimising random disk I/O and write amplification. Efficiently integrates large datasets into Erigon's flat DB.
- [Predictable RPC Performance](../fundamentals/modules/rpc-daemon): No background compaction means no unpredictable resource spikes. RPC throughput stays stable and consistent — critical for providers and validators who cannot afford surprises.
- [Modularity](../fundamentals/modules/): Core node, RPC Daemon, and TxPool run as independent processes with per-component resource limits. If one crashes the rest stay alive. Run multiple instances without downtime.
- [OtterSync](../fundamentals/pruning-modes): Shifts initial sync from CPU-intensive transaction re-execution to network download — similar to BitTorrent for state data. Reduces sync time for both full and Archive nodes.
- [Flexible Pruning](../fundamentals/optimizing-storage): Modular architecture and predictable performance handle high-volume traffic with low latency. Smaller database cuts hardware costs. Caplin reduces missed attestations and slashing risk.
- [Home Users & Solo Stakers](../staking/): Run a full or archive node on a consumer SSD. Fast sync cuts setup from days to hours. No third-party servers — your node, your keys, your contribution to decentralisation.

---

# Hardware Requirements
URL: https://docs.erigon.tech/get-started/hardware-requirements


## Overview

A locally mounted **SSD** (Solid-State Drive) or **NVMe** (Non-Volatile Memory Express) disk is essential for optimal performance. Avoid Hard Disk Drives (HDD), as they can cause Erigon to lag behind the blockchain tip, albeit not fall behind.

| Component | Recommendation | Notes |
| --- | --- | --- |
| Disk Type | Use high-end NVMe SSDs. | Avoid HDDs.SSD performance may degrade when nearing full capacity. |
| Disk Configuration | RAID 0 for multiple disks (Speed) | High-Speed Option: RAID 0 provides maximum speed but no redundancy (data loss risk).ZFS filesystems may be considered for Archive nodes for their data integrity features, but complex RAID-Z setups are generally not recommended. |
| RAM | Adequate memory is crucial | Reduces bottlenecks during sync and improves performance under load. |
| CPU | 4–8 cores for Full nodes8–16 cores for Archive nodes | More cores are generally better for intense sync and query operations. |
| Linux | Kernel version > v4 | A modern Linux distribution is required. |

## Disk Size and RAM Requirements

The amount of disk space recommended and RAM you need depends on the [pruning mode](../fundamentals/pruning-modes) you want to run. **Current Disk Usage** values listed below are obtained using the standard Erigon + [Caplin](../fundamentals/caplin) configuration, with the sole exception of the `--prune.mode` flag.

| Pruning Mode | Current Disk Usage | Disk Size (Recommended) | RAM (Required) | RAM (Recommended) |
| --- | --- | --- | --- | --- |
| Archive | — | 4 TB | 32 GB | 64 GB |
| Full (Default) | — | 2 TB | 16 GB | 32 GB |
| Minimal | — | 1 TB | 16 GB | 64 GB |

| **Pruning Mode**  | **Current Disk Usage** | **Disk Size (Recommended)** | **RAM (Required)** | **RAM (Recommended)** |
| -------------- | ---------------------- | --------------------------- | ------------------ | --------------------- |
| Archive        | — | 1 TB                        | 16 GB              | 32 GB                 |
| Full (Default) | —    | 1 TB                        | 8 GB               | 16 GB                 |
| Minimal        | — | 500 GB                      | 8 GB               | 16 GB                 |

:::warning
The final release series of Erigon that officially supports Polygon is 3.1.\*. For the software supported by Polygon, please refer to the link: [https://github.com/0xPolygon/erigon/releases](https://github.com/0xPolygon/erigon/releases). Disk usage figures below are from September 2025 and are no longer automatically updated.
:::

| **Pruning Mode**  | **Current Disk Usage** | **Disk Size (Recommended)** | **RAM (Required)** | **RAM (Recommended)** |
| -------------- | ---------------------- | --------------------------- | ------------------ | --------------------- |
| Archive        | 4.85 TB                | 8 TB                        | 64 GB              | 128 GB                |
| Full (Default) | 3.3 TB                 | 4 TB                        | 32 GB              | 64 GB                 |
| Minimal        | 1.2 TB                 | 2 TB                        | 32 GB              | 64 GB                 |

:::tip
See also how you can [optimize storage](../fundamentals/optimizing-storage).
:::

## Bandwidth Requirements

Your internet bandwidth is also an important factor, particularly for sync speed and validator performance.

| Node Type      | Bandwidth (Required) | Bandwidth (Recommended) |
| -------------- | -------------------- | ----------------------- |
| Staking/Mining | 10 Mbps              | 50 Mbps                 |
| Non-Staking    | 5 Mbps               | 25 Mbps                 |

---

# Migrating from Geth
URL: https://docs.erigon.tech/get-started/migrating-from-geth


### Migration Paths: Choosing Your Erigon Setup

When moving from another Execution Layer (EL) such as Geth, Nethermind, Reth or Besu to Erigon, node runners have a primary choice regarding their Consensus Layer (CL) setup:

* **Erigon with Caplin**: The integrated setup using Erigon's embedded CL client, [Caplin](../fundamentals/caplin). Suitable for all node types — simplifies operation by removing the need for a separate consensus client.
* **Erigon with an External Consensus Client**: This is the traditional setup, allowing to reuse an existing external CL client (like Prysm or Lighthouse).

The recommended approach involves running and syncing an **Erigon node alongside your existing Execution Layer (EL) client (like Geth)**. This allows for full functional verification, thorough testing, and a transition with **zero downtime**. Since Erigon requires **less disk space** than most clients, running both in parallel is practical for the duration of the migration.

#### Choosing Your Migration Strategy

* [Option 1](#option-1-sync-erigon-alongside-geth-and-its-cl): If you run a critical process and have enough disk space, syncing Erigon alongside Geth or any other EL is the recommended choice, and is essential for validators and RPC providers.
  * If disk space is limited and downtime is not an option, consider syncing Erigon on a separate machine.
* [Option 2](#option-2-remove-old-el-and-sync-erigon-downtime-accepted): If you are a home user or standard node runner (not running a validator), and the disk space is limited and downtime is acceptable, choose this option to remove your EL and the existing CL first.

| **Node Runner Type**                                            | **Recommended Path (If Disk Space Allows)**                                                                                        | **Rationale**                                        |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Validators                                                      | [Option 1](#option-1-sync-erigon-alongside-geth-and-its-cl): Sync Alongside Geth or any EL                   | Ensures minimal downtime and prevents slashing risk. |
| Public RPC Providers                                            | [Option 1](#option-1-sync-erigon-alongside-geth-and-its-cl): Sync Alongside Geth or any EL                   | Guarantees zero service interruption for users.      |
| Home Users / Standard Node Runners with no critical utilization | [Option 2](#option-2-remove-old-el-and-sync-erigon-downtime-accepted): Remove Geth or any EL and Sync Erigon | The fastest method if downtime is accepted.          |

### Option 1: Sync Erigon Alongside Geth and its CL

You can choose whether to migrate to Erigon + Caplin (the simplest setup) or continue using your existing CL.

This path offers the simplest validator configuration by using Erigon's embedded consensus client, Caplin. You will no longer need your external Consensus Layer (CL) client or a JWT secret for CL-EL communication.

**Steps for Minimal Downtime**

1. **Preparation**: [Install](installation/) Erigon.
2. **Configuration Check** (No Conflict): Ensure Erigon's standard [ports](../fundamentals/default-ports) (JSON-RPC, P2P) are different from Geth's. These ports are configured via the `--port` and `--p2p.allowed-ports` command-line options. For example:

    ```sh
    erigon \
      --datadir=/data/erigon \
      --chain=mainnet \
      --port=30304 \
      --p2p.allowed-ports=30310,30311,30312,30313,30314,30315,30316
    ```
3. **Synchronization**: Start syncing Erigon. Monitor the sync status using the `eth_syncing` JSON-[RPC method](../interacting-with-erigon/) or a health check.
4. **Validator Swap**: Once Erigon is fully synced, shut down Geth and the external CL client.
5. **Reconfiguration and Restart**:
   * To restart Erigon, there's no need to specify `--port` or `--P2P.allowed-ports`. Refer to this [guide](../fundamentals/caplin) for additional Erigon + Caplin configuration recommendations.
   * Crucially, reconfigure your **validator keys manager** to point directly to the Erigon Beacon API, as Erigon/Caplin now handles both layers internally).
6. **Decommission Old Setup**: Verify Erigon/Caplin is proposing and attesting blocks correctly. If confirmed, safely remove Geth, the external CL client, and all their data, including the old JWT secret.

Switch to an Erigon Execution Layer (EL) while keeping your current external Consensus Layer (CL) client (e.g., Prysm, Lighthouse) and your existing JWT secret. Start by syncing Erigon with Caplin as the CL, then configure it to use the external CL.

**Steps for Minimal Downtime**

1. **Preparation**: [Install](installation/) Erigon.
2. **Configuration Check**: run Erigon + Caplin simultaneously with Geth (or any other EL) for fast, parallel syncing and assign unique ports for its P2P networking via `--port` and `--p2p.allowed-ports` (check which ports your present
   EL is using). For example:

    ```sh
    erigon \
      --datadir=/data/erigon \
      --chain=mainnet \
      --port=30304 \
      --p2p.allowed-ports=30310,30311,30312,30313,30314,30315,30316
    ```
3. **Synchronization**: Monitor the sync status using the `eth_syncing` JSON-RPC method or a health check.
4. **Validator Swap**: Once Erigon is fully synced, **shut down** both Geth and Erigon. **Keep the external CL client running.**
5. **Reconfiguration and Restart**: Restart Erigon, ensuring it uses the **original Engine API port and JWT secret** that your old EL client used. See [here](../staking/external-consensus-client-as-validator) for details.
6. **Decommission Old Setup**: Verify Erigon and your external CL client are proposing and attesting blocks correctly. If confirmed, safely remove Geth and its data.

### Option 2: Remove Old EL and Sync Erigon (Downtime Accepted)

This is the simplest option as it requires no configuration adjustments. However, the node will be down until Erigon finishes syncing.

This path is the fastest way to get Erigon running. It utilizes **Erigon's embedded consensus client, Caplin**, requiring no external CL client or JWT secret. This is ideal for home users with limited disk space and no critical uptime requirements.

**Steps for Quickest Start**

1. **Decommission Old Setup**: Shut down and **remove your old EL** client (Geth, etc.) and its data. If you were using an external CL client, you can shut it down as well.
2. **Installation**: [Install](installation/) Erigon.
3. **Configuration**: Erigon requires no special configuration; it uses default ports and settings. The [basic setup](../fundamentals/basic-usage) is sufficient for most situations.
4. **Synchronization**: Start syncing Erigon with the default Caplin configuration (Caplin does not use the Engine API).
5. **Final Setup**: Once Erigon is fully synced, your node is online.
6. **Monitoring**: Monitor the sync progress using `eth_syncing` or the health check, and ensure no errors appear in Erigon's logs.

This path retains your existing **external Consensus Layer (CL)** client (e.g., Prysm, Lighthouse) but swaps the old EL client for Erigon. Since downtime is accepted, this process requires simpler port management.

**Steps for Quickest Start**

1. **Decommission Old Setup**: Shut down and remove your old EL client (Geth, etc.) and its data. Keep your external CL client running.
2. **Installation**: [Install](installation/) Erigon.
3.  **Configuration** (JWT and Ports): Ensure Erigon uses the same Engine API [port](../fundamentals/default-ports) (`--authrpc.port`) and JWT secret (`--authrpc.jwtsecret`) that the old EL client previously used. For example:\\

    ```sh
    erigon \
      --externalcl \
      --datadir=/data/erigon \
      --chain=mainnet \
      --authrpc.port=8551 \
      --authrpc.jwtsecret=/jwt \
      --authrpc.addr=0.0.0.0 \
      --http \
      --http.addr=0.0.0.0 \
      --http.port=8545 \
      --http.api=engine,eth,net,web3 \
      --ws \
      --ws.port=8546
    ```

    _(Otherwise, you must reconfigure your external CL client to match Erigon's default settings)_
4. **Synchronization**: Start syncing Erigon. Your external CL client will automatically connect to Erigon once Erigon is running and reachable on the Engine API port.
5. **Monitoring and Verification**: Once Erigon is fully synced, check the logs of both Erigon and the external CL client to verify correct chain following.

***

See [Basic Usage](../fundamentals/basic-usage) and [Configuring Erigon](../fundamentals/configuring-erigon/) for more details on available options.

---

# Installation
URL: https://docs.erigon.tech/get-started/installation

'install-docker':   'all-operating-systems',
  'install-prebuilt': 'linuxmacos',
  'install-source':   'linuxmacos',
  'install-native':   'windows',
  'install-wsl':      'windows',
};

  if (e) e.preventDefault();
  const el = document.getElementById(id);
  if (!el) return;

  document.querySelectorAll('details[id^="install-"]').forEach(d => {
    if (d !== el && d.open) {
      const s = d.querySelector('summary');
      if (s) s.click();
      else d.open = false;
    }
  });

  if (!el.open) {
    const summary = el.querySelector('summary');
    if (summary) summary.click();
    else el.open = true;
  }

  const sectionId = sectionForMethod[id];
  if (sectionId) {
    history.replaceState(null, '', '#' + sectionId);
  }

  const resolveTarget = () => {
    let t = sectionId && document.getElementById(sectionId);
    if (!t) {
      let cursor = el.previousElementSibling;
      while (cursor && !/^H[1-6]$/.test(cursor.tagName)) {
        cursor = cursor.previousElementSibling;
      }
      t = cursor || el;
    }
    return t;
  };

  let lastHeight = document.body.scrollHeight;
  let stableFrames = 0;
  let totalFrames = 0;
  const waitForStableLayout = () => {
    const h = document.body.scrollHeight;
    if (h === lastHeight) stableFrames++;
    else 
    totalFrames++;
    if (stableFrames >= 6 || totalFrames >= 90) {
      resolveTarget().scrollIntoView();
    } else {
      requestAnimationFrame(waitForStableLayout);
    }
  };
  requestAnimationFrame(waitForStableLayout);
};

# Installation

To install Erigon, begin by choosing an installation method suited to your operating system and technical preference. Options range from the simplest to the most complex, including pre-built images, containers, or source compilation.

Pre-built Binaries — Fastest way to get started. Download and run a pre-compiled binary for your architecture.
Docker — Run Erigon in an isolated container. Recommended for most users.
Build from Source — Full control over the build. Requires Go, C++ compiler, and CLI experience.

Docker — Run Erigon in an isolated container. The recommended method on macOS.
Build from Source — Compile directly on your Mac. Requires Go, Clang/GCC, and CLI experience.

Native Compilation — Compile and run Erigon directly on Windows using Chocolatey, MinGW, and Go.
WSL (Windows Subsystem for Linux) — Run a full Linux environment on Windows. Recommended for best performance.

### All Operating Systems

Docker

Docker is like a portable container for software. It packages Erigon and everything it needs to run, so you don't have to install complicated dependencies on your computer.

This Docker image is fully supported on **Linux**, **macOS**, and **Windows**.

_(Note: The container itself is built on multi-platform Linux architectures (linux/amd64 and linux/arm64), which is handled automatically by your Docker setup.)_

#### **Prerequisites**

[Docker Engine](https://docs.docker.com/engine/install) if you run Linux or [Docker Desktop](https://docs.docker.com/desktop/) if you run macOS/Windows.

**General Info**

* The Docker images feature several binaries, including: `erigon`, `downloader`, `evm`, `caplin`, `capcli`, `integration`, `rpcdaemon`, `sentry`, and `txpool`.
* The multi-platform Docker image is available for `linux/amd64/v2` and `linux/arm64` platforms and is now based on Debian Bookworm. There's no need to pull a different image for another supported platform.
* All build flags are now passed to the release workflow, allowing users to view previously missed build information in the released binaries and Docker images. This change is also expected to result in better build optimization.
* Docker images now contain the label `org.opencontainers.image.revision`, which refers to the commit ID from the Erigon project used to build the artifacts.
* With recent updates, all build configurations are now included in the release process. This provides users with more comprehensive build information for both binaries and Docker images, along with enhanced build optimizations.
* Images are stored at [https://hub.docker.com/r/erigontech/erigon](https://hub.docker.com/r/erigontech/erigon).

:::warning
**Windows**: note that Docker on Windows is affected by [WSL2 Performance and Data Storage](/get-started/installation/#install-wsl).
:::

#### **Download and start Erigon in Docker**

Here are the steps to download and start Erigon in Docker.

**1. Check which version you want to download**

Check in the GitHub [Release Notes](https://github.com/erigontech/erigon/releases) page which version you want to download (normally latest is the best choice).

**2. Download Erigon container**

Download the chosen version replacing `<version_tag>` with the actual version:

```sh
docker pull erigontech/erigon:<version_tag>
```

For example:

```sh
docker pull erigontech/erigon:v{ERIGON_VERSION}
```

**3. Start the Erigon container**

Start the Erigon container in your terminal:

```sh
docker run -it erigontech/erigon:<version_tag> <flags>
```

For example:

```sh
docker run -it erigontech/erigon:v{ERIGON_VERSION} --chain=hoodi --prune.mode=minimal --datadir /erigon-data
```

* `-v` connects a folder on your computer to the container (must have authorization)
* `-it` lets you see what's happening and interact with Erigon
* `--chain=hoodi` specifies which [network](/fundamentals/supported-networks) to sync
* `--prune.mode=minimal` tells Erigon to use minimal [Pruning Mode](/fundamentals/pruning-modes)
* `--datadir` tells Erigon where to store data inside the container

### Linux/macOS

Pre-built Binaries (Linux Only)

**1. Select Your Processor Architecture and Download**

Go to the Erigon [releases page](https://github.com/erigontech/erigon/releases) on GitHub and select the latest stable version (e.g., v{ERIGON_VERSION}) or whichever version you prefer.

Download the appropriate binary file for your processor architecture:

| Processor Type | Binary File Type | Example File Name |
| --- | --- | --- |
| 64-bit Intel/AMD | Debian Package (.deb) | erigon_{ERIGON_VERSION}_amd64.deb |
| 64-bit ARM | Debian Package (.deb) | erigon_{ERIGON_VERSION}_arm64.deb |
| 64-bit Intel/AMD | Compressed Archive (.tar.gz) | erigon_v{ERIGON_VERSION}_linux_amd64.tar.gz |
| 64-bit Intel/AMDv2 | Compressed Archive (.tar.gz) | erigon_v{ERIGON_VERSION}_linux_amd64v2.tar.gz |
| 64-bit ARM | Compressed Archive (.tar.gz) | erigon_v{ERIGON_VERSION}_linux_arm64.tar.gz |

Note that the Release Page Assets table contains also the **checksum** for each file and a checksum file.

**2. Verifying Binary Integrity with Checksums**

To verify the integrity and ensure your downloaded Erigon file hasn't been corrupted or tampered with, use the SHA256 checksums provided in the official release by following these steps:

**2.1 Generate the Checksum of Your Downloaded File**

Next, use the `sha256sum` command followed by the name of your downloaded binary (e.g., `erigon_v3.x.x_linux_amd64.tar.gz`).

```sh
sha256sum <DOWNLOADED_FILE_NAME>
```

Example with a `tar.gz` file:

```sh
sha256sum erigon_v{ERIGON_VERSION}_linux_amd64.tar.gz
```

This command will output a long string (the computed checksum) followed by the file name.

**2.2 Compare the Checksums**

Compare the checksum found in the previous step with those in the Release Notes Assets table or the erigon\_v3.x.x\_checksums.txt file in the same table.

The two checksum strings must match exactly. If they do not match, the file is corrupted, and you should delete it and download it again.

**3. Installing the Binary Executable**

After downloading and verifying the checksum, follow the instructions below based on the file type you chose.

**a. Using Debian Package (`.deb`)**

This method uses your distribution's package manager (like dpkg) to install Erigon system-wide.

1.  Navigate to the directory where you downloaded the pre-built binary, e.g. Downloads:

    ```bash
    cd ~/Downloads
    ```
2.  Install the package:

    ```bash
    sudo dpkg -i erigon_3.x.x_amd64.deb
    ```

    (Replace the filename with your downloaded version)

**b. Using Compressed Archive (`.tar.gz`)**

This method gives you a standalone executable that can be run from any directory.

1.  Extract the archive:

    ```bash
    tar -xzf erigon_v3.x.x_linux_amd64.tar.gz
    ```

    (Replace the filename with your downloaded version)
2.  Move the resulting `erigon` executable to a directory included in your system's $PATH(e.g., $/usr/local/bin) to run it from anywhere:

    ```bash
    sudo mv erigon /usr/local/bin/
    ```

**4. Running Erigon**

After installation, you can run Erigon from your terminal:

```bash
erigon [options]
```

Build from Source

:::info
Building from source gives you full control over the compilation process and lets you run any specific version or branch. It requires Go, a C++ compiler, and basic familiarity with the command line.

If you prefer a simpler setup, the pre-built binaries or Docker options above are recommended for most users.
:::

**1. Software Requirements**

If you intend to build Erigon from source, you must first meet the necessary prerequisites.

**1.1 Git**

Git is a tool that helps download and manage the Erigon source code. To install Git, visit [https://git-scm.com/downloads](https://git-scm.com/downloads).

**1.2 Build essential and Cmake (Linux only)**

Install **Build-essential** and **Cmake**:

```bash
sudo apt install build-essential cmake -y
```

**1.3 Go Programming Language**

Erigon utilizes Go (also known as Golang) version 1.25 or newer for part of its development. It is recommended to have a
fresh Go installation. If you have an older version, consider deleting the `/usr/local/go` folder (you may need to use
`sudo`) and re-extract the new version in its place.

To install the latest Go version, visit the official documentation at [https://golang.org/doc/install](https://golang.org/doc/install).

**1.4 C++ Compiler**

This turns the C++ part of Erigon's code into a program your computer can run. You can use either **Clang** or **GCC**:

* For **Clang** follow the instructions at [https://clang.llvm.org/get\_started.html](https://clang.llvm.org/get_started.html);
* For **GCC** (version 10 or newer): [https://gcc.gnu.org/install/index.html](https://gcc.gnu.org/install/index.html).

**2. Building Erigon from Source**

The basic Erigon configuration is suitable for most users who simply want to run a node. To ensure you are building a specific, stable release, use Git tags.

**2.1 Clone the Erigon repository**

First, clone the Erigon repository (you do not need to specify a branch):

```text
git clone https://github.com/erigontech/erigon.git
cd erigon
```

**2.2 Check Out the Desired Stable Version (Tag)**

Next, fetch all available release tags:

```sh
git fetch --tags
```

Check out the desired version tag by replacing `<tag_name>` with the version you want. Normally latest stable version is the best, check the official [Release Notes](https://github.com/erigontech/erigon/releases). For example:

```sh
git checkout v{ERIGON_VERSION}
```

**2.3 Compile the Software**

Compile the Erigon binary using the `make` command.

Standard Compilation:

```sh
make erigon
```

Fast Compilation (Recommended): to significantly speed up the process, specify the number of processors you want to use with the `-j<n>` option, where `<n>` is the number of processor you want to use (we recommend using a number slightly less than your total core count):

```sh
make -j<n> erigon
```

The resulting executable binary will be created in the `./build/bin/erigon` path.

**3. Running Erigon**

After installation, you can run Erigon from your terminal:

```sh
./build/bin/erigon [options]
```

### Windows

Native Compilation

**1. Software Prerequisites**

You must install the following software and set the below environment variables before compiling Erigon.

**1.1 Chocolatey**

Install _Chocolatey package manager_ by following these [instructions](https://docs.chocolatey.org/en-us/choco/setup).

Once your Windows machine has the above installed, open the **Command Prompt** by typing "**cmd**" in the search bar and check that you have correctly installed Chocolatey:

```bash
choco -v
```

**1.2 `cmake`, `make`, `mingw`**

Now you need to install the following components: `cmake`, `make`, `mingw` by:

```bash
choco install cmake make mingw
```

:::warning
**Important note about Anti-Virus:**

During the compiler detection phase of **MinGW**, some temporary executable files are generated to test the compiler capabilities. It's been reported that some anti-virus programs detect these files as possibly infected with the `Win64/Kryptic.CIS` Trojan horse (or a variant of it). Although these are false positives, we have no control over the 100+ vendors of security products for Windows and their respective detection algorithms and we understand that this may make your experience with Windows builds uncomfortable. To work around this, you can either set exclusions for your antivirus software specifically for the`build\bin\mdbx\CMakeFiles` subfolder of the cloned repo, or you can run Erigon using the other two options below.
:::

**1.3 Git**

Git is a tool that helps download and manage the Erigon source code. To install Git, visit [https://git-scm.com/downloads](https://git-scm.com/downloads).

**1.4 Go Programming Language**

Erigon utilizes Go (also known as Golang) version 1.25 or newer for part of its development. It is recommended to have a
fresh Go installation. If you have an older version, consider deleting the `/usr/local/go` folder (you may need to use
`sudo`) and re-extract the new version in its place.

To install the latest Go version, visit the official documentation at [https://golang.org/doc/install](https://golang.org/doc/install).

**1.5 Set the System Environment Variable**

Make sure that the Windows System Path variable is set correctly. Use the search bar on your computer to search for “**Edit the system environment variable**”.

Click the “**Environment Variables...**” button.

Look down at the "**System variables**" box and double click on "**Path**" to add a new path (or select and click on "**Edit**").

Then click on the "**New**" button and paste the following path:

```bash
 C:\ProgramData\chocolatey\lib\mingw\tools\install\mingw64\bin
```

**2. Clone the Erigon repository**

Open the Command Prompt and type the following:

```bash
git clone https://github.com/erigontech/erigon.git
cd erigon
```

Next, fetch all available release tags:

```bash
git fetch --tags
```

Check out the desired version tag by replacing `<tag_name>` with the version you want. Normally latest stable version is the best, check the official [Release Notes](https://github.com/erigontech/erigon/releases). For example:

```bash
git checkout v{ERIGON_VERSION}
```

You might need to change the `ExecutionPolicy` to allow scripts created locally or signed by a trusted publisher to run. Open a **Powershell session as Administrator** and type:

```powershell
Set-ExecutionPolicy RemoteSigned
```

**3. Compiling Erigon**

This section outlines how to compile the Erigon client and its associated modules directly from the source code on a Windows environment. Compiling from source ensures you are running the latest version and gives you control over the final binaries. All successfully compiled binaries will be placed in the `.\build\bin\` subfolder of your Erigon directory.

Open Git Bash (the shell that comes with Git for Windows) and change to the Erigon directory:

```bash
cd erigon
```

Compile Erigon and its components using `make`:

```bash
make
```

This builds all modules. All binaries will be placed in the `.\build\bin\` subfolder. The executable binary `erigon.exe` should have been created there.

You can also build specific targets, for example:

```bash
make erigon
```

You can use the same command to build other binaries such as `RPCDaemon`, `TxPool`, `Sentry` and `Downloader`.

**4. Running Erigon**

To make Erigon executable from anywhere from your terminal repeat step 1.5 and add Erigon executable path

```text
C:\Users\your-user\erigon.\build\bin\
```

You can now start Erigon by simply using:

```powershell
erigon.exe [options]
```

:::warning
**Note**: When you first start Erigon, Windows Firewall may prompt you to allow internet access. Select "YES" to proceed.
:::

Window Subsystem for Linux (WSL)

WSL enables you to run a complete GNU/Linux environment natively within Windows, offering Linux compatibility without the performance and resource overhead of traditional virtual machines.

**Installation and Version**

* Official Installation: Follow Microsoft's official guide to install WSL2: [https://learn.microsoft.com/en-us/windows/wsl/install](https://learn.microsoft.com/en-us/windows/wsl/install)
* Required Version: WSL version 2 is the only version supported by Erigon.

**Building Erigon**

Once WSL2 is set up, you can build and run Erigon exactly as you would on a regular [Linux/macOS](/get-started/installation/#linuxmacos) distribution.

**Performance and Data Storage**

The location of your Erigon data directory (`datadir`) is the most crucial factor for performance in WSL.

| **Data Location**                                                         | **Performance & Configuration**                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Recommended: Native Linux Filesystem (e.g., in your Linux home directory) | Optimal Performance. Erigon runs without restrictions, and the embedded RPC Daemon works efficiently.                                                                                                                                                                                                                                                                                                                                                            |
| Avoid: Mounted Windows Partitions (e.g., `/mnt/c/`, `/mnt/d/`)            | Performance is reduced as the native Windows drives are mounted using DrvFS (a slower network file system). This affects MDBX database access, and complicates filesystem operations that expect unix-like behaviour. Setting [`automount.options=metadata`](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#automount-options) in `/etc/wsl.conf` in your distribution is recommended, but not required. Note that Docker on Windows is also affected. |

**RPC Daemon Configuration**

The choice of data location directly impacts how you must configure the RPC Daemon:

| **Scenario**                                  | **RPC Daemon Requirement**                                                               |
| --------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Data on Native Linux Filesystem (Recommended) | Use the Embedded RPC Daemon. This is the highly preferred and most efficient method.     |
| Data on Mounted Windows Partition             | The `rpcdaemon` must be configured as a remote DB even when running on the same machine. |

:::warning
⚠️ Warning: The remote DB RPC Daemon is an experimental feature, is not recommended, and is extremely slow. Always aim to use the embedded RPC Daemon by keeping your data on the native Linux filesystem.
:::

**Networking Notes**

Be aware that the default WSL2 environment uses its own internal IP address, which is distinct from the IP address of your Windows host machine.

If you need to connect to Erigon from an external network (e.g., opening a port on your home router for peering on port `30303`), you must account for this separate WSL2 IP address when configuring NAT on your router. Alternatively consider [Mirrored mode networking](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking).

Once you have Erigon installed, you can see [Basic Usage](/fundamentals/basic-usage) to configure your node and confirm it is syncing.

---

# Upgrading from a previous version
URL: https://docs.erigon.tech/get-started/installation/upgrading


Updating to the latest version of Erigon gives you access to the latest features and ensures optimal performance and stability.

## General Recommendations Before Upgrade

* **Read Release Notes**: Carefully review the [Release Notes](https://github.com/erigontech/erigon/releases) for breaking changes and new features relevant to your setup.
* **Terminate your Erigon**: End your current Erigon session by pressing `CTRL+C`.
* **Backup**: Always back up your `datadir` before performing major upgrades.

## Managing your Data

Erigon 3.1 introduces a new snapshot format while continuing to support the old one. This means that new releases are fully compatible with your existing data. However, users who want the latest data files and data-specific fixes can perform an **optional** manual data upgrade:

1. Backup your datadir.
2. [Upgrade your Erigon installation](#upgrading-your-erigon-installation) whether from a binary, compiled source code, or Docker.
3. Upgrade your snapshots using one of the [options below](#snapshots-upgrade-options).
4. Run Erigon; it downloads any missing snapshots and resumes syncing.

### Snapshots Upgrade Options

* `erigon snapshots update-to-new-ver-format --datadir /your/datadir`: converts your existing snapshots in place to the latest format, **keeping your data**. Quicker, but you won't get the full performance benefits of freshly built snapshots.
* `erigon snapshots reset --datadir /your/datadir`: **destructive** — deletes `chaindata/` (and the Heimdall / Polygon-bridge DBs) and removes any snapshot files **not** in the preverified set (locally generated files, and torrents with a mismatched hash). Preverified snapshots already on disk are **kept**; on the next start Erigon downloads only **missing or incorrect** snapshots and rebuilds state.

:::warning
`erigon snapshots reset` does **not** reuse your `chaindata/` — it deletes the chaindata DB (and the Heimdall / Polygon-bridge DBs) and any locally generated or mismatched snapshots, then rebuilds state on the next start (downloading only missing or incorrect snapshots). Back up your `--datadir` first, and prefer `update-to-new-ver-format` if you want to keep your current data.
:::

Choose `update-to-new-ver-format` to convert your data in place, or `reset` for a clean reset to the preverified snapshot set.

Why Upgrading Erigon Doesn't Always Fix Your Data

Upgrading Erigon involves a key distinction between its core software and its data files, which are managed separately. This approach is rooted in practicality and user control.

The Erigon **software** is the application that processes and interacts with blockchain data. However, the majority of the data itself, including the state of the network, exists in **data files** that you download and store locally.

If a bug is discovered, it is often in the data itself rather than a flaw in the Erigon code. In such a case, simply updating the Erigon binary won't resolve the issue because the faulty data remains on your disk. This is because Erigon upgrades do not normally alter the data files. You must reset and re-download the data snapshots to get the corrected files.

This separation prevents unnecessary and time-consuming processes. The Erigon team cannot regenerate months of data for every minor bug fix, and users shouldn't have to re-download terabytes of information with every new weekly software release.

This design also provides flexibility. A user might need a specific data fix but prefer to remain on an older software version due to a known bug or regression in the latest release. Similarly, a user might be satisfied with their current data set and only need to update the Erigon binary.

While this dual-versioning system may seem complex, it is a deliberate design choice that optimizes for both efficiency and user autonomy.

### Snapshots Downgrade Options

If upgrading snapshots(`3.0`to `3.1`) now happens automatically, you should follow these instructions for downgrading:

:::warning
**WARNING**: This algorithm will remove incompatible `3.1` snapshot files because they are not backward-compatible.
:::

1. Make sure that you're running Erigon on 3.1.x version, use `erigon --version`.
2. Run `erigon snapshots reset-to-old-ver-format --datadir /your/datadir` to reset your snapshots to old format.
3. `git checkout v3.0.x` to checkout to preferred `3.0` version. For example now latest: `git checkout v3.0.15`
4. Run your old version of Erigon.

## Upgrading your Erigon Installation

Follow the below instructions depending on your installation method:

* [Pre-built binaries](#pre-built-binaries-only-linux-and-macos)
* [Docker](#docker)
* [Compiled source code](#compiled-from-source)

### Pre-built Binaries (only Linux and macOS)

Download the latest binary file from [https://github.com/erigontech/erigon/releases](https://github.com/erigontech/erigon/releases), do the [checksum](./#install-prebuilt) and reinstall it, no other operation needed.

### Docker

If you're using Docker to run Erigon, the process to upgrade to a newer version of the software is straightforward and revolves around pulling the latest Docker image and then running it.

Simply follow the [Docker](#docker) instructions and install and launch the new version.

### Compiled from source

To upgrade Erigon to a newer version when you've originally installed it via Git and manual compilation, follow the installation instructions from step 2 "Check Out the Desired Stable Version (Tag)".

---

# Easy Nodes
URL: https://docs.erigon.tech/get-started/easy-nodes

Guided setup for running a complete node with sensible defaults — pick your network and follow along.

## Sections

- [Ethereum Node](https://docs.erigon.tech/get-started/easy-nodes/how-to-run-an-ethereum-node): Run a full Ethereum mainnet node using Caplin (built-in consensus layer) or connect an external CL client.
- [Gnosis Chain Node](https://docs.erigon.tech/get-started/easy-nodes/how-to-run-a-gnosis-chain-node): Run a full Gnosis Chain node with Erigon's embedded consensus layer or an external CL client.
- [Polygon Node](https://docs.erigon.tech/get-started/easy-nodes/how-to-run-a-polygon-node): Step-by-step guide to running an Erigon node on the Polygon PoS network.

---

# How to run a Polygon node
URL: https://docs.erigon.tech/get-started/easy-nodes/how-to-run-a-polygon-node


:::warning
**Information**: The final release series of Erigon that officially supports Polygon is 3.1.\*. For the software supported by Polygon, please refer to the link: [https://github.com/0xPolygon/erigon/releases](https://github.com/0xPolygon/erigon/releases).
:::

## 1. Prerequisites Check

1. Confirm your machine meets the necessary [Hardware Requirements](../hardware-requirements) based on your desired pruning mode.
2. **Install Docker**:
   * For Linux, install [Docker Engine](https://docs.docker.com/engine/install).
   * For macOS or Windows, install [Docker Desktop](https://docs.docker.com/desktop/).

## 2. Configure and Launch Erigon

Follow these steps to configure and launch the All-in-One Client with the Heimdall endpoint.

### **A. Create the Configuration File**

Create a new file named `docker-compose.yml` in a directory where you want to manage your Erigon setup, and paste the following content into it:

```sh
services:
  erigon:
    image: erigontech/erigon:v{ERIGON_VERSION}
    container_name: erigon-node
    restart: always
    command:
      # --- Basic Configuration ---
      - --chain=bor-mainnet
      - --bor.heimdall=https://heimdall-api.polygon.technology
      - --http.addr="0.0.0.0"
      - --http.api=eth,web3,net,debug,trace,txpool
      # --- Performance Tweaks ---
      - --torrent.download.rate=512mb
      # --- Pruning Mode (Optional) ---
      # To change Pruning Mode, uncomment the line below:
      # - --prune.mode=archive
      # or
      # - --prune.mode=minimal
    ports:
      - "8545:8545" # Exposes the RPC port (needed for wallets/dApps)
    volumes:
      # *** IMPORTANT: CHANGE THIS PATH! ***
      # Replace the path below with an actual directory on your machine 
      # where you want the blockchain data stored (e.g., /mnt/ssd/erigon-data)
      - /path/to/erigon/data:/var/lib/erigon
```

:::warning
⚠️ **Action Required**: You must change the volume path! Replace `/path/to/erigon/data` with a valid, empty directory on your machine where you want Erigon to store its files.
:::

### **B. Launch the Node and Monitor Progress**

Open your terminal in the directory where you saved `docker-compose.yml`. To start the node and immediately see the sync process type:

```text
docker compose up
```

Now you can relax and watch your Erigon Polygon node sync!

## Flag explanation

* `--chain=bor-mainnet` and `--bor.heimdall=https://heimdall-api.polygon.technology` specify respectively the Polygon mainnet and the API endpoint for the Heimdall network
  * to use Amoy testnet, replace with flags `--chain=amoy --bor.heimdall=https://heimdall-api-amoy.polygon.technology`
* Add `--prune.mode=minimal` to run minimal [Pruning Mode](../../fundamentals/pruning-modes) or `--prune.mode=archive` to run an archive node
* `--http.addr="0.0.0.0" --http.api=eth,web3,net,debug,trace,txpool` to use RPC and e.g. be able to connect your [web3 wallet](../../fundamentals/web3-wallet);
* `--torrent.download.rate=512mb` to increase download speed. While the default downloading speed is 128mb, with this flag Erigon will use as much download speed as it can, up to a maximum of 512 megabytes per second. This means it will try to download data as quickly as possible, but it won't exceed the 512 MB/s limit you've set.

:::tip
Press `Ctrl+C` in your terminal to stop Erigon.
:::

Additional flags can be added to [configure](../../fundamentals/configuring-erigon/) Erigon with several options.

---

# How to run an Ethereum node
URL: https://docs.erigon.tech/get-started/easy-nodes/how-to-run-an-ethereum-node


## 1. Prerequisites Check

1. Confirm your machine meets the necessary [Hardware Requirements](/get-started/hardware-requirements) based on your desired pruning mode.
2. **Install Docker**:
   * For Linux, install [Docker Engine](https://docs.docker.com/engine/install).
   * For macOS or Windows, install [Docker Desktop](https://docs.docker.com/desktop/).

## 2. Configure and Launch Erigon

Follow these steps to configure and launch the All-in-One Client. Erigon uses its embedded Consensus Layer (Caplin) by default, so you don't need a separate Consensus Client (CL).

### **A. Create the Configuration File**

Create a new file named `docker-compose.yml` in a directory where you want to manage your Erigon setup, and paste the following content into it:

```sh
services:
  erigon:
    image: erigontech/erigon:v{ERIGON_VERSION}
    container_name: erigon-node
    restart: always
    command:
      # --- Basic Configuration ---
      - --chain=mainnet
      - --http.addr=0.0.0.0
      - --http.api=eth,web3,net,debug,trace,txpool
      # --- Performance Tweaks ---
      - --torrent.download.rate=512mb
      # --- Pruning Mode (Optional) ---
      # To change Pruning Mode, uncomment the line below:
      # - --prune.mode=archive
      # or
      # - --prune.mode=minimal
    ports:
      - "8545:8545" # Exposes the RPC port (needed for wallets/dApps)
    volumes:
      # *** IMPORTANT: CHANGE THIS PATH! ***
      # Replace the path below with an actual directory on your machine 
      # where you want the blockchain data stored (e.g., /mnt/ssd/erigon-data)
      - /path/to/erigon/data:/var/lib/erigon
```

:::warning
⚠️ **Action Required**: You must change the volume path! Replace `/path/to/erigon/data` with a valid, empty directory on your machine where you want Erigon to store its files.
:::

### **B. Launch the Node and Monitor Progress**

Open your terminal in the directory where you saved `docker-compose.yml`. To start the node and immediately see the sync process type:

```text
docker compose up
```

## Flag explanation

* `--chain=mainnet` specifies to run on Ethereum mainnet
* Add `--prune.mode=minimal` to run minimal [Pruning Mode](/fundamentals/pruning-modes) or `--prune.mode=archive` to run an archive node
* `--http.addr=0.0.0.0 --http.api=eth,web3,net,debug,trace,txpool` to use RPC and e.g. be able to connect your [web3 wallet](/fundamentals/web3-wallet)
* `--torrent.download.rate` sets the torrent download rate cap. The default is `512mb` (megabytes per second). During initial sync Erigon will use the full allowance — on a dedicated machine this is fine, but if you share the machine with other work you may want to lower it (e.g. `--torrent.download.rate=128mb`). Set `--torrent.download.rate=Inf` to remove the limit entirely.

When you get familiar with running Erigon from CLI you may also consider [staking](/staking/caplin) and/or running an Ethereum node with an [external Consensus Layer](/get-started/easy-nodes/how-to-run-an-ethereum-node/ethereum-with-an-external-cl).

:::tip
Press `Ctrl+C` in your terminal to stop Erigon.
:::

Additional flags can be added to [configure](/fundamentals/configuring-erigon/) Erigon with several options.

---

# Ethereum with an external CL
URL: https://docs.erigon.tech/get-started/easy-nodes/how-to-run-an-ethereum-node/ethereum-with-an-external-cl


You can use **Prysm**, **Lighthouse**, or any other Consensus Layer client with Erigon by including the `--externalcl` flag. This integration enables direct access to the Ethereum blockchain, allowing you to manage your keys for staking ETH and block production.

## Erigon with Prysm as the external CL

1.  Start Erigon adding the `--externalcl` flag:

    ```bash
    erigon --externalcl
    ```

    If your Consensus Layer (CL) client is on a different device, add the following flags:

    * `--authrpc.addr 0.0.0.0`, since the Engine API listens on localhost by default;
    * `--authrpc.vhosts <CL_host>` where \ is the source host or the appropriate hostname that your CL client is using.
2.  Install and run **Prysm** by following the official guide: [https://docs.prylabs.network/docs/install/install-with-script](https://docs.prylabs.network/docs/install/install-with-script).

    Prysm must fully synchronize before Erigon can start syncing, since Erigon requires an existing target head to sync to. The quickest way to get Prysm synced is to use a public checkpoint synchronization endpoint from the list at [https://eth-clients.github.io/checkpoint-sync-endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints).
3. To communicate with Erigon, the `--execution-endpoint` must be specified as `<erigon address>:8551`, where `<erigon address>` is either `http://localhost` or the IP address of the device running Erigon.
4.  Prysm must point to the [JWT secret](../../../fundamentals/jwt) automatically created by Erigon in the `--datadir` directory.

    ```bash
    ./prysm.sh beacon-chain \
    --execution-endpoint http://localhost:8551 \
    --mainnet --jwt-secret=<your-datadir>/jwt.hex \
    --checkpoint-sync-url=https://beaconstate.info \
    --genesis-beacon-api-url=https://beaconstate.info
    ```

1.  Start Erigon adding the `--externalcl` flag:

    ```bash
    ./build/bin/erigon --externalcl
    ```
2. Install and run Lighthouse by following the official guide: [https://lighthouse-book.sigmaprime.io/installation.html](https://lighthouse-book.sigmaprime.io/installation.html)
3. Because Erigon needs a target head in order to sync, Lighthouse must be synced before Erigon can synchronize. The fastest way to synchronize Lighthouse is to use one of the many public checkpoint synchronization endpoints at [https://eth-clients.github.io/checkpoint-sync-endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints).
4. To communicate with Erigon, the `--execution-endpoint` must be specified as `<erigon address>:8551`, where `<erigon address>` is either `http://localhost` or the IP address of the device running Erigon.
5.  Lighthouse must point to the [JWT secret](../../../fundamentals/jwt) automatically created by Erigon in the `--datadir` directory.

    ```bash
    lighthouse bn \
    --network mainnet \
    --execution-endpoint http://localhost:8551 \
    --execution-jwt <your-datadir>/jwt.hex \
    --checkpoint-sync-url https://mainnet.checkpoint.sigp.io \
    ```

Check Erigon and your chosen CL logs to make sure that the Execution Layer (EL) and CL are communicating and that your node is syncing correctly.

---

# How to run a Gnosis Chain node
URL: https://docs.erigon.tech/get-started/easy-nodes/how-to-run-a-gnosis-chain-node


## 1. Prerequisites Check

1. Confirm your machine meets the necessary [Hardware Requirements](/get-started/hardware-requirements) based on your desired pruning mode.
2. **Install Docker**:
   * For Linux, install [Docker Engine](https://docs.docker.com/engine/install).
   * For macOS or Windows, install [Docker Desktop](https://docs.docker.com/desktop/).

## 2. Configure and Launch Erigon

Follow these steps to configure and launch the All-in-One Client. Erigon uses its embedded Consensus Layer (Caplin) by default, so you don't need a separate Consensus Client (CL).

### **A. Create the Configuration File**

Create a new file named `docker-compose.yml` in a directory where you want to manage your Erigon setup, and paste the following content into it:

```sh
services:
  erigon:
    image: erigontech/erigon:v{ERIGON_VERSION}
    container_name: erigon-node
    restart: always
    command:
      # --- Basic Configuration ---
      - --chain=gnosis
      - --http.addr="0.0.0.0"
      - --http.api=eth,web3,net,debug,trace,txpool
      # --- Performance Tweaks ---
      - --torrent.download.rate=512mb
      # --- Pruning Mode (Optional) ---
      # To change Pruning Mode, uncomment the line below:
      # - --prune.mode=archive
      # or
      # - --prune.mode=minimal
    ports:
      - "8545:8545" # Exposes the RPC port (needed for wallets/dApps)
    volumes:
      # *** IMPORTANT: CHANGE THIS PATH! ***
      # Replace the path below with an actual directory on your machine 
      # where you want the blockchain data stored (e.g., /mnt/ssd/erigon-data)
      - /path/to/erigon/data:/var/lib/erigon
```

:::warning
⚠️ **Action Required**: You must change the volume path! Replace `/path/to/erigon/data` with a valid, empty directory on your machine where you want Erigon to store its files.
:::

### **B. Launch the Node and Monitor Progress**

Open your terminal in the directory where you saved `docker-compose.yml`. To start the node and immediately see the sync process type:

```text
docker compose up
```

## Flag explanation

* `--chain=gnosis` specifies to run on Gnosis Chain, use `--chain=chiado` for Chiado testnet
* Add `--prune.mode=minimal` to run minimal [Pruning Mode](/fundamentals/pruning-modes) or `--prune.mode=archive` to run an archive node
* `--http.addr="0.0.0.0" --http.api=eth,web3,net,debug,trace,txpool` to use RPC and e.g. be able to connect your [web3 wallet](/fundamentals/web3-wallet)
* `--torrent.download.rate=512mb` to increase download speed. While the default downloading speed is 128mb, with this flag Erigon will use as much download speed as it can, up to a maximum of 512 megabytes per second. This means it will try to download data as quickly as possible, but it won't exceed the 512 MB/s limit you've set

When you get familiar with running Erigon from CLI you may also consider [staking](/staking/caplin) and/or run a Gnosis node with an [external Consensus Layer](/get-started/easy-nodes/how-to-run-a-gnosis-chain-node/gnosis-with-an-external-cl).

:::tip
Press `Ctrl+C` in your terminal to stop Erigon.
:::

Additional flags can be added to [configure](/fundamentals/configuring-erigon/) Erigon with several options.

---

# Gnosis Chain with an external CL
URL: https://docs.erigon.tech/get-started/easy-nodes/how-to-run-a-gnosis-chain-node/gnosis-with-an-external-cl


Alternatively, you can also run a Gnosis Chain node as an Execution Layer (EL) and couple it with an external Consensus Layer (CL). Here is an example of configuration with **Lighthouse**.

### 1. Start Erigon:

Start Erigon adding the `--externalcl` flag.

```bash
erigon --chain=gnosis --externalcl 
```

If your CL client is on a different device, add the following flags:

* `--authrpc.addr 0.0.0.0`, since the Engine API listens on localhost by default;
* `--authrpc.vhosts <CL_host>` where `<CL_host>` is the source host or the appropriate hostname that your CL client is using.

### 2. Install Lighthouse

Install Lighthouse, following instructions at [https://lighthouse-book.sigmaprime.io/installation.html](https://lighthouse-book.sigmaprime.io/installation.html).

* Compile it with a feature flag to enable Gnosis Chain:

```bash
env FEATURES=gnosis make
```

### 3. Sync Lighthouse to a public checkpoint

Because Erigon needs a target head in order to sync, Lighthouse must be synced before Erigon can synchronize. The fastest way to synchronize Lighthouse is to use one of the many public checkpoint synchronization endpoints, for example:

1. `https://checkpoint.gnosischain.com` for Gnosis Chain;
2. `https://checkpoint.chiadochain.net` for Chiado testnet.

### 4. Set the Erigon JWT secret path in Lighthouse

To communicate with Erigon, the execution endpoint must be specified as `<erigon address>:8551`, where `<erigon address>` is either `http://localhost` or the IP address of the device running Erigon.

1.  Lighthouse must point to the [JWT secret](../../../fundamentals/jwt) automatically created by Erigon in the `--datadir` directory. In the following example the default data directory is used.

    Copy

    ```text
     lighthouse \
     --network gnosis beacon_node \
     --datadir=data \
     --http \
     --execution-endpoint http://localhost:8551 \
     --execution-jwt /home/user/.local/share/erigon/jwt.hex \
     --checkpoint-sync-url "https://checkpoint.gnosischain.com"
    ```

    Here is an example of Lighthouse running the Chiado testnet:

    Copy

    ```text
     lighthouse \
     --network chiado \
     --datadir=data \
     --http \
     --execution-endpoint http://localhost:8551 \
     --execution-jwt /home/user/.local/share/erigon/jwt.hex \
     --checkpoint-sync-url "https://checkpoint.chiadochain.net"
    ```

Check the Erigon and Lighthouse logs to make sure that the EL and CL are communicating and that your node is syncing correctly.

---

# Fundamentals
URL: https://docs.erigon.tech/fundamentals

Core concepts and day-to-day operations for running a healthy Erigon node.

## Sections

- [Basic Usage](https://docs.erigon.tech/fundamentals/basic-usage): Command-line flags, common arguments, and first steps running the Erigon binary.
- [Pruning Modes](https://docs.erigon.tech/fundamentals/pruning-modes): Full, minimal, and archive sync explained — choose the right mode for your use case.
- [Configuration](https://docs.erigon.tech/fundamentals/configuring-erigon): Full CLI flag reference, config file format, and per-component tuning options.
- [Supported Networks](https://docs.erigon.tech/fundamentals/supported-networks): All chains and testnets supported by Erigon, with network-specific flags and notes.
- [Optimizing Storage](https://docs.erigon.tech/fundamentals/optimizing-storage): Pruning, snapshots, and techniques to minimize disk footprint.
- [Docker Compose](https://docs.erigon.tech/fundamentals/docker-compose): Run Erigon and all its modules together with Docker Compose.
- [Security](https://docs.erigon.tech/fundamentals/security): Firewall rules, API exposure best practices, and hardening recommendations.
- [Modules](https://docs.erigon.tech/fundamentals/modules): Run RPC Daemon, TxPool, Sentry, and Downloader as independent processes for scalable setups.

---

# Basic Usage
URL: https://docs.erigon.tech/fundamentals/basic-usage


Erigon is mainly operated through the command line. The commands may vary based on your installation method.

Open your terminal and simply start Erigon with the command:

```text
erigon [options]
```

* You can use Docker Compose like in this [example](/get-started/easy-nodes/how-to-run-an-ethereum-node#a-create-the-configuration-file)
*   Alternatively you can use the Docker syntax, for example:

    `docker run -it erigontech/erigon:v{ERIGON_VERSION} [options]`

Open your terminal and move to the directory where you installed Erigon

```text
cd erigon
```

You can then start Erigon with the below command:

```shell
./build/bin/erigon [options]
```

To run Erigon after a native compilation, enter the following command in your Command Prompt or PowerShell:

```powershell
erigon.exe [options]
```

:::warning
**Note**: When you first start Erigon, Windows Firewall may prompt you to allow internet access. Select "YES" to proceed.
:::

To gracefully stop Erigon simply press `CTRL` + `C`.

## All-in-One Client

The all-in-one client is the preferred option for most users:

```bash
./build/bin/erigon [options]
```

This CLI command allows you to run an Ethereum **full node** where every process is integrated and no special configuration is needed.

The default Consensus Layer utilized is [Caplin](caplin), the Erigon flagship embedded CL.

## Example of configuration

To run Erigon with RPC Daemon, TxPool, and other components in a single process is the simplest way to get started. For better performance and load management, you might consider distributing these components across multiple machines.

```sh
./build/bin/erigon --datadir=/desired/path/to/datadir \
 --chain=mainnet \
 --port=30304 \
 --http.port=8546 \
 --torrent.port=42068 \
 --private.api.addr=127.0.0.1:9091 \
 --http \
 --ws \
 --http.api=eth,debug,net,trace,web3,erigon \
 --log.dir.path=/desired/path/to/logs \
 --torrent.download.rate=512mb
```

### Flags of Interest

*   Default data directory is `/home/usr/.local/share/erigon`. If you want to store Erigon files in a non-default location, use the flag:

    ```bash
    --datadir=/desired/path/to/datadir
    ```
* The `--chain=mainnet` flag is set by default for Erigon to sync with the Ethereum mainnet. To explore other network options, check the [Supported Networks](supported-networks) section. For quick testing, consider selecting a testnet.
* `--log.dir.path` dictates where [logs](logs) will be output - useful for sending reports to the Erigon team when issues occur.
* Based on the [pruning mode](pruning-modes) you want to run you can add `--prune.mode=archive` to run an archive node, `--prune.mode=full` for a full node (default value) or `--prune.mode=minimal` for a minimal node.
* `--http.addr=0.0.0.0 --http.api=eth,web3,net,debug,trace,txpool` to use [RPC Service](../interacting-with-erigon/) and e.g. be able to connect your [wallet](web3-wallet).
* `--torrent.download.rate` sets the torrent download rate cap. The default is `512mb` (megabytes per second). During initial sync Erigon will use the full allowance — on a dedicated machine this is fine, but if you share the machine with other work you may want to lower it (e.g. `--torrent.download.rate=128mb`). Set `--torrent.download.rate=Inf` to remove the limit entirely.

To stop the Erigon node you can use the `CTRL+C` command.

Additional flags can be added to configure the node with several options.

- [configuring-erigon](configuring-erigon/)

## How do I know it's syncing?

Once your node is running, there are two ways to confirm it is making progress and to see exactly which stage of the initial sync it is in.

### 1. Read the live log line

Erigon's logs are organized by [staged sync](logs#staged-synchronization-architecture). Every log line emitted by the sync engine is prefixed with the current stage and its position in the pipeline. For example:

```text
INFO[02-20|15:00:00.123] [4/8 Bodies] Downloading block bodies   block=18234567 ...
```

The prefix `[4/8 Bodies]` means: *"stage 4 of 8, currently in the Bodies stage"*. As stages complete, the prefix advances (`[5/8 Senders]`, `[6/8 Execution]`, …) until you reach `[8/8 Finish]`, at which point the node is at the chain tip.

The full ordered stage list is in [Logs → Stage Definitions](logs#stage-definitions).

### 2. Query the JSON-RPC

If the RPC Daemon is enabled (default port `8545`), the standard `eth_syncing` method tells you whether the node is still catching up and how far behind it is:

```bash
curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:8545
```

* While syncing, the result is an object with `currentBlock`, `highestBlock`, and a `stages` array (one entry per stage, with `{stage_name, block_number}`). Subtract `currentBlock` from `highestBlock` to see how many blocks remain; the `stages` array gives you the same per-stage progress as the log prefix above. (`startingBlock` is also returned but is hardcoded to `"0x0"` and carries no meaningful info.)
* Once fully synced, the result is simply `false`.

:::tip
For a quick reference on monitoring sync progress (including using AI assistants via MCP), see the [Frequently Asked Questions](/help-center/frequently-asked-questions-faqs).
:::

## Help

To learn about the available commands, open your terminal in your Erigon 3 installation directory and run:

```bash
make help
```

This command will display a list of convenience commands available in the Makefile, along with their descriptions.

```text
 go-version:                        print and verify go version
 validate_docker_build_args:        ensure docker build args are valid
 docker:                            validate, update submodules and build with docker
 setup_xdg_data_home:               TODO
 docker-compose:                    validate build args, setup xdg data home, and run docker-compose up
 dbg                                debug build allows see C stack traces, run it with GOTRACEBACK=crash. You don't need debug build for C pit for profiling. To profile C code use SETCGOTRCKEBACK=1
 erigon:                            build erigon
 all:                               run erigon with all commands
 db-tools:                          build db tools
 test:                              run unit tests with a 100s timeout
 test-integration:                  run integration tests with a 30m timeout
 lint-deps:                         install lint dependencies
 lintci:                            run golangci-lint linters
 lint:                              run all linters
 clean:                             cleans the go cache, build dir, libmdbx db dir
 devtools:                          installs dev tools (and checks for npm installation etc.)
 mocks:                             generate test mocks
 mocks-clean:                       cleans all generated test mocks
 solc:                              generate all solidity contracts
 abigen:                            generate abis using abigen
 gencodec:                          generate marshalling code using gencodec
 graphql:                           generate graphql code
 gen:                               generate all auto-generated code in the codebase
 bindings:                          generate test contracts and core contracts
 prometheus:                        run prometheus and grafana with docker-compose
 escape:                            run escape path={path} to check for memory leaks e.g. run escape path=cmd/erigon
 git-submodules:                    update git submodules
 install:                           copies binaries and libraries to DIST
 user_linux:                        create "erigon" user (Linux)
 user_macos:                        create "erigon" user (MacOS)
 hive:                              run hive test suite locally using docker e.g. OUTPUT_DIR=~/results/hive SIM=ethereum/engine make hive
 automated-tests                    run automated tests (BUILD_ERIGON=0 to prevent erigon build with local image tag)
 help:                              print commands help

```

For example, from your Erigon 3 installation directory, run:

```bash
make clean
```

This will execute the clean target in the Makefile, which cleans the `go cache`, `build` directory, and `libmdbx` db directory.

---

# Architecture
URL: https://docs.erigon.tech/fundamentals/architecture


Erigon is an Ethereum execution-layer client designed around three goals: **low disk footprint**, **predictable performance**, and **operational simplicity**. This page explains how those goals shape its internal design so you know what is happening when you run the binary.

## At a glance

```mermaid
flowchart TB
    subgraph erigon["erigon (one binary)"]
        direction TB
        Sentry["Sentry<br/>(p2p)"]
        Downloader["Downloader<br/>(snapshots + EL data)"]
        Execution["Execution<br/>(Staged Sync)"]
        RPC["RPC Daemon<br/>(JSON-RPC, WS,<br/>GraphQL, gRPC)"]
        TxPool["TxPool"]
        Caplin["Caplin (CL)<br/>embedded by default"]
        Datadir[("datadir<br/>MDBX chaindata<br/>+ .seg snapshots")]

        Caplin -->|"new blocks<br/>(Engine API)"| Execution
        Sentry -->|tx gossip| TxPool
        Execution --> RPC

        Downloader -.writes snapshots.-> Datadir
        Execution -.reads/writes.-> Datadir
        RPC -.reads.-> Datadir
        TxPool -.reads/writes.-> Datadir
        Caplin -.reads/writes.-> Datadir
    end

    classDef component fill:#fff5e6,stroke:#EF7716,stroke-width:1.5px,color:#000
    classDef storage fill:#f0f0ff,stroke:#5860EF,stroke-width:1.5px,color:#000
    class Sentry,Downloader,Execution,RPC,TxPool,Caplin component
    class Datadir storage
```

Every box above is a Go package that runs **inside the `erigon` process by default**. The same binary can also be split into independent processes — see [Modular processes](#modular-processes).

## Staged sync

Erigon processes the chain in a series of **stages** rather than the traditional "fetch block → execute block → repeat" loop. Each stage runs to completion across the whole range before the next stage starts.

A simplified pipeline:

```text
1. Snapshots    → fetch immutable history files via BitTorrent (OtterSync)
2. Headers      → download and verify block headers
3. Bodies       → download block bodies
4. Senders      → recover transaction senders from signatures
5. Execution    → re-execute transactions, write state, and build the
                  state commitment (Merkle trie) — all in a single pass
6. Finalization → update the canonical chain
```

This is the order of Erigon 3's default stage list. There is no separate
`Commitment` stage — trie/state-root computation runs *inside* Execution (see
below).

Two consequences:

- **Faster initial sync.** Stages are CPU/IO-bound in different ways, so the pipeline avoids waiting on a single bottleneck per block. Snapshot download (stage 1) parallelises with execution warm-up.
- **Cheap restarts.** Each stage records its progress. Killing Erigon mid-sync and restarting resumes from the last completed checkpoint — Erigon does not re-execute from genesis.

In Erigon 3, the Execution stage absorbs many previously-separate stages (`stage_hash_state`, `stage_trie`, `log_index`, `history_index`, `trace_index`) into a single pass, which is one reason Erigon 3 syncs faster than Erigon 2.

## Modular processes

Each of Sentry, Downloader, TxPool, RPC Daemon, and Caplin can run as an **independent process** that talks to the rest over a private gRPC API.

Use the all-in-one binary by default. Split out a service when you have a concrete reason:

- **Resource isolation** — pin the RPC Daemon to its own CPUs so a heavy `eth_call` cannot stall block production.
- **Horizontal scaling** — run multiple RPC Daemons against one execution node to serve more concurrent clients.
- **Replacement** — substitute Erigon's TxPool or Sentry with your own implementation.
- **Security** — keep the p2p surface (Sentry) on a separate host from the JSON-RPC surface (RPC Daemon).

See the [Modules](modules) section for per-component documentation, and the repository's [docker-compose.yml](https://github.com/erigontech/erigon/blob/main/docker-compose.yml) for a worked split-process example.

## Storage model

Erigon stores everything under a single **datadir**. Two kinds of files live there:

| Kind | Path | Role | Mutable? |
|------|------|------|----------|
| Active state | `chaindata/` | Recent state and recent blocks, served from MDBX | Yes |
| Historical data | `snapshots/` | Older blocks, history, indices — distributed as immutable `.seg` files | No |

This split is what enables Erigon's small disk footprint relative to other archive nodes:

- **`chaindata/` is small (~15 GB on Ethereum mainnet)** because it only holds latest state and recently-updated values.
- **`snapshots/` is large but content-addressed.** Once a `.seg` file is finalised it is the *same file* on every Erigon node in the world — meaning it can be distributed via BitTorrent and verified by hash. There is no rewrite-amplification penalty for keeping history.

For the exact directory layout, file sizes on mainnet, and how to split storage across fast/slow disks, see [Database](database) and [Optimizing Storage](optimizing-storage).

## Embedded consensus (Caplin)

Erigon ships with **Caplin**, a built-in consensus-layer client. Caplin runs embedded by default, so a single `erigon` invocation runs both the execution layer and the consensus layer with no extra processes, no JWT secret to manage, and no separate binary to upgrade.

If you prefer to run an external CL (Lighthouse, Prysm, Teku, Nimbus), pass `--externalcl` and connect via the standard Engine API. The Engine-API path is identical to what Geth, Besu, or Reth exposes.

See [Caplin](caplin) for full details.

## Flat key-value state

Where most clients store account state in a Merkle Patricia Trie *inside* the database, Erigon stores it as **flat key-value pairs** and computes the trie root incrementally as part of Execution. Trade-off:

- **Read path is direct** — `getAccount(addr)` is a single key lookup, not a multi-level trie traversal.
- **Write path defers trie hashing** — updates accumulate in the KV store and the trie is rebuilt only when state-root computation requires it.

This is the single largest reason Erigon's RPC performance stays flat under load: there is no background trie compaction that can spike CPU during an `eth_call` burst.

## Pruning is a retention decision, not a sync mode

Erigon 3 has one sync pipeline. The user-facing choice is *what to retain after sync*, controlled by `--prune.mode`:

| Mode | Retained | Use case |
|---|---|---|
| `archive` | Entire state history + all blocks | Indexers, block explorers, deep historical queries |
| `full` (default) | Latest state + a rolling window of recent blocks (the default prune distance, ~262k blocks) | Most users, dApps, validators |
| `blocks` | All blocks, but no state history | Full block/receipt history without archive-size state |
| `minimal` | Latest state only (shortest block window) | Solo stakers, constrained hardware |

See [Pruning Modes](pruning-modes) for the full comparison.

## Where to go next

- [Database](database) — datadir layout, MDBX internals, mainnet sizing
- [Modules](modules) — running RPC Daemon, TxPool, Sentry, Downloader as separate processes
- [Pruning Modes](pruning-modes) — choosing what history to keep
- [Optimizing Storage](optimizing-storage) — splitting datadir across fast and slow disks

---

# Database
URL: https://docs.erigon.tech/fundamentals/database


Erigon stores all chain data under a single **datadir**. Understanding what lives where is useful when you size hardware, debug disk-usage issues, or split storage across fast and slow drives.

This page covers the *what* and *where* of Erigon's data. For the *why* — flat KV state, immutable snapshots — see [Architecture](architecture). For operational tuning (symlinks, multi-disk layout), see [Optimizing Storage](optimizing-storage).

## The datadir at a glance

```text
datadir/
├── chaindata/        # Active state + recent blocks (MDBX). Small, hot, mutable.
├── snapshots/        # Historical data as immutable .seg files. Large, cold.
│   ├── domain/         # Latest value per domain (4 state domains + 2 receipt domains)
│   ├── history/        # Historical values per domain
│   ├── idx/            # Inverted indices — search/filter/intersect historical data
│   └── accessor/       # Random-access indices over history (point lookups only)
├── txpool/           # Pending transactions. Safe to delete; will repopulate from peers.
├── nodes/            # p2p peer cache. Safe to delete; will repopulate.
└── temp/             # External-sort buffers (~100 GB peak). Cleaned at startup.
```

The split between **`chaindata/`** (mutable) and **`snapshots/`** (immutable) is the central design decision. It is what makes Erigon's archive node 10× smaller than other clients while staying fast.

## Storage engine: MDBX

`chaindata/` is a single [MDBX](https://github.com/erigontech/mdbx-go) key-value store. MDBX is a B+ tree engine derived from LMDB, optimised for read-heavy workloads and predictable memory use.

Properties that matter operationally:

- **No background compaction.** Writes go directly into the B+ tree; there is no compaction thread that can spike CPU mid-RPC-call. This is why Erigon's RPC latency does not degrade under load the way LSM-based engines (LevelDB, RocksDB) can.
- **Memory-mapped reads.** The OS page cache is the hot data cache. There is no separate per-process cache to tune. Multiple Erigon services on one machine share the same page cache automatically.
- **Single-writer.** One process holds the write lock; readers are unlimited and lock-free. This is why splitting RPC Daemon out as a separate process for read scaling works cleanly — only one writer ever touches the file.

## Snapshots: immutable history

Older blocks and history are not stored in MDBX. They are written to **`.seg` files** in `snapshots/` and **never modified after creation**.

Once a snapshot file is finalised it is the same bytes on every Erigon node in the world, identified by content hash. This unlocks two things:

- **BitTorrent distribution.** New nodes fetch snapshots from peers in parallel rather than re-executing history from genesis. This is what OtterSync does.
- **Backup / disaster recovery costs ~10× less.** Most of your datadir is content-addressed and can be re-downloaded from any peer if a disk fails. You only need to back up `chaindata/`.

Snapshots are organised into several subdirectories. The main ones are:

| Directory | What it holds | Access pattern |
|---|---|---|
| `snapshots/domain/` | Latest value per (domain, key). 6 domains: the 4 state domains (`account`, `storage`, `code`, `commitment`) plus 2 receipt domains (`receipt`, `rcache`) | Sequential + point lookup |
| `snapshots/history/` | Every historical value per (domain, key, txn) | Point lookup keyed by transaction |
| `snapshots/idx/` | Inverted indices over history — answers "which transactions touched key X?" | Search / filter / set intersection |
| `snapshots/accessor/` | Pre-built random-access indices over history files | Random-touch point reads only |

**Per-transaction granularity.** Erigon 3 indexes history at the **transaction** level, not the block level. This means:

- You can replay a single historical transaction without re-executing its block.
- If an account changes V1 → V2 → V1 within one block, `debug_getModifiedAccountsByNumber` correctly returns it.
- Erigon stores compact per-transaction receipt *metadata* — cumulative gas used, blob gas used, log index — in a **required** receipt domain. Full receipts (with logs) live in a separate cache domain that is **persisted by default** for `full`, `minimal`, and `blocks` modes (toggled with `--persist.receipts`; `archive` nodes skip it by default and re-derive from full state history). When a full receipt isn't cached, it is reconstructed on demand, re-deriving logs by re-execution.

## What does it cost on disk?

Real numbers from a Nov 2024 mainnet archive node:

```sh
# eth-mainnet — archive — prune.mode=archive
chaindata           15 GB
snapshots/accessor 120 GB
snapshots/domain   300 GB
snapshots/history  280 GB
snapshots/idx      430 GB
snapshots TOTAL    2.3 TB
```

The breakdown above lists the state/history snapshot subdirectories. The remaining ~1.2 TB is mostly block/transaction `.seg` data, which is not broken out separately here.

For up-to-date totals across all networks and pruning modes, see [Hardware Requirements](../get-started/hardware-requirements).

## Why `chaindata/` stays so small

In Erigon 3, `chaindata/` only holds:

- The very latest state values (post-snapshot tip)
- Recent blocks not yet folded into snapshots
- Live txpool, peer state, sync stage progress

Most of the bulk that other clients keep in the active database — historical state, ancient blocks, receipt logs — is in immutable snapshot files instead. This is why `chaindata/` rarely exceeds 20 GB even on archive nodes.

Deleting `chaindata/` is **recoverable but not free**: it discards the latest mutable state and any recent blocks not yet folded into snapshots. On restart Erigon re-derives state from the immutable snapshots (re-downloading them if needed) and resyncs the post-snapshot tip forward from the consensus layer over the Engine API — blocks are no longer pulled from peers over devp2p. Treat it as a resync of the chain tip, not a quick rebuild, and keep a backup if fast recovery matters.

## Tuning knobs

- **`--batchSize`** — size of the Execution stage's in-memory buffer before it is flushed to MDBX. Default: `512M`. Raising it (for example `--batchSize 1G` or higher) can speed up execution-heavy sync at the cost of more RAM.
- **`--db.size.limit`** — caps the MDBX file size. Useful when running multiple Erigon instances on one disk to prevent one from starving the others.
- **`--db.read.concurrency`** — number of concurrent MDBX read transactions. Increase when you run a high-throughput RPC Daemon against the same datadir.
- **Symlinks for tiered storage.** Place `chaindata/` and `snapshots/domain/` on fast NVMe, leave `snapshots/idx/` and `snapshots/history/` on cheaper SATA. See [Optimizing Storage](optimizing-storage) for the recipe.

## Safe-to-delete subdirectories

If you need to reclaim space without resyncing from scratch:

| Directory | Effect of deletion |
|---|---|
| `txpool/` | Pending transactions lost; pool refills from peers within minutes |
| `nodes/` | Peer cache lost; reconnects on restart |
| `temp/` | Cleaned automatically at startup anyway |
| `chaindata/` | Recoverable, but triggers a resync of the post-snapshot tip from the consensus layer — not instant; keep a backup for fast recovery |
| `snapshots/` | **Do not delete** — would force a full resync |

## Where to go next

- [Architecture](architecture) — how this storage model fits into staged sync and the flat-KV state design
- [Optimizing Storage](optimizing-storage) — concrete recipes for splitting the datadir across multiple disks
- [Hardware Requirements](../get-started/hardware-requirements) — disk-size numbers for each `--prune.mode`
- [Pruning Modes](pruning-modes) — choosing what history to keep

---

# Pruning Modes
URL: https://docs.erigon.tech/fundamentals/pruning-modes


Erigon 3 supports four pruning modes that control how much chain history your node retains. Choose based on your use case — most users should run a Full Node.

| **Pruning Mode**                                                        | **Flag**               | **Data Retained**                                                                                   | **Primary Use Case**                                                                     |
| --------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| * Full Node(Default) | `--prune.mode=full`    | State and block data within the EIP-8252 window (last 262,144 blocks, ~36 days)                     | General users, DApp interaction, fastest sync.                                           |
| \* [Minimal Node](#minimal-node)                         | `--prune.mode=minimal` | State and block data within the last 100,000 blocks (~14 days)                                      | Solo staking, users with constrained hardware, maximum privacy for sending transactions. |
| [Historical Blocks](#blocks-node)                                     | `--prune.mode=blocks`  | All block/transaction history, plus state within the EIP-8252 window                                | Users needing historical block data for research or indexing.                            |
| [Archive Node](#archive-node)                            | `--prune.mode=archive` | All historical state and all blocks                                                                 | Developers, researchers, and RPC providers requiring full historical state access.       |

By **default**, Erigon run as a [full node](#full-node), to change its behavior use the flag `--prune.mode <value>`.

In order to switch type of node, you must first delete the `/chaindata` folder in the chosen `--datadir` directory and re-sync from scratch.

:::tip
**\* Persisting receipts**, which are pre-calculated receipts, increase the requests-per-second (RPS) and improve the latency and throughput of all receipts and logs-related RPC calls.

They are enabled by default for **Minimal** and **Full Node.** They can be activated or deactivated with the flag `--persist.receipts <value>` .
:::

:::note[Breaking change in v3.5]
**`--prune.mode=full` now follows the EIP-8252 reorg-retention window.** In v3.4, full mode pruned only pre-merge block data (EIP-4444 history-expiry) and **kept all post-merge block bodies, transactions, and receipts**, with a 100,000-block state-history window. In v3.5 it retains just the last **262,144 blocks (~36.4 days)** for *both* state and block data, matching [EIP-8252](https://github.com/ethereum/EIPs/pull/11601)'s `REORG_RETENTION_WINDOW`. The state-history window therefore grows (100,000 → 262,144), but **block bodies and receipts older than 262,144 blocks are now pruned** — a full node will no longer serve them.

`--prune.mode=blocks` is unaffected for block data (it still keeps every block back to genesis); only its `History` window bumps from 100,000 to 262,144. `--prune.mode=minimal` is unchanged — both `Blocks` and `History` retain the 100,000-block window. **Existing datadirs upgrade automatically** on first start — Erigon rewrites the persisted mode and logs the transition, no operator action required. But **already-pruned block data cannot be recovered**: if you need to keep all post-merge blocks, switch to `--prune.mode=blocks` *before* upgrading. See [#21342](https://github.com/erigontech/erigon/pull/21342) for details.
:::

## Archive node

Ethereum's state refers to account balances, contracts, and consensus data. Archive nodes retain all historical state and require more **disk space.** However, Erigon 3 has consistently reduced the [disk space](../get-started/hardware-requirements.mdx#disk-size-and-ram-requirements) requirements for running an archive node, rendering it more affordable and accessible to a broader range of users.

Archive are ideal for extensive research on the blockchain, developers, researchers, and RPC providers requiring a complete history of the state.

## Full node

The default configuration in Erigon 3 is a Full Node. This setup is designed to offer significantly **faster sync times and reduced resource consumption** for daily operations compared to other clients. It maintains state and block data within the **EIP-8252 reorg-retention window** — the last 262,144 blocks (~36.4 days), the inactivity-leak-bounded non-finality window across which an execution-layer client must be able to reconstruct state to handle any reorg without external sync. Older blocks, receipts, and state history are pruned. See [EIP-8252](https://github.com/ethereum/EIPs/pull/11601) for the rationale behind the constant.

We strongly recommend running a Full Node whenever possible, as its reduced disk space requirements make it suitable for the majority of users. By running a Full Node, you directly support the network's **decentralization, resilience, and robustness**, aligning with Ethereum's distributed ethos.

## Minimal node

The Minimal Node configuration (`--prune.mode=minimal`) is the smallest possible setup. It keeps only recent blocks and the **latest state** — it does not retain state history, so historical state queries are not supported. This makes it perfectly suited for **solo staking** and users seeking maximum **privacy** when interacting with the EVM, such as sending transactions directly through their node. This mode is the most suitable for users with severely constrained hardware.

## Blocks node

The Blocks Node configuration (`--prune.mode=blocks`) keeps the **full block and transaction history** — every block back to genesis — while pruning **state history**. It retains state only within the EIP-8252 window (the last 262,144 blocks), the same state-retention as a Full Node, but unlike a Full Node it never prunes older blocks. This suits users who need complete historical **block and receipt data** — for research, indexing, or block explorers — without paying the disk cost of an archive node's full historical **state**.

---

# Snapshots Management
URL: https://docs.erigon.tech/fundamentals/snapshots-management


Erigon stores the majority of its chain data in **snapshot files** (`.seg` segments and associated index files). These immutable, compressed files cover headers, bodies, transactions, and state history. Because snapshots can occupy hundreds of gigabytes, understanding what is on disk — and how much space each category consumes — is essential for capacity planning and node maintenance.

## `seg du` — Disk Usage Report

The `seg du` subcommand scans the snapshot directory for a given `--datadir` and reports a breakdown of disk usage by category, the detected (and configured) node type, and estimated sizes for each pruning mode.

### Syntax

```bash
erigon seg du [--datadir <path>] [--json] [-v | --verbose]
```

### Flags

| Flag | Description |
|------|-------------|
| `--datadir <path>` | Path to the Erigon data directory. Defaults to Erigon's standard data directory (`paths.DefaultDataDir()`, OS-specific) when omitted. `seg du` has no `--chain` flag, so this default is chain-agnostic. |
| `--json` | Output results as JSON instead of human-readable text. Useful for scripting or dashboards. |
| `-v`, `--verbose` | Show a per-domain / per-type subcategory breakdown within each category. |

### Example output (human-readable)

```text
mainnet | archive | blocks 0–25.296.000 | steps 0–9.153
total: 1.8TB (4285 files)

── Breakdown ──────────────────────────────────────────────────
  block segments          900.2GB      48.3%   1195 files
  domains                 306.3GB      16.4%    154 files
  inverted indices        299.7GB      16.1%    596 files
  history                 230.7GB      12.4%    296 files
  accessors               127.7GB       6.8%    892 files
  other                     9.8MB       0.0%   1152 files
    extensions: .toml, .torrent, .txt

── Estimated Size by Node Type ────────────────────────────────
  archive            1.8TB          —    all blocks      all history
  full             361.2GB     -1.5TB    last 262.144    last 262.144
  blocks             1.2TB   -589.9GB    all blocks      last 262.144
  minimal          342.3GB     -1.5TB    last 100.000    last 100.000
```

Sizes use Erigon's `ByteCount` format (e.g. `850.4GB`, `1.2TB` — binary scale, no space). Block/step counts and prune-window sizes use `.` as the thousands separator, matching the binary's own output.

The estimator only sums files already on disk, so the **archive** row always equals the current total and no node-type estimate can exceed it. Estimates are therefore most meaningful against an archive datadir (shown above); on an already-pruned node the larger modes are capped at what is physically present. Rows are always printed in the fixed order `archive → full → blocks → minimal`.

**Header fields explained:**

- **Chain** — detected from `chaindata` (falls back to `unknown` if the database is locked or empty).
- **Mode** — the configured pruning mode read from the database, plus the mode detected from which files are present on disk. If they disagree, both are shown (e.g., `full (files look like archive)`).
- **blocks 0–N** — the highest block number across all block segment files.
- **steps 0–N** — the highest step number across all state files. A step is an internal Erigon unit covering a fixed number of *transactions* (`config3.DefaultStepSize` = 390,625 txNums), so the number of blocks per step varies with chain activity.

**Breakdown categories:**

The category labels below are exactly what the command prints.

| Category | Contents |
|----------|----------|
| `domains` | Current-state domain files (latest accounts, storage, code, commitment). Never pruned, so typically the largest category on pruned (full / minimal) nodes; on an archive node, `block segments` dominate. |
| `block segments` | Headers, bodies, and transactions (`.seg` + index files) directly under `snapshots/`. |
| `history` | State-history snapshots for accounts, storage, code. |
| `inverted indices` | Inverted indices over state history (enables range lookups). |
| `accessors` | Accessor index files that speed up state queries. |
| `caplin` | Consensus-layer (beacon chain) snapshots. |
| `commitment hist` | Commitment-history files (archive nodes only). |
| `rcache` | Receipt cache (pre-computed receipts for RPC performance). |
| `forkable` | Forkable (unwindable) snapshot data. |
| `other` | Any files with unrecognised extensions (listed inline). |

**Estimates table:** shows how much space the current snapshot set would occupy under each pruning mode, given the files already on disk. The `delta` column is relative to archive (negative = smaller than archive). This lets you compare your current footprint against what other modes would consume without resyncing.

### Example output (verbose, `-v`)

With `--verbose`, each category expands into its domain or type subcategories (excerpt — every category expands the same way):

```text
  block segments          900.2GB      48.3%   1195 files
  ├─ transactions        874.2GB      97.1%    174 files
  ├─ txn2block            12.3GB       1.4%     87 files
  ├─ headers              10.3GB       1.1%    174 files
  ├─ bodies                3.3GB       0.4%    174 files
  └─ blocksidecars        26.9MB       0.0%    586 files

  domains                 306.3GB      16.4%    154 files
  ├─ commitment          195.0GB      63.7%     22 files
  ├─ storage              79.7GB      26.0%     33 files
  ├─ code                 16.5GB       5.4%     33 files
  ├─ accounts             15.1GB       4.9%     33 files
  └─ receipt               6.1KB       0.0%     33 files
```

### JSON output (`--json`)

Use `--json` to get a machine-readable object suitable for scripting:

```bash
erigon seg du --datadir /data/erigon --json | jq '.estimates'
```

The JSON schema matches the `duResult` struct: top-level fields `chain`, `configured_mode`, `detected_mode`, `block_range`, `step_range`, `total_bytes`, `total_files`, `categories`, `subcategories`, `other_extensions`, `estimates`.

:::tip
Run `seg du` while the node is **stopped**. If Erigon is running and holds the database lock, the command falls back to `unknown` for the chain name and omits the configured mode — it will still scan snapshot files and produce size figures, but mode information will be incomplete.
:::

---

## Snapshot Types (Pruning Modes)

The snapshot set on disk reflects the node's **pruning mode**, and `seg du` automatically detects which mode your current files correspond to. For what each mode retains and how to choose one, see [Pruning Modes](pruning-modes).

The `seg du` estimates table shows the projected disk footprint for each mode given the files currently present, so you can evaluate a mode change before committing to a resync.

---

## Upgrading Snapshots in v3.5

### EIP-8252 retention window change

v3.5 retargets the **Full** and **Blocks** pruning modes to the EIP-8252 reorg-retention window (262,144 blocks, ~36 days), up from the previous 100,000-block window. This changes **which snapshot files are present on disk** after upgrading — most notably, full nodes prune older block segments down to the window, freeing space. Existing datadirs migrate automatically on first start.

For the full breaking-change details — what each mode keeps, why block data older than the window cannot be recovered, and what to do *before* upgrading if you need to keep all post-merge blocks — see the v3.5 breaking-change note in [Pruning Modes](pruning-modes).

After the first prune pass, run `seg du` to inspect the resulting on-disk breakdown.

### Manual snapshot operations

To migrate snapshots to the latest format, reset them for maximum performance after a major upgrade, or downgrade to an older snapshot format, follow the step-by-step snapshot upgrade and downgrade instructions in the [Upgrading guide](../get-started/installation/upgrading). Those commands are subcommands of `erigon snapshots` (e.g. `erigon snapshots update-to-new-ver-format --datadir /your/datadir`).

:::warning
Always **back up your `--datadir`** before running snapshot reset, upgrade, or downgrade commands.
:::

---

# Caplin
URL: https://docs.erigon.tech/fundamentals/caplin


Caplin, the innovative Erigon's embedded Consensus Layer, significantly enhances the performance, efficiency, and reliability of Ethereum infrastructure. Its groundbreaking design minimizes disk usage, facilitating faster transaction processing and bolstering network security. By integrating the consensus layer directly into the EVM-node, Caplin eliminates the need for separate disk storage, thereby reducing system complexity and enhancing overall efficiency.

## Caplin Usage

Caplin is enabled by default, at which point an external consensus layer is no longer needed.

```bash
./build/bin/erigon
```

Caplin also has an archive mode for historical states, blocks, and blobs. These can be enabled with the following flags:

* `--caplin.states-archive`: Enables the storage and retrieval of historical state data, allowing access to past states of the blockchain for debugging, analytics, or other use cases.
* `--caplin.blocks-archive`: Enables the storage of historical block data, making it possible to query or analyze full block history.
* `--caplin.blobs-archive`: Enables the storage of historical blobs, ensuring access to additional off-chain data that might be required for specific applications.

In addition, Caplin can backfill recent blobs for an op-node or other uses with the new flag:

* `--caplin.blobs-immediate-backfill`: Backfills the last 18 days' worth of blobs to quickly populate historical blob data for operational needs or analytics.

### PeerDAS Data Column Retention

For nodes participating in PeerDAS (EIP-7594), Caplin retains data column sidecars for a configurable window:

* `--caplin.columns-keep-slots` (default: `131072`, ~18 days): Number of slots to retain PeerDAS data column sidecars. The default matches `MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS × SLOTS_PER_EPOCH`. Increase this value for DA oracle or rollup nodes that require a longer column history.

Caplin can also be used for [block production](../staking/caplin), aka **staking**.

## Beacon API Configuration

When Caplin is running, it exposes a Beacon API that external tools can query. The following flags control the Beacon API server:

| Flag | Default | Description |
|------|---------|-------------|
| `--beacon.api.addr` | `localhost` | Listening address for the Beacon API |
| `--beacon.api.port` | `5555` | Listening port for the Beacon API |
| `--beacon.api.cors.allow-origins` | (empty) | CORS allowed origins |
| `--beacon.api.cors.allow-methods` | `GET, POST, PUT, DELETE, OPTIONS` | CORS allowed methods |
| `--beacon.api.cors.allow-credentials` | `false` | Allow credentials in CORS requests |
| `--beacon.api.protocol` | `tcp` | Network protocol (`tcp` or `tcp4` or `tcp6`) |
| `--beacon.api.read.timeout` | `5s` | HTTP server read timeout |
| `--beacon.api.write.timeout` | `31536000s` (~1 year) | HTTP server write timeout |
| `--beacon.api.ide.timeout` | `25s` | HTTP server idle timeout (note: flag name is `ide` not `idle` — typo in source) |

---

# CLI Reference
URL: https://docs.erigon.tech/fundamentals/configuring-erigon


The Erigon CLI has a wide range of flags that can be used to customize its behavior. There are 3 ways to configure Erigon, listed by priority:

* [Command line options](/fundamentals/configuring-erigon/#command-line-options) (flags)
* [Configuration file](/fundamentals/configuring-erigon/#configuration-file)
* [Environment variables](/fundamentals/configuring-erigon/#environment-variables)

:::tip
In order to see all the available options (flags) you must run the command:

```bash
./build/bin/erigon --help
```
:::

## Command line options

Flags are passed directly to the `erigon` binary at startup. Each flag starts with `--`, followed by the flag name and, where applicable, a value separated by a space or `=`. For example, to start Erigon on the Holesky testnet with a custom data directory and the JSON-RPC API enabled on port 8545:

```bash
./build/bin/erigon --chain=holesky --datadir=/data/erigon --http --http.port=8545
```

Flags can be combined freely, providing a high degree of customization. Here's a breakdown of the most important flags:

### General Options

These flags cover the general behavior and configuration of the Erigon client.

* `--datadir value`: Specifies the data directory for the databases.
  * Default: `/home/usr/.local/share/erigon`
* `--ethash.dagdir value`: Sets the directory to store the ethash mining DAGs.
  * Default: `/home/usr/.local/share/erigon-ethash`
* `--config value`: Sets Erigon flags using a YAML/TOML file.
* `--version, -v`: Prints the version information.
* `--help, -h`: Displays help information.
* `--chain value`: Sets the name of the [network](/fundamentals/supported-networks) to join.
  * Default: `mainnet`
* `--networkid value`: Explicitly sets the network ID.
  * Default: `1`
* `--identity value`: Sets a custom node name.
* `--externalcl`: Enables the external consensus layer.
  * Default: `false`, means that Caplin is enabled.
* `--override.osaka value`: Manually specifies the Osaka fork time.
  * Default: `0`
* `--override.amsterdam value`: Manually specifies the Amsterdam fork time.
  * Default: `0`
* `--vmdebug`: Records information for VM and contract debugging.
  * Default: `false`
* `--gdbme`: Restarts Erigon under gdb for debugging.
  * Default: `false`
* `--ethstats value`: The reporting URL for an ethstats service.
* `--trusted-setup-file value`: Absolute path to a `trusted_setup.json` file.
* `--persist.receipts, --experiment.persist.receipts.v2`: Downloads historical receipts.
  * Default: `true` for minimal and full nodes, `false` for archive nodes

### Database and Caching

These flags control database performance and memory usage. See [Database](/fundamentals/database) for the on-disk layout.

* `--db.pagesize value`: Sets the fixed page size for the database.
  * Default: `16KB`
* `--db.size.limit value`: Sets a runtime limit on the chaindata database size.
  * Default: `1TB`
* `--db.writemap`: Enables `WRITE_MAP` for fast database writes.
  * Default: `true`
* `--db.read.concurrency value`: Ceiling on concurrent open database read transactions (the MDBX read-transaction semaphore); when it is full, extra readers wait for a slot by default, though some RPC paths (HTTP/WebSocket) fail fast with an overload response instead. Low values are fine for low read-concurrency nodes (for example, validators); raise it for nodes serving heavy parallel RPC.
  * Default: scales with the host as `min(max(10, GOMAXPROCS * 64), 9000)` — kept well above the CPU count because reads are I/O-bound, and capped below Go's roughly 10,000 OS-thread limit.
* `--database.verbosity value`: Enables internal database logs.
  * Default: `2`
* `--batchSize value`: Sets the batch size for the execution stage.
  * Default: `512M`
* `--bodies.cache value`: Sets the size limit for the block bodies cache.
  * Default: `268435456`
* `--state.cache value`: Sets the amount of data to store in the StateCache.
  * Default: `0MB`
* `--sync.parallel-state-flushing`: Enables parallel state flushing.
  * Default: `true`
* `--erigondb.domain.steps-in-frozen-file value`: Overrides the `steps_in_frozen_file` setting from `erigondb.toml` for the domain merge cap only (history and inverted-index merges are unaffected). Pass a positive integer to set an explicit cap, or `Inf` to leave the domain merge unbounded.
  * Default: unset (uses the value from `erigondb.toml`)
  * Use with care — an incorrect value may affect database structure.

### Pruning and Snapshots

Flags for managing how old chain data is handled and stored. See [Snapshots Management](/fundamentals/snapshots-management) for snapshot tooling and disk usage.

* `--prune.mode value`: Selects a pruning preset (`full`, `archive`, `minimal`, `blocks`). See also [Pruning Modes](/fundamentals/pruning-modes)
  * Default: `"full"`
* `--prune.distance value`: Keeps state history for the latest `N` blocks.
  * Default: `0`
* `--prune.distance.blocks value`: Keeps block history for the latest `N` blocks.
  * Default: `0`
* `--prune.include-commitment-history, --prune.experimental.include-commitment-history, --experimental.commitment-history`: Enables fast `eth_getProof` for executed blocks by storing commitment history. Requires +32 GB RAM. See [`eth_getProof`](/interacting-with-erigon/eth#eth_getproof).
  * Default: `false`
* `--snap.skip-state-snapshot-download`: Skips state download and starts from genesis.
  * Default: `false`
* `--snap.keepblocks`: Workaround/debug — keeps ancient blocks in the DB instead of moving them into snapshots (useful for debugging).
  * Default: `false`
* `--snap.stop`: Workaround for snapshot-related bugs — stops producing new snapshot files (DB will grow as a result).
  * Default: `false`
* `--snap.state.stop`: Workaround for state-related bugs — stops producing new state files (DB will grow as a result).
  * Default: `false`
* `--snap.p2p-manifest` *(New in v3.5)* (experimental): Decentralized snapshot discovery — peers advertise their `chain.toml` manifest via ENR instead of the centralized `preverified.toml`. Opt-in; requires a compatible peer network.
  * Default: `false`
* `--snap.chaintoml-url value` *(New in v3.5)*: Fetch the preverified `chain.toml` directly from this URL instead of the default R2/GitHub CDN. Precedence: the `ERIGON_REMOTE_PREVERIFIED` environment variable (path to a local override file) wins over this URL and the default CDN; a local `preverified.toml` in the datadir also takes precedence — delete it to re-fetch from the URL.
  * Default: `""` (uses the built-in CDN)

### Transaction Pool (TxPool)

Options for configuring the [transaction pool](/fundamentals/modules/txpool).

* `--txpool.api.addr value`: The TxPool API network address.
  * Default: Uses the value of `--private.api.addr`
* `--txpool.disable`: Disables the internal transaction pool.
  * Default: `false`
* `--txpool.pricelimit value`: Sets the minimum gas price for acceptance into the pool.
  * Default: `1`
* `--txpool.pricebump value`: Sets the price bump percentage to replace a transaction.
  * Default: `10`
* `--txpool.blobpricebump value`: Sets the price bump percentage for replacing a type-3 blob transaction.
  * Default: `100`
* `--txpool.accountslots value`: Sets the number of executable transaction slots per account.
  * Default: `16`
* `--txpool.blobslots value`: Sets the maximum number of blobs per account.
  * Default: `540`
* `--txpool.totalblobpoollimit value`: Sets the total limit on the number of all blobs in the pool.
  * Default: `5400`
* `--txpool.globalslots value`: Sets the maximum number of executable transaction slots for all accounts.
  * Default: `10000`
* `--txpool.globalbasefeeslots value`: Sets the maximum number of non-executable transactions with insufficient base fees.
  * Default: `30000`
* `--txpool.globalqueue value`: Sets the maximum number of non-executable transaction slots for all accounts.
  * Default: `30000`
* `--txpool.trace.senders value`: A comma-separated list of addresses whose transactions will be traced.
* `--txpool.commit.every value`: Sets how often transactions are committed to storage.
  * Default: `15s`
* `--txpool.gossip.disable`: Disables P2P gossip of transactions.
  * Default: `false`

### Network and Peers

These flags manage network connectivity, peer discovery, and traffic control. See [Default Ports](/fundamentals/default-ports) for the full port map.

* `--port value`: The main network listening port.
  * Default: `30303`
* `--p2p.protocol value`: The version of the `eth` P2P protocol.
  * Default: `68`, `69`
* `--p2p.allowed-ports value`: A comma-separated list of allowed ports for different P2P protocols.
  * Default: `30303, 30304, 30305, 30306, 30307`
* `--nat value`: The NAT port mapping mechanism (See [here](/fundamentals/nat) for more details).
* `--nodiscover`: Disables peer discovery.
  * Default: `false`
* `--discovery.v4`, `--discv4`: Enables the Node Discovery Protocol v4 (Discv4) for managed ENRs and topic discovery.
  * Default: `false` (disabled by default since v3.4; discv5 is now the default discovery protocol)
* `--discovery.v5`, `--discv5`, `--v5disc`: Enables the Node Discovery Protocol v5 (Discv5) for managed ENRs and topic discovery.
  * Default: `true` (enabled by default since v3.4)
* `--netrestrict value`: Restricts network communication to specific IP networks.
* `--nodekey value`: The P2P node key file.
* `--nodekeyhex value`: The P2P node key as a hexadecimal string.
* `--discovery.dns value`: Sets DNS discovery entry points.
* `--bootnodes value`: Comma-separated enode URLs for P2P discovery bootstrap.
* `--staticpeers value`: Comma-separated enode URLs to connect to.
* `--trustedpeers value`: Comma-separated enode URLs for trusted peers.
* `--maxpeers value`: The maximum number of network peers.
  * Default: `32`

### RPC & API

Flags for configuring various RPC servers and their behavior. See [Interacting with Erigon](/interacting-with-erigon) for the JSON-RPC API reference.

* `--private.api.addr value`: The internal gRPC API address for Erigon's components.
  * Default: `127.0.0.1:9090`
* `--private.api.ratelimit value`: Limits the number of simultaneous internal API requests.
  * Default: `31872`
* `--http`: Enables the JSON-RPC HTTP server.
  * Default: `true`
* `--http.enabled`: An alternative flag to enable the HTTP server.
  * Default: `true`
* `--graphql`: Enables the GraphQL endpoint.
  * Default: `false`
* `--http.addr value`: The HTTP-RPC server listening interface.
  * Default: `localhost`
* `--http.port value`: The HTTP-RPC server listening port.
  * Default: `8545`
* `--authrpc.addr value`: The HTTP-RPC server listening interface for the Engine API.
  * Default: `localhost`
* `--authrpc.port value`: The HTTP-RPC server listening port for the Engine API.
  * Default: `8551`
* `--authrpc.jwtsecret value`: The path to the [JWT secret](/fundamentals/jwt) file for the consensus layer.
* `--http.compression`: Enables compression over HTTP-RPC.
  * Default: `true`
* `--http.corsdomain value`: A comma-separated list of domains for cross-origin requests.
* `--http.vhosts value`: A comma-separated list of virtual hostnames.
  * Default: `localhost`
* `--authrpc.vhosts value`: A comma-separated list of virtual hostnames for the Engine API.
  * Default: `localhost`
* `--http.api value`: The APIs offered over the HTTP-RPC interface.
  * Default: `eth,erigon,engine`
* `--ws`: Enables the WS-RPC server.
  * Default: `false`
* `--ws.port value`: The WS-RPC server listening port.
  * Default: `8546`
* `--ws.compression`: Enables compression over WebSocket.
  * Default: `true`
* `--rpc.batch.concurrency value`: Limits the number of goroutines for batch requests.
  * Default: `2`
* `--rpc.max.concurrency value`: Maximum number of concurrent HTTP RPC requests (HTTP admission control).
  * Default: `0` (inherits value from `--db.read.concurrency`)
  * Set to `-1` to disable admission control (unlimited)
* `--rpc.streaming.disable`: Disables JSON streaming for heavy endpoints.
  * Default: `false`
* `--rpc.accessList value`: Specifies a granular API allowlist.
* `--rpc.gascap value`: Sets a cap on gas usage for `eth_call`/`estimateGas`.
  * Default: `50000000`
* `--rpc.batch.limit value`: Sets the maximum number of requests in a batch.
  * Default: `100`
* `--rpc.blockrange.limit value`: Sets the maximum block range for `eth_getLogs` and similar range queries.
  * Default: `1000`
  * Applies to: `eth_getLogs`, `erigon_getLogs`
* `--rpc.logs.maxresults value`: Sets the maximum number of log results returned per query.
  * Default: `20000`
  * Applies to: `eth_getLogs`, `erigon_getLogs`, `erigon_getLatestLogs`
  * Set to `0` to remove the limit entirely (use with caution on large ranges).
  * Works in tandem with `--rpc.blockrange.limit`: both constraints apply independently — a query can be blocked by either limit.
* `--rpc.returndata.limit value`: Sets the maximum return data size for `eth_call`.
  * Default: `100000`
* `--rpc.allow-unprotected-txs`: Allows unprotected transactions via RPC.
  * Default: `false`
* `--rpc.txfeecap value`: Sets a cap on transaction fees in ether.
  * Default: `1`
* `--rpc.slow value`: Logs RPC requests slower than the specified threshold.
  * Default: `0s`
* `--rpc.evmtimeout value`: The maximum time to wait for an EVM call.
  * Default: `5m0s`
* `--rpc.overlay.getlogstimeout value`: The maximum time to wait for `overlay_getLogs`.
  * Default: `5m0s`
* `--rpc.overlay.replayblocktimeout value`: The maximum time to wait to replay a single block.
  * Default: `10s`
* `--rpc.subscription.filters.maxlogs value`: Maximum logs to store per subscription.
  * Default: `10000`
* `--rpc.subscription.filters.maxheaders value`: Maximum block headers to store per subscription.
  * Default: `10000`
* `--rpc.subscription.filters.maxtxs value`: Maximum transactions to store per subscription.
  * Default: `10000`
* `--rpc.subscription.filters.maxaddresses value`: Maximum addresses per subscription to filter logs by.
  * Default: `0`
* `--rpc.subscription.filters.maxtopics value`: Maximum topics per subscription to filter logs by.
  * Default: `0`
* `--http.timeouts.read value`: Maximum duration for reading a request.
  * Default: `30s`
* `--http.timeouts.write value`: Maximum duration before timing out a response write.
  * Default: `30m0s`
* `--http.timeouts.idle value`: Maximum idle time for a connection with keep-alives enabled.
  * Default: `2m0s`
* `--authrpc.timeouts.read value`: Maximum read duration for an Engine API request.
  * Default: `30s`
* `--authrpc.timeouts.write value`: Maximum write duration for an Engine API response.
  * Default: `30m0s`
* `--authrpc.timeouts.idle value`: Maximum idle time for an Engine API connection.
  * Default: `2m0s`
* `--healthcheck`: Enables gRPC health checks.
  * Default: `false`

### MCP Server

Flags for configuring the Model Context Protocol (MCP) server. The embedded [MCP server](/fundamentals/mcp) is **enabled by default** on
`127.0.0.1:8553`. Pass `--mcp.disable` to turn it off.

* `--mcp.disable`: Disables the embedded MCP server.
    * Default: `false`
* `--mcp.addr value`: The MCP server listening address.
  * Default: `127.0.0.1`
* `--mcp.port value`: The MCP server listening port.
  * Default: `8553`

### Logging and Profiling

Flags for controlling logging and performance profiling. See [Logs](/fundamentals/logs) for log files, levels, and rotation.

* `--log.json`: Formats console logs with JSON.
  * Default: `false`
* `--log.console.json`: Formats console logs with JSON.
  * Default: `false`
* `--log.dir.json`: Formats file logs with JSON.
  * Default: `false`
* `--verbosity value`: Sets the log level for console logs.
  * Default: `info`
* `--log.console.verbosity value`: Sets the log level for console logs.
  * Default: `info`
* `--log.dir.disable`: Disables disk logging.
  * Default: `false`
* `--log.dir.path value`: The path to store user and error logs.
* `--log.dir.prefix value`: The file name prefix for logs stored on disk.
* `--log.dir.verbosity value`: Sets the log verbosity for disk logs.
  * Default: `dbug`
* `--log.delays`: Enables block delay logging.
  * Default: `false`
* `--pprof`: Enables the pprof HTTP server.
  * Default: `false`
* `--pprof.addr value`: The pprof HTTP server listening interface.
  * Default: `127.0.0.1`
* `--pprof.port value`: The pprof HTTP server listening port.
  * Default: `6060`
* `--pprof.cpuprofile value`: Writes a CPU profile to a file.
* `--trace value`: Writes an execution trace to a file.
* `--vmtrace value`: Sets the provider tracer.
* `--vmtrace.jsonconfig value`: Sets the tracer's configuration.
* `--metrics`: Enables metrics collection and reporting. See [Creating a dashboard](/fundamentals/creating-a-dashboard).
  * Default: `false`
* `--metrics.addr value`: The stand-alone metrics HTTP server listening interface.
  * Default: `127.0.0.1`
* `--metrics.port value`: The metrics HTTP server listening port.
  * Default: `6061`

### Consensus and Forks

Flags related to consensus mechanisms and network forks.

* `--clique.checkpoint value`: The number of blocks after which to save the vote snapshot.
  * Default: `10`
* `--clique.snapshots value`: The number of recent vote snapshots to keep in memory.
  * Default: `1024`
* `--clique.signatures value`: The number of recent block signatures to keep in memory.
  * Default: `16384`
* `--clique.datadir value`: The path to the clique database folder.
* `--fakepow`: Disables proof-of-work verification.
  * Default: `false`
* `--gpo.blocks value`: The number of recent blocks to check for gas prices.
  * Default: `20`
* `--gpo.percentile value`: The percentile of recent transaction gas prices to use for a suggested gas price.
  * Default: `60`
* `--proposer.disable`: Disables the PoS proposer.
  * Default: `false`
* `--bor.heimdall value`: The URL of the Heimdall service.
  * Default: `http://localhost:1317`
* `--bor.withoutheimdall`: Runs without the Heimdall service.
  * Default: `false`
* `--bor.period`: Overrides the bor block period.
  * Default: `false`
* `--bor.minblocksize`: Ignores the bor block period and waits for `blocksize` transactions.
  * Default: `false`
* `--polygon.pos.ssf`: Enables Polygon PoS Single Slot Finality.
  * Default: `false`
* `--polygon.pos.ssf.block value`: Enables Polygon PoS Single Slot Finality from a specific block.
  * Default: `0`

### Sentry

Flags for configuring the [Sentry](/fundamentals/modules/sentry) component.

* `--sentry.api.addr value`: A comma-separated list of Sentry addresses.
* `--sentry.log-peer-info`: Logs detailed peer info when a peer connects or disconnects.
  * Default: `false`
* `--sentinel.addr value`: The address for the sentinel component.
  * Default: `localhost`
* `--sentinel.port value`: The port for the sentinel component.
  * Default: `7777`
* `--sentinel.bootnodes value`: Comma-separated enode URLs for P2P discovery bootstrap for the sentinel.
* `--sentinel.staticpeers value`: Connects to comma-separated consensus static peers.

### Downloader and Synchronization

These flags control the block synchronization and data downloading process, including the BitTorrent protocol settings. See [Downloader](/fundamentals/modules/downloader) for how snapshot downloading works.

* `--downloader.api.addr value`: The Downloader address.
* `--downloader.disable.ipv4`: Disables IPv4 for the Downloader.
  * Default: `false`
* `--downloader.disable.ipv6`: Disables IPv6 for the Downloader.
  * Default: `false`
* `--no-downloader`: Disables the Downloader component.
  * Default: `false`
* `--downloader.verify`: Verifies snapshots on startup.
  * Default: `false`
* `--sync.loop.throttle value`: Sets the minimum time between sync loop starts.
* `--sync.loop.block.limit value`: Sets the maximum number of blocks to process per loop iteration.
  * Default: `5000`
* `--sync.loop.break.after value`: Sets the last stage of the sync loop to run.
* `--bad.block value`: Marks a block as bad and forces a reorg.
* `--webseed value`: Comma-separated URLs for network support infrastructure.

#### BitTorrent Options

* `--torrent.port value`: The port to listen for the BitTorrent protocol.
  * Default: `42069`
* `--torrent.maxpeers value`: An unused parameter.
  * Default: `100`
* `--torrent.conns.perfile value`: The number of connections per file.
  * Default: `10`
* `--torrent.trackers.disable`: Disables conventional BitTorrent trackers.
  * Default: `false`
* `--torrent.upload.rate value`: The upload rate in bytes per second.
  * Default: `16mb`
* `--torrent.download.rate value`: Sets the torrent download rate cap. Default: `512mb`. Use a lower value on shared machines to avoid saturating the connection; use `Inf` to remove the limit.
* `--torrent.webseed.download.rate value`: The download rate for webseeds. If not set, rate limit is shared with torrent.
* `--torrent.verbosity value`: Sets the verbosity level for BitTorrent logs. 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail (must set `--verbosity` to equal or higher level)
  * Default: `1`

### Fork Choice Update (FCU)

Flags for configuring Fork Choice Update behavior.

* `--fcu.timeout value`: FCU timeout before switching to async processing (use `0` to disable).
  * Default: `1s`
* `--fcu.background.prune`: Enables background pruning after FCU.
  * Default: `true`
* `--fcu.background.commit`: Enables background flush and commit after FCU.
  * Default: `false`

### Execution

Flags for configuring the parallel block execution engine.

**All `--exec.*` flags are new in v3.5** — they expose, as CLI flags, execution toggles that on earlier releases were settable only via the `EXEC3_*` / `NO_*` environment variables (which still work).

* `--exec.workers value`: Number of parallel block-execution workers (equivalent to the `EXEC3_WORKERS` env var). Overridden by `--exec.serial`.
  * Default: the number of CPU cores (inherited from the `EXEC3_WORKERS` default when the flag is not set).
  * Note: `erigon --help` describes this flag's default as "half the number of CPU cores". That value is not actually applied — when `--exec.workers` is omitted, Erigon uses `EXEC3_WORKERS`, which defaults to the full CPU-core count. The flag-help text is a known inconsistency in the binary.
* `--exec.serial`: Force serial execution by clamping the parallel executor to a single worker. Wins over `--exec.workers` and `EXEC3_WORKERS` — use to disable parallelism for diagnostics or like-for-like baseline comparisons.
  * Default: `false`
* `--exec.no-prune`: Disable all DB pruning: state-aggregator (Domain/InvertedIndex/forkable) plus stage-level pruning (Execution: ChangeSets3/BlockAccessList; TxLookup; WitnessProcessing; Snapshots: PruneAncientBlocks/canonical markers/retirement). Equivalent to `NO_PRUNE=true`. Diagnostic / perf-comparison use only.
  * Default: `false`
* `--exec.no-merge`: Disable state-aggregator file merges for Domain / History / Inverted-Index. Equivalent to `NO_MERGE=true`. Diagnostic / perf-comparison use only.
  * Default: `false`
* `--exec.no-background-maintenance`: Suppress background state-aggregator and E2 block-snapshot retirement goroutines so execution is not perturbed by housekeeping work. Equivalent to `NO_BACKGROUND_E3_BUILD=true`. Diagnostic / focused-performance-testing use only — NOT an operational setting.
  * Default: `false`
* `--exec.batched-io`: Enable BAL-driven I/O optimisations — read-ahead pre-warming of the DB page cache (`READ_AHEAD=true`) and version-map pre-population from BAL hints (`IGNORE_BAL=false`). Disable for cold-read or non-BAL scheduling performance measurements.
  * Default: `true`
* `--exec.state-cache`: Enable the executor's domain-shared read cache. Equivalent to `USE_STATE_CACHE=true`. Disable for cold-read performance measurements.
  * Default: `true`

### Caplin (Consensus Layer)

Flags for configuring the [Caplin](/fundamentals/caplin) consensus layer.

* `--caplin.discovery.addr value`: The address for the Caplin DISCV5 protocol.
  * Default: `0.0.0.0`
* `--caplin.discovery.port value`: The port for the Caplin DISCV5 protocol.
  * Default: `4000`
* `--caplin.discovery.tcpport value`: The TCP port for the Caplin DISCV5 protocol.
  * Default: `4001`
* `--caplin.checkpoint-sync-url value`: The checkpoint sync endpoint.
* `--caplin.subscribe-all-topics`: Subscribes to all gossip topics.
  * Default: `false`
* `--caplin.max-peer-count value`: The maximum number of peers to connect to.
  * Default: `128`
* `--caplin.enable-upnp`: Enables NAT porting for Caplin.
  * Default: `false`
* `--caplin.nat value`: NAT port mapping for Caplin P2P. Sets the external IP advertised in the discv5 ENR and libp2p multiaddrs while the socket binds to `--caplin.discovery.addr`. Required when running inside Docker or behind NAT. Accepted values: `""` (none), `"extip:1.2.3.4"`, `"stun"`, `"stun:<host>"`, `"upnp"`, `"pmp"`, `"pmp:192.168.0.1"`.
  * Default: `""` (no NAT mapping)
* `--caplin.max-inbound-traffic-per-peer value`: The maximum inbound traffic per second per peer.
  * Default: `1MB`
* `--caplin.max-outbound-traffic-per-peer value`: The maximum outbound traffic per second per peer.
  * Default: `1MB`
* `--caplin.adaptable-maximum-traffic-requirements`: Makes the node adaptable to traffic based on the number of validators.
  * Default: `true`
* `--caplin.blocks-archive`: Enables backfilling for blocks.
  * Default: `false`
* `--caplin.blobs-archive`: Enables backfilling for blobs.
  * Default: `false`
* `--caplin.states-archive`: Enables the archival node for historical states.
  * Default: `false`
* `--caplin.blobs-immediate-backfill`: Tells Caplin to immediately backfill blobs.
  * Default: `false`
* `--caplin.blobs-no-pruning`: Disables blob pruning.
  * Default: `false`
* `--caplin.columns-keep-slots value`: Number of slots to retain PeerDAS data column sidecars. Increase for DA oracle or rollup nodes that need longer column history.
  * Default: `131072` (~18 days)
* `--caplin.checkpoint-sync.disable`: Disables checkpoint sync.
  * Default: `false`
* `--caplin.snapgen`: Enables snapshot generation.
  * Default: `false`
* `--caplin.mev-relay-url value`: The MEV relay endpoint.
* `--caplin.validator-monitor`: Enables Caplin validator monitoring metrics.
  * Default: `false`
* `--caplin.custom-config value`: Sets a custom config for Caplin.
* `--caplin.custom-genesis value`: Sets a custom genesis for Caplin.
* `--caplin.use-engine-api`: Uses the Engine API for internal Caplin.
  * Default: `false`

### Shutter Network Encrypted Transactions

Flags for configuring the [Shutter Network](/staking/shutter-network) encrypted transactions mempool.

* `--shutter`: Enables the Shutter encrypted transactions mempool.
  * Default: `false`
* `--shutter.p2p.bootstrap.nodes value`: Overrides the default P2P bootstrap nodes.
* `--shutter.p2p.listen.port value`: Overrides the default P2P listen port.
  * Default: `0`

## Configuration file

You can configure Erigon using a YAML or TOML configuration file by specifying its path with the `--config` flag.

:::tip
**Note**: flags specified in the configuration file can be overridden by directly setting them in the Erigon command line.
:::

Both in YAML and TOML files boolean operators (`false`, `true`) and strings without spaces can be specified without quotes, while strings with spaces must be included in `""` or `''` quotes.

### YAML

Use the `--config` flag to point at the YAML configuration file.

```bash
./build/bin/erigon --config ./config.yaml --chain=holesky
```

Example of a YAML config file:

```yaml
datadir : 'your datadir'
chain : "mainnet"
http : true
http.api : ["eth","debug","net"]
```

In this case the `--chain` flag in the command line will override the value in the YAML file and Erigon will run on the Holesky testnet.

### TOML

Use the `--config` flag to point at the TOML configuration file.

```bash
./build/bin/erigon --config ./config.toml
```

Example of a TOML config file:

```toml
datadir = 'your datadir'
chain = "mainnet"
http = true
"http.api" = ["eth","debug","net"]
```

## Environment variables

Erigon supports configuration through environment variables, primarily for experimental features and advanced settings.

### Core Environment Variables

**Database and Performance:**

* `MDBX_LOCK_IN_RAM` - Locks MDBX database in RAM for better performance
* `MDBX_DIRTY_SPACE_MB` - Sets dirty space limit for MDBX database
* `SNAPSHOT_MADV_RND` - Controls snapshot memory advice randomization (default: `true`)

**Synchronization and Pruning:**

* `NO_PRUNE` - Disables pruning when set to true (flag equivalent: `--exec.no-prune`)
* `NO_MERGE` - Disables merging operations (flag equivalent: `--exec.no-merge`)
* `PRUNE_TOTAL_DIFFICULTY` - Controls total difficulty pruning (default: `true`)
* `MAX_REORG_DEPTH` - Sets maximum reorganization depth (default: `512`)

**Execution and Processing:**

* `EXEC3_PARALLEL` - Enables parallel block execution (Block-STM). **Default changed to `true` in v3.5** — parallel execution is now on by default. Set to `false` or use `--exec.serial` to revert to single-threaded execution.
* `EXEC3_WORKERS` - Sets number of parallel execution workers (default: number of CPU cores)
* `STAGES_ONLY_BLOCKS` - Limits stages to blocks only

### Memory and Debugging Variables

**Memory Management:**

* `NO_MEMSTAT` - Disables memory statistics collection
* `SAVE_HEAP_PROFILE` - Enables automatic heap profiling
* `HEAP_PROFILE_THRESHOLD` - Memory usage percentage threshold for heap profiling (default: 35%)

**Tracing and Debugging:**

* `TRACE_ACCOUNTS` - Comma-separated list of accounts to trace
* `TRACE_BLOCKS` - Comma-separated list of block numbers to trace
* `TRACE_INSTRUCTIONS` - Enables instruction-level tracing

### Docker Environment Variables

When running Erigon in [Docker](/fundamentals/docker-compose), you can configure user permissions and data directories:

* `DOCKER_UID` - The UID of the Docker user
* `DOCKER_GID` - The GID of the Docker user
* `XDG_DATA_HOME` - The data directory mounted to containers

### Usage Examples

**Basic Performance Tuning:**

```bash
export MDBX_LOCK_IN_RAM=true
export SNAPSHOT_MADV_RND=false
./build/bin/erigon --datadir=/path/to/data
```

**Memory Debugging:**

```bash
export SAVE_HEAP_PROFILE=true
export HEAP_PROFILE_THRESHOLD=45
./build/bin/erigon --datadir=/path/to/data
```

**Docker Deployment:**

```bash
export DOCKER_UID=$(id -u)
export DOCKER_GID=$(id -g)
export XDG_DATA_HOME=/preferred/data/folder
make docker-compose
```

---

# Supported Networks
URL: https://docs.erigon.tech/fundamentals/supported-networks


The default flag is `--chain=mainnet`, which enables Erigon to operate on the Ethereum mainnet. Utilize the flag `--chain=<tag>` to synchronize with one of the supported networks. For example, to synchronize Holesky, one of the Ethereum testnets, use:

```bash
./build/bin/erigon --chain=hoodi
```

## Mainnets

| Chain     | Tag         | ChainId |
| --------- | ----------- | ------- |
| Ethereum  | mainnet     | 1       |
| Polygon\* | bor-mainnet | 137     |
| Gnosis    | gnosis      | 100     |

## Testnets

### Ethereum testnets

| Chain   | Tag     | ChainId  |
| ------- | ------- | -------- |
| Sepolia | sepolia | 11155111 |
| Hoodi   | hoodi   | 560048   |

### Polygon testnets

| Chain  | Tag  | ChainId |
| ------ | ---- | ------- |
| Amoy\* | amoy | 80002   |

### Gnosis Chain Testnets

| Chain  | Tag    | ChainId |
| ------ | ------ | ------- |
| Chiado | chiado | 10200   |

:::warning
\* The final release series of Erigon that officially supports Polygon is 3.1.\*. For the software supported by Polygon, please refer to the link: [https://github.com/0xPolygon/erigon/releases](https://github.com/0xPolygon/erigon/releases).
:::

---

# Layer 2 Networks
URL: https://docs.erigon.tech/fundamentals/layer-2-networks


### Running an Op-Node alongside Erigon

To run an op-node alongside Erigon, follow these steps:

1.  **Start Erigon with Caplin Enabled**: If Caplin is running as the consensus layer (CL), use the `--caplin.blobs-immediate-backfill` flag to ensure the last 18 days of blobs are backfilled, which is critical for proper synchronization with the op-node, assuming you start from a snapshot.

    ```bash
    ./build/bin/erigon --caplin.blobs-immediate-backfill
    ```
2. **Run the Op-Node**: Configure the op-node with the `--l1.trustrpc` flag to trust the Erigon RPC layer as the L1 node. This setup ensures smooth communication and synchronization.

This configuration enables the op-node to function effectively with Erigon serving as both the L1 node and the CL.

### How to run Erigon Nitro for Sepolia (experimental)

To start an Erigon Nitro node, simply use this Docker command:

```shell
mkdir /disk/datadir && \
docker run -d -v /disk/datadir/:/home/user/erigon-data/ erigontech/nitro-erigon:main-fe4c973 --torrent.download.rate=10G --prune.mode=archive --l2rpc="http://rpcserver:port --sync.loop.block.limit 100000
```

* **Arbitrum Sequencer**: We're currently working on adding support for the Arbitrum Sequencer. Until that work is complete, you must point Erigon to an external L2 Arbitrum RPC to get the most recent transactions and blocks. This can be either a pruned Nitro node you operate or a publicly available RPC. Any data beyond that is queried via the configured `l2rpc` during setup and synchronization, so keep this in mind when bringing a node online.
* **RPC compatibility**: Before declaring full Arbitrum One support, we are targeting complete RPC compatibility with the Nitro node. Please note that the `timeboosted` field will remain unavailable until Sequencer integration is complete.

For more recent versions, please check [https://hub.docker.com/r/erigontech/nitro-erigon/tags](https://hub.docker.com/r/erigontech/nitro-erigon/tags).

---

# Default ports
URL: https://docs.erigon.tech/fundamentals/default-ports


Erigon use the following default port for each service:

| Component | Port    | Protocol  | Purpose                     | Should Expose |
|-----------|---------|-----------|-----------------------------|---------------|
| engine    | `9090`  | TCP       | gRPC Server                 | Private       |
| engine    | `42069` | TCP & UDP | Snap sync (Bittorrent)      | Public        |
| engine    | `8551`  | TCP       | Engine API (JWT auth)       | Private       |
| Sentry    | `30303` | TCP & UDP | eth/68 peering              | Public        |
| Sentry    | `30304` | TCP & UDP | eth/69 peering              | Public        |
| Sentry    | `9091`  | TCP       | incoming gRPC Connections   | Private       |
| RPC Daemon | `8545`  | TCP       | HTTP & WebSockets & GraphQL | Private       |
| mcp       | `8553`  | TCP       | MCP server (AI assistants)  | Private       |
| shutter   | `23102` | TCP       | Peering                     | Public        |

Typically, `30303` and `30304` are exposed to the internet to allow incoming peering connections. `9090` is exposed only internally for RPC Daemon or other connections, (e.g. RPC Daemon -> erigon). Port `8551` (JWT authenticated) is exposed only internally for Engine API JSON-RPC queries from the Consensus Layer node.

To ensure proper P2P functionality for both the Execution and Consensus layers use a minimal configuration without exposing unnecessary services:

* Avoid exposing other ports unless necessary for specific use cases (e.g., JSON-RPC or WebSocket);
* Regularly audit your firewall rules to ensure they are aligned with your infrastructure needs;
* Use monitoring tools like Prometheus or Grafana to track P2P communication metrics.

## Command-Line Switches for Network and Port Configuration

Here is a comprehensive list of port-related options:

### Engine

* `--private.api.addr [value]`: Erigon's internal gRPC API, empty string means not to start the listener (default: `127.0.0.1:9090`)
* `--txpool.api.addr [value]`: TxPool api network address, (default: use value of `--private.api.addr`)
* `--torrent.port [value]`: Port to listen and serve BitTorrent protocol (default: `42069`)
* `--authrpc.port [value]`: HTTP-RPC server listening port for the Engine API (default: `8551`)

### Sentry

* `--port [value]`: Network listening port (default: `30303`)
* `--p2p.allowed-ports [value]`: Allowed ports to pick for different eth p2p protocol versions (default: `30303`, `30304`, `30305`, `30306`, `30307`)
* `--sentry.api.addr [value]`: Comma separated Sentry addresses `<host>:<port>,<host>:<port>` (default `127.0.0.1:9091`)

### RPC Daemon

* `--ws.port [value]`: WS-RPC server listening port (default: `8546`)
* `--http.port [value]`: HTTP-RPC server listening port (default: `8545`)

### Caplin

* `--caplin.discovery.port [value]`: Port for Caplin DISCV5 protocol (default: `4000`)
* `--caplin.discovery.tcpport [value]`: TCP Port for Caplin DISCV5 protocol (default: `4001`)

### BeaconAPI

* `--beacon.api.port [value]`: Sets the port to listen for beacon api requests (default: `5555`)

### MCP Server

The embedded MCP server is enabled by default. To disable it, pass `--mcp.disable`.

* `--mcp.disable`: Disables the embedded MCP server (default: `false`)
* `--mcp.addr [value]`: MCP server listening address (default: `127.0.0.1`)
* `--mcp.port [value]`: MCP server listening port (default: `8553`)

### Diagnostics

* `--diagnostics.endpoint.port [value]`: Diagnostics HTTP server listening port (default: `6062`)

## Shutter Network Default Ports

The default peering port for Shutter is `23102` (TCP), to change it use `--shutter.p2p.listen.port <value>`.

Bootstrap nodes are used to help new nodes discover other nodes in the network. By default, the embedded configuration values are used, but these can be overridden with `--shutter.p2p.bootstrap.nodes <value>`.

### Shared ports

* `--pprof.port [value]`: pprof HTTP server listening port (default: `6060`)
* `--metrics.port [value]`: Metrics HTTP server listening port (default: `6061`)
* `--downloader.api.addr [value]`: Downloader address `<host>:<port>`

---

# NAT
URL: https://docs.erigon.tech/fundamentals/nat


### What `--nat` really controls

The `--nat` option controls how Erigon advertises its external address to other peers in the Ethereum P2P network.

It does not:

* open firewall ports for you
* guarantee inbound connectivity by itself
* directly control peer count

Instead, it determines whether other nodes can initiate inbound connections to your node, which has a significant impact on:

* peer diversity (inbound vs outbound)
* transaction gossip freshness
* block content quality for validators and block producers

### Why NAT configuration matters more than peer count

Ethereum P2P is bidirectional:

* your node connects outbound to peers
* other nodes may connect inbound to you

Nodes that are reachable from the internet (i.e. correctly advertised via NAT) tend to:

* receive transactions earlier
* receive a wider variety of transactions
* maintain a healthier "pending" transaction pool

For validators and block producers, this directly affects:

* transaction inclusion
* gas usage
* likelihood of producing empty or low-gas blocks

A high peer count alone does not guarantee good transaction propagation if most peers are outbound-only.

## NAT modes explained (practical behavior)

### `nat: none`

Disables external address advertisement.

Erigon will not advertise a reachable address to peers. In practice, this often results in:

* mostly outbound connections
* few or no inbound peers
* delayed or stale transaction gossip

**Important**: `nat: none` is generally not recommended for validators or block producers, even if peer count appears high. It is primarily suitable for:

* private networks
* non-proposing archive / RPC nodes
* restricted environments where inbound connectivity is intentionally disabled

### `nat: extip:` (recommended for datacenters & VPS)

Explicitly advertises the given public IPv4 address to peers.

This is the most reliable and deterministic option when:

* your node has a stable public IPv4 address
* required P2P ports are open in the firewall

Benefits:

* enables inbound peer connections
* improves transaction gossip freshness
* leads to healthier TxPool "pending" state
* strongly recommended for validators

Example:

```yaml
nat: "extip:203.0.113.114"
```

### `nat: any`

Enables automatic NAT detection (e.g. UPnP / NAT-PMP where available).

Suitable for:

* home networks
* environments where the external IP is not known in advance

Less deterministic than extip, but generally better than none.

### `nat: stun`

Uses STUN to discover the external address.

Useful when:

* running behind NAT
* no UPnP is available
* external IP cannot be configured manually

## Caplin (consensus layer) NAT

If you are running Erigon with the embedded Caplin consensus layer, configure NAT for the CL P2P separately using `--caplin.nat`.

This flag sets the external address advertised in the **discv5 ENR** and **libp2p multiaddrs**; the socket itself still binds to `--caplin.discovery.addr`. It accepts the same values as `--nat`:

| Value | Behavior |
|-------|-----------|
| `""` (default) | No NAT mapping — CL peers cannot reach you inbound |
| `extip:1.2.3.4` | Advertise a fixed public IP — recommended for VPS / datacenters |
| `stun` | Discover external IP via STUN |
| `upnp` | Use UPnP to discover and map the port |
| `pmp` | Use NAT-PMP; optionally `pmp:192.168.0.1` to specify the gateway |

:::tip For validators running behind NAT or inside Docker
Set **both** `--nat` and `--caplin.nat` to the same external IP, otherwise your execution-layer peers and consensus-layer peers will see different (or no) reachable addresses.

```bash
--nat extip:203.0.113.114 --caplin.nat extip:203.0.113.114
```
:::

---

# Optimizing Storage
URL: https://docs.erigon.tech/fundamentals/optimizing-storage


For optimal performance, it's recommended to store the datadir on a fast NVMe-RAID disk. However, if this is not feasible, you can store the history on a cheaper disk and still achieve good performance.

### Step 1

**Store datadir on the slow disk**

Place the `datadir` on the slower disk. Then, create symbolic links (using `ln -s`) to the **fast disk** for the following sub-folders:

* `chaindata`
* `snapshots/domain`

This will speed up the execution of E3.

On the **slow disk** place `datadir` folder with the following structure:

* `chaindata` (linked to fast disk)
* `snapshots`
  * `domain` (linked to fast disk)
  * `history`
  * `idx`
  * `accessor`
* `temp`

### Step 2

**Speed Up History Access (Optional)**

If you need to further improve performance try the following improvements step by step:

1. Store the `snapshots/accessor` folder on the fast disk. This should provide a noticeable speed boost.
2. If the speed is still not satisfactory, move the `snapshots/idx` folder to the fast disk.
3. If performance is still an issue, consider moving the entire `snapshots/history` folder to the fast disk.

By following these steps, you can optimize your Erigon 3 storage setup to achieve a good balance between performance and cost.

---

# Performance Tricks
URL: https://docs.erigon.tech/fundamentals/performance-tricks


These instructions are designed to improve the performance of Erigon 3, particularly for synchronization and memory management, on cloud drives and other systems with specific performance characteristics.

## Increase Sync Speed

* Set `--sync.loop.block.limit=10_000` and `--batchSize=2g` to speed up the synchronization process.

```bash
--sync.loop.block.limit=10_000 --batchSize=2g
```

* Adjust download speed with flag `--torrent.download.rate=[value]` setting your max speed (default value is `512mb`). For example:

```bash
--torrent.download.rate=1024mb
```

## Optimize for Cloud Drives

* Set `SNAPSHOT_MADV_RND=false` to enable the operating system's cache prefetching for better performance on cloud drives with good throughput but bad latency.

```bash
SNAPSHOT_MADV_RND=false
```

## Lock Latest State in RAM

* Use `vmtouch -vdlw /mnt/erigon/snapshots/domain/*bt` to lock the latest state in RAM, preventing it from being evicted due to high historical RPC traffic.

```bash
vmtouch -vdlw /mnt/erigon/snapshots/domain/*bt
```

* Run `ls /mnt/erigon/snapshots/domain/*.kv | parallel vmtouch -vdlw` to apply the same locking to all relevant files.

## Handle Memory Allocation Issues

* If you encounter issues with memory allocation, run the following to flush any pending write operations and free up memory:

```bash
sync && sudo sysctl vm.drop_caches=3
```

* Alternatively, set:

```bash
echo 1 > /proc/sys/vm/compact_memory
```

to help with memory allocation.

---

# Multiple instances / One machine
URL: https://docs.erigon.tech/fundamentals/multiple-instances


Erigon supports running multiple instances on the same machine by configuring distinct ports and data directories for each instance. Multiple instances are fully supported but require careful configuration to avoid port conflicts and resource contention. The modular architecture allows for flexible deployment patterns, from fully integrated instances to distributed service architectures. The primary consideration is the performance impact from shared disk access, especially during initial synchronization phases.

## Required Configuration Flags

To avoid conflicts between instances, you must define **7 essential flags** for each instance:

* `--datadir` - Separate data directory for each instance
* `--port` - P2P networking port (default: `30303`)
* `--http.port` - HTTP JSON-RPC port (default: `8545`)
* `--authrpc.port` - Engine API port (default: `8551`)
* `--torrent.port` - BitTorrent protocol port (default: `42069`)
* `--private.api.addr` - Internal gRPC API address (default: `127.0.0.1:9090`)
* `--mcp.port` - MCP server port (default: `8553`), or `--mcp.disable` to turn it off

## Example Configuration

Here's how to run mainnet and sepolia instances simultaneously:

```bash
# Mainnet instance
./build/bin/erigon \
  --datadir="<your_mainnet_data_path>" \
  --chain=mainnet \
  --port=30303 \
  --http.port=8545 \
  --authrpc.port=8551 \
  --torrent.port=42069 \
  --private.api.addr=127.0.0.1:9090 \
  --mcp.port=8553 \
  --http --ws \
  --http.api=eth,debug,net,trace,web3,erigon

# Sepolia instance
./build/bin/erigon \
  --datadir="<your_sepolia_data_path>" \
  --chain=sepolia \
  --port=30304 \
  --http.port=8546 \
  --authrpc.port=8552 \
  --torrent.port=42068 \
  --private.api.addr=127.0.0.1:9091 \
  --mcp.port=8554 \
  --http --ws \
  --http.api=eth,debug,net,trace,web3,erigon
```

## Docker Compose Multi-Instance Setup

For containerized deployments, the docker-compose configuration shows how services can be orchestrated with proper port isolation:

The compose file demonstrates the port allocation strategy:

* **9090-9094**: Internal gRPC services (execution, Sentry, consensus, Downloader, TxPool)
* **8545, 8551**: External HTTP APIs
* **30303, 42069**: P2P networking ports

## Best Practices

### 1. Resource Management

**Memory Considerations:** Erigon uses memory-mapped files (MDBX) where the OS manages page cache. Multiple instances will share the same page cache efficiently, but be aware that:

* Each instance uses \~4GB RAM during genesis sync and \~1GB during normal operation
* OS page cache can utilize unlimited memory and is shared between instances
* Memory usage shown by `htop` includes OS page cache and may appear inflated

:::warning
⚠️ **Disk Performance Warning:** Multiple instances accessing the same disk concurrently will impact performance due to increased random disk access. This is particularly problematic during the "Blocks Execution stage" which performs many random reads. **Avoid running multiple genesis syncs on the same disk.**
:::

### 2. Database Configuration

For multiple instances, consider adjusting database parameters to reduce resource contention:

```bash
# Reduce memory-mapped database size limit
--db.size.limit=512MB
```

### 3. Network Port Management

**Default Port Allocation:**

| Component | Default Port | Protocol | Purpose                  |
|-----------|--------------|----------|--------------------------|
| Engine    | 9090         | TCP      | gRPC Server (Private)    |
| Engine    | 42069        | TCP/UDP  | BitTorrent (Public)      |
| Engine    | 8551         | TCP      | Engine API (Private)     |
| Sentry    | 30303/30304  | TCP/UDP  | P2P Peering (Public)     |
| RPC Daemon | 8545         | TCP      | HTTP/WebSocket (Private) |
| MCP       | 8553         | TCP      | MCP Server (Private)     |

### 4. Service Separation

Erigon supports modular deployment where components can run as separate processes:

For multiple instances, you can:

* Run each instance with integrated services (default)
* Separate heavy components like `downloader` or `rpcdaemon` to dedicated processes
* Use the `--private.api.addr` flag for inter-service communication

### 5. Monitoring and Logging

Configure separate log directories for each instance:

```bash
# Instance 1
--log.dir.path=/logs/mainnet

# Instance 2  
--log.dir.path=/logs/sepolia
```

For Prometheus monitoring, each instance should expose metrics on different ports.

## Performance Optimization

### Cloud Storage Considerations

If using network-attached storage, apply these optimizations:

```bash
# Reduce disk latency impact
export SNAPSHOT_MADV_RND=false
--db.pagesize=64kb

# For Polygon networks
--sync.loop.block.limit=10000
```

### Memory Locking for Performance

For production setups with sufficient RAM, you can lock critical data in memory:

```bash
# Lock domain snapshots in RAM
vmtouch -vdlw /mnt/erigon/snapshots/domain/*bt
ls /mnt/erigon/snapshots/domain/*.kv | parallel vmtouch -vdlw
```

```markdown
vmtouch -vdlw /mnt/erigon/snapshots/domain/*bt
ls /mnt/erigon/snapshots/domain/*.kv | parallel vmtouch -vdlw
```

If it is failing with "can't allocate memory", try:

```text
sync && sudo sysctl vm.drop_caches=3
echo 1 > /proc/sys/vm/compact_memory
```

:::warning
⚠️**Warning**: Running multiple instances of Erigon on the same machine will cause concurrent disk access, which can negatively impact performance. One of Erigon's main optimizations is to reduce disk random access, but the "Blocks Execution stage" still performs many random reads, making it the slowest stage. Therefore, **we do not recommend running multiple genesis syncs on the same disk**. However, if the genesis sync has already been completed, it is acceptable to run multiple Erigon instances on the same disk.
:::

What can be done:

* reduce disk latency (not throughput, not iops)
  * use latency-critical cloud-drives
  * or attached-NVMe (at least for initial sync)
* increase RAM
* if you throw enough RAM, then can set env variable `SNAPSHOT_MADV_RND=false`
* Use `--db.pagesize=64kb` (less fragmentation, more IO)
* Or use Erigon 3 (it also sensitive for disk-latency - but it will download 99% of history)

```yaml
# Ports: `9090` execution engine (private api), `9091` sentry, `9092` consensus engine, `9093` snapshot downloader, `9094` TxPool
# Ports: `8545` json rpc, `8551` consensus json rpc, `30303` eth p2p protocol, `42069` bittorrent protocol,

# Connections: erigon -> (sentries, downloader), rpcdaemon -> (erigon, txpool), txpool -> erigon
```

### How RAM is used

Erigon will utilize all available RAM, but this memory will not be directly owned by Erigon's process. Instead, the operating system (OS) will manage this memory. The OS will keep the frequently accessed parts of the database (DB) in RAM. If the OS needs to allocate RAM for other programs or for a second instance of Erigon, it will handle the memory management accordingly. This mechanism is known as PageCache.

Erigon itself consumes less than 2GB of RAM. Therefore, Erigon will benefit from having more RAM available, as it can use all of it without needing any reconfiguration. The same PageCache can be shared by other processes running on the same machine, simply by opening the same DB file. For example, if RPC Daemon is started with the `--datadir` option, it will open Erigon's DB and utilize the same PageCache. This means that if data A is already in RAM because it is frequently accessed and RPC Daemon reads it, it will read it from RAM rather than from the disk, leveraging shared memory.

```go
	// These are set to prevent disk and page size churn which can be excessive
	// when running multiple nodes
	// MdbxGrowthStep impacts disk usage, MdbxDBSizeLimit impacts page file usage
	n.nodeCfg.MdbxGrowthStep = 32 * datasize.MB
	n.nodeCfg.MdbxDBSizeLimit = 512 * datasize.MB
```

```yaml
      --datadir=/home/erigon/.local/share/erigon --chain=dev --private.api.addr=0.0.0.0:9090 --mine --log.dir.path=/logs/node1
    ports:
      - "8551:8551"
    volumes:
      - datadir:/home/erigon/.local/share/erigon
      - ./logdir:/logs
    user: ${DOCKER_UID}:${DOCKER_GID}
    restart: unless-stopped
    mem_swappiness: 0

  erigon-node2:
    profiles:
      - second
    image: erigontech/erigon:$ERIGON_TAG
    command: |
      --datadir=/home/erigon/.local/share/erigon --chain=dev --private.api.addr=0.0.0.0:9090 --staticpeers=$ENODE --log.dir.path=/logs/node2
```

```yaml
      - targets:
          - erigon:6060 # If Erigon runned by default docker-compose, then it's available on `erigon` host.
          - erigon:6061
          - erigon:6062
          - 46.149.164.51:6060
          - host.docker.internal:6060 # this is how docker-for-mac allow to access host machine
          - host.docker.internal:6061
          - host.docker.internal:6062
          - 192.168.255.134:6060
          - 192.168.255.134:6061
          - 192.168.255.134:6062
          - 192.168.255.138:6060
          - 192.168.255.138:6061
          - 192.168.255.138:6062
```

---

# Logs
URL: https://docs.erigon.tech/fundamentals/logs


Erigon features a sophisticated logging framework that offers detailed visibility into the synchronization process and operational status. This system provides comprehensive, structured logs suitable for both human operators and automated monitoring, while maintaining high performance.

The modular, staged approach to logging allows for granular control over verbosity, which is crucial for precise debugging and flexible deployment across various environments.

:::tip
Erigon offers a `--metrics` flag for using Prometheus/Grafana monitoring, see [Creating a Dashboard](creating-a-dashboard).
:::

## Logging Framework Architecture

### Core Logging System

Erigon implements a custom logging framework that supports structured logging with key-value pairs and multiple output handlers.

### Configuration Options

Erigon provides extensive logging configuration through command-line flags. Key configuration options include:

* `--log.json`: Enable JSON formatting for console logs
* `--verbosity`: Set console log level (default: `info`)
* `--log.dir.path`: Specify directory for log files. By default Erigon writing logs to `datadir/logs` directory.
* `--log.dir.verbosity`: Set file log level (default: `dbug`)
* `--log.delays`: Enable block delay logging

**Log Levels**

The logging system defines six distinct log levels in hierarchical order:

* **LvlCrit (0)**: Critical errors that may cause application termination
* **LvlError (1)**: Error conditions that require attention
* **LvlWarn (2)**: Warning messages for potentially problematic situations
* **LvlInfo (3)**: General informational messages
* **LvlDebug (4)**: Detailed debugging information
* **LvlTrace (5)**: Most verbose tracing information

The log level is set by using the `--verbosity` flag, for example:

```text
./build/bin/erigon --verbosity=1
```

**Logger Interface**

The core Logger interface provides methods for each log level and supports contextual logging.

## Staged Synchronization Architecture

### Stage Definitions

Erigon's synchronization process is organized into sequential stages, each handling specific aspects of blockchain data processing.

The primary synchronization stages include:

* **Snapshots (OtterSync)**: Download and process blockchain snapshots
* **Headers**: Download and validate block headers
* **BlockHashes**: Generate block number to hash mappings
* **Bodies**: Download and validate block bodies
* **Senders**: Recover transaction senders from signatures
* **Execution**: Execute transactions and update state
* **TxLookup**: Generates transaction lookup indices. This indexing is essential for quickly finding transaction by its hash, significantly improving the performance of transaction-related RPC calls.
* **Finish**: The finalization stage of the sync process. This is the point where the node sends out notifications to subscribers about the new blockchain head, ensuring other components and external applications are instantly aware of the latest block.

### Stage Progress Tracking

Each stage maintains progress information in the database, allowing for resumable synchronization.

## Log Message Structure

### Structured Logging Format

All log messages follow a consistent structured format with key-value pairs for machine parsing and human readability.

**Standard Fields:**

* Timestamp (t)
* Log level (lvl)
* Message (msg)
* Contextual key-value pairs

### Prefix System

The sync engine uses a sophisticated prefix system to identify stage context.

The prefix format includes stage position and total count (e.g., "1/10 Headers") for easy identification of sync progress.

---

# Security
URL: https://docs.erigon.tech/fundamentals/security


The security practices focus heavily on the RPC Daemon since it's the primary external interface. The modular architecture allows you to run components separately, which can improve security by isolating services. For production deployments, consider using the distributed mode where services communicate via secured gRPC rather than running everything in a single process.

## Network Security

Securing your network ports is essential for protecting your Erigon node. Proper firewall configuration is the first line of defense.

Based on best practices for execution clients, your local machine's firewall settings should be configured as follows:

| **Port** | **Protocol** | **Purpose**                   | **Firewall Action**                                                                                                                      |
| -------- | ------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 30303    | TCP & UDP    | Peer-to-Peer (P2P) Networking | Allow inbound and outbound traffic to enable peer discovery and connections.                                                             |
| 8545     | TCP          | JSON-RPC (Public API)         | Block all traffic _except_ from explicitly defined trusted machines. This port should never be publicly exposed without strict controls. |
| 9090     | TCP          | Private API Communication     | Block all traffic except for communication between your internal components (e.g., RPC Daemon and core node).                            |

#### CORS Protection

When exposing public RPC endpoints (like those on port 8545), use the following practice to mitigate cross-origin attacks:

* Avoid using a wildcard `*` for Cross-Origin Resource Sharing (CORS) domains.
* Set specific hostnames or IP addresses for CORS to ensure only authorized frontend applications can interact with your RPC service.

## API Security

The RPC Daemon is the primary external interface, making API security critical. To protect against abuse, denial-of-service (DoS) attacks, OOM issues and unauthorized access, implement the following controls:

| **Security Measure** | **Description**                                                                                                                                                                                           | **Erigon Configuration**                                                                                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Method Allowlisting  | Restrict the available RPC methods to only those strictly necessary. This significantly reduces the attack surface.Can be applied to erigon or RPC Daemon process. | Use the `--rpc.accessList=rules.json` flag, pointing to a JSON file (e.g., `rules.json`) that specifies the allowed methods: `{"allow": ["net_version", "eth_getBlockByHash"]}`      |
| Remove Admin APIs    | Never include sensitive namespaces like `admin` or `debug` in the `--http.api` list for public-facing nodes. These APIs are intended for node operators only.                                             | Omit the `admin` and `debug` namespaces from `--http.api`.                                                                                                                           |
| Rate Limiting        | Protect against DoS attacks by limiting the processing capacity for HTTP requests and batch requests.                                                                                                               | Configure `--rpc.max.concurrency` (HTTP admission control: `0` = use `--db.read.concurrency`, `-1` = unlimited), `--rpc.batch.concurrency` and `--rpc.batch.limit`. |
| Subscription Filters | Control WebSocket subscriptions to prevent Out-of-Memory (OOM) errors caused by a large number of filter requests.                                                                                        | Utilize the various --rpc.subscription.filters.* flags.Note: These are disabled by default because they increase the risk of OOM issues. |

### External Protection Layer (Recommended for Production)

For production environments where RPC endpoints are exposed publicly, it is strongly recommended to place the Erigon node behind a robust proxy layer. This layer should be responsible for:

* **Application-Level Filtering**: Implementing more granular logic than basic allowlists.
* **Rate Limiting**: Providing centralized, high-performance rate limiting.
* **TLS Termination**: Handling SSL/TLS encryption/decryption.
* **Monitoring and Logging**: Tracking requests for security auditing.
* **Web Application Firewalls (WAFs)**: Protecting against common web exploits.

## TLS and Authentication

**TLS Encryption**: For remote RPC Daemon deployments, enable TLS authentication. The process involves:

1. Generating CA key pairs
2. Creating certificates for each instance
3. Deploying certificates to secure communication

**Private API Security**: Configure secure communication between RPC Daemon and Erigon instance using TLS certificates.

## Operational Security

**Dedicated User**: Run Erigon as a dedicated system user rather than root to limit potential damage from security breaches.

**Virtual Host Protection**: Configure `HTTPVirtualHosts` to prevent DNS rebinding attacks. This validates the Host header to ensure requests come from authorized domains.

---

# JWT Secret
URL: https://docs.erigon.tech/fundamentals/jwt


The JWT secret is a key that allows Ethereum entities to securely validate JWTs used for authentication, authorization, and transmitting information, like a passphrase that allows Ethereum nodes/servers to verify if requests are legitimate. It should be protected and not exposed publicly.

JWT stands for **JSON Web Token**, and it is a way to securely transmit information between parties as a JSON object. The JWT contains a header, payload, and signature, generated by encrypting the header and payload with a secret.

In Ethereum, JWTs can be used to validate transactions or API calls. The Ethereum node or API server would have the JWT secret stored locally. When a JWT is received, the node/server uses the same secret to generate a signature from the header and payload.

If the newly generated signature matches the one in the JWT, it proves the JWT is valid and comes from an authorized source in possession of the secret. Different nodes/servers would have different secrets allowing them to verify the JWTs intended for them.

:::tip
More information available at [https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md](https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md)
:::

## Erigon JWT secret

Erigon creates automatically a JWT secret upon launch.

By default, the JWT secret key is located in the datadir as `jwt.hex`, and its path can be specified with the `--authrpc.jwtsecret` flag.

Both Erigon and any external Consensus Layer need to point to the same JWT secret file.

---

# TLS Authentication
URL: https://docs.erigon.tech/fundamentals/tls-authentication


## Introduction

TLS authentication can be enabled to ensure communication integrity and access control to the Erigon node.

At a high level, the process consists of:

1. [Generate the Certificate Authority (CA) key pair](#1-generating-the-key-pair-for-the-certificate-authority-ca)
2. [Create the Certificate Authority certificate file](#2-creating-the-ca-certificate-file)
3. [Generate a key pair](#3-generating-a-key-pair)
4. [Create the certificate file for each public key](#4-creating-the-certificate-file-for-each-public-key)
5. [Deploy the files to each instance](#5-deploy-the-files-on-each-instance)
6. [Run Erigon and RPC Daemon with the correct tags](#6-run-erigon-and-rpc-daemon-with-the-correct-tags)

The following is a detailed description of how to use the **OpenSSL** suite of tools to secure the connection between a remote Erigon node and a remote or local RPC Daemon. The same procedure applies to any Erigon component you wish to run separately; it is recommended to name the files accordingly.

:::warning
**Warning**: To maintain a high level of security, it is recommended to create all the keys locally and then copy the 3 required files remotely to the remote node.
:::

### Prerequisites

Make sure you have [openssl](https://openssl-library.org/source/) installed.

### Notes

Normally, the "client side" (in our case, the RPC Daemon) will check that the server's host name matches the "Common Name" attribute of the "server" certificate. At this time, this check is disabled and will be re-enabled when the instructions above on how to correctly generate Common Name certificates are updated. For example, if you are running the Erigon instance in the Google Cloud, you will need to specify the internal IP in the `-private.api.addr` option. You will also need to open the firewall on the port you use to connect to the Erigon instances.

## 1. Generating the key pair for the Certificate Authority (CA)

Generate the CA key pair using Elliptic Curve (as opposed to RSA). The generated CA key will be in the `CA-key.pem` file.

:::warning
**Warning**: Access to this file will allow anyone to later add any new instance key pair to the “cluster of trust”, so keep this file safe.
:::

```bash
openssl ecparam -name prime256v1 -genkey -noout -out CA-key.pem
```

## 2. Creating the CA certificate file

Create CA self-signed certificate (this command will ask questions, the answers aren’t important for now, but at least the first one needs to be filled in with some data). The file created by this command will be called `CA-cert.pem`:

```bash
openssl req -x509 -new -nodes -key CA-key.pem -sha256 -days 3650 -out CA-cert.pem
```

## 3. Generating a key pair

Generate a key pair for the Erigon node:

```bash
openssl ecparam -name prime256v1 -genkey -noout -out erigon-key.pem
```

Also generate a key pair for the RPC Daemon:

```bash
openssl ecparam -name prime256v1 -genkey -noout -out RPC-key.pem
```

## 4. Creating the certificate file for each public key

Now create the Certificate Signing Request for the Erigon key pair, and from this request, produce the certificate (signed by the CA) that proves that this key is now part of the “cluster of trust”:

```bash
openssl x509 -req -in erigon.csr -CA CA-cert.pem -CAkey CA-key.pem -CAcreateserial -out erigon.crt -days 3650 -sha256
```

Then create the certificate signing request for the RPC Daemon key pair:

```bash
openssl req -new -key RPC-key.pem -out RPC.csr
```

From this request, produce the certificate (signed by CA), proving that this key is now part of the “cluster of trust”:

```bash
openssl x509 -req -in RPC.csr -CA CA-cert.pem -CAkey CA-key.pem -CAcreateserial -out RPC.crt -days 3650 -sha256
```

## 5. Deploy the files on each instance

These three files must be placed in the /erigon folder on the machine running Erigon:

`CA-cert.pem`

`erigon-key.pem`

`erigon.crt`

On the RPC Daemon machine, these three files must also be placed in the /erigon folder:

`CA-cert.pem`

`RPC-key.pem`

`RPC.crt`

## 6. Run Erigon and RPC Daemon with the correct tags

Once all the files have been moved, Erigon must be run with these additional options:

```bash
--tls --tls.cacert CA-cert.pem --tls.key erigon-key.pem --tls.cert erigon.crt
```

While the RPC Daemon must be started with these additional options:

```bash
--tls.key RPC-key.pem --tls.cacert CA-cert.pem --tls.cert RPC.crt
```

---

# MCP Server
URL: https://docs.erigon.tech/fundamentals/mcp


The **Model Context Protocol (MCP)** is an open standard developed by Anthropic that allows AI assistants (such as Claude Desktop) to securely connect to external data sources and tools. MCP defines a uniform interface through which an AI model can discover, read, and invoke capabilities provided by a server — without needing any custom integration code.

Erigon ships a full MCP server implementation. Once connected, an AI assistant gains structured, read-only access to Ethereum blockchain data, Erigon logs, and internal metrics — turning natural-language questions into precise on-chain lookups.

:::tip
MCP is a read-only interface: the server exposes query tools only. No write operations (sending transactions, changing state) are available.
:::

## Two Server Variants

Erigon provides two ways to run the MCP server:

### Embedded (inside Erigon)

The MCP server runs inside the main `erigon` process, with direct access to internal APIs and Prometheus metrics. It is
**enabled by default** on `127.0.0.1:8553`:

```bash
# MCP server starts automatically on 127.0.0.1:8553
./build/bin/erigon --datadir=./data
```

To disable the embedded MCP server entirely, pass `--mcp.disable`:

```bash
./build/bin/erigon --datadir=./data --mcp.disable
```

This mode uses **SSE (Server-Sent Events)** transport over HTTP and is the simplest option when you are already running a full Erigon node.

### Standalone (`mcp` binary)

A separate `mcp` binary that connects to an existing Erigon node either via its JSON-RPC endpoint or directly via the MDBX database. Supports both **stdio** (for Claude Desktop) and **SSE** transports.

```bash
make mcp
./build/bin/mcp --help
```

## Configuration

### Flags (embedded mode)

| Flag            | Default     | Description                                   |
|-----------------|-------------|-----------------------------------------------|
| `--mcp.disable` | `false`     | Disable the embedded MCP server entirely      |
| `--mcp.addr`    | `127.0.0.1` | Listening address for the embedded MCP server |
| `--mcp.port`    | `8553`      | Listening port for the embedded MCP server    |

:::info
The embedded MCP server is **enabled by default** and listens on `127.0.0.1:8553`. Because it binds to localhost only,
it is not reachable from external networks. If you do not need AI-assistant integration, pass `--mcp.disable` to avoid
opening the port. If you are running multiple Erigon instances on the same machine, assign distinct ports with
`--mcp.port` to avoid conflicts.
:::

### Flags (standalone `mcp` binary)

| Flag | Default | Description |
|------|---------|-------------|
| `--rpc.url` | `http://127.0.0.1:8545` | Erigon JSON-RPC endpoint to proxy |
| `--port` | — | Shorthand for `--rpc.url http://127.0.0.1:<port>` |
| `--datadir` | — | Erigon data directory (enables direct DB access mode) |
| `--private.api.addr` | `127.0.0.1:9090` | gRPC private API address (used with `--datadir`) |
| `--transport` | `stdio` | Transport type: `stdio` or `sse` |
| `--sse.addr` | `127.0.0.1:8553` | SSE listen address (when `--transport sse`) |
| `--log.dir` | — | Path to Erigon log directory (enables log analysis tools) |

## Connection Modes (standalone)

The standalone `mcp` binary supports three connection modes, tried in priority order:

### 1. JSON-RPC Proxy (recommended)

Forwards tool calls to a running Erigon node's HTTP JSON-RPC endpoint. Works with any Erigon instance that has the RPC server enabled.

```bash
# Explicit URL
./build/bin/mcp --rpc.url http://127.0.0.1:8545

# Port shorthand
./build/bin/mcp --port 8545

# With log analysis enabled
./build/bin/mcp --port 8545 --log.dir /data/erigon/logs
```

### 2. Direct Datadir Access

Opens Erigon's MDBX database directly — similar to an external `rpcdaemon`. Requires either a running Erigon instance with the gRPC private API, or read-only local disk access.

```bash
# gRPC + direct DB
./build/bin/mcp --datadir /data/erigon --private.api.addr 127.0.0.1:9090

# Default private.api.addr (127.0.0.1:9090)
./build/bin/mcp --datadir /data/erigon
```

### 3. Auto-Discovery

When started without flags, the binary probes `localhost:8545`, `8546`, and `8547` for a running JSON-RPC endpoint:

```bash
./build/bin/mcp
```

## Use Cases

### Interactive Blockchain Analysis

Connect your AI assistant to a running Erigon node and ask natural-language questions about on-chain data without writing a single line of code.

> **"What is the ETH balance of vitalik.eth right now, and how many transactions has it sent?"**
>
> The assistant calls `eth_getBalance` and `eth_getTransactionCount` on the address, formats the results in human-readable form, and summarises the answer.

> **"Show me all ERC-20 Transfer events emitted in the last 100 blocks from contract 0xA0b…"**
>
> The assistant calls `eth_getLogs` with the appropriate filter, decodes the ABI-encoded topics, and presents a table of transfers with amounts and counterparties.

> **"Which transactions in block 21,000,000 consumed the most gas?"**
>
> The assistant calls `eth_getBlockByNumber` and `eth_getBlockReceipts`, sorts by gas used, and returns the top offenders with links to the relevant hashes.

### Node Debugging and Monitoring

When something looks wrong with your node, ask the assistant to sift through logs and metrics for you.

> **"My node seems stuck. Check the sync status and the last 50 log lines for any errors."**
>
> The assistant calls `eth_syncing` to get the current sync progress, then uses `logs_tail` and `logs_grep` to search for `ERROR` or `WARN` entries — surfacing actionable information without requiring you to SSH into the server.

> **"Are there any unusual patterns in the torrent download stats over the last hour?"**
>
> Using the `torrent_status` prompt and `logs_stats`, the assistant analyses download throughput, stall events, and peer connectivity in a single conversational turn.

## Setting Up with Claude Desktop

Add the following to your Claude Desktop configuration file (`~/.config/claude-desktop/config.json` on Linux/macOS, `%APPDATA%\claude-desktop\config.json` on Windows):

```json
{
  "mcpServers": {
    "erigon": {
      "command": "/path/to/build/bin/mcp",
      "args": ["--port", "8545", "--log.dir", "/data/erigon/logs"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "erigon": {
      "command": "/path/to/build/bin/mcp",
      "args": ["--datadir", "/data/erigon"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "erigon": {
      "type": "sse",
      "url": "http://127.0.0.1:8553/sse"
    }
  }
}
```

The embedded MCP server starts by default on `127.0.0.1:8553`. To use a different address or port, pass `--mcp.addr` and
`--mcp.port`. To disable it, pass `--mcp.disable`.

After saving, restart Claude Desktop. The Erigon tools will appear in the tool panel under **erigon**.

## Setting Up with Claude Code

[Claude Code](https://claude.ai/code) is Anthropic's CLI coding agent. Register the Erigon MCP server with a single command — no config file editing required.

**Embedded SSE mode (recommended — zero extra binaries):**

```bash
claude mcp add --transport sse erigon http://127.0.0.1:8553/sse
```

**Standalone stdio mode:**

```bash
claude mcp add erigon /path/to/build/bin/mcp -- --port 8545
```

Verify the server is registered:

```bash
claude mcp list
```

Once added, Claude Code discovers the Erigon tools automatically at the start of every session. You can then ask natural-language questions about your node inline while coding — for example: *"What is the current block number?"* or *"Show sync status"* — and Claude will call the appropriate tool against your local node.

To remove the server:

```bash
claude mcp remove erigon
```

## Setting Up with OpenAI Codex

[OpenAI Codex CLI](https://github.com/openai/codex) supports MCP servers via `~/.codex/config.yaml`. Add the `mcp_servers` key to your existing config file:

```yaml
mcp_servers:
  erigon:
    type: sse
    url: http://127.0.0.1:8553/sse
```

```yaml
mcp_servers:
  erigon:
    command: /path/to/build/bin/mcp
    args:
      - --port
      - "8545"
```

Save the file and start a new Codex session. The Erigon tools are loaded automatically — you can query your node in natural language alongside any coding task.

:::tip
The embedded SSE mode (`http://127.0.0.1:8553/sse`) works out of the box as long as Erigon is running. No separate binary is needed.
:::

## Available Tools

The MCP server exposes over 40 tools grouped by namespace:

### Ethereum Standard (`eth_*`)

Standard JSON-RPC methods exposed as MCP tools: `eth_blockNumber`, `eth_getBlockByNumber`, `eth_getBlockByHash`, `eth_getBalance`, `eth_getTransactionByHash`, `eth_getTransactionReceipt`, `eth_getBlockReceipts`, `eth_getLogs`, `eth_getCode`, `eth_getStorageAt`, `eth_getTransactionCount`, `eth_call`, `eth_estimateGas`, `eth_gasPrice`, `eth_chainId`, `eth_syncing`, `eth_getProof`, and more.

### Erigon-Specific (`erigon_*`)

`erigon_nodeInfo`, `erigon_forks`, `erigon_getBlockByTimestamp`, `erigon_getBalanceChangesInBlock`, `erigon_getLogsByHash`, `erigon_getBlockReceiptsByBlockHash`, and more.

### Otterscan (`ots_*`)

`ots_getInternalOperations`, `ots_searchTransactionsBefore`, `ots_searchTransactionsAfter`, `ots_getBlockDetails`, `ots_traceTransaction`, `ots_getTransactionError`, `ots_getContractCreator`, and more.

### Log Analysis (`logs_*`)

`logs_tail`, `logs_head`, `logs_grep`, `logs_stats` — require `--log.dir` or `--datadir` to locate Erigon log files.

### Metrics (`metrics_*`)

`metrics_list`, `metrics_get` — available in **embedded mode only**. In standalone mode these return a descriptive message.

## Resources and Prompts

In addition to tools, the MCP server exposes structured **resources** and **prompts**:

**Resources** (addressable by URI):

| Resource | Description |
|----------|-------------|
| `erigon://node/info` | Node version, chain, capabilities |
| `erigon://chain/config` | Full chain configuration |
| `erigon://blocks/recent` | Last 10 blocks summary |
| `erigon://network/status` | Sync state and peer count |
| `erigon://gas/current` | Current gas price |
| `erigon://address/{address}/summary` | Balance, nonce, contract status |
| `erigon://block/{number}/summary` | Block summary |
| `erigon://transaction/{hash}/analysis` | Transaction analysis |

**Prompts** (pre-built analysis templates):

| Prompt | Description |
|--------|-------------|
| `analyze_transaction` | Deep-dive into a transaction |
| `investigate_address` | Profile an address (balance, history, code) |
| `analyze_block` | Summarise a block and its transactions |
| `gas_analysis` | Current and historical gas price analysis |
| `debug_logs` | Triage node issues from recent log output |
| `torrent_status` | Snapshot download health check |
| `sync_analysis` | Node sync progress and performance |

---

# Otterscan
URL: https://docs.erigon.tech/fundamentals/otterscan


Otterscan is an Ethereum block explorer designed to be run locally along with Erigon.

Entirely based on open source code, it is fast and fully private since it works on your local machine. The user interface is intentionally very similar, but with many improvements, to the most popular Ethereum block explorer to make it easy to locate where the information is. Installation and usage instructions

For the installation and usage follow the official documentation at [https://docs.otterscan.io/](https://docs.otterscan.io/).

---

# Creating a dashboard
URL: https://docs.erigon.tech/fundamentals/creating-a-dashboard


Erigon provides robust, built-in support for monitoring using the Prometheus and Grafana stack. This setup offers comprehensive visibility into node performance, storage usage, and network activity, including relevant metrics for the integrated Consensus Layer (Caplin).

#### Prerequisites

* Docker and Docker Compose installed
* Erigon node running
* Basic understanding of Prometheus and Grafana

#### Step 1: Enable Metrics in Erigon

You must first enable metrics collection in your running Erigon instance.

```sh
./erigon --metrics --datadir=/your/data/dir
```

To specify a custom address and port for metrics, use the `--metrics.addr` and `--metrics.port` flags (default port: `6061`).

#### Step 2: Configure Prometheus Targets

The Erigon codebase includes a default configuration file for Prometheus.

1. Copy the default configuration: `./cmd/prometheus/prometheus.yml`
2. Edit the file to include the endpoints of your running Erigon instance(s).
3. Save the modified configuration file.

#### Step 3: Launch Monitoring Stack

Erigon provides a simple Docker Compose setup to launch the monitoring services.

```sh
docker compose up -d prometheus grafana
```

Alternatively, use the built-in `make` target:

```sh
make prometheus
```

#### Step 4: Access Grafana Dashboard

Once the containers are running, access the Grafana interface at `localhost:3000`.

* Default credentials: `admin/admin`

#### Step 5: Utilize Pre-configured Dashboards

Erigon comes with pre-built dashboards located in `./cmd/prometheus/dashboards/`. See `./cmd/prometheus/Readme.md` for details.

**`erigon.json`** is the recommended dashboard for most users. It contains the following sections:

* **Blockchain**: Block execution speed and processing times.
* **Block consume delay**: Latency between block production and consumption.
* **RPC**: Request rates and response times for the JSON-RPC interface.
* **Private api** (collapsed): Internal gRPC API metrics.

**`erigon_internals.json`** is a low-level dashboard used by the Erigon development team for deep internal debugging. It is exported from Erigon's own Grafana Cloud instance and requires a pre-release Grafana build — it is _not recommended_ for typical users or self-hosted setups.

#### Step 6: Memory Usage Monitoring (Important Note)

Standard OS tools like `htop` can be misleading for Erigon's memory usage because its database (MDBX) uses `MemoryMap`. The OS manages the OS Page Cache, which is shared and automatically freed when needed.

The dedicated panels in the `erigon.json` dashboard track accurate Go memory statistics. Erigon's application typically uses around 1GB during normal operation, while the OS Page Cache handles the bulk of data access memory efficiently.

#### Step 7: Environment and Custom Configuration

You can customize the setup using environment variables:

| **Variable**               | **Description**                           |
| -------------------------- | ----------------------------------------- |
| `XDG_DATA_HOME`            | Changes default database folder location.  |
| `ERIGON_PROMETHEUS_CONFIG` | Path to a custom `prometheus.yml` file.    |
| `ERIGON_GRAFANA_CONFIG`    | Path to a custom `grafana.ini` file.       |
| `ERIGON_GRAFANA_DASHBOARD` | Path to a custom dashboards directory.     |

Example with a Custom Prometheus Configuration:

```sh
ERIGON_PROMETHEUS_CONFIG=/path/to/custom/prometheus.yml docker compose up prometheus grafana
```

#### Troubleshooting

* Ensure Erigon is running with the `--metrics` flag enabled.
* Verify Prometheus can reach your Erigon metrics endpoint (default port: `6061`).
* Check Docker container logs if services fail to start.
* Confirm firewall settings allow access to monitoring ports.

#### For Developers

Custom metrics can be added by searching for `grpc_prometheus.Register` within the codebase.

---

# Docker Compose
URL: https://docs.erigon.tech/fundamentals/docker-compose


#### Understanding File Permissions

When Erigon runs inside a Docker container and creates files (like its data directory), those files need to be accessible to your local user account on your host machine.

The potential issue is that Docker often creates these files with a default User ID (UID) of `1000`. If this doesn't match your host machine's UID, you may run into permission issues when trying to access, modify, or delete the data directory from your host machine.

#### The Solution: Using Your Host UID

To prevent these problems, you can run the Docker container using your local operating system's User ID (UID).

Running the container with your host machine's UID ensures that any files created or modified by Erigon inside the container will be owned by that specific user ID on the host operating system. This synchronization of permissions makes managing the data directory much easier.

If you are encountering permission issues, you can find your user ID using this command:

```bash
id -u
```

#### Example Run

To use a specific UID, like `1205`, and mount a host data directory (`/erigon-data`) into the container, use the `--user` flag:

```sh
docker run \
--user 1205 \
-v /erigon-data:/container-erigon-data \
-it erigontech/erigon:<version_tag> \
--chain=hoodi \
--prune.mode=minimal \
--datadir /container-erigon-data
```

In this example, the Erigon process inside the container will run as user `1205` and the contents of the host directory `/erigon-data` will be written and owned by user `1205` on your host OS.

### Environment Variables

There is a `.env.example` file in the root of the repo.

Copy

```text
* DOCKER_UID - The UID of the docker user

* DOCKER_GID - The GID of the docker user

* XDG_DATA_HOME - The data directory which will be mounted to the docker containers
```

If not specified, the UID/GID will use the current user.

A good choice for `XDG_DATA_HOME` is to use the `~erigon/.ethereum` directory created by helper targets `make user_linux` or `make user_macos`.

#### Check: Permissions

In all cases, `XDG_DATA_HOME` (specified or default) must be writeable by the user UID/GID in Docker, which will be determined by the `DOCKER_UID` and `DOCKER_GID` at build time.

If a build or service startup is failing due to permissions, check that all the directories, UID, and GID controlled by these environment variables are correct.

#### Run

Next command starts: `erigon` on port `30303`, `rpcdaemon` on port `8545`, `prometheus` on port `9090`, and `grafana` on port `3000`:

```bash
#
# Will mount ~/.local/share/erigon to /home/erigon/.local/share/erigon inside container
#
make docker-compose
#
# or
#
# if you want to use a custom data directory
# or, if you want to use different uid/gid for a dedicated user
#
# To solve this, pass in the uid/gid parameters into the container.
#
# DOCKER_UID: the user id
# DOCKER_GID: the group id
# XDG_DATA_HOME: the data directory (default: ~/.local/share)
#
# Note: /preferred/data/folder must be read/writeable on host OS by user with UID/GID given
#       if you followed above instructions
#
# Note: uid/gid syntax below will automatically use uid/gid of running user so this syntax
#       is intended to be run via the dedicated user setup earlier
#
DOCKER_UID=$(id -u) DOCKER_GID=$(id -g) XDG_DATA_HOME=/preferred/data/folder DOCKER_BUILDKIT=1 COMPOSE_DOCKER_CLI_BUILD=1 make docker-compose
#
# if you want to run the docker, but you are not logged in as the $ERIGON_USER
# then you'll need to adjust the syntax above to grab the correct uid/gid
#
# To run the command via another user, use
#
ERIGON_USER=erigon
sudo -u ${ERIGON_USER} DOCKER_UID=$(id -u ${ERIGON_USER}) DOCKER_GID=$(id -g ${ERIGON_USER}) XDG_DATA_HOME=~${ERIGON_USER}/.ethereum DOCKER_BUILDKIT=1 COMPOSE_DOCKER_CLI_BUILD=1 make docker-compose
```

`Makefile` creates the initial directories for `erigon`, `prometheus` and `grafana`. The PID namespace is shared between Erigon and RPC Daemon which is required to open Erigon's DB from another process (RPC Daemon local-mode). See: [https://github.com/erigontech/erigon/pull/2392/files](https://github.com/erigontech/erigon/pull/2392/files)

If your Docker installation requires the Docker daemon to run as root (which is by default), you will need to prefix the command above with `sudo`. However, it is sometimes recommended running Docker (and therefore its containers) as a non-root user for security reasons. For more information about how to do this, refer to this [article](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).

---

# web3 Wallet
URL: https://docs.erigon.tech/fundamentals/web3-wallet


Whatever network you are running, it's easy to connect your Erigon node to your local web3 wallet.

For Erigon to provide access to wallet functionalities it is necessary to enable RPC by adding the flags

```bash
--http.addr="0.0.0.0" --http.api=eth,web3,net,debug,trace,txpool
```

For example:

```bash
/build/bin/erigon --http.addr="0.0.0.0" --http.api=eth,web3,net,debug,trace,txpool
```

## Metamask

To configure your local Metamask wallet (browser extension):

* Click on the **network selector button**. This will display a list of networks to which you're already connected
* Click **Add network**
* A new browser tab will open, displaying various fields to fill out. Complete the fields with the proper information, in this example for Ethereum network:
  * **Network Name**: `Ethereum on E3` (or any name of your choice)
  * **Chain ID**: `1` for chain ID parameter see [Supported Networks](supported-networks)
  * **New RPC URL**: `http://127.0.0.1:8545`
  * **Currency Symbol**: `ETH`
  * **Block Explorer URL**: `https://www.etherscan.io` (or any explorer of your choice)

After performing the above steps, you will be able to see the custom network the next time you access the network selector.

---

# Modules
URL: https://docs.erigon.tech/fundamentals/modules

Erigon's internal components can run as separate processes for scalability, security, or custom deployments. Only split them when you have a clear reason to.

## Sections

- [RPC Daemon](https://docs.erigon.tech/fundamentals/modules/rpc-daemon): Serve JSON-RPC requests as a separate, remoteable process — the most battle-tested external component.
- [TxPool](https://docs.erigon.tech/fundamentals/modules/txpool): Manage the pending transaction pool as a standalone service, decoupled from the main node process.
- [Sentry](https://docs.erigon.tech/fundamentals/modules/sentry): Erigon's network-facing peer-to-peer communication layer, isolatable for security or multi-node setups.
- [Downloader](https://docs.erigon.tech/fundamentals/modules/downloader): Fetch and verify Erigon snapshots from the BitTorrent network — handles historical data retrieval.

---

# RPC Daemon
URL: https://docs.erigon.tech/fundamentals/modules/rpc-daemon


The RPC Daemon is a core component of Erigon that implements the [RPC Service](../../interacting-with-erigon/) by processing JSON remote procedure calls (RPCs). It can be deployed in-process (running inside Erigon) or out-of-process (as a standalone service).

### RPC Deployment Modes

The Erigon RPC service offers three distinct deployment modes when it comes to the logical functionality, depending on whether it runs as part of the main `erigon` process or as a standalone `rpcdaemon` process.

| Mode | Configuration | CLI Command to Run | Key Characteristics |
| --- | --- | --- | --- |
| Embedded | RPC server is hosted within the `erigon` process. | `./build/bin/erigon` | The simplest, all-in-one solution. No separate RPC command is needed. |
| Local | `rpcdaemon` runs as a standalone process on the same machine as `erigon`. It directly accesses local data storage. | **Erigon:** `./build/bin/erigon --private.api.addr="<host_IP>:9090"`**rpcdaemon:** `./build/bin/rpcdaemon --datadir="<erigon_data_path>"` | Improves isolation, increases tuning options, and maintains high-performance data access. Requires two processes running on the same machine. |
| Remote | `rpcdaemon` runs as a standalone process on a separate machine and accesses data storage remotely via the Erigon gRPC interface. | **Erigon:** `./build/bin/erigon --private.api.addr="<host_IP>:9090"`**rpcdaemon:** `./build/bin/rpcdaemon --private.api.addr="<erigon_IP>:9090"` | Scalable, leverages the same data storage for multiple service endpoints. Uses `--private.api.addr` to point the daemon to the remote Erigon instance. |

For a comprehensive understanding and the latest instructions, the official documentation is essential:

* **Detailed Functionality and Configuration**: The primary documentation for the `rpcdaemon` is located at [https://github.com/erigontech/erigon/blob/main/cmd/rpcdaemon/README.md](https://github.com/erigontech/erigon/blob/main/cmd/rpcdaemon/README.md).
* **Local Access**: This documentation is also contained in your locally compiled Erigon folder at `/cmd/rpcdaemon`.
* **Remote Running Instructions**: For detailed instructions on running RPC in Remote mode, refer to the documentation [here](https://github.com/erigontech/erigon/blob/main/cmd/rpcdaemon/README.md#running-remotely).

:::tip
To interact with the **RPC Service** visit the dedicated page [Interacting with Erigon](../../interacting-with-erigon/).
:::

## Command Line Options

When running RPC Daemon in Local or Remote deployment mode, use this command to display available options:

```bash
./build/bin/rpcdaemon --help
```

The `--help` flag listing is reproduced below for your convenience.

```text
rpcdaemon is JSON RPC server that connects to Erigon node for remote DB access

Usage:
  rpcdaemon [flags]

Flags:
      --datadir string                              path to Erigon working directory
      --db.read.concurrency int                     Does limit amount of parallel db reads. Default: equal to GOMAXPROCS (or number of CPU) (default 1408)
      --diagnostics.disabled                        Disable diagnostics
      --diagnostics.endpoint.addr string            Diagnostics HTTP server listening interface (default "127.0.0.1")
      --diagnostics.endpoint.port uint              Diagnostics HTTP server listening port (default 6062)
      --diagnostics.speedtest                       Enable speed test
      --graphql                                     enables graphql endpoint (disabled by default)
      --grpc                                        Enable GRPC server
      --grpc.addr string                            GRPC server listening interface (default "localhost")
      --grpc.healthcheck                            Enable GRPC health check
      --grpc.port int                               GRPC server listening port (default 8547)
  -h, --help                                        help for rpcdaemon
      --http.addr string                            HTTP server listening interface (default "localhost")
      --http.api strings                            API's offered over the RPC interface: eth,erigon,web3,net,debug,trace,txpool,db. Supported methods: https://github.com/erigontech/erigon/tree/main/cmd/rpcdaemon (default [eth,erigon])
      --http.compression                            Disable http compression (default true)
      --http.corsdomain strings                     Comma separated list of domains from which to accept cross origin requests (browser enforced)
      --http.dbg.single                             Allow pass HTTP header 'dbg: true' to printt more detailed logs - how this request was executed
      --http.enabled                                enable http server (default true)
      --http.port int                               HTTP server listening port (default 8545)
      --http.timeouts.idle duration                 Maximum amount of time to wait for the next request when keep-alives are enabled. If http.timeouts.idle is zero, the value of http.timeouts.read is used (default 2m0s)
      --http.timeouts.read duration                 Maximum duration for reading the entire request, including the body. (default 30s)
      --http.timeouts.write duration                Maximum duration before timing out writes of the response. It is reset whenever a new request's header is read (default 30m0s)
      --http.trace                                  Trace HTTP requests with INFO level
      --http.url string                             HTTP server listening url. will OVERRIDE http.addr and http.port. will NOT respect http paths. prefix supported are tcp, unix
      --http.vhosts strings                         Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default [localhost])
      --https.addr string                           rpc HTTPS server listening interface (default "localhost")
      --https.cert string                           certificate for rpc HTTPS server
      --https.enabled                               enable http server
      --https.key string                            key file for rpc HTTPS server
      --https.port int                              rpc HTTPS server listening port. default to http+363 if not set
      --https.url string                            rpc HTTPS server listening url. will OVERRIDE https.addr and https.port. will NOT respect paths. prefix supported are tcp, unix
      --log.console.json                            Format console logs with JSON
      --log.console.verbosity string                Set the log level for console logs (default "info")
      --log.delays                                  Enable block delay logging
      --log.dir.disable                             disable disk logging
      --log.dir.json                                Format file logs with JSON
      --log.dir.path string                         Path to store user and error logs to disk
      --log.dir.prefix string                       The file name prefix for logs stored to disk
      --log.dir.verbosity string                    Set the log verbosity for logs stored to disk (default "info")
      --log.json                                    Format console logs with JSON
      --metrics                                     Enable metrics collection and reporting
      --metrics.addr string                         Enable stand-alone metrics HTTP server listening interface (default "127.0.0.1")
      --metrics.port int                            Metrics HTTP server listening port (default 6061)
      --ots.search.max.pagesize uint                Max allowed page size for search methods (default 25)
      --polygon.sync                                Enable if Erigon has been synced using the new polygon sync component
      --pprof                                       Enable the pprof HTTP server
      --pprof.addr string                           pprof HTTP server listening interface (default "127.0.0.1")
      --pprof.cpuprofile string                     Write CPU profile to the given file
      --pprof.port int                              pprof HTTP server listening port (default 6060)
      --private.api.addr string                     Erigon's components (txpool, rpcdaemon, sentry, downloader, ...) can be deployed as independent Processes on same/another server. Then components will connect to erigon by this internal grpc API. Example: 127.0.0.1:9090 (default "127.0.0.1:9090")
      --rpc.accessList string                       Specify granular (method-by-method) API allowlist
      --rpc.allow-unprotected-txs                   Allow for unprotected (non-EIP155 signed) transactions to be submitted via RPC
      --rpc.batch.concurrency uint                  Does limit amount of goroutines to process 1 batch request. Means 1 bach request can't overload server. 1 batch still can have unlimited amount of request (default 2)
      --rpc.batch.limit int                         Maximum number of requests in a batch (default 100)
      --rpc.evmtimeout duration                     Maximum amount of time to wait for the answer from EVM call. (default 5m0s)
      --rpc.gascap uint                             Sets a cap on gas that can be used in eth_call/estimateGas (default 50000000)
      --rpc.maxgetproofrewindblockcount.limit int   Max GetProof rewind block count (default 100000)
      --rpc.overlay.getlogstimeout duration         Maximum amount of time to wait for the answer from the overlay_getLogs call. (default 5m0s)
      --rpc.overlay.replayblocktimeout duration     Maximum amount of time to wait for the answer to replay a single block when called from an overlay_getLogs call. (default 10s)
      --rpc.returndata.limit int                    Maximum number of bytes returned from eth_call or similar invocations (default 100000)
      --rpc.slow duration                           Print in logs RPC requests slower than given threshold: 100ms, 1s, 1m. Excluded methods: eth_getBlock,eth_getBlockByNumber,eth_getBlockByHash,eth_blockNumber,erigon_blockNumber,erigon_getHeaderByNumber,erigon_getHeaderByHash,erigon_getBlockByTimestamp,eth_call
      --rpc.streaming.disable                       Erigon has enabled json streaming for some heavy endpoints (like trace_*). It's a trade-off: greatly reduce amount of RAM (in some cases from 30GB to 30mb), but it produce invalid json format if error happened in the middle of streaming (because json is not streaming-friendly format)
      --rpc.subscription.filters.maxaddresses int   Maximum number of addresses per subscription to filter logs by.
      --rpc.subscription.filters.maxheaders int     Maximum number of block headers to store per subscription.
      --rpc.subscription.filters.maxlogs int        Maximum number of logs to store per subscription.
      --rpc.subscription.filters.maxtopics int      Maximum number of topics per subscription to filter logs by.
      --rpc.subscription.filters.maxtxs int         Maximum number of transactions to store per subscription.
      --rpc.txfeecap float                          Sets a cap on transaction fee (in ether) that can be sent via the RPC APIs (0 = no cap) (default 1)
      --socket.enabled                              Enable IPC server
      --socket.url string                           IPC server listening url. prefix supported are tcp, unix (default "unix:///var/run/erigon.sock")
      --state.cache string                          Amount of data to store in StateCache (enabled if no --datadir set). Set 0 to disable StateCache. Defaults to 0MB RAM (default "0MB")
      --tls.cacert string                           CA certificate for client side TLS handshake for GRPC
      --tls.cert string                             certificate for client side TLS handshake for GRPC
      --tls.key string                              key file for client side TLS handshake for GRPC
      --trace string                                Write execution trace to the given file
      --trace.compat                                Bug for bug compatibility with OE for trace_ routines
      --trace.maxtraces uint                        Sets a limit on traces that can be returned in trace_filter (default 200)
      --txpool.api.addr string                      txpool api network address, for example: 127.0.0.1:9090 (default: use value of --private.api.addr)
      --verbosity string                            Set the log level for console logs (default "info")
      --ws                                          Enable Websockets - Same port as HTTP[S]
      --ws.api.subscribelogs.channelsize int        Size of the channel used for websocket logs subscriptions (default 8192)
      --ws.compression                              Enable Websocket compression (RFC 7692)
```

---

# TxPool
URL: https://docs.erigon.tech/fundamentals/modules/txpool


The transaction pool, also known as the mempool, is a dynamic storage area where pending transactions are held before being confirmed and added to the blockchain. Each node on the Ethereum network maintains its own local transaction pool, which is combined with others to form the global pool.

In Erigon, the TxPool is a dedicated API namespace that stores pending and queued transactions in local memory. Its primary function is to manage transactions waiting to be processed by miners.

The TxPool component is typically run as an internal Erigon component, but it can also be operated as a separate process, providing flexibility in transaction management.

## TxPool as an internal Erigon component

TxPool is run as an internal Erigon component by default.

## TxPool as a separate process (experimental)

Running an external TxPool can provide a more secure, scalable, and flexible transaction management solution, which can be particularly beneficial in high-performance or high-availability Ethereum node deployments.

1. Before TxPool can be using as a separate process the executable must be built:

```bash
cd erigon
make txpool
```

2. Together with external TxPool also [Sentry](sentry) and [RPC Daemon](rpc-daemon) must be compiled and run separately.

```bash
make sentry
```

```bash
make rpcdaemon
```

3. Now Erigon and other services can be started as separate processes

```sh
./build/bin/erigon --txpool.disable --private.api.addr=localhost:9090 --datadir=<your datadir> --http=false
```

If Erigon is on a different device, add the flags `--pprof --pprof.addr 0.0.0.0` or TxPool will listen on localhost by default.

```sh
./build/bin/sentry --sentry.api.addr=localhost:9091 --datadir=<your datadir>
```

```sh
./build/bin/txpool --private.api.addr=localhost:9090 --sentry.api.addr=localhost:9091 --txpool.api.addr=localhost:9094 --datadir=<your datadir>
```

```sh
./build/bin/rpcdaemon --private.api.addr=localhost:9090 --datadir=<your datadir> --txpool.api.addr=localhost:9094
```

## Flags explanation

* `--txpool.disable`: This flag disables the internal transaction pool (TxPool) and block producer (default: `false`). When running the TxPool as a separate process, this flag is used to prevent the internal TxPool from interfering with the external one.
* `--private.api.addr=localhost:9090`: This flag sets the address and port for the private API. The private API is used for internal communication between Erigon components (default: `127.0.0.1:9090`).
* `--datadir=<your datadir>`: This flag specifies the data directory for Erigon. This is where Erigon stores its databases and other data.
* `--http=false`: This flag disables the HTTP API server in Erigon (default: `true)`. When running the TxPool as a separate process, this flag is used to prevent the internal HTTP server from interfering with the external TxPool.
* `--sentry.api.addr=localhost:9091`: This flag sets the address and port for the Sentry API. The Sentry API is used for communication between the TxPool and the Sentry.
* `--txpool.api.addr=localhost:9094`: This flag sets the address and port for the TxPool API (default: use value of `--private.api.addr`). The TxPool API is used for communication between the TxPool and other Erigon components.
* `--pprof`: Enable the pprof HTTP server (default: `false`)
* `--pprof.addr 0.0.0.0`: This flag sets the address for the pprof HTTP server (default: `127.0.0.1`). The pprof server is used for profiling and debugging Erigon. By setting this flag to `0.0.0.0`, the pprof server is made accessible from outside the local machine.

## Command Line Options

To display available options for TxPool digit:

```bash
./build/bin/txpool --help
```

The `--help` flag listing is reproduced below for your convenience.

```text
./build/bin/txpool --help
Launch external Transaction Pool instance - same as built-into Erigon, but as independent Process

Usage:
  txpool [flags]

Flags:
      --datadir string                     Data directory for the databases (default "/home/user/.local/share/erigon")
      --db.writemap                        Enable WRITE_MAP feature for fast database writes and fast commit times (default true)
      --diagnostics.disabled               Disable diagnostics
      --diagnostics.endpoint.addr string   Diagnostics HTTP server listening interface (default "127.0.0.1")
      --diagnostics.endpoint.port uint     Diagnostics HTTP server listening port (default 6062)
      --diagnostics.speedtest              Enable speed test
  -h, --help                               help for txpool
      --log.console.json                   Format console logs with JSON
      --log.console.verbosity string       Set the log level for console logs (default "info")
      --log.delays                         Enable block delay logging
      --log.dir.disable                    disable disk logging
      --log.dir.json                       Format file logs with JSON
      --log.dir.path string                Path to store user and error logs to disk
      --log.dir.prefix string              The file name prefix for logs stored to disk
      --log.dir.verbosity string           Set the log verbosity for logs stored to disk (default "info")
      --log.json                           Format console logs with JSON
      --metrics                            Enable metrics collection and reporting
      --metrics.addr string                Enable stand-alone metrics HTTP server listening interface (default "127.0.0.1")
      --metrics.port int                   Metrics HTTP server listening port (default 6061)
      --pprof                              Enable the pprof HTTP server
      --pprof.addr string                  pprof HTTP server listening interface (default "127.0.0.1")
      --pprof.cpuprofile string            Write CPU profile to the given file
      --pprof.port int                     pprof HTTP server listening port (default 6060)
      --private.api.addr string            execution service <host>:<port> (default "localhost:9090")
      --sentry.api.addr strings            comma separated sentry addresses '<host>:<port>,<host>:<port>' (default [localhost:9091])
      --tls.cacert string                  CA certificate for client side TLS handshake
      --tls.cert string                    certificate for client side TLS handshake
      --tls.key string                     key file for client side TLS handshake
      --trace string                       Write execution trace to the given file
      --txpool.accountslots uint           Minimum number of executable transaction slots guaranteed per account (default 16)
      --txpool.api.addr string             txpool service <host>:<port> (default "localhost:9094")
      --txpool.blobpricebump uint          Price bump percentage to replace an existing blob (type-3) transaction (default 100)
      --txpool.blobslots uint              Max allowed total number of blobs (within type-3 txs) per account (default 48)
      --txpool.commit.every duration       How often transactions should be committed to the storage (default 15s)
      --txpool.globalbasefeeslots int      Maximum number of non-executable transactions where only not enough baseFee (default 30000)
      --txpool.globalqueue int             Maximum number of non-executable transaction slots for all accounts (default 30000)
      --txpool.globalslots int             Maximum number of executable transaction slots for all accounts (default 10000)
      --txpool.gossip.disable              Disabling p2p gossip of txs. Any txs received by p2p - will be dropped. Some networks like 'Optimism execution engine'/'Optimistic Rollup' - using it to protect against MEV attacks
      --txpool.pricebump uint              Price bump percentage to replace an already existing transaction (default 10)
      --txpool.pricelimit uint             Minimum gas price (fee cap) limit to enforce for acceptance into the pool (default 1)
      --txpool.totalblobpoollimit uint     Total limit of number of all blobs in txs within the txpool (default 480)
      --txpool.trace.senders strings       Comma separated list of addresses, whose transactions will traced in transaction pool with debug printing
      --verbosity string                   Set the log level for console logs (default "info")
```

---

# Sentry
URL: https://docs.erigon.tech/fundamentals/modules/sentry


Sentry connects Erigon to the Ethereum P2P network, enabling the discovery of other participants across the Internet and secure communication with them. It performs these main functions:

* Peer discovery via the following:
  * Kademlia DHT
  * DNS lookup
  * Configured static peers
  * Node info saved in the database
  * Boot nodes pre-configured in the source code
* Peer management:
  * handshakes
  * holding p2p connection even if Erigon is restarted

The ETH core interacts with the Ethereum p2p network through the Sentry component. Sentry provides a simple interface to the core, with functions to download data, receive notifications about gossip messages, upload data on request from peers, and broadcast gossip messages either to a selected set of peers or to all peers.

## Running with one or more external Sentry instances

It is possible to have multiple Sentry to increase connectivity to the network or to obscure the location of the core computer. In this case it is necessary to define address and port of each Sentry that should be connected to the Core.

Before using the Sentry component the executable must be built:

```bash
cd erigon
make sentry
```

Then it can be launched as an independent component with the command:

```bash
./build/bin/sentry
```

### Example

In this example we will run an instance of Erigon and Sentry on the same machine.

Following is the Sentry client running separately:

```bash
./build/bin/sentry --datadir=~/.local/share/erigon
```

And Erigon attaching to it:

```bash
./build/bin/erigon --sentry.api.addr=127.0.0.1:9091
```

Erigon might be attached to several Sentry instances running across different machines. As per Erigon help:

```bash
--sentry.api.addr value
```

Where `value` is comma separated Sentry addresses `<host>:<port>,<host>:<port>`.

## More info

For other information regarding Sentry functionality, configuration, and usage, please refer to the embedded file you can find in your compiled Erigon folder at `./cmd/sentry/README.md`.

### Command Line Options

To display available options for Sentry digit:

```bash
./build/bin/sentry --help
```

The `--help` flag listing is reproduced below for your convenience.

```text
Run p2p sentry

Usage:
  sentry [flags]

Flags:
      --datadir string                     Data directory for the databases (default "/home/user/.local/share/erigon")
      --diagnostics.disabled               Disable diagnostics
      --diagnostics.endpoint.addr string   Diagnostics HTTP server listening interface (default "127.0.0.1")
      --diagnostics.endpoint.port uint     Diagnostics HTTP server listening port (default 6062)
      --diagnostics.speedtest              Enable speed test
      --discovery.dns strings              Sets DNS discovery entry points (use "" to disable DNS)
      --healthcheck                        Enabling grpc health check
  -h, --help                               help for sentry
      --log.console.json                   Format console logs with JSON
      --log.console.verbosity string       Set the log level for console logs (default "info")
      --log.delays                         Enable block delay logging
      --log.dir.disable                    disable disk logging
      --log.dir.json                       Format file logs with JSON
      --log.dir.path string                Path to store user and error logs to disk
      --log.dir.prefix string              The file name prefix for logs stored to disk
      --log.dir.verbosity string           Set the log verbosity for logs stored to disk (default "info")
      --log.json                           Format console logs with JSON
      --maxpeers int                       Maximum number of network peers (network disabled if set to 0) (default 32)
      --maxpendpeers int                   Maximum number of TCP connections pending to become connected peers (default 1000)
      --metrics                            Enable metrics collection and reporting
      --metrics.addr string                Enable stand-alone metrics HTTP server listening interface (default "127.0.0.1")
      --metrics.port int                   Metrics HTTP server listening port (default 6061)
      --nat string                         NAT port mapping mechanism (any|none|upnp|pmp|stun|extip:<IP>)
                                           			 "" or "none"         Default - do not nat
                                           			 "extip:77.12.33.4"   Will assume the local machine is reachable on the given IP
                                           			 "any"                Uses the first auto-detected mechanism
                                           			 "upnp"               Uses the Universal Plug and Play protocol
                                           			 "pmp"                Uses NAT-PMP with an auto-detected gateway address
                                           			 "pmp:192.168.0.1"    Uses NAT-PMP with the given gateway address
                                           			 "stun"               Uses STUN to detect an external IP using a default server
                                           			 "stun:<server>"      Uses STUN to detect an external IP using the given server (host:port)
                                           
      --netrestrict string                 Restricts network communication to the given IP networks (CIDR masks)
      --nodiscover                         Disables the peer discovery mechanism (manual peer addition)
      --p2p.allowed-ports uints            Allowed ports to pick for different eth p2p protocol versions as follows <porta>,<portb>,..,<porti> (default [30303,30304,30305,30306,30307])
      --p2p.protocol uint                  Version of eth p2p protocol (default 68)
      --port int                           Network listening port (default 30303)
      --pprof                              Enable the pprof HTTP server
      --pprof.addr string                  pprof HTTP server listening interface (default "127.0.0.1")
      --pprof.cpuprofile string            Write CPU profile to the given file
      --pprof.port int                     pprof HTTP server listening port (default 6060)
      --sentry.api.addr string             grpc addresses (default "localhost:9091")
      --staticpeers strings                Comma separated enode URLs to connect to
      --trace string                       Write execution trace to the given file
      --trustedpeers strings               Comma separated enode URLs which are always allowed to connect, even above the peer limit
      --verbosity string                   Set the log level for console logs (default "info")
```

---

# Downloader
URL: https://docs.erigon.tech/fundamentals/modules/downloader


The Downloader is a service responsible for seeding and downloading historical data using the BitTorrent protocol. Data is stored in the form of immutable `.seg` files, known as **snapshots**. The Ethereum core instructs the Downloader to download specific files, identified by their unique info hashes, which include both block headers and block bodies. The Downloader then communicates with the BitTorrent network to retrieve the necessary files, as specified by the Ethereum core.

:::warning
**Info**: While all Erigon components are separable and can be run on different machines, the Downloader must run on the same machine as Erigon to be able to share downloaded and seeded files.
:::

For a comprehensive understanding of the Downloader's functionality, configuration, and usage, please refer to [./cmd/downloader/readme.md](https://github.com/erigontech/erigon/blob/main/cmd/downloader/readme.md) with the following key topics:

1. **Snapshots overview**: An introduction to snapshots, their benefits, and how they are created and used in Erigon.
2. **Starting Erigon with snapshots support**: Instructions on how to start Erigon with snapshots support, either by default or as a separate process.
3. **Creating new networks or bootnodes**: A guide on how to create new networks or bootnodes, including creating new snapshots and starting the Downloader.
4. **Architecture**: An overview of the Downloader's architecture, including how it works with Erigon and the different ways .torrent files can be created.
5. **Utilities**: A list of available utilities, including `torrent_cat`, `torrent_magnet`, and `torrent_clean`.
6. **Remote manifest verify**: Instructions on how to verify that remote webseeds have available manifests and all manifested files are available.
7. **Faster rsync**: Tips on how to use `rsync` for faster file transfer.
8. **Release details**: Information on how to start automatic commits of new hashes to the `master` branch.
9. **Creating a seedbox**: A guide on how to create a seedbox to support a new network or type of snapshots.

Some of the key sections in the documentation include:

* **How to create new snapshots**: Instructions on how to create new snapshots, including using the `seg` command and creating .torrent files.
* **How to start the Downloader**: Instructions on how to start the Downloader, either as a separate process or as part of Erigon.
* **How to verify .seg files**: Instructions on how to verify that .seg files have the same checksum as the current .torrent files.

By referring to the embedded documentation file, you can gain a deeper understanding of the Downloader's capabilities and how to effectively utilize it in your Erigon setup.

## Command line options

To display available options for Downloader digit:

```bash
./build/bin/downloader --help
```

The `--help` flag listing is reproduced below for your convenience.

```text
snapshot downloader

Usage:
   [flags]
   [command]

Examples:
go run ./cmd/downloader --datadir <your_datadir> --downloader.api.addr 127.0.0.1:9093

Available Commands:
  completion      Generate the autocompletion script for the specified shell
  help            Help about any command
  manifest        
  manifest-verify 
  torrent_cat     
  torrent_clean   Remove all .torrent files from datadir directory
  torrent_create  
  torrent_hashes  
  torrent_magnet  

Flags:
      --chain string                       name of the network to join (default "mainnet")
      --datadir string                     Data directory for the databases (default "/home/admin/.local/share/erigon")
      --db.writemap                        Enable WRITE_MAP feature for fast database writes and fast commit times (default true)
      --diagnostics.disabled               Disable diagnostics
      --diagnostics.endpoint.addr string   Diagnostics HTTP server listening interface (default "127.0.0.1")
      --diagnostics.endpoint.port uint     Diagnostics HTTP server listening port (default 6062)
      --diagnostics.speedtest              Enable speed test
      --downloader.api.addr string         external downloader api network address, for example: 127.0.0.1:9093 serves remote downloader interface (default "127.0.0.1:9093")
      --downloader.disable.ipv4            Turns off ipv4 for the downloader
      --downloader.disable.ipv6            Turns off ipv6 for the downloader
  -h, --help                               help for this command
      --log.console.json                   Format console logs with JSON
      --log.console.verbosity string       Set the log level for console logs (default "info")
      --log.delays                         Enable block delay logging
      --log.dir.disable                    disable disk logging
      --log.dir.json                       Format file logs with JSON
      --log.dir.path string                Path to store user and error logs to disk
      --log.dir.prefix string              The file name prefix for logs stored to disk
      --log.dir.verbosity string           Set the log verbosity for logs stored to disk (default "info")
      --log.json                           Format console logs with JSON
      --metrics                            Enable metrics collection and reporting
      --metrics.addr string                Enable stand-alone metrics HTTP server listening interface (default "127.0.0.1")
      --metrics.port int                   Metrics HTTP server listening port (default 6061)
      --nat string                         NAT port mapping mechanism (any|none|upnp|pmp|stun|extip:<IP>)
                                           			 "" or "none"         Default - do not nat
                                           			 "extip:77.12.33.4"   Will assume the local machine is reachable on the given IP
                                           			 "any"                Uses the first auto-detected mechanism
                                           			 "upnp"               Uses the Universal Plug and Play protocol
                                           			 "pmp"                Uses NAT-PMP with an auto-detected gateway address
                                           			 "pmp:192.168.0.1"    Uses NAT-PMP with the given gateway address
                                           			 "stun"               Uses STUN to detect an external IP using a default server
                                           			 "stun:<server>"      Uses STUN to detect an external IP using the given server (host:port)
                                           
      --pprof                              Enable the pprof HTTP server
      --pprof.addr string                  pprof HTTP server listening interface (default "127.0.0.1")
      --pprof.cpuprofile string            Write CPU profile to the given file
      --pprof.port int                     pprof HTTP server listening port (default 6060)
      --seedbox                            Turns downloader into independent (doesn't need Erigon) software which discover/download/seed new files - useful for Erigon network, and can work on very cheap hardware. It will: 1) download .torrent from webseed 2) download new files after upgrade 3) we planing add discovery of new files soon
      --torrent.conns.perfile int          Number of connections per file (default 10)
      --torrent.download.rate string       Bytes per second, example: 32mb (default "512mb")
      --torrent.download.slots int         (DEPRECATED: No longer has any effect) Amount of files to download in parallel. (default 32)
      --torrent.maxpeers int               Unused parameter (reserved for future use) (default 100)
      --torrent.port int                   Port to listen and serve BitTorrent protocol (default 42069)
      --torrent.staticpeers string         Comma separated host:port to connect to
      --torrent.upload.rate string         Bytes per second, example: 32mb (default "16mb")
      --torrent.verbosity int              0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail (must set --verbosity to equal or higher level and has default: 2) (default 2)
      --trace string                       Write execution trace to the given file
      --verbosity string                   Set the log level for console logs (default "info")
      --verify                             Verify snapshots on startup. It will not report problems found, but re-download broken pieces.
      --verify.failfast                    Stop on first found error. Report it and exit
      --verify.files string                Limit list of files to verify
      --webseed string                     Comma-separated URL's, holding metadata about network-support infrastructure (like S3 buckets with snapshots, bootnodes, etc...)

Use " [command] --help" for more information about a command.
```

---

# Interacting with Erigon
URL: https://docs.erigon.tech/interacting-with-erigon


The Erigon RPC Service, managed by Erigon's modular [RPC Daemon](/fundamentals/modules/rpc-daemon), supports various API namespaces, which can be enabled or disabled using the `--http.api` flag. The available namespaces include:

* [`eth`](/interacting-with-erigon/eth): Standard Ethereum API.
* [`erigon`](/interacting-with-erigon/erigon): Erigon-specific extensions.
* [`engine`](/interacting-with-erigon/engine): The JSON-RPC Interface for Execution and Consensus Layer Communication.
* [`web3`](/interacting-with-erigon/web3): Web3 compatibility API.
* [`net`](/interacting-with-erigon/net): Network information API.
* [`debug`](/interacting-with-erigon/debug): Debugging and tracing API.
* [`trace`](/interacting-with-erigon/trace): Transaction tracing API.
* [`txpool`](/interacting-with-erigon/txpool): Transaction pool API.
* [`admin`](/interacting-with-erigon/admin): Node administration API
* [`bor`](/interacting-with-erigon/bor): Polygon Bor-specific API (when running on Polygon)
* [`ots`](/interacting-with-erigon/ots): These methods are specifically tailored for use with Otterscan, an open-source, fast block explorer.
* [`internal`](/interacting-with-erigon/internal): Erigon specific API for development and debugging purposes.
* [`gRPC`](/interacting-with-erigon/grpc): API for lower-level data access.
* [`overlay`](/interacting-with-erigon/overlay): Erigon-specific overlay API for replaying blocks with state overrides (archive nodes only).
* [`parity`](/interacting-with-erigon/parity): Partial OpenEthereum compatibility (`parity_listStorageKeys`).
* [`graphql`](/interacting-with-erigon/graphql): GraphQL endpoint following EIP-1767.

For a complete reference on the standard Ethereum JSON-RPC methods, especially those in the `eth`, `net`, and `web3` namespaces, it is recommended to consult the general documentation on [ethereum.org's JSON-RPC API page](https://ethereum.org/en/developers/docs/apis/json-rpc/). Additionally, for the formal specification of the `debug`, `engine`, and `eth` namespaces, including unique, detailed descriptions for methods like `eth_getProof` and `eth_simulateV1`, refer to the [Execution APIs documentation](https://ethereum.github.io/execution-apis).

## Erigon RPC Transports

Erigon supports [HTTP](/interacting-with-erigon/#http), [HTTPS](/interacting-with-erigon/#https), [WebSockets](/interacting-with-erigon/#websockets), [IPC](/interacting-with-erigon/#ipc), [gRPC](/interacting-with-erigon/#grpc) and [GraphQL](/interacting-with-erigon/#graphql) through its RPC Daemon.

### 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, you can either run Erigon with built-in RPC or use the separate `rpcdaemon`:

```bash
# Built-in RPC (default)
erigon --http

# Or separate RPC daemon
rpcdaemon --http.enabled
```

The default port is `8545`, and the default listen address is localhost. _node/nodecfg/defaults.go:30-31_

You can configure the listen address and port using `--http.addr` and `--http.port` respectively:

```bash
erigon --http --http.addr 127.0.0.1 --http.port 12345
# Or with rpcdaemon
rpcdaemon --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
erigon --http --http.api eth,net,debug,trace
# Or with rpcdaemon
rpcdaemon --http.api eth,net,debug,trace
```

The default APIs enabled are `eth` and `erigon`. Available namespaces include: `admin`, `debug`, `eth`, `erigon`, `net`, `trace`, `txpool`, `web3`, `bor` (Polygon only), and `internal`.

You can also restrict who can access the HTTP server by specifying domains for Cross-Origin requests using `--http.corsdomain`:

```bash
erigon --http --http.corsdomain https://mycoolapp.com
```

Alternatively, if you want to allow any domain, you can pass `*`:

```bash
erigon --http --http.corsdomain "*"
```

### HTTPS

Erigon supports HTTPS and HTTP/2 out of the box:

```bash
rpcdaemon --https.enabled --https.cert /path/to/cert.pem --https.key /path/to/key.pem
```

### 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 port by passing `--ws.port` (default `8546`) _node/nodecfg/defaults.go:34_
* Configure cross-origin requests using `--ws.origins` (though this maps to `--http.corsdomain` in Erigon)
* WebSocket APIs inherit from the HTTP API configuration

```bash
erigon --http --ws --http.api eth,net,debug,trace
```

### IPC

IPC is a simpler transport protocol for use in local environments where the node and the client exist on the same machine.

**Note:** IPC is only available through the separate `rpcdaemon` process, not the main `erigon` binary. Erigon uses a
modular architecture where RPC functionality is handled by a standalone daemon.

#### Enabling IPC with RPC Daemon

First, start Erigon with the private API enabled:

```bash
erigon --datadir=<path-to-datadir> --private.api.addr=localhost:9090
```

Then, in a separate terminal, start RPC Daemon with IPC enabled:

```bash
rpcdaemon --private.api.addr=localhost:9090 --socket.enabled --socket.url unix:///<path-to-datadir>/erigon.ipc
```

**Important:** Make sure you have write permissions to the directory where the socket will be created.

On Linux and macOS, Erigon uses UNIX sockets. On Windows, IPC is provided using named pipes (use `\\.\pipe\erigon.ipc`
format). The socket inherits the API namespaces from the `--http.api` flag passed to `rpcdaemon`:

```bash
rpcdaemon --private.api.addr=localhost:9090 --socket.enabled --socket.url unix:///<path-to-datadir>/erigon.ipc --http.api eth,net,web3,debug,trace
```

#### TCP Socket Alternative (Advanced)

You can also serve the raw JSON-RPC2 protocol over TCP instead of Unix sockets:

```bash
rpcdaemon --private.api.addr=localhost:9090 --socket.enabled --socket.url tcp://127.0.0.1:8546
```

**Note**: This creates a raw JSON-RPC2 socket without HTTP wrapping. Most users should use the HTTP endpoint (enabled by
default on port 8545) instead. The TCP socket is for specialized clients that support raw JSON-RPC2 protocol.

#### Testing IPC Connection

Test your IPC connection using curl:

```bash
curl --unix-socket <path-to-datadir>/erigon.ipc \
     -X POST http://localhost/ \
     -H "Content-Type: application/json" \
     --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

Or use the HTTP endpoint (enabled by default on port 8545):

```bash
curl http://127.0.0.1:8545 \
     -X POST \
     -H "Content-Type: application/json" \
     --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

### gRPC

Erigon also supports gRPC for high-performance access to blockchain data:

```bash
rpcdaemon --grpc --grpc.addr localhost --grpc.port 9090
```

### GraphQL

Erigon uses the standard GraphQL documented by Geth at [https://geth.ethereum.org/docs/interacting-with-geth/rpc/graphql](https://geth.ethereum.org/docs/interacting-with-geth/rpc/graphql).

## Interacting with the RPC

You can easily interact with these APIs using `curl`, a programming language with a low-level library, or tools like [Foundry](https://getfoundry.sh/) to interact with the chain at the exposed HTTP or WebSocket port.

To enable all APIs using an HTTP transport:

```bash
erigon --http --http.api "admin,debug,eth,erigon,net,trace,txpool,web3"
```

This allows you to then call:

```bash
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' localhost:8545

# With cast (if using Foundry)
cast block-number
cast rpc admin_nodeInfo  
cast rpc debug_traceTransaction <tx_hash>
cast rpc erigon_forks
```

---

# eth
URL: https://docs.erigon.tech/interacting-with-erigon/eth


The `eth` namespace is the foundational and most commonly used API set in Ethereum's JSON-RPC interface. It provides core functionality for interacting with the Ethereum blockchain, enabling users and applications to read blockchain state and submit transactions.

Key methods within this namespace allow you to check an account's balance (`eth_getBalance`), get the current block number (`eth_blockNumber`), retrieve transaction details (`eth_getTransactionByHash`), and send signed transactions to the network (`eth_sendRawTransaction`, `eth_sendRawTransactionSync`). Essentially, the `eth` namespace contains all the fundamental tools needed to observe and participate in the life of the chain.

### API usage

For API usage refer to the below official resources:

* [https://ethereum.org/en/developers/docs/apis/json-rpc/](https://ethereum.org/en/developers/docs/apis/json-rpc/)
* [https://ethereum.github.io/execution-apis/](https://ethereum.github.io/execution-apis/)

### eth\_getProof

`eth_getProof` returns Merkle proofs for account state and storage slots, as defined in [EIP-1186](https://eips.ethereum.org/EIPS/eip-1186). It is stable and production-ready as of Erigon v3.4.

To enable historical proof support, activate commitment history storage at startup:

```text
--prune.include-commitment-history=true
```

:::warning
**RAM requirement:** Historical `eth_getProof` requires at least **+32 GB RAM** to operate efficiently. Running without sufficient memory will severely degrade node performance.
:::

This enables faster retrieval of Merkle proofs for any executed block.

### eth\_getStorageValues

`eth_getStorageValues` is an Erigon extension that retrieves multiple storage slots for a given account in a single call, reducing round-trips compared to multiple `eth_getStorageAt` calls.

**Parameters**

| Parameter    | Type             | Description                                          |
| ------------ | ---------------- | ---------------------------------------------------- |
| address      | STRING           | The account address to query storage for             |
| storageKeys  | ARRAY of STRING  | List of 32-byte storage slot keys (hex-encoded)      |
| blockNumber  | STRING or NUMBER | Block number or tag (`"latest"`, `"earliest"`, etc.) |

**Example**

```bash
curl --data '{"jsonrpc":"2.0","method":"eth_getStorageValues","params":["0xAddress","["0x0000000000000000000000000000000000000000000000000000000000000001"],"latest"],"id":1}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

An object mapping each requested storage key to its 32-byte value.

---

# erigon
URL: https://docs.erigon.tech/interacting-with-erigon/erigon


Erigon provides several RPC namespaces that extend beyond the standard Ethereum JSON-RPC API, exposing Erigon-specific functionality and data structures. The primary Erigon-specific namespace is **`erigon_`** which offer extended blockchain data access methods.

These methods must be explicitly enabled using the `--http.api` flag when starting the RPC Daemon.

### Namespace Availability

* The `erigon_` namespace is enabled by default in the RPC Daemon and must be explicitly included in the `--http.api` flag if customizing enabled namespaces.

### Performance Considerations

* Erigon-specific methods are optimized for Erigon's architecture and often provide better performance than standard equivalents
* Methods like `erigon_getHeaderByNumber` and `erigon_getHeaderByHash` can be faster as they skip transaction and uncle data
* The `erigon_getLatestLogs` method includes advanced pagination to handle large result sets efficiently

### Enhanced Features

* `erigon_getLatestLogs` supports `ignoreTopicsOrder` for flexible topic matching
* `erigon_getLogs` returns enhanced ErigonLog objects with additional metadata like timestamps
* `erigon_getBlockByTimestamp` uses binary search for efficient timestamp-based block lookup

See more details [here](https://github.com/erigontech/erigon/blob/main/cmd/rpcdaemon/README.md#rpc-implementation-status) about implementation status.

***

## **erigon\_forks**

Returns the genesis block hash and a sorted list of all fork block numbers for the current chain configuration.

**Parameters**

None

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_forks","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type        | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| Object      | Contains genesis hash and fork information                    |
| genesis     | DATA, 32 BYTES - The genesis block hash                       |
| heightForks | ARRAY - Array of block numbers where height-based forks occur |
| timeForks   | ARRAY - Array of timestamps where time-based forks occur      |

***

## **erigon\_blockNumber**

Returns the latest executed block number. Unlike `eth_blockNumber`, this method can accept a specific block number parameter and returns the latest executed block rather than the fork choice head after the merge.

**Parameters**

| Parameter   | Type                | Description                                                             |
| ----------- | ------------------- | ----------------------------------------------------------------------- |
| blockNumber | QUANTITY (optional) | Block number to query. If omitted, returns latest executed block number |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_blockNumber","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type     | Description                     |
| -------- | ------------------------------- |
| QUANTITY | The block number as hexadecimal |

***

## **erigon\_getHeaderByNumber**

Returns a block header by block number, ignoring transaction and uncle data for potentially faster response times.

**Parameters**

| Parameter   | Type          | Description                                     |
| ----------- | ------------- | ----------------------------------------------- |
| blockNumber | QUANTITY\|TAG | Block number or "latest", "earliest", "pending" |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_getHeaderByNumber","params":["0x1b4"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                |
| ------ | ------------------------------------------ |
| Object | Block header object with all header fields |

***

## **erigon\_getHeaderByHash**

Returns a block header by block hash, ignoring transaction and uncle data for potentially faster response times.

**Parameters**

| Parameter | Type           | Description       |
| --------- | -------------- | ----------------- |
| blockHash | DATA, 32 BYTES | Hash of the block |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_getHeaderByHash","params":["0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                |
| ------ | ------------------------------------------ |
| Object | Block header object with all header fields |

***

## **erigon\_getBlockByTimestamp**

Returns a block by timestamp using binary search to find the closest block to the specified timestamp.

**Parameters**

| Parameter | Type     | Description                                                                  |
| --------- | -------- | ---------------------------------------------------------------------------- |
| timestamp | QUANTITY | Unix timestamp                                                               |
| fullTx    | Boolean  | If true, include full transaction objects; if false, only transaction hashes |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_getBlockByTimestamp","params":["0x5ddf2094", false],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                    |
| ------ | ---------------------------------------------- |
| Object | Block object matching closest to the timestamp |

***

## **erigon\_getBalanceChangesInBlock**

Returns all account balance changes that occurred within a specific block.

**Parameters**

| Parameter     | Type                | Description                      |
| ------------- | ------------------- | -------------------------------- |
| blockNrOrHash | QUANTITY\|TAG\|HASH | Block number, tag, or block hash |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_getBalanceChangesInBlock","params":["0x1b4"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                      |
| ------ | ------------------------------------------------ |
| Object | Mapping of addresses to their new balance values |

***

## **erigon\_getLogsByHash**

Returns an array of arrays of logs generated by transactions in a block given by block hash.

**Parameters**

| Parameter | Type           | Description       |
| --------- | -------------- | ----------------- |
| blockHash | DATA, 32 BYTES | Hash of the block |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_getLogsByHash","params":["0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type  | Description                                               |
| ----- | --------------------------------------------------------- |
| Array | Array of arrays of log objects, one array per transaction |

***

## **erigon\_getLogs**

Returns an array of logs matching a given filter object with enhanced filtering capabilities.

**Parameters**

| Parameter | Type   | Description                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------- |
| filter    | Object | Filter criteria including fromBlock, toBlock, address, topics, and blockHash |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_getLogs","params":[{"fromBlock":"0x1","toBlock":"0x2","address":"0x8888f1f195afa192cfee860698584c030f4c9db1"}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type  | Description                                       |
| ----- | ------------------------------------------------- |
| Array | Array of ErigonLog objects with enhanced metadata |

:::note
The number of logs returned is capped by [`--rpc.logs.maxresults`](../fundamentals/configuring-erigon#rpc--api) (default `20000`). Set to `0` to remove the limit. The block range of the query is independently capped by `--rpc.blockrange.limit` (default `1000`).
:::

***

## **erigon\_getLatestLogs**

Returns the latest logs matching a filter criteria in descending order with advanced pagination and topic matching options.

**Parameters**

| Parameter  | Type   | Description                                                   |
| ---------- | ------ | ------------------------------------------------------------- |
| filter     | Object | Filter criteria object                                        |
| logOptions | Object | Options including logCount, blockCount, and ignoreTopicsOrder |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_getLatestLogs","params":[{"address":"0x8888f1f195afa192cfee860698584c030f4c9db1"},{"logCount":100,"ignoreTopicsOrder":true}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type  | Description                                                  |
| ----- | ------------------------------------------------------------ |
| Array | Array of ErigonLog objects in descending chronological order |

:::note
The number of logs returned is capped by [`--rpc.logs.maxresults`](../fundamentals/configuring-erigon#rpc--api) (default `20000`). Set to `0` to remove the limit.
:::

***

## **erigon\_getBlockReceiptsByBlockHash**

Returns all transaction receipts for a canonical block by block hash.

**Parameters**

| Parameter | Type           | Description                 |
| --------- | -------------- | --------------------------- |
| blockHash | DATA, 32 BYTES | Hash of the canonical block |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_getBlockReceiptsByBlockHash","params":["0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type  | Description                                                |
| ----- | ---------------------------------------------------------- |
| Array | Array of receipt objects for all transactions in the block |

***

## **erigon\_nodeInfo**

Returns a collection of metadata known about the host node and connected peers.

**Parameters**

None

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"erigon_nodeInfo","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type  | Description                                                 |
| ----- | ----------------------------------------------------------- |
| Array | Array of NodeInfo objects containing peer and node metadata |

***

---

# engine
URL: https://docs.erigon.tech/interacting-with-erigon/engine


The Engine API is a standardized JSON-RPC interface defined by the Ethereum specification. Its purpose is to enable secure and structured communication between the Consensus Layer (CL) client and the Execution Layer (EL) client in the post-Merge Proof-of-Stake architecture.

The Engine API replaced older `eth_` methods for consensus communication. It is only required when running Erigon with an external consensus client like Prysm, Lighthouse, or Teku, as these external clients communicate exclusively through this interface.

For API usage refer to the below official resources:

* [https://ethereum.org/en/developers/docs/apis/json-rpc/](https://ethereum.org/en/developers/docs/apis/json-rpc/)
* [https://ethereum.github.io/execution-apis/](https://ethereum.github.io/execution-apis/)

#### Default Erigon Behavior (Caplin)

By default, Erigon runs its own embedded consensus layer client, Caplin. For optimized performance, Caplin bypasses the Engine API and uses direct internal calls to communicate with Erigon's execution layer.

You can optionally force Caplin to use the Engine API interface by setting the `--caplin.use-engine-api` flag. When this flag is active, Caplin connects via the same [JWT](../fundamentals/jwt)-authenticated HTTP endpoint used by external CL clients.

#### Engine API Functionality

When in use (with external CL clients), the Engine API provides essential methods for Proof-of-Stake operations:

* Payload Execution: `engine_newPayloadV1/V2/V3/V4` validates and executes blocks sent by the CL.
* Fork Choice Updates: `engine_forkchoiceUpdatedV1/V2/V3` updates the chain head and triggers block building.
* Payload Retrieval: `engine_getPayloadV1/V2/V3/V4` retrieves built blocks for the CL to propose.
* Payload Bodies: `engine_getPayloadBodiesByHashV1` and `engine_getPayloadBodiesByRangeV1` fetch historical data.
* Blob Retrieval: `engine_getBlobsV1/V2/V3` retrieves blobs by versioned hash, with V3 adding support for PeerDAS data columns.

#### Configuration and Security

For security, the Engine API listens on port 8551 by default and requires JWT authentication.

* A JWT secret is automatically generated and saved in the file `jwt.hex` within your data directory.
* This secret must be shared with your external consensus layer client to establish secure communication.
* If your CL client runs on a different machine, you must expose the API using `--authrpc.addr 0.0.0.0` and configure virtual hosts appropriately with `--authrpc.vhosts`.

---

# web3
URL: https://docs.erigon.tech/interacting-with-erigon/web3


The `web3` namespace provides utility methods that are part of the standard Ethereum JSON-RPC API. These methods offer basic functionality for client identification and cryptographic operations. In Erigon, the web3 namespace is implemented through the `Web3API` interface and `Web3APIImpl` struct. The web3 namespace is enabled by default in Erigon's RPC Daemon and provides essential utility functions that many Ethereum applications rely on for basic operations.

For API usage refer to the below official resources:

* [https://ethereum.org/en/developers/docs/apis/json-rpc/](https://ethereum.org/en/developers/docs/apis/json-rpc/)

### Implementation Details

* The web3 namespace is implemented in `Web3APIImpl` which extends `BaseAPI` and uses the `ethBackend` for client version information
* The `web3_sha3` method uses Erigon's crypto library implementation of Keccak-256, which is the same hashing algorithm used throughout Ethereum
* Both methods are lightweight utility functions that don't require complex blockchain state access

### Usage Considerations

* `web3_clientVersion` is often used by applications to identify the Ethereum client type and version for compatibility checks
* `web3_sha3` provides the same Keccak-256 hashing that's used for Ethereum addresses, transaction hashes, and other cryptographic operations in the protocol
* These methods are part of the core Ethereum JSON-RPC specification and are supported by all major Ethereum clients

### Availability

* The web3 namespace is enabled by default in Erigon's RPC Daemon
* No special configuration is required to use these methods
* They are available on both HTTP and WebSocket connections

---

# net
URL: https://docs.erigon.tech/interacting-with-erigon/net


The `net` namespace provides network-related methods that are part of the standard Ethereum JSON-RPC API. These methods offer information about the node's network connectivity, peer count, and network version. In Erigon, the net namespace is implemented through the `NetAPI` interface and `NetAPIImpl` struct.

The `net` namespace is enabled by default in Erigon's RPC Daemon and provides essential network information that applications use to understand the node's connectivity status and network configuration.

For API usage refer to the below official resources:

* [https://ethereum.org/en/developers/docs/apis/json-rpc/](https://ethereum.org/en/developers/docs/apis/json-rpc/)

### Implementation Details

* The net namespace is implemented in `NetAPIImpl` which uses the `ethBackend` to access network information.
* `net_listening` determines connectivity by attempting to retrieve peer information from the backend.
* `net_version` and `net_peerCount` require access to the backend and will return errors in `--datadir` mode when the backend is unavailable.

### Backend Dependency

* Methods `net_version` and `net_peerCount` require the `ethBackend` to be available.
* When running in `--datadir` mode or when the backend cannot be accessed, these methods will return a "not available" error.
* The `net_listening` method gracefully handles backend unavailability by returning `false` .

### Network Information Usage

* `net_version` is commonly used by applications to verify they're connected to the correct .Ethereum network.
* `net_peerCount` helps monitor node connectivity and network health.
* `net_listening` provides a basic connectivity check for the node's network interface.

### Availability and Configuration

* The net namespace is enabled by default in Erigon's RPC Daemon.
* These methods are available on both HTTP and WebSocket connections.
* For remote RPC Daemon setups, the `net` namespace must be explicitly enabled for health check functionality.

### Documentation References

* The current implementation shows some limitations noted in the documentation, such as hardcoded return values in certain scenarios.
* `net_peerCount` specifically counts only internal sentries, which may not reflect the total peer count in distributed setups.

---

# debug
URL: https://docs.erigon.tech/interacting-with-erigon/debug


The `debug` namespace provides debugging and diagnostic methods for Erigon node operators and developers. These methods offer deep introspection into blockchain state, transaction execution, and node performance.

The debug namespace must be explicitly enabled using the `--http.api=debug` flag when starting the RPC Daemon.

:::warning
The `debug` namespace is intended for debugging and development purposes, not for production use.
:::

#### Security and Access Control

* Debug methods are considered private and should not be exposed on public RPC endpoints;
* These methods can consume significant resources and should be used carefully in production environments;
* Access should be restricted to trusted operators and developers only.

#### Performance Considerations

* Tracing methods (`debug_traceBlockByHash`, `debug_traceBlockByNumber`, `debug_traceTransaction`, `debug_traceCall`, `debug_traceCallMany`) support streaming for large results to reduce memory usage
* The `AccountRangeMaxResults` constant limits account range queries to 8192 results, or 256 when storage is included;
* Memory and GC control methods allow fine-tuning of node performance.
* Some methods like `debug_accountRange` have compatibility layers for both Geth and legacy Erigon parameter formats `debug_api`

#### Integration with Erigon Architecture

* Debug methods leverage Erigon's temporal database for historical state access;
* The implementation uses `kv.TemporalRoDB` for efficient historical queries;
* Tracing functionality integrates with Erigon's execution engine and EVM implementation.

#### Usage in Development and Testing

* These methods are essential for debugging transaction execution issues;
* Storage range methods help analyze contract state changes;
* Memory management methods assist in performance optimization and resource monitoring.

***

## JSON-RPC Specification

### debug\_getRawReceipts

Returns an array of EIP-2718 binary-encoded receipts from a single block.

#### Parameters

| Parameter     | Type                    | Description                                                        |
| ------------- | ----------------------- | ------------------------------------------------------------------ |
| blockNrOrHash | QUANTITY \| TAG \| DATA | Block number, tag ("earliest", "latest", "pending"), or block hash |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_getRawReceipts","params":["0x123456"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type          | Description                                  |
| ------------- | -------------------------------------------- |
| Array of DATA | Array of binary-encoded transaction receipts |

### debug\_accountRange

Returns a range of accounts involved in the given block range.

#### Parameters

| Parameter      | Type            | Description                                                 |
| -------------- | --------------- | ----------------------------------------------------------- |
| blockNrOrHash  | QUANTITY \| TAG | Block number or tag                                         |
| start          | DATAARRAY       | Array of prefixes to match account addresses                |
| maxResults     | QUANTITY        | Maximum number of accounts to retrieve                      |
| excludeCode    | BOOLEAN         | If true, exclude byte code from results                     |
| excludeStorage | BOOLEAN         | If true, exclude storage from results                       |
| incompletes    | BOOLEAN         | If true, return missing preimages (not supported when true) |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_accountRange","params":["0xaaaaa",[1],1,true,true,true],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type   | Description                                        |
| ------ | -------------------------------------------------- |
| Object | IteratorDump object containing account information |

### debug\_accountAt

Returns account information at a specific block and transaction index.

#### Parameters

| Parameter | Type           | Description                        |
| --------- | -------------- | ---------------------------------- |
| blockHash | DATA, 32 Bytes | Hash of the block                  |
| txIndex   | QUANTITY       | Transaction index within the block |
| address   | DATA, 20 Bytes | Account address                    |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0x123456...",1,"0x123456..."],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type   | Description                                           |
| ------ | ----------------------------------------------------- |
| Object | AccountResult with balance, nonce, code, and codeHash |

### debug\_getModifiedAccountsByNumber

Returns a list of accounts modified in the given block range by number.

#### Parameters

| Parameter   | Type            | Description                        |
| ----------- | --------------- | ---------------------------------- |
| startNumber | QUANTITY \| TAG | Start block number or tag          |
| endNumber   | QUANTITY \| TAG | End block number or tag (optional) |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_getModifiedAccountsByNumber","params":["0xccccd","0xcccce"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type                    | Description                         |
| ----------------------- | ----------------------------------- |
| Array of DATA, 20 Bytes | Array of modified account addresses |

### debug\_getModifiedAccountsByHash

Returns a list of accounts modified in the given block range by hash.

#### Parameters

| Parameter | Type           | Description                      |
| --------- | -------------- | -------------------------------- |
| startHash | DATA, 32 Bytes | Hash of the start block          |
| endHash   | DATA, 32 Bytes | Hash of the end block (optional) |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_getModifiedAccountsByHash","params":["0x2a1af0...","0x4e3d3e..."],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type                    | Description                         |
| ----------------------- | ----------------------------------- |
| Array of DATA, 20 Bytes | Array of modified account addresses |

### debug\_storageRangeAt

Returns information about a range of storage locations for a contract address.

#### Parameters

| Parameter       | Type              | Description                             |
| --------------- | ----------------- | --------------------------------------- |
| blockHash       | DATA, 32 Bytes    | Hash of block at which to retrieve data |
| txIndex         | QUANTITY, 8 Bytes | Transaction index in the block          |
| contractAddress | DATA, 20 Bytes    | Contract address                        |
| keyStart        | DATA, 32 Bytes    | Storage key to start from               |
| maxResult       | QUANTITY, 8 Bytes | Maximum number of values to retrieve    |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_storageRangeAt","params":["0xd3f185...",1,"0xb734c7...","0x00",2],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type   | Description                                         |
| ------ | --------------------------------------------------- |
| Object | StorageRangeResult with key/value pairs and nextKey |

### debug\_traceBlockByHash

Returns Geth style transaction traces for a block by hash.

#### Parameters

| Parameter | Type              | Description                 |
| --------- | ----------------- | --------------------------- |
| hash      | DATA, 32 Bytes    | Hash of block to trace      |
| config    | Object (optional) | Trace configuration options |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_traceBlockByHash","params":["0x123456...",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type  | Description                        |
| ----- | ---------------------------------- |
| Array | Array of transaction trace objects |

### debug\_traceBlockByNumber

Returns Geth style transaction traces for a block by number.

#### Parameters

| Parameter   | Type              | Description                 |
| ----------- | ----------------- | --------------------------- |
| blockNumber | QUANTITY \| TAG   | Block number or tag         |
| config      | Object (optional) | Trace configuration options |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_traceBlockByNumber","params":["0x123456",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type  | Description                        |
| ----- | ---------------------------------- |
| Array | Array of transaction trace objects |

### debug\_traceTransaction

Returns Geth style transaction trace.

#### Parameters

| Parameter | Type              | Description                  |
| --------- | ----------------- | ---------------------------- |
| hash      | DATA, 32 Bytes    | Hash of transaction to trace |
| config    | Object (optional) | Trace configuration options  |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x123456...",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type   | Description              |
| ------ | ------------------------ |
| Object | Transaction trace object |

### debug\_traceCall

Returns Geth style call trace.

#### Parameters

| Parameter     | Type                    | Description                                           |
| ------------- | ----------------------- | ----------------------------------------------------- |
| args          | Object                  | Call arguments (to, from, gas, gasPrice, value, data) |
| blockNrOrHash | QUANTITY \| TAG \| DATA | Block number, tag, or hash                            |
| config        | Object (optional)       | Trace configuration options                           |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[{"to":"0x123456..."},"latest",{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type   | Description       |
| ------ | ----------------- |
| Object | Call trace object |

### debug\_traceCallMany

Returns Geth style traces for multiple call bundles.

#### Parameters

| Parameter       | Type              | Description                                        |
| --------------- | ----------------- | -------------------------------------------------- |
| bundles         | Array             | Array of transaction bundles to trace              |
| simulateContext | Object            | Simulation context (blockNumber, transactionIndex) |
| config          | Object (optional) | Trace configuration options                        |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_traceCallMany","params":[[{"transactions":[...]}],{"blockNumber":"latest"},{}],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type  | Description                            |
| ----- | -------------------------------------- |
| Array | Array of trace results for each bundle |

### debug\_setMemoryLimit

Sets the GOMEMLIMIT for the process.

#### Parameters

| Parameter | Type     | Description           |
| --------- | -------- | --------------------- |
| limit     | QUANTITY | Memory limit in bytes |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_setMemoryLimit","params":[8589934592],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type     | Description           |
| -------- | --------------------- |
| QUANTITY | Previous memory limit |

### debug\_setGCPercent

Sets the garbage collection target percentage.

#### Parameters

| Parameter | Type     | Description                                |
| --------- | -------- | ------------------------------------------ |
| v         | QUANTITY | GC percentage (negative value disables GC) |

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_setGCPercent","params":[100],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type     | Description                    |
| -------- | ------------------------------ |
| QUANTITY | Previous GC percentage setting |

### debug\_freeOSMemory

Forces a garbage collection to free OS memory.

#### **Parameters**

None

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_freeOSMemory","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type | Description     |
| ---- | --------------- |
| null | No return value |

### debug\_gcStats

Returns garbage collection statistics.

#### **Parameters**

None

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_gcStats","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type   | Description          |
| ------ | -------------------- |
| Object | GC statistics object |

### debug\_memStats

Returns detailed runtime memory statistics.

#### **Parameters**

None

#### Example

```bash
curl -s --data '{"jsonrpc":"2.0","method":"debug_memStats","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

#### Returns

| Type   | Description                      |
| ------ | -------------------------------- |
| Object | Runtime memory statistics object |

---

# trace
URL: https://docs.erigon.tech/interacting-with-erigon/trace


The `trace` module is for getting a deeper insight into transaction processing. It includes two sets of calls the transaction trace filtering API and the ad-hoc tracing API.

In order to use the Transaction-Trace Filtering API, Erigon must be fully synced with the argument `trace` in `http.api` flag.

```bash
./build/bin/erigon --http.api: eth,erigon,trace
```

As for the Ad-hoc Tracing API, as long the blocks have not yet been pruned, the RPC calls will work.

## The Ad-hoc Tracing API

The ad-hoc tracing API allows you to perform diagnostics on calls or transactions—whether they are historical ones from the chain or hypothetical ones not yet mined. As long as the blocks have not yet been pruned, the RPC calls will work.

The diagnostics are requested by providing a configuration object that specifies the tracer type to be executed, allowing for deep insight into EVM execution:

* `trace`: Provides a Transaction Trace, showing the sequence of all external calls, internal messages, and value transfers that occurred during execution.
* `vmTrace`: Provides a Virtual Machine Execution Trace, delivering a full step-by-step trace of the EVM's state throughout the transaction, including all opcodes and gas usage.
* `stateDiff`: Provides a State Difference, detailing all altered portions of the Ethereum state (e.g., storage, balances, nonces) resulting from the transaction's execution.

#### Flat Tracers

As of v3.4, Erigon supports **flat tracers**, which produce OpenEthereum-compatible call traces in a flat (non-nested) list format. Each call frame is emitted as a separate object with an explicit `subtraces` count, matching the standard output format of `trace_transaction` and `trace_block`. Flat tracers are available for all ad-hoc tracing methods by including `"trace"` in the trace type array.

#### Providing a Transaction to Trace

There are three primary ways to specify the transaction to be traced:

1. Hypothetical Call: Providing the transaction information (like sender, recipient, and data) as if making a call using `eth_call` (see `trace_call`).
2. Raw Transaction: Providing raw, signed transaction data, as when using `eth_sendRawTransaction` (see `trace_rawTransaction`).
3. Mined Transaction: Providing a transaction hash for a previously mined transaction (see `trace_replayTransaction`).

:::info
**Note**: For replaying mined transactions, your node must be in archive mode, or the transaction must be within the most recent 1000 blocks.
:::

## The Transaction-Trace Filtering API

These APIs allow you to get a full _externality_ trace on any transaction executed throughout the Erigon chain. Unlike the log filtering API, you are able to search and filter based only upon address information. Information returned includes the execution of all `CREATE`s, `SUICIDE`s and all variants of `CALL` together with input data, output data, gas usage, amount transferred and the success status of each individual action.

### `traceAddress` field

The `traceAddress` field of all returned traces, gives the exact location in the call trace \[index in root, index in first `CALL`, index in second `CALL`, ...].

i.e. if the trace is:

```text
A
  CALLs B
    CALLs G
  CALLs C
    CALLs G
```

then it should look something like:

`[ {A: []}, {B: [0]}, {G: [0, 0]}, {C: [1]}, {G: [1, 0]} ]`

## JSON-RPC methods

#### Ad-hoc Tracing

* [trace\_call](#trace_call)
* [trace\_callMany](#trace_callmany)
* [trace\_rawTransaction](#trace_rawtransaction)
* [trace\_replayBlockTransactions](#trace_replayblocktransactions)
* [trace\_replayTransaction](#trace_replaytransaction)

#### Transaction-Trace Filtering

* [trace\_block](#trace_block)
* [trace\_filter](#trace_filter)
* [trace\_get](#trace_get)
* [trace\_transaction](#trace_transaction)

## Response Fields Reference

All `trace_*` methods return objects built from the same set of fields. Each method's "Returns" section below indicates which top-level shape it produces; the field semantics are defined once here.

### Top-level shapes

| Method | Top-level shape |
| --- | --- |
| `trace_call`, `trace_rawTransaction`, `trace_replayTransaction` | `Object` with `output`, `stateDiff`, `trace[]`, `vmTrace` |
| `trace_callMany` | `Array` — one per input call |
| `trace_replayBlockTransactions` | `Array` — one per transaction; each entry adds `transactionHash` |
| `trace_block`, `trace_filter`, `trace_transaction` | `Array` (flat list across all call frames) |
| `trace_get` | `TraceEntry` (single call frame at the requested position) |

### Top-level (ad-hoc tracing) fields

| Field | Type | Description |
| --- | --- | --- |
| `output` | DATA | Return data of the top-level call (`0x` if no data was returned). |
| `stateDiff` | Object \| null | Set when `"stateDiff"` is requested in the trace types array. Maps each touched account address to an object describing changes to `balance`, `nonce`, `code`, and per-key `storage` entries. `null` if not requested. |
| `trace` | Array of TraceEntry | Set when `"trace"` is requested. Flat list of call frames executed during the transaction. See **TraceEntry fields** below. |
| `vmTrace` | Object \| null | Set when `"vmTrace"` is requested. Step-by-step EVM trace including `code`, per-step `ops` (with `pc`, `cost`, `ex` execution result, and `sub` for nested calls). `null` if not requested. |
| `transactionHash` | DATA, 32 BYTES | (Only in `trace_replayBlockTransactions` entries) Hash of the transaction this trace belongs to. |

### TraceEntry fields

A `TraceEntry` represents a single call frame (root call, internal call, contract creation, or self-destruct).

| Field | Type | Description |
| --- | --- | --- |
| `action` | Object | The action that initiated this call frame. Shape depends on `type` (see **Action variants**). |
| `result` | Object \| null | The outcome of the action. `null` if the call frame errored. See **Result variants**. |
| `error` | String | (Optional) Present when the call frame errored. `"Reverted"` (title-cased) is the only special-cased value; all other errors are the verbatim Go error string, e.g. `"out of gas"`, `"invalid opcode: ..."`. For `"Reverted"`, `result` is still populated with `gasUsed` and `output` (or `code`/`address` for a `create` frame); for other errors, `result` is `null`. |
| `subtraces` | QUANTITY | Number of direct child call frames produced by this frame. Used together with `traceAddress` to reconstruct the call tree from a flat list. |
| `traceAddress` | Array of QUANTITY | Path to this frame inside the call tree. Empty array `[]` for the root call; `[0]` is the first child of the root; `[1, 0]` is the first child of the second child of the root, etc. |
| `type` | String | One of `"call"`, `"create"`, `"suicide"` (self-destruct), `"reward"` (block/uncle reward — appears in `trace_block` and in `trace_filter` results when the filter matches block coinbases or uncle authors). |
| `blockHash` | DATA, 32 BYTES | (Only in block-level methods: `trace_block`, `trace_filter`, `trace_transaction`, `trace_get`) Hash of the block containing the transaction. |
| `blockNumber` | QUANTITY | (Block-level methods only) Number of the block containing the transaction. |
| `transactionHash` | DATA, 32 BYTES | (Block-level methods only) Hash of the transaction containing this call frame. Absent for `"reward"` entries. |
| `transactionPosition` | QUANTITY | (Block-level methods only) Index of the transaction within the block. Absent for `"reward"` entries. |

### Action variants

The `action` object's shape depends on `type`:

**`type: "call"`**

| Field | Type | Description |
| --- | --- | --- |
| `callType` | String | `"call"`, `"callcode"`, `"delegatecall"`, or `"staticcall"`. |
| `from` | DATA, 20 BYTES | Sender address. |
| `to` | DATA, 20 BYTES | Recipient address. |
| `value` | QUANTITY | Wei value transferred. |
| `gas` | QUANTITY | Gas provided to this call frame. |
| `input` | DATA | Call data (selector + arguments). |

**`type: "create"`**

| Field | Type | Description |
| --- | --- | --- |
| `from` | DATA, 20 BYTES | Address that initiated the creation. |
| `creationMethod` | String | How the contract was created: `"create"` or `"create2"`. |
| `value` | QUANTITY | Wei value sent to the new contract. |
| `gas` | QUANTITY | Gas provided to the creation. |
| `init` | DATA | Init bytecode (constructor + runtime). |

**`type: "suicide"`** (self-destruct)

| Field | Type | Description |
| --- | --- | --- |
| `address` | DATA, 20 BYTES | Address of the self-destructing contract. |
| `refundAddress` | DATA, 20 BYTES | Address that received the contract's remaining balance. |
| `balance` | QUANTITY | Wei amount transferred to `refundAddress`. |

**`type: "reward"`** (block/uncle reward, in `trace_block` and `trace_filter`)

| Field | Type | Description |
| --- | --- | --- |
| `author` | DATA, 20 BYTES | Address receiving the reward (miner / uncle author). |
| `value` | QUANTITY | Wei amount of the reward. |
| `rewardType` | String | `"block"` or `"uncle"`. |

### Result variants

The `result` object's shape depends on `type`:

**`type: "call"`**

| Field | Type | Description |
| --- | --- | --- |
| `gasUsed` | QUANTITY | Gas consumed by this call frame (excluding subcalls' charges). |
| `output` | DATA | Return data of this call frame (`0x` if no data was returned). |

**`type: "create"`**

| Field | Type | Description |
| --- | --- | --- |
| `gasUsed` | QUANTITY | Gas consumed by the creation. |
| `code` | DATA | Deployed runtime bytecode of the new contract. |
| `address` | DATA, 20 BYTES | Address of the newly deployed contract. |

**`type: "suicide"` and `type: "reward"`**

`result` is `null` — these actions have no return value.

***

## JSON-RPC API Reference

### trace\_call

Executes the given call and returns a number of possible traces for it.

#### Parameters

1. `Object` - \[Transaction object] where `from` field is optional and `nonce` field is omitted.
2. `Array` - Type of trace, one or more of: `"vmTrace"`, `"trace"`, `"stateDiff"`.
3. `Quantity` or `Tag` - (optional) Integer of a block number, or the string `'earliest'`, `'latest'` or `'pending'`.

#### Returns

`Object` containing `output`, `stateDiff`, `trace[]`, `vmTrace`. Each requested trace type is populated; the others are `null`. See [Response Fields Reference](#response-fields-reference) for full field semantics.

#### Example

Request

```bash
curl --data '{"method":"trace_call","params":[{ ... },["trace"]],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
```

Response

```js
{
  "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. i.e. transaction `n` will be executed on top of a pending block with all `n-1` transactions applied (traced) first. Allows to trace dependent transactions.

#### Parameters

1. `Array` - List of trace calls with the type of trace, one or more of: `"vmTrace"`, `"trace"`, `"stateDiff"`.
2. `Quantity` or `Tag` - (optional) integer block number, or the string `'latest'`, `'earliest'` or `'pending'` (default block parameter).

```js
params: [
  [
    [
      {
        "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
        "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
        "value": "0x186a0"
      },
      ["trace"]
    ],
    [
      {
        "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
        "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
        "value": "0x186a0"
      },
      ["trace"]
    ]
  ],
  "latest"
]
```

#### Returns

`Array` — one entry per input call, each shaped like the `trace_call` response (`output`, `stateDiff`, `trace[]`, `vmTrace`). See [Response Fields Reference](#response-fields-reference).

#### Example

Request

```bash
curl --data '{"method":"trace_callMany","params":[[[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]],[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]]],"latest"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
```

Response

```js
{
  "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

#### Parameters

1. `Data` - Raw transaction data.
2. `Array` - Type of trace, one or more of: `"vmTrace"`, `"trace"`, `"stateDiff"`.

```js
params: [
  "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",
  ["trace"]
]
```

#### Returns

`Object` shaped like the `trace_call` response (`output`, `stateDiff`, `trace[]`, `vmTrace`). See [Response Fields Reference](#response-fields-reference).

#### Example

Request

```bash
curl --data '{"method":"trace_rawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",["trace"]],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
```

Response

```js
{
  "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.

#### Parameters

1. `Quantity` or `Tag` - Integer of a block number, or the string `'earliest'`, `'latest'` or `'pending'`.
2. `Array` - Type of trace, one or more of: `"vmTrace"`, `"trace"`, `"stateDiff"`.

```js
params: [
  "0x2ed119",
  ["trace"]
]
```

#### Returns

`Array` — one entry per transaction in the block. Each entry is shaped like the `trace_call` response plus a `transactionHash` field identifying the transaction. See [Response Fields Reference](#response-fields-reference).

#### Example

Request

```bash
curl --data '{"method":"trace_replayBlockTransactions","params":["0x2ed119",["trace"]],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
```

Response

```js
{
  "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.

#### Parameters

1. `Hash` - Transaction hash.
2. `Array` - Type of trace, one or more of: `"vmTrace"`, `"trace"`, `"stateDiff"`.

```js
params: [
  "0x02d4a872e096445e80d05276ee756cefef7f3b376bcec14246469c0cd97dad8f",
  ["trace"]
]
```

#### Returns

`Object` shaped like the `trace_call` response (`output`, `stateDiff`, `trace[]`, `vmTrace`). See [Response Fields Reference](#response-fields-reference).

#### Example

Request

```bash
curl --data '{"method":"trace_replayTransaction","params":["0x02d4a872e096445e80d05276ee756cefef7f3b376bcec14246469c0cd97dad8f",["trace"]],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
```

Response

```js
{
  "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.

#### Parameters

1. `Quantity` or `Tag` - Integer of a block number, or the string `'earliest'`, `'latest'` or `'pending'`.

```js
params: [
  "0x2ed119" // 3068185
]
```

#### Returns

`Array` — flat list of all call frames in the block, including any `"reward"` entries for block/uncle rewards. Each entry includes block-level fields (`blockHash`, `blockNumber`, `transactionHash`, `transactionPosition`). See [Response Fields Reference](#response-fields-reference).

#### Example

Request

```bash
curl --data '{"method":"trace_block","params":["0x2ed119"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
```

Response

```js
{
  "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

#### Parameters

1. `Object` - The filter object
   * `fromBlock`: `Quantity` or `Tag` - (optional) From this block.
   * `toBlock`: `Quantity` or `Tag` - (optional) To this block.
   * `fromAddress`: `Array` - (optional) Sent from these addresses.
   * `toAddress`: `Address` - (optional) Sent to these addresses.
   * `after`: `Quantity` - (optional) The offset trace number
   * `count`: `Quantity` - (optional) Integer number of traces to display in a batch.
   * `mode`: `String` - (optional) Default is `"union"`, meaning traces matching either address filter are returned. Set to `"intersection"` to only return traces that satisfy both `fromAddress` and `toAddress` filters simultaneously.

```js
params: [{
  "fromBlock": "0x2ed0c4", // 3068100
  "toBlock": "0x2ed128", // 3068200
  "toAddress": ["0x8bbB73BCB5d553B5A556358d27625323Fd781D37"],
  "after": 1000,
  "count": 100
}]
```

#### Returns

`Array` — flat list of call frames that match the filter, including any `"reward"` entries when the filter matches block coinbases or uncle authors. Each entry has block-level fields (`blockHash`, `blockNumber`, `transactionHash`, `transactionPosition`). See [Response Fields Reference](#response-fields-reference).

#### Example

Request

```bash
curl --data '{"method":"trace_filter","params":[{"fromBlock":"0x2ed0c4","toBlock":"0x2ed128","toAddress":["0x8bbB73BCB5d553B5A556358d27625323Fd781D37"],"after":1000,"count":100}],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
```

Response

```js
{
  "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.

#### Parameters

1. `Hash` - Transaction hash.
2. `Array` - Index positions of the traces.

```js
params: [
  "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
  ["0x0"]
]
```

#### Returns

A single `TraceEntry` corresponding to the call frame at the requested position, with block-level fields (`blockHash`, `blockNumber`, `transactionHash`, `transactionPosition`). See [Response Fields Reference](#response-fields-reference).

#### Example

Request

```bash
curl --data '{"method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
```

Response

```js
{
  "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

#### Parameters

1. `Hash` - Transaction hash

```js
params: ["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3"]
```

#### Returns

`Array` — flat list of all call frames in the transaction, with block-level fields (`blockHash`, `blockNumber`, `transactionHash`, `transactionPosition`) on each entry. See [Response Fields Reference](#response-fields-reference).

#### Example

Request

```bash
curl --data '{"method":"trace_transaction","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
```

Response

```js
{
  "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"
    },
    ...
  ]
}
```

---

# txpool
URL: https://docs.erigon.tech/interacting-with-erigon/txpool


The `txpool` namespace provides methods for inspecting and managing the transaction pool (mempool) in Erigon. These methods allow you to view pending, queued, and base fee transactions, providing insight into the current state of unconfirmed transactions. In Erigon, the `txpool` namespace is implemented through the `TxPoolAPI` interface and `TxPoolAPIImpl` struct.

The TxPool namespace must be explicitly enabled using the `--http.api` flag when starting the RPC Daemon. These methods are particularly useful for monitoring transaction pool status and debugging transaction submission issues.

### Transaction Pool Architecture

* Erigon's transaction pool is organized into three sub-pools: pending (executable), baseFee (insufficient base fee), and queued (nonce gaps)
* The pool can run either integrated within the main Erigon process or as a separate service for scalability
* Transaction pool methods communicate via gRPC with the TxPool service when running in external mode

### Implementation Details

* The `TxPoolAPIImpl` uses a `proto_txpool.TxpoolClient` to communicate with the transaction pool service
* All transactions are decoded from RLP format and converted to `ethapi.RPCTransaction` objects for JSON-RPC responses
* The implementation handles transaction categorization based on the `TxnType` field from the pool service

### External vs Internal Mode

* **Internal Mode**: Transaction pool runs within the main Erigon process (default configuration)
* **External Mode**: Transaction pool runs as a separate service, requiring explicit configuration with `--txpool.api.addr`. External mode requires an external Sentry service and provides better resource isolation

### Usage in Development and Testing

* These methods are commonly used for monitoring transaction submission and pool state
* The `txpool_status` method provides quick insight into pool health and congestion
* Transaction pool content methods help debug why transactions may not be getting mined

### Configuration and Limits

* Transaction pool limits can be configured via flags like `--txpool.globalslots`, `--txpool.globalbasefeeslots`, and `--txpool.globalqueue`
* The pool supports various transaction types including blob transactions with separate limits
* Pool configuration is managed through the `txpoolcfg.Config` structure

### Availability

* The `txpool` namespace is available when included in the `--http.api` flag
* Methods are marked as "remote" in the documentation, indicating they communicate with external services
* All `txpool` methods are available on both HTTP and WebSocket connections

***

## **txpool\_content**

Returns the content of the transaction pool, organized by sender address and categorized into pending, queued, and baseFee sub-pools.

**Parameters**

None

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"txpool_content","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type    | Description                                         |
| ------- | --------------------------------------------------- |
| Object  | Transaction pool content organized by sub-pool type |
| pending | Object                                              |
| baseFee | Object                                              |
| queued  | Object                                              |

***

## **txpool\_contentFrom**

Returns the content of the transaction pool for a specific sender address, showing all transactions from that address across all sub-pools.

**Parameters**

| Parameter | Type           | Description                                  |
| --------- | -------------- | -------------------------------------------- |
| address   | DATA, 20 BYTES | The sender address to query transactions for |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"txpool_contentFrom","params":["0xb60e8dd61c5d32be8058bb8eb970870f07233155"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type    | Description                                        |
| ------- | -------------------------------------------------- |
| Object  | Transaction pool content for the specified address |
| pending | Object                                             |
| baseFee | Object                                             |
| queued  | Object                                             |

***

## **txpool\_status**

Returns the current status of the transaction pool, including the count of transactions in each sub-pool.

**Parameters**

None

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"txpool_status","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type    | Description                    |
| ------- | ------------------------------ |
| Object  | Transaction pool status counts |
| pending | QUANTITY                       |
| baseFee | QUANTITY                       |
| queued  | QUANTITY                       |

---

# admin
URL: https://docs.erigon.tech/interacting-with-erigon/admin


The `admin` namespace provides administrative methods for managing the Erigon node, including peer management and node information retrieval. These methods are designed for node operators and developers who need to monitor and control various aspects of the Erigon client's operation.

The admin namespace must be explicitly enabled using the `--http.api` flag when starting the RPC Daemon. For security reasons, it's recommended not to include `admin` in the API list for public RPC endpoints.

### Security Considerations

* The admin namespace provides administrative functions that should not be exposed on public RPC endpoints
* When configuring public RPC access, explicitly exclude `admin` from the `--http.api` flag to prevent unauthorized access
* These methods can affect node connectivity and should only be used by trusted operators

### Usage in Testing and Development

* Admin methods are commonly used in automated testing environments for peer management
* The docker-compose configuration for automated testing includes the admin namespace in the API list for testing purposes
* These methods are essential for setting up test networks and managing peer connections programmatically

### Availability

* Admin methods are available when the `admin` namespace is included in the `--http.api` flag
* All admin methods are available on both HTTP and WebSocket connections
* Some admin methods may require the node to be running with specific network configurations

### Integration with P2P Network

* Admin methods interact directly with Erigon's P2P networking layer
* Peer management operations may take time to complete as they involve network operations
* The effectiveness of `admin_addPeer` depends on network connectivity and peer availability

***

## **admin\_nodeInfo**

Returns information about the running node, including network details, protocols, and node identification.

**Parameters**

None

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"admin_nodeInfo","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                                     |
| ------ | --------------------------------------------------------------- |
| Object | Node information object containing network and protocol details |

***

## **admin\_peers**

Returns information about connected peers, including their network addresses, protocols, and connection status.

**Parameters**

None

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"admin_peers","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type  | Description                                                          |
| ----- | -------------------------------------------------------------------- |
| Array | Array of peer objects containing connection and protocol information |

***

## **admin\_addPeer**

Attempts to add a new peer to the node's peer list by connecting to the specified enode URL.

**Parameters**

| Parameter | Type   | Description                                                       |
| --------- | ------ | ----------------------------------------------------------------- |
| enode     | STRING | The enode URL of the peer to add (format: enode://pubkey@ip:port) |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":["enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type    | Description                                              |
| ------- | -------------------------------------------------------- |
| Boolean | True if the peer was successfully added, false otherwise |

***

## **admin\_removePeer**

Removes a peer from the node's peer list by disconnecting from the specified enode URL.

**Parameters**

| Parameter | Type   | Description                                                          |
| --------- | ------ | -------------------------------------------------------------------- |
| enode     | STRING | The enode URL of the peer to remove (format: enode://pubkey@ip:port) |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"admin_removePeer","params":["enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type    | Description                                                |
| ------- | ---------------------------------------------------------- |
| Boolean | True if the peer was successfully removed, false otherwise |

***

## **admin\_addTrustedPeer**

Adds a peer to the trusted peers list. Trusted peers are exempt from the maximum peer count limit and will always be connected, even when the node has reached its peer limit.

**Parameters**

| Parameter | Type   | Description                                                              |
| --------- | ------ | ------------------------------------------------------------------------ |
| enode     | STRING | The enode URL of the trusted peer to add (format: enode://pubkey@ip:port) |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"admin_addTrustedPeer","params":["enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type    | Description                                                       |
| ------- | ----------------------------------------------------------------- |
| Boolean | True if the trusted peer was successfully added, false otherwise  |

***

## **admin\_removeTrustedPeer**

Removes a peer from the trusted peers list. The peer may still remain connected if slots are available, but will no longer bypass the peer limit.

**Parameters**

| Parameter | Type   | Description                                                                 |
| --------- | ------ | --------------------------------------------------------------------------- |
| enode     | STRING | The enode URL of the trusted peer to remove (format: enode://pubkey@ip:port) |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"admin_removeTrustedPeer","params":["enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type    | Description                                                          |
| ------- | -------------------------------------------------------------------- |
| Boolean | True if the trusted peer was successfully removed, false otherwise   |

***

---

# bor
URL: https://docs.erigon.tech/interacting-with-erigon/bor


The `bor` namespace provides Polygon-specific RPC methods that are only available when running Erigon on Polygon networks (Mainnet, Amoy testnet, etc.). These methods expose functionality specific to the Bor consensus engine, including validator information, snapshots, and proposer sequences.

The bor namespace must be explicitly enabled using the `--http.api` flag when starting the RPC Daemon and is only functional when running on Polygon networks with the Bor consensus engine.

### Network Compatibility

* The bor namespace is only available when running Erigon on Polygon networks (Mainnet, Amoy testnet, etc.)
* These methods will return errors if called on non-Polygon networks or when the Bor consensus engine is not active
* The methods require the underlying Bor consensus engine to be properly configured and running

### Consensus Integration

* All bor methods interact directly with the Bor consensus engine and validator set management
* The methods provide access to Polygon's unique consensus features like validator snapshots and proposer sequences
* These APIs are essential for applications that need to understand Polygon's validator dynamics and block production

### Usage in Polygon Ecosystem

* These methods are commonly used by Polygon validators, delegators, and applications that need validator information
* The snapshot and signer methods are particularly useful for understanding the current validator set and their roles
* Root hash methods are used for checkpoint verification and cross-chain communication

***

## **bor\_getSnapshot**

Returns the validator snapshot at a given block number, containing information about the current validator set and their voting power.

**Parameters**

| Parameter | Type          | Description                                     |
| --------- | ------------- | ----------------------------------------------- |
| number    | QUANTITY\|TAG | Block number or "latest", "earliest", "pending" |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getSnapshot","params":["latest"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                                         |
| ------ | ------------------------------------------------------------------- |
| Object | Snapshot object containing validator information and voting details |

***

## **bor\_getAuthor**

Returns the author (block proposer) of a block at the given block number or hash.

**Parameters**

| Parameter     | Type                | Description                      |
| ------------- | ------------------- | -------------------------------- |
| blockNrOrHash | QUANTITY\|TAG\|HASH | Block number, tag, or block hash |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getAuthor","params":["0x1b4"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type           | Description                              |
| -------------- | ---------------------------------------- |
| DATA, 20 BYTES | The address of the block author/proposer |

***

## **bor\_getSnapshotAtHash**

Returns the validator snapshot at a specific block hash.

**Parameters**

| Parameter | Type           | Description       |
| --------- | -------------- | ----------------- |
| hash      | DATA, 32 BYTES | Hash of the block |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getSnapshotAtHash","params":["0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                                                  |
| ------ | ---------------------------------------------------------------------------- |
| Object | Snapshot object containing validator information at the specified block hash |

***

## **bor\_getSigners**

Returns the list of authorized signers (validators) at a given block number.

**Parameters**

| Parameter | Type          | Description                                     |
| --------- | ------------- | ----------------------------------------------- |
| number    | QUANTITY\|TAG | Block number or "latest", "earliest", "pending" |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getSigners","params":["latest"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type  | Description                                            |
| ----- | ------------------------------------------------------ |
| Array | Array of validator addresses authorized to sign blocks |

***

## **bor\_getSignersAtHash**

Returns the list of authorized signers (validators) at a specific block hash.

**Parameters**

| Parameter | Type           | Description       |
| --------- | -------------- | ----------------- |
| hash      | DATA, 32 BYTES | Hash of the block |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getSignersAtHash","params":["0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type  | Description                                                                  |
| ----- | ---------------------------------------------------------------------------- |
| Array | Array of validator addresses authorized to sign blocks at the specified hash |

***

## **bor\_getCurrentProposer**

Returns the address of the current block proposer based on the current validator set and proposer selection algorithm.

**Parameters**

None

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getCurrentProposer","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type           | Description                         |
| -------------- | ----------------------------------- |
| DATA, 20 BYTES | The address of the current proposer |

***

## **bor\_getCurrentValidators**

Returns the current validator set with their details including voting power and other metadata.

**Parameters**

None

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getCurrentValidators","params":[],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type  | Description                                                                 |
| ----- | --------------------------------------------------------------------------- |
| Array | Array of validator objects with their addresses, voting power, and metadata |

***

## **bor\_getSnapshotProposerSequence**

Returns the proposer sequence for a given block, showing the order in which validators are expected to propose blocks.

**Parameters**

| Parameter     | Type                | Description                      |
| ------------- | ------------------- | -------------------------------- |
| blockNrOrHash | QUANTITY\|TAG\|HASH | Block number, tag, or block hash |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getSnapshotProposerSequence","params":["latest"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                                      |
| ------ | ---------------------------------------------------------------- |
| Object | BlockSigners object containing the proposer sequence information |

***

## **bor\_getRootHash**

Returns the root hash for a range of blocks, used for checkpoint verification and state synchronization.

**Parameters**

| Parameter | Type     | Description           |
| --------- | -------- | --------------------- |
| start     | QUANTITY | Starting block number |
| end       | QUANTITY | Ending block number   |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getRootHash","params":["0x1", "0x100"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                 |
| ------ | ------------------------------------------- |
| STRING | The root hash for the specified block range |

***

## **bor\_getVoteOnHash**

Returns voting information for a specific block hash, used in the Bor consensus mechanism.

**Parameters**

| Parameter | Type           | Description                                     |
| --------- | -------------- | ----------------------------------------------- |
| hash      | DATA, 32 BYTES | Hash of the block to get voting information for |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"bor_getVoteOnHash","params":["0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type   | Description                                            |
| ------ | ------------------------------------------------------ |
| Object | Voting information object for the specified block hash |

---

# ots
URL: https://docs.erigon.tech/interacting-with-erigon/ots


In addition to the standard Geth methods, Erigon includes RPC methods prefixed with `ots_` for **Otterscan**. These are specific to the Otterscan functionality integrated with Erigon.

See more details at [https://docs.otterscan.io/api-docs/ots-api](https://docs.otterscan.io/api-docs/ots-api).

---

# internal
URL: https://docs.erigon.tech/interacting-with-erigon/internal


The **`internal_`** methods are for development and debugging utilities and must be explicitly included in the `--http.api` flag if customizing enabled namespaces.

## **internal\_getTxNumInfo**

Returns transaction number information for development and debugging purposes. This is part of Erigon's internal APIs and may change without notice.

**Parameters**

| Parameter | Type     | Description                 |
| --------- | -------- | --------------------------- |
| txNum     | QUANTITY | Internal transaction number |

**Example**

```bash
curl -s --data '{"jsonrpc":"2.0","method":"internal_getTxNumInfo","params":["0x1"],"id":"1"}' -H "Content-Type: application/json" -X POST http://localhost:8545
```

**Returns**

| Type     | Description                    |
| -------- | ------------------------------ |
| Object   | Transaction number information |
| blockNum | QUANTITY                       |
| idx      | QUANTITY                       |

---

# gRPC
URL: https://docs.erigon.tech/interacting-with-erigon/grpc


Erigon provides gRPC APIs that allow users to access blockchain data and services directly through protocol buffer interfaces. These APIs offer high-performance, strongly-typed access to Erigon's internal services and are particularly useful for applications requiring efficient data access or integration with other gRPC-based systems.

The gRPC server can be explicitly enabled using the `--grpc` flag when running the **standalone `rpcdaemon`** binary. This flag is **not available** on the main `erigon` binary — internal gRPC services for components like TxPool, Downloader, and Sentry start automatically on the `--private.api.addr` endpoint and do not require any additional flag.

### Performance Considerations

* gRPC APIs provide better performance than JSON-RPC for high-throughput applications
* Direct database access via KV interface offers the fastest data retrieval
* Shared memory access (when running locally) provides optimal performance

### Data Format and Buckets

Database bucket names and their formats are documented in `db/kv/tables.go`. Understanding these structures is essential for effective use of the KV interface.

### Network Access

* gRPC services can be accessed over the network when properly configured
* TLS encryption is recommended for production deployments
* Rate limiting can be configured via `--private.api.ratelimit` flag

### Integration Libraries

Erigon provides Go, Rust, and C++ implementations of the RoKV (read-only key-value) interface for easy integration with applications.

### Availability

* gRPC services are available when enabled with the `--grpc` flag on the **standalone `rpcdaemon`** binary
* Default listening address is configurable via `--grpc.addr` and `--grpc.port`
* Services require the main Erigon node to be running and accessible

For more information, visit the [Erigon Interfaces GitHub repository](https://github.com/erigontech/interfaces).

***

## **KV (Key-Value) Interface**

The KV interface provides low-level database access methods for reading blockchain data directly from Erigon's MDBX database.

**Interface Definition**

The KV interface is defined in the remote protobuf specification and provides methods for:

* Opening read-only transactions
* Reading data by key ranges
* Iterating over database buckets
* Accessing historical state data

**Example Usage**

```bash
# Connect to gRPC endpoint
grpcurl -plaintext localhost:9090 remote.KV/Version
```

**Available Methods**

| Method       | Description                                   |
| ------------ | --------------------------------------------- |
| Version      | Returns the KV service API version            |
| Tx           | Opens a read-only transaction for data access |
| StateChanges | Streams state changes for a block range       |
| Snapshots    | Returns information about available snapshots |

***

## **ETHBACKEND Interface**

The ETHBACKEND interface provides access to Ethereum-specific backend services including block data, transaction information, and network status.

**Available Services**

| Service         | Description                                         |
| --------------- | --------------------------------------------------- |
| Etherbase       | Returns the coinbase address                        |
| NetVersion      | Returns the network ID                              |
| NetPeerCount    | Returns the number of connected peers               |
| ProtocolVersion | Returns the Ethereum protocol version               |
| ClientVersion   | Returns the client version string                   |
| Subscribe       | Subscribes to blockchain events                     |
| NodeInfo        | Returns node information                            |
| Peers           | Returns information about connected peers           |
| AddPeer         | Adds a peer to the node                             |
| PendingBlock    | Returns the pending block                           |
| BorEvent        | Returns Bor-specific events (Polygon networks only) |

***

## **TxPool Interface**

The TxPool interface provides access to transaction pool operations and status information.

**Available Methods**

| Method            | Description                               |
| ----------------- | ----------------------------------------- |
| Version           | Returns the TxPool service version        |
| FindUnknownHashes | Finds unknown transaction hashes          |
| GetTransactions   | Retrieves transactions from the pool      |
| All               | Returns all transactions in the pool      |
| PendingAdd        | Adds transactions to pending pool         |
| PendingRemove     | Removes transactions from pending pool    |
| OnAdd             | Subscribes to transaction addition events |
| Mining            | Returns mining-related transaction data   |
| NonceFromAddress  | Gets the next nonce for an address        |

***

## **Downloader Interface**

The Downloader interface provides access to snapshot downloading and torrent management functionality.

**Available Methods**

| Method       | Description                        |
| ------------ | ---------------------------------- |
| Add          | Adds files to download queue       |
| Delete       | Removes files from download queue  |
| Completed    | Checks if downloads are completed  |
| SetLogPrefix | Sets logging prefix for Downloader |

***

## Polygon Bridge Backend gRPC API

These gRPC APIs are specifically designed for Polygon's Bor consensus mechanism and are only active when running Erigon with Polygon network configuration. The services provide essential functionality for bridge event processing and validator management required by the Polygon network architecture.

### Bridge Backend Methods

**Version Method:**

* `Version()` - Returns the service version number.

**Transaction Lookup:**

* `BorTxnLookup(BorTxnLookupRequest)` - Looks up Bor transaction information by hash.

**Event Retrieval:**

* `BorEvents(BorEventsRequest)` - Retrieves bridge events for a specific block.

### Bridge Backend Implementation

The server implementation is found in `polygon/bridge/server.go` where the `BackendServer` struct implements the `BridgeBackendServer` interface:

* The `BorTxnLookup` method implementation shows how it handles transaction lookups.
* The `BorEvents` method retrieves bridge events for a given block.

## Heimdall Backend gRPC API

The Heimdall Backend service provides APIs for validator and consensus-related functionality.

### Heimdall Backend Methods

**Version Method:**

* `Version()` - Returns the service version number.

**Producer Information:**

* `Producers(BorProducersRequest)` - Retrieves validator/producer information for a specific block.

## Service Integration

Both services are integrated into the main Ethereum backend when Bor consensus is configured. In the main backend initialization, you can see how these services are set up.

The Bridge and Heimdall services are created with their respective RPC servers.

***

## Configuration and Security

### TLS Configuration

Erigon supports TLS encryption for gRPC connections using certificate files:

```bash
./build/bin/rpcdaemon --grpc --tls.cert=/path/to/cert.pem --tls.key=/path/to/key.pem --tls.cacert=/path/to/ca.pem
```

### Health Checks

gRPC health checks can be enabled to monitor service availability:

```bash
./build/bin/rpcdaemon --grpc --grpc.healthcheck
```

### Connection Examples

**Go Client Example**

```go
conn, err := grpc.Dial("localhost:9090", grpc.WithInsecure())
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

client := remote.NewKVClient(conn)
// Use client for database operations
```

**Direct Database Access**

The gRPC interface allows reading Erigon's database while the node is running, sharing the same OS-level PageCache for optimal performance.

---

# overlay
URL: https://docs.erigon.tech/interacting-with-erigon/overlay


The `overlay` namespace is an **Erigon-specific** extension that allows you to replay historical blocks with a modified contract bytecode, without deploying anything on-chain. It is designed for analytics use cases where you need to inject custom event emissions into an existing contract and retrieve the logs those events would have produced.

:::warning
The `overlay` namespace requires **historical state to be available**. All methods replay historical transactions and state — a node with sufficient history retention (e.g. `--prune.mode=archive`) is needed; the methods will fail if the requested block's state has been pruned.
:::

Enable the namespace with `--http.api=...,overlay`.

## Timeouts

Two flags control how long overlay operations can run:

* `--rpc.overlay.getlogstimeout` — overall timeout for an `overlay_getLogs` call (default: `5m0s`)
* `--rpc.overlay.replayblocktimeout` — per-block replay timeout within a `getLogs` call (default: `10s`)

---

## Methods

### `overlay_getLogs`

Replays a range of historical blocks with an optional **state override** (modified bytecode, balance, nonce, or storage) and returns the logs that would have been emitted.

This is equivalent to running `eth_getLogs` on a hypothetical version of the contract — useful for retroactively adding event emissions to contracts that were deployed without them.

**Parameters**

| # | Name | Type | Description |
|---|------|------|-------------|
| 1 | `filter` | `FilterCriteria` | Same filter object as `eth_getLogs`: `fromBlock`, `toBlock`, `address`, `topics` |
| 2 | `stateOverride` | `StateOverride` (optional) | Map of `address → overrides`. Each override can set `code`, `balance`, `nonce`, `state` (full state replacement), or `stateDiff` (partial state patch). Same format as the state override in `eth_call`. |

**Returns**

Array of log objects (same structure as `eth_getLogs`).

**Example**

```bash
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "overlay_getLogs",
    "params": [
      {
        "fromBlock": "0x1000000",
        "toBlock":   "0x1000010",
        "address":   "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      },
      {
        "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": {
          "code": "0x<your_modified_bytecode>"
        }
      }
    ],
    "id": 1
  }'
```

Blocks in the requested range are replayed concurrently (up to `runtime.NumCPU()` workers). Each block is independently replayed from the state at `blockNumber - 1`.

---

### `overlay_callConstructor`

Replays the **constructor transaction** of an existing contract using a different bytecode and returns the effective creation code that would have been stored.

This is useful for understanding what a contract would have initialised to if it had been deployed with different logic, without redeploying anything.

**Parameters**

| # | Name | Type | Description |
|---|------|------|-------------|
| 1 | `address` | `Address` | The address of the already-deployed contract |
| 2 | `code` | `Bytes` | The replacement bytecode to use instead of the original deployment bytecode |

**Returns**

```json
{ "code": "0x<effective_creation_code>" }
```

**Example**

```bash
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "overlay_callConstructor",
    "params": [
      "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "0x<your_replacement_bytecode>"
    ],
    "id": 1
  }'
```

Internally, this method:
1. Looks up the contract's creation transaction via the Otterscan API
2. Replays all transactions in that block up to (but not including) the creation tx
3. Executes the creation tx using the provided bytecode instead of the original
4. Returns the effective code that would have been stored at the contract address

:::info
`overlay_callConstructor` requires the Otterscan API (`--http.api=...,ots,overlay`) to resolve the contract creation transaction.
:::

---

# parity
URL: https://docs.erigon.tech/interacting-with-erigon/parity


The `parity` namespace provides a limited subset of the OpenEthereum (formerly Parity) JSON-RPC API for compatibility with tooling that targets the original Parity client.

:::warning
Only **one** method from the original OpenEthereum `parity_*` specification is implemented in Erigon. All other `parity_*` methods (account management, vault, signing, transaction queue, etc.) are not supported. Use the equivalent `eth_*` methods instead.
:::

Enable the namespace with `--http.api=...,parity`.

For the full original OpenEthereum `parity_*` specification, see the [OpenEthereum JSON-RPC parity module documentation](https://openethereum.github.io/JSONRPC-parity-module) (archived).

---

## Methods

### `parity_listStorageKeys`

Returns all storage keys for a given contract address, paginated.

**Parameters**

| # | Name | Type | Description |
|---|------|------|-------------|
| 1 | `address` | `Address` | The contract address to query storage for |
| 2 | `quantity` | `integer` | Number of storage keys to return |
| 3 | `offset` | `Bytes` (optional) | Pagination offset — the storage key to start from |
| 4 | `blockNumber` | `BlockNumberOrHash` | Block to query. Must be `"latest"` (other tags and block numbers are not supported) |

**Returns**

Array of storage key hashes (`Bytes[]`).

**Example**

```bash
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "parity_listStorageKeys",
    "params": [
      "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      10,
      null,
      "latest"
    ],
    "id": 1
  }'
```

---

# GraphQL
URL: https://docs.erigon.tech/interacting-with-erigon/graphql


Erigon implements the standard Ethereum GraphQL interface defined in [EIP-1767](https://eips.ethereum.org/EIPS/eip-1767), following the same schema as Geth.

## Enabling GraphQL

GraphQL is disabled by default. Enable it with the `--graphql` flag:

```bash
./erigon --graphql
```

GraphQL shares the same port as the HTTP JSON-RPC server (default `8545`). It does **not** use `--http.api` — `--graphql` is its own toggle.

## Endpoints

| Endpoint | Purpose |
|----------|---------|
| `http://localhost:8545/graphql` | GraphQL API endpoint |
| `http://localhost:8545/graphql/ui` | GraphiQL browser UI for interactive queries |

## Schema Reference

Erigon follows the Geth GraphQL schema. For the full schema reference, query examples, and field descriptions, see https://geth.ethereum.org/docs/interacting-with-geth/rpc/graphql.

The schema includes queries for blocks, transactions, accounts, logs, and pending state, as well as the `sendRawTransaction` mutation.

## Example Query

```graphql
{
  block(number: 21000000) {
    hash
    number
    timestamp
    transactions {
      hash
      from { address }
      to { address }
      value
    }
  }
}
```

```bash
curl -X POST http://localhost:8545/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ block(number: 21000000) { hash number } }"}'
```

---

# Staking
URL: https://docs.erigon.tech/staking

Run an Ethereum validator with Erigon — using the built-in Caplin consensus layer or any external CL client.

## Sections

- [Caplin (Built-in CL)](https://docs.erigon.tech/staking/caplin): Configure Erigon's embedded consensus layer as a full validator — no external CL dependency required.
- [External Consensus Client](https://docs.erigon.tech/staking/external-consensus-client-as-validator): Connect Lighthouse, Prysm, Teku, or Nimbus via the Engine API for split EL/CL validator setups.
- [Shutter Network](https://docs.erigon.tech/staking/shutter-network): Privacy-preserving mempool protection — shield validator transactions from front-running and MEV.

---

# Using Caplin as Validator
URL: https://docs.erigon.tech/staking/caplin


Caplin, the Erigon embedded Consensus Layer, is also suitable for staking. However, it is required to pair it with a **validator key manager**, such as Lighthouse or Teku, since it doesn't have a native key management system.

This guide explains how to use Erigon with its embedded Caplin consensus layer and Lighthouse as the validator client for staking on Ethereum.

## 1. Start Erigon with Caplin

The following command starts Erigon with the embedded Caplin consensus layer with the beacon API on:

```bash
erigon \
  --datadir=/data/erigon \
  --http \
  --http.addr=0.0.0.0 \
  --http.port=8545 \
  --http.api=engine,eth,net,web3 \
  --ws \
  --ws.port=8546 \
  --caplin.enable-upnp \
  --caplin.discovery.addr=0.0.0.0 \
  --caplin.discovery.port=4000 \
  --caplin.discovery.tcpport=4001 \
  --beacon.api=beacon,validator,builder,config,debug,events,node,lighthouse 
```

**Flags Explanation**:

* Execution Layer (Erigon):
  * `--http.api=engine,eth,net,web3`: enables the necessary APIs for external clients and Caplin.
  * `--ws`: enables WebSocket-based communication (optional).
* Consensus Layer (Caplin):
  * `--caplin.discovery.addr` and `--caplin.discovery.port`: configures Caplin's gossip and discovery layer.
  * `--beacon.api=beacon,validator,builder,config,debug,events,node,lighthouse`: enables all possible API endpoints for the validator client.

## 2. Set Up Lighthouse Validator Client

### 2.1 Install Lighthouse

Install and run Lighthouse by following the official guide at [https://lighthouse-book.sigmaprime.io/installation.html](https://lighthouse-book.sigmaprime.io/installation.html) or use Docker:

```bash
docker pull sigp/lighthouse:latest
```

### 2.2. Create Lighthouse Validator Key Directory

```bash
mkdir -p ~/.lighthouse/validators
```

### 2.3. Run Lighthouse Validator Client

Start the validator client and connect it to the Caplin CL:

```bash
lighthouse vc \
  --network mainnet \
  --beacon-nodes http://127.0.0.1:5555 \
  --suggested-fee-recipient=<your_eth_address>
```

**Flags Explanation**:

* `--network mainnet`: Specifies the Ethereum mainnet.
* `--beacon-nodes`: Points to the Caplin beacon API at `http://127.0.0.1:5555`.
* `--suggested-fee-recipient`: Specifies your Ethereum address for block rewards.

### 2.4. Import Validator Keys

If you have existing validator keys, import them:

```bash
lighthouse account validator import --directory <path_to_validator_keys>
```

---

# Using an external consensus client as validator
URL: https://docs.erigon.tech/staking/external-consensus-client-as-validator


To use an external Consensus Layer (CL) it is necessary to add to Erigon the flag `--externalcl`. Here are a couple of examples on how to configure Lighthouse and Prysm to run along with Erigon:

* [Ethereum](../get-started/easy-nodes/how-to-run-an-ethereum-node/ethereum-with-an-external-cl)
* [Gnosis Chain](../get-started/easy-nodes/how-to-run-a-gnosis-chain-node/gnosis-with-an-external-cl)

Once you have Erigon and a CL client up and running, you can proceed to set up a Validator Client (VC). The VC is responsible for managing your keys and signing valid blocks.

## Getting Started with a Validator Client

To set up a VC, follow the instructions provided in the official documentation, such as:

[https://lighthouse-book.sigmaprime.io/mainnet_validator.html](https://lighthouse-book.sigmaprime.io/mainnet_validator.html).

This guide will walk you through the process of setting up a VC, including:

* Generating and managing your keys
* Configuring the Validator Client
* Signing valid blocks

Make sure to follow the instructions carefully and thoroughly to ensure that your VC is set up correctly. It is always recommended to start staking with a testnet.

## Example of configuration

The following example demonstrates how to configure Erigon to run with an external Consensus Layer:

```bash
erigon \
  --externalcl \
  --datadir=/data/erigon \
  --chain=sepolia \
  --authrpc.jwtsecret=/jwt \
  --authrpc.addr=0.0.0.0 \
  --http \
  --http.addr=0.0.0.0 \
  --http.port=8545 \
  --http.api=engine,eth,net,web3 \
  --ws \
  --ws.port=8546 \
```

## Flags explanation:

* `--externalcl`: Enables the use of an external CL.
* `--datadir=/data/erigon`: Defines the directory to be used for databases.
* `--chain=sepolia`: Specifies the Sepolia chain.
* `--authrpc.jwtsecret=/jwt`: Sets the location of the JWT authentication code in hex encoding. This is used by Erigon (the EL) and the CL (in this case Lighthouse) to authenticate communication.
* `--authrpc.addr=0.0.0.0`: Allows the engine API to be accessed from any address.
* `--http.api=engine,eth,net,web3`: Enables the necessary APIs for external clients and Caplin.
* `--ws`: enables WebSocket-based communication, which is optional.

:::info
Note that many pre-merge flags, such as `--miner.etherbase`, are no longer useful, as block rewards and other validator-related configurations are now controlled by the Consensus Layer (CL).
:::

---

# Shutter Network
URL: https://docs.erigon.tech/staking/shutter-network


[Shutter Network](https://www.shutter.network) is a privacy-focused protocol that provides encrypted transaction pools using threshold encryption. The main objective is to protect users from malicious MEV (Miner Extractable Value) attacks such as front-running and sandwich attacks by encrypting transactions until they are included in a block.

The key advantages of Shutter Network are:

* **Protection against MEV attacks:** By encrypting transactions, the network prevents malicious actors from exploiting transaction ordering.
* **Threshold encryption:** Transactions are only decrypted when enough key holders (keypers) participate, ensuring security and decentralization.
* **Support on Gnosis Chain:** Shutter encrypted transaction pools are currently available on [Gnosis Chain](https://docs.gnosischain.com/shutterized-gc/), with plans for Ethereum support.

### Why Use Shutter?

* **Access to Extra Transactions:** Shutterized validators can include shielded transactions not available in the public transaction pool, leading to potentially higher block rewards.
* **User Protection:** Help protect users against MEV attacks, improving the fairness of the chain.

## How to Run Erigon as a Shutterized Validator

To participate in the Shutter encrypted transaction pool as a validator using Erigon, follow these steps:

1.  **Set Up Your Validator**

    Deposit your stake and register your validator on Gnosis Chain reby following the [Gnosis Chain Validator Setup](https://docs.gnosischain.com/node/manual/validator/deposit).
2.  **Register as a Shutterized Validator**

    Complete the validator registration for Shutter using the tool provided in the [Shutter Validator Registration Guide](https://github.com/shutter-network/shutter-validator-registration).
3.  **Verify Registration**

    Use the Erigon CLI command to verify that your registration was successful:
```bash
    erigon shutter-validator-reg-check --chain <CHAIN> --el-url <EL_RPC_URL> --validator-info-file <VALIDATOR_INFO_JSON>
    ```
* `--chain` valid values are `gnosis` or `chiado`
    * `--el-url`, in case you are using Erigon default ports is `http://localhost:8545`
    * `<VALIDATOR_INFO_JSON>` is the file generated during registration.

    for example:
```bash
    erigon shutter-validator-reg-check --chain gnosis --el-url http://localhost:8545 --validator-info-file /path/validatorInfo.json
    ```
4. **Run Erigon with Shutter Support**

    Start Erigon as usual, but add the `--shutter` flag to enable Shutterized Validator mode:

    ```bash
    erigon --shutter [other options...]
    ```

    This works with Erigon's internal CL Caplin (enabled by default) or with an external CL client using `--externalcl`.

## Shutter Network Default Ports

The default peering port for Shutter is `23102` (TCP), to change it use `--shutter.p2p.listen.port <value>`.

Bootstrap nodes are used to help new nodes discover other nodes in the network. By default, the embedded configuration values are used, but these can be overridden with `--shutter.p2p.bootstrap.nodes <value>`.

## Reference Documentation

* [Shutter Validator Registration](https://github.com/shutter-network/shutter-validator-registration)
* [Shutter Specs](https://github.com/gnosischain/specs/tree/master/shutter)
* [System Overview Dashboard](https://explorer.shutter.network/system-overview)
* [Gnosis Chain Validator Setup](https://docs.gnosischain.com/node/manual/validator/deposit)

---

# About
URL: https://docs.erigon.tech/about

Learn about the project, how to get involved, and the license terms.

## Sections

- [Contributing](https://docs.erigon.tech/about/contributing): How to contribute code, report bugs, write docs, and submit pull requests to the Erigon project.
- [Disclaimer](https://docs.erigon.tech/about/disclaimer): Important notices about software maturity, stability expectations, and intended use.
- [License](https://docs.erigon.tech/about/license): Erigon's open-source licensing terms and third-party attribution.

---

# Contributing
URL: https://docs.erigon.tech/about/contributing


## Erigon Client Code

The Erigon node software is developed in the [erigontech/erigon](https://github.com/erigontech/erigon) repository. Code contributions follow the standard GitHub fork-and-PR workflow.

### Getting started

1. Fork the repository and clone your fork:
   ```bash
   git clone https://github.com/<your-username>/erigon.git
   cd erigon
   ```
2. Build the project (requires Go 1.25+ and a C++ compiler):
   ```bash
   make erigon
   ```
3. Run the test suite:
   ```bash
   go test ./...
   ```

### Reporting bugs and requesting features

- **Bugs:** open a [GitHub issue](https://github.com/erigontech/erigon/issues/new?template=bug_report.md) with steps to reproduce, your OS, Go version, and Erigon version.
- **Feature requests:** open an issue describing the use case and expected behaviour before writing any code — this avoids wasted effort if the direction needs alignment.
- For questions or informal discussion, join the [Erigon Discord](https://discord.gg/e8MBWss7uJ).

### Opening a pull request

- Target the `main` branch for new features and non-critical fixes.
- Target the relevant `release/x.y` branch for release-specific backports.
- Keep PRs focused — one logical change per PR makes review faster.
- Feel free to open a draft PR early if you want feedback on the direction before the implementation is complete.
- Include a clear description of what changed, why, and how it was tested.

### Code style and guidelines

- Follow the existing Go conventions in the codebase.
- Run `make lint` before submitting — the CI will enforce it.
- All new code should be covered by tests where practical.
- Use the package-prefix commit message format: `eth, rpc: make trace configs optional`. This keeps the git log scannable by subsystem.

## Documentation

The Erigon documentation is built with [Docusaurus](https://docusaurus.io) and lives in the [erigontech/erigon](https://github.com/erigontech/erigon) repository under `docs/site/`.

### Reporting issues

Open an issue in the repository to suggest corrections, flag outdated content, or request new pages.

### Editing locally

1. Clone the repository and install dependencies:
   ```bash
   git clone https://github.com/erigontech/erigon.git
   cd erigon/docs/site
   npm install
   ```
2. Start the local dev server:
   ```bash
   npm run start
   ```
3. Open `http://localhost:3000` in your browser — changes to Markdown files hot-reload automatically.

### Submitting a pull request

1. Create a new branch from `release/3.4`.
2. Edit or add `.md` / `.mdx` files under `docs/site/docs/`.
3. Verify your changes render correctly in the local dev server.
4. Open a pull request against `release/3.4` with a clear description of what changed and why.

---

# License
URL: https://docs.erigon.tech/about/license


© 2026 Erigon Technologies AG. All rights reserved.

Licensed under the [LGPL-3.0](https://github.com/erigontech/erigon/blob/release/2.60/COPYING.LESSER), [GPL-3.0](https://github.com/erigontech/erigon/blob/release/2.60/COPYING).

_Permissions of this copyleft license are conditioned on making available complete source code of licensed works and modifications under the same license or the GNU GPLv3. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work through interfaces provided by the licensed work may be distributed under different terms and without source code for the larger work._

---

# Disclaimer
URL: https://docs.erigon.tech/about/disclaimer


The Erigon team does not take any responsibility for losses or damages occurred through the use of Erigon. While we employ a seasoned in-house security team, we have not subjected our systems to independent third-party security assessments.

---

# Help Center
URL: https://docs.erigon.tech/help-center

Everything you need to run Erigon smoothly — from quick answers to deep diagnostics.

## Sections

- [FAQ](https://docs.erigon.tech/help-center/frequently-asked-questions-faqs): Answers to the most common questions about installing, syncing, and operating Erigon.
- [Troubleshooting](https://docs.erigon.tech/help-center/troubleshooting): Step-by-step diagnostic guides for the most frequent runtime and sync issues.
- [Known Issues](https://docs.erigon.tech/help-center/known-issues): Current confirmed bugs, limitations, and active workarounds for this release.
- [Best Practices](https://docs.erigon.tech/help-center/best-practices): Recommended configurations, operational patterns, and tips for stable long-running nodes.
- [Common Errors & Solutions](https://docs.erigon.tech/help-center/common-errors-and-solutions): Error messages decoded — causes explained and actionable fixes provided.
- [Glossary](https://docs.erigon.tech/help-center/glossary-of-key-terms): Definitions of Erigon-specific and Ethereum ecosystem terminology used throughout the docs.

---

# Frequently Asked Questions (FAQs)
URL: https://docs.erigon.tech/help-center/frequently-asked-questions-faqs


This list addresses the most common inquiries from the Erigon community, offering quick and direct answers to a variety of topics.

1. **What is the difference between Erigon and Geth?** Erigon originated as a fork of Geth but has been entirely rewritten with a focus on disk space and sync speed. It uses a flat, key-value database (MDBX) instead of a Merkle Patricia Trie, resulting in a much smaller disk footprint and faster synchronization times.
2. **Is Erigon a good choice for client diversity?** Yes. The codebases have diverged so significantly from Geth that they are now considered separate clients, making Erigon an excellent choice to support Ethereum's client diversity goals.
3. **What are the minimum hardware requirements?** The most critical component is a high-end NVMe or SSD with very low latency. While the exact requirements vary by network, 16GB of RAM and a fast SSD are generally the minimum for a full node. See [Hardware Requirements](/get-started/hardware-requirements) for detailed specs per network and pruning mode.
4. **How long does it take to sync a node?** Initial synchronization time is highly dependent on hardware and bandwidth. A fast system with a high-end NVMe can sync a full node in as little as few hours, while on slower hardware, it can take several days.
5. **How much disk space is required?** Disk space needs are constantly changing as the blockchain grows. As of September 2025, an Ethereum Mainnet full node requires about 920GB, while an archive node is significantly larger at around 1.77TB. See [Hardware Requirements](/get-started/hardware-requirements) for up-to-date figures.
6. **Can I run Erigon on an HDD?** It is not recommended to run Erigon on an HDD. The client's performance is critically dependent on high-speed disk I/O, and an HDD will almost certainly cause the node to fall behind the blockchain tip.
7. **What is the `--prune.mode` flag, and which mode should I use?** This flag determines which historical data is discarded. The `full` mode (the default for Erigon 3) is suitable for most users. The `minimal` mode is for validators with limited disk space. The `archive` mode is for those who need a full historical record for all past states. See [Pruning Modes](/fundamentals/pruning-modes) for a full comparison.
8. **Can I change my pruning mode after starting the node?** No. The pruning mode is a permanent choice made at the first sync. Changing it requires deleting the `datadir` directory and a full re-sync from scratch.
9. **Do I need a separate consensus client?** No, you don't need a separate consensus client. In many cases, it's fine to use [Caplin](/staking/caplin), the embedded consensus client that runs by default within Erigon. However, some users, especially validators, prefer to run a [separate consensus client](/staking/external-consensus-client-as-validator) for enhanced reliability.
10. **How do I upgrade my Erigon binary?** The process involves gracefully shutting down the node, replacing the old binary with the new one, and restarting. See the [Upgrading](/get-started/installation/upgrading) guide for step-by-step instructions. It is also recommended to back up your datadir before any major upgrade.
11. **How do I gracefully shut down Erigon?** The safest way to shut down is by using a process manager like `systemd` or `supervisor`. Alternatively, you can press `Ctrl+C` in the terminal to allow the database to close cleanly.
12. **What is Erigon's RPC daemon?** The [RPC daemon](/fundamentals/modules/rpc-daemon) is a separate process that handles JSON RPC API requests. It can run on a different machine from the core Erigon client to enhance security and scalability.
13. **Is it possible to recover from a database corruption?** While Erigon's database is robust, an ungraceful shutdown can cause corruption. The most reliable solution is to delete the corrupted datadir and perform a full re-sync, but it is also worth using repair tools.
14. **What are the required ports?** Erigon requires specific ports for P2P networking (default `30303` TCP/UDP) and RPC access (`8545` HTTP, `8546` WS, `8551` Engine API). See [Default Ports](/fundamentals/default-ports) for the complete list.
15. **What is a "snapshot sync"?** Snapshot sync is a stage of the synchronization process where the node downloads pre-made snapshots of the blockchain state. This significantly accelerates the initial sync, reducing the time required to catch up with the network. See [Pruning Modes](/fundamentals/pruning-modes) for details.
16. **How do I monitor my node's sync progress?** There are three complementary ways:

    * **Read the live log line** — every sync log line is prefixed with the current stage and its position in the pipeline, e.g. `[4/8 Bodies]`. The prefix advances through the stages until `[8/8 Finish]`, at which point the node is at the chain tip. See [Logs → Stage Definitions](/fundamentals/logs#stage-definitions) for the full ordered list.
    * **Query the JSON-RPC** — call `eth_syncing` against the RPC daemon (default port `8545`):

      ```bash
      curl -s -X POST -H "Content-Type: application/json" \
        --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
        http://localhost:8545
      ```

      While syncing the result is an object with `currentBlock`, `highestBlock`, and a `stages` array (per-stage progress, matching the log prefix); once fully synced it is simply `false`. (`startingBlock` is also returned but is hardcoded to `"0x0"`.)
    * **Ask an AI assistant via MCP** — Erigon's built-in [MCP server](/fundamentals/mcp) (default `127.0.0.1:8553`) lets a connected assistant like Claude Desktop answer questions like *"Is my node synced? How many blocks behind am I?"* in plain language by querying the same data the JSON-RPC exposes. Useful when you'd rather not parse logs or `eth_syncing` output by hand.
17. **Can I use Erigon with Docker?** Yes, Erigon provides official Docker images on Dockerhub. See the [Installation](/get-started/installation) guide for the Docker setup instructions.
18. **Does Erigon support other chains besides Ethereum?** Yes, Erigon is an EVM-compatible client and supports other networks like Gnosis. You can specify the chain with the `--chain` flag. See [Supported Networks](/fundamentals/supported-networks) and the [Easy Nodes](/get-started/easy-nodes) guides for chain-specific setup.
19. **Where can I find official support?** The primary channels for support and community discussions are the official Erigon Discord and GitHub repository.
20. **What is Caplin?** [Caplin](/staking/caplin) is Erigon's built-in beacon API server. It allows Erigon to function as both a consensus and execution client.
21. **What is OtterSync?** OtterSync is a syncing algorithm that further enhances performance by shifting 98% of the computation to network bandwidth, reducing synchronization times and improving chain tip performance, disk footprint, and decentralization.
22. **Why can't I query blocks before a certain height?** In `full` and `minimal` pruning modes, Erigon discards historical state data that is older than the pruning window. If you need to query early blocks, you must run an archive node (`--prune.mode=archive`). See [Pruning Modes](/fundamentals/pruning-modes) for more on pruning. Note that the pruning mode is set permanently at the first sync and cannot be changed without a full re-sync.
23. **Can I run Erigon on a Raspberry Pi or low-power ARM device?** It is not recommended for Mainnet. Erigon requires a high-end NVMe SSD and sufficient RAM (16 GB minimum) for reliable operation. Low-power ARM devices typically lack the disk I/O performance and memory needed to keep up with the chain tip. See [Hardware Requirements](/get-started/hardware-requirements). A testnet like Sepolia may be feasible on higher-end ARM hardware, but expect limited performance.
24. **What is the MCP server?** The MCP (Model Context Protocol) server is a built-in component that exposes Erigon's blockchain data to AI assistants like Claude Desktop. It is enabled by default and listens on `127.0.0.1:8553`. To disable it, pass `--mcp.disable` at startup.
25. **How do I connect Claude Desktop to my Erigon node?** Build the standalone `mcp` binary with `make mcp`, then add it to your Claude Desktop configuration at `~/.config/claude-desktop/config.json` pointing to your node's JSON-RPC endpoint or datadir. See the [MCP Server](/fundamentals/mcp) page for the full configuration example.

---

# Troubleshooting
URL: https://docs.erigon.tech/help-center/troubleshooting


## Resilience and Data Integrity

Erigon is highly resilient and uses a fully-transactional database. This design makes it safe against hard termination (`kill -9`) and power outages. The database ensures users never see "partial writes," meaning all data changes are atomic (all-or-nothing), and all RPC methods operate within Read-Only Transactions, guaranteeing a consistent data view.

**Protect Against Hardware Failure**: True data corruption is typically only caused by hardware failures (like disk or RAM failure). We strongly recommend using ECC memory, disk RAID, and performing regular backups to mitigate these risks.

When an issue arises, follow these steps to methodically diagnose and resolve the problem.

1. **Check Hardware Requirements:** The most common cause of issues is insufficient disk or RAM. Ensure your system meets the recommended [Hardware Requirements](/get-started/hardware-requirements). Note that Erigon is very adaptive—adding more RAM to the server will make Erigon faster without requiring any setting changes.
2. **Inspect Erigon Logs:** The logs are your best friend. Use `tail -f erigon.log` or `journalctl` to see real-time output and identify error messages or warnings. See [Logs](/fundamentals/logs) for log configuration options.
3. **Verify Sync Status:** Use `curl localhost:8545 \-X POST \-H "Content-Type: application/json" \--data '{"jsonrpc":"2.0","method":"eth\_syncing","params":\[\],"id":1}'` to check if the node is actively syncing.
4. **Monitor System Resources:** Use `htop`, `top`, or `iostat` to monitor CPU, RAM, and disk I/O. This can help you identify a performance bottleneck. For a full monitoring dashboard, see [Creating a Dashboard](/fundamentals/creating-a-dashboard).
5. **Look for OOM-kill events:** After an unexpected crash, always check your system logs for an "Out of Memory" killer event. This confirms if a memory issue caused the crash.
6. **Perform a Simple Restart**: If the node is stalled, simply restart the service using `systemctl restart erigon`. Erigon's transactional database is designed to handle interruption gracefully.
7. **Disable RPC/CL during Initial Sync**: If you are stalling during snapshot sync, try restarting without the [RPC daemon](/fundamentals/modules/rpc-daemon) or consensus client to reduce concurrent disk access, which is a bottleneck during the slowest stage (Blocks Execution).
8. **Check for Disk Space:** Regularly check your disk usage. A full disk will cause performance degradation and can lead to a node crash. See [Optimizing Storage](/fundamentals/optimizing-storage) for tips on reducing disk usage.
9. **Verify Network Time:** Ensure your system's clock is synchronized. Incorrect time can cause issues with block propagation.
10. **Check P2P Peer Connections:** Use `net\_peerCount` or similar RPC methods to check if you have a healthy number of peers. A low count may indicate a network problem. See [Default Ports](/fundamentals/default-ports) to verify firewall rules allow P2P traffic.
11. **Review Firewall Rules:** Confirm that your firewall is not blocking inbound or outbound traffic on the required P2P and RPC [ports](/fundamentals/default-ports).
12. **Double-Check Configuration Flags:** Review all your command-line flags for typos or incorrect values. A single misplaced character can cause a cryptic error. See the [CLI Reference](/fundamentals/configuring-erigon) for the full flag list.
13. **Check for Snapshot File Issues:** For version upgrades, a known issue with snapshot filenames can cause problems. Use snapshot [upgrade](/get-started/installation/upgrading) and repair options.
14. **Correct File Ownership:** If using a dedicated user or Docker, confirm that the user has full read/write access to the datadir. See the [Docker Compose](/fundamentals/docker-compose) guide for container-specific permission tips.
15. **Adjust RPC Timeouts:** If specific RPC requests are timing out, try increasing the timeout values to allow more time for heavy requests to complete. See the [RPC & API flags](/fundamentals/configuring-erigon#rpc--api) in the CLI Reference.
16. **Check for `DB.read.concurrency` issues:** If you have high RPC traffic and low TPS, try reducing the `--DB.read.concurrency` flag. See [Configuring Erigon](/fundamentals/configuring-erigon) for all database-related flags.
17. **Report a Bug:** If all else fails, open a detailed bug report on GitHub with logs, version info, and a clear description of the problem.
18. **Engage with the Community:** The Erigon Discord server is an invaluable resource for seeking help from core developers and experienced users.

## Collecting Diagnostics for Bug Reports

Before opening a GitHub issue, gather the following information to help the team reproduce and fix your problem faster.

**Dump goroutine stacks** (sends `SIGUSR1` to the running process — safe, non-destructive):

```bash
kill -SIGUSR1 $(pidof erigon)
# Stack traces are printed to the erigon log / stdout
```

**Capture a CPU or heap profile via pprof** (requires `--pprof` flag at startup — default address `localhost:6060`; override with `--pprof.addr` and `--pprof.port`):

```bash
# CPU profile — 30-second sample
curl -o cpu.pprof http://localhost:6060/debug/pprof/profile?seconds=30

# Heap profile
curl -o heap.pprof http://localhost:6060/debug/pprof/heap

# Inspect locally
go tool pprof -http=:8080 cpu.pprof
```

Attach the `.pprof` files and the goroutine dump to your GitHub issue.

## Hetzner Cloud / Dedicated Server Firewall Note

Hetzner applies a stateless firewall at the network edge. Ensure the following ports are open for **both TCP and UDP, inbound and outbound**:

| Purpose        | Port  | Protocol |
| -------------- | ----- | -------- |
| P2P (Ethereum) | 30303 | TCP+UDP  |
| P2P (Caplin)   | 9000  | TCP+UDP  |

Without these, the node may appear to have peers (via the cloud dashboard) but will suffer poor block propagation. Configure the firewall in the Hetzner Cloud Console under **Firewalls** or via `hcloud firewall`.

---

# Known Issues
URL: https://docs.erigon.tech/help-center/known-issues


### Incorrect Memory Usage in `htop`

If you're using `htop`, you might notice it showing very high memory usage for Erigon. This is because Erigon's internal database, MDBX, uses MemoryMap, allowing the operating system to manage all read, write, and cache operations ([linux](https://linux-kernel-labs.github.io/refs/heads/master/labs/memory_mapping.html), [windows](https://docs.microsoft.com/en-us/windows/win32/memory/file-mapping)).

The **`RES`** (Resident) column in `htop` combines the memory used by the application and the OS's page cache for that application. This can be misleading because the OS automatically frees the page cache whenever it needs memory for other processes. So, even if `htop` shows 90% memory usage, a large portion of that is just the OS page cache, and you might still be able to run other applications without issue.

#### Tools for Accurate Memory Usage

For a more accurate view of Erigon's memory usage, use one of these tools:

* **`vmmap -summary PID`** _(macOS only)_: Shows a detailed breakdown with separate **`MALLOC ZONE`** and **`REGION TYPE`** sections for application memory and OS page cache.
* **`pmap -x PID`** _(Linux)_: Prints a per-mapping breakdown of RSS and dirty pages. For the full raw detail use `cat /proc/<PID>/smaps`.
* **Prometheus Dashboard**: This provides a graphical representation of the Go application's memory usage, excluding the OS page cache. You can run it with `make prometheus` and access it in your browser at `localhost:3000` with the credentials `admin/admin`. See [Creating a Dashboard](/fundamentals/creating-a-dashboard) for full setup instructions.

Erigon typically uses about **4 GB of RAM** during a genesis sync and about **1 GB** during normal operation. The OS page cache, however, can use an unlimited amount of memory.

:::warning
**Warning:** Running multiple Erigon instances on the same machine can cause a performance hit due to concurrent disk access. This is especially true during a genesis sync, where the "Blocks Execution stage" performs many random reads. It is not recommended to run multiple genesis syncs on the same disk. Once the initial sync is complete, running multiple instances on the same disk is generally fine.
:::

### Cloud Network Drives

Cloud network drives, like gp3, aren't ideal for Erigon's block execution. This is because they are designed for parallel and batch database workloads, which contrasts with Erigon's use of non-parallel, blocking I/O for block execution. This mismatch leads to poor performance. See also issue [#1516](https://github.com/erigontech/erigon/issues/1516#issuecomment-811958891).

#### Improving Performance

Erigon3 is designed to download most of the history, making it less sensitive to disk latency. To improve performance, focus on **reducing disk latency**, not on increasing throughput or IOPS. There are several ways to do this:

* **Use latency-critical cloud drives** or attached NVMe storage, especially for the initial sync.
* **Increase RAM**. More RAM helps buffer data and reduces the need for frequent disk access.
* If you have sufficient RAM, you can set the environment variable **`ERIGON_SNAPSHOT_MADV_RND=false`**. This setting can improve performance by altering how Erigon handles memory.
* Use the flag **`--db.pagesize=64kb`** to decrease database fragmentation and improve I/O efficiency.

#### Background File System Features Can Hurt Performance

Certain file system features, such as `autodefrag` on btrfs, can drastically increase write I/O. This can lead to a significant performance hit, sometimes as much as a 100x increase in disk activity.

#### Gnome Tracker Can Interfere with Erigon

[Gnome Tracker](https://wiki.gnome.org/Attic/Tracker) is known to detect and shut down mining processes, which can cause Erigon to crash. If you're running Erigon, it's a good idea to disable Gnome Tracker to prevent this.

#### The `--mount` Option and BuildKit Errors

If you're encountering a BuildKit error when starting Erigon, it's likely due to an issue with the `--mount` option in your command. To fix this, you can use the following command to start Erigon with `docker-compose`. See [Docker Compose](/fundamentals/docker-compose) for the full setup guide.

```bash
XDG_DATA_HOME=/preferred/data/folder make docker-compose
```

#### Erigon Crashes from Kernel Allocation Limits

If Erigon crashes with a **`cannot allocate memory`** error, your kernel's memory allocation limits might be too low. You can resolve this by adding the following lines to `/etc/sysctl.conf` or a new `.conf` file in `/etc/sysctl.d/`:

```bash
vm.overcommit_memory = 1
vm.max_map_count = 16777216
```

### Changing `--db.pagesize` After First Sync

The `--db.pagesize` flag sets the MDBX page size and **must be chosen before the first sync**. It cannot be changed on an existing database without deleting the datadir and re-syncing from scratch. See [Configuring Erigon](/fundamentals/configuring-erigon) for all database flags.

The default page size is `16KB`. For cloud drives or any storage with high sequential I/O latency, a larger page size (e.g. `--db.pagesize=64kb`) reduces database fragmentation and improves I/O efficiency. See [Performance Tricks](/fundamentals/performance-tricks) and [Optimizing Storage](/fundamentals/optimizing-storage) for further tuning options.

---

# Best Practices
URL: https://docs.erigon.tech/help-center/best-practices


These integrated practices focus on maximizing the reliability, efficiency, and security of your Erigon node setup.

## Hardware and Data Integrity

| **Practice**                        | **Details**                                                                                                                                                                     | **Rationale**                                                                                                                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Use a High-End NVMe SSD             | This is a non-negotiable prerequisite. NVMe SSDs are essential for reliable, high-performance node operation. See [Hardware Requirements](/get-started/hardware-requirements).  | Erigon is highly disk I/O intensive. Fast storage prevents bottlenecks and sync issues.                                                                                                 |
| Integrate Hardware Reliability      | Use ECC memory and consider a disk RAID setup. Do regular backups of your chain data.                                                                                           | While Erigon's database is fully-transactional and resilient to graceful shutdowns, crashes, and power outages, it is not protected against hardware failures (disk or RAM corruption). |
| Symlink Data Directories (Advanced) | For systems with multiple disks, consider symlinking `snapshots` and `temp` directories to a cheaper, high-capacity drive, while keeping the main `chaindata` on the fast NVMe. See [Optimizing Storage](/fundamentals/optimizing-storage). | Optimizes cost and capacity while retaining performance for critical files.                                                                          |
| Maintain Sufficient RAM             | Ensure your system has at least the recommended RAM for your chosen network and [pruning mode](/fundamentals/pruning-modes). See [Hardware Requirements](/get-started/hardware-requirements). | Insufficient RAM, even with Erigon's memory efficiency, will lead to OOM-kill events (Out-of-Memory).                                                                                   |

## Node Configuration and Startup

| **Practice**                               | **Details**                                                                                                                                                                         | **Rationale**                                                                                                                                                           |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Make a Mindful Pruning Mode Decision       | The `--prune.mode` flag is irreversible. Choose `full` for most cases, `minimal` for validators with limited space, and `archive` only if all historical data is absolutely needed. See [Pruning Modes](/fundamentals/pruning-modes). | An incorrect choice can lead to a necessary resync. `Full` is a balance of performance and space.                                |
| Employ a Process Manager                   | Always run Erigon as a systemd or supervisor service. See the [Installation](/get-started/installation) guide for service setup examples.                                           | Ensures a graceful shutdown and allows for automatic restarts, contributing to stability.                                                                               |
| Use a Dedicated User Account               | Run the Erigon service with a non-root, dedicated user account.                                                                                                                     | Follows security best practices and prevents potential permission-related errors.                                                                                       |
| Avoid Graceful Shutdown (Unless Necessary) | While a process manager ensures a graceful shutdown, know that Erigon is safe against abrupt halts like process kills (`kill -9`) or a power outage.                                | Erigon's database is fully-transactional, meaning writes are atomic ("all-or-nothing"), preventing "partial writes" and database corruption from non-hardware failures. |
| Tune Sync Speed with Flags                 | Use flags like `--sync.loop.block.limit` and `--batchSize` to tune the synchronization speed, especially during the initial sync. See [Configuring Erigon](/fundamentals/configuring-erigon). | Allows you to optimize the sync process based on your system's hardware capabilities.                                                   |
| Lock the Latest State in RAM (Advanced)    | On systems with high historical RPC traffic, a tool like vmtouch can be used to lock the latest state files in RAM. See [Performance Tricks](/fundamentals/performance-tricks).     | Improves RPC response times for common queries by keeping the latest data in the fastest memory.                                                                        |

## Security and Monitoring

| **Practice**                | **Details**                                                                                                                                                            | **Rationale**                                                                                               |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Configure Firewall Rules    | Configure your firewall to allow only the necessary ports for P2P and RPC communication. See [Default Ports](/fundamentals/default-ports).                             | Standard security practice to limit attack surface.                                                         |
| Never Expose RPC Ports      | Never expose the RPC ports to the public internet without a reverse proxy. See [Security](/fundamentals/security).                                                     | RPC (Remote Procedure Call) ports grant access to node functions; public exposure is a major security risk. |
| Monitor Your Node's Health  | Implement comprehensive monitoring using tools like Prometheus and Grafana to track key metrics like disk I/O, CPU load, and sync status in real time. See [Creating a Dashboard](/fundamentals/creating-a-dashboard). | Essential for proactively identifying performance bottlenecks and stability issues.        |
| Enable JSON-RPC Compression | Use the `--http.compression` flag. See [Configuring Erigon](/fundamentals/configuring-erigon).                                                                         | Reduces network bandwidth usage for RPC requests.                                                           |
| Tune RPC Batch Concurrency  | Adjust the `--rpc.batch.concurrency` flag. See [RPC & API flags](/fundamentals/configuring-erigon#rpc--api).                                                           | Limits the number of parallel database reads to prevent a single batch request from overloading the server. |
| Harden Public RPC Endpoints | Place a reverse proxy (e.g. Nginx, Caddy) in front of Erigon. Enable rate-limiting, TLS termination, and authentication at the proxy layer. Never bind `--http.addr` to `0.0.0.0` directly on a public interface. See [TLS Authentication](/fundamentals/tls-authentication). | A direct public binding exposes the node to DoS attacks and unrestricted calls that can exhaust resources. |

## Maintenance and Development

| **Practice**                   | **Details**                                                                                                         | **Rationale**                                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Keep Your Binary Updated       | Regularly update your binary. Erigon is in active development. See [Upgrading](/get-started/installation/upgrading). | New releases often contain critical bug fixes and performance improvements essential for stability. |
| Use Official Docker Images     | If using Docker, rely on the official images provided by the Erigon team. See [Docker Compose](/fundamentals/docker-compose). | Best compatibility and stability for containerized deployment.                               |
| Run a Test Sync on a Testnet   | Before running on Mainnet, consider performing a sync on a testnet (e.g., Sepolia). See [Supported Networks](/fundamentals/supported-networks). | Familiarizes you with the process and your system's performance characteristics.          |
| Report Issues with Diagnostics | When a bug is encountered, provide a detailed report on GitHub with a stack trace and other diagnostic information. | Helps the development team quickly identify and fix issues.                                         |

## Validator-Specific Practices

| **Practice**                      | **Details**                                                                                    | **Rationale**                                                           |
| --------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Check Validator Health            | For validator nodes, a daily check of the node's logs and service status is essential. See [Caplin](/staking/caplin) and [External Consensus Client](/staking/external-consensus-client-as-validator). | Confirms that the node is signing attestations and performing its duty. |
| Maintain a Sufficient ETH Balance | Validators must maintain an adequate ETH balance on their signer address.                      | Required to cover transaction fees for checkpoint submissions.          |

## Advanced Performance Tricks

The following shell snippets can provide meaningful performance gains on the right hardware. See [Performance Tricks](/fundamentals/performance-tricks) for the full list.

**Speed up initial sync** — throttle block execution to leave I/O headroom for snapshot downloads:

```bash
--sync.loop.block.limit=10000
```

**Keep the latest state in RAM** — use `vmtouch` to pin the domain files so the OS page cache never evicts them:

```bash
# Install: apt install vmtouch  (or brew install vmtouch)
vmtouch -vldt /your/datadir/snapshots/domain
```

**Reduce random-read pressure on cloud / NAS storage** — disable the random-access hint for snapshot files:

```bash
export ERIGON_SNAPSHOT_MADV_RND=false
```

**Reduce database fragmentation** — set a larger page size at first sync (cannot be changed afterwards):

```bash
--db.pagesize=64kb
```

---

# Common Errors and Solutions
URL: https://docs.erigon.tech/help-center/common-errors-and-solutions


This section details common error messages and provides clear, actionable steps to resolve them.

## Sync and Performance

### Stalling during snapshot sync (0 B/s download rate)

* **Error Description:** The sync process appears to be stuck, showing a download rate of 0B/s, even with peers.
* **Cause:** The [RPC daemon](/fundamentals/modules/rpc-daemon) or a connected consensus client may be "spamming" the Erigon node with requests, which interferes with the snapshot sync. This issue is still present in recent versions.
* **Solution:** Temporarily disable the RPC by removing flags like `--http` and `--ws`, or stop your consensus client until the initial snapshot sync stage is complete.

### Sync is extremely slow or the node is constantly falling behind

* **Error Description:** The node is not keeping up with the blockchain tip despite a fast internet connection.
* **Cause:** This is almost always a disk-related problem. The read/write speed and latency of your storage device are the most significant performance bottlenecks for Erigon.
* **Solution:** Upgrade your storage to a high-end NVMe SSD. Avoid using HDDs, network drives, or slow consumer-grade SSDs. See [Hardware Requirements](/get-started/hardware-requirements) and [Performance Tricks](/fundamentals/performance-tricks).

## Memory and Resources

### Out of Memory (OOM) or unexpected process termination

* **Error Description:** The Erigon process is abruptly terminated by the operating system, often with an OOM-kill event in the system logs.
* **Cause:** This can be a genuine memory leak or, more commonly, a symptom of a disk I/O bottleneck. When the disk can't keep up with processing, memory usage can balloon as the system tries to buffer data.
* **Solution:** Ensure your system meets the recommended RAM requirements in [Hardware Requirements](/get-started/hardware-requirements). A clean shutdown and restart can often resolve the issue. If the problem persists, check your dmesg logs and consider upgrading your disk.

## Database

### Database corruption after an unexpected shutdown

* **Error Description:** The Erigon process fails to start or crashes immediately after a power outage or a forced kill.
* **Cause:** Erigon's database can be corrupted if it is not shut down gracefully, which prevents the final writes from being committed.
* **Solution:** The most reliable solution is to delete the corrupted datadir and re-sync from scratch. This is often faster than attempting to repair the database.

## Permissions and Access

### Permission denied or Access Denied errors on startup

* **Error Description:** The process fails to access the datadir, logs, or other files.
* **Cause:** The user or service account running Erigon does not have the correct file permissions for the data directory.
* **Solution:** Use the `chown` and `chmod` commands to ensure the correct user account has ownership and full read/write access to the datadir. See [Security](/fundamentals/security) for service account best practices.

### Permission denied inside Docker (UID/GID mismatch)

* **Error Description:** When running the official Docker image, Erigon fails to read or write files in the mounted datadir with a `permission denied` error.
* **Cause:** The container runs the Erigon process as UID/GID `1000`. If the host directory is owned by a different user, the process cannot access it.
* **Solution:** On the host, change ownership of the datadir to UID/GID 1000: `sudo chown -R 1000:1000 /your/datadir`. Alternatively, pass `--user $(id -u):$(id -g)` to `docker run` to run the container with your host user's identity. See [Docker Compose](/fundamentals/docker-compose).

## Network and Configuration

### Connect: connection refused or dial tcp... failures

* **Error Description:** The node cannot connect to an external service, such as a local or remote Heimdall instance.
* **Cause:** This is a configuration error. The dependent service is either not running, or the command-line flag is pointing to an incorrect address.
* **Solution:** Confirm that the required services are running and that the command-line flags (e.g., `--bor.heimdall.url`) are correctly set. See [Configuring Erigon](/fundamentals/configuring-erigon) for all available flags.

## Chain-Specific Issues

### Bad block / Invalid Merkle on Polygon network

* **Error Description:** The node stops importing new blocks, and the logs show errors related to bad blocks.
* **Cause:** This is a Polygon-specific issue that occurs when the Heimdall and Bor layers are out of sync.
* **Solution:** Verify that your Heimdall and REST servers are running. Restarting the Bor and Heimdall services on both the sentry and validator nodes should resolve the issue by bringing the layers back into sync. See the [Polygon Node](/get-started/easy-nodes/how-to-run-a-polygon-node) guide.

## Build and Installation

### `libsilkworm_capi.so`: missing shared library

* **Error Description:** Erigon fails to start with a dynamic linker error about a missing `libsilkworm_capi.so` shared library.
* **Cause:** The binary was built with Silkworm support but the shared library is not present in the system's library path or alongside the binary.
* **Solution:** Ensure the `libsilkworm_capi.so` file is located in the same directory as the `erigon` binary, or add its location to `LD_LIBRARY_PATH`. If you built from source, run `make erigon` again to confirm the library was compiled and placed correctly. See [Installation](/get-started/installation) for build-from-source instructions. Official Docker images bundle the library automatically.

---

# Glossary of Key Terms
URL: https://docs.erigon.tech/help-center/glossary-of-key-terms


This glossary provides concise definitions for essential terms related to the Erigon client. Understanding this terminology is crucial for troubleshooting, configuration, and general operation.

* **Account:** A unique entity on the Ethereum blockchain that can hold an ETH balance and send transactions. There are two types: externally owned accounts (EOAs) and contract accounts.
* **Archive Node:** A node that stores the complete history of the blockchain. This includes all historical states and past transactions, allowing for deep queries into any moment in the blockchain's history. Erigon is particularly known for its highly optimized archive node. See [Pruning Modes](/fundamentals/pruning-modes).
* **Attestation:** A validator's vote on the validity of a block or chain. A high attestation effectiveness is critical for a healthy validator and node. See [Caplin](/staking/caplin).
* **Block:** A collection of transactions, data, and a header that is cryptographically linked to the previous block.
* **Consensus Client (CL):** Software that runs the Proof-of-Stake (PoS) consensus protocol. It is responsible for a node's peer discovery, block propagation, and attesting to blocks. Examples include Lighthouse, Nimbus, and Prysm. Erigon includes its own built-in CL called [Caplin](/staking/caplin).
* **datadir:** The directory where an Erigon node stores all of its blockchain data, including the database, snapshots, and temporary files. See [Optimizing Storage](/fundamentals/optimizing-storage) for tips on managing this directory.
* **Engine API:** The communication protocol that allows the **Execution Client** (Erigon) and the **Consensus Client** to communicate and exchange data, such as new blocks and validator attestations. See the [Engine API](/interacting-with-erigon/engine) reference.
* **Erigon:** An Ethereum **Execution Client** built for efficiency. It is designed to be highly scalable and fast, with a focus on minimizing disk space and improving synchronization speed. See [Why Erigon](/get-started/why-using-erigon).
* **Execution Client (EL):** Software that executes and validates all transactions, and propagates new blocks across the network. It maintains a full record of the blockchain state. Erigon is an execution client.
* **Full Node:** A node that holds a complete copy of all block data, from the genesis block to the current head. It retains recent state, all blocks post-Merge, and prunes ancient blocks and state (EIP-4444 enabled). It verifies every block and state transition. See [Pruning Modes](/fundamentals/pruning-modes).
* **Go (Golang)**: The open-source programming language used to develop Erigon, known for its performance, concurrency, and efficiency.
* **Gnosis Chain:** A stable, community-owned EVM-compatible chain that uses a PoS consensus mechanism. Erigon has specific optimizations and troubleshooting steps for Gnosis Chain due to its large transaction history. See the [Gnosis Chain Node](/get-started/easy-nodes/how-to-run-a-gnosis-chain-node) guide.
* **JSON RPC**: JSON Remote Procedure Call. A lightweight protocol used by Ethereum clients to communicate with applications (like wallets or block explorers) over HTTP or WebSockets. See [Interacting with Erigon](/interacting-with-erigon) for the full API reference.
* **head:** The most recent block in the blockchain.
* **Minimal Node**: A node that retains the minimum amount of data necessary to function, typically by heavily pruning historical state data to significantly save disk space. See [Pruning Modes](/fundamentals/pruning-modes).
* **MDBX:** The high-performance, key-value database that Erigon uses to store blockchain data. It is a more efficient and scalable alternative to the databases used by other clients.
* **Merkle Patricia Trie:** A data structure used by most Ethereum clients (like Geth) to store the blockchain state. It is highly secure but can be less space-efficient than MDBX.
* **Mempool:** A pool of unconfirmed transactions that have been submitted to the network but have not yet been included in a block.
* **MCP Server:** The Model Context Protocol server built into Erigon that exposes blockchain data to AI assistants. See [MCP Server](/fundamentals/mcp) (v3.4 only).
* **Node:** A piece of software that runs on a computer and interacts with the blockchain network. It can be a full node, light node, or validator node.
* **OOM-kill:** An event where the operating system's "Out of Memory" killer terminates a process (e.g., Erigon) that is consuming too much memory. See [Hardware Requirements](/get-started/hardware-requirements) for recommended RAM specs.
* **Peer:** Another node on the network that your client is connected to. The more healthy peers you have, the more reliable your connection is. See [Default Ports](/fundamentals/default-ports) for P2P port configuration.
* **Pruning:** The process of removing older, unnecessary data from the blockchain to save disk space. Erigon offers different pruning modes (full, minimal, archive) to suit various needs. See [Pruning Modes](/fundamentals/pruning-modes).
* **rpcdaemon:** A separate, lightweight process in Erigon that handles JSON RPC API requests. This design allows Erigon to continue syncing efficiently even under heavy RPC load. See [RPC Daemon](/fundamentals/modules/rpc-daemon).
* **Snapshot Sync:** A rapid synchronization method that downloads a pre-made snapshot of the blockchain state and then syncs the remaining blocks. This is much faster than syncing from the genesis block. See [Pruning Modes](/fundamentals/pruning-modes).
* **Staged Sync:** Erigon's unique synchronization model. It processes the blockchain in a series of logical stages, such as downloading headers, verifying bodies, and building the state, to maximize speed and efficiency. See [Pruning Modes](/fundamentals/pruning-modes).
* **Validator:** A participant in a Proof-of-Stake network who has staked the network token and is responsible for proposing and attesting to new blocks. See [Caplin](/staking/caplin) and [External Consensus Client](/staking/external-consensus-client-as-validator).

---