From fa9991ae973865ccae459dc26f88bad0def9fdeb Mon Sep 17 00:00:00 2001 From: Antonoff <35700168+memearchivarius@users.noreply.github.com> Date: Sun, 4 Aug 2024 21:11:17 +0300 Subject: [PATCH 1/6] Transaction outcome Definition of success and some TVM details. --- .../guidelines/message-delivery-guarantees.mdx | 9 +++++++++ docs/learn/tvm-instructions/tvm-overview.mdx | 16 ++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx b/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx index cab5939ef5..3cf879aa74 100644 --- a/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx +++ b/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx @@ -58,6 +58,15 @@ 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](https://testnet.tonviewer.com/transaction/5889803bb1e0f58fdee381382fe1e38f74f3ea002a700441f8a21d52f7234ef8). +Also [TVM compute phase may be skipped](/learn/tvm-instructions/tvm-overview#compute-phase-skipped) for some reasons like +[absence of funds](https://testnet.tonviewer.com/transaction/a1612cde7fd66139a7d04b30f38db192bdb743a8b12054feba3c16061a4cb9a6) +or [state](https://testnet.tonviewer.com/transaction/7e78394d082882375a5d21affa6397dec60fc5a3ecbea87f401b0e460fb5c80c). +If compute phase is skipped, [transaction is successful like Jetton Notify message](https://testnet.tonscan.org/tx/ypgh2Z4wI9_o8R8gy9Ng_XL9QbKoL3kFRXDHAlp7byo=). + ## 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..9bbe28934c 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 — [**TVM implementation paper**](https://ton.org/tvm.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 (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 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) From a3cf2e812d45dea0dd79f0e2615d2c31f2750254 Mon Sep 17 00:00:00 2001 From: Antonoff <35700168+memearchivarius@users.noreply.github.com> Date: Mon, 5 Aug 2024 17:30:03 +0300 Subject: [PATCH 2/6] Upd transaction outcome --- .../guidelines/message-delivery-guarantees.mdx | 16 +++++++++------- docs/learn/tvm-instructions/tvm-overview.mdx | 6 +++--- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx b/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx index 3cf879aa74..149176e0dd 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. @@ -60,12 +60,14 @@ More detailed and accurate description on the [Transaction Layout](/develop/data ### 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](https://testnet.tonviewer.com/transaction/5889803bb1e0f58fdee381382fe1e38f74f3ea002a700441f8a21d52f7234ef8). -Also [TVM compute phase may be skipped](/learn/tvm-instructions/tvm-overview#compute-phase-skipped) for some reasons like -[absence of funds](https://testnet.tonviewer.com/transaction/a1612cde7fd66139a7d04b30f38db192bdb743a8b12054feba3c16061a4cb9a6) -or [state](https://testnet.tonviewer.com/transaction/7e78394d082882375a5d21affa6397dec60fc5a3ecbea87f401b0e460fb5c80c). -If compute phase is skipped, [transaction is successful like Jetton Notify message](https://testnet.tonscan.org/tx/ypgh2Z4wI9_o8R8gy9Ng_XL9QbKoL3kFRXDHAlp7byo=). +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. + +Transaction may have one of three results: + +- Success, exit code 0 or 1 +- Success, If compute phase is skipped, [like Jetton Notify message](https://testnet.tonscan.org/tx/ypgh2Z4wI9_o8R8gy9Ng_XL9QbKoL3kFRXDHAlp7byo=). +- Fail, [exit code > 1 ](https://testnet.tonviewer.com/transaction/5889803bb1e0f58fdee381382fe1e38f74f3ea002a700441f8a21d52f7234ef8) ## What is a Logical time? diff --git a/docs/learn/tvm-instructions/tvm-overview.mdx b/docs/learn/tvm-instructions/tvm-overview.mdx index 9bbe28934c..401c042f36 100644 --- a/docs/learn/tvm-instructions/tvm-overview.mdx +++ b/docs/learn/tvm-instructions/tvm-overview.mdx @@ -69,11 +69,11 @@ The computing phase consists in invoking TVM with correct inputs. On some occasi 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 (i.e., smart-contract code and data) in both the account (non-existing, uninitialized, or frozen) and the message. +- `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_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 to buy gas. (About < 0.00004 TON by [08.2024](https://testnet.tonviewer.com/transaction/9789306d7b29318c90477aa3df6599ee4a897031162ad41a24decb87db65402b)) +- `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: From 79077430bf0186f00d29dd92a531255d721f0fe2 Mon Sep 17 00:00:00 2001 From: Antonoff <35700168+memearchivarius@users.noreply.github.com> Date: Wed, 7 Aug 2024 12:29:07 +0300 Subject: [PATCH 3/6] Update message-delivery-guarantees.mdx --- .../message-delivery-guarantees.mdx | 25 +++++++++++++++++-- 1 file changed, 23 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 149176e0dd..88bd8f2b56 100644 --- a/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx +++ b/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx @@ -63,11 +63,32 @@ More detailed and accurate description on the [Transaction Layout](/develop/data 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 -- Success, If compute phase is skipped, [like Jetton Notify message](https://testnet.tonscan.org/tx/ypgh2Z4wI9_o8R8gy9Ng_XL9QbKoL3kFRXDHAlp7byo=). -- Fail, [exit code > 1 ](https://testnet.tonviewer.com/transaction/5889803bb1e0f58fdee381382fe1e38f74f3ea002a700441f8a21d52f7234ef8) +- Fail, `aborted: true` +- Fail, [exit code >= 2 ](https://testnet.tonviewer.com/transaction/5889803bb1e0f58fdee381382fe1e38f74f3ea002a700441f8a21d52f7234ef8), `aborted: true` ## What is a Logical time? From a81bafe2b9e96f72402488d33e505ee425a13632 Mon Sep 17 00:00:00 2001 From: Antonoff <35700168+memearchivarius@users.noreply.github.com> Date: Wed, 21 Aug 2024 13:45:54 +0300 Subject: [PATCH 4/6] Update tvm-overview.mdx --- docs/learn/tvm-instructions/tvm-overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/learn/tvm-instructions/tvm-overview.mdx b/docs/learn/tvm-instructions/tvm-overview.mdx index 401c042f36..56e0654e5e 100644 --- a/docs/learn/tvm-instructions/tvm-overview.mdx +++ b/docs/learn/tvm-instructions/tvm-overview.mdx @@ -60,7 +60,7 @@ Each transaction consists of up to 5 phases: In this phase, the TVM execution occurs. :::tip -* TVM 4.3.5 — [**TVM implementation paper**](https://ton.org/tvm.pdf) +* TVM 4.3.5 — [**TON Blockchain paper**](https://docs.ton.org/assets/files/tblkch-6aaf006b94ee2843a982ebf21d7c1247.pdf) ::: ### Compute phase skipped @@ -128,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) From 7b7a9ab7661797408ffb4d743aa1f9ad1ef06957 Mon Sep 17 00:00:00 2001 From: Antonoff <35700168+memearchivarius@users.noreply.github.com> Date: Wed, 28 Aug 2024 12:54:54 +0300 Subject: [PATCH 5/6] Update message-delivery-guarantees.mdx --- .../guidelines/message-delivery-guarantees.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx b/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx index 88bd8f2b56..0abbd3023f 100644 --- a/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx +++ b/docs/develop/smart-contracts/guidelines/message-delivery-guarantees.mdx @@ -60,10 +60,10 @@ More detailed and accurate description on the [Transaction Layout](/develop/data ### 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. +There is a [TVM exit code](/learn/tvm-instructions/tvm-exit-codes) for transaction which had compute phase, if it is not 0 or 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 +:::info for toncenter api v3 To determine successful transaction one should use tx.description.action.success && tx.description.compute_ph.success: ::: ```json @@ -87,8 +87,12 @@ To determine successful transaction one should use tx.description.action.success 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` +- Fail, `aborted: true` without execution +- Fail, [exit code](/learn/tvm-instructions/tvm-exit-codes), `aborted: true` + +:::info for toncenter api v3 +`aborted: true` is a toncenter field, transaction has no such field +::: ## What is a Logical time? From 19dfeb925633fb38dcd7a78ceffd93da638b97b6 Mon Sep 17 00:00:00 2001 From: Antonoff <35700168+memearchivarius@users.noreply.github.com> Date: Thu, 29 Aug 2024 13:36:32 +0300 Subject: [PATCH 6/6] Update academy-overview.md Button --- docs/learn/academy/academy-overview.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/learn/academy/academy-overview.md b/docs/learn/academy/academy-overview.md index fa776e9781..2ffe955aae 100644 --- a/docs/learn/academy/academy-overview.md +++ b/docs/learn/academy/academy-overview.md @@ -1,3 +1,5 @@ +import Button from '@site/src/components/button' + # Educational Resources ### TON Speedrun