Skip to main content

Quick Start (5min)

We recommend using offCKB to quickly set up a local development environment using our pre-built boilerplates. This streamlined approach allows you to jumpstart your project efficiently without the hassle of manual configuration.

Install OffCKB​

OffCKB provides a one-line command to start a local blockchain (CKB Devnet) with pre-funded test accounts and built-in Scripts like Omnilock and Spore-contract.

npm install -g @offckb/cli
info

Throughout this documentation, we use offckb/cli version >=0.4.0. You can always run the above command to update to the latest version.

Start the Devnet​

offckb node

Your local CKB blockchain is currently active with a proxy RPC endpoint at localhost:28114. To stop the chain, press CTRL+C in the terminal. To resume where you left off, simply run offckb node again.

If you need to start fresh with a new chain, run the following command before starting the node:

offckb clean

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 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.