diff --git a/README.md b/README.md index 9c4ec1a89..31ffe4ea7 100644 --- a/README.md +++ b/README.md @@ -17,13 +17,19 @@ zkMIPS is the industry's first zero-knowledge proof virtual machine supporting t ## Why MIPS? -* MIPS is stable and comprehensive and has an established ecosystem and a great compatibility, like Optimizm Fraud proof VM -* MIPS32r2 vs RV32IM -> * J/JAL series instructions have a jump range of up to 256MiB -> * Rich bit manipulation instructions -> * More conditional selection instructions, MOVZ, MOVN etc. +**MIPS32r2 is more consistent and offers more complex opcodes** + +* The J/JAL instructions support jump ranges of up to 256MiB, offering greater flexibility for large-scale data processing and complex control flow scenarios. +* MIPS32r2 has rich set of bit manipulation instructions and additional conditional move instructions (such as MOVZ and MOVN) that ensure precise data handling. +* MIPS32r2 has integer multiply-add/sub instructions, which can improve arithmetic computation efficiency. +* MIPS32r2 has SEH and SEB sign extension instructions, which make it very convenient to perform sign extension operations on char and short type data. + +**MIPS32r2 has a more established ecosystem** + +* All instructions in MIPS32r2, as a whole, have been very mature and widely used for more than 20 years. There will be no compatibility issues between ISA modules. And there will be no turmoil caused by manufacturer disputes. +* MIPS has been successfully applied to Optimism's Fraud Proof VM ## Acknowledgements The zkMIPS draws inspiration from the following projects, which represents the cutting-edge zero-knowledge proof systems. - [Plonky3](https://github.com/Plonky3/Plonky3): zkMIPS proving backend is based on Plonky3. -- [SP1](https://github.com/succinctlabs/sp1): zkMIPS recursion compiler, circuit builder, precompiles originate from SP1. \ No newline at end of file +- [SP1](https://github.com/succinctlabs/sp1): zkMIPS circuit builder, recursion compiler, and precompiles originate from SP1. diff --git a/docs/src/design/arithmetization.md b/docs/src/design/arithmetization.md index 5a1afe0c3..f10a58709 100644 --- a/docs/src/design/arithmetization.md +++ b/docs/src/design/arithmetization.md @@ -20,7 +20,7 @@ These constraints utilize low-degree polynomials for efficient proof generation/ ## AIR Implementation in zkMIPS Chips Having introduced various chip/table structures in zkMIPS, we note that building a chip involves: -- ​Matrix Population - Filling values into a matrix structure. +- Matrix Population - Filling values into a matrix structure. - Constraint Construction - Establishing relationships between values, particularly across consecutive rows. This process aligns with AIR's core functionality by: @@ -127,19 +127,23 @@ And for sub operation, Using operation selectors \\(s(x), t(x)\\), the derived polynomila constraint is \\[ s(x)\cdot P_{add}(x) + t(x) \cdot P_{sub}(x) = 0.\\] -Where:​​ +Where: - s(x): Add operation selector, - t(x): Sub operation selector, - j(x): First byte of op_1, - n(x): First byte of op_2, - c(x): First byte of result value add_op.value. +### Preprocessed AIR + +For invariant components (e.g., Program/Bytes chips), zkMIPS precomputes commitments to invariant data columns and predefines fixed AIR constraints among them during setup to establish the Preprocessed AIR framework. By removing redundant recomputation of preprocessed AIR constraints in proofs, PAIR reduces ZKP proving time. + ### Conclusion The AIR framework transforms trace constraints into polynomial identities, where increased rows only expand the evaluation domain rather than polynomial complexity. zkMIPS also enhances efficiency through: -- ​Lookup Tables​​ for range checks. -- ​Multiset Hashing​​ for memory consistency. -- ​FRI for polynomial interactive oracle proofs (IOP). -​ +- Lookup Tables for range checks. +- Multiset Hashing for memory consistency. +- FRI for polynomial interactive oracle proofs (IOP). + These components constitute the foundational architecture of zkMIPS and will be elaborated in subsequent sections. diff --git a/docs/src/dev/prover.md b/docs/src/dev/prover.md index 5a98f53e8..91c752f54 100644 --- a/docs/src/dev/prover.md +++ b/docs/src/dev/prover.md @@ -1,14 +1,14 @@ # Prover The zkm_sdk crate provides all the necessary tools for proof generation. Key features include the `ProverClient`, enabling you to: -- Initialize proving/verifying keys via `setup()`. +- Initialize proving/verifying keys via `setup()`. - Execute your program via `execute()`. - Generate proofs with `prove()`. - Verify proofs through `verify()`. ## Example: [Fibonacci](https://github.com/zkMIPS/zkm/blob/dev/init/examples/fibonacci/host/src/main.rs) -The following code is a example of using zkm_sdk in host. +The following code is an example of using zkm_sdk in host. ```rust use zkm_sdk::{include_elf, utils, ProverClient, ZKMProofWithPublicValues, ZKMStdin}; @@ -138,3 +138,154 @@ To activate **AVX512** optimization, add these flags to your RUSTFLAGS environme ```shell RUSTFLAGS="-C target-cpu=native -C target-feature=+avx512f" cargo run --release ``` +## Network Prover +We support the use of a network prover via the ZKM proof network, accessible through our RESTful API. +By default, it uses the Groth16 proving mode. +>The proving process consists of several stages: queuing, splitting, proving, aggregating and finalizing. +Each stage involves a varying duration. + +### Requirements + +- CA certificate: `ca.pem`, `ca.key`. +- [Register](https://www.zkm.io/apply) your address to gain access. +- Use zkm_sdk from our [project template](https://github.com/zkMIPS/zkm-project-template): +```toml +zkm-sdk = { git = "https://github.com/zkMIPS/zkm-project-template", branch = "main", features = ["snark"] } +``` +### Environment Variable Setup +Before running your application, make sure to export the required environment variable to enable the network prover. +Here's an example: + +```bash +export ZKM_PROVER=${ZKM_PROVER-"network"} +export RUST_LOG=${RUST_LOG-info} +export SEG_SIZE=${SEG_SIZE-65536} +export OUTPUT_DIR=${BASEDIR}/output +export EXECUTE_ONLY=false + +##network proving +export CA_CERT_PATH=${BASEDIR}/tool/ca.pem +export CERT_PATH=${BASEDIR}/tool/cert.pem +export KEY_PATH=${BASEDIR}/tool/key.pem +##The private key corresponding to the public key when registering in the https://www.zkm.io/apply +export PROOF_NETWORK_PRVKEY= +export ENDPOINT=https://152.32.186.45:20002 ##the test entry of zkm proof network +export DOMAIN_NAME=stage +``` + +### Example + +The following is an example of using the network prover on the host: + +```rust +const ELF: &[u8] = include_bytes!(env!("ZKM_ELF_bitvm2-covenant")); +#[tokio::main] +async fn main() -> anyhow::Result<()> { + env_logger::try_init().unwrap_or_default(); + + // Directory for output files + let output_dir = env::var("OUTPUT_DIR").unwrap_or(String::from("./output")); + let seg_size = env::var("SEG_SIZE").unwrap_or("262144".to_string()); + let seg_size = seg_size.parse::<_>().unwrap_or(262144); + let execute_only = env::var("EXECUTE_ONLY").unwrap_or("false".to_string()); + let execute_only = execute_only.parse::().unwrap_or(false); + + // Network endpoint, should be: https://152.32.186.45:20002 + let endpoint = env::var("ENDPOINT").map_or(None, |endpoint| Some(endpoint.to_string())); + let ca_cert_path = env::var("CA_CERT_PATH").map_or(None, |path| Some(path.to_string())); + let cert_path = env::var("CERT_PATH").map_or(None, |x| Some(x.to_string())); + // The private key path of the certificate + let key_path = env::var("KEY_PATH").map_or(None, |x| Some(x.to_string())); + let domain_name = Some(env::var("DOMAIN_NAME").unwrap_or("stage".to_string())); + // The private key of the proof network, which is used to sign the proof. + let proof_network_privkey = + env::var("PROOF_NETWORK_PRVKEY").map_or(None, |x| Some(x.to_string())); + + // Create configuration for the prover client + let prover_cfg = ClientCfg { + zkm_prover_type: "network".to_string(), + endpoint, + ca_cert_path, + cert_path, + key_path, + domain_name, + proof_network_privkey, + }; + let prover_client = ProverClient::new(&prover_cfg).await; + + let mut prover_input = ProverInput { + elf: Vec::from(ELF), + seg_size, + execute_only, + ..Default::default() + }; + // If the guest program doesn't have inputs, it doesn't need the setting. + set_guest_input(&mut prover_input); + + // Proving + let proving_result = prover_client.prover.prove(&prover_input, None).await; + + // Write the proof to the output directory + match proving_result { + Ok(Some(prover_result)) => { + if !execute_only { + if prover_result.proof_with_public_inputs.is_empty() { + log::info!( + "Fail: snark_proof_with_public_inputs.len() is : {}.Please try setting SEG_SIZE={}", + prover_result.proof_with_public_inputs.len(), seg_size/2 + ); + } + let output_path = Path::new(&output_dir); + let proof_result_path = + output_path.join("snark_proof_with_public_inputs.json"); + let mut f = file::new(&proof_result_path.to_string_lossy()); + match f.write(prover_result.proof_with_public_inputs.as_slice()) { + Ok(bytes_written) => { + log::info!("Proof: successfully written {} bytes.", bytes_written); + } + Err(e) => { + log::info!("Proof: failed to write to file: {}", e); + } + } + log::info!("Generating proof successfully."); + } else { + log::info!("Generating proof successfully .The proof is not saved."); + } + } + Ok(None) => { + log::info!("Failed to generate proof.The result is None."); + } + Err(e) => { + log::info!("Failed to generate proof. error: {}", e); + } + } + Ok(()) +} + +fn set_guest_input(prover_input: &mut ProverInput) { + // Combine all the inputs into a two-dimensional array + let mut private_input: Vec> = vec![]; + + let goat_withdraw_txid: Vec = + hex::decode(std::env::var("GOAT_WITHDRAW_TXID").unwrap_or("32bc8a6c5b3649f92812c461083bab5e8f3fe4516d792bb9a67054ba040b7988".to_string())).unwrap(); + write_to_guest_private_input(&mut private_input, &goat_withdraw_txid); + + // Encode private input into a one-dimensional array and pass it to the proof network. + let mut pri_buf = Vec::new(); + bincode::serialize_into(&mut pri_buf, &private_input).expect("private_input serialization failed"); + prover_input.private_inputstream = pri_buf; +} +``` + +> [!NOTE] +> The proof network uses `stdin.write_vec()` to write private input data to the guest program. +> If your guest program uses `zkm_zkvm::io::read();` to read this input, you must serialize +> it before pushing to the private input: +```rust +fn write_to_guest_private_input(private_input: &mut Vec>, data: &[u8]) { + let mut tmp = Vec::new(); + bincode::serialize_into(&mut tmp, data).expect("serialization failed"); + private_input.push(tmp); +} +``` + diff --git a/docs/src/introducation/overview.md b/docs/src/introducation/overview.md index af375928a..a138f9a28 100644 --- a/docs/src/introducation/overview.md +++ b/docs/src/introducation/overview.md @@ -1,48 +1,69 @@ # Overview -zkMIPS is an optimized iteration of the [ZKM](https://docs.zkm.io/introduction) protocol, introducing a novel [​zkMIPS](https://github.com/zkMIPS)-based virtual machine that transforms [MIPS](https://en.wikipedia.org/wiki/MIPS_architecture) instructions into arithmetic circuits for STARK-powered zero-knowledge proofs. Designed for high-performance and trust-minimized computation, zkMIPS integrates cutting-edge cryptographic techniques and architectural improvements to address scalability bottlenecks in universal zkVMs. +zkMIPS is an open-source, simple, stable, and universal zero-knowledge virtual machine on MIPS32r2 instruction set architecture(ISA). + +zkMIPS is the industry's first zero-knowledge proof virtual machine supporting the MIPS instruction set, developed by the ZKM team, enabling zero-knowledge proof generation for general-purpose computation. zkMIPS is fully open-source and comes equipped with a comprehensive developer toolkit and an efficient proof network. The Entangled Rollup protocol, built on zkMIPS, is a native asset cross-chain circulation protocol, with typical application cases including Metis Hybrid Rollup and GOAT Network. ## Architectural Workflow The workflow of zkMIPS is as follows: -- ​Frontend Compilation: +- Frontend Compilation: - Source code (Rust/Go) → MIPS assembly → Optimized MIPS instructions for algebraic representation. -- ​Constrained Execution: + Source code (Rust) → MIPS assembly → Optimized MIPS instructions for algebraic representation. +- Constrained Execution: Emulates MIPS instructions while generating execution traces with embedded constraints (ALU, memory consistency, range checks, etc.) and treating columns of execution traces as polynomials. -- ​STARK Proof Generation: +- STARK Proof Generation: Compiles traces into Plonky3 AIR (Algebraic Intermediate Representation), and proves the constraints using the Fast Reed-Solomon Interactive Oracle Proof of Proximity (FRI) technique. - STARK Compression and STARK to SNARK: - To produce a constant-size proof, zkMIPS supports first generating a recursive argument to compress STARK proofs and then wrapping the compressed proof into a final, Groth16-compatible proof for ​efficient on-chain verification. + To produce a constant-size proof, zkMIPS supports first generating a recursive argument to compress STARK proofs and then wrapping the compressed proof into a SNARK proof for efficient on-chain verification. - Verification: - On-chain verification of the Groth16-compatible proof. + On-chain verification of the SNARK proof. ## Core Innovations -Building on ZKM's full functionality, zkMIPS optimizes the entire ​workflow to achieve industry-leading performance: -- ​MIPS-to-Circuit Compiler - - Converts standard MIPS binaries into constraint systems with deterministic execution traces using proof-system-friendly compilation configuration with existing toolchains (GCC/LLVM). -- Multiset Hasing for Memory Consistency Checking + + +zkMIPS is the world first MIPS zkVM, and achieve the industry-leading performance with the core innovations as below. + +- zkMIPS Compiler + + Implement the first zero-knowledge compiler for [MIPS32r2 instruction set](/mips-vm/mips-vm.md). Converts standard MIPS binaries into constraint systems with deterministic execution traces using proof-system-friendly compilation and PAIR builder. + +- "Area Minimization" Chip Design + + zkMIPS partitions circuit constraints into highly segmented chips, strategically minimizing the total layout area while preserving logical completeness. This fine-grained decomposition enables compact polynomial representations with reduced commitment and evaluation overhead, thereby directly optimizing ZKP proof generation efficiency. + +- Multiset Hashing for Memory Consistency Checking Replaces Merkle-Patricia trees with multiset hashing for memory consistency checks, significantly reducing witness data and enabling parallel verification. -- ​KoalaBear Prime Field + +- KoalaBear Prime Field Using KoalaBear Prime \\(2^{31} - 2^{24} + 1\\) instead of 64-bit Goldilock Prime, accelerating algebraic operations in proofs. + +- Hardware Acceleration + + zkMIPS supports AVX2/512 and GPU acceleration. + - Integrating Cutting-edge Industry Advancements - zkMIPS constructs its zero-knowledge verification system by integrating [Plonky3](https://github.com/Plonky3/Plonky3)'s optimized ​​Fast Reed-Solomon IOP (FRI)​​ protocol and adapting [SP1](https://github.com/succinctlabs/sp1)'s ​​RISC-V architecture verification primitives​​—including the recursive compiler, layered circuit builder, and precompilation modules—for the MIPS architecture. + zkMIPS constructs its zero-knowledge verification system by integrating [Plonky3](https://github.com/Plonky3/Plonky3)'s optimized Fast Reed-Solomon IOP (FRI) protocol and adapting [SP1](https://github.com/succinctlabs/sp1)'s circuit builder, recursion compiler, and precompiles for the MIPS architecture. ## Target Use Cases -zkMIPS enables ​universal verifiable computation via STARK proofs, including: -- Hybrid Rollups +zkMIPS enables universal verifiable computation via STARK proofs, including: +- Bitcoin L2 + + [GOAT Network](https://www.goat.network/) is a Bitcoin L2 built on zkMIPS and BitVM2 to improve the interoperability of Bitcoin. + +- ZK-OP(HybridRollups) - Combines optimistic rollup’s cost efficiency with validity proof verifiability, allowing users to choose withdrawal modes (fast/high-cost vs. slow/low-cost) while enhancing cross-chain capital efficiency. [GOAT Network](https://www.goat.network/), a Bitcoin L2 ​built on zkMIPS, leverages Taproot scripts to validate computations, enabling ​non-EVM chains like Bitcoin to achieve Turing completeness while ​maintaining transaction finality via Bitcoin. + Combines optimistic rollup’s cost efficiency with validity proof verifiability, allowing users to choose withdrawal modes (fast/high-cost vs. slow/low-cost) while enhancing cross-chain capital efficiency. - Entangled Rollup Uses entangled rollups for trustless cross-chain communication, with universal L2 extension resolving fragmented liquidity via proof-of-burn mechanisms (e.g., cross-chain asset transfers). + - zkML Verification - Protects sensitive ML model/data privacy (e.g., healthcare), allowing result verification without exposing raw inputs (e.g., doctors validating diagnoses without patient ECG data). + Protects sensitive ML model/data privacy (e.g., healthcare), allowing result verification without exposing raw inputs (e.g., doctors validating diagnoses without patient ECG data). \ No newline at end of file diff --git a/docs/src/introducation/performance.md b/docs/src/introducation/performance.md index dc5c548e1..05e61533d 100644 --- a/docs/src/introducation/performance.md +++ b/docs/src/introducation/performance.md @@ -30,7 +30,7 @@ To achieve a more fair comparison among the different zkVMs, we provides a [zkvm ## Performance of zkMIPS -On a AWS [r6a.8xlarge](https://instances.vantage.sh/aws/ec2/r6a.8xlarge), the performance is shown as below. +On a AWS [r6a.8xlarge](https://instances.vantage.sh/aws/ec2/r6a.8xlarge), which is a CPU server, zkMIPS's performance is shown as below. Note that all the time is of unit millisecond. Define `Rate = 100*(SP1 - zkMIPS)/zkMIPS`. diff --git a/docs/src/mips-vm/mips-vm.md b/docs/src/mips-vm/mips-vm.md index 8934de586..a1a74f12a 100644 --- a/docs/src/mips-vm/mips-vm.md +++ b/docs/src/mips-vm/mips-vm.md @@ -2,28 +2,28 @@ zkMIPS is a verifiable computation infrastructure based on the MIPS32, specifically designed to provide zero-knowledge proof generation for programs written in Rust. This enhances project auditing and the efficiency of security verification. Focusing on the extensive design experience of MIPS, zkMIPS adopts the MIPS32r2 instruction set. MIPS VM, one of the core components of zkMIPS, is the execution framework of MIPS32r2 instructions. Below we will briefly introduce the advantages of MIPS32r2 over RV32IM and the execution flow of MIPS VM. -**Advantages of MIPS32r2 over RV32IM** +## Advantages of MIPS32r2 over RV32IM -MIPS32r2 has several advantages over RV32IM: -- MIPS32r2 has more powerful instructions than RV32IM: - - the J/JAL instructions support jump ranges of up to 256MiB, offering greater flexibility for large-scale data processing and complex control flow scenarios. +**1. MIPS32r2 is more consistent and offers more complex opcodes** + - The J/JAL instructions support jump ranges of up to 256MiB, offering greater flexibility for large-scale data processing and complex control flow scenarios. - MIPS32r2 has rich set of bit manipulation instructions and additional conditional move instructions (such as MOVZ and MOVN) that ensure precise data handling. - MIPS32r2 has integer multiply-add/sub instructions, which can improve arithmetic computation efficiency. - MIPS32r2 has SEH and SEB sign extension instructions, which make it very convenient to perform sign extension operations on char and short type data. -- The MIPS32r2 instruction set has a more stable ecological support: + +**2. MIPS32r2 has a more established ecosystem** - All instructions in MIPS32r2, as a whole, have been very mature and widely used for more than 20 years. There will be no compatibility issues between ISA modules. And there will be no turmoil caused by manufacturer disputes. - - MIPS has been successfully applied to Optimism's Fraud Proof verification, which is implemented based on MIPS VM. + - MIPS has been successfully applied to Optimism's Fraud Proof VM -**Execution Flow of MIPS VM** +## Execution Flow of MIPS VM The execution flow of MIPS VM is as follows: ![zkMIPS MIPS VM execution flow](mips_vm_execution.png) Before the execution process of MIPS VM, a Rust program written by the developer is first transformed by a dedicated compiler into the MIPS instruction set, generating a corresponding ELF binary file. This process accurately maps the high-level logic of the program to low-level instructions, laying a solid foundation for subsequent verification. MIPS VM employs a specially designed executor to simulate the execution of the ELF file: -- First，the ELF code is loaded into [Program](https://github.com/zkMIPS/zkMIPS/tree/main/crates/core/executor/src/program.rs), where all data is loaded into the memory image, and all the code is decoded and added into the [Instruction](https://github.com/zkMIPS/zkMIPS/tree/main/crates/core/executor/src/instruction.rs) List. -- Then, MIPS VM executes the Instruction and update the ISA states step by step, which is started from the entry point of the ELF and ended with exit condition is triggered. A complete execution record with different type of [events](https://github.com/zkMIPS/zkMIPS/tree/main/crates/core/executor/src/events) is recorded in this process. The whole program will be divided into several shards based on the shape of the execution record. +1. First，the ELF code is loaded into [Program](https://github.com/zkMIPS/zkMIPS/tree/main/crates/core/executor/src/program.rs), where all data is loaded into the memory image, and all the code is decoded and added into the [Instruction](https://github.com/zkMIPS/zkMIPS/tree/main/crates/core/executor/src/instruction.rs) List. +2. Then, MIPS VM executes the Instruction and update the ISA states step by step, which is started from the entry point of the ELF and ended with exit condition is triggered. A complete execution record with different type of [events](https://github.com/zkMIPS/zkMIPS/tree/main/crates/core/executor/src/events) is recorded in this process. The whole program will be divided into several shards based on the shape of the execution record. After the execution process of MIPS VM, the execution record will be used by the prover to generate zero-knowledge proof: - The events recorded in execution record will be used to generate different traces by different chips.