feat: reduce NoteType to a 1 bit encoding and add metadata version (#2691)

Author: PhilippGackstatter

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Changes
 
 - [BREAKING] Renamed `ProvenBatch::new` to `new_unchecked` ([#2687](https://github.com/0xMiden/miden-base/issues/2687)).
+- [BREAKING] Changed `NoteType` encoding from 2 bits to 1 and makes `NoteType::Private` the default ([#2691](https://github.com/0xMiden/miden-base/issues/2691)).
 
 ## 0.14.0 (2026-03-23)
 

crates/miden-agglayer/asm/agglayer/bridge/bridge_in.masm

@@ -9,6 +9,7 @@ use miden::core::crypto::hashes::poseidon2
 use miden::core::mem
 use miden::core::word
 use miden::protocol::note
+use miden::protocol::note::NOTE_TYPE_PUBLIC
 use miden::protocol::output_note
 use miden::protocol::output_note::ATTACHMENT_KIND_NONE
 use miden::protocol::active_account
@@ -64,9 +65,6 @@ const CLAIM_LEAF_DATA_WORD_LEN = 8
 # [16]: account_id_suffix, [17]: account_id_prefix
 const MINT_NOTE_NUM_STORAGE_ITEMS = 18
 
-# P2ID output note constants
-const OUTPUT_NOTE_TYPE_PUBLIC = 1
-
 # P2ID attachment constants (the P2ID note created by the faucet has no attachment)
 const P2ID_ATTACHMENT_SCHEME_NONE = 0
 
@@ -917,7 +915,7 @@ end
 #! Invocation: exec
 proc create_mint_note_with_attachment
     # Create the MINT output note targeting the faucet
-    push.OUTPUT_NOTE_TYPE_PUBLIC
+    push.NOTE_TYPE_PUBLIC
     # => [note_type, MINT_RECIPIENT, faucet_id_prefix, faucet_id_suffix]
 
     # Set tag to DEFAULT

crates/miden-agglayer/asm/agglayer/bridge/bridge_out.masm

@@ -78,7 +78,7 @@ const ATTACHMENT_KIND_LOC=13
 # -------------------------------------------------------------------------------------------------
 
 const LEAF_TYPE_ASSET=0
-const PUBLIC_NOTE=1
+use miden::protocol::note::NOTE_TYPE_PUBLIC
 const BURN_NOTE_NUM_STORAGE_ITEMS=0
 
 # PUBLIC INTERFACE
@@ -527,7 +527,7 @@ proc create_burn_note
     exec.note::build_recipient
     # => [RECIPIENT]
 
-    push.PUBLIC_NOTE
+    push.NOTE_TYPE_PUBLIC
     push.DEFAULT_TAG
     # => [tag, note_type, RECIPIENT]
 

crates/miden-protocol/asm/kernels/transaction/lib/note.masm

@@ -4,6 +4,9 @@ use $kernel::asset::ASSET_SIZE
 use $kernel::constants::NOTE_MEM_SIZE
 use $kernel::memory
 
+pub use $kernel::util::note::NOTE_TYPE_PUBLIC
+pub use $kernel::util::note::NOTE_TYPE_PRIVATE
+
 # ERRORS
 # =================================================================================================
 

crates/miden-protocol/asm/kernels/transaction/lib/output_note.masm

@@ -4,6 +4,7 @@ use $kernel::callbacks
 use $kernel::fungible_asset
 use $kernel::memory
 use $kernel::note
+use $kernel::note::NOTE_TYPE_PUBLIC
 use $kernel::constants::MAX_OUTPUT_NOTES_PER_TX
 use $kernel::util::note::ATTACHMENT_KIND_NONE
 use $kernel::util::note::ATTACHMENT_KIND_ARRAY
@@ -14,10 +15,6 @@ use miden::core::word
 # CONSTANTS
 # =================================================================================================
 
-# Constants for different note types
-const PUBLIC_NOTE=1     # 0b01
-const PRIVATE_NOTE=2    # 0b10
-
 # The default value of the felt at index 3 in the note metadata header when a new note is created.
 # All zeros sets the attachment kind to None and the user-defined attachment scheme to "none".
 const ATTACHMENT_DEFAULT_KIND_AND_SCHEME=0
@@ -318,10 +315,12 @@ end
 #!   or off-chain).
 #! - NOTE_METADATA_HEADER is the metadata associated with a note.
 pub proc build_metadata_header
-    # Validate that note type is private or public.
+    # Validate that note type is private (0) or public (1).
     # --------------------------------------------------------------------------------------------
 
-    dup.1 eq.PRIVATE_NOTE dup.2 eq.PUBLIC_NOTE or assert.err=ERR_NOTE_INVALID_TYPE
+    dup.1
+    u32assert.err=ERR_NOTE_INVALID_TYPE u32lte.NOTE_TYPE_PUBLIC
+    assert.err=ERR_NOTE_INVALID_TYPE
     # => [tag, note_type]
 
     # Validate the note tag fits into a u32.
@@ -330,22 +329,23 @@ pub proc build_metadata_header
     u32assert.err=ERR_NOTE_TAG_MUST_BE_U32
     # => [tag, note_type]
 
-    # Merge note type and sender ID suffix.
+    # Merge note type, version, and sender ID suffix.
     # --------------------------------------------------------------------------------------------
 
     exec.account::get_id
     # => [sender_id_suffix, sender_id_prefix, tag, note_type]
 
-    # the lower bits of an account ID suffix are guaranteed to be zero, so we can safely use that
-    # space to encode the note type
-    movup.3 add
-    # => [sender_id_suffix_and_note_type, sender_id_prefix, tag]
+    # The lower 8 bits of the account ID suffix are guaranteed to be zero by construction.
+    # Encode note_type at bit 4, leaving version at 0 (in bits 0..=3).
+    # Shifting note_type left by 4 is equivalent to multiplying by 16.
+    movup.3 mul.16 add
+    # => [sender_id_suffix_type_version, sender_id_prefix, tag]
 
     # Build metadata header.
     # --------------------------------------------------------------------------------------------
 
     push.ATTACHMENT_DEFAULT_KIND_AND_SCHEME movdn.3
-    # => [sender_id_suffix_and_note_type, sender_id_prefix, tag, attachment_kind_scheme]
+    # => [sender_id_suffix_type_version, sender_id_prefix, tag, attachment_kind_scheme]
     # => [NOTE_METADATA_HEADER]
 end
 

crates/miden-protocol/asm/protocol/note.masm

@@ -4,6 +4,8 @@ use miden::core::mem
 
 # Re-export the max inputs per note constant.
 pub use miden::protocol::util::note::MAX_NOTE_STORAGE_ITEMS
+pub use miden::protocol::util::note::NOTE_TYPE_PUBLIC
+pub use miden::protocol::util::note::NOTE_TYPE_PRIVATE
 
 # ERRORS
 # =================================================================================================
@@ -184,11 +186,11 @@ end
 #! - sender_{suffix,prefix} are the suffix and prefix felts of the sender ID of the note which
 #!   metadata was provided.
 pub proc extract_sender_from_metadata
-    # => [sender_id_suffix_and_note_type, sender_id_prefix, tag, attachment_kind_scheme]
+    # => [sender_id_suffix_type_version, sender_id_prefix, tag, attachment_kind_scheme]
 
     # drop tag and attachment_kind_scheme
     movup.3 drop movup.2 drop
-    # => [sender_id_suffix_and_note_type, sender_id_prefix]
+    # => [sender_id_suffix_type_version, sender_id_prefix]
 
     # extract suffix of sender from merged layout, which means clearing the least significant byte
     exec.account_id::shape_suffix
@@ -207,7 +209,7 @@ end
 #!
 #! Invocation: exec
 pub proc extract_attachment_info_from_metadata
-    # => [sender_id_suffix_and_note_type, sender_id_prefix, tag, attachment_kind_scheme]
+    # => [sender_id_suffix_type_version, sender_id_prefix, tag, attachment_kind_scheme]
     drop drop drop
     # => [attachment_kind_scheme]
 

crates/miden-protocol/asm/shared_utils/util/note.masm

@@ -10,3 +10,12 @@ pub const ATTACHMENT_KIND_NONE=0
 pub const ATTACHMENT_KIND_WORD=1
 #! A note attachment consisting of the commitment to a set of felts.
 pub const ATTACHMENT_KIND_ARRAY=2
+
+# Note type constants. These encode the note type in the lower byte of the metadata header.
+# See NoteType in the Rust protocol crate for details.
+
+#! The note type of private notes.
+pub const NOTE_TYPE_PRIVATE=0
+
+#! The note type of public notes.
+pub const NOTE_TYPE_PUBLIC=1

crates/miden-protocol/src/note/metadata.rs

@@ -14,6 +14,12 @@ use crate::Hasher;
 use crate::errors::NoteError;
 use crate::note::{NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme};
 
+// CONSTANTS
+// ================================================================================================
+
+/// The number of bits by which the note type is offset in the first felt of the note metadata.
+const NOTE_TYPE_SHIFT: u64 = 4;
+
 // NOTE METADATA
 // ================================================================================================
 
@@ -34,7 +40,7 @@ use crate::note::{NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme};
 /// The header word has the following layout:
 ///
 /// ```text
-/// 0th felt: [sender_id_suffix (56 bits) | 6 zero bits | note_type (2 bit)]
+/// 0th felt: [sender_id_suffix (56 bits) | reserved (3 bits) | note_type (1 bit) | version (4 bits)]
 /// 1st felt: [sender_id_prefix (64 bits)]
 /// 2nd felt: [32 zero bits | note_tag (32 bits)]
 /// 3rd felt: [30 zero bits | attachment_kind (2 bits) | attachment_scheme (32 bits)]
@@ -44,11 +50,13 @@ use crate::note::{NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme};
 /// - 1st felt: The lower 8 bits of the account ID suffix are `0` by construction, so that they can
 ///   be overwritten with other data. The suffix' most significant bit must be zero such that the
 ///   entire felt retains its validity even if all of its lower 8 bits are set to `1`. So the note
-///   type can be comfortably encoded.
+///   type and version can be comfortably encoded.
 /// - 2nd felt: Is equivalent to the prefix of the account ID so it inherits its validity.
 /// - 3rd felt: The upper 32 bits are always zero.
 /// - 4th felt: The upper 30 bits are always zero.
 ///
+/// The version is hardcoded to 0 and is reserved to make it easier to introduce another version.
+///
 /// The value of the attachment word depends on the
 /// [`NoteAttachmentKind`](crate::note::NoteAttachmentKind):
 /// - [`NoteAttachmentKind::None`](crate::note::NoteAttachmentKind::None): Empty word.
@@ -73,6 +81,12 @@ pub struct NoteMetadata {
 }
 
 impl NoteMetadata {
+    /// Version 0 of the note metadata encoding.
+    ///
+    /// If we make this public, we may want to instead consider introducing a `NoteMetadataVersion`
+    /// struct, similar to `AccountIdVersion`.
+    const VERSION_0: u8 = 0;
+
     // CONSTRUCTORS
     // --------------------------------------------------------------------------------------------
 
@@ -337,12 +351,12 @@ impl TryFrom<Word> for NoteMetadataHeader {
 // HELPER FUNCTIONS
 // ================================================================================================
 
-/// Merges the suffix of an [`AccountId`] and the [`NoteType`] into a single [`Felt`].
+/// Merges the suffix of an [`AccountId`] and note metadata into a single [`Felt`].
 ///
 /// The layout is as follows:
 ///
 /// ```text
-/// [sender_id_suffix (56 bits) | 6 zero bits | note_type (2 bits)]
+/// [sender_id_suffix (56 bits) | reserved (3 bits) | note_type (1 bit) | version (4 bits)]
 /// ```
 ///
 /// The most significant bit of the suffix is guaranteed to be zero, so the felt retains its
@@ -353,28 +367,44 @@ fn merge_sender_suffix_and_note_type(sender_id_suffix: Felt, note_type: NoteType
     let mut merged = sender_id_suffix.as_canonical_u64();
 
     let note_type_byte = note_type as u8;
-    debug_assert!(note_type_byte < 4, "note type must not contain values >= 4");
-    merged |= note_type_byte as u64;
+    debug_assert!(note_type_byte < 2, "note type must not contain values >= 2");
+    // note_type at bit 4, version at bits 0..=3 (hardcoded to NoteMetadata::VERSION_0_NUMBER)
+    merged |= (note_type_byte as u64) << NOTE_TYPE_SHIFT;
+    merged |= NoteMetadata::VERSION_0 as u64;
 
     // SAFETY: The most significant bit of the suffix is zero by construction so the u64 will be a
     // valid felt.
     Felt::try_from(merged).expect("encoded value should be a valid felt")
 }
 
-/// Unmerges the sender ID suffix and note type.
+/// Unmerges the sender ID suffix and note metadata (note type and version).
 fn unmerge_sender_suffix_and_note_type(element: Felt) -> Result<(Felt, NoteType), NoteError> {
-    const NOTE_TYPE_MASK: u8 = 0b11;
-    // Inverts the note type mask.
-    const SENDER_SUFFIX_MASK: u64 = !(NOTE_TYPE_MASK as u64);
+    // The mask that clears out the lower 8 bits to recover the sender suffix.
+    const SENDER_SUFFIX_MASK: u64 = 0xffff_ffff_ffff_ff00;
+
+    let raw = element.as_canonical_u64();
+    let version = (raw & 0b1111) as u8;
+    let note_type_bit = ((raw >> NOTE_TYPE_SHIFT) & 0b1) as u8;
+    let reserved = ((raw >> 5) & 0b111) as u8;
+
+    if reserved != 0 {
+        return Err(NoteError::other("reserved bits in note metadata header must be zero"));
+    }
+
+    if version != NoteMetadata::VERSION_0 {
+        return Err(NoteError::other(format!(
+            "unsupported note metadata version {version}, expected {}",
+            NoteMetadata::VERSION_0
+        )));
+    }
 
-    let note_type_byte = element.as_canonical_u64() as u8 & NOTE_TYPE_MASK;
-    let note_type = NoteType::try_from(note_type_byte).map_err(|source| {
+    let note_type = NoteType::try_from(note_type_bit).map_err(|source| {
         NoteError::other_with_source("failed to decode note type from metadata header", source)
     })?;
 
     // No bits were set so felt should still be valid.
-    let sender_suffix = Felt::try_from(element.as_canonical_u64() & SENDER_SUFFIX_MASK)
-        .expect("felt should still be valid");
+    let sender_suffix =
+        Felt::try_from(raw & SENDER_SUFFIX_MASK).expect("felt should still be valid");
 
     Ok((sender_suffix, note_type))
 }