Merge branch 'next' into al-gkr-circuit

CHANGELOG.md

@@ -1,6 +1,26 @@
 # Changelog
 
-## 0.9.0 (TBD)
+## 0.10.0 (TBD)
+
+#### Enhancements
+
+- Added error codes support for the `mtree_verify` instruction (#1328).
+- Added support for immediate values for `lt`, `lte`, `gt`, `gte` comparison instructions (#1346).
+
+## 0.9.2 (2024-05-22) - `stdlib` crate only
+- Skip writing MASM documentation to file when building on docs.rs (#1341).
+
+## 0.9.2 (2024-05-09) - `assembly` crate only
+- Remove usage of `group_vector_elements()` from `combine_blocks()` (#1331).
+
+## 0.9.2 (2024-04-25) - `air` and `processor` crates only
+- Allowed enabling debug mode via `ExecutionOptions` (#1316).
+
+## 0.9.1 (2024-04-04)
+
+- Added additional trait implementations to error types (#1306).
+
+## 0.9.0 (2024-04-03)
 
 #### Packaging
 - [BREAKING] The package `miden-vm` crate was renamed from `miden` to `miden-vm`. Now the package and crate names match (#1271).

README.md

@@ -17,7 +17,7 @@ Miden VM is a zero-knowledge virtual machine written in Rust. For any program ex
 * If you'd like to learn more about STARKs, check out the [references](#references) section.
 
 ### Status and features
-Miden VM is currently on release v0.8. In this release, most of the core features of the VM have been stabilized, and most of the STARK proof generation has been implemented. While we expect to keep making changes to the VM internals, the external interfaces should remain relatively stable, and we will do our best to minimize the amount of breaking changes going forward.
+Miden VM is currently on release v0.9. In this release, most of the core features of the VM have been stabilized, and most of the STARK proof generation has been implemented. While we expect to keep making changes to the VM internals, the external interfaces should remain relatively stable, and we will do our best to minimize the amount of breaking changes going forward.
 
 The next version of the VM is being developed in the [next](https://github.com/0xPolygonMiden/miden-vm/tree/next) branch. There is also a documentation for the latest features and changes in the next branch [documentation next branch](https://0xpolygonmiden.github.io/miden-vm/intro/main.html).
 

air/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "miden-air"
-version = "0.8.0"
+version = "0.9.2"
 description = "Algebraic intermediate representation of Miden VM processor"
 authors = ["miden contributors"]
 readme = "README.md"
 license = "MIT"
 repository = "https://github.com/0xPolygonMiden/miden-vm"
-documentation = "https://docs.rs/miden-air/0.8.0"
+documentation = "https://docs.rs/miden-air/0.9.2"
 categories = ["cryptography", "no-std"]
 keywords = ["air", "arithmetization", "crypto", "miden"]
 edition = "2021"
@@ -30,7 +30,7 @@ std = ["vm-core/std", "winter-air/std"]
 internals = []
 
 [dependencies]
-vm-core = { package = "miden-core", path = "../core", version = "0.8", default-features = false }
+vm-core = { package = "miden-core", path = "../core", version = "0.9", default-features = false }
 winter-air = { package = "winter-air", version = "0.9", default-features = false }
 winter-prover = { package = "winter-prover", version = "0.9", default-features = false }
 

air/src/constraints/chiplets/hasher/mod.rs

@@ -101,9 +101,9 @@ pub fn get_transition_constraint_count() -> usize {
 /// Enforces constraints for the hasher chiplet.
 ///
 /// - The `hasher_flag` determines if the hasher chiplet is currently enabled. It should be
-/// computed by the caller and set to `Felt::ONE`
+///   computed by the caller and set to `Felt::ONE`
 /// - The `transition_flag` indicates whether this is the last row this chiplet's execution trace,
-/// and therefore the constraints should not be enforced.
+///   and therefore the constraints should not be enforced.
 pub fn enforce_constraints<E: FieldElement<BaseField = Felt>>(
     frame: &EvaluationFrame<E>,
     periodic_values: &[E],

air/src/constraints/stack/field_ops/mod.rs

@@ -188,7 +188,7 @@ pub fn enforce_incr_constraints<E: FieldElement>(
 /// enforced:
 /// - The top element should be a binary. It is enforced as a general constraint.
 /// - The first element of the next frame should be a binary not of the first element of
-/// the current frame. s0` + s0 = 1.
+///   the current frame. s0` + s0 = 1.
 pub fn enforce_not_constraints<E: FieldElement>(
     frame: &EvaluationFrame<E>,
     result: &mut [E],
@@ -207,7 +207,7 @@ pub fn enforce_not_constraints<E: FieldElement>(
 /// Enforces constraints of the AND operation. The AND operation computes the bitwise and of the
 /// first two elements in the current trace. Therefore, the following constraints are enforced:
 /// - The top two element in the current frame of the stack should be binary. s0^2 - s0 = 0,
-/// s1^2 - s1 = 0. The top element is binary or not is enforced as a general constraint.
+///   s1^2 - s1 = 0. The top element is binary or not is enforced as a general constraint.
 /// - The first element of the next frame should be a binary and of the first two elements in the
 ///   current frame. s0` - s0 * s1 = 0.
 pub fn enforce_and_constraints<E: FieldElement>(
@@ -234,7 +234,7 @@ pub fn enforce_and_constraints<E: FieldElement>(
 /// Enforces constraints of the OR operation. The OR operation computes the bitwise or of the
 /// first two elements in the current trace. Therefore, the following constraints are enforced:
 /// - The top two element in the current frame of the stack should be binary. s0^2 - s0 = 0,
-/// s1^2 - s1 = 0. The top element is binary or not is enforced as a general constraint.
+///   s1^2 - s1 = 0. The top element is binary or not is enforced as a general constraint.
 /// - The first element of the next frame should be a binary or of the first two elements in the
 ///   current frame. s0` - ( s0 + s1 - s0 * s1 ) = 0.
 pub fn enforce_or_constraints<E: FieldElement>(
@@ -324,7 +324,7 @@ pub fn enforce_eqz_constraints<E: FieldElement>(
 ///   constraint.
 /// - The exp value in the next frame should be the square of exp value in the current frame.
 /// - The accumulation value in the next frame is the product of the accumulation value in the
-/// current frame and the value which needs to be included in this turn.
+///   current frame and the value which needs to be included in this turn.
 /// - The b value is right shifted by 1 bit.
 pub fn enforce_expacc_constraints<E: FieldElement>(
     frame: &EvaluationFrame<E>,

air/src/constraints/stack/op_flags/mod.rs

@@ -100,7 +100,7 @@ impl<E: FieldElement> OpFlags<E> {
     /// - composite flag for the stack if the stack has been shifted to the right.
     /// - composite flag if the current operation being executed is a control flow operation or not.
     /// - composite flag if the current operation being executed has a binary element constraint on
-    /// the top element in the stack.
+    ///   the top element in the stack.
     pub fn new(frame: &EvaluationFrame<E>) -> Self {
         // intermediary array to cache the value of intermediate flags.
         let mut degree7_op_flags = [E::ZERO; NUM_DEGREE_7_OPS];
@@ -866,7 +866,7 @@ impl<E: FieldElement> OpFlags<E> {
     /// Operation Flag of MPVERIFY operation.
     #[inline(always)]
     pub fn mpverify(&self) -> E {
-        self.degree5_op_flags[get_op_index(Operation::MpVerify.op_code())]
+        self.degree5_op_flags[get_op_index(Operation::MpVerify(0).op_code())]
     }
 
     /// Operation Flag of SPLIT operation.

air/src/constraints/stack/op_flags/tests.rs

@@ -145,7 +145,7 @@ fn degree_4_op_flags() {
 fn composite_flags() {
     // ------ no change 0 ---------------------------------------------------------------------
 
-    let op_no_change_0 = [Operation::MpVerify, Operation::Span, Operation::Halt];
+    let op_no_change_0 = [Operation::MpVerify(0), Operation::Span, Operation::Halt];
     for op in op_no_change_0 {
         // frame initialised with an op operation.
         let frame = generate_evaluation_frame(op.op_code().into());
@@ -169,7 +169,7 @@ fn composite_flags() {
         assert_eq!(op_flags.left_shift(), ZERO);
         assert_eq!(op_flags.top_binary(), ZERO);
 
-        if op == Operation::MpVerify {
+        if op == Operation::MpVerify(0) {
             assert_eq!(op_flags.control_flow(), ZERO);
         } else if op == Operation::Span || op == Operation::Halt {
             assert_eq!(op_flags.control_flow(), ONE);

air/src/constraints/stack/overflow/mod.rs

@@ -93,7 +93,7 @@ pub fn enforce_stack_depth_constraints<E: FieldElement>(
 /// Enforces constraints on the overflow flag h0. Therefore, the following constraints
 /// are enforced:
 /// - If overflow table has values, then, h0 should be set to ONE, otherwise it should
-/// be ZERO.
+///   be ZERO.
 pub fn enforce_overflow_flag_constraints<E: FieldElement>(
     frame: &EvaluationFrame<E>,
     result: &mut [E],
@@ -108,9 +108,9 @@ pub fn enforce_overflow_flag_constraints<E: FieldElement>(
 
 /// Enforces constraints on the bookkeeping index `b1`. The following constraints are enforced:
 /// - In the case of a right shift operation, the next b1 index should be updated with current
-/// `clk` value.
+///   `clk` value.
 /// - In the case of a left shift operation, the last stack item should be set to ZERO when the
-/// depth of the stack is 16.
+///   depth of the stack is 16.
 pub fn enforce_overflow_index_constraints<E: FieldElement>(
     frame: &EvaluationFrame<E>,
     result: &mut [E],

air/src/constraints/stack/stack_manipulation/mod.rs

@@ -94,7 +94,7 @@ pub fn enforce_pad_constraints<E: FieldElement>(
 /// at depth n in the stack and pushes the copy onto the stack, whereas MOVUPn opearation moves the
 /// element at depth n to the top of the stack. Therefore, the following constraints are enforced:
 /// - The top element in the next frame should be equal to the element at depth n in the
-/// current frame. s0` - sn = 0.
+///   current frame. s0` - sn = 0.
 pub fn enforce_dup_movup_n_constraints<E: FieldElement>(
     frame: &EvaluationFrame<E>,
     result: &mut [E],
@@ -245,7 +245,7 @@ pub fn enforce_swapwx_constraints<E: FieldElement>(
 /// Enforces constraints of the MOVDNn operation. The MOVDNn operation moves the top element
 /// to depth n in the stack. Therefore, the following constraints are enforced:
 /// - The top element in the current frame should be equal to the element at depth n in the
-/// next frame. s0 - sn` = 0.
+///   next frame. s0 - sn` = 0.
 pub fn enforce_movdnn_constraints<E: FieldElement>(
     frame: &EvaluationFrame<E>,
     result: &mut [E],

air/src/constraints/stack/u32_ops/mod.rs

@@ -120,7 +120,7 @@ pub fn enforce_u32split_constraints<E: FieldElement<BaseField = Felt>>(
 /// elements in the current trace of the stack. Therefore, the following constraints are
 /// enforced:
 /// - The aggregation of limbs from the helper registers is equal to the sum of the top two
-/// element in the stack.
+///   element in the stack.
 pub fn enforce_u32add_constraints<E: FieldElement<BaseField = Felt>>(
     frame: &EvaluationFrame<E>,
     result: &mut [E],
@@ -141,7 +141,7 @@ pub fn enforce_u32add_constraints<E: FieldElement<BaseField = Felt>>(
 /// elements in the current trace of the stack. Therefore, the following constraints are
 /// enforced:
 /// - The aggregation of limbs from the helper registers is equal to the sum of the top three
-/// elements in the stack.
+///   elements in the stack.
 pub fn enforce_u32add3_constraints<E: FieldElement<BaseField = Felt>>(
     frame: &EvaluationFrame<E>,
     result: &mut [E],
@@ -289,10 +289,9 @@ pub fn enforce_check_element_validity<E: FieldElement<BaseField = Felt>>(
 /// Enforces constraints of the general operation. The constaints checks if the lower 16-bits limbs
 /// are aggregated correctly or not. Therefore, the following constraints are enforced:
 /// - The aggregation of lower two lower 16-bits limbs in the helper registers is equal to the
-///   second
-/// element in the next row.
+///   second element in the next row.
 /// - The aggregation of lower two upper 16-bits limbs in the helper registers is equal to the first
-/// element in the next row.
+///   element in the next row.
 pub fn enforce_limbs_agg<E: FieldElement<BaseField = Felt>>(
     frame: &EvaluationFrame<E>,
     result: &mut [E],

air/src/options.rs

@@ -171,6 +171,7 @@ pub struct ExecutionOptions {
     max_cycles: u32,
     expected_cycles: u32,
     enable_tracing: bool,
+    enable_debugging: bool,
 }
 
 impl Default for ExecutionOptions {
@@ -179,6 +180,7 @@ impl Default for ExecutionOptions {
             max_cycles: u32::MAX,
             expected_cycles: MIN_TRACE_LEN as u32,
             enable_tracing: false,
+            enable_debugging: false,
         }
     }
 }
@@ -211,30 +213,51 @@ impl ExecutionOptions {
             max_cycles,
             expected_cycles,
             enable_tracing,
+            enable_debugging: false,
         })
     }
 
-    /// Enables Host to handle the `tracing` instructions.
+    /// Enables execution of the `trace` instructions.
     pub fn with_tracing(mut self) -> Self {
         self.enable_tracing = true;
         self
     }
 
+    /// Enables execution of programs in debug mode.
+    ///
+    /// In debug mode the VM does the following:
+    /// - Executes `debug` instructions (these are ignored in regular mode).
+    /// - Records additional info about program execution (e.g., keeps track of stack state at
+    ///   every cycle of the VM) which enables stepping through the program forward and backward.
+    pub fn with_debugging(mut self) -> Self {
+        self.enable_debugging = true;
+        self
+    }
+
     // PUBLIC ACCESSORS
     // --------------------------------------------------------------------------------------------
 
-    /// Returns maximum number of cycles
+    /// Returns maximum number of cycles a program is allowed to execute for.
     pub fn max_cycles(&self) -> u32 {
         self.max_cycles
     }
 
-    /// Returns number of the expected cycles
+    /// Returns the number of cycles a program is expected to take.
+    ///
+    /// This will serve as a hint to the VM for how much memory to allocate for a program's
+    /// execution trace and may result in performance improvements when the number of expected
+    /// cycles is equal to the number of actual cycles.
     pub fn expected_cycles(&self) -> u32 {
         self.expected_cycles
     }
 
-    /// Returns a flag indicating whether the Host should handle `trace` instructions
+    /// Returns a flag indicating whether the VM should execute `trace` instructions.
     pub fn enable_tracing(&self) -> bool {
         self.enable_tracing
     }
+
+    /// Returns a flag indicating whether the VM should execute a program in debug mode.
+    pub fn enable_debugging(&self) -> bool {
+        self.enable_debugging
+    }
 }

air/src/trace/main_trace.rs

@@ -17,7 +17,10 @@ use super::{
     STACK_TRACE_OFFSET,
 };
 use core::ops::{Deref, Range};
-use vm_core::{utils::range, Felt, ONE, ZERO};
+use vm_core::{utils::range, Felt, Word, ONE, ZERO};
+
+#[cfg(any(test, feature = "internals"))]
+use alloc::vec::Vec;
 
 // CONSTANTS
 // ================================================================================================
@@ -113,14 +116,27 @@ impl MainTrace {
     }
 
     /// Returns the first half of the hasher state at row i.
-    pub fn decoder_hasher_state_first_half(&self, i: usize) -> [Felt; DIGEST_LEN] {
+    pub fn decoder_hasher_state_first_half(&self, i: usize) -> Word {
         let mut state = [ZERO; DIGEST_LEN];
         for (col, s) in state.iter_mut().enumerate() {
             *s = self.columns.get_column(DECODER_TRACE_OFFSET + HASHER_STATE_OFFSET + col)[i];
         }
         state
     }
 
+    /// Returns the second half of the hasher state at row i.
+    pub fn decoder_hasher_state_second_half(&self, i: usize) -> Word {
+        const SECOND_WORD_OFFSET: usize = 4;
+        let mut state = [ZERO; DIGEST_LEN];
+        for (col, s) in state.iter_mut().enumerate() {
+            *s = self
+                .columns
+                .get_column(DECODER_TRACE_OFFSET + HASHER_STATE_OFFSET + SECOND_WORD_OFFSET + col)
+                [i];
+        }
+        state
+    }
+
     /// Returns a specific element from the hasher state at row i.
     pub fn decoder_hasher_state_element(&self, element: usize, i: usize) -> Felt {
         self.columns.get_column(DECODER_TRACE_OFFSET + HASHER_STATE_OFFSET + element)[i + 1]

assembly/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "miden-assembly"
-version = "0.8.0"
+version = "0.9.2"
 description = "Miden VM assembly language"
 authors = ["miden contributors"]
 readme = "README.md"
 license = "MIT"
 repository = "https://github.com/0xPolygonMiden/miden-vm"
-documentation = "https://docs.rs/miden-assembly/0.8.0"
+documentation = "https://docs.rs/miden-assembly/0.9.2"
 categories = ["compilers", "no-std"]
 keywords = ["assembler", "assembly", "language", "miden"]
 edition = "2021"
@@ -48,7 +48,7 @@ tracing = { version = "0.1", default-features = false, features = [
 ] }
 thiserror = { version = "1.0", git = "https://github.com/bitwalker/thiserror", branch = "no-std", default-features = false }
 unicode-width = { version = "0.1", features = ["no_std"] }
-vm-core = { package = "miden-core", path = "../core", version = "0.8", default-features = false }
+vm-core = { package = "miden-core", path = "../core", version = "0.9", default-features = false }
 
 [dev-dependencies]
 pretty_assertions = "1.4"

assembly/src/assembler/instruction/crypto_ops.rs

@@ -118,7 +118,7 @@ pub(super) fn mtree_get(span: &mut SpanBuilder) {
     let ops = [
         // verify the node V for root R with depth d and index i
         // => [V, d, i, R, ...]
-        MpVerify,
+        MpVerify(0),
 
         // move d, i back to the top of the stack and are dropped since they are
         // no longer needed => [V, R, ...]
@@ -172,21 +172,6 @@ pub(super) fn mtree_merge(span: &mut SpanBuilder) {
     hmerge(span);
 }
 
-/// Verifies if the node value `V`, on depth `d` and index `i` opens to the root `R` of a Merkle
-/// tree by appending a [Operation::MpVerify]. The stack is expected to be arranged as follows
-/// (from the top):
-/// - node value `V`, 4 elements
-/// - depth of the node `d`, 1 element
-/// - index of the node `i`, 1 element
-/// - root of the tree `R`, 4 elements
-///
-/// After the operation is executed, the stack remains unchanged.
-///
-/// This operation takes 1 VM cycle.
-pub(super) fn mtree_verify(span: &mut SpanBuilder) {
-    span.push_op(MpVerify);
-}
-
 // MERKLE TREES - HELPERS
 // ================================================================================================