Trait Host 

pub trait Host {
    // Required methods
    fn get_label_and_source_file(
        &self,
        location: &Location,
    ) -> (SourceSpan, Option<Arc<SourceFile>>);
    fn get_mast_forest(
        &self,
        node_digest: &Word,
    ) -> impl FutureMaybeSend<Option<Arc<MastForest>>>;
    fn on_event(
        &mut self,
        process: &ProcessorState<'_>,
    ) -> impl FutureMaybeSend<Result<Vec<AdviceMutation>, EventError>>;

    // Provided methods
    fn on_debug(
        &mut self,
        process: &ProcessorState<'_>,
        options: &DebugOptions,
    ) -> Result<(), DebugError> { ... }
    fn on_trace(
        &mut self,
        process: &ProcessorState<'_>,
        trace_id: u32,
    ) -> Result<(), TraceError> { ... }
    fn resolve_event(&self, _event_id: EventId) -> Option<&EventName> { ... }
}

Defines an interface by which the VM can interact with the host.

There are three main categories of interactions between the VM and the host:

1. getting a library’s MAST forest,
2. handling VM events (which can mutate the process’ advice provider), and
3. handling debug and trace events.

Required Methods

fn get_label_and_source_file( &self, location: &Location, ) -> (SourceSpan, Option<Arc<SourceFile>>)

Returns the SourceSpan and optional SourceFile for the provided location.

fn get_mast_forest( &self, node_digest: &Word, ) -> impl FutureMaybeSend<Option<Arc<MastForest>>>

Returns MAST forest corresponding to the specified digest, or None if the MAST forest for this digest could not be found in this host.

fn on_event( &mut self, process: &ProcessorState<'_>, ) -> impl FutureMaybeSend<Result<Vec<AdviceMutation>, EventError>>

Handles the event emitted from the VM and provides advice mutations to be applied to the advice provider.

The event ID is available at the top of the stack (position 0) when this handler is called. This allows the handler to access both the event ID and any additional context data that may have been pushed onto the stack prior to the emit operation.

Implementation notes

• Extract the event ID via EventId::from_felt(process.get_stack_item(0))
• Return errors without event names or IDs - the caller will enrich them via Host::resolve_event()
• System events (IDs 0-255) are handled by the VM before calling this method

Provided Methods

fn on_debug( &mut self, process: &ProcessorState<'_>, options: &DebugOptions, ) -> Result<(), DebugError>

Handles the debug request from the VM.

fn on_trace( &mut self, process: &ProcessorState<'_>, trace_id: u32, ) -> Result<(), TraceError>

Handles the trace emitted from the VM.

fn resolve_event(&self, _event_id: EventId) -> Option<&EventName>

Returns the EventName registered for the provided EventId, if any.

Hosts that maintain an event registry can override this method to surface human-readable names for diagnostics. The default implementation returns None.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<D, S> Host for DefaultHost<D, S>

where D: DebugHandler, S: SourceManager,