Update to arkworks libraries (#3)

Co-authored-by: Nicholas Ward <npward@berkeley.edu>

src/bits/mod.rs

@@ -0,0 +1,128 @@
+use crate::{
+    bits::{boolean::Boolean, uint8::UInt8},
+    Vec,
+};
+use ark_ff::Field;
+use ark_relations::r1cs::SynthesisError;
+
+/// This module contains `Boolean`, a R1CS equivalent of the `bool` type.
+pub mod boolean;
+/// This module contains `UInt8`, a R1CS equivalent of the `u8` type.
+pub mod uint8;
+/// This module contains a macro for generating `UIntN` types, which are R1CS
+/// equivalents of `N`-bit unsigned integers.
+#[macro_use]
+pub mod uint;
+
+make_uint!(UInt16, 16, u16, uint16, "16");
+make_uint!(UInt32, 32, u32, uint32, "32");
+make_uint!(UInt64, 64, u64, uint64, "64");
+
+/// Specifies constraints for conversion to a little-endian bit representation
+/// of `self`.
+pub trait ToBitsGadget<F: Field> {
+    /// Outputs the canonical little-endian bit-wise representation of `self`.
+    ///
+    /// This is the correct default for 99% of use cases.
+    fn to_bits_le(&self) -> Result<Vec<Boolean<F>>, SynthesisError>;
+
+    /// Outputs a possibly non-unique little-endian bit-wise representation of
+    /// `self`.
+    ///
+    /// If you're not absolutely certain that your usecase can get away with a
+    /// non-canonical representation, please use `self.to_bits()` instead.
+    fn to_non_unique_bits_le(&self) -> Result<Vec<Boolean<F>>, SynthesisError> {
+        self.to_bits_le()
+    }
+
+    /// Outputs the canonical big-endian bit-wise representation of `self`.
+    fn to_bits_be(&self) -> Result<Vec<Boolean<F>>, SynthesisError> {
+        let mut res = self.to_bits_le()?;
+        res.reverse();
+        Ok(res)
+    }
+
+    /// Outputs a possibly non-unique big-endian bit-wise representation of
+    /// `self`.
+    fn to_non_unique_bits_be(&self) -> Result<Vec<Boolean<F>>, SynthesisError> {
+        let mut res = self.to_non_unique_bits_le()?;
+        res.reverse();
+        Ok(res)
+    }
+}
+
+impl<F: Field> ToBitsGadget<F> for Boolean<F> {
+    fn to_bits_le(&self) -> Result<Vec<Boolean<F>>, SynthesisError> {
+        Ok(vec![self.clone()])
+    }
+}
+
+impl<F: Field> ToBitsGadget<F> for [Boolean<F>] {
+    /// Outputs `self`.
+    fn to_bits_le(&self) -> Result<Vec<Boolean<F>>, SynthesisError> {
+        Ok(self.to_vec())
+    }
+}
+
+impl<F: Field> ToBitsGadget<F> for UInt8<F> {
+    fn to_bits_le(&self) -> Result<Vec<Boolean<F>>, SynthesisError> {
+        Ok(self.bits.to_vec())
+    }
+}
+
+impl<F: Field> ToBitsGadget<F> for [UInt8<F>] {
+    /// Interprets `self` as an integer, and outputs the little-endian
+    /// bit-wise decomposition of that integer.
+    fn to_bits_le(&self) -> Result<Vec<Boolean<F>>, SynthesisError> {
+        let bits = self.iter().flat_map(|b| &b.bits).cloned().collect();
+        Ok(bits)
+    }
+}
+
+impl<F: Field, T> ToBitsGadget<F> for Vec<T>
+where
+    [T]: ToBitsGadget<F>,
+{
+    fn to_bits_le(&self) -> Result<Vec<Boolean<F>>, SynthesisError> {
+        self.as_slice().to_bits_le().map(|v| v.to_vec())
+    }
+
+    fn to_non_unique_bits_le(&self) -> Result<Vec<Boolean<F>>, SynthesisError> {
+        self.as_slice().to_non_unique_bits_le().map(|v| v.to_vec())
+    }
+}
+
+/// Specifies constraints for conversion to a little-endian byte representation
+/// of `self`.
+pub trait ToBytesGadget<F: Field> {
+    /// Outputs a canonical, little-endian, byte decomposition of `self`.
+    ///
+    /// This is the correct default for 99% of use cases.
+    fn to_bytes(&self) -> Result<Vec<UInt8<F>>, SynthesisError>;
+
+    /// Outputs a possibly non-unique byte decomposition of `self`.
+    ///
+    /// If you're not absolutely certain that your usecase can get away with a
+    /// non-canonical representation, please use `self.to_bytes(cs)` instead.
+    fn to_non_unique_bytes(&self) -> Result<Vec<UInt8<F>>, SynthesisError> {
+        self.to_bytes()
+    }
+}
+
+impl<F: Field> ToBytesGadget<F> for [UInt8<F>] {
+    fn to_bytes(&self) -> Result<Vec<UInt8<F>>, SynthesisError> {
+        Ok(self.to_vec())
+    }
+}
+
+impl<'a, F: Field, T: 'a + ToBytesGadget<F>> ToBytesGadget<F> for &'a T {
+    fn to_bytes(&self) -> Result<Vec<UInt8<F>>, SynthesisError> {
+        (*self).to_bytes()
+    }
+}
+
+impl<'a, F: Field> ToBytesGadget<F> for &'a [UInt8<F>] {
+    fn to_bytes(&self) -> Result<Vec<UInt8<F>>, SynthesisError> {
+        Ok(self.to_vec())
+    }
+}

src/bits/uint.rs

@@ -0,0 +1,539 @@
+macro_rules! make_uint {
+    ($name:ident, $size:expr, $native:ident, $mod_name:ident, $native_doc_name:expr) => {
+        #[doc = "This module contains a `UInt"]
+        #[doc = $native_doc_name]
+        #[doc = "`, a R1CS equivalent of the `u"]
+        #[doc = $native_doc_name]
+        #[doc = "`type."]
+        pub mod $mod_name {
+            use ark_ff::{Field, FpParameters, PrimeField};
+            use core::borrow::Borrow;
+            use core::convert::TryFrom;
+
+            use ark_relations::r1cs::{
+                ConstraintSystemRef, LinearCombination, Namespace, SynthesisError, Variable,
+            };
+
+            use crate::{
+                boolean::{AllocatedBit, Boolean},
+                prelude::*,
+                Assignment, Vec,
+            };
+
+            #[doc = "This struct represent an unsigned"]
+            #[doc = $native_doc_name]
+            #[doc = "-bit integer as a sequence of "]
+            #[doc = $native_doc_name]
+            #[doc = " `Boolean`s\n"]
+            #[doc = "This is the R1CS equivalent of the native `u"]
+            #[doc = $native_doc_name]
+            #[doc = "` unsigned integer type."]
+            #[derive(Clone, Debug)]
+            pub struct $name<F: Field> {
+                // Least significant bit first
+                bits: Vec<Boolean<F>>,
+                value: Option<$native>,
+            }
+
+            impl<F: Field> R1CSVar<F> for $name<F> {
+                type Value = $native;
+
+                fn cs(&self) -> ConstraintSystemRef<F> {
+                    self.bits.as_slice().cs()
+                }
+
+                fn value(&self) -> Result<Self::Value, SynthesisError> {
+                    let mut value = None;
+                    for (i, bit) in self.bits.iter().enumerate() {
+                        let b = $native::from(bit.value()?);
+                        value = match value {
+                            Some(value) => Some(value + (b << i)),
+                            None => Some(b << i),
+                        };
+                    }
+                    debug_assert_eq!(self.value, value);
+                    value.get()
+                }
+            }
+
+            impl<F: Field> $name<F> {
+                #[doc = "Construct a constant `UInt"]
+                #[doc = $native_doc_name]
+                #[doc = "` from the native `u"]
+                #[doc = $native_doc_name]
+                #[doc = "` type."]
+                pub fn constant(value: $native) -> Self {
+                    let mut bits = Vec::with_capacity($size);
+
+                    let mut tmp = value;
+                    for _ in 0..$size {
+                        if tmp & 1 == 1 {
+                            bits.push(Boolean::constant(true))
+                        } else {
+                            bits.push(Boolean::constant(false))
+                        }
+
+                        tmp >>= 1;
+                    }
+
+                    $name {
+                        bits,
+                        value: Some(value),
+                    }
+                }
+
+                /// Turns `self` into the underlying little-endian bits.
+                pub fn to_bits_le(&self) -> Vec<Boolean<F>> {
+                    self.bits.clone()
+                }
+
+                /// Construct `Self` from a slice of `Boolean`s.
+                ///
+                /// # Panics
+                ///
+                /// This method panics if `bits.len() != u
+                #[doc($native_doc_name)]
+                #[doc("`.")]
+                pub fn from_bits_le(bits: &[Boolean<F>]) -> Self {
+                    assert_eq!(bits.len(), $size);
+
+                    let bits = bits.to_vec();
+
+                    let mut value = Some(0);
+                    for b in bits.iter().rev() {
+                        value.as_mut().map(|v| *v <<= 1);
+
+                        match b {
+                            &Boolean::Constant(b) => {
+                                value.as_mut().map(|v| *v |= $native::from(b));
+                            }
+                            &Boolean::Is(ref b) => match b.value() {
+                                Ok(b) => {
+                                    value.as_mut().map(|v| *v |= $native::from(b));
+                                }
+                                Err(_) => value = None,
+                            },
+                            &Boolean::Not(ref b) => match b.value() {
+                                Ok(b) => {
+                                    value.as_mut().map(|v| *v |= $native::from(!b));
+                                }
+                                Err(_) => value = None,
+                            },
+                        }
+                    }
+
+                    Self { value, bits }
+                }
+
+                /// Rotates `self` to the right by `by` steps, wrapping around.
+                #[tracing::instrument(target = "r1cs", skip(self))]
+                pub fn rotr(&self, by: usize) -> Self {
+                    let by = by % $size;
+
+                    let new_bits = self
+                        .bits
+                        .iter()
+                        .skip(by)
+                        .chain(self.bits.iter())
+                        .take($size)
+                        .cloned()
+                        .collect();
+
+                    $name {
+                        bits: new_bits,
+                        value: self
+                            .value
+                            .map(|v| v.rotate_right(u32::try_from(by).unwrap())),
+                    }
+                }
+
+                /// Outputs `self ^ other`.
+                ///
+                /// If at least one of `self` and `other` are constants, then this method
+                /// *does not* create any constraints or variables.
+                #[tracing::instrument(target = "r1cs", skip(self, other))]
+                pub fn xor(&self, other: &Self) -> Result<Self, SynthesisError> {
+                    let new_value = match (self.value, other.value) {
+                        (Some(a), Some(b)) => Some(a ^ b),
+                        _ => None,
+                    };
+
+                    let bits = self
+                        .bits
+                        .iter()
+                        .zip(other.bits.iter())
+                        .map(|(a, b)| a.xor(b))
+                        .collect::<Result<_, _>>()?;
+
+                    Ok($name {
+                        bits,
+                        value: new_value,
+                    })
+                }
+
+                /// Perform modular addition of `operands`.
+                ///
+                /// The user must ensure that overflow does not occur.
+                #[tracing::instrument(target = "r1cs", skip(operands))]
+                pub fn addmany(operands: &[Self]) -> Result<Self, SynthesisError>
+                where
+                    F: PrimeField,
+                {
+                    // Make some arbitrary bounds for ourselves to avoid overflows
+                    // in the scalar field
+                    assert!(F::Params::MODULUS_BITS >= 2 * $size);
+
+                    assert!(operands.len() >= 1);
+                    assert!($size * operands.len() <= F::Params::MODULUS_BITS as usize);
+
+                    if operands.len() == 1 {
+                        return Ok(operands[0].clone());
+                    }
+
+                    // Compute the maximum value of the sum so we allocate enough bits for
+                    // the result
+                    let mut max_value = (operands.len() as u128) * u128::from($native::max_value());
+
+                    // Keep track of the resulting value
+                    let mut result_value = Some(0u128);
+
+                    // This is a linear combination that we will enforce to be "zero"
+                    let mut lc = LinearCombination::zero();
+
+                    let mut all_constants = true;
+
+                    // Iterate over the operands
+                    for op in operands {
+                        // Accumulate the value
+                        match op.value {
+                            Some(val) => {
+                                result_value.as_mut().map(|v| *v += u128::from(val));
+                            }
+
+                            None => {
+                                // If any of our operands have unknown value, we won't
+                                // know the value of the result
+                                result_value = None;
+                            }
+                        }
+
+                        // Iterate over each bit_gadget of the operand and add the operand to
+                        // the linear combination
+                        let mut coeff = F::one();
+                        for bit in &op.bits {
+                            match *bit {
+                                Boolean::Is(ref bit) => {
+                                    all_constants = false;
+
+                                    // Add coeff * bit_gadget
+                                    lc += (coeff, bit.variable());
+                                }
+                                Boolean::Not(ref bit) => {
+                                    all_constants = false;
+
+                                    // Add coeff * (1 - bit_gadget) = coeff * ONE - coeff * bit_gadget
+                                    lc = lc + (coeff, Variable::One) - (coeff, bit.variable());
+                                }
+                                Boolean::Constant(bit) => {
+                                    if bit {
+                                        lc += (coeff, Variable::One);
+                                    }
+                                }
+                            }
+
+                            coeff.double_in_place();
+                        }
+                    }
+
+                    // The value of the actual result is modulo 2^$size
+                    let modular_value = result_value.map(|v| v as $native);
+
+                    if all_constants && modular_value.is_some() {
+                        // We can just return a constant, rather than
+                        // unpacking the result into allocated bits.
+
+                        return Ok($name::constant(modular_value.unwrap()));
+                    }
+                    let cs = operands.cs();
+
+                    // Storage area for the resulting bits
+                    let mut result_bits = vec![];
+
+                    // Allocate each bit_gadget of the result
+                    let mut coeff = F::one();
+                    let mut i = 0;
+                    while max_value != 0 {
+                        // Allocate the bit_gadget
+                        let b = AllocatedBit::new_witness(cs.clone(), || {
+                            result_value.map(|v| (v >> i) & 1 == 1).get()
+                        })?;
+
+                        // Subtract this bit_gadget from the linear combination to ensure the sums
+                        // balance out
+                        lc = lc - (coeff, b.variable());
+
+                        result_bits.push(b.into());
+
+                        max_value >>= 1;
+                        i += 1;
+                        coeff.double_in_place();
+                    }
+
+                    // Enforce that the linear combination equals zero
+                    cs.enforce_constraint(lc!(), lc!(), lc)?;
+
+                    // Discard carry bits that we don't care about
+                    result_bits.truncate($size);
+
+                    Ok($name {
+                        bits: result_bits,
+                        value: modular_value,
+                    })
+                }
+            }
+
+            impl<ConstraintF: Field> ToBytesGadget<ConstraintF> for $name<ConstraintF> {
+                #[tracing::instrument(target = "r1cs", skip(self))]
+                fn to_bytes(&self) -> Result<Vec<UInt8<ConstraintF>>, SynthesisError> {
+                    Ok(self
+                        .to_bits_le()
+                        .chunks(8)
+                        .map(UInt8::from_bits_le)
+                        .collect())
+                }
+            }
+
+            impl<ConstraintF: Field> EqGadget<ConstraintF> for $name<ConstraintF> {
+                #[tracing::instrument(target = "r1cs", skip(self))]
+                fn is_eq(&self, other: &Self) -> Result<Boolean<ConstraintF>, SynthesisError> {
+                    self.bits.as_slice().is_eq(&other.bits)
+                }
+
+                #[tracing::instrument(target = "r1cs", skip(self))]
+                fn conditional_enforce_equal(
+                    &self,
+                    other: &Self,
+                    condition: &Boolean<ConstraintF>,
+                ) -> Result<(), SynthesisError> {
+                    self.bits.conditional_enforce_equal(&other.bits, condition)
+                }
+
+                #[tracing::instrument(target = "r1cs", skip(self))]
+                fn conditional_enforce_not_equal(
+                    &self,
+                    other: &Self,
+                    condition: &Boolean<ConstraintF>,
+                ) -> Result<(), SynthesisError> {
+                    self.bits
+                        .conditional_enforce_not_equal(&other.bits, condition)
+                }
+            }
+
+            impl<ConstraintF: Field> AllocVar<$native, ConstraintF> for $name<ConstraintF> {
+                fn new_variable<T: Borrow<$native>>(
+                    cs: impl Into<Namespace<ConstraintF>>,
+                    f: impl FnOnce() -> Result<T, SynthesisError>,
+                    mode: AllocationMode,
+                ) -> Result<Self, SynthesisError> {
+                    let ns = cs.into();
+                    let cs = ns.cs();
+                    let value = f().map(|f| *f.borrow());
+                    let values = match value {
+                        Ok(val) => (0..$size).map(|i| Some((val >> i) & 1 == 1)).collect(),
+                        _ => vec![None; $size],
+                    };
+                    let bits = values
+                        .into_iter()
+                        .map(|v| Boolean::new_variable(cs.clone(), || v.get(), mode))
+                        .collect::<Result<Vec<_>, _>>()?;
+                    Ok(Self {
+                        bits,
+                        value: value.ok(),
+                    })
+                }
+            }
+
+            #[cfg(test)]
+            mod test {
+                use super::$name;
+                use crate::{bits::boolean::Boolean, prelude::*, Vec};
+                use ark_test_curves::bls12_381::Fr;
+                use ark_relations::r1cs::{ConstraintSystem, SynthesisError};
+                use rand::{Rng, SeedableRng};
+                use rand_xorshift::XorShiftRng;
+
+                #[test]
+                fn test_from_bits() -> Result<(), SynthesisError> {
+                    let mut rng = XorShiftRng::seed_from_u64(1231275789u64);
+
+                    for _ in 0..1000 {
+                        let v = (0..$size)
+                            .map(|_| Boolean::constant(rng.gen()))
+                            .collect::<Vec<Boolean<Fr>>>();
+
+                        let b = $name::from_bits_le(&v);
+
+                        for (i, bit) in b.bits.iter().enumerate() {
+                            match bit {
+                                &Boolean::Constant(bit) => {
+                                    assert_eq!(bit, ((b.value()? >> i) & 1 == 1));
+                                }
+                                _ => unreachable!(),
+                            }
+                        }
+
+                        let expected_to_be_same = b.to_bits_le();
+
+                        for x in v.iter().zip(expected_to_be_same.iter()) {
+                            match x {
+                                (&Boolean::Constant(true), &Boolean::Constant(true)) => {}
+                                (&Boolean::Constant(false), &Boolean::Constant(false)) => {}
+                                _ => unreachable!(),
+                            }
+                        }
+                    }
+                    Ok(())
+                }
+
+                #[test]
+                fn test_xor() -> Result<(), SynthesisError> {
+                    use Boolean::*;
+                    let mut rng = XorShiftRng::seed_from_u64(1231275789u64);
+
+                    for _ in 0..1000 {
+                        let cs = ConstraintSystem::<Fr>::new_ref();
+
+                        let a: $native = rng.gen();
+                        let b: $native = rng.gen();
+                        let c: $native = rng.gen();
+
+                        let mut expected = a ^ b ^ c;
+
+                        let a_bit = $name::new_witness(cs.clone(), || Ok(a))?;
+                        let b_bit = $name::constant(b);
+                        let c_bit = $name::new_witness(cs.clone(), || Ok(c))?;
+
+                        let r = a_bit.xor(&b_bit).unwrap();
+                        let r = r.xor(&c_bit).unwrap();
+
+                        assert!(cs.is_satisfied().unwrap());
+
+                        assert!(r.value == Some(expected));
+
+                        for b in r.bits.iter() {
+                            match b {
+                                Is(b) => assert_eq!(b.value()?, (expected & 1 == 1)),
+                                Not(b) => assert_eq!(!b.value()?, (expected & 1 == 1)),
+                                Constant(b) => assert_eq!(*b, (expected & 1 == 1)),
+                            }
+
+                            expected >>= 1;
+                        }
+                    }
+                    Ok(())
+                }
+
+                #[test]
+                fn test_addmany_constants() -> Result<(), SynthesisError> {
+                    let mut rng = XorShiftRng::seed_from_u64(1231275789u64);
+
+                    for _ in 0..1000 {
+                        let cs = ConstraintSystem::<Fr>::new_ref();
+
+                        let a: $native = rng.gen();
+                        let b: $native = rng.gen();
+                        let c: $native = rng.gen();
+
+                        let a_bit = $name::new_constant(cs.clone(), a)?;
+                        let b_bit = $name::new_constant(cs.clone(), b)?;
+                        let c_bit = $name::new_constant(cs.clone(), c)?;
+
+                        let mut expected = a.wrapping_add(b).wrapping_add(c);
+
+                        let r = $name::addmany(&[a_bit, b_bit, c_bit]).unwrap();
+
+                        assert!(r.value == Some(expected));
+
+                        for b in r.bits.iter() {
+                            match b {
+                                Boolean::Is(_) => unreachable!(),
+                                Boolean::Not(_) => unreachable!(),
+                                Boolean::Constant(b) => assert_eq!(*b, (expected & 1 == 1)),
+                            }
+
+                            expected >>= 1;
+                        }
+                    }
+                    Ok(())
+                }
+
+                #[test]
+                fn test_addmany() -> Result<(), SynthesisError> {
+                    let mut rng = XorShiftRng::seed_from_u64(1231275789u64);
+
+                    for _ in 0..1000 {
+                        let cs = ConstraintSystem::<Fr>::new_ref();
+
+                        let a: $native = rng.gen();
+                        let b: $native = rng.gen();
+                        let c: $native = rng.gen();
+                        let d: $native = rng.gen();
+
+                        let mut expected = (a ^ b).wrapping_add(c).wrapping_add(d);
+
+                        let a_bit = $name::new_witness(ark_relations::ns!(cs, "a_bit"), || Ok(a))?;
+                        let b_bit = $name::constant(b);
+                        let c_bit = $name::constant(c);
+                        let d_bit = $name::new_witness(ark_relations::ns!(cs, "d_bit"), || Ok(d))?;
+
+                        let r = a_bit.xor(&b_bit).unwrap();
+                        let r = $name::addmany(&[r, c_bit, d_bit]).unwrap();
+
+                        assert!(cs.is_satisfied().unwrap());
+
+                        assert!(r.value == Some(expected));
+
+                        for b in r.bits.iter() {
+                            match b {
+                                Boolean::Is(b) => assert_eq!(b.value()?, (expected & 1 == 1)),
+                                Boolean::Not(b) => assert_eq!(!b.value()?, (expected & 1 == 1)),
+                                Boolean::Constant(_) => unreachable!(),
+                            }
+
+                            expected >>= 1;
+                        }
+                    }
+                    Ok(())
+                }
+
+                #[test]
+                fn test_rotr() -> Result<(), SynthesisError> {
+                    let mut rng = XorShiftRng::seed_from_u64(1231275789u64);
+
+                    let mut num = rng.gen();
+
+                    let a: $name<Fr> = $name::constant(num);
+
+                    for i in 0..$size {
+                        let b = a.rotr(i);
+
+                        assert!(b.value.unwrap() == num);
+
+                        let mut tmp = num;
+                        for b in &b.bits {
+                            match b {
+                                Boolean::Constant(b) => assert_eq!(*b, tmp & 1 == 1),
+                                _ => unreachable!(),
+                            }
+
+                            tmp >>= 1;
+                        }
+
+                        num = num.rotate_right(1);
+                    }
+                    Ok(())
+                }
+            }
+        }
+    };
+}

src/bits/uint8.rs

@@ -0,0 +1,422 @@
+use ark_ff::{Field, FpParameters, PrimeField, ToConstraintField};
+
+use ark_relations::r1cs::{ConstraintSystemRef, Namespace, SynthesisError};
+
+use crate::{fields::fp::AllocatedFp, prelude::*, Assignment, Vec};
+use core::borrow::Borrow;
+
+/// Represents an interpretation of 8 `Boolean` objects as an
+/// unsigned integer.
+#[derive(Clone, Debug)]
+pub struct UInt8<F: Field> {
+    /// Little-endian representation: least significant bit first
+    pub(crate) bits: Vec<Boolean<F>>,
+    pub(crate) value: Option<u8>,
+}
+
+impl<F: Field> R1CSVar<F> for UInt8<F> {
+    type Value = u8;
+
+    fn cs(&self) -> ConstraintSystemRef<F> {
+        self.bits.as_slice().cs()
+    }
+
+    fn value(&self) -> Result<Self::Value, SynthesisError> {
+        let mut value = None;
+        for (i, bit) in self.bits.iter().enumerate() {
+            let b = u8::from(bit.value()?);
+            value = match value {
+                Some(value) => Some(value + (b << i)),
+                None => Some(b << i),
+            };
+        }
+        debug_assert_eq!(self.value, value);
+        value.get()
+    }
+}
+
+impl<F: Field> UInt8<F> {
+    /// Construct a constant vector of `UInt8` from a vector of `u8`
+    ///
+    /// This *does not* create any new variables or constraints.
+    /// ```
+    /// # fn main() -> Result<(), ark_relations::r1cs::SynthesisError> {
+    /// // We'll use the BLS12-381 scalar field for our constraints.
+    /// use ark_test_curves::bls12_381::Fr;
+    /// use ark_relations::r1cs::*;
+    /// use ark_r1cs_std::prelude::*;
+    ///
+    /// let cs = ConstraintSystem::<Fr>::new_ref();
+    /// let var = vec![UInt8::new_witness(cs.clone(), || Ok(2))?];
+    ///
+    /// let constant = UInt8::constant_vec(&[2]);
+    /// var.enforce_equal(&constant)?;
+    /// assert!(cs.is_satisfied().unwrap());
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn constant_vec(values: &[u8]) -> Vec<Self> {
+        let mut result = Vec::new();
+        for value in values {
+            result.push(UInt8::constant(*value));
+        }
+        result
+    }
+
+    /// Construct a constant `UInt8` from a `u8`
+    ///
+    /// This *does not* create new variables or constraints.
+    ///
+    /// ```
+    /// # fn main() -> Result<(), ark_relations::r1cs::SynthesisError> {
+    /// // We'll use the BLS12-381 scalar field for our constraints.
+    /// use ark_test_curves::bls12_381::Fr;
+    /// use ark_relations::r1cs::*;
+    /// use ark_r1cs_std::prelude::*;
+    ///
+    /// let cs = ConstraintSystem::<Fr>::new_ref();
+    /// let var = UInt8::new_witness(cs.clone(), || Ok(2))?;
+    ///
+    /// let constant = UInt8::constant(2);
+    /// var.enforce_equal(&constant)?;
+    /// assert!(cs.is_satisfied().unwrap());
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn constant(value: u8) -> Self {
+        let mut bits = Vec::with_capacity(8);
+
+        let mut tmp = value;
+        for _ in 0..8 {
+            // If last bit is one, push one.
+            bits.push(Boolean::constant(tmp & 1 == 1));
+            tmp >>= 1;
+        }
+
+        Self {
+            bits,
+            value: Some(value),
+        }
+    }
+
+    /// Allocates a slice of `u8`'s as private witnesses.
+    pub fn new_witness_vec(
+        cs: impl Into<Namespace<F>>,
+        values: &[impl Into<Option<u8>> + Copy],
+    ) -> Result<Vec<Self>, SynthesisError> {
+        let ns = cs.into();
+        let cs = ns.cs();
+        let mut output_vec = Vec::with_capacity(values.len());
+        for value in values {
+            let byte: Option<u8> = Into::into(*value);
+            output_vec.push(Self::new_witness(cs.clone(), || byte.get())?);
+        }
+        Ok(output_vec)
+    }
+
+    /// Allocates a slice of `u8`'s as public inputs by first packing them into
+    /// elements of `F`, (thus reducing the number of input allocations),
+    /// allocating these elements as public inputs, and then converting
+    /// these field variables `FpVar<F>` variables back into bytes.
+    ///
+    /// From a user perspective, this trade-off adds constraints, but improves
+    /// verifier time and verification key size.
+    ///
+    /// ```
+    /// # fn main() -> Result<(), ark_relations::r1cs::SynthesisError> {
+    /// // We'll use the BLS12-381 scalar field for our constraints.
+    /// use ark_test_curves::bls12_381::Fr;
+    /// use ark_relations::r1cs::*;
+    /// use ark_r1cs_std::prelude::*;
+    ///
+    /// let cs = ConstraintSystem::<Fr>::new_ref();
+    /// let two = UInt8::new_witness(cs.clone(), || Ok(2))?;
+    /// let var = vec![two.clone(); 32];
+    ///
+    /// let c = UInt8::new_input_vec(cs.clone(), &[2; 32])?;
+    /// var.enforce_equal(&c)?;
+    /// assert!(cs.is_satisfied().unwrap());
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn new_input_vec(
+        cs: impl Into<Namespace<F>>,
+        values: &[u8],
+    ) -> Result<Vec<Self>, SynthesisError>
+    where
+        F: PrimeField,
+    {
+        let ns = cs.into();
+        let cs = ns.cs();
+        let values_len = values.len();
+        let field_elements: Vec<F> = ToConstraintField::<F>::to_field_elements(values).unwrap();
+
+        let max_size = 8 * (F::Params::CAPACITY / 8) as usize;
+        let mut allocated_bits = Vec::new();
+        for field_element in field_elements.into_iter() {
+            let fe = AllocatedFp::new_input(cs.clone(), || Ok(field_element))?;
+            let fe_bits = fe.to_bits_le()?;
+
+            // Remove the most significant bit, because we know it should be zero
+            // because `values.to_field_elements()` only
+            // packs field elements up to the penultimate bit.
+            // That is, the most significant bit (`ConstraintF::NUM_BITS`-th bit) is
+            // unset, so we can just pop it off.
+            allocated_bits.extend_from_slice(&fe_bits[0..max_size]);
+        }
+
+        // Chunk up slices of 8 bit into bytes.
+        Ok(allocated_bits[0..(8 * values_len)]
+            .chunks(8)
+            .map(Self::from_bits_le)
+            .collect())
+    }
+
+    /// Converts a little-endian byte order representation of bits into a
+    /// `UInt8`.
+    ///
+    /// ```
+    /// # fn main() -> Result<(), ark_relations::r1cs::SynthesisError> {
+    /// // We'll use the BLS12-381 scalar field for our constraints.
+    /// use ark_test_curves::bls12_381::Fr;
+    /// use ark_relations::r1cs::*;
+    /// use ark_r1cs_std::prelude::*;
+    ///
+    /// let cs = ConstraintSystem::<Fr>::new_ref();
+    /// let var = UInt8::new_witness(cs.clone(), || Ok(128))?;
+    ///
+    /// let f = Boolean::FALSE;
+    /// let t = Boolean::TRUE;
+    ///
+    /// // Construct [0, 0, 0, 0, 0, 0, 0, 1]
+    /// let mut bits = vec![f.clone(); 7];
+    /// bits.push(t);
+    ///
+    /// let mut c = UInt8::from_bits_le(&bits);
+    /// var.enforce_equal(&c)?;
+    /// assert!(cs.is_satisfied().unwrap());
+    /// # Ok(())
+    /// # }
+    /// ```
+    #[tracing::instrument(target = "r1cs")]
+    pub fn from_bits_le(bits: &[Boolean<F>]) -> Self {
+        assert_eq!(bits.len(), 8);
+
+        let bits = bits.to_vec();
+
+        let mut value = Some(0u8);
+        for (i, b) in bits.iter().enumerate() {
+            value = match b.value().ok() {
+                Some(b) => value.map(|v| v + (u8::from(b) << i)),
+                None => None,
+            }
+        }
+
+        Self { value, bits }
+    }
+
+    /// Outputs `self ^ other`.
+    ///
+    /// If at least one of `self` and `other` are constants, then this method
+    /// *does not* create any constraints or variables.
+    ///
+    /// ```
+    /// # fn main() -> Result<(), ark_relations::r1cs::SynthesisError> {
+    /// // We'll use the BLS12-381 scalar field for our constraints.
+    /// use ark_test_curves::bls12_381::Fr;
+    /// use ark_relations::r1cs::*;
+    /// use ark_r1cs_std::prelude::*;
+    ///
+    /// let cs = ConstraintSystem::<Fr>::new_ref();
+    /// let a = UInt8::new_witness(cs.clone(), || Ok(16))?;
+    /// let b = UInt8::new_witness(cs.clone(), || Ok(17))?;
+    /// let c = UInt8::new_witness(cs.clone(), || Ok(1))?;
+    ///
+    /// a.xor(&b)?.enforce_equal(&c)?;
+    /// assert!(cs.is_satisfied().unwrap());
+    /// # Ok(())
+    /// # }
+    /// ```
+    #[tracing::instrument(target = "r1cs")]
+    pub fn xor(&self, other: &Self) -> Result<Self, SynthesisError> {
+        let new_value = match (self.value, other.value) {
+            (Some(a), Some(b)) => Some(a ^ b),
+            _ => None,
+        };
+
+        let bits = self
+            .bits
+            .iter()
+            .zip(other.bits.iter())
+            .map(|(a, b)| a.xor(b))
+            .collect::<Result<_, _>>()?;
+
+        Ok(Self {
+            bits,
+            value: new_value,
+        })
+    }
+}
+
+impl<ConstraintF: Field> EqGadget<ConstraintF> for UInt8<ConstraintF> {
+    #[tracing::instrument(target = "r1cs")]
+    fn is_eq(&self, other: &Self) -> Result<Boolean<ConstraintF>, SynthesisError> {
+        self.bits.as_slice().is_eq(&other.bits)
+    }
+
+    #[tracing::instrument(target = "r1cs")]
+    fn conditional_enforce_equal(
+        &self,
+        other: &Self,
+        condition: &Boolean<ConstraintF>,
+    ) -> Result<(), SynthesisError> {
+        self.bits.conditional_enforce_equal(&other.bits, condition)
+    }
+
+    #[tracing::instrument(target = "r1cs")]
+    fn conditional_enforce_not_equal(
+        &self,
+        other: &Self,
+        condition: &Boolean<ConstraintF>,
+    ) -> Result<(), SynthesisError> {
+        self.bits
+            .conditional_enforce_not_equal(&other.bits, condition)
+    }
+}
+
+impl<ConstraintF: Field> AllocVar<u8, ConstraintF> for UInt8<ConstraintF> {
+    fn new_variable<T: Borrow<u8>>(
+        cs: impl Into<Namespace<ConstraintF>>,
+        f: impl FnOnce() -> Result<T, SynthesisError>,
+        mode: AllocationMode,
+    ) -> Result<Self, SynthesisError> {
+        let ns = cs.into();
+        let cs = ns.cs();
+        let value = f().map(|f| *f.borrow());
+        let values = match value {
+            Ok(val) => (0..8).map(|i| Some((val >> i) & 1 == 1)).collect(),
+            _ => vec![None; 8],
+        };
+        let bits = values
+            .into_iter()
+            .map(|v| Boolean::new_variable(cs.clone(), || v.get(), mode))
+            .collect::<Result<Vec<_>, _>>()?;
+        Ok(Self {
+            bits,
+            value: value.ok(),
+        })
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::UInt8;
+    use crate::{prelude::*, Vec};
+    use ark_relations::r1cs::{ConstraintSystem, SynthesisError};
+    use ark_test_curves::bls12_381::Fr;
+    use rand::{Rng, SeedableRng};
+    use rand_xorshift::XorShiftRng;
+
+    #[test]
+    fn test_uint8_from_bits_to_bits() -> Result<(), SynthesisError> {
+        let cs = ConstraintSystem::<Fr>::new_ref();
+        let byte_val = 0b01110001;
+        let byte =
+            UInt8::new_witness(ark_relations::ns!(cs, "alloc value"), || Ok(byte_val)).unwrap();
+        let bits = byte.to_bits_le()?;
+        for (i, bit) in bits.iter().enumerate() {
+            assert_eq!(bit.value()?, (byte_val >> i) & 1 == 1)
+        }
+        Ok(())
+    }
+
+    #[test]
+    fn test_uint8_new_input_vec() -> Result<(), SynthesisError> {
+        let cs = ConstraintSystem::<Fr>::new_ref();
+        let byte_vals = (64u8..128u8).collect::<Vec<_>>();
+        let bytes =
+            UInt8::new_input_vec(ark_relations::ns!(cs, "alloc value"), &byte_vals).unwrap();
+        dbg!(bytes.value())?;
+        for (native, variable) in byte_vals.into_iter().zip(bytes) {
+            let bits = variable.to_bits_le()?;
+            for (i, bit) in bits.iter().enumerate() {
+                assert_eq!(
+                    bit.value()?,
+                    (native >> i) & 1 == 1,
+                    "native value {}: bit {:?}",
+                    native,
+                    i
+                )
+            }
+        }
+        Ok(())
+    }
+
+    #[test]
+    fn test_uint8_from_bits() -> Result<(), SynthesisError> {
+        let mut rng = XorShiftRng::seed_from_u64(1231275789u64);
+
+        for _ in 0..1000 {
+            let v = (0..8)
+                .map(|_| Boolean::<Fr>::Constant(rng.gen()))
+                .collect::<Vec<_>>();
+
+            let val = UInt8::from_bits_le(&v);
+
+            for (i, bit) in val.bits.iter().enumerate() {
+                match bit {
+                    Boolean::Constant(b) => assert!(*b == ((val.value()? >> i) & 1 == 1)),
+                    _ => unreachable!(),
+                }
+            }
+
+            let expected_to_be_same = val.to_bits_le()?;
+
+            for x in v.iter().zip(expected_to_be_same.iter()) {
+                match x {
+                    (&Boolean::Constant(true), &Boolean::Constant(true)) => {}
+                    (&Boolean::Constant(false), &Boolean::Constant(false)) => {}
+                    _ => unreachable!(),
+                }
+            }
+        }
+        Ok(())
+    }
+
+    #[test]
+    fn test_uint8_xor() -> Result<(), SynthesisError> {
+        let mut rng = XorShiftRng::seed_from_u64(1231275789u64);
+
+        for _ in 0..1000 {
+            let cs = ConstraintSystem::<Fr>::new_ref();
+
+            let a: u8 = rng.gen();
+            let b: u8 = rng.gen();
+            let c: u8 = rng.gen();
+
+            let mut expected = a ^ b ^ c;
+
+            let a_bit = UInt8::new_witness(ark_relations::ns!(cs, "a_bit"), || Ok(a)).unwrap();
+            let b_bit = UInt8::constant(b);
+            let c_bit = UInt8::new_witness(ark_relations::ns!(cs, "c_bit"), || Ok(c)).unwrap();
+
+            let r = a_bit.xor(&b_bit).unwrap();
+            let r = r.xor(&c_bit).unwrap();
+
+            assert!(cs.is_satisfied().unwrap());
+
+            assert!(r.value == Some(expected));
+
+            for b in r.bits.iter() {
+                match b {
+                    Boolean::Is(b) => assert!(b.value()? == (expected & 1 == 1)),
+                    Boolean::Not(b) => assert!(!b.value()? == (expected & 1 == 1)),
+                    Boolean::Constant(b) => assert!(*b == (expected & 1 == 1)),
+                }
+
+                expected >>= 1;
+            }
+        }
+        Ok(())
+    }
+}