From ffd135f8d54349771786eb544e0be5d5c82b079c Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Thu, 9 Oct 2025 02:46:44 +0100 Subject: [PATCH 01/16] crosslink tblkch to the reference pdf --- ton/tblkch.mdx | 73 +++++++++++++++++++++++--------------------------- 1 file changed, 34 insertions(+), 39 deletions(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index 032db947..e3c08dca 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -13,11 +13,11 @@ The aim of this text is to provide a detailed description of the Telegram Open N ## Introduction -This document provides a detailed description of the TON Blockchain, including its precise block format, validity conditions, TON Virtual Machine (TVM) invocation details, smart-contract creation process, and cryptographic signatures. In this respect it is a continuation of the TON whitepaper (cf. [3](#3-messages%2C-message-descriptors%2C-and-queues)), so we freely use the terminology introduced in that document. +This document provides a detailed description of the TON Blockchain, including its precise block format, validity conditions, TON Virtual Machine (TVM) invocation details, smart-contract creation process, and cryptographic signatures. In this respect it is a continuation of the TON whitepaper (cf. [3](#ref-3)), so we freely use the terminology introduced in that document. -Chapter 1 provides a general overview of the TON Blockchain and its design principles, with particular attention to the introduction of compatibility and validity conditions and the implementation of message delivery guarantees. More detailed information, such as the TL-B schemes that describe the serialization of all required data structures into trees or collections (“bags”) of cells, is provided in subsequent chapters, culminating in a complete description of the TON Blockchain (shardchain and masterchain) block layout in Chapter 5. +[Chapter 1](#1-overview) provides a general overview of the TON Blockchain and its design principles, with particular attention to the introduction of compatibility and validity conditions and the implementation of message delivery guarantees. More detailed information, such as the TL-B schemes that describe the serialization of all required data structures into trees or collections (“bags”) of cells, is provided in subsequent chapters, culminating in a complete description of the TON Blockchain (shardchain and masterchain) block layout in [Chapter 5](#5-block-layout). -A detailed description of the elliptic curve cryptography used for signing blocks and messages, also accessible through TVM primitives, is provided in Appendix A. TVM itself is described in a separate document (cf. [4](#4-accounts-and-transactions)). +A detailed description of the elliptic curve cryptography used for signing blocks and messages, also accessible through TVM primitives, is provided in [Appendix A](#a-elliptic-curve-cryptography). TVM itself is described in a separate document (cf. [4](#ref-4)). Some subjects have intentionally been left out of this document. One is the Byzantine Fault Tolerant (BFT) protocol used by the validators to determine the next block of the masterchain or a shardchain; that subject is left for a forthcoming document dedicated to the TON Network. @@ -31,15 +31,12 @@ Please note that the current version of this document describes a preliminary te This chapter provides an overview of the main features and design principles of the TON Blockchain. More detail on each topic is provided in subsequent chapters. ## 1.1 Everything is a bag of cells -All data in the blocks and state of the TON Blockchain is represented as a collection of cells (cf. [3.2.5](#3-2-5-augmented-hashmaps%2C-or-dictionaries). Therefore, this chapter begins with a general discussion of cells. +All data in the blocks and state of the TON Blockchain is represented as a collection of cells (cf. [3](#ref-3), 2.5]. Therefore, this chapter begins with a general discussion of cells. ### 1.1.1. TVM cells -Recall that the TON Blockchain, as well as the TON Virtual Machine (TVM; cf. [4.3.1](#ref-4)), represents all permanently stored data as a collection or bag of so-called cells. Each cell consists of up to `1023` data bits and up to `4` references to other cells. - -Cyclic cell references are not allowed, so the cells are usually organized into trees of cells, or rather directed acyclic graphs (DAGs) of cells.[³](#footnote-3) Any value of an abstract algebraic (dependent) data type may be represented (serialized) as a tree of cells. - -The precise way of representing values of an abstract data type as a tree of cells is expressed by means of a TL-B scheme.[⁴](#footnote-4) A more thorough discussion of different kinds of cells may be found in [4.3.1](#4-3-1-reasons-for-omitting-data-from-a-transaction-description). +Recall that the TON Blockchain, as well as the TON Virtual Machine (TVM; cf. [4](#ref-4)), represents all permanently stored data as a collection or bag of so-called cells. Each cell consists of up to 1023 data bits and up to four references to other cells. Cyclic cell references are not allowed, so the cells are usually organized into trees of cells, or rather directed acyclic graphs (DAGs) of cells.[³](#footnote-3) Any value of an abstract algebraic (dependent) data type may be represented (serialized) as a tree of cells. +The precise way of representing values of an abstract data type as a tree of cells is expressed by means of a TL-B scheme.[⁴](#footnote-4) A more thorough discussion of different kinds of cells may be found in [[4](#ref-4), 3.1]. ### 1.1.2. Application to TON Blockchain blocks and state The above is particularly applicable to the blocks and state of the TON Blockchain, which also are values of certain (quite convoluted) dependent algebraic data types. @@ -86,7 +83,7 @@ In particular, the cell references of a cell `c` are completely determined by th Apart from the ordinary cells (also called simple or data cells) considered so far, cells of other types, called exotic cells, sometimes appear in the actual representations of TON Blockchain blocks and other data structures. -Their representation is somewhat different; they are distinguished by having the first descriptor byte `d₁ ≥ 5` (cf. [4.3.1](#4-3-1-reasons-for-omitting-data-from-a-transaction-description)). +Their representation is somewhat different; they are distinguished by having the first descriptor byte `d₁ ≥ 5` (cf. [[4](#ref-4), 3.1]). ### 1.1.6. External reference cells @@ -113,7 +110,7 @@ Signatures are an excellent example of the application of representation hashes. ### 1.1.10. Higher hashes of a cell -In addition to the transparent and representation hashes of a cell `c`, a sequence of higher hashes `Hashᵢ(c)`, `i = 1, 2, ...` may be defined, which eventually stabilizes at `Hash∞(c)`. (More detail may be found in [4.3.1](#ref-4).) +In addition to the transparent and representation hashes of a cell `c`, a sequence of higher hashes `Hashᵢ(c)`, `i = 1, 2, ...` may be defined, which eventually stabilizes at `Hash∞(c)`. (More detail may be found in [[4](#ref-4), 3.1]. --- @@ -191,7 +188,7 @@ In both cases, the reason for the removal of a message from the `OutMsgQueue` is ### 1.2.8. Layout of InMsgDescr, OutMsgDescr and OutMsgQueue -All of the most important non-split shardchain data structures related to messages are organized as hashmaps or dictionaries (implemented by means of Patricia trees serialized into a tree of cells as described in [3.3](#3-3-outbound-message-queue-and-descriptors) and [4.3.3](#4-3-3-description-of-a-storage-phase)), with the following keys: +All of the most important non-split shardchain data structures related to messages are organized as hashmaps or dictionaries (implemented by means of Patricia trees serialized into a tree of cells as described in [[4](#ref-4), 3.3], with the following keys: * The inbound message description `InMsgDescr` uses the 256-bit message hash as a key. * The outbound message description `OutMsgDescr` uses the 256-bit message hash as a key. @@ -208,7 +205,7 @@ Each transaction is described in the block by an instance of the `Transaction` t * A reference to exactly one inbound message (which must be present in `InMsgDescr` as well) that has been processed by the transaction. * References to several (maybe zero) outbound messages (also present in `OutMsgDescr` and most likely included in `OutMsgQueue`) that have been generated by the transaction. -The transaction consists of an invocation of TVM (cf. [4](#4-accounts-and-transactions)) with the code of the smart contract corresponding to the account in question loaded into the virtual machine, and with the data root cell of the smart contract loaded into the virtual machine’s register `c4`. +The transaction consists of an invocation of TVM (cf. [4](#ref-4)) with the code of the smart contract corresponding to the account in question loaded into the virtual machine, and with the data root cell of the smart contract loaded into the virtual machine’s register `c4`. The inbound message itself is passed in the stack as an argument to the smart contract’s `main()` function, along with some other important data, such as the amount of TON Grams and other defined currencies attached to the message, the sender account address, the current balance of the smart contract, and so on. @@ -517,7 +514,7 @@ In particular, when we say that a block must import in its `InMsgDescr` the mess ## 1.6 Configurable parameters and smart contracts -Recall that the TON Blockchain has several so-called “configurable parameters” (cf. [Chapter 3](#3-messages-message-descriptors-and-queues)), which are either certain values or certain smart contracts residing in the masterchain. This section discusses the storage of and access to these configurable parameters. +Recall that the TON Blockchain has several so-called “configurable parameters” (cf. [3](#ref-3)), which are either certain values or certain smart contracts residing in the masterchain. This section discusses the storage of and access to these configurable parameters. ### 1.6.1. Examples of configurable parameters The properties of the blockchain controlled by configurable parameters include: @@ -1085,13 +1082,13 @@ nanograms$_ amount:(VarUInteger 16) = Grams; If one wants to represent `x` nanograms, one selects an integer `ℓ < 16` such that `x < 2⁸ˡ`, and serializes first `ℓ` as an unsigned 4-bit integer, then `x` itself as an unsigned `8ℓ`-bit integer. Notice that four zero bits represent a zero amount of Grams. -Recall (cf. [3, A](#ref-3)) that the original total supply of Grams is fixed at five billion (i.e., `5·10¹⁸ < 2⁶³` nanograms), and is expected to grow very slowly. Therefore, all the amounts of Grams encountered in practice will fit in unsigned or even signed 64-bit integers. Validators may use the 64-bit integer representation of Grams in their internal computations; however, serialization of such values in the blockchain is another matter. +Recall (cf. [[3](#ref-3), A]) that the original total supply of Grams is fixed at five billion (i.e., `5·10¹⁸ < 2⁶³` nanograms), and is expected to grow very slowly. Therefore, all the amounts of Grams encountered in practice will fit in unsigned or even signed 64-bit integers. Validators may use the 64-bit integer representation of Grams in their internal computations; however, serialization of such values in the blockchain is another matter. ### 3.1.6. Representing collections of arbitrary currencies Recall that the TON Blockchain allows its users to define arbitrary cryptocurrencies or tokens apart from the Gram, provided some conditions are met. Such additional cryptocurrencies are identified by 32-bit `currency_id`s. The list of defined additional cryptocurrencies is a part of the blockchain configuration, stored in the masterchain. -When some amounts of one or several such cryptocurrencies need to be represented, a dictionary (cf. [4, 3.3](#ref-4)) with 32-bit `currency_id`s as keys and `VarUInteger 32` values is used: +When some amounts of one or several such cryptocurrencies need to be represented, a dictionary (cf. [[4](#ref-4), 3.3]) with 32-bit `currency_id`s as keys and `VarUInteger 32` values is used: ```c extra_currencies$_ dict:(HashmapE 32 (VarUInteger 32)) @@ -1268,7 +1265,7 @@ These augmentation values must satisfy certain aggregation conditions. Typically ### 3.2.6. Serialization of augmented hashmaps -The serialization of augmented hashmaps with `n`-bit keys, values of type `X`, and augmentation values of type `Y` is given by the following TL-B scheme, which is an extension of the one provided in [4, 3.3.3](#ref-4): +The serialization of augmented hashmaps with `n`-bit keys, values of type `X`, and augmentation values of type `Y` is given by the following TL-B scheme, which is an extension of the one provided in [[4](#ref-4), 3.3.3] ```tlb ahm_edge#_ {n:#} {X:Type} {Y:Type} {l:#} {m:#} @@ -1744,7 +1741,7 @@ old:^X new:^X = MERKLE_UPDATE X; The exclamation mark in the TL-B declaration of a merkle\_update indicates special processing required for such values. In particular, they must be kept in a separate cell, which must be marked as exotic by a bit in its header -(cf. [4, 3.1](#ref-4)). +(cf. [[4](#ref-4), 3.1]). A full explanation of the serialization of TransactionDescr, which describes one transaction according to its kind listed in [4.2.4](#4-2-4-kinds-of-transactions), can be found in [4.3](#4-3-transaction-descriptions). @@ -1807,7 +1804,7 @@ The transactions dictionary is sum-augmented by a Grams value, which aggregates the total fees collected from these transactions. In addition to this dictionary, an AccountBlock contains a Merkle update -(cf. [4, 3.1](#ref-4)) of the total state of the account. If an account did not exist +(cf. [[4](#ref-4), 3.1]) of the total state of the account. If an account did not exist before the block, its state is represented by an account\_none. ### 4.2.16. Consistency conditions for AccountBlocks. @@ -2220,7 +2217,7 @@ action_set_code#ad4de08e new_code:^Cell = OutAction; # 5 Block layout -This chapter presents the block layout used by the TON Blockchain, combining the data structures described separately in previous chapters to produce a complete description of a shardchain block. In addition to the TL-B schemes that define the representation of a shardchain block by a tree of cells, this chapter describes exact serialization formats for the resulting bags (collections) of cells, which are necessary to represent a shardchain block as a file. Masterchain blocks are similar to shardchain blocks, but have some additional fields. The necessary modifications are discussed separately in 5.2. +This chapter presents the block layout used by the TON Blockchain, combining the data structures described separately in previous chapters to produce a complete description of a shardchain block. In addition to the TL-B schemes that define the representation of a shardchain block by a tree of cells, this chapter describes exact serialization formats for the resulting bags (collections) of cells, which are necessary to represent a shardchain block as a file. Masterchain blocks are similar to shardchain blocks, but have some additional fields. The necessary modifications are discussed separately in [5.2](#5-2-masterchain-block-layout). ## 5.1 Shardchain block layout @@ -2235,7 +2232,7 @@ The shardchain state consists of: * `SharedLibraries`, the description of all shared libraries of the shardchain (for now, non-empty only in the masterchain). * The logical time and the unixtime of the last modification of the state. * The total balance of the shard. -* A hash reference to the most recent masterchain block, indirectly describing the state of the masterchain and, through it, the state of all other shardchains of the TON Blockchain (cf. 1.5.2). +* A hash reference to the most recent masterchain block, indirectly describing the state of the masterchain and, through it, the state of all other shardchains of the TON Blockchain (cf. [1.5.2](#1-5-2-total-state-defined-by-a-shardchain-block)). ### 5.1.2. Components of a shardchain block. @@ -2245,9 +2242,9 @@ A shardchain block must contain: * `BlockHeader`, containing general information about the block (cf. [1.2.5](#1-2-5-block-header)) * Hash references to the immediately preceding block or blocks of the same shardchain, and to the most recent masterchain block. * `InMsgDescr` and `OutMsgDescr`, the inbound and outbound message descriptors (cf. [3.2.8](#3-2-8-structure-of-inmsgdescr) and [3.3.5](#3-3-5-structure-of-outmsgdescr)).. -* `ShardAccountBlocks`, the collection of all transactions processed in the block (cf. [4.2.17](##4-2-17-collection-of-all-transactions-in-a-block)) along with all updates of the states of the accounts assigned to the shard. This is the split part of the shardchain block (cf. 1.2.2). +* `ShardAccountBlocks`, the collection of all transactions processed in the block (cf. [4.2.17](##4-2-17-collection-of-all-transactions-in-a-block)) along with all updates of the states of the accounts assigned to the shard. This is the split part of the shardchain block (cf. [1.2.2](#1-2-2-split-and-non-split-part-of-the-shardchain-block-and-state)). * The value flow, describing the total value imported from the preceding blocks of the same shardchain and from inbound messages, the total value exported by outbound message, the total fees collected by validators, and the total value remaining in the shard. -* A Merkle update (cf. [4, 3.1](#ref-4)) of the shardchain state. Such a Merkle update contains the hashes of the initial and final shardchain states with respect to the block, along with all new cells of the final state that have been created while processing the block.[³⁷](#footnote-37) +* A Merkle update (cf. [[4](#ref-4), 3.1]) of the shardchain state. Such a Merkle update contains the hashes of the initial and final shardchain states with respect to the block, along with all new cells of the final state that have been created while processing the block.[³⁷](#footnote-37) ### 5.1.3. Common parts of the block layout for all workchains. @@ -2365,15 +2362,14 @@ The overall procedure of serializing and signing a block may be described as fol ``` math Hᴮ := sha256( Hash∞(B) . Hashᴹ(Sᵦ) ) (18) ``` - - of the representation hash of **B** and of the Merkle hash of its serialization **Sᵦ**. +of the representation hash of **B** and of the Merkle hash of its serialization **Sᵦ**. 3. A signed shardchain block **B̃** is generated from **B** and these validator signatures as described above (cf. [5.1.8](#5-1-8-signed-shardchain-block)). 4. This signed block **B̃** is transformed into an incomplete bag of cells, which contains only the validator signatures, but the unsigned block itself is absent from this bag of cells, being its only absent cell. 5. This incomplete bag of cells is serialized, and its serialization is prepended to the previously constructed serialization of the unsigned block. The result is the serialization of the signed block into an octet string. It may be propagated by network or stored into a disk file. ## 5.2 Masterchain block layout -Masterchain blocks are very similar to shardchain blocks of the basic workchain. This section lists some of the modifications needed to obtain the description of a masterchain block from the description of a shardchain block given in 5.1. +Masterchain blocks are very similar to shardchain blocks of the basic workchain. This section lists some of the modifications needed to obtain the description of a masterchain block from the description of a shardchain block given in [5.1](#5-1-shardchain-block-layout). ### 5.2.1. Additional components present in the masterchain state. @@ -2386,9 +2382,9 @@ In addition to the components listed in [5.1.1](#5-1-1-components-of-the-shardch ### 5.2.2. Additional components present in masterchain blocks. -In addition to the components listed in 5.1.2, each masterchain block must contain: +In addition to the components listed in [5.1.2](#5-1-2-components-of-a-shardchain-block), each masterchain block must contain: -* `ShardHashes` — Describes the current shard configuration, and contains the hashes of the latest blocks of the corresponding shardchains. (Notice that this component is also present in the masterchain state.) + * `ShardHashes` — Describes the current shard configuration, and contains the hashes of the latest blocks of the corresponding shardchains. (Notice that this component is also present in the masterchain state.) ### 5.2.3. Description of `ShardHashes`. @@ -2492,7 +2488,7 @@ If cells are listed in a topological order, then the verification that there are The serialization process of a bag of cells **B** consisting of **n** cells can be outlined as follows: 1. List the cells from **B** in a topological order: **c₀**, **c₁**, …, **cₙ₋₁**. Then **c₀** is the root cell of **B**. -2. Choose an integer **s**, such that `n ≤ 2ˢ`. Represent each cell **cᵢ** by an integral number of octets in the standard way (cf. [1.1.3](#1-1-3-the-layout-of-a-single-cell) or [4, 3.1.4](#ref-4)), but using unsigned big-endian **s**-bit integer **j** instead of hash `Hash(cⱼ)` to represent internal references to cell **cⱼ** (cf. [5.3.6](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells)below). +2. Choose an integer **s**, such that `n ≤ 2ˢ`. Represent each cell **cᵢ** by an integral number of octets in the standard way (cf. [1.1.3](#1-1-3-the-layout-of-a-single-cell) or [4](#ref-4), 3.1.4]), but using unsigned big-endian **s**-bit integer **j** instead of hash `Hash(cⱼ)` to represent internal references to cell **cⱼ** (cf. [5.3.6](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) below). 3. Concatenate the representations of cells **cᵢ** thus obtained in the increasing order of **i**. 4. Optionally, an index can be constructed that consists of **n + 1** **t**-bit integer entries **L₀**, …, **Lₙ**, where **Lᵢ** is the total length (in octets) of the representations of cells **cⱼ** with `j ≤ i`, and integer `t ≥ 0` is chosen so that `Lₙ ≤ 2ᵗ`. 5. The serialization of the bag of cells now consists of a magic number indicating the precise format of the serialization, followed by integers `s ≥ 0`, `t ≥ 0`, `n ≤ 2ˢ`, an optional index consisting of `⌈(n+1)t/8⌉` octets, and **Lₙ** octets with the cell representations. @@ -2504,11 +2500,11 @@ If an index is included, any cell **cᵢ** in the serialized bag of cells may be More precisely, each individual cell `c = cᵢ` is serialized as follows, provided `s` is a multiple of eight (usually `s = 8, 16, 24, or 32`): -1. Two descriptor bytes `d₁` and `d₂` are computed similarly to [4, 3.1.4](#ref-4) by setting `d₁ = r + 8s + 16h + 32l` and `d₂ = ⌊b/8⌋ + ⌈b/8⌉`, where: +1. Two descriptor bytes `d₁` and `d₂` are computed similarly to [[4](#ref-4), 3.1.4] by setting `d₁ = r + 8s + 16h + 32l` and `d₂ = ⌊b/8⌋ + ⌈b/8⌉`, where: * `0 ≤ r ≤ 4` is the number of cell references present in cell `c`; if `c` is absent from the bag of cells being serialized and is represented by its hashes only, then `r = 7`.[³⁸](#footnote-38) * `0 ≤ b ≤ 1023` is the number of data bits in cell `c`. - * `0 ≤ l ≤ 3` is the level of cell `c` (cf. [4, 3.1.3](#ref-4)). + * `0 ≤ l ≤ 3` is the level of cell `c` (cf. [[4](#ref-4), 3.1.3]). * `s = 1` for exotic cells and `s = 0` for ordinary cells. * `h = 1` if the cell’s hashes are explicitly included into the serialization; otherwise, `h = 0`. (When `r = 7`, we must always have `h = 1`.) @@ -2516,7 +2512,7 @@ More precisely, each individual cell `c = cᵢ` is serialized as follows, provid 2. Two bytes `d₁` and `d₂` (if `r < 7`) or one byte `d₁` (if `r = 7`) begin the serialization of cell `c`. -3. If `h = 1`, the serialization is continued by `l + 1` 32-byte higher hashes of `c` (cf. [4, 3.1.6](#ref-4)): `Hash₁(c)`, …, `Hash_{l+1}(c) = Hash∞(c)`. +3. If `h = 1`, the serialization is continued by `l + 1` 32-byte higher hashes of `c` (cf. [[4](#ref-4), 3.1.6]): `Hash₁(c)`, …, `Hash_{l+1}(c) = Hash∞(c)`. 4. After that, `⌈b/8⌉` data bytes are serialized, by splitting `b` data bits into 8-bit groups and interpreting each group as a big-endian integer in the range `0 ... 255`. If `b` is not divisible by 8, then the data bits are first augmented by one binary `1` and up to six binary `0`, so as to make the number of data bits divisible by eight.[³⁹](#footnote-39) @@ -3190,11 +3186,10 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the [2] Daniel J. Bernstein, Niels Duif, Tanja Lange et al., *High-speed high-security signatures* (2012), **Journal of Cryptographic Engineering** 2(2), pp. 77–89. Available at: [https://ed25519.cr.yp.to/ed25519-20110926.pdf](https://ed25519.cr.yp.to/ed25519-20110926.pdf). -[3] N. Durov, *Telegram Open Network*, 2017. +[3] N. Durov, [Telegram Open Network*, 2017](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). -[4] N. Durov, *Telegram Open Network Virtual Machine*, 2018. - +[4] N. Durov, [Telegram Open Network Virtual Machine, 2018](https://www.docdroid.net/qY4sQEv/telegram-open-network-blockchain-september-5-2018-pdf). ## Footnotes @@ -3240,7 +3235,7 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **21** One must not only look up the key `Hash(m)` in the `InMsgDescr` of these blocks, but also check the intermediate addresses in the envelope of the corresponding entry, if found. [Back ↑](#2-3-6-checking-whether-an-hr-message-has-already-been-delivered-via-hr-to-its-final-destination-or-an-intermediate-shardchain) -**22** A description of an older version of TL may be found at [https://core.telegram.org/mtproto/TL](https://core.telegram.org/mtproto/TL). Alternatively, an informal introduction to TL-B schemes may be found in [4, 3.3.4](#ref-4). [Back ↑](#3-1-1-some-standard-definitions) +**22** A description of an older version of TL may be found at [https://core.telegram.org/mtproto/TL](https://core.telegram.org/mtproto/TL). Alternatively, an informal introduction to TL-B schemes may be found in [[4](#ref-4), 3.3.4]. [Back ↑](#3-1-1-some-standard-definitions) **23** Address rewriting is a feature used to implement “anycast addresses” employed by the so-called large or global smart contracts (cf. [[3](#ref-3), 2.3.18]), which can have instances in several shardchains. When address rewriting is enabled, a message may be routed to and processed by a smart contract with an address coinciding with the destination address up to the first `d` bits, where `d ≤ 32` is the “splitting depth” indicated in `anycast.depth` (cf. [2.1.7](#2-1-7-internal-routing)). Otherwise, the addresses must match exactly. [Back ↑](#3-1-4-internal-addresses) @@ -3258,9 +3253,9 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **30** This scheme uses anonymous constructors and anonymous fields, both represented by an underscore `_`. [Back ↑](#4-1-6-account-description) -**31** `MERKLE_UPDATE` and exotic cells. A `MERKLE_UPDATE` is a special TL-B constructor whose cell is marked exotic. It carries `old_hash` and `new_hash` (representation hashes of the subtree before/after the update) and may include old/new by reference. Verifiers can validate updates using these hashes with Merkle proofs even if full bodies aren’t inlined. [Back ↑](#4-2-6-bouncing-inbound-messages-to-non-existent-accounts) +**31** In particular, if a user mistakenly sends some funds to a non-existent address in a bounceable message, the funds will not be wasted, but rather will be returned (bounced) back. Therefore, a user wallet application should set the bounce flag in all generated messages by default unless explicitly instructed otherwise. However, non-bounceable messages are indispensable in some situations (cf. [1.7.6](#1-7-6-example%3A-creating-a-cryptocurrency-wallet-smart-contract)) [Back ↑](#4-2-8-reasons-for-splitting-the-processing-into-computation-and-action-phases) -**32** TL-B `_` and `^` syntax. `_` denotes an anonymous field/constructor; `^` means “store under a reference”. Thus the pattern `_:^[ ... ]` means: put the bracketed fields into a separate subcell and store a reference to it instead of inlining. [Back ↑](#4-2-8-reasons-for-splitting-the-processing-into-computation-and-action-phases) +**32** A reference implementation of a TVM emulator running in a stripped-down version of TVM may be committed into the masterchain to be used when a disagreement between the validators on a specific run of TVM arises. In this way, flawed implementations of TVM may be detected. The reference implementation then serves as an authoritative source on the operational semantics of TVM. (Cf. [[4](#ref-4), B.2]) [Back ↑](#4-2-8-reasons-for-splitting-the-processing-into-computation-and-action-phases) **33** Notice that this record does not represent a change in the state of the account, because the transaction may still be aborted during the action phase. In that case, the new persistent data indirectly referenced by `vm_final_state_hash` will be discarded. [Back ↑](#4-3-7-valid-computing-phase) @@ -3272,7 +3267,7 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **37** Arithmetic modulo *p* for a modulus *p* near a power of two can be implemented very efficiently. On the other hand, residues modulo 2²⁵⁵ − 19 can be represented by 255-bit integers. This is the reason this particular value of *p* has been chosen by D. Bernstein. [Back ↑](#5-1-2-components-of-a-shardchain-block) -**38** Notice that these “absent cells” are different from the library reference and external reference cells, which are kinds of exotic cells (cf. [4, 3.1.7](#ref-4)). Absent cells, by contrast, are introduced only for the purpose of serializing incomplete bags of cells, and can never be processed by TVM. [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) +**38** Notice that these “absent cells” are different from the library reference and external reference cells, which are kinds of exotic cells (cf. [[4](#ref-4), 3.1.7]). Absent cells, by contrast, are introduced only for the purpose of serializing incomplete bags of cells, and can never be processed by TVM. [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) **39** Notice that exotic cells (with `s = 1`) always have `b ≥ 8`, with the cell type encoded in the first eight data bits (cf. [4, 3.1.7](#ref-4)). [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) From c20eafe501af4aad5aa0d3b7fdb28b0fe9cf94d8 Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Thu, 9 Oct 2025 02:54:19 +0100 Subject: [PATCH 02/16] fix minor markdown issues --- ton/tblkch.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index e3c08dca..8d18308c 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -3186,7 +3186,7 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the [2] Daniel J. Bernstein, Niels Duif, Tanja Lange et al., *High-speed high-security signatures* (2012), **Journal of Cryptographic Engineering** 2(2), pp. 77–89. Available at: [https://ed25519.cr.yp.to/ed25519-20110926.pdf](https://ed25519.cr.yp.to/ed25519-20110926.pdf). -[3] N. Durov, [Telegram Open Network*, 2017](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). +[3] N. Durov, [Telegram Open Network, 2017](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). [4] N. Durov, [Telegram Open Network Virtual Machine, 2018](https://www.docdroid.net/qY4sQEv/telegram-open-network-blockchain-september-5-2018-pdf). From d1f4c6ee3d0beb7c9128c8b148f9d3adce956c79 Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Thu, 9 Oct 2025 03:21:35 +0100 Subject: [PATCH 03/16] fix link --- ton/tblkch.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index 8d18308c..2f9a96f5 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -1259,7 +1259,7 @@ Notice that the forwarding and transit fees collected from an imported message d Before continuing, let us discuss the serialization of augmented hashmaps, or dictionaries. -Augmented hashmaps are key-value storage structures with `n`-bit keys and values of some type `X`, similar to the ordinary hashmaps described in [4, 3.3](#ref-4). However, each intermediate node of the Patricia tree representing an augmented hashmap is augmented by a value of type `Y`. +Augmented hashmaps are key-value storage structures with `n`-bit keys and values of some type `X`, similar to the ordinary hashmaps described in [[4](#ref-4), 3.3]. However, each intermediate node of the Patricia tree representing an augmented hashmap is augmented by a value of type `Y`. These augmentation values must satisfy certain aggregation conditions. Typically, `Y` is an integer type, and the aggregation condition is that the augmentation value of a fork must equal the sum of the augmentation values of its two children. In general, a fork evaluation function `S : Y × Y → Y` or `S : Y → Y → Y` is used instead of the sum. The augmentation value of a leaf is usually computed from the value stored in that leaf by means of a leaf evaluation function `L : X → Y`. The augmentation value of a leaf may be stored explicitly in the leaf along with the value; however, in most cases there is no need for this, because the leaf evaluation function `L` is very simple. @@ -3199,7 +3199,7 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **3** Completely identical cells are often identified in memory and in disk storage; this is the reason why trees of cells are transparently transformed into DAGs of cells. From this perspective, a DAG is just a storage optimization of the underlying tree of cells, irrelevant for most considerations. [Back ↑](#1-1-1-tvm-cells) - **4** Cf. [4.3.3–4](#ref-4), where an example is given and explained, pending a more complete reference. [Back ↑](#1-1-1-tvm-cells) + **4** Cf. [[4](#ref-4), 3.3.3–4], where an example is given and explained, pending a more complete reference. [Back ↑](#1-1-1-tvm-cells) **5.** If there are no transactions related to an account, the corresponding virtual block is empty and is omitted in the shardchain block. [Back ↑](#1-2-1-the-infinite-sharding-paradigm-isp-applied-to-blockchain-block-and-state) @@ -3269,7 +3269,7 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **38** Notice that these “absent cells” are different from the library reference and external reference cells, which are kinds of exotic cells (cf. [[4](#ref-4), 3.1.7]). Absent cells, by contrast, are introduced only for the purpose of serializing incomplete bags of cells, and can never be processed by TVM. [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) -**39** Notice that exotic cells (with `s = 1`) always have `b ≥ 8`, with the cell type encoded in the first eight data bits (cf. [4, 3.1.7](#ref-4)). [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) +**39** Notice that exotic cells (with `s = 1`) always have `b ≥ 8`, with the cell type encoded in the first eight data bits (cf. [[4](#ref-4), 3.1.7]). [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) **40** If the bag of cells is not complete, some of these cell references may refer to cells `c′` absent from the bag of cells. In that case, special “absent cells” with `r = 7` are included into the bag of cells and are assigned some indices `j`. These indices are then used to represent references to absent cells. [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) From a387642c1c5902b9f5283ed3712190b5126c1341 Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Thu, 9 Oct 2025 15:12:49 +0100 Subject: [PATCH 04/16] some reference link fixes --- ton/tblkch.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index 2f9a96f5..99b80990 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -13,11 +13,11 @@ The aim of this text is to provide a detailed description of the Telegram Open N ## Introduction -This document provides a detailed description of the TON Blockchain, including its precise block format, validity conditions, TON Virtual Machine (TVM) invocation details, smart-contract creation process, and cryptographic signatures. In this respect it is a continuation of the TON whitepaper (cf. [3](#ref-3)), so we freely use the terminology introduced in that document. +This document provides a detailed description of the TON Blockchain, including its precise block format, validity conditions, TON Virtual Machine (TVM) invocation details, smart-contract creation process, and cryptographic signatures. In this respect it is a continuation of the TON whitepaper (cf. [[3]](#ref-3)), so we freely use the terminology introduced in that document. [Chapter 1](#1-overview) provides a general overview of the TON Blockchain and its design principles, with particular attention to the introduction of compatibility and validity conditions and the implementation of message delivery guarantees. More detailed information, such as the TL-B schemes that describe the serialization of all required data structures into trees or collections (“bags”) of cells, is provided in subsequent chapters, culminating in a complete description of the TON Blockchain (shardchain and masterchain) block layout in [Chapter 5](#5-block-layout). -A detailed description of the elliptic curve cryptography used for signing blocks and messages, also accessible through TVM primitives, is provided in [Appendix A](#a-elliptic-curve-cryptography). TVM itself is described in a separate document (cf. [4](#ref-4)). +A detailed description of the elliptic curve cryptography used for signing blocks and messages, also accessible through TVM primitives, is provided in [Appendix A](#a-elliptic-curve-cryptography). TVM itself is described in a separate document (cf. [[4]](#ref-4)). Some subjects have intentionally been left out of this document. One is the Byzantine Fault Tolerant (BFT) protocol used by the validators to determine the next block of the masterchain or a shardchain; that subject is left for a forthcoming document dedicated to the TON Network. @@ -31,11 +31,11 @@ Please note that the current version of this document describes a preliminary te This chapter provides an overview of the main features and design principles of the TON Blockchain. More detail on each topic is provided in subsequent chapters. ## 1.1 Everything is a bag of cells -All data in the blocks and state of the TON Blockchain is represented as a collection of cells (cf. [3](#ref-3), 2.5]. Therefore, this chapter begins with a general discussion of cells. +All data in the blocks and state of the TON Blockchain is represented as a collection of cells (cf. [[3]](#ref-3), 2.5]. Therefore, this chapter begins with a general discussion of cells. ### 1.1.1. TVM cells -Recall that the TON Blockchain, as well as the TON Virtual Machine (TVM; cf. [4](#ref-4)), represents all permanently stored data as a collection or bag of so-called cells. Each cell consists of up to 1023 data bits and up to four references to other cells. Cyclic cell references are not allowed, so the cells are usually organized into trees of cells, or rather directed acyclic graphs (DAGs) of cells.[³](#footnote-3) Any value of an abstract algebraic (dependent) data type may be represented (serialized) as a tree of cells. +Recall that the TON Blockchain, as well as the TON Virtual Machine (TVM; cf. [[4]](#ref-4)), represents all permanently stored data as a collection or bag of so-called cells. Each cell consists of up to 1023 data bits and up to four references to other cells. Cyclic cell references are not allowed, so the cells are usually organized into trees of cells, or rather directed acyclic graphs (DAGs) of cells.[³](#footnote-3) Any value of an abstract algebraic (dependent) data type may be represented (serialized) as a tree of cells. The precise way of representing values of an abstract data type as a tree of cells is expressed by means of a TL-B scheme.[⁴](#footnote-4) A more thorough discussion of different kinds of cells may be found in [[4](#ref-4), 3.1]. ### 1.1.2. Application to TON Blockchain blocks and state @@ -205,7 +205,7 @@ Each transaction is described in the block by an instance of the `Transaction` t * A reference to exactly one inbound message (which must be present in `InMsgDescr` as well) that has been processed by the transaction. * References to several (maybe zero) outbound messages (also present in `OutMsgDescr` and most likely included in `OutMsgQueue`) that have been generated by the transaction. -The transaction consists of an invocation of TVM (cf. [4](#ref-4)) with the code of the smart contract corresponding to the account in question loaded into the virtual machine, and with the data root cell of the smart contract loaded into the virtual machine’s register `c4`. +The transaction consists of an invocation of TVM (cf. [[4]](#ref-4)) with the code of the smart contract corresponding to the account in question loaded into the virtual machine, and with the data root cell of the smart contract loaded into the virtual machine’s register `c4`. The inbound message itself is passed in the stack as an argument to the smart contract’s `main()` function, along with some other important data, such as the amount of TON Grams and other defined currencies attached to the message, the sender account address, the current balance of the smart contract, and so on. @@ -514,7 +514,7 @@ In particular, when we say that a block must import in its `InMsgDescr` the mess ## 1.6 Configurable parameters and smart contracts -Recall that the TON Blockchain has several so-called “configurable parameters” (cf. [3](#ref-3)), which are either certain values or certain smart contracts residing in the masterchain. This section discusses the storage of and access to these configurable parameters. +Recall that the TON Blockchain has several so-called “configurable parameters” (cf. [[3]](#ref-3)), which are either certain values or certain smart contracts residing in the masterchain. This section discusses the storage of and access to these configurable parameters. ### 1.6.1. Examples of configurable parameters The properties of the blockchain controlled by configurable parameters include: @@ -2639,7 +2639,7 @@ The construction of [5.3.11](#5-3-11-merkle-hashes-for-an-octet-string) is appli This appendix contains a formal description of the elliptic curve cryptography currently used in TON, particularly in the TON Blockchain and the TON Network. -TON uses two forms of elliptic curve cryptography: Ed25519 is used for cryptographic Schnorr signatures, while Curve25519 is used for asymmetric cryptography. These curves are used in the standard way (as defined in the original articles [1](#ref-1) and [2](#ref-2) by D. Bernstein and RFCs 7748 and 8032); however, some serialization details specific to TON must be explained. One unique adaptation of these curves for TON is that TON supports automatic conversion of Ed25519 keys into Curve25519 keys, so that the same keys can be used for signatures and for asymmetric cryptography. +TON uses two forms of elliptic curve cryptography: Ed25519 is used for cryptographic Schnorr signatures, while Curve25519 is used for asymmetric cryptography. These curves are used in the standard way (as defined in the original articles [[1]](#ref-1) and [[2]](#ref-2) by D. Bernstein and RFCs 7748 and 8032); however, some serialization details specific to TON must be explained. One unique adaptation of these curves for TON is that TON supports automatic conversion of Ed25519 keys into Curve25519 keys, so that the same keys can be used for signatures and for asymmetric cryptography. ## A.1 Elliptic curves @@ -2814,7 +2814,7 @@ This algorithm for quickly computing `x_[nP]` starting from `x_P` on Montgomery ## A.2 Curve25519 cryptography -This section describes the well-known Curve25519 cryptography proposed by Daniel Bernstein [1](#ref-1) and its usage in TON. +This section describes the well-known Curve25519 cryptography proposed by Daniel Bernstein [[1]](#ref-1) and its usage in TON. ### A.2.1. Curve25519 @@ -2973,7 +2973,7 @@ Notice that the asymmetric Curve25519 cryptography described in [A.2.4](#a-2-4-p # A.3 Ed25519 cryptography -Ed25519 cryptography is extensively used for fast cryptographic signatures by both the TON Blockchain and the TON Network. This section describes the variant of Ed25519 cryptography used by TON. An important difference from the standard approaches (as defined by D. Bernstein et al. in [2](#ref-2)) is that TON provides automatic conversion of private and public Ed25519 keys into Curve25519 keys, so that the same keys could be used both for encrypting/decrypting and for signing messages. +Ed25519 cryptography is extensively used for fast cryptographic signatures by both the TON Blockchain and the TON Network. This section describes the variant of Ed25519 cryptography used by TON. An important difference from the standard approaches (as defined by D. Bernstein et al. in [[2]](#ref-2)) is that TON provides automatic conversion of private and public Ed25519 keys into Curve25519 keys, so that the same keys could be used both for encrypting/decrypting and for signing messages. ## A.3.1. Twisted Edwards curves From bc606673447176aa02ff801e2d7c88a7a1323f9d Mon Sep 17 00:00:00 2001 From: AlexG <39581753+Reveloper@users.noreply.github.com> Date: Fri, 10 Oct 2025 16:42:16 +0900 Subject: [PATCH 05/16] redirect-to-internal-links --- ton/tblkch.mdx | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index 99b80990..ddd71407 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -13,11 +13,11 @@ The aim of this text is to provide a detailed description of the Telegram Open N ## Introduction -This document provides a detailed description of the TON Blockchain, including its precise block format, validity conditions, TON Virtual Machine (TVM) invocation details, smart-contract creation process, and cryptographic signatures. In this respect it is a continuation of the TON whitepaper (cf. [[3]](#ref-3)), so we freely use the terminology introduced in that document. +This document provides a detailed description of the TON Blockchain, including its precise block format, validity conditions, TON Virtual Machine (TVM) invocation details, smart-contract creation process, and cryptographic signatures. In this respect it is a continuation of the TON whitepaper (cf. [[3]](/ton/ton)) [⁴³](#footnote-43), so we freely use the terminology introduced in that document. [Chapter 1](#1-overview) provides a general overview of the TON Blockchain and its design principles, with particular attention to the introduction of compatibility and validity conditions and the implementation of message delivery guarantees. More detailed information, such as the TL-B schemes that describe the serialization of all required data structures into trees or collections (“bags”) of cells, is provided in subsequent chapters, culminating in a complete description of the TON Blockchain (shardchain and masterchain) block layout in [Chapter 5](#5-block-layout). -A detailed description of the elliptic curve cryptography used for signing blocks and messages, also accessible through TVM primitives, is provided in [Appendix A](#a-elliptic-curve-cryptography). TVM itself is described in a separate document (cf. [[4]](#ref-4)). +A detailed description of the elliptic curve cryptography used for signing blocks and messages, also accessible through TVM primitives, is provided in [Appendix A](#a-elliptic-curve-cryptography). TVM itself is described in a separate document (cf. [[4]](/ton/tvm)). Some subjects have intentionally been left out of this document. One is the Byzantine Fault Tolerant (BFT) protocol used by the validators to determine the next block of the masterchain or a shardchain; that subject is left for a forthcoming document dedicated to the TON Network. @@ -31,11 +31,11 @@ Please note that the current version of this document describes a preliminary te This chapter provides an overview of the main features and design principles of the TON Blockchain. More detail on each topic is provided in subsequent chapters. ## 1.1 Everything is a bag of cells -All data in the blocks and state of the TON Blockchain is represented as a collection of cells (cf. [[3]](#ref-3), 2.5]. Therefore, this chapter begins with a general discussion of cells. +All data in the blocks and state of the TON Blockchain is represented as a collection of cells (cf. [[3.2.5]](/ton/ton#2-5-global-shardchain-state-bag-of-cells-philosophy)). Therefore, this chapter begins with a general discussion of cells. ### 1.1.1. TVM cells -Recall that the TON Blockchain, as well as the TON Virtual Machine (TVM; cf. [[4]](#ref-4)), represents all permanently stored data as a collection or bag of so-called cells. Each cell consists of up to 1023 data bits and up to four references to other cells. Cyclic cell references are not allowed, so the cells are usually organized into trees of cells, or rather directed acyclic graphs (DAGs) of cells.[³](#footnote-3) Any value of an abstract algebraic (dependent) data type may be represented (serialized) as a tree of cells. +Recall that the TON Blockchain, as well as the TON Virtual Machine (TVM; cf. [[4]](/ton/tvm)), represents all permanently stored data as a collection or bag of so-called cells. Each cell consists of up to 1023 data bits and up to four references to other cells. Cyclic cell references are not allowed, so the cells are usually organized into trees of cells, or rather directed acyclic graphs (DAGs) of cells.[³](#footnote-3) Any value of an abstract algebraic (dependent) data type may be represented (serialized) as a tree of cells. The precise way of representing values of an abstract data type as a tree of cells is expressed by means of a TL-B scheme.[⁴](#footnote-4) A more thorough discussion of different kinds of cells may be found in [[4](#ref-4), 3.1]. ### 1.1.2. Application to TON Blockchain blocks and state @@ -83,7 +83,7 @@ In particular, the cell references of a cell `c` are completely determined by th Apart from the ordinary cells (also called simple or data cells) considered so far, cells of other types, called exotic cells, sometimes appear in the actual representations of TON Blockchain blocks and other data structures. -Their representation is somewhat different; they are distinguished by having the first descriptor byte `d₁ ≥ 5` (cf. [[4](#ref-4), 3.1]). +Their representation is somewhat different; they are distinguished by having the first descriptor byte `d₁ ≥ 5` (cf. [[4, 3.1]](/ton/tvm#3-1-generalities-on-cells)). ### 1.1.6. External reference cells @@ -205,7 +205,7 @@ Each transaction is described in the block by an instance of the `Transaction` t * A reference to exactly one inbound message (which must be present in `InMsgDescr` as well) that has been processed by the transaction. * References to several (maybe zero) outbound messages (also present in `OutMsgDescr` and most likely included in `OutMsgQueue`) that have been generated by the transaction. -The transaction consists of an invocation of TVM (cf. [[4]](#ref-4)) with the code of the smart contract corresponding to the account in question loaded into the virtual machine, and with the data root cell of the smart contract loaded into the virtual machine’s register `c4`. +The transaction consists of an invocation of TVM (cf. [[4]](/ton/tvm)) with the code of the smart contract corresponding to the account in question loaded into the virtual machine, and with the data root cell of the smart contract loaded into the virtual machine’s register `c4`. The inbound message itself is passed in the stack as an argument to the smart contract’s `main()` function, along with some other important data, such as the amount of TON Grams and other defined currencies attached to the message, the sender account address, the current balance of the smart contract, and so on. @@ -514,7 +514,7 @@ In particular, when we say that a block must import in its `InMsgDescr` the mess ## 1.6 Configurable parameters and smart contracts -Recall that the TON Blockchain has several so-called “configurable parameters” (cf. [[3]](#ref-3)), which are either certain values or certain smart contracts residing in the masterchain. This section discusses the storage of and access to these configurable parameters. +Recall that the TON Blockchain has several so-called “configurable parameters” (cf. [[3]](/ton/ton#2-1-21-configurable-parameters)), which are either certain values or certain smart contracts residing in the masterchain. This section discusses the storage of and access to these configurable parameters. ### 1.6.1. Examples of configurable parameters The properties of the blockchain controlled by configurable parameters include: @@ -1082,13 +1082,13 @@ nanograms$_ amount:(VarUInteger 16) = Grams; If one wants to represent `x` nanograms, one selects an integer `ℓ < 16` such that `x < 2⁸ˡ`, and serializes first `ℓ` as an unsigned 4-bit integer, then `x` itself as an unsigned `8ℓ`-bit integer. Notice that four zero bits represent a zero amount of Grams. -Recall (cf. [[3](#ref-3), A]) that the original total supply of Grams is fixed at five billion (i.e., `5·10¹⁸ < 2⁶³` nanograms), and is expected to grow very slowly. Therefore, all the amounts of Grams encountered in practice will fit in unsigned or even signed 64-bit integers. Validators may use the 64-bit integer representation of Grams in their internal computations; however, serialization of such values in the blockchain is another matter. +Recall (cf. [[3, A](/ton/ton#appendix-a-the-ton-coin)]) that the original total supply of Grams is fixed at five billion (i.e., `5·10¹⁸ < 2⁶³` nanograms), and is expected to grow very slowly. Therefore, all the amounts of Grams encountered in practice will fit in unsigned or even signed 64-bit integers. Validators may use the 64-bit integer representation of Grams in their internal computations; however, serialization of such values in the blockchain is another matter. ### 3.1.6. Representing collections of arbitrary currencies Recall that the TON Blockchain allows its users to define arbitrary cryptocurrencies or tokens apart from the Gram, provided some conditions are met. Such additional cryptocurrencies are identified by 32-bit `currency_id`s. The list of defined additional cryptocurrencies is a part of the blockchain configuration, stored in the masterchain. -When some amounts of one or several such cryptocurrencies need to be represented, a dictionary (cf. [[4](#ref-4), 3.3]) with 32-bit `currency_id`s as keys and `VarUInteger 32` values is used: +When some amounts of one or several such cryptocurrencies need to be represented, a dictionary (cf. [[4](/ton/tvm#3-3-hashmaps%2C-or-dictionaries), 3.3]) with 32-bit `currency_id`s as keys and `VarUInteger 32` values is used: ```c extra_currencies$_ dict:(HashmapE 32 (VarUInteger 32)) @@ -1741,7 +1741,7 @@ old:^X new:^X = MERKLE_UPDATE X; The exclamation mark in the TL-B declaration of a merkle\_update indicates special processing required for such values. In particular, they must be kept in a separate cell, which must be marked as exotic by a bit in its header -(cf. [[4](#ref-4), 3.1]). +(cf. [[4, 3.1]](/ton/tvm#3-1-generalities-on-cells)). A full explanation of the serialization of TransactionDescr, which describes one transaction according to its kind listed in [4.2.4](#4-2-4-kinds-of-transactions), can be found in [4.3](#4-3-transaction-descriptions). @@ -1804,7 +1804,7 @@ The transactions dictionary is sum-augmented by a Grams value, which aggregates the total fees collected from these transactions. In addition to this dictionary, an AccountBlock contains a Merkle update -(cf. [[4](#ref-4), 3.1]) of the total state of the account. If an account did not exist +(cf. [[4, 3.1]](/ton/tvm#3-1-generalities-on-cells)) of the total state of the account. If an account did not exist before the block, its state is represented by an account\_none. ### 4.2.16. Consistency conditions for AccountBlocks. @@ -2244,7 +2244,7 @@ A shardchain block must contain: * `InMsgDescr` and `OutMsgDescr`, the inbound and outbound message descriptors (cf. [3.2.8](#3-2-8-structure-of-inmsgdescr) and [3.3.5](#3-3-5-structure-of-outmsgdescr)).. * `ShardAccountBlocks`, the collection of all transactions processed in the block (cf. [4.2.17](##4-2-17-collection-of-all-transactions-in-a-block)) along with all updates of the states of the accounts assigned to the shard. This is the split part of the shardchain block (cf. [1.2.2](#1-2-2-split-and-non-split-part-of-the-shardchain-block-and-state)). * The value flow, describing the total value imported from the preceding blocks of the same shardchain and from inbound messages, the total value exported by outbound message, the total fees collected by validators, and the total value remaining in the shard. -* A Merkle update (cf. [[4](#ref-4), 3.1]) of the shardchain state. Such a Merkle update contains the hashes of the initial and final shardchain states with respect to the block, along with all new cells of the final state that have been created while processing the block.[³⁷](#footnote-37) +* A Merkle update (cf. [[4, 3.1]](/ton/tvm#3-1-generalities-on-cells)) of the shardchain state. Such a Merkle update contains the hashes of the initial and final shardchain states with respect to the block, along with all new cells of the final state that have been created while processing the block.[³⁷](#footnote-37) ### 5.1.3. Common parts of the block layout for all workchains. @@ -2500,11 +2500,11 @@ If an index is included, any cell **cᵢ** in the serialized bag of cells may be More precisely, each individual cell `c = cᵢ` is serialized as follows, provided `s` is a multiple of eight (usually `s = 8, 16, 24, or 32`): -1. Two descriptor bytes `d₁` and `d₂` are computed similarly to [[4](#ref-4), 3.1.4] by setting `d₁ = r + 8s + 16h + 32l` and `d₂ = ⌊b/8⌋ + ⌈b/8⌉`, where: +1. Two descriptor bytes `d₁` and `d₂` are computed similarly to [[4, 3.1.4]](/ton/tvm#3-1-4-standard-cell-representation) by setting `d₁ = r + 8s + 16h + 32l` and `d₂ = ⌊b/8⌋ + ⌈b/8⌉`, where: * `0 ≤ r ≤ 4` is the number of cell references present in cell `c`; if `c` is absent from the bag of cells being serialized and is represented by its hashes only, then `r = 7`.[³⁸](#footnote-38) * `0 ≤ b ≤ 1023` is the number of data bits in cell `c`. - * `0 ≤ l ≤ 3` is the level of cell `c` (cf. [[4](#ref-4), 3.1.3]). + * `0 ≤ l ≤ 3` is the level of cell `c` (cf. [[4, 3.1.3]](/ton/tvm#3-1-3-the-level-of-a-cell)). * `s = 1` for exotic cells and `s = 0` for ordinary cells. * `h = 1` if the cell’s hashes are explicitly included into the serialization; otherwise, `h = 0`. (When `r = 7`, we must always have `h = 1`.) @@ -2512,7 +2512,7 @@ More precisely, each individual cell `c = cᵢ` is serialized as follows, provid 2. Two bytes `d₁` and `d₂` (if `r < 7`) or one byte `d₁` (if `r = 7`) begin the serialization of cell `c`. -3. If `h = 1`, the serialization is continued by `l + 1` 32-byte higher hashes of `c` (cf. [[4](#ref-4), 3.1.6]): `Hash₁(c)`, …, `Hash_{l+1}(c) = Hash∞(c)`. +3. If `h = 1`, the serialization is continued by `l + 1` 32-byte higher hashes of `c` (cf. [[4, 3.1.6]](/ton/tvm#3-1-6-the-higher-hashes-of-a-cell)): `Hash₁(c)`, …, `Hash_{l+1}(c) = Hash∞(c)`. 4. After that, `⌈b/8⌉` data bytes are serialized, by splitting `b` data bits into 8-bit groups and interpreting each group as a big-endian integer in the range `0 ... 255`. If `b` is not divisible by 8, then the data bits are first augmented by one binary `1` and up to six binary `0`, so as to make the number of data bits divisible by eight.[³⁹](#footnote-39) @@ -3199,7 +3199,7 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **3** Completely identical cells are often identified in memory and in disk storage; this is the reason why trees of cells are transparently transformed into DAGs of cells. From this perspective, a DAG is just a storage optimization of the underlying tree of cells, irrelevant for most considerations. [Back ↑](#1-1-1-tvm-cells) - **4** Cf. [[4](#ref-4), 3.3.3–4], where an example is given and explained, pending a more complete reference. [Back ↑](#1-1-1-tvm-cells) + **4** Cf. [[4, 3.3.3–4]](/ton/tvm#3-3-3-serialization-of-hashmaps), where an example is given and explained, pending a more complete reference. [Back ↑](#1-1-1-tvm-cells) **5.** If there are no transactions related to an account, the corresponding virtual block is empty and is omitted in the shardchain block. [Back ↑](#1-2-1-the-infinite-sharding-paradigm-isp-applied-to-blockchain-block-and-state) @@ -3237,7 +3237,7 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **22** A description of an older version of TL may be found at [https://core.telegram.org/mtproto/TL](https://core.telegram.org/mtproto/TL). Alternatively, an informal introduction to TL-B schemes may be found in [[4](#ref-4), 3.3.4]. [Back ↑](#3-1-1-some-standard-definitions) - **23** Address rewriting is a feature used to implement “anycast addresses” employed by the so-called large or global smart contracts (cf. [[3](#ref-3), 2.3.18]), which can have instances in several shardchains. When address rewriting is enabled, a message may be routed to and processed by a smart contract with an address coinciding with the destination address up to the first `d` bits, where `d ≤ 32` is the “splitting depth” indicated in `anycast.depth` (cf. [2.1.7](#2-1-7-internal-routing)). Otherwise, the addresses must match exactly. [Back ↑](#3-1-4-internal-addresses) + **23** Address rewriting is a feature used to implement “anycast addresses” employed by the so-called large or global smart contracts (cf. [[3](/ton/ton#2-3-18-local-and-global-smart-contracts%3B-smart-contract-instances), 2.3.18]), which can have instances in several shardchains. When address rewriting is enabled, a message may be routed to and processed by a smart contract with an address coinciding with the destination address up to the first `d` bits, where `d ≤ 32` is the “splitting depth” indicated in `anycast.depth` (cf. [2.1.7](#2-1-7-internal-routing)). Otherwise, the addresses must match exactly. [Back ↑](#3-1-4-internal-addresses) **24** The information from the `init` field of an inbound message is used either when the receiving account is uninitialized or frozen with the hash of `StateInit` equal to the one expected by the account, or when the receiving account is active and its code or data is an external hash reference matching the hash received in the `StateInit` of the message. [Back ↑](#3-1-12-deserialization-of-a-message-payload) @@ -3255,7 +3255,7 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **31** In particular, if a user mistakenly sends some funds to a non-existent address in a bounceable message, the funds will not be wasted, but rather will be returned (bounced) back. Therefore, a user wallet application should set the bounce flag in all generated messages by default unless explicitly instructed otherwise. However, non-bounceable messages are indispensable in some situations (cf. [1.7.6](#1-7-6-example%3A-creating-a-cryptocurrency-wallet-smart-contract)) [Back ↑](#4-2-8-reasons-for-splitting-the-processing-into-computation-and-action-phases) -**32** A reference implementation of a TVM emulator running in a stripped-down version of TVM may be committed into the masterchain to be used when a disagreement between the validators on a specific run of TVM arises. In this way, flawed implementations of TVM may be detected. The reference implementation then serves as an authoritative source on the operational semantics of TVM. (Cf. [[4](#ref-4), B.2]) [Back ↑](#4-2-8-reasons-for-splitting-the-processing-into-computation-and-action-phases) +**32** A reference implementation of a TVM emulator running in a stripped-down version of TVM may be committed into the masterchain to be used when a disagreement between the validators on a specific run of TVM arises. In this way, flawed implementations of TVM may be detected. The reference implementation then serves as an authoritative source on the operational semantics of TVM. (Cf. [[4, B.2]](/ton/tvm#b-2-step-function-of-tvm)) [Back ↑](#4-2-8-reasons-for-splitting-the-processing-into-computation-and-action-phases) **33** Notice that this record does not represent a change in the state of the account, because the transaction may still be aborted during the action phase. In that case, the new persistent data indirectly referenced by `vm_final_state_hash` will be discarded. [Back ↑](#4-3-7-valid-computing-phase) @@ -3267,12 +3267,14 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **37** Arithmetic modulo *p* for a modulus *p* near a power of two can be implemented very efficiently. On the other hand, residues modulo 2²⁵⁵ − 19 can be represented by 255-bit integers. This is the reason this particular value of *p* has been chosen by D. Bernstein. [Back ↑](#5-1-2-components-of-a-shardchain-block) -**38** Notice that these “absent cells” are different from the library reference and external reference cells, which are kinds of exotic cells (cf. [[4](#ref-4), 3.1.7]). Absent cells, by contrast, are introduced only for the purpose of serializing incomplete bags of cells, and can never be processed by TVM. [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) +**38** Notice that these “absent cells” are different from the library reference and external reference cells, which are kinds of exotic cells (cf. [[4, 3.1.7]](/ton/tvm#3-1-7-types-of-exotic-cells)). Absent cells, by contrast, are introduced only for the purpose of serializing incomplete bags of cells, and can never be processed by TVM. [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) -**39** Notice that exotic cells (with `s = 1`) always have `b ≥ 8`, with the cell type encoded in the first eight data bits (cf. [[4](#ref-4), 3.1.7]). [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) +**39** Notice that exotic cells (with `s = 1`) always have `b ≥ 8`, with the cell type encoded in the first eight data bits (cf. [[4, 3.1.7]](/ton/tvm#3-1-7-types-of-exotic-cells)). [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) **40** If the bag of cells is not complete, some of these cell references may refer to cells `c′` absent from the bag of cells. In that case, special “absent cells” with `r = 7` are included into the bag of cells and are assigned some indices `j`. These indices are then used to represent references to absent cells. [Back ↑](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) **41** Arithmetic modulo **p** for a modulus **p** near a power of two can be implemented very efficiently. On the other hand, residues modulo **2²⁵⁵ − 19** can be represented by 255-bit integers. This is the reason this particular value of **p** has been chosen by D. Bernstein. [Back ↑](#a-1-1-finite-fields) **42** Actually, D. Bernstein chose `A = 486662` because it is the smallest positive integer `A ≡ 2 (mod 4)` such that both the corresponding Montgomery curve ([31](#a-2-1-curve25519)) over `F_p` for `p = 2^255 − 19` and the quadratic twist of this curve have small cofactors. Such an arrangement avoids the necessity to check whether an x-coordinate `x_P ∈ F_p` of a point `P` defines a point `(x_P, y_P) ∈ F_{p^2}` lying on the Montgomery curve itself or on its quadratic twist. [Back ↑](#a2-curve25519-cryptography) + + **43** The original PDF was referred to early version of the [Telegram Open Network](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). We have redirected these links [3.x.x] to a more up-to-date document — [The Open Network](/ton/ton). [Back ↑](#introduction) From 5773fa39a3facc8d1926fa67c2d1572d95d77a59 Mon Sep 17 00:00:00 2001 From: AlexG <39581753+Reveloper@users.noreply.github.com> Date: Fri, 10 Oct 2025 17:04:12 +0900 Subject: [PATCH 06/16] sync-main --- ton/tblkch.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index a9058bfe..00fab55d 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -1089,7 +1089,7 @@ Recall (cf. [[3, A](/ton/ton#appendix-a-the-ton-coin)]) that the original total Recall that the TON Blockchain allows its users to define arbitrary cryptocurrencies or tokens apart from the Gram, provided some conditions are met. Such additional cryptocurrencies are identified by 32-bit `currency_id`s. The list of defined additional cryptocurrencies is a part of the blockchain configuration, stored in the masterchain. -When some amounts of one or several such cryptocurrencies need to be represented, a dictionary (cf. [[4](/ton/tvm#3-3-hashmaps%2C-or-dictionaries), 3.3]) with 32-bit `currency_id`s as keys and `VarUInteger 32` values is used: +When some amounts of one or several such cryptocurrencies need to be represented, a dictionary (cf. [[4, 3.3]](/ton/tvm#3-3-hashmaps%2C-or-dictionaries)) with 32-bit `currency_id`s as keys and `VarUInteger 32` values is used: ```c extra_currencies$_ dict:(HashmapE 32 (VarUInteger 32)) @@ -3236,9 +3236,9 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **21** One must not only look up the key `Hash(m)` in the `InMsgDescr` of these blocks, but also check the intermediate addresses in the envelope of the corresponding entry, if found. [Back ↑](#2-3-6-checking-whether-an-hr-message-has-already-been-delivered-via-hr-to-its-final-destination-or-an-intermediate-shardchain) -**22** A description of an older version of TL may be found at [https://core.telegram.org/mtproto/TL](https://core.telegram.org/mtproto/TL). Alternatively, an informal introduction to TL-B schemes may be found in [[4](#ref-4), 3.3.4]. [Back ↑](#3-1-1-some-standard-definitions) +**22** A description of an older version of TL may be found at [https://core.telegram.org/mtproto/TL](https://core.telegram.org/mtproto/TL). Alternatively, an informal introduction to TL-B schemes may be found in [[4, 3.3.4]](/ton/tvm#3-3-4-brief-explanation-of-tl-b-schemes). [Back ↑](#3-1-1-some-standard-definitions) - **23** Address rewriting is a feature used to implement “anycast addresses” employed by the so-called large or global smart contracts (cf. [[3](/ton/ton#2-3-18-local-and-global-smart-contracts%3B-smart-contract-instances), 2.3.18]), which can have instances in several shardchains. When address rewriting is enabled, a message may be routed to and processed by a smart contract with an address coinciding with the destination address up to the first `d` bits, where `d ≤ 32` is the “splitting depth” indicated in `anycast.depth` (cf. [2.1.7](#2-1-7-internal-routing)). Otherwise, the addresses must match exactly. [Back ↑](#3-1-4-internal-addresses) + **23** Address rewriting is a feature used to implement “anycast addresses” employed by the so-called large or global smart contracts (cf. [[3, 2.3.18]](/ton/ton#2-3-18-local-and-global-smart-contracts%3B-smart-contract-instances)), which can have instances in several shardchains. When address rewriting is enabled, a message may be routed to and processed by a smart contract with an address coinciding with the destination address up to the first `d` bits, where `d ≤ 32` is the “splitting depth” indicated in `anycast.depth` (cf. [2.1.7](#2-1-7-internal-routing)). Otherwise, the addresses must match exactly. [Back ↑](#3-1-4-internal-addresses) **24** The information from the `init` field of an inbound message is used either when the receiving account is uninitialized or frozen with the hash of `StateInit` equal to the one expected by the account, or when the receiving account is active and its code or data is an external hash reference matching the hash received in the `StateInit` of the message. [Back ↑](#3-1-12-deserialization-of-a-message-payload) From c0b83d7d7f6f050ddc0e0bbd779bd2dc67f17afb Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Fri, 10 Oct 2025 10:07:48 +0100 Subject: [PATCH 07/16] update the remaining links to tvm pdf --- ton/tblkch.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index 00fab55d..d513b7e2 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -37,7 +37,7 @@ All data in the blocks and state of the TON Blockchain is represented as a colle ### 1.1.1. TVM cells Recall that the TON Blockchain, as well as the TON Virtual Machine (TVM; cf. [[4]](/ton/tvm)), represents all permanently stored data as a collection or bag of so-called cells. Each cell consists of up to 1023 data bits and up to four references to other cells. Cyclic cell references are not allowed, so the cells are usually organized into trees of cells, or rather directed acyclic graphs (DAGs) of cells.[³](#footnote-3) Any value of an abstract algebraic (dependent) data type may be represented (serialized) as a tree of cells. -The precise way of representing values of an abstract data type as a tree of cells is expressed by means of a TL-B scheme.[⁴](#footnote-4) A more thorough discussion of different kinds of cells may be found in [[4](#ref-4), 3.1]. +The precise way of representing values of an abstract data type as a tree of cells is expressed by means of a TL-B scheme.[⁴](#footnote-4) A more thorough discussion of different kinds of cells may be found in [[4, 3.1](/ton/tvm#3-1-generalities-on-cells)]. ### 1.1.2. Application to TON Blockchain blocks and state The above is particularly applicable to the blocks and state of the TON Blockchain, which also are values of certain (quite convoluted) dependent algebraic data types. @@ -111,7 +111,7 @@ Signatures are an excellent example of the application of representation hashes. ### 1.1.10. Higher hashes of a cell -In addition to the transparent and representation hashes of a cell `c`, a sequence of higher hashes `Hashᵢ(c)`, `i = 1, 2, ...` may be defined, which eventually stabilizes at `Hash∞(c)`. (More detail may be found in [[4](#ref-4), 3.1]. +In addition to the transparent and representation hashes of a cell `c`, a sequence of higher hashes `Hashᵢ(c)`, `i = 1, 2, ...` may be defined, which eventually stabilizes at `Hash∞(c)`. (More detail may be found in [[4, 3.1](/ton/tvm#3-1-generalities-on-cells)]. --- @@ -189,7 +189,7 @@ In both cases, the reason for the removal of a message from the `OutMsgQueue` is ### 1.2.8. Layout of InMsgDescr, OutMsgDescr and OutMsgQueue -All of the most important non-split shardchain data structures related to messages are organized as hashmaps or dictionaries (implemented by means of Patricia trees serialized into a tree of cells as described in [[4](#ref-4), 3.3], with the following keys: +All of the most important non-split shardchain data structures related to messages are organized as hashmaps or dictionaries (implemented by means of Patricia trees serialized into a tree of cells as described in [[4, 3.3](#3-3-hashmaps%2C-or-dictionaries)], with the following keys: * The inbound message description `InMsgDescr` uses the 256-bit message hash as a key. * The outbound message description `OutMsgDescr` uses the 256-bit message hash as a key. @@ -1260,13 +1260,13 @@ Notice that the forwarding and transit fees collected from an imported message d Before continuing, let us discuss the serialization of augmented hashmaps, or dictionaries. -Augmented hashmaps are key-value storage structures with `n`-bit keys and values of some type `X`, similar to the ordinary hashmaps described in [[4](#ref-4), 3.3]. However, each intermediate node of the Patricia tree representing an augmented hashmap is augmented by a value of type `Y`. +Augmented hashmaps are key-value storage structures with `n`-bit keys and values of some type `X`, similar to the ordinary hashmaps described in [[4, 3.3](#3-3-hashmaps%2C-or-dictionaries)]. However, each intermediate node of the Patricia tree representing an augmented hashmap is augmented by a value of type `Y`. These augmentation values must satisfy certain aggregation conditions. Typically, `Y` is an integer type, and the aggregation condition is that the augmentation value of a fork must equal the sum of the augmentation values of its two children. In general, a fork evaluation function `S : Y × Y → Y` or `S : Y → Y → Y` is used instead of the sum. The augmentation value of a leaf is usually computed from the value stored in that leaf by means of a leaf evaluation function `L : X → Y`. The augmentation value of a leaf may be stored explicitly in the leaf along with the value; however, in most cases there is no need for this, because the leaf evaluation function `L` is very simple. ### 3.2.6. Serialization of augmented hashmaps -The serialization of augmented hashmaps with `n`-bit keys, values of type `X`, and augmentation values of type `Y` is given by the following TL-B scheme, which is an extension of the one provided in [[4](#ref-4), 3.3.3] +The serialization of augmented hashmaps with `n`-bit keys, values of type `X`, and augmentation values of type `Y` is given by the following TL-B scheme, which is an extension of the one provided in [[4, 3.3.3](#3-3-hashmaps%2C-or-dictionaries)] ```tlb ahm_edge#_ {n:#} {X:Type} {Y:Type} {l:#} {m:#} @@ -2489,7 +2489,7 @@ If cells are listed in a topological order, then the verification that there are The serialization process of a bag of cells **B** consisting of **n** cells can be outlined as follows: 1. List the cells from **B** in a topological order: **c₀**, **c₁**, …, **cₙ₋₁**. Then **c₀** is the root cell of **B**. -2. Choose an integer **s**, such that `n ≤ 2ˢ`. Represent each cell **cᵢ** by an integral number of octets in the standard way (cf. [1.1.3](#1-1-3-the-layout-of-a-single-cell) or [4](#ref-4), 3.1.4]), but using unsigned big-endian **s**-bit integer **j** instead of hash `Hash(cⱼ)` to represent internal references to cell **cⱼ** (cf. [5.3.6](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) below). +2. Choose an integer **s**, such that `n ≤ 2ˢ`. Represent each cell **cᵢ** by an integral number of octets in the standard way (cf. [1.1.3](#1-1-3-the-layout-of-a-single-cell) or [4, 3.1.4](#3-1-4-standard-cell-representation)), but using unsigned big-endian **s**-bit integer **j** instead of hash `Hash(cⱼ)` to represent internal references to cell **cⱼ** (cf. [5.3.6](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) below). 3. Concatenate the representations of cells **cᵢ** thus obtained in the increasing order of **i**. 4. Optionally, an index can be constructed that consists of **n + 1** **t**-bit integer entries **L₀**, …, **Lₙ**, where **Lᵢ** is the total length (in octets) of the representations of cells **cⱼ** with `j ≤ i`, and integer `t ≥ 0` is chosen so that `Lₙ ≤ 2ᵗ`. 5. The serialization of the bag of cells now consists of a magic number indicating the precise format of the serialization, followed by integers `s ≥ 0`, `t ≥ 0`, `n ≤ 2ˢ`, an optional index consisting of `⌈(n+1)t/8⌉` octets, and **Lₙ** octets with the cell representations. From 8d65f79e019cca386037e07faba82497f0c42a5d Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Fri, 10 Oct 2025 10:15:29 +0100 Subject: [PATCH 08/16] crosslink to the tvm --- ton/tblkch.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index d513b7e2..c03855d1 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -32,7 +32,7 @@ Please note that the current version of this document describes a preliminary te This chapter provides an overview of the main features and design principles of the TON Blockchain. More detail on each topic is provided in subsequent chapters. ## 1.1 Everything is a bag of cells -All data in the blocks and state of the TON Blockchain is represented as a collection of cells (cf. [[3.2.5]](/ton/ton#2-5-global-shardchain-state-bag-of-cells-philosophy)). Therefore, this chapter begins with a general discussion of cells. +All data in the blocks and state of the TON Blockchain is represented as a collection of cells (cf. [[3, 2.5]](/ton/ton#2-5-global-shardchain-state-bag-of-cells-philosophy)). Therefore, this chapter begins with a general discussion of cells. ### 1.1.1. TVM cells @@ -515,7 +515,7 @@ In particular, when we say that a block must import in its `InMsgDescr` the mess ## 1.6 Configurable parameters and smart contracts -Recall that the TON Blockchain has several so-called “configurable parameters” (cf. [[3]](/ton/ton#2-1-21-configurable-parameters)), which are either certain values or certain smart contracts residing in the masterchain. This section discusses the storage of and access to these configurable parameters. +Recall that the TON Blockchain has several so-called “configurable parameters” (cf. [[3, 2.1.21]](/ton/ton#2-1-21-configurable-parameters)), which are either certain values or certain smart contracts residing in the masterchain. This section discusses the storage of and access to these configurable parameters. ### 1.6.1. Examples of configurable parameters The properties of the blockchain controlled by configurable parameters include: From 06328c7fc49c76ddee357aa519edee2b2ee5438b Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Fri, 10 Oct 2025 11:46:54 +0100 Subject: [PATCH 09/16] update footnote --- ton/tblkch.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index c03855d1..99879351 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -3278,4 +3278,4 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **42** Actually, D. Bernstein chose `A = 486662` because it is the smallest positive integer `A ≡ 2 (mod 4)` such that both the corresponding Montgomery curve ([31](#a-2-1-curve25519)) over `F_p` for `p = 2^255 − 19` and the quadratic twist of this curve have small cofactors. Such an arrangement avoids the necessity to check whether an x-coordinate `x_P ∈ F_p` of a point `P` defines a point `(x_P, y_P) ∈ F_{p^2}` lying on the Montgomery curve itself or on its quadratic twist. [Back ↑](#a2-curve25519-cryptography) - **43** The original PDF was referred to early version of the [Telegram Open Network](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). We have redirected these links [3.x.x] to a more up-to-date document — [The Open Network](/ton/ton). [Back ↑](#introduction) + **43** The original PDF was referred to early version of the [Telegram Open Network](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). We have redirected links **[3.x.x]** to the more up-to-date [The Open Network](/ton/ton), and links **[4.x.x]** to the [TVM](/ton/tvm). [Back ↑](#introduction) \ No newline at end of file From a685277ea7a497307e3d415ac690f45f33d07d20 Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Fri, 10 Oct 2025 12:04:37 +0100 Subject: [PATCH 10/16] crosschecked links --- ton/tblkch.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index 99879351..f3dfab85 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -189,7 +189,7 @@ In both cases, the reason for the removal of a message from the `OutMsgQueue` is ### 1.2.8. Layout of InMsgDescr, OutMsgDescr and OutMsgQueue -All of the most important non-split shardchain data structures related to messages are organized as hashmaps or dictionaries (implemented by means of Patricia trees serialized into a tree of cells as described in [[4, 3.3](#3-3-hashmaps%2C-or-dictionaries)], with the following keys: +All of the most important non-split shardchain data structures related to messages are organized as hashmaps or dictionaries (implemented by means of Patricia trees serialized into a tree of cells as described in [[4, 3.3](/ton/tvm#3-3-hashmaps%2C-or-dictionaries)], with the following keys: * The inbound message description `InMsgDescr` uses the 256-bit message hash as a key. * The outbound message description `OutMsgDescr` uses the 256-bit message hash as a key. @@ -1260,13 +1260,13 @@ Notice that the forwarding and transit fees collected from an imported message d Before continuing, let us discuss the serialization of augmented hashmaps, or dictionaries. -Augmented hashmaps are key-value storage structures with `n`-bit keys and values of some type `X`, similar to the ordinary hashmaps described in [[4, 3.3](#3-3-hashmaps%2C-or-dictionaries)]. However, each intermediate node of the Patricia tree representing an augmented hashmap is augmented by a value of type `Y`. +Augmented hashmaps are key-value storage structures with `n`-bit keys and values of some type `X`, similar to the ordinary hashmaps described in [[4, 3.3](/ton/tvm#3-3-hashmaps%2C-or-dictionaries)]. However, each intermediate node of the Patricia tree representing an augmented hashmap is augmented by a value of type `Y`. These augmentation values must satisfy certain aggregation conditions. Typically, `Y` is an integer type, and the aggregation condition is that the augmentation value of a fork must equal the sum of the augmentation values of its two children. In general, a fork evaluation function `S : Y × Y → Y` or `S : Y → Y → Y` is used instead of the sum. The augmentation value of a leaf is usually computed from the value stored in that leaf by means of a leaf evaluation function `L : X → Y`. The augmentation value of a leaf may be stored explicitly in the leaf along with the value; however, in most cases there is no need for this, because the leaf evaluation function `L` is very simple. ### 3.2.6. Serialization of augmented hashmaps -The serialization of augmented hashmaps with `n`-bit keys, values of type `X`, and augmentation values of type `Y` is given by the following TL-B scheme, which is an extension of the one provided in [[4, 3.3.3](#3-3-hashmaps%2C-or-dictionaries)] +The serialization of augmented hashmaps with `n`-bit keys, values of type `X`, and augmentation values of type `Y` is given by the following TL-B scheme, which is an extension of the one provided in [[4, 3.3.3](/ton/tvm#3-3-3-serialization-of-hashmaps)] ```tlb ahm_edge#_ {n:#} {X:Type} {Y:Type} {l:#} {m:#} From 0955decdcaa55fa8e31ac2222843ab0636a7c4f4 Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Fri, 10 Oct 2025 15:38:46 +0100 Subject: [PATCH 11/16] vale fixes --- .vale/config/vocabularies/Custom/accept.txt | 3 +++ ton/tblkch.mdx | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.vale/config/vocabularies/Custom/accept.txt b/.vale/config/vocabularies/Custom/accept.txt index fb55bfe1..259aa629 100644 --- a/.vale/config/vocabularies/Custom/accept.txt +++ b/.vale/config/vocabularies/Custom/accept.txt @@ -17,6 +17,8 @@ Altcoin Andrey Avacoin Axios +anin +account_none Basechain Binance Birman @@ -840,6 +842,7 @@ tracebacks trie truthy ts +ns tsUSDe TVM TVM's diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index f3dfab85..26bbf629 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -3278,4 +3278,4 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **42** Actually, D. Bernstein chose `A = 486662` because it is the smallest positive integer `A ≡ 2 (mod 4)` such that both the corresponding Montgomery curve ([31](#a-2-1-curve25519)) over `F_p` for `p = 2^255 − 19` and the quadratic twist of this curve have small cofactors. Such an arrangement avoids the necessity to check whether an x-coordinate `x_P ∈ F_p` of a point `P` defines a point `(x_P, y_P) ∈ F_{p^2}` lying on the Montgomery curve itself or on its quadratic twist. [Back ↑](#a2-curve25519-cryptography) - **43** The original PDF was referred to early version of the [Telegram Open Network](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). We have redirected links **[3.x.x]** to the more up-to-date [The Open Network](/ton/ton), and links **[4.x.x]** to the [TVM](/ton/tvm). [Back ↑](#introduction) \ No newline at end of file + **43** The original PDF was referred to early version of the [Telegram Open Network](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). We have redirected links [3.x.x] to the updated document [The Open Network](/ton/ton), and links [4.x.x] to the [TVM](/ton/tvm). [Back ↑](#introduction) \ No newline at end of file From 03f92ec7d86bf0af2f4849f28dd044596a1f4aa1 Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Fri, 10 Oct 2025 16:17:51 +0100 Subject: [PATCH 12/16] add aside callout block --- ton/tblkch.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index 26bbf629..e15523a9 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -12,6 +12,11 @@ description: "Whitepaper by Dr. Nikolai Durov" The aim of this text is to provide a detailed description of the Telegram Open Network (TON) Blockchain. + + ## Introduction This document provides a detailed description of the TON Blockchain, including its precise block format, validity conditions, TON Virtual Machine (TVM) invocation details, smart-contract creation process, and cryptographic signatures. In this respect it is a continuation of the TON whitepaper (cf. [[3]](/ton/ton)) [⁴³](#footnote-43), so we freely use the terminology introduced in that document. From 0148111ed3926e45b3ebe99d0ca524f71eceb882 Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Fri, 10 Oct 2025 16:35:39 +0100 Subject: [PATCH 13/16] remove footnote --- ton/tblkch.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index e15523a9..480d96ef 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -19,7 +19,7 @@ We have redirected links **[3.x.x]** to the updated document — [The Open Netwo ## Introduction -This document provides a detailed description of the TON Blockchain, including its precise block format, validity conditions, TON Virtual Machine (TVM) invocation details, smart-contract creation process, and cryptographic signatures. In this respect it is a continuation of the TON whitepaper (cf. [[3]](/ton/ton)) [⁴³](#footnote-43), so we freely use the terminology introduced in that document. +This document provides a detailed description of the TON Blockchain, including its precise block format, validity conditions, TON Virtual Machine (TVM) invocation details, smart-contract creation process, and cryptographic signatures. In this respect it is a continuation of the TON whitepaper (cf. [[3]](/ton/ton)), so we freely use the terminology introduced in that document. [Chapter 1](#1-overview) provides a general overview of the TON Blockchain and its design principles, with particular attention to the introduction of compatibility and validity conditions and the implementation of message delivery guarantees. More detailed information, such as the TL-B schemes that describe the serialization of all required data structures into trees or collections (“bags”) of cells, is provided in subsequent chapters, culminating in a complete description of the TON Blockchain (shardchain and masterchain) block layout in [Chapter 5](#5-block-layout). From 18e51a1f6ab1d7fa92cc374a8838f056c653100f Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Fri, 10 Oct 2025 16:43:32 +0100 Subject: [PATCH 14/16] add import field --- ton/tblkch.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index 480d96ef..3132be9f 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -4,6 +4,8 @@ sidebarTitle: "TON Blockchain" description: "Whitepaper by Dr. Nikolai Durov" --- +import { Aside } from '/snippets/aside.jsx'; + **Authors**: Nikolai Durov
**Date**: February 8, 2020
: [Original whitepaper, PDF](/resources/pdfs/tblkch.pdf) @@ -3283,4 +3285,4 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **42** Actually, D. Bernstein chose `A = 486662` because it is the smallest positive integer `A ≡ 2 (mod 4)` such that both the corresponding Montgomery curve ([31](#a-2-1-curve25519)) over `F_p` for `p = 2^255 − 19` and the quadratic twist of this curve have small cofactors. Such an arrangement avoids the necessity to check whether an x-coordinate `x_P ∈ F_p` of a point `P` defines a point `(x_P, y_P) ∈ F_{p^2}` lying on the Montgomery curve itself or on its quadratic twist. [Back ↑](#a2-curve25519-cryptography) - **43** The original PDF was referred to early version of the [Telegram Open Network](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). We have redirected links [3.x.x] to the updated document [The Open Network](/ton/ton), and links [4.x.x] to the [TVM](/ton/tvm). [Back ↑](#introduction) \ No newline at end of file + **43** The original PDF was referred to early version of the [Telegram Open Network](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). We have redirected links [3.x.x] to the updated document [The Open Network](/ton/ton), and links [4.x.x] to the [TVM](/ton/tvm). [Back ↑](#introduction) From 70fe6768c22475849e1a57024a00a987da1d8d24 Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Mon, 13 Oct 2025 14:41:57 +0100 Subject: [PATCH 15/16] Update tblkch.mdx --- ton/tblkch.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index 3132be9f..b836f7b4 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -16,7 +16,7 @@ The aim of this text is to provide a detailed description of the Telegram Open N ## Introduction From 3b6dca650953e10350c4c80471dea5222dc6976e Mon Sep 17 00:00:00 2001 From: Favour Kelvin Date: Mon, 13 Oct 2025 14:46:04 +0100 Subject: [PATCH 16/16] Update tblkch.mdx --- ton/tblkch.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/ton/tblkch.mdx b/ton/tblkch.mdx index b836f7b4..d081cbb8 100644 --- a/ton/tblkch.mdx +++ b/ton/tblkch.mdx @@ -2496,7 +2496,7 @@ If cells are listed in a topological order, then the verification that there are The serialization process of a bag of cells **B** consisting of **n** cells can be outlined as follows: 1. List the cells from **B** in a topological order: **c₀**, **c₁**, …, **cₙ₋₁**. Then **c₀** is the root cell of **B**. -2. Choose an integer **s**, such that `n ≤ 2ˢ`. Represent each cell **cᵢ** by an integral number of octets in the standard way (cf. [1.1.3](#1-1-3-the-layout-of-a-single-cell) or [4, 3.1.4](#3-1-4-standard-cell-representation)), but using unsigned big-endian **s**-bit integer **j** instead of hash `Hash(cⱼ)` to represent internal references to cell **cⱼ** (cf. [5.3.6](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) below). +2. Choose an integer **s**, such that `n ≤ 2ˢ`. Represent each cell **cᵢ** by an integral number of octets in the standard way (cf. [1.1.3](#1-1-3-the-layout-of-a-single-cell) or [4, 3.1.4](/ton/tvm#3-1-4-standard-cell-representation)), but using unsigned big-endian **s**-bit integer **j** instead of hash `Hash(cⱼ)` to represent internal references to cell **cⱼ** (cf. [5.3.6](#5-3-6-serialization-of-one-cell-from-a-bag-of-cells) below). 3. Concatenate the representations of cells **cᵢ** thus obtained in the increasing order of **i**. 4. Optionally, an index can be constructed that consists of **n + 1** **t**-bit integer entries **L₀**, …, **Lₙ**, where **Lᵢ** is the total length (in octets) of the representations of cells **cⱼ** with `j ≤ i`, and integer `t ≥ 0` is chosen so that `Lₙ ≤ 2ᵗ`. 5. The serialization of the bag of cells now consists of a magic number indicating the precise format of the serialization, followed by integers `s ≥ 0`, `t ≥ 0`, `n ≤ 2ˢ`, an optional index consisting of `⌈(n+1)t/8⌉` octets, and **Lₙ** octets with the cell representations. @@ -3284,5 +3284,3 @@ In order to verify signature `(Ṙ,s)` of a message *M*, supposedly made by the **41** Arithmetic modulo **p** for a modulus **p** near a power of two can be implemented very efficiently. On the other hand, residues modulo **2²⁵⁵ − 19** can be represented by 255-bit integers. This is the reason this particular value of **p** has been chosen by D. Bernstein. [Back ↑](#a-1-1-finite-fields) **42** Actually, D. Bernstein chose `A = 486662` because it is the smallest positive integer `A ≡ 2 (mod 4)` such that both the corresponding Montgomery curve ([31](#a-2-1-curve25519)) over `F_p` for `p = 2^255 − 19` and the quadratic twist of this curve have small cofactors. Such an arrangement avoids the necessity to check whether an x-coordinate `x_P ∈ F_p` of a point `P` defines a point `(x_P, y_P) ∈ F_{p^2}` lying on the Montgomery curve itself or on its quadratic twist. [Back ↑](#a2-curve25519-cryptography) - - **43** The original PDF was referred to early version of the [Telegram Open Network](https://www.editionmultimedia.fr/wp-content/uploads/2019/10/Telegram-Open-Network-2017.pdf). We have redirected links [3.x.x] to the updated document [The Open Network](/ton/ton), and links [4.x.x] to the [TVM](/ton/tvm). [Back ↑](#introduction)