🐻⛓️ Berachain Docs

Appearance

Syncing Node ​

The faster your node gets up to sync with the current state of the network, the faster it can be used. Syncing is the process of a node catching up with the current state.

There are multiple methods of syncing your node:

  • Block Sync
    • The node downloads all of the data of an application from genesis and verifies it
  • State Sync (⚠️ work-in-progress)
    • The node downloads data related to the head or near the head of the chain and verifies the data
  • Snapshots
    • Find a trusted snapshot provider, download the snapshot and restore the state from that snapshot

Block Sync ​

Recommended for Beginners

TIP

This is also known as "Fast Sync"

This option is enabled by default. In this mode, the CometBFT daemon will sync hundreds of times faster than if it used the real-time consensus process. Once caught up, the daemon will switch out of block sync and into the normal consensus mode. After running for some time, the node is considered caught up if it has at least one peer and its height is at least as high as the max reported peer height.

Adjusting Block Sync Configuration ​

This option can be adjusted in the config.toml file.

WARNING

We recommend leaving these as their defaults


To enable / disable Block Sync, edit the block_sync value:

toml
block_sync = true
block_sync = true

To change the version of Block Sync you are running, edit version value:

toml
#######################################################
###       Block Sync Configuration Options          ###
#######################################################
[blocksync]

# Block Sync version to use:
# 
# In v0.37, v1 and v2 of the block sync protocols were deprecated.
# Please use v0 instead.
#
#   1) "v0" - the default block sync implementation
version = "v0"
#######################################################
###       Block Sync Configuration Options          ###
#######################################################
[blocksync]

# Block Sync version to use:
# 
# In v0.37, v1 and v2 of the block sync protocols were deprecated.
# Please use v0 instead.
#
#   1) "v0" - the default block sync implementation
version = "v0"

You can read more about Fast Sync in the CometBFT documentation.

State Sync (⚠️ work-in-progress) ​

State Sync is an efficient and fast way to bootstrap a new node, and it works by replaying larger chunks of application state directly rather than replaying individual blocks or consensus rounds. This allows state sync to be much faster than Block Sync.

To use state sync, you will need to:

  1. Enable state sync
  2. Select 2+ trusted RPCs to sync against
  3. Select a trusted height
  4. Select a trusted hash

First, visit an explorer to get a recent block height and corresponding hash. A node operator can choose any height/hash in the current bonding period, but as the recommended snapshot period is 1000 blocks, it is advised to choose something close to current height - 1000.

Next, identify 2+ trusted RPC node providers that you can sync against.

WARNING

Make sure that you are retrieving this from trusted node providers, there are trust assumptions being made in order to quickly sync your node.

Now we can edit our config.toml file as follows, under the [statesync] section:

  • Set enable to true
  • Place your trusted RPCs in rpc_servers, separated by commas
  • Set trust_height to your selected height
  • Set trust_hash to your selected hash
  • (You can leave trust_period as its default)
toml
#######################################################
###         State Sync Configuration Options        ###
#######################################################
[statesync]
# State sync rapidly bootstraps a new node by discovering, fetching, and restoring a state machine
# snapshot from peers instead of fetching and replaying historical blocks. Requires some peers in
# the network to take and serve state machine snapshots. State sync is not attempted if the node
# has any local state (LastBlockHeight > 0). The node will have a truncated block history,
# starting from the height of the snapshot.
enable = true

# RPC servers (comma-separated) for light client verification of the synced state machine and
# retrieval of state data for node bootstrapping. Also needs a trusted height and corresponding
# header hash obtained from a trusted source, and a period during which validators can be trusted.
#
# For Cosmos SDK-based chains, trust_period should usually be about 2/3 of the unbonding time (~2
# weeks) during which they can be financially punished (slashed) for misbehavior.
rpc_servers = "https://trusted.com:443,https://provider.com:443"
trust_height = 10000
trust_hash = "3D8F12EA302AEDA66E80939F7FC785206692F8B6EE6F727F1655F1AFB6A873A5"
trust_period = "168h0m0s"
#######################################################
###         State Sync Configuration Options        ###
#######################################################
[statesync]
# State sync rapidly bootstraps a new node by discovering, fetching, and restoring a state machine
# snapshot from peers instead of fetching and replaying historical blocks. Requires some peers in
# the network to take and serve state machine snapshots. State sync is not attempted if the node
# has any local state (LastBlockHeight > 0). The node will have a truncated block history,
# starting from the height of the snapshot.
enable = true

# RPC servers (comma-separated) for light client verification of the synced state machine and
# retrieval of state data for node bootstrapping. Also needs a trusted height and corresponding
# header hash obtained from a trusted source, and a period during which validators can be trusted.
#
# For Cosmos SDK-based chains, trust_period should usually be about 2/3 of the unbonding time (~2
# weeks) during which they can be financially punished (slashed) for misbehavior.
rpc_servers = "https://trusted.com:443,https://provider.com:443"
trust_height = 10000
trust_hash = "3D8F12EA302AEDA66E80939F7FC785206692F8B6EE6F727F1655F1AFB6A873A5"
trust_period = "168h0m0s"

Now when you start your node it will begin syncing with State Sync, to do so use the following command:

shell
$ berad start --x-crisis-skip-assert-invariants
$ berad start --x-crisis-skip-assert-invariants

Once state sync successfully completes, the node will begin to process blocks normally. If state sync fails and the node operator encounters the following error: State sync failed err="state sync aborted", either try restarting berad or running berad unsafe-reset-all (make sure to backup any configuration and history before doing this).


Advanced State Sync Configuration ​

You'll find the following additional State Sync settings in config.toml, only modify them if you know how they work, otherwise leave them as their defaults:

toml
# Time to spend discovering snapshots before initiating a restore.
discovery_time = "15s"

# Temporary directory for state sync snapshot chunks, defaults to the OS tempdir (typically /tmp).
# Will create a new, randomly named directory within, and remove it when done.
temp_dir = ""

# The timeout duration before re-requesting a chunk, possibly from a different
# peer (default: 1 minute).
chunk_request_timeout = "10s"

# The number of concurrent chunk fetchers to run (default: 1).
chunk_fetchers = "4"
# Time to spend discovering snapshots before initiating a restore.
discovery_time = "15s"

# Temporary directory for state sync snapshot chunks, defaults to the OS tempdir (typically /tmp).
# Will create a new, randomly named directory within, and remove it when done.
temp_dir = ""

# The timeout duration before re-requesting a chunk, possibly from a different
# peer (default: 1 minute).
chunk_request_timeout = "10s"

# The number of concurrent chunk fetchers to run (default: 1).
chunk_fetchers = "4"

To learn more about State Sync, check out the CometBFT documentation.

Snapshots ​

Unlike previous syncing methods, snapshots involve downloading the blockchain state as a direct download and copying the data into your node directly. This snapshot could come from a trusted provider or from your own backups in case one of your nodes goes down unexpectedly.

To do so you can simply download the snapshot from a trusted provider and copy it into your node's data directory($HOME/.berad/data).