Chain management

The Lotus chain carries the information necessary to compute the current state of the Filecoin network. This guide explains how to manage several aspects of the chain, including how to decrease your node's sync time by loading the chain from a snapshot.

Syncing

Lotus will automatically sync to the latest chain head by fetching the block headers from the current head down to the last synced epoch. The node then retrieves and verifies all the blocks from the last synced epoch to the current head. Once Lotus is synced, it will learn about new blocks as they are mined for every epoch and verify them accordingly. Every epoch might see a variable number of mined blocks.

Filecoin’s blockchain is complex and grows relatively fast. It takes about 4 seconds to verify a tipset, which in turn means it takes about 1 month to validate 700,000 tipsets. As syncing the chain from genesis is no longer practical, an alternative is to obtain a collection of all IPLD blocks one needs to continue validating the chain state going forward. Such a collection is called a snapshot. Currently one such snapshot is available

NameEnd heightMessage start heightState start height
LightweightRecent blockRecent block - 2000 blocksCurrent block - 2000 blocks

Lightweight snapshot

We recommend most users perform the initial node sync from a lightweight snapshot. These snapshots do not contain the full states of the chain and are not suitable for nodes that need to perform queries against historical state information, such as block explorers. However, they are significantly smaller than full chain snapshots and should be sufficient for most use-cases.

  1. Download the most recent lightweight snapshot:

    a. For mainnet, command always contains the latest snapshot available for mainnet:

    aria2c -x5 https://forest-archive.chainsafe.dev/latest/mainnet/

    a. For calibnet, command always contains the latest snapshot available for the calibration testnet:

    aria2c -x5 https://forest-archive.chainsafe.dev/latest/calibnet/

  1. Start the Lotus daemon using --import-snapshot:

    # Replace the filename for the `.car` file based on the snapshot you downloaded.
lotus daemon --import-snapshot forest_snapshot_mainnet_2024-01-11_height_3555440.forest.car.zst

Sync wait

Use sync wait to output the state of your current chain as an ongoing process:

lotus sync wait

This will output something like:

Worker: 0; Base: 0; Target: 414300 (diff: 414300)
State: header sync; Current Epoch: 410769; Todo: 3531
Validated 0 messages (0 per second)
...

Use chain getblock to check when the last synced block was mined:

date -d @$(./lotus chain getblock $(./lotus chain head) | jq .Timestamp)

This will output something like:

Mon 24 Aug 2020 06:00:00 PM EDT

Creating a snapshot

A lightweight chain CAR-snapshot can be created with chain export:

lotus chain export --recent-stateroots=2000 --skip-old-msgs <filename>

Restoring a custom snapshot

You can restore snapshots by starting the daemon with the --import-snapshot option:

lotus daemon --import-snapshot <filename>

If you do not want the daemon to start once the snapshot has finished, add the --halt-after-import flag:

lotus daemon --halt-after-import --import-snapshot <filename>

Compacting the chain data

It is possible to prune the current chain data used by Lotus to reduce the node’s disk footprint by resyncing from a minimal snapshot.

  1. Download a lightweight snapshot following the steps in Lightweight Snapshots

  2. Stop the Lotus daemon:

    lotus daemon stop

  3. Back up the chain data and create a directory for chain data:

    mv ~/.lotus/datastore/chain ~/.lotus/datastore/chain_backup
mkdir ~/.lotus/datastore/chain

  4. Import the chain data:

    lotus daemon --import-snapshot my-snapshot.car --halt-after-import

  5. Start the daemon:

    lotus daemon

  6. Open another ssh connection or terminal to check sync status :

    lotus sync status 
lotus sync wait

  7. That’s it!

Edit this page on GitHub

← Multisig
Message pool →