cairo_program_runner_lib/
lib.rs

1use cairo_vm::cairo_run::{cairo_run_program_with_initial_scope, CairoRunConfig};
2use cairo_vm::hint_processor::hint_processor_definition::HintProcessor;
3use cairo_vm::types::exec_scope::ExecutionScopes;
4use cairo_vm::types::program::Program;
5use cairo_vm::vm::errors::cairo_run_errors::CairoRunError;
6use cairo_vm::vm::runners::cairo_runner::CairoRunner;
7pub use hints::*;
8use tracing::{span, Level};
9
10pub mod hints;
11pub mod tasks;
12pub mod test_utils;
13pub mod utils;
14pub use utils::ProgramInput;
15
16/// Executes a Cairo program with the given configuration, optionally handling program input and
17/// proof mode.
18///
19/// # Arguments
20/// - `program`: A reference to a `Program` object that represents the compiled Cairo program to
21///   run.
22/// - `program_input`: An optional program input source. If `Some`, the input is injected into the
23///   execution scope under the key `"program_input"` and later decoded by hints into the concrete
24///   type the hints expect (e.g. `SimpleProgramInput`).
25/// - `layout`: A `LayoutName` specifying the Cairo layout to use in the VM (e.g., `plain`,
26///   `all_cairo`).
27/// - `dynamic_layout_params`: An optional `CairoLayoutParams` providing dynamic parameters for the
28///   layout. This is used only if the `dynamic` layout is selected.
29/// - `proof_mode`: A `bool` indicating whether to run the program in proof mode (`true`) or
30///   validation mode (`false`).
31///
32/// # Returns
33/// - `Ok(CairoRunner)`: If the program runs successfully, returns the `CairoRunner` instance
34///   containing the execution state.
35/// - `Err(CairoRunError)`: If an error occurs during execution, returns a `CairoRunError`
36///   describing the problem.
37#[allow(clippy::result_large_err)]
38pub fn cairo_run_program(
39    program: &Program,
40    program_input: Option<ProgramInput>,
41    cairo_run_config: CairoRunConfig<'_>,
42    extra_hint_processor: Option<&mut dyn HintProcessor>,
43) -> Result<CairoRunner, CairoRunError> {
44    let _span = span!(Level::INFO, "cairo_run_program").entered();
45
46    let mut hint_processor = BootloaderHintProcessor::new(extra_hint_processor);
47
48    let mut exec_scopes = ExecutionScopes::new();
49
50    if let Some(program_input) = program_input {
51        // Insert the program input into the execution scopes if exists
52        exec_scopes.insert_value(PROGRAM_INPUT, program_input);
53    }
54
55    // Insert the program object into the execution scopes
56    exec_scopes.insert_value(PROGRAM_OBJECT, program.clone());
57
58    // Run the program with the configured execution scopes and cairo_run_config
59    let runner = cairo_run_program_with_initial_scope(
60        program,
61        &cairo_run_config,
62        &mut hint_processor,
63        exec_scopes,
64    )?;
65
66    Ok(runner)
67}
cairo_program_runner_lib/lib.rs

cairo_program_runner_lib/
lib.rs
