feat: add output_not_set_attachment kernel API (#2252)

* feat: Implement `output_note_set_attachment` kernel API

* feat: Implement `miden::protocol` set_attachment wrappers

* feat: Emit event during `set_attachment` for tx host

* chore: add tests for `set_attachment` APIs

* chore: regenerate kernel procedure hashes

* chore: add changelog

* chore: rename `Raw` -> `Word` and `Commitment` -> `Array`

* fix: renamed attachment content variants

* chore: make attachment content type constants public

* chore: move note ptr to idx conversion to helper

* chore: merge attachment validation procedures into one

* chore: simplify setting output note attachment type info

* chore: make `set_attachment` public

* fix: commitment to array rename

* chore: require attachment_type == 0 when content type is None

* chore: enforce none / attachment type restriction in `NoteAttachment`

Author: PhilippGackstatter

CHANGELOG.md

@@ -10,6 +10,7 @@
 - Add `AccountId::parse()` helper function to parse both hex and bech32 formats ([#2223](https://github.com/0xMiden/miden-base/pull/2223)).
 - Add `read_foreign_account_inputs()`, `read_vault_asset_witnesses()`, and `read_storage_map_witness()` for `TransactionInputs` ([#2246](https://github.com/0xMiden/miden-base/pull/2246)).
 - [BREAKING] Introduce `NoteAttachment` as part of `NoteMetadata` and remove `aux` and `execution_hint` ([#2249](https://github.com/0xMiden/miden-base/pull/2249)).
+- [BREAKING] Introduce `NoteAttachment` as part of `NoteMetadata` and remove `aux` and `execution_hint` ([#2249](https://github.com/0xMiden/miden-base/pull/2249), [#2252](https://github.com/0xMiden/miden-base/pull/2252)).
 
 ### Changes
 

crates/miden-protocol/asm/kernels/transaction/api.masm

@@ -1189,6 +1189,33 @@ pub proc output_note_add_asset
     # => [pad(16)]
 end
 
+#! Sets the attachment of the note specified by the index.
+#!
+#! Inputs:  [note_idx, attachment_content_type, attachment_type, ATTACHMENT, pad(9)]
+#! Outputs: [pad(16)]
+#!
+#! Where:
+#! - note_idx is the index of the note on which the attachment is set.
+#! - attachment_content_type is the content type of the attachment.
+#! - attachment_type is the user-defined type of the attachment.
+#! - ATTACHMENT is the attachment to be set.
+#!
+#! Panics if:
+#! - the procedure is called when the active account is not the native one.
+#! - the note index points to a non-existent output note.
+#! - any of the attachment types does not fit into a u32.
+#! - the attachment content type is an unknown variant.
+#!
+#! Invocation: dynexec
+pub proc output_note_set_attachment
+    # check that this procedure was executed against the native account
+    exec.memory::assert_native_account
+    # => [note_idx, attachment_content_type, attachment_type, ATTACHMENT, pad(9)]
+
+    exec.output_note::set_attachment
+    # => [pad(16)]
+end
+
 #! Returns the information about assets in the output note with the specified index.
 #!
 #! Inputs:  [note_index, pad(15)]

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

@@ -240,6 +240,7 @@ const OUTPUT_NOTE_SECTION_OFFSET=16777216
 # The offsets at which data of an output note is stored relative to the start of its data segment.
 const OUTPUT_NOTE_ID_OFFSET=0
 const OUTPUT_NOTE_METADATA_HEADER_OFFSET=4
+const OUTPUT_NOTE_METADATA_ATTACHMENT_TYPE_INFO_OFFSET=OUTPUT_NOTE_METADATA_HEADER_OFFSET + 3
 const OUTPUT_NOTE_ATTACHMENT_OFFSET=8
 const OUTPUT_NOTE_RECIPIENT_OFFSET=12
 const OUTPUT_NOTE_ASSETS_COMMITMENT_OFFSET=16
@@ -1891,6 +1892,19 @@ pub proc set_output_note_metadata_header
     mem_storew_be
 end
 
+#! Sets the output note's attachment type info in the metadata header.
+#!
+#! Inputs:  [note_ptr, attachment_type_info]
+#! Outputs: []
+#!
+#! Where:
+#! - attachment_type_info is the type information of the attachment that will be overwritten.
+#! - note_ptr is the memory address at which the output note data begins.
+pub proc set_output_note_attachment_type_info
+    add.OUTPUT_NOTE_METADATA_ATTACHMENT_TYPE_INFO_OFFSET
+    mem_store
+end
+
 #! Returns the output note's attachment.
 #!
 #! Inputs:  [note_ptr]

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

@@ -3,6 +3,7 @@ use $kernel::memory
 use $kernel::note
 use $kernel::asset
 use $kernel::constants::MAX_OUTPUT_NOTES_PER_TX
+use miden::core::mem
 use miden::core::word
 
 # CONSTANTS
@@ -23,6 +24,9 @@ const ATTACHMENT_CONTENT_TYPE_ARRAY=2
 # "untyped".
 const ATTACHMENT_DEFAULT_TYPE_INFO=0
 
+#! The default attachment type, representing an untyped attachment.
+const ATTACHMENT_TYPE_UNTYPED=0
+
 # ERRORS
 # =================================================================================================
 
@@ -32,6 +36,14 @@ const ERR_NOTE_INVALID_TYPE="invalid note type"
 
 const ERR_OUTPUT_NOTE_INDEX_OUT_OF_BOUNDS="requested output note index should be less than the total number of created output notes"
 
+const ERR_OUTPUT_NOTE_INVALID_ATTACHMENT_TYPES="attachment types must fit into u32s"
+
+const ERR_OUTPUT_NOTE_UNKNOWN_ATTACHMENT_CONTENT_TYPE="attachment content type variant must be between 0 and 2"
+
+const ERR_OUTPUT_NOTE_ATTACHMENT_NONE_MUST_HAVE_UNTYPED_ATTACHMENT_TYPE="attachment type of content type none must be 0"
+
+const ERR_OUTPUT_NOTE_ATTACHMENT_NONE_MUST_BE_EMPTY_WORD="attachment of content type none must be set to an empty word"
+
 const ERR_NOTE_INVALID_INDEX="failed to find note at the given index; index must be within [0, num_of_notes]"
 
 const ERR_NOTE_FUNGIBLE_MAX_AMOUNT_EXCEEDED="adding a fungible asset to a note cannot exceed the max_amount of 9223372036854775807"
@@ -53,6 +65,9 @@ const NOTE_BEFORE_ADD_ASSET_EVENT=event("miden::note::before_add_asset")
 # Event emitted after an ASSET is added to a note
 const NOTE_AFTER_ADD_ASSET_EVENT=event("miden::note::after_add_asset")
 
+# Event emitted before an ATTACHMENT is added to a note
+const NOTE_BEFORE_SET_ATTACHMENT_EVENT=event("miden::note::before_set_attachment")
+
 # OUTPUT NOTE PROCEDURES
 # =================================================================================================
 
@@ -185,6 +200,7 @@ end
 #! - ASSET can be a fungible or non-fungible asset.
 #!
 #! Panics if:
+#! - the note index points to a non-existent output note.
 #! - the ASSET is malformed (e.g., invalid faucet ID).
 #! - the max amount of fungible assets is exceeded.
 #! - the non-fungible asset already exists in the note.
@@ -239,6 +255,51 @@ pub proc add_asset
     # => []
 end
 
+#! Sets the attachment of the note specified by the index.
+#!
+#! Inputs:  [note_idx, attachment_content_type, attachment_type, ATTACHMENT]
+#! Outputs: []
+#!
+#! Where:
+#! - note_idx is the index of the note on which the attachment is set.
+#! - attachment_content_type is the content type of the attachment.
+#! - attachment_type is the user-defined type of the attachment.
+#! - ATTACHMENT is the attachment to be set.
+#!
+#! Panics if:
+#! - the note index points to a non-existent output note.
+#! - any of the attachment types does not fit into a u32.
+#! - the attachment content type is an unknown variant.
+pub proc set_attachment
+    dup exec.memory::get_num_output_notes lte assert.err=ERR_NOTE_INVALID_INDEX
+    # => [note_idx, attachment_content_type, attachment_type, ATTACHMENT]
+
+    exec.memory::get_output_note_ptr dup
+    # => [note_ptr, note_ptr, attachment_content_type, attachment_type, ATTACHMENT]
+
+    dupw.1
+    # => [ATTACHMENT, note_ptr, note_ptr, attachment_content_type, attachment_type, ATTACHMENT]
+
+    dup.7 dup.7
+    # => [attachment_content_type, attachment_type, ATTACHMENT, note_ptr, note_ptr,
+    #     attachment_content_type, attachment_type, ATTACHMENT]
+
+    exec.validate_attachment
+    # => [note_ptr, note_ptr, attachment_content_type, attachment_type, ATTACHMENT]
+
+    movdn.3 movdn.3
+    # => [attachment_content_type, attachment_type, note_ptr, note_ptr, ATTACHMENT]
+
+    emit.NOTE_BEFORE_SET_ATTACHMENT_EVENT
+    # => [attachment_content_type, attachment_type, note_ptr, note_ptr, ATTACHMENT]
+
+    exec.set_attachment_type_info
+    # => [note_ptr, ATTACHMENT]
+
+    exec.memory::set_output_note_attachment
+    # => []
+end
+
 #! Assert that the provided note index is less than the total number of output notes.
 #!
 #! Inputs:  [note_index]
@@ -306,6 +367,89 @@ pub proc build_metadata_header
     # => [NOTE_METADATA_HEADER]
 end
 
+#! Validate the ATTACHMENT against the content type.
+#!
+#! Inputs:  [attachment_content_type, attachment_type, ATTACHMENT]
+#! Outputs: []
+#!
+#! Where:
+#! - attachment_type is the user-defined type of the attachment.
+#! - attachment_content_type is the content type of the attachment.
+#! - ATTACHMENT is the attachment to validate.
+#!
+#! Panics if:
+#! - any of the attachment types does not fit into a u32.
+#! - the attachment content type is an unknown variant.
+#! - the content type is None and the ATTACHMENT is not an empty word.
+proc validate_attachment
+    u32assert2.err=ERR_OUTPUT_NOTE_INVALID_ATTACHMENT_TYPES
+    # => [attachment_content_type, attachment_type, ATTACHMENT]
+
+    # assert that the attachment content type is valid
+    dup u32lte.ATTACHMENT_CONTENT_TYPE_ARRAY
+    assert.err=ERR_OUTPUT_NOTE_UNKNOWN_ATTACHMENT_CONTENT_TYPE
+    # => [attachment_content_type, attachment_type, ATTACHMENT]
+
+    eq.ATTACHMENT_CONTENT_TYPE_NONE
+    # => [is_attachment_none, attachment_type, ATTACHMENT]
+
+    if.true
+        eq.ATTACHMENT_TYPE_UNTYPED
+        assert.err=ERR_OUTPUT_NOTE_ATTACHMENT_NONE_MUST_HAVE_UNTYPED_ATTACHMENT_TYPE
+        # => [ATTACHMENT]
+
+        padw assert_eqw.err=ERR_OUTPUT_NOTE_ATTACHMENT_NONE_MUST_BE_EMPTY_WORD
+        # => []
+    else
+        drop dropw
+        # => []
+    end
+    # => []
+end
+
+#! Sets an output note's attachment type info in the metadata header.
+#!
+#! WARNING: The attachment types must be valid.
+#!
+#! Inputs:  [attachment_content_type, attachment_type, note_ptr]
+#! Outputs: []
+#!
+#! Where:
+#! - attachment_content_type is the content type of the attachment.
+#! - attachment_type is the user-defined type of the attachment.
+#! - note_ptr is the memory address at which the output note data begins.
+proc set_attachment_type_info
+    exec.merge_attachment_type_info
+    # => [attachment_type_info, note_ptr]
+
+    swap
+    # => [note_ptr, attachment_type_info]
+
+    exec.memory::set_output_note_attachment_type_info
+    # => []
+end
+
+#! Merges the attachment types into a single felt with the following layout:
+#!
+#! [30 zero bits | attachment_content_type (2 bits) | attachment_type (32 bits)]
+#!
+#! WARNING: The attachment types must be valid.
+#!
+#! Inputs:  [attachment_content_type, attachment_type]
+#! Outputs: [attachment_type_info]
+#!
+#! Where:
+#! - attachment_content_type is the content type of the attachment.
+#! - attachment_type is the user-defined type of the attachment.
+#! - attachment_type_info is the felt constructed from the inputs.
+proc merge_attachment_type_info
+    # shift the content type 32 bits to the left, which is the same as multiplying by 2^32
+    # and set the lower bits to the attachment_type, which is done by adding the values together
+    mul.0x100000000
+    add
+    # => [attachment_type_info]
+end
+
 #! Increments the number of output notes by one. Returns the index of the next note to be created.
 #!
 #! Inputs:  []

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

@@ -67,29 +67,30 @@ const OUTPUT_NOTE_GET_METADATA_OFFSET=37
 const OUTPUT_NOTE_GET_ASSETS_INFO_OFFSET=38
 const OUTPUT_NOTE_GET_RECIPIENT_OFFSET=39
 const OUTPUT_NOTE_ADD_ASSET_OFFSET=40
+const OUTPUT_NOTE_SET_ATTACHMENT_OFFSET=41
 
 ### Tx ##########################################
 
 # input notes
-const TX_GET_NUM_INPUT_NOTES_OFFSET=41
-const TX_GET_INPUT_NOTES_COMMITMENT_OFFSET=42
+const TX_GET_NUM_INPUT_NOTES_OFFSET=42
+const TX_GET_INPUT_NOTES_COMMITMENT_OFFSET=43
 
 # output notes
-const TX_GET_NUM_OUTPUT_NOTES_OFFSET=43
-const TX_GET_OUTPUT_NOTES_COMMITMENT_OFFSET=44
+const TX_GET_NUM_OUTPUT_NOTES_OFFSET=44
+const TX_GET_OUTPUT_NOTES_COMMITMENT_OFFSET=45
 
 # block info
-const TX_GET_BLOCK_COMMITMENT_OFFSET=45
-const TX_GET_BLOCK_NUMBER_OFFSET=46
-const TX_GET_BLOCK_TIMESTAMP_OFFSET=47
+const TX_GET_BLOCK_COMMITMENT_OFFSET=46
+const TX_GET_BLOCK_NUMBER_OFFSET=47
+const TX_GET_BLOCK_TIMESTAMP_OFFSET=48
 
 # foreign context
-const TX_START_FOREIGN_CONTEXT_OFFSET=48
-const TX_END_FOREIGN_CONTEXT_OFFSET=49
+const TX_START_FOREIGN_CONTEXT_OFFSET=49
+const TX_END_FOREIGN_CONTEXT_OFFSET=50
 
 # expiration data
-const TX_GET_EXPIRATION_DELTA_OFFSET=50               # accessor
-const TX_UPDATE_EXPIRATION_BLOCK_DELTA_OFFSET=51      # mutator
+const TX_GET_EXPIRATION_DELTA_OFFSET=51               # accessor
+const TX_UPDATE_EXPIRATION_BLOCK_DELTA_OFFSET=52      # mutator
 
 # ACCESSORS
 # -------------------------------------------------------------------------------------------------
@@ -484,6 +485,19 @@ pub proc output_note_add_asset_offset
     push.OUTPUT_NOTE_ADD_ASSET_OFFSET
 end
 
+#! Returns the offset of the `output_note_set_attachment` kernel procedure.
+#!
+#! Inputs:  []
+#! Outputs: [proc_offset]
+#!
+#! Where:
+#! - proc_offset is the offset of the `output_note_set_attachment` kernel procedure required to get
+#!   the address where this procedure is stored.
+pub proc output_note_set_attachment_offset
+    push.OUTPUT_NOTE_SET_ATTACHMENT_OFFSET
+end
+
+
 #! Returns the offset of the `output_note_get_assets_info` kernel procedure.
 #!
 #! Inputs:  []