Skip to main content

Quick Start(5m)

Use offckb to quickly setup a local dev environment with full-stack dApp boilerplates.

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.

Install​

npm install -g @offckb/cli
note

Required offckb version >= 0.2.2

Create A New Project​

Select from different boilerplates to create your project:

offckb create <your-project-name>

By default, the boilerplate is the a full-stack dApps with frontend and scripts(smart contract). If you only want to create and devleop a script project without any frontends, you can use the following commands:

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

offckb doesn't do much things for you. It simply calls the underlying script developing tools called ckb-script-templates and do the jobs for you. You can of course dirrectly use the ckb-script-templates to init script project directly. Check the script tutorial for more details.

Start the Devnet​

offckb node

Your local CKB blockchain is now running. The RPC endpoint is localhost:8114. Anytime you want to stop the chain, just press CTRL+C to exit the process in the terminal. Running offckb node again will strat the chain where it lefts.

If you want to restart over with a clean chain, just run offckb clean before running offckb node, the previous chain data will be removed.

Project Structure​

The boilerplate project constructs two parts of a full stack CKB dApp:

  • One is the frontend part based on the CKB Javascript framework Lumos.
  • One is the scripts(smart-contract) part based on the ckb-script-templates.

Script Development​

By default, this template comes with a single simple smart contract hello-world: contracts/hello-world/src/main.rs.

The smart contract is written in Rust lang. In order to develop, the following dependencies are required:

  • git, make, sed, bash, sha256sum and others Unix utilities.
  • Rust with riscv64 target: rustup target add riscv64imac-unknown-none-elf
  • Clang 16+
  • cargo-generate

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

Usage​

Add a new script:

make generate

Build script:

make build

Run unit test:

make test

DApp development​

The dApp is based on different Javascript web frontend framework like remix-vite and next.js, integrated with the CKB Javascript framework Lumos. All the Lumos related code are defined in the frontend/offckb.config.ts file.

To develop, enter the frontend workspace:

cd frontend

Checkout the README.md to see how to start the app.

Normally it is something like:

npm i && npm run dev

Deploy Scripts to Blockchain​

After building your scripts, you can deploy it with offckb and the scripts deployed information will automatically get updated in the frontend config so you don't need to worried about it.

offckb will look for the offckb.config.ts file to read config information. so you will need to enter the frontend workspace to do the instruction:

cd frontend
offckb deploy --network devnet

If successfully deployed, you will see the deploy script info for your smart contract recorded in the offckb.config.ts file. You can then directly import and use your smart contract in your frontend Dapp like this:

import offckb from "offckb.config";
import { CellDep } from "@ckb-lumos/lumos";

const lumosConfig = offckb.lumosConfig;
const myContractDep: CellDep = {
  outPoint: {
    txHash: lumosConfig.SCRIPTS.YOUR_SCRIPT_NAME!.TX_HASH,
    index: lumosConfig.SCRIPTS.YOUR_SCRIPT_NAME!.INDEX,
  },
  depType: lumosConfig.SCRIPTS.YOUR_SCRIPT_NAME!.DEP_TYPE,
};

Every time you deploy a new version of your smart contracts, those script infos will be updated by offckb in the offckb.config.ts and work out-of-box in your frontend.

You can also deploy smart contracts to the CKB Testnet like this:

cd frontend
offckb deploy --network testnet

Easily Switch Between Different Networks​

One of the things you might want to do is to swtich different blockchain networks across the development of your dapps. This can be done by applying different environment variables in the project.

Accroding to your boilerplate, you will switch the CKB blockchain network by applying different environment variables.

Remix-Vite boilerplate​

export NETWORK=devnet # or testnet, mainnet

Start the dApp:

yarn dev

or

NETWORK=devnet yarn dev

Next.js boilerplate​

edit .env file:

NEXT_PUBLIC_NETWORK=testnet # or testnet, mainnet

Start the dApp:

npm run dev

Access Test accounts​

offckb has 20 prefund accounts to be used on devnet. Each account is funded with 42_000_000_00000000 capacity in the devnet genesis block. You can access the accounts and copy the private keys and addresses to use when developing your dApps.

offckb accounts

Check out specific account's balance:

offckb balance <CKB-address> --network <devnet/testnet>
note

Required offckb node running when checking devnet balance

Deposit To Your Own Account​

Sometime you want to use your own CKB account instead of pre-funded accounts in offckb. You can deposit CKB to your own accounts using offckb:

offckb deposit --network devnet <your-ckb-address> <deposit-amount-in-shannon>
note

Required offckb node running when depositing in devnet

Use A Different Frontend Framework?​

The frontend world is filled with many(maybe too many) frameworks. New framework comes out everyday. Different develops has different favors over all 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, just init your dApp project with your favorite framework, say CRA:

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

Second, init the offckb config in 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>, after the deployment, you can run offckb sync-config in your frontend root path where the offckb.config.ts located to update the deployed scripts infos for your frontend.

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

function readEnvNetwork(): 'devnet' | 'testnet' | 'mainnet' {
  // you may need to update the env method
  // accroding 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';
}

About offckb.config.ts​

offckb.config.ts is a very simple typescript code that wrap some basic info and configs for lumos. Everything is plain and exlicity so it is easy to modify. In this way, we hope offckb is doing a very thin wrapping and is not limited to the tech selections and different ways of building proecess from developers.

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