Add save command to the examples

Author: Dmytro Gordon

crates/examples/README.md

@@ -274,6 +274,48 @@ cargo run --release --example my_circuit -- --help
 RUST_LOG=info cargo run --release --example my_circuit
 ```
 
+## CLI subcommands
+
+All example binaries share a common CLI with these subcommands:
+
+- prove (default): build the circuit, generate witness, create and verify a proof
+- stat: print circuit statistics
+- composition: output circuit composition as JSON
+- check-snapshot: compare current stats with the stored snapshot
+- bless-snapshot: update the stored snapshot with current stats
+- save: save artifacts to files (only those explicitly requested)
+
+### Save artifacts
+
+Use the save subcommand to write selected artifacts to disk. Nothing is written unless a corresponding path is provided.
+
+Flags:
+- --cs-path PATH: write the constraint system binary
+- --pub-witness-path PATH: write the public values (ValuesData) binary
+- --non-pub-data-path PATH: write the non-public values (ValuesData) binary
+
+Examples:
+
+```bash
+# Save only the constraint system
+cargo run --release --example my_circuit -- save --cs-path out/cs.bin
+
+# Save public values and non-public values
+cargo run --release --example my_circuit -- save \
+    --pub-witness-path out/public.bin \
+    --non-pub-data-path out/non_public.bin
+
+# Save all three
+cargo run --release --example my_circuit -- save \
+    --cs-path out/cs.bin \
+    --pub-witness-path out/public.bin \
+    --non-pub-data-path out/non_public.bin
+```
+
+Notes:
+- Public and non-public outputs are serialized using the versioned ValuesData format from core.
+- Parent directories are created automatically if they don’t exist.
+
 ## Adding to Cargo.toml
 
 Add your example to `crates/examples/Cargo.toml`:

crates/examples/src/cli.rs

@@ -1,9 +1,26 @@
+use std::{fs, path::Path};
+
 use anyhow::Result;
+use binius_core::constraint_system::{ValueVec, ValuesData};
 use binius_frontend::{compiler::CircuitBuilder, stat::CircuitStat};
+use binius_utils::serialization::SerializeBytes;
 use clap::{Arg, Args, Command, FromArgMatches, Subcommand};
 
 use crate::{ExampleCircuit, prove_verify, setup};
 
+/// Serialize a value implementing `SerializeBytes` and write it to the given path.
+fn write_serialized<T: SerializeBytes>(value: &T, path: &str) -> Result<()> {
+	if let Some(parent) = Path::new(path).parent()
+		&& !parent.as_os_str().is_empty()
+	{
+		fs::create_dir_all(parent)?;
+	}
+	let mut buf: Vec<u8> = Vec::new();
+	value.serialize(&mut buf)?;
+	fs::write(path, &buf)?;
+	Ok(())
+}
+
 /// A CLI builder for circuit examples that handles all command-line parsing and execution.
 ///
 /// This provides a clean API for circuit examples where developers only need to:
@@ -74,6 +91,27 @@ enum Commands {
 		#[command(flatten)]
 		params: CommandArgs,
 	},
+
+	/// Save constraint system, public witness, and non-public data to files if paths are provided
+	Save {
+		/// Output path for the constraint system binary
+		#[arg(long = "cs-path")]
+		cs_path: Option<String>,
+
+		/// Output path for the public witness binary
+		#[arg(long = "pub-witness-path")]
+		pub_witness_path: Option<String>,
+
+		/// Output path for the non-public data (witness + internal) binary
+		#[arg(long = "non-pub-data-path")]
+		non_pub_data_path: Option<String>,
+
+		#[command(flatten)]
+		params: CommandArgs,
+
+		#[command(flatten)]
+		instance: CommandArgs,
+	},
 }
 
 /// Wrapper for dynamic command arguments
@@ -102,13 +140,15 @@ where
 		let composition_cmd = Self::build_composition_subcommand();
 		let check_snapshot_cmd = Self::build_check_snapshot_subcommand();
 		let bless_snapshot_cmd = Self::build_bless_snapshot_subcommand();
+		let save_cmd = Self::build_save_subcommand();
 
 		let command = command
 			.subcommand(prove_cmd)
 			.subcommand(stat_cmd)
 			.subcommand(composition_cmd)
 			.subcommand(check_snapshot_cmd)
-			.subcommand(bless_snapshot_cmd);
+			.subcommand(bless_snapshot_cmd)
+			.subcommand(save_cmd);
 
 		// Also add top-level args for default prove behavior
 		let command = command.arg(
@@ -171,6 +211,34 @@ where
 		E::Params::augment_args(cmd)
 	}
 
+	fn build_save_subcommand() -> Command {
+		let mut cmd = Command::new("save").about(
+			"Save constraint system, public witness, and non-public data to files if paths are provided",
+		);
+		cmd = cmd
+			.arg(
+				Arg::new("cs_path")
+					.long("cs-path")
+					.value_name("PATH")
+					.help("Output path for the constraint system binary"),
+			)
+			.arg(
+				Arg::new("pub_witness_path")
+					.long("pub-witness-path")
+					.value_name("PATH")
+					.help("Output path for the public witness binary"),
+			)
+			.arg(
+				Arg::new("non_pub_data_path")
+					.long("non-pub-data-path")
+					.value_name("PATH")
+					.help("Output path for the non-public data (witness + internal) binary"),
+			);
+		cmd = E::Params::augment_args(cmd);
+		cmd = E::Instance::augment_args(cmd);
+		cmd
+	}
+
 	/// Set the about/description text for the command.
 	///
 	/// This appears in the help output.
@@ -212,6 +280,7 @@ where
 			Some(("bless-snapshot", sub_matches)) => {
 				Self::run_bless_snapshot_impl(sub_matches.clone(), circuit_name)
 			}
+			Some(("save", sub_matches)) => Self::run_save(sub_matches.clone()),
 			Some((cmd, _)) => anyhow::bail!("Unknown subcommand: {}", cmd),
 			None => {
 				// No subcommand - default to prove behavior for backward compatibility
@@ -319,6 +388,51 @@ where
 		Ok(())
 	}
 
+	fn run_save(matches: clap::ArgMatches) -> Result<()> {
+		// Extract optional output paths
+		let cs_path = matches.get_one::<String>("cs_path").cloned();
+		let pub_witness_path = matches.get_one::<String>("pub_witness_path").cloned();
+		let non_pub_data_path = matches.get_one::<String>("non_pub_data_path").cloned();
+
+		// If nothing to save, exit early
+		if cs_path.is_none() && pub_witness_path.is_none() && non_pub_data_path.is_none() {
+			tracing::info!("No output paths provided; nothing to save");
+			return Ok(());
+		}
+
+		// Parse Params and Instance
+		let params = E::Params::from_arg_matches(&matches)?;
+		let instance = E::Instance::from_arg_matches(&matches)?;
+
+		// Build circuit
+		let mut builder = CircuitBuilder::new();
+		let example = E::build(params, &mut builder)?;
+		let circuit = builder.build();
+
+		// Generate witness
+		let mut filler = circuit.new_witness_filler();
+		example.populate_witness(instance, &mut filler)?;
+		circuit.populate_wire_witness(&mut filler)?;
+		let witness: ValueVec = filler.into_value_vec();
+
+		// Conditionally write artifacts
+		if let Some(path) = cs_path.as_deref() {
+			write_serialized(circuit.constraint_system(), path)?;
+		}
+
+		if let Some(path) = pub_witness_path.as_deref() {
+			let data = ValuesData::from(witness.public());
+			write_serialized(&data, path)?;
+		}
+
+		if let Some(path) = non_pub_data_path.as_deref() {
+			let data = ValuesData::from(witness.non_public());
+			write_serialized(&data, path)?;
+		}
+
+		Ok(())
+	}
+
 	/// Parse arguments and run the circuit example.
 	///
 	/// This orchestrates the entire flow: