miden-protocol 0.15.2

use miden::protocol::kernel_proc_offsets::OUTPUT_NOTE_CREATE_OFFSET
use miden::protocol::kernel_proc_offsets::OUTPUT_NOTE_GET_ASSETS_INFO_OFFSET
use miden::protocol::kernel_proc_offsets::OUTPUT_NOTE_ADD_ASSET_OFFSET
use miden::protocol::kernel_proc_offsets::OUTPUT_NOTE_ADD_ATTACHMENT_OFFSET
use miden::protocol::kernel_proc_offsets::OUTPUT_NOTE_GET_RECIPIENT_OFFSET
use miden::protocol::kernel_proc_offsets::OUTPUT_NOTE_GET_METADATA_OFFSET
use miden::protocol::kernel_proc_offsets::OUTPUT_NOTE_GET_ATTACHMENTS_COMMITMENT_OFFSET
use miden::protocol::util::constants::WORD_NUM_ELEMENTS
use miden::protocol::note
use miden::core::crypto::hashes::poseidon2

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

#! Creates a new note and returns the index of the note.
#!
#! Inputs:  [tag, note_type, RECIPIENT]
#! Outputs: [note_idx]
#!
#! Where:
#! - tag is the tag to be included in the note.
#! - note_type is the storage type of the note.
#! - RECIPIENT is the recipient of the note.
#! - note_idx is the index of the created note.
#!
#! Panics if:
#! - the note_type is unknown.
#! - the note tag is not a u32.
#! - the number of output notes exceeds the maximum limit of 1024.
#!
#! Invocation: exec
pub proc create
    # pad the stack before the syscall to prevent accidental modification of the deeper stack
    # elements
    push.0 movdn.6 push.0
    # => [0, tag, note_type, RECIPIENT, 0]

    padw padw swapdw drop
    # => [tag, note_type, RECIPIENT, pad(9)]

    push.OUTPUT_NOTE_CREATE_OFFSET
    # => [offset, tag, note_type, RECIPIENT, pad(9)]

    syscall.exec_kernel_proc
    # => [note_idx, pad(15)]

    # remove excess PADs from the stack
    swapdw dropw dropw movdn.7 dropw drop drop drop
    # => [note_idx]
end

#! Returns the information about assets in the output 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 output 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 output notes.
#!
#! Invocation: exec
pub proc get_assets_info
    # start padding the stack
    push.0.0 movup.2
    # => [note_index, 0, 0]

    push.OUTPUT_NOTE_GET_ASSETS_INFO_OFFSET
    # => [offset, note_index, 0, 0]

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

    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 output 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 output 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 output 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 commitment over all attachments of the output note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [ATTACHMENTS_COMMITMENT]
#!
#! Where:
#! - note_index is the index of the output 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 output notes.
#!
#! Invocation: exec
pub proc get_attachments_commitment
    # start padding the stack
    push.0.0 movup.2
    # => [note_index, 0, 0]

    push.OUTPUT_NOTE_GET_ATTACHMENTS_COMMITMENT_OFFSET
    # => [offset, note_index, 0, 0]

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

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

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

#! Adds the asset to the note specified by the index.
#!
#! Inputs:  [ASSET_KEY, ASSET_VALUE, note_idx]
#! Outputs: []
#!
#! Where:
#! - note_idx is the index of the note to which the asset is added.
#! - ASSET_KEY is the vault key of the asset to add.
#! - ASSET_VALUE is the value of the asset to add.
#!
#! Invocation: exec
pub proc add_asset
    push.OUTPUT_NOTE_ADD_ASSET_OFFSET
    # => [offset, ASSET_KEY, ASSET_VALUE, note_idx]

    # pad the stack
    repeat.6 push.0 movdn.10 end
    # => [offset, ASSET_KEY, ASSET_VALUE, note_idx, pad(6)]

    syscall.exec_kernel_proc
    # => [pad(16)]

    # remove excess PADs from the stack
    dropw dropw dropw dropw
    # => []
end

#! Adds an attachment to the note specified by the note index.
#!
#! There must be an advice map entry for ATTACHMENT_COMMITMENT that maps to the raw attachment
#! elements.
#!
#! Inputs:
#!   Operand Stack: [attachment_scheme, ATTACHMENT_COMMITMENT, note_idx]
#!   Advice map: {
#!     ATTACHMENT_COMMITMENT: [[ATTACHMENT_ELEMENTS]],
#!   }
#! Outputs: []
#!
#! Where:
#! - attachment_scheme is the user-defined scheme of the attachment.
#! - ATTACHMENT_COMMITMENT is the hash commitment to the attachment elements.
#! - note_idx is the index of the note to which the attachment is added.
#! - ATTACHMENT_ELEMENTS are the elements for which ATTACHMENT_COMMITMENT is the sequential
#!   commitment.
#!
#! 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.
#! - the attachment scheme is 0 or exceeds 65534.
#! - the note already has 4 attachments.
#! - the number of words in the attachment exceeds 256.
#! - the total number of attachment words in the note exceeds 512.
#!
#! Invocation: exec
pub proc add_attachment
    push.OUTPUT_NOTE_ADD_ATTACHMENT_OFFSET
    # => [offset, attachment_scheme, ATTACHMENT_COMMITMENT, note_idx]

    # pad the stack before the syscall
    push.0 movdn.7 padw padw swapdw
    # => [offset, attachment_scheme, ATTACHMENT_COMMITMENT, note_idx, pad(9)]

    syscall.exec_kernel_proc
    # => [pad(16)]

    # remove excess PADs from the stack
    dropw dropw dropw dropw
    # => []
end

#! Adds a single-word attachment to the note specified by the note index.
#!
#! Hashes the raw attachment word to produce the commitment, inserts the raw elements into the
#! advice map keyed by that commitment, then delegates to `add_attachment`.
#!
#! Inputs:  [attachment_scheme, ATTACHMENT, note_idx]
#! Outputs: []
#!
#! Where:
#! - attachment_scheme is the user-defined scheme of the attachment.
#! - ATTACHMENT is the raw attachment word.
#! - note_idx is the index of the note to which the attachment is added.
#!
#! 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.
#! - the attachment scheme is 0 or exceeds 65534.
#! - the note already has 4 attachments.
#! - the total number of attachment words in the note exceeds 512.
#!
#! Invocation: exec
@locals(4)
pub proc add_word_attachment
    # => [attachment_scheme, ATTACHMENT, note_idx]

    # Store ATTACHMENT to local memory for hashing and advice map insertion
    movdn.4
    # => [ATTACHMENT, attachment_scheme, note_idx]

    loc_storew_le.0
    # => [ATTACHMENT, attachment_scheme, note_idx]

    exec.poseidon2::hash
    # => [ATTACHMENT_COMMITMENT, attachment_scheme, note_idx]

    locaddr.0 dup add.4
    # => [end_ptr, start_ptr, ATTACHMENT_COMMITMENT, attachment_scheme, note_idx]

    movdn.5 movdn.4
    # => [ATTACHMENT_COMMITMENT, start_ptr, end_ptr, attachment_scheme, note_idx]

    # Insert the raw attachment elements into the advice map keyed by the commitment.
    adv.insert_mem
    # => [ATTACHMENT_COMMITMENT, start_ptr, end_ptr, attachment_scheme, note_idx]

    # Clean up and arrange stack for add_attachment
    movup.4 drop movup.4 drop
    # => [ATTACHMENT_COMMITMENT, attachment_scheme, note_idx]

    movup.4
    # => [attachment_scheme, ATTACHMENT_COMMITMENT, note_idx]

    exec.add_attachment
    # => []
end

#! Adds a multi-word attachment to the note specified by the note index.
#!
#! Hashes the raw attachment words starting at attachment_ptr to produce the commitment, inserts the raw
#! elements into the advice map keyed by that commitment, then delegates to `add_attachment`.
#!
#! To add a single word as an attachment, prefer add_word_attachment.
#!
#! Inputs:  [attachment_scheme, num_words, attachment_ptr, note_idx]
#! Outputs: []
#!
#! Where:
#! - attachment_scheme is the user-defined scheme of the attachment.
#! - attachment_ptr is the pointer to the first word of the raw attachment data in memory.
#! - num_words is the number of words of the attachment data.
#! - note_idx is the index of the note to which the attachment is added.
#!
#! 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.
#! - the attachment scheme is 0 or exceeds 65534.
#! - the note already has 4 attachments.
#! - the number of words in the attachment exceeds 256.
#! - the total number of attachment words in the note exceeds 512.
#!
#! Invocation: exec
pub proc add_attachment_from_memory
    # Compute num_elements = num_words * WORD_NUM_ELEMENTS
    movdn.3 mul.WORD_NUM_ELEMENTS
    # => [num_elements, attachment_ptr, note_idx, attachment_scheme]

    # Compute end_ptr = attachment_ptr + num_elements
    dup.1 dup.1 add
    # => [end_ptr, num_elements, attachment_ptr, note_idx, attachment_scheme]

    movdn.2 dup.1
    # => [attachment_ptr, num_elements, attachment_ptr, end_ptr, note_idx, attachment_scheme]

    exec.poseidon2::hash_elements
    # => [ATTACHMENT_COMMITMENT, attachment_ptr, end_ptr, note_idx, attachment_scheme]

    # Insert the raw attachment elements into the advice map keyed by the commitment
    adv.insert_mem
    # => [ATTACHMENT_COMMITMENT, attachment_ptr, end_ptr, note_idx, attachment_scheme]

    # Clean up attachment_ptr and end_ptr
    movup.4 drop movup.4 drop
    # => [ATTACHMENT_COMMITMENT, note_idx, attachment_scheme]

    movup.5
    # => [attachment_scheme, ATTACHMENT_COMMITMENT, note_idx]

    exec.add_attachment
    # => []
end

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

    push.OUTPUT_NOTE_GET_RECIPIENT_OFFSET
    # => [offset, note_index, 0, 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 output note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [METADATA]
#!
#! Where:
#! - note_index is the index of the output note whose metadata should be returned.
#! - METADATA is the metadata of the specified output note.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of output notes.
#!
#! Invocation: exec
pub proc get_metadata
    # start padding the stack
    push.0.0 movup.2
    # => [note_index, 0, 0]

    push.OUTPUT_NOTE_GET_METADATA_OFFSET
    # => [offset, note_index, 0, 0]

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

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

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

#! Searches the metadata of the output 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 output 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 output 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

#! Writes the attachment commitments of the output 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 output 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 output 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 output 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 output 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 output 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