{"id":18674157,"url":"https://github.com/nervosnetwork/ckb-contract-guidelines","last_synced_at":"2026-03-07T01:02:16.114Z","repository":{"id":97374520,"uuid":"316407955","full_name":"nervosnetwork/ckb-contract-guidelines","owner":"nervosnetwork","description":null,"archived":false,"fork":false,"pushed_at":"2020-12-11T01:48:45.000Z","size":132,"stargazers_count":10,"open_issues_count":2,"forks_count":2,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-12T01:55:32.998Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nervosnetwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-11-27T05:26:07.000Z","updated_at":"2024-09-06T09:23:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"b1b7334e-864f-456a-be68-a8811e89385c","html_url":"https://github.com/nervosnetwork/ckb-contract-guidelines","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nervosnetwork/ckb-contract-guidelines","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nervosnetwork%2Fckb-contract-guidelines","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nervosnetwork%2Fckb-contract-guidelines/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nervosnetwork%2Fckb-contract-guidelines/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nervosnetwork%2Fckb-contract-guidelines/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nervosnetwork","download_url":"https://codeload.github.com/nervosnetwork/ckb-contract-guidelines/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nervosnetwork%2Fckb-contract-guidelines/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30204452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T09:17:44.694Z","updated_at":"2026-03-07T01:02:16.053Z","avatar_url":"https://github.com/nervosnetwork.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ckb-contract-guidelines\n\nThis repository provides guidelines for writing secure CKB smart contracts. It consists of guidelines, or recommendations kept in this README file, as well as sample C and Rust based smart contracts organized following the guidelines.\n\nNote we still recommend a full code audit for any smart contracts deployed to CKB, even though you might have followed all the guidelines here. The purpose of this repository, is to put together some low hanging fruits that can be done before a security audit, to make sure the code is already in a high quality state, thus minimizing efforts required in a formal audit.\n\n# Guideline Version 1\n\n## Rule 1: 100% test coverage\n\nAll smart contracts should have 100% test coverage in terms of both code lines and branches. If you add a line of code, you must make sure there is a test covering the code.\n\nSince coveraging tooling for RISC-V is still in immature phase, several different methodologies can be leveraged. The smart contract author is free to pick any solution.\n\n## Rule 2: Multiple execution environment for tests\n\nEach test case should be executed in all of the following environment:\n\n1. Normal CKB-VM as used in CKB\n2. At least 20 runs of CKB-VM running in [chaos mode](https://github.com/nervosnetwork/ckb-vm/pull/118)\n3. Native x64 environment for gathering test coverage\n4. (For C based smart contract only) Native x64 environment with the latest stable version of [LLVM Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) enabled\n5. (For C based smart contract only) Native x64 environment with the latest stable version of [LLVM Address Sanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) enabled\n\n# How To Gather Code Coverage Data\n\nThere are several ways to gather code coverage data for smart contracts.\n\n## Native Simulators\n\nSmart contracts can be coded against the [publicly defined set of APIs](https://github.com/nervosnetwork/ckb-c-stdlib/blob/23c85c7588b56f29f15dc7002b2e485d0e6df251/ckb_syscall_apis.h). It's okay to build abstractions on top of the APIs, such as [checked functions in C](https://github.com/nervosnetwork/ckb-c-stdlib/blob/23c85c7588b56f29f15dc7002b2e485d0e6df251/ckb_syscalls.h#L11-L126). Rust might also have its own abstractions. However the defined APIs must be the sole way a smart contract interacts with CKB, no other ways of making syscalls are allowed. For example, a smart contract shall not make calls to [ckb_load_cell_data_as_code](https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0009-vm-syscalls/0009-vm-syscalls.md#load-cell-data-as_code), only the wrapped [ckb_dlopen2](https://github.com/nervosnetwork/ckb-c-stdlib/blob/master/ckb_syscall_apis.h#L36-L38) can be used.\n\nAs a result, smart contracts following above rules can be compiled to x64 native binary by linking against [ckb-x64-simulator](https://github.com/nervosnetwork/ckb-x64-simulator). The simulator provides native implementations for all the publicly defined APIs above. Hence for each smart contract, we can have 2 binaries:\n\n* A RISC-V version that is runnable in CKB-VM\n* A native x64 version for test coverage and sanitizing purposes.\n\nThe benefit here, is that all existing toolings on x64 platform can be leverage on the smart contract code. For example, gcov can be used for gathering code coverage data, LLVM sanitizers can be used to discover potential vulnerabilities in C based smart contracts.\n\nIn this repository you can find smart contracts tested in this solution.\n\n## Special organization within smart contracts\n\nSmart contracts themselves can be better organized, so test cases can be written on the code directly without CKB-VM environment. [This project](https://github.com/nervosnetwork/force-bridge-eth/blob/2d16aa4ab459ec00d98aa94d110d8ec5791855c8/ckb-contracts/contracts/eth-bridge-typescript/src/main.rs) serves as a decent example in this category.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnervosnetwork%2Fckb-contract-guidelines","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnervosnetwork%2Fckb-contract-guidelines","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnervosnetwork%2Fckb-contract-guidelines/lists"}