Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

feat: add cross-linking to ton whitepaper#1435

Draft
fakela wants to merge 10 commits into
main from
crosslinking-ton
Draft

feat: add cross-linking to ton whitepaper #1435
fakela wants to merge 10 commits into
main from
crosslinking-ton

Conversation

@fakela

@fakela fakela commented Nov 26, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

Closes #1393

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update; I left one inline suggestion in foundations/whitepapers/ton.mdx: please apply the inline suggestion to align with the style guide.

Comment thread foundations/whitepapers/ton.mdx Outdated
@fakela fakela marked this pull request as ready for review December 11, 2025 16:21

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the detailed TON whitepaper updates. In foundations/whitepapers/ton.mdx I have several suggestions around anchors, cross-references, and wording—please apply the inline suggestions.

Comment thread foundations/whitepapers/ton.mdx
Comment thread foundations/whitepapers/ton.mdx Outdated

- A distributed file storage technology (*TON Storage*; cf. [4.1.8](#4-1-8-example%3A-keeping-files-off-chain%3B-ton-storage)), accessible through *TON Network*, used by the TON Blockchain to store archive copies of blocks and status data (snapshots), but also available for storing arbitrary files for users or other services running on the platform, with torrent-like access technology.
- A [distributed file storage](#4-1-8-example:-keeping-files-off-chain;-ton-storage) technology (*TON Storage*), accessible through *TON Network*, used by the TON Blockchain to store archive copies of blocks and status data (snapshots), but also available for storing arbitrary files for users or other services running on the platform, with torrent-like access technology.

@github-actions github-actions Bot Dec 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Malformed TON Storage anchor slug

The TON Storage bullet now links to #4-1-8-example:-keeping-files-off-chain;-ton-storage, which includes a colon and semicolon in the slug. The referenced heading is #### 4.1.8. Example: keeping files off-chain; TON Storage, whose generated ID under common slug rules will drop punctuation characters, yielding a form like 4-1-8-example-keeping-files-off-chain-ton-storage. Because the link slug retains punctuation that is not present in the heading ID, it is at high risk of not matching the actual anchor. This breaks intra-page navigation from the top-level description of TON components to the detailed TON Storage section.

Suggested change
- A [distributed file storage](#4-1-8-example:-keeping-files-off-chain;-ton-storage) technology (*TON Storage*), accessible through *TON Network*, used by the TON Blockchain to store archive copies of blocks and status data (snapshots), but also available for storing arbitrary files for users or other services running on the platform, with torrent-like access technology.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

Comment thread foundations/whitepapers/ton.mdx Outdated

- A Kademlia-like distributed hash table (*TON DHT*; cf. [3.2](#3-2-ton-dht%3A-kademlia-like-distributed-hash-table)), used as a "torrent tracker" for *TON Storage* (cf. [3.2.10](#3-2-10-distributed-"torrent-trackers"-and-"network-interest-groups"-in-ton-dht)), as an "input tunnel locator" for *TON Proxy* (cf. [3.2.14](#3-2-14-locating-abstract-addresses)), and as a service locator for *TON Services* (cf. [3.2.12](#3-2-12-locating-services)).
- A [Kademlia-like distributed hash table](#3-2-ton-dht%3A-kademlia-like-distributed-hash-table (*TON DHT*), used as a [torrent tracker](#3-2-10-distributed-"torrent-trackers"-and-"network-interest-groups"-in-ton-dht)for *TON Storage* as an [input tunnel locator](#3-2-14-locating-abstract-addresses) for *TON Proxy*, and as a [service locator](#3-2-12-locating-services) for *TON Services*.

@github-actions github-actions Bot Dec 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Malformed TON DHT and related internal links

The TON DHT bullet line currently has a malformed Markdown link and several brittle anchor slugs. The first link is [Kademlia-like distributed hash table](#3-2-ton-dht%3A-kademlia-like-distributed-hash-table (*TON DHT*), ... which is missing a closing parenthesis for the link and thereby breaks the Markdown structure for the entire line. In addition, the slug uses a percent-encoded colon (%3A) and the nested links for "torrent trackers" and "network interest groups" use curly-quoted, punctuation-heavy slugs; these do not cleanly correspond to the section headings such as #### 3.2.10. Distributed "torrent trackers" and "network interest groups" in TON DHT, whose IDs are normally normalized to plain ASCII text (for example, 3-2-10-distributed-torrent-trackers-and-network-interest-groups-in-ton-dht). As written, this line both breaks rendering and likely produces non-functional anchors for several core DHT sections.

Suggested change
- A [Kademlia-like distributed hash table](#3-2-ton-dht%3A-kademlia-like-distributed-hash-table (*TON DHT*), used as a [torrent tracker](#3-2-10-distributed-"torrent-trackers"-and-"network-interest-groups"-in-ton-dht) for *TON Storage* as an [input tunnel locator](#3-2-14-locating-abstract-addresses) for *TON Proxy*, and as a [service locator](#3-2-12-locating-services) for *TON Services*.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

Comment thread foundations/whitepapers/ton.mdx Outdated
@@ -268,11 +268,11 @@ $$
\text{Blockchain} \equiv \Sigma_{(\mathbb{B} : \text{Block}^*)} \text{isValidBc}(\mathbb{B}) \tag{2}
$$

We use here the notation for dependent sums of types borrowed from \[[16](#ref-16)].
We use here the notation for dependent sums of types borrowed from \<sup>[[16]](#references)</sup>.

@github-actions github-actions Bot Dec 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Escaped footnote <sup> markup

The sentence introducing dependent sums ends with \\<sup>[[16]](#references)</sup>, where the leading < is escaped. This causes the superscript footnote reference to render as literal text instead of HTML/MDX markup. The regression appears only in the modified line and disrupts the reference to the Homotopy Type Theory source in a definitional equation.

Suggested change
We use here the notation for dependent sums of types borrowed from \<sup>[[16]](#references)</sup>.
We use here the notation for dependent sums of types borrowed from <sup>[[16]](#references)</sup>.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

Comment thread foundations/whitepapers/ton.mdx Outdated

This raw value format may be used to implement arbitrary sum-product algebraic types. In this case, the value would contain a raw byte first, describing the constructor being used (from the perspective of a high-level language), and then other fields or constructor arguments, consisting of raw bytes and references to other structures depending on the constructor chosen (cf. [2.2.5](#2-2-5-tl%2C-or-the-type-language)). However, TVM does not know anything about the correspondence between constructors and their arguments; the mixture of bytes and references is explicitly described by certain descriptor bytes.<sup>[8](#fn8)</sup>
This raw value format may be used to implement arbitrary sum-product algebraic types. In this case, the value would contain a raw byte first, describing the constructor being used (from the perspective of a high-level language), and then other fields or constructor arguments, consisting of raw bytes and references to other structures depending on the [constructor](#2-2-5-tl,-or-the-type-language) chosen. However, TVM does not know anything about the correspondence between constructors and their arguments; the mixture of bytes and references is explicitly described by certain descriptor bytes.<a id="ref-fn8"></a><sup>[8](#fn8)</sup>

@github-actions github-actions Bot Dec 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Incorrect TL constructor anchor slug

In the description of the TVM value format, the link on "constructor" uses the anchor #2-2-5-tl,-or-the-type-language, inserting a comma into the slug. Elsewhere in the document, references to the same section use the canonical #2-2-5-tl-or-the-type-language form, so this variant is inconsistent and likely does not match the actual heading ID. This inconsistency can break navigation in a core explanation of value representation.

Suggested change
This raw value format may be used to implement arbitrary sum-product algebraic types. In this case, the value would contain a raw byte first, describing the constructor being used (from the perspective of a high-level language), and then other fields or constructor arguments, consisting of raw bytes and references to other structures depending on the [constructor](#2-2-5-tl,-or-the-type-language) chosen. However, TVM does not know anything about the correspondence between constructors and their arguments; the mixture of bytes and references is explicitly described by certain descriptor bytes.<a id="ref-fn8"></a><sup>[8](#fn8)</sup>
This raw value format may be used to implement arbitrary sum-product algebraic types. In this case, the value would contain a raw byte first, describing the constructor being used (from the perspective of a high-level language), and then other fields or constructor arguments, consisting of raw bytes and references to other structures depending on the [constructor](#2-2-5-tl-or-the-type-language) chosen. However, TVM does not know anything about the correspondence between constructors and their arguments; the mixture of bytes and references is explicitly described by certain descriptor bytes.<a id="ref-fn8"></a><sup>[8](#fn8)</sup>

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

Comment thread foundations/whitepapers/ton.mdx Outdated

$$
\mathit{ShardchainState}:=(\mathit{Account}\dashrightarrow\mathit{AccountState}) \tag{23}
$$

where all $\mathit{account\_id}$ appearing as indices of this hashmap must begin with prefix $s,ドル if we are discussing the state of shard $(w,s)$ (cf. [2.1.8](#2-1-8-identification-of-shardchains)).
where all $\mathit{account\_id}$ appearing as indices of this hashmap must begin with prefix $s,ドル if we are discussing the [state of shard](#2-1-8-identification-of-shardchains) $(w,s).

@github-actions github-actions Bot Dec 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Missing closing parenthesis in shard state notation

The equation for ShardchainState is followed by a sentence ending in $(w,s)., i.e., ... [state of shard](#2-1-8-identification-of-shardchains) $(w,s).. This leaves the math expression with an unbalanced opening parenthesis, which is a regression from $(w,s)$ in the base version. The mismatch harms readability of the formal shard identifier notation in a definitional section.

Suggested change
where all $\mathit{account\_id}$ appearing as indices of this hashmap must begin with prefix $s,ドル if we are discussing the [state of shard](#2-1-8-identification-of-shardchains) $(w,s).
where all $\mathit{account\_id}$ appearing as indices of this hashmap must begin with prefix $s,ドル if we are discussing the [state of shard](#2-1-8-identification-of-shardchains) $(w,s)$.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

Comment thread foundations/whitepapers/ton.mdx Outdated

However, sharding is not so easy to implement in a fast and reliable fashion, because it implies a lot of messages between different shardchains. For example, if accounts are evenly distributed between $N$ shards, and the only transactions are simple fund transfers from one account to another, then only a small fraction (1ドル/N$) of all transactions will be performed within a single blockchain; almost all (1ドル-1/N$) transactions will involve two blockchains, requiring inter-blockchain communication. If we want these transactions to be fast, we need a fast system for transferring messages between shardchains. In other words, the blockchain project needs to be "tightly-coupled" in the sense described in [2.8.14](#2-8-14-interaction-between-blockchains-loosely-coupled-and-tightly-coupled-systems).
However, sharding is not so easy to implement in a fast and reliable fashion, because it implies a lot of messages between different shardchains. For example, if accounts are evenly distributed between $N$ shards, and the only transactions are simple fund transfers from one account to another, then only a small fraction (1ドル/N$) of all transactions will be performed within a single blockchain; almost all (1ドル-1/N$) transactions will involve two blockchains, requiring inter-blockchain communication. If we want these transactions to be fast, we need a fast system for transferring messages between shardchains. In other words, the blockchain project needs to be [tightly-coupled](#2-8-14-interaction-between-blockchains%3A-loosely-coupled-and-tightly-coupled-systems) in the sense.

@github-actions github-actions Bot Dec 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Truncated "tightly-coupled" sharding sentence

In the discussion of sharding support, the sentence ends with the blockchain project needs to be [tightly-coupled](#2-8-14-interaction-between-blockchains%3A-loosely-coupled-and-tightly-coupled-systems) in the sense.. The phrase "in the sense" is left hanging without specifying what it refers to, unlike the base text which explicitly ties the sense to section 2.8.14. This truncation makes the requirement less clear in an important conceptual passage.

Suggested change
However, sharding is not so easy to implement in a fast and reliable fashion, because it implies a lot of messages between different shardchains. For example, if accounts are evenly distributed between $N$ shards, and the only transactions are simple fund transfers from one account to another, then only a small fraction (1ドル/N$) of all transactions will be performed within a single blockchain; almost all (1ドル-1/N$) transactions will involve two blockchains, requiring inter-blockchain communication. If we want these transactions to be fast, we need a fast system for transferring messages between shardchains. In other words, the blockchain project needs to be [tightly-coupled](#2-8-14-interaction-between-blockchains%3A-loosely-coupled-and-tightly-coupled-systems) in the sense.
However, sharding is not so easy to implement in a fast and reliable fashion, because it implies a lot of messages between different shardchains. For example, if accounts are evenly distributed between $N$ shards, and the only transactions are simple fund transfers from one account to another, then only a small fraction (1ドル/N$) of all transactions will be performed within a single blockchain; almost all (1ドル-1/N$) transactions will involve two blockchains, requiring inter-blockchain communication. If we want these transactions to be fast, we need a fast system for transferring messages between shardchains. In other words, the blockchain project needs to be [tightly-coupled](#2-8-14-interaction-between-blockchains%3A-loosely-coupled-and-tightly-coupled-systems) in the sense described there.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

Comment thread foundations/whitepapers/ton.mdx Outdated

#### 3.3.7. Locating more members of the overlay network. Creating links

Once one node of the overlay network is found, a special query may be sent to that node requesting a list of other members, for instance, neighbors of the node being queried, or a random selection thereof.

This enables the joining member to populate her "adjacency" or "neighbor list" with respect to the overlay network, by selecting some newly-learned network nodes and establishing links to them (i.e., dedicated ADNL point-to-point channels, as outlined in [3.3.2](#3-3-2-overlay-networks-in-ton)). After that, special messages are sent to all neighbors indicating that the new member is ready to work in the overlay network. The neighbors include their links to the new member in their neighbor lists.
This enables the joining member to populate her "adjacency" or "neighbor list" with respect to the [overlay network(#3-3-2-overlay-networks-in-ton), by selecting some newly-learned network nodes and establishing links to them (i.e., dedicated ADNL point-to-point channels). After that, special messages are sent to all neighbors indicating that the new member is ready to work in the overlay network. The neighbors include their links to the new member in their neighbor lists.

@github-actions github-actions Bot Dec 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Broken overlay network link syntax

The sentence about populating the neighbor list reads with respect to the [overlay network(#3-3-2-overlay-networks-in-ton), ..., placing the anchor parentheses inside the link text and omitting the closing ] before the (. This malformed link breaks the reference to section 3.3.2 and degrades readability in the description of joining overlay networks.

Suggested change
This enables the joining member to populate her "adjacency" or "neighbor list" with respect to the [overlay network(#3-3-2-overlay-networks-in-ton), by selecting some newly-learned network nodes and establishing links to them (i.e., dedicated ADNL point-to-point channels). After that, special messages are sent to all neighbors indicating that the new member is ready to work in the overlay network. The neighbors include their links to the new member in their neighbor lists.
This enables the joining member to populate her "adjacency" or "neighbor list" with respect to the [overlay network](#3-3-2-overlay-networks-in-ton), by selecting some newly-learned network nodes and establishing links to them (i.e., dedicated ADNL point-to-point channels). After that, special messages are sent to all neighbors indicating that the new member is ready to work in the overlay network. The neighbors include their links to the new member in their neighbor lists.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

Comment thread foundations/whitepapers/ton.mdx Outdated
Comment on lines +2295 to +2333
## Footnotes

<span id="fn20">20.</span> It makes sense to generate and use a new key pair for every validator election. [Back ↑](#2-6-7-global-validator-set-election)
<span id="fn1">**1.**</span> https://github.com/ethresearch. [Back ↑](#ref-fn1)

<span id="fn21">21.</span> A possible exception is the state of output queues of the neighboring shardchains, needed to guarantee the message ordering requirements described in [2.4.21](#2-4-21-collecting-input-messages-from-output-queues-of-neighboring-shardchains), because the size of Merkle proofs might become prohibitive in this case. [Back ↑](#2-6-11-validation-of-block-candidates)
<span id="fn2">**2.**</span> Even this is slightly simplified; in fact, the BFT consensus is run only if the designated block producer fails to produce a block in a set amount of time. [Back ↑](#ref-fn2)

<span id="fn22">22.</span> Actually, the shard configuration is completely determined by the last masterchain block; this simplifies getting access to the shard configuration. [Back ↑](#2-7-1-shard-configuration)
<span id="fn3">**3.**</span> https://coq.inria.fr. [Back ↑](#ref-fn3)

<span id="fn23">23.</span> Unless some validators are temporarily or permanently banned because of signing invalid blocks—then they are automatically excluded from all task groups. [Back ↑](#2-7-4-validator-task-groups-for-new-shardchains)
<span id="fn4">**4.**</span> https://core.telegram.org/mtproto/TL. [Back ↑](#ref-fn4)

<span id="fn24">24.</span> More like 15, for the time being. However, some upgrades are being planned to make Ethereum transaction throughput several times larger. [Back ↑](#2-8-2-single-blockchain-vs-multi-blockchain-projects)
<span id="fn5">**5.**</span> Or one might use any prefix-free encoding for natural numbers instead of the unary encoding of the length of a bit string. [Back ↑](#ref-fn5)

<span id="fn25">25.</span> Some people even claim DPOS block generation times of half a second, which does not seem realistic if validators are scattered across several continents. [Back ↑](#2-8-5-comparison-of-dpos-and-bft-pos)
<span id="fn6">**6.**</span> A *light node* is a node that does not keep track of the complete state of a shardchain; it downloads only the block headers along with the Merkle proofs of the specific data it is interested in. [Back ↑](#ref-fn6)

<span id="fn26">26.</span> For instance, EOS, one of the best DPOS projects proposed up to this date, promises a 45-second confirmation and inter-blockchain interaction delay (cf. EOS White Paper, "Transaction Confirmation" and "Latency of Interchain Communication" sections). [Back ↑](#2-8-5-comparison-of-dpos-and-bft-pos)
<span id="fn7">**7.**</span> A *full node* is a node that keeps track of the complete state of a shardchain. [Back ↑](#ref-fn7)

<span id="fn27">27.</span> For example, the Plasma project plans to use the Ethereum blockchain as its (external) masterchain; it does not interact much with Ethereum otherwise, and it could have been suggested and implemented by a team unrelated to the Ethereum project. [Back ↑](#2-8-16-complications-of-changing-the-genome-of-a-blockchain-project)
<span id="fn8">**8.**</span> Of course, the abstract description of a TVM value format given here is not complete. We refer the reader to the TVM documentation for more details. [Back ↑](#ref-fn8)

<span id="fn28">28.</span> As of 2017, Ethereum is still struggling to transition from PoW to a combined PoW+PoS system; we hope it will become a truly PoS system someday. [Back ↑](#2-8-16-complications-of-changing-the-genome-of-a-blockchain-project)
<span id="fn9">**9.**</span> Cf. the TVM documentation. [Back ↑](#ref-fn9)

<span id="fn29">29.</span> There are sharding proposals for Ethereum dating back to 2015; it is unclear how they might be implemented and deployed without disrupting Ethereum or creating an essentially independent parallel project. [Back ↑](#2-8-16-complications-of-changing-the-genome-of-a-blockchain-project)
<span id="fn10">**10.**</span> Or a directed acyclic graph (dag), if the same cell is referred to from several other cells. [Back ↑](#ref-fn10)

<span id="fn30">30.</span> https://blog.ethereum.org/2015/08/01/introducing-casper-friendly-ghost/ [Back ↑](#2-9-5-casper)
<span id="fn11">**11.**</span> Recall that, if workchain $w$ has not been split at all, it has exactly one shard $(w, \emptyset)$. [Back ↑](#ref-fn11)

<span id="fn31">31.</span> https://geti2p.net/en/docs/how/garlic-routing [Back ↑](#3-1-6-channel-as-a-tunnel-identifier)
<span id="fn12">**12.**</span> Alternatively, a global smart contract can be created in all shards $(w, s)$ with $|s| = d$ for some $d \leq 60$. [Back ↑](#ref-fn12)

<span id="fn32">32.</span> If there are sufficiently many nodes in a bucket, it can be subdivided further into, say, eight sub-buckets depending on the top four bits of the Kademlia distance. This would speed up DHT lookups. [Back ↑](#3-2-6-kademlia-routing-table)
<span id="fn13">**13.**</span> In some blockchains, this is the only way of creating new messages. [Back ↑](#ref-fn13)

<span id="fn33">33.</span> Alternatively, the abstract address might be stored in the DHT as explained in [3.2.12](#3-2-12-locating-services). [Back ↑](#3-3-5-joining-an-overlay-network)
<span id="fn14">**14.**</span> Or to the shardchain containing that account. [Back ↑](#ref-fn14)

<span id="fn34">34.</span> https://core.telegram.org/mtproto [Back ↑](#4-1-4-telegram-messenger-as-a-ton-service-mtproto-over-rldp)
<span id="fn15">**15.**</span> There are some special rules related to account splitting and merging, but we will not discuss them here. [Back ↑](#ref-fn15)

<span id="fn35">35.</span> https://telegram.org/ [Back ↑](#4-1-4-telegram-messenger-as-a-ton-service-mtproto-over-rldp)
<span id="fn16">**16.**</span> In fact, they might be punished if they lose too many "fast path" messages; however, the punishment cannot be too large, otherwise an attacker could deliberately cause "fast path" messages to be lost to make the validators suffer. [Back ↑](#ref-fn16)

<span id="fn36">36.</span> TL-schemes can be TL-serialized themselves; cf. https://core.telegram.org/mtproto/TL-tl. [Back ↑](#4-3-14-public-interfaces-of-a-smart-contract)
<span id="fn17">**17.**</span> In fact, to avoid some subtle problems, a small additional fee is exacted for the "slow path" delivery attempt, so that everybody in the system is interested in receiving "fast path" delivery confirmations as soon as possible. [Back ↑](#ref-fn17)

<span id="fn37">37.</span> The maximum total amount of validator stakes is a configurable parameter of the blockchain, so this restriction can be enforced by the protocol if necessary. [Back ↑](#a-3-original-supply-mining-rewards-and-inflation)
<span id="fn30">**30.**</span> https://github.com/ethereum/wiki/wiki/Casper-Proof-of-Stake-compendium. [Back ↑](#ref-fn30)

<span id="fn37">**37.**</span> This estimate can be justified as follows: a validator typically needs to stake between two and ten times more than it hopes to earn per year by participating in the validation process. If the projected annual return is 20%, the stakes will constitute between 40% and 200% of the annual return; that is, between 8% and 40% of the total supply. We estimate the average at about 10%. [Back ↑](#ref-fn37)

@github-actions github-actions Bot Dec 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Footnotes block desynchronized from in-text references

The entire ## Footnotes block has been rewritten to use new ids (fn1, fn2, ..., fn17, fn30, fn37) and "Back ↑" links that point to #ref-fnN, while many in-text references still use <a id="ref-fnN"></a><sup>[N](#fnN)</sup> patterns for values of N (e.g., 20) that no longer have corresponding <span id="fnN"> entries. For instance, the validator key sentence at line 917 links to #fn20, but there is no <span id="fn20"> in the new block, making that footnote anchor broken. This desynchronization affects multiple references and violates the internal consistency of cross-references throughout the document.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

Comment thread foundations/whitepapers/ton.mdx Outdated

<span id="fn20">20.</span> It makes sense to generate and use a new key pair for every validator election. [Back ↑](#2-6-7-global-validator-set-election)
<span id="fn1">**1.**</span> https://github.com/ethresearch. [Back ↑](#ref-fn1)

@github-actions github-actions Bot Dec 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Missing back-reference anchors for several footnotes

The footnote section at the end of the file now uses [Back ↑](#ref-fnX) links for many entries (for example, fn1, fn2, ..., fn7, and fn30 at lines 2297–2331), but in the body of the document only some corresponding id="ref-fnX" anchors have been introduced. For instance, the main text at line 69 still has <sup>[1](#fn1)</sup> with no preceding <a id="ref-fn1"></a>, while other notes such as fn10–fn17 and fn37 do have matching ref-fn10–ref-fn17/ref-fn37 anchors in the body (e.g., lines 493, 537, 563, 654–692, 706–708, 788, 796, and 2152). This partial migration leaves several "Back ↑" links pointing at non-existent IDs, creating broken in-page navigation for readers trying to return from the footnotes to their call sites—a class of errors that your style guide classifies as HIGH severity.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!


#### 2.1.1. List of blockchain types

The blockchains in this collection are:

- The unique *master blockchain*, or *masterchain* for short, containing general information about the protocol and the current values of its parameters, the set of validators and their stakes, the set of currently active workchains and their "shards", and, most importantly, the set of hashes of the most recent blocks of all workchains and shardchains.

- Several (up to 2ドル^{32}$) *working blockchains*, or *workchains* for short, which are actually the "workhorses", containing the value-transfer and smart-contract transactions. Different workchains may have different "rules", meaning different formats of account addresses, different formats of transactions, different virtual machines (VMs) for smart contracts, different basic cryptocurrencies and so on. However, they all must satisfy certain basic interoperability criteria to make interaction between different workchains possible and relatively simple. In this respect, the TON Blockchain is *heterogeneous* (cf. [2.8.8](#2-8-8-blockchain-types%3A-homogeneous-and-heterogeneous-systems)), similarly to the EOS (cf. [2.9.7](#2-9-7-eos)) and PolkaDot (cf. [2.9.8](#2-9-8-polkadot)) projects.
- Several (up to 2ドル^{32}$) *working blockchains*, or *workchains* for short, which are actually the "workhorses", containing the value-transfer and smart-contract transactions. Different workchains may have different "rules", meaning different formats of account addresses, different formats of transactions, different virtual machines (VMs) for smart contracts, different basic cryptocurrencies and so on. However, they all must satisfy certain basic interoperability criteria to make interaction between different workchains possible and relatively simple. In this respect, the TON Blockchain is [heterogeneous](#2-8-8-blockchain-types%3A-homogeneous-and-heterogeneous-systems), similarly to the [EOS](#2-9-7-eos-%5B5%5D%3B-https%3A%2F%2Feos-io) and [PolkaDot](#2-9-8-polkadot-%5B17%5D%3B-https%3A%2F%2Fpolkadot-io%2F) projects.

@fakela fakela Dec 12, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The links to EOS and PolkaDot are correct but don't navigate to the exact section when clicked. This is because the EOS and PolkaDot headings contain URLs in the heading text itself, I think this should be checked out

Copy link
Copy Markdown
Contributor

1st Chapter ok.

@novusnota novusnota marked this pull request as draft January 16, 2026 12:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@github-actions github-actions[bot] github-actions[bot] left review comments
@reveloper reveloper Awaiting requested review from reveloper

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

cross-link ton.pdf

2 participants

AltStyle によって変換されたページ (->オリジナル) /