Struct kimchi::circuits::gate::CircuitGate

pub struct CircuitGate<F: PrimeField> {
    pub typ: GateType,
    pub wires: GateWires,
    pub coeffs: Vec<F>,
}

A single gate in a circuit.

Fields

typ: GateType

type of the gate

wires: GateWires

gate wiring (for each cell, what cell it is wired to)

coeffs: Vec<F>

public selector polynomials that can used as handy coefficients in gates

Implementations

impl<F> CircuitGate<F>where F: PrimeField,

pub fn new(typ: GateType, wires: GateWires, coeffs: Vec<F>) -> Self

impl<F: PrimeField> CircuitGate<F>

pub fn zero(wires: GateWires) -> Self

this function creates “empty” circuit gate

pub fn verify<G: KimchiCurve<ScalarField = F>, OpeningProof: OpenProof<G>>( &self, row: usize, witness: &[Vec<F>; 15], index: &ProverIndex<G, OpeningProof>, public: &[F] ) -> Result<(), String>

This function verifies the consistency of the wire assignments (witness) against the constraints

Errors

Will give error if verify process returns error.

pub fn verify_witness<G: KimchiCurve<ScalarField = F>>( &self, row: usize, witness: &[Vec<F>; 15], cs: &ConstraintSystem<F>, _public: &[F] ) -> CircuitGateResult<()>

Verify the witness against the constraints

impl<F: PrimeField> CircuitGate<F>

pub fn extend_and(gates: &mut Vec<Self>, bytes: usize) -> usize

Extends an AND gadget for bytes length. The full operation being performed is the following: a AND b = 1/2 * (a + b - (a XOR b)) Includes:

• num_xors Xor16 gates to perform xor = a XOR b
• 1 Generic gate to constrain the final row to be zero with itself
• 1 double Generic gate to perform the AND operation as a + b = sum and 2 * and = sum - xor Input:
• gates : vector of circuit gates comprising the full circuit
• bytes : number of bytes of the AND operation Output:
• next_row : next row after this gate Warning:
• if there’s any public input for the and, don’t forget to wire it

impl<F: PrimeField> CircuitGate<F>

pub fn verify_complete_add( &self, row: usize, witness: &[Vec<F>; 15] ) -> Result<(), String>

Check the correctness of witness values for a complete-add gate.

Errors

Will give error if the gate value validations are not met.

Panics

Will panic if multiplicative inverse operation between gate values fails.

impl<F: PrimeField> CircuitGate<F>

pub fn verify_endomul_scalar<G: KimchiCurve<ScalarField = F>>( &self, row: usize, witness: &[Vec<F>; 15], _cs: &ConstraintSystem<F> ) -> Result<(), String>

Verify the EndoMulscalar gate.

Errors

Will give error if self.typ is not GateType::EndoMulScalar, or there are errors in gate values.

impl<F: PrimeField> CircuitGate<F>

Implementation of group endomorphism optimised variable base scalar multiplication custom Plonk constraints.

pub fn create_endomul(wires: GateWires) -> Self

pub fn verify_endomul<G: KimchiCurve<ScalarField = F>>( &self, row: usize, witness: &[Vec<F>; 15], cs: &ConstraintSystem<F> ) -> Result<(), String>

Verify the EndoMul gate.

Errors

Will give error if self.typ is not GateType::EndoMul, or constraint evaluation fails.

pub fn endomul(&self) -> F

impl<F: PrimeField> CircuitGate<F>

pub fn create_chain_ffadd( start_row: usize, opcodes: &[FFOps], foreign_field_modulus: &BigUint ) -> (usize, Vec<Self>)

Create foreign field addition gate chain without range checks (needs to wire the range check for result bound manually)

• Inputs
  • starting row
  • operations to perform
  • modulus of the foreign field
• Outputs tuple (next_row, circuit_gates) where
  • next_row - next row after this gate
  • circuit_gates - vector of circuit gates comprising this gate

Note that the final structure of the circuit is as follows: circuit_gates = [ { (i) -> -> 1 ForeignFieldAdd row } * num times (n) -> 1 ForeignFieldAdd row (this is where the final result goes) (n+1) -> 1 Zero row for bound result ]

Warning:

• Wire the range check for result bound manually
• Connect to public input containing the 1 value for the overflow in the final bound check
• If the inputs of the addition come from public input, wire it as well

pub fn create_single_ffadd( start_row: usize, operation: FFOps, foreign_field_modulus: &BigUint ) -> (usize, Vec<Self>)

Create a single foreign field addition gate. This is used for example in the final bound check.

• Inputs
  • starting row
  • operation to perform
  • modulus of the foreign field
• Outputs tuple (next_row, circuit_gates) where
  • next_row - next row after this gate
  • circuit_gates - vector of circuit gates comprising this gate

pub fn extend_chain_ffadd( gates: &mut Vec<Self>, pub_row: usize, curr_row: &mut usize, opcodes: &[FFOps], foreign_field_modulus: &BigUint )

Extend a chain of foreign field addition gates. It already wires 1 value to the overflow cell.

• Inputs
  • gates: vector of gates to extend
  • pub_row: row of the public input
  • curr_row: mutable reference to the current row
  • opcodes: operations to perform
  • foreign_field_modulus: modulus of the foreign field

pub fn extend_single_ffadd( gates: &mut Vec<Self>, curr_row: &mut usize, operation: FFOps, foreign_field_modulus: &BigUint )

Extend a single foreign field addition gate followed by a zero row containing the result

impl<F: PrimeField> CircuitGate<F>

pub fn create_foreign_field_mul( start_row: usize, foreign_field_modulus: &BigUint ) -> (usize, Vec<Self>)

Create foreign field multiplication gate Inputs the starting row Outputs tuple (next_row, circuit_gates) where next_row - next row after this gate circuit_gates - vector of circuit gates comprising this gate

pub fn extend_foreign_field_mul( gates: &mut Vec<Self>, curr_row: &mut usize, foreign_field_modulus: &BigUint )

Create foreign field multiplication gate by extending the existing gates

pub fn extend_high_bounds( gates: &mut Vec<Self>, curr_row: &mut usize, foreign_field_modulus: &BigUint )

impl<F: PrimeField> CircuitGate<F>

pub fn verify_generic( &self, row: usize, witness: &[Vec<F>; 15], public: &[F] ) -> Result<(), String>

verifies that the generic gate constraints are solved by the witness

Errors

Will give error if self.typ is not GateType::Generic.

impl<F: PrimeField> CircuitGate<F>

pub fn create_generic(wires: GateWires, c: [F; 10]) -> Self

This allows you to create two generic gates that will fit in one row, check Self::create_generic_gadget for a better to way to create these gates.

pub fn create_generic_gadget( wires: GateWires, gate1: GenericGateSpec<F>, gate2: Option<GenericGateSpec<F>> ) -> Self

This allows you to create two generic gates by passing the desired gate1 and gate2 as two GenericGateSpec.

pub fn extend_generic( gates: &mut Vec<Self>, curr_row: &mut usize, wires: GateWires, gate1: GenericGateSpec<F>, gate2: Option<GenericGateSpec<F>> )

impl<F: PrimeField> CircuitGate<F>

pub fn extend_keccak(circuit: &mut Vec<Self>, bytelength: usize) -> usize

Extends a Keccak circuit to hash one message Note: Requires at least one more row after the Keccak gadget so that constraints can access the next row in the squeeze

impl<F: PrimeField> CircuitGate<F>

pub fn extend_not_gadget_unchecked_length( gates: &mut Vec<Self>, n: usize, pub_row: usize ) -> usize

Extends a bitwise negation gadget with n NOT components of some length previously constrained using a generic gate (checking that a cell stores 2^bits-1 value). Assumes that the inputs are known to have at most bits length. Starts the gates in the new_row position. Includes:

• ceil(n/2) Double Generic gates to perform the ( 2^(bits) - 1 ) - input operation for every two inputs in each row Input:
• gates : full circuit
• n : number of negations to perform
• pub_row : row containing the public input with the all-one word of the given length Important:
• If the bit length of the input is not fixed, then it must be constrained somewhere else.
• Otherwise, use the extend_neg_checked_length instead (but this one requires about 8 times more rows). Warning:
• don’t forget to include a public input in pub_row to constrain the left of each generic gate for negation to be 2^bits - 1

pub fn extend_not_gadget_checked_length( gates: &mut Vec<Self>, all_ones_row: usize, bits: usize ) -> usize

Extends a NOT gadget for bits length using Xor gates. It implicitly constrains the length of the input to be at most 16 * num_xors bits. Includes:

• num_xors Xor16 gates
• 1 Generic gate to constrain the final row to be zero with itself Input:
• gates : full circuit
• pub_row : row containing the public input with the all-one word of the given length
• bits : number of bits of the input Precndition:
• 1 initial public input generic gate in all_ones_row to constrain the input to be 2^bits-1. Warning:
• don’t forget to connect the left input to a public input row containing the 2^bits - 1 value

impl<F: PrimeField> CircuitGate<F>

pub fn create_poseidon(wires: GateWires, coeffs: [[F; 3]; 5]) -> Self

pub fn create_poseidon_gadget( row: usize, first_and_last_row: [GateWires; 2], round_constants: &[Vec<F>] ) -> (Vec<Self>, usize)

create_poseidon_gadget(row, first_and_last_row, round_constants) creates an entire set of constraint for a Poseidon hash. For that, you need to pass:

• the index of the first row
• the first and last rows’ wires (because they are used in the permutation)
• the round constants The function returns a set of gates, as well as the next pointer to the circuit (next empty absolute row)

pub fn verify_poseidon<G: KimchiCurve<ScalarField = F>>( &self, row: usize, witness: &[Vec<F>; 15] ) -> Result<(), String>

Checks if a witness verifies a poseidon gate

Errors

Will give error if self.typ is not Poseidon gate, or state does not match after permutation.

pub fn ps(&self) -> F

pub fn rc(&self) -> [[F; 3]; 5]

round constant that are relevant for this specific gate

impl<F: PrimeField> CircuitGate<F>

pub fn create_multi_range_check(start_row: usize) -> (usize, Vec<Self>)

Create range check gate for constraining three 88-bit values. Inputs the starting row Outputs tuple (next_row, circuit_gates) where next_row - next row after this gate circuit_gates - vector of circuit gates comprising this gate

pub fn create_compact_multi_range_check(start_row: usize) -> (usize, Vec<Self>)

Create range check gate for constraining compact limbs. Inputs the starting row Outputs tuple (next_row, circuit_gates) where next_row - next row after this gate circuit_gates - vector of circuit gates comprising this gate

pub fn extend_multi_range_check(gates: &mut Vec<Self>, curr_row: &mut usize)

Create foreign field muti-range-check gadget by extending the existing gates

pub fn extend_compact_multi_range_check( gates: &mut Vec<Self>, curr_row: &mut usize )

Create foreign field muti-range-check gadget by extending the existing gates

pub fn create_range_check(start_row: usize) -> (usize, Vec<Self>)

Create single range check gate Inputs the starting row Outputs tuple (next_row, circuit_gates) where next_row - next row after this gate circuit_gates - vector of circuit gates comprising this gate

pub fn extend_range_check(gates: &mut Vec<Self>, curr_row: &mut usize)

Create foreign field range-check gate by extending the existing gates

impl<F: PrimeField> CircuitGate<F>

pub fn create_rot64(new_row: usize, rot: u32) -> Vec<Self>

Creates a Rot64 gadget to rotate a word It will need:

• 1 Generic gate to constrain to zero the top 2 limbs of the shifted and excess witness of the rotation

It has:

• 1 Rot64 gate to rotate the word
• 1 RangeCheck0 to constrain the size of the shifted witness of the rotation
• 1 RangeCheck0 to constrain the size of the excess witness of the rotation Assumes:
• the witness word is 64-bits, otherwise, will need to append a new RangeCheck0 for the word

pub fn extend_rot( gates: &mut Vec<Self>, rot: u32, side: RotMode, zero_row: usize ) -> usize

Extend one rotation Right now it only creates a Generic gate followed by the Rot64 gates It allows to configure left or right rotation. Input:

• gates : the full circuit
• rot : the rotation offset
• side : the rotation side
• zero_row : the row of the Generic gate to constrain the 64-bit check of shifted word Warning:
• witness word should come from the copy of another cell so it is intrinsic that it is 64-bits length,
• same with rotated word

pub fn create_rot(new_row: usize, rot: u32, side: RotMode) -> (usize, Vec<Self>)

Create one rotation Right now it only creates a Generic gate followed by the Rot64 gates It allows to configure left or right rotation. Input:

• rot : the rotation offset
• side : the rotation side Warning:
• Word should come from the copy of another cell so it is intrinsic that it is 64-bits length,
• same with rotated word
• need to check that the 2 most significant limbs of shifted are zero

impl<F: PrimeField> CircuitGate<F>

pub fn create_cairo_claim(wires: GateWires) -> Self

This function creates a CairoClaim gate

pub fn create_cairo_instruction(wires: GateWires) -> Self

This function creates a CairoInstruction gate

pub fn create_cairo_flags(wires: GateWires) -> Self

This function creates a CairoFlags gate

pub fn create_cairo_transition(wires: GateWires) -> Self

This function creates a CairoTransition gate

pub fn create_cairo_gadget(row: usize, num: usize) -> (Vec<Self>, usize)

Gadget generator of the whole cairo circuits from an absolute row and number of instructions Returns a vector of gates, and the next available row after the gadget

pub fn verify_cairo_gate<G: KimchiCurve<ScalarField = F>>( &self, row: usize, witness: &[Vec<F>; 15], cs: &ConstraintSystem<F> ) -> Result<(), String>

verifies that the Cairo gate constraints are solved by the witness depending on its type

Errors

Will give error if constraint evaluation is invalid.

Panics

Will panic if constraint linearization fails.

impl<F: PrimeField> CircuitGate<F>

pub fn create_vbmul(wires: &[GateWires; 2]) -> Vec<Self>

pub fn verify_vbmul( &self, _row: usize, _witness: &[Vec<F>; 15] ) -> Result<(), String>

Verify the GateType::VarBaseMul(TODO)

Errors

TODO

pub fn vbmul(&self) -> F

impl<F: PrimeField> CircuitGate<F>

pub fn extend_xor_gadget(gates: &mut Vec<Self>, bits: usize) -> usize

Extends a XOR gadget for bits length to a circuit Includes:

• num_xors Xor16 gates
• 1 Generic gate to constrain the final row to be zero with itself Input:
• gates : vector of circuit gates
• bits : length of the XOR gadget Output:
• new row index

pub fn create_xor_gadget(new_row: usize, bits: usize) -> (usize, Vec<Self>)

Creates a XOR gadget for bits length Includes:

• num_xors Xor16 gates
• 1 Generic gate to constrain the final row to be zero with itself Input:
• new_row : row to start the XOR gadget
• bits : number of bits in the XOR Outputs tuple (next_row, circuit_gates) where
• next_row : next row after this gate
• gates : vector of circuit gates comprising this gate Warning:
• don’t forget to check that the final row is all zeros as in extend_xor_gadget

Trait Implementations

impl<F: Clone + PrimeField> Clone for CircuitGate<F>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F: Debug + PrimeField> Debug for CircuitGate<F>

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

Formats the value using the given formatter.

impl<F: Default + PrimeField> Default for CircuitGate<F>

fn default() -> CircuitGate<F>

Returns the “default value” for a type.

impl<'de, F: PrimeField> Deserialize<'de> for CircuitGate<F>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<F, CamlF> From<&CircuitGate<F>> for CamlCircuitGate<CamlF>where CamlF: From<F>, F: PrimeField,

fn from(cg: &CircuitGate<F>) -> Self

Converts to this type from the input type.

impl<F, CamlF> From<CamlCircuitGate<CamlF>> for CircuitGate<F>where F: From<CamlF> + PrimeField,

fn from(ccg: CamlCircuitGate<CamlF>) -> Self

Converts to this type from the input type.

impl<F, CamlF> From<CircuitGate<F>> for CamlCircuitGate<CamlF>where CamlF: From<F>, F: PrimeField,

fn from(cg: CircuitGate<F>) -> Self

Converts to this type from the input type.

impl<F: PrimeField> Serialize for CircuitGate<F>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>where __S: Serializer,

Serialize this value into the given Serde serializer.