[NONEVM-2624] TON Trace Explorer #227

patricios-space · 2025-09-30T17:38:23Z

This pull request introduces a new TON Explorer command-line tool, adds developer and user documentation for it, and updates/adds new contract bindings. The main focus is on providing an extensible, documented explorer utility for analyzing TON blockchain message traces, with guidance for extending contract decoding support.

TON Explorer Tool and Documentation

Added a new command-line tool for exploring TON blockchain transactions and traces, including a main.go entrypoint in cmd/explorer that wires up the explorer command.
Added comprehensive user and developer guides for the TON Explorer, covering usage, build instructions, output formats, extension points for contract decoders, and best practices for decoder implementation. [1] [2]

Smart Contract Updates

Added code() and codeHash() getter functions to ccipsend_executor and bumped CONTRACT_VERSION to "0.0.4". [1] [2]

pkg/ton/debug/explorer/explorer.go

Copilot

Pull Request Overview

This PR introduces a comprehensive trace explorer for TON blockchain transactions with multiple visualization options and enhanced debugging capabilities. The changes include message decoding infrastructure, visualization frameworks, and dependency updates.

Key changes:

New trace explorer CLI tool with tree and sequence diagram visualization
Message decoding framework with support for jetton and CCIP contracts
Refactored jetton package structure with separate wallet/minter packages
Updated dependencies and removed obsolete code

Reviewed Changes

Copilot reviewed 45 out of 49 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pkg/ton/debug/explorer/explorer.go	Core explorer implementation with network connection and trace visualization
pkg/ton/debug/pretty_print.go	Message decoding and debugging framework
pkg/ton/debug/visualizations/sequence/sequence_diagram.go	Sequence diagram visualization using Mermaid
pkg/ton/debug/visualizations/tree/tree_diagram.go	Tree-based trace visualization
pkg/ton/tracetracking/message.go	Added SrcAddr/DstAddr fields to OutgoingExternalMessages
pkg/bindings/jetton/wallet/codec.go	New jetton wallet message codecs and structures
pkg/bindings/jetton/minter/codec.go	New jetton minter message codecs and structures
integration-tests/jetton/jetton_test.go	Updated tests to use new debugger and package structure
go.mod	Dependency updates including new visualization library
staging-messaging-test/go.mod	Dependency version updates

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

pkg/ton/debug/explorer/explorer.go

docs/.misc/dev-guides/explorer/usage.md

docs/.misc/dev-guides/explorer/development.md

docs/.misc/dev-guides/explorer/usage.md

jadepark-dev

I have some general comments.

Have you considered any mechanisms to ensure this debugger framework continues to work even when contracts or bindings are modified (e.g., debugger unit or integration tests)?
It seems that each contract binding is kept as a pure off-chain representation(good), but a “codec” file has been added. Could you explain why that's separated into individual files? In some cases, the opcodes are defined in the original files, while in others, they appear in the codec files.

cmd/explorer/main.go

jadepark-dev · 2025-10-14T16:27:40Z

pkg/ton/codec/builder.go

@@ -0,0 +1,31 @@
+package codec


It seems this file is wrapping tlb.LoadFromCell. Could you clarify why this wrapper is necessary? We should also confirm whether there’s been alignment with the team that originally developed the binding. The concept of a "codec" already exists in our system. cc. @archseer @huangzhen1997

TBH, it is not really necesary for the explorer, but I consider it makes for a more idiomatic usage, with an api similar to what we are doing in TS bindings. Still, I will remove this from this PR and put it in a separate branch so it doesn't distract from the explorer stuff.

pkg/ton/debug/decoders/ccip/ccipcommon/common.go

jadepark-dev · 2025-10-14T16:30:40Z

pkg/ton/debug/visualizations/tree/tree_diagram.go

+	return n.description + "\n" + strings.Join(n.toTreeLines(""), "\n")
+}
+
+func (n treeNode) toTreeLines(prefix string) []string {


I remember something similar in tracetracker, why do we need a duplicated implementations?

This was removed from the trace tracker. The pretty printing functionality of the trace tracker was moved to this debug pkg.

jadepark-dev · 2025-10-14T16:34:24Z

pkg/ton/debug/explorer/explorer.go

+func (c *client) tryMatchByCodeHash(ctx context.Context, block *ton.BlockIDExt, addr *address.Address, knownActors map[string]deployment.TypeAndVersion) error {
+	account, err := c.connection.GetAccount(ctx, block, addr)
+	if err != nil {
+		return fmt.Errorf("get account: %w", err)
+	}
+	code := account.Code.ToBOC()
+	codeHex := hex.EncodeToString(code)
+	switch codeHex {
+	case "b5ee9c7241021001000228000114ff00f4a413f4bcf2c80b01020120020d02014803040078d020d74bc00101c060b0915be101d0d3030171b0915be0fa4030f828c705b39130e0d31f018210ae42e5a4ba9d8040d721d74cf82a01ed55fb04e030020120050a02027306070011adce76a2686b85ffc00201200809001aabb6ed44d0810122d721d70b3f0018aa3bed44d08307d721d70b1f0201200b0c001bb9a6eed44d0810162d721d70b15800e5b8bf2eda2edfb21ab09028409b0ed44d0810120d721f404f404d33fd315d1058e1bf82325a15210b99f326df82305aa0015a112b992306dde923033e2923033e25230800df40f6fa19ed021d721d70a00955f037fdb31e09130e259800df40f6fa19cd001d721d70a00937fdb31e0915be270801f6f2d48308d718d121f900ed44d0d3ffd31ff404f404d33fd315d1f82321a15220b98e12336df82324aa00a112b9926d32de58f82301de541675f910f2a106d0d31fd4d307d30cd309d33fd315d15168baf2a2515abaf2a6f8232aa15250bcf2a304f823bbf2a35304800df40f6fa199d024d721d70a00f2649130e20e01fe5309800df40f6fa18e13d05004d718d20001f264c858cf16cf8301cf168e1030c824cf40cf8384095005a1a514cf40e2f800c94039800df41704c8cbff13cb1ff40012f40012cb3f12cb15c9ed54f80f21d0d30001f265d3020171b0925f03e0fa4001d70b01c000f2a5fa4031fa0031f401fa0031fa00318060d721d300010f0020f265d2000193d431d19130e272b1fb00b585bf03": // https://github.com/ton-blockchain/highload-wallet-contract-v3/blob/main/build/HighloadWalletV3.compiled.json


can we externalize these codeHex?

Removing this for now as it was not working propperly.

jadepark-dev · 2025-10-14T16:37:46Z

pkg/ton/tracetracking/message.go

 // emitted by contracts to communicate with external systems.
 func (m *ReceivedMessage) AppendEvent(outMsg *tlb.ExternalMessageOut) {
-	e := OutgoingExternalMessages{outMsg.CreatedAt, outMsg.CreatedLT, outMsg.Body}
+	e := OutgoingExternalMessages{outMsg.SrcAddr, outMsg.DstAddr, outMsg.CreatedAt, outMsg.CreatedLT, outMsg.Body}


how's the external message's topic is resolved? Is it extracted inside of trace tracker vs handled outside?

It is currently handled outside in the bindings. See the onramp debug decoder for an example.

pkg/ton/debug/pretty_print.go

patricios-space force-pushed the debug/cld-trace-explorer branch from 3ecbb11 to 114c118 Compare October 1, 2025 19:29

nicolasgnr reviewed Oct 3, 2025

View reviewed changes

pkg/ton/debug/explorer/explorer.go Show resolved Hide resolved

patricios-space force-pushed the debug/cld-trace-explorer branch 2 times, most recently from 9439517 to 1f5bc38 Compare October 9, 2025 18:37

patricios-space force-pushed the debug/cld-trace-explorer branch from e305b02 to a3b4789 Compare October 13, 2025 15:00

patricios-space marked this pull request as ready for review October 13, 2025 19:35

patricios-space requested a review from a team as a code owner October 13, 2025 19:35

Copilot AI review requested due to automatic review settings October 13, 2025 19:35

product-security-plaid-production bot requested a review from toblich October 13, 2025 19:35

Copilot AI reviewed Oct 13, 2025

View reviewed changes

patricios-space changed the title ~~cld trace explorer~~ [NONEVM-2624] TON Trace Explorer Oct 13, 2025

jadepark-dev reviewed Oct 14, 2025

View reviewed changes

patricios-space mentioned this pull request Oct 14, 2025

wip: contract type deduction by code matching #245

Draft

patricios-space added 17 commits October 14, 2025 19:48

squash: ton explorer

3c4e74f

fix: update mod

8a6dc1f

fix: update mod

b88c276

doc: explaing builder interface

a68f423

fix: bump nix sha

a7b1485

ref: paging

82e927e

ref: paging

8f54da1

feat: extend with toncenter

884a175

ref: rm extra context

18dd90d

feat: query contract type

eaa7ccb

wip: match wallet code

b979934

feat: decoding ccipmessagesent

500adad

fix: onramp opcodes

a818fc7

fix: gomods tidy after rebase

ec002ed

fix: bump nix hash

796268f

fix: bump contract version

9d7c1e7

fix: golint

b5fdd34

patricios-space added 25 commits October 14, 2025 19:49

feat: expose generate cmd

e7b4b7c

feat: admint actor map in command

c31306a

test

1677c00

fix: missing lggr

7439210

debug

5bf3b79

debug

43bbf0f

debug

2cd3a43

fix: format output

f3c7234

fix: nix hash

34f7d9c

fix: url encoding

7be59f3

feat: mylocalton port scan

5e38d59

doc: usage and development guies

d51b3f8

doc:development guies

dcf41e0

fix: bump nix hash

b474d02

fix: golint

25043dc

fix: typos

53fda9a

feat: mylocalton explorer url support

c02d050

feat: dash padding only for sequence diagram

b505cd3

fix: golint

0c52c35

fix: explorer

bc8e48f

fix: explorer

d0a03dd

chore: remove codec from this pr

45145f8

fix: rm panic

7fb341a

fix: rm commented code

9c41962

chore: codehash matching not working properly

7bf0bb4

patricios-space force-pushed the debug/cld-trace-explorer branch from 8b6c2d5 to 7bf0bb4 Compare October 14, 2025 22:50

patricios-space added 4 commits October 14, 2025 19:57

fix: golint

17ea622

fix: gomods tidy

cb0bea6

fix: missing error handling

1eeb5b7

fix: bump nix

44603b8

[NONEVM-2624] TON Trace Explorer #227

Are you sure you want to change the base?

[NONEVM-2624] TON Trace Explorer #227

Uh oh!

Conversation

patricios-space commented Sep 30, 2025 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jadepark-dev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

patricios-space commented Sep 30, 2025 •

edited by atlassian bot

Loading