Lumera Mainnet State Sync

State sync allows a node to synchronize with the network quickly by downloading a recent application state snapshot instead of replaying all historical blocks.

This method significantly reduces sync time and disk usage.

Requirements

Before using state sync, make sure:

• The RPC endpoint supports state sync snapshots
• jq is installed
• Your node binary is stopped

Configuration Overview

State sync parameters in this guide are derived from the snapshot configuration of Linknode-operated Lumera RPC nodes.

Snapshot settings:

Setting	Value
Snapshot interval	1000 blocks
Snapshots retained	5 recent snapshots

These values directly affect the trusted height calculation used during state sync.
RPC providers with different snapshot configurations may require a different offset value.

State Sync Instructions

CHAIN_HOME="$HOME/.lumera"
CHAIN_BIN="lumerad"
RPC_URL="https://lumera-rpc.linknode.org"
OFFSET=1000
PERSISTENT_PEERS="22e6390f4d0c90c297cac4ac5a00ea53cec9b9e3@89.58.12.214:10656"

# Stop node
sudo systemctl stop $CHAIN_BIN

sudo mv $HOME/.lumera/data/priv_validator_state.json $HOME/.lumera/priv_validator_state.json.backup

# Reset data
$CHAIN_BIN tendermint unsafe-reset-all --home $CHAIN_HOME --keep-addr-book

# Get latest height
LATEST_HEIGHT=$(curl -s $RPC_URL/block | jq -r .result.block.header.height)

if [ -z "$LATEST_HEIGHT" ]; then
  echo "Failed to fetch latest height from RPC"
  exit 1
fi

# Calculate trusted height
TRUST_HEIGHT=$((LATEST_HEIGHT - OFFSET))

# Get trusted hash
TRUST_HASH=$(curl -s "$RPC_URL/block?height=$TRUST_HEIGHT" | jq -r .result.block_id.hash)

if [ -z "$TRUST_HASH" ]; then
  echo "Failed to fetch trusted hash from RPC"
  exit 1
fi

echo "Trusted Height: $TRUST_HEIGHT"
echo "Trusted Hash: $TRUST_HASH"

# Configure state sync
sed -i \
  -e "s|^enable *=.*|enable = true|" \
  -e "s|^rpc_servers *=.*|rpc_servers = \"$RPC_URL,$RPC_URL\"|" \
  -e "s|^trust_height *=.*|trust_height = $TRUST_HEIGHT|" \
  -e "s|^trust_hash *=.*|trust_hash = \"$TRUST_HASH\"|" \
  $CHAIN_HOME/config/config.toml

sed -i "s|^persistent_peers *=.*|persistent_peers = \"$PERSISTENT_PEERS\"|" $HOME/.lumera/config/config.toml

sudo mv $HOME/.lumera/priv_validator_state.json.backup $HOME/.lumera/data/priv_validator_state.json

# Start node
sudo systemctl start $CHAIN_BIN

# Check logs
journalctl -u $CHAIN_BIN -f

If configured correctly, the node will discover snapshots and complete synchronization within a few minutes.

Notes

• The OFFSET value must match the snapshot interval used by the RPC provider
• If state sync fails, reduce the offset value
• Avoid using large offsets unless the RPC serves older snapshots

Common Errors

no snapshot available

• The RPC endpoint does not serve snapshots
• The trusted height is lower than the available snapshot height

Solution: reduce the offset or switch RPC endpoints

Node stuck at Discovering snapshots

• RPC endpoint overloaded or unstable

Solution: retry later or use an alternative RPC

Verify Sync Status

$CHAIN_BIN status 2>&1 | jq .SyncInfo

The node is fully synced when:

"catching_up": false

Summary

State sync is the recommended way to quickly synchronize a Lumera node.

Using the correct offset value ensures a reliable and successful state sync process.