1//! This module defines various traits required by the users of the library to implement.
  2use bellperson::{gadgets::num::AllocatedNum, ConstraintSystem, SynthesisError};
  3use core::{
  4  borrow::Borrow,
  5  fmt::Debug,
  6  ops::{Add, AddAssign, Mul, MulAssign, Neg, Sub, SubAssign},
  7};
  8use merlin::Transcript;
  9use rand::{CryptoRng, RngCore};
 10use rug::Integer;
 11
 12/// Represents an element of a prime field
 13pub trait PrimeField:
 14  Sized
 15  + Eq
 16  + Copy
 17  + Clone
 18  + Default
 19  + Send
 20  + Sync
 21  + Debug
 22  + Add<Output = Self>
 23  + Sub<Output = Self>
 24  + Mul<Output = Self>
 25  + Neg<Output = Self>
 26  + for<'a> Add<&'a Self, Output = Self>
 27  + for<'a> Mul<&'a Self, Output = Self>
 28  + for<'a> Sub<&'a Self, Output = Self>
 29  + AddAssign
 30  + MulAssign
 31  + SubAssign
 32  + for<'a> AddAssign<&'a Self>
 33  + for<'a> MulAssign<&'a Self>
 34  + for<'a> SubAssign<&'a Self>
 35{
 36  /// returns the additive identity of the field
 37  fn zero() -> Self;
 38
 39  /// returns the multiplicative identity of the field
 40  fn one() -> Self;
 41
 42  /// converts the supplied bytes into an element of the field
 43  fn from_bytes_mod_order_wide(bytes: &[u8]) -> Option<Self>;
 44
 45  /// returns an uniformly random element from the finite field
 46  fn random(rng: &mut (impl RngCore + CryptoRng)) -> Self;
 47
 48  /// Get prime field order as a rug::Integer
 49  fn get_order() -> Integer;
 50}
 51
 52/// Represents an element of a group
 53pub trait Group:
 54  Clone
 55  + Copy
 56  + Debug
 57  + Eq
 58  + Sized
 59  + GroupOps
 60  + GroupOpsOwned
 61  + ScalarMul<<Self as Group>::Scalar>
 62  + ScalarMulOwned<<Self as Group>::Scalar>
 63{
 64  /// A type representing an element of the base field of the group
 65  type Base: PrimeField;
 66
 67  /// A type representing an element of the scalar field of the group
 68  type Scalar: PrimeField + ChallengeTrait;
 69
 70  /// A type representing the compressed version of the group element
 71  type CompressedGroupElement: CompressedGroup<GroupElement = Self>;
 72
 73  /// A method to compute a multiexponentation
 74  fn vartime_multiscalar_mul<I, J>(scalars: I, points: J) -> Self
 75  where
 76    I: IntoIterator,
 77    I::Item: Borrow<Self::Scalar>,
 78    J: IntoIterator,
 79    J::Item: Borrow<Self>,
 80    Self: Clone;
 81
 82  /// Compresses the group element
 83  fn compress(&self) -> Self::CompressedGroupElement;
 84
 85  /// Attempts to create a group element from a sequence of bytes,
 86  /// failing with a `None` if the supplied bytes do not encode the group element
 87  fn from_uniform_bytes(bytes: &[u8]) -> Option<Self>;
 88
 89  /// Returns the affine coordinates (x, y, infinty) for the point
 90  fn to_coordinates(&self) -> (Self::Base, Self::Base, bool);
 91}
 92
 93/// Represents a compressed version of a group element
 94pub trait CompressedGroup: Clone + Copy + Debug + Eq + Sized + Send + Sync + 'static {
 95  /// A type that holds the decompressed version of the compressed group element
 96  type GroupElement: Group;
 97
 98  /// Decompresses the compressed group element
 99  fn decompress(&self) -> Option<Self::GroupElement>;
100
101  /// Returns a byte array representing the compressed group element
102  fn as_bytes(&self) -> &[u8];
103}
104
105/// A helper trait to generate challenges using a transcript object
106pub trait ChallengeTrait {
107  /// Returns a Scalar representing the challenge using the transcript
108  fn challenge(label: &'static [u8], transcript: &mut Transcript) -> Self;
109}
110
111/// A helper trait for types with a group operation.
112pub trait GroupOps<Rhs = Self, Output = Self>:
113  Add<Rhs, Output = Output> + Sub<Rhs, Output = Output> + AddAssign<Rhs> + SubAssign<Rhs>
114{
115}
116
117impl<T, Rhs, Output> GroupOps<Rhs, Output> for T where
118  T: Add<Rhs, Output = Output> + Sub<Rhs, Output = Output> + AddAssign<Rhs> + SubAssign<Rhs>
119{
120}
121
122/// A helper trait for references with a group operation.
123pub trait GroupOpsOwned<Rhs = Self, Output = Self>: for<'r> GroupOps<&'r Rhs, Output> {}
124impl<T, Rhs, Output> GroupOpsOwned<Rhs, Output> for T where T: for<'r> GroupOps<&'r Rhs, Output> {}
125
126/// A helper trait for types implementing group scalar multiplication.
127pub trait ScalarMul<Rhs, Output = Self>: Mul<Rhs, Output = Output> + MulAssign<Rhs> {}
128
129impl<T, Rhs, Output> ScalarMul<Rhs, Output> for T where T: Mul<Rhs, Output = Output> + MulAssign<Rhs>
130{}
131
132/// A helper trait for references implementing group scalar multiplication.
133pub trait ScalarMulOwned<Rhs, Output = Self>: for<'r> ScalarMul<&'r Rhs, Output> {}
134impl<T, Rhs, Output> ScalarMulOwned<Rhs, Output> for T where T: for<'r> ScalarMul<&'r Rhs, Output> {}
135
136/// A helper trait for a step of the incremental computation (i.e., circuit for F)
137pub trait StepCircuit<F: PrimeField + ff::PrimeField> {
138  /// Sythesize the circuit for a computation step and return variable
139  /// that corresponds to the output of the step z_{i+1}
140  fn synthesize<CS: ConstraintSystem<F>>(
141    &self,
142    cs: &mut CS,
143    z: AllocatedNum<F>,
144  ) -> Result<AllocatedNum<F>, SynthesisError>;
145}