Add xperimental features and add table for how sync works (#1662)

* update with experimental Signed-off-by: Joan E <[email protected]> * update spelling Signed-off-by: Joan E <[email protected]> * fix typo Signed-off-by: Joan E <[email protected]> * fix typo Signed-off-by: Joan E <[email protected]> * add suggestions Signed-off-by: Joan E <[email protected]> * Apply suggestions from code review Co-authored-by: Simon Dudley <[email protected]> Signed-off-by: Joan E <[email protected]> * fix broken links Signed-off-by: Joan E <[email protected]> * Apply suggestions from code review Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: Joan E <[email protected]> * update with suggestions Signed-off-by: Joan E <[email protected]> * update broken Signed-off-by: Joan E <[email protected]> * Apply suggestions from code review Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: Joan E <[email protected]> * Update table for consistency Signed-off-by: Joan E <[email protected]> * Apply suggestions from code review Co-authored-by: Alexandra Carrillo <[email protected]> Signed-off-by: Joan E <[email protected]> --------- Signed-off-by: Joan E <[email protected]> Co-authored-by: Simon Dudley <[email protected]> Co-authored-by: Alexandra Carrillo <[email protected]>
hyperledger · Oct 4, 2024 · 575a049 · 575a049
1 parent 2c6dc29
commit 575a049
Show file tree

Hide file tree

Showing 22 changed files with 155 additions and 54 deletions.
diff --git a/docs/private-networks/concepts/node-sync-private.md 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
@@ -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
@@ -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
@@ -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
@@ -25,17 +25,21 @@ To run a node with Bonsai Tries data storage format, use the command line option
 </p>
 
 :::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,18 +50,20 @@ In forest mode, each node in the trie is saved in a key-value store by hash. For
 </p>
 
 :::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
 
 ### 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
@@ -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
@@ -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
@@ -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
@@ -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/...networks/get-started/connect/sync-node.md → docs/public-networks/concepts/node-sync.md b/...networks/get-started/connect/sync-node.md → 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
@@ -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
@@ -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
@@ -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).