diff --git a/halo2_gadgets/src/ecc/chip/mul_fixed.rs b/halo2_gadgets/src/ecc/chip/mul_fixed.rs index f7c19a97..a4e3691e 100644 --- a/halo2_gadgets/src/ecc/chip/mul_fixed.rs +++ b/halo2_gadgets/src/ecc/chip/mul_fixed.rs @@ -130,7 +130,7 @@ impl> Config { fn running_sum_coords_gate(&self, meta: &mut ConstraintSystem) { meta.create_gate("Running sum coordinates check", |meta| { let q_mul_fixed_running_sum = - meta.query_selector(self.running_sum_config.q_range_check); + meta.query_selector(self.running_sum_config.q_range_check()); let z_cur = meta.query_advice(self.window, Rotation::cur()); let z_next = meta.query_advice(self.window, Rotation::next()); diff --git a/halo2_gadgets/src/ecc/chip/mul_fixed/base_field_elem.rs b/halo2_gadgets/src/ecc/chip/mul_fixed/base_field_elem.rs index 1b0db637..a8be85d1 100644 --- a/halo2_gadgets/src/ecc/chip/mul_fixed/base_field_elem.rs +++ b/halo2_gadgets/src/ecc/chip/mul_fixed/base_field_elem.rs @@ -190,7 +190,7 @@ impl> Config { offset, &(&scalar).into(), base, - self.super_config.running_sum_config.q_range_check, + self.super_config.running_sum_config.q_range_check(), )?; Ok((scalar, acc, mul_b)) diff --git a/halo2_gadgets/src/ecc/chip/mul_fixed/short.rs b/halo2_gadgets/src/ecc/chip/mul_fixed/short.rs index 3f033f02..c921d668 100644 --- a/halo2_gadgets/src/ecc/chip/mul_fixed/short.rs +++ b/halo2_gadgets/src/ecc/chip/mul_fixed/short.rs @@ -117,7 +117,7 @@ impl> Config { offset, &(&scalar).into(), base, - self.super_config.running_sum_config.q_range_check, + self.super_config.running_sum_config.q_range_check(), )?; Ok((scalar, acc, mul_b)) diff --git a/halo2_gadgets/src/sinsemilla/merkle.rs b/halo2_gadgets/src/sinsemilla/merkle.rs index 7c8caef5..38c7436b 100644 --- a/halo2_gadgets/src/sinsemilla/merkle.rs +++ b/halo2_gadgets/src/sinsemilla/merkle.rs @@ -13,7 +13,7 @@ use crate::utilities::{ }; use std::iter; -pub(crate) mod chip; +pub mod chip; /// SWU hash-to-curve personalization for the Merkle CRH generator pub const MERKLE_CRH_PERSONALIZATION: &str = "z.cash:Orchard-MerkleCRH"; @@ -58,12 +58,40 @@ pub struct MerklePath< > where MerkleChip: MerkleInstructions + Clone, { - pub(crate) chip_1: MerkleChip, - pub(crate) chip_2: MerkleChip, - pub(crate) domain: MerkleChip::HashDomains, - pub(crate) leaf_pos: Option, + chip_1: MerkleChip, + chip_2: MerkleChip, + domain: MerkleChip::HashDomains, + leaf_pos: Option, // The Merkle path is ordered from leaves to root. - pub(crate) path: Option<[C::Base; PATH_LENGTH]>, + path: Option<[C::Base; PATH_LENGTH]>, +} + +impl< + C: CurveAffine, + MerkleChip, + const PATH_LENGTH: usize, + const K: usize, + const MAX_WORDS: usize, + > MerklePath +where + MerkleChip: MerkleInstructions + Clone, +{ + /// Constructs a [`MerklePath`]. + pub fn construct( + chip_1: MerkleChip, + chip_2: MerkleChip, + domain: MerkleChip::HashDomains, + leaf_pos: Option, + path: Option<[C::Base; PATH_LENGTH]>, + ) -> Self { + Self { + chip_1, + chip_2, + domain, + leaf_pos, + path, + } + } } #[allow(non_snake_case)] @@ -78,7 +106,7 @@ where MerkleChip: MerkleInstructions + Clone, { /// Calculates the root of the tree containing the given leaf at this Merkle path. - pub(crate) fn calculate_root( + pub fn calculate_root( &self, mut layouter: impl Layouter, leaf: MerkleChip::Var, @@ -253,7 +281,7 @@ pub mod tests { let leaf = chip_1.load_private( layouter.namespace(|| ""), - config.0.cond_swap_config.a, + config.0.cond_swap_config.a(), self.leaf, )?; diff --git a/halo2_gadgets/src/sinsemilla/merkle/chip.rs b/halo2_gadgets/src/sinsemilla/merkle/chip.rs index d19aae3a..0e800bca 100644 --- a/halo2_gadgets/src/sinsemilla/merkle/chip.rs +++ b/halo2_gadgets/src/sinsemilla/merkle/chip.rs @@ -1,3 +1,5 @@ +//! Chip implementing a Merkle hash using Sinsemilla as the hash function. + use halo2_proofs::{ circuit::{AssignedCell, Chip, Layouter}, plonk::{Advice, Column, ConstraintSystem, Error, Selector}, @@ -25,6 +27,7 @@ use crate::{ use group::ff::PrimeField; use std::array; +/// Configuration for the `MerkleChip` implementation. #[derive(Clone, Debug)] pub struct MerkleConfig where @@ -38,6 +41,7 @@ where pub(super) sinsemilla_config: SinsemillaConfig, } +/// Chip implementing `MerkleInstructions`. #[derive(Clone, Debug)] pub struct MerkleChip where @@ -72,6 +76,7 @@ where F: FixedPoints, Commit: CommitDomains, { + /// Configures the [`MerkleChip`]. pub fn configure( meta: &mut ConstraintSystem, sinsemilla_config: SinsemillaConfig, @@ -175,6 +180,7 @@ where } } + /// Constructs a [`MerkleChip`] given a [`MerkleConfig`]. pub fn construct(config: MerkleConfig) -> Self { MerkleChip { config } } diff --git a/halo2_gadgets/src/utilities.rs b/halo2_gadgets/src/utilities.rs index 8eafbbd2..b4d18150 100644 --- a/halo2_gadgets/src/utilities.rs +++ b/halo2_gadgets/src/utilities.rs @@ -8,9 +8,9 @@ use halo2_proofs::{ use pasta_curves::arithmetic::FieldExt; use std::{array, ops::Range}; -pub(crate) mod cond_swap; -pub(crate) mod decompose_running_sum; -pub(crate) mod lookup_range_check; +pub mod cond_swap; +pub mod decompose_running_sum; +pub mod lookup_range_check; /// Trait for a variable in the circuit. pub trait Var: Clone + std::fmt::Debug + From> { diff --git a/halo2_gadgets/src/utilities/cond_swap.rs b/halo2_gadgets/src/utilities/cond_swap.rs index 616d883c..2486924f 100644 --- a/halo2_gadgets/src/utilities/cond_swap.rs +++ b/halo2_gadgets/src/utilities/cond_swap.rs @@ -1,3 +1,5 @@ +//! Gadget and chip for a conditional swap utility. + use super::{bool_check, ternary, UtilitiesInstructions}; use halo2_proofs::{ circuit::{AssignedCell, Chip, Layouter}, @@ -7,6 +9,7 @@ use halo2_proofs::{ use pasta_curves::arithmetic::FieldExt; use std::{array, marker::PhantomData}; +/// Instructions for a conditional swap gadget. pub trait CondSwapInstructions: UtilitiesInstructions { #[allow(clippy::type_complexity)] /// Given an input pair (a,b) and a `swap` boolean flag, returns @@ -42,14 +45,22 @@ impl Chip for CondSwapChip { } } +/// Configuration for the [`CondSwapChip`]. #[derive(Clone, Debug)] pub struct CondSwapConfig { - pub q_swap: Selector, - pub a: Column, - pub b: Column, - pub a_swapped: Column, - pub b_swapped: Column, - pub swap: Column, + q_swap: Selector, + a: Column, + b: Column, + a_swapped: Column, + b_swapped: Column, + swap: Column, +} + +#[cfg(test)] +impl CondSwapConfig { + pub(crate) fn a(&self) -> Column { + self.a + } } impl UtilitiesInstructions for CondSwapChip { @@ -185,6 +196,7 @@ impl CondSwapChip { config } + /// Constructs a [`CondSwapChip`] given a [`CondSwapConfig`]. pub fn construct(config: CondSwapConfig) -> Self { CondSwapChip { config, diff --git a/halo2_gadgets/src/utilities/decompose_running_sum.rs b/halo2_gadgets/src/utilities/decompose_running_sum.rs index 259d7523..1f519f53 100644 --- a/halo2_gadgets/src/utilities/decompose_running_sum.rs +++ b/halo2_gadgets/src/utilities/decompose_running_sum.rs @@ -34,6 +34,7 @@ use pasta_curves::arithmetic::FieldExt; use std::marker::PhantomData; /// The running sum $[z_0, ..., z_W]$. If created in strict mode, $z_W = 0$. +#[derive(Debug)] pub struct RunningSum(Vec>); impl std::ops::Deref for RunningSum { type Target = Vec>; @@ -43,16 +44,22 @@ impl std::ops::Deref for RunningSum { } } +/// Configuration that provides methods for running sum decomposition. #[derive(Debug, Clone, Copy, Eq, PartialEq)] pub struct RunningSumConfig { - pub q_range_check: Selector, - pub z: Column, + q_range_check: Selector, + z: Column, _marker: PhantomData, } impl RunningSumConfig { + /// Returns the q_range_check selector of this [`RunningSumConfig`]. + pub(crate) fn q_range_check(&self) -> Selector { + self.q_range_check + } + /// `perm` MUST include the advice column `z`. /// /// # Panics diff --git a/halo2_gadgets/src/utilities/lookup_range_check.rs b/halo2_gadgets/src/utilities/lookup_range_check.rs index a68fcc59..86889f13 100644 --- a/halo2_gadgets/src/utilities/lookup_range_check.rs +++ b/halo2_gadgets/src/utilities/lookup_range_check.rs @@ -23,12 +23,13 @@ impl std::ops::Deref for RunningSum { } } +/// Configuration that provides methods for a lookup range check. #[derive(Eq, PartialEq, Debug, Clone, Copy)] pub struct LookupRangeCheckConfig { - pub q_lookup: Selector, - pub q_running: Selector, - pub q_bitshift: Selector, - pub running_sum: Column, + q_lookup: Selector, + q_running: Selector, + q_bitshift: Selector, + running_sum: Column, table_idx: TableColumn, _marker: PhantomData, }