cairo_program_runner_lib/
lib.rs

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

cairo_program_runner_lib/
lib.rs
