Miden VM Instruction Reference

This page provides a comprehensive reference for Miden Assembly instructions.

Field Operations

Comparison Operations

Instruction	Stack Input	Stack Output	Cycles	Notes
lte lte.b	[b, a, ...]	[c, ...]	15 16	$c = \begin{cases} 1, & \text{if } a \leq b 0, & \text{otherwise} \end{cases}$
lt lt.b	[b, a, ...]	[c, ...]	14 15	$c = \begin{cases} 1, & \text{if } a < b 0, & \text{otherwise} \end{cases}$
gte gte.b	[b, a, ...]	[c, ...]	16 17	$c = \begin{cases} 1, & \text{if } a \geq b 0, & \text{otherwise} \end{cases}$
gt gt.b	[b, a, ...]	[c, ...]	15 16	$c = \begin{cases} 1, & \text{if } a > b 0, & \text{otherwise} \end{cases}$
eq eq.b	[b, a, ...]	[c, ...]	1 1-2	$c = \begin{cases} 1, & \text{if } a = b 0, & \text{otherwise} \end{cases}$
neq neq.b	[b, a, ...]	[c, ...]	2 2-3	$c = \begin{cases} 1, & \text{if } a \neq b 0, & \text{otherwise} \end{cases}$
eqw	[A, B, ...]	[c, A, B, ...]	15	$c = \begin{cases} 1, & \text{if } a_i = b_i\ \forall i \in \{0,1,2,3\} 0, & \text{otherwise} \end{cases}$
is_odd	[a, ...]	[b, ...]	5	$b = \begin{cases} 1, & \text{if $a$ is odd} 0, & \text{otherwise} \end{cases}$

Assertions and Tests

Instruction	Stack Input	Stack Output	Cycles	Notes
assert	[a, ...]	[...]	1	Removes $a$ if $a = 1$. Fails if $a \neq 1$.
assertz	[a, ...]	[...]	2	Removes $a$ if $a = 0$. Fails if $a \neq 0$.
assert_eq	[b, a, ...]	[...]	2	Removes $a, b$ if $a = b$. Fails if $a \neq b$.
assert_eqw	[B, A, ...]	[...]	11	Removes $A, B$ if $A = B$. Fails if $A \neq B$.

Note: Assertions can be parameterized with an error message (e.g., assert.err="Division by 0").

Arithmetic and Boolean Operations

Instruction	Stack Input	Stack Output	Cycles	Notes
add add.b	[b, a, ...]	[c, ...]	1 1-2	$c = (a + b) \bmod p$
sub sub.b	[b, a, ...]	[c, ...]	2 2	$c = (a - b) \bmod p$
mul mul.b	[b, a, ...]	[c, ...]	1 2	$c = (a \cdot b) \bmod p$
div div.b	[b, a, ...]	[c, ...]	2 2	$c = (a \cdot b^{-1}) \bmod p$. Fails if $b = 0$.
neg	[a, ...]	[b, ...]	1	$b = -a \bmod p$
inv	[a, ...]	[b, ...]	1	$b = a^{-1} \bmod p$. Fails if $a = 0$.
pow2	[a, ...]	[b, ...]	16	$b = 2^a$. Fails if $a > 63$.
exp.uxx exp.b	[b, a, ...]	[c, ...]	9+xx 9+log2(b)	$c = a^b$. Fails if $xx$ is outside $[0, 63)$. exp is exp.u64 (73 cycles).
ilog2	[a, ...]	[b, ...]	44	$b = \lfloor \log_2(a) \rfloor$. Fails if $a = 0$.
not	[a, ...]	[b, ...]	1	$b = 1 - a$. Fails if $a > 1$.
and	[b, a, ...]	[c, ...]	1	$c = a \cdot b$. Fails if $\max(a, b) > 1$.
or	[b, a, ...]	[c, ...]	1	$c = a + b - a \cdot b$. Fails if $\max(a, b) > 1$.
xor	[b, a, ...]	[c, ...]	7	$c = a + b - 2 \cdot a \cdot b$. Fails if $\max(a, b) > 1$.

Extension Field Operations

All operations in this section are defined over the quadratic extension field $\mathbb{F}_p[x] / (x^2 - x + 2)$, with modulus $p = 2^{64} - 2^{32} + 1$.

Instruction	Stack Input	Stack Output	Cycles	Notes
ext2add	[b1, b0, a1, a0, ...]	[c1, c0, ...]	5	$c1 = (a1 + b1) \bmod p$ $c0 = (a0 + b0) \bmod p$
ext2sub	[b1, b0, a1, a0, ...]	[c1, c0, ...]	7	$c1 = (a1 - b1) \bmod p$ $c0 = (a0 - b0) \bmod p$
ext2mul	[b1, b0, a1, a0, ...]	[c1, c0, ...]	3	$c1 = (a0 + a1)(b0 + b1) - a0b0 \bmod p$ $c0 = a0b0 - 2a1b1 \bmod p$
ext2neg	[a1, a0, ...]	[a1', a0', ...]	4	$a1' = -a1$ $a0' = -a0$
ext2inv	[a1, a0, ...]	[a1', a0', ...]	8	$a' = a^{-1}$ in $\mathbb{F}_p[x]/(x^2 - x + 2)$. Fails if $a = 0$.
ext2div	[b1, b0, a1, a0, ...]	[c1, c0, ...]	11	$c = a \cdot b^{-1}$ in $\mathbb{F}_p[x]/(x^2 - x + 2)$. Fails if $b = 0$.

U32 Operations

Operations on 32-bit integers. Most instructions will fail or have undefined behavior if inputs are not valid u32 values.

Conversions and Tests

Instruction	Stack Input	Stack Output	Cycles	Notes
u32test	[a, ...]	[b, a, ...]	5	$b = \begin{cases} 1, & \text{if } a < 2^{32} 0, & \text{otherwise} \end{cases}$
u32testw	[A, ...]	[b, A, ...]	23	$b = \begin{cases} 1, & \text{if } \forall i \in \{0,1,2,3\}, a_i < 2^{32} 0, & \text{otherwise} \end{cases}$
u32assert	[a, ...]	[a, ...]	3	Fails if $a \geq 2^{32}$.
u32assert2	[b, a,...]	[b, a,...]	1	Fails if $a \geq 2^{32}$ or $b \geq 2^{32}$.
u32assertw	[A, ...]	[A, ...]	6	Fails if any element of $A$ is $\geq 2^{32}$.
u32cast	[a, ...]	[b, ...]	2	$b = a \bmod 2^{32}$
u32split	[a, ...]	[c, b, ...]	1	$b = a \bmod 2^{32}$, $c = \lfloor a / 2^{32} \rfloor$

Note: Assertions can be parameterized with an error message (e.g., assert.err="Division by 0").

Arithmetic Operations

Instruction	Stack Input	Stack Output	Cycles	Notes
u32overflowing_add u32overflowing_add.b	[b, a, ...]	[d, c, ...]	1 2-3	$c = (a + b) \bmod 2^{32}$, $d = \begin{cases} 1, & \text{if } (a + b) \geq 2^{32} 0, & \text{otherwise} \end{cases}$. Undefined if $\max(a,b) \geq 2^{32}$.
u32wrapping_add u32wrapping_add.b	[b, a, ...]	[c, ...]	2 3-4	$c = (a + b) \bmod 2^{32}$. Undefined if $\max(a,b) \geq 2^{32}$.
u32overflowing_add3	[c, b, a, ...]	[e, d, ...]	1	$d = (a+b+c) \bmod 2^{32}$, $e = \lfloor (a+b+c)/2^{32} \rfloor$. Undefined if $\max(a,b,c) \geq 2^{32}$.
u32wrapping_add3	[c, b, a, ...]	[d, ...]	2	$d = (a+b+c) \bmod 2^{32}$. Undefined if $\max(a,b,c) \geq 2^{32}$.
u32overflowing_sub u32overflowing_sub.b	[b, a, ...]	[d, c, ...]	1 2-3	$c = (a - b) \bmod 2^{32}$, $d = \begin{cases} 1, & \text{if } a < b 0, & \text{otherwise} \end{cases}$. Undefined if $\max(a,b) \geq 2^{32}$.
u32wrapping_sub u32wrapping_sub.b	[b, a, ...]	[c, ...]	2 3-4	$c = (a - b) \bmod 2^{32}$. Undefined if $\max(a,b) \geq 2^{32}$.
u32overflowing_mul u32overflowing_mul.b	[b, a, ...]	[d, c, ...]	1 2-3	$c = (a \cdot b) \bmod 2^{32}$, $d = \lfloor(a \cdot b) / 2^{32}\rfloor$. Undefined if $\max(a,b) \geq 2^{32}$.
u32wrapping_mul u32wrapping_mul.b	[b, a, ...]	[c, ...]	2 3-4	$c = (a \cdot b) \bmod 2^{32}$. Undefined if $\max(a,b) \geq 2^{32}$.
u32overflowing_madd	[b, a, c, ...]	[e, d, ...]	1	$d = (a \cdot b+c) \bmod 2^{32}$, $e = \lfloor(a \cdot b+c) / 2^{32}\rfloor$. Undefined if $\max(a,b,c) \geq 2^{32}$.
u32wrapping_madd	[b, a, c, ...]	[d, ...]	2	$d = (a \cdot b+c) \bmod 2^{32}$. Undefined if $\max(a,b,c) \geq 2^{32}$.
u32div u32div.b	[b, a, ...]	[c, ...]	2 3-4	$c = \lfloor a/b \rfloor$. Fails if $b=0$. Undefined if $\max(a,b) \geq 2^{32}$.
u32mod u32mod.b	[b, a, ...]	[c, ...]	3 4-5	$c = a \bmod b$. Fails if $b=0$. Undefined if $\max(a,b) \geq 2^{32}$.
u32divmod u32divmod.b	[b, a, ...]	[d, c, ...]	1 2-3	$c = \lfloor a/b \rfloor$, $d = a \bmod b$. Fails if $b=0$. Undefined if $\max(a,b) \geq 2^{32}$.

Bitwise Operations

Instruction	Stack Input	Stack Output	Cycles	Notes
u32and u32and.b	[b, a, ...]	[c, ...]	1 2	Bitwise AND. Fails if $\max(a,b) \geq 2^{32}$.
u32or u32or.b	[b, a, ...]	[c, ...]	6 7	Bitwise OR. Fails if $\max(a,b) \geq 2^{32}$.
u32xor u32xor.b	[b, a, ...]	[c, ...]	1 2	Bitwise XOR. Fails if $\max(a,b) \geq 2^{32}$.
u32not u32not.a	[a, ...]	[b, ...]	5 6	Bitwise NOT. Fails if $a \geq 2^{32}$.
u32shl u32shl.b	[b, a, ...]	[c, ...]	18 3	$c = (a \cdot 2^b) \bmod 2^{32}$. Undefined if $a \geq 2^{32}$ or $b > 31$.
u32shr u32shr.b	[b, a, ...]	[c, ...]	18 3	$c = \lfloor a / 2^b \rfloor$. Undefined if $a \geq 2^{32}$ or $b > 31$.
u32rotl u32rotl.b	[b, a, ...]	[c, ...]	18 3	Rotate left. Undefined if $a \geq 2^{32}$ or $b > 31$.
u32rotr u32rotr.b	[b, a, ...]	[c, ...]	23 3	Rotate right. Undefined if $a \geq 2^{32}$ or $b > 31$.
u32popcnt	[a, ...]	[b, ...]	33	Population count (Hamming weight). Undefined if $a \geq 2^{32}$.
u32clz	[a, ...]	[b, ...]	42	Count leading zeros. Undefined if $a \geq 2^{32}$.
u32ctz	[a, ...]	[b, ...]	34	Count trailing zeros. Undefined if $a \geq 2^{32}$.
u32clo	[a, ...]	[b, ...]	41	Count leading ones. Undefined if $a \geq 2^{32}$.
u32cto	[a, ...]	[b, ...]	33	Count trailing ones. Undefined if $a \geq 2^{32}$.

Comparison Operations

Instruction	Stack Input	Stack Output	Cycles	Notes
u32lt u32lt.b	[b, a, ...]	[c, ...]	3 4	$c = \begin{cases} 1, & \text{if } a < b 0, & \text{otherwise} \end{cases}$. Undefined if $\max(a,b) \geq 2^{32}$.
u32lte u32lte.b	[b, a, ...]	[c, ...]	5 6	$c = \begin{cases} 1, & \text{if } a \leq b 0, & \text{otherwise} \end{cases}$. Undefined if $\max(a,b) \geq 2^{32}$.
u32gt u32gt.b	[b, a, ...]	[c, ...]	4 5	$c = \begin{cases} 1, & \text{if } a > b 0, & \text{otherwise} \end{cases}$. Undefined if $\max(a,b) \geq 2^{32}$.
u32gte u32gte.b	[b, a, ...]	[c, ...]	4 5	$c = \begin{cases} 1, & \text{if } a \geq b 0, & \text{otherwise} \end{cases}$. Undefined if $\max(a,b) \geq 2^{32}$.
u32min u32min.b	[b, a, ...]	[c, ...]	8 9	$c = \min(a,b)$. Undefined if $\max(a,b) \geq 2^{32}$.
u32max u32max.b	[b, a, ...]	[c, ...]	9 10	$c = \max(a,b)$. Undefined if $\max(a,b) \geq 2^{32}$.

Stack Manipulation

Instructions for directly manipulating the operand stack. Only the top 16 elements are directly accessible.

Instruction	Stack Input	Stack Output	Cycles	Notes
drop	[a, ... ]	[ ... ]	1	Deletes the top stack item.
dropw	[A, ... ]	[ ... ]	4	Deletes a word (4 elements) from the top of the stack.
padw	[ ... ]	[0,0,0,0, ... ]	4	Pushes four 0 values onto the stack.
dup.n	[ ..., a, ... ]	[a, ..., a, ... ]	1-3	Pushes a copy of the nth stack item (0-indexed) onto the stack. dup is dup.0. Valid for n in 0..=15.
dupw.n	[ ..., A, ... ]	[A, ..., A, ... ]	4	Pushes a copy of the nth stack word (0-indexed) onto the stack. dupw is dupw.0. Valid for n in 0..=3.
swap.n	[a, ..., b, ... ]	[b, ..., a, ... ]	1-6	Swaps the top stack item with the nth stack item (1-indexed). swap is swap.1. Valid for n in 1..=15.
swapw.n	[A, ..., B, ... ]	[B, ..., A, ... ]	1	Swaps the top stack word with the nth stack word (1-indexed). swapw is swapw.1. Valid for n in 1..=3.
swapdw	[D,C,B,A, ... ]	[B,A,D,C ... ]	1	Swaps words: 1st with 3rd, 2nd with 4th.
movup.n	[ ..., a, ... ]	[a, ... ]	1-4	Moves the nth stack item (2-indexed) to the top. Valid for n in 2..=15.
movupw.n	[ ..., A, ... ]	[A, ... ]	2-3	Moves the nth stack word (2-indexed) to the top. Valid for n in 2..=3.
movdn.n	[a, ... ]	[ ..., a, ... ]	1-4	Moves the top stack item to the nth position (2-indexed). Valid for n in 2..=15.
movdnw.n	[A, ... ]	[ ..., A, ... ]	2-3	Moves the top stack word to the nth word position (2-indexed). Valid for n in 2..=3.

Conditional Manipulation

Instruction	Stack Input	Stack Output	Cycles	Notes
cswap	[c, b, a, ... ]	[e, d, ... ]	1	If c = 1, d=b, e=a. If c = 0, d=a, e=b. Fails if c > 1.
cswapw	[c, B, A, ... ]	[E, D, ... ]	1	If c = 1, D=B, E=A. If c = 0, D=A, E=B. Fails if c > 1.
cdrop	[c, b, a, ... ]	[d, ... ]	2	If c = 1, d=b. If c = 0, d=a. Fails if c > 1.
cdropw	[c, B, A, ... ]	[D, ... ]	5	If c = 1, D=B. If c = 0, D=A. Fails if c > 1.

Input/Output Operations

Instructions for moving data between the stack and other sources like program code, environment, advice provider, and memory.

Constant Inputs

Instruction	Stack Input	Stack Output	Cycles	Notes
push.a...	[ ... ]	[c, b, a, ...]	1-2	Pushes up to 16 field elements (decimal or hex) onto the stack. Hex words (32 bytes) are little-endian; short hex values are big-endian. Example: push.0x1234.0x5678 or push.0x34120000...78560000...

Environment Inputs

Instruction	Stack Input	Stack Output	Cycles	Notes
clk	[ ... ]	[t, ... ]	1	Pushes current clock cycle t.
sdepth	[ ... ]	[d, ... ]	1	Pushes current stack depth d.
caller	[A, b,...]	[H, b,...]	1	In context 0, overwrites the top 4 stack items with hash H of the function that syscall'd into the current context, or [0, 0, 0, 0] when not servicing a SYSCALL. In any other context, H corresponds to the hash of the function that entered the current context.
locaddr.i	[ ... ]	[a, ... ]	2	Pushes absolute memory address a of local memory at index i.
procref.name	[ ... ]	[A, ... ]	4	Pushes MAST root A of procedure name.

Nondeterministic Inputs (Advice Provider)

Reading from Advice Stack

Instruction	Stack Input	Stack Output	Cycles	Notes
adv_push.n	[ ... ]	[a, ...]	n	Pops n values from advice stack to operand stack (1st popped is deepest). Valid n in 1..=16. Fails if advice stack has < n values.
adv_loadw	[0,0,0,0, ...]	[A, ...]	1	Pops word A (4 elements) from advice stack, overwrites top word of operand stack. Fails if advice stack has < 4 values.
adv_pipe	[C,B,A,a,...]	[E,D,A,a',...]	1	Pops 2 words [D,E] from advice stack. Overwrites top 2 words of operand stack. Writes [D,E] to memory at a and a+1. a' ← a+2. Fails if advice stack has < 8 values.

Injecting into Advice Provider (System Events - 3 cycles)

Push to Advice Stack:

Instruction	Stack Input	Stack Output	Notes
adv.push_mapval	[K, ... ]	[K, ... ]	Pushes values from advice_map[K] to advice stack.
adv.push_mapvaln	[K, ... ]	[K, ... ]	Pushes [n, ele1, ele2, ...] from advice_map[K] to advice stack, where n is element count.
adv.push_mtnode	[d, i, R, ... ]	[d, i, R, ... ]	Pushes Merkle tree node (root R, depth d, index i) from Merkle store to advice stack.

Insert into Advice Map:

Instruction	Stack Input	Stack Output	Notes
adv.insert_mem	[K, a, b, ... ]	[K, a, b, ... ]	advice_map[K] ← mem[a..b].
adv.insert_hdword	[B, A, ... ]	[B, A, ... ]	K ← hash(A || B, domain=0). advice_map[K] ← [A,B].
adv.insert_hdword_d	[B, A, d, ... ]	[B, A, d, ... ]	K ← hash(A || B, domain=d). advice_map[K] ← [A,B].
adv.insert_hqword	[D, C, B, A, ... ]	[D, C, B, A, ... ]	K ← hash(hash(hash(A || B) || C) || D), domain=0. advice_map[K] ← [A,B,C,D].
adv.insert_hperm	[B, A, C, ...]	[B, A, C, ...]	K ← permute(C,A,B).digest. advice_map[K] ← [A,B].

Random Access Memory

Memory is 0-initialized. Addresses are absolute [0, 2^32). Locals are stored at offset 2^30.

Absolute Addressing

Instruction	Stack Input	Stack Output	Cycles	Notes
mem_load mem_load.a	[a, ... ]	[v, ... ]	1 2	v ← mem[a]. Pushes element from mem[a]. If a on stack, it's popped. Fails if a >= 2^32.
mem_loadw_be mem_loadw_be.a	[a, 0,0,0,0,...]	[A, ... ]	1 2	A ← mem[a..a+3] (word, big-endian). Overwrites top 4 stack elements (mem[a+3] is top). If a on stack, it's popped. Fails if a >= 2^32 or a not multiple of 4.
mem_loadw_le mem_loadw_le.a	[a, 0,0,0,0,...]	[A, ... ]	4 5	A ← mem[a..a+3] (word, little-endian). Overwrites top 4 stack elements (mem[a] is top). Equivalent to mem_loadw_be reversew. If a on stack, it's popped. Fails if a >= 2^32 or a not multiple of 4.
mem_store mem_store.a	[a, v, ... ]	[ ... ]	2 3-4	mem[a] ← v. Pops v to mem[a]. If a on stack, it's popped. Fails if a >= 2^32.
mem_storew_be mem_storew_be.a	[a, A, ... ]	[A, ... ]	1 2-3	mem[a..a+3] ← A. Stores word A in big-endian order (top stack element at mem[a+3]). If a on stack, it's popped. Fails if a >= 2^32 or a not multiple of 4.
mem_storew_le mem_storew_le.a	[a, A, ... ]	[A, ... ]	9 8-9	mem[a..a+3] ← A. Stores word A in little-endian order (top stack element at mem[a]). Equivalent to reversew mem_storew_be reversew. If a on stack, it's popped. Fails if a >= 2^32 or a not multiple of 4.
mem_stream	[C, B, A, a, ... ]	[E,D,A,a',...]	1	[E,D] ← [mem[a..a+3], mem[a+4..a+7]]. a' ← a+8. Reads 2 sequential words from memory to top of stack.

Procedure Locals (Context-Specific)

Locals are not 0-initialized. Max $2^{16}$ locals per procedure, $2^{31} - 1$ total. Rounded up to multiple of 4.

Instruction	Stack Input	Stack Output	Cycles	Notes
loc_load.i	[ ... ]	[v, ... ]	5-6	v ← local[i]. Pushes element from local memory at index i.
loc_loadw_be.i	[0,0,0,0, ...]	[A, ... ]	5-6	A ← local[i..i+3]. Reads word in big-endian order, local[i+3] is top of stack. Fails if i not multiple of 4.
loc_loadw_le.i	[0,0,0,0, ...]	[A, ... ]	9-10	A ← local[i..i+3]. Reads word in little-endian order, local[i] is top of stack. Equivalent to loc_loadw_be reversew. Fails if i not multiple of 4.
loc_store.i	[v, ... ]	[ ... ]	6-7	local[i] ← v. Pops v to local memory at index i.
loc_storew_be.i	[A, ... ]	[A, ... ]	5-6	local[i..i+3] ← A. Stores word in big-endian order, top stack element at local[i+3].
loc_storew_le.i	[A, ... ]	[A, ... ]	13-14	local[i..i+3] ← A. Stores word in little-endian order, top stack element at local[i]. Equivalent to reversew loc_storew_be reversew.

Cryptographic Operations

Common cryptographic operations, including hashing and Merkle tree manipulations using Rescue Prime Optimized.

Hashing and Merkle Trees

Instruction	Stack Input	Stack Output	Cycles	Notes
hash	[A, ...]	[B, ...]	20	B ← hash(A). 1-to-1 Rescue Prime Optimized hash.
hperm	[B, A, C, ...]	[F, E, D, ...]	1	D,E,F ← permute(C,A,B). Rescue Prime Optimized permutation. C=capacity, A,B=rate, E=digest.
hmerge	[B, A, ...]	[C, ...]	16	C ← hash(A,B). 2-to-1 Rescue Prime Optimized hash.
mtree_get	[d, i, R, ...]	[V, R, ...]	9	Verifies Merkle path for node V at depth d, index i for tree R (from advice provider), returns V.
mtree_set	[d, i, R, V', ...]	[V, R', ...]	29	Updates node in tree R at d,i to V'. Returns old value V and new root R'. Both trees in advice provider.
mtree_merge	[R, L, ...]	[M, ...]	16	Merges Merkle trees with roots L (left) and R (right) into new tree M. Input trees retained.
mtree_verify	[V, d, i, R, ...]	[V,d,i,R,...]	1	Verifies Merkle path for node V at depth d, index i for tree R (from advice provider). Can be parameterized with err code (e.g., mtree_verify.err=123). Default error code is 0.

Flow Control Operations

High-level constructs for controlling the execution flow.

Conditional Execution: if.true ... else ... end / if.false ... else ... end

• Syntax:

  if.true
    # instructions for true branch
  else
    # instructions for false branch
  end

  Or with if.false (condition inverted). The else block is optional.
• Stack Input: [cond, ...] (where cond is 0 or 1)
• Cycles: Incurs a small overhead. For simple conditionals, cdrop might be more efficient if side-effects can be managed.
• Notes:
  • Pops cond from the stack. Fails if not boolean.
  • if.true: Executes first block if cond = 1, second (else) block if cond = 0.
  • if.false: Executes first block if cond = 0, second (else) block if cond = 1.
  • Empty or elided branches are treated as a nop.
  • Ensure stack consistency at join points if modifications persist beyond a branch.

Counter-Controlled Loops: repeat.count ... end

• Syntax:

  repeat.COUNT
    # instructions to repeat
  end

• Cycles: No additional cost for counting; the block is unrolled COUNT times during compilation.
• Notes:
  • COUNT must be an integer or a named constant greater than 0.
  • Instructions inside can include nested control structures.

Condition-Controlled Loops: while.true ... end

• Syntax:

  while.true
    # instructions for loop body
  end

• Stack Input (for each iteration check): [cond, ...] (where cond is 0 or 1)
• Cycles: Overhead per iteration for condition check.
• Notes:
  1. Pops cond from the stack. If 0, skips loop. Fails if not boolean.
  2. If cond = 1, executes loop body.
  3. After body execution, pops a new cond. If 1, repeats body. If 0, exits loop. Fails if not boolean.

No-Operation: nop

• Syntax: nop
• Cycles: 1
• Notes:
  • Increments the cycle counter with no other effects.
  • Useful for empty blocks or explicitly advancing cycles.
  • Assembler automatically inserts nop for empty/elided branches in if statements.

Events

Instructions for communicating with the host through events and tracing.

Instruction	Stack Input	Stack Output	Cycles	Notes
emit.<event_id>	[...]	[...]	3	Emits an event with the specified event_id to the host. The net effect on the operand stack is no change (internally expands to push.<event_id> emit drop). Immediate event_id must be defined via const.ID=event("...") or inlined as emit.event("..."). Events allow programs to communicate contextual information to the host for triggering appropriate actions. Example: emit.event("foo") or emit.MY_EVENT
emit	[event_id, ...]	[event_id, ...]	1	Emits an event using the event_id from the top of the stack. The stack remains unchanged as the event_id is read without consuming it. This instruction reads the event ID from the stack but does not modify the stack depth. Example: with push.1230 on stack, emit reads the event ID 1230 and executes the corresponding event handler. Note that event IDs in the range 0..256 are reserved for system events.
trace.<trace_id>	[...]	[...]	0	Emits a trace with the specified trace_id to the host. Does not change the state of the operand stack. The trace_id can be any 32-bit value specified either directly or via a named constant. Only active when programs are run with tracing flag (-t or --trace), otherwise ignored. Example: trace.123 or trace.TRACE_ID_1
log_precompile	[COMM, TAG, PAD, ...]	[R1, R0, CAP_NEXT, ...]	1	Absorbs a precompile commitment into the transcript used for deferred verification. Takes a precompile commitment (TAG and COMM) from the stack and performs an RPO256 permutation to update the transcript capacity (sponge capacity). Outputs [R1, R0, CAP_NEXT]; callers normally drop all three words immediately. See “Precompile flow” for initialization details.

Debugging Operations

Instructions for inspecting VM state during execution. These do not affect VM state or program hash and are only active when the assembler is in debug mode.

debug

• Syntax & Parameters:
  • debug.stack: Prints entire stack.
  • debug.stack.N: Prints top N stack items (0 < N < 256).
  • debug.mem: Prints entire RAM.
  • debug.mem.A: Prints memory at address A.
  • debug.mem.A.M: Prints memory from address A to M (inclusive, M >= A).
  • debug.local: Prints entire local memory of the current procedure.
  • debug.local.I: Prints local memory at index I (0 <= I < 65536).
  • debug.local.I.M: Prints local memory from index I to M (inclusive, M >= I, 0 <= I, M < 65536).
• Cycles: 0 (does not consume VM cycles).
• Notes:
  • Prints the specified part of the VM state.
  • Ignored if assembler is not in debug mode.