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

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 current 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 current 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 current 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 Procedures (`miden::account`)

Account procedures can be used to read and write to account storage, add or remove assets from the vault and fetch or compute commitments.

Procedure	Description	Context
`get_id`	Returns the account ID of the current account. Inputs: `[]` Outputs: `[account_id_prefix, account_id_suffix]`	Any
`get_nonce`	Returns the nonce of the current account. Always returns the initial nonce as it can only be incremented in auth procedures. Inputs: `[]` Outputs: `[nonce]`	Any
`incr_nonce`	Increments the account nonce by one and returns the new nonce. Can only be called from auth procedures. Inputs: `[]` Outputs: `[final_nonce]`	Auth
`get_initial_commitment`	Returns the native account commitment at the beginning of the transaction. Inputs: `[]` Outputs: `[INIT_COMMITMENT]`	Any
`compute_current_commitment`	Computes and returns the account commitment from account data stored in memory. Inputs: `[]` Outputs: `[ACCOUNT_COMMITMENT]`	Any
`compute_delta_commitment`	Computes the commitment to the native account's delta. Can only be called from auth procedures. Inputs: `[]` Outputs: `[DELTA_COMMITMENT]`	Auth
`get_item`	Gets an item from the account storage. Inputs: `[index]` Outputs: `[VALUE]`	Account
`set_item`	Sets an item in the account storage. Inputs: `[index, VALUE]` Outputs: `[OLD_VALUE]`	Native & Account
`get_map_item`	Returns the VALUE located under the specified KEY within the map contained in the given account storage slot. Inputs: `[index, KEY]` Outputs: `[VALUE]`	Account
`set_map_item`	Sets VALUE under the specified KEY within the map contained in the given account storage slot. Inputs: `[index, KEY, VALUE]` Outputs: `[OLD_MAP_ROOT, OLD_MAP_VALUE]`	Native & Account
`get_code_commitment`	Gets the account code commitment of the current account. Inputs: `[]` Outputs: `[CODE_COMMITMENT]`	Account
`get_initial_storage_commitment`	Returns the storage commitment of the native account at the beginning of the transaction. Inputs: `[]` Outputs: `[INIT_STORAGE_COMMITMENT]`	Any
`compute_storage_commitment`	Computes the latest account storage commitment of the current account. Inputs: `[]` Outputs: `[STORAGE_COMMITMENT]`	Account
`get_balance`	Returns the balance of the fungible asset associated with the provided faucet_id in the current account's vault. Inputs: `[faucet_id_prefix, faucet_id_suffix]` Outputs: `[balance]`	Any
`has_non_fungible_asset`	Returns a boolean indicating whether the non-fungible asset is present in the current account's vault. Inputs: `[ASSET]` Outputs: `[has_asset]`	Any
`add_asset`	Adds the specified asset to the vault. For fungible assets, returns the total after addition. Inputs: `[ASSET]` Outputs: `[ASSET']`	Native & Account
`remove_asset`	Removes the specified asset from the vault. Inputs: `[ASSET]` Outputs: `[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]`	Any
`get_vault_root`	Returns the vault root of the current account. Inputs: `[]` Outputs: `[VAULT_ROOT]`	Any
`was_procedure_called`	Returns 1 if a procedure was called during transaction execution, and 0 otherwise. Inputs: `[PROC_ROOT]` Outputs: `[was_called]`	Any

Note Procedures (`miden::note`)

Note procedures can be used to fetch data from the note that is currently being processed.

Procedure	Description	Context
`get_assets`	Writes the assets of the currently executing note into memory starting at the specified address. Inputs: `[dest_ptr]` Outputs: `[num_assets, dest_ptr]`	Note
`get_inputs`	Loads the note's inputs to the specified memory address. Inputs: `[dest_ptr]` Outputs: `[num_inputs, dest_ptr]`	Note
`get_sender`	Returns the sender of the note currently being processed. Inputs: `[]` Outputs: `[sender_id_prefix, sender_id_suffix]`	Note
`get_serial_number`	Returns the serial number of the note currently being processed. Inputs: `[]` Outputs: `[SERIAL_NUMBER]`	Note
`get_script_root`	Returns the script root of the note currently being processed. Inputs: `[]` Outputs: `[SCRIPT_ROOT]`	Note
`compute_inputs_commitment`	Computes the commitment to the note inputs starting at the specified memory address. Inputs: `[inputs_ptr, num_inputs]` Outputs: `[COMMITMENT]`	Any
`add_assets_to_account`	Adds all assets from the currently executing note to the account vault. Inputs: `[]` Outputs: `[]`	Note

Input Note Procedures (`miden::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

Output Note Procedures (`miden::output_note`)

Output note procedures can be used to fetch data on output notes created by the transaction.

Procedure	Description	Context
`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
`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

Transaction Procedures (`miden::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
`create_note`	Creates a new note and returns the index of the note. Inputs: `[tag, aux, note_type, execution_hint, RECIPIENT]` Outputs: `[note_idx]`	Native & Account
`add_asset_to_note`	Adds the ASSET to the note specified by the index. Inputs: `[ASSET, note_idx]` Outputs: `[ASSET, note_idx]`	Native
`build_recipient_hash`	Returns the RECIPIENT for a specified SERIAL_NUM, SCRIPT_ROOT, and inputs commitment. Inputs: `[SERIAL_NUM, SCRIPT_ROOT, INPUT_COMMITMENT]` Outputs: `[RECIPIENT]`	Any
`execute_foreign_procedure`	Executes the provided procedure against the foreign account. Inputs: `[foreign_account_id_prefix, foreign_account_id_suffix, 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::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]` Outputs: `[ASSET]`	Native & Account & Faucet
`burn`	Burn an asset from the faucet the transaction is being executed against. Inputs: `[ASSET]` Outputs: `[ASSET]`	Native & Account & Faucet
`get_total_issuance`	Returns the total issuance of the fungible faucet the transaction is being executed against. Inputs: `[]` Outputs: `[total_issuance]`	Faucet
`is_non_fungible_asset_issued`	Returns a boolean indicating whether the provided non-fungible asset has been already issued by this faucet. Inputs: `[ASSET]` Outputs: `[is_issued]`	Faucet

Asset Procedures (`miden::asset`)

Asset procedures provide utilities for creating fungible and non-fungible assets.

Procedure	Description	Context
`build_fungible_asset`	Builds a fungible asset for the specified fungible faucet and amount. Inputs: `[faucet_id_prefix, faucet_id_suffix, amount]` Outputs: `[ASSET]`	Any
`create_fungible_asset`	Creates a fungible asset for the faucet the transaction is being executed against. Inputs: `[amount]` Outputs: `[ASSET]`	Faucet
`build_non_fungible_asset`	Builds a non-fungible asset for the specified non-fungible faucet and data hash. Inputs: `[faucet_id_prefix, DATA_HASH]` Outputs: `[ASSET]`	Any
`create_non_fungible_asset`	Creates a non-fungible asset for the faucet the transaction is being executed against. Inputs: `[DATA_HASH]` Outputs: `[ASSET]`	Faucet

Keyboard shortcuts

The Miden book