binius_core/constraint_system/

proof.rs

// Copyright 2025 Irreducible Inc.
use std::borrow::Cow;

use binius_utils::serialization::{DeserializeBytes, SerializationError, SerializeBytes};
use bytes::{Buf, BufMut};

/// A zero-knowledge proof that can be serialized for cross-host verification.
///
/// This structure contains the complete proof transcript generated by the prover,
/// along with information about the challenger type needed for verification.
/// The proof data represents the Fiat-Shamir transcript that can be deserialized
/// by the verifier to recreate the interactive protocol.
///
/// # Design
///
/// The proof contains:
/// - `data`: The actual proof transcript as bytes (zero-copy with Cow)
/// - `challenger_type`: String identifying the challenger used (e.g., `"HasherChallenger<Sha256>"`)
///
/// This enables complete cross-host verification where a proof generated on one
/// machine can be serialized, transmitted, and verified on another machine with
/// the correct challenger configuration.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Proof<'a> {
	data: Cow<'a, [u8]>,
	challenger_type: String,
}

impl<'a> Proof<'a> {
	/// Serialization format version for compatibility checking
	pub const SERIALIZATION_VERSION: u32 = 1;

	/// Create a new Proof from borrowed transcript data
	pub const fn borrowed(data: &'a [u8], challenger_type: String) -> Self {
		Self {
			data: Cow::Borrowed(data),
			challenger_type,
		}
	}

	/// Create a new Proof from owned transcript data
	pub const fn owned(data: Vec<u8>, challenger_type: String) -> Self {
		Self {
			data: Cow::Owned(data),
			challenger_type,
		}
	}

	/// Get the proof transcript data as a slice
	pub fn as_slice(&self) -> &[u8] {
		&self.data
	}

	/// Get the challenger type identifier
	pub fn challenger_type(&self) -> &str {
		&self.challenger_type
	}

	/// Get the number of bytes in the proof transcript
	pub fn len(&self) -> usize {
		self.data.len()
	}

	/// Check if the proof transcript is empty
	pub fn is_empty(&self) -> bool {
		self.data.is_empty()
	}

	/// Convert to owned data, consuming self
	pub fn into_owned(self) -> (Vec<u8>, String) {
		(self.data.into_owned(), self.challenger_type)
	}

	/// Convert to owned version of Proof
	pub fn to_owned(&self) -> Proof<'static> {
		Proof {
			data: Cow::Owned(self.data.to_vec()),
			challenger_type: self.challenger_type.clone(),
		}
	}
}

impl<'a> SerializeBytes for Proof<'a> {
	fn serialize(&self, mut write_buf: impl BufMut) -> Result<(), SerializationError> {
		Self::SERIALIZATION_VERSION.serialize(&mut write_buf)?;

		self.challenger_type.serialize(&mut write_buf)?;

		self.data.as_ref().serialize(write_buf)
	}
}

impl DeserializeBytes for Proof<'static> {
	fn deserialize(mut read_buf: impl Buf) -> Result<Self, SerializationError>
	where
		Self: Sized,
	{
		let version = u32::deserialize(&mut read_buf)?;
		if version != Self::SERIALIZATION_VERSION {
			return Err(SerializationError::InvalidConstruction {
				name: "Proof::version",
			});
		}

		let challenger_type = String::deserialize(&mut read_buf)?;
		let data = Vec::<u8>::deserialize(read_buf)?;

		Ok(Proof::owned(data, challenger_type))
	}
}

impl<'a> From<(&'a [u8], String)> for Proof<'a> {
	fn from((data, challenger_type): (&'a [u8], String)) -> Self {
		Proof::borrowed(data, challenger_type)
	}
}

impl From<(Vec<u8>, String)> for Proof<'static> {
	fn from((data, challenger_type): (Vec<u8>, String)) -> Self {
		Proof::owned(data, challenger_type)
	}
}

impl<'a> AsRef<[u8]> for Proof<'a> {
	fn as_ref(&self) -> &[u8] {
		self.as_slice()
	}
}

impl<'a> std::ops::Deref for Proof<'a> {
	type Target = [u8];

	fn deref(&self) -> &Self::Target {
		self.as_slice()
	}
}

#[cfg(test)]
mod tests {
	use rand::prelude::*;

	use super::*;

	#[test]
	fn test_proof_serialization_round_trip_owned() {
		let transcript_data = vec![0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0];
		let challenger_type = "HasherChallenger<Sha256>".to_string();
		let proof = Proof::owned(transcript_data.clone(), challenger_type.clone());

		let mut buf = Vec::new();
		proof.serialize(&mut buf).unwrap();

		let deserialized = Proof::deserialize(&mut buf.as_slice()).unwrap();
		assert_eq!(proof, deserialized);
		assert_eq!(deserialized.as_slice(), transcript_data.as_slice());
		assert_eq!(deserialized.challenger_type(), &challenger_type);
	}

	#[test]
	fn test_proof_serialization_round_trip_borrowed() {
		let transcript_data = vec![0xAA, 0xBB, 0xCC, 0xDD];
		let challenger_type = "TestChallenger".to_string();
		let proof = Proof::borrowed(&transcript_data, challenger_type.clone());

		let mut buf = Vec::new();
		proof.serialize(&mut buf).unwrap();

		let deserialized = Proof::deserialize(&mut buf.as_slice()).unwrap();
		assert_eq!(proof, deserialized);
		assert_eq!(deserialized.as_slice(), transcript_data.as_slice());
		assert_eq!(deserialized.challenger_type(), &challenger_type);
	}

	#[test]
	fn test_proof_empty_transcript() {
		let proof = Proof::owned(vec![], "EmptyProof".to_string());
		assert!(proof.is_empty());
		assert_eq!(proof.len(), 0);

		let mut buf = Vec::new();
		proof.serialize(&mut buf).unwrap();

		let deserialized = Proof::deserialize(&mut buf.as_slice()).unwrap();
		assert_eq!(proof, deserialized);
		assert!(deserialized.is_empty());
	}

	#[test]
	fn test_proof_large_transcript() {
		let mut rng = StdRng::seed_from_u64(12345);
		let mut large_data = vec![0u8; 10000];
		rng.fill_bytes(&mut large_data);

		let challenger_type = "LargeProofChallenger".to_string();
		let proof = Proof::owned(large_data.clone(), challenger_type.clone());

		let mut buf = Vec::new();
		proof.serialize(&mut buf).unwrap();

		let deserialized = Proof::deserialize(&mut buf.as_slice()).unwrap();
		assert_eq!(proof, deserialized);
		assert_eq!(deserialized.len(), 10000);
		assert_eq!(deserialized.challenger_type(), &challenger_type);
	}

	#[test]
	fn test_proof_version_mismatch() {
		let mut buf = Vec::new();
		999u32.serialize(&mut buf).unwrap(); // Wrong version
		"TestChallenger".serialize(&mut buf).unwrap(); // Some challenger type
		vec![0xAAu8].serialize(&mut buf).unwrap(); // Some data

		let result = Proof::deserialize(&mut buf.as_slice());
		assert!(result.is_err());
		match result.unwrap_err() {
			SerializationError::InvalidConstruction { name } => {
				assert_eq!(name, "Proof::version");
			}
			_ => panic!("Expected version mismatch error"),
		}
	}

	#[test]
	fn test_proof_into_owned() {
		let original_data = vec![1, 2, 3, 4, 5];
		let original_challenger = "TestChallenger".to_string();
		let proof = Proof::owned(original_data.clone(), original_challenger.clone());

		let (data, challenger_type) = proof.into_owned();
		assert_eq!(data, original_data);
		assert_eq!(challenger_type, original_challenger);
	}

	#[test]
	fn test_proof_to_owned() {
		let data = vec![0xFF, 0xEE, 0xDD];
		let challenger_type = "BorrowedChallenger".to_string();
		let borrowed_proof = Proof::borrowed(&data, challenger_type.clone());

		let owned_proof = borrowed_proof.to_owned();
		assert_eq!(owned_proof.as_slice(), data);
		assert_eq!(owned_proof.challenger_type(), &challenger_type);
		// Verify it's truly owned (not just borrowed)
		drop(data); // This would fail if owned_proof was still borrowing
		assert_eq!(owned_proof.len(), 3);
	}

	#[test]
	fn test_proof_different_challenger_types() {
		let data = vec![0x42];
		let challengers = vec![
			"HasherChallenger<Sha256>".to_string(),
			"HasherChallenger<Blake2b>".to_string(),
			"CustomChallenger".to_string(),
			"".to_string(), // Empty string should also work
		];

		for challenger_type in challengers {
			let proof = Proof::owned(data.clone(), challenger_type.clone());
			let mut buf = Vec::new();
			proof.serialize(&mut buf).unwrap();

			let deserialized = Proof::deserialize(&mut buf.as_slice()).unwrap();
			assert_eq!(deserialized.challenger_type(), &challenger_type);
		}
	}

	#[test]
	fn test_proof_serialization_with_different_sources() {
		let transcript_data = vec![0x11, 0x22, 0x33, 0x44];
		let challenger_type = "MultiSourceChallenger".to_string();
		let original = Proof::owned(transcript_data, challenger_type);

		// Test with Vec<u8> (memory buffer)
		let mut vec_buf = Vec::new();
		original.serialize(&mut vec_buf).unwrap();
		let deserialized1 = Proof::deserialize(&mut vec_buf.as_slice()).unwrap();
		assert_eq!(original, deserialized1);

		// Test with bytes::BytesMut (another common buffer type)
		let mut bytes_buf = bytes::BytesMut::new();
		original.serialize(&mut bytes_buf).unwrap();
		let deserialized2 = Proof::deserialize(bytes_buf.freeze()).unwrap();
		assert_eq!(original, deserialized2);
	}

	/// Helper function to create or update the reference binary file for Proof version
	/// compatibility testing.
	#[test]
	#[ignore] // Use `cargo test -- --ignored create_proof_reference_binary` to run this
	fn create_proof_reference_binary_file() {
		let transcript_data = vec![
			0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54,
			0x32, 0x10, 0xDE, 0xAD, 0xBE, 0xEF, 0xCA, 0xFE, 0xBA, 0xBE,
		];
		let challenger_type = "HasherChallenger<Sha256>".to_string();
		let proof = Proof::owned(transcript_data, challenger_type);

		let mut buf = Vec::new();
		proof.serialize(&mut buf).unwrap();

		let test_data_path = std::path::Path::new("verifier/core/test_data/proof_v1.bin");

		if let Some(parent) = test_data_path.parent() {
			std::fs::create_dir_all(parent).unwrap();
		}

		std::fs::write(test_data_path, &buf).unwrap();

		println!("Created Proof reference binary file at: {:?}", test_data_path);
		println!("Binary data length: {} bytes", buf.len());
	}

	/// Test deserialization from a reference binary file to ensure Proof version
	/// compatibility. This test will fail if breaking changes are made without incrementing the
	/// version.
	#[test]
	fn test_proof_deserialize_from_reference_binary_file() {
		let binary_data = include_bytes!("../../test_data/proof_v1.bin");

		let deserialized = Proof::deserialize(&mut binary_data.as_slice()).unwrap();

		assert_eq!(deserialized.len(), 24); // 24 bytes of transcript data
		assert_eq!(deserialized.challenger_type(), "HasherChallenger<Sha256>");

		let expected_data = vec![
			0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54,
			0x32, 0x10, 0xDE, 0xAD, 0xBE, 0xEF, 0xCA, 0xFE, 0xBA, 0xBE,
		];
		assert_eq!(deserialized.as_slice(), expected_data);

		// Verify that the version is what we expect
		// This is implicitly checked during deserialization, but we can also verify
		// the file starts with the correct version bytes
		let version_bytes = &binary_data[0..4]; // First 4 bytes should be version
		let expected_version_bytes = 1u32.to_le_bytes(); // Version 1 in little-endian
		assert_eq!(
			version_bytes, expected_version_bytes,
			"Proof binary file version mismatch. If you made breaking changes, increment Proof::SERIALIZATION_VERSION"
		);
	}
}