State Synchronization

Nodes in an Aptos network (e.g., validators, VFNs and PFNs) must always be synchronized to the latest blockchain state. The state synchronization (state sync) component that runs on each node is responsible for this. State sync identifies and fetches new blockchain data from peers, validates the data and persists it to local storage. This document explains how to configure state sync on your node.

State sync

At a high-level, state sync operates in two phases. First, nodes bootstrap on startup (in the bootstrapping phase). This allows the node to catch up to the latest state in the Aptos blockchain. Then, the node will stay up-to-date with the blockchain by continuously syncing (in the continuous syncing phase).

Tip

Need to start a node quickly? Here’s what we recommend:

• Mainnet: To sync the entire blockchain history, restore from a backup. Otherwise, use fast sync.
• Testnet: To sync the entire blockchain history, restore from a backup. Otherwise, use fast sync.
• Devnet: To sync the entire blockchain history, use intelligent syncing. Otherwise, use fast sync.

Bootstrapping modes

When the node starts, state sync will perform bootstrapping using the configured bootstrapping mode.

Tip

Default bootstrapping modes?

• Mainnet and Testnet: The default bootstrapping mode is fast syncing, because these networks are long-lived and have a large amount of historical data.
• Devnet: The default bootstrapping mode is intelligent syncing from genesis, because this network is short-lived and typically has a small amount of historical data.

There are several bootstrapping modes:

• Execute transactions from genesis. This mode will fetch all transactions since genesis (i.e., the start of the blockchain’s history), and re-execute each transaction. This mode is the slowest bootstrapping mode.
• Apply transaction outputs from genesis. This mode will fetch all transactions since genesis (i.e., the start of the blockchain’s history), but it will skip transaction re-execution and instead apply the outputs of the transactions as originally produced by validator execution.
• Intelligent syncing from genesis. This mode is a hybrid of the previous two modes. It will fetch all transactions since genesis (i.e., the start of the blockchain’s history), and will either execute the transactions, or apply the transaction outputs, depending on whichever is faster, per data chunk. This allows the node to adapt to CPU and network resource constraints more efficiently.
• Fast syncing. This mode will fetch the latest blockchain state directly, skipping all historical transactions. As a result, the node will not have historical transaction data, but it will be able to catch up much more quickly.

Caution

Syncing from genesis?
Most nodes in Mainnet and Testnet do not keep all transaction data since genesis. If you wish to sync all data since genesis, you need to manually add seed peers to node’s configuration file, so that your node can connect to peers with the data. See Connecting to Seed Peers.

Continuous syncing modes

After the node has bootstrapped, state sync will move into the continuous syncing phase to stay up-to-date with the blockchain.

Tip

Default continuous syncing modes?
The default continuous syncing mode is always intelligent syncing, because this mode is the most performant.

There are several continuous syncing modes:

• Executing transactions. This mode will keep the node up-to-date by executing transactions as they are committed to the blockchain.
• Applying transaction outputs. This mode will keep the node up-to-date by skipping the transaction execution and only applying the outputs of the transactions as previously produced by validator execution.
• Intelligent syncing. This mode will keep the node up-to-date by either executing the transactions, or applying the transaction outputs, depending on whichever is faster, per data chunk. This allows the node to adapt to CPU and network resource constraints more efficiently.

Configuring state sync

The snippets below provide instructions for configuring state sync on your nodes for different use cases. These configurations can be added to your node’s configuration file, e.g., fullnode.yaml or validator.yaml.

Danger

Do you need to configure state sync?
Most users should not need to configure state sync manually. State sync will automatically select the best configuration for your node and network. You should only configure state sync if you have a use case that requires it. Selecting the wrong configuration will lead to slower syncing times and degraded performance.

Executing transactions from genesis

To execute all transactions from genesis and continue to execute new transactions as they are committed, add the following to your node configuration file:

state_sync:
  state_sync_driver:
    bootstrapping_mode: ExecuteTransactionsFromGenesis
    continuous_syncing_mode: ExecuteTransactions

Applying transaction outputs from genesis

To apply all transaction outputs from genesis and continue to apply new transaction outputs as transactions are committed, add the following to your node configuration file:

state_sync:
  state_sync_driver:
    bootstrapping_mode: ApplyTransactionOutputsFromGenesis
    continuous_syncing_mode: ApplyTransactionOutputs

Intelligent syncing from genesis

To execute or apply all transactions and outputs since genesis (and continue to do the same as new transactions are committed), add the following to your node configuration file:

state_sync:
  state_sync_driver:
    bootstrapping_mode: ExecuteOrApplyFromGenesis
    continuous_syncing_mode: ExecuteTransactionsOrApplyOutputs

Fast syncing

To download the latest blockchain state and continue to process new transactions as they are committed, add the following to your node configuration file:

state_sync:
  state_sync_driver:
    bootstrapping_mode: DownloadLatestStates
    continuous_syncing_mode: ExecuteTransactionsOrApplyOutputs

Verifying Syncing Progress

To verify that your node is syncing correctly, you can monitor the relevant state sync metrics exposed by the Node Inspection Service.

If your node is bootstrapping in fast syncing mode, you should monitor the following metric:

• aptos_state_sync_version{type="synced_states"}: This metric indicates the highest blockchain state that has been processed. This metric will increase as your node fast syncs. Once all states have been downloaded, this metric will stop increasing and your node will begin processing transactions as usual.

During normal node operation, you should monitor the following metric:

• aptos_state_sync_version{type="synced"}: This metric indicates the highest transaction version that has been fully processed by your node. This metric will increase as long as your node is syncing correctly.

Tip

Fast syncing times
The speed of fast syncing depends on several factors, including your network bandwidth and disk performance. On most well-provisioned nodes, fast syncing usually completes within a few hours.

Archival PFNs

Danger

Archival nodes are deprecated
Running archival nodes is expensive and slow, as the amount of data being stored on the node will grow indefinitely. As a result, archival nodes have officially been deprecated. If you wish to store and maintain the entire blockchain history, we recommend using an Indexer.

To operate an archival PFN (which is a PFN that contains all blockchain data since the start of the network, i.e., genesis), you can:

1. Make sure that your PFN is not using fast syncing as the bootstrapping mode. Fast syncing will skip the transaction history. Instead, using a mode that syncs from genesis, e.g., intelligent syncing from genesis.
2. Disable the ledger pruner, as described in the Data Pruning document. This will ensure that no data is deleted and the PFN contains all blockchain data.

Following these two steps together will ensure that your PFN fetches all data since genesis, and continues to synchronize without pruning any data.

Caution

Syncing from genesis?
As mentioned above, if you wish to sync all data since genesis, you need to manually add seed peers to your node’s configuration file. See Connecting to Seed Peers.

Security implications and data integrity

All state syncing modes perform data integrity verifications to ensure that data is correct and appropriately signed by the validators. However, there are some differences in the security guarantees provided by each mode:

1. Executing transactions from genesis: Executing transactions from genesis is the most secure syncing mode. It will verify that all transactions since the beginning of time were correctly agreed upon by consensus and that all transactions were appropriately executed by the validators.
2. Applying transaction outputs from genesis: Applying transaction outputs from genesis requires that the syncing node trust the validators to have executed the transactions correctly. However, all other blockchain state is still manually re-verified, e.g., consensus messages, the transaction history and state hashes.
3. Intelligent syncing: Intelligent syncing will either execute transactions or apply transaction outputs depending on whichever is faster, per data chunk. The security implications of using this mode are identical to above, depending on which method is used for each data chunk.
4. Fast syncing: Fast syncing skips the transaction history and downloads the latest blockchain state before continuously syncing. To do this, it requires that the syncing node trust the validators to have correctly agreed upon all transactions in the transaction history as well as the results of executing those transactions. However, all other blockchain data is still manually re-verified, e.g., epoch changes and the resulting blockchain states.

All the syncing modes get their root of trust from the validator set and cryptographic signatures from those validators over the blockchain data. For more information about how this works, see the state synchronization blog post.