Besu supports two node types, commonly referred to as full nodes andarchive nodes.
A full node consists of anexecution and consensus client,and stores a local copy of the blockchain.With a full node, you can check current balances, sign and send transactions, and look at currentdapp data.
Full nodes can guarantee the latest state of the blockchain (and some older states). However, theycan't serve the network with all data requests (for example, the balance of an account at an oldblock).
An archive node is a node that also stores the intermediary state of every account and contractfor 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.
Besu must connect with other peers to sync with the network. If your node is having trouble peering,try troubleshooting peering.
Sync times
To sync with a public network, Besu runs two processes in parallel: the world state sync and theblockchain 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 thecurrent 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 eachsync 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.
| Sync mode | Time to sync world state | Time to download blockchain | Disk usage |
|---|---|---|---|
| Snap | ~6 hours | ~1.5 days | Average disk |
| Checkpoint | ~5 hours | ~13 hours | Smallest disk |
| Fast | ~1.5 days | ~1.5 days | Average disk |
| Full | ~weeks | ~weeks | Largest disk |
Notes
- As of late 2023, an average Mainnet snap sync consumes around 1000 GB using Bonsai Tries.Read more about storage requirementsacross 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 Triesor Bonsai Tries.
If you're running a full node, we recommend using Bonsai Tries for the loweststorage requirements.
Run a full node
A full node stores a local copy of the blockchain and the current state of the blockchain.You can run a full node using snap synchronization (snap sync),checkpoint synchronization (checkpoint sync), orfast synchronization (fast sync).
Sync nodes for BFT
Snap sync and checkpoint sync are not supported forQBFT orIBFT 2.0 networks.
Snap synchronization
tip
We recommend using snap sync over fast sync because snap sync can be faster than fast sync byseveral days (for Mainnet).
We recommend using snap sync with the Bonsaidata storage format for the fastest sync and lowest storage requirements.
Enable snap sync using --sync-mode=SNAP. You need Besuversion 22.4.0 or later to use snap sync.
Instead of downloading the state trie node by node, snapsync 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, andstarting over using --sync-mode=SNAP.
You can restart Besu during a snap sync in case of hardware or software problems. The sync resumesfrom the last valid world state and continues to download blocks starting from the last downloadedblock.
See how to read the Besu metrics charts when usingsnap sync.
Checkpoint synchronization
Enable checkpoint sync using --sync-mode=CHECKPOINT.You need Besu version 22.4.3 or later to use checkpoint sync.
Checkpoint sync behaves like snap sync, but instead of syncing from thegenesis block, it syncs from a specific checkpoint block configured in the Besu genesis file.
Ethereum Mainnet and the Holesky testnet configurations already define default checkpoints, so youdon'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.
Checkpoint configuration example
"checkpoint": {
"hash": "0x844d581cb00058d19f0584fb582fa2de208876ee56bbae27446a679baf4633f4",
"number": 14700000,
"totalDifficulty": "0xA2539264C62BF98CFC6"
}
note
If using Clique consensus, thecheckpoint must be the beginning of an epoch.
If you enable checkpoint sync without a checkpoint configuration in the genesis file, Besu snapsyncs from the genesis block.
You can restart Besu during a checkpoint sync in case of hardware or software problems. The syncresumes from the last valid world state and continues to download blocks starting from the lastdownloaded block.
Fast synchronization
caution
It might become impossible to sync Ethereum Mainnet using fast sync in the future. If you sync forthe 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.
Fast sync downloads the block headers and transaction receipts, and verifies the chain of blockheaders from the genesis block.
When starting fast sync, Besu first downloads the world state for a recent block verified by itspeers (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 option, except for the dev developmentnetwork. It's also the default if connecting to Ethereum Mainnet by not specifying the--network or--genesis-file options.
Using fast sync with private transactionsisn't supported.
You can observe the besu_synchronizer_fast_sync_* and besu_synchronizer_world_state_*metrics to monitor fast sync.
note
When fast syncing, block numbers increase until close to the head block, then the process pauseswhile the world state download completes. This may take a significant amount of time depending onworld state size, during which the current head block doesn't increase. For example, Mainnet maytake several days or more to fast sync. Fast sync time may increase because Besu picks new pivotblocks, or because peers prune the world state before it completes downloading.
RocksDB error on AWS
When running Besu on some cloud providers, a knownRocksDB 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.
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 torestart the fast sync. Fast sync isn'tcurrently supported on Digital Ocean.
Pending state nodes stays constant
When fast syncing, the pending state nodes count is the number of nodes yet to be downloaded, and itshould 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. Thismeans the node isn't syncing against any peers. The fact that state nodes have been downloaded meansat some stage it was syncing.
The easiest solution in this scenario is to restart fast sync to obtain a new pivot block.
Run an archive node
An archive node stores all historical states of the blockchain.To run an archive node, enable full synchronization (full sync) using--sync-mode=FULL.
Full sync starts from the genesis block and reprocesses all transactions.
important
Do not run an archive node with the Bonsai Triesdata storage format.Bonsai is designed for retrieving recent data only.
