chore: merge main branch into next (#1351)

CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-## 0.9.0 (TBD)
+## 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/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
+    }
 }

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"

core/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "miden-core"
-version = "0.8.0"
+version = "0.9.1"
 description = "Miden VM core components"
 authors = ["miden contributors"]
 readme = "README.md"
 license = "MIT"
 repository = "https://github.com/0xPolygonMiden/miden-vm"
-documentation = "https://docs.rs/miden-core/0.8.0"
+documentation = "https://docs.rs/miden-core/0.9.1"
 categories = ["emulators", "no-std"]
 keywords = ["instruction-set", "miden", "program"]
 edition = "2021"

docs/src/intro/main.md

@@ -2,7 +2,7 @@
 Miden VM is a zero-knowledge virtual machine written in Rust. For any program executed on Miden VM, a STARK-based proof of execution is automatically generated. This proof can then be used by anyone to verify that the program was executed correctly without the need for re-executing the program or even knowing the contents of the program.
 
 ## 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.
 
 At this point, Miden VM is good enough for experimentation, and even for real-world applications, but it is not yet ready for production use. The codebase has not been audited and contains known and unknown bugs and security flaws.
 

docs/src/intro/usage.md

@@ -1,5 +1,5 @@
 # Usage
-Before you can use Miden VM, you'll need to make sure you have Rust [installed](https://www.rust-lang.org/tools/install). Miden VM v0.8 requires Rust version **1.75** or later.
+Before you can use Miden VM, you'll need to make sure you have Rust [installed](https://www.rust-lang.org/tools/install). Miden VM v0.9 requires Rust version **1.75** or later.
 
 Miden VM consists of several crates, each of which exposes a small set of functionality. The most notable of these crates are:
 * [miden-processor](https://crates.io/crates/miden-processor), which can be used to execute Miden VM programs.

docs/src/user_docs/assembly/field_operations.md

@@ -23,7 +23,7 @@ If the error code is omitted, the default value of $0$ is assumed.
 
 ### Arithmetic and Boolean operations
 
-The arithmetic operations below are performed in a 64-bit [prime filed](https://en.wikipedia.org/wiki/Finite_field) defined by modulus $p = 2^{64} - 2^{32} + 1$. This means that overflow happens after a value exceeds $p$. Also, the result of divisions may appear counter-intuitive because divisions are defined via inversions.
+The arithmetic operations below are performed in a 64-bit [prime field](https://en.wikipedia.org/wiki/Finite_field) defined by modulus $p = 2^{64} - 2^{32} + 1$. This means that overflow happens after a value exceeds $p$. Also, the result of divisions may appear counter-intuitive because divisions are defined via inversions.
 
 | Instruction                                                                    | Stack_input | Stack_output  | Notes                                                                                                        |
 | ------------------------------------------------------------------------------ | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------ |

miden/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "miden-vm"
-version = "0.8.0"
-description = "Miden virtual machine"
+version = "0.9.1"
+description="Miden virtual machine"
 authors = ["miden contributors"]
 readme = "README.md"
 license = "MIT"
 repository = "https://github.com/0xPolygonMiden/miden-vm"
-documentation = "https://docs.rs/miden-vm/0.8.0"
+documentation = "https://docs.rs/miden-vm/0.9.1"
 categories = ["cryptography", "emulators", "no-std"]
 keywords = ["miden", "stark", "virtual-machine", "zkp"]
 edition = "2021"
@@ -56,17 +56,17 @@ metal = ["prover/metal", "std"]
 std = ["assembly/std", "processor/std", "prover/std", "verifier/std"]
 
 [dependencies]
-assembly = { package = "miden-assembly", path = "../assembly", version = "0.8", default-features = false }
+assembly = { package = "miden-assembly", path = "../assembly", version = "0.9", default-features = false }
 blake3 = "1.5"
 clap = { version = "4.4", features = ["derive"], optional = true }
 hex = { version = "0.4", optional = true }
-processor = { package = "miden-processor", path = "../processor", version = "0.8", default-features = false }
-prover = { package = "miden-prover", path = "../prover", version = "0.8", default-features = false }
+processor = { package = "miden-processor", path = "../processor", version = "0.9", default-features = false }
+prover = { package = "miden-prover", path = "../prover", version = "0.9", default-features = false }
 rustyline = { version = "13.0", default-features = false, optional = true }
 serde = { version = "1.0", optional = true }
 serde_derive = { version = "1.0", optional = true }
 serde_json = { version = "1.0", optional = true }
-stdlib = { package = "miden-stdlib", path = "../stdlib", version = "0.8", default-features = false }
+stdlib = { package = "miden-stdlib", path = "../stdlib", version = "0.9", default-features = false }
 tracing = { version = "0.1", default-features = false, features = [
     "attributes",
 ] }
@@ -78,8 +78,8 @@ tracing-forest = { version = "0.1", optional = true, features = [
     "ansi",
     "smallvec",
 ] }
-verifier = { package = "miden-verifier", path = "../verifier", version = "0.8", default-features = false }
-vm-core = { package = "miden-core", path = "../core", version = "0.8", default-features = false }
+verifier = { package = "miden-verifier", path = "../verifier", version = "0.9", default-features = false }
+vm-core = { package = "miden-core", path = "../core", version = "0.9", default-features = false }
 
 [dev-dependencies]
 assert_cmd = "2.0"
@@ -88,6 +88,6 @@ escargot = "0.5"
 num-bigint = "0.4"
 predicates = "3.0"
 test-utils = { package = "miden-test-utils", path = "../test-utils" }
-vm-core = { package = "miden-core", path = "../core", version = "0.8" }
+vm-core = { package = "miden-core", path = "../core", version = "0.9" }
 winter-fri = { package = "winter-fri", version = "0.8" }
 rand_chacha = "0.3.1"

processor/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "miden-processor"
-version = "0.8.0"
+version = "0.9.2"
 description = "Miden VM processor"
 authors = ["miden contributors"]
 readme = "README.md"
 license = "MIT"
 repository = "https://github.com/0xPolygonMiden/miden-vm"
-documentation = "https://docs.rs/miden-processor/0.8.0"
+documentation = "https://docs.rs/miden-processor/0.9.2"
 categories = ["emulators", "no-std"]
 keywords = ["miden", "virtual-machine"]
 edition = "2021"
@@ -26,13 +26,13 @@ std = ["vm-core/std", "winter-prover/std"]
 tracing = { version = "0.1", default-features = false, features = [
     "attributes",
 ] }
-vm-core = { package = "miden-core", path = "../core", version = "0.8", default-features = false }
-miden-air = { package = "miden-air", path = "../air", version = "0.8", default-features = false }
+vm-core = { package = "miden-core", path = "../core", version = "0.9", default-features = false }
+miden-air = { package = "miden-air", path = "../air", version = "0.9", default-features = false }
 winter-prover = { package = "winter-prover", version = "0.9", default-features = false }
 
 [dev-dependencies]
 logtest = { version = "2.0", default-features = false }
-assembly = { package = "miden-assembly", path = "../assembly", version = "0.8", default-features = false }
+assembly = { package = "miden-assembly", path = "../assembly", version = "0.9", default-features = false }
 test-utils = { package = "miden-test-utils", path = "../test-utils" }
 winter-fri = { package = "winter-fri", version = "0.9" }
 winter-utils = { package = "winter-utils", version = "0.9" }

processor/src/chiplets/aux_trace/mod.rs

@@ -1,5 +1,4 @@
 use alloc::vec::Vec;
-
 use miden_air::trace::{
     chiplets::{
         bitwise::OP_CYCLE_LEN as BITWISE_OP_CYCLE_LEN,

processor/src/errors.rs

@@ -14,7 +14,7 @@ use std::error::Error;
 // EXECUTION ERROR
 // ================================================================================================
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ExecutionError {
     AdviceMapKeyNotFound(Word),
     AdviceStackReadFailed(u32),
@@ -215,7 +215,7 @@ impl From<Ext2InttError> for ExecutionError {
 // EXT2INTT ERROR
 // ================================================================================================
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub enum Ext2InttError {
     DomainSizeNotPowerOf2(u64),
     DomainSizeTooSmall(u64),

processor/src/host/mod.rs

@@ -82,7 +82,7 @@ pub trait Host {
         Ok(HostResponse::None)
     }
 
-    /// Handles the trace emmited from the VM.
+    /// Handles the trace emitted from the VM.
     fn on_trace<S: ProcessState>(
         &mut self,
         _process: &S,

processor/src/lib.rs

@@ -186,7 +186,7 @@ where
         host: H,
         execution_options: ExecutionOptions,
     ) -> Self {
-        Self::initialize(kernel, stack_inputs, host, false, execution_options)
+        Self::initialize(kernel, stack_inputs, host, execution_options)
     }
 
     /// Creates a new process with provided inputs and debug options enabled.
@@ -195,18 +195,17 @@ where
             kernel,
             stack_inputs,
             host,
-            true,
-            ExecutionOptions::default().with_tracing(),
+            ExecutionOptions::default().with_tracing().with_debugging(),
         )
     }
 
     fn initialize(
         kernel: Kernel,
         stack: StackInputs,
         host: H,
-        in_debug_mode: bool,
         execution_options: ExecutionOptions,
     ) -> Self {
+        let in_debug_mode = execution_options.enable_debugging();
         Self {
             system: System::new(execution_options.expected_cycles() as usize),
             decoder: Decoder::new(in_debug_mode),

processor/src/operations/comb_ops.rs

@@ -173,11 +173,10 @@ where
 mod tests {
     use alloc::{borrow::ToOwned, vec::Vec};
 
+    use crate::{ContextId, Process, QuadFelt};
     use test_utils::{build_test, rand::rand_array};
     use vm_core::{Felt, FieldElement, Operation, StackInputs, ONE, ZERO};
 
-    use crate::{ContextId, Process, QuadFelt};
-
     #[test]
     fn rcombine_main() {
         // --- build stack inputs -----------------------------------------------------------------

prover/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "miden-prover"
-version = "0.8.0"
+version = "0.9.1"
 description = "Miden VM prover"
 authors = ["miden contributors"]
 readme = "README.md"
 license = "MIT"
 repository = "https://github.com/0xPolygonMiden/miden-vm"
-documentation = "https://docs.rs/miden-prover/0.8.0"
+documentation = "https://docs.rs/miden-prover/0.9.1"
 categories = ["cryptography", "emulators", "no-std"]
 keywords = ["miden", "prover", "stark", "zkp"]
 edition = "2021"
@@ -19,8 +19,8 @@ metal = ["dep:miden-gpu", "dep:elsa", "dep:pollster", "concurrent", "std"]
 std = ["air/std", "processor/std", "winter-prover/std"]
 
 [dependencies]
-air = { package = "miden-air", path = "../air", version = "0.8", default-features = false }
-processor = { package = "miden-processor", path = "../processor", version = "0.8", default-features = false }
+air = { package = "miden-air", path = "../air", version = "0.9", default-features = false }
+processor = { package = "miden-processor", path = "../processor", version = "0.9", default-features = false }
 tracing = { version = "0.1", default-features = false, features = ["attributes"] }
 winter-prover = { package = "winter-prover", version = "0.9", default-features = false }