Skip to content

Commit

Permalink
better (not total) character limit adherence
Browse files Browse the repository at this point in the history 
Signed-off-by: m4sterbunny <harrie.bickle@consensys.net>
  • Loading branch information
@m4sterbunny
m4sterbunny authored Jun 10, 2024
1 parent 1f8c380 commit e9a2c7f
Showing 1 changed file with 76 additions and 31 deletions.
107 changes: 76 additions & 31 deletions docs/public-networks/get-started/connect/sync-node.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,24 @@ tags:
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), and stores a local copy of the blockchain.
A full node consists of an
[execution and consensus client](../../concepts/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.

Full nodes can guarantee the latest state of the blockchain (and some older states). However, they can't serve the network with all data requests (for example, the balance of an account at an old block).
Full nodes can guarantee the latest state of the blockchain (and some older states). However, they
can't serve the network with all data requests (for example, the balance of an account at an old
block).

An archive node is a node that also stores the intermediary state of every account and contract
for every block since the genesis block.

Archive nodes can do everything full nodes do, and they can also access historical state data. This means that archive nodes require more disk space than full nodes.
Archive nodes can do everything full nodes do, and they can also access historical state data.
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).
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).

## Sync times

Expand All @@ -31,9 +37,11 @@ blockchain download.

While the world state syncs, Besu downloads and imports the blockchain in the background.
The blockchain download time depends on CPU, the network, Besu's peers, and disk speed.
The blockchain download generally takes longer than the world state sync. Besu must catch up to the current chain head and sync the world state to participate on Mainnet.
The blockchain download generally takes longer than the world state sync. Besu must catch up to the
current chain head and sync the world state to participate on Mainnet.

The following table shows the average world state sync time, and blockchain download time, for each sync mode on Mainnet.
The following table shows the average world state sync time, and blockchain download time, for each
sync mode on Mainnet.

All times are hardware dependent; this table is based on running AWS instances m6gd.2xlarge.
Each sync mode also has its own world state database size.
Expand Down Expand Up @@ -79,32 +87,44 @@ Snap sync and checkpoint sync are not supported for

:::tip

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 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)
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 version 22.4.0 or later to use snap sync.
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 sync downloads as many leaves of the trie as possible, and reconstructs the trie locally.
Instead of downloading the [state trie](../../concepts/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, you can start over using snap sync instead by stopping the node, deleting the data directory, and starting over using `--sync-mode=SNAP`.
You can't switch from fast sync to snap sync. If your node is blocked in the middle of a fast sync,
you can start over using snap sync instead by stopping the node, deleting the data directory, and
starting over using `--sync-mode=SNAP`.

You can restart Besu during a snap sync in case of hardware or software problems. The sync resumes from the last valid world state and continues to download blocks starting from the last downloaded block.
You can restart Besu during a snap sync in case of hardware or software problems. The sync resumes
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 snap sync.
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). You need Besu version 22.4.3 or later to use checkpoint sync.
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).
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).

Ethereum Mainnet and the Holesky testnet configurations already define default checkpoints, so you don't have to add this yourself.
Ethereum Mainnet and the Holesky testnet configurations already define default checkpoints, so you
don't have to add this yourself.

For other networks, you can configure a checkpoint in the genesis file by specifying the block hash, number, and total difficulty as in the following example.
For other networks, you can configure a checkpoint in the genesis file by specifying the block hash,
number, and total difficulty as in the following example.

```json title="Checkpoint configuration example"
"checkpoint": {
Expand All @@ -116,60 +136,85 @@ For other networks, you can configure a checkpoint in the genesis file by specif

:::note

If using [Clique](../../../private-networks/how-to/configure/consensus/clique.md) consensus, the checkpoint must be the beginning of an epoch.
If using [Clique](../../../private-networks/how-to/configure/consensus/clique.md) consensus, the
checkpoint must be the beginning of an epoch.

:::

If you enable checkpoint sync without a checkpoint configuration in the genesis file, Besu snap syncs from the genesis block.
If you enable checkpoint sync without a checkpoint configuration in the genesis file, Besu snap
syncs from the genesis block.

You can restart Besu during a checkpoint sync in case of hardware or software problems. The sync resumes from the last valid world state and continues to download blocks starting from the last downloaded block.
You can restart Besu during a checkpoint sync in case of hardware or software problems. The sync
resumes from the last valid world state and continues to download blocks starting from the last
downloaded block.

### Fast synchronization

:::caution

It might become impossible to sync Ethereum Mainnet using fast sync in the future. If you sync for the first time or ever need to re-sync, update Besu to a version that supports newer sync methods.
It might become impossible to sync Ethereum Mainnet using fast sync in the future. If you sync for
the first time or ever need to re-sync, update Besu to a version that supports newer sync methods.

:::

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.
Fast sync downloads the block headers and transaction receipts, and verifies the chain of block
headers from the genesis block.

When starting fast sync, Besu first downloads the world state for a recent block verified by its peers (referred to as a pivot block), and then begins fast sync from the genesis block.
When starting fast sync, Besu first downloads the world state for a recent block verified by its
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. 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.
Fast sync is the default for named networks specified using the
[`--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.

Using fast sync with [private transactions](../../../private-networks/concepts/privacy/index.md) isn't supported.
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.
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.

:::note

When fast syncing, block numbers increase until close to the head block, then the process pauses while the world state download completes. This may take a significant amount of time depending on world state size, during which the current head block doesn't increase. For example, Mainnet may take several days or more to fast sync. Fast sync time may increase because Besu picks new pivot blocks, or because peers prune the world state before it completes downloading.
When fast syncing, block numbers increase until close to the head block, then the process pauses
while the world state download completes. This may take a significant amount of time depending on
world state size, during which the current head block doesn't increase. For example, Mainnet may
take several days or more to fast sync. Fast sync time may increase because Besu picks new pivot
blocks, or because peers prune the world state before it completes downloading.

:::

:::caution RocksDB error on AWS

When running Besu on some cloud providers, a known [RocksDB](https://github.com/facebook/rocksdb/issues/6435) issue causes fast sync to fail occasionally. The following error is displayed repeatedly:
When running Besu on some cloud providers, a known
[RocksDB](https://github.com/facebook/rocksdb/issues/6435) issue causes fast sync to fail occasionally.
The following error is displayed repeatedly:

```
EthScheduler-Services-1 (importBlock) | ERROR | PipelineChainDownloader | Chain download failed. Restarting after short delay.
EthScheduler-Services-1 (importBlock) | ERROR | PipelineChainDownloader | Chain download failed.
Restarting after short delay.
java.util.concurrent.CompletionException: org.hyperledger.besu.plugin.services.exception.StorageException: org.rocksdb.RocksDBException: block checksum mismatch:
```

The failure has been seen on AWS and Digital Ocean. On AWS, A full restart of the VM is required to restart the fast sync. Fast sync isn't [currently supported on Digital Ocean](https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/CHANGELOG.md#143).
The failure has been seen on AWS and Digital Ocean. On AWS, A full restart of the VM is required to
restart the fast sync. Fast sync isn't
[currently supported on Digital Ocean](https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/CHANGELOG.md#143).

:::

:::caution Pending state nodes stays constant

When fast syncing, the pending state nodes count is the number of nodes yet to be downloaded, and it should change constantly. Pending state nodes trend to 0 during fast sync and then goes to 0.
When fast syncing, the pending state nodes count is the number of nodes yet to be downloaded, and it
should change constantly. Pending state nodes trend to 0 during fast sync and then goes to 0.

If the number stays constant, this could mean your node isn't syncing against any peers.

In the following example, the pivot block is 0 and the pending state nodes value is constant. This means the node isn't syncing against any peers. The fact that state nodes have been downloaded means at some stage it was syncing.
In the following example, the pivot block is 0 and the pending state nodes value is constant. This
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)

Expand Down

0 comments on commit e9a2c7f

Please sign in to comment.