State Sync

Fast Node Bootstrapping with State Sync on BitNet

To improve validator onboarding and reduce syncing time, BitNet supports Tendermint Core State Sync, allowing nodes to join the network by restoring the latest application state from trusted peers instead of replaying all historical blocks.

What is State Sync?

State Sync enables a new BitNet node to:

• Download a recent snapshot of the network’s application state.

• Skip downloading and replaying every block since genesis.

• Join the consensus in minutes instead of days.

This drastically reduces disk usage and sync time, especially on mature networks with extensive history.

---

How State Sync Works

BitNet validators serve state snapshots, which are shared in binary chunks. Tendermint fetches and verifies these chunks using light client techniques. Once all chunks are applied, the node verifies the state root (appHash) and proceeds with normal consensus participation.

Each snapshot includes:

• height: block height of the snapshot

• chunks: number of binary chunks

• hash: snapshot identifier (used for cross-node comparison)

• metadata: optional binary data for verification

Snapshots must be deterministic, consistent, and isolated from concurrent block writes.

---

Enabling Snapshot Creation (Validator Setup)

Validators should enable periodic snapshots to assist new nodes. In app.toml:

snapshot-interval = 1000
snapshot-keep-recent = 2

This setup:

• Generates a snapshot every 1000 blocks

• Keeps the last 2 snapshots to support syncing peers

Snapshot interval must be a multiple of pruning-keep-every to avoid accidental pruning during snapshot creation.

---

State Sync Configuration (Joining as a New Node)

To configure a new node using state sync:

1. Fetch trusted block data:

   • Snapshot height from a trusted source

   • appHash from that height

   • Two RPC endpoints to sync from

2. Set up state sync in config.toml:

enable = true
rpc_servers = "https://rpc1.bitnet.org:26657,https://rpc2.bitnet.org:26657"
trust_height = <snapshot_height>
trust_hash = "<trusted_block_hash>"
seeds = ""

1. Run node:

bitnetd start

1. Watch logs for confirmation:

Discovered new snapshot at height=3000
Snapshot accepted, restoring...
Applied chunk 1/3
Verified ABCI app hash

Once all chunks are applied and verified, the node switches to fast sync mode, catching up remaining blocks before joining consensus.

---

Important Notes

• State-synced nodes will not retain full block history. They start from the snapshot height.

• Archive nodes should be maintained for historical data and audits.

• It is safe to disable state sync after the node is fully synced to prevent unnecessary memory or CPU use:

sed -i 's/^enable *= *.*/enable = false/' ~/.bitnetd/config/config.toml