Ciphera - Zero Knowledge Appchain

A Bitcoin L2 ZK rollup for privacy preserving transactions. The codebase ascends to Payy Project.

From Payy existing prototype acquired following features:

• Fast proof generation. Runs in under 3 seconds on an iPhone
• Tiny size. UTXO proofs are under 2.8KB

On the Bitcoin side Ciphera rollup features

• "Rollup contract" represented by Script-based Bitcoin multisignature wallet
• Flexible blinded vaults with signers which are generally independant from protocol participants
• Backup transactions for mints

For a detailed description of ZK-rollup architecture, please see the Payy team's whitepaper. Some ideas around combining ZK-rollup with Bitcoin are outlined in this post.

Module	Path	Desc
Contracts	pkg/prover	Rust interface to Bitcoin BDK wallet
RPC	pkg/rpc	RPC common utilities shared across all RPC services
Smirk	pkg/smirk	Sparse merkle tree
ZK-Circuits	fixtures	UltraHonk ZK circuits for proving UTXO, merkle and state transitions
ZK-Primitives	pkg/zk-primitives	ZK primitives used across multiple modules

Running minimal network configuration

Rollup's BDK wallet instance relies on running Bitcoin Core client. Ciphera nodes also depend Electrum RPC for obtaining balances. The Electrum server works as an indexer for mints and is used for broadcasting finalized signed transactions for zk-note burns.

Requirements

There are no strict requirements for Core and Fulcrum versions. Likely readily available version would be enough for running rollup in regtest network.

• Bitcoin Core version v28.0.0
• Fulcrum 1.11.1 (Release)
• zk-musig
• signer

Running Prover and Validator nodes

Here are two commands which allow to launch a toy rollup network locally:

node --mode=validator --rpc-laddr=0.0.0.0:8091 --p2p-laddr=/ip4/127.0.0.1/tcp/5000 --p2p-dial=/ip4/127.0.0.1/tcp/5001 --contract-outpoint=”$BDK WALLET_UTXO” > validator.log 2>&1 &

runs validator. Preferrably, the user has to make one first test run and going further launch validator ahead of prover. On the first run, user may see generated rollup wallet address that has to receive some confirmed coins to be accessible to spend from rollup BDK wallet. With default config expected rollup address is bcrt1p39g0zxwx7vgaul4j9qe99ylhw86zadyxwvzu7kh7q3gw4u5kqhwqxzu60v.

The standard command for mining blocks and allocating subsidy to a single address is given below.

bitcoin-cli -regtest generatetoaddress 101 bcrt1p39g0zxwx7vgaul4j9qe99ylhw86zadyxwvzu7kh7q3gw4u5kqhwqxzu60v

With default private keys and default address these are three outpoints which may be used for running rollup node in regtest after generating first 103 blocks.

e136ea733c2ce10fbed3dfd26d460181d2bcd06e6a19c10cf5066137587c0eda:0
bf67c5712efda058833be82b5f722c1ae446a30bbe46485a2e7eaf6a87954108:0
9f9a559041031eb74668cd0c19338a8fe9d149a50cf90fddd742f5933ac9867b:0

A CLI command for running prover in mock mode.

node --db-path ~/.ciphera/prover/db --smirk-path ~/.ciphera/prover/smirk
--mode=mock-prover --rpc-laddr=0.0.0.0:8092 --p2p-laddr=/ip4/127.0.0.1/tcp/5001 --p2p-dial=/ip4/127.0.0.1/tcp/5000
--contract-outpoint=”$BDK WALLET_UTXO” > prover.log 2>&1 &

Zk-musig will be working much faster if the Risc0 development mode flag is set.

export RISC0_DEV_MODE=1.

Everything altogether in single bash script:

#!/bin/bash
export RISC0_DEV_MODE=1
rm -rf ~/.ciphera/db/* && rm -rf ~/.ciphera/smirk/* && rm -rf ~/.ciphera/prover/db/* && rm -rf ~/.ciphera/prover/smirk/*
RUST_LOG=error ./target/debug/node --mode=validator --rpc-laddr=0.0.0.0:8091 --p2p-laddr=/ip4/127.0.0.1/tcp/5000 --p2p-dial=/ip4/127.0.0.1/tcp/5001 --contract-outpoint=4a7260b3c62c5b406beef99af674934b53536fa0d289b14d5aa18f86947d7b03:0 > validator.log 2>&1 &
RUST_LOG=error ./target/debug/node --db-path ~/.ciphera/prover/db --smirk-path ~/.ciphera/prover/smirk --mode=mock-prover --rpc-laddr=0.0.0.0:8092 --p2p-laddr=/ip4/127.0.0.1/tcp/5001 --p2p-dial=/ip4/127.0.0.1/tcp/5000 --contract-outpoint=4a7260b3c62c5b406beef99af674934b53536fa0d289b14d5aa18f86947d7b03:0 > prover.log 2>&1 &

Tests

cargo test

Note: these tests can take a while to run on your laptop (e.g. more than 20 minutes)

Audit

The ZK-Circuits and Ethereum Contracts have been audited by KALOS. All report findings have been fixed and resolved.

KALOS Audit Report 2024-02-23

Git LFS

We use Git LFS for storing large files (e.g. srs params).

A one-time setup needs to be done for local development:

1. Install git lfs following the instructions at https://git-lfs.com/
2. Inside the zk-rollup root directory, run the following commands:

$ git lfs install
$ git lfs pull

Contributing

We appreciate your interest in contributing to our open-source project. Your contributions help improve the project for everyone.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Security vulnerabilities

We take security issues seriously. If you discover a security vulnerability, we appreciate your assistance in disclosing it to us in a responsible manner. Do not report security vulnerabilities through public issues or forums. Instead, send a full report to hello@polybaselabs.com. We do not have an official bug bounty program but will reward responsibly disclosed vulnerabilities at our discretion.

Reporting Bugs

If you find a bug, please report it by opening an issue. Include as much detail as possible, including steps to reproduce the issue, the environment in which it occurs, and any relevant screenshots or code snippets.

Suggesting Enhancements

We appreciate enhancements! To suggest a feature or enhancement, please open an issue with a detailed description of your proposal. Explain why it is needed and how it would benefit the project.

Submitting Pull Requests

1. Fork the repository
2. Create a new branch (git checkout -b feature/YourFeature)
3. Make your changes
4. Commit your changes (git commit -m 'Add some feature')
5. Push to the branch (git push origin feature/YourFeature)
6. Open a pull request

License

By contributing, you agree that your contributions will be licensed under the same license as the project. For more details, see LICENSE.