feat: transactions

docs.json

@@ -505,6 +505,7 @@
             "group": "Messages & Transactions",
             "pages": [
               "foundations/messages/overview",
+              "foundations/messages/transaction-overview",
               "foundations/messages/internal",
               "foundations/messages/external-in",
               "foundations/messages/external-out",

foundations/messages/ordinary-tx.mdx

@@ -2,8 +2,30 @@
 title: "Ordinary transactions"
 ---
 
-import { Stub } from '/snippets/stub.jsx';
+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).
 
-<Stub
-  issue="1242"
-/>
+The structure of an ordinary transaction is as follows:
+
+```tlb
+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;
+```
+
+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.
+- `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.
+- `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`.

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.

foundations/messages/transaction-overview.mdx

@@ -0,0 +1,35 @@
+---
+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.