add TON consensus doc

[laviniat1996]

This PR adds an indepth doc about how consensus works in TON. The doc still needs improvements, but it is in good shape to be added as it is.

Closes: #171

[github-actions]

Thanks for the substantial update to ton/consensus.mdx. I found a few clarity and style items plus one terminology inconsistency to address before this merges cleanly.

Findings (14)

High (1)

[HIGH] “three-phase commit” contradicts five-step list

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L85-L91

Description:
The text labels BCP as a “three-phase commit” but immediately lists five steps, which is contradictory and can mislead readers about protocol structure.

Suggestion:

-BCP is structured as a **three-phase commit**:
+BCP is structured as a five‑step flow:

Medium (10)

Click to expand

[MEDIUM] Fenced code blocks lack required language tags

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L29-L32

Description:
Several fenced code blocks omit a language specifier (also at L47–L49, L66–L68, and L131–L134). The style requires explicit languages for rendering, syntax highlighting, and tooling.

Suggestion:

--- a/ton/consensus.mdx
+++ b/ton/consensus.mdx
@@
-```
+```text
 f < n/3
 q ≥ 2n/3

@@
- +text
m(v, h) = (id = v, height = h, deps[], payload, sig)

@@
-```
+```text
∃ m1, m2 : m1.id = m2.id, m1.height = m2.height, m1 ≠ m2

@@
- +text
effectiveStake(v) = min(stake(v), minStake × stakeFactor)

[MEDIUM] Headings are not in sentence case

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L19-L21

Description:
Multiple headings use Title Case instead of sentence case, reducing consistency and scanability.

Suggestion:

-## Consensus Model
-### Byzantine Fault Tolerance
-## Catchain Protocol
-## Block Consensus Protocol (BCP)
-## Rounds and Attempts
-## Validator Elections
-## Incentives and Penalties
-## Validator Guidelines
-## Extended Fault Tolerance Analysis
+## Consensus model
+### Byzantine fault tolerance
+## Catchain protocol
+## Block consensus protocol (BCP)
+## Rounds and attempts
+## Validator elections
+## Incentives and penalties
+## Validator guidelines
+## Extended fault tolerance analysis

[MEDIUM] Generic “Introduction” heading should be specific

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L6-L6

Description:
The first H2 is a generic “Introduction,” which the style guide discourages because it is ambiguous in navigation and deep links.

Suggestion:

-## Introduction
+## Overview

[MEDIUM] Code identifiers not formatted in code font

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L90-L91

Description:
Protocol/event identifiers appear without code formatting (also affects “CommitSigns” at L200), reducing readability and precision.

Suggestion:

-4. **PreCommit** – once ≥ `q` votes are collected, validators broadcast PreCommit.  
-5. **Commit** – once ≥ `q` PreCommits are observed, validators issue CommitSign and the block is finalized.  
+4. **PreCommit** – once ≥ `q` votes are collected, validators broadcast `PreCommit`.  
+5. **Commit** – once ≥ `q` `PreCommit` messages are observed, validators issue `CommitSign` and the block is finalized.  
@@
--  - Finalization requires ≥ `2n/3` CommitSigns.  
+-  - Finalization requires ≥ `2n/3` `CommitSign` messages.  

[MEDIUM] TON-specific chain names use non-canonical casing

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L148-L149

Description:
Uses “Masterchain” and “Shardchains” instead of canonical “MasterChain” and “ShardChain”. The same issue appears in rewards bullets (L159–L160).

Suggestion:

-### Set sizes
-- **Masterchain** – ~100 validators.  
-- **Shardchains** – ~23 validators each.
+### Set sizes
+- **MasterChain** — ~100 validators.  
+- **ShardChain** — ~23 validators each.
@@
-  - ~1.7 TON per masterchain block.  
-  - ~1 TON per shardchain block.  
+  - ~1.7 TON per MasterChain block.  
+  - ~1 TON per ShardChain block.  

[MEDIUM] Inconsistent and non‑SI time units (“seconds” vs “s”; missing space)

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L15-L15

Description:
Time units are inconsistent across the page. Standardize to SI format with a space (e.g., “3–6 s”). Also update the later “3–6s” usage at L117.

Suggestion:

-This separation allows TON to finalize blocks in **3–6 seconds** with **hundreds of validators** across the globe.
+This separation allows TON to finalize blocks in **3–6 s** with **hundreds of validators** across the globe.

-Block latency is typically **3–6s**, bounded by attempt timers.
+Block latency is typically **3–6 s**, bounded by attempt timers.

[MEDIUM] Words instead of numerals for a technical quantity

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L8-L8

Description:
“one-third malicious validators” uses words for a technical fraction; the guide requires numerals for technical quantities.

Suggestion:

-...security against up to one-third malicious validators**.
+...security against up to 1/3 malicious validators**.

[MEDIUM] Non‑standard numeric shorthand without separators

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L143-L145

Description:
Informal abbreviations “100k”, “300k”, and “1M” are used. Prefer full numerals with thousands separators for clarity.

Suggestion:

-If the smallest validator stakes 100k TON, then:  
-- The largest counted stake = 300k TON.  
-- A validator staking 1M TON still only contributes 300k TON effectively.
+If the smallest validator stakes 100,000 TON, then:  
+- The largest counted stake = 300,000 TON.  
+- A validator staking 1,000,000 TON still only contributes 300,000 TON effectively.

[MEDIUM] Non‑ISO date format

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L166-L166

Description:
“Since June 2023” is not ISO‑8601. Use YYYY‑MM for month precision.

Suggestion:

-- Since June 2023, part of the subsidy is burned, introducing deflationary pressure as usage grows.
+- Since 2023-06, part of the subsidy is burned, introducing deflationary pressure as usage grows.

[MEDIUM] Promotional tone in closing sentence

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L225-L225

Description:
The closing sentence uses marketing-style phrasing. Prefer a factual statement grounded in the metrics given.

Suggestion:

-This architecture enables TON to deliver **fast finality, decentralization, and strong BFT guarantees** at global scale.
+This architecture finalizes blocks in 3–6 seconds and preserves Byzantine fault tolerance with a decentralized validator set.

Low (3)

Click to expand

[LOW] Mid-sentence capitalization and missing hyphen in “Byzantine Fault Tolerant”

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L8-L8

Description:
Uses mid-sentence capitalization and omits the hyphen in the compound modifier.

Suggestion:

-The TON Blockchain achieves consensus through a layered Byzantine Fault Tolerant (BFT) protocol designed for **high throughput, low latency, and security against up to one-third malicious validators**.
+The TON Blockchain achieves consensus through a layered Byzantine fault-tolerant (BFT) protocol designed for **high throughput, low latency, and security against up to one-third malicious validators**.

[LOW] Vague quantity “hundreds of validators”

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L15-L15

Description:
“hundreds of validators” is vague for a technical metric. Prefer a neutral phrasing if a precise figure isn’t available.

Suggestion:

-This separation allows TON to finalize blocks in **3–6 seconds** with **hundreds of validators** across the globe.
+This separation allows TON to finalize blocks in **3–6 seconds** with a decentralized validator set.

[LOW] List punctuation inconsistent for non‑sentence items

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/bc9f46b0f1880e2b6872b68fda445014531979bb/ton/consensus.mdx?plain=1#L156-L161

Description:
Fragment bullets end with periods. The style guide advises omitting terminal punctuation for fragments.

Suggestion:

-- **Transaction fees** (gas costs).  
-  - ~1.7 TON per MasterChain block.  
-  - ~1 TON per ShardChain block.  
+- **Transaction fees** (gas costs)  
+  - ~1.7 TON per MasterChain block  
+  - ~1 TON per ShardChain block

[github-actions]

To fix the formatting issues:

1. Install necessary dependencies: npm ci
2. Then, run this command:

npx remark -o --quiet --silently-ignore ton/consensus.mdx 

[github-actions]

To fix the formatting issues:

1. Install necessary dependencies: npm ci
2. Then, run this command:

npx remark -o --quiet --silently-ignore ton/consensus.mdx 

[anton-trunov]

@laviniat1996 please add "closes #..." to your original post, so we know which task this PR is solving

[reveloper]

Added link to issue

[github-actions]

To fix the formatting issues:

1. Install necessary dependencies: npm ci
2. Then, run this command:

npx remark -o --quiet --silently-ignore ton/consensus.mdx 

[verytactical]

This seems to be AI generated.

[verytactical]

Why does it have a summary?

[reveloper]

@laviniat1996 Please, take into account the following info

Audience

This page is designed for individuals (developers) seeking to understand how consensus is maintained in TON and how security is guaranteed. We can gain additional insights from the top-performing pages of other chains. I noticed that readers who seek this typically acknowledge this for other chains.

Scope of work

• This document should cover the questions of how consensus works in TON.
• Catchain itself doesn't cover the entire consensus flow, but this is the fundamental base for building this page.
• Validator elections are not related to the consensus mechanism and should be described in a separate page.

Technical insights for rework

Here is the feedback and suggestions I collected from TON Core.

1. Explain what Catchain is?

The Catchain core thing is to build a DAG tree of options, catch deviation events (that’s why it was initially called catch chain), and adjust the difference.

Catchain Overview

Catchain is a communication protocol between validators. It does not execute the consensus algorithm itself but prepares data required for the decision-making of a higher-level component: validator-session (BCP). Essential catchain tasks are:

- setting up a network overlay on the top of ADNL ensuring communication between validators;
- setting up and updating a list of neighbor nodes for direct communications inside the overlay;
- receiving catchain blocks from other validators and sending back decisions of the current validator;
- controlling blocks dependencies;
- managing an internal database holding current catchain session results
- restoring catchain session state after a validator restart;
- detecting forks and blaming validators;
- maintaining the consensus algorithm.

2. Make a clear definition and roles of Catchain and BCP in TON

Unlike Classic three-phase BFT(pre-prepare, prepare, commit) in current PR, TON uses Catchain DAG. Overall this works according the following steps:

• Validators exchange block candidates
• DAG synchronization with causal ordering is used
• Nodes sign only one branch, otherwise - blaming (marking a participant as a bad actor, the entire chain from them is invalidated, and they are banned)
• Consensus is reached without all-to-all voting
• The decision on what to do with blamed participants performed by BCP, it's not the scope of the catchain

3. Explain the definition and the difference between a catchain session and и validator session.

Important references

• More detailed reference: link
• Example implementation of how 11 different nodes generate a random number and then agree through catchain which number is better to choose (in this case, whoever has the bigger number is right): link