miden-protocol 0.15.2

use miden::protocol::kernel_proc_offsets::INPUT_NOTE_GET_ASSETS_INFO_OFFSET
use miden::protocol::kernel_proc_offsets::INPUT_NOTE_GET_RECIPIENT_OFFSET
use miden::protocol::kernel_proc_offsets::INPUT_NOTE_GET_METADATA_OFFSET
use miden::protocol::kernel_proc_offsets::INPUT_NOTE_GET_STORAGE_INFO_OFFSET
use miden::protocol::kernel_proc_offsets::INPUT_NOTE_GET_SCRIPT_ROOT_OFFSET
use miden::protocol::kernel_proc_offsets::INPUT_NOTE_GET_SERIAL_NUMBER_OFFSET
use miden::protocol::kernel_proc_offsets::INPUT_NOTE_GET_ATTACHMENTS_COMMITMENT_OFFSET
use miden::protocol::note

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

#! Returns the information about assets in the input note with the specified index.
#!
#! This information can then be used to retrieve the actual assets from the advice map.
#!
#! 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 in the specified note.
#! - ASSETS_COMMITMENT is a sequential hash of the assets in the specified note.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_assets_info
    # 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_ASSETS_INFO_OFFSET
    # => [offset, is_active_note = 0, note_index, 0]

    # pad the stack
    padw swapw padw padw swapdw
    # => [offset, 0, 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

#! Writes the assets of the input note with the specified index into memory starting at the
#! specified address.
#!
#! 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 `4 * num_assets` memory elements are available,
#! or if the number of assets is not yet known, at least `4 * 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 one word. 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 assets info should be returned.
#! - num_assets is the number of assets in the specified note.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_assets
    # get the assets commitment and assets number
    swap exec.get_assets_info
    # => [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 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
    # 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
    # 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
    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
    # 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
    # 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
    # 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
    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 (ignored when is_active_note = 1).
#! - 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
    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
    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
    # 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
    swap exec.get_metadata
    # => [METADATA, attachment_scheme]

    movup.4
    # => [attachment_scheme, METADATA]

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