diff --git a/README.md b/README.md index 7af40fbd..447b7d45 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ This workspace contains multiple CLI binaries. Start here, then follow the links to each binary’s README for full usage. + ## Binaries ### `cairo_program_runner` (crate: `cairo-program-runner`) @@ -16,6 +17,7 @@ Docs: `crates/cairo-program-runner/README.md` Quick start: cargo run -p cairo-program-runner --bin cairo_program_runner -- --help + ### `vm_runner` / `stwo_vm_runner` (crate: `vm_runner`) Runs a compiled Cairo program in proof-mode config and adapts the result to `stwo_cairo_adapter::ProverInput`. Writes execution resources, and optionally prover input. @@ -25,6 +27,17 @@ Docs: `crates/vm_runner/README.md` Quick start: cargo run -p vm_runner -- --help + +### `stwo_run_and_prove` / (crate: `stwo_run_and_prove`) + +Runs a compiled cairo program and generates a Stwo proof for it. Optionally verifies the proof, and saves the program output and data for debugging. + +Docs: `crates/stwo_run_and_prove/README.md` + +Quick start: +cargo run -p stwo_run_and_prove -- --help + + ## Build cargo build --release diff --git a/crates/stwo_run_and_prove/src/README.md b/crates/stwo_run_and_prove/src/README.md new file mode 100644 index 00000000..66fb898a --- /dev/null +++ b/crates/stwo_run_and_prove/src/README.md @@ -0,0 +1,57 @@ +# stwo_run_and_prove + +Runs a compiled Cairo program and generates a Stwo proof for it. Optionally verifies the proof. +Saves the proof to the given path with the requested format, and optionally saves the program output and data for debugging. + +Entry point: `crates/stwo_run_and_prove/src/main.rs` + + +## Build & run + +cargo run -p stwo_run_and_prove -- --help + + +## Basic usage + +Required arguments: +- `--program `: Absolute path to the compiled Cairo program. +- `--proof_path `: Absolute path where the generated proof will be saved. + +Basic Example: +cargo run -p stwo_run_and_prove -- \ + --program path/to/compiled_program.json \ + --proof_path proof.json + +Optional arguments: +- `--program_input `: Absolute path to the program input file. +- `--program_output `: Absolute path where the program's output will be saved. +- `--prover_params_json `: Absolute path to the JSON file containing the prover parameters. +- `--proof_format `: Proof format (Json or CairoSerde. default: CairoSerde). +- `--verify`: Verifies the generated proof. +- `--save_debug_data`: Saves the ProverInput to a file in `debug_data_dir` for both success and failure. +- `--debug_data_dir `: Absolute path to the output directory where the ProverInput will be saved in the + case of a proving error, or when the save_debug_data flag is enabled. + +Example with verification and debug data: +cargo run -p stwo_run_and_prove -- \ + --program path/to/compiled_program.json \ + --program_input path/to/program_input.json \ + --proof_path path/to/proof.json \ + --verify \ + --debug_data_dir path/to/debug_output \ + --save_debug_data + + +## What it does + +1. Runs the given Cairo program with cairo-vm. +2. Calls `stwo_cairo_adapter::adapter::adapt(&cairo_runner)` to produce `ProverInput`. +3. Proves the program, and optionally verifies it. +4. Saves the proof, and optionally the program's output and the debug data, to the given paths. + + +## Outputs + +- Proof (`--proof_path`): Stwo proof file in the specified format. +- Program output (`--program_output`): JSON array of program output felts (if specified). +- Debug data: ProverInput JSON saved to `debug_data_dir` (when `--save_debug_data` is enabled or on proving failure). diff --git a/crates/stwo_run_and_prove/src/main.rs b/crates/stwo_run_and_prove/src/main.rs index 3a4cd64a..5193af2c 100644 --- a/crates/stwo_run_and_prove/src/main.rs +++ b/crates/stwo_run_and_prove/src/main.rs @@ -53,7 +53,7 @@ struct Args { verify: bool, #[clap( long = "program_output", - help = "Optional absolute path for the program output." + help = "Optional absolute path where the program's output will be saved." )] program_output: Option, #[clap(