miden_debug_engine/exec/
diagnostic.rs

1use std::{sync::Arc, vec::Vec};
2
3use miden_core::{Word, operations::DebugOptions, program::Program};
4use miden_processor::{
5    ExecutionError, ExecutionOptions, ExecutionOutput, FastProcessor, Felt, FutureMaybeSend, Host,
6    ProcessorState, StackInputs, TraceError,
7    advice::{AdviceInputs, AdviceMutation},
8    event::EventError,
9    mast::MastForest,
10    trace::RowIndex,
11};
12
13use super::{ProgramExecutor, TraceEvent};
14
15// DIAGNOSTIC HOST WRAPPER
16// ================================================================================================
17
18/// A host wrapper that intercepts trace events to track call frames and processor state,
19/// while delegating all other operations to the inner host.
20///
21/// This enables capturing diagnostic information during transaction execution (or any program
22/// execution) without modifying the inner host.
23struct DiagnosticHostWrapper<'a, H: Host> {
24    inner: &'a mut H,
25    /// Call depth tracked from FrameStart/FrameEnd trace events.
26    call_depth: usize,
27    /// Stack state captured at the last trace or event callback.
28    last_stack_state: Vec<Felt>,
29    /// Clock cycle at the last trace or event callback.
30    last_cycle: RowIndex,
31}
32
33impl<'a, H: Host> DiagnosticHostWrapper<'a, H> {
34    fn new(inner: &'a mut H) -> Self {
35        Self {
36            inner,
37            call_depth: 0,
38            last_stack_state: Vec::new(),
39            last_cycle: RowIndex::from(0u32),
40        }
41    }
42
43    /// Report diagnostic information when an execution error occurs.
44    fn report_diagnostics(&self, err: &ExecutionError) {
45        eprintln!("\n=== Transaction Execution Failed ===");
46        eprintln!("Error: {err}");
47        eprintln!("Last known cycle: {}", self.last_cycle);
48        eprintln!("Call depth at failure: {}", self.call_depth);
49
50        if !self.last_stack_state.is_empty() {
51            let stack_display: Vec<_> =
52                self.last_stack_state.iter().take(16).map(|f| f.as_canonical_u64()).collect();
53            eprintln!("Last known stack state (top 16): {stack_display:?}");
54        }
55
56        eprintln!("====================================\n");
57    }
58
59    fn capture_state(&mut self, process: &ProcessorState<'_>) {
60        self.last_stack_state = process.get_stack_state();
61        self.last_cycle = process.clock();
62    }
63}
64
65impl<H: Host> Host for DiagnosticHostWrapper<'_, H> {
66    fn get_label_and_source_file(
67        &self,
68        location: &miden_debug_types::Location,
69    ) -> (miden_debug_types::SourceSpan, Option<Arc<miden_debug_types::SourceFile>>) {
70        self.inner.get_label_and_source_file(location)
71    }
72
73    fn get_mast_forest(&self, node_digest: &Word) -> impl FutureMaybeSend<Option<Arc<MastForest>>> {
74        self.inner.get_mast_forest(node_digest)
75    }
76
77    fn on_event(
78        &mut self,
79        process: &ProcessorState<'_>,
80    ) -> impl FutureMaybeSend<Result<Vec<AdviceMutation>, EventError>> {
81        self.capture_state(process);
82        self.inner.on_event(process)
83    }
84
85    fn on_debug(
86        &mut self,
87        process: &ProcessorState<'_>,
88        options: &DebugOptions,
89    ) -> Result<(), miden_processor::DebugError> {
90        self.inner.on_debug(process, options)
91    }
92
93    fn on_trace(&mut self, process: &ProcessorState<'_>, trace_id: u32) -> Result<(), TraceError> {
94        self.capture_state(process);
95
96        let event = TraceEvent::from(trace_id);
97        match event {
98            TraceEvent::FrameStart => self.call_depth += 1,
99            TraceEvent::FrameEnd => self.call_depth = self.call_depth.saturating_sub(1),
100            _ => {}
101        }
102
103        self.inner.on_trace(process, trace_id)
104    }
105
106    fn resolve_event(
107        &self,
108        event_id: miden_core::events::EventId,
109    ) -> Option<&miden_core::events::EventName> {
110        self.inner.resolve_event(event_id)
111    }
112}
113
114// DIAGNOSTIC EXECUTOR
115// ================================================================================================
116
117/// A [`ProgramExecutor`] that wraps [`FastProcessor`] with diagnostic capabilities.
118///
119/// When execution fails, it captures and reports rich diagnostic information including:
120/// - The clock cycle at failure
121/// - The call depth (from trace events)
122/// - The last known operand stack state
123///
124/// This executor is intended for use with [`TransactionExecutor`] to provide better error
125/// diagnostics when transactions fail during testing or development.
126///
127/// # Usage
128///
129/// ```ignore
130/// use miden_tx::TransactionExecutor;
131/// use miden_debug::DiagnosticExecutor;
132///
133/// let executor = TransactionExecutor::new(&store)
134///     .with_program_executor::<DiagnosticExecutor>()
135///     .execute_transaction(account_id, block_num, notes, tx_args)
136///     .await;
137/// ```
138pub struct DiagnosticExecutor {
139    stack_inputs: StackInputs,
140    advice_inputs: AdviceInputs,
141    options: ExecutionOptions,
142}
143
144impl ProgramExecutor for DiagnosticExecutor {
145    fn new(
146        stack_inputs: StackInputs,
147        advice_inputs: AdviceInputs,
148        options: ExecutionOptions,
149    ) -> Self {
150        DiagnosticExecutor {
151            stack_inputs,
152            advice_inputs,
153            options,
154        }
155    }
156
157    fn execute<H: Host + Send>(
158        self,
159        program: &Program,
160        host: &mut H,
161    ) -> impl FutureMaybeSend<Result<ExecutionOutput, ExecutionError>> {
162        async move {
163            // Enable debugging and tracing for richer diagnostics.
164            let options = self.options.with_debugging(true).with_tracing(true);
165            let processor = FastProcessor::new(self.stack_inputs)
166                .with_advice(self.advice_inputs)
167                .with_options(options);
168
169            let mut wrapper = DiagnosticHostWrapper::new(host);
170
171            match processor.execute(program, &mut wrapper).await {
172                Ok(output) => Ok(output),
173                Err(err) => {
174                    wrapper.report_diagnostics(&err);
175                    Err(err)
176                }
177            }
178        }
179    }
180}
miden_debug_engine/exec/diagnostic.rs

miden_debug_engine/exec/
diagnostic.rs
