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    ///
123    /// If `self` is a constant value, then this *must* return `r1cs_core::ConstraintSystemRef::None`.
124    fn cs(&self) -> r1cs_core::ConstraintSystemRef<F>;
125
126    /// Returns `true` if `self` is a circuit-generation-time constant.
127    fn is_constant(&self) -> bool {
128        self.cs().is_none()
129    }
130
131    /// Returns the value that is assigned to `self` in the underlying
132    /// `ConstraintSystem`.
133    fn value(&self) -> Result<Self::Value, r1cs_core::SynthesisError>;
134}
135
136impl<F: Field, T: R1CSVar<F>> R1CSVar<F> for [T] {
137    type Value = Vec<T::Value>;
138
139    fn cs(&self) -> r1cs_core::ConstraintSystemRef<F> {
140        let mut result = r1cs_core::ConstraintSystemRef::None;
141        for var in self {
142            result = var.cs().or(result);
143        }
144        result
145    }
146
147    fn value(&self) -> Result<Self::Value, r1cs_core::SynthesisError> {
148        let mut result = Vec::new();
149        for var in self {
150            result.push(var.value()?);
151        }
152        Ok(result)
153    }
154}
155
156impl<'a, F: Field, T: 'a + R1CSVar<F>> R1CSVar<F> for &'a T {
157    type Value = T::Value;
158
159    fn cs(&self) -> r1cs_core::ConstraintSystemRef<F> {
160        (*self).cs()
161    }
162
163    fn value(&self) -> Result<Self::Value, r1cs_core::SynthesisError> {
164        (*self).value()
165    }
166}
167
168/// A utility trait to convert `Self` to `Result<T, SynthesisErrorA`.>
169pub trait Assignment<T> {
170    /// Converts `self` to `Result`.
171    fn get(self) -> Result<T, r1cs_core::SynthesisError>;
172}
173
174impl<T> Assignment<T> for Option<T> {
175    fn get(self) -> Result<T, r1cs_core::SynthesisError> {
176        self.ok_or(r1cs_core::SynthesisError::AssignmentMissing)
177    }
178}
179
180/// Specifies how to convert a variable of type `Self` to variables of
181/// type `FpVar<ConstraintF>`
182pub trait ToConstraintFieldGadget<ConstraintF: algebra::PrimeField> {
183    /// Converts `self` to `FpVar<ConstraintF>` variables.
184    fn to_constraint_field(
185        &self,
186    ) -> Result<Vec<crate::fields::fp::FpVar<ConstraintF>>, r1cs_core::SynthesisError>;
187}