traces

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"
     }
   ]
-}
+}

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_.
+
+<div
+  className="flex justify-center my-4"
+>
+  <Image
+    src="/resources/images/rpc/trace_def_light.svg"
+    darkSrc="/resources/images/rpc/trace_def_dark.svg"
+    alt="Trace diagram"
+  />
+</div>
+
+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.
+
+<Image
+  src="/resources/images/rpc/traces_lt_light.svg"
+  darkSrc="/resources/images/rpc/traces_lt_dark.svg"
+  alt="Traces with logical time"
+/>
+
+<Aside
+  type={"note"}
+>
+  Transactions may be triggered not only by external messages but also by [tick-tock](/foundations/whitepapers/tblkch#4-2-4-kinds-of-transactions) events, commonly used within internal TON Blockchain contracts, such as governance or elector contracts.
+
+  **Example:** [Tick-tock initiated trace](https://tonviewer.com/transaction/c386d3f7cc797aeb4d126a17da9055e47e79a1bce73262e8d665d94636f97bdc).
+</Aside>
+
+## 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).
+
+<Image
+  src="/resources/images/rpc/nft_transfer_trace_light.png"
+  darkSrc="/resources/images/rpc/nft_transfer_trace_dark.png"
+  alt="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.