Version: 0.15 (unstable)

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 account IDs and inspect their account type.

Procedure	Description	Context
`is_fungible_faucet`	Returns whether the account ID prefix belongs to a fungible faucet account. Inputs: `[account_id_prefix]` Outputs: `[is_fungible_faucet]`	Any
`is_non_fungible_faucet`	Returns whether the account ID prefix belongs to a non-fungible faucet account. Inputs: `[account_id_prefix]` Outputs: `[is_non_fungible_faucet]`	Any
`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
`is_faucet`	Returns whether the account ID prefix belongs to a faucet account. Inputs: `[account_id_prefix]` Outputs: `[is_faucet]`	Any
`is_updatable_account`	Returns whether the account ID prefix belongs to a regular account with updatable code. Inputs: `[account_id_prefix]` Outputs: `[is_updatable_account]`	Any
`is_immutable_account`	Returns whether the account ID prefix belongs to a regular account with immutable code. Inputs: `[account_id_prefix]` Outputs: `[is_immutable_account]`	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]`	Any
`get_initial_commitment`	Returns the active account commitment at the beginning of the transaction. Inputs: `[]` Outputs: `[INIT_COMMITMENT]`	Any
`compute_commitment`	Computes and returns the account commitment from account data stored in memory. Inputs: `[]` Outputs: `[ACCOUNT_COMMITMENT]`	Any
`get_code_commitment`	Gets the account code commitment of the active account. Inputs: `[]` Outputs: `[CODE_COMMITMENT]`	Account
`get_initial_storage_commitment`	Returns the storage commitment of the active account at the beginning of the transaction. Inputs: `[]` Outputs: `[INIT_STORAGE_COMMITMENT]`	Any
`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_initial_item`	Gets the initial item from the account storage slot as it was at the beginning of the transaction. 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_initial_map_item`	Gets the initial VALUE from the account storage map as it was at the beginning of the transaction. Inputs: `[slot_id_suffix, slot_id_prefix, KEY]` Outputs: `[VALUE]`	Account
`get_asset`	Returns the asset associated with the provided asset vault key in the active account's vault. Inputs: `[ASSET_KEY]` Outputs: `[ASSET_VALUE]`	Any
`get_initial_asset`	Returns the asset associated with the provided asset vault key in the active account's vault at the beginning of the transaction. Inputs: `[ASSET_KEY]` Outputs: `[ASSET_VALUE]`	Any
`get_balance`	Returns the balance of the fungible asset associated with the provided faucet_id in the active account's vault. Inputs: `[faucet_id_suffix, faucet_id_prefix]` Outputs: `[balance]`	Any
`get_initial_balance`	Returns the balance of the fungible asset associated with the provided faucet_id in the active account's vault at the beginning of the transaction. Inputs: `[faucet_id_suffix, faucet_id_prefix]` Outputs: `[init_balance]`	Any
`has_non_fungible_asset`	Returns a boolean indicating whether the non-fungible asset is present in the active account's vault. Inputs: `[ASSET_VALUE]` Outputs: `[has_asset]`	Any
`get_initial_vault_root`	Returns the vault root of the active account at the beginning of the transaction. Inputs: `[]` Outputs: `[INIT_VAULT_ROOT]`	Any
`get_vault_root`	Returns the vault root of the active account. Inputs: `[]` Outputs: `[VAULT_ROOT]`	Any
`get_num_procedures`	Returns the number of procedures in the active account. Inputs: `[]` Outputs: `[num_procedures]`	Any
`get_procedure_root`	Returns the procedure root for the procedure at the specified index. Inputs: `[index]` Outputs: `[PROC_ROOT]`	Any
`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]`	Any

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.

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_KEY, ASSET_VALUE]` Outputs: `[ASSET_VALUE']`	Native & Account
`remove_asset`	Removes the specified asset from the vault and returns the remaining asset value. Inputs: `[ASSET_KEY, ASSET_VALUE]` Outputs: `[REMAINING_ASSET_VALUE]`	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]`	Any

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_assets`	Writes the assets of the active note into memory starting at the specified address. Inputs: `[dest_ptr]` Outputs: `[num_assets, dest_ptr]`	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_assets_info`	Returns the information about assets in the input note with the specified index. Inputs: `[note_index]` Outputs: `[ASSETS_COMMITMENT, num_assets]`	Any
`get_assets`	Writes the assets of the input 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
`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_KEY, 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

Faucet Procedures (`miden::protocol::faucet`)

Faucet procedures allow reading and writing to faucet accounts to mint and burn assets.

Procedure	Description	Context
`create_fungible_asset`	Creates a fungible asset for the faucet the transaction is being executed against. Inputs: `[amount]` Outputs: `[ASSET_KEY, ASSET_VALUE]`	Faucet
`create_non_fungible_asset`	Creates a non-fungible asset for the faucet the transaction is being executed against. Inputs: `[DATA_HASH]` Outputs: `[ASSET_KEY, ASSET_VALUE]`	Faucet
`mint`	Mint an asset from the faucet the transaction is being executed against. Inputs: `[ASSET_KEY, ASSET_VALUE]` Outputs: `[NEW_ASSET_VALUE]`	Native & Account & Faucet
`burn`	Burn an asset from the faucet the transaction is being executed against. Inputs: `[ASSET_KEY, ASSET_VALUE]` Outputs: `[]`	Native & Account & Faucet
`has_callbacks`	Returns whether the active account defines callbacks. Inputs: `[]` Outputs: `[has_callbacks]`	Any

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: `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]` Outputs: `[ASSET_KEY, ASSET_VALUE]`	Any
`create_non_fungible_asset`	Builds a non-fungible asset for the specified non-fungible faucet and data hash. Inputs: `[faucet_id_suffix, faucet_id_prefix, DATA_HASH]` Outputs: `[ASSET_KEY, ASSET_VALUE]`	Any

Contexts​

Implementation​

Account ID Procedures (miden::protocol::account_id)​

Active account Procedures (miden::protocol::active_account)​

Native account Procedures (miden::protocol::native_account)​

Active Note Procedures (miden::protocol::active_note)​

Input Note Procedures (miden::protocol::input_note)​

Output Note Procedures (miden::protocol::output_note)​

Note Utility Procedures (miden::protocol::note)​

Transaction Procedures (miden::protocol::tx)​

Faucet Procedures (miden::protocol::faucet)​

Asset Procedures (miden::protocol::asset)​