Add miden-package crate with Package type to represent a compiled Miden program/library.

CHANGELOG.md

@@ -15,6 +15,7 @@
 - Added `miden_core::mast::MastForest::advice_map` to load it into the advice provider before the `MastForest` execution (#1574).
 - Optimized the computation of the DEEP queries in the recursive verifier (#1594).
 - Added validity checks for the inputs to the recursive verifier (#1596).
+- Added `miden-package` crate with `Package` type to represent a compiled Miden program/library (#1544).
 
 ## 0.11.0 (2024-11-04)
 

Cargo.toml

@@ -4,6 +4,7 @@ members = [
     "assembly",
     "core",
     "miden",
+    "package",
     "processor",
     "prover",
     "stdlib",

air/Cargo.toml

@@ -38,5 +38,5 @@ winter-prover = { package = "winter-prover", version = "0.11", default-features
 
 [dev-dependencies]
 criterion = "0.5"
-proptest = "1.5"
+proptest = "1.6"
 rand-utils = { package = "winter-rand-utils", version = "0.11" }

assembly/Cargo.toml

@@ -20,7 +20,7 @@ doctest = false
 [features]
 default = ["std"]
 std = ["aho-corasick/std", "miette/fancy", "miette/std", "vm-core/std", "thiserror/std"]
-testing = ["dep:regex"]
+testing = ["dep:regex", "dep:proptest", "dep:proptest-derive"]
 
 [dependencies]
 aho-corasick = { version = "1.1", default-features = false }
@@ -29,6 +29,10 @@ miette = { package = "miden-miette", version = "8.0", default-features = false,
     "fancy-no-syscall",
     "derive"
 ] }
+proptest = { version = "1.6", optional = true, default-features = false, features = [
+  "no_std", "alloc"
+] }
+proptest-derive = { version = "0.5", optional = true, default-features = false }
 regex = { version = "1.10", optional = true, default-features = false, features = ["unicode", "perf"] }
 smallvec = { version = "1.13", features = ["union", "const_generics", "const_new"] }
 thiserror = { workspace = true }

assembly/src/ast/ident.rs

@@ -108,7 +108,10 @@ impl Ident {
         if !source.starts_with(|c: char| c.is_ascii_alphabetic()) {
             return Err(IdentError::InvalidStart);
         }
-        if !source.chars().all(|c| c.is_ascii_alphabetic() || matches!(c, '_' | '0'..='9')) {
+        if !source
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | ':' | '/' | '@' | '.'))
+        {
             return Err(IdentError::InvalidChars { ident: source.into() });
         }
         Ok(())

assembly/src/ast/procedure/name.rs

@@ -1,10 +1,15 @@
-use alloc::{string::ToString, sync::Arc};
+use alloc::{
+    string::{String, ToString},
+    sync::Arc,
+};
 use core::{
     fmt,
     hash::{Hash, Hasher},
     str::FromStr,
 };
 
+use vm_core::utils::{ByteReader, ByteWriter, Deserializable, DeserializationError, Serializable};
+
 use crate::{
     ast::{CaseKindError, Ident, IdentError},
     diagnostics::{IntoDiagnostic, Report},
@@ -20,8 +25,10 @@ use crate::{
 /// A qualified procedure name can be context-sensitive, i.e. the module path might refer
 /// to an imported
 #[derive(Clone)]
+#[cfg_attr(feature = "testing", derive(proptest_derive::Arbitrary))]
 pub struct QualifiedProcedureName {
     /// The source span associated with this identifier.
+    #[cfg_attr(feature = "testing", proptest(value = "SourceSpan::default()"))]
     pub span: SourceSpan,
     /// The module path for this procedure.
     pub module: LibraryPath,
@@ -116,6 +123,21 @@ impl fmt::Display for QualifiedProcedureName {
     }
 }
 
+impl Serializable for QualifiedProcedureName {
+    fn write_into<W: ByteWriter>(&self, target: &mut W) {
+        self.module.write_into(target);
+        self.name.write_into(target);
+    }
+}
+
+impl Deserializable for QualifiedProcedureName {
+    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
+        let module = LibraryPath::read_from(source)?;
+        let name = ProcedureName::read_from(source)?;
+        Ok(Self::new(module, name))
+    }
+}
+
 // PROCEDURE NAME
 // ================================================================================================
 
@@ -311,10 +333,12 @@ impl FromStr for ProcedureName {
                     break Err(IdentError::InvalidChars { ident: s.into() });
                 }
             },
-            Some((_, c)) if c.is_ascii_lowercase() || c == '_' || c == '$' => {
+            Some((_, c))
+                if c.is_ascii_lowercase() || c == '_' || c == '-' || c == '$' || c == '.' =>
+            {
                 if chars.as_str().contains(|c| match c {
                     c if c.is_ascii_alphanumeric() => false,
-                    '_' | '$' => false,
+                    '_' | '-' | '$' | '.' => false,
                     _ => true,
                 }) {
                     Err(IdentError::InvalidChars { ident: s.into() })
@@ -328,3 +352,60 @@ impl FromStr for ProcedureName {
         Ok(Self(Ident::new_unchecked(Span::unknown(raw))))
     }
 }
+
+impl Serializable for ProcedureName {
+    fn write_into<W: ByteWriter>(&self, target: &mut W) {
+        self.as_str().write_into(target)
+    }
+}
+
+impl Deserializable for ProcedureName {
+    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
+        let str: String = source.read()?;
+        let proc_name = ProcedureName::new(str)
+            .map_err(|e| DeserializationError::InvalidValue(e.to_string()))?;
+        Ok(proc_name)
+    }
+}
+
+// ARBITRARY IMPLEMENTATION
+// ================================================================================================
+
+#[cfg(feature = "testing")]
+impl proptest::prelude::Arbitrary for ProcedureName {
+    type Parameters = ();
+
+    fn arbitrary_with(_args: Self::Parameters) -> Self::Strategy {
+        use proptest::prelude::*;
+        // see https://doc.rust-lang.org/rustc/symbol-mangling/v0.html#symbol-grammar-summary
+        let all_possible_chars_in_mangled_name =
+            "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_.$";
+        let mangled_rustc_name = ProcedureName::new(all_possible_chars_in_mangled_name).unwrap();
+        let plain = ProcedureName::new("user_func").unwrap();
+        let wasm_cm_style = ProcedureName::new("kebab-case-func").unwrap();
+        prop_oneof![Just(mangled_rustc_name), Just(plain), Just(wasm_cm_style)].boxed()
+    }
+
+    type Strategy = proptest::prelude::BoxedStrategy<Self>;
+}
+
+// TESTS
+// ================================================================================================
+
+/// Tests
+#[cfg(test)]
+mod tests {
+    use proptest::prelude::*;
+    use vm_core::utils::{Deserializable, Serializable};
+
+    use super::ProcedureName;
+
+    proptest! {
+        #[test]
+        fn procedure_name_serialization_roundtrip(path in any::<ProcedureName>()) {
+            let bytes = path.to_bytes();
+            let deserialized = ProcedureName::read_from_bytes(&bytes).unwrap();
+            assert_eq!(path, deserialized);
+        }
+    }
+}

assembly/src/library/mod.rs

@@ -7,13 +7,12 @@ use alloc::{
 
 use vm_core::{
     crypto::hash::RpoDigest,
-    debuginfo::Span,
     mast::{MastForest, MastNodeId},
     utils::{ByteReader, ByteWriter, Deserializable, DeserializationError, Serializable},
-    Kernel,
+    AdviceMap, Kernel,
 };
 
-use crate::ast::{Ident, ProcedureName, QualifiedProcedureName};
+use crate::ast::QualifiedProcedureName;
 
 mod error;
 mod module;
@@ -92,6 +91,17 @@ impl Library {
 
         Ok(Self { digest, exports, mast_forest })
     }
+
+    /// Produces a new library with the existing [`MastForest`] and where all key/values in the  
+    /// provided advice map are added to the internal advice map.
+    pub fn with_advice_map(self, advice_map: AdviceMap) -> Self {
+        let mut mast_forest = (*self.mast_forest).clone();
+        mast_forest.advice_map_mut().extend(advice_map);
+        Self {
+            mast_forest: Arc::new(mast_forest),
+            ..self
+        }
+    }
 }
 
 // ------------------------------------------------------------------------------------------------
@@ -170,7 +180,7 @@ impl Serializable for Library {
         target.write_usize(exports.len());
         for (proc_name, proc_node_id) in exports {
             proc_name.module.write_into(target);
-            proc_name.name.as_str().write_into(target);
+            proc_name.name.write_into(target);
             target.write_u32(proc_node_id.as_u32());
         }
     }
@@ -187,10 +197,7 @@ impl Deserializable for Library {
         let mut exports = BTreeMap::new();
         for _ in 0..num_exports {
             let proc_module = source.read()?;
-            let proc_name: String = source.read()?;
-            let proc_name = ProcedureName::new_unchecked(Ident::new_unchecked(Span::unknown(
-                Arc::from(proc_name),
-            )));
+            let proc_name = source.read()?;
             let proc_name = QualifiedProcedureName::new(proc_module, proc_name);
             let proc_node_id = MastNodeId::from_u32_safe(source.read_u32()?, &mast_forest)?;