miden_processor/host/
mod.rs

1use alloc::{sync::Arc, vec::Vec};
2use core::future::Future;
3
4use miden_core::{
5    AdviceMap, DebugOptions, EventId, EventName, Felt, Word, crypto::merkle::InnerNodeInfo,
6    mast::MastForest, precompile::PrecompileRequest,
7};
8use miden_debug_types::{Location, SourceFile, SourceSpan};
9
10use crate::{EventError, ExecutionError, ProcessState};
11
12pub(super) mod advice;
13
14pub mod debug;
15
16pub mod default;
17
18pub mod handlers;
19use handlers::DebugHandler;
20
21mod mast_forest_store;
22pub use mast_forest_store::{MastForestStore, MemMastForestStore};
23
24// ADVICE MAP MUTATIONS
25// ================================================================================================
26
27/// Any possible way an event can modify the advice provider.
28#[derive(Debug, PartialEq, Eq)]
29pub enum AdviceMutation {
30    ExtendStack { values: Vec<Felt> },
31    ExtendMap { other: AdviceMap },
32    ExtendMerkleStore { infos: Vec<InnerNodeInfo> },
33    ExtendPrecompileRequests { data: Vec<PrecompileRequest> },
34}
35
36impl AdviceMutation {
37    pub fn extend_stack(iter: impl IntoIterator<Item = Felt>) -> Self {
38        Self::ExtendStack { values: Vec::from_iter(iter) }
39    }
40
41    pub fn extend_map(other: AdviceMap) -> Self {
42        Self::ExtendMap { other }
43    }
44
45    pub fn extend_merkle_store(infos: impl IntoIterator<Item = InnerNodeInfo>) -> Self {
46        Self::ExtendMerkleStore { infos: Vec::from_iter(infos) }
47    }
48
49    pub fn extend_precompile_requests(data: impl IntoIterator<Item = PrecompileRequest>) -> Self {
50        Self::ExtendPrecompileRequests { data: Vec::from_iter(data) }
51    }
52}
53// HOST TRAIT
54// ================================================================================================
55
56/// Defines the common interface between [SyncHost] and [AsyncHost], by which the VM can interact
57/// with the host.
58///
59/// There are three main categories of interactions between the VM and the host:
60/// 1. getting a library's MAST forest,
61/// 2. handling VM events (which can mutate the process' advice provider), and
62/// 3. handling debug and trace events.
63pub trait BaseHost {
64    // REQUIRED METHODS
65    // --------------------------------------------------------------------------------------------
66
67    /// Returns the [`SourceSpan`] and optional [`SourceFile`] for the provided location.
68    fn get_label_and_source_file(
69        &self,
70        location: &Location,
71    ) -> (SourceSpan, Option<Arc<SourceFile>>);
72
73    /// Handles the debug request from the VM.
74    fn on_debug(
75        &mut self,
76        process: &mut ProcessState,
77        options: &DebugOptions,
78    ) -> Result<(), ExecutionError> {
79        let mut handler = debug::DefaultDebugHandler::default();
80        handler.on_debug(process, options)
81    }
82
83    /// Handles the trace emitted from the VM.
84    fn on_trace(
85        &mut self,
86        process: &mut ProcessState,
87        trace_id: u32,
88    ) -> Result<(), ExecutionError> {
89        let mut handler = debug::DefaultDebugHandler::default();
90        handler.on_trace(process, trace_id)
91    }
92
93    /// Handles the failure of the assertion instruction.
94    fn on_assert_failed(&mut self, _process: &ProcessState, _err_code: Felt) {}
95
96    /// Returns the [`EventName`] registered for the provided [`EventId`], if any.
97    ///
98    /// Hosts that maintain an event registry can override this method to surface human-readable
99    /// names for diagnostics. The default implementation returns `None`.
100    fn resolve_event(&self, _event_id: EventId) -> Option<&EventName> {
101        None
102    }
103}
104
105/// Defines an interface by which the VM can interact with the host.
106///
107/// There are four main categories of interactions between the VM and the host:
108/// 1. accessing the advice provider,
109/// 2. getting a library's MAST forest,
110/// 3. handling VM events (which can mutate the process' advice provider), and
111/// 4. handling debug and trace events.
112pub trait SyncHost: BaseHost {
113    // REQUIRED METHODS
114    // --------------------------------------------------------------------------------------------
115
116    /// Returns MAST forest corresponding to the specified digest, or None if the MAST forest for
117    /// this digest could not be found in this host.
118    fn get_mast_forest(&self, node_digest: &Word) -> Option<Arc<MastForest>>;
119
120    /// Invoked when the VM encounters an `EMIT` operation.
121    ///
122    /// The event ID is available at the top of the stack (position 0) when this handler is called.
123    /// This allows the handler to access both the event ID and any additional context data that
124    /// may have been pushed onto the stack prior to the emit operation.
125    ///
126    /// ## Implementation notes
127    /// - Extract the event ID via `EventId::from_felt(process.get_stack_item(0))`
128    /// - Return errors without event names or IDs - the p will enrich them via
129    ///   [`BaseHost::resolve_event()`]
130    /// - System events (IDs 0-255) are handled by the VM before calling this method
131    fn on_event(&mut self, process: &ProcessState) -> Result<Vec<AdviceMutation>, EventError>;
132}
133
134// ASYNC HOST trait
135// ================================================================================================
136
137/// Analogous to the [SyncHost] trait, but designed for asynchronous execution contexts.
138pub trait AsyncHost: BaseHost {
139    // REQUIRED METHODS
140    // --------------------------------------------------------------------------------------------
141
142    // Note: we don't use the `async` keyword in this method, since we need to specify the `+ Send`
143    // bound to the returned Future, and `async` doesn't allow us to do that.
144
145    /// Returns MAST forest corresponding to the specified digest, or None if the MAST forest for
146    /// this digest could not be found in this host.
147    fn get_mast_forest(&self, node_digest: &Word) -> impl FutureMaybeSend<Option<Arc<MastForest>>>;
148
149    /// Handles the event emitted from the VM and provides advice mutations to be applied to
150    /// the advice provider.
151    ///
152    /// The event ID is available at the top of the stack (position 0) when this handler is called.
153    /// This allows the handler to access both the event ID and any additional context data that
154    /// may have been pushed onto the stack prior to the emit operation.
155    ///
156    /// ## Implementation notes
157    /// - Extract the event ID via `EventId::from_felt(process.get_stack_item(0))`
158    /// - Return errors without event names or IDs - the caller will enrich them via
159    ///   [`BaseHost::resolve_event()`]
160    /// - System events (IDs 0-255) are handled by the VM before calling this method
161    fn on_event(
162        &mut self,
163        process: &ProcessState<'_>,
164    ) -> impl FutureMaybeSend<Result<Vec<AdviceMutation>, EventError>>;
165}
166
167/// Alias for a `Future`
168///
169/// Unless the compilation target family is `wasm`, we add `Send` to the required bounds. For
170/// `wasm` compilation targets there is no `Send` bound.
171///
172/// We also provide a blank implementation of this trait for all features.
173#[cfg(target_family = "wasm")]
174pub trait FutureMaybeSend<O>: Future<Output = O> {}
175
176#[cfg(target_family = "wasm")]
177impl<T, O> FutureMaybeSend<O> for T where T: Future<Output = O> {}
178
179/// Alias for a `Future`
180///
181/// Unless the compilation target family is `wasm`, we add `Send` to the required bounds. For
182/// `wasm` compilation targets there is no `Send` bound.
183///
184/// We also provide a blank implementation of this trait for all features.
185#[cfg(not(target_family = "wasm"))]
186pub trait FutureMaybeSend<O>: Future<Output = O> + Send {}
187
188#[cfg(not(target_family = "wasm"))]
189impl<T, O> FutureMaybeSend<O> for T where T: Future<Output = O> + Send {}
miden_processor/host/mod.rs

miden_processor/host/
mod.rs
