Struct plonk_pallet::TurboComposer

pub struct TurboComposer { /* fields omitted */ }

The TurboComposer is the circuit-builder tool that the dusk-plonk repository provides so that circuit descriptions can be written, stored and transformed into a Proof at some point.

A TurboComposer stores all of the circuit information, being this one all of the witness and circuit descriptors info (values, positions in the circuits, gates and Wires that occupy..), the public inputs, the connection relationships between the witnesses and how they’re repesented as Wires (so basically the Permutation argument etc..).

The TurboComposer also grants us a way to introduce our secret witnesses in a for of a Witness into the circuit description as well as the public inputs. We can do this with methods like TurboComposer::append_witness.

The TurboComposer also contains as associated functions all the neccessary tools to be able to istrument the circuits that the user needs through the addition of gates. There are functions that may add a single gate to the circuit as for example TurboComposer::gate_add and others that can add several gates to the circuit description such as TurboComposer::component_select.

Each gate or group of gates adds an specific functionallity or operation to de circuit description, and so, that’s why we can understand the TurboComposer as a builder.

Implementations

impl TurboComposer

pub const fn constant_zero() -> Witness

Returns a Witness representation of zero.

Every TurboComposer is initialized with a circuit description containing a representation of zero. This function will return the index of that representation.

pub const fn gates(&self) -> u32

Return the number of gates in the circuit

pub unsafe fn evaluate_witness(&self, witness: &Witness) -> &Scalar

Evaluate the runtime value of a witness

Safety

Witness evaluation inside a gadget isn’t expected and could produce an unsound circuit (different circuit representation for the same code).

Calling this function performs operations outside the circuit.

pub fn public_input_indexes(&self) -> Vec<u32, Global>

Returns the positions that the Public Inputs occupy in this Composer instance.

impl TurboComposer

pub fn append_constant(&mut self, value: Scalar) -> Witness

Constrain a scalar into the circuit description and return an allocated Witness with its value

pub fn append_witness<T>(&mut self, scalar: T) -> Witness where
    T: Into<Scalar>, 

Allocate a witness value into the composer and return its index.

pub fn append_gate(&mut self, s: Constraint)

Adds a width-4 poly gate.

The final constraint added will enforce the following: q_m · a · b + q_l · a + q_r · b + q_o · o + q_4 · d + q_c + PI = 0.

pub fn assert_equal_constant(
    &mut self,
    a: Witness,
    constant: Scalar,
    pi: Option<Scalar>
)

Constrain a to be equal to constant + pi.

constant will be defined as part of the public circuit description.

pub fn assert_equal(&mut self, a: Witness, b: Witness)

Asserts a == b by appending a gate

pub fn component_select(
    &mut self,
    bit: Witness,
    a: Witness,
    b: Witness
) -> Witness

Conditionally selects a Witness based on an input bit.

bit == 1 => a, bit == 0 => b,

bit is expected to be constrained by TurboComposer::component_boolean

pub fn component_select_zero(&mut self, bit: Witness, value: Witness) -> Witness

Conditionally selects a Witness based on an input bit.

bit == 1 => value, bit == 0 => 0,

bit is expected to be constrained by TurboComposer::component_boolean

pub fn component_select_one(&mut self, bit: Witness, value: Witness) -> Witness

Conditionally selects a Witness based on an input bit.

bit == 1 => value, bit == 0 => 1,

bit is expected to be constrained by TurboComposer::component_boolean

pub fn component_decomposition<const N: usize>(
    &mut self,
    scalar: Witness
) -> [Witness; N]

Decomposes scalar into an array truncated to N bits (max 256).

Asserts the reconstruction of the bits to be equal to scalar.

Consume 2 · N + 1 gates

pub fn append_dummy_gates(&mut self)

This function is used to add a blinding factor to the witness polynomials. It essentially adds two dummy gates to the circuit description which are guaranteed to always satisfy the gate equation.

pub fn append_plonkup_gate(
    &mut self,
    a: Witness,
    b: Witness,
    c: Witness,
    d: Witness,
    pi: Option<Scalar>
) -> Witness

Adds a plonkup gate to the circuit with its corresponding gates.

This type of gate is usually used when we need to have the largest amount of performance and the minimum circuit-size possible. Since it allows the end-user to set every selector coefficient as scaling value on the gate eq.

pub fn append_plonkup_table(&mut self, table: &LookupTable)

When TurboComposer is initialised, it spawns a dummy table with 3 entries that should not be removed. This function appends its input table to the composer’s dummy table

impl TurboComposer

pub fn component_add_point(
    &mut self,
    a: WitnessPoint,
    b: WitnessPoint
) -> WitnessPoint

Adds two curve points by consuming 2 gates.

impl TurboComposer

pub fn component_mul_generator<P>(
    &mut self,
    jubjub: Witness,
    generator: P
) -> WitnessPoint where
    P: Into<JubJubExtended>, 

Evaluate jubjub · Generator as a WitnessPoint

generator will be appended to the circuit description as constant

impl TurboComposer

pub fn component_mul_point(
    &mut self,
    jubjub: Witness,
    point: WitnessPoint
) -> WitnessPoint

Evaluate jubjub · point as a WitnessPoint

impl TurboComposer

pub fn append_point<P>(&mut self, affine: P) -> WitnessPoint where
    P: Into<JubJubAffine>, 

Appends a point in affine form as WitnessPoint

pub fn append_public_point<P>(&mut self, affine: P) -> WitnessPoint where
    P: Into<JubJubAffine>, 

Appends a point in affine form as WitnessPoint

Creates two public inputs as (x, y)

pub fn append_constant_point<P>(&mut self, affine: P) -> WitnessPoint where
    P: Into<JubJubAffine>, 

Constrain a point into the circuit description and return an allocated WitnessPoint with its coordinates

pub fn append_constant_identity(&mut self) -> WitnessPoint

Create an identity WitnessPoint constrained by the circuit description

pub fn assert_equal_public_point<P>(&mut self, point: WitnessPoint, public: P) where
    P: Into<JubJubAffine>, 

Asserts point == public.

Will add public affine coordinates (x,y) as public inputs

pub fn assert_equal_point(&mut self, a: WitnessPoint, b: WitnessPoint)

Asserts a == b by appending two gates

pub fn component_select_point(
    &mut self,
    a: WitnessPoint,
    b: WitnessPoint,
    bit: Witness
) -> WitnessPoint

Conditionally selects a WitnessPoint based on an input bit.

bit == 1 => a, bit == 0 => b,

bit is expected to be constrained by TurboComposer::component_boolean

pub fn component_select_identity(
    &mut self,
    bit: Witness,
    a: WitnessPoint
) -> WitnessPoint

Conditionally selects identity as WitnessPoint based on an input bit.

bit == 1 => a, bit == 0 => identity,

bit is expected to be constrained by TurboComposer::component_boolean

impl TurboComposer

pub fn component_xor(
    &mut self,
    a: Witness,
    b: Witness,
    num_bits: usize
) -> Witness

Adds a logical XOR gate that performs the XOR between two values for the specified first num_bits returning a Witness holding the result.

Panics

If the num_bits specified in the fn params is odd.

pub fn component_and(
    &mut self,
    a: Witness,
    b: Witness,
    num_bits: usize
) -> Witness

Adds a logical AND gate that performs the bitwise AND between two values for the specified first num_bits returning a Witness holding the result.

Panics

If the num_bits specified in the fn params is odd.

impl TurboComposer

pub fn component_range(&mut self, witness: Witness, num_bits: usize)

Adds a range-constraint gate that checks and constrains a Witness to be inside of the range [0,num_bits].

This function adds num_bits/4 gates to the circuit description in order to add the range constraint.

Panics

This function will panic if the num_bits specified is not even, ie. num_bits % 2 != 0.

impl TurboComposer

pub fn gate_add(&mut self, s: Constraint) -> Witness

Evaluate and return o by appending a new constraint into the circuit.

The output of the constraint will be overwritten with o := q_l · a + q_r · b + q_4 · d + q_c + PI

pub fn gate_mul(&mut self, s: Constraint) -> Witness

Evaluate and return o by appending a new constraint into the circuit.

The output of the constraint will be overwritten with o := q_m · a · b + q_4 · d + q_c + PI

impl TurboComposer

pub fn component_boolean(&mut self, a: Witness)

Adds a boolean constraint (also known as binary constraint) where the gate eq. will enforce that the Witness received is either 0 or 1 by adding a constraint in the circuit.

Note that using this constraint with whatever Witness that is not representing a value equalling 0 or 1, will always force the equation to fail.

Trait Implementations

impl Debug for TurboComposer

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

Formats the value using the given formatter.

impl Default for TurboComposer

pub fn default() -> TurboComposer

Returns the “default value” for a type.