Struct PlonkCircuit

pub struct PlonkCircuit<F>
where
    F: FftField,
{ /* private fields */ }

A specific Plonk circuit instantiation.

Implementations

impl<F: PrimeField> PlonkCircuit<F>

pub fn emulated_sw_point_witness<E: EmulationConfig<F>>( &self, point_var: &EmulatedSWPointVariable<E>, ) -> Result<SWPoint<E>, CircuitError>

Return the witness point

pub fn create_emulated_sw_point_variable<E: EmulationConfig<F>>( &mut self, point: SWPoint<E>, ) -> Result<EmulatedSWPointVariable<E>, CircuitError>

Add a new emulated EC point (as witness)

pub fn create_constant_emulated_sw_point_variable<E: EmulationConfig<F>>( &mut self, point: SWPoint<E>, ) -> Result<EmulatedSWPointVariable<E>, CircuitError>

Add a new constant emulated EC point

pub fn create_public_emulated_sw_point_variable<E: EmulationConfig<F>>( &mut self, point: SWPoint<E>, ) -> Result<EmulatedSWPointVariable<E>, CircuitError>

Add a new public emulated EC point

pub fn binary_emulated_sw_point_vars_select<E: EmulationConfig<F>>( &mut self, b: BoolVar, p0: &EmulatedSWPointVariable<E>, p1: &EmulatedSWPointVariable<E>, ) -> Result<EmulatedSWPointVariable<E>, CircuitError>

Obtain an emulated point variable of the conditional selection from 2 emulated point variables. b is a boolean variable that indicates selection of P_b from (P0, P1). Return error if invalid input parameters are provided.

pub fn enforce_emulated_sw_point_equal<E: EmulationConfig<F>>( &mut self, p0: &EmulatedSWPointVariable<E>, p1: &EmulatedSWPointVariable<E>, ) -> Result<(), CircuitError>

Constrain two emulated point variables to be the same. Return error if the input point variables are invalid.

pub fn is_emulated_sw_point_equal<E: EmulationConfig<F>>( &mut self, p0: &EmulatedSWPointVariable<E>, p1: &EmulatedSWPointVariable<E>, ) -> Result<BoolVar, CircuitError>

Obtain a bool variable representing whether two input emulated point variables are equal. Return error if variables are invalid.

pub fn emulated_sw_ecc_add_gate<E: EmulationConfig<F>>( &mut self, p0: &EmulatedSWPointVariable<E>, p1: &EmulatedSWPointVariable<E>, p2: &EmulatedSWPointVariable<E>, a: E, ) -> Result<(), CircuitError>

Constrain variable p2 to be the point addition of p0 and p1 over an elliptic curve. Let p0 = (x0, y0, inf0), p1 = (x1, y1, inf1), p2 = (x2, y2, inf2) The addition formula for affine points of sw curve is as follows:

If either p0 or p1 is infinity, then p2 equals to another point.

1. if p0 == p1
   • if y0 == 0 then inf2 = 1
   • Calculate s = (3 * x0^2 + a) / (2 * y0)
   • x2 = s^2 - x0 - x1
   • y2 = s(x0 - x2) - y0
2. Otherwise
   • if x0 == x1 then inf2 = 1
   • Calculate s = (y0 - y1) / (x0 - x1)
   • x2 = s^2 - x0 - x1
   • y2 = s(x0 - x2) - y0

The first case is equivalent to the following:

• inf0 == 1 || inf1 == 1 || x0 != x1 || y0 != y1 || y0 != 0 || inf2 == 0
• (x0 + x1 + x2) * (y0 + y0)^2 == (3 * x0^2 + a)^2
• (y2 + y0) * (y0 + y0) == (3 * x0^2 + a) (x0 - x2)

The second case is equivalent to the following:

• inf0 == 1 || inf1 == 1 || x0 != x1 || y0 == y1 || inf2 == 0
• (x0 - x1)^2 (x0 + x1 + x2) == (y0 - y1)^2
• (x0 - x2) (y0 - y1) == (y0 + y2) (x0 - x1)

First check in both cases can be combined into the following:

inf0 == 1 || inf1 == 1 || inf2 == 0 || x0 != x1 || (y0 == y1 && y0 != 0)

For the rest equality checks,

• Both LHS and RHS must be multiplied with an indicator variable (!inf0 && !inf1). So that if either p0 or p1 is infinity, those checks will trivially pass.
• For the first case (point doubling), both LHS and RHS must be multiplied with an indicator variable (y0 != 0 && x0 == x1 && y1 == y0). So that when y0 == 0 || x0 != x1 || y0 != y1, these checks will trivially pass.
• For the second case, both LHS and RHS must be multiplied with (x0 - x1). So that when x0 == x1, these checks will trivially pass.

pub fn emulated_sw_ecc_add<E: EmulationConfig<F>>( &mut self, p0: &EmulatedSWPointVariable<E>, p1: &EmulatedSWPointVariable<E>, a: E, ) -> Result<EmulatedSWPointVariable<E>, CircuitError>

Obtain a variable to the point addition result of p0 + p1

impl<F: PrimeField> PlonkCircuit<F>

pub fn emulated_te_point_witness<E: EmulationConfig<F>>( &self, point_var: &EmulatedTEPointVariable<E>, ) -> Result<TEPoint<E>, CircuitError>

Return the witness point

pub fn create_emulated_te_point_variable<E: EmulationConfig<F>>( &mut self, p: TEPoint<E>, ) -> Result<EmulatedTEPointVariable<E>, CircuitError>

Add a new emulated EC point (as witness)

pub fn create_constant_emulated_te_point_variable<E: EmulationConfig<F>>( &mut self, p: TEPoint<E>, ) -> Result<EmulatedTEPointVariable<E>, CircuitError>

Add a new constant emulated EC point

pub fn create_public_emulated_te_point_variable<E: EmulationConfig<F>>( &mut self, p: TEPoint<E>, ) -> Result<EmulatedTEPointVariable<E>, CircuitError>

Add a new public emulated EC point

pub fn binary_emulated_te_point_vars_select<E: EmulationConfig<F>>( &mut self, b: BoolVar, p0: &EmulatedTEPointVariable<E>, p1: &EmulatedTEPointVariable<E>, ) -> Result<EmulatedTEPointVariable<E>, CircuitError>

Obtain an emulated point variable of the conditional selection from 2 emulated point variables. b is a boolean variable that indicates selection of P_b from (P0, P1). Return error if invalid input parameters are provided.

pub fn enforce_emulated_te_point_equal<E: EmulationConfig<F>>( &mut self, p0: &EmulatedTEPointVariable<E>, p1: &EmulatedTEPointVariable<E>, ) -> Result<(), CircuitError>

Constrain two emulated point variables to be the same. Return error if the input point variables are invalid.

pub fn is_emulated_te_point_equal<E: EmulationConfig<F>>( &mut self, p0: &EmulatedTEPointVariable<E>, p1: &EmulatedTEPointVariable<E>, ) -> Result<BoolVar, CircuitError>

Obtain a bool variable representing whether two input emulated point variables are equal. Return error if variables are invalid.

pub fn emulated_te_ecc_add_gate<E: EmulationConfig<F>>( &mut self, p0: &EmulatedTEPointVariable<E>, p1: &EmulatedTEPointVariable<E>, p2: &EmulatedTEPointVariable<E>, d: E, ) -> Result<(), CircuitError>

Constrain variable p2 to be the point addition of p0 and p1 over an elliptic curve.

pub fn emulated_te_ecc_add<E: EmulationConfig<F>>( &mut self, p0: &EmulatedTEPointVariable<E>, p1: &EmulatedTEPointVariable<E>, d: E, ) -> Result<EmulatedTEPointVariable<E>, CircuitError>

Obtain a variable to the point addition result of a + b

impl<F> PlonkCircuit<F>

where F: PrimeField,

pub fn glv_mul<P: TECurveConfig<BaseField = F>>( &mut self, scalar: Variable, base: &PointVariable, ) -> Result<PointVariable, CircuitError>

Perform GLV multiplication in circuit (which costs a few less constraints).

impl<F: PrimeField> PlonkCircuit<F>

pub fn point_witness( &self, point_var: &PointVariable, ) -> Result<TEPoint<F>, CircuitError>

Return the witness point for the circuit

pub fn create_point_variable( &mut self, point: TEPoint<F>, ) -> Result<PointVariable, CircuitError>

Add a new EC point (as witness) to the circuit

pub fn create_constant_point_variable( &mut self, point: TEPoint<F>, ) -> Result<PointVariable, CircuitError>

Add a new EC point (as a constant) to the circuit

pub fn create_public_point_variable( &mut self, point: TEPoint<F>, ) -> Result<PointVariable, CircuitError>

Add a new EC point (as public input) to the circuit

pub fn binary_point_vars_select( &mut self, b: BoolVar, point0: &PointVariable, point1: &PointVariable, ) -> Result<PointVariable, CircuitError>

Obtain a point variable of the conditional selection from 2 point variables. b is a boolean variable that indicates selection of P_b from (P0, P1). Return error if invalid input parameters are provided.

pub fn enforce_point_equal( &mut self, point0: &PointVariable, point1: &PointVariable, ) -> Result<(), CircuitError>

Constrain two point variables to be the same. Return error if the input point variables are invalid.

pub fn is_point_equal( &mut self, point0: &PointVariable, point1: &PointVariable, ) -> Result<BoolVar, CircuitError>

Obtain a bool variable representing whether two point variables are equal. Return error if point variables are invalid.

impl<F: PrimeField> PlonkCircuit<F>

pub fn inverse_point( &mut self, point_var: &PointVariable, ) -> Result<PointVariable, CircuitError>

Inverse a point variable

pub fn neutral_point_variable(&self) -> PointVariable

Return the point variable for the infinity point in the TE form: (0, 1)

pub fn is_neutral_point<P>( &mut self, point_var: &PointVariable, ) -> Result<BoolVar, CircuitError>

where P: Config<BaseField = F>,

Obtain a boolean variable indicating whether a point is the neutral point (0, 1) Return variable with value 1 if it is, or 0 otherwise Return error if input variables are invalid

pub fn enforce_on_curve<P: Config<BaseField = F>>( &mut self, point_var: &PointVariable, ) -> Result<(), CircuitError>

Constrain a point to be on certain curve, namely its coordinates satisfy the curve equation, which is curve-dependent. Currently we only support checks of a Affine::<P> over a base field which is the bls12-381 scalar field

Returns error if input variables are invalid

pub fn ecc_add<P: Config<BaseField = F>>( &mut self, point_a: &PointVariable, point_b: &PointVariable, ) -> Result<PointVariable, CircuitError>

Obtain a variable to the point addition result of point_a + point_b where “+” is the group operation over an elliptic curve. Currently only supports Affine::<P> addition.

Returns error if inputs are invalid

pub fn fixed_base_scalar_mul<P: Config<BaseField = F>>( &mut self, scalar: Variable, base: &Affine<P>, ) -> Result<PointVariable, CircuitError>

Obtain the fixed-based scalar multiplication result of scalar * Base Currently only supports Affine::<P> scalar multiplication.

pub fn variable_base_scalar_mul<P: Config<BaseField = F>>( &mut self, scalar: Variable, base: &PointVariable, ) -> Result<PointVariable, CircuitError>

Obtain a variable of the result of a variable base scalar multiplication. both scalar and base are variables. Currently only supports Affine::<P>. If the parameter is bandersnatch, we will use GLV multiplication.

pub fn variable_base_binary_scalar_mul<P: Config<BaseField = F>>( &mut self, scalar_bits_le: &[BoolVar], base: &PointVariable, ) -> Result<PointVariable, CircuitError>

Obtain a variable of the result of a variable base scalar multiplication. Both scalar_bits_le and base are variables, where scalar_bits_le is the little-endian form of the scalar. Currently only supports Affine::<P>.

impl<F: PrimeField> PlonkCircuit<F>

pub fn create_table_and_lookup_variables( &mut self, lookup_vars: &[(Variable, Variable, Variable)], table_vars: &[(Variable, Variable)], ) -> Result<(), CircuitError>

Create a table with keys/values [0, …, n - 1] and [table_vars[0], …, table_vars[n - 1]]; and create a list of variable tuples to be looked up: [lookup_vars[0], …, lookup_vars[m - 1]];

w.l.o.g we assume n = m as we can pad with dummy tuples when n != m

impl<F: PrimeField> PlonkCircuit<F>

pub fn mod_add( &mut self, x: &FpElemVar<F>, y: &FpElemVar<F>, p: &FpElem<F>, ) -> Result<FpElemVar<F>, CircuitError>

Modular addition gate: Given Fp elements x, y and modulus p, compute z = x + y mod p

pub fn mod_add_constant( &mut self, x: &FpElemVar<F>, y: &FpElem<F>, p: &FpElem<F>, ) -> Result<FpElemVar<F>, CircuitError>

Modular addition gate: Given input x: Fp element variable, y: Fp element, and modulus p: Fp element, use y as a constant and compute z = x + y mod p

pub fn mod_add_vec( &mut self, x: &[FpElemVar<F>], p: &FpElem<F>, ) -> Result<FpElemVar<F>, CircuitError>

Modular addition gate: Given Fp elements &[x] and modulus p, compute z = \sum x mod p

pub fn mod_mul( &mut self, x: &FpElemVar<F>, y: &FpElemVar<F>, p: &FpElem<F>, ) -> Result<FpElemVar<F>, CircuitError>

Modular multiplication gate: Given Fp elements x, y and modulus p, compute z = x * y mod p.

pub fn mod_mul_constant( &mut self, x: &FpElemVar<F>, y: &FpElem<F>, p: &FpElem<F>, ) -> Result<FpElemVar<F>, CircuitError>

Modular multiplication gate: Given input x: Fp element variable, y: Fp element, and modulus p: Fp element, use y as a constant compute z = x * y mod p

pub fn mod_negate( &mut self, x: &FpElemVar<F>, p: &F, ) -> Result<FpElemVar<F>, CircuitError>

Negate an FpElemVar mod p where p is a public variable which is also the modulus for the FpElem element.

impl<F: PrimeField> PlonkCircuit<F>

pub fn non_native_power_11_gate<T: PrimeField>( &mut self, x: &FpElemVar<F>, x_to_11: &FpElemVar<F>, ) -> Result<(), CircuitError>

generate a non-native circuit for the statement x^11 = y

Input:

• variable representation of x over a target field T whose order is less than F.
• variable representation of x^11 over a same field

Cost: 5 mod_mul + 2 equal gate

pub fn non_native_power_11_gen<T: PrimeField>( &mut self, x: &FpElemVar<F>, ) -> Result<FpElemVar<F>, CircuitError>

generate a non-native circuit for the statement x^11 = y

Input: variable representation of x over a target field T whose order is less than F.

Output: variable representation of x^11

Cost: 5 mod_mul

pub fn non_native_power_5_gen<T: PrimeField>( &mut self, x: &FpElemVar<F>, ) -> Result<FpElemVar<F>, CircuitError>

generate a non-native circuit for the statement x^5 = y

Input: variable representation of x over a target field T whose order is less than F.

Output: variable representation of x^5

Cost: 3 mod_mul

pub fn non_native_linear_gen<T: PrimeField>( &mut self, x: &[FpElemVar<F>], y: &[FpElem<F>], c: &FpElem<F>, ) -> Result<FpElemVar<F>, CircuitError>

Input vector x and y, and a constant c, generate a non-native circuit for the statement var_output = inner_product(x, y) + c Input: variable representation of x, y, c over a target field T whose order is less than F.

Cost: 4 mod_mul_constant + 1 mod_add_internal

impl<F: PrimeField> PlonkCircuit<F>

pub fn num_range_blocks(&self) -> Result<usize, CircuitError>

The number of range blocks, i.e., the minimal integer such that RANGE_SIZE^NUM_RANGES >= p,

impl<F: PrimeField> PlonkCircuit<F>

pub fn quad_poly_gate( &mut self, wires: &[Variable; 5], q_lc: &[F; 4], q_mul: &[F; 2], q_o: F, q_c: F, ) -> Result<(), CircuitError>

Arithmetic gates

Quadratic polynomial gate: q1 * a + q2 * b + q3 * c + q4 * d + q12 * a * b + q34 * c * d + q_c = q_o * e, where q1, q2, q3, q4, q12, q34, q_c, q_o are selectors; a, b, c, d are input wires; e is the output wire. Return error if variables are invalid.

pub fn gen_quad_poly( &mut self, wires: &[Variable; 4], q_lc: &[F; 4], q_mul: &[F; 2], q_c: F, ) -> Result<Variable, CircuitError>

Arithmetic gates

Quadratic polynomial gate: e = q1 * a + q2 * b + q3 * c + q4 * d + q12 * a * b + q34 * c * d + q_c, where q1, q2, q3, q4, q12, q34, q_c are selectors; a, b, c, d are input wires

Return the variable for Return error if variables are invalid.

pub fn lc_gate( &mut self, wires: &[Variable; 5], coeffs: &[F; 4], ) -> Result<(), CircuitError>

Constrain a linear combination gate: q1 * a + q2 * b + q3 * c + q4 * d = y

pub fn lc( &mut self, wires_in: &[Variable; 4], coeffs: &[F; 4], ) -> Result<Variable, CircuitError>

Obtain a variable representing a linear combination. Return error if variables are invalid.

pub fn mul_add_gate( &mut self, wires: &[Variable; 5], q_muls: &[F; 2], ) -> Result<(), CircuitError>

Constrain a mul-addition gate: q_muls[0] * wires[0] * wires[1] + q_muls[1] * wires[2] * wires[3] = wires[4]

pub fn mul_add( &mut self, wires_in: &[Variable; 4], q_muls: &[F; 2], ) -> Result<Variable, CircuitError>

Obtain a variable representing q12 * a * b + q34 * c * d, where a, b, c, d are input wires, and q12, q34 are selectors. Return error if variables are invalid.

pub fn sum(&mut self, elems: &[Variable]) -> Result<Variable, CircuitError>

Obtain a variable representing the sum of a list of variables. Return error if variables are invalid.

pub fn add_constant_gate( &mut self, x: Variable, c: F, y: Variable, ) -> Result<(), CircuitError>

Constrain variable y to the addition of a and c, where c is a constant value Return error if the input variables are invalid.

pub fn add_constant( &mut self, input_var: Variable, elem: &F, ) -> Result<Variable, CircuitError>

Obtains a variable representing an addition with a constant value Return error if the input variable is invalid

pub fn mul_constant_gate( &mut self, x: Variable, c: F, y: Variable, ) -> Result<(), CircuitError>

Constrain variable y to the product of a and c, where c is a constant value Return error if the input variables are invalid.

pub fn mul_constant( &mut self, input_var: Variable, elem: &F, ) -> Result<Variable, CircuitError>

Obtains a variable representing a multiplication with a constant value Return error if the input variable is invalid

pub fn power_11_gen(&mut self, x: Variable) -> Result<Variable, CircuitError>

Return a variable to be the 11th power of the input variable. Cost: 3 constraints.

pub fn power_11_gate( &mut self, x: Variable, x_to_11: Variable, ) -> Result<(), CircuitError>

Constraint a variable to be the 11th power of another variable. Cost: 3 constraints.

pub fn truncate( &mut self, a: Variable, bit_length: usize, ) -> Result<Variable, CircuitError>

Obtain the truncation of the input. Constrain that the input and output values congruent modulo 2^bit_length. Return error if the input is invalid.

pub fn truncate_gate( &mut self, a: Variable, b: Variable, bit_length: usize, ) -> Result<(), CircuitError>

Truncation gate. Constrain that b == a modulo 2^bit_length. Return error if the inputs are invalid; or b >= 2^bit_length.

impl<F: PrimeField> PlonkCircuit<F>

pub fn enforce_lt( &mut self, a: Variable, b: Variable, ) -> Result<(), CircuitError>

where F: PrimeField,

Constrain that a < b.

pub fn enforce_leq( &mut self, a: Variable, b: Variable, ) -> Result<(), CircuitError>

where F: PrimeField,

Constrain that a <= b

pub fn enforce_gt( &mut self, a: Variable, b: Variable, ) -> Result<(), CircuitError>

where F: PrimeField,

Constrain that a > b.

pub fn enforce_geq( &mut self, a: Variable, b: Variable, ) -> Result<(), CircuitError>

where F: PrimeField,

Constrain that a >= b.

pub fn is_lt( &mut self, a: Variable, b: Variable, ) -> Result<BoolVar, CircuitError>

where F: PrimeField,

Returns a BoolVar indicating whether a < b.

pub fn is_gt( &mut self, a: Variable, b: Variable, ) -> Result<BoolVar, CircuitError>

where F: PrimeField,

Returns a BoolVar indicating whether a > b.

pub fn is_leq( &mut self, a: Variable, b: Variable, ) -> Result<BoolVar, CircuitError>

where F: PrimeField,

Returns a BoolVar indicating whether a <= b.

pub fn is_geq( &mut self, a: Variable, b: Variable, ) -> Result<BoolVar, CircuitError>

where F: PrimeField,

Returns a BoolVar indicating whether a >= b.

pub fn is_lt_constant( &mut self, a: Variable, val: F, ) -> Result<BoolVar, CircuitError>

where F: PrimeField,

Returns a BoolVar indicating whether the variable a is less than a given constant val.

pub fn is_leq_constant( &mut self, a: Variable, val: F, ) -> Result<BoolVar, CircuitError>

where F: PrimeField,

Returns a BoolVar indicating whether the variable a is less than or equal to a given constant val.

pub fn is_gt_constant( &mut self, a: Variable, val: F, ) -> Result<BoolVar, CircuitError>

where F: PrimeField,

Returns a BoolVar indicating whether the variable a is greater than a given constant val.

pub fn is_geq_constant( &mut self, a: Variable, val: F, ) -> Result<BoolVar, CircuitError>

where F: PrimeField,

Returns a BoolVar indicating whether the variable a is greater than or equal a given constant val.

pub fn enforce_lt_constant( &mut self, a: Variable, val: F, ) -> Result<(), CircuitError>

where F: PrimeField,

Enforce the variable a to be less than a given constant val.

pub fn enforce_leq_constant( &mut self, a: Variable, val: F, ) -> Result<(), CircuitError>

where F: PrimeField,

Enforce the variable a to be less than or equal to a given constant val.

pub fn enforce_gt_constant( &mut self, a: Variable, val: F, ) -> Result<(), CircuitError>

where F: PrimeField,

Enforce the variable a to be greater than a given constant val.

pub fn enforce_geq_constant( &mut self, a: Variable, val: F, ) -> Result<(), CircuitError>

where F: PrimeField,

Enforce the variable a to be greater than or equal a given constant val.

impl<F: PrimeField> PlonkCircuit<F>

pub fn emulated_witness<E: EmulationConfig<F>>( &self, var: &EmulatedVariable<E>, ) -> Result<E, CircuitError>

Return the witness point for the circuit

pub fn create_emulated_variable<E: EmulationConfig<F>>( &mut self, val: E, ) -> Result<EmulatedVariable<E>, CircuitError>

Add an emulated variable

pub fn create_constant_emulated_variable<E: EmulationConfig<F>>( &mut self, val: E, ) -> Result<EmulatedVariable<E>, CircuitError>

Add a constant emulated variable

pub fn create_public_emulated_variable<E: EmulationConfig<F>>( &mut self, val: E, ) -> Result<EmulatedVariable<E>, CircuitError>

Add a public emulated variable

pub fn emulated_mul_gate<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: &EmulatedVariable<E>, c: &EmulatedVariable<E>, ) -> Result<(), CircuitError>

Constrain that a*b=c in the emulated field. Checking that a * b - k * E::MODULUS = c. This function doesn’t perform emulated variable validity check on the input a, b and c. We assume that they are already performed elsewhere.

pub fn emulated_mul<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: &EmulatedVariable<E>, ) -> Result<EmulatedVariable<E>, CircuitError>

Return an EmulatedVariable which equals to a*b.

pub fn emulated_mul_constant_gate<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: E, c: &EmulatedVariable<E>, ) -> Result<(), CircuitError>

Constrain that a*b=c in the emulated field for a constant b. This function doesn’t perform emulated variable validity check on the input a and c. We assume that they are already performed elsewhere.

pub fn emulated_mul_constant<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: E, ) -> Result<EmulatedVariable<E>, CircuitError>

Return an EmulatedVariable which equals to a*b.

pub fn emulated_add_gate<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: &EmulatedVariable<E>, c: &EmulatedVariable<E>, ) -> Result<(), CircuitError>

Constrain that a+b=c in the emulated field. Checking whether a + b = k * E::MODULUS + c This function doesn’t perform emulated variable validity check on the input a, b and c. We assume that they are already performed elsewhere.

pub fn emulated_add<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: &EmulatedVariable<E>, ) -> Result<EmulatedVariable<E>, CircuitError>

Return an EmulatedVariable which equals to a+b.

pub fn emulated_sub<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: &EmulatedVariable<E>, ) -> Result<EmulatedVariable<E>, CircuitError>

Return an EmulatedVariable which equals to a-b.

pub fn emulated_add_constant_gate<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: E, c: &EmulatedVariable<E>, ) -> Result<(), CircuitError>

Constrain that a+b=c in the emulated field. This function doesn’t perform emulated variable validity check on the input a and c. We assume that they are already performed elsewhere.

pub fn emulated_add_constant<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: E, ) -> Result<EmulatedVariable<E>, CircuitError>

Return an EmulatedVariable which equals to a + b where b is a constant.

pub fn emulated_sub_constant<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: E, ) -> Result<EmulatedVariable<E>, CircuitError>

Return an EmulatedVariable which equals to a - b where b is a constant.

pub fn conditional_select_emulated<E: EmulationConfig<F>>( &mut self, b: BoolVar, p0: &EmulatedVariable<E>, p1: &EmulatedVariable<E>, ) -> Result<EmulatedVariable<E>, CircuitError>

Obtain an emulated variable of the conditional selection from 2 emulated variables. b is a boolean variable that indicates selection of P_b from (P0, P1). Return error if invalid input parameters are provided.

pub fn enforce_emulated_var_equal<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: &EmulatedVariable<E>, ) -> Result<(), CircuitError>

Constrain two emulated variables to be the same. Return error if the input variables are invalid.

pub fn is_emulated_var_equal<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, b: &EmulatedVariable<E>, ) -> Result<BoolVar, CircuitError>

Obtain a bool variable representing whether two input emulated variables are equal. Return error if variables are invalid.

pub fn is_emulated_var_zero<E: EmulationConfig<F>>( &mut self, a: &EmulatedVariable<E>, ) -> Result<BoolVar, CircuitError>

Obtain a bool variable representing whether the input emulated variable is zero. Return error if variables are invalid.

impl<F: PrimeField> PlonkCircuit<F>

pub fn logic_or_gate( &mut self, a: BoolVar, b: BoolVar, ) -> Result<(), CircuitError>

Constrain that a is true or b is true. Return error if variables are invalid.

pub fn is_equal( &mut self, a: Variable, b: Variable, ) -> Result<BoolVar, CircuitError>

Obtain a bool variable representing whether two input variables are equal. Return error if variables are invalid.

pub fn is_zero(&mut self, a: Variable) -> Result<BoolVar, CircuitError>

Obtain a bool variable representing whether input variable is zero. Return error if the input variable is invalid.

pub fn non_zero_gate(&mut self, var: Variable) -> Result<(), CircuitError>

Constrain a variable to be non-zero. Return error if the variable is invalid.

pub fn logic_neg(&mut self, a: BoolVar) -> Result<BoolVar, CircuitError>

Obtain a variable representing the result of a logic negation gate. Return the index of the variable. Return error if the input variable is invalid.

pub fn logic_and( &mut self, a: BoolVar, b: BoolVar, ) -> Result<BoolVar, CircuitError>

Obtain a variable representing the result of a logic AND gate. Return the index of the variable. Return error if the input variables are invalid.

pub fn logic_and_all( &mut self, vars: &[BoolVar], ) -> Result<BoolVar, CircuitError>

Given a list of boolean variables, obtain a variable representing the result of a logic AND gate. Return the index of the variable. Return error if the input variables are invalid.

pub fn logic_or( &mut self, a: BoolVar, b: BoolVar, ) -> Result<BoolVar, CircuitError>

Obtain a variable representing the result of a logic OR gate. Return the index of the variable. Return error if the input variables are invalid.

pub fn enforce_true(&mut self, a: Variable) -> Result<(), CircuitError>

Assuming values represented by a is boolean. Constrain a is true

pub fn enforce_false(&mut self, a: Variable) -> Result<(), CircuitError>

Assuming values represented by a is boolean. Constrain a is false

pub fn conditional_select( &mut self, b: BoolVar, x_0: Variable, x_1: Variable, ) -> Result<Variable, CircuitError>

Obtain a variable that equals x_0 if b is zero, or x_1 if b is one. Return error if variables are invalid.

impl<F: PrimeField> PlonkCircuit<F>

pub fn enforce_in_range( &mut self, a: Variable, bit_len: usize, ) -> Result<(), CircuitError>

Constrain a variable to be within the [0, 2^bit_len) range Return error if the variable is invalid.

pub fn is_in_range( &mut self, a: Variable, bit_len: usize, ) -> Result<BoolVar, CircuitError>

Return a boolean variable indicating whether variable a is in the range [0, 2^bit_len). Return error if the variable is invalid. TODO: optimize the gate for UltraPlonk.

pub fn unpack( &mut self, a: Variable, bit_len: usize, ) -> Result<Vec<BoolVar>, CircuitError>

Obtain the bit_len-long binary representation of variable a Return a list of variables [b0, …, b_bit_len] which is the binary representation of a. Return error if the a is not the range of [0, 2^bit_len).

impl<F: FftField> PlonkCircuit<F>

pub fn new_turbo_plonk() -> Self

Construct a new TurboPlonk circuit.

pub fn new_ultra_plonk(range_bit_len: usize) -> Self

Construct a new UltraPlonk circuit.

pub fn insert_gate( &mut self, wire_vars: &[Variable; 5], gate: Box<dyn Gate<F>>, ) -> Result<(), CircuitError>

Insert a general (algebraic) gate

• wire_vars - wire variables. Each of these variables must be in range
• gate - specific gate to be inserted
• returns - an error if some verification fails

pub fn add_range_check_variable( &mut self, var: Variable, ) -> Result<(), CircuitError>

Add a range_check gate that checks whether a variable is in the range [0, range_size). Return an error if the circuit does not support lookup.

pub fn check_var_bound(&self, var: Variable) -> Result<(), CircuitError>

Checks if a variable is strictly less than the number of variables. This function must be invoked for each gate as this check is not applied in the function insert_gate

• var - variable to check
• returns - Error if the variable is out of bound (i.e. >= number of variables)

pub fn check_vars_bound(&self, vars: &[Variable]) -> Result<(), CircuitError>

Check if a list of variables are strictly less than the number of variables.

• vars - variables to check
• returns - Error if the variable is out of bound (i.e. >= number of variables)

pub fn witness_mut(&mut self, idx: Variable) -> &mut F

Change the value of a variable. Only used for testing.

pub fn range_bit_len(&self) -> Result<usize, CircuitError>

The bit length of UltraPlonk range gates.

pub fn range_size(&self) -> Result<usize, CircuitError>

The range size of UltraPlonk range gates.

impl<F: PrimeField> PlonkCircuit<F>

Methods for finalizing and merging the circuits.

pub fn finalize_for_arithmetization(&mut self) -> Result<(), CircuitError>

Finalize the setup of the circuit before arithmetization.

pub fn finalize_for_mergeable_circuit( &mut self, circuit_type: MergeableCircuitType, ) -> Result<(), CircuitError>

Finalize the setup of a mergeable circuit. Two circuits can be merged only if they are with different circuit types The method only supports TurboPlonk circuits.

pub fn merge(&self, other: &Self) -> Result<Self, CircuitError>

Merge a type A circuit with a type B circuit. Both circuits should have been finalized before. The method only supports TurboPlonk circuits.

Trait Implementations

impl<F> Arithmetization<F> for PlonkCircuit<F>

where F: PrimeField,

fn srs_size(&self) -> Result<usize, CircuitError>

The required SRS size for the circuit.

fn eval_domain_size(&self) -> Result<usize, CircuitError>

Get the size of the evaluation domain for arithmetization (after circuit has been finalized).

fn compute_selector_polynomials( &self, ) -> Result<Vec<DensePolynomial<F>>, CircuitError>

Compute and return selector polynomials. Return an error if the circuit has not been finalized yet.

fn compute_extended_permutation_polynomials( &self, ) -> Result<Vec<DensePolynomial<F>>, CircuitError>

Compute and return extended permutation polynomials. Return an error if the circuit has not been finalized yet.

fn compute_prod_permutation_polynomial( &self, beta: &F, gamma: &F, ) -> Result<DensePolynomial<F>, CircuitError>

Compute and return the product polynomial for permutation arguments. Return an error if the circuit has not been finalized yet.

fn compute_wire_polynomials( &self, ) -> Result<Vec<DensePolynomial<F>>, CircuitError>

Compute and return the list of wiring witness polynomials. Return an error if the circuit has not been finalized yet.

fn compute_pub_input_polynomial( &self, ) -> Result<DensePolynomial<F>, CircuitError>

Compute and return the public input polynomial. Return an error if the circuit has not been finalized yet. The IO gates of the circuit are guaranteed to be in the front.

fn compute_range_table_polynomial( &self, ) -> Result<DensePolynomial<F>, CircuitError>

Plookup-related methods Return default errors if the constraint system does not support lookup gates.

fn compute_key_table_polynomial( &self, ) -> Result<DensePolynomial<F>, CircuitError>

Compute and return the polynomial that interpolates the key table elements. Return an error if the circuit does not support lookup or has not been finalized yet.

fn compute_table_dom_sep_polynomial( &self, ) -> Result<DensePolynomial<F>, CircuitError>

Compute and return the polynomial that interpolates the table domain separation ids. Return an error if the circuit does not support lookup or has not been finalized.

fn compute_q_dom_sep_polynomial( &self, ) -> Result<DensePolynomial<F>, CircuitError>

Compute and return the polynomial that interpolates the lookup domain sepration selectors for the lookup gates. Return an error if the circuit does not support lookup or has not been finalized.

fn compute_merged_lookup_table(&self, tau: F) -> Result<Vec<F>, CircuitError>

Compute and return the combined lookup table vector given random challenge tau.

fn compute_lookup_prod_polynomial( &self, tau: &F, beta: &F, gamma: &F, merged_lookup_table: &[F], sorted_vec: &[F], ) -> Result<DensePolynomial<F>, CircuitError>

Compute and return the product polynomial for Plookup arguments. beta and gamma are random challenges, sorted_vec is the sorted concatenation of the lookup table and the lookup witnesses. Return an error if the circuit does not support lookup or has not been finalized yet.

fn compute_lookup_sorted_vec_polynomials( &self, tau: F, merged_lookup_table: &[F], ) -> Result<(Vec<F>, DensePolynomial<F>, DensePolynomial<F>), CircuitError>

Compute the sorted concatenation of the (merged) lookup table and the witness values to be checked in lookup gates. Return the sorted vector and 2 polynomials that interpolate the vector. Return an error if the circuit does not support lookup or has not been finalized yet.

impl<F: FftField> Circuit<F> for PlonkCircuit<F>

fn zero(&self) -> Variable

Default zero variable

fn one(&self) -> Variable

Default one variable

fn num_gates(&self) -> usize

The number of constraints.

fn num_vars(&self) -> usize

The number of variables.

fn num_inputs(&self) -> usize

The number of public input variables.

fn num_wire_types(&self) -> usize

The number of wire types of the circuit. E.g., UltraPlonk has 4 different types of input wires, 1 type of output wires, and 1 type of lookup wires.

fn public_input(&self) -> Result<Vec<F>, CircuitError>

The list of public input values.

fn check_circuit_satisfiability( &self, pub_input: &[F], ) -> Result<(), CircuitError>

Check circuit satisfiability against a public input.

fn create_constant_variable(&mut self, val: F) -> Result<Variable, CircuitError>

Add a constant variable to the circuit; return the index of the variable.

fn create_variable(&mut self, val: F) -> Result<Variable, CircuitError>

Add a variable to the circuit; return the index of the variable.

fn create_public_variable(&mut self, val: F) -> Result<Variable, CircuitError>

Add a public input variable; return the index of the variable.

fn set_variable_public(&mut self, var: Variable) -> Result<(), CircuitError>

Set a variable to a public variable

fn witness(&self, idx: Variable) -> Result<F, CircuitError>

Return the witness value of variable idx. Return error if the input variable is invalid.

fn enforce_constant( &mut self, var: Variable, constant: F, ) -> Result<(), CircuitError>

Common gates that should be implemented in any constraint systems.

fn add_gate( &mut self, a: Variable, b: Variable, c: Variable, ) -> Result<(), CircuitError>

Constrain variable c to the addition of a and b. Return error if the input variables are invalid.

fn add(&mut self, a: Variable, b: Variable) -> Result<Variable, CircuitError>

Obtain a variable representing an addition. Return the index of the variable. Return error if the input variables are invalid.

fn sub_gate( &mut self, a: Variable, b: Variable, c: Variable, ) -> Result<(), CircuitError>

Constrain variable c to the subtraction of a and b. Return error if the input variables are invalid.

fn sub(&mut self, a: Variable, b: Variable) -> Result<Variable, CircuitError>

Obtain a variable representing a subtraction. Return the index of the variable. Return error if the input variables are invalid.

fn mul_gate( &mut self, a: Variable, b: Variable, c: Variable, ) -> Result<(), CircuitError>

Constrain variable c to the multiplication of a and b. Return error if the input variables are invalid.

fn mul(&mut self, a: Variable, b: Variable) -> Result<Variable, CircuitError>

Obtain a variable representing a multiplication. Return the index of the variable. Return error if the input variables are invalid.

fn enforce_bool(&mut self, a: Variable) -> Result<(), CircuitError>

Constrain a variable to a bool. Return error if the input is invalid.

fn enforce_equal( &mut self, a: Variable, b: Variable, ) -> Result<(), CircuitError>

Constrain two variables to have the same value. Return error if the input variables are invalid.

fn pad_gates(&mut self, n: usize)

Pad the circuit with n dummy gates

fn support_lookup(&self) -> bool

Plookup-related methods. Return true if the circuit support lookup gates.

fn create_boolean_variable( &mut self, val: bool, ) -> Result<BoolVar, CircuitError>

Add a bool variable to the circuit; return the index of the variable.

fn create_public_boolean_variable( &mut self, val: bool, ) -> Result<BoolVar, CircuitError>

Add a public bool variable to the circuit; return the index of the variable.

fn false_var(&self) -> BoolVar

Return a default variable with value false (namely zero).

fn true_var(&self) -> BoolVar

Return a default variable with value true (namely one).

impl<F> Clone for PlonkCircuit<F>

where F: FftField + Clone,

fn clone(&self) -> PlonkCircuit<F>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<F> Debug for PlonkCircuit<F>

where F: FftField + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: FftField> Default for PlonkCircuit<F>

fn default() -> Self

Returns the “default value” for a type.

impl<F, P> MultiScalarMultiplicationCircuit<F, P> for PlonkCircuit<F>

where F: PrimeField, P: Config<BaseField = F>,

fn msm( &mut self, bases: &[PointVariable], scalars: &[Variable], ) -> Result<PointVariable, CircuitError>

Compute the multi-scalar-multiplications. Use pippenger when the circuit supports lookup; Use naive method otherwise. Return error if the number bases does not match the number of scalars.

fn msm_with_var_scalar_length( &mut self, bases: &[PointVariable], scalars: &[Variable], scalar_bit_length: usize, ) -> Result<PointVariable, CircuitError>

Compute the multi-scalar-multiplications where each scalar has at most scalar_bit_length bits.