Miden Protocol Library
The Miden protocol library provides a set of procedures that wrap transaction kernel procedures to provide a more convenient interface for common operations. These can be invoked by account code, note scripts, and transaction scripts, though some have restriction from where they can be called. The procedures are organized into modules corresponding to different functional areas.
Contexts
Here and in other places we use the notion of active account: it is the account which is currently being accessed.
The Miden VM contexts from which procedures can be called are:
- Account: Can only be called from native or foreign accounts.
- Native: Can only be called when the active account is the native account.
- Auth: Can only be called from the authentication procedure. Since it is called on the native account, it implies Native and Account.
- Faucet: Can only be called when the active account is a faucet.
- Note: Can only be called from a note script.
- Any: Can be called from any context.
If a procedure has multiple context requirements they are combined using &. For instance, "Native & Account" means the procedure can only be called when the active account is the native one and only from the account context.
Implementation
Most procedures in the Miden protocol library are implemented as wrappers around underlying kernel procedures. They handle the necessary stack padding and cleanup operations required by the kernel interface, providing a more convenient API for developers.
The procedures maintain the same security and context restrictions as the underlying kernel procedures. When invoking these procedures, ensure that the calling context matches the requirements.
Account ID Procedures (miden::protocol::account_id)
Account ID procedures can be used to validate and compare account IDs.
| Procedure | Description | Context |
|---|---|---|
is_equal | Returns whether two account IDs are equal. Inputs: [account_id_suffix, account_id_prefix, other_account_id_suffix, other_account_id_prefix]Outputs: [is_id_equal] | Any |
validate | Validates the provided account ID. Inputs: [account_id_suffix, account_id_prefix]Outputs: [] | Any |
shape_suffix | Shapes a digest suffix into an account ID suffix by clearing the lower 8 bits. Inputs: [seed_digest_suffix]Outputs: [account_id_suffix] | Any |
Active account Procedures (miden::protocol::active_account)
Active account procedures can be used to read from storage, fetch or compute commitments or obtain other internal data of the active account.
| Procedure | Description | Context |
|---|---|---|
get_id | Returns the ID of the active account. Inputs: []Outputs: [account_id_suffix, account_id_prefix] | Any |
get_nonce | Returns the nonce of the active account. Always returns the initial nonce as it can only be incremented in auth procedures. Inputs: []Outputs: [nonce] | Account |
compute_commitment | Computes and returns the account commitment from account data stored in memory. Inputs: []Outputs: [ACCOUNT_COMMITMENT] | Account |
get_code_commitment | Gets the account code commitment of the active account. Inputs: []Outputs: [CODE_COMMITMENT] | Account |
compute_storage_commitment | Computes the latest account storage commitment of the active account. Inputs: []Outputs: [STORAGE_COMMITMENT] | Account |
get_item | Gets an item from the account storage. Inputs: [slot_id_suffix, slot_id_prefix]Outputs: [VALUE] | Account |
get_map_item | Returns the VALUE located under the specified KEY within the map contained in the given account storage slot. Inputs: [slot_id_suffix, slot_id_prefix, KEY]Outputs: [VALUE] | Account |
get_asset | Returns the asset associated with the provided asset ID in the active account's vault. Inputs: [ASSET_ID]Outputs: [ASSET_VALUE] | Account |
has_asset | Returns a boolean indicating whether the asset with the provided asset ID is present in the active account's vault. Inputs: [ASSET_ID]Outputs: [has_asset] | Account |
get_vault_root | Returns the vault root of the active account. Inputs: []Outputs: [VAULT_ROOT] | Account |
get_num_procedures | Returns the number of procedures in the active account. Inputs: []Outputs: [num_procedures] | Account |
get_procedure_root | Returns the procedure root for the procedure at the specified index. Inputs: [index]Outputs: [PROC_ROOT] | Account |
has_procedure | Returns the binary flag indicating whether the procedure with the provided root is available on the active account. Inputs: [PROC_ROOT]Outputs: [is_procedure_available] | Account |
Native account Procedures (miden::protocol::native_account)
Native account procedures can be used to write to storage, add or remove assets from the vault and compute delta commitment of the native account. They also expose the initial (beginning-of-transaction) state of the native account.
Notice that the initial-state getters can only be executed against the native account: invoking them against the foreign account (during FPI) panics. Foreign accounts are immutable, so in order to read their (initial) values, the corresponding getters from the active_account module should be used.
| Procedure | Description | Context |
|---|---|---|
get_id | Returns the ID of the native account of the transaction. Inputs: []Outputs: [account_id_suffix, account_id_prefix] | Any |
incr_nonce | Increments the nonce of the native account by one and returns the new nonce. Can only be called from auth procedures. Inputs: []Outputs: [final_nonce] | Auth |
compute_delta_commitment | Computes the commitment to the native account's delta. Can only be called from auth procedures. Inputs: []Outputs: [DELTA_COMMITMENT] | Auth |
set_item | Sets an item in the native account storage. Inputs: [slot_id_suffix, slot_id_prefix, VALUE]Outputs: [OLD_VALUE] | Native & Account |
set_map_item | Sets VALUE under the specified KEY within the map contained in the given native account storage slot. Inputs: [slot_id_suffix, slot_id_prefix, KEY, VALUE]Outputs: [OLD_VALUE] | Native & Account |
add_asset | Adds the specified asset to the vault. For fungible assets, returns the total after addition. Inputs: [ASSET_ID, ASSET_VALUE]Outputs: [ASSET_VALUE'] | Native & Account |
remove_asset | Removes the specified asset from the vault and returns the remaining asset value. Inputs: [ASSET_ID, ASSET_VALUE]Outputs: [REMAINING_ASSET_VALUE] | Native & Account |
upgrade | Records the commitments describing an upgrade of the native account's code and storage. Currently a no-op beyond storing the commitments; the commitment formats are not yet defined. Inputs: [CODE_UPGRADE_COMMITMENT, STORAGE_UPGRADE_COMMITMENT]Outputs: [] | Native & Account |
get_initial_commitment | Returns the native account commitment at the beginning of the transaction. Inputs: []Outputs: [INIT_COMMITMENT] | Native & Account |
get_initial_storage_commitment | Returns the storage commitment of the native account at the beginning of the transaction. Inputs: []Outputs: [INIT_STORAGE_COMMITMENT] | Native & Account |
get_initial_item | Gets the initial item from the native account storage slot as it was at the beginning of the transaction. Inputs: [slot_id_suffix, slot_id_prefix]Outputs: [VALUE] | Native & Account |
get_initial_map_item | Gets the initial VALUE from the native account storage map as it was at the beginning of the transaction. Inputs: [slot_id_suffix, slot_id_prefix, KEY]Outputs: [VALUE] | Native & Account |
get_initial_asset | Returns the asset associated with the provided asset ID in the native account's vault at the beginning of the transaction. Inputs: [ASSET_ID]Outputs: [ASSET_VALUE] | Native & Account |
has_initial_asset | Returns a boolean indicating whether the native account's vault contained an asset with the provided asset ID at the beginning of the transaction. Inputs: [ASSET_ID]Outputs: [has_asset] | Native & Account |
get_initial_vault_root | Returns the vault root of the native account at the beginning of the transaction. Inputs: []Outputs: [INIT_VAULT_ROOT] | Native & Account |
was_procedure_called | Returns 1 if a native account procedure was called during transaction execution, and 0 otherwise. Inputs: [PROC_ROOT]Outputs: [was_called] | Native & Account |
Active Note Procedures (miden::protocol::active_note)
Active note procedures can be used to fetch data from the note that is currently being processed by the transaction kernel.
| Procedure | Description | Context |
|---|---|---|
get_initial_assets | Writes the initial assets of the active note, i.e. the assets the note was created with, into memory starting at the specified address. Unaffected by asset removal. Inputs: [dest_ptr]Outputs: [num_assets] | Note |
get_initial_assets_info | Returns the initial assets information of the active note, i.e. the assets the note was created with. Unaffected by asset removal. Inputs: []Outputs: [ASSETS_COMMITMENT, num_assets] | Note |
get_initial_num_assets | Returns the number of assets the active note was created with. Unaffected by asset removal. Inputs: []Outputs: [num_assets] | Note |
get_asset | Returns the asset at the specified index in the active note as it currently is; a removed asset is returned as two empty words. Inputs: [asset_index]Outputs: [ASSET_ID, ASSET_VALUE] | Note |
remove_asset | Removes an asset from the active note and returns the value remaining in the note, which is the empty word if the entire asset was removed. Inputs: [ASSET_ID, ASSET_VALUE]Outputs: [FINAL_ASSET_VALUE] | Note |
remove_all_assets | Removes all remaining assets from the active note and writes them into memory starting at the specified address. Inputs: [dest_ptr]Outputs: [num_assets] | Note |
get_recipient | Returns the recipient of the active note. Inputs: []Outputs: [RECIPIENT] | Note |
get_storage | Writes the note's inputs to the specified memory address. Inputs: [dest_ptr]Outputs: [num_storage_items, dest_ptr] | Note |
get_metadata | Returns the metadata of the active note. Inputs: []Outputs: [METADATA] | Note |
get_sender | Returns the sender of the active note. Inputs: []Outputs: [sender_id_suffix, sender_id_prefix] | Note |
get_serial_number | Returns the serial number of the active note. Inputs: []Outputs: [SERIAL_NUMBER] | Note |
get_script_root | Returns the script root of the active note. Inputs: []Outputs: [SCRIPT_ROOT] | Note |
get_attachments_commitment | Returns the commitment over all attachments of the active note. Inputs: []Outputs: [ATTACHMENTS_COMMITMENT] | Note |
write_attachment_commitments_to_memory | Writes the attachment commitments of the active note to the specified memory address. Inputs: [dest_ptr]Outputs: [num_attachments] | Note |
write_attachment_to_memory | Writes the attachment with the provided index from the active note to the specified memory address. Inputs: [dest_ptr, attachment_idx]Outputs: [num_words] | Note |
find_attachment | Searches the metadata of the active note for the specified attachment scheme and returns the index of the first matching slot. Inputs: [attachment_scheme]Outputs: [is_found, attachment_idx] | Note |
Input Note Procedures (miden::protocol::input_note)
Input note procedures can be used to fetch data on input notes consumed by the transaction.
| Procedure | Description | Context |
|---|---|---|
get_initial_assets | Writes the initial assets of the input note with the specified index, i.e. the assets the note was created with, into memory starting at the specified address. Unaffected by asset removal. Inputs: [dest_ptr, note_index]Outputs: [num_assets] | Any |
get_initial_assets_info | Returns the initial assets information of the input note with the specified index, i.e. the assets the note was created with. Unaffected by asset removal. Inputs: [note_index]Outputs: [ASSETS_COMMITMENT, num_assets] | Any |
get_initial_num_assets | Returns the number of assets the input note with the specified index was created with. Unaffected by asset removal. Inputs: [note_index]Outputs: [num_assets] | Any |
get_asset | Returns the asset at the specified index in the input note with the specified index as it currently is; a removed asset is returned as two empty words. Inputs: [asset_index, note_index]Outputs: [ASSET_ID, ASSET_VALUE] | Any |
remove_asset | Removes an asset from the input note with the specified index and returns the value remaining in the note, which is the empty word if the entire asset was removed. Inputs: [ASSET_ID, ASSET_VALUE, note_index]Outputs: [FINAL_ASSET_VALUE] | Any |
remove_all_assets | Removes all remaining assets from the input note with the specified index and writes them into memory starting at the specified address. Inputs: [dest_ptr, note_index]Outputs: [num_assets] | Any |
get_recipient | Returns the recipient of the input note with the specified index. Inputs: [note_index]Outputs: [RECIPIENT] | Any |
get_metadata | Returns the metadata of the input note with the specified index. Inputs: [note_index]Outputs: [METADATA] | Any |
get_sender | Returns the sender of the input note with the specified index. Inputs: [note_index]Outputs: [sender_id_suffix, sender_id_prefix] | Any |
get_storage_info | Returns the inputs commitment and length of the input note with the specified index. Inputs: [note_index]Outputs: [NOTE_STORAGE_COMMITMENT, num_storage_items] | Any |
get_script_root | Returns the script root of the input note with the specified index. Inputs: [note_index]Outputs: [SCRIPT_ROOT] | Any |
get_serial_number | Returns the serial number of the input note with the specified index. Inputs: [note_index]Outputs: [SERIAL_NUMBER] | Any |
get_attachments_commitment | Returns the commitment over all attachments of the input note with the specified index. Inputs: [note_index]Outputs: [ATTACHMENTS_COMMITMENT] | Any |
write_attachment_commitments_to_memory | Writes the attachment commitments of the input note with the specified index to the specified memory address. Inputs: [dest_ptr, note_index]Outputs: [num_attachments] | Any |
write_attachment_to_memory | Writes the attachment with the provided index from the input note with the specified index to the specified memory address. Inputs: [dest_ptr, attachment_idx, note_index]Outputs: [num_words] | Any |
find_attachment | Searches the metadata of the input note for the specified attachment scheme and returns the index of the first matching slot. Inputs: [attachment_scheme, note_index]Outputs: [is_found, attachment_idx] | Any |
Output Note Procedures (miden::protocol::output_note)
Output note procedures can be used to fetch data on output notes created by the transaction.
| Procedure | Description | Context |
|---|---|---|
create | Creates a new output note and returns its index. Inputs: [tag, note_type, RECIPIENT]Outputs: [note_idx] | Native & Account |
get_assets_info | Returns the information about assets in the output note with the specified index. Inputs: [note_index]Outputs: [ASSETS_COMMITMENT, num_assets] | Any |
get_assets | Writes the assets of the output note with the specified index into memory starting at the specified address. Inputs: [dest_ptr, note_index]Outputs: [num_assets, dest_ptr, note_index] | Any |
add_asset | Adds the asset to the output note specified by the index. Inputs: [ASSET_ID, ASSET_VALUE, note_idx]Outputs: [] | Native |
add_attachment | Adds an attachment to the note specified by the 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: [] | Native |
add_word_attachment | 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, then delegates to add_attachment.Inputs: [attachment_scheme, ATTACHMENT, note_idx]Outputs: [] | Native |
add_attachment_from_memory | Adds a multi-word attachment to the note specified by the note index. Hashes the raw attachment words to produce the commitment, inserts the raw elements into the advice map, then delegates to add_attachment.Inputs: [attachment_scheme, num_words, attachment_ptr, note_idx]Outputs: [] | Native |
get_attachments_commitment | Returns the commitment over all attachments of the output note with the specified index. Inputs: [note_index]Outputs: [ATTACHMENTS_COMMITMENT] | Any |
write_attachment_commitments_to_memory | Writes the attachment commitments of the output note with the specified index to the specified memory address. Inputs: [dest_ptr, note_index]Outputs: [num_attachments] | Any |
write_attachment_to_memory | Writes the attachment with the provided index from the output note with the specified index to the specified memory address. Inputs: [dest_ptr, attachment_idx, note_index]Outputs: [num_words] | Any |
find_attachment | Searches the metadata of the output note for the specified attachment scheme and returns the index of the first matching slot. Inputs: [attachment_scheme, note_index]Outputs: [is_found, attachment_idx] | Any |
get_recipient | Returns the recipient of the output note with the specified index. Inputs: [note_index]Outputs: [RECIPIENT] | Any |
get_metadata | Returns the metadata of the output note with the specified index. Inputs: [note_index]Outputs: [METADATA] | Any |
Note Utility Procedures (miden::protocol::note)
Note utility procedures can be used to compute the required utility data or write note data to memory.
| Procedure | Description | Context |
|---|---|---|
compute_storage_commitment | Computes the commitment to the output note storage starting at the specified memory address. Inputs: [storage_ptr, num_storage_items]Outputs: [STORAGE_COMMITMENT] | Any |
write_assets_to_memory | Writes the assets data stored in the advice map to the memory specified by the provided destination pointer. Inputs: [ASSETS_COMMITMENT, num_assets, dest_ptr]Outputs: [num_assets, dest_ptr] | Any |
write_attachments_to_memory | Writes the attachment commitments stored in the advice map to the memory specified by the provided destination pointer. Inputs: Operand Stack: [ATTACHMENTS_COMMITMENT, dest_ptr]Advice map: { ATTACHMENTS_COMMITMENT: [[ATTACHMENT_COMMITMENT]] }Outputs: [num_attachments] | Any |
write_attachment_to_memory | Writes a single attachment's data stored in the advice map to the memory specified by the provided destination pointer. Inputs: Operand Stack: [ATTACHMENT_COMMITMENT, dest_ptr]Advice map: { ATTACHMENT_COMMITMENT: [[ATTACHMENT_ELEMENTS]] }Outputs: [num_words] | Any |
write_indexed_attachment_to_memory | Writes the attachment with the provided index from the provided attachment commitments to the specified memory address. Inputs: [num_attachments, attachment_commitments_ptr, attachment_idx, dest_ptr]Outputs: [num_words] | Any |
find_attachment_idx | Searches the metadata for the specified attachment scheme and returns the index of the first matching slot. Inputs: [attachment_scheme, METADATA]Outputs: [is_found, attachment_idx] | Any |
compute_recipient | Returns the RECIPIENT for a specified SERIAL_NUM, SCRIPT_ROOT, and storage commitment.Inputs: [SERIAL_NUM, SCRIPT_ROOT, STORAGE_COMMITMENT]Outputs: [RECIPIENT] | Any |
compute_and_store_recipient | Computes the recipient from note storage, script root, and serial number, and stores the recipient preimages in advice inputs. Inputs: [storage_ptr, num_storage_items, SERIAL_NUM, SCRIPT_ROOT]Outputs: [RECIPIENT] | Any |
metadata_into_sender | Extracts the sender ID from the provided metadata word. Inputs: [METADATA]Outputs: [sender_id_suffix, sender_id_prefix] | Any |
metadata_into_attachment_schemes | Extracts the attachment schemes from the provided metadata. Inputs: [METADATA]Outputs: [attachment_0_scheme, attachment_1_scheme, attachment_2_scheme, attachment_3_scheme] | Any |
metadata_into_note_type | Extracts the note type from the provided metadata. The note type is encoded as a single bit (0 = Private, 1 = Public). Inputs: [METADATA]Outputs: [note_type] | Any |
Transaction Procedures (miden::protocol::tx)
Transaction procedures manage transaction-level operations including note creation, context switching, and reading transaction metadata.
| Procedure | Description | Context |
|---|---|---|
get_block_number | Returns the block number of the transaction reference block. Inputs: []Outputs: [num] | Any |
get_block_commitment | Returns the block commitment of the reference block. Inputs: []Outputs: [BLOCK_COMMITMENT] | Any |
get_block_timestamp | Returns the timestamp of the reference block for this transaction. Inputs: []Outputs: [timestamp] | Any |
get_input_notes_commitment | Returns the input notes commitment hash. Inputs: []Outputs: [INPUT_NOTES_COMMITMENT] | Any |
get_output_notes_commitment | Returns the output notes commitment hash. Inputs: []Outputs: [OUTPUT_NOTES_COMMITMENT] | Any |
get_num_input_notes | Returns the total number of input notes consumed by this transaction. Inputs: []Outputs: [num_input_notes] | Any |
get_num_output_notes | Returns the current number of output notes created in this transaction. Inputs: []Outputs: [num_output_notes] | Any |
execute_foreign_procedure | Executes the provided procedure against the foreign account. Inputs: [foreign_account_id_suffix, foreign_account_id_prefix, FOREIGN_PROC_ROOT, <inputs>, pad(n)]Outputs: [<outputs>] | Any |
get_expiration_block_delta | Returns the transaction expiration delta, or 0 if not set. Inputs: []Outputs: [block_height_delta] | Any |
update_expiration_block_delta | Updates the transaction expiration delta. Inputs: [block_height_delta]Outputs: [] | Any |
compute_fee | Computes the fee required for the current transaction. Inputs: [num_extra_cycles, EXCLUDE_NOTES_COMMITMENT]Outputs: [fee_amount] | Any |
Note on execute_foreign_procedure: the values it reads reflect the foreign account's state at the transaction reference block, which is chosen by the executor. The foreign account commitment is not a transaction public input and is not revalidated against the foreign account's current on-chain state at inclusion, so a foreign read may be outdated. If a foreign account holds time-sensitive data, it is the responsibility of that account to set the transaction expiration delta according to how time-sensitive the data is, so that the FPI interface cannot be used in unintended ways.
Faucet Procedures (miden::protocol::faucet)
Faucet procedures allow reading and writing to faucet accounts to mint and burn assets.
| Procedure | Description | Context |
|---|---|---|
mint | Mint an asset from the faucet the transaction is being executed against. Inputs: [ASSET_ID, ASSET_VALUE]Outputs: [] | Native & Account & Faucet |
burn | Burn an asset from the faucet the transaction is being executed against. Inputs: [ASSET_ID, ASSET_VALUE]Outputs: [] | Native & Account & Faucet |
Asset Procedures (miden::protocol::asset)
Asset procedures provide utilities for creating fungible and non-fungible assets.
| Procedure | Description | Context |
|---|---|---|
create_fungible_asset | Builds a fungible asset for the specified fungible faucet and amount. Inputs: [faucet_id_suffix, faucet_id_prefix, amount]Outputs: [ASSET_ID, ASSET_VALUE] | Any |