a few comments on proof aggregation circuit (#558)

* a few comments inside core function for proof compression: extract_accumulators_and_proof

* comments on proof compression circuit

* comments on pi aggregation circuit, especially calculation of hash indexes when using Keccak circuit, which are hard-coded here so needs be very careful

* comments on proof aggregation circuit

* a few comments inside core function for proof compression: extract_accumulators_and_proof

* comments on proof compression circuit

* comments on pi aggregation circuit, especially calculation of hash indexes when using Keccak circuit, which are hard-coded here so needs be very careful

* comments on proof aggregation circuit

* clean up all commits from my side

* clean up of all commits on my side

Author: huwenqing0606

aggregator/src/core.rs

@@ -50,6 +50,20 @@ pub(crate) fn assign_batch_hashes<F: Field>(
     let num_rows = 1 << LOG_DEGREE;
 
     let timer = start_timer!(|| ("multi keccak").to_string());
+    // wenqing: preimages consists of the following parts
+    // (1) batchPiHash preimage =
+    //      (chain_id ||
+    //      chunk[0].prev_state_root ||
+    //      chunk[k-1].post_state_root ||
+    //      chunk[k-1].withdraw_root ||
+    //      batch_data_hash)
+    // (2) batchDataHash preimage = 
+    //      (chunk[0].dataHash || ... || chunk[k-1].dataHash)
+    // (3) chunk[i].piHash preimage =
+    //      (chain id ||
+    //      chunk[i].prevStateRoot || chunk[i].postStateRoot || 
+    //      chunk[i].withdrawRoot || chunk[i].datahash)
+    // each part of the preimage is mapped to image by Keccak256
     let witness = multi_keccak(preimages, challenges, capacity(num_rows))?;
     end_timer!(timer);
 
@@ -84,10 +98,12 @@ pub(crate) fn assign_batch_hashes<F: Field>(
                 let row = config.set_row(&mut region, offset, keccak_row)?;
 
                 if cur_preimage_index.is_some() && *cur_preimage_index.unwrap() == offset {
+                    // wenqing: 7-th column is Keccak input in Keccak circuit
                     current_hash_input_cells.push(row[6].clone());
                     cur_preimage_index = preimage_indices_iter.next();
                 }
                 if cur_digest_index.is_some() && *cur_digest_index.unwrap() == offset {
+                    // wenqing: last column is Keccak output in Keccak circuit
                     current_hash_output_cells.push(row.last().unwrap().clone());
                     cur_digest_index = digest_indices_iter.next();
                 }
@@ -126,6 +142,7 @@ pub(crate) fn assign_batch_hashes<F: Field>(
             for i in 0..4 {
                 for j in 0..8 {
                     // sanity check
+                    // wenqing: 96 + CHAIN_ID_LEN is the byte position for batch_data_hash
                     assert_equal(
                         &hash_input_cells[0][i * 8 + j + 96 + CHAIN_ID_LEN],
                         &hash_output_cells[1][(3 - i) * 8 + j],
@@ -155,6 +172,10 @@ pub(crate) fn assign_batch_hashes<F: Field>(
             //        chunk[i].postStateRoot ||
             //        chunk[i].withdrawRoot  ||
             //        chunk[i].datahash)
+            // wenqing: CHAIN_ID_LEN, 
+            //          CHAIN_ID_LEN+32, 
+            //          CHAIN_ID_LEN+64 used below are byte positions for 
+            //          prev_state_root, post_state_root, withdraw_root
             for i in 0..32 {
                 // 2.2.1 chunk[0].prev_state_root
                 // sanity check
@@ -271,6 +292,8 @@ pub(crate) fn extract_accumulators_and_proof(
                 &snark.instances,
                 &mut transcript_read,
             );
+            // wenqing: each accumulator has (lhs, rhs) based on Shplonk
+            // lhs and rhs are EC points
             Shplonk::succinct_verify(&svk, &snark.protocol, &snark.instances, &proof)
         })
         .collect::<Vec<_>>();
@@ -279,6 +302,11 @@ pub(crate) fn extract_accumulators_and_proof(
         PoseidonTranscript::<NativeLoader, Vec<u8>>::from_spec(vec![], POSEIDON_SPEC.clone());
     // We always use SHPLONK for accumulation scheme when aggregating proofs
     let accumulator =
+        // wenqing: core step
+        // KzgAs does KZG accumulation scheme based on given accumulators and random number (for adding blinding)
+        // accumulated ec_pt = ec_pt_1 * 1 + ec_pt_2 * r + ... + ec_pt_n * r^{n-1}
+        // ec_pt can be lhs and rhs
+        // r is the challenge squeezed from proof
         KzgAs::<Kzg<Bn256, Bdfg21>>::create_proof::<PoseidonTranscript<NativeLoader, Vec<u8>>, _>(
             &Default::default(),
             &accumulators,

aggregator/src/proof_aggregation/circuit.rs

@@ -68,6 +68,11 @@ impl AggregationCircuit {
             let snark_hash_bytes = &snark.instances[0];
 
             for i in 0..32 {
+                // wenqing: for each snark, 
+                //  first 12 elements are accumulator
+                //  next 32 elements are data hash (44=12+32)
+                //  next 32 elements are public_input_hash
+                //  data hash + public_input_hash = snark public input
                 assert_eq!(
                     Fr::from(chunk.data_hash.as_bytes()[i] as u64),
                     snark_hash_bytes[i + 12]
@@ -83,6 +88,8 @@ impl AggregationCircuit {
         // extract the accumulators and proofs
         let svk = params.get_g()[0].into();
 
+        // wenqing: this aggregates MULTIPLE snarks 
+        //  (instead of ONE as in proof compression)
         let (accumulator, as_proof) = extract_accumulators_and_proof(params, snarks, rng);
         let KzgAccumulator::<G1Affine, NativeLoader> { lhs, rhs } = accumulator;
         let acc_instances = [lhs.x, lhs.y, rhs.x, rhs.y]
@@ -164,7 +171,7 @@ impl Circuit<Fr> for AggregationCircuit {
         //   re-export all the public input of the snarks, denoted by [snarks_instances], and the
         //   accumulator [acc_instances]
         // - 2. use public input aggregation circuit to aggregate the chunks; expose the instance
-        //   dentoed by [pi_agg_instances]
+        //   denoted by [pi_agg_instances]
         // - 3. assert [snarks_instances] are private inputs used for public input aggregation
         //   circuit
 
@@ -195,7 +202,7 @@ impl Circuit<Fr> for AggregationCircuit {
                 //
                 // extract the assigned values for
                 // - instances which are the public inputs of each chunk (prefixed with 12 instances
-                //   from previous accumualtors)
+                //   from previous accumulators)
                 // - new accumulator to be verified on chain
                 //
                 let (assigned_aggregation_instances, acc) = aggregate::<Kzg<Bn256, Bdfg21>>(
@@ -350,6 +357,7 @@ impl Circuit<Fr> for AggregationCircuit {
             for i in 0..4 {
                 for j in 0..8 {
                     // digest in circuit has a different endianness
+                    // wenqing: 96 is the byte position for batch data hash
                     layouter.constrain_instance(
                         hash_output_cells[0][(3 - i) * 8 + j].cell(),
                         config.instance,
@@ -358,6 +366,7 @@ impl Circuit<Fr> for AggregationCircuit {
                 }
             }
             // last 8 inputs are the chain id
+            // wenqing: chain_id is put at last here
             for i in 0..CHAIN_ID_LEN {
                 layouter.constrain_instance(
                     hash_input_cells[0][i].cell(),

aggregator/src/proof_aggregation/config.rs

@@ -30,11 +30,12 @@ pub struct AggregationConfig {
     /// Instance for public input; stores
     /// - accumulator from aggregation (12 elements)
     /// - aggregated public inputs (136 elements):
-    ///     chain_id ||
     ///     chunk\[0\].prev_state_root ||
     ///     chunk\[k-1\].post_state_root ||
     ///     chunk\[k-1\].withdraw_root ||
-    ///     batch_data_hash
+    ///     batch_data_hash ||
+    ///     chain_id
+    /// wenqing: chain_id is put at last here for instance
     pub instance: Column<Instance>,
 }
 

aggregator/src/proof_compression/circuit.rs

@@ -84,6 +84,8 @@ impl Circuit<Fr> for CompressionCircuit {
         )
         .unwrap();
 
+        // wenqing: circuit configuration is built from config with given num columns etc
+        // can be wide or thin circuit
         Self::Config::configure(meta, params)
     }
 
@@ -166,6 +168,10 @@ impl CompressionCircuit {
     ) -> Self {
         let svk = params.get_g()[0].into();
 
+        // wenqing: for the proof compression, only ONE snark is under accumulation
+        // it is turned into an accumulator via KzgAs accumulation scheme
+        // in case not first time: 
+        // (old_accumulator, public inputs) -> (new_accumulator, public inputs)
         let (accumulator, as_proof) = extract_accumulators_and_proof(params, &[snark.clone()], rng);
 
         // the instance for the outer circuit is

aggregator/src/util.rs

@@ -30,6 +30,12 @@ pub(crate) fn get_indices(preimages: &[Vec<u8>]) -> (Vec<usize>, Vec<usize>) {
     let mut round_ctr = 0;
 
     for preimage in preimages.iter() {
+        // wenqing: 136 = 17 * 8 is the size in bits of each 
+        //  input chunk that can be processed by Keccak circuit using absorb
+        //  each chunk of size 136 needs 300 Keccak circuit rows to prove
+        //  which consists of 12 Keccak rows for each of 24 + 1 Keccak cicuit rounds
+        //  digest only happens at the end of the last input chunk with 
+        //  4 Keccak circuit rounds, so 48 Keccak rows, and 300 - 48 = 256
         let num_rounds = 1 + preimage.len() / 136;
         let mut preimage_padded = preimage.clone();
         preimage_padded.resize(136 * num_rounds, 0);