CKB Script Templates

https://github.com/nervosnetwork/ckb-script-templates
Admin
CKB Script Templates provides a collection of templates for developing, building, and testing native...
Tokens:7,592
Snippets:43
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Set up and generate code coverage reports

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Installs LLVM tools, generates native simulators for contracts, and produces coverage reports in text, HTML, or LCOV formats. Only works on x86_64 Linux and only for contracts created with the 'contract' template.

```bash
make coverage-install
```

```bash
make generate-native-simulator CRATE=<contract_name>
```

```bash
make coverage        # Text report to console
make coverage-html   # HTML report in target/coverage/html/
make coverage-lcov   # LCOV format for CI integration
```

--------------------------------

### Create contract and run coverage

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Complete workflow to create a contract, generate its native simulator, install coverage tools, and run coverage. The coverage runs tests with the 'native-simulator' feature, executing contract code natively on x86_64 instead of in CKB-VM.

```bash
# Create a contract using the default 'contract' template
make generate CRATE=my-contract

# Generate native simulator for it
make generate-native-simulator CRATE=my-contract

# Install tools and run coverage
make coverage-install
make coverage
```

--------------------------------

### Build and test standalone contract

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Build and test the standalone contract crate. The template is designed for use outside a workspace and includes its own test setup with a dedicated tests crate.

```shell
$ cd standalone-first-contract
$ make build
$ make test
$ make check
$ make clippy
```

--------------------------------

### Enter workspace and view tree

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Navigate into the generated workspace and inspect its structure. The tree output shows a standard Rust workspace with a Makefile, a scripts/find_clang helper, and a tests crate containing lib.rs and tests.rs.

```shell
$ cd my-first-contract-workspace
```

```shell
$ tree .
.
├── Cargo.toml
├── Makefile
├── scripts
│   └── find_clang
└── tests
    ├── Cargo.toml
    └── src
        ├── lib.rs
        └── tests.rs

4 directories, 6 files
```

--------------------------------

### Verify changes with make build and make test

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/workspace/AGENTS.md

Run these commands after any changes to verify the project builds and tests pass.

```makefile
make build
make test
```

--------------------------------

### Generate native simulator with CRATE parameter

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Generates a native simulator for a specified subproject. The CRATE parameter must refer to an existing subproject; otherwise the command fails.

```bash
make generate-native-simulator CRATE=<subproject_name>
```

```bash
make generate-native-simulator CRATE=example_crate
```

--------------------------------

### Run contract tests with make test

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Run the contract tests in the prepared tests crate.

```shell
make test
```

--------------------------------

### Generate a contract crate with make generate

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Run `make generate` to create a new contract crate interactively. The command prompts for a project name and generates a Rust contract in the `contracts` folder using the default `contract` template.

```shell
$ make generate
🤷   Project Name: first-contract
🔧   Destination: /tmp/my-first-contract-workspace/contracts/first-contract ...
🔧   project-name: first-contract ...
🔧   Generating template ...
🔧   Moving generated files into: `/tmp/my-first-contract-workspace/contracts/first-contract`...
🔧   Initializing a fresh Git repository
✨   Done! New project created /tmp/my-first-contract-workspace/contracts/first-contract
```

--------------------------------

### Create a new on-chain script with make generate

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/workspace/AGENTS.md

Run from the project root to scaffold a new on-chain script crate. The generated crate is placed in the contracts folder and should target RISC-V with no_std.

```shell
make generate CRATE=on-chain-script-1
```

--------------------------------

### Generate a contract crate with make generate CRATE=second-contract

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Generate a contract crate non-interactively by supplying the `CRATE` parameter. The crate is placed in the `contracts` folder using the default `contract` template.

```shell
$ make generate CRATE=second-contract
🔧   Destination: /tmp/my-first-contract-workspace/contracts/second-contract ...
🔧   project-name: second-contract ...
🔧   Generating template ...
🔧   Moving generated files into: `/tmp/my-first-contract-workspace/contracts/second-contract`...
🔧   Initializing a fresh Git repository
✨   Done! New project created /tmp/my-first-contract-workspace/contracts/second-contract
```

--------------------------------

### Reproducible build with ./scripts/reproducible_build_docker

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Perform reproducible builds using the included docker script. By default it cleans the repository, builds all contracts with locked LLVM & Rust, and tests against a checksum file. Use --update to refresh the checksum file, --no-clean to skip cleaning intermediate files (not recommended), and --proxy to configure a proxy for pulling Rust crates.

```shell
$ ./scripts/reproducible_build_docker               # Clean current repository, used locked LLVM & Rust from a docker container
                                                    # to build all contracts, then test the binaries against a checksum file.

$ ./scripts/reproducible_build_docker --update      # Update the checksum file with new binaries, could be handy when you have
                                                    # made changes to the binaries.

$ ./scripts/reproducible_build_docker --no-clean    # Do not clean intermediate files before building, it is not recommended to
                                                    # use this but when you really know what you are doing, it could help you save
                                                    # some time.

$ ./scripts/reproducible_build_docker --proxy "..." # Setup docker container so it pulls Rust crates using a proxy server
```

--------------------------------

### Customize make generate with TEMPLATE and DESTINATION

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Customize `make generate` with `TEMPLATE` and `DESTINATION` parameters. The first command uses the `atomics-contract` template in the default `contracts` folder; the second changes the destination folder to `crates` while keeping the default template; the third combines both a custom template and a custom destination.

```shell
$ make generate TEMPLATE=atomics-contract                      # generate a Rust contract crate in contracts subfolder, but use atomics-contract template
$ make DESTINATION=crates                                      # generate a crate in crates folder, and still use the default contract template
$ make generate TEMPLATE=c-wrapper-crate DESTINATION=crates    # generate a crate in crates folder, but use c-wrapper-crate template
```

--------------------------------

### Add sparse-merkle-tree with required features

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/workspace/AGENTS.md

Add this dependency to use sparse-merkle-tree in a no_std on-chain script. Enable the with-blake2b-ref and smtc features.

```toml
sparse-merkle-tree = { version = "???", default-features = false, features = ["with-blake2b-ref", "smtc"] }
```

--------------------------------

### Build contracts with make build

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Build contracts with the provided Makefile. The Makefile automatically adds the contract crate to Cargo.toml. Use MODE=debug for a debug build, CUSTOM_RUSTFLAGS="" for a release build without debug assertions, CARGO_ARGS to pass extra cargo arguments, CONTRACT to build a single contract, CLEAN_BUILD_DIR_FIRST=false to keep old binaries, and CLANG to select a specific clang version.

```shell
$ make build
$ make build MODE=debug                   # for debug build
$ make build CUSTOM_RUSTFLAGS=""          # release build without debug assertions
$ make build CARGO_ARGS="--verbose"       # release build with `--verbose` attached to cargo command, you can use other arguments accepted by cargo
$ make build CONTRACT=second-contract     # build a single contract
$ make build CLEAN_BUILD_DIR_FIRST=false  # keep old untouched binaries
$ make build CLANG=clang-17               # use a specific clang version to build C code
```

--------------------------------

### Generate workspace with cargo generate

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Generate a new CKB script workspace using cargo-generate. The first command prompts for a project name; the second shows the same workflow via a shell alias. Output includes the generated project path and a fresh Git repository.

```shell
$ cargo generate gh:nervosnetwork/ckb-script-templates workspace
⚠️   Favorite `gh:nervosnetwork/ckb-script-templates` not found in config, using it as a git repository: https://github.com/nervosnetwork/ckb-script-templates.git
🤷   Project Name: my-first-contract-workspace
🔧   Destination: /tmp/my-first-contract-workspace ...
🔧   project-name: my-first-contract-workspace ...
🔧   Generating template ...
🔧   Moving generated files into: `/tmp/my-first-contract-workspace`...
🔧   Initializing a fresh Git repository
✨   Done! New project created /tmp/my-first-contract-workspace
```

```shell
$ alias create-ckb-scripts="cargo generate gh:nervosnetwork/ckb-script-templates workspace"
$ create-ckb-scripts
⚠️   Favorite `gh:nervosnetwork/ckb-script-templates` not found in config, using it as a git repository: https://github.com/nervosnetwork/ckb-script-templates.git
🤷   Project Name: my-first-contract-workspace
🔧   Destination: /tmp/my-first-contract-workspace ...
🔧   project-name: my-first-contract-workspace ...
🔧   Generating template ...
🔧   Moving generated files into: `/tmp/my-first-contract-workspace`...
🔧   Initializing a fresh Git repository
✨   Done! New project created /tmp/my-first-contract-workspace
```

--------------------------------

### Add ckb-hash with ckb-contract feature

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/workspace/AGENTS.md

Add this dependency to use blake2b in a no_std on-chain script. The ckb-contract feature is required.

```toml
ckb-hash = { version = "???", default-features = false, features = ["ckb-contract"]}
```

--------------------------------

### Generate standalone contract with cargo generate

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/README.md

Generate a standalone contract crate using cargo generate. The command prompts for a project name and creates a new project in the specified destination. The output shows the generation steps and the final project location.

```shell
$ cargo generate gh:nervosnetwork/ckb-script-templates standalone-contract
⚠️   Favorite `gh:nervosnetwork/ckb-script-templates` not found in config, using it as a git repository: https://github.com/nervosnetwork/ckb-script-templates.git
🤷   Project Name: standalone-first-contract
🔧   Destination: /tmp/standalone-first-contract ...
🔧   project-name: standalone-first-contract ...
🔧   Generating template ...
🔧   Moving generated files into: `/tmp/standalone-first-contract`...
🔧   Initializing a fresh Git repository
✨   Done! New project created /tmp/standalone-first-contract
```

--------------------------------

### Configure ckb-std default_alloc! with fixed and dynamic heap sizes

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/workspace/AGENTS.md

Default memory allocation configuration used by ckb-std. It sets a 16KB fixed heap, a 1.2MB dynamic heap (rounded to 16-byte alignment), and a 64-byte minimum memory block. The heap is a static buffer inside .bss of the ELF.

```rust
// * 16KB fixed heap
// * 1.2MB(rounded up to be 16-byte aligned) dynamic heap
// * Minimal memory block in dynamic heap is 64 bytes
ckb_std::default_alloc!(16384, 1258306, 64);
```

--------------------------------

### Add ckb-types with default-features disabled

Source: https://github.com/nervosnetwork/ckb-script-templates/blob/main/workspace/AGENTS.md

Add this dependency to use ckb-types in a no_std on-chain script. Set default-features to false.

```toml
ckb-types = { package = "ckb-gen-types", version = "???", default-features = false }
```
Tokens:
Raw