TVM tooling page

docs.json

@@ -404,6 +404,16 @@
         "group": "TVM: TON Virtual Machine",
         "pages": [
           "tvm/overview",
+          {
+            "group": "Tools",
+            "pages": [
+              "tvm/tools/index",
+              "tvm/tools/tx-tracer",
+              "tvm/tools/retracer",
+              "tvm/tools/tvm-explorer",
+              "tvm/tools/ton-decompiler"
+            ]
+          },
           {
             "group": "Serialization",
             "pages": [

extra.js

@@ -1,3 +1,5 @@
 /* See: https://mintlify.com/docs/settings/custom-scripts#custom-javascript */
 
 /* TODO: try to add a heading outline on mobile similar to one Astro provides */
+
+/* TODO: make sidebar group headers open their index page when clicked. */

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.

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/)

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.

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

tvm/tools/tx-tracer.mdx

@@ -0,0 +1,25 @@
+---
+title: "TxTracer"
+sidebarTitle: "TxTracer"
+---
+
+TxTracer is a modern TVM transaction tracing tool that combines multiple debugging and analysis features in one interface.
+
+## Features
+
+- **Retracer-style tracing** — End-to-end transaction tracing similar to Retracer
+- **Assembly playground** — Interactive environment for experimenting with TVM assembly
+- **Code explorer** — Convert FunC/Tolk code to TVM code and explore the results
+- **TVM specification** — Built-in reference for opcodes, stack effects, and control flow
+- **Sandbox visualization** — Visual representation of TVM execution
+
+## Use cases
+
+- **Instruction lookup** — Find TVM instruction semantics while reading disassembly
+- **Error investigation** — Debug invalid opcodes and type errors using instruction constraints
+- **Transaction tracing** — Follow execution path and stack changes end-to-end
+- **Assembly experimentation** — Test and compile code, inspect VM logs from local tests
+
+## Getting started
+
+Access TxTracer through its web interface to start exploring TVM execution and debugging transactions.