Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 3 additions & 59 deletions docs/base-chain/node-operators/performance-tuning.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,10 @@ If utilizing Amazon Elastic Block Store (EBS), io2 Block Express volumes are rec

The following are the hardware specifications used for Base production nodes:

- **Reth Archive Node (recommended):**
- Instance: AWS `i7i.12xlarge` or larger
- Storage: RAID 0 of all local NVMe drives (`/dev/nvme*`)
- Filesystem: ext4

- **Geth Full Node:**
- **Reth Archive Node:**
- Instance: AWS `i7i.12xlarge` or larger
- Storage: RAID 0 of all local NVMe drives (`/dev/nvme*`)
- Filesystem: ext4
- Storage: RAID 0 of all local NVMe drives (`/dev/nvme*`)
- Filesystem: ext4

## Initial Sync

Expand All @@ -48,54 +43,3 @@ The [Base Node](https://github.com/base/node) repository contains the current st

Reth is currently the most performant client for running Base nodes. Future optimizations will primarily focus on Reth. You can read more about the migration to Reth [here](https://blog.base.dev/scaling-base-with-reth).

### Geth Performance Tuning (deprecated)

<Warning>
Geth is no longer supported and Reth is the recommended client and shown to be more performant. We recommend migrating Geth nodes to Reth, especially if you are experiencing performance issues.
</Warning>

#### Geth Cache Settings

For Geth nodes, tuning cache allocation via environment variables can improve performance. These settings are used in the standard Docker configuration:

```bash
# .env.mainnet / .env.sepolia
GETH_CACHE="20480" # Total P2P cache memory allowance (MB) (default: 1024)
GETH_CACHE_DATABASE="20" # Percentage of cache memory allowance for database IO (default: 75)
GETH_CACHE_GC="12" # Percentage of cache memory allowance for garbage collection (default: 25)
GETH_CACHE_SNAPSHOT="24" # Percentage of cache memory allowance for snapshot caching (default: 10)
GETH_CACHE_TRIE="44" # Percentage of cache memory allowance for trie caching (default: 25)
```

#### Geth LevelDB Tuning

For teams running Geth with LevelDB, the following patch allows setting LevelDB initialization parameters via environment variables:

[https://github.com/0x00101010/goleveldb/commit/55ef3429673fb70d389d052a15a4423e13d8b43c](https://github.com/0x00101010/goleveldb/commit/55ef3429673fb70d389d052a15a4423e13d8b43c)

This patch can be applied using a `replace` directive in `go.mod` when building `op-geth`. Here’s how to modify your Dockerfile:

```dockerfile
RUN git clone $REPO --branch $VERSION --single-branch . && \
git switch -c branch-$VERSION $COMMIT && \
bash -c '[ "$(git rev-parse HEAD)" = "$COMMIT" ]'

RUN echo '' >> go.mod && \
echo 'replace github.com/syndtr/goleveldb => github.com/0x00101010/goleveldb v1.0.4-param-customization' >> go.mod && \
go mod tidy

# Continue building op-geth
COPY op-geth/ ./
RUN go run build/ci.go install -static ./cmd/geth
```

Recommended LevelDB environment variable values with this patch:

```bash
# Recommended LevelDB Settings
LDB_BLOCK_SIZE="524288" # 512 KiB block size (matches common RAID 0 chunk sizes)
LDB_COMPACTION_TABLE_SIZE="8388608" # 8 MiB compaction table size (default: 2 MiB)
LDB_COMPACTION_TOTAL_SIZE="41943040" # 40 MiB total compaction size (default: 8 MiB)
LDB_DEBUG_OPTIONS="1" # Emit LevelDB debug logs
```

6 changes: 1 addition & 5 deletions docs/base-chain/node-operators/run-a-base-node.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -82,11 +82,7 @@ Syncing your node may take **days** and will consume a vast amount of your reque

### Snapshots

<Note>
Geth Archive Nodes are no longer supported. For Archive functionality, use Reth, which provides significantly better performance in Base’s high-throughput environment.
</Note>

If you're a Base Node operator and would like to save significant time on the initial sync, you may [restore from a snapshot](/base-chain/node-operators/snapshots#restoring-from-snapshot). The snapshots are updated every week.
If you’re a Base Node operator and would like to save significant time on the initial sync, you may [restore from a snapshot](/base-chain/node-operators/snapshots#restoring-from-snapshot). The snapshots are updated every week.

### Syncing

Expand Down
43 changes: 11 additions & 32 deletions docs/base-chain/node-operators/snapshots.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,38 +5,27 @@ sidebarTitle: Snapshots

Using a snapshot significantly reduces the initial time required to sync a Base node. Snapshots are updated regularly.

<Warning>
Geth Archive Nodes are no longer supported via snapshots due to performance limitations. For Archive functionality, please use Reth.
</Warning>

If you're a prospective or current Base node operator, you can restore from a snapshot to speed up your initial sync. Follow the steps below carefully.

## Restoring from Snapshot

These steps assume you are in the cloned `node` directory (the one containing `docker-compose.yml`).

1. **Prepare Data Directory**:
- **Before running Docker for the first time**, create the data directory on your host machine that will be mapped into the Docker container. This directory must match the `volumes` mapping in the `docker-compose.yml` file for the client you intend to use.
- For Reth (recommended):
- **Before running Docker for the first time**, create the data directory on your host machine that will be mapped into the Docker container. This directory must match the `volumes` mapping in the `docker-compose.yml` file.
```bash
mkdir ./reth-data
```
- For Geth:
```bash
mkdir ./geth-data
```
```
- If you have previously run the node and have an existing data directory, **stop the node** (`docker compose down`), remove the _contents_ of the existing directory (e.g. `rm -rf ./reth-data/*`), and proceed.

2. **Download Snapshot**: Choose the appropriate snapshot for your network and client from the table below. Use `wget` (or similar) to download it into the `node` directory.

| Network | Client | Snapshot Type | Download Command (`wget …`) |
| -------- | ------ | ------------- | ----------------------------------------------------------------------------------------------------------------- |
| Testnet | Reth | Archive (recommended)| `wget -c https://sepolia-reth-archive-snapshots.base.org/$(curl https://sepolia-reth-archive-snapshots.base.org/latest)` |
| Testnet | Reth | Pruned | `wget -c https://sepolia-reth-pruned-snapshots.base.org/$(curl https://sepolia-reth-pruned-snapshots.base.org/latest)` | |
| Testnet | Geth | Full | `wget -c https://sepolia-full-snapshots.base.org/$(curl https://sepolia-full-snapshots.base.org/latest)` |
| Mainnet | Reth | Archive (recommended)| `wget -c https://mainnet-reth-archive-snapshots.base.org/$(curl https://mainnet-reth-archive-snapshots.base.org/latest)` |
| Mainnet | Reth | Pruned | `wget -c https://mainnet-reth-pruned-snapshots.base.org/$(curl https://mainnet-reth-pruned-snapshots.base.org/latest)` | |
| Mainnet | Geth | Full | `wget -c https://mainnet-full-snapshots.base.org/$(curl https://mainnet-full-snapshots.base.org/latest)` |
| Network | Snapshot Type | Download Command (`wget …`) |
| -------- | ------------- | ----------------------------------------------------------------------------------------------------------------- |
| Testnet | Archive (recommended)| `wget -c https://sepolia-reth-archive-snapshots.base.org/$(curl https://sepolia-reth-archive-snapshots.base.org/latest)` |
| Testnet | Pruned | `wget -c https://sepolia-reth-pruned-snapshots.base.org/$(curl https://sepolia-reth-pruned-snapshots.base.org/latest)` |
| Mainnet | Archive (recommended)| `wget -c https://mainnet-reth-archive-snapshots.base.org/$(curl https://mainnet-reth-archive-snapshots.base.org/latest)` |
| Mainnet | Pruned | `wget -c https://mainnet-reth-pruned-snapshots.base.org/$(curl https://mainnet-reth-pruned-snapshots.base.org/latest)` |

<Note>
Ensure you have enough free disk space to download the snapshot archive (`.tar.gz` / `.tar.zst` file) _and_ extract its contents. The extracted data will be significantly larger than the archive.
Expand All @@ -51,26 +40,16 @@ These steps assume you are in the cloned `node` directory (the one containing `d
tar -I zstd -xvf <snapshot-filename.tar.zst>
```

4. **Move Data**: The extraction process will likely create a directory (e.g., `reth` or `geth`).
4. **Move Data**: The extraction process will likely create a `reth` directory.

* Move the *contents* of that directory into the data directory you created in Step 1.
* Example (if archive extracted to a reth folder - **verify actual folder name**):
* Move the *contents* of that directory into the data directory you created in Step 1:

```bash
# For Reth
mv ./reth/* ./reth-data/
rm -rf ./reth # Clean up empty extracted folder
```

* Example (if archive extracted to a geth folder):

```bash
# For Geth
mv ./geth/* ./geth-data/
rm -rf ./geth # Clean up empty extracted folder
```

* The goal is to have the chain data directories (e.g., `chaindata`, `nodes`, `segments`, etc.) directly inside `./reth-data` or `./geth-data`, not nested within another subfolder.
* The goal is to have the chain data directories (e.g., `chaindata`, `nodes`, `segments`, etc.) directly inside `./reth-data`, not in a nested subfolder.

5. **Start the Node**: Now that the snapshot data is in place, return the root of your Base node folder and start the node:

Expand Down
18 changes: 8 additions & 10 deletions docs/base-chain/node-operators/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This guide covers common issues encountered when setting up and running a Base n
Before diving into specific issues, here are some general steps that often help:

1. **Check Container Logs**: This is usually the most informative step. Use `docker compose logs -f <service_name>` to view the real-time logs for a specific container.
- L2 Client (Reth/Geth): `docker compose logs -f execution`
- L2 Client (Reth): `docker compose logs -f execution`
- Rollup Node: `docker compose logs -f node`. Look for errors, warnings, or repeated messages.

2. **Check Container Status**: Ensure the relevant Docker containers are running: `docker compose ps`. If a container is restarting frequently or exited, check its logs.
Expand Down Expand Up @@ -41,8 +41,8 @@ Before diving into specific issues, here are some general steps that often help:
- **Issue**: Errors related to JWT secret or authentication between `op-node` and L2 client.
- **Check**: Ensure you haven't manually modified the `OP_NODE_L2_ENGINE_AUTH` variable or the JWT file path (`$OP_NODE_L2_ENGINE_AUTH`) unless you know what you're doing. The `docker-compose` setup usually handles this automatically.

- **Issue**: Permission errors related to data volumes (`./reth-data`, `./geth-data`).
- **Check**: Ensure the user running `docker compose` has write permissions to the directory where the `node` repository was cloned. Docker needs to be able to write to `./reth-data` or `./geth-data`. Sometimes running Docker commands with `sudo` can cause permission issues later; try running as a non-root user added to the `docker` group.
- **Issue**: Permission errors related to data volumes (`./reth-data`).
- **Check**: Ensure the user running `docker compose` has write permissions to the directory where the `node` repository was cloned. Docker needs to be able to write to `./reth-data`. Sometimes running Docker commands with `sudo` can cause permission issues later; try running as a non-root user added to the `docker` group.

### Syncing Problems

Expand All @@ -67,11 +67,9 @@ Before diving into specific issues, here are some general steps that often help:

### Performance Issues

- **Issue**: High CPU, RAM, or Disk I/O usage.
- **Action**: If running Geth, we highly recommend migrating to Reth, as it’s the recommended client and generally more performant for Base.
- **Check**: Hardware specifications against recommendations in the [Node Performance](/base-chain/node-operators/performance-tuning). Upgrade if necessary. Local NVMe SSDs are critical.
- **Check**: (Geth) Review Geth cache settings and LevelDB tuning options mentioned in [Node Performance – Geth Performance Tuning](/base-chain/node-operators/performance-tuning#geth-performance-tuning) and [Advanced Configuration](/base-chain/node-operators/run-a-base-node#geth-configuration-via-environment-variables).
- **Check**: Review client logs for specific errors or bottlenecks.
- **Issue**: High CPU, RAM, or Disk I/O usage.
- **Check**: Hardware specifications against recommendations in the [Node Performance](/base-chain/node-operators/performance-tuning). Upgrade if necessary. Local NVMe SSDs are critical.
- **Check**: Review client logs for specific errors or bottlenecks.

### Snapshot Restoration Problems

Expand All @@ -89,8 +87,8 @@ Refer to the [Snapshots](/base-chain/node-operators/snapshots) guide for the cor

- **Issue**: Node fails to start after restoring snapshot; logs show database errors or missing files.
- **Check**: Did you stop the node (`docker compose down`) _before_ modifying the data directory?
- **Check**: Did you remove the _contents_ of the old data directory (`./reth-data/*` or `./geth-data/*`) before extracting/moving the snapshot data?
- **Check**: Was the snapshot data moved correctly? The chain data needs to be directly inside `./reth-data` or `./geth-data`, not in a nested subfolder (e.g., `./reth-data/reth/...`). Verify the folder structure.
- **Check**: Did you remove the _contents_ of the old data directory (`./reth-data/*`) before extracting/moving the snapshot data?
- **Check**: Was the snapshot data moved correctly? The chain data needs to be directly inside `./reth-data`, not in a nested subfolder (e.g., `./reth-data/reth/...`). Verify the folder structure.

- **Issue**: Ran out of disk space during download or extraction.
- **Action**: Free up disk space or provision a larger volume. Remember the storage formula:
Expand Down
Loading