Skip to main content

State Sync Configuration

TL;DR: ZIGChain state sync brings a fresh node to near-current height without replaying every block from genesis. Trust a recent state proof from a snapshot-enabled RPC, update config.toml, refresh seeds, and restart zigchaind.

Overview​

ZIGChain state sync is the recommended method for bringing a fresh node to near-current height without downloading every historical block. Instead of replaying the consensus log from genesis, your node trusts a recent state proof from a well-known RPC node and downloads the state directly. Operators use this path when they need a signing or full node at the chain tip quickly.

State sync is built into the Cosmos SDK and allows validators or sentry nodes to join the network rapidly by trusting a snapshot-enabled RPC endpoint from a recent block height. This dramatically reduces the time it takes to reach the tip of the chain, but it also means the node only stores the most recent state that the RPC service exposes. Plan disk and RPC usage accordingly before you enable the mode on a host.

Before running state sync, finish the steps in Set Up a ZIGChain Node. The setup guide covers zigchaind install, genesis, and baseline config.toml values. Return here afterward to set SNAP_RPC variables, trust height, trust hash, and seed peers on the same machine.

info

For nodes that serve explorers, dApps, or other RPC clients that require the full historical transaction log, state sync is not appropriate—these workloads still need a fully synced node with the entire block history. If state sync is unavailable or fails, use Snapshots as an alternative bootstrap method.

Key Concepts​

  • ZIGChain state sync: Cosmos SDK mode that downloads recent chain state instead of replaying from genesis.
  • Trust height and trust hash: Trusted block height and block ID hash written into config.toml for sync start.
  • SNAP_RPC: Snapshot-enabled RPC used to query head height and the trusted block.
  • Seed nodes: Addresses from SEED_NODES, written to persistent_peers so the node can join the mesh.
  • persistent_peers: Comma-separated peer list in config.toml; the seed download step populates it from the network seed file.

RPC and Seed References​

Define the variables that match your target network before continuing. Mainnet and testnet use different public RPC endpoints and seed list URLs from the ZIGChain networks repository. Export SNAP_RPC and SEED_NODES in the same shell session you use for trust-parameter queries and sed edits.

Pick Mainnet or Testnet in the tab below and run the matching block once per machine. Keep that shell open through the enable and verify steps so SNAP_RPC stays set for block queries and for rpc_servers in config.toml. You will query the latest height and the trusted block from the same SNAP_RPC value.

SNAP_RPC="https://public-zigchain-rpc.numia.xyz:443"
SEED_NODES="https://raw.githubusercontent.com/ZIGChain/networks/main/zigchain-1/seed-nodes.txt"

Enable ZIGChain state sync​

ZIGChain state sync is configured in $HOME/.zigchain/config/config.toml under the state sync settings. You compute trust height and hash from SNAP_RPC, enable the service, refresh persistent peers from the seed file, and restart zigchaind. Run every step on the host where you completed node setup.

The trust block must sit slightly below the chain head so the RPC still serves that height and its block ID hash. The commands below use a fixed offset from the latest height; if sync fails, recalculate trust parameters from a fresh head query before you retry.

  1. Calculate trust parameters.

    The node must trust a block that is slightly behind the head so that the block is available from the RPC endpoint.

LATEST_HEIGHT=$(curl -s $SNAP_RPC/block | jq -r .result.block.header.height)
BLOCK_HEIGHT=$((LATEST_HEIGHT - 5000))
TRUST_HASH=$(curl -s "$SNAP_RPC/block?height=$BLOCK_HEIGHT" | jq -r .result.block_id.hash)
  1. Update config.toml.

Enable the service and inject the RPC servers, trust height, and trust hash. The commands differ slightly per platform:

sed -i.bak -E \
    "s|^(enable[[:space:]]*=[[:space:]]*).*$|\1true| ; \
     s|^(rpc_servers[[:space:]]*=[[:space:]]*).*$|\1\"$SNAP_RPC,$SNAP_RPC\"| ; \
     s|^(trust_height[[:space:]]*=[[:space:]]*).*$|\1$BLOCK_HEIGHT| ; \
     s|^(trust_hash[[:space:]]*=[[:space:]]*).*$|\1\"$TRUST_HASH\"|" \
    "$HOME/.zigchain/config/config.toml"

  1. Refresh the seed list.

    Download the current seed nodes and write them into config.toml.

SEED_FILE="$HOME/.zigchain/config/seeds.txt"
wget "$SEED_NODES" -O "$SEED_FILE"
SEEDS=$(paste -sd, "$SEED_FILE")
sed -i.bak -E "s|^(persistent_peers[[:space:]]*=[[:space:]]*).*|\1\"$SEEDS\"|" "$HOME/.zigchain/config/config.toml"

  1. Restart the node.

    Once the configuration is updated, restart zigchaind. Use your service manager (systemctl, launchctl, etc.) or run zigchaind start in the foreground. The log should show state sync progress (e.g., service state-sync logs).

Verify Synchronization​

Confirm that the node is no longer catching up and that state sync completed. Query the local Tendermint RPC on port 26657 and inspect the sync_info object from the node host or from any client that can reach that port.

curl -s localhost:26657/status | jq '.result.sync_info'

Look for catching_up: false and ensure the latest_block_height increases over time without the node replaying every block. A rising height with catching_up: false means the node is following new blocks after state sync finished.

If catching_up stays true, recheck trust height, trust hash, and seed peers in config.toml. Re-run the trust-parameter commands from SNAP_RPC if the trusted block may have fallen outside the RPC retention window. Startup logs that mention service state-sync confirm the node loaded your state sync settings.

Compare two status queries a few minutes apart when you want to confirm forward progress. A climbing latest_block_height with catching_up: false is the expected steady state on a healthy peer set. When progress stalls, fix configuration before you switch to Snapshots for bootstrap.

Common Questions​

Who should use ZIGChain state sync?​

Validators and sentry nodes that need current chain state and forward blocks are the usual fit. They benefit from faster bootstrap without storing full history on day one. Operators still run the same trust-parameter and seed steps as full nodes, but they do not need a complete transaction archive at join time.

Nodes that must index or serve every past transaction should use full sync instead. Explorer backends and dApp RPC providers fall in that group because clients expect old heights and proofs. See the info note at the top of this page when you are unsure which path fits your workload.