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

A Script in Nervos CKB is a binary executable on the CKB-VM.
like Omnilock and Spore-contract.

npm install -g @offckb/cli
info

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

Create a New Project​

To setup a boilerplate for a full-stacked dApp, run the following command. Replace <my-dapp-project> with any name you like.

offckb create <my-dapp-project>

When prompted to select a bare template, use your arrow keys to select the frontend framework you prefer. If you wish to use a frontend framework not listed, please refer to this section.

? Select a bare template
  Remix-Vite Bare Templates
> Next.js Bare Templates
---
A full-stack template with Next.js framework and ckb-script-templates,
[next.js,tailwindcss,ckb-script-templates,typescript,rust]
How to create a Script-only project?

To create a project focused solely on Script development without any frontend work, you can run the following command. Replace <my-script-project> with any name you like.

offckb create --script <my-script-project>

Note that offckb essentially utilizes an underlying tool called ckb-script-templates to initialize Script projects. You can directly engage ckb-script-templates for more specific Script development tasks. For further details, refer to the Script tutorial.

Start the Devnet​

offckb node

Your local CKB blockchain is currently active with the RPC endpoint at localhost:8114. 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

Run the DApp Project​

The dApp is based on various JavaScript web frontend frameworks, such as Remix-Vite and Next.js, and is integrated with the CKB JavaScript framework, Lumos. All Lumos-related code is defined in the frontend/offckb.config.ts file.

To start development, navigate to the frontend workspace:

cd frontend

Now, run the following command to install dependencies and start the dApp:

npm i && npm run dev

Once the server is up and running, you can view the dApp by visiting localhost:3000. You can start editing the page by modifying app/page.tsx. As you make changes to the file, the page will automatically update to reflect your edits. For detailed instructions on how to start the dApp and explore additional config options, please see the README.md file.

dapp-screenshot

DApp Project Structure​

The boilerplate project for a full-stack CKB dApp comprises two main components:

  • The frontend, which utilizes the CKB JavaScript framework, CCC.
  • The Scripts, which leverage the ckb-script-templates.

By default, the Next.js template comes with a simple Script hello-world under contracts/hello-world/src/main.rs.

Tools You Need

  • git, make, sed, bash, sha256sum and others Unix utilities.

  • Rust with riscv64 target: rustup target add riscv64imac-unknown-none-elf

  • Clang 16+

    • Debian / Ubuntu: wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo./llvm.sh 16 && rm llvm.sh
    • Fedora 39+: sudo dnf -y install clang
    • Archlinux: sudo pacman --noconfirm -Syu clang
    • MacOS (with Homebrew): brew install llvm@16
    • Windows (with Scoop): scoop install llvm yasm

  • Cargo-generate

Check out the ckb-script-templates for more details.

  • Add a new Script: make generate
  • Build Script: make build
  • Run unit tests: make test

Deploy Scripts to Blockchain​

After building your Scripts, you can navigate to your frontend workspace and deploy your Scripts to the Devnet or Testnet by using the following command:

offckb deploy --network devnet

Use Scripts in Frontend​

If the deployment is successful, the offckb.config.ts file will contain the necessary details to import and utilize your Scripts in your frontend dApp. Here's how you can use your Scripts directly:

import offckb from "offckb.config";

const myScriptDeps: CellDep[] = offCKB.myScripts["YOUR_SCRIPT_NAME"]!.cellDeps;
const myScript: Script = {
  codeHash: offCKB.myScripts["hash-lock"]!.codeHash,
  hashType: offCKB.myScripts["hash-lock"]!.hashType,
  args: lockArgs,
};

Use a Different Frontend Framework?​

The frontend world is filled with numerous (perhaps too many) frameworks. New frameworks come out every day, and different developers have different preferences among these frameworks. So if you don't use the framework in the pre-defined boilerplate, like remix-vite and next.js, don't worry! You can still use offckb with the inject-config command.

First, simply initialize your dApp project with your preferred framework, such as CRA:

npx create-react-app my-cra-dapp --template typescript

Next, navigate to your dApp directory and initialize the offckb config within your framework:

cd my-cra-dapp
offckb inject-config

Now, when you deploy your Scripts with offckb deploy --network devnet --target <your-folder-to-your-script-binaries>, run the following command in your frontend root path where the offckb.config.ts file is located to update the deployed Scripts info for your frontend.

offckb sync-scripts

For switching between different networks, you might need to update the readEnvNetwork method in offckb.config.ts according to your framework.

function readEnvNetwork(): "devnet" | "testnet" | "mainnet" {
  // you may need to update the env method
  // according to your frontend framework
  const network = process.env.NETWORK;
  const defaultNetwork = "devnet";
  if (!network) return defaultNetwork;
  if (!["devnet", "testnet", "mainnet"].includes(network)) {
    return defaultNetwork;
  }

  return network as "devnet" | "testnet" | "mainnet";
}

Debug a transaction​

If you are using the offckb dApp template to create your project, one of the beneficial is that all the failed transactions will be dumped and recorded so you can debug them later.

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

About offckb.config.ts​

offckb.config.ts is a straightforward TypeScript file that encapsulates basic devnet information. Everything is explicitly defined, making it easy to modify. This minimalistic approach ensures that offckb does not impose limitations on the tech selections and development processes of developers.

If you have any feedback you would like to share with us, feel free to contact us at github or discord.