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.


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 grows relatively fast and a full sync will take a long time. Lotus offers a faster way to sync by using trusted state snapshots. There are two types of snapshot available:

NameEnd heightMessage start heightState start height
LightweightCurrent blockCurrent block - 2000 blocksCurrent block - 2000 blocks
Full chainCurrent blockGenesis blockCurrent 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 and its checksum:

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

    curl -sI | perl -ne '/x-amz-website-redirect-location:\s(.+)\.car/ && print "$1.sha256sum\n$"' | xargs wget

    b. For testnet, use the latest calibration network snapshot. Testnet snapshots are maintained by Filecoin community voluntarily, and may not be up-to-date. Please double check before using them.

    curl -sI
  2. Check the sha256sum of the downloaded snapshot:

    # Replace the filenames for both `.sha256sum` and `.car` files based on the snapshot you downloaded.
    echo "$(cut -c 1-64 minimal_finality_stateroots_517061_2021-02-20_11-00-00.sha256sum)" | sha256sum --check

    This will output something like: OK
  3. Start the Lotus daemon using --import-snapshot:

    # Replace the filename for the `.car` file based on the snapshot you downloaded.
    lotus daemon --import-snapshot

Full chain snapshot

Full chain snapshots contain every block from genesis until the current tipset. You can trustlessly import these complete snapshots by supplying the --import-chain option to recalculate the entire state during import:

lotus daemon --import-chain

This operation will take multiple days due to the size and complexity of the Filecoin blockchain.

Checking sync status

There are two ways to check your Lotus daemon’s chain synching progress.

Sync status

Use sync status to output the current state of your local chain:

lotus sync status

This will output something like:

sync status:
worker 0:
        Base:   [bafy2bzacecnamqgqmifpluoeldx7zzglxcljo6oja4vrmtj7432rphldpdmm2]
        Target: [bafy2bzaceb4b3ionbbxz4uqoehzkjlt4ayta7bneh2bh5xatnwypeuqypebmw bafy2bzaceb2uct4pawanule5bt2ivepcgqls6e6f52lccofvdyfynyfnsa3aa bafy2bzacealylayv2mpgx7wkf54diu6vqmw5yubdgkauii7q2fb7hvwk4343i] (414300)
        Height diff:    414300
        Stage: header sync
        Height: 414300
        Elapsed: 765.267091ms

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 full chain CAR-snapshot can be created with chain export:

lotus chain export <filename>

To back up a certain number of the most recent state roots, use the --recent-stateroots option, along with how many state roots you would like to backup:

lotus chain export --recent-stateroots=2000 <filename>

To create a pruned snapshot and only include blocks directly referenced by the exported state roots, add the skip-old-msgs option:

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:

# Without verification
lotus daemon --import-snapshot <filename>

# With verification
lotus daemon --import-chain <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. Export the chain data:

    lotus chain export --recent-stateroots=901 --skip-old-msgs
  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 --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