Skip to main content

Nervos CKB Mainnet - Integration Guide

Connecting to the CKB network is extremely easy and only requires running one node on a machine. Once you've connected to the CKB network, you can use the RPC interface to interacting with the node.

About Nervos CKB​

CKB is the layer 1 of Nervos Network, a public/permissionless blockchain. CKB uses Proof of Work and improved Nakamoto consensus to achieve maximized performance on average hardware and internet conditions without sacrificing decentralization and security, which are the core values of blockchain.

Run A CKB Node​

You’ll need to deploy nodes to connect with the CKB network, read data from the blockchain, and broadcast transactions onto the CKB network. For more information, please see Run CKB With The Latest Release or Run CKB With Docker. You may also need an indexer to index live cells and transactions, and then you can try CKB Indexer. If you are looking for a one-stop solution that includes both node and indexer, you can try Perkins' Tent.

Server Requirements​

  • OS: Ubuntu 18.04 LTS x86_64 (recommended)
  • Processor: Mainstream CPU 4c
  • RAM: 4G
  • Storage: 100G SSD

A Checklist for Integration​

Before starting your integration, we recommend reading CKB Transaction Structure RFC to familiarize yourself with an essential data structure in CKB. Some common issues and corresponding example solutions (using CKB SDK Java) are listed below.

Generating and Parsing Address​

CKB Address Format is an application-level recommendation for cell lock script display. The lock script consists of three key parameters, including code_hash, hash_type, and args. CKB address packages lock script into a single line, verifiable, and human read friendly format.

Transferring CKB​

The transmission of CKB between addresses is divided into three steps, constructing, signing, and submitting the transaction. You can use the following example to understand how to transfer CKB between addresses SingleSigWithCkbIndexerTxExample and TransferAllBalanceWithCkbIndexerExample. If you want to know the signing process, you can check How to sign the transaction. For the calculation of transaction fees, please see the Transaction Fee.

For withdrawal, need to support both transfers to Short Payload Format Address and transfers to Full Payload Format.

Retrieving data from node​

You can make a JSON-RPC request to your CKB node with the SDK. There are some CKB SDK Java examples: JSON-RPC Example. Commonly used RPC interfaces are

How to manage cells(like UTXO set)​

Cell management mainly affects cell collection and address balance display. There are many ways to manage cells; Here are two typical example solutions.

  • Recommended: use CKB indexer to collect cells and display balance. Recommend using built-in version available since v0.106.0, standalone version is also available.
    • get_cells_capacity Returns the live cells total capacity by the lock or type script. You can use this RPC to display address balance.
  • Use your UTXO management framework to combine CKB JSON-RPC protocols to scan the entire CKB blockchain.

CKB built-in indexer​

CKB​

Since v0.106.0, CKB has integrated the functions in previous standalone ckb-indexers. Users of v0.106.0 nodes or above have no need to start ckb-indexer service separately. Ckb-indexer-related RPC is included in the current RPC as a module. Users don't have to configure the indexer port separately.

There are three ways to enable CKB built-in indexer:

  • Add the parameter --indexer to the command line to start CKB
ckb run -C <path> --indexer
  • Add Indexer module in the RPC section of CKB config file. CKB built-in indexer will be enabled along with the node.
[rpc]
modules = [..., "Indexer"]
  • Add indexer_v2 section to the config file to configure the indexer. Since the indexer section was deprecated in the configuration file once before, the v2 suffix is added to avoid conflicts and to be compatible with older config files. Once the indexer section is configured, the CKB built-in indexer will be enabled along with the node.
[indexer_v2]
index_tx_pool = false

These three methods do not mutually conflict. Users can choose based on their preferences. The third method supports advanced indexer configuration.

Below listed the items to be configured:

ItemsDescription
store = <PATH>Indexer db directory. Configured as data/indexer/store by default.
secondary_path = <PATH>Indexer directory for node data synchronization. Configured as data/indexer/secondary_path by default.
poll_interval = 2Indexer data synchronization interval. Measured in second, 2s by default. Mainly used for testing. We recommended not to modify.
index_tx_pool = boolWhether to create index for the unconfirmed transactions in tx_pool.
db_background_jobs = 6Number of indexer db background job. 6 by default. We recommended not to modify.
db_keep_log_file_num = 1Number of indexer db debug logs. 1 by default.

Block_filter and cell_filter provide options to customize index rules via a simple Rhai script. Configured as below:

block_filter = "block.header.number.to_uint() > "1000000".to_uint()"
cell_filter = 'let script = output.lock; script.code_hash == "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8" && script.hash_type == "type" && script.args == "0xa897829e60ee4e3fb0e4abe65549ec4a5ddafad7"'

Also note that the difference between the RPC of CKB built-in indexer and the RPC of the previous standalone ckb-indexer:

  • get_tip RPC in ckb-indexer is renamed to get_indexer_tip to avoid ambiguity.
  • get_indexer_info RPC is removed.

Ckb-cli​

Ckb-cli requires v1.2.0 or higher to support CKB built-in indexer.

Specifying ckb-indexer-url is no longer necessary.

Ckb-sdk​

Go SDK

Importing Go SDK is no longer necessary.

All previous method calls are switched from indexerClient to CKB client as follows:

//import [github.com/nervosnetwork/ckb-sdk-go/indexer](http://github.com/nervosnetwork/ckb-sdk-go/indexer)
import github.com/nervosnetwork/ckb-sdk-go/rpc

///BEFORE
//!!NOTE: OLD ONE, this is deprated!
//indexerClient, err := indexer.Dial("http://127.0.0.1:8114")
//indexerClient.GetCells....

///AFTER
//!!NOTE: USE THIS INSTEAD
var client, _ = rpc.Dial("https://testnet.ckb.dev")
//client.GetCells(...)

Lumos​

Lumos needs v0.19.0 to adapt to CKB build-in indexer.

import { Indexer } from '@ckb-lumos/lumos';

// before
// const indexer = new Indexer(
//   "https://testnet.ckb.dev/indexer",
//   "https://testnet.ckb.dev/rpc",
// );

// after
const indexer = new Indexer("https://testnet.ckb.dev/rpc");

Confirmation count suggestion​

Since Nervos CKB network is secured by ASIC PoW miners with extreme hash rate now, it could achieve the same or better security threshold than Ethereum at 24 block confirmations.

This essay demonstrates how the transaction confirmation number is calculated.

Testing​

Once you’ve fully integrated with the CKB network, please test on the testnet and mainnet.

Q&A​

When you integrate CKB into your system, you may face some challenges. Here is a Q&A that may help you.