Skip to content

Docs: Migrate blockchain state storage to RocksDB and add state migration guide #159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dobotro wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Docs: Migrate blockchain state storage to RocksDB and add state migration guide #159

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
97a8761
Docs: Add state storage migration guide to node setup
Nov 17, 2025
3c66aa3
Update checkpoint documentation to reflect new .ckpt format and conve…
Nov 17, 2025
2bff6d5
Docs: Update unbonding period in Solo Staking section
Nov 17, 2025
f8d78e0
Docs: Update node.md with new configuration parameters and sections
Nov 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 53 additions & 39 deletions zq2/docs/nodes/checkpoints/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,72 +13,86 @@ You can find a list of checkpoints and hashes to download in the menu bar.

Before proceeding, ensure you have completed the [Node Setup](../nodes/node.md#setting-up-your-node) section.

For **mainnet**, you will need the `zq2-mainnet.toml` configuration file and the `start_node.sh` script, both generated during the setup process. Similarly, for **testnet** and **devnet**, you will use the `zq2-testnet.toml` and `zq2-devnet.toml` configuration file.
For **mainnet**, you will need the `zq2-mainnet.toml` configuration file and the `start_node.sh` script, both generated during the setup process. Similarly, for **testnet** and **devnet**, you will use the `zq2-testnet.toml` and `zq2-devnet.toml` configuration files.

The following steps apply to both networks.

### Step-by-Step Guide to Configure Checkpoints

1. **Ensure Proper Directory**
Navigate to the directory you created during the setup process, e.g., `/my/dir/zq2`.
1. **Ensure Proper Directory**
Navigate to the directory you created during the setup process, e.g., `/my/dir/zq2`.

2. **Download the Checkpoint File**
2. **Download the Checkpoint File**

Follow these steps to download the latest checkpoint file for your chosen network:
Follow these steps to download the latest checkpoint file for your chosen network:

- **Devnet**
Visit the public [checkpoint URL](https://checkpoints.zq2-devnet.zilliqa.com).
- **Devnet**:
Visit the public [checkpoint URL](https://checkpoints.zq2-devnet.zilliqa.com).

- **Testnet**:
Visit the public [checkpoint URL](https://checkpoints.testnet.zilliqa.com).
- **Testnet**:
Visit the public [checkpoint URL](https://checkpoints.testnet.zilliqa.com).

- **Mainnet**:
Visit the public [checkpoint URL](https://checkpoints.zilliqa.com).
- **Mainnet**:
Visit the public [checkpoint URL](https://checkpoints.zilliqa.com).

From the XML file at the respective URL:
From the XML file at the respective URL:

- Look for the `<key>` tag, which contains the checkpoint file's name. The file follows the `block_num.dat` format (e.g., `000291600.dat`).
- Look for the `<Key>` tag, which contains the checkpoint file's name. The file follows the `block_num.ckpt` format (e.g., `0000291600.ckpt`).

- Copy the file name of the latest checkpoint from the topmost `<key>` tag. For older checkpoints, explore the `previous/` directory.
- Copy the file name of the latest checkpoint from the topmost `<Key>` tag. For older checkpoints, explore the `previous/` directory.

- Download the checkpoint file using the `wget` command or paste the link in your browser:
- Download the checkpoint file using the `wget` command or paste the link in your browser:

```bash
wget https://checkpoints.zq2-<network>.zilliqa.com/<block_num.dat>
```
```bash
wget https://checkpoints.zq2-<network>.zilliqa.com/<block_num.ckpt>
```

Replace <network> with `mainnet`, `testnet` or `devnet` based on your selected network.
Replace `<network>` with `mainnet`, `testnet` or `devnet` based on your selected network.

_NOTE: Checkpoints are generated every 86400 blocks. The earliest checkpoint for the mainnet and testnet was generated at the switchover from Zilliqa 1. If the node does not need historical state it is recommended to use the latest checkpoint file to speed up synchronization. Keep in mind that the node can’t process RPC requests such as eth_getBalance on blocks that were produced before the checkpoint._
_NOTE: Checkpoints are generated every 86400 blocks. The earliest checkpoint for the mainnet and testnet was generated at the switchover from Zilliqa 1. If the node does not need historical state it is recommended to use the latest checkpoint file to speed up synchronization. Keep in mind that the node can’t process RPC requests such as eth_getBalance on blocks that were produced before the checkpoint._

3. **Configure Checkpoints in the Configuration File**
Open the respective configuration file (`zq2-mainnet.toml` or `zq2-testnet.toml`) and add the following lines to enable checkpoint settings:
```toml
[nodes.load_checkpoint]
file = "xxxxx..." # File name of the checkpoint block. for eg: 3000.dat
hash = "xxxxx..." # Block hash corresponding to the file block (Remove '0x' prefix from hash if present)
```
::: danger Incompatibility Warning
The new `.ckpt` checkpoint format is **incompatible** with the old `.dat` format.
If you have existing `.dat` checkpoints and need to use them, you must convert them to the new `.ckpt` format using the `scripts/convert-ckpt` utility provided in the Zilliqa repository.
:::

`file` : This parameter specifies the name of the checkpoint or block number file, which
can be obtained from the public GCS bucket. It’s recommended to download the latest checkpoint
file from this source.
### Checkpoint File Format

`hash` : The hash is used to verify the validity of the state data and ensure that no
tampering has occurred. You can obtain the block hash corresponding to the checkpoint height from the
public explorer of your chosen network. For example, if the downloaded
checkpoint file is 3000, you can use the `eth_getBlockByNumber` API to query the block hash:
The new checkpoint files are `ZIP64 archives` with a `.ckpt` extension. Each archive contains the following files:

- `metadata.json`: Contains metadata about the checkpoint, such as the block number and hash.
- `block.bincode`: Encoded block data.
- `parent.bincode`: Encoded parent block data.
- `transactions.bincode`: Encoded transaction data.
- `state.bincode`: Encoded state data.
- `history.bincode`: Encoded historical data.

3. **Configure Checkpoints in the Configuration File**

Open the respective configuration file (`zq2-mainnet.toml` or `zq2-testnet.toml`) and add the following lines to enable checkpoint settings:

```toml
[nodes.load_checkpoint]
file = "xxxxxx..." # File name of the checkpoint block. for eg: 3000.ckpt
hash = "xxxxxx..." # Block hash corresponding to the file block (Remove '0x' prefix from hash if present)
```

`file` : This parameter specifies the name of the checkpoint or block number file, which can be obtained from the public GCS bucket. It's recommended to download the latest checkpoint file from this source.

`hash` : The hash is used to verify the validity of the state data and ensure that no tampering has occurred. You can obtain the block hash corresponding to the checkpoint height from the public explorer of your chosen network. For example, if the downloaded checkpoint file is 3000.ckpt, you can use the `eth_getBlockByNumber` API to query the block hash:

```bash
curl --request POST --url https://api.zq2-mainnet.zilliqa.com/ \
--header 'Content-Type: application/json' \
--data '{"method":"eth_getBlockByNumber","params":["0xBB8",false],"id":1,"jsonrpc":"2.0"}' \
| grep -o '"hash":"[^"]*"' | awk -F':' '{print $2}' | tr -d '"'
```
Alternatively, you can retrieve the block hash directly from the public explorer of your chosen network by searching for the block number.
Refer to [block explorers](../endpoints.md#block-explorer) section for public explorer.
By this stage, your checkpoints settings should be specified in the configuration file.

4. **Launch the node**
Now the node is ready to launch. Follow the instructions in the [Start the Node](../nodes/node.md#starting-your-node) section to start your node.
Alternatively, you can retrieve the block hash directly from the public explorer of your chosen network by searching for the block number.
Refer to [block explorers](../endpoints.md#block-explorers) section for public explorer.
By this stage, your checkpoints settings should be specified in the configuration file.

4. **Launch the node**
Now the node is ready to launch. Follow the instructions in the [Start the Node](../nodes/node.md#starting-your-node) section to start your node.

**Note**: After starting a node from a checkpoint for the first time it typically takes approximately 1.5 hours to start syncing. During this time the node won’t respond to RPC requests. Please allow sufficient time for the process to complete.
Loading
Loading