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, such as `Boolean`s, `FieldVar`s, `GroupVar`s, etc.
116pub trait R1CSVar<F: Field> {
117    /// The type of the "native" value that `Self` represents in the constraint system.
118    type Value: core::fmt::Debug + Eq + Clone;
119
120    /// Returns the underlying `ConstraintSystemRef`.
121    fn cs(&self) -> Option<r1cs_core::ConstraintSystemRef<F>>;
122
123    /// Returns `true` if `self` is a circuit-generation-time constant.
124    fn is_constant(&self) -> bool {
125        self.cs()
126            .map_or(true, |cs| cs == r1cs_core::ConstraintSystemRef::None)
127    }
128
129    /// Returns the value that is assigned to `self` in the underlying
130    /// `ConstraintSystem`.
131    fn value(&self) -> Result<Self::Value, r1cs_core::SynthesisError>;
132}
133
134impl<F: Field, T: R1CSVar<F>> R1CSVar<F> for [T] {
135    type Value = Vec<T::Value>;
136
137    fn cs(&self) -> Option<r1cs_core::ConstraintSystemRef<F>> {
138        let mut result = None;
139        for var in self {
140            result = var.cs().or(result);
141        }
142        result
143    }
144
145    fn value(&self) -> Result<Self::Value, r1cs_core::SynthesisError> {
146        let mut result = Vec::new();
147        for var in self {
148            result.push(var.value()?);
149        }
150        Ok(result)
151    }
152}
153
154impl<'a, F: Field, T: 'a + R1CSVar<F>> R1CSVar<F> for &'a T {
155    type Value = T::Value;
156
157    fn cs(&self) -> Option<r1cs_core::ConstraintSystemRef<F>> {
158        (*self).cs()
159    }
160
161    fn value(&self) -> Result<Self::Value, r1cs_core::SynthesisError> {
162        (*self).value()
163    }
164}
165
166/// A utility trait to convert `Self` to `Result<T, SynthesisErrorA`.>
167pub trait Assignment<T> {
168    /// Converts `self` to `Result`.
169    fn get(self) -> Result<T, r1cs_core::SynthesisError>;
170}
171
172impl<T> Assignment<T> for Option<T> {
173    fn get(self) -> Result<T, r1cs_core::SynthesisError> {
174        self.ok_or(r1cs_core::SynthesisError::AssignmentMissing)
175    }
176}
177
178/// Obtains the field variables
179pub trait ToConstraintFieldGadget<ConstraintF: algebra::PrimeField> {
180    fn to_constraint_field(
181        &self,
182    ) -> Result<Vec<crate::fields::fp::FpVar<ConstraintF>>, r1cs_core::SynthesisError>;
183}