Join the network using Snapshots

Detailed guide for using snapshots to join the network

Before you resync a node from a snapshot, make sure that your validator cannot double sign. After a successful resync, your validator must under no circumstance double sign blocks at previous heights. If it does, the validator is tombstoned.

Use snapshot sync to start a new full node and join an existing network quickly. Snapshot sync restores the node from a snapshot instead of replaying all historical blocks.

Snapshot sync

Snapshot sync lets a new node join a network with a recent, compressed copy of the entire application state. The node downloads the copy and extracts it directly into the data directory. This reduces the initial sync time from days to minutes.

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. RocksDB support for the SeiDB state store will be removed. No target release has been published. If you are replacing an existing RocksDB node, see Move off RocksDB.

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 download snapshots from these providers:

• Polkachu: Sei Mainnet snapshots | Sei Testnet snapshots
• Imperator.co
• Stakeme
• kjnodes

Snapshot providers do not consistently label the state-store backend. Before you restore a snapshot, ask the provider to confirm that it uses PebbleDB. 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 the node is not new, back up and clean up the existing node first.

Skip this step on a new node.

1. Stop the service

   sudo systemctl stop seid
   

2. Back up validator state (critical for validators) If 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 what 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 that the snapshot’s default paths are used. If you keep custom paths, follow your provider’s placement instructions. 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
   

Copy the wasm folder too. All snapshots include the wasm folder, and the node cannot sync successfully without it.

Download & restore

These commands are generic examples. Verify the SNAPSHOT_URL and the extraction command with the provider that you chose above.

Prerequisites

Make sure that you have the necessary tools installed (for example, lz4, aria2, pv, and 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. The -s 16 flag splits the file into 16 segments for parallel download. You can adjust these values to match 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. This 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 that SeiDB is enabled and that 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 missing, 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 cannot download a snapshot. A: Try again later, because providers refresh these snapshots regularly. Also report the problem in the Sei Tech Chat.

Q: The snapshot finishes, but I get AppHash errors as soon as regular block sync starts. A: Make sure that you use the latest version of the node software. These errors usually mean that the snapshot version does not match your node version, or that the snapshot is corrupted. Make sure that you use 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. Make sure that you have enough free space (check with df -h).