Transaction procedures

There are user-facing procedures and kernel procedures. Users don’t directly invoke kernel procedures, but instead they invoke them indirectly via account code, note, or transaction scripts. In these cases, kernel procedures are invoked by a syscall instruction which always executes in the kernel context.

User-facing procedures (APIs)¶

These procedures can be used to create smart contract/account code, note scripts, or account scripts. They basically serve as an API for the underlying kernel procedures. If a procedure can be called in the current context, an exec is sufficient. Otherwise the context procedures must be invoked by call. Users never need to invoke syscall procedures themselves.

Tip

If capitalized, a variable representing a word, e.g., ACCT_HASH consists of four felts. If lowercase, the variable is represented by a single felt.

Account¶

To import the account procedures, set use.miden::account at the beginning of the file.

Any procedure that changes the account state must be invoked in the account context and not by note or transaction scripts. All procedures invoke syscall to the kernel API and some are restricted by the kernel procedure exec.authenticate_account_origin, which fails if the parent context is not the executing account.

Procedure name	Stack	Output	Context	Description
`get_id`	`[]`	`[acct_id]`	account, note	Returns the account id.
`get_nonce`	`[]`	`[nonce]`	account, note	Returns the account nonce.
`get_initial_hash`	`[]`	`[H]`	account, note	Returns the initial account hash.
`get_current_hash`	`[]`	`[ACCT_HASH]`	account, note	Computes and returns the account hash from account data stored in memory.
`incr_nonce`	`[value]`	`[]`	account	Increments the account nonce by the provided `value` which can be at most `2^32 - 1` otherwise the procedure panics.
`get_item`	`[index]`	`[VALUE]`	account, note	Gets an item `VALUE` by `index` from the account storage. Panics if the index is out of bounds.
`set_item`	`[index, V']`	`[R', V]`	account	Sets an index/value pair in the account storage. Panics if the index is out of bounds. `R` is the new storage root.
`set_code`	`[CODE_ROOT]`	`[]`	account	Sets the code (`CODE_ROOT`) of the account the transaction is being executed against. This procedure can only be executed on regular accounts with updatable code. Otherwise, the procedure fails.
`get_balance`	`[faucet_id]`	`[balance]`	account, note	Returns the `balance` of a fungible asset associated with a `faucet_id`. Panics if the asset is not a fungible asset.
`has_non_fungible_asset`	`[ASSET]`	`[has_asset]`	account, note	Returns a boolean `has_asset` indicating whether the non-fungible asset is present in the vault. Panics if the `ASSET` is a fungible asset.
`add_asset`	`[ASSET]`	`[ASSET']`	account	Adds the specified asset `ASSET` to the vault. Panics under various conditions. If `ASSET` is a non-fungible asset, then `ASSET'` is the same as `ASSET`. If `ASSET` is a fungible asset, then `ASSET'` is the total fungible asset in the account vault after `ASSET` was added to it.
`remove_asset`	`[ASSET]`	`[ASSET]`	account	Removes the specified `ASSET` from the vault. Panics under various conditions.
`get_vault_commitment`	`[]`	`[COM]`	account, note	Returns a commitment `COM` to the account vault.

Note¶

To import the note procedures, set use.miden::note at the beginning of the file. All procedures are restricted to the note context.

Procedure name	Inputs	Outputs	Context	Description
`get_assets`	`[dest_ptr]`	`[num_assets, dest_ptr]`	note	Writes the assets of the currently executing note into memory starting at the specified address `dest_ptr`. `num_assets` is the number of assets in the currently executing note.
`get_inputs`	`[dest_ptr]`	`[dest_ptr]`	note	Writes the inputs of the currently executed note into memory starting at the specified address, `dest_ptr`.
`get_sender`	`[]`	`[sender]`	note	Returns the `sender` of the note currently being processed. Panics if a note is not being processed.

Tx¶

To import the transaction procedures set use.miden::tx at the beginning of the file. Only the create_note procedure is restricted to the account context.

Procedure name	Inputs	Outputs	Context	Description
`get_block_number`	`[]`	`[num]`	account, note	Returns the block number `num` of the last known block at the time of transaction execution.
`get_block_hash`	`[]`	`[H]`	account, note	Returns the block hash `H` of the last known block at the time of transaction execution.
`get_input_notes_hash`	`[]`	`[COM]`	account, note	Returns the input notes hash `COM`. This is computed as a sequential hash of (nullifier, script_root) tuples over all input notes.
`get_output_notes_hash`	`[0, 0, 0, 0]`	`[COM]`	account, note	Returns the output notes hash `COM`. This is computed as a sequential hash of (note_hash, note_metadata) tuples over all output notes.
`create_note`	`[ASSET, tag, RECIPIENT]`	`[ptr]`	account	Creates a new note and returns a pointer to the memory address at which the note is stored. `ASSET` is the asset to be included in the note. `tag` is the tag to be included in the note. `RECIPIENT` is the recipient of the note. `ptr` is the pointer to the memory address at which the note is stored.

Asset¶

To import the asset procedures set use.miden::asset at the beginning of the file. These procedures can only be called by faucet accounts.

Procedure name	Stack	Output	Context	Description
`build_fungible_asset`	`[faucet_id, amount]`	`[ASSET]`	faucet	Builds a fungible asset `ASSET` for the specified fungible faucet `faucet_id`, and `amount` of asset to create.
`create_fungible_asset`	`[amount]`	`[ASSET]`	faucet	Creates a fungible asset `ASSET` for the faucet the transaction is being executed against and `amount` of the asset to create.
`build_non_fungible_asset`	`[faucet_id, DATA_HASH]`	`[ASSET]`	faucet	Builds a non-fungible asset `ASSET` for the specified non-fungible faucet. `faucet_id` is the faucet to create the asset for. `DATA_HASH` is the data hash of the non-fungible asset to build.
`create_non_fungible_asset`	`[DATA_HASH]`	`[ASSET]`	faucet	Creates a non-fungible asset `ASSET` for the faucet the transaction is being executed against. `DATA_HASH` is the data hash of the non-fungible asset to create.

Faucet¶

To import the faucet procedures, set use.miden::faucet at the beginning of the file.

Procedure name	Stack	Outputs	Context	Description
`mint`	`[ASSET]`	`[ASSET]`	faucet	Mint an asset `ASSET` from the faucet the transaction is being executed against. Panics under various conditions.
`burn`	`[ASSET]`	`[ASSET]`	faucet	Burn an asset `ASSET` from the faucet the transaction is being executed against. Panics under various conditions.
`get_total_issuance`	`[]`	`[total_issuance]`	faucet	Returns the `total_issuance` of the fungible faucet the transaction is being executed against. Panics if the transaction is not being executed against a fungible faucet.