more refactoring and better inline docs

Author: roynalnaruto

prover/src/zkevm.rs

@@ -1,19 +1,21 @@
 #[cfg(feature = "scroll")]
 mod capacity_checker;
+#[cfg(feature = "scroll")]
+pub use capacity_checker::{CircuitCapacityChecker, RowUsage, SubCircuitRowUsage};
+
 pub mod circuit;
+
 mod error;
+pub use error::ChunkProverError;
+
 mod prover;
-mod verifier;
+pub use prover::Prover;
 
-pub use self::prover::Prover;
-#[cfg(feature = "scroll")]
-pub use capacity_checker::{CircuitCapacityChecker, RowUsage};
-pub use error::ChunkProverError;
-use serde::{Deserialize, Serialize};
+mod verifier;
 pub use verifier::Verifier;
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
-pub struct SubCircuitRowUsage {
-    pub name: String,
-    pub row_number: usize,
-}
+/// Alias to be re-exported.
+pub type ChunkProver<'a> = Prover<'a>;
+
+/// Alias to be re-exported.
+pub type ChunkVerifier<'a> = Verifier<'a>;

prover/src/zkevm/capacity_checker.rs

@@ -1,5 +1,4 @@
-use super::circuit::{calculate_row_usage_of_witness_block, finalize_builder};
-use bus_mapping::circuit_input_builder::{self, CircuitInputBuilder};
+use bus_mapping::circuit_input_builder::{Blocks, CircuitInputBuilder};
 use eth_types::{
     l2_types::BlockTrace,
     state_db::{CodeDB, StateDB},
@@ -14,7 +13,13 @@ use zkevm_circuits::{
     super_circuit::params::{get_sub_circuit_limit_and_confidence, get_super_circuit_params},
 };
 
-pub use super::SubCircuitRowUsage;
+use super::circuit::{calculate_row_usage_of_witness_block, finalize_builder};
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct SubCircuitRowUsage {
+    pub name: String,
+    pub row_number: usize,
+}
 
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct RowUsage {
@@ -145,8 +150,7 @@ impl CircuitCapacityChecker {
                 // the previous one and do not use zktrie state,
                 // notice the prev_root in current builder may be not invalid (since the state has
                 // changed but we may not update it in light mode)
-                let mut builder_block =
-                    circuit_input_builder::Blocks::init(trace.chain_id, get_super_circuit_params());
+                let mut builder_block = Blocks::init(trace.chain_id, get_super_circuit_params());
                 builder_block.start_l1_queue_index = trace.start_l1_queue_index;
                 builder_block.prev_state_root = mpt_state
                     .as_ref()

prover/src/zkevm/circuit/builder.rs

@@ -1,4 +1,3 @@
-use crate::zkevm::{ChunkProverError, SubCircuitRowUsage};
 use bus_mapping::{circuit_input_builder::CircuitInputBuilder, Error as CircuitBuilderError};
 use eth_types::{l2_types::BlockTrace, ToWord};
 use itertools::Itertools;
@@ -9,6 +8,10 @@ use zkevm_circuits::{
     witness::block_convert,
 };
 
+use crate::zkevm::{ChunkProverError, SubCircuitRowUsage};
+
+/// Returns the row-usage for all sub-circuits in the process of applying the entire witness block
+/// to the super circuit.
 pub fn calculate_row_usage_of_witness_block(
     witness_block: &Block,
 ) -> Result<Vec<SubCircuitRowUsage>, ChunkProverError> {
@@ -45,14 +48,17 @@ pub fn calculate_row_usage_of_witness_block(
         .collect_vec())
 }
 
-pub fn dummy_witness_block() -> anyhow::Result<Block> {
-    log::debug!("generate dummy witness block");
+/// Generate a dummy witness block to eventually generate proving key and verifying key for the
+/// target circuit without going through the expensive process of actual witness assignment.
+pub fn dummy_witness_block() -> Block {
     let dummy_chain_id = 0;
-    let witness_block = zkevm_circuits::witness::dummy_witness_block(dummy_chain_id);
-    log::debug!("generate dummy witness block done");
-    Ok(witness_block)
+    zkevm_circuits::witness::dummy_witness_block(dummy_chain_id)
 }
 
+/// Build a witness block from block traces for all blocks in the chunk.
+///
+/// Kind of a duplication of [`self::chunk_trace_to_witness_block`], so should eventually be
+/// deprecated.
 pub fn block_traces_to_witness_block(
     block_traces: Vec<BlockTrace>,
 ) -> Result<Block, ChunkProverError> {
@@ -103,6 +109,7 @@ pub fn block_traces_to_witness_block(
     Ok(witness_block)
 }
 
+/// Build a witness block from block traces for all blocks in the chunk.
 pub fn chunk_trace_to_witness_block(
     chunk_trace: Vec<BlockTrace>,
 ) -> Result<Block, ChunkProverError> {

prover/src/zkevm/circuit.rs prover/src/zkevm/circuit/mod.rsprover/src/zkevm/circuit.rs renamed to prover/src/zkevm/circuit/mod.rs

@@ -3,31 +3,28 @@ use snark_verifier_sdk::CircuitExt;
 use zkevm_circuits::{super_circuit::params::ScrollSuperCircuit, util::SubCircuit, witness};
 
 mod builder;
-pub use self::builder::{
+pub use builder::{
     block_traces_to_witness_block, calculate_row_usage_of_witness_block,
     chunk_trace_to_witness_block, finalize_builder,
 };
 
-pub use zkevm_circuits::super_circuit::params::{MAX_CALLDATA, MAX_INNER_BLOCKS, MAX_TXS};
-
 /// A target circuit trait is a wrapper of inner circuit, with convenient APIs for building
 /// circuits from traces.
 pub trait TargetCircuit {
     /// The actual inner circuit that implements Circuit trait.
     type Inner: CircuitExt<Fr> + SubCircuit<Fr>;
 
-    /// Generate a dummy circuit with an empty trace.
-    /// This is useful for generating vk and pk.
+    /// Generate a dummy circuit with an empty trace. This is useful for generating vk and pk.
     fn dummy_inner_circuit() -> anyhow::Result<Self::Inner>
     where
         Self: Sized,
     {
-        let witness_block = builder::dummy_witness_block()?;
+        let witness_block = builder::dummy_witness_block();
         let circuit = Self::from_witness_block(&witness_block)?;
         Ok(circuit)
     }
 
-    /// Build the inner circuit and the instances from the witness block
+    /// Build the inner circuit and the instances from the witness block.
     fn from_witness_block(witness_block: &witness::Block) -> anyhow::Result<Self::Inner>
     where
         Self: Sized,