ZKsync OS is a new state transition function implementation that enables multiple execution environments (EVM, EraVM, Wasm, etc.) to operate within a unified ecosystem. It is implemented in Rust and compiled into a RISC-V binary, which can later be proven using the zksync-airbender.
The most recent documentation can be found here:
The project contains the following crates (the list is not complete):
- zk_ee - execution environment
- zksync_os - operating system - that can handle multiple execution environments. Compiled into RISC-V.
- zksync_os_runner - allows running programs on zksync_os using RISC-V simulator.
- basic_system - basic implementation of zk_ee::system and system functions
- basic_bootloader - implementation of bootloader and main execution loop
- evm_interpreter - EVM execution environment
- forward_system - implementation for "forward" running (sequencing)
Run the following commands to prepare your environment (only needed once):
rustup target add riscv32i-unknown-none-elf
cargo install cargo-binutils && rustup component add llvm-tools-preview
ZKsync OS should be built for 2 targets:
- your platform, this will be used in the sequencer to execute blocks
- RISC-V, this is a program that will be proved using RISC-V prover
cargo build --release
Navigate to the zksync_os directory and run:
./dump_bin.sh --type for-tests
To run the integration tests you should build ZKsync OS first, see the building section above
Integration tests are located in the tests folder. You can run them as regular cargo tests.
For example, to run basic tests that execute a few ERC-20 calls using different tx types use:
cargo test --release -p transactions -- --nocapture
You can run proving by enabling the e2e_proving feature while running tests, for example:
cargo test --release --features e2e_proving -p transactions -- --nocapture
Generating the CRS File
You can set the CSR_READS_DUMP env variable to dump CSR reads for proving (witnesses) and then run any test.
It will create a CSR file with the path CSR_READS_DUMP.
Using the Prover CLI
The Prover CLI is part of the zksync-airbender repository, located in the tools/cli directory.
Run the following from the zksync-airbender repository:
mkdir zkee_output
cargo run --profile cli --no-default-features -p cli prove --bin ../zksync-os/zksync_os/for_tests.bin --input-file ${CSR_READS_DUMP} --output-dir zkee_output
This generates multiple proof files in the zkee_output directory. For recursion (compressing proofs into fewer files), refer to the instructions in the zksync-airbender repository.
- Build ZKsync OS
- Run anvil-zksync
- Send transactions
- Tell prover cli to get the witnesses from anvil-zksync
Anvil ZKsync
Run anvil-zksync from GitHub - IMPORTANT - make sure to use the zkos-dev branch.
cargo run -- --use-zkos --zkos-bin-path=../zksync-os/zksync_os/for_tests.binSend transactions
You can use any tool (for example, forge) to send transactions to the anvil binary.
Tell prover cli to get the witnesses from anvil-zksync
From the zksync-airbender repo:
cargo run --no-default-features -- run --bin ../zksync-os/zksync_os/for_tests.bin --input-rpc http://localhost:8012 --input-batch 15
You can get the witness via the RPC call, where you pass the batch ID as a parameter:
http POST http://127.0.0.1:8011 \
Content-Type:application/json \
id:=1 jsonrpc="2.0" method="zkos_getWitness" params:='[1]'
ZKsync OS is distributed under the terms of either
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/blog/license/mit/)
at your option.