feat: FastProcessor outputs a list of checkpoints

Author: plafer

CHANGELOG.md

@@ -33,6 +33,7 @@
 - [BREAKING] The serialized representation for `Package` was changed to include procedure type information. Older packages will not work with the new serialization code, and vice versa. The version of the binary format was incremented accordingly ([#2028](https://github.com/0xMiden/miden-vm/pull/2028)).
 - [BREAKING] Procedure-related metadata types in the `miden-assembly` crate in some cases now require an optional type signature argument. If that information is not available, you can simply pass `None` to retain current behavior ([#2028](https://github.com/0xMiden/miden-vm/pull/2028)).
 - Remove basic block clock cycle optimization from `FastProcessor` ([#2054](https://github.com/0xMiden/miden-vm/pull/2054)).
+- Added `FastProcessor::execute_for_trace()`, which outputs a series of checkpoints necessary to build the trace in parallel ([#2023](https://github.com/0xMiden/miden-vm/pull/2023))
 
 ## 0.16.4 (2025-07-24)
 

air/src/trace/rows.rs

@@ -19,7 +19,7 @@ pub enum RowIndexError {
 // ================================================================================================
 
 /// A newtype wrapper around a usize value representing a step in the execution trace.
-#[derive(Debug, Copy, Clone, Eq, Ord, PartialOrd)]
+#[derive(Debug, Default, Copy, Clone, Eq, Ord, PartialOrd)]
 pub struct RowIndex(u32);
 
 impl RowIndex {

processor/src/continuation_stack.rs

@@ -12,7 +12,7 @@ const CONTINUATION_STACK_SIZE_HINT: usize = 64;
 ///
 /// This enum defines the different types of continuations that can be performed on MAST nodes
 /// during program execution.
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub enum Continuation {
     /// Start processing a node in the MAST forest.
     StartNode(MastNodeId),
@@ -39,7 +39,7 @@ pub enum Continuation {
 /// This allows the processor to execute a program iteratively in a loop rather than recursively
 /// traversing the nodes. It also allows the processor to pass the state of execution to another
 /// processor for further processing, which is useful for parallel execution of MAST forests.
-#[derive(Debug)]
+#[derive(Debug, Default, Clone)]
 pub struct ContinuationStack {
     stack: Vec<Continuation>,
 }

processor/src/decoder/block_stack.rs

@@ -7,7 +7,7 @@ use crate::system::ContextId;
 // ================================================================================================
 
 /// Keeps track of code blocks which are currently being executed by the VM.
-#[derive(Debug, Default)]
+#[derive(Debug, Default, Clone)]
 pub struct BlockStack {
     blocks: Vec<BlockInfo>,
 }
@@ -98,7 +98,7 @@ impl BlockStack {
 // ================================================================================================
 
 /// Contains basic information about a code block.
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub struct BlockInfo {
     pub addr: Felt,
     block_type: BlockType,

processor/src/fast/checkpoints.rs

@@ -124,7 +124,7 @@ impl StackState {
 
     /// Derives the stack depth (b0 helper column) from the overflow table
     pub fn stack_depth(&self) -> Felt {
-        Felt::new((MIN_STACK_DEPTH + self.overflow.total_num_elements()) as u64)
+        Felt::new((MIN_STACK_DEPTH + self.overflow.num_elements_in_current_ctx()) as u64)
     }
 
     /// Derives the overflow address (b1 helper column) from the overflow table
@@ -136,6 +136,11 @@ impl StackState {
         self.overflow.num_elements_in_current_ctx()
     }
 
+    pub fn advance_clock(&mut self) {
+        // Advance the overflow table clock to the next row
+        self.overflow.advance_clock();
+    }
+
     pub fn push_overflow(&mut self, element: Felt) {
         self.overflow.push(element);
     }

processor/src/fast/circuit_eval.rs

@@ -1,7 +1,7 @@
 use miden_air::RowIndex;
 use miden_core::{Felt, FieldElement, QuadFelt};
 
-use super::{FastProcessor, memory::Memory};
+use super::{FastProcessor, memory::Memory, trace_state_builder::CoreTraceStateBuilder};
 use crate::{
     ContextId, ExecutionError,
     chiplets::{CircuitEvaluation, MAX_NUM_ACE_WIRES, PTR_OFFSET_ELEM, PTR_OFFSET_WORD},
@@ -32,9 +32,18 @@ impl FastProcessor {
         let num_read = self.stack_get(1);
         let ptr = self.stack_get(0);
         let ctx = self.ctx;
-        let circuit_evaluation =
-            eval_circuit_fast_(ctx, ptr, self.clk, num_read, num_eval, &mut self.memory, err_ctx)?;
-        self.ace.add_circuit_evaluation(self.clk, circuit_evaluation);
+        let clk = self.clk;
+        let circuit_evaluation = eval_circuit_fast_(
+            ctx,
+            ptr,
+            self.clk,
+            num_read,
+            num_eval,
+            &mut self.memory,
+            err_ctx,
+            &mut self.trace_state_builder,
+        )?;
+        self.ace.add_circuit_evaluation(clk, circuit_evaluation);
 
         Ok(())
     }
@@ -50,6 +59,7 @@ pub fn eval_circuit_fast_(
     num_eval: Felt,
     mem: &mut Memory,
     err_ctx: &impl ErrorContext,
+    trace_state_builder: &mut Option<CoreTraceStateBuilder>,
 ) -> Result<CircuitEvaluation, ExecutionError> {
     let num_vars = num_vars.as_int();
     let num_eval = num_eval.as_int();
@@ -87,14 +97,17 @@ pub fn eval_circuit_fast_(
     let mut ptr = ptr;
     // perform READ operations
     for _ in 0..num_read_rows {
-        let word = mem.read_word(ctx, ptr, clk, err_ctx).map_err(ExecutionError::MemoryError)?;
+        let word = mem
+            .read_word(ctx, ptr, clk, err_ctx, trace_state_builder)
+            .map_err(ExecutionError::MemoryError)?;
         evaluation_context.do_read(ptr, word)?;
         ptr += PTR_OFFSET_WORD;
     }
     // perform EVAL operations
     for _ in 0..num_eval_rows {
-        let instruction =
-            mem.read_element(ctx, ptr, err_ctx).map_err(ExecutionError::MemoryError)?;
+        let instruction = mem
+            .read_element(ctx, ptr, err_ctx, trace_state_builder)
+            .map_err(ExecutionError::MemoryError)?;
         evaluation_context.do_eval(ptr, instruction, err_ctx)?;
         ptr += PTR_OFFSET_ELEM;
     }

processor/src/fast/crypto_ops.rs

@@ -21,6 +21,10 @@ impl FastProcessor {
         };
 
         self.stack[state_range].copy_from_slice(&hashed_state);
+
+        if let Some(trace_state_builder) = &mut self.trace_state_builder {
+            trace_state_builder.hasher.record_permute(hashed_state);
+        }
     }
 
     /// Analogous to `Process::op_mpverify`.
@@ -42,6 +46,10 @@ impl FastProcessor {
             .get_merkle_path(root, &depth, &index)
             .map_err(|err| ExecutionError::advice_error(err, self.clk, err_ctx))?;
 
+        if let Some(trace_state_builder) = &mut self.trace_state_builder {
+            trace_state_builder.hasher.record_build_merkle_root(&path, root);
+        }
+
         // verify the path
         match path.verify(index.as_int(), node, &root) {
             Ok(_) => Ok(()),
@@ -84,6 +92,10 @@ impl FastProcessor {
         // Replace the old node value with computed new root; everything else remains the same.
         self.stack_write_word(0, &new_root);
 
+        if let Some(trace_state_builder) = &mut self.trace_state_builder {
+            trace_state_builder.hasher.record_update_merkle_root(&path, old_root, new_root);
+        }
+
         Ok(())
     }
 }

processor/src/fast/horner_ops.rs

@@ -107,7 +107,7 @@ impl FastProcessor {
             let addr = self.stack_get(ALPHA_ADDR_INDEX);
             let word = self
                 .memory
-                .read_word(self.ctx, addr, self.clk, err_ctx)
+                .read_word(self.ctx, addr, self.clk, err_ctx, &mut self.trace_state_builder)
                 .map_err(ExecutionError::MemoryError)?;
 
             (word[0], word[1])

processor/src/fast/io_ops.rs

@@ -11,22 +11,37 @@ impl FastProcessor {
     /// Analogous to `Process::op_advpop`.
     #[inline(always)]
     pub fn op_advpop(&mut self, err_ctx: &impl ErrorContext) -> Result<(), ExecutionError> {
-        let value = self
-            .advice
-            .pop_stack()
-            .map_err(|err| ExecutionError::advice_error(err, self.clk, err_ctx))?;
+        let value = {
+            let value = self
+                .advice
+                .pop_stack()
+                .map_err(|err| ExecutionError::advice_error(err, self.clk, err_ctx))?;
+            if let Some(trace_state_builder) = &mut self.trace_state_builder {
+                trace_state_builder.advice.record_pop_stack(value);
+            }
+            value
+        };
+
         self.increment_stack_size();
         self.stack_write(0, value);
+
         Ok(())
     }
 
     /// Analogous to `Process::op_advpopw`.
     #[inline(always)]
     pub fn op_advpopw(&mut self, err_ctx: &impl ErrorContext) -> Result<(), ExecutionError> {
-        let word = self
-            .advice
-            .pop_stack_word()
-            .map_err(|err| ExecutionError::advice_error(err, self.clk, err_ctx))?;
+        let word = {
+            let word = self
+                .advice
+                .pop_stack_word()
+                .map_err(|err| ExecutionError::advice_error(err, self.clk, err_ctx))?;
+            if let Some(trace_state_builder) = &mut self.trace_state_builder {
+                trace_state_builder.advice.record_pop_stack_word(word);
+            }
+            word
+        };
+
         self.stack_write_word(0, &word);
 
         Ok(())
@@ -40,7 +55,7 @@ impl FastProcessor {
 
         let word = self
             .memory
-            .read_word(self.ctx, addr, self.clk, err_ctx)
+            .read_word(self.ctx, addr, self.clk, err_ctx, &mut self.trace_state_builder)
             .map_err(ExecutionError::MemoryError)?;
         self.stack_write_word(0, &word);
 
@@ -66,7 +81,7 @@ impl FastProcessor {
         let element = {
             let addr = self.stack_get(0);
             self.memory
-                .read_element(self.ctx, addr, err_ctx)
+                .read_element(self.ctx, addr, err_ctx, &mut self.trace_state_builder)
                 .map_err(ExecutionError::MemoryError)?
         };
 
@@ -100,10 +115,22 @@ impl FastProcessor {
         let addr_second_word = addr_first_word + WORD_SIZE_FELT;
         let words = [
             self.memory
-                .read_word(self.ctx, addr_first_word, self.clk, err_ctx)
+                .read_word(
+                    self.ctx,
+                    addr_first_word,
+                    self.clk,
+                    err_ctx,
+                    &mut self.trace_state_builder,
+                )
                 .map_err(ExecutionError::MemoryError)?,
             self.memory
-                .read_word(self.ctx, addr_second_word, self.clk, err_ctx)
+                .read_word(
+                    self.ctx,
+                    addr_second_word,
+                    self.clk,
+                    err_ctx,
+                    &mut self.trace_state_builder,
+                )
                 .map_err(ExecutionError::MemoryError)?,
         ];
 
@@ -133,6 +160,10 @@ impl FastProcessor {
             .pop_stack_dword()
             .map_err(|err| ExecutionError::advice_error(err, self.clk, err_ctx))?;
 
+        if let Some(trace_state_builder) = &mut self.trace_state_builder {
+            trace_state_builder.advice.record_pop_stack_dword(words);
+        }
+
         // write the words to memory
         self.memory
             .write_word(self.ctx, addr_first_word, self.clk, words[0], err_ctx)

processor/src/fast/memory.rs

@@ -3,7 +3,10 @@ use alloc::{collections::BTreeMap, vec::Vec};
 use miden_air::RowIndex;
 use miden_core::{EMPTY_WORD, Felt, WORD_SIZE, Word, ZERO};
 
-use crate::{ContextId, ErrorContext, MemoryAddress, MemoryError};
+use crate::{
+    ContextId, ErrorContext, MemoryAddress, MemoryError,
+    fast::trace_state_builder::CoreTraceStateBuilder,
+};
 
 /// The memory for the processor.
 ///
@@ -30,8 +33,14 @@ impl Memory {
         ctx: ContextId,
         addr: Felt,
         err_ctx: &impl ErrorContext,
+        trace_state_builder: &mut Option<CoreTraceStateBuilder>,
     ) -> Result<Felt, MemoryError> {
         let element = self.read_element_impl(ctx, clean_addr(addr, err_ctx)?).unwrap_or(ZERO);
+
+        if let Some(trace_state_builder) = trace_state_builder {
+            trace_state_builder.memory.record_element(element, addr);
+        }
+
         Ok(element)
     }
 
@@ -46,10 +55,15 @@ impl Memory {
         addr: Felt,
         clk: RowIndex,
         err_ctx: &impl ErrorContext,
+        trace_state_builder: &mut Option<CoreTraceStateBuilder>,
     ) -> Result<Word, MemoryError> {
         let addr = clean_addr(addr, err_ctx)?;
         let word = self.read_word_impl(ctx, addr, Some(clk), err_ctx)?.unwrap_or(EMPTY_WORD);
 
+        if let Some(trace_state_builder) = trace_state_builder {
+            trace_state_builder.memory.record_word(word, addr.into());
+        }
+
         Ok(word)
     }