Skip to main content

OffCKB

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

  • Simplifies development with one-line command to start the devnet
  • Comes with pre-funded Devnet accounts
  • Generates JavaScript or TypeScript CKB Smart Contract projects from templates
  • Embeds common Scripts in the genesis block, such as Omnilock, xUDT, and Spore
  • Provides debugging 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.13 or later.

Install​

OffCKB requires Node.js 20 or later. Check your installed version:

node -v

If the version is below v20.0.0, install a current Node.js LTS release before continuing.

npm install -g @offckb/cli

or use pnpm to install:

pnpm install -g @offckb/cli

Usage​

Usage: offckb [options] [command]

ckb development network for your first try

Options:
  -V, --version                                output the version number
  --json                                       Output logs in JSON format for agent/programmatic consumption
  -h, --help                                   display help for command

Commands:
  node [options] [CKB-Version]                 Use the CKB to start devnet
  logs [options] [target]                      Show devnet logs: node (default), contract script debug output, miner, or RPC proxy events
  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 [options]                              Clean the devnet data, need to stop running the chain first
  accounts [options]                           Print account list info
  deposit [options] [toAddress] [amountInCKB]  Deposit CKB tokens to address, only devnet and testnet
  transfer [options] [toAddress] [amount]      Transfer CKB or UDT 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 (CKB + detected SUDT/xUDT), only devnet and testnet
  udt                                          UDT token commands
  install <tool>                               Install a tool binary used by offckb (e.g. the native ckb-debugger)
  debugger                                     Port of the raw CKB Standalone Debugger
  status [options]                             Show ckb-tui status interface
  config <action> [item] [value]               do a configuration action
  devnet                                       Devnet utility commands
  help [command]                               display help for command

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

Get started​

Run a Local CKB Devnet​

Start a local blockchain with one command:

offckb node

Your local CKB blockchain is now running. Use the proxy RPC endpoint at http://127.0.0.1:28114 as the default for local development. It forwards requests to the node and records failed transactions for debugging. The direct RPC endpoint at http://127.0.0.1:8114 bypasses the debugging proxy.

Keep this terminal open while you use the Devnet, and open a second terminal for the commands you run next. To stop the chain, press CTRL+C. To resume where you left off, run offckb node again.

note

This Devnet runs only on your computer. Its transactions will not appear in public Testnet or Mainnet explorers.

To run a specific CKB version:

offckb node 0.208.0

To save it as the default version:

offckb config set ckb-version 0.208.0
offckb node

You can also run a local debugging proxy in front of a public Testnet or Mainnet RPC. This does not start a Testnet or Mainnet node on your computer:

offckb node --network <testnet or mainnet>

View Pre-funded Accounts​

In the second terminal, list the pre-funded Devnet accounts:

offckb accounts

Run offckb accounts whenever you need the account list or funding provided by your installed version.

warning

These accounts are for local testing only. Never send Mainnet assets to them.

  • Private keys are hidden by default. Display them only in a trusted local terminal with offckb accounts --show-private-keys.
  • Contract deployment costs are deducted from these Devnet accounts, so no faucet or manual funding is required.

Create a Contract Project​

Generate a JavaScript or TypeScript contract project:

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

The -c option is optional; the default contract name is hello-world. Generated projects include their own build, test, and deployment scripts. Follow the generated project's README because its commands and artifact paths may differ from Rust projects or other templates.

When a generated example includes dApp or client-side code, it uses CCC to interact with CKB. CCC does not compile the on-chain Script.

Deploy a CKB Smart Contract​

Before deploying, confirm that:

  • The target Devnet is running (offckb node), or the Testnet RPC is reachable.
  • The contract has been compiled using the command documented by its project.
  • The compiled binary or target folder exists.
  • The deployment network matches the network used by your application.

If you already have a compiled contract binary or folder, deploy it directly with OffCKB:

offckb deploy --network devnet --target <path-to-contract-binary-or-folder> --output ./deployment

If your project provides a deployment script, prefer that project-level command. For example:

npm run deploy

Project-level scripts may compile the contract, select the correct --target, and synchronize deployment information automatically.

Unlike an EVM contract, a deployed CKB Script does not have a contract address. Its code is stored in a Cell and identified by an OutPoint; transactions include that reference in a CellDep.

After a successful deployment, OffCKB writes these deployment records:

  • <output>/<network>/<contract>/deployment.toml
  • <output>/<network>/<contract>/migrations/<timestamp>.json
  • <output>/scripts.json

These files are outputs of a successful deployment. They do not need to exist before the first deployment.

Pass --type-id if you want the Script to be upgradable:

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

Upgrades are keyed by the contract artifact's name. Do not rename the artifact between deployments; otherwise, OffCKB cannot find its previous Type ID information and creates a new Type ID.

When Deployment Fails​

SymptomWhat to check
Cannot connect to the node or RPCStart offckb node and wait for the ready message. Use offckb logs -f to inspect the full node log.
Contract binary or target not foundRun the build command from the project's README and confirm the path passed to --target.
Deployment records are missingConfirm that the command reached tx committed., then check the folder passed to --output. OffCKB generates the records after a successful deployment.
Transaction is rejectedSend requests through http://127.0.0.1:28114, then run offckb debug --tx-hash <transaction-hash> to inspect the recorded transaction.
Insufficient capacity or feeCheck the output's occupied capacity and the transaction fee rate. Larger signatures and additional Cell data can increase the cost.

Debug a Transaction​

When you send Devnet requests through the proxy RPC endpoint at http://127.0.0.1:28114, failed transactions are recorded so you can debug them later.

Start by checking the relevant logs:

offckb logs script                       # Contract Script output
offckb logs rpc                          # RPC requests and errors
offckb logs rpc --tail 200 --grep ERROR  # Recent RPC errors

Then debug the transaction with its hash:

offckb debug --tx-hash <transaction-hash>

Projects generated with offckb create install the native ckb-debugger automatically. If OffCKB reports that it is missing, install it once:

offckb install ckb-debugger

The command verifies the Scripts in the transaction and prints their execution results and cycle usage. A shortened response looks like this:

offckb debug --tx-hash 0x...
Dump transaction successfully

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

Run result: 0
Total cycles consumed: ...

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

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

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

  • cell-type is input or output.
  • cell-index is the Cell's index in the transaction.
  • script-type is lock or type.

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

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

These debugging features use ckb-debugger.

Reset the Devnet​

If you need to start fresh with a new chain, first stop the running node by pressing CTRL+C. Then run:

offckb clean
caution

Cleaning the Devnet creates a new local chain. Transaction hashes and deployed Script OutPoints from the previous chain will no longer be valid.

Inspect Built-in Scripts​

Print all predefined Scripts for the local blockchain:

offckb system-scripts

Export them in Lumos or CCC format, or write them to a JSON file:

offckb system-scripts --export-style lumos
offckb system-scripts --export-style ccc
offckb system-scripts --output <output-file-path>

The default Devnet includes xUDT, Omnilock, AnyoneCanPay, AlwaysSuccess, Spore, CKB-JS-VM, Nostr-Lock, and Type ID. Use offckb system-scripts to inspect the information for the Scripts included with your installed version.

Configuration​

Locate Configuration Files​

Run the following command and look for the devnet.configPath and devnet.dataPath values:

offckb config list

Customize the Devnet​

Stop the running node, then open the Devnet configuration editor:

offckb devnet config

After saving your changes, remove only the existing chain data and restart the Devnet:

offckb clean -d
offckb node
caution

Running offckb clean -d preserves the Devnet configuration but deletes its chain data. Transaction hashes and deployed Script OutPoints from the previous chain will no longer be valid.

For advanced changes, you can edit the files under devnet.configPath directly. See Custom Devnet Setup and Configure CKB for details.

Set the Default CKB Version​

Set and confirm the version used when offckb node is run without a version argument:

offckb config get ckb-version
> 0.208.0
offckb config set ckb-version 0.208.0
> save new settings
offckb config get ckb-version
> 0.208.0

Set an HTTP Proxy​

This setting controls the HTTP proxy OffCKB uses for downloads and network requests. It is separate from the CKB RPC proxy at http://127.0.0.1:28114.

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.

Configure Logging​

Set LOG_LEVEL=debug to print more detailed OffCKB and RPC proxy logs:

LOG_LEVEL=debug offckb node