[frontend] Add Blake2s circuit (#757)

Author: fkondej

.github/workflows/ci.yml

@@ -144,7 +144,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        example: [ethsign, zklogin, sha256, sha512, keccak, hash_based_sig]
+        example: [ethsign, zklogin, sha256, sha512, keccak, blake2s, hash_based_sig]
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v4

crates/examples/Cargo.toml

@@ -21,6 +21,7 @@ ethsign = "0.9.0"
 tiny-keccak = "2.0.2"
 rand.workspace = true
 base64.workspace = true
+blake2.workspace = true
 jwt-simple.workspace = true
 sha2.workspace = true
 
@@ -35,6 +36,10 @@ harness = false
 name = "ethsign"
 harness = false
 
+[[bench]]
+name = "blake2s"
+harness = false
+
 [features]
 default = ["rayon"]
 perfetto = ["tracing-profile/perfetto"]

crates/examples/benches/blake2s.rs

@@ -0,0 +1,160 @@
+//! Blake2s hash benchmark
+
+use std::env;
+
+use binius_examples::{
+	ExampleCircuit,
+	circuits::blake2s::{Blake2sExample, Instance, Params},
+	setup,
+};
+use binius_frontend::compiler::CircuitBuilder;
+use binius_utils::platform_diagnostics::PlatformDiagnostics;
+use binius_verifier::{
+	config::StdChallenger,
+	transcript::{ProverTranscript, VerifierTranscript},
+};
+use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_main};
+
+const DEFAULT_MAX_BYTES: usize = 2048 * 64; // 2048 blocks × 64 bytes/block = 131,072 bytes
+
+fn get_feature_suffix(_diagnostics: &PlatformDiagnostics) -> String {
+	let mut suffix_parts = vec![];
+
+	// Add architecture
+	#[cfg(target_arch = "x86_64")]
+	{
+		suffix_parts.push("x86_64");
+		// Add key features based on compile-time features
+		#[cfg(target_feature = "gfni")]
+		suffix_parts.push("gfni");
+		#[cfg(target_feature = "avx512f")]
+		suffix_parts.push("avx512");
+		#[cfg(all(not(target_feature = "avx512f"), target_feature = "avx2"))]
+		suffix_parts.push("avx2");
+	}
+
+	#[cfg(target_arch = "aarch64")]
+	{
+		suffix_parts.push("arm64");
+		// Check for NEON and AES
+		#[cfg(all(target_feature = "neon", target_feature = "aes"))]
+		suffix_parts.push("neon_aes");
+		#[cfg(all(target_feature = "neon", not(target_feature = "aes")))]
+		suffix_parts.push("neon");
+	}
+
+	suffix_parts.join("_")
+}
+
+/// Benchmark Blake2s hash circuit
+fn bench_blake2s_hash(c: &mut Criterion) {
+	// Get maximum message size from environment or use default
+	let max_bytes = env::var("BLAKE2S_MAX_BYTES")
+		.ok()
+		.and_then(|s| s.parse::<usize>().ok())
+		.unwrap_or(DEFAULT_MAX_BYTES);
+
+	// Gather and print comprehensive platform diagnostics
+	let diagnostics = PlatformDiagnostics::gather();
+	diagnostics.print();
+
+	// Print benchmark-specific parameters
+	let blocks = max_bytes.div_ceil(64);
+	println!("\nBlake2s Benchmark Parameters:");
+	println!("  Circuit capacity: {} bytes ({} blocks × 64 bytes/block)", max_bytes, blocks);
+	println!("  Message length: {} bytes (using full capacity)", max_bytes);
+	println!("  Note: Circuit size is dynamic based on max_bytes parameter");
+	println!("=======================================\n");
+
+	let params = Params { max_bytes };
+	let instance = Instance {};
+
+	// Setup phase - do this once outside the benchmark loop
+	let mut builder = CircuitBuilder::new();
+	let example = Blake2sExample::build(params.clone(), &mut builder).unwrap();
+	let circuit = builder.build();
+	let cs = circuit.constraint_system().clone();
+	let (verifier, prover) = setup(cs, 1).unwrap();
+
+	// Create a witness once for proof size measurement
+	let mut filler = circuit.new_witness_filler();
+	example
+		.populate_witness(instance.clone(), &mut filler)
+		.unwrap();
+	circuit.populate_wire_witness(&mut filler).unwrap();
+	let witness = filler.into_value_vec();
+
+	let feature_suffix = get_feature_suffix(&diagnostics);
+
+	// Benchmark 1: Witness generation
+	{
+		let mut group = c.benchmark_group("blake2s_witness_generation");
+		group.throughput(Throughput::Bytes(max_bytes as u64));
+
+		let bench_name = format!("bytes_{}_{}", max_bytes, feature_suffix);
+		group.bench_with_input(BenchmarkId::from_parameter(&bench_name), &max_bytes, |b, _| {
+			b.iter(|| {
+				let mut filler = circuit.new_witness_filler();
+				example
+					.populate_witness(instance.clone(), &mut filler)
+					.unwrap();
+				circuit.populate_wire_witness(&mut filler).unwrap();
+				filler.into_value_vec()
+			})
+		});
+
+		group.finish();
+	}
+
+	// Benchmark 2: Proof generation
+	{
+		let mut group = c.benchmark_group("blake2s_proof_generation");
+		group.throughput(Throughput::Bytes(max_bytes as u64));
+		group.measurement_time(std::time::Duration::from_secs(120)); // 120 seconds measurement time
+		group.sample_size(100); // Keep 100 samples
+
+		let bench_name = format!("bytes_{}_{}", max_bytes, feature_suffix);
+		group.bench_with_input(BenchmarkId::from_parameter(&bench_name), &max_bytes, |b, _| {
+			b.iter(|| {
+				let mut prover_transcript = ProverTranscript::new(StdChallenger::default());
+				prover
+					.prove(witness.clone(), &mut prover_transcript)
+					.unwrap()
+			})
+		});
+
+		group.finish();
+	}
+
+	// Generate one proof for verification benchmark and size reporting
+	let mut prover_transcript = ProverTranscript::new(StdChallenger::default());
+	prover
+		.prove(witness.clone(), &mut prover_transcript)
+		.unwrap();
+	let proof_bytes = prover_transcript.finalize();
+
+	// Benchmark 3: Proof verification
+	{
+		let mut group = c.benchmark_group("blake2s_proof_verification");
+		group.throughput(Throughput::Bytes(max_bytes as u64));
+
+		let bench_name = format!("bytes_{}_{}", max_bytes, feature_suffix);
+		group.bench_with_input(BenchmarkId::from_parameter(&bench_name), &max_bytes, |b, _| {
+			b.iter(|| {
+				let mut verifier_transcript =
+					VerifierTranscript::new(StdChallenger::default(), proof_bytes.clone());
+				verifier
+					.verify(witness.public(), &mut verifier_transcript)
+					.expect("Proof verification failed")
+			})
+		});
+
+		group.finish();
+	}
+
+	// Print proof size
+	println!("\n\nBlake2s proof size for {} bytes message: {} bytes", max_bytes, proof_bytes.len());
+}
+
+criterion_group!(benches, bench_blake2s_hash);
+criterion_main!(benches);

crates/examples/examples/blake2s.rs

@@ -0,0 +1,117 @@
+use anyhow::{Result, ensure};
+use binius_examples::{Cli, ExampleCircuit};
+use binius_frontend::{
+	circuits::blake2s::Blake2s,
+	compiler::{CircuitBuilder, circuit::WitnessFiller},
+};
+use blake2::{Blake2s256, Digest};
+use clap::Args;
+use rand::prelude::*;
+
+/// Blake2s circuit example demonstrating the Blake2s hash function implementation
+struct Blake2sExample {
+	blake2s_gadget: Blake2s,
+}
+
+/// Circuit parameters that affect structure (compile-time configuration)
+#[derive(Args, Debug)]
+struct Params {
+	/// Maximum message length in bytes that the circuit can handle.
+	#[arg(long, default_value_t = 128)]
+	max_bytes: usize,
+}
+
+/// Instance data for witness population (runtime values)
+#[derive(Args, Debug)]
+#[group(multiple = false)]
+struct Instance {
+	/// Length of the randomly generated message, in bytes (defaults to half of --max-message-len).
+	#[arg(long)]
+	message_len: Option<usize>,
+
+	/// UTF-8 string to hash (if not provided, random bytes are generated)
+	#[arg(long)]
+	message_string: Option<String>,
+}
+
+impl ExampleCircuit for Blake2sExample {
+	type Params = Params;
+	type Instance = Instance;
+
+	fn build(params: Params, builder: &mut CircuitBuilder) -> Result<Self> {
+		// Create the Blake2s gadget with witness wires
+		let blake2s_gadget = Blake2s::new_witness(builder, params.max_bytes);
+
+		Ok(Self { blake2s_gadget })
+	}
+
+	fn populate_witness(&self, instance: Instance, w: &mut WitnessFiller) -> Result<()> {
+		// Determine the message bytes to hash
+		let message_bytes = if let Some(message_string) = instance.message_string {
+			// Use provided UTF-8 string
+			message_string.as_bytes().to_vec()
+		} else {
+			// Generate random bytes
+			let mut rng = StdRng::seed_from_u64(0);
+			let len = instance
+				.message_len
+				.unwrap_or(self.blake2s_gadget.max_bytes / 2);
+
+			let mut message_bytes = vec![0u8; len];
+			rng.fill_bytes(&mut message_bytes);
+			message_bytes
+		};
+
+		// Validate message length
+		ensure!(
+			message_bytes.len() <= self.blake2s_gadget.max_bytes,
+			"Message length ({}) exceeds maximum ({})",
+			message_bytes.len(),
+			self.blake2s_gadget.max_bytes
+		);
+
+		// Compute the expected Blake2s digest using the reference implementation
+		let mut hasher = Blake2s256::new();
+		hasher.update(&message_bytes);
+		let digest = hasher.finalize();
+		let digest_array: [u8; 32] = digest.into();
+
+		// Populate the witness values
+		self.blake2s_gadget.populate_message(w, &message_bytes);
+		self.blake2s_gadget.populate_digest(w, &digest_array);
+
+		Ok(())
+	}
+}
+
+fn main() -> Result<()> {
+	let _tracing_guard = tracing_profile::init_tracing()?;
+
+	// Create and run the CLI
+	Cli::<Blake2sExample>::new("blake2s")
+		.about("Blake2s hash function circuit example")
+		.long_about(
+			"Blake2s cryptographic hash function circuit implementation.\n\
+            \n\
+            This example demonstrates the Blake2s hash function which produces \
+            32-byte digests. Blake2s is optimized for 32-bit platforms and is \
+            faster than Blake2b on such architectures.\n\
+            \n\
+            The circuit supports variable-length messages up to the specified \
+            maximum length. It implements the full Blake2s algorithm as \
+            specified in RFC 7693, including 10 rounds of the compression \
+            function.\n\
+            \n\
+            Examples:\n\
+            \n\
+            Hash a string:\n\
+            cargo run --release --example blake2s -- --message-string \"Hello, World!\"\n\
+            \n\
+            Generate and hash random data (64 bytes):\n\
+            cargo run --release --example blake2s -- --message-len 64\n\
+            \n\
+            Test with maximum message length:\n\
+            cargo run --release --example blake2s -- --max-message-len 256 --message-len 256",
+		)
+		.run()
+}

crates/examples/snapshots/blake2s.snap

@@ -0,0 +1,11 @@
+blake2s circuit
+--
+Number of gates: 2937
+Number of evaluation instructions: 3068
+Number of AND constraints: 3897
+Number of MUL constraints: 0
+Length of value vec: 8192
+  Constants: 140
+  Inout: 0
+  Witness: 137
+  Internal: 3761

crates/examples/src/circuits/blake2s.rs

@@ -0,0 +1,62 @@
+//! Blake2s circuit benchmark wrapper
+
+use anyhow::{Result, ensure};
+use binius_frontend::{
+	circuits::blake2s::Blake2s,
+	compiler::{CircuitBuilder, circuit::WitnessFiller},
+};
+use clap::Args;
+use rand::{RngCore, SeedableRng, rngs::StdRng};
+
+use crate::ExampleCircuit;
+
+#[derive(Debug, Clone, Args)]
+pub struct Params {
+	#[arg(long, default_value_t = 131072)]
+	pub max_bytes: usize,
+}
+
+#[derive(Debug, Clone, Args)]
+pub struct Instance {}
+
+pub struct Blake2sExample {
+	blake2s_circuit: Blake2s,
+	max_bytes: usize,
+}
+
+impl ExampleCircuit for Blake2sExample {
+	type Params = Params;
+	type Instance = Instance;
+
+	fn build(params: Params, builder: &mut CircuitBuilder) -> Result<Self> {
+		ensure!(params.max_bytes > 0, "max_bytes must be positive");
+
+		// Create the Blake2s circuit with the specified max_bytes
+		let blake2s_circuit = Blake2s::new_witness(builder, params.max_bytes);
+
+		Ok(Self {
+			blake2s_circuit,
+			max_bytes: params.max_bytes,
+		})
+	}
+
+	fn populate_witness(&self, _instance: Instance, w: &mut WitnessFiller) -> Result<()> {
+		// Generate deterministic random message using the full capacity
+		let mut rng = StdRng::seed_from_u64(42);
+		let mut message_bytes = vec![0u8; self.max_bytes];
+		rng.fill_bytes(&mut message_bytes);
+
+		// Compute the expected digest using blake2 crate
+		use blake2::{Blake2s256, Digest};
+		let mut hasher = Blake2s256::new();
+		hasher.update(&message_bytes);
+		let digest = hasher.finalize();
+		let digest_bytes: [u8; 32] = digest.into();
+
+		// Populate the witness
+		self.blake2s_circuit.populate_message(w, &message_bytes);
+		self.blake2s_circuit.populate_digest(w, &digest_bytes);
+
+		Ok(())
+	}
+}

crates/examples/src/circuits/mod.rs

@@ -1,3 +1,4 @@
+pub mod blake2s;
 pub mod ethsign;
 pub mod keccak;
 pub mod sha256;