Overview of TVM
The TON Virtual Machine (TVM) executes all TON smart contracts. TVM operates on the stack principle, which ensures efficiency and ease of implementation.
This document provides a high-level overview of how TVM processes transactions.
- TVM source: TVM C++ implementation
- TVM retracer
TON course: TVM
Before starting the course, ensure you have a solid understanding of blockchain basics. If you need to fill knowledge gaps, consider taking the Blockchain basics with TON course (RU version, CHN version).
The TON blockchain course is a comprehensive guide to TON blockchain development. Module 2 covers TVM, transactions, scalability, and business cases in detail.
Explore TON blockchain course
CHN
RU
Transactions and phases
When an event occurs on an account in the TON blockchain, it triggers a transaction. The most common event is receiving a message, but other events like tick-tock
, merge
, and split
can also initiate transactions.
Each transaction consists of up to five phases:
- Storage phase: calculates storage fees for the contract based on the space it occupies in the blockchain state. Learn more in storage fees.
- Credit phase: updates the contract's balance by accounting for incoming message values and storage fees.
- Compute phase: executes the contract code on TVM. The result includes
exit_code
,actions
,gas_details
,new_storage
, and other data. - Action phase: processes actions from the compute phase if it succeeds. Actions may include sending messages, updating contract code, or modifying libraries. If an action fails, for example, due to lack of funds, the transaction may revert or skip the action, depending on its mode (
send-or-revert
ortry-send-if-no-ignore
). - Bounce phase: if the compute phase fails (
exit_code >= 2
), this phase generates a bounce message for transactions initiated by an incoming message.
Compute phase
The compute phase involves executing the contract code on TVM.
- TVM 4.3.5: TON blockchain paper
When the compute phase is skipped
The compute phase may be skipped under certain conditions, such as when the account is missing, uninitialized, or frozen, or when the incoming message lacks code or data fields. These scenarios are represented by specific constructors:
cskip_no_state$00
: the account or message lacks a valid state (for example, missing code or data).cskip_bad_state$01
: the message contains an invalid state (for example, incorrect hash) for a frozen or uninitialized account.cskip_no_gas$10
: the account lacks enough funds to cover gas costs (less than ~0.00004 TON as of August 2024).
TVM state
At any point, the TVM state is defined by six properties:
- Stack: a last-in-first-out data structure.
- Control registers: up to 16 variables that can be directly accessed during execution.
- Current continuation: describes the sequence of instructions being executed.
- Current codepage: specifies the TVM version in use.
- Gas limits: includes the current gas limit (
g<sub>l</sub>
), maximum gas limit (g<sub>m</sub>
), remaining gas (g<sub>r</sub>
), and gas credit (g<sub>c</sub>
). - Library context: a hashmap of libraries available for TVM.
TVM as a stack machine
TVM operates as a stack machine, supporting seven variable types:
- Non-cell types:
- Integer: signed 257-bit integers.
- Tuple: ordered collections of up to 255 elements.
- Null.
- Cell types:
- Cell: basic data structure for storing information.
- Slice: allows reading data from a cell.
- Builder: enables creating new cells.
- Continuation: treats a cell as a source of TVM instructions.
Control registers
c0
: stores the next or return continuation, similar to a return address.c1
: stores the alternative continuation.c2
: contains the exception handler. Continuation.c3
: holds the current dictionary like a hashmap of functions codes. Continuation.c4
: stores the persistent data (contract'sdata
section). Cell.c5
: contains output actions. Cell.c7
: stores temporary data. Tuple.
Initializing TVM
TVM initializes during the compute phase and executes commands/opcodes from the current continuation until no more commands remain. For a detailed explanation, see TVM initialization.
TVM instructions
For a complete list of TVM instructions, visit TVM instructions.
Results of TVM execution
Besides exit_code
and gas consumption, TVM outputs:
c4
: the newdata
cell for the contract (if execution succeeds).c5
: a cell containing output actions.
Other register values are discarded. Note:
- The maximum cell depth during execution is
<1024
, butc4
andc5
must not exceed a depth of512
. - A contract can't create more than 255 output actions.
To send more than 255 messages, a contract can send a message to itself with a request to process the remaining messages. See an example in the highload wallet contract.
See also
- TVM instructions
- TON TVM concepts (may include outdated information)