feat: transactions

foundations/messages/ordinary-tx.mdx

@@ -2,8 +2,30 @@
 title: "Ordinary transactions"
 ---
 
-import { Stub } from '/snippets/stub.jsx';
+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).
 
-<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](/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.
+- `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.
@@ -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.