ckb-script-app

🚀 The ultimate TypeScript template for building CKB app from smart contracts to user interface. Powered by offckb, ckb-js-vm and CCC.

What is this?

An all-in-one boilerplate for developing smart contracts app on the CKB blockchain using TypeScript. Write, test, deploy and interact with contracts using familiar JavaScript tooling.

Why ckb-js-vm?

CKB is unique - it allows smart contracts in any language that compiles to RISC-V. The ckb-js-vm is a JavaScript runtime (based on QuickJS) compiled to RISC-V, enabling you to write contracts in TypeScript instead of low-level languages.

✨ Features

• 📝 TypeScript Support - Full type checking and IDE support
• 🧪 Built-in Testing - Full test flow from Jest + ckb-testtool for mock testing to CCC + offckb for local node and testnet testing
• 🚀 One-Command Deploy - Deploy to devnet, testnet, or mainnet
• 🔄 Upgradable Contracts - Type ID pattern support for contract updates
• 🌐 Next.js Frontend - Ready-to-use dApp with CCC wallet integration
• 🤖 AI-Friendly - Documentation optimized for LLM assistants

🏁 Quick Start

# Clone the template
git clone https://github.com/cryptape/ckb-script-app my-ckb-project
cd my-ckb-project

# Install dependencies
pnpm install

# Build contracts
pnpm run build

# Run tests
pnpm test

# Start frontend (optional)
cd app && pnpm dev

📁 Project Structure

ckb-script-app/
├── contracts/              # 📜 Smart contract source code
│   └── hello-world/
│       └── src/
│           └── index.ts    # Contract entry point
├── tests/                  # 🧪 Contract tests
│   ├── *.mock.test.ts      # Mock tests (no node required)
│   └── *.devnet.test.ts    # Integration tests
├── dist/                   # 📦 Compiled output
│   └── *.bc                # Bytecode for CKB
├── deployment/             # 🚀 Deployment artifacts
│   └── scripts.json        # Deployed contract info
├── app/                    # 🌐 Next.js frontend
│   ├── components/         # React components
│   └── utils/              # CKB utilities
├── .skills/                # 🤖 AI skill patterns
│   ├── ckb-contract-patterns/  # Contract patterns
│   └── ckb-ccc-frontend/       # Frontend patterns
├── scripts/                # 🔧 Build tooling
├── CLAUDE.md               # 🤖 AI assistant guide
├── AGENTS.md               # 🤖 AI assistant guide

📜 Writing Contracts

Basic Contract Template

import * as bindings from '@ckb-js-std/bindings';
import { log } from '@ckb-js-std/core';

function main(): number {
  log.setLevel(log.LogLevel.Debug);
  
  // Load current script info
  const script = bindings.loadScript();
  log.debug(`Script: ${JSON.stringify(script)}`);
  
  // Your validation logic here
  // Return 0 for success, non-zero for failure
  
  return 0;
}

bindings.exit(main());

Create a New Contract

pnpm run add-contract my-token

This creates:

• contracts/my-token/src/index.ts - Contract code
• tests/my-token.mock.test.ts - Mock test file

Key APIs

Function	Description
bindings.loadScript()	Get current script info
bindings.loadCell(index, source)	Load cell at index
bindings.loadCellData(index, source)	Load cell data field
bindings.loadInput(index, source)	Load transaction input
bindings.loadWitness(index, source)	Load witness data
bindings.exit(code)	Exit with return code

Cell Sources

bindings.SOURCE_INPUT          // Input cells
bindings.SOURCE_OUTPUT         // Output cells
bindings.SOURCE_GROUP_INPUT    // Same-script input cells
bindings.SOURCE_GROUP_OUTPUT   // Same-script output cells

🧪 Testing

Mock Tests (Recommended)

Test without running a CKB node:

import { Resource, Verifier } from 'ckb-testtool';

describe('my-contract', () => {
  test('should validate correctly', async () => {
    const resource = Resource.default();
    const tx = Transaction.default();
    
    // Setup transaction cells...
    
    const verifier = Verifier.from(resource, tx);
    await verifier.verifySuccess(true);
  });
});

pnpm test                    # Run all tests
pnpm test -- my-contract     # Run specific contract tests

Devnet Tests

For integration testing with a real node:

offckb node                  # Start local devnet
pnpm test -- devnet          # Run devnet tests

🚀 Deployment

Deploy Commands

# Deploy to local devnet (default)
pnpm run deploy

# Deploy to testnet
pnpm run deploy -- --network testnet

# Deploy to mainnet
pnpm run deploy -- --network mainnet

# Deploy with upgradable Type ID
pnpm run deploy -- --network testnet --type-id

# Deploy with custom key
pnpm run deploy -- --network testnet --privkey 0x...

Deployment Output

After deployment, deployment/scripts.json contains your contract info:

{
  "devnet": {
    "hello-world.bc": {
      "codeHash": "0x...",
      "hashType": "type",
      "cellDeps": [...]
    }
  }
}

🌐 Frontend Integration

The app/ directory contains a Next.js app with CCC wallet integration.

Using Deployed Contracts

import scripts from "@/deployment/scripts.json";
import systemScripts from "@/deployment/system-scripts.json";

// Build script for ckb-js-vm contract
const myScript = {
  codeHash: systemScripts.devnet["ckb_js_vm"].script.codeHash,
  hashType: systemScripts.devnet["ckb_js_vm"].script.hashType,
  args: buildScriptArgs(scripts.devnet["hello-world.bc"]),
};

Start Frontend

cd app
pnpm install
pnpm dev

Open http://localhost:3000

📋 Available Scripts

Script	Description
pnpm run build	Build all contracts
pnpm run build:contract <name>	Build specific contract
pnpm run build:debug	Build with debug symbols
pnpm test	Run all tests
pnpm run add-contract <name>	Create new contract
pnpm run deploy	Deploy contracts
pnpm run clean	Remove build outputs
pnpm run format	Format code with Prettier

🤖 AI Assistant Support

This template includes documentation for AI coding assistants:

File	Purpose
CLAUDE.md	Guide for Claude, ChatGPT, and general LLMs
AGENTS.md	Quick reference for OpenAI agents
.skills/	Structured patterns (Agent Skills format)

AI Skills

The .skills/ folder contains detailed patterns:

Skill	Description
ckb-contract-patterns	Smart contract patterns for ckb-js-vm
ckb-ccc-frontend	Frontend patterns with CCC wallet integration

When using AI assistants, share the repo URL and they'll understand the project structure.

📚 CKB Concepts

Concept	Description
Cell	Data unit on CKB (like enhanced UTXO)
Lock Script	Defines who can spend a cell
Type Script	Defines cell creation/destruction rules
Capacity	CKB tokens; also determines storage size
Cell Dep	Reference to code/data cells in transaction
Witness	Signature and proof data

🔗 Resources

• The Little Book of ckb-js-vm - Comprehensive guide
• CKB JS Quick Start - Official docs
• CCC Documentation - Wallet connector
• CKB RFCs - Protocol specs
• ckb-js-vm GitHub - VM source

🛠️ Prerequisites

• Node.js v20 or later
• pnpm package manager
• offckb (optional, for local devnet): npm install -g @offckb/cli

📄 License

MIT

---

Built with ❤️ for the CKB ecosystem