TVM tooling page #509

memearchivarius · 2025-09-29T19:28:39Z

Closes #343

Added brief descriptions for related links

anton-trunov · 2025-09-30T09:15:48Z

/review

anton-trunov · 2025-09-30T09:33:05Z

tvm/tools.mdx

+### More tools
+
+- [tvm-web-viewer](https://github.com/ton-blockchain/tvm-web-viewer/) — source code for Retracer
+- [TVM Explorer](https://tvm-explorer.netlify.app/) — interactive explorer for TVM bytecode and instructions; check how your code compiles to TVM bytecode


Suggested change

- [TVM Explorer](https://tvm-explorer.netlify.app/) — interactive explorer for TVM bytecode and instructions; check how your code compiles to TVM bytecode

- [TVM Explorer](https://tvm-explorer.netlify.app/) — interactive explorer for TVM bitcode and instructions; check how your code compiles to TVM code

anton-trunov · 2025-09-30T09:33:15Z

tvm/tools.mdx

+
+- [tvm-web-viewer](https://github.com/ton-blockchain/tvm-web-viewer/) — source code for Retracer
+- [TVM Explorer](https://tvm-explorer.netlify.app/) — interactive explorer for TVM bytecode and instructions; check how your code compiles to TVM bytecode
+- [tact-lang/ton-opcode](https://github.com/tact-lang/ton-opcode) — decompiler from TVM bytecode to Fift assembly


Suggested change

- [tact-lang/ton-opcode](https://github.com/tact-lang/ton-opcode) — decompiler from TVM bytecode to Fift assembly

- [tact-lang/ton-opcode](https://github.com/tact-lang/ton-opcode) — decompiler from TVM bitcode to Fift assembly

anton-trunov · 2025-09-30T09:33:27Z

tvm/tools.mdx

+- [TVM exit codes](/tvm/exit-codes)
+- [TVM instructions](/tvm/instructions)
+
+


Suggested change

anton-trunov · 2025-09-30T09:33:49Z

tvm/tools.mdx

+
+This page lists essential tools for inspecting TVM (TON Virtual Machine) execution, transactions, and opcodes.
+
+### Retracer


let's add retracer to the dictionary

github-actions · 2025-09-30T09:35:06Z

Thanks for the update to tvm/tools.mdx. A couple of medium issues and several low-severity polish edits need attention to align with the style guide.

Findings (8)

Medium (2)

Click to expand

[MEDIUM] Acronym introduced before expansion in H2

Location:

mintlify-ton-docs/tvm/tools.mdx

Line 8 in 3a5e499

## TVM debugging and tracing tools

Description:
The first occurrence of “TVM” is in the H2 and appears without expansion. The style guide requires spelling out the term on first mention, followed by the acronym (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L124-L129). Expanding here aids clarity for readers scanning headings.

Suggestion:

-## TVM debugging and tracing tools
+## TON Virtual Machine (TVM) debugging and tracing tools

[MEDIUM] Throat-clearing opener and reversed acronym

Location:

mintlify-ton-docs/tvm/tools.mdx

Line 10 in 3a5e499

    
           This page lists essential tools for inspecting TVM (TON Virtual Machine) execution, transactions, and opcodes.

Description:
Line 10 opens with a throat-clearing sentence (“This page lists…”) instead of delivering value directly, which the style guide forbids (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L156-L160). It also introduces the acronym in reverse order (“TVM (TON Virtual Machine)”) instead of spelling out the term and then the acronym (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L124-L129).

Suggestion:

-This page lists essential tools for inspecting TVM (TON Virtual Machine) execution, transactions, and opcodes.
+Inspect TON Virtual Machine (TVM) execution, transactions, and opcodes with these tools.

Low (6)

Click to expand

[LOW] Inconsistent list punctuation in “Retracer” section

Location:

mintlify-ton-docs/tvm/tools.mdx

Lines 15 to 19 in 3a5e499

    
           - Purpose: Inspect the action list (C5), the TVM stack and executed instructions, basic transaction details (sender, contract, amounts, time, logical time (LT), fees, balances), and executor logs 
        
           - Typical use cases: 
        
             - Inspect C5 to see full details of performed actions (for example, message mode or balance reservation) 
        
             - Follow the instruction trace and stack changes to pinpoint errors 
        
             - Check executor logs for deeper debugging or issue reports

Description:
The “Purpose” line and the nested “Typical use cases” items are sentence-style but lack terminal periods. The style guide recommends ending full-sentence list items with periods, or omitting terminal punctuation consistently for all items (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L262-L265).

Suggestion:

- - Purpose: Inspect the action list (C5), the TVM stack and executed instructions, basic transaction details (sender, contract, amounts, time, logical time (LT), fees, balances), and executor logs
+ - Purpose: Inspect the action list (C5), the TVM stack and executed instructions, basic transaction details (sender, contract, amounts, time, logical time (LT), fees, balances), and executor logs.
@@
-   - Inspect C5 to see full details of performed actions (for example, message mode or balance reservation)
+   - Inspect C5 to see full details of performed actions (for example, message mode or balance reservation).
-   - Follow the instruction trace and stack changes to pinpoint errors
+   - Follow the instruction trace and stack changes to pinpoint errors.
-   - Check executor logs for deeper debugging or issue reports
+   - Check executor logs for deeper debugging or issue reports.

[LOW] Inconsistent list punctuation in “TxTracer” section

Location:

mintlify-ton-docs/tvm/tools.mdx

Lines 28 to 34 in 3a5e499

    
           - Purpose: Combines Retracer‑style transaction tracing with an Assembly Playground, a Code Explorer (FunC/Tolk → TVM), the TVM Specification (opcodes, stack effects, control flow, disassembly), and Sandbox visualization 
        
           - Built by: TON Studio and TON Core 
        
           - Typical use cases: 
        
             - Look up TVM instructions and semantics while reading disassembly 
        
             - Investigate invalid opcode and type errors by checking instruction constraints 
        
             - Trace transactions end‑to‑end, similar to Retracer 
        
             - Experiment with assembly, compile code, and inspect VM logs from local tests

Description:
The “Purpose” line and the nested use-case items are sentence-style but end without periods. The style guide calls for consistent punctuation for sentence-style list items (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L262-L265).

Suggestion:

- - Purpose: Combines Retracer‑style transaction tracing with an Assembly Playground, a Code Explorer (FunC/Tolk → TVM), the TVM Specification (opcodes, stack effects, control flow, disassembly), and Sandbox visualization
+ - Purpose: Combines Retracer‑style transaction tracing with an Assembly Playground, a Code Explorer (FunC/Tolk → TVM), the TVM Specification (opcodes, stack effects, control flow, disassembly), and Sandbox visualization.
@@
-   - Look up TVM instructions and semantics while reading disassembly
+   - Look up TVM instructions and semantics while reading disassembly.
-   - Investigate invalid opcode and type errors by checking instruction constraints
+   - Investigate invalid opcode and type errors by checking instruction constraints.
-   - Trace transactions end‑to‑end, similar to Retracer
+   - Trace transactions end‑to‑end, similar to Retracer.
-   - Experiment with assembly, compile code, and inspect VM logs from local tests
+   - Experiment with assembly, compile code, and inspect VM logs from local tests.

[LOW] Inconsistent list punctuation in “More tools” section

Location:

mintlify-ton-docs/tvm/tools.mdx

Lines 38 to 40 in 3a5e499

    
           - [tvm-web-viewer](https://github.com/ton-blockchain/tvm-web-viewer/) — source code for Retracer 
        
           - [TVM Explorer](https://tvm-explorer.netlify.app/) — interactive explorer for TVM bytecode and instructions; check how your code compiles to TVM bytecode 
        
           - [tact-lang/ton-opcode](https://github.com/tact-lang/ton-opcode) — decompiler from TVM bytecode to Fift assembly

Description:
Each item reads like a sentence-style description but lacks a terminal period. The style guide recommends consistent punctuation for sentence-style list items (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L262-L265).

Suggestion:

- - [tvm-web-viewer](https://github.com/ton-blockchain/tvm-web-viewer/) — source code for Retracer
+ - [tvm-web-viewer](https://github.com/ton-blockchain/tvm-web-viewer/) — source code for Retracer.
- - [TVM Explorer](https://[REDACTED]/) — interactive explorer for TVM bytecode and instructions; check how your code compiles to TVM bytecode
+ - [TVM Explorer](https://[REDACTED]/) — interactive explorer for TVM bytecode and instructions; check how your code compiles to TVM bytecode.
- - [tact-lang/ton-opcode](https://github.com/tact-lang/ton-opcode) — decompiler from TVM bytecode to Fift assembly
+ - [tact-lang/ton-opcode](https://github.com/tact-lang/ton-opcode) — decompiler from TVM bytecode to Fift assembly.

[LOW] Internal links should be relative

Location:

mintlify-ton-docs/tvm/tools.mdx

Lines 44 to 46 in 3a5e499

    
           - [TVM overview](/tvm/overview) 
        
           - [TVM exit codes](/tvm/exit-codes) 
        
           - [TVM instructions](/tvm/instructions)

Description:
Internal links use root-absolute paths (for example, “/tvm/overview”), coupling to the domain/root. The style guide recommends relative internal links for stability across domain/path changes (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L518-L518, https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L674-L675).

Suggestion:

- - [TVM overview](/tvm/overview)
- - [TVM exit codes](/tvm/exit-codes)
- - [TVM instructions](/tvm/instructions)
+ - [TVM overview](./overview)
+ - [TVM exit codes](./exit-codes)
+ - [TVM instructions](./instructions)

[LOW] Ampersand in title; prefer “and” for clarity/search

Location:

mintlify-ton-docs/tvm/tools.mdx

Line 2 in 3a5e499

title: "Debugging & tools"

Description:
The page title uses “&”. Spelling out “and” improves readability, searchability, and localization, and avoids shorthand in titles.

Suggestion:

-title: "Debugging & tools"
+title: "Debugging and tools"

[LOW] Unexpanded acronym “VM” in list item

Location:

mintlify-ton-docs/tvm/tools.mdx

Line 34 in 3a5e499

- Experiment with assembly, compile code, and inspect VM logs from local tests

Description:
“VM” appears without prior expansion and is ambiguous relative to the page’s use of “TVM.” The acronyms rule requires expansion on first use and consistent terminology thereafter (https://github.com/tact-lang/mintlify-ton-docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L124-L129). Using “TVM” keeps the term aligned with the rest of the page.

Suggestion:

-  - Experiment with assembly, compile code, and inspect VM logs from local tests
+  - Experiment with assembly, compile code, and inspect TVM logs from local tests

github-actions · 2025-10-03T14:09:49Z

To fix the formatting issues:

Install necessary dependencies: npm ci
Then, run this command:

npx remark -o --quiet --silently-ignore tvm/tools.mdx

verytactical

There should be separate pages for use of these tools, not mere mentions. These tools are not particularly user-friendly due to how technical the topic is. "Typical use cases" are the kind of topics that should be covered in these articles.
TxTracer should be mentioned above Retracer, because it's a much more modern and improved version of it.
Source code of tools (i.e. "source code of Retracer") must not be separate from the section describing the tool (i.e. "Retracer" section above)
The overview page should give similar exposure to different tools, with most useful of them juse listed first.
"Related docs" section should be removed. Obviously articles in the same group are related. Otherwise they wouldn't be in the same group.

github-actions · 2025-10-06T14:02:29Z

To fix the formatting issues:

Install necessary dependencies: npm ci
Then, run this command:

npx remark -o --quiet --silently-ignore tvm/tools/index.mdx tvm/tools/retracer.mdx tvm/tools/ton-decompiler.mdx tvm/tools/tvm-explorer.mdx tvm/tools/tx-tracer.mdx

github-actions · 2025-10-07T09:33:19Z

To fix the formatting issues:

Install necessary dependencies: npm ci
Then, run this command:

npx remark -o --silent --silently-ignore tvm/tools/overview.mdx tvm/tools/retracer.mdx tvm/tools/ton-decompiler.mdx tvm/tools/tvm-explorer.mdx tvm/tools/tx-tracer.mdx

memearchivarius · 2025-10-07T09:49:08Z

@anton-trunov @verytactical, please review the new variant.
I'm not familiar with most of the mentioned tools' functionality, so I tried my best to describe them.

verytactical · 2025-10-07T15:39:03Z

extra.js

 /* See: https://mintlify.com/docs/settings/custom-scripts#custom-javascript */

 /* TODO: try to add a heading outline on mobile similar to one Astro provides */
+


Please do not add TODOs in code. Create GH issues instead

verytactical · 2025-10-07T15:42:34Z

docs.json

+          {
+            "group": "Tools",
+            "pages": [
+              "tvm/tools/index",


Broken link

verytactical · 2025-10-07T15:45:31Z

tvm/tools/tx-tracer.mdx

+sidebarTitle: "TxTracer"
+---
+
+TxTracer is a modern TVM transaction tracing tool that combines multiple debugging and analysis features in one interface.


The whole article doesn't even link to TxTracer. How is user supposed to find it?

verytactical · 2025-10-07T15:45:41Z

tvm/tools/tx-tracer.mdx

+
+## Features
+
+- **Retracer-style tracing** — End-to-end transaction tracing similar to Retracer


Please don't use AI to produce articles.

draft

3a5e499

memearchivarius self-assigned this Sep 29, 2025

mintlify bot deployed to staging September 29, 2025 19:29 View deployment

anton-trunov reviewed Sep 30, 2025

View reviewed changes

tvm/tools.mdx Outdated

- [TVM exit codes](/tvm/exit-codes)

- [TVM instructions](/tvm/instructions)

Copy link

Member

anton-trunov Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

anton-trunov reviewed Sep 30, 2025

View reviewed changes

Merge branch 'main' into 343-tvm-tooling

be21160

verytactical requested a review from a team as a code owner October 3, 2025 14:09

mintlify bot deployed to staging October 3, 2025 14:10 View deployment

verytactical requested changes Oct 3, 2025

View reviewed changes

remake

fb66baa

mintlify bot deployed to staging October 6, 2025 14:02 View deployment

fixes

13a3f05

mintlify bot deployed to staging October 7, 2025 09:33 View deployment

remark

c172c06

mintlify bot deployed to staging October 7, 2025 09:37 View deployment

Update tx-tracer.mdx

aab5dc3

mintlify bot deployed to staging October 7, 2025 09:41 View deployment

verytactical requested changes Oct 7, 2025

View reviewed changes

hacker-volodya removed the request for review from a team October 7, 2025 18:58

	- [TVM Explorer](https://tvm-explorer.netlify.app/) — interactive explorer for TVM bytecode and instructions; check how your code compiles to TVM bytecode
	- [TVM Explorer](https://tvm-explorer.netlify.app/) — interactive explorer for TVM bitcode and instructions; check how your code compiles to TVM code

	- [tact-lang/ton-opcode](https://github.com/tact-lang/ton-opcode) — decompiler from TVM bytecode to Fift assembly
	- [tact-lang/ton-opcode](https://github.com/tact-lang/ton-opcode) — decompiler from TVM bitcode to Fift assembly

		- [TVM exit codes](/tvm/exit-codes)
		- [TVM instructions](/tvm/instructions)


		This page lists essential tools for inspecting TVM (TON Virtual Machine) execution, transactions, and opcodes.

		### Retracer

		/* See: https://mintlify.com/docs/settings/custom-scripts#custom-javascript */

		/* TODO: try to add a heading outline on mobile similar to one Astro provides */


		## Features

		- Retracer-style tracing — End-to-end transaction tracing similar to Retracer

TVM tooling page #509

Are you sure you want to change the base?

TVM tooling page #509

Uh oh!

Conversation

memearchivarius commented Sep 29, 2025

Uh oh!

anton-trunov commented Sep 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Sep 30, 2025

Findings (8)

Medium (2)

[MEDIUM] Acronym introduced before expansion in H2

[MEDIUM] Throat-clearing opener and reversed acronym

Low (6)

[LOW] Inconsistent list punctuation in “Retracer” section

[LOW] Inconsistent list punctuation in “TxTracer” section

[LOW] Inconsistent list punctuation in “More tools” section

[LOW] Internal links should be relative

[LOW] Ampersand in title; prefer “and” for clarity/search

[LOW] Unexpanded acronym “VM” in list item

Uh oh!

github-actions bot commented Oct 3, 2025

Uh oh!

verytactical left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Oct 6, 2025

Uh oh!

github-actions bot commented Oct 7, 2025

Uh oh!

memearchivarius commented Oct 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!