Skip to content

Latest commit

 

History

History
772 lines (588 loc) · 20.8 KB

run-devnet-node.mdx

File metadata and controls

772 lines (588 loc) · 20.8 KB
id title
run-devnet-node
Run a Devnet Node

import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem";

Run a Devnet Node

The CKB Devnet is designed for fast, local development. It offers a lightweight, isolated environment for building and testing your dApps without syncing the full chain or affecting real networks. 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

Quick Start with OffCKB

You can run a Devnet node by installing @offckb/cli. It provides a one-line command to start a Devnet.

Install

npm install -g @offckb/cli

Start the Devnet

offckb node # start the Devnet of CKB, `ctrl-c` to stop running the chain

Custom Devnet Setup

While OffCKB offers a streamlined, one-line command to quickly start a Devnet, you may find the need for a more nuanced configuration.

For those requiring deeper customization, Nervos CKB's development mode is highly configurable, supporting both Dummy-Worker for constant block intervals without Proof-of-Work (PoW) and Eaglesong-Worker for real PoW block production. This flexibility allows you to tailor the local blockchain setup using CKB binary on your computer, speeding up block intervals, adjusting epoch lengths, and creating blocks to suit your testing and development needs.

:::tip It is highly recommended to use Dummy-Worker for most development scenarios. Eaglesong-Worker should only be used when validating the PoW function is necessary, because the block time can behave erratically with extremely low hashrates. :::

Download the CKB Binary

Download the latest version of CKB from the official GitHub Releases page. Make sure to download the correct version for your operating system.

:::info This guide uses version ckb_v0.115.0 as an example. :::

Navigate to the CKB Directory

Unzip the downloaded archive into a location that's easy to find. We recommend:

  • MacOS: ~/Documents/ckb_v0.115.0/...
  • Windows: C:\ckb_v0.115.0\...
<Tabs>
  <TabItem value="mac" label="Mac">

Open a terminal and navigate into the folder using the following command:

cd /Users/(NAME)/Documents/ckb_v0.115.0_aarch64-apple-darwin-portable/ckb

Remember to replace “(NAME)” with your actual name on the device.

  </TabItem>
  <TabItem value="windows" label="Windows">

Open a command prompt and navigate into the folder using the following command:

cd C:/ckb_v0.115.0_x86_64-pc-windows-msvc
  </TabItem>
</Tabs>

Verify Installed Versions

Run the following commands:

<Tabs>
  <TabItem value="mac" label="Mac">

./ckb --version
./ckb-cli --version

Notice for Unix-like systems, you need to explicitly use ./ to tell the shell to run ckb file in the current folder.

You should see the installed version printed in the terminal, like this:

ckb 0.115.0 (d845cbf 2024-04-01)
ckb-cli 1.8.0-rc1 (cf4159b 2024-03-28)

:::note If you see a message like 'ckb' cannot be opened because the developer cannot be verified, this is macOS blocking unsigned binaries. To bypass:

  1. Go to System Settings → Privacy & Security
  2. Scroll down and click “Open Anyway”
  3. Rerun the command :::
  </TabItem>
  <TabItem value="windows" label="Windows">

ckb --version
ckb-cli --version

You should see the installed version printed in the terminal, like this:

ckb 0.115.0 (d845cbf 2024-04-01)
ckb-cli 1.8.0-rc1 (cf4159b 2024-03-28)
  </TabItem>
</Tabs>

Dummy-Worker Setup

1. Initialize

Use the following command to initialize the development blockchain and generate the required configuration files:

<Tabs>
  <TabItem value="initialize" label="Command">

ckb init --chain dev

If you're using a Unix-like system, run ./ckb init --chain dev instead.

  </TabItem>
  <TabItem value="after-initialize" label="Response">

WARN: mining feature is disabled because of lacking the block assembler config options
Initialized CKB directory in  /PATH/ckb_v0.115.0-rc2_x86_64-unknown-linux-gnu
create specs/dev.toml
create ckb.toml
create ckb-miner.toml
create default.db-options
Genesis Hash: 0x180621a13efd899730abfb3dd7aaa82f4b61ac9ed5283fe73b47b0f4c4196757
  </TabItem>
</Tabs>

2. Config Block Assembler

The Block Assembler configuration specifies which address should receive block rewards for mining.

2a. Create Account

To receive the block rewards, you'll need to generate an address. This can be accomplished using the ckb-cli tool.

Note: Be sure to record the lock_arg value in the response which we will use in the next step.
<Tabs>
  <TabItem value="create-new-account" label="Command">

ckb-cli account new

If you're using a Unix-like system, run ./ckb-cli account new instead.

  </TabItem>
  <TabItem value="account-created" label="Response">

Your new account is locked with a password. Please give a password. Do not forget this password.
Password:
Repeat password:
address:
  mainnet: ckb1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqghklqs0vttylku4pjxhr8hxsaratn8muc28r7vu
  testnet: ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqghklqs0vttylku4pjxhr8hxsaratn8mucy4g3xy
address(deprecated):
  mainnet: ckb1qyqp0d7pq7ckkflde2rydwx0wdp686hx0hesvfqn3l
  testnet: ckt1qyqp0d7pq7ckkflde2rydwx0wdp686hx0hes3v7var
lock_arg: 0x17b7c107b16b27edca8646b8cf7343a3eae67df3
lock_hash: 0x9fecea1600fecfac989b2d15dc227b885afe68f5b652a1a159b59cb69e83ddae
  </TabItem>
</Tabs>

2b. Update Config

Modify the args and message parameters in the ckb.toml file under the block_assembler section:

[block_assembler]
code_hash = "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8" # Do not change this.
args = "0x8d627decece439977a3a0a97815b63debaff2874" # Change this to your lock_arg value.
hash_type = "type" # Do not change this.
message = "A 0x-prefixed hex string" # Change this to "0x" to supply an empty message.

3. Shorten Block Interval (Optional)

For most development, the default configuration should be sufficient, but sometimes speeding up certain operations is beneficial so results can be viewed quickly.

3a. Adjust Epoch

The default epoch length is 1000 blocks. Reducing this to 10 or 100 can help with testing Nervos DAO operations.

Modify the genesis_epoch_length parameter in the specs/dev.toml file under the params section:

[params]
genesis_epoch_length = 1000  # The unit of meansurement is "block".

3b. Set Permanent Difficulty

When permanent_difficulty_in_dummy is set to true, all epochs will use the same length as the genesis epoch length, skipping the difficulty adjustment entirely. This param is typically used in conjunction with genesis_epoch_length.

Modify the permanent_difficulty_in_dummy parameter in the specs/dev.toml file under the params section:

[params]
genesis_epoch_length = 10
permanent_difficulty_in_dummy = true

3c. Adjust Mining Interval

The default mining interval is 5000, which is a value in milliseconds, meaning 5 seconds. Reducing this value will result in blocks being created faster.

Modify the value parameter in the ckb-miner.toml file under the miner.workers section:

[[miner.workers]]
worker_type = "Dummy"
delay_type = "Constant"
value = 5000  # The unit of measurement is "ms".

4. Start the Node

<Tabs>
  <TabItem value="run-node" label="Command">

ckb run

If you're using a Unix-like system, run ./ckb run instead.

  </TabItem>
  <TabItem value="node-running" label="Response">

2020-06-05 18:31:14.970 +08:00 main INFO sentry  sentry is disabled
2020-06-05 18:31:15.058 +08:00 main INFO ckb-db  Initialize a new database
2020-06-05 18:31:15.136 +08:00 main INFO ckb-db  Init database version 20191127135521
2020-06-05 18:31:15.162 +08:00 main INFO ckb-memory-tracker  track current process: unsupported
2020-06-05 18:31:15.164 +08:00 main INFO main  ckb version: 0.32.1 (9ebc9ce 2020-05-29)
2020-06-05 18:31:15.164 +08:00 main INFO main  chain genesis hash: 0x823b2ff5785b12da8b1363cac9a5cbe566d8b715a4311441b119c39a0367488c
2020-06-05 18:31:15.166 +08:00 main INFO ckb-network  Generate random key
2020-06-05 18:31:15.166 +08:00 main INFO ckb-network  write random secret key to "/PATH/ckb_v0.32.1_x86_64-apple-darwin/data/network/secret_key"
2020-06-05 18:31:15.177 +08:00 NetworkRuntime INFO ckb-network  p2p service event: ListenStarted { address: "/ip4/0.0.0.0/tcp/8115" }
2020-06-05 18:31:15.179 +08:00 NetworkRuntime INFO ckb-network  Listen on address: /ip4/0.0.0.0/tcp/8115/p2p/QmSHk4EucevEuX76Q44hEdYpRxr3gyDmbKtnMQ4kxGaJ6m
2020-06-05 18:31:15.185 +08:00 main INFO ckb-db  Initialize a new database
2020-06-05 18:31:15.211 +08:00 main INFO ckb-db  Init database version 20191201091330
2020-06-05 18:31:26.586 +08:00 ChainService INFO ckb-chain  block: 1, hash: 0x47995f78e95202d2c85ce11bce2ee16d131a57d871f7d93cd4c90ad2a8220bd1, epoch: 0(1/1000), total_diff: 0x200, txs: 1
  </TabItem>
</Tabs>

5. Start CKB Miner

Open another teriminal window and run the following commands:

<Tabs>
  <TabItem value="start-miner" label="Command">

ckb miner

If you're using a Unix-like system, run ./ckb miner instead.

  </TabItem>
  <TabItem value="mining" label="Response">

2020-06-05 18:31:21.558 +08:00 main INFO sentry  sentry is disabled
Dummy-Worker ⠁ [00:00:00]
Found! #1 0x47995f78e95202d2c85ce11bce2ee16d131a57d871f7d93cd4c90ad2a8220bd1
Found! #2 0x19978085abfa6204471d42bfb279eac0c20e3b81745b48c4dcaea85643e301f9
Found! #3 0x625b230f84cb92bcd9cb0bf76d1397c1d948ab25c19df3c4edc246a765f94427
Found! #4 0x4550fb3b62d9d5ba4d3926db6704b25b90438cfb67037d253ceceb2d86ffdbf7
  </TabItem>
</Tabs>

Eaglesong-Worker Setup

1. Create Account

An address to receive the block rewards must be created using ckb-cli.

Note: Be sure to record the lock_arg value from the response, as it will be used in the next step.
<Tabs>
  <TabItem value="check-ckb-binary-version" label="Command">

ckb-cli account new

If you're using a Unix-like system, run ./ckb-cli account new instead.

  </TabItem>
  <TabItem value="show-ckb-binary-version" label="Response">

ckb-cli account new
Your new account is locked with a password. Please give a password. Do not forget this password.
Password:
Repeat password:
address:
  mainnet: ckb1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqghklqs0vttylku4pjxhr8hxsaratn8muc28r7vu
  testnet: ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqghklqs0vttylku4pjxhr8hxsaratn8mucy4g3xy
address(deprecated):
  mainnet: ckb1qyqp0d7pq7ckkflde2rydwx0wdp686hx0hesvfqn3l
  testnet: ckt1qyqp0d7pq7ckkflde2rydwx0wdp686hx0hes3v7var
lock_arg: 0x17b7c107b16b27edca8646b8cf7343a3eae67df3
lock_hash: 0x9fecea1600fecfac989b2d15dc227b885afe68f5b652a1a159b59cb69e83ddae
  </TabItem>
</Tabs>

2. Initialize Miner

<Tabs>
  <TabItem value="initialize-miner" label="Command">

ckb init -c dev --ba-arg 0x41ecee7b8fc0783c75da1f4346009b2e5a774a96 // Change this to your lock_arg value.

If you're using a Unix-like system, run ./ckb int -c dev --ba-arg instead.

  </TabItem>
  <TabItem value="mining-initialized" label="Response">

Initialized CKB directory in /PATH/ckb_v0.32.1_x86_64-apple-darwin
create specs/dev.toml
create ckb.toml
create ckb-miner.toml
  </TabItem>
</Tabs>

3. Change PoW Function

Modify the func parameter in the specs/dev.toml file under the pow section:

func = "Eaglesong"

Replace the miner.workers section in the ckb-miner.toml file with the following:

[[miner.workers]]
worker_type = "EaglesongSimple"
threads = 1

4. Start the Node

<Tabs>
  <TabItem value="run-node" label="Command">

ckb run

If you're using a Unix-like system, run ./ckb run instead.

  </TabItem>
  <TabItem value="node-running" label="Response">

2020-06-05 11:25:31.433 +08:00 main INFO sentry  sentry is disabled
2020-06-05 11:25:31.508 +08:00 main INFO ckb-db  Initialize a new database
2020-06-05 11:25:31.590 +08:00 main INFO ckb-db  Init database version 20191127135521
2020-06-05 11:25:31.604 +08:00 main INFO ckb-memory-tracker  track current process: unsupported
2020-06-05 11:25:31.604 +08:00 main INFO main  ckb version: 0.32.1 (9ebc9ce 2020-05-29)
2020-06-05 11:25:31.604 +08:00 main INFO main  chain genesis hash: 0x823b2ff5785b12da8b1363cac9a5cbe566d8b715a4311441b119c39a0367488c
2020-06-05 11:25:31.604 +08:00 main INFO ckb-network  Generate random key
2020-06-05 11:25:31.604 +08:00 main INFO ckb-network  write random secret key to "/PATH/ckb_v0.32.1_x86_64-apple-darwin/data/network/secret_key"
2020-06-05 11:25:31.608 +08:00 NetworkRuntime INFO ckb-network  p2p service event: ListenStarted { address: "/ip4/0.0.0.0/tcp/8115" }
2020-06-05 11:25:31.610 +08:00 NetworkRuntime INFO ckb-network  Listen on address: /ip4/0.0.0.0/tcp/8115/p2p/QmcCGH7VeXbpV4jj7VgSEM7NANuud6TmGHV2DXPsSVrRkR
2020-06-05 11:25:31.612 +08:00 main INFO ckb-db  Initialize a new database
2020-06-05 11:25:31.638 +08:00 main INFO ckb-db  Init database version 20191201091330
  </TabItem>
</Tabs>

5. Start CKB Miner

This should be performed in a separate terminal.

<Tabs>
  <TabItem value="start-mining" label="Command">

ckb miner

If you're using a Unix-like system, run ./ckb miner instead.

  </TabItem>
  <TabItem value="mining" label="Response">

2020-06-05 11:25:37.867 +08:00 main INFO sentry  sentry is disabled
EaglesongSimple-Worker-0 ⠁ [00:00:00]
2020-06-05 11:25:37.870 +08:00 main INFO ckb-memory-tracker  track current proceFound! #1 0x57e6ad0f15bacc4f30e53811d488d895e6619c17222981eca5484f0115f84acd
Found! #2 0xe5831f39f928dca599a02e490c482a881ccdc47a2376371dec4e440e363fa5c0
Found! #3 0x605b3e6449954c2daa996c06b2412bbf60b8231763149742119fb623f9de27b2
Found! #4 0x64064e7257ea4589e8cb177cf119c68ab1b4559de005a20dc13ef3d42949e04b
  </TabItem>
</Tabs>

Transfer CKBytes Using ckb-cli

Included in CKB releases is the ckb-cli command-line tool, which can be used to directly invoke RPC calls for actions such as managing accounts, transferring CKBytes, and checking account balances. Below, we will demonstrate a CKBytes transfer. Please refer to ckb-cli for full instructions.

:::caution Using ckb-cli to transfer CKBytes is recommended only for development and testing purposes. For managing real funds and assets, please use a wallet. :::

1. Access ckb-cli

<Tabs>
  <TabItem value="access-ckb-cli" label="Command">

ckb-cli

If you're using a Unix-like system, run ./ckb-cli instead.

  </TabItem>
  <TabItem value="ckb-cli-accessed" label="Response">

[  ckb-cli version ]: 1.7.0 (0c8711e 2024-02-29)
[              url ]: http://127.0.0.1:8114/ (network: Dev, loading...)
[              pwd ]: /home/ckb/xueyl/ckb/ckb_v0.115.0-rc2_x86_64-unknown-linux-gnu
[            color ]: true
[            debug ]: false
[          no-sync ]: false
[    output format ]: yaml
[ completion style ]: List
[       edit style ]: Emacs
No previous history.
CKB>
  </TabItem>
</Tabs>

2. Create Account

<Tabs>
  <TabItem value="create-account" label="Command">

account new
  </TabItem>
  <TabItem value="account-created" label="Response">

$ ckb-cli account new
Your new account is locked with a password. Please give a password. Do not forget this password.
Password:
Repeat password:
address:
  mainnet: ckb1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqghklqs0vttylku4pjxhr8hxsaratn8muc28r7vu
  testnet: ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqghklqs0vttylku4pjxhr8hxsaratn8mucy4g3xy
address(deprecated):
  mainnet: ckb1qyqp0d7pq7ckkflde2rydwx0wdp686hx0hesvfqn3l
  testnet: ckt1qyqp0d7pq7ckkflde2rydwx0wdp686hx0hes3v7var
lock_arg: 0x17b7c107b16b27edca8646b8cf7343a3eae67df3
lock_hash: 0x9fecea1600fecfac989b2d15dc227b885afe68f5b652a1a159b59cb69e83ddae
  </TabItem>
</Tabs>

3. Check Balance

In the previous sections, you created a miner account that collects all mining rewards. Using the following command with the correct address will show you the current CKByte balance:

<Tabs>
  <TabItem value="check-balance" label="Command">

wallet get-capacity --address "miner's address"
  </TabItem>
  <TabItem value="balance-result" label="Response">

CKB> wallet get-capacity --address "ckt1qyqg6cnaankwgwvh0gaq49uptd3aawhl9p6qpg5cus"
immature: 8027902.89083717 (CKB)
total: 46253677.72927512 (CKB)
  </TabItem>
</Tabs>

4. Transfer CKBytes

<Tabs>
  <TabItem value="transfer-ckb" label="Command">

wallet transfer --from-account "miner's address" --to-address "new account's address" --capacity 10000 --tx-fee 0.00001
  </TabItem>
  <TabItem value="ckb-transferred" label="Response">

CKB> wallet transfer --from-account ckt1qyqg6cnaankwgwvh0gaq49uptd3aawhl9p6qpg5cus --to-address ckt1qyq0g9p6nxf5cdy38fm35zech5f90jl5aueqnsxch5 --capacity 10000 --max-tx-fee 0.00001
Password:
0x1b66aafaaba5ce34de494f60374ef78e8f536bb3af9cab4fa63c0f29374c3f89
  </TabItem>
</Tabs>

5. Verify Balance

<Tabs>
  <TabItem value="verify-balance" label="Command">

wallet get-capacity --address "new account's address"
  </TabItem>
  <TabItem value="balance-displayed" label="Response">

CKB> wallet get-capacity --address ckt1qyq0g9p6nxf5cdy38fm35zech5f90jl5aueqnsxch5
total: 10000.0 (CKB)
  </TabItem>
</Tabs>

The transfer is successful!

Add the Genesis Issued Cells

When the development blockchain configuration is generated with ckb init --chain dev, a few Cells are created with large capacities. These are specified in specs/dev.toml and exist only on your local development blockchain, making them useful for testing purposes.

Genesis Issued Cell #1
Private Key 0xd00c06bfd800d27397002dca6fb0993d5ba6399b4238b2f29ee9deb97593d2bc
Lock Arg 0xc8328aabcd9b9e8e64fbc566c4385c3bdeb219d7
Testnet Address ckt1qyqvsv5240xeh85wvnau2eky8pwrhh4jr8ts8vyj37
Capcity 20,000,000,000 CKBytes
Genesis Issued Cell #2
Private Key 0x63d86723e08f0f813a36ce6aa123bb2289d90680ae1e99d4de8cdb334553f24d
Lock Arg 0x470dcdc5e44064909650113a274b3b36aecb6dc7
Testnet Address ckt1qyqywrwdchjyqeysjegpzw38fvandtktdhrs0zaxl4
Capcity 5,198,735,037 CKBytes

1. Add Private Keys to File

Private keys must be added to a text file before they can be used.

echo 0xd00c06bfd800d27397002dca6fb0993d5ba6399b4238b2f29ee9deb97593d2bc > pk1
echo 0x63d86723e08f0f813a36ce6aa123bb2289d90680ae1e99d4de8cdb334553f24d > pk2

2. Import Private Keys

Import the private key files using ckb-cli:

<Tabs>
  <TabItem value="import-privkey" label="Command">

CKB> account import --privkey-path pk1
CKB> account import --privkey-path pk2
  </TabItem>
  <TabItem value="privkey-result" label="Response">

$ ckb-cli account import --privkey-path  pk1
Password:
address:
  mainnet: ckb1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqvgswj39m3rs0qp2a9r9rmqamxtkntcysq007jd8
  testnet: ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqvgswj39m3rs0qp2a9r9rmqamxtkntcysqpa4a8l
address(deprecated):
  mainnet: ckb1qyqg3qa9zthz8q7qz462x28kpmkvhdxhsfqqjavu23
  testnet: ckt1qyqg3qa9zthz8q7qz462x28kpmkvhdxhsfqq0cjrxd
lock_arg: 0x8883a512ee2383c01574a328f60eeccbb4d78240
  </TabItem>
</Tabs>