Struct CircuitBuilder 

pub struct CircuitBuilder { /* private fields */ }

Circuit builder for constructing zero-knowledge proof circuits.

CircuitBuilder provides the primary interface for constructing circuits in the Binius64 proof system. The builder compiles imperative gate operations into a constraint system suitable for zero-knowledge proof generation.

Circuit Model

A circuit represents computation as a directed acyclic graph where 64-bit values flow through gates via wires. Gates transform input wires to produce output wires. Methods like band and iadd_32 add gates to the graph and return handles to output wires.

During build, the gate graph compiles into ZERO, AND, IMUL, and BMUL constraints that the proof system operates on directly.

Wire Types

Wires are handles to 64-bit values that exist during proof generation. During circuit construction, wires represent value placeholders.

Constants - Values known at compile time. Zero constraint cost as both prover and verifier know these values. Created with add_constant.

Public inputs/outputs - Values visible to both prover and verifier. Form part of the proof statement (e.g., hash output in a preimage proof). Created with add_inout.

Private witnesses - Values known only to the prover. The circuit proves knowledge of these values without revealing them (e.g., preimage in a hash proof). Created with add_witness.

Internal wires - Created automatically by gate operations. Represent intermediate computation values.

MSB-Boolean Convention

Boolean values encode in the most significant bit (bit 63) of a 64-bit word. MSB = 1 represents true, MSB = 0 represents false. The lower 63 bits are “don’t care” values.

Constraint Costs

AND constraints - Baseline unit of cost. Bitwise operations and comparisons generate 1-2 AND constraints.

IMUL constraints - 64-bit multiplication costs ~3-4× more than AND constraints.

Committed values - Each public input/output and witness adds to proof size (~0.2× of an AND constraint).

Linear operations - XOR and shifts generate virtual linear constraints. During compilation these either:

• Fuse into adjacent non-linear gates (near-zero cost)
• Materialize as ZERO constraints, which the Zero reduction discharges without a prover message

Gate fusion inlines compatible XOR expressions and shifts into existing AND gates. Incompatible operations (e.g., right shift into left shift) and heuristic limits prevent some fusions. XORs typically cost <0.1× of an AND constraint, shifts slightly more.

Compilation

The builder uses reference-counted sharing internally. subcircuit returns a builder referencing the same graph with hierarchical naming.

build triggers compilation:

1. Validates the circuit structure
2. Runs optimization passes (constant propagation, gate fusion)
3. Generates the final constraint system

build consumes internal state and can only be called once per builder instance.

Implementations

impl CircuitBuilder

pub fn new() -> Self

Create a new circuit builder with default options.

pub fn with_opts(opts: Options) -> Self

Create a new circuit builder with the given options.

pub fn add_chip(&self, chip: CircuitM4) -> ChipRef

Registers a chip the built circuit can delegate subrelations to, and returns a reference naming it.

The registered system is flattened into the builder’s own: its main circuit becomes the chip the returned reference names, and the chips it calls follow, with the IDs inside it shifted to their new slots. Each system occupies one contiguous run of IDs and calls only into its own run, so the chips stay in the topological order CircuitM4::validate requires.

The registered system’s active-instance counts are dropped, and the instances its calls name are left stale. They say how often its own main reached each chip, which says nothing about how often this circuit will; Self::build_m4 recounts the whole graph.

Only Self::build_m4 returns the registered chips; Self::build rejects a builder carrying any.

pub fn call_chip(&self, chip: ChipRef, inout: &[Wire])

Calls a registered chip, passing the given wires as the inout words of one invocation.

The chip gains an instance serving this call, and that instance’s inout values are these wires’ words. The chip’s own constraints are what relate them, so this is how a circuit delegates a relation rather than constraining it inline.

A chip does not say which of its inout words are inputs and which are outputs; a call constrains them all alike. The expected shape computes the outputs from the inputs with a hint and passes both: the hint hands the witness its values, and the call is the constraint that makes them correct.

The build treats a call as a constraint on the words it names. Each wire passed takes a committed word of the value vector, and the gate defining it stays live however little else reads it. A call names words rather than expressions, though, so a linear argument such as a ^ b is committed together with the ZERO constraint defining it, where a constraint operand would have fused it in for free.

The wires are matched positionally against the callee’s Circuit::inout, so they are given in that order and there is one per inout word.

Panics

Panics if the wire count differs from the callee’s inout word count.

pub fn register_chip<G: ChipGadget>(&self, gadget: G, dimensions: &[usize])

Makes a gadget a chip of the circuit being built, so that every emission of it is a call.

The chip is the gadget as a system of its own: its inputs declared with Self::add_inout, its gates emitted by ChipGadget::build, and its outputs promoted with Self::mark_inout. Building it here rather than taking one built elsewhere is what holds the chip’s interface and the call sites’ words to the same order.

The chip’s own gates are emitted on a builder of its own, which registers no gadget. So a gadget reaching Self::build_gadget for itself emits its gates inside its chip rather than calling back into it.

The gadget is keyed by its NAME and dimensions: a later Self::build_gadget on the same pair is a call to this chip, and any other emission is gates as before. Registering is the whole of the opt-in, and it reaches every subcircuit, since they build the same circuit.

Registering a gadget the circuit never builds leaves a chip nothing calls, which CircuitM4::validate rejects. So a circuit registers the gadgets it goes on to use.

Panics

Panics if the gadget is already registered for these dimensions, if its build returns a number of outputs other than its shape declares, or if its build declares inout wires of its own, which the interface a call site passes cannot reach.

pub fn build_gadget<G: ChipGadget>( &self, gadget: G, dimensions: &[usize], inputs: &[Wire], ) -> Vec<Wire>

Emits a gadget, as a call to its chip where Self::register_chip has made it one and as its gates otherwise.

A call passes the words the gadget relates rather than computing them, so the outputs come from the gadget’s own Hint: Self::call_hint hands the witness its values, and the call is the constraint that makes them the ones the gadget’s gates would have produced.

Either way the returned wires hold the gadget’s outputs, so a caller reads the same wires whichever way the gadget landed.

Panics

Panics if inputs.len() or the gadget’s output count differs from its shape.

pub fn build(self) -> Circuit

Returns the circuit built by this builder.

Consumes the builder, so building is a one-shot operation. There is no builder left afterward for the type system to reject a second call on.

Panics

Panics if a clone or a subcircuit still holds a live handle to the same shared state. Only sole ownership can be unwrapped out of a reference count.

Panics if the builder carries a chip registered by Self::add_chip. Build that one with Self::build_m4 instead.

Panics if an enabled constant-propagation pass finds an unsatisfiable gate.

pub fn try_build(self) -> Result<Circuit, AlwaysFailingGateError>

Returns the circuit built by this builder. Returns an error instead of panicking on an unsatisfiable constant gate.

Panics

Panics if a clone or a subcircuit still holds a live handle to the same shared state. Only sole ownership can be unwrapped out of a reference count.

Panics if the builder carries a chip registered by Self::add_chip. Build that one with Self::build_m4 instead.

Errors

Returns an error when an enabled constant-propagation pass finds an unsatisfiable gate.

pub fn build_m4(self) -> CircuitM4

Returns the chip-composed circuit built by this builder.

The built circuit is the main one, over the chips registered with Self::add_chip and making the calls emitted by Self::call_chip. Each call’s wires resolve to the value indices the build assigned them, and each chip’s active-instance count is counted off the resulting call graph.

Consumes the builder, so building is a one-shot operation. There is no builder left afterward for the type system to reject a second call on.

Panics

Panics if a clone or a subcircuit still holds a live handle to the same shared state. Only sole ownership can be unwrapped out of a reference count.

Panics if an enabled constant-propagation pass finds an unsatisfiable gate.

pub fn try_build_m4(self) -> Result<CircuitM4, AlwaysFailingGateError>

Returns the chip-composed circuit built by this builder. Returns an error instead of panicking on an unsatisfiable constant gate.

Panics

Panics if a clone or a subcircuit still holds a live handle to the same shared state. Only sole ownership can be unwrapped out of a reference count.

Errors

Returns an error when an enabled constant-propagation pass finds an unsatisfiable gate.

pub fn subcircuit(&self, name: impl AsRef<str>) -> CircuitBuilder

Creates a reference to the same underlying circuit builder that is namespaced to the given name.

This is useful for creating subcircuits within a larger circuit.

Note that this is the same builder instance, but with a different namespace, and that means calling Self::build on the returned builder is going to build the whole circuit.

pub fn force_commit(&self, wire: Wire)

Force commit the given wire.

This annotate the wire to be forcefully committed. This instructs optimization passes (ATOW only gate fusion) to forcibly materialize wire.

pub fn mark_inout(&self, wire: Wire)

Promotes a gate-created wire to a public output.

The wire moves from the private segment to the inout one, joining the circuit’s public interface. This is what a circuit exposing a gadget’s result wants: declaring a separate inout wire and asserting the result against it costs a second committed word and a constraint whenever the result is a wire that has to be committed anyway.

The value is still derived by the gate producing it, so a witness filler must not assign it — unlike a wire from Self::add_inout, which the filler is required to set.

Promoting also pins the wire, so this subsumes Self::force_commit rather than needing it alongside.

Position in the segment

The inout segment is ordered by wire creation, so a promoted wire follows the declared inout wires and sits among its fellow promotions in the order their gates created them — which is not necessarily the order they are promoted in. That is invisible to a caller filling by Wire, but a caller building the positional public-input vector a verifier takes should read each index back with Circuit::witness_index rather than assume promotion order.

Panics

Panics unless the wire is a gate-created internal wire. A constant, an input, or an already-public wire has nothing to promote.

pub fn add_constant(&self, word: Word) -> Wire

Creates a wire from a 64-bit word.

Arguments

• word - The word to add to the circuit.

Returns

A Wire representing the constant value. The wire might be aliased because the constants are deduplicated.

Cost

Constants have no constraint cost - they are “free” in the circuit.

pub fn add_constant_64(&self, c: u64) -> Wire

Creates a constant wire from a 64-bit unsigned integer.

This method adds a 64-bit constant value to the circuit. The constant is stored as a Word and can be used in constraints and operations.

Constants are automatically deduplicated - multiple calls with the same value will return the same wire.

Arguments

• c - The 64-bit constant value to add to the circuit

Returns

A Wire representing the constant value that can be used in circuit operations

pub fn add_constant_zx_8(&self, c: u8) -> Wire

Creates a constant wire from an 8-bit value, zero-extended to 64 bits.

This method takes an 8-bit unsigned integer (byte) and zero-extends it to a 64-bit value before adding it as a constant to the circuit. The resulting wire contains the byte value in the lower 8 bits and zeros in the upper 56 bits. This is commonly used for byte constants in circuits that process byte data.

Arguments

• c - The 8-bit constant value (0-255) to add to the circuit

pub fn add_inout(&self) -> Wire

Creates a public input/output wire.

Public wires form part of the proof statement and are visible to both prover and verifier. They are committed in the public section of the value vector alongside constants.

The wire must be manually assigned a value using WitnessFiller before circuit evaluation.

pub fn add_witness(&self) -> Wire

Creates a private input wire.

Private wires contain secret values known only to the prover. They are placed in the private section of the value vector and are not revealed to the verifier.

The wire must be manually assigned a value using WitnessFiller before circuit evaluation.

pub fn band(&self, x: Wire, y: Wire) -> Wire

Bitwise AND.

Returns z = x & y

Cost

1 AND constraint, or none when an algebraic identity resolves it.

pub fn bxor(&self, a: Wire, b: Wire) -> Wire

Bitwise XOR.

Returns z = x ^ y

Cost

1 linear constraint, or none when an algebraic identity resolves it.

pub fn bxor_multi(&self, wires: &[Wire]) -> Wire

Multi-way bitwise XOR operation.

Takes a variable-length slice of wires and XORs them all together.

Returns z = i ^ j ^ k ^ …

Cost

1 linear constraint.

pub fn bnot(&self, a: Wire) -> Wire

Bitwise Not

Returns z = ~x

Cost

1 linear constraint.

pub fn bor(&self, a: Wire, b: Wire) -> Wire

Bitwise OR.

Returns z = x | y

Cost

1 AND constraint, or none when an algebraic identity resolves it.

pub fn fax(&self, x: Wire, y: Wire, w: Wire) -> Wire

Fused AND-XOR operation.

Computes (x & y) ^ w in a single gate.

Returns z = (x & y) ^ w

Cost

1 AND constraint.

pub fn iadd_32(&self, a: Wire, b: Wire) -> Wire

Parallel 32-bit integer addition.

Performs simultaneous independent 32-bit additions on the upper and lower halves, discarding the carry-out.

Cost

1 AND constraint, 1 linear constraint.

pub fn iadd32_cin_cout(&self, a: Wire, b: Wire, cin: Wire) -> (Wire, Wire)

Parallel 32-bit integer addition with carry-in and carry-out.

Performs simultaneous independent 32-bit additions on the upper and lower halves of the 64-bit word, with per-half carry-in and carry-out.

The carry-in for each half is taken from the MSB of that half in cin: bit 31 for the lower half, bit 63 for the upper half. The carry-out is a full carry word where bit 31 and bit 63 indicate the carry-out of the lower and upper halves respectively.

Cost

1 AND constraint, 1 linear constraint.

pub fn iadd_cin_cout(&self, a: Wire, b: Wire, cin: Wire) -> (Wire, Wire)

64-bit integer addition with carry input and output.

Performs full 64-bit unsigned addition of two wires plus a carry input.

Returns (sum, carry_out) where:

• sum is the 64-bit result and
• carry_out is a 64-bit word where every bit position with a carry is set to 1.

Cost

• 1 AND constraint,
• 1 linear constraint.

pub fn isub_bin_bout(&self, a: Wire, b: Wire, bin: Wire) -> (Wire, Wire)

64-bit subtraction with borrow input and output.

Performs full 64-bit unsigned subtraction of two wires plus a borrow input.

Returns (diff, borrow_out) where:

• diff is the 64-bit result and
• borrow_out is a 64-bit word where every bit position with a borrow is set to 1.

Cost

• 1 AND constraint,
• 1 linear constraint.

pub fn rotl32(&self, x: Wire, n: u32) -> Wire

32-bit half-wise rotate left.

Rotates the upper and lower 32-bit halves left independently by n. Bits do not cross the 32-bit lane boundary.

Returns x ROTL32 n

Panics

Panics if n ≥ 32.

Cost

1 AND constraint (0 if n = 0).

pub fn rotr32(&self, x: Wire, n: u32) -> Wire

32-bit half-wise rotate right.

Rotates the upper and lower 32-bit halves right independently by n. Bits do not cross the 32-bit lane boundary.

Returns x ROTR32 n

Panics

Panics if n ≥ 32.

Cost

1 AND constraint (0 if n = 0).

pub fn rotl(&self, x: Wire, n: u32) -> Wire

64-bit rotate left.

Rotates a 64-bit value left by n positions. Bits shifted out on the left wrap around to the right.

Returns x rotated left by n

Panics

Panics if n ≥ 64.

Cost

1 AND constraint (0 if n = 0).

pub fn rotr(&self, x: Wire, n: u32) -> Wire

64-bit rotate right.

Rotates a 64-bit value right by n positions. Bits shifted out on the right wrap around to the left.

Returns x rotated right by n

Panics

Panics if n ≥ 64.

Cost

1 AND constraint (0 if n = 0).

pub fn srl32(&self, x: Wire, n: u32) -> Wire

32-bit half-wise logical right shift.

Shifts the upper and lower 32-bit halves right independently by n. Bits do not cross the 32-bit lane boundary.

Returns x SRL32 n

Panics

Panics if n ≥ 32.

Cost

1 AND constraint (0 if n = 0).

pub fn sll32(&self, x: Wire, n: u32) -> Wire

32-bit half-wise logical left shift.

Shifts the upper and lower 32-bit halves left independently by n. Bits do not cross the 32-bit lane boundary.

Returns x SLL32 n.

Panics

Panics if n ≥ 32.

Cost

1 AND constraint (0 if n = 0).

pub fn shl(&self, a: Wire, n: u32) -> Wire

Logical left shift.

Shifts a 64-bit wire left by n bits, filling with zeros from the right.

Returns a << n

Cost

1 AND constraint (0 if n = 0).

pub fn shr(&self, a: Wire, n: u32) -> Wire

Logical right shift.

Shifts a 64-bit wire right by n bits, filling with zeros from the left.

Returns a >> n

Cost

1 AND constraint (0 if n = 0).

pub fn sar(&self, a: Wire, n: u32) -> Wire

Arithmetic right shift.

Shifts a 64-bit wire right by n bits, filling with the MSB from the left.

Returns a SAR n

Cost

1 AND constraint (0 if n = 0).

pub fn sra32(&self, a: Wire, n: u32) -> Wire

32-bit half-wise arithmetic right shift.

Shifts the upper and lower 32-bit halves right independently by n, sign-extending each half from its own bit 31.

Returns x SRA32 n.

Panics

Panics if n ≥ 32.

Cost

1 AND constraint (0 if n = 0).

pub fn assert_eq(&self, name: impl AsRef<str>, x: Wire, y: Wire)

Equality assertion.

Asserts that two 64-bit wires are equal.

Takes wires x and y and enforces x == y. If the assertion fails, the circuit will report an error with the given name.

Cost

1 AND constraint.

pub fn assert_eq_v<const N: usize>( &self, name: impl AsRef<str>, x: [Wire; N], y: [Wire; N], )

Vector equality assertion.

Asserts that two arrays of 64-bit wires are equal element-wise.

Takes wire arrays x and y and enforces x[i] == y[i] for all i. Each element assertion is named with the base name and index.

Cost

N AND constraints (one per element).

pub fn assert_zero(&self, name: impl AsRef<str>, x: Wire)

Asserts that the given wire equals zero.

Enforces that x = 0 exactly. Every bit of the 64-bit value must be zero.

Cost

1 AND constraint.

pub fn assert_non_zero(&self, name: impl AsRef<str>, x: Wire)

Asserts that the given wire is not zero.

Enforces that x ≠ 0. At least one bit must be non-zero.

Cost

1 AND constraint.

pub fn assert_false(&self, name: impl AsRef<str>, x: Wire)

Asserts that the given wire’s MSB (Most Significant Bit) is 0.

This treats the wire as an MSB-boolean where:

• MSB = 0 → false (assertion passes)
• MSB = 1 → true (assertion fails)

All bits except the MSB are ignored. This is commonly used with comparison results which return MSB-boolean values.

Cost

1 AND constraint.

pub fn assert_true(&self, name: impl AsRef<str>, x: Wire)

Asserts that the given wire’s MSB (Most Significant Bit) is 1.

This treats the wire as an MSB-boolean where:

• MSB = 1 → true (assertion passes)
• MSB = 0 → false (assertion fails)

All bits except the MSB are ignored. This is commonly used with comparison results which return MSB-boolean values.

Cost

1 AND constraint.

pub fn imul(&self, a: Wire, b: Wire) -> (Wire, Wire)

64-bit × 64-bit → 128-bit unsigned multiplication.

Performs unsigned integer multiplication of two 64-bit values, producing a 128-bit result split into high and low 64-bit words.

Returns (hi, lo) where a * b = (hi << 64) | lo

Cost

1 IMUL constraint.

pub fn bmul( &self, a_lo: Wire, a_hi: Wire, b_lo: Wire, b_hi: Wire, ) -> (Wire, Wire)

Multiplication in the GHASH field GF(2^128).

Multiplies two field elements, each carried by a (lo, hi) pair of 64-bit words — lo holds the coefficients of 1, X, …, X^63 and hi those of X^64, …, X^127.

Returns (c_lo, c_hi), the product (a_lo, a_hi) * (b_lo, b_hi) in the same representation.

Cost

• 1 BMUL constraint.

pub fn assert_eq_cond( &self, name: impl AsRef<str>, x: Wire, y: Wire, cond: Wire, )

Conditional equality assertion.

Asserts that two 64-bit wires are equal only when a condition is true (MSB = 1). When the condition is false (MSB = 0), no constraint is enforced.

Cost

1 AND constraint.

pub fn icmp_ult(&self, x: Wire, y: Wire) -> Wire

Unsigned less-than comparison.

Compares two 64-bit wires as unsigned integers.

Returns:

• a wire whose MSB-bool value is true if a < b
• a wire whose MSB-bool value is false if a ≥ b

the non-most-significant bits of the output wire are undefined.

Cost

• 1 AND constraint,
• 1 linear constraint.

pub fn icmp_ule(&self, x: Wire, y: Wire) -> Wire

Unsigned less-than-or-equal comparison.

Compares two 64-bit wires as unsigned integers.

Returns:

• a wire whose MSB-bool value is true if x <= y
• a wire whose MSB-bool value is false if x > y

the non-most-significant bits of the output wire are undefined.

Cost

• 1 AND constraint,
• 1 linear constraint.

pub fn icmp_ugt(&self, x: Wire, y: Wire) -> Wire

Unsigned greater-than comparison.

Compares two 64-bit wires as unsigned integers.

Returns:

• a wire whose MSB-bool value is true if x > y
• a wire whose MSB-bool value is false if x <= y

the non-most-significant bits of the output wire are undefined.

Cost

1 AND constraint.

pub fn icmp_uge(&self, x: Wire, y: Wire) -> Wire

Unsigned greater-than-or-equal comparison.

Compares two 64-bit wires as unsigned integers.

Returns:

• a wire whose MSB-bool value is true if x >= y
• a wire whose MSB-bool value is false if x < y

the non-most-significant bits of the output wire are undefined.

Cost

• 1 AND constraint,
• 1 linear constraint.

pub fn icmp_eq(&self, x: Wire, y: Wire) -> Wire

Equality comparison.

Compares two 64-bit wires for equality.

Returns:

• a wire whose MSB-bool value is true if a == b
• a wire whose MSB-bool value is false if a != b

the non-most-significant bits of the output wire are undefined.

Cost

1 AND constraint.

pub fn icmp_ne(&self, x: Wire, y: Wire) -> Wire

Inequality comparison.

Compares two 64-bit wires for inequality.

Returns:

• a wire whose MSB-bool value is true if a != b
• a wire whose MSB-bool value is false if a == b

the non-most-significant bits of the output wire are undefined.

Cost

• 1 AND constraint,
• 1 linear constraint.

pub fn extract_byte(&self, word: Wire, j: u32) -> Wire

Byte extraction.

Extracts byte j from a 64-bit word (j=0 is least significant byte).

Returns the extracted byte (0-255) in the low 8 bits, with high 56 bits zero.

Panics

Panics if j is greater than or equal to 8.

Cost

• 1 AND constraint,
• 1 linear constraint.

pub fn select(&self, cond: Wire, t: Wire, f: Wire) -> Wire

Select operation.

Returns t if cond is true (MSB-bit set), otherwise returns f.

Cost

1 BMUL constraint, or none when an algebraic identity resolves it.

pub fn call_hint<T: Hint>( &self, hint: T, dimensions: &[usize], inputs: &[Wire], ) -> Vec<Wire>

Invoke a Hint and emit the corresponding gate.

Registers hint in the builder’s hint registry (keyed by T::NAME), allocates output wires according to hint.shape(dimensions), and emits a generic hint gate. Returns the freshly allocated output wires.

dimensions is passed verbatim to Hint::shape and Hint::execute; it is the hint’s parameterization (e.g., limb counts for a bignum hint).

The registry keys on the name alone. Only the first value passed under a name survives; a later value’s fields are ignored. Per-call parameters belong in dimensions, not in the hint’s fields.

Panics

Panics if the declared arity or a dimension exceeds what the witness bytecode encodes.

Panics if inputs.len() does not match the hint’s declared input arity. Panics if another hint name already holds this hint’s id.

pub fn iadd(&self, a: Wire, b: Wire) -> (Wire, Wire)

64-bit unsigned integer addition, returning the sum and carry-out.

Addition with a carry-in is the general primitive. Plain addition is the special case where the carry-in is zero.

Returns (sum, cout) where:

• sum is the 64-bit result a + b.
• cout has a set bit at every position where a carry occurred.

Cost

• 1 AND constraint,
• 1 linear constraint.

pub fn smul(&self, a: Wire, b: Wire) -> (Wire, Wire)

64-bit × 64-bit → 128-bit signed multiplication.

Handles two’s complement operands, including overflow cases.

Returns (hi, lo) where the signed product equals (hi << 64) | lo.

The high word is the sign extension of the product.

Trait Implementations

impl Clone for CircuitBuilder

fn clone(&self) -> CircuitBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for CircuitBuilder

fn default() -> Self

Returns the “default value” for a type.