miden-protocol 0.17.0-rc.5

use {
    AccountId,
    Asset,
    AssetValue,
    Bool,
    NoteAssetsCommitment,
    NoteAttachmentCommitment,
    NoteAttachmentsCommitment,
    NoteId,
    NoteMetadata,
    NoteRecipient,
    NoteScriptRoot,
    NoteSerialNumber,
    NoteStorageCommitment,
} from miden::protocol::types
use miden::core::word
use miden::protocol::input_note_internal
use miden::protocol::note
use miden::protocol::note_internal
use miden::protocol::tx

# EVENTS
# =================================================================================================

#! Requests that the transaction host resolve the specified input note ID through the advice
#! provider.
#! The host places [note_idx, is_found] on the advice stack. Because this response is
#! unauthenticated, callers must validate both reported matches and misses.
pub const INPUT_NOTE_INDEX_LOOKUP_EVENT = event("miden::protocol::input_note::index_lookup")

# ERRORS
# =================================================================================================

const ERR_INPUT_NOTE_INDEX_LOOKUP_INVALID = "input note index lookup result from the host is invalid"

# 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(dest_ptr: ptr<Asset>, note_index: u16) -> u8
    swap push.0
    # => [is_active_note = 0, note_index, dest_ptr]

    exec.input_note_internal::get_initial_assets_raw
    # => [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) -> (NoteAssetsCommitment, u8)
    push.0
    # => [is_active_note = 0, note_index]

    exec.input_note_internal::get_initial_assets_info_raw
    # => [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(note_index: u16) -> u8
    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(asset_index: u8, note_index: u16) -> Asset
    push.0
    # => [is_active_note = 0, asset_index, note_index]

    exec.input_note_internal::get_asset_raw
    # => [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 invocation does not originate from the native account's account context.
#! - the note index is greater or equal to the total number of input notes.
#! - the asset ID to remove is the empty word or is not a well-formed asset ID.
#! - 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(asset: Asset, note_index: u16) -> AssetValue
    push.0
    # => [is_active_note = 0, ASSET_ID, ASSET_VALUE, note_index]

    exec.input_note_internal::remove_asset_raw
    # => [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 invocation does not originate from the native account's account context.
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc remove_all_assets(dest_ptr: ptr<Asset>, note_index: u16) -> u8
    swap push.0
    # => [is_active_note = 0, note_index, dest_ptr]

    exec.input_note_internal::remove_all_assets_raw
    # => [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
    push.0
    # => [is_active_note = 0, note_index]

    exec.input_note_internal::get_recipient_raw
    # => [RECIPIENT]
end

#! Returns the ID of the input note with the specified index.
#!
#! Inputs:  [note_index]
#! Outputs: [NOTE_ID]
#!
#! Where:
#! - note_index is the index of the input note whose ID should be returned.
#! - NOTE_ID is the ID of the specified input note, cached by the transaction prologue.
#!
#! Panics if:
#! - the note index is greater or equal to the total number of input notes.
#!
#! Invocation: exec
pub proc get_note_id(note_index: u16) -> NoteId
    push.0
    # => [is_active_note = 0, note_index]

    exec.input_note_internal::get_note_id_raw
    # => [NOTE_ID]
end

#! Finds the input note with the specified ID among the transaction's input notes.
#!
#! The host first supplies an index and a presence flag. A reported match is validated in O(1) by
#! comparing the note ID cached by the prologue at the supplied index. If the host reports no
#! match, every input note is inspected to prove that the note is absent.
#!
#! Inputs:  [NOTE_ID]
#! Outputs: [is_found, note_idx]
#!
#! Where:
#! - NOTE_ID is the ID of the input note to look for.
#! - is_found is 1 if an input note with the specified ID exists, 0 otherwise.
#! - note_idx is the index of the matching input note; it is only meaningful if is_found is 1.
#!
#! Panics if:
#! - the host reports a matching index whose cached note ID differs from NOTE_ID.
#! - the host reports that NOTE_ID is absent when it is present among the input notes.
#!
#! Invocation: exec
pub proc find_note(note_id: NoteId) -> (Bool, u16)
    # Keep the target ID on the stack and emit a copy as the event payload.
    dupw emit.INPUT_NOTE_INDEX_LOOKUP_EVENT dropw
    # => [NOTE_ID]

    adv_push adv_push
    # => [is_found, note_idx, TARGET_NOTE_ID]

    if.true
        # Authenticate the claimed match against the note's ID.
        movdn.4 dup.4 exec.get_note_id
        # => [NOTE_ID, TARGET_NOTE_ID, note_idx]

        exec.word::eq assert.err=ERR_INPUT_NOTE_INDEX_LOOKUP_INVALID
        # => [note_idx]

        push.1
        # => [is_found = 1, note_idx]
    else
        # The host-reported index is meaningless when no match was reported.
        drop
        # => [TARGET_NOTE_ID]

        exec.tx::get_num_input_notes
        # => [num_notes, TARGET_NOTE_ID]

        dup neq.0
        # => [should_loop, num_notes, TARGET_NOTE_ID]

        while.true
            # The counter holds the number of notes not yet inspected; the note at counter - 1 is
            # inspected next, so after sub.1 the value doubles as that note's index.
            sub.1
            # => [note_idx, TARGET_NOTE_ID]

            movdn.4 dup.4 exec.get_note_id
            # => [NOTE_ID, TARGET_NOTE_ID, note_idx]

            exec.word::test_eq
            # => [is_match, NOTE_ID, TARGET_NOTE_ID, note_idx]

            not assert.err=ERR_INPUT_NOTE_INDEX_LOOKUP_INVALID
            dropw movup.4
            # => [note_idx, TARGET_NOTE_ID]

            dup neq.0
            # => [should_loop, note_idx]
        end
        # => [note_idx, TARGET_NOTE_ID]

        drop dropw push.0 push.0
        # => [is_found = 0, note_idx = 0]
    end
    # => [is_found, note_idx]
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
    push.0
    # => [is_active_note = 0, note_index]

    exec.input_note_internal::get_metadata_raw
    # => [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) -> (NoteStorageCommitment, u16)
    push.0
    # => [is_active_note = 0, note_index]

    exec.input_note_internal::get_storage_info_raw
    # => [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
    push.0
    # => [is_active_note = 0, note_index]

    exec.input_note_internal::get_script_root_raw
    # => [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) -> NoteSerialNumber
    push.0
    # => [is_active_note = 0, note_index]

    exec.input_note_internal::get_serial_number_raw
    # => [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) -> NoteAttachmentsCommitment
    push.0
    # => [is_active_note = 0, note_index]

    exec.input_note_internal::get_attachments_commitment_raw
    # => [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: ptr<NoteAttachmentCommitment>,
    note_index: u16
) -> u8
    swap exec.get_attachments_commitment
    # => [ATTACHMENTS_COMMITMENT, dest_ptr]

    exec.note_internal::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: ptr<word>,
    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_internal::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