cairo-program-runner-lib 1.2.2

Library for running Cairo programs on the Cairo VM with hint support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

use cairo_vm::cairo_run::{cairo_run_program_with_initial_scope, CairoRunConfig};
use cairo_vm::hint_processor::hint_processor_definition::HintProcessor;
use cairo_vm::types::exec_scope::ExecutionScopes;
use cairo_vm::types::program::Program;
use cairo_vm::vm::errors::cairo_run_errors::CairoRunError;
use cairo_vm::vm::runners::cairo_runner::CairoRunner;
pub use hints::*;
use tracing::{span, Level};

pub mod hints;
pub mod tasks;
pub mod test_utils;
pub mod utils;
pub use utils::ProgramInput;

/// Executes a Cairo program with the given configuration, optionally handling program input and
/// proof mode.
///
/// # Arguments
/// - `program`: A reference to a `Program` object that represents the compiled Cairo program to
///   run.
/// - `program_input`: An optional program input source. If `Some`, the input is injected into the
///   execution scope under the key `"program_input"` and later decoded by hints into the concrete
///   type the hints expect (e.g. `SimpleProgramInput`).
/// - `layout`: A `LayoutName` specifying the Cairo layout to use in the VM (e.g., `plain`,
///   `all_cairo`).
/// - `dynamic_layout_params`: An optional `CairoLayoutParams` providing dynamic parameters for the
///   layout. This is used only if the `dynamic` layout is selected.
/// - `proof_mode`: A `bool` indicating whether to run the program in proof mode (`true`) or
///   validation mode (`false`).
///
/// # Returns
/// - `Ok(CairoRunner)`: If the program runs successfully, returns the `CairoRunner` instance
///   containing the execution state.
/// - `Err(CairoRunError)`: If an error occurs during execution, returns a `CairoRunError`
///   describing the problem.
#[allow(clippy::result_large_err)]
pub fn cairo_run_program(
    program: &Program,
    program_input: Option<ProgramInput>,
    cairo_run_config: CairoRunConfig<'_>,
    extra_hint_processor: Option<&mut dyn HintProcessor>,
) -> Result<CairoRunner, CairoRunError> {
    let _span = span!(Level::INFO, "cairo_run_program").entered();

    let mut hint_processor = BootloaderHintProcessor::new(extra_hint_processor);

    let mut exec_scopes = ExecutionScopes::new();

    if let Some(program_input) = program_input {
        // Insert the program input into the execution scopes if exists
        exec_scopes.insert_value(PROGRAM_INPUT, program_input);
    }

    // Insert the program object into the execution scopes
    exec_scopes.insert_value(PROGRAM_OBJECT, program.clone());

    // Run the program with the configured execution scopes and cairo_run_config
    let runner = cairo_run_program_with_initial_scope(
        program,
        &cairo_run_config,
        &mut hint_processor,
        exec_scopes,
    )?;

    Ok(runner)
}