Skip to main content

Run a Light Client Node

Why Light Client?​

Running a light client is fundamental to maintaining blockchain decentralization and trustlessness. While light clients don't store the entire blockchain, they independently verify transactions and blocks, embodying the core principle of blockchain: "Don't trust, verify." By lowering the barriers of running a light client, we can encourage broader participation in the network, thereby strengthening its decentralization.

Light clients strike an optimal balance between resource requirements and security, making blockchain verification accessible to more users. This widespread verification is crucial for maintaining the integrity and trustless nature of the network.

Compare to traditional light client, CKB has a more efficient FlyClient-based light client protocol. It uses a sampling protocol tailored for NC-Max difficulty adjustment algorithm. It requires downloading only a logarithmic number of block headers while storing only a single block header between executions.

CKB’s Light Client is not only lightweight but also compatible with WebAssembly (WASM), ideal for use in mobile applications, browsers, and resource-constrained environments.

Prerequisite​

Step 1: Build or Download CKB Light Client Binary​

You can either:

  • Download the prebuilt binary from Github releases based on your operating system.
  • Or build it from source:
  git clone https://github.com/nervosnetwork/ckb-light-client.git
  cd ckb-light-client
  cargo build --release

Step 2: Setup A Working Folder​

To keep things tidy, copy the binary (target/release/ckb-light-client) and config/mainnet.toml file into a new folder, then navigate into it:

  mkdir ~/light-client
  cp target/release/ckb-light-client ~/light-client/
  cp config/mainnet.toml ~/light-client/
  cd ~/light-client

You can name the folder anything you like—light-client is just an example. Your folder should now contain:

  light-client/
  ├── ckb-light-client
  └── mainnet.toml

Step 3: Start the Light Client​

Generally, you don't need to configure anything. But you may edit mainnet.toml file to customize:

  • Network connection parameters
  • RPC port
  • Storage directory
  • Bootnodes list

Run the following command in your working folder to start the light client:

  RUST_LOG=info,ckb_light_client=info ./ckb-light-client run --config-file ./mainnet.toml

Once running, the light client will listen for RPC requests at http://localhost:9000/ (unless configured otherwise in the mainnet.toml).

Step 4: Interact with the Light Client​

You can interact with your light client using JSON-RPC calls. Here are some common examples:

1. Get the current tip header​

curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "get_tip_header", "params": [], "id": 1}'

2. Set scripts to filter​

curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method":"set_scripts", "params": [[{"script": {"code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type", "args": "0x64257f00b6b63e987609fa9be2d0c86d351020fb"}, "script_type": "lock", "block_number": "0x0"}]], "id": 1}'

3. Get filtered scripts​

curl http://localhost:9000/ -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method":"get_scripts", "params": [], "id": 1}'

WASM Version for Browsers​

The CKB Light Client can also run directly in web browsers through WebAssembly (WASM). This allows you to build trustless, lightweight dApps without needing to connect to a full node.

  • To see how it works, check out the wasm folder in the repo.
  • For JavaScript/TypeScript projects, use the ready-to-go NPM package: ckb-light-client-js.

With this setup, you can verify transactions and headers entirely in the browser—ideal for mobile wallets, extensions, or web-based explorers.

Additional Resources​