Skip to content

Commit b7769be

Browse files
committed
docs: add bytecode overview and module format pages, fix cross-references
The previous commit left index.mdx and module-format.mdx empty. This commit adds the correct content: a bytecode reference overview and a complete module binary format specification (header, table directory, all 19 table types, code unit format). Also fixes the constant-pool anchor link in instructions.mdx and applies remark formatting to type-system.mdx.
1 parent fd7416a commit b7769be

File tree

4 files changed

+716
-128
lines changed

4 files changed

+716
-128
lines changed
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: "Bytecode Reference"
3+
description: "Technical reference for the Move bytecode format used by the Aptos Move VM, including the module binary layout, instruction set, type system, and version history."
4+
---
5+
6+
This section is a technical reference for the **Move bytecode format** -- the binary
7+
representation that the Aptos Move VM verifies and executes. It is aimed at developers building
8+
tooling (disassemblers, debuggers, static analyzers) and anyone who wants to understand what
9+
happens between `aptos move compile` and on-chain execution.
10+
11+
## How Move Source Becomes Bytecode
12+
13+
```
14+
┌──────────────┐ ┌──────────┐ ┌───────────────┐ ┌───────────┐
15+
│ Move source │ ──▶ │ Compiler │ ──▶ │ Module binary │ ──▶ │ Aptos VM │
16+
│ (.move) │ │ │ │ (bytecode blob)│ │ (execute) │
17+
└──────────────┘ └──────────┘ └───────────────┘ └───────────┘
18+
```
19+
20+
1. The **compiler** translates Move source into a self-contained module binary.
21+
2. The binary is published on-chain via a `publish` transaction.
22+
3. At execution time the **VM** loads the binary, runs the bytecode verifier, and then
23+
interprets the instructions.
24+
25+
## What Is in This Section
26+
27+
| Page | Description |
28+
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
29+
| [Module Binary Format](/build/smart-contracts/bytecode/module-format) | Header layout, magic bytes, table directory, and every table type in the binary format. Start here if you are writing a parser. |
30+
| [Instruction Set Reference](/build/smart-contracts/bytecode/instructions) | Every opcode the VM can execute -- operands, stack effects, and execution semantics. |
31+
| [Type System](/build/smart-contracts/bytecode/type-system) | How types are represented as signature tokens, how abilities work at the bytecode level, and the handle indirection model. |
32+
| [Version History](/build/smart-contracts/bytecode/version-history) | What changed in each bytecode format version from v5 through v10. |
33+
34+
## Source Code Pointers
35+
36+
The canonical definitions live in the `aptos-core` repository:
37+
38+
- **Binary format structs:** [`third_party/move/move-binary-format/src/file_format.rs`](https://github.com/AptosFoundation/aptos-core/blob/main/third_party/move/move-binary-format/src/file_format.rs)
39+
- **Serialization:** [`third_party/move/move-binary-format/src/serializer.rs`](https://github.com/AptosFoundation/aptos-core/blob/main/third_party/move/move-binary-format/src/serializer.rs)
40+
- **Deserialization:** [`third_party/move/move-binary-format/src/deserializer.rs`](https://github.com/AptosFoundation/aptos-core/blob/main/third_party/move/move-binary-format/src/deserializer.rs)
41+
- **Bytecode opcodes:** [`third_party/move/move-binary-format/src/file_format.rs`](https://github.com/AptosFoundation/aptos-core/blob/main/third_party/move/move-binary-format/src/file_format.rs) (the `Bytecode` enum)
42+
- **Bytecode verifier:** [`third_party/move/move-bytecode-verifier/src/`](https://github.com/AptosFoundation/aptos-core/tree/main/third_party/move/move-bytecode-verifier/src)

src/content/docs/build/smart-contracts/bytecode/instructions.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,7 @@ Push the given `u256` constant onto the stack.
261261
| **Operands** | `const_idx` (ULEB128 -- ConstantPoolIndex) |
262262
| **Stack** | `[...] -> [..., constant_value]` |
263263

264-
Load a constant from the module's [constant pool](/build/smart-contracts/bytecode/module-format#constant-pool),
264+
Load a constant from the module's [constant pool](/build/smart-contracts/bytecode/module-format#constant_pool-0x06),
265265
deserialize it according to its declared type, and push the resulting value onto the stack.
266266
The constant pool entry stores both the serialized bytes and the type signature.
267267

0 commit comments

Comments
 (0)