Separate circuit generation and garb/eval tooling

[Zk2u]

Circuit generation should likely be the main crate and shared code from this crate. The existing code does a relatively good job at separating this via traits and modules but it should isolate circuit generation code into its own crate.

Existing garb/eval tooling in the modules can be moved to a smaller subcrate or a separate repo

[cyphersnake]

It's good that you started this issue, because in my head, the relationship is exactly the opposite.

There is a framework that implements the base - CircuitContext and CircuitMode. These two traits are the base trait. The first one is the interface for gadgets. The second is the interface for handlers of these gadgets.

There is also tooling, in fact the implementation of specific CircuitMode: Execute, Garble, Evaluate, as well as Streaming as a wrapper over these three.

There are gadgets, i.e., representations of arithmetization. They are not agnostic to the framework, they use at least CirctuiContext. They need a basic interface to represent the logic.

---

Therefore, gadgets are a derivative of the framework. The basic separation is the separation of the protocol implementation and the derived crate with gadgets.

An alternative division is to put the tooling (specific modes of operation) into a 4 crate. Then we'd have:

• core - root types, root traits.
• halfgarbling - current implementations of GarbleMode, EvaluateMode, hashing etc.
• groth16_gadgets - gadgets that import core but not halfgarbling.
• garbled_groth16 - which imports both gadgets and halfgarbling and pub API

Not that I'm against it, but it's no longer a free complication, it's 4 crates instead of one. Overall as a plus - build time for external crates using only gadgets. But this approach doesn't open up any scenario that wasn't available before.

Now you can also use gadgets by implementing one crate - CircuitContext - and reimplementing it for any other framework, handling the topology however you want. We can also discuss its design if there's something you're missing.

What do you think?

[cyphersnake]

pub trait CircuitContext: Sized {
    type Mode: CircuitMode;

    /// Allocates a new wire and returns its identifier
    fn issue_wire(&mut self) -> WireId;

    /// Adds a gate to the current component
    fn add_gate(&mut self, gate: Gate);

    fn with_named_child<I: WiresObject, O: FromWires>(
        &mut self,
        key: ComponentKey,
        inputs: I,
        f: impl Fn(&mut Self, &I) -> O,
        arity: usize,
    ) -> O;
}

What concerns the child is a logical division into subgadgets. It can be ignored outwardly if you don't need it. You can make this path more obvious.

It just seems like you're trying to solve the integration problem, but it won't be solved by separation, you want to make arithmetization completely agnostic to the framework, that's a different and more complex problem that needs to be discussed in a targeted way.

[cyphersnake]

Here is for example the current baseline for creating your own Mode. I think we can try to reduce the size of the boilerplate and think about the API design, but this code already allows us to build a topology or something similar (run_simple should definitely be part of CircuitBuilder for example).

// Minimal, non-streaming execution example using BitVec-backed storage.
//
// This demonstrates how to build a custom `CircuitMode` without the streaming
// metadata/credits machinery: two `BitVecs` track values and initialization,
// and gates are evaluated immediately.

use bitvec::vec::BitVec;
use garbled_snark_verifier as gsv;
use gsv::{
    circuit::WiresObject,
    Gate, WireId,
    circuit::{
        CircuitContext, CircuitInput, CircuitMode, CircuitOutput, ComponentKey, EncodeInput,
        FALSE_WIRE, SimpleInputs, SimpleInputsWire, TRUE_WIRE,
    },
    storage::Credits,
};

// ---------------------- Simple, non-streaming mode ----------------------

#[derive(Debug, Default, Clone)]
struct SimpleMode {
    values: BitVec,
    is_init: BitVec,
    next_id: usize, // starts at 2 (0/1 are constants)
}

impl SimpleMode {
    fn new() -> Self {
        Self {
            values: BitVec::new(),
            is_init: BitVec::new(),
            next_id: 2,
        }
    }

    #[inline]
    fn idx(w: WireId) -> usize {
        let WireId(raw) = w;
        debug_assert!(raw >= 2, "indexing constants via storage is not allowed");
        raw - 2
    }

    #[inline]
    fn ensure_slot(&mut self, w: WireId) {
        let idx = Self::idx(w);
        if idx >= self.values.len() {
            let need = idx + 1 - self.values.len();
            self.values.resize(self.values.len() + need, false);
            self.is_init.resize(self.is_init.len() + need, false);
        }
    }
}

impl CircuitMode for SimpleMode {
    type WireValue = bool;
    type CiphertextAcc = ();

    #[inline]
    fn false_value(&self) -> bool {
        false
    }

    #[inline]
    fn true_value(&self) -> bool {
        true
    }

    #[inline]
    fn allocate_wire(&mut self, _credits: Credits) -> WireId {
        let id = self.next_id;
        self.next_id += 1;
        self.values.push(false);
        self.is_init.push(false);
        WireId(id)
    }

    #[inline]
    fn evaluate_gate(&mut self, gate: &Gate) {
        if gate.wire_c == WireId::UNREACHABLE {
            return;
        }

        // Lookup A
        let a = match gate.wire_a {
            TRUE_WIRE => true,
            FALSE_WIRE => false,
            WireId::UNREACHABLE => panic!("wire_a is unreachable"),
            w => {
                let idx = Self::idx(w);
                if idx >= self.is_init.len() || !self.is_init[idx] {
                    panic!("lookup_wire called for {w:?} before initialization");
                }
                self.values[idx]
            }
        };

        // Lookup B
        let b = match gate.wire_b {
            TRUE_WIRE => true,
            FALSE_WIRE => false,
            WireId::UNREACHABLE => panic!("wire_b is unreachable"),
            w => {
                let idx = Self::idx(w);
                if idx >= self.is_init.len() || !self.is_init[idx] {
                    panic!("lookup_wire called for {w:?} before initialization");
                }
                self.values[idx]
            }
        };

        let c = gate.execute(a, b);
        self.feed_wire(gate.wire_c, c);
    }

    #[inline]
    fn lookup_wire(&mut self, wire_id: WireId) -> Option<bool> {
        match wire_id {
            TRUE_WIRE => Some(true),
            FALSE_WIRE => Some(false),
            WireId::UNREACHABLE => None,
            w => {
                let idx = Self::idx(w);
                if idx >= self.is_init.len() {
                    None
                } else if self.is_init[idx] {
                    Some(self.values[idx])
                } else {
                    panic!("Called `lookup_wire` for {w:?} that was created but not initialized")
                }
            }
        }
    }

    #[inline]
    fn feed_wire(&mut self, wire_id: WireId, value: bool) {
        if matches!(wire_id, TRUE_WIRE | FALSE_WIRE | WireId::UNREACHABLE) {
            return;
        }
        self.ensure_slot(wire_id);
        let idx = Self::idx(wire_id);
        self.values.set(idx, value);
        self.is_init.set(idx, true);
    }

    #[inline]
    fn add_credits(&mut self, _wires: &[WireId], _credits: std::num::NonZero<Credits>) {}
}

// ---------------------- Minimal context ----------------------

#[derive(Debug, Default, Clone)]
struct SimpleContext {
    mode: SimpleMode,
}

impl SimpleContext {
    fn new() -> Self {
        Self {
            mode: SimpleMode::new(),
        }
    }
}

impl CircuitContext for SimpleContext {
    type Mode = SimpleMode;

    #[inline]
    fn issue_wire(&mut self) -> WireId {
        self.mode.allocate_wire(1)
    }

    #[inline]
    fn add_gate(&mut self, gate: Gate) {
        self.mode.evaluate_gate(&gate)
    }

    // No component/template plumbing; just run the closure in-place.
    #[inline]
    fn with_named_child<I: gsv::circuit::WiresObject, O: gsv::circuit::FromWires>(
        &mut self,
        _key: ComponentKey,
        inputs: I,
        f: impl Fn(&mut Self, &I) -> O,
        _arity: usize,
    ) -> O {
        f(self, &inputs)
    }
}

// ---------------------- Simple runner ----------------------

#[allow(dead_code)]
#[derive(Debug)]
struct SimpleResult<M: CircuitMode, I: CircuitInput, O: CircuitOutput<M>> {
    false_wire_constant: M::WireValue,
    true_wire_constant: M::WireValue,
    input_wires_repr: I::WireRepr,
    output_wires_ids: Vec<WireId>,
    output_value: O,
    input_wire_values: Vec<M::WireValue>,
}

fn run_simple<I, F, O>(inputs: I, f: F) -> SimpleResult<SimpleMode, I, O>
where
    I: CircuitInput + EncodeInput<SimpleMode>,
    O: CircuitOutput<SimpleMode>,
    F: Fn(&mut SimpleContext, &I::WireRepr) -> O::WireRepr,
{
    let mut ctx = SimpleContext::new();

    // Allocate and encode inputs
    let input_repr = inputs.allocate(|| ctx.issue_wire());
    inputs.encode(&input_repr, &mut ctx.mode);

    // Build and evaluate
    let output_repr = f(&mut ctx, &input_repr);
    let output_ids = output_repr.to_wires_vec();

    // Snapshot inputs
    let input_values = I::collect_wire_ids(&input_repr)
        .into_iter()
        .map(|w| ctx.mode.lookup_wire(w).expect("input present"))
        .collect();

    let output_value = O::decode(output_repr, &mut ctx.mode);

    SimpleResult::<SimpleMode, I, O> {
        false_wire_constant: ctx.mode.false_value(),
        true_wire_constant: ctx.mode.true_value(),
        input_wires_repr: input_repr,
        output_wires_ids: output_ids,
        output_value,
        input_wire_values: input_values,
    }
}

// Decode single-bit boolean outputs for SimpleMode.
impl CircuitOutput<SimpleMode> for bool {
    type WireRepr = WireId;

    fn decode(wire: Self::WireRepr, cache: &mut SimpleMode) -> Self {
        cache
            .lookup_wire(wire)
            .unwrap_or_else(|| panic!("Can't find {wire:?}"))
    }
}

// ---------------------- Demonstration ----------------------

fn main() {
    // Example 1: basic AND
    let inputs: SimpleInputs<2> = [true, false];
    let out1: SimpleResult<_, _, Vec<bool>> = run_simple(inputs, |ctx, wires| {
        let [a, b]: SimpleInputsWire<2> = *wires;
        let o = ctx.issue_wire();
        ctx.add_gate(Gate::and(a, b, o));
        vec![o]
    });
    println!(
        "AND: inputs={:?} -> {:?}",
        out1.input_wire_values, out1.output_value
    );

    // Example 2: XOR then AND with TRUE
    let inputs2: SimpleInputs<2> = [true, true];
    let out2: SimpleResult<_, _, Vec<bool>> = run_simple(inputs2, |ctx, wires| {
        let [a, b]: SimpleInputsWire<2> = *wires;
        let t = ctx.issue_wire();
        ctx.add_gate(Gate::xor(a, b, t));
        let o = ctx.issue_wire();
        ctx.add_gate(Gate::and(t, TRUE_WIRE, o));
        vec![o]
    });
    println!(
        "XOR->AND(TRUE): inputs={:?} -> {:?}",
        out2.input_wire_values, out2.output_value
    );

    // Example 3: Groth16 verifier gadget on SimpleMode (non-streaming)
    run_groth16_big_example();
}

// ---------------------- Big example: Groth16 verify ----------------------

#[derive(Copy, Clone)]
struct DummyCircuit<F: gsv::ark::PrimeField> {
    a: Option<F>,
    b: Option<F>,
    num_variables: usize,
    num_constraints: usize,
}

impl<F: gsv::ark::PrimeField> gsv::ark::ConstraintSynthesizer<F> for DummyCircuit<F> {
    fn generate_constraints(
        self,
        cs: gsv::ark::ConstraintSystemRef<F>,
    ) -> Result<(), gsv::ark::SynthesisError> {
        let a =
            cs.new_witness_variable(|| self.a.ok_or(gsv::ark::SynthesisError::AssignmentMissing))?;
        let b =
            cs.new_witness_variable(|| self.b.ok_or(gsv::ark::SynthesisError::AssignmentMissing))?;
        let c = cs.new_input_variable(|| {
            let a = self.a.ok_or(gsv::ark::SynthesisError::AssignmentMissing)?;
            let b = self.b.ok_or(gsv::ark::SynthesisError::AssignmentMissing)?;
            Ok(a * b)
        })?;

        for _ in 0..(self.num_variables - 3) {
            let _ = cs.new_witness_variable(|| {
                self.a.ok_or(gsv::ark::SynthesisError::AssignmentMissing)
            })?;
        }

        for _ in 0..self.num_constraints - 1 {
            cs.enforce_constraint(
                gsv::ark::lc!() + a,
                gsv::ark::lc!() + b,
                gsv::ark::lc!() + c,
            )?;
        }

        cs.enforce_constraint(gsv::ark::lc!(), gsv::ark::lc!(), gsv::ark::lc!())?;
        Ok(())
    }
}

fn run_groth16_big_example() {
    use gsv::ark::{AffineRepr, CircuitSpecificSetupSNARK, Groth16, SNARK, UniformRand};
    use rand::SeedableRng;
    use rand_chacha::ChaCha20Rng;

    // Build a small circuit and generate a valid proof
    let k = 6; // 2^k constraints
    let mut rng = ChaCha20Rng::seed_from_u64(12345);
    let circuit = DummyCircuit::<ark_bn254::Fr> {
        a: Some(ark_bn254::Fr::rand(&mut rng)),
        b: Some(ark_bn254::Fr::rand(&mut rng)),
        num_variables: 10,
        num_constraints: 1 << k,
    };
    let (pk, vk) = Groth16::<ark_bn254::Bn254>::setup(circuit, &mut rng).unwrap();
    let c_val = circuit.a.unwrap() * circuit.b.unwrap();
    let proof = Groth16::<ark_bn254::Bn254>::prove(&pk, circuit, &mut rng).unwrap();

    // Prepare inputs for the gadget (convert to projective for wire encoding)
    let inputs = gsv::Groth16VerifyInput {
        public: vec![c_val],
        a: proof.a.into_group(),
        b: proof.b.into_group(),
        c: proof.c.into_group(),
        vk,
    };

    // Run the Groth16 verify gadget against the SimpleMode context
    let out: SimpleResult<SimpleMode, gsv::Groth16VerifyInput, bool> =
        run_simple(inputs, gsv::groth16_verify);
    println!("Groth16 verify (SimpleMode): {}", out.output_value);
}

[cyphersnake]

@Zk2u any questions here?