Crate docs
This commit is contained in:
parent
701cb2b348
commit
f50079f03d
|
@ -1,14 +1,15 @@
|
||||||
//! This module contains an `EvaluationDomain` abstraction for
|
//! This module contains an [`EvaluationDomain`] abstraction for performing
|
||||||
//! performing various kinds of polynomial arithmetic on top of
|
//! various kinds of polynomial arithmetic on top of the scalar field.
|
||||||
//! the scalar field.
|
|
||||||
//!
|
//!
|
||||||
//! In pairing-based SNARKs like Groth16, we need to calculate
|
//! In pairing-based SNARKs like [Groth16], we need to calculate a quotient
|
||||||
//! a quotient polynomial over a target polynomial with roots
|
//! polynomial over a target polynomial with roots at distinct points associated
|
||||||
//! at distinct points associated with each constraint of the
|
//! with each constraint of the constraint system. In order to be efficient, we
|
||||||
//! constraint system. In order to be efficient, we choose these
|
//! choose these roots to be the powers of a 2<sup>n</sup> root of unity in the
|
||||||
//! roots to be the powers of a 2^n root of unity in the field.
|
//! field. This allows us to perform polynomial operations in O(n) by performing
|
||||||
//! This allows us to perform polynomial operations in O(n)
|
//! an O(n log n) FFT over such a domain.
|
||||||
//! by performing an O(n log n) FFT over such a domain.
|
//!
|
||||||
|
//! [`EvaluationDomain`]: crate::domain::EvaluationDomain
|
||||||
|
//! [Groth16]: https://eprint.iacr.org/2016/260
|
||||||
|
|
||||||
use ff::{Field, PrimeField, ScalarEngine};
|
use ff::{Field, PrimeField, ScalarEngine};
|
||||||
use group::CurveProjective;
|
use group::CurveProjective;
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
//! Self-contained sub-circuit implementations for various primitives.
|
||||||
|
|
||||||
pub mod test;
|
pub mod test;
|
||||||
|
|
||||||
pub mod blake2s;
|
pub mod blake2s;
|
||||||
|
|
|
@ -1,3 +1,7 @@
|
||||||
|
//! The [BLAKE2s] hash function with personalization support.
|
||||||
|
//!
|
||||||
|
//! [BLAKE2s]: https://tools.ietf.org/html/rfc7693
|
||||||
|
|
||||||
use super::{boolean::Boolean, multieq::MultiEq, uint32::UInt32};
|
use super::{boolean::Boolean, multieq::MultiEq, uint32::UInt32};
|
||||||
use crate::{ConstraintSystem, SynthesisError};
|
use crate::{ConstraintSystem, SynthesisError};
|
||||||
use ff::ScalarEngine;
|
use ff::ScalarEngine;
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
//! Gadgets for allocating bits in the circuit and performing boolean logic.
|
||||||
|
|
||||||
use ff::{BitIterator, Field, PrimeField, ScalarEngine};
|
use ff::{BitIterator, Field, PrimeField, ScalarEngine};
|
||||||
|
|
||||||
use crate::{ConstraintSystem, LinearCombination, SynthesisError, Variable};
|
use crate::{ConstraintSystem, LinearCombination, SynthesisError, Variable};
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
//! Window table lookup gadgets.
|
||||||
|
|
||||||
use ff::{Field, ScalarEngine};
|
use ff::{Field, ScalarEngine};
|
||||||
|
|
||||||
use super::boolean::Boolean;
|
use super::boolean::Boolean;
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
//! Helpers for packing vectors of bits into scalar field elements.
|
||||||
|
|
||||||
use super::boolean::Boolean;
|
use super::boolean::Boolean;
|
||||||
use super::num::Num;
|
use super::num::Num;
|
||||||
use super::Assignment;
|
use super::Assignment;
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
//! Gadgets representing numbers in the scalar field of the underlying curve.
|
||||||
|
|
||||||
use ff::{BitIterator, Field, PrimeField, PrimeFieldRepr, ScalarEngine};
|
use ff::{BitIterator, Field, PrimeField, PrimeFieldRepr, ScalarEngine};
|
||||||
|
|
||||||
use crate::{ConstraintSystem, LinearCombination, SynthesisError, Variable};
|
use crate::{ConstraintSystem, LinearCombination, SynthesisError, Variable};
|
||||||
|
|
|
@ -1,3 +1,8 @@
|
||||||
|
//! Circuits for the [SHA-256] hash function and its internal compression
|
||||||
|
//! function.
|
||||||
|
//!
|
||||||
|
//! [SHA-256]: https://tools.ietf.org/html/rfc6234
|
||||||
|
|
||||||
use super::boolean::Boolean;
|
use super::boolean::Boolean;
|
||||||
use super::multieq::MultiEq;
|
use super::multieq::MultiEq;
|
||||||
use super::uint32::UInt32;
|
use super::uint32::UInt32;
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
//! Helpers for testing circuit implementations.
|
||||||
|
|
||||||
use ff::{Field, PrimeField, PrimeFieldRepr, ScalarEngine};
|
use ff::{Field, PrimeField, PrimeFieldRepr, ScalarEngine};
|
||||||
|
|
||||||
use crate::{ConstraintSystem, Index, LinearCombination, SynthesisError, Variable};
|
use crate::{ConstraintSystem, Index, LinearCombination, SynthesisError, Variable};
|
||||||
|
|
|
@ -1,3 +1,6 @@
|
||||||
|
//! Circuit representation of a [`u32`], with helpers for the [`sha256`]
|
||||||
|
//! gadgets.
|
||||||
|
|
||||||
use ff::{Field, PrimeField, ScalarEngine};
|
use ff::{Field, PrimeField, ScalarEngine};
|
||||||
|
|
||||||
use crate::{ConstraintSystem, LinearCombination, SynthesisError};
|
use crate::{ConstraintSystem, LinearCombination, SynthesisError};
|
||||||
|
|
|
@ -1,3 +1,7 @@
|
||||||
|
//! The [Groth16] proving system.
|
||||||
|
//!
|
||||||
|
//! [Groth16]: https://eprint.iacr.org/2016/260
|
||||||
|
|
||||||
use group::{CurveAffine, EncodedPoint};
|
use group::{CurveAffine, EncodedPoint};
|
||||||
use pairing::{Engine, PairingCurveAffine};
|
use pairing::{Engine, PairingCurveAffine};
|
||||||
|
|
||||||
|
|
134
src/lib.rs
134
src/lib.rs
|
@ -1,3 +1,137 @@
|
||||||
|
//! `bellman` is a crate for building zk-SNARK circuits. It provides circuit
|
||||||
|
//! traits and and primitive structures, as well as basic gadget implementations
|
||||||
|
//! such as booleans and number abstractions.
|
||||||
|
//!
|
||||||
|
//! # Example circuit
|
||||||
|
//!
|
||||||
|
//! Say we want to write a circuit that proves we know the preimage to some hash
|
||||||
|
//! computed using SHA-256d (calling SHA-256 twice). The preimage must have a
|
||||||
|
//! fixed length known in advance (because the circuit parameters will depend on
|
||||||
|
//! it), but can otherwise have any value. We take the following strategy:
|
||||||
|
//!
|
||||||
|
//! - Witness each bit of the preimage.
|
||||||
|
//! - Compute `hash = SHA-256d(preimage)` inside the circuit.
|
||||||
|
//! - Expose `hash` as a public input using multiscalar packing.
|
||||||
|
//!
|
||||||
|
//! ```
|
||||||
|
//! use bellman::{
|
||||||
|
//! gadgets::{
|
||||||
|
//! boolean::{AllocatedBit, Boolean},
|
||||||
|
//! multipack,
|
||||||
|
//! sha256::sha256,
|
||||||
|
//! },
|
||||||
|
//! groth16, Circuit, ConstraintSystem, SynthesisError,
|
||||||
|
//! };
|
||||||
|
//! use pairing::{bls12_381::Bls12, Engine};
|
||||||
|
//! use rand::rngs::OsRng;
|
||||||
|
//! use sha2::{Digest, Sha256};
|
||||||
|
//!
|
||||||
|
//! /// Our own SHA-256d gadget. Input and output are in little-endian bit order.
|
||||||
|
//! fn sha256d<E: Engine, CS: ConstraintSystem<E>>(
|
||||||
|
//! mut cs: CS,
|
||||||
|
//! data: &[Boolean],
|
||||||
|
//! ) -> Result<Vec<Boolean>, SynthesisError> {
|
||||||
|
//! // Flip endianness of each input byte
|
||||||
|
//! let input: Vec<_> = data
|
||||||
|
//! .chunks(8)
|
||||||
|
//! .map(|c| c.iter().rev())
|
||||||
|
//! .flatten()
|
||||||
|
//! .cloned()
|
||||||
|
//! .collect();
|
||||||
|
//!
|
||||||
|
//! let mid = sha256(cs.namespace(|| "SHA-256(input)"), &input)?;
|
||||||
|
//! let res = sha256(cs.namespace(|| "SHA-256(mid)"), &mid)?;
|
||||||
|
//!
|
||||||
|
//! // Flip endianness of each output byte
|
||||||
|
//! Ok(res
|
||||||
|
//! .chunks(8)
|
||||||
|
//! .map(|c| c.iter().rev())
|
||||||
|
//! .flatten()
|
||||||
|
//! .cloned()
|
||||||
|
//! .collect())
|
||||||
|
//! }
|
||||||
|
//!
|
||||||
|
//! struct MyCircuit {
|
||||||
|
//! /// The input to SHA-256d we are proving that we know. Set to `None` when we
|
||||||
|
//! /// are verifying a proof (and do not have the witness data).
|
||||||
|
//! preimage: Option<[u8; 80]>,
|
||||||
|
//! }
|
||||||
|
//!
|
||||||
|
//! impl<E: Engine> Circuit<E> for MyCircuit {
|
||||||
|
//! fn synthesize<CS: ConstraintSystem<E>>(self, cs: &mut CS) -> Result<(), SynthesisError> {
|
||||||
|
//! // Compute the values for the bits of the preimage. If we are verifying a proof,
|
||||||
|
//! // we still need to create the same constraints, so we return an equivalent-size
|
||||||
|
//! // Vec of None (indicating that the value of each bit is unknown).
|
||||||
|
//! let bit_values = if let Some(preimage) = self.preimage {
|
||||||
|
//! preimage
|
||||||
|
//! .into_iter()
|
||||||
|
//! .map(|byte| (0..8).map(move |i| (byte >> i) & 1u8 == 1u8))
|
||||||
|
//! .flatten()
|
||||||
|
//! .map(|b| Some(b))
|
||||||
|
//! .collect()
|
||||||
|
//! } else {
|
||||||
|
//! vec![None; 80 * 8]
|
||||||
|
//! };
|
||||||
|
//! assert_eq!(bit_values.len(), 80 * 8);
|
||||||
|
//!
|
||||||
|
//! // Witness the bits of the preimage.
|
||||||
|
//! let preimage_bits = bit_values
|
||||||
|
//! .into_iter()
|
||||||
|
//! .enumerate()
|
||||||
|
//! // Allocate each bit.
|
||||||
|
//! .map(|(i, b)| {
|
||||||
|
//! AllocatedBit::alloc(cs.namespace(|| format!("preimage bit {}", i)), b)
|
||||||
|
//! })
|
||||||
|
//! // Convert the AllocatedBits into Booleans (required for the sha256 gadget).
|
||||||
|
//! .map(|b| b.map(Boolean::from))
|
||||||
|
//! .collect::<Result<Vec<_>, _>>()?;
|
||||||
|
//!
|
||||||
|
//! // Compute hash = SHA-256d(preimage).
|
||||||
|
//! let hash = sha256d(cs.namespace(|| "SHA-256d(preimage)"), &preimage_bits)?;
|
||||||
|
//!
|
||||||
|
//! // Expose the vector of 32 boolean variables as compact public inputs.
|
||||||
|
//! multipack::pack_into_inputs(cs.namespace(|| "pack hash"), &hash)
|
||||||
|
//! }
|
||||||
|
//! }
|
||||||
|
//!
|
||||||
|
//! // Create parameters for our circuit. In a production deployment these would
|
||||||
|
//! // be generated securely using a multiparty computation.
|
||||||
|
//! let params = {
|
||||||
|
//! let c = MyCircuit { preimage: None };
|
||||||
|
//! groth16::generate_random_parameters::<Bls12, _, _>(c, &mut OsRng).unwrap()
|
||||||
|
//! };
|
||||||
|
//!
|
||||||
|
//! // Prepare the verification key (for proof verification).
|
||||||
|
//! let pvk = groth16::prepare_verifying_key(¶ms.vk);
|
||||||
|
//!
|
||||||
|
//! // Pick a preimage and compute its hash.
|
||||||
|
//! let preimage = [42; 80];
|
||||||
|
//! let hash = Sha256::digest(&Sha256::digest(&preimage));
|
||||||
|
//!
|
||||||
|
//! // Create an instance of our circuit (with the preimage as a witness).
|
||||||
|
//! let c = MyCircuit {
|
||||||
|
//! preimage: Some(preimage),
|
||||||
|
//! };
|
||||||
|
//!
|
||||||
|
//! // Create a Groth16 proof with our parameters.
|
||||||
|
//! let proof = groth16::create_random_proof(c, ¶ms, &mut OsRng).unwrap();
|
||||||
|
//!
|
||||||
|
//! // Pack the hash as inputs for proof verification.
|
||||||
|
//! let hash_bits = multipack::bytes_to_bits_le(&hash);
|
||||||
|
//! let inputs = multipack::compute_multipacking::<Bls12>(&hash_bits);
|
||||||
|
//!
|
||||||
|
//! // Check the proof!
|
||||||
|
//! assert!(groth16::verify_proof(&pvk, &proof, &inputs).unwrap());
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! # Roadmap
|
||||||
|
//!
|
||||||
|
//! `bellman` is being refactored into a generic proving library. Currently it
|
||||||
|
//! is pairing-specific, and different types of proving systems need to be
|
||||||
|
//! implemented as sub-modules. After the refactor, `bellman` will be generic
|
||||||
|
//! using the [`ff`] and [`group`] crates, while specific proving systems will
|
||||||
|
//! be separate crates that pull in the dependencies they require.
|
||||||
|
|
||||||
// Catch documentation errors caused by code changes.
|
// Catch documentation errors caused by code changes.
|
||||||
#![deny(intra_doc_link_resolution_failure)]
|
#![deny(intra_doc_link_resolution_failure)]
|
||||||
|
|
||||||
|
|
|
@ -1,8 +1,9 @@
|
||||||
//! This is an interface for dealing with the kinds of
|
//! An interface for dealing with the kinds of parallel computations involved in
|
||||||
//! parallel computations involved in bellman. It's
|
//! `bellman`. It's currently just a thin wrapper around [`CpuPool`] and
|
||||||
//! currently just a thin wrapper around CpuPool and
|
//! [`crossbeam`] but may be extended in the future to allow for various
|
||||||
//! crossbeam but may be extended in the future to
|
//! parallelism strategies.
|
||||||
//! allow for various parallelism strategies.
|
//!
|
||||||
|
//! [`CpuPool`]: futures_cpupool::CpuPool
|
||||||
|
|
||||||
#[cfg(feature = "multicore")]
|
#[cfg(feature = "multicore")]
|
||||||
mod implementation {
|
mod implementation {
|
||||||
|
|
Loading…
Reference in New Issue