diff --git a/docs.json b/docs.json index baea3b86e..ef0df0e85 100644 --- a/docs.json +++ b/docs.json @@ -500,11 +500,10 @@ "foundations/config", "foundations/proofs", "foundations/consensus", - "foundations/system-contracts", + "foundations/system", "foundations/precompiled", "foundations/network", "foundations/blocks", - "foundations/system", { "group": "Whitepapers", "expanded": true, diff --git a/foundations/config.mdx b/foundations/config.mdx index 7203c1d4a..28e475f67 100644 --- a/foundations/config.mdx +++ b/foundations/config.mdx @@ -37,7 +37,7 @@ This parameter is the address of a special smart contract that stores the blockc ## Param 1: elector address -This parameter is the address of the [elector smart contract](/foundations/system-contracts), responsible for appointing validators, distributing rewards, and voting on changes to blockchain parameters. +This parameter is the address of the [elector smart contract](/foundations/system), responsible for appointing validators, distributing rewards, and voting on changes to blockchain parameters. [Parameter #1 on mainnet](https://tonviewer.com/config#1) @@ -163,7 +163,7 @@ This parameter represents the configuration of a WorkChain in the TON Blockchain ## Param 13: complaint cost -This parameter defines the cost of filing complaints about the incorrect operation of validators in the [elector smart contract](/foundations/system-contracts). +This parameter defines the cost of filing complaints about the incorrect operation of validators in the [elector smart contract](/foundations/system). [Parameter #13 on mainnet](https://tonviewer.com/config#13) diff --git a/foundations/system-contracts.mdx b/foundations/system-contracts.mdx deleted file mode 100644 index ba99ad634..000000000 --- a/foundations/system-contracts.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: "System contracts" ---- - -import { Aside } from "/snippets/aside.jsx"; - - - - - -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**). - -## Elector - -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). - -### Data storage - -The Elector stores: - -- Non-withdrawn Toncoin in the `credits` hashmap. -- New validator applications in the `elect` hashmap. -- 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)). - -### Key functions - -1. **Process validator applications** -1. **Conduct elections** -1. **Handle validator misbehavior reports** -1. **Distribute validation rewards** - -#### Processing applications - -To apply, a validator must: - -1. Send a message to the Elector with their Abstract Datagram Network Layer (ADNL) address, public key, `max_factor`, and stake (TON amount). -1. The Elector validates the parameters and either registers the application or refunds the stake. - _Note:_ Only masterchain addresses can apply. - -### Conducting elections - -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. - -**Process details:** - -- Take applications with stake ≥ `min_stake` ([**ConfigParam 17**](https://tonviewer.com/config#17)). -- Arrange candidates by stake in descending order. -- If applicants exceed `max_validators` ([**ConfigParam 16**](https://tonviewer.com/config#16)), discard the lowest-staked candidates. -- For each subset size `i` (from 1 to remaining candidates): -- Assume the `i`-th candidate (lowest in the subset) defines the baseline. -- Calculate effective stake (`true_stake`) for each `j`-th candidate (`j < i`) as: - -```python not runnable -min(stake[i] * max_factor[j], stake[j]) -``` - -- Track the subset with the highest **total effective stake (TES)**. -- Submit the winning validator set to the **Config** contract. -- Return unused stakes and excess amounts (e.g., `stake[j] - min(stake[i] * max_factor[j], stake[j])`) to `credits`. - -**Example breakdown**: - -- **Case 1**: 9 candidates stake 100,000 TON (`max_factor=2.7`), 1 candidate stakes 10,000. - -- _Without the 10,000-stake candidate_: TES = 900,000. - -- _With the 10,000-stake candidate_: TES = 9 \* 27,000 + 10,000 = 253,000. - -- **Result**: 10,000-stake candidate are excluded. - -- **Case 2**: 1 candidate stakes 100,000-stake (`max_factor=2.7`), 9 stake 10,000. - -- Effective stake for the 100,000-stake candidate: `10,000 * 2.7 = 27,000`. - -- Excess: `100,000 - 27,000 = 73,000` → sent to `credits`. - -- **Result**: All 10 participate. - -**Election constraints**: - -- `min_validators` ≤ participants ≤ `max_validators` (**ConfigParam 16**). -- Stakes must satisfy: -- `min_stake` ≤ stake ≤ `max_stake` -- `min_total_stake` ≤ total stake ≤ `max_total_stake` -- Stake ratios ≤ `max_stake_factor` (**ConfigParam 17**). -- If conditions aren’t met, elections are **postponed**. - -### Report validator misbehavior - -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. - -To report misbehavior, a user must: - -1. Generate a **Merkle proof** demonstrating the validator's failure to produce the expected blocks. -1. Propose a fine proportional to the severity of the offense. -1. Submit the proof and fine proposal to the Elector contract, covering the associated storage costs. - -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). - -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`). - -#### Distributing rewards - -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`. - -## Config - -The **Config** contract manages TON’s configuration parameters, validator set updates, and proposal voting. - -### Validator set updates - -1. The **Elector** notifies **Config** of a new validator set. -1. **Config** stores it in `ConfigParam 36` (_next validators_). -1. At the scheduled time (`utime_since`), **Config**: - -- Moves the old set to `ConfigParam 32` (_previous validators_). -- Promotes `ConfigParam 36` to `ConfigParam 34` (_current validators_). - -### Proposal/voting mechanism - -1. **Submit a proposal**: Pay storage fees to propose parameter changes. -1. **Vote**: Validators (from **ConfigParam 34**) sign approval messages. -1. **Outcome**: - -- **Approved**: After `min_wins` rounds (**ConfigParam 11**) with ≥3/4 weighted votes. -- **Rejected**: After `max_losses` rounds. -- _Critical parameters_ (**ConfigParam 10**) require more rounds. - -#### Emergency updates - -- Reserved indexes (`-999`, `-1000`, `-1001`) allow urgent updates to **Config**/**Elector** code. -- A temporary emergency key (assigned to the TON Foundation in 2021) accelerated fixes but couldn't alter contracts. -- **Key retired** on Nov 22, 2023 (**block 34312810**), replaced with zeros. -- Later patched to a fixed byte sequence (`sha256("Not a valid curve point")`) to prevent exploits. - -**Historical uses**: - -- **Apr 2022**: Increased gas limits (**blocks 19880281/19880300**) to unblock elections. -- **Mar 2023**: Raised `special_gas_limit` to 25M (**block 27747086**) for election throughput. diff --git a/foundations/system.mdx b/foundations/system.mdx index bb5d3aef6..ba99ad634 100644 --- a/foundations/system.mdx +++ b/foundations/system.mdx @@ -2,6 +2,142 @@ title: "System contracts" --- -import { Stub } from '/snippets/stub.jsx'; +import { Aside } from "/snippets/aside.jsx"; - + + + + +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**). + +## Elector + +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). + +### Data storage + +The Elector stores: + +- Non-withdrawn Toncoin in the `credits` hashmap. +- New validator applications in the `elect` hashmap. +- 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)). + +### Key functions + +1. **Process validator applications** +1. **Conduct elections** +1. **Handle validator misbehavior reports** +1. **Distribute validation rewards** + +#### Processing applications + +To apply, a validator must: + +1. Send a message to the Elector with their Abstract Datagram Network Layer (ADNL) address, public key, `max_factor`, and stake (TON amount). +1. The Elector validates the parameters and either registers the application or refunds the stake. + _Note:_ Only masterchain addresses can apply. + +### Conducting elections + +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. + +**Process details:** + +- Take applications with stake ≥ `min_stake` ([**ConfigParam 17**](https://tonviewer.com/config#17)). +- Arrange candidates by stake in descending order. +- If applicants exceed `max_validators` ([**ConfigParam 16**](https://tonviewer.com/config#16)), discard the lowest-staked candidates. +- For each subset size `i` (from 1 to remaining candidates): +- Assume the `i`-th candidate (lowest in the subset) defines the baseline. +- Calculate effective stake (`true_stake`) for each `j`-th candidate (`j < i`) as: + +```python not runnable +min(stake[i] * max_factor[j], stake[j]) +``` + +- Track the subset with the highest **total effective stake (TES)**. +- Submit the winning validator set to the **Config** contract. +- Return unused stakes and excess amounts (e.g., `stake[j] - min(stake[i] * max_factor[j], stake[j])`) to `credits`. + +**Example breakdown**: + +- **Case 1**: 9 candidates stake 100,000 TON (`max_factor=2.7`), 1 candidate stakes 10,000. + +- _Without the 10,000-stake candidate_: TES = 900,000. + +- _With the 10,000-stake candidate_: TES = 9 \* 27,000 + 10,000 = 253,000. + +- **Result**: 10,000-stake candidate are excluded. + +- **Case 2**: 1 candidate stakes 100,000-stake (`max_factor=2.7`), 9 stake 10,000. + +- Effective stake for the 100,000-stake candidate: `10,000 * 2.7 = 27,000`. + +- Excess: `100,000 - 27,000 = 73,000` → sent to `credits`. + +- **Result**: All 10 participate. + +**Election constraints**: + +- `min_validators` ≤ participants ≤ `max_validators` (**ConfigParam 16**). +- Stakes must satisfy: +- `min_stake` ≤ stake ≤ `max_stake` +- `min_total_stake` ≤ total stake ≤ `max_total_stake` +- Stake ratios ≤ `max_stake_factor` (**ConfigParam 17**). +- If conditions aren’t met, elections are **postponed**. + +### Report validator misbehavior + +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. + +To report misbehavior, a user must: + +1. Generate a **Merkle proof** demonstrating the validator's failure to produce the expected blocks. +1. Propose a fine proportional to the severity of the offense. +1. Submit the proof and fine proposal to the Elector contract, covering the associated storage costs. + +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). + +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`). + +#### Distributing rewards + +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`. + +## Config + +The **Config** contract manages TON’s configuration parameters, validator set updates, and proposal voting. + +### Validator set updates + +1. The **Elector** notifies **Config** of a new validator set. +1. **Config** stores it in `ConfigParam 36` (_next validators_). +1. At the scheduled time (`utime_since`), **Config**: + +- Moves the old set to `ConfigParam 32` (_previous validators_). +- Promotes `ConfigParam 36` to `ConfigParam 34` (_current validators_). + +### Proposal/voting mechanism + +1. **Submit a proposal**: Pay storage fees to propose parameter changes. +1. **Vote**: Validators (from **ConfigParam 34**) sign approval messages. +1. **Outcome**: + +- **Approved**: After `min_wins` rounds (**ConfigParam 11**) with ≥3/4 weighted votes. +- **Rejected**: After `max_losses` rounds. +- _Critical parameters_ (**ConfigParam 10**) require more rounds. + +#### Emergency updates + +- Reserved indexes (`-999`, `-1000`, `-1001`) allow urgent updates to **Config**/**Elector** code. +- A temporary emergency key (assigned to the TON Foundation in 2021) accelerated fixes but couldn't alter contracts. +- **Key retired** on Nov 22, 2023 (**block 34312810**), replaced with zeros. +- Later patched to a fixed byte sequence (`sha256("Not a valid curve point")`) to prevent exploits. + +**Historical uses**: + +- **Apr 2022**: Increased gas limits (**blocks 19880281/19880300**) to unblock elections. +- **Mar 2023**: Raised `special_gas_limit` to 25M (**block 27747086**) for election throughput. diff --git a/standard/wallets/restricted.mdx b/standard/wallets/restricted.mdx index feb12b483..4340b3b2f 100644 --- a/standard/wallets/restricted.mdx +++ b/standard/wallets/restricted.mdx @@ -21,7 +21,7 @@ Unlike standard wallets that allow transfers to any address, Restricted Wallet i You can send funds to any valid address. **Restricted Wallet behavior:**\ -You can only send funds to the predefined owner address or do operations with [Elector](https://beta-docs.ton.org/foundations/system-contracts#elector) (new stake, recover stake request, new complaint, and vote for a complaint) and [Config](/foundations/system-contracts#config) (vote for specific proposal to change config) contracts. +You can only send funds to the predefined owner address or do operations with [Elector](https://beta-docs.ton.org/foundations/system#elector) (new stake, recover stake request, new complaint, and vote for a complaint) and [Config](/foundations/system#config) (vote for specific proposal to change config) contracts. ## How it works @@ -30,8 +30,8 @@ You can only send funds to the predefined owner address or do operations with [E ### Allowed actions 1. Send a message to the owner of this wallet. -1. Send "vote for a configuration proposal" message to the [Config contract](/foundations/system-contracts#config). -1. Send "new stake", "recover stake request", "new complaint", or "vote for a complaint" messages to the [Elector contract](https://beta-docs.ton.org/foundations/system-contracts#elector). +1. Send "vote for a configuration proposal" message to the [Config contract](/foundations/system#config). +1. Send "new stake", "recover stake request", "new complaint", or "vote for a complaint" messages to the [Elector contract](https://beta-docs.ton.org/foundations/system#elector). It is allowed to use [message modes](/languages/func/stdlib#send-raw-message) 128, 64, 2, and 1. Mode 2 (ignore errors) is always enabled when sending messages from this wallet.