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 df1dd939..00e1b0bf 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) @@ -12,13 +14,18 @@ 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](#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]](/ton/ton)), 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]](/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. @@ -32,15 +39,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, 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.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]](/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, 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. @@ -87,7 +91,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, 3.1]](/ton/tvm#3-1-generalities-on-cells)). ### 1.1.6. External reference cells @@ -114,7 +118,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, 3.1](/ton/tvm#3-1-generalities-on-cells)]. --- @@ -192,7 +196,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, 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. @@ -209,7 +213,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]](/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. @@ -518,7 +522,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, 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: @@ -1086,13 +1090,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, 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, 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, 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)) @@ -1263,13 +1267,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](#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, 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](#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, 3.3.3](/ton/tvm#3-3-3-serialization-of-hashmaps)] ```tlb ahm_edge#_ {n:#} {X:Type} {Y:Type} {l:#} {m:#} @@ -1745,7 +1749,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, 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). @@ -1808,7 +1812,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, 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. @@ -2221,7 +2225,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 @@ -2236,7 +2240,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. @@ -2246,9 +2250,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, 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. @@ -2366,15 +2370,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. @@ -2387,9 +2390,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`. @@ -2493,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](#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, 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. @@ -2505,11 +2508,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, 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, 3.1.3](#ref-4)). + * `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`.) @@ -2517,7 +2520,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, 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) @@ -2644,7 +2647,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 @@ -2819,7 +2822,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 @@ -2978,7 +2981,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 @@ -3191,11 +3194,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 @@ -3205,7 +3207,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, 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) @@ -3241,9 +3243,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, 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, 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](#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, 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) @@ -3259,9 +3261,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, 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) @@ -3273,9 +3275,9 @@ 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, 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, 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, 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)