|
2 | 2 | title: "System contracts" |
3 | 3 | --- |
4 | 4 |
|
5 | | -import { Stub } from '/snippets/stub.jsx'; |
| 5 | +import { Aside } from "/snippets/aside.jsx"; |
6 | 6 |
|
7 | | -<Stub issue="107" /> |
| 7 | +<Aside> |
| 8 | + These are low-level TON Blockchain internals. You typically do not need to write or deploy these contracts. |
| 9 | +</Aside> |
| 10 | + |
| 11 | +<Aside> |
| 12 | + System contracts are smart contracts and have on‑chain addresses. See [config parameters 1–4](https://tonviewer.com/config). The Config account stores the Config contract address. To track changes, review proposals to the Config contract. |
| 13 | +</Aside> |
| 14 | + |
| 15 | +In TON, a set of special smart contracts controls consensus parameters for node operation — including TVM, catchain, fees, and chain topology — and how these parameters are stored and updated. Unlike older blockchains that hardcode these parameters, TON enables transparent on‑chain governance. The current governance contracts include the **Elector** and **Config** contracts, with expansion plans (for example, the extra‑currency **Minter**). |
| 16 | + |
| 17 | +## Elector |
| 18 | + |
| 19 | +The **Elector** smart contract manages validator elections, validation rounds, and reward distribution. To become a validator and interact with the Elector, follow the [validator instructions](https://ton.org/validator). |
| 20 | + |
| 21 | +### Data storage |
| 22 | + |
| 23 | +The Elector stores: |
| 24 | + |
| 25 | +- Non-withdrawn Toncoin in the `credits` hashmap. |
| 26 | +- New validator applications in the `elect` hashmap. |
| 27 | +- Past election data in the `past_elections` hashmap (including complaints and `frozen` stakes held for `stake_held_for` periods, defined in [**ConfigParam 15**](https://tonviewer.com/config#15)). |
| 28 | + |
| 29 | +### Key functions |
| 30 | + |
| 31 | +1. **Process validator applications** |
| 32 | +1. **Conduct elections** |
| 33 | +1. **Handle validator misbehavior reports** |
| 34 | +1. **Distribute validation rewards** |
| 35 | + |
| 36 | +#### Processing applications |
| 37 | + |
| 38 | +To apply, a validator must: |
| 39 | + |
| 40 | +1. Send a message to the Elector with their Abstract Datagram Network Layer (ADNL) address, public key, `max_factor`, and stake (TON amount). |
| 41 | +1. The Elector validates the parameters and either registers the application or refunds the stake. |
| 42 | + _Note:_ Only masterchain addresses can apply. |
| 43 | + |
| 44 | +### Conducting elections |
| 45 | + |
| 46 | +The Elector is a special smart contract triggered by **Tick and Tock transactions** (forced executions at the start and end of each block). It checks whether it’s time to conduct a new election during each block. |
| 47 | + |
| 48 | +**Process details:** |
| 49 | + |
| 50 | +- Take applications with stake ≥ `min_stake` ([**ConfigParam 17**](https://tonviewer.com/config#17)). |
| 51 | +- Arrange candidates by stake in descending order. |
| 52 | +- If applicants exceed `max_validators` ([**ConfigParam 16**](https://tonviewer.com/config#16)), discard the lowest-staked candidates. |
| 53 | +- For each subset size `i` (from 1 to remaining candidates): |
| 54 | +- Assume the `i`-th candidate (lowest in the subset) defines the baseline. |
| 55 | +- Calculate effective stake (`true_stake`) for each `j`-th candidate (`j < i`) as: |
| 56 | + |
| 57 | +```python not runnable |
| 58 | +min(stake[i] * max_factor[j], stake[j]) |
| 59 | +``` |
| 60 | + |
| 61 | +- Track the subset with the highest **total effective stake (TES)**. |
| 62 | +- Submit the winning validator set to the **Config** contract. |
| 63 | +- Return unused stakes and excess amounts (e.g., `stake[j] - min(stake[i] * max_factor[j], stake[j])`) to `credits`. |
| 64 | + |
| 65 | +**Example breakdown**: |
| 66 | + |
| 67 | +- **Case 1**: 9 candidates stake 100,000 TON (`max_factor=2.7`), 1 candidate stakes 10,000. |
| 68 | + |
| 69 | +- _Without the 10,000-stake candidate_: TES = 900,000. |
| 70 | + |
| 71 | +- _With the 10,000-stake candidate_: TES = 9 \* 27,000 + 10,000 = 253,000. |
| 72 | + |
| 73 | +- **Result**: 10,000-stake candidate are excluded. |
| 74 | + |
| 75 | +- **Case 2**: 1 candidate stakes 100,000-stake (`max_factor=2.7`), 9 stake 10,000. |
| 76 | + |
| 77 | +- Effective stake for the 100,000-stake candidate: `10,000 * 2.7 = 27,000`. |
| 78 | + |
| 79 | +- Excess: `100,000 - 27,000 = 73,000` → sent to `credits`. |
| 80 | + |
| 81 | +- **Result**: All 10 participate. |
| 82 | + |
| 83 | +**Election constraints**: |
| 84 | + |
| 85 | +- `min_validators` ≤ participants ≤ `max_validators` (**ConfigParam 16**). |
| 86 | +- Stakes must satisfy: |
| 87 | +- `min_stake` ≤ stake ≤ `max_stake` |
| 88 | +- `min_total_stake` ≤ total stake ≤ `max_total_stake` |
| 89 | +- Stake ratios ≤ `max_stake_factor` (**ConfigParam 17**). |
| 90 | +- If conditions aren’t met, elections are **postponed**. |
| 91 | + |
| 92 | +### Report validator misbehavior |
| 93 | + |
| 94 | +Each validator is periodically assigned the duty to create new blocks, with the frequency of assignments determined by their weight. After a validation round, anyone can audit the blocks to check whether the actual number of blocks produced by a validator significantly deviates from the expected number (based on their weight). A statistically significant underperformance (e.g., fewer blocks created than expected) constitutes misbehavior. |
| 95 | + |
| 96 | +To report misbehavior, a user must: |
| 97 | + |
| 98 | +1. Generate a **Merkle proof** demonstrating the validator's failure to produce the expected blocks. |
| 99 | +1. Propose a fine proportional to the severity of the offense. |
| 100 | +1. Submit the proof and fine proposal to the Elector contract, covering the associated storage costs. |
| 101 | + |
| 102 | +The Elector registers the complaint in the `past_elections` hashmap. Current round validators then verify the complaint. If the proof is valid and the proposed fine aligns with the severity of the misbehavior, validators vote on the complaint. Approval requires agreement from over **two-thirds of the total validator weight** (not just a majority of participants). |
| 103 | + |
| 104 | +The fine is deducted from the validator's `frozen` stake in the relevant `past_elections` record if approved. These funds stay locked for the period defined by [**ConfigParam 15**](https://tonviewer.com/config#15) (`stake_held_for`). |
| 105 | + |
| 106 | +#### Distributing rewards |
| 107 | + |
| 108 | +The Elector releases `frozen` stakes and rewards (gas fees plus block rewards) proportionally to past validators. Funds move to `credits`, and the election record clears from `past_elections`. |
| 109 | + |
| 110 | +## Config |
| 111 | + |
| 112 | +The **Config** contract manages TON’s configuration parameters, validator set updates, and proposal voting. |
| 113 | + |
| 114 | +### Validator set updates |
| 115 | + |
| 116 | +1. The **Elector** notifies **Config** of a new validator set. |
| 117 | +1. **Config** stores it in `ConfigParam 36` (_next validators_). |
| 118 | +1. At the scheduled time (`utime_since`), **Config**: |
| 119 | + |
| 120 | +- Moves the old set to `ConfigParam 32` (_previous validators_). |
| 121 | +- Promotes `ConfigParam 36` to `ConfigParam 34` (_current validators_). |
| 122 | + |
| 123 | +### Proposal/voting mechanism |
| 124 | + |
| 125 | +1. **Submit a proposal**: Pay storage fees to propose parameter changes. |
| 126 | +1. **Vote**: Validators (from **ConfigParam 34**) sign approval messages. |
| 127 | +1. **Outcome**: |
| 128 | + |
| 129 | +- **Approved**: After `min_wins` rounds (**ConfigParam 11**) with ≥3/4 weighted votes. |
| 130 | +- **Rejected**: After `max_losses` rounds. |
| 131 | +- _Critical parameters_ (**ConfigParam 10**) require more rounds. |
| 132 | + |
| 133 | +#### Emergency updates |
| 134 | + |
| 135 | +- Reserved indexes (`-999`, `-1000`, `-1001`) allow urgent updates to **Config**/**Elector** code. |
| 136 | +- A temporary emergency key (assigned to the TON Foundation in 2021) accelerated fixes but couldn't alter contracts. |
| 137 | +- **Key retired** on Nov 22, 2023 (**block 34312810**), replaced with zeros. |
| 138 | +- Later patched to a fixed byte sequence (`sha256("Not a valid curve point")`) to prevent exploits. |
| 139 | + |
| 140 | +**Historical uses**: |
| 141 | + |
| 142 | +- **Apr 2022**: Increased gas limits (**blocks 19880281/19880300**) to unblock elections. |
| 143 | +- **Mar 2023**: Raised `special_gas_limit` to 25M (**block 27747086**) for election throughput. |
0 commit comments