[frontend] Add Blake2s circuit

Author: fkondej

.github/workflows/ci.yml

@@ -144,7 +144,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        example: [ethsign, zklogin, sha256, sha512, keccak]
+        example: [ethsign, zklogin, sha256, sha512, keccak, blake2s]
     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
 

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/frontend/src/circuits/blake2s/constants.rs

@@ -0,0 +1,43 @@
+//! Blake2s constants
+//!
+//! This module contains the constants used in the Blake2s hash function,
+//! including initialization vectors and the message permutation schedule.
+
+/// Blake2s initialization vectors derived from the fractional parts of
+/// square roots of the first 8 prime numbers (2, 3, 5, 7, 11, 13, 17, 19).
+///
+/// These values are specified in RFC 7693 Section 2.6 and provide the
+/// initial state for the hash computation. They ensure that even empty
+/// messages produce non-zero hashes.
+pub const IV: [u32; 8] = [
+	0x6A09E667, // Frac(sqrt(2)) - first 32 bits
+	0xBB67AE85, // Frac(sqrt(3))
+	0x3C6EF372, // Frac(sqrt(5))
+	0xA54FF53A, // Frac(sqrt(7))
+	0x510E527F, // Frac(sqrt(11))
+	0x9B05688C, // Frac(sqrt(13))
+	0x1F83D9AB, // Frac(sqrt(17))
+	0x5BE0CD19, // Frac(sqrt(19))
+];
+
+/// SIGMA permutation schedule for message word selection.
+///
+/// Defines which message words are used in each G-function call during
+/// the 10 rounds of compression. This permutation ensures that all message
+/// words influence the output multiple times in different combinations,
+/// providing cryptographic diffusion as specified in RFC 7693 Section 3.1.
+///
+/// Each row represents one round, with 16 indices selecting message words
+/// for the 8 G-function calls (2 words per G-function).
+pub const SIGMA: [[usize; 16]; 10] = [
+	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], // Round 0
+	[14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3], // Round 1
+	[11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4], // Round 2
+	[7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8], // Round 3
+	[9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13], // Round 4
+	[2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9], // Round 5
+	[12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11], // Round 6
+	[13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10], // Round 7
+	[6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5], // Round 8
+	[10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0], // Round 9
+];