Instructions

Wax instructions are expression-oriented.

Literals

A character literal is an i32 constant (its Unicode code point); a string literal builds an i8 or i16 array with array.new_fixed. An i8 array holds the raw UTF-8 bytes; an i16 array holds the UTF-16 code units (so the string must be valid Unicode).

In WAT both forms are written with annotations ((@char …) and (@string …)), so they round-trip faithfully through WAT. A Wasm binary keeps only the underlying i32.const / array.new_fixed: a character decompiles to a plain integer, and an array.new_fixed is recovered as a string only when its elements, decoded by the array’s element type (UTF-8 for i8, UTF-16 for i16), form a reasonable string (valid text, no control characters other than tab/newline/carriage return); otherwise it stays an array literal.

Numeric Instructions

Binary and unary operations use standard mathematical operators. Signedness is often explicit in the operator.

Floating Point Operations

Advanced Integer Operations

Wide Arithmetic

These 128-bit operations take and return their operands as (low, high) pairs of i64 values, so each is written as a call returning two results (typically bound with a multi-value let).

Conversions

Comparison

On reference operands (any subtype of &eq), == and != are reference equality: a == b is ref.eq, and a != b is ref.eq followed by i32.eqz (there is no ref.ne instruction).

Variable Instructions

When an expression leaves several values on the stack (typically a call to a multi-result function) and a run of local.set instructions immediately stores them into locals, the two collapse into a single multi-binding let. A drop of one of the results becomes a _ binding:

(call $divmod ...)      let (q, r) = divmod(...);
(local.set $r)
(local.set $q)

The number of stores folded is exactly the producer’s result arity, so a local.set that consumes a value already on the stack below the call is left as its own assignment.

A compound assignment x op= val is shorthand for x = x op val; it lowers to a local.get/global.get of x, the operand, the binary operator, and a local.set/global.set back into x. The reverse direction recognises exactly this shape (a set of x whose value is a binary operator with x as its left operand) and reconstructs the compound form (x = x + 1 becomes x += 1). A comparison, or x in the right operand (x = 1 - x), is left as an ordinary assignment.

Control Instructions

A drop becomes an assignment to _, an anonymous binding that evaluates its value and discards it (see Discarding a value). When the dropped value is a bare numeric expression whose width the Wax syntax would not otherwise carry, the conversion pins it with a type annotation, _: t = val, so re-reading the Wax does not re-default the value to i32/f64 and silently change its width. The annotation is emitted only where it is load-bearing; a value already anchored by a typed sub-expression (a local, a call) needs none.

The rows above are the raw instructions. Two common shapes built from them are recovered as higher-level constructs on the way back to Wax: a br_table in the conventional dense void-switch shape becomes a dispatch, and a br_on_cast/br_on_null ladder becomes a match (both below).

Block Labels and Types

Blocks, loops, and ifs can be labeled and typed. Labels are identifiers starting with ' followed by a colon.

'my_block: do { ... }
'my_loop: loop { ... }

Block types (signatures) can be specified using (param) -> result syntax or a single value type. If no type is specified, the do keyword is optional.

do (i32) -> i32 { ... }
do i32 { ... }
{ ... }                  ;; equivalent to do { ... }
if cond => (i32) -> i32 { ... } else { ... }

A single result type can be inferred, so converting from WebAssembly drops it wherever it is redundant: a do i32 { ... } becomes do { ... }, an if cond => i32 { ... } loses its => i32, and likewise for loop, try, and try_table. The type is recovered when reading the Wax back, from the values reaching the block’s exit or from the surrounding context (see Type inference). Parameterized and multi-result block types are always kept.

Branch Hints

The branch-hinting proposal annotates a conditional branch as likely or unlikely taken. Wax writes the hint as an attribute on the branch and preserves it on every round-trip (it is stored in the metadata.code.branch_hint custom section; no feature flag is needed):

#[likely] if cond { ... } else { ... }
#[unlikely] br_if 'l cond

Any conditional branch may be hinted: if, br_if, br_on_null, br_on_non_null, br_on_cast, and br_on_cast_fail. In WAT the same hint is the (@metadata.code.branch_hint "\00"|"\01") annotation preceding the branch ("\01" = likely, "\00" = unlikely).

Dispatch and Match

Two Wax control constructs have no instruction of their own: they are readable spellings of a lower-level shape, so they lower to that shape and are recovered from it on decompilation (both round-trip through the binary). See the language guide for the surface syntax: dispatch and match.

dispatch is a jump table. It lowers to one nested block per case with a br_table in the innermost block and the case bodies (which fall through) after their blocks; a br_table matching that dense void-switch shape decompiles back to dispatch:

(block $big (block $b (block $a           dispatch x ['zero 'one else 'big] {
  (br_table $a $b $big (local.get $x)))     'big:  { … }
  … 'one body …) … 'big body …)             'one:  { … }
                                            'zero: { … } }

match is a multi-way type test. It lowers to a ladder of blocks threading the scrutinee through br_on_cast (and br_on_null for a null arm), each branch delivering the narrowed value out to its arm; such a ladder decompiles back to match:

(block $default (block $arm_1                match v {
  (block $arm (result (ref $point))            p: &point => { … }
    (br_on_null $arm_1                          null      => { … }
      (br_on_cast $arm eqref (ref $point) …)))  _         => { … } }
  … arm body …) … default …)

Reference Instructions

A bare function name used as a value, f rather than the call f(args), is ref.func $f: it produces a reference to the function. This works in a global initializer and anywhere a &func reference is expected (for example the callee of an indirect call).

These casts can also chain through a forced intermediate, written as a single as:

• &ref as i32_s/as i32_u on a reference that is not already &i31 (e.g. an &any or &eq) inserts a ref.cast (ref i31) before the i31.get, so it covers both i31.get_s and ref.cast (ref i31) + i31.get_s.
• &ref as i64_s/as i64_u widens that further: the i31.get (with the ref.cast above as needed) is followed by i64.extend_i32_s/_u.
• i64 as &i31 wraps to i32 (i32.wrap_i64) before ref.i31.
• extern_val as &T for an any-hierarchy T (e.g. a struct type) inserts any.convert_extern before the ref.cast (ref T); likewise an any-hierarchy value as &extern uses extern.convert_any.
• i32_val as &extern boxes the i32 with ref.i31 before extern.convert_any.

Aggregate Instructions

A struct or array literal takes an optional type prefix ({t| … } for a struct, [t| … ] for an array), but it is omitted whenever the literal’s type can be inferred from context (an assignment, a return, a call argument), which is the common case shown below. Write the prefix only when the type is ambiguous. The {descriptor(d)| … } forms are different: descriptor(d) supplies the runtime descriptor and is part of the construction, not a prefix that can be dropped.

A packed (i8/i16) struct field or array element read sign- or zero-extends to i32 via the as i32_s/as i32_u cast, as shown above (struct.get_s/_u, array.get_s/_u). Widening straight to i64 (val.field as i64_s or arr[idx] as i64_u) emits the packed read followed by i64.extend_i32_s/_u.

SIMD (Vector) Instructions

v128 vector operations are written as method intrinsics with the lane shape baked into the name. The Wax name is the WebAssembly mnemonic with the leading shape moved to the end: i32x4.add becomes add_i32x4, f32x4.sqrt becomes sqrt_f32x4, and the whole-vector v128.and becomes and_v128. Signed/unsigned variants keep the _s/_u (min_s_i8x16, extract_lane_u_i8x16). Constant lane immediates (lane indices, shuffle indices) come first in the argument list, before any remaining stack operands.

Lanewise unary and binary operations (the receiver is the first operand):

Whole-vector bitwise operations, bit selection (a free function):

Splat, lane access, and shuffle:

Shifts, tests, and bitmask:

Constants are v128:: free functions (one argument per lane: 16, 8, 4, or 2). v128.const is a constant expression, so it may initialise a global:

Memory loads and stores are methods on a memory, like the scalar memory accesses (the optional trailing align/offset arguments work the same way):

Relaxed-SIMD operations follow the same scheme:

No intrinsic can clash with a module entity name: the free-function intrinsics are written as v128::/i64:: qualified paths and every other is a method on a receiver, so a function may freely be named e.g. v128_bitselect without any renaming.

Memory Access

Loads and stores are method calls on a memory. The method name carries the access width; the value’s signedness (for narrow loads) and its i32/i64 type are expressed with the surrounding as iN_s/as iN_u cast, mirroring packed array access.

A bare narrow load (m.load8(p) with no cast) defaults to unsigned i32, like array.get_u. The store value’s i32/i64 type is inferred from the operand.

Two optional trailing arguments give the align and offset of the access (both constant integers); offset requires align to fill its positional slot:

m.load32(p);          // i32.load
m.load32(p, 1);       // i32.load align=1
m.load32(p, 1, 16);   // i32.load align=1 offset=16

The alignment defaults to the access’s natural alignment and is only printed when it differs; the offset defaults to 0.

The remaining memory operations are also methods on the memory (a data segment is named directly, not as a value):

Atomics

Atomic accesses (the threads proposal) are methods on a memory, named after the WebAssembly mnemonic with . rewritten as _ (the value type stays in the name). They require exactly their natural alignment. atomic.fence has no memory operand and is the atomic::fence() intrinsic.

Table Access

A table is indexed like an array, and an indirect call is written as a call through a table slot cast to the callee’s function type.

call_indirect is reconstructed from this pattern on conversion to WAT/Wasm, so it round-trips. The cast target names the callee’s function type, a defined type (ft) or an inline one written fn(params) -> results (used when the WAT type is anonymous), and matches the table’s element type: for a funcref table (the usual case) it is the nullable &?ft, as shown. When the element type is already a non-null &ft, the cast may be omitted (t[i](args)).

The other table operations are methods on the table (an element segment is named directly):

A GC array can also be filled from a segment with arr.init(seg, dest, src, len) (array.init_data/array.init_elem, selected by the array’s element type), the segment-from-array counterpart of array.new_data/array.new_elem.

Exception Instructions

The try { ... } catch [ ... ] syntax compiles to WebAssembly’s try_table instruction (the current standard). The try { ... } catch { tag => { ... } } syntax compiles to the older try/catch instructions (deprecated but still supported for compatibility).

Stack Switching Instructions

These correspond to the WebAssembly stack-switching proposal. A continuation type is declared with type k = cont ft; (see Types); <k> and <tag> below are the names of a continuation type and a tag respectively.

Operands are written in WebAssembly stack order, so the continuation reference is the last argument. The handler list in [ ... ] mirrors the try ... catch [ ... ] syntax: tag -> 'l is an (on $tag $l) clause and tag -> switch is an (on $tag switch) clause.

Tags used with suspend/resume may have result types (unlike exception tags); see Tags. When a function reference is passed to cont_new for a continuation whose function type belongs to a recursion group, declare the function with an explicit type (fn f: ft (...) { ... }) so its type matches the continuation’s.