Integrate halo2_gadgets into the workspace

THe SHA-256 example gadget has been moved into the `halo2_gadgets` crate
behind an `unstable` feature flag.

Cargo.toml

@@ -1,5 +1,6 @@
 [workspace]
 members = [
     "halo2",
+    "halo2_gadgets",
     "halo2_proofs",
 ]

book/macros-gadgets.txt

@@ -1,24 +0,0 @@
-# Conventions
-
-\bconcat:{\mathop{\kern 0.1em||\kern 0.1em}}
-\Repr:{\star}
-
-# Conversions
-
-\ItoLEBSP:{\mathsf{I2LEBSP}_{#1}}
-
-# Fields and curves
-
-\BaseLength:{\ell^\mathsf{#1\vphantom{p}}_{\mathsf{base}}}
-
-# Commitments and hashes
-
-\SinsemillaHash:{\mathsf{SinsemillaHash}}
-\SinsemillaCommit:{\mathsf{SinsemillaCommit}}
-\SinsemillaShortCommit:{\mathsf{SinsemillaShortCommit}}
-
-# Circuit constraint helper methods
-
-\BoolCheck:{\texttt{bool\_check}({#1})}
-\RangeCheck:{\texttt{range\_check}({#1, #2})}
-\ShortLookupRangeCheck:{\texttt{short\_lookup\_range\_check}({#1})}

book/macros.txt

@@ -1,3 +1,30 @@
+# Conventions
+
+\bconcat:{\mathop{\kern 0.1em||\kern 0.1em}}
+\Repr:{\star}
+
+# Conversions
+
+\ItoLEBSP:{\mathsf{I2LEBSP}_{#1}}
+
+# Fields and curves
+
+\BaseLength:{\ell^\mathsf{#1\vphantom{p}}_{\mathsf{base}}}
+
+# Commitments and hashes
+
+\SinsemillaHash:{\mathsf{SinsemillaHash}}
+\SinsemillaCommit:{\mathsf{SinsemillaCommit}}
+\SinsemillaShortCommit:{\mathsf{SinsemillaShortCommit}}
+
+# Circuit constraint helper methods
+
+\BoolCheck:{\texttt{bool\_check}({#1})}
+\RangeCheck:{\texttt{range\_check}({#1, #2})}
+\ShortLookupRangeCheck:{\texttt{short\_lookup\_range\_check}({#1})}
+
+# Halo 2 proof
+
 \field:{\mathbb{F}}
 \group:{\mathbb{G}}
 \setup:{\textnormal{Setup}}

book/src/SUMMARY.md

@@ -26,6 +26,13 @@
     - [Proofs](design/implementation/proofs.md)
     - [Fields](design/implementation/fields.md)
   - [Gadgets](design/gadgets.md)
+    - [Elliptic curve cryptography](design/gadgets/ecc.md)
+      - [Incomplete and complete addition](design/gadgets/ecc/addition.md)
+      - [Fixed-base scalar multiplication](design/gadgets/ecc/fixed-base-scalar-mul.md)
+      - [Variable-base scalar multiplication](design/gadgets/ecc/var-base-scalar-mul.md)
+    - [Sinsemilla](design/gadgets/sinsemilla.md)
+      - [MerkleCRH](design/gadgets/sinsemilla/merkle-crh.md)
+    - [Decomposition](design/gadgets/decomposition.md)
     - [SHA-256](design/gadgets/sha256.md)
       - [16-bit table chip](design/gadgets/sha256/table16.md)
 - [Background Material](background.md)

book/src/design/gadgets.md

@@ -1,7 +1,7 @@
 # Gadgets
 
-In this section we document some example gadgets and chip designs that are suitable for
-Halo 2.
+In this section we document the gadgets and chip designs provided in the `halo2_gadgets`
+crate.
 
 > Neither these gadgets, nor their implementations, have been reviewed, and they should
 > not be used in production.

halo2_gadgets/COPYING

@@ -1,35 +0,0 @@
-Copyright 2020-2021 The Electric Coin Company
-
-This package ("Original Work") is licensed under the terms of the Bootstrap Open
-Source License, version 1.0, or at your option, any later version ("BOSL"). See
-the file ./LICENSE-BOSL for the terms of the Bootstrap Open Source Licence,
-version 1.0.
-
-Only if this Original Work is included as part of the distribution of one of the
-following projects ("the Project"):
-
-- The Zcash projects published by the Electric Coin Company,
-- The Zebra project published by the Zcash Foundation,
-
-then License is granted to use this package under the BOSL as modified by the
-following clarification and special exception. This exception applies only to
-the Original Work when linked or combined with the Project and not to the
-Original Work when linked, combined, or included in or with any other software
-or project or on a standalone basis.
-
-    Under the terms of the BOSL, linking or combining this Original Work with
-    the Project creates a Derivative Work based upon the Original Work and the
-    terms of the BOSL thus apply to both the Original Work and that Derivative
-    Work. As a special exception to the BOSL, and to allow this Original Work to
-    be linked and combined with the Project without having to apply the BOSL to
-    the other portions of the Project, you are granted permission to link or
-    combine this Original Work with the Project and to copy and distribute the
-    resulting work ("Resulting Work") under the open source license applicable
-    to the Project ("Project License"), provided that any portions of this
-    Original Work included in the Resulting Work remain subject to the BOSL. For
-    clarity, you may continue to treat all other portions of the Project under
-    the Project License, provided that you comply with the BOSL with respect to
-    the Original Work. If you modify this Original Work, your version of the
-    Original Work must remain under the BOSL. You may also extend this exception
-    to your version, but you are not obligated to do so. If you do not wish to
-    do so, delete this exception statement from your version.

halo2_gadgets/Cargo.toml

@@ -10,7 +10,7 @@ authors = [
 ]
 edition = "2018"
 description = "[BETA] Reusable gadgets and chip implementations for Halo 2"
-license-file = "LICENSE-BOSL"
+license-file = "../COPYING"
 repository = "https://github.com/zcash/halo2"
 readme = "README.md"
 categories = ["cryptography"]
@@ -18,7 +18,7 @@ keywords = ["zcash"]
 
 [package.metadata.docs.rs]
 all-features = true
-rustdoc-args = ["--cfg", "docsrs", "--html-in-header", "katex-header.html"]
+rustdoc-args = ["--cfg", "docsrs", "--html-in-header", "../katex-header.html"]
 
 [dependencies]
 arrayvec = "0.7.0"
@@ -26,9 +26,9 @@ bigint = "4"
 bitvec = "0.22"
 ff = "0.11"
 group = "0.11"
-halo2 = "=0.1.0-beta.1"
+halo2 = { package = "halo2_proofs", version = "=0.1.0-beta.1", path = "../halo2_proofs" }
 lazy_static = "1"
-pasta_curves = "0.2.1"
+pasta_curves = "0.3"
 proptest = { version = "1.0.0", optional = true }
 rand = "0.8"
 subtle = "2.3"
@@ -49,6 +49,7 @@ bench = false
 [features]
 dev-graph = ["halo2/dev-graph", "plotters"]
 test-dependencies = ["proptest"]
+unstable = []
 
 [[bench]]
 name = "primitives"
@@ -58,11 +59,7 @@ harness = false
 name = "poseidon"
 harness = false
 
-[profile.release]
-debug = true
-
-[profile.bench]
-debug = true
-
-[patch.crates-io]
-halo2 = { git = "https://github.com/zcash/halo2.git", rev = "f9b3ff2aef09a5a3cb5489d0e7e747e9523d2e6e" }
+[[bench]]
+name = "sha256"
+harness = false
+required-features = ["unstable"]

halo2_gadgets/LICENSE-BOSL

@@ -1,176 +0,0 @@
-=======================================================
-Bootstrap Open Source Licence ("BOSL") v. 1.0
-=======================================================
-This Bootstrap Open Source Licence (the "License") applies to any original work
-of authorship (the "Original Work") whose owner (the "Licensor") has placed the
-following licensing notice adjacent to the copyright notice for the Original
-Work:
-
-*Licensed under the Bootstrap Open Source Licence version 1.0*
-
-1.  **Grant of Copyright License.** Licensor grants You a worldwide,
-    royalty-free, non-exclusive, sublicensable license, for the duration of the
-    copyright in the Original Work, to do the following:
-
-        a. to reproduce the Original Work in copies, either alone or as part of
-        a collective work;
-
-        b. to translate, adapt, alter, transform, modify, or arrange the
-        Original Work, thereby creating derivative works ("Derivative Works")
-        based upon the Original Work;
-
-        c. to distribute or communicate copies of the Original Work and
-        Derivative Works to the public, provided that prior to any such
-        distribution or communication You first place a machine-readable copy
-        of the Source Code of the Original Work and such Derivative Works that
-        You intend to distribute or communicate in an information repository
-        reasonably calculated to permit inexpensive and convenient access
-        thereto by the public (“Information Repository”) for as long as You
-        continue to distribute or communicate said copies, accompanied by an
-        irrevocable offer to license said copies to the public free of charge
-        under this License, said offer valid starting no later than 12 months
-        after You first distribute or communicate said copies;
-
-    d. to perform the Original Work publicly; and
-
-    e. to display the Original Work publicly.
-
-2.  **Grant of Patent License.** Licensor grants You a worldwide, royalty-free,
-non-exclusive, sublicensable license, under patent claims owned or controlled
-by the Licensor that are embodied in the Original Work as furnished by the
-Licensor, for the duration of the patents, to make, use, sell, offer for sale,
-have made, and import the Original Work and Derivative Works.
-
-3.  **Grant of Source Code License.** The "Source Code" for a work means the
-preferred form of the work for making modifications to it and all available
-documentation describing how to modify the work. Licensor agrees to provide a
-machine-readable copy of the Source Code of the Original Work along with each
-copy of the Original Work that Licensor distributes. Licensor reserves the
-right to satisfy this obligation by placing a machine-readable copy of said
-Source Code in an Information Repository for as long as Licensor continues to
-distribute the Original Work.
-
-4.  **Exclusions From License Grant.** Neither the names of Licensor, nor the
-names of any contributors to the Original Work, nor any of their trademarks or
-service marks, may be used to endorse or promote products derived from this
-Original Work without express prior permission of the Licensor. Except as
-expressly stated herein, nothing in this License grants any license to
-Licensor's trademarks, copyrights, patents, trade secrets or any other
-intellectual property. No patent license is granted to make, use, sell, offer
-for sale, have made, or import embodiments of any patent claims other than the
-licensed claims defined in Section 2. No license is granted to the trademarks
-of Licensor even if such marks are included in the Original Work. Nothing in
-this License shall be interpreted to prohibit Licensor from licensing under
-terms different from this License any Original Work that Licensor otherwise
-would have a right to license.
-
-5.  **External Deployment.** The term "External Deployment" means the use,
-distribution, or communication of the Original Work or Derivative Works in any
-way such that the Original Work or Derivative Works may be used by anyone other
-than You, whether those works are distributed or communicated to those persons
-or made available as an application intended for use over a network. As an
-express condition for the grants of license hereunder, You must treat any
-External Deployment by You of the Original Work or a Derivative Work as a
-distribution under section 1(c).
-
-6.  **Attribution Rights.** You must retain, in the Source Code of any
-Derivative Works that You create, all copyright, patent, or trademark notices
-from the Source Code of the Original Work, as well as any notices of licensing
-and any descriptive text identified therein as an "Attribution Notice." You
-must cause the Source Code for any Derivative Works that You create to carry a
-prominent Attribution Notice reasonably calculated to inform recipients that
-You have modified the Original Work.
-
-7.  **Warranty of Provenance and Disclaimer of Warranty.** Licensor warrants
-that the copyright in and to the Original Work and the patent rights granted
-herein by Licensor are owned by the Licensor or are sublicensed to You under
-the terms of this License with the permission of the contributor(s) of those
-copyrights and patent rights. Except as expressly stated in the immediately
-preceding sentence, the Original Work is provided under this License on an "AS
-IS" BASIS and WITHOUT WARRANTY, either express or implied, including, without
-limitation, the warranties of non-infringement, merchantability or fitness for
-a particular purpose. THE ENTIRE RISK AS TO THE QUALITY OF THE ORIGINAL WORK IS
-WITH YOU. This DISCLAIMER OF WARRANTY constitutes an essential part of this
-License. No license to the Original Work is granted by this License except
-under this disclaimer.
-
-8.  **Limitation of Liability.** Under no circumstances and under no legal
-theory, whether in tort (including negligence), contract, or otherwise, shall
-the Licensor be liable to anyone for any indirect, special, incidental, or
-consequential damages of any character arising as a result of this License or
-the use of the Original Work including, without limitation, damages for loss of
-goodwill, work stoppage, computer failure or malfunction, or any and all other
-commercial damages or losses. This limitation of liability shall not apply to
-the extent applicable law prohibits such limitation.
-
-9.  **Acceptance and Termination.** If, at any time, You expressly assented to
-this License, that assent indicates your clear and irrevocable acceptance of
-this License and all of its terms and conditions. If You distribute or
-communicate copies of the Original Work or a Derivative Work, You must make a
-reasonable effort under the circumstances to obtain the express assent of
-recipients to the terms of this License. This License conditions your rights to
-undertake the activities listed in Section 1, including your right to create
-Derivative Works based upon the Original Work, and doing so without honoring
-these terms and conditions is prohibited by copyright law and international
-treaty. Nothing in this License is intended to affect copyright exceptions and
-limitations (including 'fair use' or 'fair dealing'). This License shall
-terminate immediately and You may no longer exercise any of the rights granted
-to You by this License upon your failure to honor the conditions in Section
-1(c).
-
-10.  **Termination for Patent Action.** This License shall terminate
-automatically and You may no longer exercise any of the rights granted to You
-by this License as of the date You commence an action, including a cross-claim
-or counterclaim, against Licensor or any licensee alleging that the Original
-Work infringes a patent. This termination provision shall not apply for an
-action alleging patent infringement by combinations of the Original Work with
-other software or hardware.
-
-11.  **Jurisdiction, Venue and Governing Law.** Any action or suit relating to
-this License may be brought only in the courts of a jurisdiction wherein the
-Licensor resides or in which Licensor conducts its primary business, and under
-the laws of that jurisdiction excluding its conflict-of-law provisions. The
-application of the United Nations Convention on Contracts for the International
-Sale of Goods is expressly excluded. Any use of the Original Work outside the
-scope of this License or after its termination shall be subject to the
-requirements and penalties of copyright or patent law in the appropriate
-jurisdiction. This section shall survive the termination of this License.
-
-12.  **Attorneys' Fees.** In any action to enforce the terms of this License or
-seeking damages relating thereto, the prevailing party shall be entitled to
-recover its costs and expenses, including, without limitation, reasonable
-attorneys' fees and costs incurred in connection with such action, including
-any appeal of such action. This section shall survive the termination of this
-License.
-
-13.  **Miscellaneous.** If any provision of this License is held to be
-unenforceable, such provision shall be reformed only to the extent necessary to
-make it enforceable.
-
-14.  **Definition of "You" in This License.** "You" throughout this License,
-whether in upper or lower case, means an individual or a legal entity
-exercising rights under, and complying with all of the terms of, this License.
-For legal entities, "You" includes any entity that controls, is controlled by,
-or is under common control with you. For purposes of this definition, "control"
-means (i) the power, direct or indirect, to cause the direction or management
-of such entity, whether by contract or otherwise, or (ii) ownership of fifty
-percent (50%) or more of the outstanding shares, or (iii) beneficial ownership
-of such entity.
-
-15.  **Right to Use.** You may use the Original Work in all ways not otherwise
-restricted or conditioned by this License or by law, and Licensor promises not
-to interfere with or be responsible for such uses by You.
-
-16.  **Modification of This License.** This License is Copyright © 2007 Zooko
-Wilcox-O'Hearn. Permission is granted to copy, distribute, or communicate this
-License without modification. Nothing in this License permits You to modify
-this License as applied to the Original Work or to Derivative Works. However,
-You may modify the text of this License and copy, distribute or communicate
-your modified version (the "Modified License") and apply it to other original
-works of authorship subject to the following conditions: (i) You may not
-indicate in any way that your Modified License is the "Bootstrap Open Source
-Licence" or "BOSL" and you may not use those names in the name of your Modified
-License; and (ii) You must replace the notice specified in the first paragraph
-above with the notice "Licensed under <insert your license name here>" or with
-a notice of your own that is not confusingly similar to the notice in this
-License.

halo2_gadgets/README.md

@@ -1,4 +1,4 @@
-# orchard [![Crates.io](https://img.shields.io/crates/v/orchard.svg)](https://crates.io/crates/orchard) #
+# halo2_gadgets [![Crates.io](https://img.shields.io/crates/v/halo2_gadgets.svg)](https://crates.io/crates/halo2_gadgets) #
 
 **IMPORTANT**: This library is being actively developed and should not be used in production software.
 
@@ -6,8 +6,8 @@ Requires Rust 1.51+.
 
 ## Documentation
 
-- [The Orchard Book](https://zcash.github.io/orchard/)
-- [Crate documentation](https://docs.rs/orchard)
+- [The Halo 2 Book](https://zcash.github.io/halo2/)
+- [Crate documentation](https://docs.rs/halo2_gadgets)
 
 ## License
 

halo2_gadgets/benches/poseidon.rs

@@ -4,7 +4,7 @@ use halo2::{
     pasta::Fp,
     plonk::{
         create_proof, keygen_pk, keygen_vk, verify_proof, Advice, Circuit, Column,
-        ConstraintSystem, Error,
+        ConstraintSystem, Error, SingleVerifier,
     },
     poly::commitment::Params,
     transcript::{Blake2bRead, Blake2bWrite, Challenge255},
@@ -234,11 +234,9 @@ fn bench_poseidon<S, const WIDTH: usize, const RATE: usize, const L: usize>(
 
     c.bench_function(&verifier_name, |b| {
         b.iter(|| {
-            let msm = params.empty_msm();
+            let strategy = SingleVerifier::new(&params);
             let mut transcript = Blake2bRead::<_, _, Challenge255<_>>::init(&proof[..]);
-            let guard = verify_proof(&params, pk.get_vk(), msm, &[&[]], &mut transcript).unwrap();
-            let msm = guard.clone().use_challenges();
-            assert!(msm.eval());
+            assert!(verify_proof(&params, pk.get_vk(), strategy, &[&[]], &mut transcript).is_ok());
         });
     });
 }

halo2_gadgets/benches/sha256.rs

@@ -3,12 +3,12 @@ use halo2::{
     pasta::{pallas, EqAffine},
     plonk::{
         create_proof, keygen_pk, keygen_vk, verify_proof, Circuit, ConstraintSystem, Error,
-        VerifyingKey,
+        SingleVerifier, VerifyingKey,
     },
     poly::commitment::Params,
     transcript::{Blake2bRead, Blake2bWrite, Challenge255},
 };
-use rand_core::OsRng;
+use rand::rngs::OsRng;
 
 use std::{
     fs::File,
@@ -18,7 +18,7 @@ use std::{
 
 use criterion::{criterion_group, criterion_main, Criterion};
 
-use crate::{BlockWord, Sha256, Table16Chip, Table16Config, BLOCK_SIZE};
+use halo2_gadgets::sha256::{BlockWord, Sha256, Table16Chip, Table16Config, BLOCK_SIZE};
 
 #[allow(dead_code)]
 fn bench(name: &str, k: u32, c: &mut Criterion) {
@@ -150,12 +150,9 @@ fn bench(name: &str, k: u32, c: &mut Criterion) {
 
     c.bench_function(&verifier_name, |b| {
         b.iter(|| {
-            let msm = params.empty_msm();
+            let strategy = SingleVerifier::new(&params);
             let mut transcript = Blake2bRead::<_, _, Challenge255<_>>::init(&proof[..]);
-            let guard =
-                verify_proof(&params, pk.get_vk(), msm, &[], OsRng, &mut transcript).unwrap();
-            let msm = guard.clone().use_challenges();
-            assert!(msm.eval());
+            assert!(verify_proof(&params, pk.get_vk(), strategy, &[], &mut transcript).is_ok());
         });
     });
 }

halo2_gadgets/src/ecc/chip/constants.rs

@@ -39,7 +39,7 @@ pub(crate) const T_P: u128 = 45560315531419706090280762371685220353;
 
 /// For each fixed base, we calculate its scalar multiples in three-bit windows.
 /// Each window will have $2^3 = 8$ points. The tables are computed as described in
-/// [the Orchard book](https://zcash.github.io/orchard/design/circuit/gadgets/ecc/fixed-base-scalar-mul.html#load-fixed-base).
+/// [the Halo 2 book](https://zcash.github.io/halo2/design/gadgets/ecc/fixed-base-scalar-mul.html#load-fixed-base).
 fn compute_window_table<C: CurveAffine>(base: C, num_windows: usize) -> Vec<[C; H]> {
     let mut window_table: Vec<[C; H]> = Vec::with_capacity(num_windows);
 
@@ -160,9 +160,11 @@ pub fn test_zs_and_us<C: CurveAffine>(base: C, z: &[u64], u: &[[[u8; 32]; H]], n
     for ((u, z), window_points) in u.iter().zip(z.iter()).zip(window_table) {
         for (u, point) in u.iter().zip(window_points.iter()) {
             let y = *point.coordinates().unwrap().y();
-            let u = C::Base::from_bytes(u).unwrap();
-            assert_eq!(C::Base::from_u64(*z) + y, u * u); // allow either square root
-            assert!(bool::from((C::Base::from_u64(*z) - y).sqrt().is_none()));
+            let mut u_repr = <C::Base as PrimeField>::Repr::default();
+            u_repr.as_mut().copy_from_slice(u);
+            let u = C::Base::from_repr(u_repr).unwrap();
+            assert_eq!(C::Base::from(*z) + y, u * u); // allow either square root
+            assert!(bool::from((C::Base::from(*z) - y).sqrt().is_none()));
         }
     }
 }

halo2_gadgets/src/ecc/chip/mul_fixed.rs

@@ -314,7 +314,7 @@ impl<FixedPoints: super::FixedPoints<pallas::Affine>> Config<FixedPoints> {
         };
 
         // Assign u = (y_p + z_w).sqrt()
-        let u_val = k_usize.map(|k| pallas::Base::from_bytes(&base_u[w][k]).unwrap());
+        let u_val = k_usize.map(|k| pallas::Base::from_repr(base_u[w][k]).unwrap());
         region.assign_advice(|| "u", self.u, offset + w, || u_val.ok_or(Error::Synthesis))?;
 
         Ok(mul_b)
@@ -376,7 +376,7 @@ impl<FixedPoints: super::FixedPoints<pallas::Affine>> Config<FixedPoints> {
         // Assign u = (y_p + z_w).sqrt() for the most significant window
         {
             let u_val = scalar.windows_usize()[NUM_WINDOWS - 1]
-                .map(|k| pallas::Base::from_bytes(&base.u()[NUM_WINDOWS - 1][k]).unwrap());
+                .map(|k| pallas::Base::from_repr(base.u()[NUM_WINDOWS - 1][k]).unwrap());
             region.assign_advice(
                 || "u",
                 self.u,
@@ -491,6 +491,8 @@ impl ScalarFixed {
             .iter()
             .map(|window| {
                 if let Some(window) = window {
+                    // TODO: Remove this trait dependency
+                    use pasta_curves::arithmetic::SqrtRatio;
                     let window = window.get_lower_32() as usize;
                     assert!(window < H);
                     Some(window)

halo2_gadgets/src/lib.rs

@@ -1,11 +1,4 @@
-//! # orchard
-//!
-//! ## Nomenclature
-//!
-//! All types in the `orchard` crate, unless otherwise specified, are Orchard-specific
-//! types. For example, [`Address`] is documented as being a shielded payment address; we
-//! implicitly mean it is an Orchard payment address (as opposed to e.g. a Sapling payment
-//! address, which is also shielded).
+//! # halo2_gadgets
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
 // Temporary until we have more of the crate implemented.
@@ -18,6 +11,8 @@
 
 pub mod ecc;
 pub mod poseidon;
+#[cfg(feature = "unstable")]
+pub mod sha256;
 pub mod sinsemilla;
 pub mod utilities;
 

halo2_gadgets/src/sha256.rs

@@ -12,7 +12,6 @@ use halo2::{
     plonk::Error,
 };
 
-mod benches;
 mod table16;
 
 pub use table16::{BlockWord, Table16Chip, Table16Config};
@@ -165,5 +164,3 @@ impl<F: FieldExt, Sha256Chip: Sha256Instructions<F>> Sha256<F, Sha256Chip> {
         hasher.finalize(layouter.namespace(|| "finalize"))
     }
 }
-
-fn main() {}

halo2_gadgets/src/sha256/table16.rs

@@ -48,7 +48,8 @@ const IV: [u32; STATE] = [
 
 #[derive(Clone, Copy, Debug, Default)]
 /// A word in a `Table16` message block.
-pub struct BlockWord(pub(crate) Option<u32>);
+// TODO: Make the internals of this struct private.
+pub struct BlockWord(pub Option<u32>);
 
 #[derive(Clone, Debug)]
 /// Little-endian bits (up to 64 bits)
@@ -255,6 +256,7 @@ impl Chip<pallas::Base> for Table16Chip {
 }
 
 impl Table16Chip {
+    /// Reconstructs this chip from the given config.
     pub fn construct(config: <Self as Chip<pallas::Base>>::Config) -> Self {
         Self {
             config,
@@ -262,6 +264,7 @@ impl Table16Chip {
         }
     }
 
+    /// Configures a circuit to include this chip.
     pub fn configure(
         meta: &mut ConstraintSystem<pallas::Base>,
     ) -> <Self as Chip<pallas::Base>>::Config {
@@ -314,6 +317,7 @@ impl Table16Chip {
         }
     }
 
+    /// Loads the lookup table required by this chip into the circuit.
     pub fn load(
         config: Table16Config,
         layouter: &mut impl Layouter<pallas::Base>,

halo2_gadgets/src/sha256/table16/compression/compression_util.rs

@@ -2,7 +2,9 @@ use super::{
     AbcdVar, CompressionConfig, EfghVar, RoundWord, RoundWordA, RoundWordDense, RoundWordE,
     RoundWordSpread, State, UpperSigmaVar,
 };
-use crate::table16::{util::*, AssignedBits, SpreadVar, SpreadWord, StateWord, Table16Assignment};
+use crate::sha256::table16::{
+    util::*, AssignedBits, SpreadVar, SpreadWord, StateWord, Table16Assignment,
+};
 use halo2::{
     circuit::Region,
     pasta::pallas,