diff --git a/docs.json b/docs.json index 487a9e570..cbeeacdb7 100644 --- a/docs.json +++ b/docs.json @@ -526,6 +526,7 @@ "foundations/status", "foundations/phases", "foundations/fees", + "foundations/traces", "foundations/shards", "foundations/limits", "foundations/config", diff --git a/foundations/traces.mdx b/foundations/traces.mdx new file mode 100644 index 000000000..425339c6c --- /dev/null +++ b/foundations/traces.mdx @@ -0,0 +1,63 @@ +--- +title: "Traces" +--- + +import { Image } from '/snippets/image.jsx'; + +A trace is a partially ordered set of messages. This set includes all dependent messages. In other words, if message B was sent while message A was being processed, then both of these messages belong to exactly one trace. Strictly speaking, this set is partially ordered according to the causal relation “A is sent as a result of processing B.” + +When drawing a trace, messages are usually drawn on the edges, and the addresses of the accounts to which the messages are sent are drawn at the vertices. Transactions that occurred on the account at that moment in time are also usually signed at the vertex. + +### Start of the trace + +Most often, a trace begins with an [external message](/foundations/messages/external-in). It is the first one, since there is no message that could generate an external-in. However, trace may be started not only by external messages but also by [tick-tock transactions](/foundations/messages/overview#transactions), commonly used within TON Blockchain [system contracts](/foundations/system). Traces can also start with split and merge transactions, but since they are not currently implemented, this will not occur in a real network. + +
+ Trace diagram +
+ +As a result, messages in the trace are partially 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. It is important to note that in the network in general, lt is formed as follows: + +- lt transactions = lt incoming message + 1 +- lt outgoing message = lt transaction + outgoing message index + This scheme is not applicable to the first vertex if the trace is started by special transactions mentioned above, as in that case there is no `incoming message` for the first vertex. + +Traces with logical time + +## Traces representation 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. + +## Examples + +The NFT transfer illustrates a single operation that consists of multiple messages. To learn how to read traces, follow [this article](/ecosystem/explorers/tonviewer#steps-to-read-a-trace). + +This trace is started with an external message and can be inspected in [Tonviewer](https://tonviewer.com/transaction/47d0989633fc03ff3fdca05880ab5760d0321c196501a6a4cbb5578dea2624cb) + +NFT transfer trace + +Here is the [example](https://tonviewer.com/transaction/9effb91e18be732033fe6aa8c39941f26f5e9566848bc487aa7c6bfecdd9d89d) of the trace that started with tick-tock transaction + +Trace initiated by tick-tock transaction + +## Access using API + +To fetch traces data, use the [`GET /traces`](/ecosystem/api/toncenter/v3/actions-and-traces/list-actions-by-filters-tx-msg-trace) endpoint. This method allows finding a trace if any of its parameters are known. 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/tick_tock_initiated_trace_dark.png b/resources/images/rpc/tick_tock_initiated_trace_dark.png new file mode 100644 index 000000000..f8ecfc687 Binary files /dev/null and b/resources/images/rpc/tick_tock_initiated_trace_dark.png differ diff --git a/resources/images/rpc/tick_tock_initiated_trace_light.png b/resources/images/rpc/tick_tock_initiated_trace_light.png new file mode 100644 index 000000000..63cb13bd2 Binary files /dev/null and b/resources/images/rpc/tick_tock_initiated_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..256d5b8c8 --- /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..e665435a8 --- /dev/null +++ b/resources/images/rpc/traces_lt_light.svg @@ -0,0 +1 @@ + \ No newline at end of file