From 575a049ea541c520504c613bb6696dc75fc035fa Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Fri, 4 Oct 2024 01:17:35 -0400 Subject: [PATCH] Add xperimental features and add table for how sync works (#1662) * update with experimental Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * update spelling Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * fix typo Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * fix typo Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * add suggestions Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Simon Dudley Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * fix broken links Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * update with suggestions Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * update broken Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * Update table for consistency Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> --------- Signed-off-by: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Co-authored-by: Simon Dudley Co-authored-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> --- .../concepts/node-sync-private.md | 44 ++++++++++ .../get-started/start-node.md | 2 +- .../how-to/configure/consensus/ibft.md | 9 ++ .../how-to/configure/consensus/qbft.md | 9 ++ .../concepts/data-storage-formats.md | 16 ++-- .../concepts/events-and-logs.md | 2 +- docs/public-networks/concepts/genesis-file.md | 2 +- .../concepts/network-and-chain-id.md | 2 +- docs/public-networks/concepts/node-keys.md | 2 +- .../sync-node.md => concepts/node-sync.md} | 86 +++++++++++++------ .../parallel-transaction-execution.md | 3 +- .../concepts/transactions/_category_.json | 2 +- .../get-started/migrate-to-besu.md | 2 +- .../public-networks/get-started/start-node.md | 4 +- .../how-to/configure-besu/index.md | 2 +- .../how-to/connect/manage-peers.md | 2 +- .../how-to/monitor/understand-metrics.md | 2 +- .../how-to/troubleshoot/peering.md | 2 +- .../how-to/troubleshoot/trace-transactions.md | 2 +- docs/public-networks/reference/api/index.md | 8 +- docs/public-networks/reference/cli/options.md | 4 +- .../tutorials/besu-teku-mainnet.md | 2 +- 22 files changed, 155 insertions(+), 54 deletions(-) create mode 100644 docs/private-networks/concepts/node-sync-private.md rename docs/public-networks/{get-started/connect/sync-node.md => concepts/node-sync.md} (68%) diff --git a/docs/private-networks/concepts/node-sync-private.md b/docs/private-networks/concepts/node-sync-private.md new file mode 100644 index 00000000000..b2bef82622c --- /dev/null +++ b/docs/private-networks/concepts/node-sync-private.md @@ -0,0 +1,44 @@ +--- +sidebar_label: Node synchronization +sidebar_position: 4 +description: Learn about node synchronization for private networks. +tags: + - private networks +--- + +# Node synchronization for private networks + +For private, permissioned blockchain networks, Besu uses the same [synchronization +modes](/public-networks/concepts/node-sync.md) as public networks, but with specific configurations for private network needs. + +To sync Besu on a private network: + +- Ensure all nodes use compatible sync modes and configurations. +- Configure the network with a custom genesis file. +- Set the network ID and bootnodes specific to your private network. +- Implement permissioning features to control network access. + +Choose the appropriate sync mode based on your private network's requirements and node purposes. + +| Sync mode | Description | Requirements | Limitations | +|-----------|-------------|--------------|-------------| +| [Snap](../../public-networks/concepts/node-sync.md#snap-synchronization) | Recommended for fastest sync and lowest storage requirements on Mainnet. Downloads as many leaves of the trie as possible and reconstructs the trie locally. Faster than fast sync. | Available as an _early access feature_ in Besu version 24.7.1 or later | Cannot switch from fast sync to snap sync mid-process. | +| [Checkpoint](../../public-networks/concepts/node-sync.md#checkpoint-synchronization) | Syncs from a specific checkpoint block configured in the genesis file. Fastest sync mode with lowest storage requirements. | Besu version 22.4.3 or later | Not supported for QBFT or IBFT 2.0 networks without a checkpoint configuration. | +| [Fast](../../public-networks/concepts/node-sync.md#fast-synchronization) |Default for named networks except `dev`. Downloads block headers and transaction receipts, verifies chain from genesis block. | None | Not supported with private transactions. | +| [Full](../../public-networks/concepts/node-sync.md#run-an-archive-node) | Downloads and verifies the entire blockchain and state from genesis block, building an archive node with full state history. | None | Slowest sync mode, requires the most disk space. | + +:::warning Early access feature + +`--Xsnapsync-bft-enabled` is an early access feature available in Besu version 24.7.1 and later. +It is not stable, so use this option with caution. + +Use `--Xsnapsync-bft-enabled` with `--sync-mode=SNAP` to enable snap sync in QBFT and IBFT 2.0 private networks. + +::: + +:::tip + +We recommend snap sync because it follows the Ethereum specification and enables you to serve full historical data. + +::: + diff --git a/docs/private-networks/get-started/start-node.md b/docs/private-networks/get-started/start-node.md index ef1f8f57c22..0a7559a38fd 100644 --- a/docs/private-networks/get-started/start-node.md +++ b/docs/private-networks/get-started/start-node.md @@ -107,7 +107,7 @@ You might need to set [`--tx-pool-limit-by-account-percentage`](../../public-net :::note Sync nodes for BFT -If you're running a node on a [QBFT](../how-to/configure/consensus/qbft.md) or [IBFT 2.0](../how-to/configure/consensus/ibft.md) network, your node must use [fast sync](../../public-networks/get-started/connect/sync-node.md#fast-synchronization) or [full sync](../../public-networks/get-started/connect/sync-node.md#run-an-archive-node). +If you're running a node on a [QBFT](../how-to/configure/consensus/qbft.md) or [IBFT 2.0](../how-to/configure/consensus/ibft.md) network, your node must use [fast sync](../../public-networks/concepts/node-sync.md#fast-synchronization) or [full sync](../../public-networks/concepts/node-sync.md#run-an-archive-node). Full sync is set by default. diff --git a/docs/private-networks/how-to/configure/consensus/ibft.md b/docs/private-networks/how-to/configure/consensus/ibft.md index bc98b4f86d2..f39a2220d5b 100644 --- a/docs/private-networks/how-to/configure/consensus/ibft.md +++ b/docs/private-networks/how-to/configure/consensus/ibft.md @@ -31,6 +31,15 @@ You can use a plugin to securely store a validator's key using the [`--security- ::: +:::warning Early access feature + +`--Xsnapsync-bft-enabled` is an early access feature available in Besu version 24.7.1 and later. +It is not stable, so use this option with caution. + +Use `--Xsnapsync-bft-enabled` with `--sync-mode=SNAP` to enable snap sync in IBFT 2.0 networks. + +::: + ## Genesis file To use IBFT 2.0, Besu requires an IBFT 2.0 [genesis file](../../../../public-networks/concepts/genesis-file.md). The genesis file defines properties specific to IBFT 2.0. diff --git a/docs/private-networks/how-to/configure/consensus/qbft.md b/docs/private-networks/how-to/configure/consensus/qbft.md index 1b9178e6f23..205dde8c246 100644 --- a/docs/private-networks/how-to/configure/consensus/qbft.md +++ b/docs/private-networks/how-to/configure/consensus/qbft.md @@ -31,6 +31,15 @@ You can use a plugin to securely store a validator's key using the [`--security- ::: +:::warning Early access feature + +`--Xsnapsync-bft-enabled` is an early access feature available in Besu version 24.7.1 and later. +It is not stable, so use this option with caution. + +Use `--Xsnapsync-bft-enabled` with `--sync-mode=SNAP` to enable snap sync in QBFT networks. + +::: + ## Genesis file To use QBFT, define a [genesis file](../../../../public-networks/concepts/genesis-file.md) that contains the QBFT properties. diff --git a/docs/public-networks/concepts/data-storage-formats.md b/docs/public-networks/concepts/data-storage-formats.md index fe6ead1ad1b..8331b28c9e9 100644 --- a/docs/public-networks/concepts/data-storage-formats.md +++ b/docs/public-networks/concepts/data-storage-formats.md @@ -25,17 +25,21 @@ To run a node with Bonsai Tries data storage format, use the command line option

:::caution important -Do not run an [archive node](../get-started/connect/sync-node.md#run-an-archive-node) with Bonsai Tries. + +Do not run an [archive node](node-sync.md#run-an-archive-node) with Bonsai Tries. Bonsai is designed for retrieving recent data only. + ::: :::tip + You can read more about Bonsai in [Consensys' Guide to Bonsai Tries](https://consensys.io/blog/bonsai-tries-guide). + ::: ## Forest of Tries -Forest of Tries, also called forest mode, is another method of representing the world state, and is more suitable for [archive nodes](../get-started/connect/sync-node.md#run-an-archive-node). +Forest of Tries, also called forest mode, is another method of representing the world state, and is more suitable for [archive nodes](node-sync.md#run-an-archive-node). In forest mode, each node in the trie is saved in a key-value store by hash. For each block, the world state is updated with new nodes, leaf nodes, and a new state root. Old leaf nodes remain in the underlying data store. Data is accessed and stored by hash, which increases the size of the database and increases the resources and time needed to access account data. @@ -46,8 +50,10 @@ In forest mode, each node in the trie is saved in a key-value store by hash. For

:::warning + Forest pruning using the `--pruning-enabled` option is no longer supported. We recommend using [Bonsai Tries](#bonsai-tries) to save disk space. + ::: ## Forest of Tries vs. Bonsai Tries @@ -55,9 +61,9 @@ We recommend using [Bonsai Tries](#bonsai-tries) to save disk space. ### Storage requirements Forest mode uses significantly more memory than Bonsai. -With a [full node](../get-started/connect/sync-node.md#run-a-full-node), forest mode uses an +With a [full node](node-sync.md#run-a-full-node), forest mode uses an estimated 750 GB of storage, while Bonsai uses an estimated 650 GB of storage. -[Archive nodes](../get-started/connect/sync-node.md#run-an-archive-node) must use forest mode, which +[Archive nodes](node-sync.md#run-an-archive-node) must use forest mode, which uses an estimated 12 TB of storage. ### Accessing data @@ -74,7 +80,7 @@ Using `--bonsai-historical-block-limit` doesn't affect the size of the database ### Syncing nodes -The following table shows the ways you can [sync a full node](../get-started/connect/sync-node.md#run-a-full-node) with the different data storage formats using [fast](../get-started/connect/sync-node.md#fast-synchronization) and [snap](../get-started/connect/sync-node.md#snap-synchronization) sync. +The following table shows the ways you can [sync a full node](node-sync.md#run-a-full-node) with the different data storage formats using [fast](node-sync.md#fast-synchronization) and [snap](node-sync.md#snap-synchronization) sync. | Data storage format | Sync mode | Storage estimate | Can other nodes sync to your node? | | --- | --- | --- | --- | diff --git a/docs/public-networks/concepts/events-and-logs.md b/docs/public-networks/concepts/events-and-logs.md index f3b769eb8b5..f5c63f7e01d 100644 --- a/docs/public-networks/concepts/events-and-logs.md +++ b/docs/public-networks/concepts/events-and-logs.md @@ -1,6 +1,6 @@ --- title: Events and logs -sidebar_position: 7 +sidebar_position: 8 description: Learn about events and logs in Besu. tags: - public networks diff --git a/docs/public-networks/concepts/genesis-file.md b/docs/public-networks/concepts/genesis-file.md index c743109bd62..762c6fccbb9 100644 --- a/docs/public-networks/concepts/genesis-file.md +++ b/docs/public-networks/concepts/genesis-file.md @@ -1,6 +1,6 @@ --- title: Genesis file -sidebar_position: 8 +sidebar_position: 9 description: Learn about configuring a network using the genesis file. tags: - public networks diff --git a/docs/public-networks/concepts/network-and-chain-id.md b/docs/public-networks/concepts/network-and-chain-id.md index bb90d32726d..ae5f6afe213 100644 --- a/docs/public-networks/concepts/network-and-chain-id.md +++ b/docs/public-networks/concepts/network-and-chain-id.md @@ -1,6 +1,6 @@ --- title: Network ID and chain ID -sidebar_position: 6 +sidebar_position: 7 description: Learn about network ID and chain ID in Besu. tags: - public networks diff --git a/docs/public-networks/concepts/node-keys.md b/docs/public-networks/concepts/node-keys.md index 261e34e3b82..8b220dee17e 100644 --- a/docs/public-networks/concepts/node-keys.md +++ b/docs/public-networks/concepts/node-keys.md @@ -1,6 +1,6 @@ --- title: Node keys -sidebar_position: 9 +sidebar_position: 10 description: Learn about node public and private keys, and the node address. tags: - public networks diff --git a/docs/public-networks/get-started/connect/sync-node.md b/docs/public-networks/concepts/node-sync.md similarity index 68% rename from docs/public-networks/get-started/connect/sync-node.md rename to docs/public-networks/concepts/node-sync.md index 921b12ecff1..9583aa4de3f 100644 --- a/docs/public-networks/get-started/connect/sync-node.md +++ b/docs/public-networks/concepts/node-sync.md @@ -1,18 +1,18 @@ --- -title: Sync Besu -sidebar_position: 1 -description: Full and archive node types +title: Node synchronization +sidebar_position: 4 +description: Learn about node synchronization for public networks. tags: - public networks --- -# Sync Besu +# Node synchronization Besu supports two node types, commonly referred to as [full nodes](#run-a-full-node) and [archive nodes](#run-an-archive-node). A full node consists of an -[execution and consensus client](../../concepts/node-clients.md#execution-and-consensus-clients), +[execution and consensus client](node-clients.md#execution-and-consensus-clients), and stores a local copy of the blockchain. With a full node, you can check current balances, sign and send transactions, and look at current dapp data. @@ -28,7 +28,39 @@ Archive nodes can do everything full nodes do, and they can also access historic This means that archive nodes require more disk space than full nodes. Besu must connect with other peers to sync with the network. If your node is having trouble peering, -try [troubleshooting peering](../../how-to/troubleshoot/peering.md). +try [troubleshooting peering](../how-to/troubleshoot/peering.md). + +## Sync modes + +Besu supports several sync modes for different network types and use cases. +For public networks, Besu offers the following sync modes: + +| Sync mode | Description | Requirements | Limitations | +|-----------|-------------|--------------|-------------| +| [Snap](#snap-synchronization) | Default for Mainnet. Efficient sync from genesis block, downloading as many trie leaves as possible and reconstructing locally. Faster than fast sync. | Besu version 22.4.0 or later | Cannot switch from fast sync to snap sync mid-process. | +| [Checkpoint](#checkpoint-synchronization) | Syncs from a specific checkpoint block configured in the genesis file. Fastest sync mode with lowest storage requirements. | Besu version 22.4.3 or later | | +| [Fast](#fast-synchronization) | Default for named networks except `dev`. Downloads block headers and transaction receipts, verifies chain from genesis block. | None | Might become impossible to fast sync Ethereum Mainnet in the future. | +| [Full](#run-an-archive-node) | Downloads and verifies the entire blockchain and state from genesis block, building an archive node with full state history. | None | Slowest sync mode, requires the most disk space. | + +:::tip + +We recommend snap sync because it follows the Ethereum specification and enables you to serve full historical data. + +::: + +:::note + +Ethereum nodes sync two types of data: chain data (blocks) and world state data (account storage). +Snap and checkpoint syncs handle chain data similarly to fast sync, but differ in how they process world state data. + +::: + +:::note Private network syncing + +Private networks can use the same sync methods as public networks, but might require different configurations. +See [Node synchronization for private networks](../../private-networks/concepts/node-sync-private.md) for more information. + +::: ## Sync times @@ -55,15 +87,15 @@ Each sync mode also has its own world state database size. :::note Notes - As of late 2023, an average Mainnet snap sync consumes around 1000 GB using Bonsai Tries. - Read more about [storage requirements](../../concepts/data-storage-formats.md#storage-requirements) + Read more about [storage requirements](data-storage-formats.md#storage-requirements) across data storage formats and sync modes. - Testnets take significantly less time and space to sync. ::: ## Storage -You can store the world state using [Forest of Tries](../../concepts/data-storage-formats.md#forest-of-tries) -or [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries). +You can store the world state using [Forest of Tries](data-storage-formats.md#forest-of-tries) +or [Bonsai Tries](data-storage-formats.md#bonsai-tries). If you're [running a full node](#run-a-full-node), we recommend using Bonsai Tries for the lowest storage requirements. @@ -78,8 +110,8 @@ You can run a full node using [snap synchronization (snap sync)](#snap-synchroni :::note Sync nodes for BFT Snap sync and checkpoint sync are not supported for -[QBFT](../../../private-networks/how-to/configure/consensus/qbft.md) or -[IBFT 2.0](../../../private-networks/how-to/configure/consensus/ibft.md) networks. +[QBFT](../../private-networks/how-to/configure/consensus/qbft.md) or +[IBFT 2.0](../../private-networks/how-to/configure/consensus/ibft.md) networks. ::: @@ -90,15 +122,15 @@ Snap sync and checkpoint sync are not supported for We recommend using snap sync over fast sync because snap sync can be faster than fast sync by several days (for Mainnet). -We recommend using snap sync with the [Bonsai](../../concepts/data-storage-formats.md#bonsai-tries) +We recommend using snap sync with the [Bonsai](data-storage-formats.md#bonsai-tries) data storage format for the fastest sync and lowest storage requirements. ::: -Enable snap sync using [`--sync-mode=SNAP`](../../reference/cli/options.md#sync-mode). You need Besu +Enable snap sync using [`--sync-mode=SNAP`](../reference/cli/options.md#sync-mode). You need Besu version 22.4.0 or later to use snap sync. -Instead of downloading the [state trie](../../concepts/data-storage-formats.md) node by node, snap +Instead of downloading the [state trie](data-storage-formats.md) node by node, snap sync downloads as many leaves of the trie as possible, and reconstructs the trie locally. You can't switch from fast sync to snap sync. If your node is blocked in the middle of a fast sync, @@ -109,16 +141,16 @@ You can restart Besu during a snap sync in case of hardware or software problems from the last valid world state and continues to download blocks starting from the last downloaded block. -See [how to read the Besu metrics charts](../../how-to/monitor/understand-metrics.md) when using +See [how to read the Besu metrics charts](../how-to/monitor/understand-metrics.md) when using snap sync. ### Checkpoint synchronization -Enable checkpoint sync using [`--sync-mode=CHECKPOINT`](../../reference/cli/options.md#sync-mode). +Enable checkpoint sync using [`--sync-mode=CHECKPOINT`](../reference/cli/options.md#sync-mode). You need Besu version 22.4.3 or later to use checkpoint sync. Checkpoint sync behaves like [snap sync](#snap-synchronization), but instead of syncing from the -genesis block, it syncs from a specific checkpoint block configured in the [Besu genesis file](../../concepts/genesis-file.md). +genesis block, it syncs from a specific checkpoint block configured in the [Besu genesis file](genesis-file.md). Ethereum Mainnet and the Holesky testnet configurations already define default checkpoints, so you don't have to add this yourself. @@ -136,7 +168,7 @@ number, and total difficulty as in the following example. :::note -If using [Clique](../../../private-networks/how-to/configure/consensus/clique.md) consensus, the +If using [Clique](../../private-networks/how-to/configure/consensus/clique.md) consensus, the checkpoint must be the beginning of an epoch. ::: @@ -157,7 +189,7 @@ the first time or ever need to re-sync, update Besu to a version that supports n ::: -Enable fast sync using [`--sync-mode=FAST`](../../reference/cli/options.md#sync-mode). +Enable fast sync using [`--sync-mode=FAST`](../reference/cli/options.md#sync-mode). Fast sync downloads the block headers and transaction receipts, and verifies the chain of block headers from the genesis block. @@ -166,16 +198,16 @@ When starting fast sync, Besu first downloads the world state for a recent block peers (referred to as a pivot block), and then begins fast sync from the genesis block. Fast sync is the default for named networks specified using the -[`--network`](../../reference/cli/options.md#network) option, except for the `dev` development +[`--network`](../reference/cli/options.md#network) option, except for the `dev` development network. It's also the default if connecting to Ethereum Mainnet by not specifying the -[`--network`](../../reference/cli/options.md#network) or -[`--genesis-file`](../../reference/cli/options.md#genesis-file) options. +[`--network`](../reference/cli/options.md#network) or +[`--genesis-file`](../reference/cli/options.md#genesis-file) options. -Using fast sync with [private transactions](../../../private-networks/concepts/privacy/index.md) +Using fast sync with [private transactions](../../private-networks/concepts/privacy/index.md) isn't supported. You can observe the `besu_synchronizer_fast_sync_*` and `besu_synchronizer_world_state_*` -[metrics](../../how-to/monitor/metrics.md#metrics-list) to monitor fast sync. +[metrics](../how-to/monitor/metrics.md#metrics-list) to monitor fast sync. :::note @@ -216,7 +248,7 @@ In the following example, the pivot block is 0 and the pending state nodes value means the node isn't syncing against any peers. The fact that state nodes have been downloaded means at some stage it was syncing. -![Fast synchronization](../../../assets/images/fastsync.png) +![Fast synchronization](../../assets/images/fastsync.png) The easiest solution in this scenario is to restart fast sync to obtain a new pivot block. @@ -226,12 +258,12 @@ The easiest solution in this scenario is to restart fast sync to obtain a new pi An archive node stores all historical states of the blockchain. To run an archive node, enable full synchronization (full sync) using -[`--sync-mode=FULL`](../../reference/cli/options.md#sync-mode). +[`--sync-mode=FULL`](../reference/cli/options.md#sync-mode). Full sync starts from the genesis block and reprocesses all transactions. :::caution important -Do not run an archive node with the [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries) +Do not run an archive node with the [Bonsai Tries](data-storage-formats.md#bonsai-tries) data storage format. Bonsai is designed for retrieving recent data only. ::: diff --git a/docs/public-networks/concepts/parallel-transaction-execution.md b/docs/public-networks/concepts/parallel-transaction-execution.md index 8dba7993bc5..ab0d01b0104 100644 --- a/docs/public-networks/concepts/parallel-transaction-execution.md +++ b/docs/public-networks/concepts/parallel-transaction-execution.md @@ -1,5 +1,6 @@ --- -sidebar_position: 4 +title: Parallel transaction execution +sidebar_position: 5 description: Learn about parallel transaction execution. tags: - public networks diff --git a/docs/public-networks/concepts/transactions/_category_.json b/docs/public-networks/concepts/transactions/_category_.json index 6026a5487c2..48d67cc3e5d 100644 --- a/docs/public-networks/concepts/transactions/_category_.json +++ b/docs/public-networks/concepts/transactions/_category_.json @@ -1,4 +1,4 @@ { "label": "Transactions", - "position": 5 + "position": 6 } diff --git a/docs/public-networks/get-started/migrate-to-besu.md b/docs/public-networks/get-started/migrate-to-besu.md index e4b721730c5..7981717b624 100644 --- a/docs/public-networks/get-started/migrate-to-besu.md +++ b/docs/public-networks/get-started/migrate-to-besu.md @@ -10,6 +10,6 @@ Migrate from a different Ethereum [execution client](../concepts/node-clients.md To migrate from a different client, [configure Besu as an execution client](connect/mainnet.md#2-start-besu) and connect your [consensus client](../concepts/node-clients.md#consensus-clients) to Besu instead of your original execution client. -To minimize downtime while [Besu syncs](connect/sync-node.md) and avoid downtime penalties, you can sync Besu with a new consensus layer instance. Once Besu has fully synced you can connect it to your existing consensus client. +To minimize downtime while [Besu syncs](../concepts/node-sync.md) and avoid downtime penalties, you can sync Besu with a new consensus layer instance. Once Besu has fully synced you can connect it to your existing consensus client. Find guides to switch from specific clients on the [client diversity website](https://clientdiversity.org/#switch). diff --git a/docs/public-networks/get-started/start-node.md b/docs/public-networks/get-started/start-node.md index 09bce3d1e04..bc520b48ed5 100644 --- a/docs/public-networks/get-started/start-node.md +++ b/docs/public-networks/get-started/start-node.md @@ -40,12 +40,12 @@ To define a genesis configuration, create a genesis file (for example, `genesis. ## Syncing and storage -By default, Besu syncs to the current state of the blockchain using [fast sync](connect/sync-node.md#fast-synchronization) in: +By default, Besu syncs to the current state of the blockchain using [fast sync](../concepts/node-sync.md#fast-synchronization) in: - Networks specified using [`--network`](../reference/cli/options.md#network) except for the `dev` development network. - Ethereum Mainnet. -We recommend using [snap sync](connect/sync-node.md#snap-synchronization) for a faster sync, by starting Besu with [`--sync-mode=SNAP`](../reference/cli/options.md#sync-mode). +We recommend using [snap sync](../concepts/node-sync.md#snap-synchronization) for a faster sync, by starting Besu with [`--sync-mode=SNAP`](../reference/cli/options.md#sync-mode). By default, Besu stores data in the [Forest of Tries](../concepts/data-storage-formats.md#forest-of-tries) format. We recommend using [Bonsai Tries](../concepts/data-storage-formats.md#bonsai-tries) for lower storage requirements, by starting Besu with [`--data-storage-format=BONSAI`](../reference/cli/options.md#data-storage-format). diff --git a/docs/public-networks/how-to/configure-besu/index.md b/docs/public-networks/how-to/configure-besu/index.md index 98bda1507ce..c938a949955 100644 --- a/docs/public-networks/how-to/configure-besu/index.md +++ b/docs/public-networks/how-to/configure-besu/index.md @@ -106,7 +106,7 @@ For example, extending the default configuration using the [staker profile](prof |Configuration option|Default|Description| |---------------------------|--------------------|------------------------------------------| -|[`sync-mode`](../../reference/cli/options.md#sync-mode)|`SNAP`|Besu syncs using [snap sync](../../get-started/connect/sync-node.md#snap-synchronization), the most time-efficient sync method.| +|[`sync-mode`](../../reference/cli/options.md#sync-mode)|`SNAP`|Besu syncs using [snap sync](../../concepts/node-sync.md#snap-synchronization), the most time-efficient sync method.| :::note You can see all default configuration values in the [configuration options reference](../../reference/cli/options.md). diff --git a/docs/public-networks/how-to/connect/manage-peers.md b/docs/public-networks/how-to/connect/manage-peers.md index 4e70ec9e80c..52add02509c 100644 --- a/docs/public-networks/how-to/connect/manage-peers.md +++ b/docs/public-networks/how-to/connect/manage-peers.md @@ -57,7 +57,7 @@ In detail, the P2P discovery process is as follows: as network details, what the peer believes to be the current chain head, and its list of neighbors. From this point on any traffic to that peer is only done using TCP. -5. Depending on the [synchronization method](../../get-started/connect/sync-node.md), a common block +5. Depending on the [synchronization method](../../concepts/node-sync.md), a common block (the pivot block) is selected that all connected peers (default of 5) have, and Besu syncs from that block till it gets to chain head. Log messages look like `Downloading world state from peers for pivot block .......`. diff --git a/docs/public-networks/how-to/monitor/understand-metrics.md b/docs/public-networks/how-to/monitor/understand-metrics.md index 863798555be..155d8a99be0 100644 --- a/docs/public-networks/how-to/monitor/understand-metrics.md +++ b/docs/public-networks/how-to/monitor/understand-metrics.md @@ -8,7 +8,7 @@ tags: # Understand metrics -When running Besu on Ethereum Mainnet using [snap sync](../../get-started/connect/sync-node.md#snap-synchronization), you might notice graphical patterns that stand out in different metrics charts. These patterns are related to the [CPU usage](#cpu-usage) and [block time](#block-time) of the Besu sync process. +When running Besu on Ethereum Mainnet using [snap sync](../../concepts/node-sync.md#snap-synchronization), you might notice graphical patterns that stand out in different metrics charts. These patterns are related to the [CPU usage](#cpu-usage) and [block time](#block-time) of the Besu sync process. ## CPU usage diff --git a/docs/public-networks/how-to/troubleshoot/peering.md b/docs/public-networks/how-to/troubleshoot/peering.md index 20452939433..861480a409f 100644 --- a/docs/public-networks/how-to/troubleshoot/peering.md +++ b/docs/public-networks/how-to/troubleshoot/peering.md @@ -19,7 +19,7 @@ One or more of the following may be the cause: - Your hardware doesn't have enough CPU, disk IOPS, or bandwidth to handle all the peers. - Your ports aren't open in your firewall and/or router. - Your node is sending large numbers of DNS requests. See [issue #4375](https://github.com/hyperledger/besu/issues/4375). -- You're using [checkpoint sync](../../get-started/connect/sync-node.md#checkpoint-synchronization), which doesn't download all historical block data, so your peers may disconnect you when fetching those blocks. +- You're using [checkpoint sync](../../concepts/node-sync.md#checkpoint-synchronization), which doesn't download all historical block data, so your peers may disconnect you when fetching those blocks. - Your node is experiencing the normal behavior of peers connecting and disconnecting. This is especially normal soon after you start your node. You can try the following to find more peers: diff --git a/docs/public-networks/how-to/troubleshoot/trace-transactions.md b/docs/public-networks/how-to/troubleshoot/trace-transactions.md index 77c334c50c4..913369eef07 100644 --- a/docs/public-networks/how-to/troubleshoot/trace-transactions.md +++ b/docs/public-networks/how-to/troubleshoot/trace-transactions.md @@ -34,7 +34,7 @@ The ad-hoc tracing APIs are: These APIs allow you to filter and search by specific information such as the block, address, or transaction. These APIs only use the [`trace` type](../../reference/trace-types.md#trace). To use the transaction-trace filtering APIs, your node must be an -[archive node](../../get-started/connect/sync-node.md#run-an-archive-node), or the requested block +[archive node](../../concepts/node-sync.md#run-an-archive-node), or the requested block or transaction must be within the number of [blocks retained](../../reference/cli/options.md#bonsai-historical-block-limit) when using [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries) (by default, 512 from the head diff --git a/docs/public-networks/reference/api/index.md b/docs/public-networks/reference/api/index.md index f0f62a876d0..5327d71f4fe 100644 --- a/docs/public-networks/reference/api/index.md +++ b/docs/public-networks/reference/api/index.md @@ -7131,7 +7131,7 @@ The `TRACE` API methods are not enabled by default for JSON-RPC. To enable the ` Provides transaction processing of [type `trace`](../trace-types.md#trace) for the specified block. :::info note -Your node must be an [archive node](../../get-started/connect/sync-node.md#run-an-archive-node), or +Your node must be an [archive node](../../concepts/node-sync.md#run-an-archive-node), or the requested block must be within the number of [blocks retained](../cli/options.md#bonsai-historical-block-limit) when using [Bonsai](../../concepts/data-storage-formats.md#bonsai-tries) (by default, 512 from the head of the chain). @@ -7441,7 +7441,7 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"trace_callMany","params":[[[{"fr Returns traces matching the specified filter. The maximum number of blocks you can supply to `trace_filter` is 1000 by default. You can adjust this limit using the [`--rpc-max-trace-filter-range`](../cli/options.md#rpc-max-trace-filter-range) option. :::info note -Your node must be an [archive node](../../get-started/connect/sync-node.md#run-an-archive-node), or +Your node must be an [archive node](../../concepts/node-sync.md#run-an-archive-node), or the requested blocks must be within the number of [blocks retained](../cli/options.md#bonsai-historical-block-limit) when using [Bonsai](../../concepts/data-storage-formats.md#bonsai-tries) (by default, 512 from the head of the chain). @@ -7545,7 +7545,7 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"trace_filter","params":[{"fromBl Returns a trace at the given position. :::info note -Your node must be an [archive node](../../get-started/connect/sync-node.md#run-an-archive-node), or +Your node must be an [archive node](../../concepts/node-sync.md#run-an-archive-node), or the requested transaction must be contained in a block within the number of [blocks retained](../cli/options.md#bonsai-historical-block-limit) when using [Bonsai](../../concepts/data-storage-formats.md#bonsai-tries) (by default, 512 from the head of the chain). @@ -7822,7 +7822,7 @@ curl -X POST --data '{"jsonrpc": "2.0", "method": "trace_replayBlockTransactions Provides transaction processing of [type `trace`](../trace-types.md#trace) for the specified transaction. :::info note -Your node must be an [archive node](../../get-started/connect/sync-node.md#run-an-archive-node), or +Your node must be an [archive node](../../concepts/node-sync.md#run-an-archive-node), or the requested transaction must be contained in a block within the number of [blocks retained](../cli/options.md#bonsai-historical-block-limit) when using [Bonsai](../../concepts/data-storage-formats.md#bonsai-tries) (by default, 512 from the head of the chain). diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md index 0c15a295d30..af42ef701d1 100644 --- a/docs/public-networks/reference/cli/options.md +++ b/docs/public-networks/reference/cli/options.md @@ -5043,7 +5043,7 @@ sync-min-peers=8 -The minimum number of peers required before starting [sync](../../get-started/connect/sync-node.md). The default is `5`. Set to `1` to enable static peers to contribute to the initial sync. +The minimum number of peers required before starting [sync](../../concepts/node-sync.md). The default is `5`. Set to `1` to enable static peers to contribute to the initial sync. :::info @@ -5089,7 +5089,7 @@ sync-mode="SNAP" -The synchronization mode. Use `SNAP` for [snap sync](../../get-started/connect/sync-node.md#snap-synchronization), `CHECKPOINT` for [checkpoint sync](../../get-started/connect/sync-node.md#checkpoint-synchronization), `FAST` for [fast sync](../../get-started/connect/sync-node.md#fast-synchronization), and `FULL` for [full sync](../../get-started/connect/sync-node.md#run-an-archive-node). +The synchronization mode. Use `SNAP` for [snap sync](../../concepts/node-sync.md#snap-synchronization), `CHECKPOINT` for [checkpoint sync](../../concepts/node-sync.md#checkpoint-synchronization), `FAST` for [fast sync](../../concepts/node-sync.md#fast-synchronization), and `FULL` for [full sync](../../concepts/node-sync.md#run-an-archive-node). - The default is `FULL` when connecting to a private network by not using the [`--network`](#network) option and specifying the [`--genesis-file`](#genesis-file) option. - The default is `SNAP` when using the [`--network`](#network) option with named networks, except for the `dev` development network. `SNAP` is also the default if running Besu on the default network (Ethereum Mainnet) by specifying neither [network](#network) nor [genesis file](#genesis-file). diff --git a/docs/public-networks/tutorials/besu-teku-mainnet.md b/docs/public-networks/tutorials/besu-teku-mainnet.md index c8cc99784ab..6d5658b39e4 100644 --- a/docs/public-networks/tutorials/besu-teku-mainnet.md +++ b/docs/public-networks/tutorials/besu-teku-mainnet.md @@ -70,7 +70,7 @@ Specify: Also, in the command: -- [`--sync-mode`](../reference/cli/options.md#sync-mode) specifies using [snap sync](../get-started/connect/sync-node.md#snap-synchronization). +- [`--sync-mode`](../reference/cli/options.md#sync-mode) specifies using [snap sync](../concepts/node-sync.md#snap-synchronization). - [`--data-storage-format`](../reference/cli/options.md#data-storage-format) specifies using [Bonsai Tries](../concepts/data-storage-formats.md#bonsai-tries). - [`--rpc-http-enabled`](../reference/cli/options.md#rpc-http-enabled) enables the HTTP JSON-RPC service. - [`--engine-rpc-enabled`](../reference/cli/options.md#engine-rpc-enabled) enables the [Engine API](../reference/engine-api/index.md).