Struct BaseCircuitBuilder

pub struct BaseCircuitBuilder<F: ScalarField> {
    pub config_params: BaseCircuitParams,
    pub assigned_instances: Vec<Vec<AssignedValue<F>>>,
    /* private fields */
}

A circuit builder is a collection of virtual region managers that together assign virtual regions into a single physical circuit.

BaseCircuitBuilder is a circuit builder to create a circuit where the columns correspond to super::BaseConfig. This builder can hold multiple threads, but the Circuit implementation only evaluates the first phase. The user will have to implement a separate Circuit with multi-phase witness generation logic.

This is used to manage the virtual region corresponding to super::FlexGateConfig and (optionally) RangeConfig. This can be used even if only using GateChip without RangeChip.

The circuit will have NI public instance (aka public inputs+outputs) columns.

Fields

config_params: BaseCircuitParams

Configuration parameters for the circuit shape

assigned_instances: Vec<Vec<AssignedValue<F>>>

The assigned instances to expose publicly at the end of circuit synthesis

Implementations

impl<F: ScalarField> BaseCircuitBuilder<F>

pub fn core(&self) -> &MultiPhaseCoreManager<F>

Virtual region for each challenge phase. These cannot be shared across threads while keeping circuit deterministic.

pub fn lookup_manager(&self) -> &[LookupAnyManager<F, 1>; 3]

The range lookup manager

impl<F: ScalarField> BaseCircuitBuilder<F>

pub fn core_mut(&mut self) -> &mut MultiPhaseCoreManager<F>

Virtual region for each challenge phase. These cannot be shared across threads while keeping circuit deterministic.

pub fn lookup_manager_mut(&mut self) -> &mut [LookupAnyManager<F, 1>; 3]

The range lookup manager

impl<F: ScalarField> BaseCircuitBuilder<F>

pub fn set_core(&mut self, val: MultiPhaseCoreManager<F>) -> &mut Self

Virtual region for each challenge phase. These cannot be shared across threads while keeping circuit deterministic.

pub fn set_lookup_manager( &mut self, val: [LookupAnyManager<F, 1>; 3], ) -> &mut Self

The range lookup manager

impl<F: ScalarField> BaseCircuitBuilder<F>

pub fn new(witness_gen_only: bool) -> Self

Creates a new BaseCircuitBuilder with all default managers.

• witness_gen_only:
  • If true, the builder only does witness asignments and does not store constraint information – this should only be used for the real prover.
  • If false, the builder also imposes constraints (selectors, fixed columns, copy constraints). Primarily used for keygen and mock prover (but can also be used for real prover).

By default, no circuit configuration parameters have been set. These should be set separately using use_params, or use_k, use_lookup_bits, and calculate_params.

Upon construction, there are no public instances (aka all witnesses are private). The intended usage is that before calling synthesize, witness generation can be done to populate assigned instances, which are supplied as assigned_instances to this struct. The Circuit implementation for this struct will then expose these instances and constrain them using the Halo2 API.

pub fn from_stage(stage: CircuitBuilderStage) -> Self

Creates a new MultiPhaseCoreManager depending on the stage of circuit building. If the stage is CircuitBuilderStage::Prover, the MultiPhaseCoreManager is used for witness generation only.

pub fn prover( config_params: BaseCircuitParams, break_points: MultiPhaseThreadBreakPoints, ) -> Self

Creates a new BaseCircuitBuilder with a pinned circuit configuration given by config_params and break_points.

pub fn set_copy_manager(&mut self, copy_manager: SharedCopyConstraintManager<F>)

Sets the copy manager to the given one in all shared references.

pub fn use_copy_manager( self, copy_manager: SharedCopyConstraintManager<F>, ) -> Self

Returns self with a given copy manager

pub fn deep_clone(&self) -> Self

Deep clone of self, where the underlying object of shared references in SharedCopyConstraintManager and LookupAnyManager are cloned.

pub fn lookup_bits(&self) -> Option<usize>

The log_2 size of the lookup table, if using.

pub fn set_lookup_bits(&mut self, lookup_bits: usize)

Set lookup bits

pub fn use_lookup_bits(self, lookup_bits: usize) -> Self

Returns new with lookup bits

pub fn set_k(&mut self, k: usize)

Sets new k = log2 of domain

pub fn use_k(self, k: usize) -> Self

Returns new with k set

pub fn set_instance_columns(&mut self, num_instance_columns: usize)

Set the number of instance columns. This resizes self.assigned_instances.

pub fn use_instance_columns(self, num_instance_columns: usize) -> Self

Returns new with self.assigned_instances resized to specified number of instance columns.

pub fn set_params(&mut self, params: BaseCircuitParams)

Set config params

pub fn use_params(self, params: BaseCircuitParams) -> Self

Returns new with config params

pub fn break_points(&self) -> MultiPhaseThreadBreakPoints

The break points of the circuit.

pub fn set_break_points(&mut self, break_points: MultiPhaseThreadBreakPoints)

Sets the break points of the circuit.

pub fn use_break_points(self, break_points: MultiPhaseThreadBreakPoints) -> Self

Returns new with break points

pub fn witness_gen_only(&self) -> bool

Returns if the circuit is only used for witness generation.

pub fn unknown(self, use_unknown: bool) -> Self

Creates a new MultiPhaseCoreManager with use_unknown flag set.

• use_unknown: If true, during key generation witness Values are replaced with Value::unknown() for safety.

pub fn clear(&mut self)

Clears state and copies, effectively resetting the circuit builder.

pub fn main(&mut self, phase: usize) -> &mut Context<F>

Returns a mutable reference to the Context of a gate thread. Spawns a new thread for the given phase, if none exists.

• phase: The challenge phase (as an index) of the gate thread.

pub fn pool(&mut self, phase: usize) -> &mut SinglePhaseCoreManager<F>

Returns SinglePhaseCoreManager with the virtual region with all core threads in the given phase.

pub fn new_thread(&mut self, phase: usize) -> &mut Context<F>

Spawns a new thread for a new given phase. Returns a mutable reference to the Context of the new thread.

• phase: The phase (index) of the gate thread.

pub fn statistics(&self) -> RangeStatistics

Returns some statistics about the virtual region.

pub fn calculate_params( &mut self, minimum_rows: Option<usize>, ) -> BaseCircuitParams

Auto-calculates configuration parameters for the circuit and sets them.

• k: The number of in the circuit (i.e. numeber of rows = 2^k)
• minimum_rows: The minimum number of rows in the circuit that cannot be used for witness assignments and contain random blinding factors to ensure zk property, defaults to 0.
• lookup_bits: The fixed lookup table will consist of [0, 2^lookup_bits)

pub fn assign_instances( &self, instance_columns: &[Column<Instance>], layouter: impl Layouter<F>, )

Copies assigned_instances to the instance columns. Should only be called at the very end of synthesize after virtual assigned_instances have been assigned to physical circuit.

pub fn range_chip(&self) -> RangeChip<F>

Creates a new RangeChip sharing the same LookupAnyManagers as self.

pub fn assign_lookups_in_phase( &self, config: &RangeConfig<F>, region: &mut Region<'_, F>, phase: usize, )

Copies the queued cells to be range looked up in phase phase to special advice lookup columns using LookupAnyManager.

Special case

Just for RangeConfig, we have special handling for the case where there is a single (physical) advice column in super::FlexGateConfig. In this case, RangeConfig does not create extra lookup advice columns, the single advice column has lookup enabled, and there is a selector to toggle when lookup should be turned on.

Trait Implementations

impl<F: ScalarField> AsMut<BaseCircuitBuilder<F>> for BaseCircuitBuilder<F>

fn as_mut(&mut self) -> &mut BaseCircuitBuilder<F>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<F: ScalarField> AsRef<BaseCircuitBuilder<F>> for BaseCircuitBuilder<F>

fn as_ref(&self) -> &BaseCircuitBuilder<F>

Converts this type into a shared reference of the (usually inferred) input type.

impl<F: ScalarField> Circuit<F> for BaseCircuitBuilder<F>

fn without_witnesses(&self) -> Self

Creates a new instance of the BaseCircuitBuilder without witnesses by setting the witness_gen_only flag to false

fn configure_with_params( meta: &mut ConstraintSystem<F>, params: Self::Params, ) -> Self::Config

Configures a new circuit using BaseCircuitParams

fn synthesize( &self, config: Self::Config, layouter: impl Layouter<F>, ) -> Result<(), Error>

Performs the actual computation on the circuit (e.g., witness generation), populating the lookup table and filling in all the advice values for a particular proof.

type Config = BaseConfig<F>

This is a configuration object that stores things like columns.

type FloorPlanner = SimpleFloorPlanner

The floor planner used for this circuit. This is an associated type of the Circuit trait because its behaviour is circuit-critical.

type Params = BaseCircuitParams

Optional circuit configuration parameters. Requires the circuit-params feature.

fn params(&self) -> Self::Params

Returns a reference to the parameters that should be used to configure the circuit. Requires the circuit-params feature.

fn configure(_: &mut ConstraintSystem<F>) -> Self::Config

The circuit is given an opportunity to describe the exact gate arrangement, column arrangement, etc.

impl<F: Clone + ScalarField> Clone for BaseCircuitBuilder<F>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F: Debug + ScalarField> Debug for BaseCircuitBuilder<F>

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

Formats the value using the given formatter.

impl<F: ScalarField> Default for BaseCircuitBuilder<F>

fn default() -> Self

Quick start default circuit builder which can be used for MockProver, Keygen, and real prover. For best performance during real proof generation, we recommend using BaseCircuitBuilder::prover instead.