RISC Zero各功能模块代码解析

1. 引言

开源代码见：

https://github.com/risc0/risc0（C++ 和 Rust）

2. risc0-build-kernel模块

risc0-build-kernel模块：

用于构建kernels的工具。所谓kernels，包括CPU、CUDA、Metal。
代码见：risc0/build_kernel。

依赖库有：

cc：用于将 C/C++/汇编代码，编译进Rust库或Rust应用中。
directories：为一个小的中间层库，用于为Linux/Windows/macOS等操作系统上的config、cache或其它数据，提供平台指定的标准路径位置。
hex：以十六进制对数据进行编解码。
sha2：SHA2哈希函数，包括：SHA-224、SHA-256、SHA-384 和 SHA-512。
tempfile：管理临时文件和路径。

risc0-build-kernel模块，提供了接口函数：

	pub fn compile(&mut self, output: &str) {
    
    
        for src in self.files.iter() {
    
    
            println!("cargo:rerun-if-changed={}", src.display());
        }
        for dep in self.deps.iter() {
    
    
            println!("cargo:rerun-if-changed={}", dep.display());
        }
        match &self.kernel_type {
    
    
            KernelType::Cpp => self.compile_cpp(output), //直接使用cc::Build
            KernelType::Cuda => self.compile_cuda(output), //使用nvcc
            KernelType::Metal => self.compile_metal(output), //使用xcrun
        }
    }

3. risc0-core模块

risc0-core模块：

RISC Zero的核心类型
主要定义了Babybear域和Goldilocks域。
代码见：risc0/core。

依赖库有：

bytemuck：在数据类型之间安全地执行“位转换（bit cast）”操作。
rand_core：Core 随机数生成器。
rand：随机数生成器，以及其他随机值功能。

4. risc0-circuit-rv32im-sys模块

risc0-circuit-rv32im-sys模块：

为rv32im电路，生成HAL（Hardware Abstraction Layer）代码。
代码见：risc0/circuit/rv32im-sys。

针对不同的模式，会编译生成不同的库文件：

CPU模式：生成libcircuit.a库文件。
Metal模式：生成libmetal_kernel.a库文件。
CUDA模式：生成libcuda_kernel.a库文件。

依赖库有：

risc0-build-kernel模块
risc0-core模块
glob：支持根据Unix shell样式模式匹配文件路径。

risc0-circuit-rv32im-sys模块内的cxx目录、kernels/cuda、kernels/metal目录下的rv32im ZK电路文件，均由Zirgen编译生成。目前Zirgen未开源。

5. risc0-circuit-recursion-sys模块

risc0-circuit-recursion-sys模块：

为递归电路生成HAL（Hardware Abstraction Layer）代码。
代码见：risc0/circuit/recursion-sys。

针对不同的模式，会编译生成不同的库文件：

CPU模式：生成libcircuit.a库文件。
Metal模式：生成libmetal_kernel.a库文件。
CUDA模式：生成libcuda_kernel.a库文件。

依赖库有：

risc0-build-kernel模块
risc0-core模块
glob：支持根据Unix shell样式模式匹配文件路径。

risc0-circuit-recursion-sys模块内的cxx目录、kernels/cuda、kernels/metal目录下的ZK递归电路文件，均由Zirgen编译生成。目前Zirgen未开源。

6. risc0-sys模块

risc0-sys模块：

为RISC Zero生成原生/HAL（Hardware Abstraction Layer）代码。
代码见：rics0/sys。
主要用于生成：
- CUDA库：libcuda_kernels_zkp.a 和 libsupra_ntt.a。
- Metal库：libmetal_kernels_zkp.a。

依赖库有：

risc0-build-kernel模块
cc：用于将 C/C++/汇编代码，编译进Rust库或Rust应用中。
cust：对 CUDA Driver API的高层bindings。
risc0-sppark：该库专注于加速ZKP中计算昂贵的部分，如multi-scalar multiplication（MSM）、number theoretic transform（NTT）、arithmetic hashes等。该库是CUDA/C++模板的集合，可以为一系列有限域和椭圆曲线实例化。

7. risc0-zkvm-platform模块

risc0-zkvm-platform模块：

为RISC Zero zkVM
对RISC Zero zkVM的平台定义，包括：
- IO端口地址：见lib.rs。
- 内存区域：见memory.rs。zkVM单个内存page size为1024字节；单个word size为32字节。
- 底层运行时函数：见syscall.rs。定义了reg_abi（包括REG_ZERO、REG_RA、REG_SP等），以及ecall类型（包括HALT、INPUT、SOFTWARE、SHA、BIGINT）等等。

/// Size of a zkVM machine word in bytes.
/// 4 bytes (i.e. 32 bits) as the zkVM is an implementation of the rv32im ISA.
pub const WORD_SIZE: usize = core::mem::size_of::<u32>();

/// Size of a zkVM memory page.
pub const PAGE_SIZE: usize = 1024;

/// Standard IO file descriptors for use with sys_read and sys_write.
pub mod fileno {
    
    
    pub const STDIN: u32 = 0;
    pub const STDOUT: u32 = 1;
    pub const STDERR: u32 = 2;
    pub const JOURNAL: u32 = 3;
}

依赖的库有：

bytemuck：在数据类型之间安全地执行“位转换（bit cast）”操作。
getrandom：一个用于从系统源检索随机数据的小型跨平台库
libm：为wasm32-unknown-unknown target提供数学支持，如sin、atan2等。

8. risc0-zkvm-receipts模块

risc0-zkvm-receipts模块：

读取receipts.rs内容，写入到lib.rs中。
代码见：risc0/zkvm/receipts

9. risc0-zkp模块

risc0-zkp模块：

为RISC Zero ZKP证明系统核心库
详情参看：
- RISC Zero zk-STARK证明系统代码解析

10. risc0-zkvm-methods模块

risc0-zkvm-methods模块：

用于测试和benchmark的RISC Zero zkVM guest code。
代码见：risc0/zkvm/methods。

有2大类methods：【未包含risc0-zkvm-methods-rand？】

risc0-zkvm-methods-guest：见risc0/zkvm/methods/guest。
risc0-zkvm-methods-std：见risc0/zkvm/methods/std。

均会调用risc0-build模块的embed_methods_with_options函数，来生成methods.rs文件——嵌入为RISC-V构建的methods，供host端依赖项使用。

	let map = HashMap::from([
        (
            "risc0-zkvm-methods-guest",
            GuestOptions {
    
    
                features: vec![],
                use_docker,
            },
        ),
        (
            "risc0-zkvm-methods-std",
            GuestOptions {
    
    
                features: vec!["test_feature1".to_string(), "test_feature2".to_string()],
                use_docker: None,
            },
        ),
    ]);

    embed_methods_with_options(map);

依赖库有：

risc0-build 模块，使用其embed_methods_with_options函数。
risc0-zkvm模块
risc0-zkevm-platform模块
tracing-subscriber：用于实现和组成“tracing”订阅者的实用程序。
serde：序列化、反序列化库。

11. risc0-binfmt模块

risc0-binfmt模块：

RISC Zero二进制格式库
代码见：risc0/binfmt

有：

elf.rs：加载ELF文件来初始化RISC Zero program。
hash.rs：采用Sha256哈希函数。
image.rs：对应某zkVM guest程序的memory image。

sys_state.rs：表示某segment的public state：

/// Represents the public state of a segment, needed for continuations and
/// receipt verification.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct SystemState {
        
        
    /// The program counter.
    pub pc: u32,

    /// The root hash of a merkle tree which confirms the
    /// integrity of the memory image.
    pub merkle_root: Digest,
}

依赖库有：

risc0-zkvm-methods模块
risc0-zkevm-platform模块
risc0-zkp模块
tracing-subscriber：用于实现和组成“tracing”订阅者的实用程序。
serde：序列化、反序列化库。
test-log：替代#[test]属性，支持在运行tests之前，对logging和（或）tracing框架进行初始化。
anyhow：基于std::error::Error构建的灵活具体错误类型库。
elf：解析ELF文件的库。
tracing：应用层的tracing。

RISC Zero program结构为：【对应load_elf函数为：从ELF文件加载初始化RISC Zero program。】

/// A RISC Zero program
pub struct Program {
    
    
    /// The entrypoint of the program
    pub entry: u32,

    /// The initial memory image
    pub image: BTreeMap<u32, u32>,
}

zkVM guest程序的memory image定义为：

/// An image of a zkVM guest's memory
///
/// This is an image of the full memory state of the zkVM, including the data,
/// text, inputs, page table, and system memory. In addition to the memory image
/// proper, this includes some metadata about the page table.
#[derive(Clone, Serialize, Deserialize)]
pub struct MemoryImage {
    
    
    /// Sparse memory memory image as a map from page index to page.
    pub pages: BTreeMap<u32, Vec<u8>>,

    /// Metadata about the structure of the page table
    pub info: PageTableInfo,

    /// Program Counter from [Program] entry point
    pub pc: u32,
}

相应的ImageID计算方式为：

/// Compute and return the ImageID of the specified ELF binary.
#[cfg(not(target_os = "zkvm"))]
pub fn compute_image_id(elf: &[u8]) -> anyhow::Result<risc0_zkp::core::digest::Digest> {
    
    
    use risc0_zkvm_platform::{
    
    memory::GUEST_MAX_MEM, PAGE_SIZE};

    let program = Program::load_elf(elf, GUEST_MAX_MEM as u32)?;
    let image = MemoryImage::new(&program, PAGE_SIZE as u32)?;
    image.compute_id()
}
	/// Compute and return the root merkle entry of this image.
    pub fn compute_root_hash(&self) -> Result<Digest> {
    
    
        let root_page = self
            .pages
            .get(&self.info.root_idx)
            .expect("Missing root page?");
        hash_page_bytes(&root_page[..(self.info.root_addr - self.info.root_page_addr) as usize])
    }

    /// Compute and return the ImageID of this image.
    pub fn compute_id(&self) -> Result<Digest> {
    
    
        Ok(compute_image_id(&self.compute_root_hash()?, self.pc))
    }

/// Compute and return the ImageID of the given `(merkle_root, pc)` pair.
fn compute_image_id(merkle_root: &Digest, pc: u32) -> Digest {
    
    
    SystemState {
    
    
        merkle_root: *merkle_root,
        pc,
    }
    .digest::<Impl>()
}

12. risc0-build模块

risc0-build模块：

为RISC Zero zkVM build工具
代码见：risc0/build

const RUSTUP_TOOLCHAIN_NAME: &str = "risc0";

#[derive(Debug, Deserialize)]
struct Risc0Metadata {
    
    
    methods: Vec<String>,
}
struct Risc0Method {
    
    
    name: String,
    elf_path: PathBuf,
}

依赖库有：

risc0-binfmt模块
risc0-zkevm-platform模块
risc0-zkp模块
serde：序列化、反序列化库。
serde_json：json序列化。
anyhow：基于std::error::Error构建的灵活具体错误类型库。
cargo_metadata：结构化访问cargo metadata的输出。cargo metadata：以 JSON 格式输出包结构和依赖关系信息。
docker-generate：docker文件读写。
tempfile：管理临时文件和路径。

13. risc0-circuit-rv32im模块

risc0-circuit-rv32im模块：

为rv32im的RISC Zero电路
代码见：risc0/circuit/rv32im。
有：
- cpu.rs/cuda.rs/metal.rs：实现了eval_check函数。
- cpp.rs：实现了step_compute_accum、step_verify_accum、step_exec、step_verify_bytes、step_verify_mem等函数。
- layout.rs 和 layout.rs.inc ：定义了code、data和out的layout buffer信息。
- taps.rs、info.rs、poly_ext.rs：为自动生成的代码。

依赖库有：

risc0-core模块
risc0-zkp模块
risc0-zkvm-platform模块
risc0-circuit-rv32im-sys模块
anyhow：基于std::error::Error构建的灵活具体错误类型库。
tracing：应用层的tracing。
rand：随机数生成器，以及其他随机值功能。
cust：对 CUDA Driver API的高层bindings。
metal：Unsafe Rust bindings for the Metal 3D Graphics API。针对Macos的Metal GPU。
rayon：并行库。
criterion：统计驱动的微benchmark库。
test-log：替代#[test]属性，支持在运行tests之前，对logging和（或）tracing框架进行初始化。
tracing-subscriber：用于实现和组成“tracing”订阅者的实用程序。

14. risc0-circuit-recursion模块

risc0-circuit-recursion模块：

为递归的RISC Zero电路
代码见：risc0/circuit/recursion
会下载recursion_zkr.zip文件。配置RECURSION_SRC_PATH环境变量，下载链接为“https://risc0-artifacts.s3.us-west-2.amazonaws.com/zkr/{SHA256_HASH}.zip”。

依赖库有：

risc0-core模块
risc0-zkp模块
risc0-circuit-recursion-sys模块
anyhow：基于std::error::Error构建的灵活具体错误类型库。
tracing：应用层的tracing。
rand：随机数生成器，以及其他随机值功能。
cust：对 CUDA Driver API的高层bindings。
metal：Unsafe Rust bindings for the Metal 3D Graphics API。针对Macos的Metal GPU。
rayon：并行库。
criterion：统计驱动的微benchmark库。
test-log：替代#[test]属性，支持在运行tests之前，对logging和（或）tracing框架进行初始化。
tracing-subscriber：用于实现和组成“tracing”订阅者的实用程序。
bytemuck：在数据类型之间安全地执行“位转换（bit cast）”操作。
zip：支持对zip文件读写。
tracing-forest：保持来自并发任务的跟踪数据之间的上下文一致性
downloader：通过HTTP/HTTPS下载。
sha2：SHA2哈希函数，包括：SHA-224、SHA-256、SHA-384 和 SHA-512。

15. risc0-zkvm模块

risc0-zkvm模块：

为RISC Zero zkVM
代码见：risc0/zkvm。
有：
- benches：benchmark
- examples：包含fib、loop和recursion例子。运行cargo run --example fib --features="prove" -- --iterations 10。
- methods：见risc0-zkvm-methods模块。用于测试和benchmark的RISC Zero zkVM guest code。
- platform：见risc0-zkvm-platform模块。定义了IO端口地址、内存区域和底层runtime函数。
- receipts：见risc0-zkvm-receipts模块。读取receipts.rs内容，写入到lib.rs中。
- src：定义了guest和host以及序列化相关接口。

risc0-zkvm支持如下features：【注意，若想在guest中使用risc0-zkvm，需通过设置default-features = false来禁用"prove" feature。】

Feature	Target(s)	Implies	Description
client	all except rv32im	std	Enables the client API.
cuda		prove, std	Enables CUDA GPU acceleration for the prover. Requires CUDA toolkit to be installed.
disable-dev-mode	all except rv32im		Disables dev mode so that proving and verifying may not be faked. Used to prevent a misplaced `RISC0_DEV_MODE` from breaking security in production systems.
metal	macos	prove, std	Enables Metal GPU acceleration for the prover.
prove	all except rv32im	std	Enables the prover, incompatible within the zkvm guest.
std	all		Support for the Rust stdlib.

依赖库有：

prost-build：使用protoc来解析 .proto 文件。
protobuf-src：集成了C++版本的libprotobuf。
anyhow：基于std::error::Error构建的灵活具体错误类型库。
bytemuck：在数据类型之间安全地执行“位转换（bit cast）”操作。
cfg-if：一个宏，用于根据大量#[cfg]参数以符合人体工程学的方式定义items。结构类似于if-else链，第一个匹配的分支是发出的项。
getrandom：一个用于从系统源检索随机数据的小型跨平台库。
hex：以十六进制对数据进行编解码。
risc0-binfmt模块
risc0-core模块
risc0-zkp模块
risc0-zkvm-platform模块
rrs-lib：构建RISC-V指令集模拟器的库。
semver：解析Cargo风格的语义版本控制。
serde：序列化库。
addr2line：使用gimli用Rust编写的跨平台符号库。
ark-bn254：BN254 pairing-friendly elliptic curve
ark-groth16：Groth16 ZKP系统。
ark-serialize：arkworks生态序列化库。
bincode：结构体与字节码之间的相互二进制转换。
bonsai-sdk模块
bytes：字节码操作相关库。
crypto-bigint：大整数库。
elf：解析ELF文件的库。
lazy-regex：编译时检查的惰性静态正则表达式
num-bigint：大整数库。
num-derive：数字语法扩展
num-traits：通用数学数字traits
prost：对proto2和proto3文件解析库。
rayon：并行库。
risc0-circuit-recursion模块
risc0-circuit-rv32im模块
rustc-demangle：Rust编译器符号解映射。
sha2：SHA2哈希函数，包括：SHA-224、SHA-256、SHA-384 和 SHA-512。
tempfile：管理临时文件和路径。
tracing：应用层的tracing。
typetag：trait对象的序列化和反序列化。
clap：命令行参数解析器。
criterion：统计驱动的微benchmark库。
human-repr：Generate beautiful human representations of bytes, durations, and even throughputs! 即让表示更人性化。
lazy_static：A macro for declaring lazily evaluated statics in Rust.
rand：随机数生成器，以及其他随机值功能。
tracing-forest：保持来自并发任务的跟踪数据之间的上下文一致性。
tracing-subscriber：用于实现和组成“tracing”订阅者的实用程序。
flate2：DEFLATE压缩和解压缩暴露为Read/BufRead/Write流。支持miniz_oxide和多个zlib实现。支持zlib、gzip和原始deflate流。
risc0-zkvm-methods模块。
serde_json：json序列化。
serial_test：支持创建序列化Rust测试。
tar：tar文件读写库
tempfile：管理临时文件和路径。
test-log：替代#[test]属性，支持在运行tests之前，对logging和（或）tracing框架进行初始化。