Blockchain configuration

TON features a complex configuration comprising many technical parameters, some of which are used by the blockchain itself, while others serve the ecosystem. However, only a limited number of individuals fully understand the significance of these parameters. This article aims to provide users with an overview of configuration parameters, their modification processes, and a straightforward explanation of each parameter and its purpose.

Prerequisites

The parameter values in the current configuration, and the method of writing them into cells are outlined in the block.tlb file in TL-B format.

All parameters are in place, and you won't get lost. For your convenience, please use the right sidebar for quick navigation.

Overview

The configuration parameters are specific values that influence the behavior of validators and fundamental smart contracts on the TON blockchain. The current values of all configuration parameters are stored as a distinct part of the masterchain state and are retrieved whenever necessary. Consequently, we can refer to the values of the configuration parameters concerning a particular masterchain block. Each shardchain block includes a reference to the most recently known masterchain block; the values from the corresponding masterchain state are considered active for this shardchain block and are used during its generation and validation.

For masterchain blocks, the state of the previous masterchain block is used to extract the active configuration parameters. Therefore, even if certain configuration parameters are attempted to be modified within a masterchain block, any changes will only take effect in the subsequent masterchain block.

Each configuration parameter is identified by a signed 32-bit integer known as the configuration parameter index, or simply the index. The value of a configuration parameter is always a Cell. In some cases, certain configuration parameters may be absent, and it is generally assumed that the value of these missing parameters is Null. Additionally, there is a list of mandatory configuration parameters that must always be present. This list is stored in configuration parameter #9.

All configuration parameters are combined into a configuration dictionary with signed 32-bit keys (the configuration parameter indices) and values that consist of exactly one cell reference. The collection of all configuration parameters is retained in the masterchain state as a value of the TL-B type ConfigParams:

_ config_addr:bits256 config:^(Hashmap 32 ^Cell) = ConfigParams;

In addition to the configuration dictionary, ConfigParams contains config_addr—the 256-bit address of the configuration smart contract within the masterchain. Further details on the configuration smart contract will be provided later.

The configuration dictionary, which contains the active values of all configuration parameters, is accessible to all smart contracts through a special TVM register called c7 during the execution of a transaction. Specifically, when a smart contract is executed, c7 is initialized as a tuple. This tuple consists of a single element, which is another tuple containing several "context" values that are useful for executing the smart contract, such as the current Unix time (as recorded in the block header).

The tenth entry of this inner tuple (i.e., the one indexed with zero-based index 9) contains a Cell representing the configuration dictionary. This configuration dictionary can be accessed by using the TVM instructions PUSH c7; FIRST; INDEX 9 or the equivalent instruction CONFIGROOT. Furthermore, special TVM instructions like CONFIGPARAM and CONFIGOPTPARAM streamline this process by combining the previous actions with a dictionary lookup, allowing smart contracts to retrieve any configuration parameter by its index.

It is important to note that all configuration parameters are readily accessible to all smart contracts, whether they operate on the masterchain or shardchain. As a result, smart contracts can inspect these parameters and utilize them for specific checks. For instance, a smart contract might extract data storage prices for different WorkChains from a configuration parameter in order to calculate the cost of storing a piece of user-provided data.

The values of configuration parameters are not arbitrary. Specifically, if the configuration parameter index i is non-negative, then its value must correspond to a valid value of the TL-B type ConfigParam i. Validators enforce this restriction and do not accept changes to configuration parameters with non-negative indices unless the values are valid for the corresponding TL-B type.

The structure of these parameters is defined in the source file crypto/block/block.tlb, where ConfigParam i is specified for different values of i. For example:

_ config_addr:bits256 = ConfigParam 0;
_ elector_addr:bits256 = ConfigParam 1;
_ dns_root_addr:bits256 = ConfigParam 4;  // root TON DNS resolver

capabilities#c4 version:uint32 capabilities:uint64 = GlobalVersion;
_ GlobalVersion = ConfigParam 8;  // all zero if absent

The configuration parameter #8 includes a Cell that has no references and contains exactly 104 data bits. The first eight bits are allocated for 11000100 (0xc4), followed by 32 bits that represent the currently enabled "global version". This is followed by a 64-bit integer with flags that correspond to the currently enabled capabilities. A more detailed description of all configuration parameters will be provided in an appendix to the TON blockchain documentation. In the meantime, you can review the TL-B scheme in crypto/block/block.tlb to see how different parameters are utilized in the validator sources.

Unlike configuration parameters with non-negative indices, those with negative indices can hold arbitrary values. Validators do not enforce any restrictions on these values. As a result, they can be used to store essential information, such as the Unix time when specific smart contracts are set to begin operating. This information is not critical for block generation but is necessary for some fundamental smart contracts.

Changing configuration parameters

The current values of configuration parameters are stored in a special section of the masterchain state. But how are they changed?

There is a special smart contract known as the configuration smart contract that resides in the masterchain. Its address is specified by the config_addr field in ConfigParams. The first cell reference in its data must contain an up-to-date copy of all configuration parameters. When a new masterchain block is generated, the configuration smart contract is accessed using its address (config_addr), and the new configuration dictionary is extracted from the first cell reference of its data.

Following some validity checks—like ensuring that any value with a non-negative 32-bit index i is indeed a valid TL-B type (ConfigParam i)—the validator copies this new configuration dictionary into the portion of the masterchain that contains ConfigParams. This operation occurs after all transactions have been created, meaning only the final version of the new configuration dictionary stored in the smart contract is evaluated.

If the validity checks fail, the existing configuration dictionary remains unchanged, ensuring that the configuration smart contract cannot install invalid parameter values. If the new configuration dictionary is identical to the current one, no checks are performed, and no changes are made.

All changes to configuration parameters are executed by the configuration smart contract, which defines the rules for modifying these parameters. Currently, the contract supports two methods for changing them:

• External message: This method involves an external message signed by a specific private key, which corresponds to a public key stored in the configuration smart contract's data. This approach is typically used in the testnet and, possibly, in smaller private test networks controlled by a single entity, as it allows the operator to easily modify any configuration parameter values.

  It is important to note that this public key can be changed through a special external message signed by the previous key, and if changed to zero, this mechanism becomes disabled. This means the method can be used for fine-tuning right after launch and then permanently disabled.

• Configuration proposals: This method involves creating "configuration proposals" that validators vote on. Generally, a configuration proposal must gather votes from more than 3/4 (75%) of all validators by weight, and this requires approval in multiple rounds (i.e., several consecutive sets of validators must confirm the proposed parameter change). This serves as the distributed governance mechanism for the TON blockchain Mainnet.

Param 0: config address

This parameter is the address of a special smart contract that stores the blockchain's configuration. The configuration is stored in the contract to simplify its loading and modification during validator voting.

Parameter #0 on mainnet

Param 1: elector address

This parameter is the address of the elector smart contract, responsible for appointing validators, distributing rewards, and voting on changes to blockchain parameters.

Parameter #1 on mainnet

Param 2: TON minting address

This parameter represents the address of the system, on behalf of which new Gram are minted and sent as rewards for validating the blockchain.

Parameter #2 on mainnet

Param 3: fee collector address

This parameter is the address of the transaction fee collector.

Parameter #3 on mainnet

Param 4: root DNS address

This parameter is the address of the root DNS contract of the TON network.

Parameter #4 on mainnet

Param 6: extra currency fee

This parameter is responsible for minting fees for new currencies.

Parameter #6 on mainnet

Param 7: extra currency volume

This parameter stores the volume of each extra currency in circulation. The data is organized as a dictionary (also referred to as a hashmap). The structure uses the format currency_id -> amount, where the amount is represented as a VarUInteger 32, which is an integer ranging from 0 to 2^248-1.

Parameter #7 on mainnet

Param 8: network version

This parameter indicates the network version and additional capabilities supported by the validators.

• version: This field specifies the version.

• capabilities: This field is a set of flags that are used to indicate the presence or absence of certain features or capabilities.

Thus, when updating the network, validators will vote to change parameter 8. This way, the TON Blockchain network can be updated without downtime.

Parameter #8 on mainnet

Param 9: mandatory params

This parameter contains a list (binary tree) of mandatory parameters. It ensures that certain configuration parameters are always present and cannot be removed by a proposal to change the configuration until parameter 9 changes.

Parameter #9 on mainnet

Param 10: critical params

This parameter represents a list (binary tree) of critical TON parameters whose change significantly affects the network, so more voting rounds are held.

Parameter #10 on mainnet

Param 11: config params

This parameter indicates under what conditions proposals to change the TON configuration are accepted.

• min_tot_rounds: The minimum number of rounds before a proposal can be applied. Currently, this parameter is not used: only max_tot_round (when the proposal will be rejected) and min_wins (when the proposal will be accepted) matter.

• max_tot_rounds: The maximum number of rounds, upon reaching which the proposal will automatically be rejected

• min_wins: The required number of wins (3/4 of validators by the sum of the pledges must vote in favor)

• max_losses: The maximum number of losses, upon reaching which the proposal will automatically be rejected

• min_store_sec and max_store_sec determine the possible time interval during which the proposal will be stored

• bit_price and cell_price indicate the price of storing one bit or one cell of the proposal

Parameter #11 on mainnet

Param 12: Workchain config

This parameter represents the configuration of a workchain in the TON Blockchain. workchains are designed as independent blockchains that can operate in parallel, allowing TON to scale and process a large number of transactions and smart contracts.

Workchain configuration parameters

• enabled_since: A UNIX timestamp of the moment this workchain was enabled.

• actual_min_split: The minimum depth of the split (sharding) of this workchain, supported by validators.

• min_split: The minimum depth of the split of this workchain, set by the configuration.

• max_split: The maximum depth of the split of this workchain.

• basic: A boolean flag (1 for true, 0 for false) indicating whether this workchain is basic, i.e., handles Gram values (smart contracts based on the TON Virtual Machine).

• active: A boolean flag indicating whether this workchain is active at the moment.

• accept_msgs: A boolean flag indicating whether this workchain is accepting messages at the moment.

• flags: Additional flags for the workchain (reserved, currently always 0).

• zerostate_root_hash and zerostate_file_hash: Hashes of the first block of the workchain.

• version: Version of the workchain.

• format: The format of the workchain, which includes vm_version and vm_mode - the virtual machine used there.

Parameter #12 on mainnet

Param 13: complaint cost

This parameter defines the cost of filing complaints about the incorrect operation of validators in the elector smart contract.

Parameter #13 on mainnet

Param 14: block reward

This parameter indicates the reward for creating a block in the TON Blockchain. Values are in nanograms; therefore, the reward for block creation in the masterchain is 1.7 Gram, while in the basechain, it is 1.0 Gram. In the event of a workchain split, the block reward is also divided: if there are two shardchains within the workchain, then the reward for each shard block will be 0.5 Gram.

Parameter #14 on mainnet

Param 15: elections timing

This parameter contains the duration of different stages of elections and validators' work in the TON Blockchain.

For each validation period, there is an election_id equal to the UNIX-format time at the start of the validation.

You can get the current election_id (if elections are ongoing) or the past one by invoking the elector smart contract's respective get-methods active_election_id and past_election_ids.

Election and validation timing parameters

• validators_elected_for: The number of seconds the elected validators perform their role (one round).

• elections_start_before: The seconds before the end of the current round, when the election process for the next period will start.

• elections_end_before: The seconds before the end of the current round, the validators for the next round will be chosen.

• stake_held_for: The period for which a validator's stake is held (for handling complaints) after the round expires.

Examples

In the TON Blockchain, validation periods are typically divided into even and odd rounds that alternate. Voting for the next round occurs during the previous one, so a validator must allocate their funds into two separate pools to participate in both rounds.

Mainnet

Current values:

constants = {
    'validators_elected_for': 65536,  # 18.2 hours
    'elections_start_before': 32768,  # 9.1 hours
    'elections_end_before': 8192,     # 2.2 hours
    'stake_held_for': 32768           # 9.1 hours
}

Scheme: