Skip to content

Commit

Permalink
Transaction outcome description (#708)
Browse files Browse the repository at this point in the history
* Transaction outcome

Definition of success and some TVM details.

* Upd transaction outcome

* Update message-delivery-guarantees.mdx

* Update tvm-overview.mdx
  • Loading branch information
memearchivarius authored Aug 28, 2024
1 parent 7f46271 commit eb9a0b1
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 2 deletions.
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import ConceptImage from '@site/src/components/conceptImage';
import ThemedImage from '@theme/ThemedImage';

# Message Overview
# Messages and Transactions

TON is an asynchronous blockchain with a complex structure very different from other blockchains. Because of this, new developers often have questions about low-level things in TON. In this article, we will have a look at one of these related to message delivery.

Expand Down Expand Up @@ -58,6 +58,38 @@ To achieve the infinite sharding paradigm, it is necessary to ensure full parall
More detailed and accurate description on the [Transaction Layout](/develop/data-formats/transaction-layout) page.
:::

### Transaction outcome

There is a [TVM exit code](/learn/tvm-instructions/tvm-exit-codes) for transaction which had compute phase, if it is >1 then there was an error.
Also TVM [compute phase may be skipped](/learn/tvm-instructions/tvm-overview#compute-phase-skipped) for some reasons like absence of funds or state.

:::info
To determine successful transaction one should use tx.description.action.success && tx.description.compute_ph.success:
:::
```json
"transactions": [
{
"description": {
. . . . . . . .
"action": {
"valid": true,
"success": true,
. . . . . . . .
},
. . . . . . . .
"destroyed": false,
"compute_ph": {
"mode": 0,
"type": "vm",
"success": true,
```

Transaction may have one of three results:

- Success, exit code 0 or 1
- Fail, `aborted: true`
- Fail, [exit code >= 2 ](https://testnet.tonviewer.com/transaction/5889803bb1e0f58fdee381382fe1e38f74f3ea002a700441f8a21d52f7234ef8), `aborted: true`

## What is a Logical time?

In such a system with asynchronous and parallel smart contract calls, it can be hard to define the order of actions to process. That's why each message in TON has its _Logical time_ or _Lamport time_ (later just _lt_). It is used to understand which event caused another and what a validator needs to process first.
Expand Down
18 changes: 17 additions & 1 deletion docs/learn/tvm-instructions/tvm-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,22 @@ Each transaction consists of up to 5 phases:
## Compute phase
In this phase, the TVM execution occurs.

:::tip
* TVM 4.3.5 — [**TON Blockchain paper**](https://docs.ton.org/assets/files/tblkch-6aaf006b94ee2843a982ebf21d7c1247.pdf)
:::

### Compute phase skipped

The computing phase consists in invoking TVM with correct inputs. On some occasions, TVM cannot be invoked at all (e.g., if the account is absent, not initialized, or frozen, and the inbound message being processed has no code or data fields or these fields have an incorrect hash)

This is reflected by corresponding [constructors](https://github.com/ton-blockchain/ton/blob/5c392e0f2d946877bb79a09ed35068f7b0bd333a/crypto/block/block.tlb#L314):

- `cskip_no_state$00` - The [absence of a state](https://testnet.tonviewer.com/transaction/7e78394d082882375a5d21affa6397dec60fc5a3ecbea87f401b0e460fb5c80c) (i.e., smart-contract code and data) in both the account (non-existing, uninitialized, or frozen) and the message.

- `cskip_bad_state$01` - An invalid state passed in the message (i.e., the state's hash differs from the expected value) to a frozen or uninitialized account.

- `cskip_no_gas$10` - The [absence of funds](https://testnet.tonviewer.com/transaction/a1612cde7fd66139a7d04b30f38db192bdb743a8b12054feba3c16061a4cb9a6) to buy gas. (About < 0.00004 TON by [08.2024](https://testnet.tonviewer.com/transaction/9789306d7b29318c90477aa3df6599ee4a897031162ad41a24decb87db65402b))

### TVM state
At any given moment, the TVM state is fully determined by 6 properties:
* Stack (see below)
Expand Down Expand Up @@ -112,4 +128,4 @@ Note, that since there is a limit on max cell-depth `<1024`, and particularly th
## See Also

- [TVM Instructions](/learn/tvm-instructions/instructions)
- [TON TVM](https://ton.org/tvm.pdf) TVM Concepts(may include outdated information)
- [TON TVM](https://ton.org/tvm.pdf) TVM Concepts(may include outdated information)

0 comments on commit eb9a0b1

Please sign in to comment.