Skip to main content

Dev Environment

For developers, a dev environment is the most important place to start their little side projects with blockchain on weekends.

Here we have provide different ways to setup your CKB dev environment to start your journey.

Quick Setup with OffCKB​

You can set up your local development environment by installing @offckb/cli. It provides a one-line command to start a Devnet, pre-funded test accounts and useful Scripts like Omnilock and Spore-contract.

Install​

npm install -g @offckb/cli

Usage​

offckb node # start the Devnet of CKB, `ctrl-c` to stop running the chain 
offckb clean # clean the Devnet data, needs to stop running the chain first  
offckb init <project-name> # init a CKB dApp typescript boilerplate from multiple templates  
offckb accounts # list 20 accounts info with prefund CKB tokens 
offckb list-hashes # list built-in scripts hashes, equals `ckb list-hashes`

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 CKB Binary​

Download the latest ckb binary file from the CKB releases page on GitHub.

The following commands can be used to verify the binaries are working and to check versions:

ckb --version
ckb-cli --version

Dummy-Worker Setup​

1. Initialize​

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

ckb init --chain dev

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.​
ckb-cli account new

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 CKB Node​

ckb run

5. Start CKB Miner​

This should be performed in a separate terminal.

ckb miner

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.​
$ ckb-cli account new

2. Initialize Miner​

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

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 CKB Node​

ckb run

5. Start CKB Miner​

This should be performed in a separate terminal.

ckb miner

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​

ckb-cli

2. Create Account​

account new

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:

wallet get-capacity --address "miner's address"

4. Transfer CKBytes​

wallet transfer --from-account "miner's address" --to-address "new account's address" --capacity 10000 --tx-fee 0.00001

5. Verify Balance​

wallet get-capacity --address "new account's address"

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 Key0xd00c06bfd800d27397002dca6fb0993d5ba6399b4238b2f29ee9deb97593d2bc
Lock Arg0xc8328aabcd9b9e8e64fbc566c4385c3bdeb219d7
Testnet Addressckt1qyqvsv5240xeh85wvnau2eky8pwrhh4jr8ts8vyj37
Capcity20,000,000,000 CKBytes
Genesis Issued Cell #2
Private Key0x63d86723e08f0f813a36ce6aa123bb2289d90680ae1e99d4de8cdb334553f24d
Lock Arg0x470dcdc5e44064909650113a274b3b36aecb6dc7
Testnet Addressckt1qyqywrwdchjyqeysjegpzw38fvandtktdhrs0zaxl4
Capcity5,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:

CKB> account import --privkey-path pk1
CKB> account import --privkey-path pk2