Syncing is the process by which Geth catches up to the latest Ethereum block and current global state. There are several ways to sync a Geth node that differ in their speed, storage requirements and trust assumptions. This page outlines three sync configurations for full nodes and one for light nodes.
There are two types of full node that use different mechanisms to sync up to the head of the chain:
A snap sync’d node holds the most recent 128 block states in memory, so transactions in that range are always quickly accessible. However, snap-sync only starts processing from a relatively recent block (as opposed to genesis for a full node). Between the initial sync block and the 128 most recent blocks, the node stores occasional checkpoints that can be used to rebuild the state on-the-fly. This means transactions can be traced back as far as the block that was used for the initial sync. Tracing a single transaction requires reexecuting all preceding transactions in the same block and all preceding blocks until the previous stored snapshot. Snap-sync’d nodes are therefore full nodes, with the only difference being the initial synchronization required a checkpoint block to sync from instead of independently verifying the chain all the way from genesis. Snap sync then only verifies the proof-of-work and ancestor-child block progression and assumes that the state transitions are correct rather than re-executing the transactions in each block to verify the state changes. Snap sync is much faster than block-by-block sync. To start a node with snap sync pass
--syncmode snapat startup.
Snap sync starts by downloading the headers for a chunk of blocks. Once the headers have been verified, the block bodies and receipts for those blocks are downloaded. In parallel, Geth also sync begins state-sync. In state-sync, Geth first downloads the leaves of the state trie for each block without the intermediate nodes along with a range proof. The state trie is then regenerated locally. The state download is the part of the snap-sync that takes the most time to complete and the progress can be monitored using the ETA values in the log messages. However, the blockchain is also progressing at the same time and invalidating some of the regenerated state data. This means it is also necessary to have a ‘healing’ phase where errors in the state are fixed. It is not possible to monitor the progress of the state heal because the extent of the errors cannot be known until the current state has already been regenerated. The healing has to outpace the growth of the blockchain, otherwise the node will never catch up to the current state. There are some hardware factors that determine the speed of the state healing (speed of disk read/write and internet connection) and also the total gas used in each block (more gas means more changes to the state that have to be handled).
To summarize, snap sync progresses in the following sequence:
- download and verify headers
- download block bodies and receipts.In parallel, download raw state data and build state trie
- heal state trie to account for newly arriving data
Note Snap sync is the default behaviour, so if the
--syncmodevalue is not passed to Geth at startup, Geth will use snap sync. A node that is started using
snapwill switch to block-by-block sync once it has caught up to the head of the chain.
A full sync generates the current state by executing every block starting from the genesis block. A full sync indendently verifies proof-of-Stake and block provenance as well as all state transitions by re-executing the transactions in the entire historical sequence of blocks. Only the most recent 128 block states are stored in a full node - older block states are pruned periodically and represented as a series of checkpoints from which any previous state can be regenerated on request. 128 blocks is about 25.6 minutes of history with a block time of 12 seconds. To create a full node pass
--syncmode fullat startup.
An archive node is a node that retains all historical data right back to genesis. There is no need to regenerate any data from checkpoints because all data is directly available in the node’s own storage. Archive nodes are therefore ideal for making fast queries about historical states. At the time of writing (September 2022) a full archive node that stores all data since genesis occupies nearly 1GB of disk space Archive nodes are created by configuring Geth’s garbage collection so that old data is never deleted:
geth --syncmode full --gcmode archive.
It is also possible to create a partial/recent archive node where the node was synced using
snapbut the state is never pruned. This creates an archive node that saves all state data from the point that the node first syncs. This is configured by starting Geth with
--syncmode snap --gcmode archive.
A light node syncs very quickly and stores the bare minimum of blockchain data. Light nodes only process block headers, not entire blocks. This greatly reduces the computation time, storage and bandwidth required relative to a full node. This means light nodes are suitable for resource-constrained devices and can catch up to the head of the chain much faster when they are new or have been offline for a while. The trade-off is that light nodes rely heavily on data served by altruistic full nodes. A light client can be used to query data from Ethereum and submit transactions, acting as a locally-hosted Ethereum wallet. However, because they don’t keep local copies of the Ethereum state, light nodes can’t validate blocks in the same way as full nodes - they receive a proof from the full node and verify it against their local header chain. To start a node in light mode, pass
--syncmode light. Be aware that full nodes serving light data are relative scarce so light nodes can struggle to find peers.
There are several ways to sync a Geth node. The default is to use snap sync to create a full node. This verifies all blocks using some recent block that is old enough to be safe from re-orgs as a sync target. A trust-minimized alternative is full-sync, which verifies every block since genesis. These modes drop state data older than 128 blocks, keeping only checkpoints that enable on-request regeneration of historical states. For rapid queries of historical data an archive node is required. Archive nodes keep local copies of all historical data right back to genesis - currently about 12 TB and growing. The opposite extreme is a light node that doesn’t store any blockchain data - it requests everything from full nodes. These configurations are controlled by passing
--syncmodeat startup. For an archive node,
--gcmodeshould be set to
archive. Currently, due to the transition to proof-of-stake, light-sync dot not work (new light client protocols are being developed).