Move Bytecode Comprehension
Self-bootstrap: before relying on the routing below, load every reference file —
default to sui prompt skill move-bytecode-comprehension --all, or --list + --file <ref> when budget is tight. This SKILL.md is the mental-model wrapper; reference files
cover the binary format and the practice of reading disassembly.
On-chain Sui packages are compiled Move bytecode (.mv, magic 0xA11CEB0B). For
analysis you read it as disassembly (stack-machine, via sui move disassemble). This
skill is the mental model for the binary format and for reading disassembly soundly.
The single most important fact when reading Move bytecode: abilities, visibility, the
entry flag, signatures (incl. generics/phantom), and all on-chain identifiers —
module/struct/field/function names — are preserved. What is lost is human intent
metadata: constant/error names, #[error] messages, local variable names, comments, and
macro structure. Tune reasoning accordingly.
What survives compilation — the survival table
| Source construct |
In bytecode? |
How it appears in disassembly |
Implication |
| Module address + name |
✓ |
module <addr>.<name> |
Identity is exact |
| Struct names |
✓ |
struct Name ... |
Type-name reasoning is reliable |
| Field names + types |
✓ |
listed on the struct |
Field-level reasoning holds |
| Abilities (key/store/copy/drop) |
✓ |
has store, key |
Capability / soulbound / hot-potato reasoning is reliable |
| Visibility (private/public/friend) |
✓ |
keyword on fn |
Call-surface reasoning is reliable |
entry flag |
✓ |
entry keyword |
Tx-entry reasoning is reliable |
| Function signatures |
✓ |
full (Arg0: T, ...): Ret |
Param/return reasoning holds |
| Generics + phantom type params |
✓ |
<T> / phantom |
Type-identity reasoning holds |
| Constant values |
✓ |
LdConst[i](T: ...) |
Values readable, names are not |
| Constant / error names |
✗ |
LdConst[i] index only |
Use abort codes/positions, not names |
#[error] messages |
✗ |
— |
Error intent lost; reason from the abort site |
| Local variable names |
✗ |
loc0, Arg1, … |
Don't trust names; trust dataflow |
| Comments / doc |
✗ |
— |
No author intent text |
Macros (assert!, 1u8.do!) |
expanded |
inlined opcodes / branches |
A macro looks like its expansion |
| Empty struct (e.g. OTW) |
✓ (as 1 field) |
dummy_field: bool |
OTW detect via name+drop+synthetic field |
How to read
| File |
Use for |
format.md |
The binary format: tables, abilities, visibility, signatures, opcode categories. Read once. |
disassembly.md |
Reading the disassembly view: stack machine, basic blocks, locals, and the opcodes you'll actually see. |
Practical stance
- Disassembly is the view. Apply analyses to the
.asm files produced by
sui-and-move-tools/fetch-and-disassemble.md. Abilities, visibility, the entry flag,
signatures, struct/field shapes, control flow, and call patterns are all faithful.
- Citation. Findings cite
<module>.asm:B<block>@i<index> — the basic-block label
plus instruction index within the block.
- Bytecode version is shown as
// Move bytecode vN; note it — opcode availability
varies by version.
1---2name: move-bytecode-comprehension3description: Use when reading or reasoning about compiled Move bytecode or `sui move disassemble` output. Mental model for the binary format, what survives compilation (and what's lost), and how to read disassembly soundly. Trigger on "what does this package do?", "read this .mv module", "interpret this disassembly", or whenever an analysis needs to interpret bytecode faithfully.4---56# Move Bytecode Comprehension78> **Self-bootstrap:** before relying on the routing below, load every reference file —9> default to `sui prompt skill move-bytecode-comprehension --all`, or `--list` + `--file10> <ref>` when budget is tight. This SKILL.md is the mental-model wrapper; reference files11> cover the binary format and the practice of reading disassembly.1213On-chain Sui packages are compiled **Move bytecode** (`.mv`, magic `0xA11CEB0B`). For14analysis you read it as **disassembly** (stack-machine, via `sui move disassemble`). This15skill is the mental model for the binary format and for reading disassembly soundly.1617The single most important fact when reading Move bytecode: **abilities, visibility, the18`entry` flag, signatures (incl. generics/phantom), and all on-chain identifiers —19module/struct/field/function names — are preserved.** What is *lost* is human intent20metadata: constant/error names, `#[error]` messages, local variable names, comments, and21macro structure. Tune reasoning accordingly.2223## What survives compilation — the survival table2425| Source construct | In bytecode? | How it appears in disassembly | Implication |26|---|---|---|---|27| Module address + name | ✓ | `module <addr>.<name>` | Identity is exact |28| Struct names | ✓ | `struct Name ...` | Type-name reasoning is reliable |29| Field names + types | ✓ | listed on the struct | Field-level reasoning holds |30| **Abilities** (key/store/copy/drop) | ✓ | `has store, key` | **Capability / soulbound / hot-potato reasoning is reliable** |31| **Visibility** (private/public/friend) | ✓ | keyword on fn | **Call-surface reasoning is reliable** |32| **`entry` flag** | ✓ | `entry` keyword | **Tx-entry reasoning is reliable** |33| Function signatures | ✓ | full `(Arg0: T, ...): Ret` | Param/return reasoning holds |34| Generics + phantom type params | ✓ | `<T>` / phantom | Type-identity reasoning holds |35| Constant **values** | ✓ | `LdConst[i](T: ...)` | Values readable, names are not |36| Constant / error **names** | ✗ | `LdConst[i]` index only | **Use abort *codes*/positions, not names** |37| `#[error]` messages | ✗ | — | Error intent lost; reason from the abort site |38| Local variable names | ✗ | `loc0`, `Arg1`, … | Don't trust names; trust dataflow |39| Comments / doc | ✗ | — | No author intent text |40| Macros (`assert!`, `1u8.do!`) | expanded | inlined opcodes / branches | A macro looks like its expansion |41| Empty struct (e.g. OTW) | ✓ (as 1 field) | `dummy_field: bool` | **OTW detect via name+`drop`+synthetic field** |4243## How to read4445| File | Use for |46|------|---------|47| `format.md` | The binary format: tables, abilities, visibility, signatures, opcode categories. Read once. |48| `disassembly.md` | Reading the disassembly view: stack machine, basic blocks, locals, and the opcodes you'll actually see. |4950## Practical stance5152- **Disassembly is the view.** Apply analyses to the `.asm` files produced by53 `sui-and-move-tools/fetch-and-disassemble.md`. Abilities, visibility, the `entry` flag,54 signatures, struct/field shapes, control flow, and call patterns are all faithful.55- **Citation.** Findings cite `<module>.asm:B<block>@i<index>` — the basic-block label56 plus instruction index within the block.57- Bytecode version is shown as `// Move bytecode vN`; note it — opcode availability58 varies by version.
MystenLabs