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.

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).

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

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.

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

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.

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.

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

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

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

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

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.

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.

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.