Skip to main content

OffCKB

offckb is a an all-in-one CLI tool that provides a local CKB development environment.

  • Simplifies development with one-line command to start the devnet and create projects from boilerplate
  • Comes with 20 pre-funded accounts and multiple minimal dApp templates for quick project setup
  • Embeds common Scripts in the genesis block, such as CKB-VM-JS, Omnilock, xUDT, and Spore
  • Provides a complete workflow from Script building and deployment to frontend integration for devnet
  • Includes tools like ckb-debugger
  • Offers configurable settings via a JSON file

This guide will walk you through leveraging OffCKB to kickstart your first CKB project. The version used here is v0.4.0 or later.

Install​

npm install -g @offckb/cli

or use pnpm to install:

pnpm install -g @offckb/cli

Requires Node version >= v20.0.0. We recommend using latest LTS version of Node to run offckb

Usage​

Usage: offckb [options] [command]

ckb development network for your first try

Options:
  -V, --version                                 output the version number
  -h, --help                                    display help for command

Commands:
  node [CKB-Version]                            Use the CKB to start devnet
  create [options] [project-name]               Create a new CKB Smart Contract project in JavaScript.
  deploy [options]                              Deploy contracts to different networks, only supports devnet and testnet
  debug [options]                               Quickly debug transaction with tx-hash
  system-scripts [options]                      Print/Output system scripts of the CKB blockchain
  clean                                         Clean the devnet data, need to stop running the chain first
  accounts                                      Print account list info
  deposit [options] [toAddress] [amountInCKB]   Deposit CKB tokens to address, only devnet and testnet
  transfer [options] [toAddress] [amountInCKB]  Transfer CKB tokens to address, only devnet and testnet
  transfer-all [options] [toAddress]            Transfer All CKB tokens to address, only devnet and testnet
  balance [options] [toAddress]                 Check account balance, only devnet and testnet
  debugger                                      Port of the raw CKB Standalone Debugger
  config <action> [item] [value]                do a configuration action
  help [command]                                display help for command

Use offckb [command] -h to learn more about a specific command.

Get started​

Running CKB​

Start a local blockchain with the default CKB version:

offckb node

Or specify a CKB version:

offckb node 0.201.0

Or set the default CKB version:

offckb config set ckb-version 0.201.0
offckb node

Once you start the devnet, there is a RPC server running at http://127.0.0.1:8114. There is also a RPC proxy server running at http://127.0.0.1:28114 which will proxy all the requests to the RPC server. The meaning of using a proxy RPC server is to record request and automatically dump failed transactions so you can debug them easily later.

In the same way, you can also start proxy RPC server for testnet and mainnet by running:

offckb node --network <testnet or mainnet>

Using a local proxy RPC server for public testnet/mainnet is also very helpful for debugging the requests and the automatically recorded dump transactions.

List scripts info​

Print all the predefined scripts for the local blockchain:

offckb system-scripts

Or print the scripts info to a lumos JSON file:

offckb system-scripts --export-style lumos

Or print the scripts info in a CCC style:

offckb system-scripts --export-style ccc

You can also export the scripts info to a JSON file:

offckb system-scripts --output <output-file-path>

Tweak Devnet Config​

By default, offckb use a fixed devnet config for the local blockchain. You can tweak the config to customize the devnet, for example, modify the default log level for the devnet CKB Node warn,ckb-script=debug.

To tweak the devnet config, follow the steps below:

  1. Locate your devnet config folder by running:
offckb config list

Result:

{
  "devnet": {
    "rpcUrl": "http://127.0.0.1:8114",
    "configPath": "~/Library/Application Support/offckb-nodejs/devnet",
    "dataPath": "~/Library/Application Support/offckb-nodejs/devnet/data"
  }
}
  1. Pay attention to the devnet.configPath and devnet.dataPath. They are the ones we need.
  2. cd into the devnet.configPath, this is the config folder for the local blockchain. Modify the config in the folder to better customize the devnet. For customization, see Custom Devnet Setup and Configure CKB for better explanation of the config files.
  3. After modifications, remove everything in the devnet.dataPath folder. This will clean the chain data.
  4. Restart local blockchain by running offckb node

Done.

Create a CKB Smart Contract Project​

You can create a new CKB Smart Contract project in Typescript from our boilerplate.

offckb create <your-project-name> -c <your-contract-name>

The -c option is optional, if you don't provide it, the contract name will be hello-world.

After create the project, you can follow the instructions on build, deploy and test the contract in README.md of the project.

The project includes both mock test and devnet test. For developing frontend interacting with the blockchain, you can refer to the devnet test and see how it works.

Deploy a CKB Smart Contract​

To deploy the script, use offckb deploy command:

offckb deploy --network <devnet/testnet> --target <path-to-your-contract-binary-file-or-folder> --output <output-folder-path>

Pass --type-id option if you want Scripts to be upgradable

offckb deploy --type-id --network <devnet/testnet>

Your deployed scripts info will be listed in the output-folder-path which you defined in the command.

Note that upgrades are keyed by the contract‘s artifact name. If you plan to upgrade with --type-id, do not rename your contract artifact (e.g. keep hello-world.bc). Renaming it makes the offckb unable to find the previous Type ID info from the output-folder-path and will create a new Type ID.

Debug a transaction​

If you are interacting the CKB devnet via the proxy RPC server(localhost:28114), all the failed transactions will be dumped and recorded so you can debug them later.

Every time you run a transaction, you can debug it with the transaction hash:

offckb debug <transaction-hash>

It will verify all the scripts in the transaction and print the detailed info in the terminal.

offckb debug --tx-hash 0x64c936ee78107450d49e57b7453dce9031ce68b056b2f1cdad5c2218ab7232ad
Dump transaction successfully

******************************
****** Input[0].Lock ******

hello, this is new add!
Hashed 1148 bytes in sighash_all
sighash_all = 5d9b2340738ee28729fc74eba35e6ef969878354fe556bd89d5b6f62642f6e50
event = {"pubkey":"45c41f21e1cf715fa6d9ca20b8e002a574db7bb49e96ee89834c66dac5446b7a","tags":[["ckb_sighash_all","5d9b2340738ee28729fc74eba35e6ef969878354fe556bd89d5b6f62642f6e50"]],"created_at":1725339769,"kind":23334,"content":"Signing a CKB transaction\n\nIMPORTANT: Please verify the integrity and authenticity of connected Nostr client before signing this message\n","id":"90af298075ac878901282e23ce35b24e584b7727bc545e149fc259875a23a7aa","sig":"b505e7d5b643d2e6b1f0e5581221bbfe3c37f17534715e51eecf5ff97a2e1b828a3d767eb712555c78a8736e9085b4960458014fa171d5d169a1b267b186d2f3"}
verify_signature costs 3654 k cycles
Run result: 0
Total cycles consumed: 4013717(3.8M)
Transfer cycles: 44947(43.9K), running cycles: 3968770(3.8M)

******************************
****** Output[0].Type ******

verify_signature costs 3654 k cycles
Run result: 0
Total cycles consumed: 3916670(3.7M)
Transfer cycles: 43162(42.2K), running cycles: 3873508(3.7M)

If you want to debug a single cell script in the transaction, you can use the following command:

offckb debug <transaction-hash> --single-script <single-cell-script-option>

The single-cell-script-option format is <cell-type>[<cell-index>].<script-type>, eg: "input[0].lock"

  • cell-type could be input or output, refers to the cell type
  • cell-index is the index of the cell in the transaction
  • script-type could be lock or type, refers to the script type

Or you can replace the script with a binary file in your single cell script debug session:

offckb debug <transaction-hash> --single-script <single-cell-script-option> --bin <path/to/binary/file>

All the debug utils are borrowed from ckb-debugger.

Config Setting​

List All Settings​

offckb config list

Set CKB version​

offckb config get ckb-version
> 0.113.0
offckb config set ckb-version 0.117.0
offckb config get ckb-version
> 0.117.0

Set Network Proxy​

offckb config set proxy http://127.0.0.1:1086
> save new settings
offckb config get proxy
> http://127.0.0.1:1086
offckb config rm proxy
> save new settings
offckb config get proxy
> No Proxy.

Log-Level​

You can tweak env LOG_LEVEL to control the offckb log level.

For example, set LOG_LEVEL=debug gives you more outputs of offckb proxy RPC.

LOG_LEVEL=debug offckb node

Built-in scripts​

Accounts​

offckb comes with 20 accounts, each account is funded with 42_000_000_00000000 capacity in the genesis block.

all the private keys are recorded in the account/keys file. detail informations about each account are recorded in the account/account.json file.

⚠️ DO NOT SEND REAL ASSETS INTO ALL THESE ACCOUNTS, YOU CAN LOOSE YOUR MONEY ⚠️

About CCC​

offckb uses CCC as the development framework to build the CKB dApp template projects.