CellScript Wiki

Home

Home

CellScript is a small language for writing Cell-based contracts on CKB. You describe the Cells your protocol cares about, the actions that move those Cells, and the locks that decide whether a Cell may be spent. The compiler then turns that .cell source into ckb-vm compatible RISC-V assembly or ELF artifacts, and writes metadata that explains what was built.

Last updated: 2026-06-28.

This wiki is a guided path. It starts with one compiled example, then slowly builds the mental model: source files, Cell effects, packages, the CKB profile, metadata, tooling, and finally the bundled examples. You do not need to understand every production gate on the first read. The important thing is to learn what each layer proves, and what it does not prove yet.

How to Read This Wiki

If CellScript is new to you, read the numbered tutorials in order. The sequence starts with source shape, Cell movement, packages, CKB profiles, metadata, and tooling, then continues into bundled examples and the deeper language chapters. Those later chapters explain how the canonical action model expresses input-to-output verification with transition and verification. The v0.15 material then extends that model with identity policies, scoped invariants, ProofPlan metadata, and primitive capability boundaries.

After that, the wiki continues outward:

  • packages make builds repeatable;
  • the CKB profile chooses the chain-facing runtime rules;
  • metadata explains the artifact;
  • v0.16 assurance commands explain ProofPlan soundness and builder assumptions;
  • production evidence proves more than compiler success;
  • editor tooling shortens the local loop;
  • bundled examples show the style in real contracts.

If you already know what you need, jump directly:

Tutorial Path

  1. Getting Started: compile one example and verify its artifact.
  2. Language Basics: learn the shape of a .cell file.
  3. Resources and Cell Effects: understand how values move through a Cell transaction.
  4. Packages and CLI Workflow: create a package, build it, check it, and inspect reports.
  5. CKB Target Profiles: choose the CKB runtime assumptions before compiling.
  6. Metadata, Verification, and Production Gates: learn what artifact verification proves, and what still needs chain evidence.
  7. LSP and Tooling: use editor feedback and command-backed reports.
  8. Bundled Example Contracts: study the examples in a useful order.
  9. Action Model and Canonical Syntax: learn the signature-direction action model, verification, transition, named outputs, and source qualifiers.
  10. Standard Library: use stdlib lifecycle, Cell metadata, accounting, runtime, and collection helpers without hiding verifier obligations.
  11. Scoped Invariants and ProofPlan: inspect 0.15 invariant trigger/scope/read metadata and understand metadata-only ProofPlan gaps.
  12. Phase 1 Registry: End-to-End: follow the registry package flow from init through verification.
  13. Agentic Loops and cellc-mcp: drive the read-oriented compiler surface from an automated writer in a write -> check -> explain -> fix loop.

After the numbered path, use Cookbook Recipes for small patterns and keep CKB Glossary nearby for terminology.

The Core Idea

CellScript tries to keep the CKB model visible. A contract should not look like an account database if it is really spending input Cells and creating output Cells.

That is why the language has:

  • resource, shared, and receipt for persistent Cell-backed values;
  • explicit effects such as consume, create, action-boundary read parameters, expression-level read_ref<T>(), destroy, claim, and settle;
  • compiler-recognized stdlib lifecycle patterns such as std::lifecycle::transfer, std::receipt::claim, and std::lifecycle::settle;
  • identity-aware lifecycle forms such as create_unique and replace_unique;
  • scoped invariant declarations with explicit trigger, scope, and reads;
  • action entries for type-script style state transitions;
  • lock entries for spend-boundary predicates;
  • protected, witness, lock_args, and require so verifier-boundary source data and failure points are visible in source;
  • metadata sidecars and ProofPlan records that describe schema, ABI, constraints, runtime requirements, and verifier obligations.
  • builder assumption records and schema-bound transaction-shape validation for pre-signing review.

The wiki uses the same rule throughout: if something is only compiler evidence, it is described as compiler evidence. If something needs a builder-backed CKB transaction, the wiki says so.

First Run

The fastest way to get oriented is to compile the token example:

git clone https://github.com/CellScript-Labs/CellScript.git
cd CellScript
./scripts/cellscript_gate.sh dev
cargo run --locked --bin cellc -- examples/token.cell --target riscv64-elf --target-profile ckb --primitive-strict 0.16 -o /tmp/token.elf
cargo run --locked --bin cellc -- verify-artifact /tmp/token.elf --expect-target-profile ckb

The compile step writes two files:

/tmp/token.elf
/tmp/token.elf.meta.json

The ELF is the executable artifact. The metadata sidecar is the explanation: where the source came from, which profile was used, what schema was produced, and which obligations still need review.

Before You Call It Production

cellc verify-artifact is an important first check, but it is not the whole story. It proves that an artifact and its metadata agree. It does not prove that a concrete CKB transaction can spend the right inputs, serialize the right witness, fit capacity rules, pass dry-run, and commit.

Keep two levels separate:

  • compiler evidence: source, artifact, metadata, and selected policy flags agree;
  • CKB chain evidence: builder-generated transactions were checked on a local CKB chain with cycles, transaction size, capacity, and positive/negative behavior evidence.

Release-facing CKB evidence comes from the repository root:

./scripts/cellscript_gate.sh release

The bundled examples are covered by the current local production evidence suite. The NovaSeal core, Agreement, six planned NovaSeal profiles, and Evolving DOB profile now have current local devnet/source-package readiness evidence. Public or mainnet deployment claims still need their own CellDep, verifier TCB, BTC SPV, RWA/legal, or other external attestations where a profile depends on those facts. The 0.16.1 patch line also closes the token/AMM/launch and NFT first-cell bootstrap examples used by external builders. New external contracts still need their own metadata review, builder evidence, security review, and chain acceptance evidence before they should be called production-ready.

Reference Examples

On this page