diff --git a/docs.json b/docs.json index 1339614f..a5df8962 100644 --- a/docs.json +++ b/docs.json @@ -224,6 +224,7 @@ "group": "RPC providers", "pages": [ "ecosystem/rpc/overview", + "ecosystem/rpc/traces", { "group": "TON Center", "pages": [ diff --git a/ecosystem/rpc/traces.mdx b/ecosystem/rpc/traces.mdx new file mode 100644 index 00000000..7d80fef1 --- /dev/null +++ b/ecosystem/rpc/traces.mdx @@ -0,0 +1,55 @@ +--- +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)](/ton/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)**, 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 offer **a high-level** view of an operation, illustrating how multiple transactions and messages interact to produce the final result. Within the graph, related transactions are grouped into human-readable actions, _providing developers with both the low-level transaction flow and the corresponding higher-level operations_. + +**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 + +## High-level access using API + +To fetch transaction data, use the high-level [`GET /traces`](/api-reference/actions/get-traces) endpoint. +This method allows you to retrieve all related transactions for a given operation, without parsing individual transactions. + 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 00000000..8cbab6f4 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 00000000..49929611 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 00000000..bf322b3e --- /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 00000000..accaac2b --- /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 00000000..043935a6 --- /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 00000000..446841bd --- /dev/null +++ b/resources/images/rpc/traces_lt_light.svg @@ -0,0 +1 @@ + \ No newline at end of file