[GH-ISSUE #3731] [Feature] Move VM reverse engineering: bytecode modules, abilities, resources, types and call graphs #1442

New issue

Open

opened 2026-10-16 21:05:28 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:05:28 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3731

Problem Statement & Context

The Move programming language and MoveVM represent a modern smart contract execution model designed around linear types, first-class resources, and formal verifiability. Move powers major high-throughput Layer 1 blockchains, primarily Aptos and Sui, each featuring unique architectural extensions:

Core MoveVM Bytecode: Bytecode modules (.mv) composed of 16-bit table headers, constant pools, address/module handles, struct definitions, function signatures, field handles, and register-less stack-based opcodes (MoveLoc, CopyLoc, BorrowField, Pack, Unpack).
First-Class Resources & Abilities: Struct abilities (copy, drop, store, key) strictly enforcing ownership semantics (resources cannot be copied or dropped unless explicitly permitted).
Aptos Move: Global storage partitioned by user account addresses (0x1::coin::CoinStore<AptosCoin>), resource groups, and module table changesets.
Sui Move: Object-centric architecture where state is stored in discrete, typed objects (UID, version, owner: address/shared/immutable), package linkage tables, type-origin records, and programmable transaction blocks (PTB).

Reverse engineering a compiled Move package currently requires disparate command-line tools. REA needs a unified MoveVM reverse engineering engine capable of disassembling Move bytecode, analyzing struct abilities, and reconstructing cross-module call graphs for both Aptos and Sui targets.

Proposed Architecture

flowchart TD
    A["Move Module / Package (.mv / BCS compiled package)"] --> B["Move VM Semantic Engine"]
    B --> C["Move Header & Constant Pool Deserializer"]
    B --> D["Bytecode Disassembler & CFG Constructor"]
    B --> E["Ability & Type System Reconstructor"]
    B --> F["Chain Profile Specializer (Aptos vs Sui)"]
    
    C --> C1["Magic Verification (0xA11CEB0B) & Version"]
    C --> C2["Table Stream Offsets (Structs, Functions, Signatures)"]
    
    D --> D1["Opcode Disassembly (Pack, Unpack, BorrowLoc, Branch)"]
    D --> D2["Control Flow Graph & Basic Block Analysis"]
    
    E --> E1["Struct Definitions & Abilities (copy, drop, store, key)"]
    E --> E2["Resource Access Patterns (moves_from, borrows_global)"]
    
    F --> F1["Aptos: Account Storage & Entry Function Registry"]
    F --> F2["Sui: Object Types, Shared/Owned Flags, Linkage Tables"]
    
    C & D & E & F --> G["Synthesized Move Module Interface, Resource Graph & Call Hierarchy"]

Technical Capabilities & Modules

Move Bytecode Deserialization (.mv):
- Parse Move binary header: magic bytes (0xA11CEB0B), bytecode version, and table count.
- Deserialize internal table streams: ModuleHandle, StructHandle, FunctionHandle, FieldHandle, TypeSignature, ConstantPool.
- Support both module binaries and Move script binaries.
Opcode Disassembly & Control Flow Reconstruction:
- Disassemble all standard MoveVM instructions: local variable operations, reference operations, struct operations (Pack, Unpack, BorrowField), and arithmetic/comparison opcodes.
- Reconstruct basic blocks and control flow graphs from relative jump targets.
Abilities & Resource Safety Verification:
- Extract declared abilities for every struct definition:
  - copy: Can be cloned.
  - drop: Can be popped or discarded.
  - store: Can be stored inside other structs.
  - key: Can serve as a global storage resource key or Sui object root.
- Detect operations interacting with global storage (move_to, move_from, borrow_global, borrow_global_mut).
Sui Object & Package Linkage Reconstruction:
- Parse Sui-specific package metadata:
  - Linkage table mapping original package IDs to upgraded package addresses.
  - Type origin table tracking struct provenance across package versions.
- Reconstruct programmable transaction block entrypoints (public entry fun) and object parameters (owned vs shared vs immutable references).
Aptos Resource & Changeset Modeling:
- Map entry functions, initialization functions, and view functions.
- Model resource group definitions and account storage layouts.

Acceptance Criteria

Automated detection and parsing of Move bytecode binaries (.mv) across Aptos and Sui format revisions.
Disassembly of MoveVM bytecode opcodes into structured instructions with typed operand references.
Accurate extraction of struct definitions, field types, and declared abilities (copy, drop, store, key).
Reconstruction of cross-module dependencies and function call hierarchies.
Generation of an interactive resource and object interaction diagram.

Complements #3621 (Unknown binary file-format inference)
Complements #3716 (Common Bytecode and VM Framework)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3731 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Blockchain RE](https://img.shields.io/badge/domain-blockchain_RE-orange.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ### Problem Statement & Context The Move programming language and MoveVM represent a modern smart contract execution model designed around linear types, first-class resources, and formal verifiability. Move powers major high-throughput Layer 1 blockchains, primarily **Aptos** and **Sui**, each featuring unique architectural extensions: - **Core MoveVM Bytecode**: Bytecode modules (`.mv`) composed of 16-bit table headers, constant pools, address/module handles, struct definitions, function signatures, field handles, and register-less stack-based opcodes (`MoveLoc`, `CopyLoc`, `BorrowField`, `Pack`, `Unpack`). - **First-Class Resources & Abilities**: Struct abilities (`copy`, `drop`, `store`, `key`) strictly enforcing ownership semantics (resources cannot be copied or dropped unless explicitly permitted). - **Aptos Move**: Global storage partitioned by user account addresses (`0x1::coin::CoinStore<AptosCoin>`), resource groups, and module table changesets. - **Sui Move**: Object-centric architecture where state is stored in discrete, typed objects (UID, version, owner: address/shared/immutable), package linkage tables, type-origin records, and programmable transaction blocks (PTB). Reverse engineering a compiled Move package currently requires disparate command-line tools. REA needs a unified MoveVM reverse engineering engine capable of disassembling Move bytecode, analyzing struct abilities, and reconstructing cross-module call graphs for both Aptos and Sui targets. ### Proposed Architecture ```mermaid flowchart TD A["Move Module / Package (.mv / BCS compiled package)"] --> B["Move VM Semantic Engine"] B --> C["Move Header & Constant Pool Deserializer"] B --> D["Bytecode Disassembler & CFG Constructor"] B --> E["Ability & Type System Reconstructor"] B --> F["Chain Profile Specializer (Aptos vs Sui)"] C --> C1["Magic Verification (0xA11CEB0B) & Version"] C --> C2["Table Stream Offsets (Structs, Functions, Signatures)"] D --> D1["Opcode Disassembly (Pack, Unpack, BorrowLoc, Branch)"] D --> D2["Control Flow Graph & Basic Block Analysis"] E --> E1["Struct Definitions & Abilities (copy, drop, store, key)"] E --> E2["Resource Access Patterns (moves_from, borrows_global)"] F --> F1["Aptos: Account Storage & Entry Function Registry"] F --> F2["Sui: Object Types, Shared/Owned Flags, Linkage Tables"] C & D & E & F --> G["Synthesized Move Module Interface, Resource Graph & Call Hierarchy"] ``` ### Technical Capabilities & Modules 1. **Move Bytecode Deserialization (`.mv`):** - Parse Move binary header: magic bytes (`0xA11CEB0B`), bytecode version, and table count. - Deserialize internal table streams: `ModuleHandle`, `StructHandle`, `FunctionHandle`, `FieldHandle`, `TypeSignature`, `ConstantPool`. - Support both module binaries and Move script binaries. 2. **Opcode Disassembly & Control Flow Reconstruction:** - Disassemble all standard MoveVM instructions: local variable operations, reference operations, struct operations (`Pack`, `Unpack`, `BorrowField`), and arithmetic/comparison opcodes. - Reconstruct basic blocks and control flow graphs from relative jump targets. 3. **Abilities & Resource Safety Verification:** - Extract declared abilities for every struct definition: - `copy`: Can be cloned. - `drop`: Can be popped or discarded. - `store`: Can be stored inside other structs. - `key`: Can serve as a global storage resource key or Sui object root. - Detect operations interacting with global storage (`move_to`, `move_from`, `borrow_global`, `borrow_global_mut`). 4. **Sui Object & Package Linkage Reconstruction:** - Parse Sui-specific package metadata: - Linkage table mapping original package IDs to upgraded package addresses. - Type origin table tracking struct provenance across package versions. - Reconstruct programmable transaction block entrypoints (`public entry fun`) and object parameters (owned vs shared vs immutable references). 5. **Aptos Resource & Changeset Modeling:** - Map entry functions, initialization functions, and view functions. - Model resource group definitions and account storage layouts. ### Acceptance Criteria - [ ] Automated detection and parsing of Move bytecode binaries (`.mv`) across Aptos and Sui format revisions. - [ ] Disassembly of MoveVM bytecode opcodes into structured instructions with typed operand references. - [ ] Accurate extraction of struct definitions, field types, and declared abilities (`copy`, `drop`, `store`, `key`). - [ ] Reconstruction of cross-module dependencies and function call hierarchies. - [ ] Generation of an interactive resource and object interaction diagram. ### Related Issues & Dependencies - Complements #3621 (Unknown binary file-format inference) - Complements #3716 (Common Bytecode and VM Framework)

bsakaguchi referenced this issue

2026-10-17 21:11:28 +00:00

[PR #1445] [MERGED] fix(javascript): invalidate references stored through property targets #2892

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#1442

No description provided.

Rows
Columns