diff --git a/docs.json b/docs.json index 6b5c28223..dacfb4593 100644 --- a/docs.json +++ b/docs.json @@ -514,6 +514,7 @@ "foundations/status", "foundations/phases", "foundations/fees", + "foundations/traces", "foundations/shards", "foundations/limits", "foundations/config", @@ -1680,4 +1681,4 @@ "destination": "/contribute" } ] -} \ No newline at end of file +} diff --git a/foundations/traces.mdx b/foundations/traces.mdx new file mode 100644 index 000000000..bd937d7e6 --- /dev/null +++ b/foundations/traces.mdx @@ -0,0 +1,59 @@ +--- +title: "Traces" +--- + +import { Aside } from "/snippets/aside.jsx"; +import { Image } from '/snippets/image.jsx'; + +A trace is a set of messages and transactions produced by a single external message. + +Each _i-th_ transaction in the trace is triggered by a message sent during the action phase of some earlier _j-th_ transaction, where _j \< i_. + +
+ Trace diagram +
+ +All messages and transactions in the trace are ordered by their [logical time (lt)](/foundations/whitepapers/tblkch#1-4-1-logical-time), reflecting their logical dependencies. The diagram shows transactions on independent accounts, each triggered by an incoming message, with `lt` values indicated for every message. + +Traces with logical time + + + +## Using traces in Tonviewer + +In [Tonviewer](https://tonviewer.com/), traces are visualized as [directed acyclic graphs (DAGs)](https://en.wikipedia.org/wiki/Directed_acyclic_graph), where _transactions are nodes_ and _messages are edges_, showing the full sequence of account state changes triggered by a single external message. + +### Tracing operations + +Traces show the execution flow of an operation, such as a Jetton or NFT transfer, illustrating how transactions and messages connect to produce the final result. Each trace is an automatically generated tree of related transactions derived from message propagation. + +**Example** + +The NFT transfer illustrates a single operation that consists of **three transactions**, each triggered by messages. To learn how to read traces, follow [this article](/ecosystem/explorers/tonviewer#steps-to-analyze-an-operation). + +NFT transfer trace + +## Access using API + +To fetch transaction data, use the [`GET /traces`](/ecosystem/api/toncenter/v3/actions-and-traces/list-actions-by-filters-tx-msg-trace) endpoint. +This method returns all transactions related to a given operation without requiring individual parsing. diff --git a/resources/images/rpc/nft_transfer_trace_dark.png b/resources/images/rpc/nft_transfer_trace_dark.png new file mode 100644 index 000000000..8cbab6f41 Binary files /dev/null and b/resources/images/rpc/nft_transfer_trace_dark.png differ diff --git a/resources/images/rpc/nft_transfer_trace_light.png b/resources/images/rpc/nft_transfer_trace_light.png new file mode 100644 index 000000000..499296116 Binary files /dev/null and b/resources/images/rpc/nft_transfer_trace_light.png differ diff --git a/resources/images/rpc/trace_def_dark.svg b/resources/images/rpc/trace_def_dark.svg new file mode 100644 index 000000000..c325d129a --- /dev/null +++ b/resources/images/rpc/trace_def_dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/resources/images/rpc/trace_def_light.svg b/resources/images/rpc/trace_def_light.svg new file mode 100644 index 000000000..13bda340d --- /dev/null +++ b/resources/images/rpc/trace_def_light.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/resources/images/rpc/traces_lt_dark.svg b/resources/images/rpc/traces_lt_dark.svg new file mode 100644 index 000000000..043935a6e --- /dev/null +++ b/resources/images/rpc/traces_lt_dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/resources/images/rpc/traces_lt_light.svg b/resources/images/rpc/traces_lt_light.svg new file mode 100644 index 000000000..446841bdc --- /dev/null +++ b/resources/images/rpc/traces_lt_light.svg @@ -0,0 +1 @@ + \ No newline at end of file