Fix note script compilation: use libraries instead of programs (#2822)

* refactor: make all notes be libs, update CodeBuilder::compile_note_script

* refactor: compile and store note script libs instead of scripts themselves

* chore: fix comment format

* chore: increment crate versions to v0.14.5

---------

Co-authored-by: Bobbin Threadbare <bobbinth@protonmail.com>

Author: Fumuran

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.14.5 (2026-04-23)
+
+- Fixed note script compilation: all note scripts are now compiled as libraries ([#2822](https://github.com/0xMiden/protocol/pull/2822)).
+
 ## 0.14.4 (2026-04-09)
 
 - Fixed AggLayer `write_mint_note_storage` stack padding before loading the mint serial number ([#2749](https://github.com/0xMiden/protocol/pull/2749)).

Cargo.lock

@@ -21,7 +21,7 @@ homepage     = "https://miden.xyz"
 license      = "MIT"
 repository   = "https://github.com/0xMiden/protocol"
 rust-version = "1.90"
-version      = "0.14.4"
+version      = "0.14.5"
 
 [profile.release]
 codegen-units = 1

Cargo.toml

@@ -85,7 +85,7 @@ pub fn setup_mixed_notes_benchmark(config: MixedNotesConfig) -> anyhow::Result<M
         seed[0] = i as u8;
         let mut rng = RandomCoin::new([i as u32, 0, 0, 0].into());
         let failing_note = NoteBuilder::new(sender, &mut rng)
-            .code("begin push.0 div end") // Division by zero - will fail.
+            .code("@note_script pub proc main push.0 div end") // Division by zero - will fail.
             .build()?;
         failing_notes.push(failing_note);
     }

bin/bench-note-checker/src/lib.rs

@@ -402,7 +402,7 @@ Keccak preimage format directly — the felt value does **not** equal the numeri
 | Field | Value |
 |-------|-------|
 | `serial_num` | Random (`rng.draw_word()`) |
-| `script` | `B2AGG.masb` |
+| `script` | `B2AGG.masl` |
 | `storage` | 6 felts -- see layout below |
 
 **Storage layout (6 felts):**
@@ -461,7 +461,7 @@ token registry, and creates a MINT note targeting the faucet.
 | Field | Value |
 |-------|-------|
 | `serial_num` | Random (`rng.draw_word()`) |
-| `script` | `CLAIM.masb` |
+| `script` | `CLAIM.masl` |
 | `storage` | 569 felts -- see layout below |
 
 **Storage layout (569 felts):**
@@ -530,7 +530,7 @@ The storage is divided into three logical regions: proof data (felts 0-535), lea
 | Field | Value |
 |-------|-------|
 | `serial_num` | Random (`rng.draw_word()`) |
-| `script` | `CONFIG_AGG_BRIDGE.masb` |
+| `script` | `CONFIG_AGG_BRIDGE.masl` |
 | `storage` | 7 felts -- see layout below |
 
 **Storage layout (7 felts):**
@@ -577,7 +577,7 @@ CLAIM notes can be verified against it.
 | Field | Value |
 |-------|-------|
 | `serial_num` | Random (`rng.draw_word()`) |
-| `script` | `UPDATE_GER.masb` |
+| `script` | `UPDATE_GER.masl` |
 | `storage` | 8 felts -- see layout below |
 
 **Storage layout (8 felts):**

crates/miden-agglayer/SPEC.md

@@ -50,7 +50,8 @@ const ERR_B2AGG_TARGET_ACCOUNT_MISMATCH="B2AGG note attachment target account do
 #! - The note does not contain exactly 6 storage items.
 #! - The note does not contain exactly 1 asset.
 #! - The note attachment does not target the consuming account.
-begin
+@note_script
+pub proc main
     dropw
     # => [pad(16)]
 

crates/miden-agglayer/asm/note_scripts/B2AGG.masm

@@ -75,7 +75,8 @@ const ERR_CLAIM_TARGET_ACCT_MISMATCH = "CLAIM note attachment target account doe
 #! Panics if:
 #! - account does not expose claim procedure.
 #! - note attachment target account does not match the consuming account.
-begin
+@note_script
+pub proc main
     dropw
     # => [pad(16)]
 

crates/miden-agglayer/asm/note_scripts/CLAIM.masm

@@ -47,7 +47,8 @@ const ERR_CONFIG_AGG_BRIDGE_TARGET_ACCOUNT_MISMATCH = "CONFIG_AGG_BRIDGE note at
 #! - The note attachment target account does not match the consuming bridge account.
 #! - The note does not contain exactly 7 storage items.
 #! - The account does not expose the register_faucet procedure.
-begin
+@note_script
+pub proc main
     dropw
     # => [pad(16)]
 

crates/miden-agglayer/asm/note_scripts/CONFIG_AGG_BRIDGE.masm

@@ -39,7 +39,8 @@ const ERR_UPDATE_GER_TARGET_ACCOUNT_MISMATCH = "UPDATE_GER note attachment targe
 #! - account does not expose update_ger procedure.
 #! - target account ID does not match the consuming account ID.
 #! - number of note storage items is not exactly 8.
-begin
+@note_script
+pub proc main
     dropw
     # => [pad(16)]
 

crates/miden-agglayer/asm/note_scripts/UPDATE_GER.masm

@@ -5,7 +5,6 @@ use std::sync::Arc;
 
 use fs_err as fs;
 use miden_assembly::diagnostics::{IntoDiagnostic, NamedSource, Result, WrapErr};
-use miden_assembly::serde::Serializable;
 use miden_assembly::{Assembler, Library, Report};
 use miden_crypto::hash::keccak::{Keccak256, Keccak256Digest};
 use miden_protocol::account::{
@@ -43,7 +42,7 @@ const AGGLAYER_GLOBAL_CONSTANTS_FILE_NAME: &str = "agglayer_constants.rs";
 /// Read and parse the contents from `./asm`.
 /// - Compiles the contents of asm/agglayer directory into a single agglayer.masl library.
 /// - Compiles the contents of asm/components directory into individual per-component .masl files.
-/// - Compiles the contents of asm/note_scripts directory into individual .masb files.
+/// - Compiles the contents of asm/note_scripts directory into individual `.masl` libraries.
 fn main() -> Result<()> {
     // re-build when the MASM code changes
     println!("cargo::rerun-if-changed={ASM_DIR}/");
@@ -124,39 +123,38 @@ fn compile_agglayer_lib(
 // COMPILE EXECUTABLE MODULES
 // ================================================================================================
 
-/// Reads all MASM files from the "{source_dir}", complies each file individually into a MASB
-/// file, and stores the compiled files into the "{target_dir}".
-///
-/// The source files are expected to contain executable programs.
+/// Reads all MASM files from `{source_dir}`, compiles each file as a note script library with
+/// [`Assembler::assemble_library`], and writes the serialized library as `.masl` via
+/// [`Library::write_to_file`].
 fn compile_note_scripts(
     source_dir: &Path,
-    target_dir: &Path,
+    note_scripts_target_dir: &Path,
     mut assembler: Assembler,
 ) -> Result<()> {
-    fs::create_dir_all(target_dir)
+    fs::create_dir_all(note_scripts_target_dir)
         .into_diagnostic()
         .wrap_err("failed to create note_scripts directory")?;
 
     // Add the miden-standards library to the assembler so note scripts can use it
     let standards_lib = miden_standards::StandardsLib::default();
     assembler.link_static_library(standards_lib)?;
 
-    for masm_file_path in shared::get_masm_files(source_dir).unwrap() {
-        // read the MASM file, parse it, and serialize the parsed AST to bytes
-        let code = assembler.clone().assemble_program(masm_file_path.clone())?;
-
-        let bytes = code.to_bytes();
+    for note_file_path in shared::get_masm_files(source_dir).unwrap() {
+        // compile the note script library from the provided MASM file
+        let note_library = assembler.clone().assemble_library([note_file_path.clone()])?;
 
-        let masm_file_name = masm_file_path
+        let note_file_name = note_file_path
             .file_name()
             .expect("file name should exist")
             .to_str()
             .ok_or_else(|| Report::msg("failed to convert file name to &str"))?;
-        let mut masb_file_path = target_dir.join(masm_file_name);
+        let mut masl_file_path = note_scripts_target_dir.join(note_file_name);
+        masl_file_path.set_extension(Library::LIBRARY_EXTENSION);
 
-        // write the binary MASB to the output dir
-        masb_file_path.set_extension("masb");
-        fs::write(masb_file_path, bytes).unwrap();
+        // write the note script library to the output dir
+        note_library
+            .write_to_file(&masl_file_path)
+            .map_err(|e| Report::msg(format!("{e:#}")))?;
     }
     Ok(())
 }