1//! This crate implements common "gadgets" that make
  2//! programming rank-1 constraint systems easier.
  3#![cfg_attr(not(feature = "std"), no_std)]
  4#![deny(unused_import_braces, unused_qualifications, trivial_casts)]
  5#![deny(trivial_numeric_casts, variant_size_differences, unreachable_pub)]
  6#![deny(non_shorthand_field_patterns, unused_attributes, unused_imports)]
  7#![deny(unused_extern_crates, renamed_and_removed_lints, unused_allocation)]
  8#![deny(unused_comparisons, bare_trait_objects, const_err, unused_must_use)]
  9#![deny(unused_mut, unused_unsafe, private_in_public, unsafe_code)]
 10#![deny(missing_docs)]
 11#![forbid(unsafe_code)]
 12
 13#[doc(hidden)]
 14#[cfg(all(test, not(feature = "std")))]
 15#[macro_use]
 16extern crate std;
 17
 18#[doc(hidden)]
 19#[cfg(not(feature = "std"))]
 20extern crate alloc as ralloc;
 21
 22#[doc(hidden)]
 23#[macro_use]
 24extern crate algebra;
 25
 26#[doc(hidden)]
 27#[macro_use]
 28extern crate derivative;
 29
 30/// Some utility macros for making downstream impls easier.
 31#[macro_use]
 32pub mod macros;
 33
 34#[cfg(not(feature = "std"))]
 35use ralloc::vec::Vec;
 36
 37#[cfg(feature = "std")]
 38use std::vec::Vec;
 39
 40use algebra::prelude::Field;
 41
 42/// This module implements gadgets related to bit manipulation, such as `Boolean` and `UInt`s.
 43pub mod bits;
 44pub use self::bits::*;
 45
 46/// This module implements gadgets related to field arithmetic.
 47pub mod fields;
 48
 49/// This module implements gadgets related to group arithmetic, and specifically elliptic curve arithmetic.
 50pub mod groups;
 51
 52mod instantiated;
 53
 54#[cfg(feature = "bls12_377")]
 55pub use instantiated::bls12_377;
 56
 57#[cfg(feature = "ed_on_bn254")]
 58pub use instantiated::ed_on_bn254;
 59
 60#[cfg(feature = "ed_on_bls12_377")]
 61pub use instantiated::ed_on_bls12_377;
 62
 63#[cfg(feature = "ed_on_mnt4_298")]
 64pub use instantiated::ed_on_mnt4_298;
 65
 66#[cfg(feature = "ed_on_mnt4_753")]
 67pub use instantiated::ed_on_mnt4_753;
 68
 69#[cfg(feature = "ed_on_cp6_782")]
 70pub use instantiated::ed_on_cp6_782;
 71
 72#[cfg(feature = "ed_on_bw6_761")]
 73pub use instantiated::ed_on_bw6_761;
 74
 75#[cfg(feature = "ed_on_bls12_381")]
 76pub use instantiated::ed_on_bls12_381;
 77
 78#[cfg(feature = "mnt4_298")]
 79pub use instantiated::mnt4_298;
 80
 81#[cfg(feature = "mnt4_753")]
 82pub use instantiated::mnt4_753;
 83
 84#[cfg(feature = "mnt6_298")]
 85pub use instantiated::mnt6_298;
 86
 87#[cfg(feature = "mnt6_753")]
 88pub use instantiated::mnt6_753;
 89
 90/// This module implements gadgets related to computing pairings in bilinear groups.
 91pub mod pairing;
 92
 93/// This module describes a trait for allocating new variables in a constraint system.
 94pub mod alloc;
 95/// This module describes a trait for checking equality of variables.
 96pub mod eq;
 97/// This module describes traits for conditionally selecting a variable from a list of variables.
 98pub mod select;
 99
100#[allow(missing_docs)]
101pub mod prelude {
102    pub use crate::{
103        alloc::*,
104        bits::{boolean::Boolean, uint32::UInt32, uint8::UInt8, ToBitsGadget, ToBytesGadget},
105        eq::*,
106        fields::{FieldOpsBounds, FieldVar},
107        groups::{CurveVar, GroupOpsBounds},
108        instantiated::*,
109        pairing::PairingVar,
110        select::*,
111        R1CSVar,
112    };
113}
114
115/// This trait describes some core functionality that is common to high-level variables,
116/// such as `Boolean`s, `FieldVar`s, `GroupVar`s, etc.
117pub trait R1CSVar<F: Field> {
118    /// The type of the "native" value that `Self` represents in the constraint system.
119    type Value: core::fmt::Debug + Eq + Clone;
120
121    /// Returns the underlying `ConstraintSystemRef`.
122    fn cs(&self) -> Option<r1cs_core::ConstraintSystemRef<F>>;
123
124    /// Returns `true` if `self` is a circuit-generation-time constant.
125    fn is_constant(&self) -> bool {
126        self.cs()
127            .map_or(true, |cs| cs == r1cs_core::ConstraintSystemRef::None)
128    }
129
130    /// Returns the value that is assigned to `self` in the underlying
131    /// `ConstraintSystem`.
132    fn value(&self) -> Result<Self::Value, r1cs_core::SynthesisError>;
133}
134
135impl<F: Field, T: R1CSVar<F>> R1CSVar<F> for [T] {
136    type Value = Vec<T::Value>;
137
138    fn cs(&self) -> Option<r1cs_core::ConstraintSystemRef<F>> {
139        let mut result = None;
140        for var in self {
141            result = var.cs().or(result);
142        }
143        result
144    }
145
146    fn value(&self) -> Result<Self::Value, r1cs_core::SynthesisError> {
147        let mut result = Vec::new();
148        for var in self {
149            result.push(var.value()?);
150        }
151        Ok(result)
152    }
153}
154
155impl<'a, F: Field, T: 'a + R1CSVar<F>> R1CSVar<F> for &'a T {
156    type Value = T::Value;
157
158    fn cs(&self) -> Option<r1cs_core::ConstraintSystemRef<F>> {
159        (*self).cs()
160    }
161
162    fn value(&self) -> Result<Self::Value, r1cs_core::SynthesisError> {
163        (*self).value()
164    }
165}
166
167/// A utility trait to convert `Self` to `Result<T, SynthesisErrorA`.>
168pub trait Assignment<T> {
169    /// Converts `self` to `Result`.
170    fn get(self) -> Result<T, r1cs_core::SynthesisError>;
171}
172
173impl<T> Assignment<T> for Option<T> {
174    fn get(self) -> Result<T, r1cs_core::SynthesisError> {
175        self.ok_or(r1cs_core::SynthesisError::AssignmentMissing)
176    }
177}
178
179/// Specifies how to convert a variable of type `Self` to variables of
180/// type `FpVar<ConstraintF>`
181pub trait ToConstraintFieldGadget<ConstraintF: algebra::PrimeField> {
182    /// Converts `self` to `FpVar<ConstraintF>` variables.
183    fn to_constraint_field(
184        &self,
185    ) -> Result<Vec<crate::fields::fp::FpVar<ConstraintF>>, r1cs_core::SynthesisError>;
186}