Move snark-gadgets to r1cs-std

r1cs-std/src/bits/mod.rs

@@ -0,0 +1,84 @@
+use crate::bits::{boolean::Boolean, uint8::UInt8};
+use algebra::Field;
+use r1cs_core::{ConstraintSystem, SynthesisError};
+
+pub mod boolean;
+pub mod uint32;
+pub mod uint8;
+
+pub trait ToBitsGadget<ConstraintF: Field> {
+    fn to_bits<CS: ConstraintSystem<ConstraintF>>(&self, cs: CS) -> Result<Vec<Boolean>, SynthesisError>;
+
+    /// Additionally checks if the produced list of booleans is 'valid'.
+    fn to_bits_strict<CS: ConstraintSystem<ConstraintF>>(
+        &self,
+        cs: CS,
+    ) -> Result<Vec<Boolean>, SynthesisError>;
+}
+
+impl<ConstraintF: Field> ToBitsGadget<ConstraintF> for Boolean {
+    fn to_bits<CS: ConstraintSystem<ConstraintF>>(&self, _: CS) -> Result<Vec<Boolean>, SynthesisError> {
+        Ok(vec![self.clone()])
+    }
+
+    fn to_bits_strict<CS: ConstraintSystem<ConstraintF>>(
+        &self,
+        _: CS,
+    ) -> Result<Vec<Boolean>, SynthesisError> {
+        Ok(vec![self.clone()])
+    }
+}
+
+impl<ConstraintF: Field> ToBitsGadget<ConstraintF> for [Boolean] {
+    fn to_bits<CS: ConstraintSystem<ConstraintF>>(&self, _cs: CS) -> Result<Vec<Boolean>, SynthesisError> {
+        Ok(self.to_vec())
+    }
+
+    fn to_bits_strict<CS: ConstraintSystem<ConstraintF>>(
+        &self,
+        _cs: CS,
+    ) -> Result<Vec<Boolean>, SynthesisError> {
+        Ok(self.to_vec())
+    }
+}
+impl<ConstraintF: Field> ToBitsGadget<ConstraintF> for Vec<Boolean> {
+    fn to_bits<CS: ConstraintSystem<ConstraintF>>(&self, _cs: CS) -> Result<Vec<Boolean>, SynthesisError> {
+        Ok(self.clone())
+    }
+
+    fn to_bits_strict<CS: ConstraintSystem<ConstraintF>>(
+        &self,
+        _cs: CS,
+    ) -> Result<Vec<Boolean>, SynthesisError> {
+        Ok(self.clone())
+    }
+}
+
+impl<ConstraintF: Field> ToBitsGadget<ConstraintF> for [UInt8] {
+    fn to_bits<CS: ConstraintSystem<ConstraintF>>(&self, _cs: CS) -> Result<Vec<Boolean>, SynthesisError> {
+        let mut result = Vec::with_capacity(&self.len() * 8);
+        for byte in self {
+            result.extend_from_slice(&byte.into_bits_le());
+        }
+        Ok(result)
+    }
+
+    fn to_bits_strict<CS: ConstraintSystem<ConstraintF>>(
+        &self,
+        cs: CS,
+    ) -> Result<Vec<Boolean>, SynthesisError> {
+        self.to_bits(cs)
+    }
+}
+
+pub trait ToBytesGadget<ConstraintF: Field> {
+    fn to_bytes<CS: ConstraintSystem<ConstraintF>>(&self, cs: CS) -> Result<Vec<UInt8>, SynthesisError>;
+
+    /// Additionally checks if the produced list of booleans is 'valid'.
+    fn to_bytes_strict<CS: ConstraintSystem<ConstraintF>>(
+        &self,
+        cs: CS,
+    ) -> Result<Vec<UInt8>, SynthesisError>;
+}
+
+

r1cs-std/src/bits/uint32.rs

@@ -0,0 +1,534 @@
+use algebra::{FpParameters, PrimeField, Field};
+
+use r1cs_core::{ConstraintSystem, LinearCombination, SynthesisError};
+
+use crate::boolean::{AllocatedBit, Boolean};
+use crate::Assignment;
+use crate::prelude::*;
+
+/// Represents an interpretation of 32 `Boolean` objects as an
+/// unsigned integer.
+#[derive(Clone, Debug)]
+pub struct UInt32 {
+    // Least significant bit_gadget first
+    bits:  Vec<Boolean>,
+    value: Option<u32>,
+}
+
+impl UInt32 {
+    /// Construct a constant `UInt32` from a `u32`
+    pub fn constant(value: u32) -> Self {
+        let mut bits = Vec::with_capacity(32);
+
+        let mut tmp = value;
+        for _ in 0..32 {
+            if tmp & 1 == 1 {
+                bits.push(Boolean::constant(true))
+            } else {
+                bits.push(Boolean::constant(false))
+            }
+
+            tmp >>= 1;
+        }
+
+        UInt32 {
+            bits,
+            value: Some(value),
+        }
+    }
+
+    /// Allocate a `UInt32` in the constraint system
+    pub fn alloc<ConstraintF, CS>(mut cs: CS, value: Option<u32>) -> Result<Self, SynthesisError>
+    where
+        ConstraintF: Field,
+        CS: ConstraintSystem<ConstraintF>,
+    {
+        let values = match value {
+            Some(mut val) => {
+                let mut v = Vec::with_capacity(32);
+
+                for _ in 0..32 {
+                    v.push(Some(val & 1 == 1));
+                    val >>= 1;
+                }
+
+                v
+            },
+            None => vec![None; 32],
+        };
+
+        let bits = values
+            .into_iter()
+            .enumerate()
+            .map(|(i, v)| {
+                Ok(Boolean::from(AllocatedBit::alloc(
+                    cs.ns(|| format!("allocated bit_gadget {}", i)),
+                    || v.get(),
+                )?))
+            })
+            .collect::<Result<Vec<_>, SynthesisError>>()?;
+
+        Ok(UInt32 { bits, value })
+    }
+
+    /// Turns this `UInt32` into its little-endian byte order representation.
+    pub fn to_bits_le(&self) -> Vec<Boolean> {
+        self.bits.clone()
+    }
+
+    /// Converts a little-endian byte order representation of bits into a
+    /// `UInt32`.
+    pub fn from_bits_le(bits: &[Boolean]) -> Self {
+        assert_eq!(bits.len(), 32);
+
+        let bits = bits.to_vec();
+
+        let mut value = Some(0u32);
+        for b in bits.iter().rev() {
+            value.as_mut().map(|v| *v <<= 1);
+
+            match b {
+                &Boolean::Constant(b) => {
+                    if b {
+                        value.as_mut().map(|v| *v |= 1);
+                    }
+                },
+                &Boolean::Is(ref b) => match b.get_value() {
+                    Some(true) => {
+                        value.as_mut().map(|v| *v |= 1);
+                    },
+                    Some(false) => {},
+                    None => value = None,
+                },
+                &Boolean::Not(ref b) => match b.get_value() {
+                    Some(false) => {
+                        value.as_mut().map(|v| *v |= 1);
+                    },
+                    Some(true) => {},
+                    None => value = None,
+                },
+            }
+        }
+
+        Self { value, bits }
+    }
+
+    pub fn rotr(&self, by: usize) -> Self {
+        let by = by % 32;
+
+        let new_bits = self
+            .bits
+            .iter()
+            .skip(by)
+            .chain(self.bits.iter())
+            .take(32)
+            .cloned()
+            .collect();
+
+        UInt32 {
+            bits:  new_bits,
+            value: self.value.map(|v| v.rotate_right(by as u32)),
+        }
+    }
+
+    /// XOR this `UInt32` with another `UInt32`
+    pub fn xor<ConstraintF, CS>(&self, mut cs: CS, other: &Self) -> Result<Self, SynthesisError>
+    where
+        ConstraintF: Field,
+        CS: ConstraintSystem<ConstraintF>,
+    {
+        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())
+            .enumerate()
+            .map(|(i, (a, b))| Boolean::xor(cs.ns(|| format!("xor of bit_gadget {}", i)), a, b))
+            .collect::<Result<_, _>>()?;
+
+        Ok(UInt32 {
+            bits,
+            value: new_value,
+        })
+    }
+
+    /// Perform modular addition of several `UInt32` objects.
+    pub fn addmany<ConstraintF, CS>(mut cs: CS, operands: &[Self]) -> Result<Self, SynthesisError>
+    where
+        ConstraintF: PrimeField,
+        CS: ConstraintSystem<ConstraintF>,
+    {
+        // Make some arbitrary bounds for ourselves to avoid overflows
+        // in the scalar field
+        assert!(ConstraintF::Params::MODULUS_BITS >= 64);
+        assert!(operands.len() >= 2); // Weird trivial cases that should never happen
+        assert!(operands.len() <= 10);
+
+        // Compute the maximum value of the sum so we allocate enough bits for
+        // the result
+        let mut max_value = (operands.len() as u64) * u64::from(u32::max_value());
+
+        // Keep track of the resulting value
+        let mut result_value = Some(0u64);
+
+        // 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 += u64::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 = ConstraintF::one();
+            for bit in &op.bits {
+                match *bit {
+                    Boolean::Is(ref bit) => {
+                        all_constants = false;
+
+                        // Add coeff * bit_gadget
+                        lc = lc + (coeff, bit.get_variable());
+                    },
+                    Boolean::Not(ref bit) => {
+                        all_constants = false;
+
+                        // Add coeff * (1 - bit_gadget) = coeff * ONE - coeff * bit_gadget
+                        lc = lc + (coeff, CS::one()) - (coeff, bit.get_variable());
+                    },
+                    Boolean::Constant(bit) => {
+                        if bit {
+                            lc = lc + (coeff, CS::one());
+                        }
+                    },
+                }
+
+                coeff.double_in_place();
+            }
+        }
+
+        // The value of the actual result is modulo 2^32
+        let modular_value = result_value.map(|v| v as u32);
+
+        if all_constants && modular_value.is_some() {
+            // We can just return a constant, rather than
+            // unpacking the result into allocated bits.
+
+            return Ok(UInt32::constant(modular_value.unwrap()));
+        }
+
+        // Storage area for the resulting bits
+        let mut result_bits = vec![];
+
+        // Allocate each bit_gadget of the result
+        let mut coeff = ConstraintF::one();
+        let mut i = 0;
+        while max_value != 0 {
+            // Allocate the bit_gadget
+            let b = AllocatedBit::alloc(cs.ns(|| format!("result bit_gadget {}", i)), || {
+                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.get_variable());
+
+            result_bits.push(b.into());
+
+            max_value >>= 1;
+            i += 1;
+            coeff.double_in_place();
+        }
+
+        // Enforce that the linear combination equals zero
+        cs.enforce(|| "modular addition", |lc| lc, |lc| lc, |_| lc);
+
+        // Discard carry bits that we don't care about
+        result_bits.truncate(32);
+
+        Ok(UInt32 {
+            bits:  result_bits,
+            value: modular_value,
+        })
+    }
+}
+
+impl<ConstraintF: Field> ToBytesGadget<ConstraintF> for UInt32 {
+    #[inline]
+    fn to_bytes<CS: ConstraintSystem<ConstraintF>>(&self, _cs: CS) -> Result<Vec<UInt8>, SynthesisError> {
+        let value_chunks = match self.value.map(|val| {
+            use algebra::bytes::ToBytes;
+            let mut bytes = [0u8; 4];
+            val.write(bytes.as_mut()).unwrap();
+            bytes
+        }) {
+            Some(chunks) => [
+                Some(chunks[0]),
+                Some(chunks[1]),
+                Some(chunks[2]),
+                Some(chunks[3]),
+            ],
+            None => [None, None, None, None],
+        };
+        let mut bytes = Vec::new();
+        for (i, chunk8) in self.to_bits_le().chunks(8).into_iter().enumerate() {
+            let byte = UInt8 {
+                bits:  chunk8.to_vec(),
+                value: value_chunks[i],
+            };
+            bytes.push(byte);
+        }
+
+        Ok(bytes)
+    }
+
+    fn to_bytes_strict<CS: ConstraintSystem<ConstraintF>>(
+        &self,
+        cs: CS,
+    ) -> Result<Vec<UInt8>, SynthesisError> {
+        self.to_bytes(cs)
+    }
+}
+
+impl PartialEq for UInt32 {
+    fn eq(&self, other: &Self) -> bool {
+        !self.value.is_none() && !other.value.is_none() && self.value == other.value
+    }
+}
+
+impl Eq for UInt32 {}
+
+impl<ConstraintF: Field> ConditionalEqGadget<ConstraintF> for UInt32 {
+    fn conditional_enforce_equal<CS: ConstraintSystem<ConstraintF>>(
+        &self,
+        mut cs: CS,
+        other: &Self,
+        condition: &Boolean,
+    ) -> Result<(), SynthesisError> {
+        for (i, (a, b)) in self.bits.iter().zip(&other.bits).enumerate() {
+            a.conditional_enforce_equal(
+                &mut cs.ns(|| format!("uint32_equal_{}", i)),
+                b,
+                condition,
+            )?;
+        }
+        Ok(())
+    }
+
+    fn cost() -> usize {
+        32 * <Boolean as ConditionalEqGadget<ConstraintF>>::cost()
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::UInt32;
+    use crate::{bits::boolean::Boolean, test_constraint_system::TestConstraintSystem};
+    use algebra::fields::{bls12_381::Fr, Field};
+    use rand::{Rng, SeedableRng, XorShiftRng};
+    use r1cs_core::ConstraintSystem;
+
+    #[test]
+    fn test_uint32_from_bits() {
+        let mut rng = XorShiftRng::from_seed([0x5dbe6259, 0x8d313d76, 0x3237db17, 0xe5bc0653]);
+
+        for _ in 0..1000 {
+            let v = (0..32)
+                .map(|_| Boolean::constant(rng.gen()))
+                .collect::<Vec<_>>();
+
+            let b = UInt32::from_bits_le(&v);
+
+            for (i, bit_gadget) in b.bits.iter().enumerate() {
+                match bit_gadget {
+                    &Boolean::Constant(bit_gadget) => {
+                        assert!(bit_gadget == ((b.value.unwrap() >> 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!(),
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_uint32_xor() {
+        let mut rng = XorShiftRng::from_seed([0x5dbe6259, 0x8d313d76, 0x3237db17, 0xe5bc0653]);
+
+        for _ in 0..1000 {
+            let mut cs = TestConstraintSystem::<Fr>::new();
+
+            let a: u32 = rng.gen();
+            let b: u32 = rng.gen();
+            let c: u32 = rng.gen();
+
+            let mut expected = a ^ b ^ c;
+
+            let a_bit = UInt32::alloc(cs.ns(|| "a_bit"), Some(a)).unwrap();
+            let b_bit = UInt32::constant(b);
+            let c_bit = UInt32::alloc(cs.ns(|| "c_bit"), Some(c)).unwrap();
+
+            let r = a_bit.xor(cs.ns(|| "first xor"), &b_bit).unwrap();
+            let r = r.xor(cs.ns(|| "second xor"), &c_bit).unwrap();
+
+            assert!(cs.is_satisfied());
+
+            assert!(r.value == Some(expected));
+
+            for b in r.bits.iter() {
+                match b {
+                    &Boolean::Is(ref b) => {
+                        assert!(b.get_value().unwrap() == (expected & 1 == 1));
+                    },
+                    &Boolean::Not(ref b) => {
+                        assert!(!b.get_value().unwrap() == (expected & 1 == 1));
+                    },
+                    &Boolean::Constant(b) => {
+                        assert!(b == (expected & 1 == 1));
+                    },
+                }
+
+                expected >>= 1;
+            }
+        }
+    }
+
+    #[test]
+    fn test_uint32_addmany_constants() {
+        let mut rng = XorShiftRng::from_seed([0x5dbe6259, 0x8d313d76, 0x3237db17, 0xe5bc0654]);
+
+        for _ in 0..1000 {
+            let mut cs = TestConstraintSystem::<Fr>::new();
+
+            let a: u32 = rng.gen();
+            let b: u32 = rng.gen();
+            let c: u32 = rng.gen();
+
+            let a_bit = UInt32::constant(a);
+            let b_bit = UInt32::constant(b);
+            let c_bit = UInt32::constant(c);
+
+            let mut expected = a.wrapping_add(b).wrapping_add(c);
+
+            let r = UInt32::addmany(cs.ns(|| "addition"), &[a_bit, b_bit, c_bit]).unwrap();
+
+            assert!(r.value == Some(expected));
+
+            for b in r.bits.iter() {
+                match b {
+                    &Boolean::Is(_) => panic!(),
+                    &Boolean::Not(_) => panic!(),
+                    &Boolean::Constant(b) => {
+                        assert!(b == (expected & 1 == 1));
+                    },
+                }
+
+                expected >>= 1;
+            }
+        }
+    }
+
+    #[test]
+    fn test_uint32_addmany() {
+        let mut rng = XorShiftRng::from_seed([0x5dbe6259, 0x8d313d76, 0x3237db17, 0xe5bc0654]);
+
+        for _ in 0..1000 {
+            let mut cs = TestConstraintSystem::<Fr>::new();
+
+            let a: u32 = rng.gen();
+            let b: u32 = rng.gen();
+            let c: u32 = rng.gen();
+            let d: u32 = rng.gen();
+
+            let mut expected = (a ^ b).wrapping_add(c).wrapping_add(d);
+
+            let a_bit = UInt32::alloc(cs.ns(|| "a_bit"), Some(a)).unwrap();
+            let b_bit = UInt32::constant(b);
+            let c_bit = UInt32::constant(c);
+            let d_bit = UInt32::alloc(cs.ns(|| "d_bit"), Some(d)).unwrap();
+
+            let r = a_bit.xor(cs.ns(|| "xor"), &b_bit).unwrap();
+            let r = UInt32::addmany(cs.ns(|| "addition"), &[r, c_bit, d_bit]).unwrap();
+
+            assert!(cs.is_satisfied());
+
+            assert!(r.value == Some(expected));
+
+            for b in r.bits.iter() {
+                match b {
+                    &Boolean::Is(ref b) => {
+                        assert!(b.get_value().unwrap() == (expected & 1 == 1));
+                    },
+                    &Boolean::Not(ref b) => {
+                        assert!(!b.get_value().unwrap() == (expected & 1 == 1));
+                    },
+                    &Boolean::Constant(_) => unreachable!(),
+                }
+
+                expected >>= 1;
+            }
+
+            // Flip a bit_gadget and see if the addition constraint still works
+            if cs.get("addition/result bit_gadget 0/boolean").is_zero() {
+                cs.set("addition/result bit_gadget 0/boolean", Field::one());
+            } else {
+                cs.set("addition/result bit_gadget 0/boolean", Field::zero());
+            }
+
+            assert!(!cs.is_satisfied());
+        }
+    }
+
+    #[test]
+    fn test_uint32_rotr() {
+        let mut rng = XorShiftRng::from_seed([0x5dbe6259, 0x8d313d76, 0x3237db17, 0xe5bc0654]);
+
+        let mut num = rng.gen();
+
+        let a = UInt32::constant(num);
+
+        for i in 0..32 {
+            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);
+        }
+    }
+}

r1cs-std/src/bits/uint8.rs

@@ -0,0 +1,399 @@
+use algebra::{ToConstraintField, FpParameters, Field, PrimeField};
+
+use r1cs_core::{ConstraintSystem, SynthesisError};
+
+use crate::boolean::AllocatedBit;
+use crate::fields::fp::FpGadget;
+use crate::prelude::*;
+use crate::Assignment;
+use std::borrow::Borrow;
+
+/// Represents an interpretation of 8 `Boolean` objects as an
+/// unsigned integer.
+#[derive(Clone, Debug)]
+pub struct UInt8 {
+    // Least significant bit_gadget first
+    pub(crate) bits:  Vec<Boolean>,
+    pub(crate) value: Option<u8>,
+}
+
+impl UInt8 {
+    pub fn get_value(&self) -> Option<u8> {
+        self.value
+    }
+
+    /// Construct a constant vector of `UInt8` from a vector of `u8`
+    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`
+    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.
+            if tmp & 1 == 1 {
+                bits.push(Boolean::constant(true))
+            } else {
+                bits.push(Boolean::constant(false))
+            }
+
+            tmp >>= 1;
+        }
+
+        Self {
+            bits,
+            value: Some(value),
+        }
+    }
+
+    pub fn alloc_vec<ConstraintF, CS, T>(mut cs: CS, values: &[T]) -> Result<Vec<Self>, SynthesisError>
+    where
+        ConstraintF: Field,
+        CS: ConstraintSystem<ConstraintF>,
+        T: Into<Option<u8>> + Copy,
+    {
+        let mut output_vec = Vec::with_capacity(values.len());
+        for (i, value) in values.into_iter().enumerate() {
+            let byte: Option<u8> = Into::into(*value);
+            let alloc_byte = Self::alloc(&mut cs.ns(|| format!("byte_{}", i)), || byte.get())?;
+            output_vec.push(alloc_byte);
+        }
+        Ok(output_vec)
+    }
+
+    /// Allocates a vector of `u8`'s by first converting (chunks of) them to
+    /// `ConstraintF` elements, (thus reducing the number of input allocations), and
+    /// then converts this list of `ConstraintF` gadgets back into bytes.
+    pub fn alloc_input_vec<ConstraintF, CS>(mut cs: CS, values: &[u8]) -> Result<Vec<Self>, SynthesisError>
+    where
+        ConstraintF: PrimeField,
+        CS: ConstraintSystem<ConstraintF>,
+    {
+        let values_len = values.len();
+        let field_elements: Vec<ConstraintF> = ToConstraintField::<ConstraintF>::to_field_elements(values).unwrap();
+
+        let max_size = 8 * (ConstraintF::Params::CAPACITY / 8) as usize;
+        let mut allocated_bits = Vec::new();
+        for (i, field_element) in field_elements.into_iter().enumerate() {
+            let fe = FpGadget::alloc_input(&mut cs.ns(|| format!("Field element {}", i)), || {
+                Ok(field_element)
+            })?;
+            let mut fe_bits = fe.to_bits(cs.ns(|| format!("Convert fe to bits {}", i)))?;
+            // FpGadget::to_bits outputs a big-endian binary representation of
+            // fe_gadget's value, so we have to reverse it to get the little-endian
+            // form.
+            fe_bits.reverse();
+
+            // 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())
+    }
+
+    /// Turns this `UInt8` into its little-endian byte order representation.
+    /// LSB-first means that we can easily get the corresponding field element
+    /// via double and add.
+    pub fn into_bits_le(&self) -> Vec<Boolean> {
+        self.bits.iter().cloned().collect()
+    }
+
+    /// Converts a little-endian byte order representation of bits into a
+    /// `UInt8`.
+    pub fn from_bits_le(bits: &[Boolean]) -> Self {
+        assert_eq!(bits.len(), 8);
+
+        let bits = bits.to_vec();
+
+        let mut value = Some(0u8);
+        for b in bits.iter().rev() {
+            value.as_mut().map(|v| *v <<= 1);
+
+            match *b {
+                Boolean::Constant(b) => {
+                    if b {
+                        value.as_mut().map(|v| *v |= 1);
+                    }
+                },
+                Boolean::Is(ref b) => match b.get_value() {
+                    Some(true) => {
+                        value.as_mut().map(|v| *v |= 1);
+                    },
+                    Some(false) => {},
+                    None => value = None,
+                },
+                Boolean::Not(ref b) => match b.get_value() {
+                    Some(false) => {
+                        value.as_mut().map(|v| *v |= 1);
+                    },
+                    Some(true) => {},
+                    None => value = None,
+                },
+            }
+        }
+
+        Self { value, bits }
+    }
+
+    /// XOR this `UInt8` with another `UInt8`
+    pub fn xor<ConstraintF, CS>(&self, mut cs: CS, other: &Self) -> Result<Self, SynthesisError>
+    where
+        ConstraintF: Field,
+        CS: ConstraintSystem<ConstraintF>,
+    {
+        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())
+            .enumerate()
+            .map(|(i, (a, b))| Boolean::xor(cs.ns(|| format!("xor of bit_gadget {}", i)), a, b))
+            .collect::<Result<_, _>>()?;
+
+        Ok(Self {
+            bits,
+            value: new_value,
+        })
+    }
+}
+
+impl PartialEq for UInt8 {
+    fn eq(&self, other: &Self) -> bool {
+        !self.value.is_none() && !other.value.is_none() && self.value == other.value
+    }
+}
+
+impl Eq for UInt8 {}
+
+impl<ConstraintF: Field> ConditionalEqGadget<ConstraintF> for UInt8 {
+    fn conditional_enforce_equal<CS: ConstraintSystem<ConstraintF>>(
+        &self,
+        mut cs: CS,
+        other: &Self,
+        condition: &Boolean,
+    ) -> Result<(), SynthesisError> {
+        for (i, (a, b)) in self.bits.iter().zip(&other.bits).enumerate() {
+            a.conditional_enforce_equal(
+                &mut cs.ns(|| format!("UInt8 equality check for {}-th bit", i)),
+                b,
+                condition,
+            )?;
+        }
+        Ok(())
+    }
+
+    fn cost() -> usize {
+        8 * <Boolean as ConditionalEqGadget<ConstraintF>>::cost()
+    }
+}
+
+impl<ConstraintF: Field> EqGadget<ConstraintF> for UInt8 {}
+
+impl<ConstraintF: Field> AllocGadget<u8, ConstraintF> for UInt8 {
+    fn alloc<F, T, CS: ConstraintSystem<ConstraintF>>(
+        mut cs: CS,
+        value_gen: F,
+    ) -> Result<Self, SynthesisError>
+    where
+        F: FnOnce() -> Result<T, SynthesisError>,
+        T: Borrow<u8>,
+    {
+        let value = value_gen().map(|val| *val.borrow());
+        let values = match value {
+            Ok(mut val) => {
+                let mut v = Vec::with_capacity(8);
+
+                for _ in 0..8 {
+                    v.push(Some(val & 1 == 1));
+                    val >>= 1;
+                }
+
+                v
+            },
+            _ => vec![None; 8],
+        };
+
+        let bits = values
+            .into_iter()
+            .enumerate()
+            .map(|(i, v)| {
+                Ok(Boolean::from(AllocatedBit::alloc(
+                    &mut cs.ns(|| format!("allocated bit_gadget {}", i)),
+                    || v.ok_or(SynthesisError::AssignmentMissing),
+                )?))
+            })
+            .collect::<Result<Vec<_>, SynthesisError>>()?;
+
+        Ok(Self {
+            bits,
+            value: value.ok(),
+        })
+    }
+
+    fn alloc_input<F, T, CS: ConstraintSystem<ConstraintF>>(
+        mut cs: CS,
+        value_gen: F,
+    ) -> Result<Self, SynthesisError>
+    where
+        F: FnOnce() -> Result<T, SynthesisError>,
+        T: Borrow<u8>,
+    {
+        let value = value_gen().map(|val| *val.borrow());
+        let values = match value {
+            Ok(mut val) => {
+                let mut v = Vec::with_capacity(8);
+                for _ in 0..8 {
+                    v.push(Some(val & 1 == 1));
+                    val >>= 1;
+                }
+
+                v
+            },
+            _ => vec![None; 8],
+        };
+
+        let bits = values
+            .into_iter()
+            .enumerate()
+            .map(|(i, v)| {
+                Ok(Boolean::from(AllocatedBit::alloc_input(
+                    &mut cs.ns(|| format!("allocated bit_gadget {}", i)),
+                    || v.ok_or(SynthesisError::AssignmentMissing),
+                )?))
+            })
+            .collect::<Result<Vec<_>, SynthesisError>>()?;
+
+        Ok(Self {
+            bits,
+            value: value.ok(),
+        })
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::UInt8;
+    use crate::{
+        bits::boolean::Boolean, test_constraint_system::TestConstraintSystem, utils::AllocGadget,
+    };
+    use algebra::fields::bls12_381::Fr;
+    use rand::{Rng, SeedableRng, XorShiftRng};
+    use r1cs_core::ConstraintSystem;
+
+    #[test]
+    fn test_uint8_from_bits_to_bits() {
+        let mut cs = TestConstraintSystem::<Fr>::new();
+        let byte_val = 0b01110001;
+        let byte = UInt8::alloc(cs.ns(|| "alloc value"), || Ok(byte_val)).unwrap();
+        let bits = byte.into_bits_le();
+        for (i, bit) in bits.iter().enumerate() {
+            assert_eq!(bit.get_value().unwrap(), (byte_val >> i) & 1 == 1)
+        }
+    }
+
+    #[test]
+    fn test_uint8_alloc_input_vec() {
+        let mut cs = TestConstraintSystem::<Fr>::new();
+        let byte_vals = (64u8..128u8).into_iter().collect::<Vec<_>>();
+        let bytes = UInt8::alloc_input_vec(cs.ns(|| "alloc value"), &byte_vals).unwrap();
+        for (native_byte, gadget_byte) in byte_vals.into_iter().zip(bytes) {
+            let bits = gadget_byte.into_bits_le();
+            for (i, bit) in bits.iter().enumerate() {
+                assert_eq!(bit.get_value().unwrap(), (native_byte >> i) & 1 == 1)
+            }
+        }
+    }
+
+    #[test]
+    fn test_uint8_from_bits() {
+        let mut rng = XorShiftRng::from_seed([0x5dbe6259, 0x8d313d76, 0x3237db17, 0xe5bc0653]);
+
+        for _ in 0..1000 {
+            let v = (0..8)
+                .map(|_| Boolean::constant(rng.gen()))
+                .collect::<Vec<_>>();
+
+            let b = UInt8::from_bits_le(&v);
+
+            for (i, bit_gadget) in b.bits.iter().enumerate() {
+                match bit_gadget {
+                    &Boolean::Constant(bit_gadget) => {
+                        assert!(bit_gadget == ((b.value.unwrap() >> i) & 1 == 1));
+                    },
+                    _ => unreachable!(),
+                }
+            }
+
+            let expected_to_be_same = b.into_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!(),
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_uint8_xor() {
+        let mut rng = XorShiftRng::from_seed([0x5dbe6259, 0x8d313d76, 0x3237db17, 0xe5bc0653]);
+
+        for _ in 0..1000 {
+            let mut cs = TestConstraintSystem::<Fr>::new();
+
+            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::alloc(cs.ns(|| "a_bit"), || Ok(a)).unwrap();
+            let b_bit = UInt8::constant(b);
+            let c_bit = UInt8::alloc(cs.ns(|| "c_bit"), || Ok(c)).unwrap();
+
+            let r = a_bit.xor(cs.ns(|| "first xor"), &b_bit).unwrap();
+            let r = r.xor(cs.ns(|| "second xor"), &c_bit).unwrap();
+
+            assert!(cs.is_satisfied());
+
+            assert!(r.value == Some(expected));
+
+            for b in r.bits.iter() {
+                match b {
+                    &Boolean::Is(ref b) => {
+                        assert!(b.get_value().unwrap() == (expected & 1 == 1));
+                    },
+                    &Boolean::Not(ref b) => {
+                        assert!(!b.get_value().unwrap() == (expected & 1 == 1));
+                    },
+                    &Boolean::Constant(b) => {
+                        assert!(b == (expected & 1 == 1));
+                    },
+                }
+
+                expected >>= 1;
+            }
+        }
+    }
+}