TON Virtual Machine (TVM)

TL;DR – The TON Virtual Machine (TVM) runs smart contracts on the TON blockchain using a stack‑based architecture, cell‑based storage, and continuations for flow control. It emphasizes deterministic execution, high code density, and backward compatibility through code pages.

Overview#

The Open Network Virtual Machine (TVM or TON VM) is the execution layer of the TON blockchain. It processes incoming messages, updates persistent contract state, and generates outbound messages. TVM’s design goals are:

• Determinism – identical inputs produce identical results on every validator node.
• Code density – compact on‑chain bytecode to minimize storage costs.
• Extensibility – support for future instruction sets while preserving backward compatibility.

Developers interact with TVM through tooling that compiles high‑level languages (primarily FunC) into TVM bytecode, enabling the creation of decentralized applications.

History#

TVM was created by the Telegram team in 2018 and has evolved through several milestones: – First version released alongside the TON test network. – Detailed technical documentation published, describing data types and optimization techniques. – Core network (mainnet) launch; TVM supported a full set of deterministic operations.

Further development continues via the TON Improvement Proposal (TIP) process, where updates are introduced through community‑reviewed proposals and activated by validator consensus.

Core Concepts#

Data Representation

TVM uses bit strings represented in two notations:

• Hexadecimal notation – groups of four bits are encoded as a single hex digit (0‑F). Non‑multiple‑of‑four lengths receive a special completion tag.
• Octet serialization – groups of eight bits are stored as bytes, with padding added when necessary.

Stack Machine Model

TVM operates as a stack machine: data resides in a last‑in‑first‑out stack rather than registers. Most operations (arithmetic, comparisons, parameter passing) pop arguments from the stack and push results back onto it, yielding compact instruction encoding.

Value Types

TVM works with a fixed set of primitive types:

• Integer – 257‑bit signed integers.
• Cell – containers holding up to 1,023 bits of data and up to four references to other cells.
• Tuple – ordered collections of heterogeneous values.
• Slice – a view into a cell’s data and references.
• Builder – a buffer for constructing new cells.
• Continuation – a saved execution point containing code, stack, and register state.
• Null – represents the absence of a value.

Instruction Categories

• Stack and tuple primitives – stack reordering and tuple manipulation.
• Constant primitives – push predefined constants onto the stack.
• Arithmetic primitives – perform standard arithmetic with automatic overflow checking.
• Cell primitives – create, read, and modify cells.
• Flow‑control primitives – conditional branches, loops, and continuation management.
• Custom primitives – TON‑specific operations (e.g., address handling, signature verification).

Cells and Continuations#

Cells

Cells are the fundamental storage units in TVM and the TON blockchain. Each cell can store up to 1,023 bits and reference up to four other cells, forming a directed acyclic graph (DAG). All on‑chain data—smart contracts, states, messages, blocks—is represented as collections of cells.

Cell types

• Normal cells (type‑1) – standard data containers.
• Exotic cells – types 2‑255 with special deserialization and hashing rules, used for truncated branches, library references, and Merkle proofs.

Continuations

Continuations encapsulate a saved execution context, enabling subroutine calls, conditional logic, loops, and exception handling. Types include:

• Normal continuations – contain code, stack, saved registers, and a 16‑bit code‑page identifier.
• Simple continuations – only code and code page, without stack data.
• Current continuations (cc) – represent the code currently executing.

Control flow switches between continuations via JMP (jump) and RET (return) instructions. Exceptions are modeled as special continuations that receive error parameters.

Code Pages and Compatibility#

Each regular continuation carries a 16‑bit code‑page (cp) field that determines how its instructions are decoded. This mechanism allows contracts compiled for different instruction sets to coexist on the network, ensuring backward compatibility. Invalid opcode prefixes trigger an exception, preventing ambiguous execution.

Automatic code‑page switching can optimize performance by selecting specialized pages for frequent operation groups (e.g., stack manipulation).

Comparison with the Ethereum Virtual Machine (EVM)#

The cell‑based model simplifies handling complex structures (trees, DAGs) and reduces on‑chain storage compared to the EVM’s trie. Automatic overflow checking and richer cryptographic primitives enhance security and functionality.

See also#

• The Open Network
• Smart contracts (no existing slug)
• Toncoin