Transaction Contexts

Miden assembly program execution can span multiple isolated contexts. An execution context defines its own memory space which is not accessible from other execution contexts. Note scripts cannot directly write into account data. This should be possible if only if the account exposes respective functions.

The kernel program always starts executing in a root context. Thus, the prologue sets the memory for the root context. To move execution into a different context, we can invoke a procedure using the call or dyncall instruction. In fact, any time we invoke a procedure using the call instruction, the procedure is executed in a new context.

While executing in a note, account, or tx script context, we can request to execute some procedures in the kernel context, which is where all necessary information was stored during the prologue. Switching to the kernle context can be done via the syscall instruction. The set of procedures which can be invoked via the syscall instruction is limited by the transaction kernel API. Once the procedure call via syscall returns, the execution moves back to the note, account, or tx script from which it was invoked.

\

\

The above diagram shows different context switches in a simple transaction. In this example, an account consumes a P2ID note and receives the asset into its vault. As with in any MASM program, the transaction kernel program starts in the root context. It executes the Prologue and stores all necessary information into the root memory.

The next step, note processing, starts with a dyncall and in doing so, invoking the note script. This command moves execution into a different context (1). In this new context, the note has no access to the kernel memory. After a successful ID check, which changes back to the kernel context twice to get the note inputs and the account id, the script executes the add_note_assets_to_account procedure.

# Pay-to-ID script: adds all assets from the note to the account, assuming ID of the account
# matches target account ID specified by the note inputs.
# ...
begin

    ... <check correct ID>

    exec.add_note_assets_to_account
    # => [...]
end

The procedure cannot simply add assets to the account, because it is executed in a note context. Therefore, it needs to call the account interface. And in doing so, it moves execution into a second context - Account context - isolated from the note context (2).

#! Helper procedure to add all assets of a note to an account.
#! ...
proc.add_note_assets_to_account
    ...

    while.true
        ...

        # load the asset and add it to the account
        mem_loadw call.wallet::receive_asset
        # => [ASSET, ptr, end_ptr, ...]
        ...
    end
    ...
end

The wallet smart contract provides an interface for accounts to recieve and send assets. In this new context, the wallet calls the add_asset procedure of the account API.

export.receive_asset
    exec.account::add_asset
    ...
end

The account API exposes procedures to manage accounts. This particular procedure that was called by the wallet invokes a syscall to return back to the root context (3), where the account vault is stored in memory (see Prologue). syscall can incoke all procedures defined in the Kernel API.

#! Add the specified asset to the vault.
#! ...
export.add_asset
    syscall.account_vault_add_asset
end

Now, the asset can be safely added to the vault within the kernel context and the note successfully be processed.

Transaction Procedures

There are user-facing procedures and kernel procedures. Users don't directly invoke kernel procedures, but indirectly via account code, note or transaction scripts. In that case, kernel procedures can only be 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 if being the wrong context procedures must be invoked by call. Users will never need to invoke syscall procedures themselves.

Note: If capitalized, a variable represents 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, can only 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.

Note

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

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.

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.

Faucet

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

Kernel Procedures

WIP - we will add those later.