diff --git a/.vale/config/vocabularies/Custom/accept.txt b/.vale/config/vocabularies/Custom/accept.txt index fb55bfe1..13c3101f 100644 --- a/.vale/config/vocabularies/Custom/accept.txt +++ b/.vale/config/vocabularies/Custom/accept.txt @@ -53,6 +53,7 @@ Cryptobot Cryptocurrencies DApps? DEX(s|es)? +(?i)Decompil(ation|ed|er) DHTs? D_m Daniil @@ -163,6 +164,7 @@ Reindexing Relatedly Reputational Reth +(?i)Retracer Revm Ristretto Rollup diff --git a/docs.json b/docs.json index 4ffb14f7..a761676a 100644 --- a/docs.json +++ b/docs.json @@ -413,6 +413,16 @@ "group": "TVM: TON Virtual Machine", "pages": [ "tvm/overview", + { + "group": "Tools", + "pages": [ + "tvm/tools/overview", + "tvm/tools/txtracer", + "tvm/tools/retracer", + "tvm/tools/tvm-explorer", + "tvm/tools/ton-decompiler" + ] + }, { "group": "Serialization", "pages": [ diff --git a/resources/images/tvmexplorer.png b/resources/images/tvmexplorer.png new file mode 100644 index 00000000..bbfcdc10 Binary files /dev/null and b/resources/images/tvmexplorer.png differ diff --git a/resources/images/txtracer.png b/resources/images/txtracer.png new file mode 100644 index 00000000..059f5cfa Binary files /dev/null and b/resources/images/txtracer.png differ diff --git a/tvm/tools/overview.mdx b/tvm/tools/overview.mdx new file mode 100644 index 00000000..a41c4598 --- /dev/null +++ b/tvm/tools/overview.mdx @@ -0,0 +1,22 @@ +--- +title: "TVM Tools" +sidebarTitle: "Overview" +--- + +TVM tools help developers analyze, debug, and understand TON Virtual Machine execution. These utilities provide insights into bitcode, transactions, and contract behavior. + +## Available Tools + +- **[TxTracer](/tvm/tools/tx-tracer)** — Modern transaction tracing tool with assembly playground and code exploration +- **[Retracer](/tvm/tools/retracer)** — Classic transaction tracing tool for detailed execution analysis +- **[Ton Decompiler](/tvm/tools/ton-decompiler)** — Reverse-engineer TVM bitcode into readable pseudocode +- **[TVM Explorer](/tvm/tools/tvm-explorer)** — Interactive bitcode and instruction explorer + +## Use Cases + +- Debug transaction execution and identify issues +- Analyze contract bitcode without source code +- Learn TVM internals through interactive exploration +- Verify contract behavior through decompilation + +Choose the tool that best fits your debugging or analysis needs. diff --git a/tvm/tools/retracer.mdx b/tvm/tools/retracer.mdx new file mode 100644 index 00000000..86887564 --- /dev/null +++ b/tvm/tools/retracer.mdx @@ -0,0 +1,29 @@ +--- +title: "Retracer" +sidebarTitle: "Retracer" +--- + +[Retracer](https://retracer.ton.org/) is a classic TVM transaction tracing tool that provides detailed inspection of transaction execution. + +## What it shows + +- **Action list (C5)** — Complete details of all actions performed during the transaction +- **TVM stack trace** — Step-by-step stack changes during instruction execution +- **Transaction details** — Sender, contract, amounts, time, LT, fees, and balances +- **Executor logs** — Detailed logs for deeper debugging + +## Use cases + +- **Action inspection** — Examine C5 to understand message modes and balance reservations +- **Error pinpointing** — Follow instruction traces and stack changes to locate issues +- **Debugging** — Check executor logs for detailed debugging and issue reporting + +## Technical details + +Retracer provides low-level insights into TVM execution, making it essential for: + +- Understanding complex transaction flows +- Debugging smart contract behavior +- Analyzing gas usage and performance + +Source code: [tvm-web-viewer](https://github.com/ton-blockchain/tvm-web-viewer/) diff --git a/tvm/tools/ton-decompiler.mdx b/tvm/tools/ton-decompiler.mdx new file mode 100644 index 00000000..44c2c846 --- /dev/null +++ b/tvm/tools/ton-decompiler.mdx @@ -0,0 +1,91 @@ +--- +title: "Ton Decompiler" +sidebarTitle: "Ton Decompiler" +--- + +[**Ton Decompiler**](https://github.com/tact-lang/ton-opcode) is a powerful utility for analyzing and reverse-engineering smart contracts deployed on The Open Network (TON). It transforms compiled TVM bytecode (represented as a `Cell`) back into human-readable pseudocode resembling **Func/Fift**, greatly simplifying contract auditing, verification, and comprehension. + +## Features + +- **Decompiles TVM bytecode** into structured pseudocode +- Supports complex constructs: dictionaries, global variables, built-in functions, hashes, signatures, and more +- Recovers procedures and methods by their hashes (`?fun_ref_xxx`) +- Integrates with `@ton/core`, `@ton-community/func-js`, and `@scaleton/func-debug-symbols` +- End-to-end testing via **Vitest** with round-trip compilation/decompilation validation +- Generates code hashes for verification (used in Tact contract tests) + +## Testing and verification + +The tool is extensively tested against a wide range of contracts: + +- **Tact contracts**: Jetton, NFT, Vesting, Lottery, SkatePassport, and more +- **Func contracts**: `jetton-minter.fc`, `nft-collection.fc`, `wallet v3/v4`, `stdlib.fc`, `mathlib.fc` +- Supports contracts compiled via **Func**, **Tact**, and **Fift** + +Each test validates: + +- Correctness of decompilation output +- Re-compilability via Fift +- Hash stability (`exports[...] = "..."` in test snapshots) + +## Architecture + +### Core modules + +- **`disasm`** — TVM instruction disassembler +- **`AssemblyWriter`** — generates readable assembly with configurable options: + - Instruction aliases (e.g., `SWAP` instead of `s0 s1 XCHG`) + - Inline hex comments (e.g., `// 0xD0`) + - Resolution of procedure and method names +- **`utils/known-methods`** — registry of known method IDs and debug symbols +- **`e2e/utils`** — utilities for compilation and result comparison + +### Supported TVM instructions + +- Arithmetic (`DIVMOD`, `LSHIFT`, `MULRSHIFTR#`, and more) +- Dictionary operations (`DICTGET`, `DICTSETB`, `DICTDEL`, `DICTUREMMIN`, and more) +- Stack manipulation (`XCHG`, `PUXC`, `BLKSWAP`) +- Control flow (`IFELSE`, `WHILE`, `CALLREF`, `INLINECALLDICT`) +- Cell and slice handling (`CTOS`, `STREF`, `LDREF`, `STSLICECONST`) + +## Installation and usage + +```bash +npm install @tact-lang/ton-decompiler +# or clone the repository +git clone https://github.com/tact-lang/ton-decompiler.git +``` + +### Example usage + +```ts +import { Cell } from "@ton/core"; +import { disassembleRoot } from "./decompiler/disasm"; +import { AssemblyWriter } from "./printer/assembly-writer"; + +const cell: Cell = ...; // your TVM contract bytecode +const program = disassembleRoot(cell); +const writer = new AssemblyWriter(); +const code = writer.write(program); +console.log(code); +``` + +## For developers + +- **Tests**: Run with `vitest`; cover hundreds of real-world contracts +- **Specification generation**: `npm run gen-spec` +- **Linting**: `eslint` with modern rules +- **Compatibility**: Integrates with `@tact-lang/compiler` and `tact-template` + +## License + +This project is licensed under the **MIT License** — free to use, modify, and distribute. + +## Why use it? + +- **Security auditing**: Analyze third-party contracts without source code +- **Reverse engineering**: Understand the logic of closed-source contracts +- **Education**: Learn TVM internals and low-level TON contract behavior +- **IDE integration**: Enable decompilation features in development tools + +> **Note**: Decompiled code may not exactly match the original source — variable names and high-level structure can differ — but semantic equivalence is preserved. diff --git a/tvm/tools/tvm-explorer.mdx b/tvm/tools/tvm-explorer.mdx new file mode 100644 index 00000000..46b4b31f --- /dev/null +++ b/tvm/tools/tvm-explorer.mdx @@ -0,0 +1,22 @@ +--- +title: "TVM Explorer" +sidebarTitle: "TVM Explorer" +--- + +[TVM Explorer](https://tvm-explorer.netlify.app/) is an interactive tool for exploring TVM bytecode and instructions.\ +Use it to see how your [Fift](/language/fift) code compiles to TVM bytecode. + +![TVM Explorer interface](/resources/images/tvmexplorer.png) + +## What it does + +- **Interactive exploration** — Examine TVM bytecode and understand instruction behavior +- **Compilation visualization** — See how high-level code translates to TVM instructions +- **Learning tool** — Understand TVM internals through hands-on exploration + +## Use cases + +- Learn how different code patterns compile to TVM bytecode +- Debug compilation issues by examining bytecode +- Understand TVM instruction behavior +- Educational tool for TVM architecture diff --git a/tvm/tools/txtracer.mdx b/tvm/tools/txtracer.mdx new file mode 100644 index 00000000..031e2314 --- /dev/null +++ b/tvm/tools/txtracer.mdx @@ -0,0 +1,25 @@ +--- +title: "TxTracer" +sidebarTitle: "TxTracer" +--- + +[TxTracer](https://txtracer.ton.org/) is a modern TVM transaction tracing tool that combines multiple debugging and analysis features in one interface. + +## Features + +![TxTracer screenshot](/resources/images/txtracer.png) + +1. Tracing TVM execution with transaction details and logs +1. Interactive environment for experimenting with TVM assembly and FunC +1. Convert FunC/Tolk code to TVM assembly and explore how it is compiled +1. Built-in reference for TVM opcodes, stack effects, and control flow +1. Sandbox UI extends the standard `@ton/sandbox` with transaction tracing capabilities, allowing you to visualize and debug smart contract interactions. +1. Emulate transaction tree using your BoC message + +## Use cases + +- **Transaction tracing** — Follow execution path and stack changes end-to-end +- **Assembly experimentation** — Test and compile code, inspect VM behavior in real-time +- **Instruction lookup** — Find TVM instruction semantics while reading disassembly +- **Error investigation** — Debug invalid opcodes and type errors using instruction constraints +- **Debugging** — Debug smart contracts using it with sandbox