Skip to content

Commit b788938

Browse files
YairVaknin-starkwareYairVaknin-starkware
committed
Add READMEs for cairo_program_runner and vm_runner
1 parent ddb5d53 commit b788938

File tree

3 files changed

+162
-23
lines changed

3 files changed

+162
-23
lines changed

‎README.md‎

Lines changed: 17 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,30 @@
1-
# Cairo bootloader
1+
# Proving Utils Workspace
22

3-
Cairo bootloader port for the Rust Cairo VM.
3+
This workspace contains multiple CLI binaries. Start here, then follow the links to each binary’s README for full usage.
44

5-
The Cairo bootloader is a Cairo program that loads and executes other programs in a provable way.
6-
It is also able to execute Cairo PIEs (Position Independent Executables) along with regular Cairo programs.
5+
## Binaries
76

8-
We currently support Cairo bootloader v0.13.0.
7+
### `cairo_program_runner` (crate: `cairo-program-runner`)
98

10-
## How to use this library
9+
Runs a compiled Cairo program. Can optionally:
1110

12-
We provide two hint processors that can be used to execute bootloader hints.
11+
- write a Cairo PIE (non-proof mode), or
12+
- in proof mode, generate AIR public/private inputs plus encoded trace/memory.
1313

14-
### Standalone hint processor
14+
Docs: `crates/cairo-program-runner/README.md`
1515

16-
The standalone hint processor (`BootloaderHintProcessor`) is the simplest way to execute the bootloader.
17-
You can just declare the hint processor and use it in `cairo_run_program`.
16+
Quick start:
17+
cargo run -p cairo-program-runner --bin cairo_program_runner -- --help
1818

19-
Check the [run program example](./examples/run_program.rs) for more details on how to configure the bootloader options.
19+
### `vm_runner` / `stwo_vm_runner` (crate: `vm_runner`)
2020

21-
### Minimal hint processor.
21+
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.
2222

23-
For advanced use cases, we also provide the `MinimalBootloaderHintProcessor` struct.
24-
This is useful when you want to mix multiple hint processors (ex: Starknet OS hints + bootloader hints + builtin hints)
25-
and avoid checking for the Cairo VM hints multiple times, or simply avoid compatibility issues between different
26-
versions of `cairo-vm`.
23+
Docs: `crates/vm_runner/README.md`
2724

28-
To use this hint processor, you will need to define your own hint processor structure and implement the `HintProcessorLogic`
29-
trait yourself.
25+
Quick start:
26+
cargo run -p vm_runner -- --help
3027

31-
Note that this is exactly how the `BootloaderHintProcessor` struct is implemented.
28+
## Build
3229

33-
## Limitations
34-
35-
* Composite packed outputs are not supported yet.
36-
* The bootloader is not able to load hints for Cairo 0 programs with hints yet.
30+
cargo build --release

‎crates/cairo-program-runner/README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# cairo_program_runner
2+
3+
Run a compiled Cairo program, optionally produce a Cairo PIE, and (in proof mode) generate AIR public/private inputs plus encoded trace/memory files.
4+
This runner uses a custom hint processor that supports internal programs used in SHARP, namely bootloaders and cairo verifier hints.
5+
It also uses the hints implemented in lambda-class's `cairo-vm` repo for hints from the cairo common library.
6+
7+
Entry point: `crates/cairo-program-runner/src/bin/cairo_program_runner/main.rs`
8+
9+
## Build & run
10+
11+
cargo run -p cairo-program-runner --bin cairo_program_runner -- --help
12+
13+
## Basic run (no proof mode)
14+
15+
Runs the program. You may also dump:
16+
17+
- program outputs (`--outputs_file`)
18+
- execution resources (`--execution_resources_file`)
19+
- Cairo PIE (`--cairo_pie_output`)
20+
21+
Example:
22+
cargo run -p cairo-program-runner --bin cairo_program_runner -- \
23+
--program path/to/compiled_program.json \
24+
--program_input path/to/program_input.json \
25+
--layout plain \
26+
--outputs_file outputs.json \
27+
--execution_resources_file execution_resources.json
28+
29+
- The options for `--layout` are: `plain`, `small`, `dex`, `recursive`, `starknet`, `starknet_with_keccak`, `recursive_large_output`, `recursive_with_poseidon`, `all_solidity`, `all_cairo`, `dynamic`, `all_cairo_stwo`, `perpetual`, `dex_with_bitwise`. See the `LayoutName` enum definition in `cairo-vm`.
30+
31+
### Cairo PIE output
32+
33+
Write a Cairo PIE zip file:
34+
cargo run -p cairo-program-runner --bin cairo_program_runner -- \
35+
--program path/to/compiled_program.json \
36+
--program_input path/to/program_input.json \
37+
--layout plain \
38+
--cairo_pie_output run.pie.zip
39+
40+
Optional:
41+
42+
- `--merge_extra_segments`: merge extra memory segments before creating the PIE.
43+
44+
Note: `--cairo_pie_output` cannot be used with `--proof_mode`.
45+
46+
## Proof mode
47+
48+
Proof mode enables generation of AIR inputs and encoded trace/memory.
49+
50+
Required flags (must be provided together):
51+
52+
- `--proof_mode`
53+
- `--air_public_input <PATH>`
54+
- `--air_private_input <PATH>`
55+
56+
Optional outputs:
57+
58+
- `--trace_file <PATH>` (if omitted, a temp file is created)
59+
- `--memory_file <PATH>` (if omitted, a temp file is created)
60+
61+
Example:
62+
cargo run -p cairo-program-runner --bin cairo_program_runner -- \
63+
--program path/to/compiled_program.json \
64+
--program_input path/to/program_input.json \
65+
--layout plain \
66+
--proof_mode \
67+
--air_public_input air_public_input.json \
68+
--air_private_input air_private_input.json \
69+
--trace_file trace.bin \
70+
--memory_file memory.bin
71+
72+
## Flag notes
73+
74+
- `--disable_trace_padding`: disables padding the trace at end of run. Requires `--proof_mode`.
75+
- `--relocate_mem [true|false]` (default: `true`): only applies in proof mode; set `false` if relocation will be done later (e.g., by an adapter).
76+
- `--allow_missing_builtins[=true|false]`: boolean flag with optional value. Allows running programs that reference builtins not present in the layout (will fail if the run actually uses them).
77+
- default: `false`
78+
- `--allow_missing_builtins` (without value) sets it to `true`
79+
- accepts `true/false/1/0`
80+
- `--dynamic_params_file`: required only when `--layout dynamic`. This is the path to the dynamic layout parameters JSON file.
81+
82+
## Outputs
83+
84+
- `--outputs_file`: JSON array of output segment felts (parsed from VM output as decimal felts).
85+
- `--execution_resources_file`: JSON-serialized execution resources.
86+
- `--cairo_pie_output`: Cairo PIE zip file (non-proof mode only).
87+
- `--air_public_input`: AIR public input JSON (proof mode only).
88+
- `--air_private_input`: AIR private input JSON referencing trace/memory file paths (proof mode only).
89+
- `--trace_file` / `--memory_file`: encoded (binary) trace/memory.
90+
91+
## Notes
92+
93+
If `--trace_file` / `--memory_file` are not provided in proof mode, temporary files are created and kept on disk, and their paths are embedded into the AIR private input.

‎crates/vm_runner/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# vm_runner (stwo_vm_runner)
2+
3+
Runs a compiled Cairo program in a proof-mode configuration, adapts the run result to a `stwo_cairo_adapter::ProverInput`, using stwo-cairo's adapter implementation and writes execution resources (and optionally the prover input) to disk.
4+
5+
Entry point: `crates/vm_runner/src/main.rs`
6+
7+
## Build & run
8+
9+
cargo run -p vm_runner -- --help
10+
11+
## Usage
12+
13+
Required flags:
14+
15+
- `--program <PATH>`: absolute path to compiled program
16+
- `--layout <LAYOUT>`: Cairo VM layout
17+
- `--output_execution_resources_path <PATH>`: absolute path to write execution resources JSON
18+
19+
- The options for `--layout` are: `plain`, `small`, `dex`, `recursive`, `starknet`, `starknet_with_keccak`, `recursive_large_output`, `recursive_with_poseidon`, `all_solidity`, `all_cairo`, `dynamic`, `all_cairo_stwo`, `perpetual`, `dex_with_bitwise`. See the `LayoutName` enum definition in `cairo-vm`.
20+
21+
Optional:
22+
23+
- `--program_input <PATH>`: absolute path to program input
24+
- `--output_prover_input_path <PATH>`: absolute path to write prover input JSON
25+
- `--secure_run`: enable Cairo VM secure_run mode
26+
27+
Example:
28+
cargo run -p vm_runner -- \
29+
--program /abs/path/to/compiled_program.json \
30+
--program_input /abs/path/to/program_input.json \
31+
--layout plain \
32+
--output_execution_resources_path /abs/path/to/execution_resources.json \
33+
--output_prover_input_path /abs/path/to/prover_input.json \
34+
--secure_run
35+
36+
## What it does
37+
38+
1. Runs the Cairo program with:
39+
- `proof_mode = true`
40+
- `trace_enabled = true`
41+
- `fill_holes = true`
42+
- `disable_trace_padding = true`
43+
- `relocate_mem = false`, `relocate_trace = false` (adapter handles relocation)
44+
2. Calls `stwo_cairo_adapter::adapter::adapt(&cairo_runner)` to produce `ProverInput`.
45+
3. Writes:
46+
- `ProverInput` (optional)
47+
- `ExecutionResources` (always)
48+
49+
## Output files
50+
51+
- Prover input (`--output_prover_input_path`): JSON serialization of `ProverInput`.
52+
- Execution resources (`--output_execution_resources_path`): JSON serialization of `ExecutionResources::from_prover_input(&prover_input)`.

0 commit comments

Comments
 (0)