miden-protocol 0.16.0-alpha.4

use {INPUT_NOTE_GET_ASSET_OFFSET, INPUT_NOTE_GET_ATTACHMENTS_COMMITMENT_OFFSET, INPUT_NOTE_GET_INITIAL_ASSETS_INFO_OFFSET, INPUT_NOTE_GET_METADATA_OFFSET, INPUT_NOTE_GET_RECIPIENT_OFFSET, INPUT_NOTE_GET_SCRIPT_ROOT_OFFSET, INPUT_NOTE_GET_SERIAL_NUMBER_OFFSET, INPUT_NOTE_GET_STORAGE_INFO_OFFSET, INPUT_NOTE_REMOVE_ALL_ASSETS_OFFSET, INPUT_NOTE_REMOVE_ASSET_OFFSET}
    from miden::protocol::kernel_proc_offsets
use miden::protocol::note
use {AccountId, Bool, MemoryAddress, NoteMetadata, NoteRecipient, NoteScriptRoot}
    from miden::protocol::types

# PROCEDURES
# =================================================================================================

#! Writes the initial assets of the input note with the specified index into memory starting at
#! the specified address.
#!
#! The written assets are the ones the note was created with; they are unaffected by asset removal
#! during transaction execution.
#!
#! Attention: memory starting from the `dest_ptr` should have enough space to store all the assets
#! the note was created with. Make sure that at least `8 * num_assets` memory elements are
#! available, or if the number of assets is not yet known, at least `8 * MAX_ASSETS_PER_NOTE`.
#!
#! The memory layout after the execution of this procedure will look like so:
#! [ASSET_ID_0, ASSET_VALUE_0, ASSET_ID_1, ASSET_VALUE_1, ..., ASSET_ID_N, ASSET_VALUE_N], where
#! each asset occupies two words. For more detailed information about the layout of each asset see
#! the description of the `Asset` Rust type.
#!
#! Inputs:  [dest_ptr, note_index]
#! Outputs: [num_assets]
#!
#! Where:
#! - dest_ptr is the memory address to write the assets.
#! - note_index is the index of the input note whose initial assets should be written.
#! - num_assets is the number of assets the note was created with.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_initial_assets
    swap push.0
    # => [is_active_note = 0, note_index, dest_ptr]

    exec.get_initial_assets_raw
    # => [num_assets]
end

#! Writes the initial assets of the input note with the specified index or the active note,
#! depending on the provided flag, into memory starting at the specified address.
#!
#! This is the shared implementation used by both `input_note::get_initial_assets` and
#! `active_note::get_initial_assets`. See `input_note::get_initial_assets` for details on the
#! memory requirements and layout at `dest_ptr`.
#!
#! Inputs:  [is_active_note, note_index, dest_ptr]
#! Outputs: [num_assets]
#!
#! Where:
#! - is_active_note is 0 for indexed access, 1 for the currently active note.
#! - note_index is the index of the input note.
#! - dest_ptr is the memory address to write the assets.
#! - num_assets is the number of assets the note was created with.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_initial_assets_raw
    exec.get_initial_assets_info_raw
    # => [ASSETS_COMMITMENT, num_assets, dest_ptr]

    # save num_assets for the return value
    dup.4 movdn.6
    # => [ASSETS_COMMITMENT, num_assets, dest_ptr, num_assets]

    # write the assets stored in the advice map to the specified memory pointer
    exec.note::write_assets_to_memory
    # => [num_assets]
end

#! Returns the initial assets information of the input note with the specified index.
#!
#! The returned commitment and number of assets are the ones the note was created with; they do
#! not change when assets are removed from the note during transaction execution.
#!
#! Inputs:  [note_index]
#! Outputs: [ASSETS_COMMITMENT, num_assets]
#!
#! Where:
#! - note_index is the index of the input note whose assets info should be returned.
#! - num_assets is the number of assets the note was created with.
#! - ASSETS_COMMITMENT is a sequential hash of the assets the note was created with.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_initial_assets_info(note_index: u16) -> (word, u8)
    push.0
    # => [is_active_note = 0, note_index]

    exec.get_initial_assets_info_raw
    # => [ASSETS_COMMITMENT, num_assets]
end

#! Returns the initial assets information of the input note with the specified index or the
#! active note, depending on the provided flag.
#!
#! This is the shared implementation used by both `input_note::get_initial_assets_info` and
#! `active_note::get_initial_assets_info`.
#!
#! Inputs:  [is_active_note, note_index]
#! Outputs: [ASSETS_COMMITMENT, num_assets]
#!
#! Where:
#! - is_active_note is 0 for indexed access, 1 for the currently active note.
#! - note_index is the index of the input note.
#! - num_assets is the number of assets the note was created with.
#! - ASSETS_COMMITMENT is a sequential hash of the assets the note was created with.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_initial_assets_info_raw
    push.0 movdn.2
    # => [is_active_note, note_index, 0]

    push.INPUT_NOTE_GET_INITIAL_ASSETS_INFO_OFFSET
    # => [offset, is_active_note, note_index, 0]

    # pad the stack
    padw swapw padw padw swapdw
    # => [offset, is_active_note, note_index, pad(13)]

    syscall.exec_kernel_proc
    # => [ASSETS_COMMITMENT, num_assets, pad(11)]

    # clean the stack
    swapdw dropw dropw
    repeat.3
        movup.5 drop
    end
    # => [ASSETS_COMMITMENT, num_assets]
end

#! Returns the number of assets the input note with the specified index was created with.
#!
#! The returned number does not change when assets are removed from the note during transaction
#! execution.
#!
#! Inputs:  [note_index]
#! Outputs: [num_assets]
#!
#! Where:
#! - note_index is the index of the input note whose number of assets should be returned.
#! - num_assets is the number of assets the note was created with.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_initial_num_assets
    exec.get_initial_assets_info
    # => [ASSETS_COMMITMENT, num_assets]

    dropw
    # => [num_assets]
end

#! Returns the asset at the specified index in the input note with the specified index.
#!
#! The asset is returned as it currently is: if it was removed from the note, the returned
#! ASSET_ID and ASSET_VALUE are both the EMPTY_WORD.
#!
#! Inputs:  [asset_index, note_index]
#! Outputs: [ASSET_ID, ASSET_VALUE]
#!
#! Where:
#! - asset_index is the index of the asset to return.
#! - note_index is the index of the input note whose asset should be returned.
#! - ASSET_ID is the asset ID of the asset at the specified index.
#! - ASSET_VALUE is the value of the asset at the specified index.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#! - the asset index is greater or equal to the number of assets in the note.
#!
#! Invocation: exec
pub proc get_asset
    push.0
    # => [is_active_note = 0, asset_index, note_index]

    exec.get_asset_raw
    # => [ASSET_ID, ASSET_VALUE]
end

#! Returns the asset at the specified index in the input note with the specified index or the
#! active note, depending on the provided flag.
#!
#! This is the shared implementation used by both `input_note::get_asset` and
#! `active_note::get_asset`.
#!
#! Inputs:  [is_active_note, asset_index, note_index]
#! Outputs: [ASSET_ID, ASSET_VALUE]
#!
#! Where:
#! - is_active_note is 0 for indexed access, 1 for the currently active note.
#! - asset_index is the index of the asset to return.
#! - note_index is the index of the input note.
#! - ASSET_ID is the asset ID of the asset at the specified index.
#! - ASSET_VALUE is the value of the asset at the specified index.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#! - the asset index is greater or equal to the number of assets in the note.
#!
#! Invocation: exec
pub proc get_asset_raw
    push.INPUT_NOTE_GET_ASSET_OFFSET
    # => [offset, is_active_note, asset_index, note_index]

    # pad the stack
    padw swapw padw padw swapdw
    # => [offset, is_active_note, asset_index, note_index, pad(12)]

    syscall.exec_kernel_proc
    # => [ASSET_ID, ASSET_VALUE, pad(8)]

    # clean the stack
    swapdw dropw dropw
    # => [ASSET_ID, ASSET_VALUE]
end

#! Removes an asset from the input note with the specified index.
#!
#! For instance, if the note holds a fungible asset with amount 100 under ASSET_ID, and
#! ASSET_VALUE has amount 30, then the value remaining in the note has amount 70.
#!
#! If the entire asset value is removed, the asset's slot in the note is cleared, i.e. the asset
#! at the corresponding index becomes (EMPTY_WORD, EMPTY_WORD). This is always the case for
#! non-composable assets.
#!
#! Inputs:  [ASSET_ID, ASSET_VALUE, note_index]
#! Outputs: [FINAL_ASSET_VALUE]
#!
#! Where:
#! - ASSET_ID is the asset ID of the asset to remove from the note.
#! - ASSET_VALUE is the value of the asset to remove from the note.
#! - note_index is the index of the input note from which the asset should be removed.
#! - FINAL_ASSET_VALUE is the value of the asset remaining in the note after removal, which is
#!   the EMPTY_WORD if the entire asset was removed.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#! - the asset's composition is Custom (not yet supported).
#! - the asset is not present in the note.
#! - the asset is not composable and is not present in the note with the exact value.
#! - the amount of the fungible asset in the note is less than the amount to be removed.
#!
#! Invocation: exec
pub proc remove_asset
    push.0
    # => [is_active_note = 0, ASSET_ID, ASSET_VALUE, note_index]

    exec.remove_asset_raw
    # => [FINAL_ASSET_VALUE]
end

#! Removes an asset from the input note with the specified index or the active note, depending on
#! the provided flag.
#!
#! This is the shared implementation used by both `input_note::remove_asset` and
#! `active_note::remove_asset`.
#!
#! Inputs:  [is_active_note, ASSET_ID, ASSET_VALUE, note_index]
#! Outputs: [FINAL_ASSET_VALUE]
#!
#! Where:
#! - is_active_note is 0 for indexed access, 1 for the currently active note.
#! - ASSET_ID is the asset ID of the asset to remove from the note.
#! - ASSET_VALUE is the value of the asset to remove from the note.
#! - note_index is the index of the input note.
#! - FINAL_ASSET_VALUE is the value of the asset remaining in the note after removal, which is
#!   the EMPTY_WORD if the entire asset was removed.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#! - the asset's composition is Custom (not yet supported).
#! - the asset is not present in the note.
#! - the asset is not composable and is not present in the note with the exact value.
#! - the amount of the fungible asset in the note is less than the amount to be removed.
#!
#! Invocation: exec
pub proc remove_asset_raw
    push.INPUT_NOTE_REMOVE_ASSET_OFFSET
    # => [offset, is_active_note, ASSET_ID, ASSET_VALUE, note_index]

    # pad the stack
    repeat.5
        push.0 movdn.11
    end
    # => [offset, is_active_note, ASSET_ID, ASSET_VALUE, note_index, pad(5)]

    syscall.exec_kernel_proc
    # => [FINAL_ASSET_VALUE, pad(12)]

    # clean the stack
    swapdw dropw dropw swapw dropw
    # => [FINAL_ASSET_VALUE]
end

#! Removes all remaining assets from the input note with the specified index and writes them into
#! memory starting at the specified address.
#!
#! The written assets are the ones that remained in the note at the time of the call, i.e.
#! excluding assets that were already removed. After this procedure returns, the note holds no
#! more assets; the written memory is a snapshot of the removed assets. The note's initial assets
#! info (see get_initial_assets_info) is not affected.
#!
#! Attention: memory starting from the `dest_ptr` should have enough space to store all the assets
#! in the specified note. Make sure that at least `8 * num_assets` memory elements are available,
#! or if the number of assets is not yet known, at least `8 * MAX_ASSETS_PER_NOTE`.
#!
#! The memory layout after the execution of this procedure will look like so:
#! [ASSET_0, ASSET_1, ..., ASSET_N], where each asset occupies two words. For more detailed
#! information about the layout of each asset see the description of the `Asset` Rust type.
#!
#! Inputs:  [dest_ptr, note_index]
#! Outputs: [num_assets]
#!
#! Where:
#! - dest_ptr is the memory address to write the assets.
#! - note_index is the index of the input note from which the assets should be removed.
#! - num_assets is the number of assets removed by this procedure.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc remove_all_assets
    swap push.0
    # => [is_active_note = 0, note_index, dest_ptr]

    exec.remove_all_assets_raw
    # => [num_assets]
end

#! Removes all remaining assets from the input note with the specified index or the active note,
#! depending on the provided flag, and writes them into memory starting at the specified address.
#!
#! This is the shared implementation used by both `input_note::remove_all_assets` and
#! `active_note::remove_all_assets`. See `input_note::remove_all_assets` for details on the
#! memory requirements and layout at `dest_ptr`.
#!
#! Inputs:  [is_active_note, note_index, dest_ptr]
#! Outputs: [num_assets]
#!
#! Where:
#! - is_active_note is 0 for indexed access, 1 for the currently active note.
#! - note_index is the index of the input note.
#! - dest_ptr is the memory address to write the assets.
#! - num_assets is the number of assets removed by this procedure.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc remove_all_assets_raw(is_active_note: Bool, dest_ptr: MemoryAddress, note_index: u16) -> u8
    push.0 movdn.2
    # => [is_active_note, note_index, 0, dest_ptr]

    push.INPUT_NOTE_REMOVE_ALL_ASSETS_OFFSET
    # => [offset, is_active_note, note_index, 0, dest_ptr]

    # pad the stack
    padw swapw padw padw swapdw
    # => [offset, is_active_note, note_index, pad(13), dest_ptr]

    syscall.exec_kernel_proc
    # => [ASSETS_COMMITMENT, num_assets, pad(11), dest_ptr]

    # clean the stack
    swapdw dropw dropw
    repeat.3
        movup.5 drop
    end
    # => [ASSETS_COMMITMENT, num_assets, dest_ptr]

    # save num_assets for the return value
    dup.4 movdn.6
    # => [ASSETS_COMMITMENT, num_assets, dest_ptr, num_assets]

    # write the removed assets stored in the advice map to the specified memory pointer
    exec.note::write_assets_to_memory
    # => [num_assets]
end

#! Returns the recipient of the input note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [RECIPIENT]
#!
#! Where:
#! - note_index is the index of the input note whose recipient should be returned.
#! - RECIPIENT is the commitment to the input note's script, storage, the serial number.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_recipient(note_index: u16) -> NoteRecipient
    # start padding the stack
    push.0 swap
    # => [note_index, 0]

    # push the flag indicating that we want to request assets info from the note with the specified
    # index
    push.0
    # => [is_active_note = 0, note_index, 0]

    push.INPUT_NOTE_GET_RECIPIENT_OFFSET
    # => [offset, is_active_note = 0, note_index, 0]

    # pad the stack
    padw swapw padw padw swapdw
    # => [offset, note_index, pad(14)]

    syscall.exec_kernel_proc
    # => [RECIPIENT, pad(12)]

    # clean the stack
    swapdw dropw dropw swapw dropw
    # => [RECIPIENT]
end

#! Returns the metadata of the input note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [METADATA]
#!
#! Where:
#! - note_index is the index of the input note whose metadata should be returned.
#! - METADATA is the metadata of the specified input note.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_metadata(note_index: u16) -> NoteMetadata
    # start padding the stack
    push.0 swap
    # => [note_index, 0]

    # push the flag indicating that we want to request metadata from the note with the specified
    # index
    push.0
    # => [is_active_note = 0, note_index, 0]

    push.INPUT_NOTE_GET_METADATA_OFFSET
    # => [offset, is_active_note = 0, note_index, 0]

    # pad the stack
    padw swapw padw padw swapdw
    # => [offset, is_active_note = 0, note_index, pad(13)]

    syscall.exec_kernel_proc
    # => [METADATA, pad(12)]

    # clean the stack
    swapdw dropw dropw swapw dropw
    # => [METADATA]
end

#! Returns the sender of the input note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [sender_id_suffix, sender_id_prefix]
#!
#! Where:
#! - note_index is the index of the input note whose sender should be returned.
#! - sender_{suffix,prefix} are the suffix and prefix felts of the specified note.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_sender(note_index: u16) -> AccountId
    exec.get_metadata
    # => [METADATA]

    # extract the sender ID from the metadata
    exec.note::metadata_into_sender
    # => [sender_id_suffix, sender_id_prefix]
end

#! Returns the inputs commitment and length of the input note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [NOTE_STORAGE_COMMITMENT, num_storage_items]
#!
#! Where:
#! - note_index is the index of the input note whose data should be returned.
#! - NOTE_STORAGE_COMMITMENT is the inputs commitment of the specified input note.
#! - num_storage_items is the number of input values of the specified input note.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_storage_info(note_index: u16) -> (word, u16)
    # start padding the stack
    push.0 swap
    # => [note_index, 0]

    # push the flag indicating that we want to request inputs info from the note with the specified
    # index
    push.0
    # => [is_active_note = 0, note_index, 0]

    push.INPUT_NOTE_GET_STORAGE_INFO_OFFSET
    # => [offset, is_active_note = 0, note_index, 0]

    # pad the stack
    padw swapw padw padw swapdw
    # => [offset, is_active_note = 0, note_index, pad(13)]

    syscall.exec_kernel_proc
    # => [NOTE_STORAGE_COMMITMENT, num_storage_items, pad(11)]

    # clean the stack
    swapdw dropw dropw
    repeat.3
        movup.5 drop
    end
    # => [NOTE_STORAGE_COMMITMENT, num_storage_items]
end

#! Returns the script root of the input note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [SCRIPT_ROOT]
#!
#! Where:
#! - note_index is the index of the input note whose script root should be returned.
#! - SCRIPT_ROOT is the script root of the specified input note.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_script_root(note_index: u16) -> NoteScriptRoot
    # start padding the stack
    push.0 swap
    # => [note_index, 0]

    # push the flag indicating that we want to request script root from the note with the specified
    # index
    push.0
    # => [is_active_note = 0, note_index, 0]

    push.INPUT_NOTE_GET_SCRIPT_ROOT_OFFSET
    # => [offset, is_active_note = 0, note_index, 0]

    # pad the stack
    padw swapw padw padw swapdw
    # => [offset, is_active_note = 0, note_index, pad(13)]

    syscall.exec_kernel_proc
    # => [SCRIPT_ROOT, pad(12)]

    # clean the stack
    swapdw dropw dropw swapw dropw
    # => [SCRIPT_ROOT]
end

#! Returns the serial number of the input note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [SERIAL_NUMBER]
#!
#! Where:
#! - note_index is the index of the input note whose serial number should be returned.
#! - SERIAL_NUMBER is the serial number of the specified input note.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_serial_number(note_index: u16) -> word
    # start padding the stack
    push.0 swap
    # => [note_index, 0]

    # push the flag indicating that we want to request serial number from the note with the
    # specified index
    push.0
    # => [is_active_note = 0, note_index, 0]

    push.INPUT_NOTE_GET_SERIAL_NUMBER_OFFSET
    # => [offset, is_active_note = 0, note_index, 0]

    # pad the stack
    padw swapw padw padw swapdw
    # => [offset, is_active_note = 0, note_index, pad(13)]

    syscall.exec_kernel_proc
    # => [SERIAL_NUMBER, pad(12)]

    # clean the stack
    swapdw dropw dropw swapw dropw
    # => [SERIAL_NUMBER]
end

# ATTACHMENTS
# =================================================================================================

#! Returns the commitment over all attachments of the input note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [ATTACHMENTS_COMMITMENT]
#!
#! Where:
#! - note_index is the index of the input note whose attachments commitment should be returned.
#! - ATTACHMENTS_COMMITMENT is the commitment to all attachments of the note, or the EMPTY_WORD if
#!   the note does not have any attachments.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_attachments_commitment(note_index: u16) -> word
    push.0
    # => [is_active_note = 0, note_index]

    exec.get_attachments_commitment_raw
    # => [ATTACHMENTS_COMMITMENT]
end

#! Returns the commitment over all attachments of the input note with the specified index or the
#! active note, depending on the provided flag.
#!
#! This is the shared implementation used by both `input_note::get_attachments_commitment` and
#! `active_note::get_attachments_commitment`.
#!
#! Inputs:  [is_active_note, note_index]
#! Outputs: [ATTACHMENTS_COMMITMENT]
#!
#! Where:
#! - is_active_note is 0 for indexed access, 1 for the currently active note.
#! - note_index is the index of the input note.
#! - ATTACHMENTS_COMMITMENT is the commitment to all attachments of the note, or the EMPTY_WORD if
#!   the note does not have any attachments.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_attachments_commitment_raw(is_active_note: Bool, note_index: u16) -> word
    push.0 movdn.2
    # => [is_active_note, note_index, 0]

    push.INPUT_NOTE_GET_ATTACHMENTS_COMMITMENT_OFFSET
    # => [offset, is_active_note, note_index, 0]

    padw swapw padw padw swapdw
    # => [offset, is_active_note, note_index, pad(13)]

    syscall.exec_kernel_proc
    # => [ATTACHMENTS_COMMITMENT, pad(12)]

    # clean the stack, keeping only the commitment
    swapdw dropw dropw swapw dropw
    # => [ATTACHMENTS_COMMITMENT]
end

#! Writes the attachment commitments of the input note with the specified index to the provided
#! destination pointer.
#!
#! Inputs:  [dest_ptr, note_index]
#! Outputs: [num_attachments]
#!
#! Where:
#! - dest_ptr is the memory address to which to write the attachment commitments.
#! - note_index is the index of the input note.
#! - num_attachments is the number of attachments in the note.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#! - the sequential hash over the attachment commitments in the advice inputs does not match the
#!   attachments commitment.
#!
#! Invocation: exec
pub proc write_attachment_commitments_to_memory(dest_ptr: MemoryAddress, note_index: u16) -> u8
    swap exec.get_attachments_commitment
    # => [ATTACHMENTS_COMMITMENT, dest_ptr]

    exec.note::write_attachment_commitments_to_memory
    # => [num_attachments]
end

#! Writes the attachment with the provided index from the input note with the specified index
#! to the provided destination pointer.
#!
#! Inputs:  [dest_ptr, attachment_idx, note_index]
#! Outputs: [num_words]
#!
#! Where:
#! - dest_ptr is the memory address to which to write the attachment data.
#! - attachment_idx is the index of the attachment to retrieve.
#! - note_index is the index of the input note.
#! - num_words is the number of words in the attachment.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#! - the attachment index is greater or equal to the number of attachments.
#! - the sequential hash over the attachment data in the advice inputs does not match the
#!   attachment commitment.
#!
#! Invocation: exec
@locals(16)
pub proc write_attachment_to_memory(
    dest_ptr: MemoryAddress,
    attachment_idx: u8,
    note_index: u16
) -> u16
    # set up call to write the attachment commitments to local memory
    # we allocate 16 elements of memory (max num attachments * WORD_SIZE) to store all
    # four attachment commitments
    movdn.2 swap locaddr.0
    # => [attachment_commitments_ptr, note_index, attachment_idx, dest_ptr]

    exec.write_attachment_commitments_to_memory
    # => [num_attachments, attachment_idx, dest_ptr]

    locaddr.0 swap
    # => [num_attachments, attachment_commitments_ptr, attachment_idx, dest_ptr]

    exec.note::write_indexed_attachment_to_memory
    # => [num_words]
end

#! Searches the metadata of the input note with the specified index for the specified
#! attachment scheme and returns the index of the first matching slot.
#!
#! Inputs:  [attachment_scheme, note_index]
#! Outputs: [is_found, attachment_idx]
#!
#! Where:
#! - attachment_scheme is the scheme of the attachment to find.
#! - note_index is the index of the input note.
#! - is_found is 1 if the attachment with the provided scheme was found, 0 otherwise.
#! - attachment_idx is the index (0-3) of the first matching slot, or undefined if not found.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc find_attachment(attachment_scheme: u16, note_index: u16) -> (Bool, u8)
    swap exec.get_metadata
    # => [METADATA, attachment_scheme]

    movup.4
    # => [attachment_scheme, METADATA]

    exec.note::find_attachment_idx
    # => [is_found, attachment_idx]
end