Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion .autopilot/last_ckb_release.txt
Original file line number Diff line number Diff line change
@@ -1 +1 @@
v0.207.0
v0.208.0-rc0
101 changes: 101 additions & 0 deletions website/docs/node/devnet-from-existing-data.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
---
id: devnet-from-existing-data
title: Devnet From Existing Data
---

# Devnet From Existing Data

This guide explains how to run a local `dev` chain using an existing Mainnet or Testnet data directory. This setup is useful when you want local testing with real chain data without syncing from scratch.

:::caution
Always work on a copy of the data directory. Never modify your original Mainnet or Testnet data directly.
:::

## 1. Copy the Existing Data Directory

Copy the source data directory to a new location for the dev chain:

```bash
cp -r /path/to/ckb-data /path/to/ckb-dev-fork
cd /path/to/ckb-dev-fork
```

All commands below assume the current directory is the copied directory.

## 2. Get the Source Chain Spec File

Download the chain spec file that matches your copied data:

- Mainnet: `https://github.com/nervosnetwork/ckb/blob/develop/resource/specs/mainnet.toml`
- Testnet: `https://github.com/nervosnetwork/ckb/blob/develop/resource/specs/testnet.toml`

For example, for Mainnet:

```bash
curl -L -o mainnet.toml \
https://raw.githubusercontent.com/nervosnetwork/ckb/develop/resource/specs/mainnet.toml
```

## 3. Initialize the Dev Chain and Import the Source Spec

```bash
ckb init --chain dev --import-spec ./mainnet.toml --force
```

If you copied Testnet data, replace `mainnet.toml` with `testnet.toml`.

## 4. Update `specs/dev.toml`

Set `Dummy` Proof-of-Work for local development. The `[params]` section differs between Mainnet and Testnet — use the matching block below.

:::note
`genesis_epoch_length` (together with the epoch reward fields) participates in the genesis cellbase reward calculation, which determines the genesis block hash. If the value here does not match the value the source chain was launched with, the node will refuse to start with `chainspec error: ChainSpec: genesis hash mismatch`.
:::

### Mainnet

Mainnet was launched with `genesis_epoch_length = 1743`, so this value must be preserved:

```toml
[params]
genesis_epoch_length = 1743
cellbase_maturity = 0
permanent_difficulty_in_dummy = true

[pow]
func = "Dummy"
```

### Testnet

The bundled Testnet spec has no `[params]` section and was launched with the default `genesis_epoch_length = 1000`. Do **not** add `genesis_epoch_length` here — leaving it unset lets it fall back to the default and keeps the genesis hash consistent:

```toml
[params]
cellbase_maturity = 0
permanent_difficulty_in_dummy = true

[pow]
func = "Dummy"
```

- `cellbase_maturity = 0` makes locally mined cellbase outputs immediately spendable, which is convenient for development.
- `permanent_difficulty_in_dummy = true` keeps the difficulty constant when running with `Dummy` PoW. Its default is `false`, which would let difficulty be recalculated from the dummy block timestamps and swing wildly once you start mining locally; the bundled `resource/specs/dev.toml` therefore enables it by default and the same is recommended here.

## 5. First Run Requires Spec-Check Flags

The copied database still records the original chain spec hash, so the first startup must include:

```bash
ckb run --skip-spec-check --overwrite-spec
```

After the first successful run, `ckb run` can be used normally.

## Troubleshooting

If you see a log like `init_snapshot Spec(GenesisMismatch(...))`, the running spec and database spec do not match. Ensure:

1. You imported the correct source chain spec.
2. The first run uses `--skip-spec-check --overwrite-spec`.
3. You are operating in the copied data directory, not the original one.
4 changes: 4 additions & 0 deletions website/docs/node/run-devnet-node.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@ This guide covers two ways to run a Devnet node:
- A quickstart using OffCKB, a tool that simplifies the process by running everything you need out of the box
- A manual setup using the CKB binary, similar to running a Mainnet or Testnet node

:::tip
If you want to run a local dev chain that starts from existing Mainnet or Testnet data instead of a fresh genesis block, see [Devnet From Existing Data](/docs/node/devnet-from-existing-data).
:::

## Quick Start with OffCKB

You can run a Devnet node by installing [@offckb/cli](https://www.npmjs.com/package/@offckb/cli). It provides a one-line command to start a Devnet.
Expand Down
1 change: 1 addition & 0 deletions website/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -498,6 +498,7 @@ export default {
"node/run-mainnet-node",
"node/run-testnet-node",
"node/run-devnet-node",
"node/devnet-from-existing-data",
"node/run-node-docker",
"node/run-node-over-tor",
],
Expand Down
Loading