diff --git a/foundations/config.mdx b/foundations/config.mdx index 87c717f74..f1b991c7e 100644 --- a/foundations/config.mdx +++ b/foundations/config.mdx @@ -432,10 +432,14 @@ This parameter provides the configuration for the `Catchain` protocol in the TON This parameter provides the configuration for the consensus protocol above `Catchain` ([Param 28](#param-28)) in the TON Blockchain. The consensus protocol is a crucial component of a blockchain network, and it ensures that all nodes agree on the state of the distributed ledger. +`ConfigParam 29` has evolved through several constructors. The most recent one, `consensus_config_v4#d9`, is documented in [`block.tlb`](https://github.com/ton-blockchain/ton/blob/af252bcdaea357fee21739e984654c2c84e7d61d/crypto/block/block.tlb#L782) and is identical to the previous `consensus_config_v3#d8`, except that one bit is reallocated from `flags` to a new `use_quic:Bool` field that selects the network transport used by the legacy Catchain consensus path. + ### Configuration parameters - `flags`: A general field that can be used to set various binary parameters. +- `use_quic`: A Boolean value indicating whether the legacy Catchain consensus path uses QUIC transport instead of RLDP2. Introduced in `consensus_config_v4#d9`; has the same meaning as the `use_quic` field in [Param 30](#param-30). + - `new_catchain_ids`: A Boolean value indicating whether to generate new `Catchain` identifiers. - `round_candidates`: The number of candidates to be considered in each round of the consensus protocol. @@ -460,8 +464,150 @@ This parameter provides the configuration for the consensus protocol above `Catc For up-to-date values, see [https://tonviewer.com/config](https://tonviewer.com/config). +#### On-chain schema + +`ConfigParam 29` is a tagged union: validators must accept any of the legacy constructors so old serialized configs keep parsing, but new on-chain values are written using the latest tag. The current set defined in [`block.tlb`](https://github.com/ton-blockchain/ton/blob/af252bcdaea357fee21739e984654c2c84e7d61d/crypto/block/block.tlb#L782) is: + +```tlb +consensus_config#d6 round_candidates:# { round_candidates >= 1 } + next_candidate_delay_ms:uint32 consensus_timeout_ms:uint32 + fast_attempts:uint32 attempt_duration:uint32 catchain_max_deps:uint32 + max_block_bytes:uint32 max_collated_bytes:uint32 = ConsensusConfig; + +consensus_config_new#d7 flags:(## 7) { flags = 0 } new_catchain_ids:Bool + round_candidates:(## 8) { round_candidates >= 1 } + next_candidate_delay_ms:uint32 consensus_timeout_ms:uint32 + fast_attempts:uint32 attempt_duration:uint32 catchain_max_deps:uint32 + max_block_bytes:uint32 max_collated_bytes:uint32 = ConsensusConfig; + +consensus_config_v3#d8 flags:(## 7) { flags = 0 } new_catchain_ids:Bool + round_candidates:(## 8) { round_candidates >= 1 } + next_candidate_delay_ms:uint32 consensus_timeout_ms:uint32 + fast_attempts:uint32 attempt_duration:uint32 catchain_max_deps:uint32 + max_block_bytes:uint32 max_collated_bytes:uint32 + proto_version:uint16 = ConsensusConfig; + +consensus_config_v4#d9 flags:(## 6) { flags = 0 } use_quic:Bool new_catchain_ids:Bool + round_candidates:(## 8) { round_candidates >= 1 } + next_candidate_delay_ms:uint32 consensus_timeout_ms:uint32 + fast_attempts:uint32 attempt_duration:uint32 catchain_max_deps:uint32 + max_block_bytes:uint32 max_collated_bytes:uint32 + proto_version:uint16 catchain_max_blocks_coeff:uint32 = ConsensusConfig; + +_ ConsensusConfig = ConfigParam 29; +``` + +#### `consensus_config_v4#d9` (current format) + +`consensus_config_v4#d9` is the current canonical layout for `ConfigParam 29`. Compared to `consensus_config_v3#d8`: + +| Aspect | `consensus_config_v3#d8` | `consensus_config_v4#d9` | +| ------------- | ------------------------ | ------------------------------------------ | +| `flags` width | `## 7` | `## 6` (one bit reallocated) | +| New field | — | `use_quic:Bool` placed right after `flags` | +| Other fields | unchanged | unchanged | + +The reallocation is wire-compatible in the sense that no existing flag bit is repurposed — the previous `flags` value of `0` is still expressible — but the new constructor has its own tag (`#d9`) so parsers must recognize it explicitly. + + + [Parameter #29 on mainnet](https://tonviewer.com/config#29) +## Param 30: consensus extension + + + +This parameter stores optional per-workchain settings for the [Simplex](https://github.com/ton-blockchain/simplex-docs/blob/main/Simplex.md)-based Catchain 2.0 consensus path. It does not fully replace `ConfigParam 29`: the node still uses `max_block_size` and `max_collated_data_size` from the `ConfigParam 29`. + +The `crypto/block/block.tlb` [defines](https://github.com/ton-blockchain/ton/blob/v2026.04/crypto/block/block.tlb#L782) the following schema: + +```tlb +simplex_config#21 flags:(## 7) + use_quic:Bool + target_rate_ms:uint32 + slots_per_leader_window:uint32 + first_block_timeout_ms:uint32 + max_leader_window_desync:uint32 + = NewConsensusConfig; + +simplex_config_v2#22 flags:(## 7) + use_quic:Bool + slots_per_leader_window:uint32 + noncritical_params:(HashmapE 8 uint32) + = NewConsensusConfig; + +new_consensus_config_all#10 + mc:(Maybe ^NewConsensusConfig) + shard:(Maybe ^NewConsensusConfig) + = NewConsensusConfigAll; + +_ NewConsensusConfigAll = ConfigParam 30; +``` + +There are two optional refs in `new_consensus_config_all#10`. If a ref is absent, then the pre-2.0 Catchain config is active for the corresponding class of chains: + +| Field | Type | Meaning | +| ------- | --------------------------- | ------------------------------------------------------- | +| `mc` | `Maybe ^NewConsensusConfig` | Config for the masterchain (`workchain = -1`) | +| `shard` | `Maybe ^NewConsensusConfig` | Config for shardchains (all non-masterchain workchains) | + +The `NewConsensusConfig` has two constructors: + +- `simplex_config#21` is the legacy fixed-layout format; scheduled for removal. +- `simplex_config_v2#22` is the current extensible format, which supports arbitrary `noncritical_params` without changes to the `block.tlb` layout. + +The `simplex_config_v2#22` constructor moves noncritical configuration parameters into a sparse dictionary: + +```tlb +simplex_config_v2#22 flags:(## 7) + use_quic:Bool + slots_per_leader_window:uint32 + noncritical_params:(HashmapE 8 uint32) + = NewConsensusConfig; +``` + +### Configuration parameters of `simplex_config_v2` + +- `flags`: A general field that can be used to set various binary parameters. +- `use_quic`: Whether the QUIC transport is used instead of RLDP2. Set to **True** in mainnet. +- `slots_per_leader_window`: Number of consecutive slots assigned to one leader. Set to **4** in mainnet. +- `max_block_size = 4 MiB` +- `max_collated_data_size = 4 MiB` +- `noncritical_params`: A `HashmapE 8 uint32` map from parameter IDs to raw 32-bit values. + +The `noncritical_params` dictionary contains tunable timing and DoS-protection parameters that might differ between validators: + +- The key is an 8-bit parameter ID. +- The value is always a raw 32-bit word. +- Unknown IDs are ignored by the current implementation. +- Missing IDs use default values. +- Duration-like parameters store milliseconds directly. +- Floating-point parameters store `float32` bits according to the [IEEE-754](https://en.wikipedia.org/wiki/IEEE_754) standard in a `uint32` value. The loader then reinterprets these bits as a floating-point numeric value. + +IDs from `0` through `14` are recognized and supported. On the mainnet, only IDs `0`, `1`, and `13` are explicitly set. All other IDs are normally absent and use defaults. + +| ID | Name | Stored as | Default | Meaning | +| ---- | -------------------------------------- | -------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- | +| `0` | `target_rate` | `uint32` milliseconds | `2400 ms` | Target slot or block interval; used for leader pacing, block production timing, and skip scheduling. | +| `1` | `first_block_timeout` | `uint32` milliseconds | `1000 ms` | Base timeout before skip voting starts for the first missing block in a leader window. | +| `2` | `first_block_timeout_multiplier` | `float32` bits in `uint32` | `1.2` | Multiplier applied to `first_block_timeout` after a window that had skips. | +| `3` | `first_block_timeout_cap` | `uint32` milliseconds | `100000 ms` | Cap for the adaptive `first_block_timeout` growth. | +| `4` | `candidate_resolve_timeout` | `uint32` milliseconds | `1000 ms` | Initial timeout for candidate or notarization resolution requests. | +| `5` | `candidate_resolve_timeout_multiplier` | `float32` bits in `uint32` | `1.2` | Backoff multiplier for candidate resolution retries. | +| `6` | `candidate_resolve_timeout_cap` | `uint32` milliseconds | `10000 ms` | Cap for candidate resolution timeout growth. | +| `7` | `candidate_resolve_cooldown` | `uint32` milliseconds | `10 ms` | Cooldown between candidate resolution attempts. | +| `8` | `standstill_timeout` | `uint32` milliseconds | `10000 ms` | No-progress timeout before standstill recovery or rebroadcast logic triggers. | +| `9` | `standstill_max_egress_bytes_per_s` | `uint32` number | `6553600` (`50 << 17`) | Egress rate cap used during standstill rebroadcast. | +| `10` | `max_leader_window_desync` | `uint32` number | `250` | Maximum tolerated future leader-window distance for inbound Simplex traffic. | +| `11` | `bad_signature_ban_duration` | `uint32` milliseconds | `5000 ms` | Temporary ban duration after receiving bad signatures from a peer. | +| `12` | `candidate_resolve_rate_limit` | `uint32` number | `10` | Per-peer rate limit for candidate resolution requests. | +| `13` | `min_block_interval` | `uint32` milliseconds | `0 ms` | Minimum interval between parent block time and the next locally generated block. | +| `14` | `no_empty_blocks_on_error_timeout` | `uint32` milliseconds | `15000 ms` | How long empty-block fallback is allowed after the last finalized block when collation fails or times out. | + ## Param 31: fee-exempt contracts This parameter represents the configuration of smart contract addresses from which no fees are charged for either gas or storage, and where **tick-tock** transactions can be created. The list usually includes governance contracts. The parameter is presented as a binary tree structure — a tree (HashMap 256), where the keys are a 256-bit representation of the address. Only addresses in the masterchain can be present in this list.