Join the network using Snapshots

Detailed guide for using snapshots to join the network

Before you resync a node using snapshots, make sure that in case of a successful resync that you under no circumstance double sign blocks at previous heights with your validator. Failure to do so will cause tombstoning of your validator.

Follow this guide to join an existing network through snapshot sync. To quickly spin up a fresh full node and join the network, it’s recommended to restore from a snapshot instead of replaying all historical blocks.

Snapshot Sync

Snapshot sync allows a new node to join a network by downloading a recent, compressed copy of the entire application state and extracting it directly into the data directory. This reduces the initial sync time from days to minutes.

RocksDB support for the SeiDB state store will be removed. No target release has been published. For new or resynced nodes, use a snapshot only after its provider confirms that the state store uses PebbleDB. Keep ss-backend = "pebbledb" in app.toml. See Move off RocksDB if you are replacing an existing RocksDB node.

Do not restore a pruned snapshot onto an archive node. It does not contain the earlier state-store versions that the archive node must retain. Use only a provider-confirmed full-history PebbleDB archive snapshot, or follow the archive-node guidance in Move off RocksDB.

Snapshot Providers

You can select from various providers for downloading snapshots:

• Polkachu: Mainnet Snapshots | Testnet Snapshots
• Imperator.co
• Stakeme
• kjnodes

Snapshot providers do not consistently label the state-store backend. Ask the provider to confirm that the snapshot uses PebbleDB before you restore it. The post-extraction check below is a second guard against archives that contain an obvious RocksDB path. It does not replace provider confirmation because some legacy and custom directory names do not identify their backend.

Clean Up & Preparation

If you are not starting a node from fresh, perform the following backups and clean‑ups first.

Note: This step is not needed for fresh nodes.

1. Stop the service

   sudo systemctl stop seid
   

2. Backup Validator State (Critical for Validators) Assuming your sei home directory is $HOME/.sei, back up priv_validator_key.json and priv_validator_state.json:

   cp $HOME/.sei/data/priv_validator_state.json $HOME/priv_validator_state.json
   cp $HOME/.sei/config/priv_validator_key.json $HOME/priv_validator_key.json
   

3. Reset the State

   seid tendermint unsafe-reset-all --home $HOME/.sei
   

4. Check custom state-store paths Print the state-store section from app.toml:

   sed -n '/^\[state-store\]/,/^\[.*\]/p' $HOME/.sei/config/app.toml
   

   If ss-db-directory or evm-ss-db-directory is not empty, the state store may live outside $HOME/.sei/data. Back up anything you need, then move or remove the old state-store data before you restore the snapshot. The generic commands below expect both settings to be empty so the snapshot’s default paths are used. Follow your provider’s placement instructions if you keep custom paths. Do not reuse a RocksDB directory with ss-backend = "pebbledb".

5. Remove data and Wasm

   rm -rf $HOME/.sei/data
   rm -rf $HOME/.sei/wasm
   

All snapshots also include the wasm folder. Make sure to copy over the wasm folder as well, the node cannot successfully sync without it.

Download & Restore

The following commands are generic examples. Please verify the SNAPSHOT_URL and extraction command from your chosen provider above.

Prerequisites

Ensure you have the necessary tools installed (e.g., lz4, aria2, pv, wget).

sudo apt update
sudo apt install curl lz4 wget aria2 pv -y

Download and Extract

1. Set the Snapshot URL Replace <SNAPSHOT_URL> with the link from your chosen provider.

   SNAPSHOT_URL="<PASTE_SNAPSHOT_URL_HERE>"
   

2. Extract the snapshot Most providers compress the data and wasm directories directly. Stream the archive to avoid storing a second compressed copy:

   set -o pipefail
   curl --fail -L "$SNAPSHOT_URL" | lz4 -c -d | tar -x -C "$HOME/.sei"
   

   Alternative: parallel download with aria2

   aria2c supports parallel connections but keeps the compressed archive beside the extracted data. Put the archive on a data disk with enough free space for both:

   set -o pipefail
   SNAPSHOT_FILE="/path/on-data-disk/snapshot.tar.lz4"
   aria2c -x 16 -s 16 \
     -d "$(dirname "$SNAPSHOT_FILE")" \
     -o "$(basename "$SNAPSHOT_FILE")" \
     "$SNAPSHOT_URL" && \
     pv "$SNAPSHOT_FILE" | lz4 -c -d | tar -x -C "$HOME/.sei"
   
   The -x 16 flag sets the maximum connections per server, and -s 16 splits the file into 16 segments for parallel downloading. You can adjust these values based on your network conditions.

   If extraction fails, remove the partially extracted data and wasm directories before you retry. Do not continue to verification.

   Some providers wrap the data in another directory or use a different compression format. For a .tar.gz snapshot, use the provider’s tar -xzf command. If the archive contains a root directory such as sei/data, adjust the extraction target or --strip-components. Run the backend check below after any extraction method.

3. Verify every extracted state-store path The check below scans every backend-labelled default state-store path instead of stopping at the first result. It catches archives that contain both PebbleDB and RocksDB:

   verify_snapshot_backend() {
     local state_store_config backend_dirs backend path
   
     if [ ! -f "$HOME/.sei/config/app.toml" ]; then
       echo "UNVERIFIED: app.toml not found. Do not start seid." >&2
       return 1
     fi
   
     state_store_config="$(
       sed -n '/^\[state-store\]/,/^\[.*\]/p' \
         "$HOME/.sei/config/app.toml"
     )"
   
     if printf '%s\n' "$state_store_config" | \
       grep -Eq "^[[:space:]]*(ss-db-directory|evm-ss-db-directory)[[:space:]]*=[[:space:]]*(\"[^\"]+\"|'[^']+')"; then
       echo "UNVERIFIED: custom state-store directory configured." >&2
       echo "Use the provider-specific placement and verification steps." >&2
       return 1
     fi
   
     backend_dirs="$(
       for backend in pebbledb rocksdb; do
         for path in \
           "$HOME/.sei/data/$backend" \
           "$HOME/.sei/data/state_store/cosmos/$backend" \
           "$HOME/.sei/data/state_store/evm/$backend"; do
           if [ -d "$path" ]; then
             printf '%s\n' "$path"
           fi
         done
       done
     )"
   
     printf '%s\n' "$backend_dirs"
   
     if printf '%s\n' "$backend_dirs" | grep -Eq '(^|/)rocksdb$'; then
       echo "FAIL: RocksDB data found. Do not start seid." >&2
       return 1
     fi
   
     if ! printf '%s\n' "$backend_dirs" | grep -Eq '(^|/)pebbledb$'; then
       echo "UNVERIFIED: no PebbleDB state-store directory found." >&2
       return 1
     fi
   
     echo "PASS: PebbleDB found and no RocksDB directory found."
   }
   
   verify_snapshot_backend
   

   The function returns a nonzero status for FAIL and UNVERIFIED. Continue only if the provider confirmed PebbleDB and the command prints PASS. A legacy EVM store at data/evm_ss/ does not identify its backend in the directory name, which is why provider confirmation is still required. If you used aria2c, remove the downloaded archive after this check passes:

   rm "$SNAPSHOT_FILE"
   

4. Restore validator state

   cp $HOME/priv_validator_state.json $HOME/.sei/data/priv_validator_state.json
   

5. Enable SeiDB and configure PebbleDB Make sure SeiDB is enabled and the state-store backend is PebbleDB:

   sed -i.bak -E "/^\[state-commit\]/,/^\[.*\]/ s|^[#[:space:]]*(sc-enable[[:space:]]*=[[:space:]]*).*$|\1true| ; /^\[state-store\]/,/^\[.*\]/ s|^[#[:space:]]*(ss-enable[[:space:]]*=[[:space:]]*).*$|\1true| ; /^\[state-store\]/,/^\[.*\]/ s|^[#[:space:]]*(ss-backend[[:space:]]*=[[:space:]]*).*$|\1\"pebbledb\"|" $HOME/.sei/config/app.toml
   
   sed -n '/^\[state-store\]/,/^\[.*\]/p' $HOME/.sei/config/app.toml
   

   Confirm that the output includes ss-backend = "pebbledb". If the key is absent, add it directly below [state-store] before you restart the node.

6. Restart the node

   sudo systemctl start seid
   

7. Monitor logs

   sudo journalctl -fu seid
   

Troubleshooting

Q: I can’t download a snapshot. A: Try another time later as these snapshots are refreshed regularly and inform us in the Sei Tech Chat.

Q: The snapshot finishes, but I immediately get AppHash errors upon regular block syncing. A: Make sure that you use the latest version of the node software. This usually means the snapshot version doesn’t match your node version, or the snapshot is corrupted. Ensure you are using the correct binary version for the block height of the snapshot.

Q: “No space left on device” A: Snapshots require significant disk space to download and extract. Ensure you have enough free space (check with df -h).