add 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:

mintlify-ton-docs/ton/consensus.mdx

Lines 85 to 91 in bc9f46b

	BCP is structured as a **three-phase commit**:
	1. **Proposal** – a leader proposes a block candidate.
	2. **Validation** – validators verify correctness (transaction validity, state consistency).
	3. **Voting** – validators vote for approved candidates.
	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.

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:

mintlify-ton-docs/ton/consensus.mdx

Lines 29 to 32 in bc9f46b

	```
	f < n/3
	q ≥ 2n/3
	```

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:

mintlify-ton-docs/ton/consensus.mdx

Lines 19 to 21 in bc9f46b

	## Consensus Model
	### Byzantine Fault Tolerance

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:

mintlify-ton-docs/ton/consensus.mdx

Line 6 in bc9f46b

## Introduction

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:

mintlify-ton-docs/ton/consensus.mdx

Lines 90 to 91 in bc9f46b

	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.

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:

mintlify-ton-docs/ton/consensus.mdx

Lines 148 to 149 in bc9f46b

	- **Masterchain** – ~100 validators.
	- **Shardchains** – ~23 validators each.

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:

mintlify-ton-docs/ton/consensus.mdx

Line 15 in bc9f46b

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

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:

mintlify-ton-docs/ton/consensus.mdx

Line 8 in bc9f46b

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**.

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:

mintlify-ton-docs/ton/consensus.mdx

Lines 143 to 145 in bc9f46b

	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.

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:

mintlify-ton-docs/ton/consensus.mdx

Line 166 in bc9f46b

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

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:

mintlify-ton-docs/ton/consensus.mdx

Line 225 in bc9f46b

This architecture enables TON to deliver **fast finality, decentralization, and strong BFT guarantees** at global scale.

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:

mintlify-ton-docs/ton/consensus.mdx

Line 8 in bc9f46b

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**.

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:

mintlify-ton-docs/ton/consensus.mdx

Line 15 in bc9f46b

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

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:

mintlify-ton-docs/ton/consensus.mdx

Lines 156 to 161 in bc9f46b

	Validators are compensated with:
	- **Transaction fees** (gas costs).
	- **Block subsidies**:
	- ~1.7 TON per masterchain block.
	- ~1 TON per shardchain block.

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?