Module Header and Section Layout
Every .wasm file begins with an 8-byte header: the four magic bytes 0x00 0x61 0x73 0x6D (spelling '\0asm') followed by a 4-byte little-endian version number, currently 0x01000000. After that, the entire rest of the module is a sequence of sections, each starting with a single byte section ID (0 through 12) followed by a LEB128-encoded size in bytes and then the section's payload. Known section IDs include Type (1, function signatures), Import (2), Function (3, maps functions to type indices), Table (4), Memory (5), Global (6), Export (7), Start (8), Element (9), Code (10, the actual function bodies), Data (11), and the custom section (0), which tools use for debug info like DWARF or the 'name' section without affecting execution semantics.
Cricket analogy: The magic bytes and version number are like a match scorecard's letterhead confirming it's an official ICC-format record before you even read the innings data, and each following section (Type, Import, Code) is like a separate tab, bowling figures, batting card, fall of wickets, that a parser reads in a fixed, known order.
LEB128 Encoding and Instruction Bytes
Wasm uses LEB128 (Little Endian Base 128) variable-length encoding for most integers throughout the format, including section sizes, type indices, and local variable counts, because it lets small values (the overwhelming majority in practice) take just 1 byte instead of a fixed 4 or 8, directly shrinking file size. Each byte carries 7 bits of the value plus a high continuation bit signaling whether more bytes follow; unsigned LEB128 (used for indices and counts) and signed LEB128 (used for i32.const/i64.const immediates, using two's-complement sign extension) are subtly different encodings that a hand-written decoder must implement correctly. Function bodies inside the Code section are themselves a flat stream of single-byte opcodes (like 0x20 for local.get, 0x6A for i32.add, 0x0B for the end marker closing a block) interleaved with any LEB128-encoded immediates those opcodes require.
Cricket analogy: LEB128's variable length is like how a scorecard writes '4' or '6' for a boundary in a single digit but needs extra digits for a rare double-century total, most deliveries (values) are small and get the compact encoding, while big totals spend a few extra characters, exactly LEB128's size trade-off.
Inspecting a Module with wasm-objdump
The WABT (WebAssembly Binary Toolkit) provides wasm-objdump and wasm2wat for peeling back a compiled .wasm file into human-readable form: wasm-objdump -h lists every section with its offset and size, while wasm-objdump -d disassembles the Code section into opcode mnemonics, and wasm2wat converts the whole binary into the S-expression-based WAT (WebAssembly Text) format that mirrors the binary structure one-to-one. Because WAT and the binary format are two representations of the exact same underlying structure, no information is lost converting between them, tools like wat2wasm perform the reverse compilation, which makes WAT the standard way developers and spec authors read and hand-write Wasm without dealing with raw hex.
Cricket analogy: wasm2wat is like Hawk-Eye's ball-tracking data being rendered into a readable trajectory graphic for broadcast, the underlying raw sensor bytes (binary Wasm) and the visual overlay (WAT) represent identical information in two forms suited to different audiences.
;; Equivalent WAT for a tiny Wasm module
(module
(type $add_t (func (param i32 i32) (result i32)))
(func $add (type $add_t) (param $a i32) (param $b i32) (result i32)
local.get $a
local.get $b
i32.add)
(export "add" (func $add)))
;; Inspecting the compiled binary:
;; $ wat2wasm add.wat -o add.wasm
;; $ wasm-objdump -h add.wasm
;; $ wasm-objdump -d add.wasm
;; 000019 func[0] <add>:
;; 00001a: 20 00 | local.get 0
;; 00001c: 20 01 | local.get 1
;; 00001e: 6a | i32.add
;; 00001f: 0b | endThe custom section (ID 0) is the only section the spec explicitly allows engines to skip entirely without affecting behavior; the 'name' custom section, which maps function/local indices back to source-level names, and DWARF debug sections both live here, which is why stripping custom sections is a safe way to shrink a Wasm binary for production.
Because LEB128 has both an unsigned and a signed variant with different bit-shifting and sign-extension rules, a decoder that applies the wrong variant to a given field (e.g., treating a signed i32.const immediate as unsigned) will silently produce an incorrect value rather than an obvious parse error, a common bug source when hand-writing a Wasm parser.
- Every .wasm file starts with the 4-byte magic number '\0asm' followed by a 4-byte version field.
- The rest of the module is a sequence of numbered sections (Type, Import, Function, Code, Data, etc.), each with an ID, LEB128 size, and payload.
- LEB128 variable-length encoding keeps small, common integers (indices, counts) to 1 byte, directly reducing binary size.
- Unsigned and signed LEB128 are distinct encodings; using the wrong one silently corrupts decoded values.
- The Code section holds function bodies as flat streams of single-byte opcodes plus LEB128-encoded immediates.
- WAT (WebAssembly Text format) is a lossless, one-to-one textual representation of the binary format, convertible via wat2wasm/wasm2wat.
- Custom sections (ID 0), including debug info and the 'name' section, can be safely stripped without changing execution behavior.
Practice what you learned
1. What are the first four bytes of every valid .wasm file?
2. Why does Wasm use LEB128 encoding for most integer fields?
3. Which section ID is reserved for data that engines are explicitly allowed to skip without affecting execution?
4. What is the relationship between the WAT text format and the Wasm binary format?
Was this page helpful?
You May Also Like
Compiling C/C++ to Wasm with Emscripten
Learn how the Emscripten toolchain turns C and C++ source code into WebAssembly modules that run in browsers and Node.js.
wasm-bindgen Explained
How wasm-bindgen generates the glue code that lets Rust and JavaScript exchange complex types across the Wasm boundary.
WASI Explained
What the WebAssembly System Interface is, why it exists, and how it lets Wasm modules run safely outside the browser.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics
Web DevelopmentNext.js Study Notes
JavaScript · 30 topics