Zero Knowledge Proofs Toolkit for CKB
(a.k.a. zkp-toolkit-ckb)
Zero-knowledge proofs toolkit for CKB, empowering the community with the cutting-edge techniques of zero-knowledge proofs to develop all kinds of decentralized applications.
The project is going to bridge the gap of cryptographic engineering between thriving academic research and aspiring dAPPs developers, by providing multiple zkp schemes and curve options, a more user-friendly interface, many useful gadget libraries, and many more tutorials and examples.
Besides, it provides smart contracts that run as zero-knowledge proof verifiers on the Nervos CKB chain. CKB developers and users can implement various complex zero-knowledge verification processes through the simplest contract invocation. Cooperate with the core zkp-toolkit to complete off-chain prove and on-chain verify.
This project is also known as zkp-toolkit-ckb and is supported by the Nervos Foundation. Check out the original proposal and grant announcement.
The following document is more focused on CKB smart contracts. Check this doc for more details on zkp-toolkit usage and features.
An early runnable version of the toolkit with basic features.
A contract for verification is deployed on the ckb chain. The prover and the verifier know where the contract is deployed.
Ensure the version of rustc is not lower than 1.42 and use stable version of toolchain.
Install the CKB contract development framework capsule. Access the wiki page for more details about capsule
.
cargo install ckb-capsule
Deploy a ckb dev chain if you need to deploy the contract to the blockchain. See https://docs.nervos.org/dev-guide/devchain.html for guidance.
You can choose to build the contract in dev mode or release mode like Cargo. The product under release mode is suitable for deployment with a reasonable size and execution consumption, and, debug!
macro is disabled. Dev mode product allows you to use debug!
macro to print logs in ckb log, but on the cost of larger binary size and execution cycles. The product resides in ./ckb-contracts/build/[release|debug]/universal_groth16_verifier.
ATTENTION:
capsule
commands should be executed at the project root.# At ckb-contracts directory.
# Dev mode, enable debug! macro but result in bloated size.
cd ckb-contracts
capsule build
# Release mode. Slim, no outputs in the logs.
capsule build --release
debug!
macro in release modeIn ckb-std
version 0.7.2 and newer, debug!
macro is disabled in release mode. If you still want to enable debug!
macro in release mode, insert debug-assertions = true
under [profile.release]
in ckb-contracts/Cargo.toml
.
A simplified, one-time blockchain context is used in the test environment using ckb-tool crate. Needless to setup an authentic blockchain and run a ckb node, one can simply send a transaction to invoke the contract and checkout if the contract works as expected.
Go to ./cli and generate a vk file and a proof file using ckb-zkp's command line utility.
Use groth16 scheme & bls12_381 curve:
Complete trusted-setup:
# ./cli
cargo run --bin setup groth16 bls12_381 hash
Prove the secret string.
# ./cli
cargo run --bin zkp-prove groth16 bls12_381 hash iamsecret
When successful, it will create a proof file at proof_files.
(Optional) Do the verification.
# ./cli
cargo run --bin zkp-verify proof_files/groth16-bls12_381-hash.proof.json
Check supported schemes and curves:
# ./cli
cargo run --bin setup
cargo run --bin zkp-prove
cargo run --bin zkp-verify
See cli document for further help.
ATTENTION:
--release
flag, you should run tests with CAPSULE_TEST_ENV=release
.--test-threads 1
after --
is used to ensure debug!
outputs print in order.#[ignore]
attribute (By remove the leading double slants //
) before a test function to omit during the testing. Or specify the test function name to filter others out.# At ckb-contracts/bench-tests directory root
# Dev mode contracts.
cargo test -- --nocapture --test-threads 1
# Release mode contracts.
CAPSULE_TEST_ENV=release cargo test -- --nocapture
# Specify a test name `test_groth16` that you want to execute
CAPSULE_TEST_ENV=release cargo test test_groth16 -- --nocapture
Capsule
brings out-of-box contract deploying and migrating. It works for development and test on dev chain. To deploy a contract you have just cooked, you need:
capsule
uses ckb-cli to interact with ckb client.When everything needed is met, you should theoretically be able to deploy the contract. Use the command below to launch the transaction, and note that commonly the <ADDRESS>
is a 46-bit alphanumeric string (Starting with ckt1
if you use a test net or dev chain).
# At ckb-contracts directory root
capsule deploy --address <ADDRESS>
No ready-to-use gear for invoking a contract on a real chain. Use ckb-cli, or an SDK to build a transaction to invoke the contract on-chain.
capsule
itself (Temporary usage)You can use the master branch of capsule
and the following commands to track the panics.
# At ckb-contracts directory root
RUST_LOG=capsule=trace capsule deploy --address <ADDRESS>
In Nervos ckb, one should pay for data storage, transaction fees and computer resources. Paying for data storage means, one needs to pay a number of ckb tokens in direct proportion to the size of the transaction he raises. Paying for computer resources means one should pay extra ckbs based on the amount of computer resources that are used to verify a transaction. The computer resources are measured as cycles.
On the other hand, On mainnet Lina, the value of MAX_BLOCK_BYTES
is 597_000
and MAX_BLOCK_CYCLES
is 3_500_000_000
.
For these reasons, we take contract binary size and execution cost both into consideration.
The deployer should pay for storing his contract on-chain. The larger the binary is, the more ckb tokens will be spent for deployment. So several compiling options are analyzed to reduce the contract binary size.
opt-level
codegen-units
To use LTO, opt-level
and codegen-units
, modify Cargo.toml:
# File: ckb-contracts/Cargo.toml
[profile.release]
overflow-checks = true
# lto: true, "thin", false(default)
lto = true
# opt-level: 0, 1, 2, 3(default), "s", "z"
opt-level = "z"
# codegen-units: greater than 0, default 16
codegen-units = 1
To strip the binary, use rustflags = "-C link-arg=-s"
in cargo config, which is a default option in Capsule with release compiling mode.
We will not try to explain what each option means (Explained in The Cargo Book), but list the size and running cost of the contract binaries under different combinations of these building options.
Test setup:
secbit/ckb-zkp-capsule:2021-02-17
to build and test and measure running costs;overflow-checks = true
and panic = 'abort'
.LTO | opt-level |
codegen-units |
Binary size(Byte) | Execution cost (cycles) |
---|---|---|---|---|
not set | not set | not set | 192,152 | 90,944,391 |
true |
not set | not set | 172,976 | 93,392,615 |
true |
"s" |
not set | 107,440 | 151,462,521 |
true |
"z" |
not set | 70,576 | 191,976,741 |
true |
"z" |
1 |
58,288 | 195,535,979 |
Here comes a rough result:
opt-level = "z"
, codegen-units = 1
and panic = "abort"
for minimum binary size, at the cost of a higher cycle consumption.Currently, we use different curves in proving and verifying, so we performed a simple benchmark on execution costs separately.
Test setup:
LTO = true
, codegen-units = 1
, panic = "abort"
, overflow-checks = true
, opt-level = "z"
;secbit/ckb-zkp-capsule:2021-02-17
to build and test and measure running costs;Curve | Binary size(Byte) | Execution cost (cycles) |
---|---|---|
bn_256 | 91,056 | 796,836,045 |
bls12_381 | 91,056 | 1,908,755,330 |
JubJub | 74,672 | 695,621,515 |
Baby_JubJub | 74,762 | 691,819,058 |
Currently, we use different schemes in proving and verifying, so we performed a simple benchmark on execution costs separately.
Test setup:
LTO = true
, codegen-units = 1
, panic = "abort"
, overflow-checks = true
, opt-level = "z"
;secbit/ckb-zkp-capsule:2021-02-17
to build and test and measure running costs;Scheme | Binary size(Byte) | Execution cost (cycles) |
---|---|---|
Groth16 | 58,288 | 195,535,979 |
Bulletproofs | 91,056 | 796,836,045 |
Marlin | 132,016 | 500,725,146 |
Spartan (nizk) | 91,056 | 1,085,652,230 |
Spartan (snark) | 119,728 | 1,911,833,747 |
CLINKv2 (ipa) | 82,864 | 508,330,342 |
CLINKv2 (kzg10) | 82,864 | 213,212,113 |
We have accomplished the main goal we set for the Milestone-I of the zkp-toolkit-ckb, which was a simple on-chain verifier for CKB. The proof-of-concept smart contract code shows that we can make a usable zkp verifier for CKB with pure Rust without modifying the underlying chain. This also gives us a baseline on the performance of zkp verifiers for CKB-VM.
We'll implement more zkp verifiers in the following milestones, looking at reducing the binary size and execution cost, as well as the best practice to integrate with other contracts.
capsule
complained error: Can't found capsule.toml, current directory is not a project
All the commands executed by capsule
should be executed under the project root.
Modify ckb's configuration as below:
# File: ckb.toml of your chain.
[logger]
filter = "info,ckb-script=debug"
Make sure you build and test the contract in the same mode (dev or release, specified by flag --release
).
# At ckb-contracts directory root
capsule build && cargo test -p tests --tests -- --nocapture --test-threads 1
# Or
capsule build --release && CAPSULE_TEST_ENV=release cargo test -p tests --tests -- --nocapture
As capsule executes building and testing in docker, the absolute path may not work as expected, so use relative path. And currently, the Capsule (nervosnetwork/capsule) mount the whole project folder into docker, so any relative location inside the project folder is allowed.
In the nervosnetwork/capsule
, capsule
mounts the project folder into the container with path /code. But in the main source nervosnetwork/capsule
, capsule
may only mount the contract folder into the container. As docker is used, the absolute path is not recommended.
The concept and intruduction of cycles can be found here.
This project is still under active development and is currently being used for research and experimental purposes only, please DO NOT USE IT IN PRODUCTION for now.
This project is licensed under either of
at your option.