Skip to content

ckb-ecofund/offckb

BranchesTags

Repository files navigation

OffCKB

npm CI npm npm node

CKB local development network for your first try.

  • One-line command to start a devnet
  • No docker required
  • Pre-funded test accounts
  • Built-in scripts like Omnilock and Spore-contract
  • Multiple minimal dApp templates to learn and get your hands dirty

Migrate from v0.2.x to v0.3.x:

There are BREAKING CHANGES between v0.2.x and v0.3.x, make sure to read the migration guide before upgrading.

Table of Contents

Install

npm install -g @offckb/cli

We recommand using 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:
  create [options] [your-project-name]              Create a new dApp from bare templates
  node [options] [CKB-Version]                      Use the CKB to start devnet
  proxy-rpc [options]                               Start the rpc proxy server
  clean                                             Clean the devnet data, need to stop running the chain first
  accounts                                          Print account list info
  list-hashes [CKB-Version]                         Use the CKB to list blockchain scripts hashes
  inject-config                                     Add offckb.config.ts to your frontend workspace
  sync-scripts                                      Sync scripts json file in your frontend workspace
  deposit [options] [toAddress] [amountInShannon]   Deposit CKB tokens to address, only devnet and testnet
  transfer [options] [toAddress] [amountInShannon]  Transfer CKB tokens to address, only devnet and testnet
  balance [options] [toAddress]                     Check account balance, only devnet and testnet
  deploy [options]                                  Deploy contracts to different networks, only supports devnet and testnet
  my-scripts [options]                              Show deployed contracts info on different networks, only supports devnet and testnet
  config <action> [item] [value]                    do a configuration action
  debug [options]                                   CKB Debugger for development
  system-scripts [options]                          Output system scripts of the local devnet
  mol [options]                                     Generate CKB Moleculec binding code for development
  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.117.0

Or set the default CKB version:

offckb config set ckb-version 0.117.0
offckb node

Once you start the devnet, there is a RPC server running at http://localhost:8114. There is also a RPC proxy server running at http://localhost:9000 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.

The proxy server is optional, you can use the RPC server directly if you don't need a proxy:

offckb node --no-proxy

Or start the proxy server in a standalone terminal to better monitor the logs:

offckb proxy-rpc --ckb-rpc http://localhost:8114 --port 9000 --network devnet

List scripts info

List all the predefined scripts for the local blockchain:

offckb system-scripts

Or export 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

Create a full-stack Project

Create a new project from predefined boilerplates.

offckb create <your-project-name, eg:my-first-ckb-project>

The boilerplate can be targeting on different CKB networks. Check README.md in the project to get started.

Create a script-only Project

You can create a new script project without a frontend. This is useful when you only want to develop smart contracts for CKB.

offckb create <your-project-name> --script

Note: you need to have rust/cargo/cargo-generate/clang 16+ installed in your environment to use this command. offckb doesn't do anything really, it just call ckb-script-template to do all the magic.

Build and Deploy a script

The fullstack boilerplate project is a monorepo, which contains a script project and a frontend project.

To build the script, in the root of the project, run:

make build

To deploy the script, cd into the frontend folder and run:

cd frontend && offckb deploy --network <devnet/testnet>

Once the deployment is done, you can use the following command to check the deployed scripts:

offckb my-scripts --network <devnet/testnet>

Your deployed scripts will be also be listed in the frontend/offckb/my-scripts folder in your frontend project.

Start the frontend project

To start the frontend project, cd into the frontend folder and run:

npm i & npm run dev

Debug a transaction

If you are using the proxy RPC server, 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.

Generate Moleculec bindings

Moleculec is the official Serialization/Deserialization system for CKB smart contracts.

You will define your data structure in .mol file(schema), and generate the bindings for different programming languages to use in your development.

offckb mol --schema <path/to/mol/file> --output <path/to/output/file> --lang <lang>

The lang could be ts, js, c, rs and go.

If you have multiple .mol files, you can use a folder as the input and specify an output folder:

offckb mol --schema <path/to/mol/folder> --output-folder <path/to/output/folder> --lang <lang>

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.

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.

FAQ

Sometimes you might encounter sudo permission problems. Granting the current user write access to the node_modules directory can resolve the problem.

sudo chown -R $(whoami) /usr/local/lib/node_modules
npm install -g @offckb/cli

Contributing

check development doc

About

CKB local development network for your first try.

www.npmjs.com/package/@offckb/cli

Topics

cli ckb ckb-dapp

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

11 stars

Watchers

5 watching

Forks

3 forks
Report repository

Releases 20

v0.2.7 Latest
Aug 12, 2024
+ 19 releases

Packages

No packages published

Contributors 2

  •  
  •  

Languages