feat(starknet_os): initial API definition, execution helper (#3946)

crates/starknet_os/Cargo.toml

@@ -10,6 +10,7 @@ description = "The Starknet OS."
 testing = ["dep:strum", "dep:strum_macros"]
 
 [dependencies]
+blockifier.workspace = true
 cairo-vm.workspace = true
 indoc.workspace = true
 starknet-types-core.workspace = true

crates/starknet_os/src/errors.rs

@@ -0,0 +1,2 @@
+#[derive(Debug, thiserror::Error)]
+pub enum StarknetOsError {}

crates/starknet_os/src/hint_processor.rs

@@ -0,0 +1 @@
+pub mod execution_helper;

crates/starknet_os/src/hint_processor/execution_helper.rs

@@ -0,0 +1,20 @@
+use blockifier::state::cached_state::CachedState;
+use blockifier::state::state_api::StateReader;
+
+use crate::io::os_input::StarknetOsInput;
+
+/// A helper struct that provides access to the OS state and commitments.
+pub struct OsExecutionHelper<S: StateReader> {
+    _cached_state: CachedState<S>,
+}
+
+impl<S: StateReader> OsExecutionHelper<S> {
+    pub fn new(os_input: &StarknetOsInput) -> Self {
+        Self { _cached_state: Self::initialize_cached_state(os_input) }
+    }
+
+    // TODO(Dori): Create a cached state with all initial read values from the OS input.
+    fn initialize_cached_state(_os_input: &StarknetOsInput) -> CachedState<S> {
+        todo!()
+    }
+}

crates/starknet_os/src/io.rs

@@ -0,0 +1,2 @@
+pub mod os_input;
+pub mod os_output;

crates/starknet_os/src/io/os_input.rs

@@ -0,0 +1,4 @@
+/// All input needed to initialize the execution helper.
+// TODO(Dori): Add all fields needed to compute commitments, initialize a CachedState and other data
+//   required by the execution helper.
+pub struct StarknetOsInput {}

crates/starknet_os/src/io/os_output.rs

@@ -0,0 +1,9 @@
+use cairo_vm::vm::runners::cairo_pie::CairoPie;
+
+// TODO(Dori): Add fields.
+pub struct StarknetOsOutput {}
+
+pub struct StarknetOsRunnerOutput {
+    pub os_output: StarknetOsOutput,
+    pub cairo_pie: CairoPie,
+}

crates/starknet_os/src/lib.rs

@@ -1 +1,5 @@
+pub mod errors;
+pub mod hint_processor;
 pub mod hints;
+pub mod io;
+pub mod runner;

crates/starknet_os/src/runner.rs

@@ -0,0 +1,18 @@
+use blockifier::context::BlockContext;
+use blockifier::state::state_api::StateReader;
+use cairo_vm::types::layout_name::LayoutName;
+
+use crate::errors::StarknetOsError;
+use crate::hint_processor::execution_helper::OsExecutionHelper;
+use crate::io::os_input::StarknetOsInput;
+use crate::io::os_output::StarknetOsRunnerOutput;
+
+pub fn run_os<S: StateReader>(
+    _compiled_os: &[u8],
+    _layout: LayoutName,
+    _block_context: BlockContext,
+    os_input: &StarknetOsInput,
+) -> Result<StarknetOsRunnerOutput, StarknetOsError> {
+    let _execution_helper = OsExecutionHelper::<S>::new(os_input);
+    todo!()
+}