Repository files navigation

(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 corezkp-toolkit to complete off-chain prove and on-chain verify.

This project is also known aszkp-toolkit-ckb and is supported by the Nervos Foundation. Check out theoriginal proposal andgrant announcement.

The following document is more focused on CKB smart contracts.Check this doc for more details on zkp-toolkit usage and features.

• More schemes: Marlin, Spartan, CLINKv2, Libra, Hyrax, and aSVC
• Efficient ECC for zkSNARKs: Jubjub and BabyJubJub
• More useful gadgets: sha256, blake2s, Poseidon, rescue, and Merkle tree
• More examples
• Many new zkp verifiers on CKB-VM
• Benchmarks on curves, schemes, and CKB-VM

An early runnable version of the toolkit with basic features.

• Schemes: Groth16 and Bulletproofs with R1CS
• Curves: BN256 and BLS12-381
• Gadgets: basic gadgets
• Smart contracts: Groth16 verifier on CKB-VM

• ckb-zkp
  • What's new?
    • Milestone #2 (2020/12/20)
    • Milestone #1 (2020/07/10)
  • Table of contents
  • How does this contract help to verify a zero-knowledge proof?
  • Prerequisites
  • Build contracts
    • Enabledebug! macro in release mode
  • Tests
    • Run zkp-toolkit cli tests
    • Run CKB contacts tests
  • Deployment
    • Invoking the contract on-chain
    • Debugging thecapsule itself (Temporary usage)
  • Optimizations & Benchmarks
    • Binary size optimization
    • Curve benchmark
    • Disabling ckb-zkp's crate features of curves for the verifier contract
    • Further optimizations
  • Troubleshooting
    • capsule complainederror: Can't found capsule.toml, current directory is not a project
    • I can't see any output of my contract in the CKB's log on dev chain.
    • The test can't find contract binary.
    • How is the project mounted into the Docker container?
    • What does "cycles" mean in Nervos ckb?
  • Acknowledgement
  • Security
  • License

A contract for verification is deployed on the ckb chain. The prover and the verifier know where the contract is deployed.

1. The prover completes the trusted-setup, and generates a proof (in the form of a file);
2. The prover sends a transaction that creates some new cells(aka. utxo, but carrying some data), with one containing the proof and vk files and using the previous contract as its type script (which means, this cell should pass the verification of the contract logic);
3. The miner collects the transaction and executes the assigned contract. All the cells in a transaction assigning one contract as type script are verified by the contract logic. Otherwise, the transaction is rejected by the miner.
4. The prover goes public with the transaction, the proof, the vk file, and the verification contract address that is needed to do the verification.
5. The verifier is able to verify the proof using the information provided by the prover.

1. Ensure the version of rustc isnot lower than 1.42 and usestable version of toolchain.

2. Install the CKB contract development frameworkcapsule. Access thewiki page for more details aboutcapsule.

   cargo install ckb-capsule

3. Deploy a ckb dev chain if you need to deploy the contract to the blockchain. Seehttps://docs.nervos.org/dev-guide/devchain.html for guidance.

You can choose to build the contract indev mode orrelease 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 usedebug! 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:

• all thecapsule commands should be executed at the project root.
• Users in mainland China can add thetuna's mirror of crates.io in the file./cargo/config for a faster download of dependencies.

# At ckb-contracts directory.# Dev mode, enable debug! macro but result in bloated size.cd ckb-contractscapsule build# Release mode. Slim, no outputs in the logs.capsule build --release

Inckb-std version 0.7.2 and newer,debug! macro is disabled in release mode. If you still want to enabledebug! macro inrelease mode, insertdebug-assertions = true under[profile.release] inckb-contracts/Cargo.toml.

A simplified, one-time blockchain context is used in the test environment usingckb-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.

1. 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:

   1. Complete trusted-setup:

      # ./clicargo run --bin setup groth16 bls12_381hash

   2. Prove the secret string.

      # ./clicargo run --bin zkp-prove groth16 bls12_381hash iamsecret

      When successful, it will create a proof file at proof_files.

   3. (Optional) Do the verification.

      # ./clicargo run --bin zkp-verify proof_files/groth16-bls12_381-hash.proof.json

   Check supported schemes and curves:

   # ./clicargo run --bin setupcargo run --bin zkp-provecargo run --bin zkp-verify

   Seecli document for further help.

ATTENTION:

• If you build the contract with--release flag, you should run tests withCAPSULE_TEST_ENV=release.
• The flag--test-threads 1 after-- is used to ensuredebug! outputs print in order.
• In the file./tests/src/tests.rs, you can uncomment the#[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.
• Or you can specify a test function name, and perform only one test.

# At ckb-contracts/bench-tests directory root# Dev mode contracts.cargotest -- --nocapture --test-threads 1# Release mode contracts.CAPSULE_TEST_ENV=release cargotest -- --nocapture# Specify a test name `test_groth16` that you want to executeCAPSULE_TEST_ENV=release cargotest 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:

• A running ckb client on the local machine or the net.
• A ckb-cli executable.capsule uses ckb-cli to interact with ckb client.
• An account with sufficient CKBs for deployment (1 Byte of contract binary will consume 1 CKB. The transaction body will also take some extra CKBs, but not much). This account should be imported into ckb-cli.
• A deployment manifest./ckb-contracts/deployment.toml, which assigns the contract binary and cell lock-arg.

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 withckt1 if you use a test net or dev chain).

# At ckb-contracts directory rootcapsule deploy --address<ADDRESS>

No ready-to-use gear for invoking a contract on a real chain. Use ckb-cli, or anSDK to build a transaction to invoke the contract on-chain.

You can use themaster branch ofcapsule and the following commands to track the panics.

# At ckb-contracts directory rootRUST_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 ascycles.

On the other hand,On mainnet Lina, the value ofMAX_BLOCK_BYTES is597_000 andMAX_BLOCK_CYCLES is3_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.

• To build in release mode, this is enabled by default.
• LTO
• Strip
• opt-level
• codegen-units

To use LTO,opt-level andcodegen-units, modifyCargo.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 16codegen-units =1

To strip the binary, userustflags = "-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 inThe Cargo Book), but list the size and running cost of the contract binaries under different combinations of these building options.

Test setup:

• Release mode;
• stripped;
• usingsecbit/ckb-zkp-capsule:2021-02-17 to build and test and measure running costs;
• using scheme groth16 and curve bn_256;
• ckb-std version 0.7.2;
• ckb-tool and ckb-testtool version 0.2.2;
• Default profile setting:overflow-checks = true andpanic = 'abort'.

Here comes a rough result:

• Generally, size decreasing results to execution cost increasing.
• Enabling LTO, useopt-level = "z",codegen-units = 1 andpanic = "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:

• Release mode;
• stripped;
• Profile:LTO = true,codegen-units = 1,panic = "abort",overflow-checks = true,opt-level = "z";
• usingsecbit/ckb-zkp-capsule:2021-02-17 to build and test and measure running costs;
• using scheme bulletproofs (it can use all curves);
• ckb-std version 0.7.2;
• ckb-tool and ckb-testtool version 0.2.2.

Currently, we use different schemes in proving and verifying, so we performed a simple benchmark on execution costs separately.

Test setup:

• Release mode;
• stripped;
• Profile:LTO = true,codegen-units = 1,panic = "abort",overflow-checks = true,opt-level = "z";
• usingsecbit/ckb-zkp-capsule:2021-02-17 to build and test and measure running costs;
• using curve bn_256 (it can use all schemes);
• ckb-std 0.7.2;
• ckb-tool and ckb-testtool version 0.2.2.

We have accomplished the main goal we set for the Milestone-I of thezkp-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 andexecutioncost, as well as the best practice to integrate with other contracts.

All the commands executed bycapsule 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 youbuild and test the contract in the same mode (dev or release, specified by flag--release).

# At ckb-contracts directory rootcapsule build&& cargotest -p tests --tests -- --nocapture --test-threads 1# Orcapsule build --release&& CAPSULE_TEST_ENV=release cargotest -p tests --tests -- --nocapture

As capsule executes building and testing in docker, the absolute path may not work as expected, souse 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 thenervosnetwork/capsule,capsule mounts the project folder into the container with path/code. But in the main sourcenervosnetwork/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 foundhere.

• Many, many thanks tojjy, a developer ofnervosnetwork, for his selfless help and advice on this project.

This project is still under active development and is currently being used for research and experimental purposes only, pleaseDO NOT USE IT IN PRODUCTION for now.

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

at your option.