From 45ce98d87f3fb124e7f7390344cf4c3a23dca7bb Mon Sep 17 00:00:00 2001 From: Robin Salen Date: Sun, 3 Dec 2023 18:09:23 -0500 Subject: [PATCH] Add documentation --- src/lib.rs | 95 +++++++++++++++++++++++++++++++++++++++++++++ src/proof_gen.rs | 17 +++++--- src/proof_types.rs | 20 ++++++++++ src/prover_state.rs | 8 ++++ src/types.rs | 6 +++ 5 files changed, 140 insertions(+), 6 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 8491598..585be4d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,98 @@ +//! This library is intended to generate proofs with the [plonky2 zkEVM](https://github.com/0xPolygonZero/plonky2/evm), given +//! transactions provided in Intermediate Representation (IR) format. +//! +//! The exact format of this IR is defined by the [GenerationInputs](https://github.com/0xPolygonZero/plonky2/evm/src/generation/mod.rs) +//! used by the zkEVM prover, containing an RLP-encoded transaction along with +//! state metadata prior and post execution of this transaction. +//! +//! # Usage +//! +//! First, a prover needs to initialize its `ProverState`. For this, one can +//! use the `ProverStateBuilder`, which contains the ranges to be used by all +//! internal STARK tables of the zkEVM. +//! +//! The default method contains an initial set of ranges for each table, that +//! can be overriden at will by calling +//! `ProverStateBuilder::set_foo_circuit_size` where `foo` is the name of the +//! targeted table. At the moment, plonky2 zkEVM contains seven tables: +//! `arithmetic`, `byte_packing`, `cpu`, `keccak`, `keccak_sponge`, `logic` and +//! `memory`. +//! +//! ```rust +//! let mut builder = ProverStateBuilder::default(); +//! +//! // Change Cpu and Memory tables supported ranges. +//! builder.set_cpu_circuit_size(12..25); +//! builder.set_cpu_circuit_size(18..28); +//! +//! // Generate a `ProverState` from the builder. +//! let prover_state = builder.build(); +//! ``` +//! +//! ***NOTE***: All the circuits to generate the different kind of proofs, from +//! transaction proofs to block proofs, are specific to the initial set of +//! ranges selected for each table. Changing one of them will require building a +//! new `ProverState`, and will make all previously generated proofs +//! incompatible with the new state. Make sure you select sufficiently large +//! ranges for your application! +//! +//! Once all circuits have been pre-processed, a prover can now generate proofs +//! from inputs passed as Intermediary Representation. +//! +//! This library handles the 3 kinds of proof generations necessary for the +//! zkEVM: +//! +//! ### Transaction proofs +//! +//! From a `ProverState` and a transaction processed with some metadata in +//! Intermediate Representation, one can obtain a transaction proof by calling +//! the method below: +//! +//! ```rust +//! pub fn generate_txn_proof( +//! p_state: &ProverState, +//! start_info: TxnProofGenIR, +//! ) -> ProofGenResult { ... } +//! ``` +//! +//! The obtained `GeneratedTxnProof` contains the actual proof and some +//! additional data to be used when aggregating this transaction with others. +//! +//! ### Aggregation proofs +//! +//! Two proofs can be aggregated together with a `ProverState`. These `child` +//! proofs can either be transaction proofs, or aggregated proofs themselves. +//! This library abstracts their type behind an `AggregatableProof` enum. +//! +//! ```rust +//! pub fn generate_agg_proof( +//! p_state: &ProverState, +//! lhs_child: &AggregatableProof, +//! rhs_child: &AggregatableProof, +//! ) -> ProofGenResult { ... } +//! ``` +//! +//! ### Block proofs +//! +//! Once the prover has obtained a `GeneratedAggProof` corresponding to the +//! entire set of transactions within a block, they can then wrap it into a +//! final `GeneratedBlockProof`. The prover can pass an optional previous +//! block proof as argument to the `generate_block_proof` method, to combine +//! both statement into one, effectively proving an entire chain from genesis +//! through a single final proof. +//! +//! ```rust +//! pub fn generate_block_proof( +//! p_state: &ProverState, +//! prev_opt_parent_b_proof: Option<&GeneratedBlockProof>, +//! curr_block_agg_proof: &GeneratedAggProof, +//! ) -> ProofGenResult { ... } +//! ``` + +#![cfg_attr(docsrs, feature(doc_cfg))] +#![deny(rustdoc::broken_intra_doc_links)] +#![deny(missing_docs)] + pub mod proof_gen; pub mod proof_types; pub mod prover_state; diff --git a/src/proof_gen.rs b/src/proof_gen.rs index f91583f..2ae989b 100644 --- a/src/proof_gen.rs +++ b/src/proof_gen.rs @@ -1,3 +1,6 @@ +//! This module defines the proof generation methods corresponding to the three +//! types of proofs the zkEVM internally handles. + use plonky2::util::timing::TimingTree; use plonky2_evm::{all_stark::AllStark, config::StarkConfig}; use proof_protocol_decoder::types::TxnProofGenIR; @@ -7,8 +10,10 @@ use crate::{ prover_state::ProverState, }; +/// A type alias for `Result`. pub type ProofGenResult = Result; +/// A custom error type to handle failure cases during proof generation. // Plonky2 is still using `anyhow` for proof gen, and since this is a library, // it's probably best if we at least convert it to a `String`. #[derive(Debug)] @@ -28,7 +33,7 @@ impl From for ProofGenError { } } -/// Generate a txn proof from proof IR data. +/// Generates a transaction proof from some IR data. pub fn generate_txn_proof( p_state: &ProverState, start_info: TxnProofGenIR, @@ -46,9 +51,9 @@ pub fn generate_txn_proof( Ok(GeneratedTxnProof { p_vals, intern }) } -/// Generate a agg proof from two child proofs. +/// Generates an aggregation proof from two child proofs. /// -/// Note that the child proofs may be either txn or agg proofs. +/// Note that the child proofs may be either transaction or aggregation proofs. pub fn generate_agg_proof( p_state: &ProverState, lhs_child: &AggregatableProof, @@ -69,10 +74,10 @@ pub fn generate_agg_proof( Ok(GeneratedAggProof { p_vals, intern }) } -/// Generate a block proof. +/// Generates a block proof. /// -/// Note that `prev_opt_parent_b_proof` is able to be `None` on checkpoint -/// heights. +/// It takes an optional argument, `prev_opt_parent_b_proof`, that can be set to +/// `None` on checkpoint heights. pub fn generate_block_proof( p_state: &ProverState, prev_opt_parent_b_proof: Option<&GeneratedBlockProof>, diff --git a/src/proof_types.rs b/src/proof_types.rs index 84a249e..20a7d71 100644 --- a/src/proof_types.rs +++ b/src/proof_types.rs @@ -1,24 +1,42 @@ +//! This module defines the various proof types used throughout the block proof +//! generation process. + use plonky2_evm::proof::PublicValues; use proof_protocol_decoder::types::BlockHeight; use serde::{Deserialize, Serialize}; use crate::types::PlonkyProofIntern; +/// A transaction proof along with its public values, for proper connection with +/// contiguous proofs. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct GeneratedTxnProof { + /// Public values of this transaction proof. pub p_vals: PublicValues, + /// Underlying plonky2 proof. pub intern: PlonkyProofIntern, } +/// An aggregation proof along with its public values, for proper connection +/// with contiguous proofs. +/// +/// Aggregation proofs can represent any contiguous range of two or more +/// transactions, up to an entire block. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct GeneratedAggProof { + /// Public values of this aggregation proof. pub p_vals: PublicValues, + /// Underlying plonky2 proof. pub intern: PlonkyProofIntern, } +/// A block proof along with the block height against which this proof ensures +/// the validity since the last proof checkpoint. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct GeneratedBlockProof { + /// Associated block height. pub b_height: BlockHeight, + /// Underlying plonky2 proof. pub intern: PlonkyProofIntern, } @@ -27,7 +45,9 @@ pub struct GeneratedBlockProof { /// away whether or not the proof was a txn or agg proof. #[derive(Clone, Debug, Deserialize, Serialize)] pub enum AggregatableProof { + /// The underlying proof is a transaction proof. Txn(GeneratedTxnProof), + /// The underlying proof is an aggregation proof. Agg(GeneratedAggProof), } diff --git a/src/prover_state.rs b/src/prover_state.rs index aabb2b1..7cb601a 100644 --- a/src/prover_state.rs +++ b/src/prover_state.rs @@ -1,3 +1,8 @@ +//! This module defines the `ProverState`, that contains all pre-processed +//! circuits necessary to handle arbitrary transaction proving and proof +//! aggregation to generate succinct block proofs attesting validity of an +//! entire EVM-based chain. + use std::ops::Range; use log::info; @@ -9,6 +14,7 @@ use crate::types::AllRecursiveCircuits; /// Plonky2 proving state. Note that this is generally going to be massive in /// terms of memory and has a long spin-up time, pub struct ProverState { + /// The set of pre-processed circuits to recursively prove transactions. pub state: AllRecursiveCircuits, } @@ -44,6 +50,8 @@ impl Default for ProverStateBuilder { macro_rules! define_set_circuit_size_method { ($name:ident) => { paste! { + /// Specifies a range of degrees to be supported for this STARK + /// table's associated recursive circuits. pub fn [](mut self, size: Range) -> Self { self.[<$name _circuit_size>] = size; self diff --git a/src/types.rs b/src/types.rs index c46471f..1344984 100644 --- a/src/types.rs +++ b/src/types.rs @@ -1,10 +1,16 @@ +//! This module contains type aliases and custom `Error` definition for +//! convenient proof generation. + use plonky2::{ field::goldilocks_field::GoldilocksField, plonk::{config::PoseidonGoldilocksConfig, proof::ProofWithPublicInputs}, }; +/// A type alias for proofs generated by the zkEVM. pub type PlonkyProofIntern = ProofWithPublicInputs; +/// A type alias for the set of preprocessed circuits necessary to generate +/// succinct block proofs. pub type AllRecursiveCircuits = plonky2_evm::fixed_recursive_verifier::AllRecursiveCircuits< GoldilocksField, PoseidonGoldilocksConfig,