From 83a05ace4033c50319e27b59ec6d9203195fd6c2 Mon Sep 17 00:00:00 2001 From: Antonoff <35700168+memearchivarius@users.noreply.github.com> Date: Wed, 28 Aug 2024 12:45:20 +0300 Subject: [PATCH] Transaction outcome description (#708) * Transaction outcome Definition of success and some TVM details. * Upd transaction outcome * Update message-delivery-guarantees.mdx * Update tvm-overview.mdx --- .../message-delivery-guarantees.mdx | 34 ++++++++++++++++++- docs/learn/tvm-instructions/tvm-overview.mdx | 18 +++++++++- 2 files changed, 50 insertions(+), 2 deletions(-) diff --git a/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx b/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx index cab5939ef5..88bd8f2b56 100644 --- a/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx +++ b/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx @@ -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. @@ -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. diff --git a/docs/learn/tvm-instructions/tvm-overview.mdx b/docs/learn/tvm-instructions/tvm-overview.mdx index 55c2d2c8be..56e0654e5e 100644 --- a/docs/learn/tvm-instructions/tvm-overview.mdx +++ b/docs/learn/tvm-instructions/tvm-overview.mdx @@ -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) @@ -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) \ No newline at end of file +- [TON TVM](https://ton.org/tvm.pdf) TVM Concepts(may include outdated information)