Sync-modes

Syncing is the process by which Etn-sc catches up to the latest Electroneum block and current global state. There are several ways to sync a Etn-sc node that differ in their speed, storage requirements and trust assumptions.

Full nodes

There are two types of full node that use different mechanisms to sync up to the head of the chain:

Snap (default)

Snap sync starts from a relatively recent block and syncs from there to the head of the chain, keeping only the most recent 128 block states in memory. Between the initial sync block and the 128 most recent blocks, the node stores occasional snapshots that can be used to rebuild any intermediate state "on-the-fly". The difference between the snap-synced node and a full block-by-block synced node is that a snap synced node started from an initial checkpoint that was more recent than the genesis block. Snap sync is much faster than a full block-by-block sync from genesis. To start a node with snap sync pass --syncmode snap at startup.

Snap sync works by first 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, Etn-sc also begins state-sync. In state-sync, Etn-sc 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. Etn-sc regularly reports Syncing, state heal in progress during state healing - this informs the user that state heal has not finished. It is also possible to confirm this using eth.syncing - if this command returns false then the node is in sync. If it returns anything other than false then syncing is still in progress.

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

Snap sync is the default behaviour, so if the --syncmode value is not passed to Etn-sc at startup, Etn-sc will use snap sync. A node that is started using snap will switch to block-by-block sync once it has caught up to the head of the chain.

Full

A full block-by-block sync generates the current state by executing every block starting from the genesis block. A full sync independently verifies 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 10.7 minutes of history with a block time of 5 seconds.

To create a full node pass --syncmode full at startup.

Archive nodes

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. Archive nodes are created by configuring Etn-sc's garbage collection so that old data is never deleted: etn-sc --syncmode full --gcmode archive.

It is also possible to create a partial/recent archive node where the node was synced using snap but 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 Etn-sc with --syncmode snap --gcmode archive.

Light nodes

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 Electroneum and submit transactions, acting as a locally-hosted Electroneum wallet. However, because they don't keep local copies of the Electroneum 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 relatively scarce so light nodes can struggle to find peers.

Read more about light nodes on our LES page.

Summary

There are several ways to sync an Etn-sc node. The default is to use snap sync to create a full node. Full nodes can be created by syncing block-by-block from genesis (full-sync) or by starting at an intermediate checkpoint block (snap-sync). By default, these modes prune 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. Partial archive nodes can be created by snap-syncing a node and turning off state-pruning to create a node that keeps all states since the initial sync block.