From abec6acee00b12465a65c667fb3c236a97308335 Mon Sep 17 00:00:00 2001 From: Henri Devieux Date: Fri, 25 Apr 2025 00:54:58 -0400 Subject: [PATCH] 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', - }, ], }, {