A Miden assembly program is just a sequence of instructions each describing a specific directive or an operation. You can use any combination of whitespace characters to separate one instruction from another.
In turn, Miden assembly instructions are just keywords which can be parameterized by zero or more parameters. The notation for specifying parameters is keyword.param1.param2 - i.e., the parameters are separated by periods. For example,
push.123 instruction denotes a
push operation which is parameterized by value
Miden assembly programs are organized into procedures. Procedures, in turn, can be grouped into modules.
A procedure can be used to encapsulate a frequently-used sequence of instructions which can later be invoked via a label. A procedure must start with a
proc.<label>.<number of locals> instruction and terminate with an
end instruction. For example:
A procedure label must start with a letter and can contain any combination of numbers, ASCII letters, and underscores (
_). The number of characters in the procedure label cannot exceed 100.
The number of locals specifies the number of memory-based local words a procedure can access (via
loc_store, and other instructions). If a procedure doesn't need any memory-based locals, this parameter can be omitted or set to
0. A procedure can have at most locals, and the total number of locals available to all procedures at runtime is limited to .
To execute a procedure, the
syscall.<label> instructions can be used. For example:
The difference between using each of these instructions is explained in the next section.
A procedure may execute any other previously defined procedure, but it cannot execute itself or any of the subsequent procedures. Thus, recursive procedure calls are not possible. For example, the following code block defines a program with two procedures:
A module consists of one or more procedures. There are two types of modules: library modules and executable modules (also called programs).
Library modules contain zero or more internal procedures and one or more exported procedures. For example, the following module defines one internal procedure (defined with
proc instruction) and one exported procedure (defined with
Executable modules are used to define programs. A program contains zero or more internal procedures (defined with
proc instruction) and exactly one main procedure (defined with
begin instruction). For example, the following module defines one internal procedure and a main procedure:
A program cannot contain any exported procedures.
When a program is executed, the execution starts at the first instruction following the
begin instruction. The main procedure is expected to be the last procedure in the program and can be followed only by comments.
To invoke a procedure from an external module, the module first needs to be imported using a
use instruction. Once a module is imported, procedures from this module can be invoked via the regular
call instructions as
label is the name of the procedure. For example:
In the above example we import
std::math::u64 module from the standard library. We then execute a program which pushes two 64-bit integers onto the stack, and then invokes a 64-bit addition procedure from the imported module.
The set of modules which can be imported by a program can be specified via a Module Provider when instantiating the Miden Assembler used to compile the program.
Miden assembly supports constant declarations. These constants are scoped to the module they are defined in and can be used as immediate parameters for Miden assembly instructions. Currently only
push instruction supports this.
Constants must be declared right after module imports and before any procedures or program bodies. A constant's name must start with an upper-case letter and can contain any combination of numbers, upper-case ASCII letters, and underscores (
_). The number of characters in a constant name cannot exceed 100.
Miden assembly allows annotating code with simple comments. There are two types of comments: single-line comments which start with a
# (pound) character, and documentation comments which start with
#! characters. For example:
#! This is a documentation comment
# this is a comment
Documentation comments must precede a procedure declaration. Using them inside a procedure body is an error.