From abec6acee00b12465a65c667fb3c236a97308335 Mon Sep 17 00:00:00 2001 From: Henri Devieux Date: Fri, 25 Apr 2025 00:54:58 -0400 Subject: [PATCH 01/14] Refactor Chain docs to add performance and troubleshooting --- ...network-information.mdx => connecting.mdx} | 15 ++-- .../docs/pages/chain/node-performance.mdx | 72 +++++++++++++++++++ .../docs/pages/chain/run-a-base-node.mdx | 38 ++-------- apps/base-docs/docs/pages/chain/snapshots.mdx | 40 +++++++++++ .../docs/pages/chain/troubleshooting.mdx | 13 ++++ apps/base-docs/sidebar.ts | 35 +++++---- 6 files changed, 157 insertions(+), 56 deletions(-) rename apps/base-docs/docs/pages/chain/{network-information.mdx => connecting.mdx} (83%) create mode 100644 apps/base-docs/docs/pages/chain/node-performance.mdx create mode 100644 apps/base-docs/docs/pages/chain/snapshots.mdx create mode 100644 apps/base-docs/docs/pages/chain/troubleshooting.mdx diff --git a/apps/base-docs/docs/pages/chain/network-information.mdx b/apps/base-docs/docs/pages/chain/connecting.mdx similarity index 83% rename from apps/base-docs/docs/pages/chain/network-information.mdx rename to apps/base-docs/docs/pages/chain/connecting.mdx index b8b0cc55d0d..3a69f833ad4 100644 --- a/apps/base-docs/docs/pages/chain/network-information.mdx +++ b/apps/base-docs/docs/pages/chain/connecting.mdx @@ -1,10 +1,10 @@ --- -title: Network Information -slug: /network-information -description: Documentation about Base Mainnet and Base Testnet. This page covers network information for the Base network, including network names, descriptions, RPC endpoints, chain IDs, currency symbols, and block explorers. +title: Connecting +slug: /connecting +description: Documentation about connecting to Base Mainnet and Base Testnet. This page covers network information for the Base network, including network names, descriptions, RPC endpoints, chain IDs, currency symbols, and block explorers. --- -# Network Information +# Connecting #### Base Mainnet @@ -29,13 +29,12 @@ description: Documentation about Base Mainnet and Base Testnet. This page covers | Block Explorer | [https://sepolia-explorer.base.org](https://sepolia-explorer.base.org) | :::info -L1 & L2 protocol and network-related smart contract deployments can be found on the [Base Contracts](./base-contracts) page. +L1 & L2 protocol and network-related smart contract deployments can be found on the [Base Contracts](/chain/base-contracts) page. ::: :::info For production systems, we recommend using a node from one of our [node partners], or [running your own Base node]. ::: -[running your own Base node]: /tutorials/run-a-base-node -[node partners]: /docs/tools/node-providers - +[running your own Base node]: /chain/run-a-base-node +[node partners]: /chain/node-providers diff --git a/apps/base-docs/docs/pages/chain/node-performance.mdx b/apps/base-docs/docs/pages/chain/node-performance.mdx new file mode 100644 index 00000000000..d9987480840 --- /dev/null +++ b/apps/base-docs/docs/pages/chain/node-performance.mdx @@ -0,0 +1,72 @@ +--- +title: Node Performance +slug: /node-performance +description: Guides on how to improve syncing performance of Base node clients +--- + +import { Button } from 'vocs/components' + +# Node Performance + +## Hardware + +We recommend the following hardware configuration to run a Base mainnet node: + +1. A modern multi-core CPU with good single-core performance +2. At least 16 GB RAM (32 GB recommended) +3. A locally attached NVMe SSD drive +4. Adequate storage capacity to accommodate both the snapshot restoration process (if restoring from snapshot) and chain data, plus a 20% buffer for growth. + +:::info + +If utilizing Amazon Elastic Block Store (EBS), io2 Block Express is recommended to ensure timing buffered disk reads are fast enough in order to avoid latency issues alongside the rate of new blocks added to Base during the initial synchronization process. + +**The Base team highly recommends using locally attached NVMe SSD drives rather than networked storage.** + +::: + +## Client Software + +The [Base Node](https://github.com/base/node) repository contains the current stable configurations. + +#### Supported Clients + +Reth is currently the most performant client for running Base nodes. Future optimizations will be made +primarily to Reth. You can read more about our migration to Reth [here](https://blog.base.dev/scaling-base-with-reth) + +| Type | Supported Clients | +| :------ | :------------------------------------------------------------------------------------------------------- | +| Full | [Reth](https://github.com/base/node/tree/main/reth), [Geth](https://github.com/base/node/tree/main/geth) | +| Archive | [Reth](https://github.com/base/node/tree/main/reth) | + +## Geth LevelDB Tuning + +For teams running Geth with leveldb, the following patch can be used to set leveldb initialization parameters via environment variables: + +[https://github.com/0x00101010/goleveldb/commit/55ef34](https://github.com/0x00101010/goleveldb/commit/55ef3429673fb70d389d052a15a4423e13d8b43c) + +This patch can be applied with a replace directive for leveldb in go.mod go.mod when building op-geth. +Here is how that can be done via the Dockerfile: + +```docker +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 && \ // [!code ++] + echo 'replace github.com/syndtr/goleveldb => github.com/0x00101010/goleveldb v1.0.4-param-customization' >> go.mod && \ // [!code ++] + go mod tidy \ // [!code ++] + +# Continue building op-geth +COPY op-geth/ ./ +RUN go run build/ci.go install -static ./cmd/geth +``` + +Sensible values for leveldb with this patch are as follows: + +```bash +LDB_BLOCK_SIZE="524288" #Maximizes IO efficiency, 512 KiB block size which equals our raid 0 config chunk size shown in `cat /proc/mdstat`. See http://go/leveldb for detailed explanation +LDB_COMPACTION_TABLE_SIZE="8388608" #8 MiB, default is 2 MiB for leveldb. See http://go/leveldb for detailed explanation +LDB_COMPACTION_TOTAL_SIZE="41943040" #40 MiB, default is 8 MiB for leveldb. See http://go/leveldb for detailed explanation +LDB_DEBUG_OPTIONS="1" #Emit leveldb debug logs +``` diff --git a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx index af842aacfb1..23f4217517e 100644 --- a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx +++ b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx @@ -5,6 +5,8 @@ description: A tutorial that teaches how to set up and run a Base Node. author: taycaldwell & wbnns --- +import Snapshots from './snapshots.mdx' + # Running a Base Node This tutorial will walk you through setting up your own [Base Node]. @@ -17,7 +19,7 @@ By the end of this tutorial you should be able to: ## Prerequisites -:::caution +:::warning Running a node is time consuming, resource expensive, and potentially costly. If you don't already know why you want to run your own node, you probably don't need to. @@ -73,39 +75,7 @@ Syncing your node may take **days** and will consume a vast amount of your reque ::: -### Snapshots - -:::info - -Geth Archive Nodes are no longer supported. For Archive functionality, use Reth, which provides significantly better performance in Base’s high-throughput environment. - -::: - -If you're a prospective or current Base Node operator and would like to restore from a snapshot to save time on the initial sync, it's possible to always get the latest available snapshot of the Base chain on mainnet and/or testnet by using the following CLI commands. The snapshots are updated every week. - -#### Restoring from snapshot - -In the home directory of your Base Node, create a folder named `geth-data` or `reth-data`. If you already have this folder, remove it to clear the existing state and then recreate it. Next, run the following code and wait for the operation to complete. - -| Network | Client | Snapshot Type | Command | -| ------- | ------ | ------------- | --------------------------------------------------------------------------------------------------------------------- | -| Testnet | Geth | Full | `wget https://sepolia-full-snapshots.base.org/$(curl https://sepolia-full-snapshots.base.org/latest)` | -| Testnet | Reth | Archive | `wget https://sepolia-reth-archive-snapshots.base.org/$(curl https://sepolia-reth-archive-snapshots.base.org/latest)` | -| Mainnet | Geth | Full | `wget https://mainnet-full-snapshots.base.org/$(curl https://mainnet-full-snapshots.base.org/latest)` | -| Mainnet | Reth | Archive | `wget https://mainnet-reth-archive-snapshots.base.org/$(curl https://mainnet-reth-archive-snapshots.base.org/latest)` | - -You'll then need to untar the downloaded snapshot and place the `geth` subfolder inside of it in the `geth-data` folder you created (unless you changed the location of your data directory). - -Return to the root of your Base node folder and start your node. - -```bash [Terminal] -cd .. -docker compose up --build -``` - -Your node should begin syncing from the last block in the snapshot. - -Check the latest block to make sure you're syncing from the snapshot and that it restored correctly. If so, you can remove the snapshot archive that you downloaded. + ### Syncing diff --git a/apps/base-docs/docs/pages/chain/snapshots.mdx b/apps/base-docs/docs/pages/chain/snapshots.mdx new file mode 100644 index 00000000000..11b55986d9d --- /dev/null +++ b/apps/base-docs/docs/pages/chain/snapshots.mdx @@ -0,0 +1,40 @@ +--- +title: Snapshots +slug: /snapshots +description: Information for how to restore a base node from a snapshots +author: taycaldwell & wbnns +--- + +# Snapshots + +:::warning + +Geth Archive Nodes are no longer supported. For Archive functionality, use Reth, which provides significantly better performance in Base’s high-throughput environment. + +::: + +If you're a prospective or current Base Node operator and would like to restore from a snapshot to save time on the initial sync, it's possible to always get the latest available snapshot of the Base chain on mainnet and/or testnet by using the following CLI commands. The snapshots are updated every week. + +#### Restoring from snapshot + +In the home directory of your Base Node, create a folder named `geth-data` or `reth-data`. If you already have this folder, remove it to clear the existing state and then recreate it. Next, run the following code and wait for the operation to complete. + +| Network | Client | Snapshot Type | Command | +| ------- | ------ | ------------- | --------------------------------------------------------------------------------------------------------------------- | +| Testnet | Geth | Full | `wget https://sepolia-full-snapshots.base.org/$(curl https://sepolia-full-snapshots.base.org/latest)` | +| Testnet | Reth | Archive | `wget https://sepolia-reth-archive-snapshots.base.org/$(curl https://sepolia-reth-archive-snapshots.base.org/latest)` | +| Mainnet | Geth | Full | `wget https://mainnet-full-snapshots.base.org/$(curl https://mainnet-full-snapshots.base.org/latest)` | +| Mainnet | Reth | Archive | `wget https://mainnet-reth-archive-snapshots.base.org/$(curl https://mainnet-reth-archive-snapshots.base.org/latest)` | + +You'll then need to untar the downloaded snapshot and place the `geth` subfolder inside of it in the `geth-data` folder you created (unless you changed the location of your data directory). + +Return to the root of your Base node folder and start your node. + +```bash [Terminal] +cd .. +docker compose up --build +``` + +Your node should begin syncing from the last block in the snapshot. + +Check the latest block to make sure you're syncing from the snapshot and that it restored correctly. If so, you can remove the snapshot archive that you downloaded. diff --git a/apps/base-docs/docs/pages/chain/troubleshooting.mdx b/apps/base-docs/docs/pages/chain/troubleshooting.mdx new file mode 100644 index 00000000000..6c8d73c8636 --- /dev/null +++ b/apps/base-docs/docs/pages/chain/troubleshooting.mdx @@ -0,0 +1,13 @@ +--- +title: Troubleshooting +slug: /troubleshooting +description: Information on how to troubleshooting a Base node +author: hndvx +--- + +# Troubleshooting + +If you still cannot resolve the problems with your node, please open a GitHub issue or reach out on our Discord: + +Once you've joined, in the Discord app go to server menu > Linked Roles > connect GitHub and connect your GitHub account so you can gain access to our developer channels +Report your issue in #🛟|developer-support or 🛠 ｜ node-operators diff --git a/apps/base-docs/sidebar.ts b/apps/base-docs/sidebar.ts index 91eefbf387a..31fb6848052 100644 --- a/apps/base-docs/sidebar.ts +++ b/apps/base-docs/sidebar.ts @@ -1010,19 +1010,34 @@ export const sidebar: Sidebar = [ { text: 'Why Base?', link: '/chain/why-base' }, { text: 'Using Base', link: '/chain/using-base' }, { text: 'Deploy on Base', link: '/chain/deploy-on-base-quickstart' }, - { text: 'Network Information', link: '/chain/network-information' }, { text: 'Fees', link: '/chain/fees' }, { text: 'Differences Between Ethereum and Base', link: '/chain/differences-between-ethereum-and-base', }, - { text: 'Run a Base Node', link: '/chain/run-a-base-node' }, + { text: 'Flashblocks', link: '/chain/flashblocks' }, { text: 'Bridge an L1 Token to Base', link: '/chain/bridge-an-l1-token-to-base' }, { text: 'Adding tokens to Coinbase Wallet', link: '/chain/wallet' }, - { - text: 'Decentralizing Base with Optimism↗', - link: 'https://base.mirror.xyz/H_KPwV31M7OJT-THUnU7wYjOF16Sy7aWvaEr5cgHi8I', - }, + ], + }, + { + text: 'Network Information', + collapsed: true, + items: [ + { text: 'Connecting to Base', link: '/chain/connecting' }, + { text: 'Base Contracts', link: '/chain/base-contracts' }, + { text: 'Chain Stats ↗', link: 'https://www.base.org/stats' }, + { text: 'Status Page ↗', link: 'https://status.base.org' }, + ], + }, + { + text: 'Node Operators', + collapsed: true, + items: [ + { text: 'Run a Base Node', link: '/chain/run-a-base-node' }, + { text: 'Snapshots', link: '/chain/snapshots' }, + { text: 'Node Performance', link: '/chain/node-performance' }, + { text: 'Troubleshooting', link: '/chain/troubleshooting' }, ], }, { @@ -1052,18 +1067,10 @@ export const sidebar: Sidebar = [ }, ], }, - { - text: 'Chain Stats ↗', - link: 'https://www.base.org/stats', - }, { text: 'Flashblocks ↗', link: '/chain/flashblocks', }, - { - text: 'Base Contracts', - link: '/chain/base-contracts', - }, ], }, { From b06e6f5ea2b575a49c894b18e565a4e22a0140a5 Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 10:57:37 +0000 Subject: [PATCH 02/14] refactor(server): Add redirect to Connecting to Base page --- apps/base-docs/docs/public/serve.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/apps/base-docs/docs/public/serve.json b/apps/base-docs/docs/public/serve.json index 86f4da15cc9..7f3303d6dae 100644 --- a/apps/base-docs/docs/public/serve.json +++ b/apps/base-docs/docs/public/serve.json @@ -26,6 +26,10 @@ "source": "/network-information", "destination": "/chain/network-information" }, + { + "source": "/chain/network-information", + "destination": "/chain/connecting-to-base" + }, { "source": "/tutorials/deploy-with-remix", "destination": "/cookbook/smart-contract-development/remix/deploy-with-remix" From e68bc46f72e96f4c2efbf265cd8bfc192c090951 Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 11:00:58 +0000 Subject: [PATCH 03/14] refactor(docs): Name of Connecting page --- apps/base-docs/docs/pages/chain/connecting.mdx | 4 ++-- apps/base-docs/sidebar.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apps/base-docs/docs/pages/chain/connecting.mdx b/apps/base-docs/docs/pages/chain/connecting.mdx index 3a69f833ad4..8e37cca27e6 100644 --- a/apps/base-docs/docs/pages/chain/connecting.mdx +++ b/apps/base-docs/docs/pages/chain/connecting.mdx @@ -1,6 +1,6 @@ --- -title: Connecting -slug: /connecting +title: Connecting to Base +slug: /connecting-to-base description: Documentation about connecting to Base Mainnet and Base Testnet. This page covers network information for the Base network, including network names, descriptions, RPC endpoints, chain IDs, currency symbols, and block explorers. --- diff --git a/apps/base-docs/sidebar.ts b/apps/base-docs/sidebar.ts index 31fb6848052..2d924aa95d8 100644 --- a/apps/base-docs/sidebar.ts +++ b/apps/base-docs/sidebar.ts @@ -1024,7 +1024,7 @@ export const sidebar: Sidebar = [ text: 'Network Information', collapsed: true, items: [ - { text: 'Connecting to Base', link: '/chain/connecting' }, + { text: 'Connecting to Base', link: '/chain/connecting-to-base' }, { text: 'Base Contracts', link: '/chain/base-contracts' }, { text: 'Chain Stats ↗', link: 'https://www.base.org/stats' }, { text: 'Status Page ↗', link: 'https://status.base.org' }, From 37b1e03ef1c536719d157295a928f79798e467ff Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 11:06:46 +0000 Subject: [PATCH 04/14] refactor(sidebar): Alphabetize --- apps/base-docs/sidebar.ts | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/apps/base-docs/sidebar.ts b/apps/base-docs/sidebar.ts index 2d924aa95d8..1cc2822a92b 100644 --- a/apps/base-docs/sidebar.ts +++ b/apps/base-docs/sidebar.ts @@ -1007,25 +1007,29 @@ export const sidebar: Sidebar = [ text: 'General', collapsed: true, items: [ - { text: 'Why Base?', link: '/chain/why-base' }, - { text: 'Using Base', link: '/chain/using-base' }, + { text: 'Adding tokens to Coinbase Wallet', link: '/chain/wallet' }, + { text: 'Bridge an L1 Token to Base', link: '/chain/bridge-an-l1-token-to-base' }, { text: 'Deploy on Base', link: '/chain/deploy-on-base-quickstart' }, - { text: 'Fees', link: '/chain/fees' }, { text: 'Differences Between Ethereum and Base', link: '/chain/differences-between-ethereum-and-base', }, + { text: 'Fees', link: '/chain/fees' }, { text: 'Flashblocks', link: '/chain/flashblocks' }, - { text: 'Bridge an L1 Token to Base', link: '/chain/bridge-an-l1-token-to-base' }, - { text: 'Adding tokens to Coinbase Wallet', link: '/chain/wallet' }, + { text: 'Using Base', link: '/chain/using-base' }, + { text: 'Why Base?', link: '/chain/why-base' }, ], }, + { + text: 'Flashblocks ↗', + link: '/chain/flashblocks', + }, { text: 'Network Information', collapsed: true, items: [ - { text: 'Connecting to Base', link: '/chain/connecting-to-base' }, { text: 'Base Contracts', link: '/chain/base-contracts' }, + { text: 'Connecting to Base', link: '/chain/connecting-to-base' }, { text: 'Chain Stats ↗', link: 'https://www.base.org/stats' }, { text: 'Status Page ↗', link: 'https://status.base.org' }, ], @@ -1034,9 +1038,9 @@ export const sidebar: Sidebar = [ text: 'Node Operators', collapsed: true, items: [ + { text: 'Node Performance', link: '/chain/node-performance' }, { text: 'Run a Base Node', link: '/chain/run-a-base-node' }, { text: 'Snapshots', link: '/chain/snapshots' }, - { text: 'Node Performance', link: '/chain/node-performance' }, { text: 'Troubleshooting', link: '/chain/troubleshooting' }, ], }, @@ -1044,15 +1048,15 @@ export const sidebar: Sidebar = [ text: 'Tools', collapsed: true, items: [ - { text: 'Onchain Registry API', link: '/chain/registry-api' }, - { text: 'Node Providers', link: '/chain/node-providers' }, + { text: 'Account Abstraction', link: '/chain/account-abstraction' }, { text: 'Block Explorers', link: '/chain/block-explorers' }, - { text: 'Network Faucets', link: '/chain/network-faucets' }, - { text: 'Oracles', link: '/chain/oracles' }, - { text: 'Data Indexers', link: '/chain/data-indexers' }, { text: 'Cross-chain', link: '/chain/cross-chain' }, - { text: 'Account Abstraction', link: '/chain/account-abstraction' }, + { text: 'Data Indexers', link: '/chain/data-indexers' }, + { text: 'Network Faucets', link: '/chain/network-faucets' }, + { text: 'Node Providers', link: '/chain/node-providers' }, + { text: 'Onchain Registry API', link: '/chain/registry-api' }, { text: 'Onramps', link: '/chain/onramps' }, + { text: 'Oracles', link: '/chain/oracles' }, ], }, { @@ -1060,17 +1064,13 @@ export const sidebar: Sidebar = [ collapsed: true, items: [ { text: 'Bug Bounty', link: '/chain/security/bounty' }, - { text: 'Report a Vulnerability', link: '/chain/security/report' }, { text: 'How to avoid getting your app flagged as malicious', link: '/chain/security/app-blocklist', }, + { text: 'Report a Vulnerability', link: '/chain/security/report' }, ], }, - { - text: 'Flashblocks ↗', - link: '/chain/flashblocks', - }, ], }, { From feeb6299a0758be68a65fc077a20d98b1b0bbe65 Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 11:07:58 +0000 Subject: [PATCH 05/14] refactor(docs): Drop external link artifact for Flashblocks --- apps/base-docs/sidebar.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/base-docs/sidebar.ts b/apps/base-docs/sidebar.ts index 1cc2822a92b..469e8e1e5de 100644 --- a/apps/base-docs/sidebar.ts +++ b/apps/base-docs/sidebar.ts @@ -1021,7 +1021,7 @@ export const sidebar: Sidebar = [ ], }, { - text: 'Flashblocks ↗', + text: 'Flashblocks', link: '/chain/flashblocks', }, { From e457cd28b21182c4aa0af97fc644a9581ee320db Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 11:09:37 +0000 Subject: [PATCH 06/14] Drop external link to Flashblocks from sidebar --- apps/base-docs/sidebar.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/apps/base-docs/sidebar.ts b/apps/base-docs/sidebar.ts index 469e8e1e5de..4db1bf86a1c 100644 --- a/apps/base-docs/sidebar.ts +++ b/apps/base-docs/sidebar.ts @@ -1015,7 +1015,6 @@ export const sidebar: Sidebar = [ link: '/chain/differences-between-ethereum-and-base', }, { text: 'Fees', link: '/chain/fees' }, - { text: 'Flashblocks', link: '/chain/flashblocks' }, { text: 'Using Base', link: '/chain/using-base' }, { text: 'Why Base?', link: '/chain/why-base' }, ], From 07b5664032ef828e0ab2bec7226e02cea8ec67a6 Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 11:17:27 +0000 Subject: [PATCH 07/14] refactor(node-performance): Add additional content --- .../docs/pages/chain/node-performance.mdx | 75 +++++++++++++------ 1 file changed, 53 insertions(+), 22 deletions(-) diff --git a/apps/base-docs/docs/pages/chain/node-performance.mdx b/apps/base-docs/docs/pages/chain/node-performance.mdx index d9987480840..4f2cdbd63fa 100644 --- a/apps/base-docs/docs/pages/chain/node-performance.mdx +++ b/apps/base-docs/docs/pages/chain/node-performance.mdx @@ -8,45 +8,75 @@ import { Button } from 'vocs/components' # Node Performance -## Hardware +This guide provides recommendations for hardware, client software, and configuration settings to optimize the performance of your Base node. -We recommend the following hardware configuration to run a Base mainnet node: +## Hardware -1. A modern multi-core CPU with good single-core performance -2. At least 16 GB RAM (32 GB recommended) -3. A locally attached NVMe SSD drive -4. Adequate storage capacity to accommodate both the snapshot restoration process (if restoring from snapshot) and chain data, plus a 20% buffer for growth. +Running a performant Base node requires adequate hardware. We recommend the following minimum specifications: -:::info +1. A modern multi-core CPU with good single-core performance. +2. At least 32 GB RAM (64 GB recommended). +3. A locally attached NVMe SSD drive. RAID 0 configurations can improve performance. +4. Sufficient storage capacity calculated as: `(2 * [current chain size](https://base.org/stats) + [snapshot size](https://basechaindata.vercel.app) + 20% buffer)`. This accounts for chain data growth and snapshot restoration space. -If utilizing Amazon Elastic Block Store (EBS), io2 Block Express is recommended to ensure timing buffered disk reads are fast enough in order to avoid latency issues alongside the rate of new blocks added to Base during the initial synchronization process. +:::info EBS Recommendations -**The Base team highly recommends using locally attached NVMe SSD drives rather than networked storage.** +If utilizing Amazon Elastic Block Store (EBS), io2 Block Express volumes are recommended to ensure sufficient disk read speeds, preventing latency issues during initial sync. However, **locally attached NVMe SSDs are strongly recommended over networked storage for optimal performance.** ::: +### Production Hardware Examples + +The following are the hardware specifications used for Base production nodes: + +- **Geth Full Node:** + - Instance: AWS `i4i.12xlarge` + - Storage: RAID 0 of all local NVMe drives (`/dev/nvme*`) + - Filesystem: ext4 +- **Reth Archive Node:** + - Instance: AWS `i4ie.6xlarge` + - Storage: RAID 0 of all local NVMe drives (`/dev/nvme*`) + - Filesystem: ext4 + +## Initial Sync + +Using a recent [snapshot](run-a-base-node.mdx#snapshots) can significantly reduce the time required for the initial node synchronization process. + ## Client Software -The [Base Node](https://github.com/base/node) repository contains the current stable configurations. +The [Base Node](https://github.com/base/node) repository contains the current stable configurations and instructions for running different client implementations. -#### Supported Clients +### Supported Clients -Reth is currently the most performant client for running Base nodes. Future optimizations will be made -primarily to Reth. You can read more about our migration to Reth [here](https://blog.base.dev/scaling-base-with-reth) +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). | Type | Supported Clients | | :------ | :------------------------------------------------------------------------------------------------------- | | Full | [Reth](https://github.com/base/node/tree/main/reth), [Geth](https://github.com/base/node/tree/main/geth) | | Archive | [Reth](https://github.com/base/node/tree/main/reth) | -## Geth LevelDB Tuning +### Geth Performance Tuning + +#### 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 can be used to set leveldb initialization parameters via environment variables: +For teams running Geth with LevelDB, the following patch allows setting LevelDB initialization parameters via environment variables: [https://github.com/0x00101010/goleveldb/commit/55ef34](https://github.com/0x00101010/goleveldb/commit/55ef3429673fb70d389d052a15a4423e13d8b43c) -This patch can be applied with a replace directive for leveldb in go.mod go.mod when building op-geth. -Here is how that can be done via the Dockerfile: +This patch can be applied using a `replace` directive in `go.mod` when building `op-geth`. Here's how to modify the Dockerfile: ```docker RUN git clone $REPO --branch $VERSION --single-branch . && \ @@ -62,11 +92,12 @@ COPY op-geth/ ./ RUN go run build/ci.go install -static ./cmd/geth ``` -Sensible values for leveldb with this patch are as follows: +Recommended LevelDB environment variable values with this patch: ```bash -LDB_BLOCK_SIZE="524288" #Maximizes IO efficiency, 512 KiB block size which equals our raid 0 config chunk size shown in `cat /proc/mdstat`. See http://go/leveldb for detailed explanation -LDB_COMPACTION_TABLE_SIZE="8388608" #8 MiB, default is 2 MiB for leveldb. See http://go/leveldb for detailed explanation -LDB_COMPACTION_TOTAL_SIZE="41943040" #40 MiB, default is 8 MiB for leveldb. See http://go/leveldb for detailed explanation -LDB_DEBUG_OPTIONS="1" #Emit leveldb debug logs +# 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 ``` From 505cb5f28d822fe51e7b8bb51b5bcd2f1a2c05b2 Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 11:38:17 +0000 Subject: [PATCH 08/14] Add additional content to running a base node doc --- .../docs/pages/chain/run-a-base-node.mdx | 229 +++++++++++++++--- 1 file changed, 191 insertions(+), 38 deletions(-) diff --git a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx index 23f4217517e..ddb9549df83 100644 --- a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx +++ b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx @@ -9,88 +9,241 @@ import Snapshots from './snapshots.mdx' # Running a Base Node -This tutorial will walk you through setting up your own [Base Node]. +This tutorial walks you through setting up and running your own [Base Node] using Docker. ## Objectives -By the end of this tutorial you should be able to: +By the end of this tutorial, you should be able to: -- Deploy and sync a Base node +- Configure and deploy a Base node using Docker Compose. +- Select the network (Mainnet or Sepolia Testnet). +- Choose a client implementation (Geth, Reth, Nethermind). +- Start the synchronization process. ## Prerequisites :::warning +Is Running a Node Necessary? -Running a node is time consuming, resource expensive, and potentially costly. If you don't already know why you want to run your own node, you probably don't need to. +Running your own node is time-consuming, resource-intensive, and can be costly. If you don't have a specific reason, you might not need one. -If you're just getting started and need an RPC URL, you can use our free endpoints: +For development or basic needs, consider using the free public Base endpoints: - **Mainnet**: `https://mainnet.base.org` - **Testnet (Sepolia)**: `https://sepolia.base.org` -**Note:** Our RPCs are rate-limited, they are not suitable for production apps. - -If you're looking to harden your app and avoid rate-limiting for your users, please check out one of our [partners]. +**Note:** Public RPCs are rate-limited and not suitable for production applications. For production needs, consider using a dedicated [Node Provider]. ::: -### Hardware requirements +### Hardware Requirements -We recommend you have this configuration to run a node: +Refer to the [Node Performance](./node-performance.mdx#hardware) guide for detailed hardware recommendations. Minimums include: -- 8-Core CPU -- at least 16 GB RAM -- a locally attached NVMe SSD drive -- adequate storage capacity to accommodate both the snapshot restoration process (if restoring from snapshot) and chain data, ensuring a minimum of (2 \* current_chain_size) + snapshot_size + 20%\_buffer +- A modern multi-core CPU. +- 32 GB RAM (64 GB recommended). +- A locally attached NVMe SSD drive. +- Sufficient storage: `(2 * [current chain size](https://base.org/stats) + [snapshot size](https://basechaindata.vercel.app) + 20% buffer)`. -:::info +### Docker -If utilizing Amazon Elastic Block Store (EBS), ensure timing buffered disk reads are fast enough in order to avoid latency issues alongside the rate of new blocks added to Base during the initial synchronization process; `io2 block express` is recommended. +This section assumes you are familiar with [Docker] and have Docker and Docker Compose installed and running. -::: +#### L1 Endpoints -### Docker +You need access to synced Ethereum L1 (execution and consensus) endpoints. These can be self-hosted or from a third-party provider. You will need: -This tutorial assumes you are familiar with [Docker] and have it running on your machine. +- **L1 Execution RPC URL**: An HTTP(S) endpoint for the L1 execution client. +- **L1 Beacon API URL**: An HTTP(S) endpoint for the L1 consensus client Beacon API. +- **L1 Beacon Archiver API URL**: An HTTP(S) endpoint for an L1 consensus client Beacon API with archival capabilities. -### L1 RPC URL +These URLs will be configured in your `.env.mainnet` or `.env.testnet` file later. -You'll need your own L1 RPC URL. This can be one that you run yourself, or via a third-party provider, such as our [partners]. +#### Setting Up and Running the Node -## Running a Node +1. **Clone the Repository**: Clone the official [Base Node repository]: -1. Clone the [repo]. -2. Ensure you have an Ethereum L1 full node RPC available (not Base), and set `OP_NODE_L1_ETH_RPC` & `OP_NODE_L1_BEACON` (in the `.env.*` file if using `docker-compose`). If running your own L1 node, it needs to be synced before Base will be able to fully sync. -3. Uncomment the line relevant to your network (`.env.sepolia`, or `.env.mainnet`) under the 2 `env_file` keys in `docker-compose.yml`. -4. Run `docker compose up`. Confirm you get a response from: + ```bash + git clone https://github.com/base/node.git + cd node + ``` -```bash [Terminal] -curl -d '{"id":0,"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest",false]}' \ - -H "Content-Type: application/json" http://localhost:8545 -``` +2. **Choose Network and Configure L1 Endpoints**: + + - Select the environment file for your desired network: + - Mainnet: `.env.mainnet` + - Testnet: `.env.sepolia` + - Open the chosen `.env` file (e.g., `.env.mainnet`) and configure your L1 endpoints: + ```dotenv + # .env.mainnet or .env.sepolia + OP_NODE_L1_ETH_RPC= + OP_NODE_L1_BEACON= + OP_NODE_L1_BEACON_ARCHIVER= + ``` + - **Optional**: Also set `OP_NODE_L1_RPC_KIND` based on your L1 provider (e.g., `alchemy`, `quicknode`, `infura`, `debug_geth`, `erigon`, `basic`, `any`). See the `.env` file comments for supported values. + +3. **Start the Node with Docker Compose**: + + - Use the following commands to build and start the node containers. + + - **Mainnet (Default Client - Geth)**: + + ```bash + docker compose up --build -d + ``` + + _The `-d` flag runs the containers in detached mode (in the background)._ + + - **Sepolia Testnet (Default Client - Geth)**: + + ```bash + NETWORK_ENV=.env.sepolia docker compose up --build -d + ``` + + - **Specifying a Client (e.g., Reth on Mainnet)**: + Choose between `geth` (default), `reth`, or `nethermind`. + + ```bash + CLIENT=reth docker compose up --build -d + ``` + + - **Sepolia Testnet with a Specific Client (e.g., Reth)**: + ```bash + NETWORK_ENV=.env.sepolia CLIENT=reth docker compose up --build -d + ``` + +4. **Verify Node is Running**: + Check if the node is responding to RPC requests. It might take a few minutes for the services to start. + ```bash + curl -d '{"id":0,"jsonrpc":"2.0","method":"eth_chainId"}' \ + -H "Content-Type: application/json" http://localhost:8545 + # Expected Mainnet output: {"jsonrpc":"2.0","id":0,"result":"0x2105"} + # Expected Sepolia output: {"jsonrpc":"2.0","id":0,"result":"0xaa36a7"} + ``` :::caution -Syncing your node may take **days** and will consume a vast amount of your requests quota. Be sure to monitor usage and up your plan if needed. +Syncing your node can take **hours to days**, depending on hardware, network, and whether you use a snapshot. It consumes significant resources. ::: -### Syncing +## Monitoring Sync Progress -You can monitor the progress of your sync with: +You can monitor the sync status using the `optimism_syncStatus` RPC method: -```bash [Terminal] +```bash echo Latest synced block behind by: $((($(date +%s)-$( \ curl -d '{"id":0,"jsonrpc":"2.0","method":"optimism_syncStatus"}' \ -H "Content-Type: application/json" http://localhost:7545 | \ jq -r .result.unsafe_l2.timestamp))/60)) minutes ``` -You'll also know that the sync hasn't completed if you get `Error: nonce has already been used` if you try to deploy using your node. +If you attempt transactions or deployments before the node is fully synced, you might encounter errors like `Error: nonce has already been used`. + +## Optional Features + +The Base Node configuration supports optional features like EthStats monitoring and Trusted RPC mode. These can be enabled by uncommenting the relevant sections in your `.env` file (`.env.mainnet` or `.env.sepolia`). + +## Advanced Configuration and Networking (Geth) + +:::warning Advanced Users Only +Modifying the settings below requires familiarity with Geth configuration and Docker. Incorrect settings can impact node stability and performance. Proceed with caution. +::: + +The standard Base Node Docker setup for Geth uses specific configurations and exposes several ports. Understanding these can be helpful for firewall rules, monitoring, and advanced tuning. + +### Default Network Ports (Geth Container) + +- **HTTP RPC**: `8545` (Configurable via `$RPC_PORT` in `.env`) +- **WebSocket RPC**: `8546` (Configurable via `$WS_PORT` in `.env`) +- **Authenticated RPC (Engine API)**: `8551` (Configurable via `$AUTHRPC_PORT` in `.env`) +- **Metrics**: `6060` (Configurable via `$METRICS_PORT` in `.env`) +- **P2P Discovery/Connection**: `30303` (Configurable via `$P2P_PORT` in `.env`) + +Ensure these ports are accessible as needed, especially the P2P port (`30303`) for peer discovery if your node is behind a firewall. + +### Improving Peer Connectivity + +For better peer discovery, especially if running behind NAT, you can specify your external IP address. Add the following line to your `.env.mainnet` or `.env.sepolia` file: + +```dotenv +# .env.mainnet or .env.sepolia +ADDITIONAL_ARGS="--nat=extip:" +``` + +Replace `` with your actual public IP. You also need to ensure the P2P port (default `30303`) is open and forwarded correctly in your firewall/router configuration. + +### Geth Configuration via Environment Variables + +Several Geth parameters can be tuned by setting environment variables in your `.env.mainnet` or `.env.sepolia` file: + +- **Verbosity**: `GETH_VERBOSITY` (Default: `3`) - Controls log level. +- **Sync Mode**: `OP_GETH_SYNCMODE` (Default: `full`) - Geth sync strategy. +- **GC Mode**: `OP_GETH_GCMODE` (Default: `full`) - Garbage collection mode. +- **Cache Settings**: `GETH_CACHE`, `GETH_CACHE_DATABASE`, etc. (See [Node Performance](./node-performance.mdx#geth-cache-settings)). +- **Transaction Pool**: `GETH_TXPOOL_GLOBALQUEUE`, `GETH_TXPOOL_GLOBALSLOTS`, `GETH_TXPOOL_LIFETIME`, `TXPOOL_PRICE_LIMIT`. Fine-tuning these requires understanding Geth's transaction pool mechanics. + +Refer to the [official Geth documentation](https://geth.ethereum.org/docs/interface/command-line-options) for details on these parameters. + +### Base/Rollup Specific Flags + +The entrypoint script passes rollup-specific flags necessary for Base operation, such as: + +- `--rollup.disabletxpoolgossip=true`: Disables standard L1 transaction gossip over P2P. +- `--rollup.halt=major`: Halts the node on major configuration mismatches with the L1 chain. +- `--op-network="$OP_NODE_NETWORK"`: Sets the specific OP Stack network configuration (e.g., `base-mainnet`). + +## Advanced Configuration and Networking (Reth) + +:::warning Advanced Users Only +Modifying the settings below requires familiarity with Reth configuration and Docker. Incorrect settings can impact node stability and performance. Proceed with caution. +::: + +The standard Base Node Docker setup for Reth also uses specific configurations. + +### Default Network Ports & Sockets (Reth Container) + +- **HTTP RPC**: `8545` (Configurable via `$RPC_PORT` in `.env`) +- **WebSocket RPC**: `8546` (Configurable via `$WS_PORT` in `.env`) +- **Authenticated RPC (Engine API)**: `8551` (Configurable via `$AUTHRPC_PORT` in `.env`) +- **Metrics**: `6060` (Configurable via `$METRICS_PORT` in `.env`) +- **IPC Socket**: `/data/reth.ipc` (Path configurable via `--ipcpath` flag, see Reth docs) +- **P2P Discovery/Connection**: Default `30303` (Configurable via `--port` flag, see Reth docs) + +Ensure these ports/sockets are accessible as needed. + +### Node Type and Flashblocks + +The `NODE_TYPE` environment variable (default: `vanilla`) determines the Reth binary used: + +- `vanilla`: Uses the standard `op-reth` binary. +- `base`: Uses the `base-reth-node` binary. + +When `NODE_TYPE` is set to `base`, you can enable Flashblocks support by setting the `RETH_FB_WEBSOCKET_URL` environment variable in your `.env` file to your Flashblocks relay endpoint. + +### Reth Configuration via Environment Variables + +Key Reth parameters are configured via environment variables in `.env.mainnet` or `.env.sepolia`: + +- **Chain Spec**: `RETH_CHAIN` (Required, e.g., `base`, `base_sepolia`) - Specifies the network configuration. +- **Sequencer Endpoint**: `RETH_SEQUENCER_HTTP` (Required) - URL of the Base sequencer. + +Other Reth CLI flags can often be passed via `ADDITIONAL_ARGS` in the `.env` file, but consult the [official Reth documentation](https://paradigmxyz.github.io/reth/) for available options and syntax. + +### Verbosity + +The default Reth entrypoint runs with high verbosity (`-vvv`). This can be adjusted by modifying the entrypoint script directly or potentially overriding the command in a custom `docker-compose.override.yml` file. + +### Base/Rollup Specific Flags + +The entrypoint script passes rollup-specific flags necessary for Base operation, such as: + +- `--rollup.sequencer-http`: Configures the sequencer endpoint. +- `--rollup.disable-tx-pool-gossip`: Disables standard L1 transaction gossip over P2P. [docker]: https://www.docker.com/ -[base node]: https://github.com/base-org/node -[repo]: https://github.com/base-org/node -[partners]: /chain/node-providers +[Base Node]: https://github.com/base-org/node +[Base Node repository]: https://github.com/base-org/node +[Node Provider]: /chain/node-providers From 7e10a1f99470319381d37f24a483ae4d1f893bb2 Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 11:46:31 +0000 Subject: [PATCH 09/14] Add additional content to Snapshots doc --- .../docs/pages/chain/run-a-base-node.mdx | 2 +- apps/base-docs/docs/pages/chain/snapshots.mdx | 75 ++++++++++++++----- 2 files changed, 56 insertions(+), 21 deletions(-) diff --git a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx index ddb9549df83..22d75053d4b 100644 --- a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx +++ b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx @@ -2,7 +2,6 @@ title: Running a Base Node slug: /run-a-base-node description: A tutorial that teaches how to set up and run a Base Node. -author: taycaldwell & wbnns --- import Snapshots from './snapshots.mdx' @@ -23,6 +22,7 @@ By the end of this tutorial, you should be able to: ## Prerequisites :::warning + Is Running a Node Necessary? Running your own node is time-consuming, resource-intensive, and can be costly. If you don't have a specific reason, you might not need one. diff --git a/apps/base-docs/docs/pages/chain/snapshots.mdx b/apps/base-docs/docs/pages/chain/snapshots.mdx index 11b55986d9d..ba98479edb7 100644 --- a/apps/base-docs/docs/pages/chain/snapshots.mdx +++ b/apps/base-docs/docs/pages/chain/snapshots.mdx @@ -1,40 +1,75 @@ --- title: Snapshots slug: /snapshots -description: Information for how to restore a base node from a snapshots -author: taycaldwell & wbnns +description: Information for how to restore a Base node from a snapshot --- # 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. For Archive functionality, use Reth, which provides significantly better performance in Base’s high-throughput environment. +Geth Archive Nodes are no longer supported via snapshots due to performance limitations. For Archive functionality, please use Reth. ::: -If you're a prospective or current Base Node operator and would like to restore from a snapshot to save time on the initial sync, it's possible to always get the latest available snapshot of the Base chain on mainnet and/or testnet by using the following CLI commands. The snapshots are updated every week. +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 Geth: `mkdir ./geth-data` + - For Reth: `mkdir ./reth-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 ./geth-data/*`), and proceed. + +2. **Download Snapshot**: Choose the appropriate snapshot for your network and client from the table below. Use `wget` or a similar tool to download it into the `node` directory. + + | Network | Client | Snapshot Type | Download Command (`wget ...`) | + | ------- | ------ | ------------- | ---------------------------------------------------------------------------------------------------------------- | + | Testnet | Geth | Full | `https://sepolia-full-snapshots.base.org/$(curl https://sepolia-full-snapshots.base.org/latest)` | + | Testnet | Reth | Archive | `https://sepolia-reth-archive-snapshots.base.org/$(curl https://sepolia-reth-archive-snapshots.base.org/latest)` | + | Mainnet | Geth | Full | `https://mainnet-full-snapshots.base.org/$(curl https://mainnet-full-snapshots.base.org/latest)` | + | Mainnet | Reth | Archive | `https://mainnet-reth-archive-snapshots.base.org/$(curl https://mainnet-reth-archive-snapshots.base.org/latest)` | + + :::info + + Ensure you have enough free disk space to download the snapshot archive (`.tar.gz` file) _and_ extract its contents. The extracted data will be significantly larger than the archive. -#### Restoring from snapshot + ::: -In the home directory of your Base Node, create a folder named `geth-data` or `reth-data`. If you already have this folder, remove it to clear the existing state and then recreate it. Next, run the following code and wait for the operation to complete. +3. **Extract Snapshot**: Untar the downloaded snapshot archive. Replace `` with the actual downloaded filename. -| Network | Client | Snapshot Type | Command | -| ------- | ------ | ------------- | --------------------------------------------------------------------------------------------------------------------- | -| Testnet | Geth | Full | `wget https://sepolia-full-snapshots.base.org/$(curl https://sepolia-full-snapshots.base.org/latest)` | -| Testnet | Reth | Archive | `wget https://sepolia-reth-archive-snapshots.base.org/$(curl https://sepolia-reth-archive-snapshots.base.org/latest)` | -| Mainnet | Geth | Full | `wget https://mainnet-full-snapshots.base.org/$(curl https://mainnet-full-snapshots.base.org/latest)` | -| Mainnet | Reth | Archive | `wget https://mainnet-reth-archive-snapshots.base.org/$(curl https://mainnet-reth-archive-snapshots.base.org/latest)` | + ```bash + tar -xzvf + ``` -You'll then need to untar the downloaded snapshot and place the `geth` subfolder inside of it in the `geth-data` folder you created (unless you changed the location of your data directory). +4. **Move Data**: The extraction process will likely create a directory (e.g., `geth` or similar, check the output of the `tar` command). -Return to the root of your Base node folder and start your node. + - Move the _contents_ of this extracted directory into the data directory you created in Step 1. + - Example (if archive extracted to a `geth` folder): + ```bash + # For Geth + mv ./geth/* ./geth-data/ + rm -rf ./geth # Clean up empty extracted folder + ``` + - Example (if archive extracted to a `reth` folder - **verify actual folder name**): + ```bash + # For Reth + mv ./reth/* ./reth-data/ + rm -rf ./reth # Clean up empty extracted folder + ``` + - The goal is to have the chain data (directories like `chaindata`, `nodes`, `segments`, etc.) directly inside `./geth-data` or `./reth-data`, not within an extra subfolder. -```bash [Terminal] -cd .. -docker compose up --build -``` +5. **Start the Node**: Now that the snapshot data is in place, start the node using the appropriate command (see the [Running a Base Node](./run-a-base-node.mdx#setting-up-and-running-the-node) guide): -Your node should begin syncing from the last block in the snapshot. + ```bash + # Example for Mainnet Geth + docker compose up --build -d + ``` -Check the latest block to make sure you're syncing from the snapshot and that it restored correctly. If so, you can remove the snapshot archive that you downloaded. +6. **Verify and Clean Up**: Monitor the node logs (`docker compose logs -f `) or use the [sync monitoring](./run-a-base-node.mdx#monitoring-sync-progress) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive (`.tar.gz` file) to free up disk space. From cd23765974831af5a9f8cfe3e7fad42582239148 Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 11:55:59 +0000 Subject: [PATCH 10/14] Add content for troubleshooting page --- .../{snapshots.mdx => node-snapshots.mdx} | 8 +- .../docs/pages/chain/node-troubleshooting.mdx | 109 ++++++++++++++++++ .../docs/pages/chain/troubleshooting.mdx | 13 --- apps/base-docs/sidebar.ts | 8 +- 4 files changed, 117 insertions(+), 21 deletions(-) rename apps/base-docs/docs/pages/chain/{snapshots.mdx => node-snapshots.mdx} (90%) create mode 100644 apps/base-docs/docs/pages/chain/node-troubleshooting.mdx delete mode 100644 apps/base-docs/docs/pages/chain/troubleshooting.mdx diff --git a/apps/base-docs/docs/pages/chain/snapshots.mdx b/apps/base-docs/docs/pages/chain/node-snapshots.mdx similarity index 90% rename from apps/base-docs/docs/pages/chain/snapshots.mdx rename to apps/base-docs/docs/pages/chain/node-snapshots.mdx index ba98479edb7..534922a0d11 100644 --- a/apps/base-docs/docs/pages/chain/snapshots.mdx +++ b/apps/base-docs/docs/pages/chain/node-snapshots.mdx @@ -1,6 +1,6 @@ --- -title: Snapshots -slug: /snapshots +title: Node Snapshots +slug: /node-snapshots description: Information for how to restore a Base node from a snapshot --- @@ -65,11 +65,11 @@ These steps assume you are in the cloned `node` directory (the one containing `d ``` - The goal is to have the chain data (directories like `chaindata`, `nodes`, `segments`, etc.) directly inside `./geth-data` or `./reth-data`, not within an extra subfolder. -5. **Start the Node**: Now that the snapshot data is in place, start the node using the appropriate command (see the [Running a Base Node](./run-a-base-node.mdx#setting-up-and-running-the-node) guide): +5. **Start the Node**: Now that the snapshot data is in place, start the node using the appropriate command (see the [Running a Base Node](/chain/run-a-base-node#setting-up-and-running-the-node) guide): ```bash # Example for Mainnet Geth docker compose up --build -d ``` -6. **Verify and Clean Up**: Monitor the node logs (`docker compose logs -f `) or use the [sync monitoring](./run-a-base-node.mdx#monitoring-sync-progress) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive (`.tar.gz` file) to free up disk space. +6. **Verify and Clean Up**: Monitor the node logs (`docker compose logs -f `) or use the [sync monitoring](/chain/run-a-base-node#monitoring-sync-progress) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive (`.tar.gz` file) to free up disk space. diff --git a/apps/base-docs/docs/pages/chain/node-troubleshooting.mdx b/apps/base-docs/docs/pages/chain/node-troubleshooting.mdx new file mode 100644 index 00000000000..75959c0e2ab --- /dev/null +++ b/apps/base-docs/docs/pages/chain/node-troubleshooting.mdx @@ -0,0 +1,109 @@ +--- +title: Node Troubleshooting +slug: /node-troubleshooting +description: A guide to diagnosing and resolving common issues when running a Base node. +author: hndvx +--- + +# Node Troubleshooting + +This guide covers common issues encountered when setting up and running a Base node using the official [Base Node Docker setup](https://github.com/base/node) and provides steps to diagnose and resolve them. + +## General Troubleshooting Steps + +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 ` to view the real-time logs for a specific container. + - L2 Client (Geth): `docker compose logs -f op-geth` + - L2 Client (Reth): `docker compose logs -f op-reth` + - Rollup Node: `docker compose logs -f op-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. +3. **Check Resource Usage**: Monitor your server's CPU, RAM, disk I/O, and network usage. Performance issues are often linked to insufficient resources. Tools like `htop`, `iostat`, and `iftop` can be helpful. +4. **Verify RPC Endpoints**: Use `curl` to check if the L2 client's RPC endpoint is responding (see [Running a Base Node > Verify Node is Running](./run-a-base-node#verify-node-is-running)). Also, verify your L1 endpoints are correct and accessible from the node server. +5. **Check L1 Node**: Ensure your configured L1 node (Execution and Consensus) is fully synced, healthy, and accessible. Issues with the L1 node will prevent the L2 node from syncing correctly. + +## Common Issues and Solutions + +### Setup & Configuration Issues + +- **Issue**: Docker command fails (`docker compose up ...`). + - **Check**: Is Docker and Docker Compose installed and the Docker daemon running? + - **Check**: Are you in the correct directory (the cloned `node` directory containing `docker-compose.yml`)? + - **Check**: Syntax errors in the command (e.g., misspelled `NETWORK_ENV` or `CLIENT`). +- **Issue**: Container fails to start, logs show errors related to `.env` files or environment variables. + - **Check**: Did you correctly configure the L1 endpoints (`OP_NODE_L1_ETH_RPC`, `OP_NODE_L1_BEACON`) in the correct `.env` file (`.env.mainnet` or `.env.sepolia`)? + - **Check**: Is the `OP_NODE_L1_BEACON_ARCHIVER` endpoint set if required by your configuration or L1 node? + - **Check**: Is `OP_NODE_L1_RPC_KIND` set correctly for your L1 provider? + - **Check**: (Reth) Are `RETH_CHAIN` and `RETH_SEQUENCER_HTTP` correctly set in the `.env` file? +- **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 (`./geth-data`, `./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 `./geth-data` or `./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 + +- **Issue**: Node doesn't start syncing or appears stuck (block height not increasing). + - **Check**: `op-node` logs. Look for errors connecting to L1 endpoints or the L2 client. + - **Check**: L2 client (`op-geth`/`op-reth`) logs. Look for errors connecting to `op-node` via the Engine API (port `8551`) or P2P issues. + - **Check**: L1 node health and sync status. Is the L1 node accessible and fully synced? + - **Check**: System time. Ensure the server's clock is accurately synchronized (use `ntp` or `chrony`). Significant time drift can cause P2P issues. +- **Issue**: Syncing is extremely slow. + - **Check**: Hardware specifications. Are you meeting the recommended specs (especially RAM and **NVMe SSD**) outlined in the [Node Performance](./node-performance) guide? Disk I/O is often the bottleneck. + - **Check**: L1 node performance. Is your L1 RPC endpoint responsive? A slow L1 node will slow down L2 sync. + - **Check**: Network connection quality and bandwidth. + - **Check**: `op-node` and L2 client logs for any performance warnings or errors. +- **Issue**: `optimism_syncStatus` (port `7545` on `op-node`) shows a large time difference or errors. + - **Action**: Check the logs for both `op-node` and the L2 client (`op-geth`/`op-reth`) around the time the status was checked to identify the root cause (e.g., L1 connection issues, L2 client issues). +- **Issue**: `Error: nonce has already been used` when trying to send transactions. + - **Cause**: The node is not yet fully synced to the head of the chain. + - **Action**: Wait for the node to fully sync. Monitor progress using `optimism_syncStatus` or logs. + +### Performance Issues + +- **Issue**: High CPU, RAM, or Disk I/O usage. + - **Check**: Hardware specifications against recommendations in [Node Performance](./node-performance). Upgrade if necessary. Local NVMe SSDs are critical. + - **Check**: (Geth) Review Geth cache settings and LevelDB tuning options mentioned in [Node Performance](./node-performance#geth-performance-tuning) and [Advanced Configuration](./run-a-base-node#geth-configuration-via-environment-variables). + - **Check**: Review client logs for specific errors or bottlenecks. + - **Action**: Consider using Reth if running Geth, as it's generally more performant for Base. + +### Snapshot Restoration Problems + +Refer to the [Snapshots](./node-snapshots) guide for the correct procedure. + +- **Issue**: `wget` command fails or snapshot download is corrupted. + - **Check**: Network connectivity. + - **Check**: Available disk space. + - **Action**: Retry the download. Verify the download URL is correct. +- **Issue**: `tar` extraction fails. + - **Check**: Downloaded file integrity (is it corrupted?). + - **Check**: Available disk space (extraction requires much more space than the download). + - **Check**: `tar` command syntax. +- **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 (`./geth-data/*` or `./reth-data/*`) before extracting/moving the snapshot data? + - **Check**: Was the snapshot data moved correctly? The chain data needs to be directly inside `./geth-data` or `./reth-data`, not in a nested subfolder (e.g., `./geth-data/geth/...`). 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: `(2 * chain_size + snapshot_size + 20% buffer)`. + +### Networking / Connectivity Issues + +- **Issue**: RPC/WS connection refused (e.g., `curl` to `localhost:8545` fails). + - **Check**: Is the L2 client container (`op-geth`/`op-reth`) running (`docker compose ps`)? + - **Check**: Are you using the correct port (`8545` for HTTP, `8546` for WS by default)? + - **Check**: L2 client logs. Did it fail to start the RPC server? + - **Check**: Are the `--http.addr` and `--ws.addr` flags set to `0.0.0.0` in the client config/entrypoint to allow external connections (within the Docker network)? +- **Issue**: Node has low peer count. + - **Check**: P2P port (default `30303`) accessibility. Is it blocked by a firewall on the host or network? + - **Check**: Node logs for P2P errors. + - **Action**: If behind NAT, configure the `--nat=extip:` flag via `ADDITIONAL_ARGS` in the `.env` file (see [Advanced Configuration](./run-a-base-node#improving-peer-connectivity)). +- **Issue**: Port conflicts reported in logs or `docker compose up` fails. + - **Check**: Are other services running on the host using the default ports (`8545`, `8546`, `8551`, `6060`, `7545`, `30303`)? Use `sudo lsof -i -P -n | grep LISTEN` or `sudo netstat -tulpn | grep LISTEN`. + - **Action**: Stop the conflicting service or change the ports used by the Base node containers by modifying the `ports` section in `docker-compose.yml` and updating the relevant environment variables (`$RPC_PORT`, `$WS_PORT`, etc.) in the `.env` file if necessary. + +## Getting Further Help + +If you've followed this guide and are still encountering issues, seek help from the community: + +- **Discord**: Join the [Base Discord](https://discord.gg/buildonbase) and post in the `🛠｜node-operators` channel, providing details about your setup, the issue, and relevant logs. +- **GitHub**: Check the [Base Node repository issues](https://github.com/base-org/node/issues) or open a new one if you suspect a bug. diff --git a/apps/base-docs/docs/pages/chain/troubleshooting.mdx b/apps/base-docs/docs/pages/chain/troubleshooting.mdx deleted file mode 100644 index 6c8d73c8636..00000000000 --- a/apps/base-docs/docs/pages/chain/troubleshooting.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Troubleshooting -slug: /troubleshooting -description: Information on how to troubleshooting a Base node -author: hndvx ---- - -# Troubleshooting - -If you still cannot resolve the problems with your node, please open a GitHub issue or reach out on our Discord: - -Once you've joined, in the Discord app go to server menu > Linked Roles > connect GitHub and connect your GitHub account so you can gain access to our developer channels -Report your issue in #🛟|developer-support or 🛠 ｜ node-operators diff --git a/apps/base-docs/sidebar.ts b/apps/base-docs/sidebar.ts index 4db1bf86a1c..110362da125 100644 --- a/apps/base-docs/sidebar.ts +++ b/apps/base-docs/sidebar.ts @@ -1037,10 +1037,10 @@ export const sidebar: Sidebar = [ text: 'Node Operators', collapsed: true, items: [ - { text: 'Node Performance', link: '/chain/node-performance' }, - { text: 'Run a Base Node', link: '/chain/run-a-base-node' }, - { text: 'Snapshots', link: '/chain/snapshots' }, - { text: 'Troubleshooting', link: '/chain/troubleshooting' }, + { text: 'Getting Started', link: '/chain/run-a-base-node' }, + { text: 'Performance Tuning', link: '/chain/node-performance' }, + { text: 'Snapshots', link: '/chain/node-snapshots' }, + { text: 'Troubleshooting', link: '/chain/node-troubleshooting' }, ], }, { From 94c3e983af9a8d35536082514a3f6c09236e087f Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 12:14:05 +0000 Subject: [PATCH 11/14] Fix link to node snapshots --- apps/base-docs/docs/pages/chain/run-a-base-node.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx index 22d75053d4b..f4287fd7a7c 100644 --- a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx +++ b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx @@ -4,7 +4,7 @@ slug: /run-a-base-node description: A tutorial that teaches how to set up and run a Base Node. --- -import Snapshots from './snapshots.mdx' +import Snapshots from './node-snapshots.mdx' # Running a Base Node From 45ec2694ac8d91d1a5ffe754494788059ec00766 Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 12:15:38 +0000 Subject: [PATCH 12/14] Fix link to the Connecting to Base page --- .../docs/pages/chain/{connecting.mdx => connecting-to-base.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename apps/base-docs/docs/pages/chain/{connecting.mdx => connecting-to-base.mdx} (100%) diff --git a/apps/base-docs/docs/pages/chain/connecting.mdx b/apps/base-docs/docs/pages/chain/connecting-to-base.mdx similarity index 100% rename from apps/base-docs/docs/pages/chain/connecting.mdx rename to apps/base-docs/docs/pages/chain/connecting-to-base.mdx From 3b7fe2f690722e805f2fcfeb679e2ca08d110680 Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 12:33:47 +0000 Subject: [PATCH 13/14] Fix warning boxes on running a node page --- apps/base-docs/docs/pages/chain/run-a-base-node.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx index f4287fd7a7c..f87a7d45b1f 100644 --- a/apps/base-docs/docs/pages/chain/run-a-base-node.mdx +++ b/apps/base-docs/docs/pages/chain/run-a-base-node.mdx @@ -148,8 +148,10 @@ The Base Node configuration supports optional features like EthStats monitoring ## Advanced Configuration and Networking (Geth) -:::warning Advanced Users Only +:::warning + Modifying the settings below requires familiarity with Geth configuration and Docker. Incorrect settings can impact node stability and performance. Proceed with caution. + ::: The standard Base Node Docker setup for Geth uses specific configurations and exposes several ports. Understanding these can be helpful for firewall rules, monitoring, and advanced tuning. @@ -197,8 +199,10 @@ The entrypoint script passes rollup-specific flags necessary for Base operation, ## Advanced Configuration and Networking (Reth) -:::warning Advanced Users Only +:::warning + Modifying the settings below requires familiarity with Reth configuration and Docker. Incorrect settings can impact node stability and performance. Proceed with caution. + ::: The standard Base Node Docker setup for Reth also uses specific configurations. From dc474a2dd84f3fc76be8a55c5515c210ce49fc1e Mon Sep 17 00:00:00 2001 From: wbnns Date: Fri, 2 May 2025 12:39:40 +0000 Subject: [PATCH 14/14] Fix additional and callouts --- apps/base-docs/docs/pages/chain/node-performance.mdx | 4 ++-- .../docs/pages/chain/node-troubleshooting.mdx | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/apps/base-docs/docs/pages/chain/node-performance.mdx b/apps/base-docs/docs/pages/chain/node-performance.mdx index 4f2cdbd63fa..ec150c69c37 100644 --- a/apps/base-docs/docs/pages/chain/node-performance.mdx +++ b/apps/base-docs/docs/pages/chain/node-performance.mdx @@ -19,7 +19,7 @@ Running a performant Base node requires adequate hardware. We recommend the foll 3. A locally attached NVMe SSD drive. RAID 0 configurations can improve performance. 4. Sufficient storage capacity calculated as: `(2 * [current chain size](https://base.org/stats) + [snapshot size](https://basechaindata.vercel.app) + 20% buffer)`. This accounts for chain data growth and snapshot restoration space. -:::info EBS Recommendations +:::info If utilizing Amazon Elastic Block Store (EBS), io2 Block Express volumes are recommended to ensure sufficient disk read speeds, preventing latency issues during initial sync. However, **locally attached NVMe SSDs are strongly recommended over networked storage for optimal performance.** @@ -40,7 +40,7 @@ The following are the hardware specifications used for Base production nodes: ## Initial Sync -Using a recent [snapshot](run-a-base-node.mdx#snapshots) can significantly reduce the time required for the initial node synchronization process. +Using a recent [snapshot](/chain/snapshots) can significantly reduce the time required for the initial node synchronization process. ## Client Software diff --git a/apps/base-docs/docs/pages/chain/node-troubleshooting.mdx b/apps/base-docs/docs/pages/chain/node-troubleshooting.mdx index 75959c0e2ab..92aae031998 100644 --- a/apps/base-docs/docs/pages/chain/node-troubleshooting.mdx +++ b/apps/base-docs/docs/pages/chain/node-troubleshooting.mdx @@ -49,7 +49,7 @@ Before diving into specific issues, here are some general steps that often help: - **Check**: L1 node health and sync status. Is the L1 node accessible and fully synced? - **Check**: System time. Ensure the server's clock is accurately synchronized (use `ntp` or `chrony`). Significant time drift can cause P2P issues. - **Issue**: Syncing is extremely slow. - - **Check**: Hardware specifications. Are you meeting the recommended specs (especially RAM and **NVMe SSD**) outlined in the [Node Performance](./node-performance) guide? Disk I/O is often the bottleneck. + - **Check**: Hardware specifications. Are you meeting the recommended specs (especially RAM and **NVMe SSD**) outlined in the [Node Performance](/chain/node-performance) guide? Disk I/O is often the bottleneck. - **Check**: L1 node performance. Is your L1 RPC endpoint responsive? A slow L1 node will slow down L2 sync. - **Check**: Network connection quality and bandwidth. - **Check**: `op-node` and L2 client logs for any performance warnings or errors. @@ -62,14 +62,14 @@ Before diving into specific issues, here are some general steps that often help: ### Performance Issues - **Issue**: High CPU, RAM, or Disk I/O usage. - - **Check**: Hardware specifications against recommendations in [Node Performance](./node-performance). Upgrade if necessary. Local NVMe SSDs are critical. - - **Check**: (Geth) Review Geth cache settings and LevelDB tuning options mentioned in [Node Performance](./node-performance#geth-performance-tuning) and [Advanced Configuration](./run-a-base-node#geth-configuration-via-environment-variables). + - **Check**: Hardware specifications against recommendations in [Node Performance](/chain/node-performance). Upgrade if necessary. Local NVMe SSDs are critical. + - **Check**: (Geth) Review Geth cache settings and LevelDB tuning options mentioned in [Node Performance](/chain/node-performance#geth-performance-tuning) and [Advanced Configuration](/chain/run-a-base-node#geth-configuration-via-environment-variables). - **Check**: Review client logs for specific errors or bottlenecks. - **Action**: Consider using Reth if running Geth, as it's generally more performant for Base. ### Snapshot Restoration Problems -Refer to the [Snapshots](./node-snapshots) guide for the correct procedure. +Refer to the [Snapshots](/chain/node-snapshots) guide for the correct procedure. - **Issue**: `wget` command fails or snapshot download is corrupted. - **Check**: Network connectivity. @@ -96,7 +96,7 @@ Refer to the [Snapshots](./node-snapshots) guide for the correct procedure. - **Issue**: Node has low peer count. - **Check**: P2P port (default `30303`) accessibility. Is it blocked by a firewall on the host or network? - **Check**: Node logs for P2P errors. - - **Action**: If behind NAT, configure the `--nat=extip:` flag via `ADDITIONAL_ARGS` in the `.env` file (see [Advanced Configuration](./run-a-base-node#improving-peer-connectivity)). + - **Action**: If behind NAT, configure the `--nat=extip:` flag via `ADDITIONAL_ARGS` in the `.env` file (see [Advanced Configuration](/chain/run-a-base-node#improving-peer-connectivity)). - **Issue**: Port conflicts reported in logs or `docker compose up` fails. - **Check**: Are other services running on the host using the default ports (`8545`, `8546`, `8551`, `6060`, `7545`, `30303`)? Use `sudo lsof -i -P -n | grep LISTEN` or `sudo netstat -tulpn | grep LISTEN`. - **Action**: Stop the conflicting service or change the ports used by the Base node containers by modifying the `ports` section in `docker-compose.yml` and updating the relevant environment variables (`$RPC_PORT`, `$WS_PORT`, etc.) in the `.env` file if necessary.