September 11, 2021

Nervos: Running your own Testnet Node

Key Points

When developing Dapps and smart contracts it is useful to have a test environment similar to the real blockchain without having to deal with real balances (and real loss of money if something goes wrong). We have two options:

Running a Dev Node: A dummy workers blockchain that runs fully local where you are the only miner. It is useful when you need fast contracts deployments or when you have to wait for a lot of blocks to be mined for your test, you can generate blocks at a configurable fixed rate. Also, there is no need to sync the node, having a fully functional node almost immediately. But if you want to test your developments on a decentralized blockchain that looks more like the real one you will want to try the next option.
Running a Testnet Node: Nervos Foundation launched Aggron Testnet where you can test your applications in a real decentralized blockchain with nodes and miners all over the world. It makes it possible to deploy smart contracts and test their integration as if they were in the real Nervos blockchain.

We will go throw the steps of setting up a Dev and a Testnet Node, funding a Testnet wallet with the faucet, and using the ckb-cli to interact with our node.

Setting up ckb and ckb-cli binaries

Before running any node we need to download the binaries for ckb and ckb-cli, from nervosnetwork GitHub page: Releases. To verify that the binaries are working you can run these commands from the folder the files were extracted to:

<pre><code>./ckb --version
./ckb-cli --version</code></pre>

You should get something like this:

Running a Testnet Node

To run the Testnet node we have to initialize its configuration first, to do this run the following command:

<pre><code>./ckb init --chain testnet</code></pre>

We should get a result similar to:

<pre><code>WARN: mining feature is disabled because of lacking the block assembler config optionsInitialized CKB directory in /PATH/ckb_v0.43.2create ckb.tomlcreate ckb-miner.tomlcreate default.db-optionsGenesis Hash: 0x10639e0895502b5688a6be8cf69460d76541bfa4821629d86d62ba0aae3f9606</code></pre>

The files created can be modified before running the node to customize its behavior, but it's recommended to use the default configuration unless you have specific needs.

Now we are ready to run our node:

The node should be running and syncing with the blockchain. To be able to use our node correctly we need to wait until the node has synchronized, for this is possible to compare the current block in our node with the last block in the blockchain from the Aggron Testnet explorer. When the block last block in our node is equal to the latest block in the explorer we are good to go.

To speed up the syncing process there are snapshots of the Testnet available with instruction on how to use them in CKBtools.

Creating a Testnet wallet

A new address for the Testnet blockchain can be generated using this Tool. Remember to store your private key if you want to spend your CKBs in the future.

Funding your wallet with the Faucet

On the Testnet you can claim free CKBs to test your applications. You can claim 10,000 CKB every 24 hours by putting your address in the following Faucet.

Checking the balance on our Node

The cbk-cli can be used to check our recently claimed CKBs. For this just run the following command:

<pre><code>./ckb-cli wallet get-capacity --address <YOUR_ADDRESS></code></pre>

You get a response like this:

<pre><code>total: 10000.00 (CKB)</code></pre>

And now you are ready to start expending your CKB on the Testnet.

Running a Dev node

To initialize a dev node run the following command:

<pre><code>./ckb init --chain dev</code></pre>

This will return a very similar output to the one for the Testnet command, but with one new file, specs/dev.toml that can be used to configure the dummy blocks generation:

<pre><code>WARN: mining feature is disabled because of lacking the block assembler config optionsInitialized CKB directory in /PATH/ckb_v0.43.2create specs/dev.tomlcreate ckb.tomlcreate ckb-miner.tomlcreate default.db-optionsGenesis Hash: 0x8d08926b0b0640aa240272647841f56a0bd183683d955406f3e91c159c4cb1c6</code></pre>

We will be the only miner on this blockchain, so we need to set up a mining account to receive the rewards. To create this new account we use de ckb-cli:

<pre><code>./ckb-cli account new</code></pre>

We need to provide a password for this account and we get the addresses for Testnet and Mainnet, and other info we will need to set up the node:

<pre><code>Your new account is locked with a password.
Please give a password.
Do not forget this password.
Password:
Repeat password:
address:
mainnet: ckb1qyqxg5che4q0tu88pt9t6ftjkqfcs8f3ml9se7njjx
testnet: ckt1qyqxg5che4q0tu88pt9t6ftjkqfcs8f3ml9symdd76
lock_arg: 0x645317cd40f5f0e70acabd2572b013881d31dfc
block_hash: 0x461c5201302b3b2084a8ae76f09e4766ef87e6d88cb88b48751b5fba30ceda78</code></pre>

Update the args and message under [block assembler] block in ckb.toml file to use your lock_arg (remember to uncomment these lines):

<pre><code>[block_assembler]code_hash = "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8"
args = "0x645317cd40f5f0e70acabd2572b013881d31dfcb"
hash_type = "type"
message = "0x"</code></pre>

Now we are ready to start the dev node:

The node should start running and keep waiting for new blocks to be mined, but we won’t have new blocks until we start our miner. To start the miner just run the following command in a separate terminal:

<pre><code>./ckb miner</code></pre>

The miner should start and we should see the mined blocks on both: the node and the miner processes:

<pre><code>./ckb miner2021-09-08 19:34:32.256 +02:00 main INFO sentry sentry is disabled2021-09-08 19:34:32.256 +02:00 main INFO ckb_bin::helper raise_fd_limit newly-increased limit: 10485762021-09-08 19:34:32.257 +02:00 main INFO ckb_memory_tracker::process track current process: disableFound! #1 0x0ba5ca4c5c23589ca92c64a8d87f27a26c9133a1844150e0d0d8201edc3beb12Found! #2 0x8e844405f7584fac5953d53f1ab63db388c4bc2ab1a2a2d04103bfb62945b707Found! #3 0x57d9b5e841a7ab1410d34dc3cef8c68ecf215a538d073e4686db0ebfd441e1bfFound! #4 0x8c25f37c7f902c1e9110185156beaf746b0ac7dee79b2edb368967518175c1f2Dummy-Worker ⠁ [00:00:00]
Total nonces found: 4</code></pre>

Now our dev node is ready to start receiving requests! But as this is a local blockchain with only one node (ours), we cannot use the faucet to get free CKB on our wallet, luckily we can get these new CKBs from our miner that is constantly getting the rewards from the mined blocks. The miner's balance will keep increasing with every new block, to check its balance we can again use the ckb-cli:

<pre><code>./ckb-cli wallet get-capacity --address <MINER_ADDRESS></code></pre>

We can use this miner balance to transfer funds to other addresses we want to test, for example, we can use the ckb-cli to create a new account and transfer some CKB to it:

<pre><code>./ckb-cli account new
./ckb-cli wallet transfer --from-account <MINER_ADDRESS> --to-address <NEW_ACCOUNT_ADDRESS> --capacity 10000 --tx-fee 0.00001</code></pre>

We should have now balance in the new account to run our tests.

If you followed these steps you now have a Testnet (or dev) node up and running to dive into the Nervos developing experience. Next articles will cover some layer 1 and layer 2 developing examples that we can deploy and test on our own nodes before going into production.

Thanks to Guido Giuntoli and Federico Caccia