Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update syncing docs #1717

Merged
merged 4 commits into from
Oct 21, 2024
Merged

Update syncing docs #1717

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6538797
Update syncing docs
Oct 18, 2024
a71655e
Merge branch 'main' into 1715-update-syncing
joaniefromtheblock Oct 18, 2024
9f8eade
Update options.md
alexandratran Oct 18, 2024
fc5d162
address reviewer feedback + edits
Oct 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 8 additions & 14 deletions docs/private-networks/concepts/node-sync-private.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,15 @@ To sync Besu on a private network:
- 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.
alexandratran marked this conversation as resolved.
Show resolved Hide resolved
The following is an overview of the private network sync modes.
Select the sync mode based on your 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. |
joaniefromtheblock marked this conversation as resolved.
Show resolved Hide resolved
| [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. |
| 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) | Downloads block headers and transaction receipts, verifies chain from genesis block. | None | Not supported with private transactions. |
| [Full](../../public-networks/concepts/node-sync.md#full-synchronization) | Default for all private networks. 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

Expand All @@ -36,10 +37,3 @@ 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.

:::

2 changes: 1 addition & 1 deletion docs/private-networks/get-started/start-node.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/concepts/node-sync.md#fast-synchronization) or [full sync](../../public-networks/concepts/node-sync.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#full-synchronization).

Full sync is set by default.

Expand Down
11 changes: 7 additions & 4 deletions docs/private-networks/how-to/configure/consensus/ibft.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,11 @@ Existing validators propose and vote to [add or remove validators](#add-and-remo

You can [create a private network using IBFT](../../../tutorials/ibft/index.md).

:::danger
:::caution

Configure your network to ensure you never lose more than 1/3 of your validators. If more than 1/3 of validators stop participating, new blocks are no longer created, and the network stalls. It may take significant time to recover once nodes are restarted.
Configure your network to ensure you never lose more than 1/3 of your validators.
If more than 1/3 of validators stop participating, the network stops creating new blocks and stalls.
It might take significant time to recover after nodes are restarted.

:::

Expand All @@ -31,12 +33,13 @@ You can use a plugin to securely store a validator's key using the [`--security-

:::

:::warning Early access feature
:::info 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.
Use `--Xsnapsync-bft-enabled` with `--sync-mode=SNAP` to enable
[snap sync](../../../concepts/node-sync-private.md) in IBFT 2.0 networks.

:::

Expand Down
9 changes: 6 additions & 3 deletions docs/private-networks/how-to/configure/consensus/qbft.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,9 @@ You can [create a private network using QBFT](../../../tutorials/qbft.md).

:::caution

Configure your network to ensure you never lose more than 1/3 your validators. If more than 1/3 of validators stop participating, new blocks are no longer created, and the network stalls. It may take significant time to recover once nodes are restarted.
Configure your network to ensure you never lose more than 1/3 of your validators.
If more than 1/3 of validators stop participating, the network stops creating new blocks and stalls.
It might take significant time to recover after nodes are restarted.

:::

Expand All @@ -31,12 +33,13 @@ You can use a plugin to securely store a validator's key using the [`--security-

:::

:::warning Early access feature
:::info 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.
Use `--Xsnapsync-bft-enabled` with `--sync-mode=SNAP` to enable
[snap sync](../../../concepts/node-sync-private.md) in QBFT networks.

:::

Expand Down
10 changes: 5 additions & 5 deletions docs/public-networks/concepts/data-storage-formats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ To run a node with Bonsai Tries data storage format, use the command line option

:::caution important

Do not run an [archive node](node-sync.md#run-an-archive-node) with Bonsai Tries.
Do not run an [archive node](node-sync.md#archive-nodes) with Bonsai Tries.
Bonsai is designed for retrieving recent data only.

:::
Expand All @@ -39,7 +39,7 @@ You can read more about Bonsai in [Consensys' Guide to Bonsai Tries](https://con

## 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](node-sync.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#archive-nodes).

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.

Expand All @@ -61,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](node-sync.md#run-a-full-node), forest mode uses an
With a [full node](node-sync.md#full-nodes), forest mode uses an
estimated 750 GB of storage, while Bonsai uses an estimated 650 GB of storage.
[Archive nodes](node-sync.md#run-an-archive-node) must use forest mode, which
[Archive nodes](node-sync.md#archive-nodes) must use forest mode, which
uses an estimated 12 TB of storage.

### Accessing data
Expand All @@ -80,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](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.
The following table shows the ways you can sync a [full node](node-sync.md#full-nodes) 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? |
| --- | --- | --- | --- |
Expand Down
Loading
Loading