Add documentation

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<GeneratedTxnProof> { ... }
+//! ```
+//!
+//! 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<GeneratedAggProof> { ... }
+//! ```
+//!
+//! ### 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<GeneratedBlockProof> { ... }
+//! ```
+
+#![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;

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<T, ProofGenError>`.
 pub type ProofGenResult<T> = Result<T, ProofGenError>;
 
+/// 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<String> 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>,

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),
 }
 

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 [<set_ $name _circuit_size>](mut self, size: Range<usize>) -> Self {
                 self.[<$name _circuit_size>] = size;
                 self

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<GoldilocksField, PoseidonGoldilocksConfig, 2>;
 
+/// 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,