state graphs #1455

New issue

Open

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

bsakaguchi commented

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

Owner

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

Problem Statement & Context

The Open Network (TON) operates on an asynchronous actor-based multi-blockchain architecture centered around the TON Virtual Machine (TVM):

Bag of Cells (BOC) Architecture: All code, data, contracts, blocks, and messages in TON are represented as directed acyclic graphs (DAGs) of "cells". Each cell stores up to 1023 bits of arbitrary data and up to 4 references (refs) to other cells. Serialized as binary BOC containers with CRC32-C checksums.
TL-B (Typed Language - Binary) Schemas: Formal binary specification language defining how high-level types (integers, coins, addresses, dictionaries, messages) serialize into cell trees.
Hashic and Merkle Cells: Cells addressed by their cryptographic 32-byte representation hash; Merkle proofs and exotic cells (pruned branch cells) allowing verifiable sub-graph inspection.
TVM Bytecode: Stack-based virtual machine executing variable-length bit-aligned opcodes (from 4 bits to dozens of bits). Features custom stack primitives, continuation registers (c0–c7), dictionary operations (hash maps stored as Patricia trees in cells), and integer arithmetic up to 1023-bit integers.
Asynchronous Actor Messaging: Contracts communicate strictly through asynchronous messages: Inbound External (user transactions), Inbound Internal (contract-to-contract), Outbound Internal, and Outbound External (events/logs).

Reverse engineering a TON smart contract or transaction requires a completely different paradigm than EVM or WASM. REA needs a dedicated TON/TVM semantic engine capable of deserializing BOC trees, applying TL-B schemas, disassembling TVM opcodes, and modeling asynchronous actor messaging.

Proposed Architecture

flowchart TD
    A["TON Artifact (BOC Hex / Base64 / Account StateInit)"] --> B["TON / TVM Semantic Engine"]
    B --> C["BOC (Bag of Cells) Deserializer"]
    B --> D["TL-B Schema & Cell Tree Parser"]
    B --> E["TVM Bytecode Disassembler"]
    B --> F["Actor Message & State Flow Reconstructor"]
    
    C --> C1["Cell Header (Bits, Refs, Exotic Flags)"]
    C --> C2["Cell DAG Reassembly & CRC32-C Validation"]
    
    D --> D1["Standard TL-B Schemas (Message, StateInit, CommonMsgInfo)"]
    D --> D2["HashmapE / Dictionary Tree Traversal (Patricia Trie)"]
    
    E --> E1["Bit-Aligned Opcode Stream Decoding"]
    E --> E2["Continuation Registers (c0 return, c3 code, c4 data, c5 actions)"]
    
    F --> F1["Inbound / Outbound Message Slicing (Internal, External)"]
    F --> F2["Asynchronous Contract-to-Contract Call Graph"]
    
    C & D & E & F --> G["Synthesized TON Contract Blueprint, Cell Hierarchy & Message Flow"]

Technical Capabilities & Modules

Bag of Cells (BOC) Binary Deserializer:
- Parse BOC binary headers: magic bytes (0xB5EE9C72 standard, 0x68FF65F3 CRC-checked, 0xACC3A728 exotic), cell count, root count, and byte widths.
- Reassemble the directed acyclic graph of cells: decode raw bit streams (up to 1023 bits) and reference indices (up to 4 references).
- Compute standard cell representation hashes.
TL-B Type System & Dictionary Decoding:
- Implement TL-B parser mapping cell trees into typed structures:
  - MsgAddress: addr_none, addr_std (workchain ID + 256-bit account ID).
  - CommonMsgInfo: int_msg_info, ext_in_msg_info, ext_out_msg_info.
  - StateInit: split code cell and data cell.
  - Grams / Coins: variable-length coin values.
- Traverse binary Patricia trees (HashmapE, HashmapAugE) used for contract storage and jetton balances.
TVM Bytecode Disassembly:
- Disassemble variable-length, bit-aligned TVM instructions:
  - Stack manipulation: PUSH, POP, XCHG, ROT, BLKSWAP.
  - Control flow & Continuations: CALLDICT, EXECUTE, JMPX, IFRET, WHILE.
  - Cell & Slice operations: NEWC, ENDC, LDU, STU, LDSLICE, STREF.
  - Dictionary operations: DICTGET, DICTSET, DICTUGET.
Continuation & Special Register Modeling:
- Model TVM execution registers:
  - c0: Return continuation.
  - c3: Main code dictionary.
  - c4: Root persistent data cell.
  - c5: Outbound action list (messages queued to be sent).
  - c7: Temporary context tuple (balance, now, block_lt, config).
Asynchronous Actor Message Flow Reconstruction:
- Trace contract execution: input message -> TVM state transition -> emitted output actions.
- Construct an asynchronous message causality graph across multi-contract interactions (e.g. Jetton transfer, DEX swap).

Acceptance Criteria

Robust parsing and validation of binary BOC files and serialized cell graphs.
Extraction and traversal of cell bit slices and child reference trees.
Decoding of standard TL-B schemas (Message, StateInit, Account).
Disassembly of bit-aligned TVM opcodes and continuation control flow.
Reconstruction of asynchronous contract message interactions and persistent data cells.

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/3746 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Reverse Engineering](https://img.shields.io/badge/domain-reverse_engineering-blueviolet.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 Open Network (TON) operates on an asynchronous actor-based multi-blockchain architecture centered around the **TON Virtual Machine (TVM)**: 1. **Bag of Cells (BOC) Architecture**: All code, data, contracts, blocks, and messages in TON are represented as directed acyclic graphs (DAGs) of "cells". Each cell stores up to 1023 bits of arbitrary data and up to 4 references (`refs`) to other cells. Serialized as binary BOC containers with CRC32-C checksums. 2. **TL-B (Typed Language - Binary) Schemas**: Formal binary specification language defining how high-level types (integers, coins, addresses, dictionaries, messages) serialize into cell trees. 3. **Hashic and Merkle Cells**: Cells addressed by their cryptographic 32-byte representation hash; Merkle proofs and exotic cells (pruned branch cells) allowing verifiable sub-graph inspection. 4. **TVM Bytecode**: Stack-based virtual machine executing variable-length bit-aligned opcodes (from 4 bits to dozens of bits). Features custom stack primitives, continuation registers (`c0`–`c7`), dictionary operations (hash maps stored as Patricia trees in cells), and integer arithmetic up to 1023-bit integers. 5. **Asynchronous Actor Messaging**: Contracts communicate strictly through asynchronous messages: Inbound External (user transactions), Inbound Internal (contract-to-contract), Outbound Internal, and Outbound External (events/logs). Reverse engineering a TON smart contract or transaction requires a completely different paradigm than EVM or WASM. REA needs a dedicated TON/TVM semantic engine capable of deserializing BOC trees, applying TL-B schemas, disassembling TVM opcodes, and modeling asynchronous actor messaging. ### Proposed Architecture ```mermaid flowchart TD A["TON Artifact (BOC Hex / Base64 / Account StateInit)"] --> B["TON / TVM Semantic Engine"] B --> C["BOC (Bag of Cells) Deserializer"] B --> D["TL-B Schema & Cell Tree Parser"] B --> E["TVM Bytecode Disassembler"] B --> F["Actor Message & State Flow Reconstructor"] C --> C1["Cell Header (Bits, Refs, Exotic Flags)"] C --> C2["Cell DAG Reassembly & CRC32-C Validation"] D --> D1["Standard TL-B Schemas (Message, StateInit, CommonMsgInfo)"] D --> D2["HashmapE / Dictionary Tree Traversal (Patricia Trie)"] E --> E1["Bit-Aligned Opcode Stream Decoding"] E --> E2["Continuation Registers (c0 return, c3 code, c4 data, c5 actions)"] F --> F1["Inbound / Outbound Message Slicing (Internal, External)"] F --> F2["Asynchronous Contract-to-Contract Call Graph"] C & D & E & F --> G["Synthesized TON Contract Blueprint, Cell Hierarchy & Message Flow"] ``` ### Technical Capabilities & Modules 1. **Bag of Cells (BOC) Binary Deserializer:** - Parse BOC binary headers: magic bytes (`0xB5EE9C72` standard, `0x68FF65F3` CRC-checked, `0xACC3A728` exotic), cell count, root count, and byte widths. - Reassemble the directed acyclic graph of cells: decode raw bit streams (up to 1023 bits) and reference indices (up to 4 references). - Compute standard cell representation hashes. 2. **TL-B Type System & Dictionary Decoding:** - Implement TL-B parser mapping cell trees into typed structures: - `MsgAddress`: `addr_none`, `addr_std` (workchain ID + 256-bit account ID). - `CommonMsgInfo`: `int_msg_info`, `ext_in_msg_info`, `ext_out_msg_info`. - `StateInit`: split code cell and data cell. - `Grams` / `Coins`: variable-length coin values. - Traverse binary Patricia trees (`HashmapE`, `HashmapAugE`) used for contract storage and jetton balances. 3. **TVM Bytecode Disassembly:** - Disassemble variable-length, bit-aligned TVM instructions: - Stack manipulation: `PUSH`, `POP`, `XCHG`, `ROT`, `BLKSWAP`. - Control flow & Continuations: `CALLDICT`, `EXECUTE`, `JMPX`, `IFRET`, `WHILE`. - Cell & Slice operations: `NEWC`, `ENDC`, `LDU`, `STU`, `LDSLICE`, `STREF`. - Dictionary operations: `DICTGET`, `DICTSET`, `DICTUGET`. 4. **Continuation & Special Register Modeling:** - Model TVM execution registers: - `c0`: Return continuation. - `c3`: Main code dictionary. - `c4`: Root persistent data cell. - `c5`: Outbound action list (messages queued to be sent). - `c7`: Temporary context tuple (balance, now, block_lt, config). 5. **Asynchronous Actor Message Flow Reconstruction:** - Trace contract execution: input message -> TVM state transition -> emitted output actions. - Construct an asynchronous message causality graph across multi-contract interactions (e.g. Jetton transfer, DEX swap). ### Acceptance Criteria - [ ] Robust parsing and validation of binary BOC files and serialized cell graphs. - [ ] Extraction and traversal of cell bit slices and child reference trees. - [ ] Decoding of standard TL-B schemas (`Message`, `StateInit`, `Account`). - [ ] Disassembly of bit-aligned TVM opcodes and continuation control flow. - [ ] Reconstruction of asynchronous contract message interactions and persistent data cells. ### 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:33 +00:00

[PR #1455] [MERGED] docs: add Italian (it) README translation #2897

bsakaguchi referenced this issue

2026-10-31 00:50:58 +00:00

[GH-ISSUE #7656] [Bug] Indonesian and Italian analysis tables omit the Linux x64 host prerequisite #4579