binius_spartan_prover/wrapper/

replay_channel.rs

// Copyright 2026 The Binius Developers

//! [`ReplayChannel`]: an [`IPVerifierChannel`] that replays recorded interaction values through a
//! [`WitnessGenerator`], filling both inout and private wires in the outer witness.

use std::{
	cell::RefCell,
	rc::{Rc, Weak},
	sync::Arc,
	vec::IntoIter as VecIntoIter,
};

use binius_core::word::Word;
use binius_field::{BinaryField, Field};
use binius_iop::channel::{IOPVerifierChannel, OracleSpec, TransparentEvalFn};
use binius_ip::channel::{
	IPVerifierChannel, WordIPVerifierChannel, pack_words_concrete, select_word, subset_sum_word,
};
use binius_spartan_frontend::{
	circuit_builder::{CircuitBuilder, WireAllocator, WitnessError, WitnessGenerator},
	constraint_system::{WireKind, Witness, WitnessLayout},
};
use binius_spartan_verifier::wrapper::circuit_elem::CircuitElem;

/// A channel that replays recorded interaction values through a [`WitnessGenerator`], filling
/// both inout and private wires in the outer witness.
///
/// This mirrors
/// [`IronSpartanBuilderChannel`](binius_spartan_verifier::wrapper::IronSpartanBuilderChannel)
/// but uses concrete evaluation instead of symbolic constraint building. Each operation consumes
/// the next value and writes it to the corresponding inout wire in the [`WitnessGenerator`]. When
/// the verifier's arithmetic runs on the returned [`CircuitElem`] values, the [`WitnessGenerator`]
/// fills private wires.
pub struct ReplayChannel<F: Field> {
	witness_gen: Rc<RefCell<WitnessGenerator<F>>>,
	/// Allocators for the InOut and Precommit segments. They live here, not on the
	/// [`WitnessGenerator`], because allocating wires in interaction order is the channel's job;
	/// the generator just writes a value to a given wire. Allocation order must match the symbolic
	/// [`IronSpartanBuilderChannel`](binius_spartan_verifier::wrapper::IronSpartanBuilderChannel)
	/// so the wire ids align with `layout`.
	inout_alloc: WireAllocator,
	precommit_alloc: WireAllocator,
	keys: VecIntoIter<F>,
	events: VecIntoIter<F>,
}

impl<F: Field> ReplayChannel<F> {
	/// Creates a new replay channel.
	///
	/// TODO: Document args. Keys are the symmetric OTP keys for the received values.
	///
	/// Takes a shared `Arc<WitnessLayout<F>>`, not a borrow.
	/// The backing [`WitnessGenerator`] must be `'static`: its `CircuitElem`s outlive this call.
	/// The `Arc` is a bumped reference count on the layout the config already owns, not a clone.
	pub fn new(layout: Arc<WitnessLayout<F>>, keys: Vec<F>, events: Vec<F>) -> Self {
		Self {
			witness_gen: Rc::new(RefCell::new(WitnessGenerator::new(layout))),
			inout_alloc: WireAllocator::new(WireKind::InOut),
			precommit_alloc: WireAllocator::new(WireKind::Precommit),
			keys: keys.into_iter(),
			events: events.into_iter(),
		}
	}

	fn next_inout_elem(&mut self) -> CircuitElem<F, WitnessGenerator<F>> {
		let value = self
			.events
			.next()
			.unwrap_or_else(|| panic!("replay exhausted: no more events"));

		self.alloc_inout_elem(value)
	}

	/// Allocates the next inout wire around a value the replay computes rather than reads back.
	///
	/// Most inout wires carry a recorded value, since they stand for what crossed the channel. The
	/// packed statement does not cross it: both sides hold the words and pack them, so the value
	/// comes from the caller.
	fn alloc_inout_elem(&mut self, value: F) -> CircuitElem<F, WitnessGenerator<F>> {
		let wire = self.inout_alloc.alloc();
		let witness_wire = self.witness_gen.borrow_mut().write_inout(wire, value);
		CircuitElem::wire(&self.witness_gen, witness_wire)
	}

	fn next_precommit_elem(&mut self) -> CircuitElem<F, WitnessGenerator<F>> {
		let value = self
			.keys
			.next()
			.expect("precommit segment is sized incorrectly");

		let wire = self.precommit_alloc.alloc();
		let witness_wire = self.witness_gen.borrow_mut().write_precommit(wire, value);
		CircuitElem::wire(&self.witness_gen, witness_wire)
	}

	/// Consumes the channel and builds the outer witness.
	pub fn finish(self) -> Result<Witness<F>, WitnessError> {
		Rc::try_unwrap(self.witness_gen)
			.expect("CircuitElem values should only hold Weak references")
			.into_inner()
			.build()
	}
}

impl<F: Field> IPVerifierChannel<F> for ReplayChannel<F> {
	type Elem = CircuitElem<F, WitnessGenerator<F>>;

	fn recv_one(&mut self) -> Result<Self::Elem, binius_ip::channel::Error> {
		let encrypted_elem = self.next_inout_elem();
		let key = self.next_precommit_elem();
		Ok(encrypted_elem + key)
	}

	fn recv_public_claim(&mut self) -> Result<Self::Elem, binius_ip::channel::Error> {
		// Mirror `IronSpartanBuilderChannel::recv_public_claim`: the recorded interaction holds the
		// claim unencrypted, so it fills one inout wire and no precommit key.
		Ok(self.next_inout_elem())
	}

	fn sample(&mut self) -> Self::Elem {
		self.next_inout_elem()
	}

	fn observe_one(&mut self, _val: F) -> Self::Elem {
		self.next_inout_elem()
	}

	fn assert_zero(&mut self, val: Self::Elem) -> Result<(), binius_ip::channel::Error> {
		match val {
			// A compile-time constant is checked here; any other wire's value is checked by the
			// witness generator, which records a constraint violation as a build error.
			CircuitElem::Constant(c) => {
				if c == F::ZERO {
					Ok(())
				} else {
					Err(binius_ip::channel::Error::InvalidAssert)
				}
			}
			CircuitElem::Wire { builder, wire } => {
				assert!(Weak::ptr_eq(&Rc::downgrade(&self.witness_gen), &builder));
				self.witness_gen.borrow_mut().assert_zero(wire);
				Ok(())
			}
		}
	}
}

impl<F: BinaryField> WordIPVerifierChannel<F> for ReplayChannel<F> {
	type Word = Word;

	// The recorded interaction already holds whatever the Fiat-Shamir state produced, so replaying
	// observes nothing. This mirrors `IronSpartanBuilderChannel::observe_words`.
	fn observe_words(&mut self, words: &[Word]) -> Vec<Word> {
		words.to_vec()
	}

	fn subset_sum(&mut self, elems: &[Self::Elem], word: &Word) -> Self::Elem {
		subset_sum_word(elems, *word)
	}

	fn select(&mut self, elems: &[Self::Elem], word: &Word) -> Self::Elem {
		select_word(elems, *word)
	}

	fn sample_bits(&mut self, _bits: usize) -> Word {
		Word::ZERO
	}

	fn pack_words(&mut self, words: &[Word]) -> Vec<Self::Elem> {
		// One inout wire per packed element, matching the symbolic phase; the prover holds the same
		// words the verifier does, so it packs them itself rather than replaying them.
		pack_words_concrete::<F, F>(words)
			.into_iter()
			.map(|value| self.alloc_inout_elem(value))
			.collect()
	}
}

impl<F: Field> IOPVerifierChannel<F> for ReplayChannel<F> {
	type Oracle = ();

	fn remaining_oracle_specs(&self) -> &[OracleSpec] {
		&[]
	}

	fn recv_oracle(
		&mut self,
		_log_msg_len: usize,
		_is_witness_dependent: bool,
	) -> Result<Self::Oracle, binius_iop::channel::Error> {
		Ok(())
	}

	fn verify_oracle_relation(
		&mut self,
		_oracle: Self::Oracle,
		_transparent: TransparentEvalFn<Self::Elem>,
		claim: Self::Elem,
	) -> Result<(), binius_iop::channel::Error> {
		// For each oracle opening, the prover sends the decrypted evaluation. The outer verifier
		// checks in the circuit equality of this value with the expected expression over encrypted
		// values.
		let decrypted_claim = self.next_inout_elem();
		self.assert_zero(claim - decrypted_claim)?;
		Ok(())
	}
}

#[cfg(test)]
mod tests {
	use std::{cell::RefCell, rc::Rc, sync::Arc};

	use binius_field::{BinaryField1b as B1, ExtensionField, Ghash128b as B128, field::FieldOps};
	use binius_spartan_frontend::circuit_builder::{ConstraintBuilder, WitnessGenerator};
	use binius_spartan_verifier::wrapper::circuit_elem::CircuitElem;

	type BuildElem = CircuitElem<B128, ConstraintBuilder<B128>>;
	type WitnessElem = CircuitElem<B128, WitnessGenerator<B128>>;

	#[test]
	fn test_square_transpose_wires() {
		// Test that square_transpose on wire elements builds a valid constraint system,
		// and that a WitnessGenerator with correct values satisfies all constraints.
		type FSub = B1;
		let degree = <B128 as ExtensionField<FSub>>::DEGREE;

		// Phase 1: Build the constraint system symbolically.
		let mut constraint_builder = ConstraintBuilder::<B128>::new();
		let inout_wires: Vec<_> = (0..degree)
			.map(|_| constraint_builder.alloc_inout())
			.collect();

		// Build CircuitElem wires via a shared Rc.
		let rc = Rc::new(RefCell::new(constraint_builder));
		let mut elems: Vec<BuildElem> = inout_wires
			.iter()
			.map(|&w| BuildElem::wire(&rc, w))
			.collect();

		<BuildElem as FieldOps>::square_transpose::<FSub>(&mut elems);

		// The transposed outputs are wires; drop them so we can extract the builder.
		drop(elems);
		let constraint_builder = Rc::try_unwrap(rc).unwrap().into_inner();
		let (cs, layout) = constraint_builder.build().finalize();

		// The constraint system should have multiplication constraints from
		// Frobenius checks, reconstruction, and transposed output.
		assert!(!cs.mul_constraints().is_empty());

		// Phase 2: Generate a witness with concrete values and verify all constraints.
		let test_values: Vec<B128> = (0..degree)
			.map(<B128 as ExtensionField<FSub>>::basis)
			.collect();

		let layout = Arc::new(layout);
		let mut witness_gen = WitnessGenerator::new(Arc::clone(&layout));
		let witness_wires: Vec<_> = inout_wires
			.iter()
			.zip(&test_values)
			.map(|(&wire, &val)| witness_gen.write_inout(wire, val))
			.collect();

		let witness_rc = Rc::new(RefCell::new(witness_gen));
		let mut witness_elems: Vec<WitnessElem> = witness_wires
			.iter()
			.map(|&w| WitnessElem::wire(&witness_rc, w))
			.collect();

		<WitnessElem as FieldOps>::square_transpose::<FSub>(&mut witness_elems);

		drop(witness_elems);
		let witness_gen = Rc::try_unwrap(witness_rc).unwrap().into_inner();
		let witness = witness_gen
			.build()
			.expect("witness generation should succeed (all constraints satisfied)");

		cs.validate(&witness);
	}
}