add some docs

halo2_gadgets/src/ecc.rs

@@ -2,10 +2,9 @@
 
 use std::fmt::Debug;
 
-use halo2_proofs::circuit::AssignedCell;
 use halo2_proofs::{
     arithmetic::CurveAffine,
-    circuit::{Chip, Layouter, Value},
+    circuit::{AssignedCell, Chip, Layouter, Value},
     plonk::Error,
 };
 
@@ -1056,21 +1055,21 @@ pub(crate) mod tests {
 
             // Generate a random non-identity point P
             let p_val = pallas::Point::random(rand::rngs::OsRng).to_affine(); // P
-            let p = crate::ecc::NonIdentityPoint::new(
+            let p = super::NonIdentityPoint::new(
                 chip.clone(),
                 layouter.namespace(|| "P"),
                 Value::known(p_val),
             )?;
             let p_neg = -p_val;
-            let p_neg = crate::ecc::NonIdentityPoint::new(
+            let p_neg = super::NonIdentityPoint::new(
                 chip.clone(),
                 layouter.namespace(|| "-P"),
                 Value::known(p_neg),
             )?;
 
             // Generate a random non-identity point Q
             let q_val = pallas::Point::random(rand::rngs::OsRng).to_affine(); // Q
-            let q = crate::ecc::NonIdentityPoint::new(
+            let q = super::NonIdentityPoint::new(
                 chip.clone(),
                 layouter.namespace(|| "Q"),
                 Value::known(q_val),

halo2_gadgets/src/ecc/chip/mul.rs

@@ -460,9 +460,8 @@ pub mod tests {
         ff::{Field, PrimeField},
         Curve,
     };
-    use halo2_proofs::circuit::Chip;
     use halo2_proofs::{
-        circuit::{Layouter, Value},
+        circuit::{Chip, Layouter, Value},
         plonk::Error,
     };
     use pasta_curves::pallas;

halo2_gadgets/src/ecc/chip/mul_fixed/short.rs

@@ -3,9 +3,8 @@ use std::convert::TryInto;
 use super::super::{EccPoint, EccScalarFixedShort, FixedPoints, L_SCALAR_SHORT, NUM_WINDOWS_SHORT};
 use crate::{ecc::chip::MagnitudeSign, utilities::bool_check};
 
-use halo2_proofs::circuit::AssignedCell;
 use halo2_proofs::{
-    circuit::{Layouter, Region},
+    circuit::{AssignedCell, Layouter, Region},
     plonk::{ConstraintSystem, Constraints, Error, Expression, Selector},
     poly::Rotation,
 };

halo2_gadgets/src/sinsemilla/chip.rs

@@ -381,9 +381,9 @@ where
     }
 }
 
-/// A chip that implements 10-bit Sinsemilla using a lookup table and 5 advice columns.
-///
-/// [Chip description](https://zcash.github.io/halo2/design/gadgets/sinsemilla.html#plonk--halo-2-constraints).
+/// 'SinsemillaChipOptimized' is an extended version of the SinsemillaChip.
+/// The corresponding lookup table support optimized range check for 4 and 5 bits.
+/// It also implements methods for hash optimization.
 #[derive(Eq, PartialEq, Clone, Debug)]
 pub struct SinsemillaChipOptimized<Hash, Commit, Fixed>
 where
@@ -440,6 +440,7 @@ where
         )
     }
 
+    /// Assign y_q to an advice column
     #[allow(non_snake_case)]
     fn create_initial_y_q_gate(
         meta: &mut ConstraintSystem<pallas::Base>,

halo2_gadgets/src/sinsemilla/merkle/chip.rs

@@ -10,6 +10,7 @@ use pasta_curves::pallas;
 use super::MerkleInstructions;
 
 use crate::sinsemilla::chip::SinsemillaChipOptimized;
+use crate::utilities::cond_swap::CondSwapInstructionsOptimized;
 use crate::utilities::lookup_range_check::PallasLookupConfigOptimized;
 use crate::{
     sinsemilla::{primitives as sinsemilla, MessagePiece},
@@ -591,16 +592,7 @@ where
     }
 }
 
-/// Chip implementing `MerkleInstructions`.
-///
-/// This chip specifically implements `MerkleInstructions::hash_layer` as the `MerkleCRH`
-/// function `hash = SinsemillaHash(Q, 𝑙⋆ || left⋆ || right⋆)`, where:
-/// - `𝑙⋆ = I2LEBSP_10(l)`
-/// - `left⋆ = I2LEBSP_255(left)`
-/// - `right⋆ = I2LEBSP_255(right)`
-///
-/// This chip does **NOT** constrain `left⋆` and `right⋆` to be canonical encodings of
-/// `left` and `right`.
+/// 'MerkleChipOptimized' Chip extends 'MerkleChip', supporting new methods
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct MerkleChipOptimized<Hash, Commit, Fixed>
 where
@@ -686,6 +678,26 @@ where
     }
 }
 
+impl<Hash, Commit, F> CondSwapInstructionsOptimized<pallas::Base>
+    for MerkleChipOptimized<Hash, Commit, F>
+where
+    Hash: HashDomains<pallas::Affine>,
+    F: FixedPoints<pallas::Affine>,
+    Commit: CommitDomains<pallas::Affine, F, Hash>,
+{
+    fn mux(
+        &self,
+        layouter: &mut impl Layouter<pallas::Base>,
+        choice: Self::Var,
+        left: Self::Var,
+        right: Self::Var,
+    ) -> Result<Self::Var, Error> {
+        let config = self.config().cond_swap_config.clone();
+        let chip = CondSwapChip::<pallas::Base>::construct(config);
+        chip.mux(layouter, choice, left, right)
+    }
+}
+
 impl<Hash, Commit, F> SinsemillaInstructions<pallas::Affine, { sinsemilla::K }, { sinsemilla::C }>
     for MerkleChipOptimized<Hash, Commit, F>
 where

halo2_gadgets/src/utilities/cond_swap.rs

@@ -195,7 +195,7 @@ impl<F: PrimeField> CondSwapChip<F> {
     }
 }
 
-/// Instructions for a conditional swap gadget.
+/// 'CondSwapInstructionsOptimized' extends 'CondSwapInstructions', provides new method 'mux'.
 pub trait CondSwapInstructionsOptimized<F: Field>: CondSwapInstructions<F> {
     /// Given an input `(choice, left, right)` where `choice` is a boolean flag,
     /// returns `left` if `choice` is not set and `right` if `choice` is set.
@@ -304,7 +304,7 @@ impl CondSwapChip<pallas::Base> {
 mod tests {
     use super::super::UtilitiesInstructions;
     use super::{CondSwapChip, CondSwapConfig, CondSwapInstructions};
-    use crate::utilities::lookup_range_check::{LookupRangeCheck, LookupRangeCheckConfigOptimized};
+    use crate::utilities::lookup_range_check::LookupRangeCheckConfigOptimized;
     use group::ff::{Field, PrimeField};
     use halo2_proofs::{
         circuit::{Layouter, SimpleFloorPlanner, Value},

halo2_gadgets/src/utilities/lookup_range_check.rs

@@ -58,7 +58,7 @@ impl<F: PrimeFieldBits> RangeConstrained<F, AssignedCell<F, F>> {
     }
 }
 
-/// Configuration that provides methods for a lookup range check.
+/// Configuration that provides methods for a 10-bit lookup range check.
 #[derive(Eq, PartialEq, Debug, Clone, Copy)]
 pub struct LookupRangeCheckConfig<F: PrimeFieldBits, const K: usize> {
     q_lookup: Selector,
@@ -456,7 +456,7 @@ pub type PallasLookupRCConfig = LookupRangeCheckConfig<pallas::Base, { sinsemill
 
 impl PallasLookupRC for PallasLookupRCConfig {}
 
-/// Configuration that provides methods for a lookup range check 'LookupRangeCheckConfigOptimized'.
+/// Configuration that provides methods for an efficient 4, 5, and 10-bit lookup range check.
 #[derive(Eq, PartialEq, Debug, Clone, Copy)]
 pub struct LookupRangeCheckConfigOptimized<F: PrimeFieldBits, const K: usize> {
     base: LookupRangeCheckConfig<F, K>,