> For the complete documentation index, see [llms.txt](https://bitnet-whitepaper.gitbook.io/developer-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bitnet-whitepaper.gitbook.io/developer-docs/setup-and-configuration/state-sync.md).

# 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

{% hint style="info" %}
Snapshots must be **deterministic**, **consistent**, and **isolated** from concurrent block writes.
{% endhint %}

***

#### Enabling Snapshot Creation (Validator Setup)

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

```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

{% hint style="danger" %}
Snapshot interval must be a multiple of `pruning-keep-every` to avoid accidental pruning during snapshot creation.
{% endhint %}

***

#### 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`:**

```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 = ""
```

3. **Run node:**

```bash
bitnetd start
```

4. **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:

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bitnet-whitepaper.gitbook.io/developer-docs/setup-and-configuration/state-sync.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.