From 82804e4201f675fda91119414c706d07e4ecd4fe Mon Sep 17 00:00:00 2001 From: Robin Salen Date: Mon, 8 Jan 2024 15:14:26 +0100 Subject: [PATCH] Add some more + module doc --- plonky2/src/fri/mod.rs | 3 +++ plonky2/src/gadgets/mod.rs | 3 ++- plonky2/src/gates/mod.rs | 22 +++++++++++++++++++ plonky2/src/hash/mod.rs | 3 +++ plonky2/src/lib.rs | 1 + plonky2/src/plonk/circuit_builder.rs | 4 ++-- plonky2/src/plonk/mod.rs | 5 +++++ plonky2/src/recursion/mod.rs | 6 +++++ plonky2/src/util/mod.rs | 2 ++ .../util/serialization/gate_serialization.rs | 2 +- .../serialization/generator_serialization.rs | 2 +- 11 files changed, 48 insertions(+), 5 deletions(-) diff --git a/plonky2/src/fri/mod.rs b/plonky2/src/fri/mod.rs index 100ae851..11d469f4 100644 --- a/plonky2/src/fri/mod.rs +++ b/plonky2/src/fri/mod.rs @@ -1,3 +1,6 @@ +//! Fast Reed-Solomon IOP (FRI) protocol and its circuit version +//! of the FRI verifier for recursive proof composition. + use alloc::vec::Vec; use serde::Serialize; diff --git a/plonky2/src/gadgets/mod.rs b/plonky2/src/gadgets/mod.rs index ba19e667..cc14a835 100644 --- a/plonky2/src/gadgets/mod.rs +++ b/plonky2/src/gadgets/mod.rs @@ -1,4 +1,5 @@ -//! Gadgets provide additional methods to [`CircuitBuilder`] +//! Helper gadgets providing additional methods to +//! [CircuitBuilder](crate::plonk::circuit_builder::CircuitBuilder), //! to ease circuit creation. pub mod arithmetic; diff --git a/plonky2/src/gates/mod.rs b/plonky2/src/gates/mod.rs index 432f0264..446f1aed 100644 --- a/plonky2/src/gates/mod.rs +++ b/plonky2/src/gates/mod.rs @@ -1,3 +1,25 @@ +//! plonky2 custom gates. +//! +//! Vanilla Plonk arithmetization only supports basic fan-in 2 / fan-out 1 arithmetic gates, +//! each of the form +//! +//! $$ a.b.q_M + a.q_L + b.q_R + c.q_O + q_C = 0 $$ +//! +//! where: +//! - q_M, q_L, q_R and q_O are boolean selectors, +//! - a, b and c are values used as inputs and output respectively, +//! - q_C is a constant (possibly 0). +//! +//! This allows expressing simple operations like multiplication, addition, etc. For +//! instance, to define a multiplication, one can set q_M=1, q_L=q_R=0, q_O = -1 and q_C = 0. +//! Hence, the gate equation simplifies to a.b - c = 0, or a.b = c. +//! +//! However, such gate is fairly limited for more complex computations. Hence, when a computation may +//! require too many of these "vanilla" gates, or when a computation arises often within the same circuit, +//! one may want to construct a tailored custom gate. These custom gates can use more selectors and are +//! not necessarily limited to 2 inputs + 1 output = 3 wires. +//! For instance, plonky2 supports natively a custom Poseidon hash gate that uses 135 wires. + // Gates have `new` methods that return `GateRef`s. pub mod arithmetic_base; diff --git a/plonky2/src/hash/mod.rs b/plonky2/src/hash/mod.rs index b8293920..c98c5706 100644 --- a/plonky2/src/hash/mod.rs +++ b/plonky2/src/hash/mod.rs @@ -1,3 +1,6 @@ +//! plonky2 hashing logic for in-circuit hashing and Merkle proof verification +//! as well as specific hash functions implementation. + mod arch; pub mod hash_types; pub mod hashing; diff --git a/plonky2/src/lib.rs b/plonky2/src/lib.rs index b02fc21b..44bc2cf6 100644 --- a/plonky2/src/lib.rs +++ b/plonky2/src/lib.rs @@ -4,6 +4,7 @@ pub extern crate alloc; +/// Re-export of `plonky2_field`. #[doc(inline)] pub use plonky2_field as field; diff --git a/plonky2/src/plonk/circuit_builder.rs b/plonky2/src/plonk/circuit_builder.rs index c0e0d870..4a1eee90 100644 --- a/plonky2/src/plonk/circuit_builder.rs +++ b/plonky2/src/plonk/circuit_builder.rs @@ -136,7 +136,7 @@ pub struct LookupWire { /// assert!(circuit_data.verify(proof).is_ok()); /// ``` pub struct CircuitBuilder, const D: usize> { - /// Circuit configuration to be used by this `CircuitBuilder`. + /// Circuit configuration to be used by this [`CircuitBuilder`]. pub config: CircuitConfig, /// A domain separator, which is included in the initial Fiat-Shamir seed. This is generally not @@ -179,7 +179,7 @@ pub struct CircuitBuilder, const D: usize> { /// List of constant generators used to fill the constant wires. constant_generators: Vec>, - /// Rows for each LUT: LookupWire contains: first `LookupGate`, first `LookupTableGate`, last `LookupTableGate`. + /// Rows for each LUT: LookupWire contains: first `LookupGate`, first [`LookupTableGate`], last `LookupTableGate`. lookup_rows: Vec, /// For each LUT index, vector of `(looking_in, looking_out)` pairs. diff --git a/plonky2/src/plonk/mod.rs b/plonky2/src/plonk/mod.rs index 604c1f79..565b1c57 100644 --- a/plonky2/src/plonk/mod.rs +++ b/plonky2/src/plonk/mod.rs @@ -1,3 +1,8 @@ +//! plonky2 proving system. +//! +//! This module also defines the [CircuitBuilder](circuit_builder::CircuitBuilder) +//! structure, used to build custom plonky2 circuits satisfying arbitrary statements. + pub mod circuit_builder; pub mod circuit_data; pub mod config; diff --git a/plonky2/src/recursion/mod.rs b/plonky2/src/recursion/mod.rs index 0e9cd2cc..438f6007 100644 --- a/plonky2/src/recursion/mod.rs +++ b/plonky2/src/recursion/mod.rs @@ -1,3 +1,9 @@ +//! Recursion logic for verifying recursively plonky2 circuits. +//! +//! This module also provides ways to perform conditional recursive verification +//! (between two different circuits, depending on a condition), and cyclic +//! recursion where a circuit implements its own verification logic. + pub mod conditional_recursive_verifier; pub mod cyclic_recursion; pub mod dummy_circuit; diff --git a/plonky2/src/util/mod.rs b/plonky2/src/util/mod.rs index fc2c4f09..e0f71f12 100644 --- a/plonky2/src/util/mod.rs +++ b/plonky2/src/util/mod.rs @@ -1,3 +1,5 @@ +//! Utility module for helper methods and plonky2 serialization logic. + use alloc::vec::Vec; use plonky2_maybe_rayon::*; diff --git a/plonky2/src/util/serialization/gate_serialization.rs b/plonky2/src/util/serialization/gate_serialization.rs index d858a057..c5763fb0 100644 --- a/plonky2/src/util/serialization/gate_serialization.rs +++ b/plonky2/src/util/serialization/gate_serialization.rs @@ -59,7 +59,7 @@ macro_rules! get_gate_tag_impl { } #[macro_export] -/// Macro implementing the `GateSerializer` trait. +/// Macro implementing the [`GateSerializer`] trait. /// To serialize a list of gates used for a circuit, /// this macro should be called with a struct on which to implement /// this as first argument, followed by all the targeted gates. diff --git a/plonky2/src/util/serialization/generator_serialization.rs b/plonky2/src/util/serialization/generator_serialization.rs index 19a22a77..bad24ceb 100644 --- a/plonky2/src/util/serialization/generator_serialization.rs +++ b/plonky2/src/util/serialization/generator_serialization.rs @@ -63,7 +63,7 @@ macro_rules! get_generator_tag_impl { } #[macro_export] -/// Macro implementing the `WitnessGeneratorSerializer` trait. +/// Macro implementing the [`WitnessGeneratorSerializer`] trait. /// To serialize a list of generators used for a circuit, /// this macro should be called with a struct on which to implement /// this as first argument, followed by all the targeted generators.