From 6ac937ffea022fdd3e97f70e020f562e39e10fd0 Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Tue, 18 Nov 2025 23:46:33 +0300 Subject: [PATCH 01/13] transaction overview demo --- docs.json | 1 + foundations/messages/ordinary-tx.mdx | 29 ++++++++++++--- foundations/messages/overview.mdx | 2 +- foundations/messages/transaction-overview.mdx | 35 +++++++++++++++++++ 4 files changed, 62 insertions(+), 5 deletions(-) create mode 100644 foundations/messages/transaction-overview.mdx diff --git a/docs.json b/docs.json index 5c2ef6fa8..135c0cd1e 100644 --- a/docs.json +++ b/docs.json @@ -546,6 +546,7 @@ "group": "Messages & Transactions", "pages": [ "foundations/messages/overview", + "foundations/messages/transaction-overview", "foundations/messages/internal", "foundations/messages/external-in", "foundations/messages/external-out", diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index 610ae090c..92ed8664b 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -2,8 +2,29 @@ title: "Ordinary transactions" --- -import { Stub } from '/snippets/stub.jsx'; +Ordinary [transactions](/foundations/messages/transaction-overview) are the most common type of transaction as they occur as the result of processing [incoming external](/foundations/messages/external-in) and [internal](/foundations/messages/internal) messages. More specifically, they may occur only as the result of processing such messages. The phases of transaction are described in detail in the [dedicated page](/foundations/phases). - +Contents of the ordinary transaction are as follows: +```tl-b +trans_ord$0000 + credit_first:Bool + storage_ph:(Maybe TrStoragePhase) + credit_ph:(Maybe TrCreditPhase) + compute_ph:TrComputePhase + action:(Maybe ^TrActionPhase) + aborted:Bool + bounce:(Maybe TrBouncePhase) + destroyed:Bool + = TransactionDescr; +``` + +Ordinary transactions have specific fields: + +- `credit_first` indicates whether the transaction started with a credit phase, or with a storage phase. This flag is equal to `bounce` flag of the message that triggered the transaction. Equal to `true` if the transaction was triggered by an incoming external message. +- `storage_ph` indicates the result of the storage phase: the number of storage fees collected and the possible state change of the contract. This field is never equal to `Nothing` in the current implementation. +- `credit_ph` indicates the result of the credit phase: the number of credits collected and the possible state change of the contract. This field is equal to `Nothing` if the transaction was triggered by an incoming external message. +- `compute_ph` holds the result of TVM execution on the contract. If this phase is skipped for some reason e.g., no funds, or no state on a destination account, then this field will contain the skip reason. +- `action_ph` holds the result of the action phase. This field will be equal to `Nothing` if compute phase failed, and will not be `Nothing` otherwise. +- `aborted` is the flag that represents, whether the action phase was successful or not. +- `bounce` holds the result of the bounce phase, equal to `Nothing` if there was no bounce phase. +- `destroyed` indicates, whether the account was deleted in the action phase by using [`SendDestroyIfZero`](/foundations/messages/modes). If the contract was deleted in the action phase, this flag is equal to `false`. diff --git a/foundations/messages/overview.mdx b/foundations/messages/overview.mdx index d1f991c49..31457570c 100644 --- a/foundations/messages/overview.mdx +++ b/foundations/messages/overview.mdx @@ -16,7 +16,7 @@ message$_ ``` - `init` is an optional field of [`StateInit`](/foundations/messages/deploy) type used to initialize the contract state, stored either in-place or in a ref of the cell with a message. -- `body` is the actual message content that can be stored either in-place or in a reference. Typically it is the payload of the message that will be read by the receiver. +- `body` is the actual message content that can be stored either in-place or in a reference. Typically, it is the payload of the message that will be read by the receiver. - `info` describes the type of the message, and fields specific to messages of this type: - [Internal messages](/foundations/messages/internal) are messages from one contract to another. - [Incoming external](/foundations/messages/external-in) messages are messages from the outside world to the contract. diff --git a/foundations/messages/transaction-overview.mdx b/foundations/messages/transaction-overview.mdx new file mode 100644 index 000000000..81d5ef9e3 --- /dev/null +++ b/foundations/messages/transaction-overview.mdx @@ -0,0 +1,35 @@ +--- +title: "Transactions overview" +--- + +A transaction is a record that stores the state changes of a contract. A contract's state cannot be changed without a transaction. Transaction is the structure of the following type: + +```tl-b + transaction$0111 + account_addr:bits256 + lt:uint64 + prev_trans_hash:bits256 + prev_trans_lt:uint64 + now:uint32 + outmsg_cnt:uint15 + orig_status:AccountStatus + end_status:AccountStatus + ^[ + in_msg:(Maybe ^(Message Any)) + out_msgs:(HashmapE 15 ^(Message Any)) + ] + total_fees:CurrencyCollection + state_update:^(HASH_UPDATE Account) + description:^TransactionDescr += Transaction; +``` + +Transactions reflect the concept of `AccountChain` described in the [TON Blockchain whitepaper](/foundations/whitepapers/tblkch#1-2-1-the-infinite-sharding-paradigm-isp-applied-to-blockchain-block-and-state). Each account state can be interpreted as a state of a separate blockchain. So transactions have a very specific order, which is defined by the `prev_trans_hash` field. Thanks to consensus of TON blockchain, transactions get finalized with the fist masterchain block that references them, by storing the hash of `ShardChain` state, that stores the hash of `AccountChain` state. + +As transactions form `AccountChain`, each transaction has a logical timestamp, `lt`, that is strictly increasing with each new transaction of the account. The `now` field stores the unix time of the moment when the transaction was created. + +The other interesting field is `state_update`, which is a [Merkle update](/foundations/serialization/merkle-update), that stores the difference between the previous and the current state of the account. The information about [contract status](/foundations/status) before and after the transaction is duplicated, for convenience. + +Other fields, such as `in_msg`, `out_msg` and `outmsg_cnt`, are related to the [messages](/foundations/messages/overview) processed and spawned during the transaction. The interesting fact is that the [trace](/foundations/trace) may be initiated by a transaction, not by a message. In this case, the `in_msg` field will be `Nothing`. However, the trace can't continue without a message. Strictly speaking, if the trace contains `n` transactions then it contains at least `n-1` messages. As a result, the trace can't hold more than one non-ordinary transaction, as messages may result only in an [ordinary transaction](/foundations/messages/ordinary-tx). + +The `total_fees` field stores the total number of [fees](/foundations/fees) paid by the transaction. What is interesting here is that the fees can possibly be paid in extra-currency, but this is not implemented feature yet. From 527118149ba683172842c42aea31e1ebb2a8eb27 Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Wed, 19 Nov 2025 01:13:57 +0300 Subject: [PATCH 02/13] fix by codex --- foundations/messages/ordinary-tx.mdx | 22 +++++++++---------- foundations/messages/transaction-overview.mdx | 12 +++++----- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index 92ed8664b..1b65c0584 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -2,9 +2,9 @@ title: "Ordinary transactions" --- -Ordinary [transactions](/foundations/messages/transaction-overview) are the most common type of transaction as they occur as the result of processing [incoming external](/foundations/messages/external-in) and [internal](/foundations/messages/internal) messages. More specifically, they may occur only as the result of processing such messages. The phases of transaction are described in detail in the [dedicated page](/foundations/phases). +Ordinary [transactions](/foundations/messages/transaction-overview) are the most common type of transaction because they result from processing [incoming external](/foundations/messages/external-in) and [internal](/foundations/messages/internal) messages. They can be produced only while processing such messages. The phases of a transaction are described in detail on the [dedicated page](/foundations/phases). -Contents of the ordinary transaction are as follows: +The structure of an ordinary transaction is as follows: ```tl-b trans_ord$0000 credit_first:Bool @@ -18,13 +18,13 @@ trans_ord$0000 = TransactionDescr; ``` -Ordinary transactions have specific fields: +The fields of an ordinary transaction are: -- `credit_first` indicates whether the transaction started with a credit phase, or with a storage phase. This flag is equal to `bounce` flag of the message that triggered the transaction. Equal to `true` if the transaction was triggered by an incoming external message. -- `storage_ph` indicates the result of the storage phase: the number of storage fees collected and the possible state change of the contract. This field is never equal to `Nothing` in the current implementation. -- `credit_ph` indicates the result of the credit phase: the number of credits collected and the possible state change of the contract. This field is equal to `Nothing` if the transaction was triggered by an incoming external message. -- `compute_ph` holds the result of TVM execution on the contract. If this phase is skipped for some reason e.g., no funds, or no state on a destination account, then this field will contain the skip reason. -- `action_ph` holds the result of the action phase. This field will be equal to `Nothing` if compute phase failed, and will not be `Nothing` otherwise. -- `aborted` is the flag that represents, whether the action phase was successful or not. -- `bounce` holds the result of the bounce phase, equal to `Nothing` if there was no bounce phase. -- `destroyed` indicates, whether the account was deleted in the action phase by using [`SendDestroyIfZero`](/foundations/messages/modes). If the contract was deleted in the action phase, this flag is equal to `false`. +- `credit_first` indicates whether the transaction started with the credit phase or the storage phase. This flag matches the `bounce` flag of the message that triggered the transaction and is `true` for incoming external messages. +- `storage_ph` indicates the result of the storage phase: the number of storage fees collected and any resulting contract state change. This field is never equal to `Nothing` in the current implementation. +- `credit_ph` indicates the result of the credit phase: the number of credits collected and the state update of the contract, if any. This field is `Nothing` when the transaction was triggered by an incoming external message. +- `compute_ph` holds the result of TVM execution on the contract. If this phase is skipped, for example because there are no funds or no state on the destination account, the field stores the skip reason instead. +- `action` holds the result of the action phase. This field is `Nothing` if the compute phase failed and is populated otherwise. +- `aborted` indicates whether the action phase was successful. +- `bounce` holds the result of the bounce phase and is `Nothing` if the bounce phase was not executed. +- `destroyed` indicates whether the account was deleted in the action phase by using [`SendDestroyIfZero`](/foundations/messages/modes). If the contract was deleted in the action phase, this flag is `true`. diff --git a/foundations/messages/transaction-overview.mdx b/foundations/messages/transaction-overview.mdx index 81d5ef9e3..3dc0b1d96 100644 --- a/foundations/messages/transaction-overview.mdx +++ b/foundations/messages/transaction-overview.mdx @@ -2,7 +2,7 @@ title: "Transactions overview" --- -A transaction is a record that stores the state changes of a contract. A contract's state cannot be changed without a transaction. Transaction is the structure of the following type: +A transaction is a record that stores every state change of a contract. A contract's state cannot be changed without a transaction. Each transaction has the following structure: ```tl-b transaction$0111 @@ -24,12 +24,12 @@ A transaction is a record that stores the state changes of a contract. A contrac = Transaction; ``` -Transactions reflect the concept of `AccountChain` described in the [TON Blockchain whitepaper](/foundations/whitepapers/tblkch#1-2-1-the-infinite-sharding-paradigm-isp-applied-to-blockchain-block-and-state). Each account state can be interpreted as a state of a separate blockchain. So transactions have a very specific order, which is defined by the `prev_trans_hash` field. Thanks to consensus of TON blockchain, transactions get finalized with the fist masterchain block that references them, by storing the hash of `ShardChain` state, that stores the hash of `AccountChain` state. +Transactions implement the concept of `AccountChain` described in the [TON Blockchain whitepaper](/foundations/whitepapers/tblkch#1-2-1-the-infinite-sharding-paradigm-isp-applied-to-blockchain-block-and-state). Each account state can be interpreted as a separate blockchain, so transactions follow a strict order defined by the `prev_trans_hash` field. Thanks to the TON consensus protocol, a transaction becomes final when the first masterchain block references it by storing the hash of the corresponding `ShardChain` state, which in turn stores the hash of the `AccountChain` state. -As transactions form `AccountChain`, each transaction has a logical timestamp, `lt`, that is strictly increasing with each new transaction of the account. The `now` field stores the unix time of the moment when the transaction was created. +Because transactions form the `AccountChain`, each one carries a logical timestamp, `lt`, that strictly increases with every new transaction of the account. The `now` field stores the Unix time when the transaction was created. -The other interesting field is `state_update`, which is a [Merkle update](/foundations/serialization/merkle-update), that stores the difference between the previous and the current state of the account. The information about [contract status](/foundations/status) before and after the transaction is duplicated, for convenience. +The `state_update` field is a [Merkle update](/foundations/serialization/merkle-update) that captures the difference between the previous and current state of the account. The [contract status](/foundations/status) before and after the transaction is duplicated for convenience. -Other fields, such as `in_msg`, `out_msg` and `outmsg_cnt`, are related to the [messages](/foundations/messages/overview) processed and spawned during the transaction. The interesting fact is that the [trace](/foundations/trace) may be initiated by a transaction, not by a message. In this case, the `in_msg` field will be `Nothing`. However, the trace can't continue without a message. Strictly speaking, if the trace contains `n` transactions then it contains at least `n-1` messages. As a result, the trace can't hold more than one non-ordinary transaction, as messages may result only in an [ordinary transaction](/foundations/messages/ordinary-tx). +Other fields, such as `in_msg`, `out_msgs`, and `outmsg_cnt`, relate to the [messages](/foundations/messages/overview) processed and emitted during the transaction. A [trace](/foundations/trace) may start from a transaction rather than a message, in which case `in_msg` is `Nothing`. However, a trace cannot continue without messages: if it contains `n` transactions it must contain at least `n-1` messages. Consequently, a trace can include at most one non-ordinary transaction, because messages can trigger only an [ordinary transaction](/foundations/messages/ordinary-tx). -The `total_fees` field stores the total number of [fees](/foundations/fees) paid by the transaction. What is interesting here is that the fees can possibly be paid in extra-currency, but this is not implemented feature yet. +The `total_fees` field stores the total number of [fees](/foundations/fees) paid by the transaction. These fees may eventually be paid in extra currencies, but that feature is not implemented yet. From 2277eb972a0dacf93d1036d1c120c4e2b4c5e648 Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Wed, 19 Nov 2025 01:15:39 +0300 Subject: [PATCH 03/13] fmt --- foundations/messages/ordinary-tx.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index 1b65c0584..5878d2ceb 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -5,6 +5,7 @@ title: "Ordinary transactions" Ordinary [transactions](/foundations/messages/transaction-overview) are the most common type of transaction because they result from processing [incoming external](/foundations/messages/external-in) and [internal](/foundations/messages/internal) messages. They can be produced only while processing such messages. The phases of a transaction are described in detail on the [dedicated page](/foundations/phases). The structure of an ordinary transaction is as follows: + ```tl-b trans_ord$0000 credit_first:Bool From 4b9c0a47decbbab681d40b0295aad0705deb59f1 Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Wed, 19 Nov 2025 01:19:10 +0300 Subject: [PATCH 04/13] added traces stub --- foundations/traces.mdx | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 foundations/traces.mdx diff --git a/foundations/traces.mdx b/foundations/traces.mdx new file mode 100644 index 000000000..084eead1d --- /dev/null +++ b/foundations/traces.mdx @@ -0,0 +1,7 @@ +--- +title: "Traces" +--- + +import { Stub } from '/snippets/stub.jsx'; + + From a9bc7ec536cb5156967bbff612f7c795cbfa8098 Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Wed, 19 Nov 2025 01:20:29 +0300 Subject: [PATCH 05/13] fix link --- foundations/messages/transaction-overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/foundations/messages/transaction-overview.mdx b/foundations/messages/transaction-overview.mdx index 3dc0b1d96..38a891578 100644 --- a/foundations/messages/transaction-overview.mdx +++ b/foundations/messages/transaction-overview.mdx @@ -30,6 +30,6 @@ Because transactions form the `AccountChain`, each one carries a logical timesta The `state_update` field is a [Merkle update](/foundations/serialization/merkle-update) that captures the difference between the previous and current state of the account. The [contract status](/foundations/status) before and after the transaction is duplicated for convenience. -Other fields, such as `in_msg`, `out_msgs`, and `outmsg_cnt`, relate to the [messages](/foundations/messages/overview) processed and emitted during the transaction. A [trace](/foundations/trace) may start from a transaction rather than a message, in which case `in_msg` is `Nothing`. However, a trace cannot continue without messages: if it contains `n` transactions it must contain at least `n-1` messages. Consequently, a trace can include at most one non-ordinary transaction, because messages can trigger only an [ordinary transaction](/foundations/messages/ordinary-tx). +Other fields, such as `in_msg`, `out_msgs`, and `outmsg_cnt`, relate to the [messages](/foundations/messages/overview) processed and emitted during the transaction. A [trace](/foundations/traces) may start from a transaction rather than a message, in which case `in_msg` is `Nothing`. However, a trace cannot continue without messages: if it contains `n` transactions it must contain at least `n-1` messages. Consequently, a trace can include at most one non-ordinary transaction, because messages can trigger only an [ordinary transaction](/foundations/messages/ordinary-tx). The `total_fees` field stores the total number of [fees](/foundations/fees) paid by the transaction. These fees may eventually be paid in extra currencies, but that feature is not implemented yet. From 94289ba06873e160db6caf2c68777d3eb2fbc8b6 Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Wed, 19 Nov 2025 01:22:18 +0300 Subject: [PATCH 06/13] fix language name --- foundations/messages/ordinary-tx.mdx | 2 +- foundations/messages/transaction-overview.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index 5878d2ceb..2d1f6efb5 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -6,7 +6,7 @@ Ordinary [transactions](/foundations/messages/transaction-overview) are the most The structure of an ordinary transaction is as follows: -```tl-b +```tlb trans_ord$0000 credit_first:Bool storage_ph:(Maybe TrStoragePhase) diff --git a/foundations/messages/transaction-overview.mdx b/foundations/messages/transaction-overview.mdx index 38a891578..3874d813a 100644 --- a/foundations/messages/transaction-overview.mdx +++ b/foundations/messages/transaction-overview.mdx @@ -4,7 +4,7 @@ title: "Transactions overview" A transaction is a record that stores every state change of a contract. A contract's state cannot be changed without a transaction. Each transaction has the following structure: -```tl-b +```tlb transaction$0111 account_addr:bits256 lt:uint64 From 357a3c11f26ea948e8d15b639d0a3ba9a2e167b5 Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Wed, 19 Nov 2025 01:22:36 +0300 Subject: [PATCH 07/13] fmt --- foundations/messages/ordinary-tx.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index 2d1f6efb5..af45ac84e 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -16,7 +16,7 @@ trans_ord$0000 aborted:Bool bounce:(Maybe TrBouncePhase) destroyed:Bool - = TransactionDescr; += TransactionDescr; ``` The fields of an ordinary transaction are: From b258c65bd9f4dee0d0cf38b4a95bf94dca12dd8e Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Wed, 19 Nov 2025 01:24:04 +0300 Subject: [PATCH 08/13] removed stub --- foundations/messages/transaction-overview.mdx | 2 +- foundations/traces.mdx | 7 ------- 2 files changed, 1 insertion(+), 8 deletions(-) delete mode 100644 foundations/traces.mdx diff --git a/foundations/messages/transaction-overview.mdx b/foundations/messages/transaction-overview.mdx index 3874d813a..6b51328c0 100644 --- a/foundations/messages/transaction-overview.mdx +++ b/foundations/messages/transaction-overview.mdx @@ -30,6 +30,6 @@ Because transactions form the `AccountChain`, each one carries a logical timesta The `state_update` field is a [Merkle update](/foundations/serialization/merkle-update) that captures the difference between the previous and current state of the account. The [contract status](/foundations/status) before and after the transaction is duplicated for convenience. -Other fields, such as `in_msg`, `out_msgs`, and `outmsg_cnt`, relate to the [messages](/foundations/messages/overview) processed and emitted during the transaction. A [trace](/foundations/traces) may start from a transaction rather than a message, in which case `in_msg` is `Nothing`. However, a trace cannot continue without messages: if it contains `n` transactions it must contain at least `n-1` messages. Consequently, a trace can include at most one non-ordinary transaction, because messages can trigger only an [ordinary transaction](/foundations/messages/ordinary-tx). +Other fields, such as `in_msg`, `out_msgs`, and `outmsg_cnt`, relate to the [messages](/foundations/messages/overview) processed and emitted during the transaction. A trace may start from a transaction rather than a message, in which case `in_msg` is `Nothing`. However, a trace cannot continue without messages: if it contains `n` transactions it must contain at least `n-1` messages. Consequently, a trace can include at most one non-ordinary transaction, because messages can trigger only an [ordinary transaction](/foundations/messages/ordinary-tx). The `total_fees` field stores the total number of [fees](/foundations/fees) paid by the transaction. These fees may eventually be paid in extra currencies, but that feature is not implemented yet. diff --git a/foundations/traces.mdx b/foundations/traces.mdx deleted file mode 100644 index 084eead1d..000000000 --- a/foundations/traces.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Traces" ---- - -import { Stub } from '/snippets/stub.jsx'; - - From 99241d080cc326f2b24081541fcced659f02bb5f Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Wed, 19 Nov 2025 01:52:35 +0300 Subject: [PATCH 09/13] ai review --- foundations/messages/ordinary-tx.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index af45ac84e..4b64c23d9 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -26,6 +26,6 @@ The fields of an ordinary transaction are: - `credit_ph` indicates the result of the credit phase: the number of credits collected and the state update of the contract, if any. This field is `Nothing` when the transaction was triggered by an incoming external message. - `compute_ph` holds the result of TVM execution on the contract. If this phase is skipped, for example because there are no funds or no state on the destination account, the field stores the skip reason instead. - `action` holds the result of the action phase. This field is `Nothing` if the compute phase failed and is populated otherwise. -- `aborted` indicates whether the action phase was successful. +- `aborted` indicates whether the action phase was unsuccessful. - `bounce` holds the result of the bounce phase and is `Nothing` if the bounce phase was not executed. - `destroyed` indicates whether the account was deleted in the action phase by using [`SendDestroyIfZero`](/foundations/messages/modes). If the contract was deleted in the action phase, this flag is `true`. From 4bca62d8c5ee0d90526ec251d6bdfcc3da3ee57c Mon Sep 17 00:00:00 2001 From: b4cksl4sh Date: Wed, 19 Nov 2025 01:52:43 +0300 Subject: [PATCH 10/13] ai review --- foundations/messages/ordinary-tx.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index 4b64c23d9..1274ed307 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -24,7 +24,7 @@ The fields of an ordinary transaction are: - `credit_first` indicates whether the transaction started with the credit phase or the storage phase. This flag matches the `bounce` flag of the message that triggered the transaction and is `true` for incoming external messages. - `storage_ph` indicates the result of the storage phase: the number of storage fees collected and any resulting contract state change. This field is never equal to `Nothing` in the current implementation. - `credit_ph` indicates the result of the credit phase: the number of credits collected and the state update of the contract, if any. This field is `Nothing` when the transaction was triggered by an incoming external message. -- `compute_ph` holds the result of TVM execution on the contract. If this phase is skipped, for example because there are no funds or no state on the destination account, the field stores the skip reason instead. +- `compute_ph` holds the result of TVM execution on the contract. If this phase is skipped, for example, because there are no funds or no state on the destination account, the field stores the skip reason instead. - `action` holds the result of the action phase. This field is `Nothing` if the compute phase failed and is populated otherwise. - `aborted` indicates whether the action phase was unsuccessful. - `bounce` holds the result of the bounce phase and is `Nothing` if the bounce phase was not executed. From 38fefe12c2b47b104e708a95ba7c479e4c3930f2 Mon Sep 17 00:00:00 2001 From: Anton Trunov Date: Wed, 19 Nov 2025 10:18:12 +0400 Subject: [PATCH 11/13] Update foundations/messages/ordinary-tx.mdx --- foundations/messages/ordinary-tx.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index 1274ed307..659958a57 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -24,7 +24,7 @@ The fields of an ordinary transaction are: - `credit_first` indicates whether the transaction started with the credit phase or the storage phase. This flag matches the `bounce` flag of the message that triggered the transaction and is `true` for incoming external messages. - `storage_ph` indicates the result of the storage phase: the number of storage fees collected and any resulting contract state change. This field is never equal to `Nothing` in the current implementation. - `credit_ph` indicates the result of the credit phase: the number of credits collected and the state update of the contract, if any. This field is `Nothing` when the transaction was triggered by an incoming external message. -- `compute_ph` holds the result of TVM execution on the contract. If this phase is skipped, for example, because there are no funds or no state on the destination account, the field stores the skip reason instead. +- `compute_ph` holds the result of TVM execution on the contract. If this phase is [skipped](/foundations/phases#when-the-compute-phase-is-skipped), for example, because there are no funds or no state on the destination account, the field stores the skip reason instead. - `action` holds the result of the action phase. This field is `Nothing` if the compute phase failed and is populated otherwise. - `aborted` indicates whether the action phase was unsuccessful. - `bounce` holds the result of the bounce phase and is `Nothing` if the bounce phase was not executed. From 010454ca031613b172091ef4edac6835559204a1 Mon Sep 17 00:00:00 2001 From: Anton Trunov Date: Wed, 19 Nov 2025 10:25:58 +0400 Subject: [PATCH 12/13] move transaction-overview.mdx to messages/overview --- docs.json | 1 - foundations/messages/ordinary-tx.mdx | 2 +- foundations/messages/overview.mdx | 40 +++++++++++++++++-- foundations/messages/transaction-overview.mdx | 35 ---------------- 4 files changed, 37 insertions(+), 41 deletions(-) delete mode 100644 foundations/messages/transaction-overview.mdx diff --git a/docs.json b/docs.json index 8c831e1df..487a9e570 100644 --- a/docs.json +++ b/docs.json @@ -505,7 +505,6 @@ "group": "Messages & Transactions", "pages": [ "foundations/messages/overview", - "foundations/messages/transaction-overview", "foundations/messages/internal", "foundations/messages/external-in", "foundations/messages/external-out", diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index 659958a57..4126affa1 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -2,7 +2,7 @@ title: "Ordinary transactions" --- -Ordinary [transactions](/foundations/messages/transaction-overview) are the most common type of transaction because they result from processing [incoming external](/foundations/messages/external-in) and [internal](/foundations/messages/internal) messages. They can be produced only while processing such messages. The phases of a transaction are described in detail on the [dedicated page](/foundations/phases). +Ordinary [transactions](/foundations/messages/overview-transactions) are the most common type of transaction because they result from processing [incoming external](/foundations/messages/external-in) and [internal](/foundations/messages/internal) messages. They can be produced only while processing such messages. The phases of a transaction are described in detail on the [dedicated page](/foundations/phases). The structure of an ordinary transaction is as follows: diff --git a/foundations/messages/overview.mdx b/foundations/messages/overview.mdx index 6cb93d307..088d109d4 100644 --- a/foundations/messages/overview.mdx +++ b/foundations/messages/overview.mdx @@ -32,7 +32,39 @@ A transaction is a record that stores the state changes of a contract. A contrac However, a transaction may be created independently of message processing by -- tick-tock transactions -- split-prepare transactions -- split-install transactions -- storage-tx transactions +- tick-tock transactions, +- split-prepare transactions, +- split-install transactions, +- storage-tx transactions. + +Each transaction has the following structure: + +```tlb + transaction$0111 + account_addr:bits256 + lt:uint64 + prev_trans_hash:bits256 + prev_trans_lt:uint64 + now:uint32 + outmsg_cnt:uint15 + orig_status:AccountStatus + end_status:AccountStatus + ^[ + in_msg:(Maybe ^(Message Any)) + out_msgs:(HashmapE 15 ^(Message Any)) + ] + total_fees:CurrencyCollection + state_update:^(HASH_UPDATE Account) + description:^TransactionDescr += Transaction; +``` + +Transactions implement the concept of `AccountChain` described in the [TON Blockchain whitepaper](/foundations/whitepapers/tblkch#1-2-1-the-infinite-sharding-paradigm-isp-applied-to-blockchain-block-and-state). Each account state can be interpreted as a separate blockchain, so transactions follow a strict order defined by the `prev_trans_hash` field. Thanks to the TON consensus protocol, a transaction becomes final when the first masterchain block references it by storing the hash of the corresponding `ShardChain` state, which in turn stores the hash of the `AccountChain` state. + +Because transactions form the `AccountChain`, each one carries a logical timestamp, `lt`, that strictly increases with every new transaction of the account. The `now` field stores the Unix time when the transaction was created. + +The `state_update` field is a [Merkle update](/foundations/serialization/merkle-update) that captures the difference between the previous and current state of the account. The [contract status](/foundations/status) before and after the transaction is duplicated for convenience. + +Other fields, such as `in_msg`, `out_msgs`, and `outmsg_cnt`, relate to the [messages](/foundations/messages/overview) processed and emitted during the transaction. A trace may start from a transaction rather than a message, in which case `in_msg` is `Nothing`. However, a trace cannot continue without messages: if it contains `n` transactions it must contain at least `n-1` messages. Consequently, a trace can include at most one non-ordinary transaction, because messages can trigger only an [ordinary transaction](/foundations/messages/ordinary-tx). + +The `total_fees` field stores the total number of [fees](/foundations/fees) paid by the transaction. These fees may eventually be paid in extra currencies, but that feature is not implemented yet. diff --git a/foundations/messages/transaction-overview.mdx b/foundations/messages/transaction-overview.mdx deleted file mode 100644 index 6b51328c0..000000000 --- a/foundations/messages/transaction-overview.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "Transactions overview" ---- - -A transaction is a record that stores every state change of a contract. A contract's state cannot be changed without a transaction. Each transaction has the following structure: - -```tlb - transaction$0111 - account_addr:bits256 - lt:uint64 - prev_trans_hash:bits256 - prev_trans_lt:uint64 - now:uint32 - outmsg_cnt:uint15 - orig_status:AccountStatus - end_status:AccountStatus - ^[ - in_msg:(Maybe ^(Message Any)) - out_msgs:(HashmapE 15 ^(Message Any)) - ] - total_fees:CurrencyCollection - state_update:^(HASH_UPDATE Account) - description:^TransactionDescr -= Transaction; -``` - -Transactions implement the concept of `AccountChain` described in the [TON Blockchain whitepaper](/foundations/whitepapers/tblkch#1-2-1-the-infinite-sharding-paradigm-isp-applied-to-blockchain-block-and-state). Each account state can be interpreted as a separate blockchain, so transactions follow a strict order defined by the `prev_trans_hash` field. Thanks to the TON consensus protocol, a transaction becomes final when the first masterchain block references it by storing the hash of the corresponding `ShardChain` state, which in turn stores the hash of the `AccountChain` state. - -Because transactions form the `AccountChain`, each one carries a logical timestamp, `lt`, that strictly increases with every new transaction of the account. The `now` field stores the Unix time when the transaction was created. - -The `state_update` field is a [Merkle update](/foundations/serialization/merkle-update) that captures the difference between the previous and current state of the account. The [contract status](/foundations/status) before and after the transaction is duplicated for convenience. - -Other fields, such as `in_msg`, `out_msgs`, and `outmsg_cnt`, relate to the [messages](/foundations/messages/overview) processed and emitted during the transaction. A trace may start from a transaction rather than a message, in which case `in_msg` is `Nothing`. However, a trace cannot continue without messages: if it contains `n` transactions it must contain at least `n-1` messages. Consequently, a trace can include at most one non-ordinary transaction, because messages can trigger only an [ordinary transaction](/foundations/messages/ordinary-tx). - -The `total_fees` field stores the total number of [fees](/foundations/fees) paid by the transaction. These fees may eventually be paid in extra currencies, but that feature is not implemented yet. From 256bab850a1f8a07b4c1f85a2087ed73b72d6e16 Mon Sep 17 00:00:00 2001 From: Anton Trunov Date: Wed, 19 Nov 2025 10:27:58 +0400 Subject: [PATCH 13/13] linkrot --- foundations/messages/ordinary-tx.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/foundations/messages/ordinary-tx.mdx b/foundations/messages/ordinary-tx.mdx index 4126affa1..32b0d059f 100644 --- a/foundations/messages/ordinary-tx.mdx +++ b/foundations/messages/ordinary-tx.mdx @@ -2,7 +2,7 @@ title: "Ordinary transactions" --- -Ordinary [transactions](/foundations/messages/overview-transactions) are the most common type of transaction because they result from processing [incoming external](/foundations/messages/external-in) and [internal](/foundations/messages/internal) messages. They can be produced only while processing such messages. The phases of a transaction are described in detail on the [dedicated page](/foundations/phases). +Ordinary [transactions](/foundations/messages/overview#transactions) are the most common type of transaction because they result from processing [incoming external](/foundations/messages/external-in) and [internal](/foundations/messages/internal) messages. They can be produced only while processing such messages. The phases of a transaction are described in detail on the [dedicated page](/foundations/phases). The structure of an ordinary transaction is as follows: