Skip to content

guide.md

Latest commit

 

History

History
54 lines (39 loc) · 3 KB

guide.md

File metadata and controls

54 lines (39 loc) · 3 KB
Raw

ckb-std Developer Guide

This document provides a guide for developers and AI agents on how to use ckb-std.

Compilation

All projects with ckb-std should target RISC-V (rv64imcb) and require no_std.

The recommended compilation options for Rust are as follows:

-C target-feature=+zba,+zbb,+zbc,+zbs -C passes=lower-atomic --target=riscv64imac-unknown-none-elf --release -C debug-assertions

This is already specified by the scaffold ckb-script-templates.

Features

  • calc-hash, supports the blake2b hash function
  • allocator, a basic memory allocator
  • native-simulator, the native simulator of ckb-std that lets on-chain scripts run on native machines
  • dlopen-c, dynamic library support on ckb-vm
  • build-with-clang, uses clang as the compiler when C is used
  • libc, for compiling with C. Normally works with dlopen-c.
  • dummy-atomic, a stub for atomic operations
  • log, supports logging
  • type-id, Type ID support

Some notes:

  • dlopen-c is to support dynamic libraries on ckb-vm. However, it is not needed nowadays, since this can be done with the exec or spawn syscalls. Thus, no C compiler is needed, and the libc and build-with-clang features can be disabled.
  • dummy-atomic works with the Rust -C target-feature-a option. Since we now have -C passes=lower-atomic, it is also not needed.

The recommended feature combination is allocator, calc-hash, and ckb-types. Add more as required.

Syscalls

Detailed information about syscalls:

When using syscalls, first use the high_level module. If it doesn't meet your requirements, use the syscalls module instead. When using syscalls, use the predefined types in ckb-types, such as Script, WitnessArgs, Transaction, CellInput, CellOutput, etc, instead of parsing molecule from scratch.

IMPORTANT: Overview of transaction structure: https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0022-transaction-structure/0022-transaction-structure.md

When the stub-syscalls feature is enabled, these syscalls can be mocked, which is useful for unit tests and fuzzing tests.

Log

Logging is supported by enabling the log feature. Call logger::init in the entry first, and then call the logger functions.

It is the most useful debugging method for AI agents. Enable log by default, and add log statements as required. When troubleshooting, add logs to suspicious locations first and then verify. Some libraries might need the environment variable RUST_LOG=info to enable outputs. When using log, the first step is to make sure the log can be output properly.

Others

Like a traditional C program, on-chain scripts accept argc/argv via the env module.

Use the asserts module if the failure is unrecoverable.