starfish_config/

parameters.rs

// Copyright (c) Mysten Labs, Inc.
// Modifications Copyright (c) 2024 IOTA Stiftung
// SPDX-License-Identifier: Apache-2.0

use std::{path::PathBuf, time::Duration};

use serde::{Deserialize, Serialize};

/// Ceiling on the number of headers, and on the number of shards, a bundle may
/// declare. Enforced while decoding, before the entries are materialised, so a
/// peer cannot make the decoder build a vector far larger than the configured
/// caps allow it to keep. Both caps are validated against it at startup.
pub const MAX_HEADERS_OR_SHARDS_PER_BUNDLE: usize = 1024;

/// Ceiling on the headers a fetch response may carry, for header sync and
/// commit sync alike. The server truncates its response to its own
/// `max_headers_per_header_sync_fetch` or `max_headers_per_commit_sync_fetch`,
/// both validated against this at startup, so a client can reject a response
/// past it as misbehaviour while still accepting a peer configured above its
/// own cap. Enforced while decoding each response message, before its entries
/// are materialised.
pub const HEADERS_PER_FETCH_CEILING: usize = 1024;

/// Ceiling on the transaction entries a fetch request or response may carry,
/// for transaction sync and regular commit sync alike. A client requests at
/// most its own `max_transactions_per_transaction_sync_fetch` or
/// `max_transactions_per_commit_sync_fetch`, both validated against this at
/// startup, and the server returns at most one entry per requested reference.
/// Enforced while decoding each message, before its entries are materialised.
pub const TRANSACTIONS_PER_FETCH_CEILING: usize = 1024;

/// Ceiling on the commits a commit-sync fetch may request, for regular and
/// fast commit sync alike. A client requests at most its own
/// `commit_sync_batch_size` or `fast_commit_sync_batch_size` commits, both
/// validated against this at startup. Enforced while decoding each response
/// message, before its entries are materialised.
pub const COMMITS_PER_FETCH_CEILING: usize = 1024;

/// Operational configurations of a consensus authority.
///
/// All fields should tolerate inconsistencies among authorities, without
/// affecting safety of the protocol. Otherwise, they need to be part of IOTA
/// protocol config or epoch state on-chain.
///
/// NOTE: fields with default values are specified in the serde default
/// functions. Most operators should not need to specify any field, except
/// db_path.
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct Parameters {
    /// Path to consensus DB for this epoch. Required when initializing
    /// consensus. This is calculated based on user configuration for base
    /// directory.
    #[serde(skip)]
    pub db_path: PathBuf,

    /// Time to wait for parent round leader before sealing a block, from when
    /// parent round has a quorum.
    #[serde(default = "Parameters::default_leader_timeout")]
    pub leader_timeout: Duration,

    /// Sustained spacing between own blocks: long-run production never exceeds
    /// one block per `min_block_delay`. This avoids generating too many rounds
    /// when latency is low. This is especially necessary for tests running
    /// locally. If setting a non-default value, it should be set low enough
    /// to avoid reducing round rate and increasing latency in realistic and
    /// distributed configurations.
    #[serde(default = "Parameters::default_min_block_delay")]
    pub min_block_delay: Duration,

    /// Soft counterpart of `leader_timeout`: after this duration we are
    /// willing to propose a block even without a strong-vote quorum, to avoid
    /// liveness stalls when leader data is slow to propagate. Fires earlier
    /// than `leader_timeout` and does not force block creation on its own.
    #[serde(default = "Parameters::default_soft_leader_timeout")]
    pub soft_leader_timeout: Duration,

    /// Window bounding own block production together with `min_block_delay`:
    /// idle time accrues budget for bursts of up to `block_rate_window /
    /// min_block_delay` back-to-back blocks, letting a validator that fell
    /// behind catch up on rounds instead of skipping them. Set at or below
    /// `min_block_delay` to disable bursting (fixed spacing between blocks).
    #[serde(default = "Parameters::default_block_rate_window")]
    pub block_rate_window: Duration,

    /// Number of block headers to fetch per commit sync request.
    #[serde(default = "Parameters::default_max_headers_per_commit_sync_fetch")]
    pub max_headers_per_commit_sync_fetch: usize,

    /// Number of transactions to fetch per commit sync request.
    #[serde(default = "Parameters::default_max_transactions_per_commit_sync_fetch")]
    pub max_transactions_per_commit_sync_fetch: usize,

    /// Number of block headers to fetch per header sync (periodic or live)
    /// request.
    #[serde(default = "Parameters::default_max_headers_per_header_sync_fetch")]
    pub max_headers_per_header_sync_fetch: usize,

    /// Number of transactions to fetch per transaction sync request.
    #[serde(default = "Parameters::default_max_transactions_per_transaction_sync_fetch")]
    pub max_transactions_per_transaction_sync_fetch: usize,

    /// Time to wait during node start up until the node has synced the last
    /// proposed block via the network peers. When set to `0` the sync
    /// mechanism is disabled. This property is meant to be used for amnesia
    /// recovery.
    #[serde(default = "Parameters::default_sync_last_known_own_block_timeout")]
    pub sync_last_known_own_block_timeout: Duration,

    /// The number of rounds of blocks to be kept in the Dag state cache per
    /// authority. The larger the number the more the blocks that will be
    /// kept in memory allowing minimising any potential disk access.
    /// Value should be at minimum 50 rounds to ensure node performance, but
    /// being too large can be expensive in memory usage.
    #[serde(default = "Parameters::default_dag_state_cached_rounds")]
    pub dag_state_cached_rounds: u32,

    /// Rounds a header from a far-future-bounded source may lead the locally
    /// accepted frontier, in addition to `dag_state_cached_rounds`, before it
    /// is dropped as too far ahead to connect.
    #[serde(default = "Parameters::default_peer_round_ahead_margin")]
    pub peer_round_ahead_margin: u32,

    // Number of authorities commit syncer fetches in parallel.
    // Both commits in a range and blocks referenced by the commits are fetched per authority.
    #[serde(default = "Parameters::default_commit_sync_parallel_fetches")]
    pub commit_sync_parallel_fetches: usize,

    // Number of commits to fetch in a batch, also the maximum number of commits returned per
    // fetch. If this value is set too small, fetching becomes inefficient.
    // If this value is set too large, it can result in load imbalance and stragglers.
    #[serde(default = "Parameters::default_commit_sync_batch_size")]
    pub commit_sync_batch_size: u32,

    // This affects the maximum number of commit batches being fetched, and those fetched but not
    // processed as consensus output, before throttling of outgoing commit fetches starts.
    #[serde(default = "Parameters::default_commit_sync_batches_ahead")]
    pub commit_sync_batches_ahead: usize,

    /// Maximum number of commits scanned and replayed per batch during
    /// recovery, bounding peak memory when a large unprocessed range is
    /// replayed at startup.
    #[serde(default = "Parameters::default_commit_recovery_batch_size")]
    pub commit_recovery_batch_size: u32,

    /// Maximum number of headers to be included in a bundle. Headers exceeding
    /// the max allowed limit will be truncated.
    #[serde(default = "Parameters::default_max_headers_per_bundle")]
    pub max_headers_per_bundle: usize,

    /// Maximum number of transaction shards to be included in a bundle. Shards
    /// exceeding the max allowed limit will be truncated.
    #[serde(default = "Parameters::default_max_shards_per_bundle")]
    pub max_shards_per_bundle: usize,

    /// Tonic network settings.
    #[serde(default = "TonicParameters::default")]
    pub tonic: TonicParameters,

    /// Number of commits requested per fast commit sync fetch. A response may
    /// carry up to twice this many, since it extends past the requested end to
    /// reach a certifiable commit. Set too small, fetching is inefficient and
    /// the server has little room to reach one; set too large, it causes load
    /// imbalance and stragglers.
    #[serde(default = "Parameters::default_fast_commit_sync_batch_size")]
    pub fast_commit_sync_batch_size: u32,

    // Gap threshold for switching between commit syncers. When the gap between quorum and local
    // commit index is larger than this threshold, FastCommitSyncer fetches. Otherwise,
    // CommitSyncer fetches.
    #[serde(default = "Parameters::default_commit_sync_gap_threshold")]
    pub commit_sync_gap_threshold: u32,

    /// Enable FastCommitSyncer for faster recovery from large commit gaps.
    /// Enabled by default; operators can disable it locally if bugs are
    /// discovered.
    #[serde(default = "Parameters::default_enable_fast_commit_syncer")]
    pub enable_fast_commit_syncer: bool,

    /// Reconnect block streams after fast commit sync reinitializes consensus,
    /// discarding bundles buffered against the previous state. Enabled by
    /// default; operators can disable it locally. Has no effect unless
    /// `enable_fast_commit_syncer` is also enabled, since only fast sync
    /// signals the reset.
    #[serde(default = "Parameters::default_enable_block_stream_reset_on_fast_sync_exit")]
    pub enable_block_stream_reset_on_fast_sync_exit: bool,

    /// Ask commit-sync peers that have voted for the end of the requested
    /// range before those that have not, since a vote means the peer has
    /// solidified every commit in the range. Peers without an observed vote
    /// are ordered behind; each fetch round tries a bounded number of peers,
    /// so on a committee larger than that bound they can stay outside the
    /// round until their votes are observed. The header fetch that
    /// reinitializes the node at the end of fast sync likewise asks peers that
    /// have voted for the last commit first. Enabled by default; disabling it
    /// leaves peers in the order `enable_peer_responsiveness_ranking` gives
    /// them.
    #[serde(default = "Parameters::default_enable_commit_sync_peer_selection_by_commit_votes")]
    pub enable_commit_sync_peer_selection_by_commit_votes: bool,

    /// Enable adaptive acknowledgment filtering for StarfishSpeed.
    /// Local heuristic that leaves out of leader blocks the acknowledgments
    /// that the voters are not expected to hold at the next round, judged
    /// from how soon they acknowledged recent blocks. Voters count by how
    /// often this node's blocks reference them. Deferred acknowledgments go
    /// into later blocks. Effective only when the
    /// protocol-level `consensus_starfish_speed` flag is also on.
    #[serde(default = "Parameters::default_enable_starfish_speed_adaptive_acknowledgments")]
    pub enable_starfish_speed_adaptive_acknowledgments: bool,

    /// Prefer more responsive peers when the transactions synchronizer, the
    /// commit syncer and the header synchronizer select peers to fetch from.
    /// Responses are verified the same way regardless, so it cannot affect
    /// safety. Enabled by default; disabling it restores the previous
    /// selection: for the transactions synchronizer a uniform random order
    /// that excludes the most recently failed peers (up to less than f+1 by
    /// stake), and for the commit syncer and the header synchronizer a uniform
    /// random order.
    #[serde(default = "Parameters::default_enable_peer_responsiveness_ranking")]
    pub enable_peer_responsiveness_ranking: bool,

    /// Ask only a bounded number of peers that recently supplied a new header
    /// or referenced a missing one to push more headers from that author.
    #[serde(default = "Parameters::default_enable_bounded_header_advertisement")]
    pub enable_bounded_header_advertisement: bool,

    /// Ask only the fastest peers that together provide enough shards and
    /// stake for reconstruction. Enabled by default; disabling it asks every
    /// peer.
    #[serde(default = "Parameters::default_enable_shard_peer_selection")]
    pub enable_shard_peer_selection: bool,

    /// Port for the DAG visualizer gRPC server (localhost only).
    /// When set, starts a debugging server for real-time DAG visualization.
    /// Only has an effect when the `dag-visualizer` feature is compiled in.
    /// Disabled by default (None).
    #[serde(default)]
    pub dag_visualizer_port: Option<u16>,

    /// Maximum number of rounds the last commit's leader may run ahead of the
    /// last solid commit's leader before the node stops accepting new block
    /// bundles and restricts header fetching, until solidification catches up.
    #[serde(default = "Parameters::default_solid_commit_lag_threshold")]
    pub solid_commit_lag_threshold: u32,

    /// Maximum number of shards from one relaying authority retained across
    /// all pending shard accumulators. At the budget, admitting a new shard
    /// from the authority evicts its oldest retained one, so reconstructor
    /// memory stays bounded by `committee size × budget × shard size`
    /// regardless of how far commits run ahead of solidification.
    #[serde(default = "Parameters::default_shard_budget_per_authority")]
    pub shard_budget_per_authority: u32,

    /// Maximum transaction payload bytes one fast commit-sync response carries.
    /// A fetch covering more commits than this is answered with the commits
    /// whose payloads fit, and the requester asks for the rest in its next
    /// fetch. When the range's first commit exceeds this on its own it is
    /// still served whole. A requester stops reading a response once it passes
    /// this and its first commit is complete.
    #[serde(default = "Parameters::default_max_fast_commit_sync_transaction_bytes")]
    pub max_fast_commit_sync_transaction_bytes: usize,
}

impl Parameters {
    /// Threshold for the number of commits sent to the consumer but not yet
    /// handled, above which commit producers (commit syncers, commit observer
    /// recovery) pause to let the consumer catch up.
    pub fn unhandled_commits_threshold(&self) -> u32 {
        self.commit_sync_batch_size * (self.commit_sync_batches_ahead as u32)
    }

    pub(crate) fn default_leader_timeout() -> Duration {
        Duration::from_millis(200)
    }

    pub(crate) fn default_min_block_delay() -> Duration {
        if cfg!(msim) || std::env::var("__TEST_ONLY_CONSENSUS_USE_LONG_MIN_BLOCK_DELAY").is_ok() {
            // Checkpoint building and execution cannot keep up with high commit rate in
            // simtests, leading to long reconfiguration delays. This is because
            // simtest is single threaded, and spending too much time in
            // consensus can lead to starvation elsewhere.
            Duration::from_millis(400)
        } else if cfg!(test) {
            // Avoid excessive CPU, data and logs in tests.
            Duration::from_millis(250)
        } else {
            // For production, use min delay between block being set to 50ms, reducing the
            // block rate to 20 blocks/sec
            Duration::from_millis(50)
        }
    }

    pub(crate) fn default_soft_leader_timeout() -> Duration {
        Duration::from_millis(5)
    }

    pub(crate) fn default_block_rate_window() -> Duration {
        Duration::from_secs(2)
    }

    /// Burst capacity: maximum number of own blocks within `block_rate_window`
    /// (40 in production, 5 in msim, 8 in tests with the default window).
    pub fn block_rate_burst(&self) -> u64 {
        let interval_ms = self.min_block_delay.as_millis().max(1) as u64;
        (self.block_rate_window.as_millis() as u64 / interval_ms).max(1)
    }

    /// Highest round a header from a far-future-bounded source may have,
    /// relative to the accepted `frontier`, to still be close enough to
    /// connect; headers above this are too far ahead and dropped.
    pub fn far_future_round_ceiling(&self, frontier: u32) -> u32 {
        frontier
            .saturating_add(self.dag_state_cached_rounds)
            .saturating_add(self.peer_round_ahead_margin)
    }

    /// Maximum number of block headers served per fetch request, depending on
    /// whether the request comes from commit sync or the header synchronizer.
    pub fn max_headers_per_fetch(&self, commit_sync: bool) -> usize {
        if commit_sync {
            self.max_headers_per_commit_sync_fetch
        } else {
            self.max_headers_per_header_sync_fetch
        }
    }

    /// Validates local consensus parameters, rejecting zero values that can
    /// lead to synchronization problems. Returns a description of the first
    /// offending field.
    pub fn validate(&self) -> Result<(), String> {
        let positive_fields = [
            (
                "max_headers_per_commit_sync_fetch",
                self.max_headers_per_commit_sync_fetch as u128,
            ),
            (
                "max_transactions_per_commit_sync_fetch",
                self.max_transactions_per_commit_sync_fetch as u128,
            ),
            (
                "max_headers_per_header_sync_fetch",
                self.max_headers_per_header_sync_fetch as u128,
            ),
            (
                "max_transactions_per_transaction_sync_fetch",
                self.max_transactions_per_transaction_sync_fetch as u128,
            ),
            (
                "dag_state_cached_rounds",
                self.dag_state_cached_rounds as u128,
            ),
            (
                "commit_sync_parallel_fetches",
                self.commit_sync_parallel_fetches as u128,
            ),
            (
                "commit_sync_batch_size",
                self.commit_sync_batch_size as u128,
            ),
            (
                "commit_recovery_batch_size",
                self.commit_recovery_batch_size as u128,
            ),
            (
                "commit_sync_batches_ahead",
                self.commit_sync_batches_ahead as u128,
            ),
            (
                "max_headers_per_bundle",
                self.max_headers_per_bundle as u128,
            ),
            ("max_shards_per_bundle", self.max_shards_per_bundle as u128),
            (
                "fast_commit_sync_batch_size",
                self.fast_commit_sync_batch_size as u128,
            ),
            (
                "max_fast_commit_sync_transaction_bytes",
                self.max_fast_commit_sync_transaction_bytes as u128,
            ),
            (
                "tonic.connection_buffer_size",
                self.tonic.connection_buffer_size as u128,
            ),
            (
                "tonic.excessive_message_size",
                self.tonic.excessive_message_size as u128,
            ),
            (
                "tonic.message_size_limit",
                self.tonic.message_size_limit as u128,
            ),
            (
                "tonic.keepalive_interval",
                self.tonic.keepalive_interval.as_nanos(),
            ),
            (
                "shard_budget_per_authority",
                self.shard_budget_per_authority as u128,
            ),
        ];
        for (name, value) in positive_fields {
            if value == 0 {
                return Err(format!("{name} must be positive"));
            }
        }
        let bundle_fields = [
            ("max_headers_per_bundle", self.max_headers_per_bundle),
            ("max_shards_per_bundle", self.max_shards_per_bundle),
        ];
        for (name, value) in bundle_fields {
            if value > MAX_HEADERS_OR_SHARDS_PER_BUNDLE {
                return Err(format!(
                    "{name} must not exceed {MAX_HEADERS_OR_SHARDS_PER_BUNDLE}"
                ));
            }
        }
        let header_fetch_fields = [
            (
                "max_headers_per_header_sync_fetch",
                self.max_headers_per_header_sync_fetch,
            ),
            (
                "max_headers_per_commit_sync_fetch",
                self.max_headers_per_commit_sync_fetch,
            ),
        ];
        for (name, value) in header_fetch_fields {
            if value > HEADERS_PER_FETCH_CEILING {
                return Err(format!(
                    "{name} must not exceed {HEADERS_PER_FETCH_CEILING}"
                ));
            }
        }
        let transaction_fetch_fields = [
            (
                "max_transactions_per_transaction_sync_fetch",
                self.max_transactions_per_transaction_sync_fetch,
            ),
            (
                "max_transactions_per_commit_sync_fetch",
                self.max_transactions_per_commit_sync_fetch,
            ),
        ];
        for (name, value) in transaction_fetch_fields {
            if value > TRANSACTIONS_PER_FETCH_CEILING {
                return Err(format!(
                    "{name} must not exceed {TRANSACTIONS_PER_FETCH_CEILING}"
                ));
            }
        }
        let commit_fetch_fields = [
            ("commit_sync_batch_size", self.commit_sync_batch_size),
            (
                "fast_commit_sync_batch_size",
                self.fast_commit_sync_batch_size,
            ),
        ];
        for (name, value) in commit_fetch_fields {
            if value as usize > COMMITS_PER_FETCH_CEILING {
                return Err(format!(
                    "{name} must not exceed {COMMITS_PER_FETCH_CEILING}"
                ));
            }
        }
        Ok(())
    }

    // Maximum number of block headers to fetch per commit sync request.
    pub(crate) fn default_max_headers_per_commit_sync_fetch() -> usize {
        if cfg!(msim) {
            // Exercise hitting blocks per fetch limit.
            10
        } else {
            1000
        }
    }

    // Maximum number of transactions to fetch per commit sync request.
    pub(crate) fn default_max_transactions_per_commit_sync_fetch() -> usize {
        if cfg!(msim) {
            // Exercise hitting transactions per fetch limit.
            10
        } else {
            1000
        }
    }

    // Maximum number of block headers to fetch per header sync (periodic or
    // live) request.
    pub(crate) fn default_max_headers_per_header_sync_fetch() -> usize {
        if cfg!(msim) {
            // Exercise hitting blocks per fetch limit.
            10
        } else {
            // TODO: This might should match the value of block headers in the bundle.
            100
        }
    }

    // Maximum number of transactions to fetch per transaction sync request.
    pub(crate) fn default_max_transactions_per_transaction_sync_fetch() -> usize {
        if cfg!(msim) { 10 } else { 1000 }
    }

    pub(crate) fn default_sync_last_known_own_block_timeout() -> Duration {
        if cfg!(msim) {
            Duration::from_millis(500)
        } else {
            // Here we prioritise liveness over the complete de-risking of block
            // equivocation. 5 seconds in the majority of cases should be good
            // enough for this given a healthy network.
            Duration::from_secs(5)
        }
    }

    pub(crate) fn default_dag_state_cached_rounds() -> u32 {
        if cfg!(msim) {
            // Exercise reading blocks from store.
            5
        } else {
            500
        }
    }

    pub(crate) fn default_peer_round_ahead_margin() -> u32 {
        1000
    }

    pub(crate) fn default_commit_sync_parallel_fetches() -> usize {
        8
    }

    pub(crate) fn default_commit_sync_batch_size() -> u32 {
        if cfg!(msim) {
            // Exercise commit sync.
            5
        } else {
            100
        }
    }

    pub(crate) fn default_commit_recovery_batch_size() -> u32 {
        if cfg!(msim) { 3 } else { 250 }
    }

    pub(crate) fn default_commit_sync_batches_ahead() -> usize {
        // This is set to be a multiple of default commit_sync_parallel_fetches to allow
        // fetching ahead, while keeping the total number of inflight fetches
        // and unprocessed fetched commits limited.
        32
    }

    pub(crate) fn default_max_headers_per_bundle() -> usize {
        150
    }

    pub(crate) fn default_max_shards_per_bundle() -> usize {
        150
    }

    pub(crate) fn default_fast_commit_sync_batch_size() -> u32 {
        if cfg!(msim) {
            // Exercise fast commit sync.
            5
        } else {
            // Sized so that commit_sync_parallel_fetches ranges fit under the
            // unhandled-commits threshold (8 x 400 <= 3200), letting fast sync
            // actually run its fetches in parallel. The server chunks larger
            // responses across multiple messages either way.
            400
        }
    }

    pub(crate) fn default_commit_sync_gap_threshold() -> u32 {
        if cfg!(msim) {
            // Use smaller threshold for testing.
            10
        } else {
            // When gap > 1000, FastCommitSyncer is more efficient.
            // When gap <= 1000, CommitSyncer handles incremental sync.
            1000
        }
    }

    pub(crate) fn default_enable_fast_commit_syncer() -> bool {
        // Enabled by default. Operators can disable it locally if bugs are discovered,
        // without waiting for a protocol upgrade.
        true
    }

    pub(crate) fn default_enable_block_stream_reset_on_fast_sync_exit() -> bool {
        true
    }

    pub(crate) fn default_enable_commit_sync_peer_selection_by_commit_votes() -> bool {
        // Enabled by default. Ordering only, so it cannot diverge consensus.
        true
    }

    pub(crate) fn default_enable_starfish_speed_adaptive_acknowledgments() -> bool {
        true
    }

    pub(crate) fn default_enable_peer_responsiveness_ranking() -> bool {
        true
    }

    pub(crate) fn default_enable_bounded_header_advertisement() -> bool {
        true
    }

    pub(crate) fn default_enable_shard_peer_selection() -> bool {
        true
    }

    pub(crate) fn default_solid_commit_lag_threshold() -> u32 {
        // The healthy gap is a few rounds at most; 500 rounds (a few minutes of
        // commits) is far above live jitter yet caps how long a solidification
        // stall can keep widening the shard/payload retention window.
        500
    }

    pub(crate) fn default_max_fast_commit_sync_transaction_bytes() -> usize {
        64 * 1024 * 1024
    }

    pub(crate) fn default_shard_budget_per_authority() -> u32 {
        // Honest need per authority is one shard per slot times a few rounds
        // until decode, well under the budget at any realistic committee size.
        // Worst-case total pool ≈ 3 × budget × the maximum payload size.
        1000
    }
}

impl Default for Parameters {
    fn default() -> Self {
        Self {
            db_path: PathBuf::default(),
            leader_timeout: Parameters::default_leader_timeout(),
            min_block_delay: Parameters::default_min_block_delay(),
            soft_leader_timeout: Parameters::default_soft_leader_timeout(),
            block_rate_window: Parameters::default_block_rate_window(),
            max_headers_per_commit_sync_fetch:
                Parameters::default_max_headers_per_commit_sync_fetch(),
            max_transactions_per_commit_sync_fetch:
                Parameters::default_max_transactions_per_commit_sync_fetch(),
            max_headers_per_header_sync_fetch:
                Parameters::default_max_headers_per_header_sync_fetch(),
            max_transactions_per_transaction_sync_fetch:
                Parameters::default_max_transactions_per_transaction_sync_fetch(),
            sync_last_known_own_block_timeout:
                Parameters::default_sync_last_known_own_block_timeout(),
            dag_state_cached_rounds: Parameters::default_dag_state_cached_rounds(),
            peer_round_ahead_margin: Parameters::default_peer_round_ahead_margin(),
            commit_sync_parallel_fetches: Parameters::default_commit_sync_parallel_fetches(),
            commit_sync_batch_size: Parameters::default_commit_sync_batch_size(),
            commit_sync_batches_ahead: Parameters::default_commit_sync_batches_ahead(),
            commit_recovery_batch_size: Parameters::default_commit_recovery_batch_size(),
            max_headers_per_bundle: Parameters::default_max_headers_per_bundle(),
            max_shards_per_bundle: Parameters::default_max_shards_per_bundle(),
            tonic: TonicParameters::default(),
            fast_commit_sync_batch_size: Parameters::default_fast_commit_sync_batch_size(),
            commit_sync_gap_threshold: Parameters::default_commit_sync_gap_threshold(),
            enable_fast_commit_syncer: Parameters::default_enable_fast_commit_syncer(),
            enable_block_stream_reset_on_fast_sync_exit:
                Parameters::default_enable_block_stream_reset_on_fast_sync_exit(),
            enable_commit_sync_peer_selection_by_commit_votes:
                Parameters::default_enable_commit_sync_peer_selection_by_commit_votes(),
            enable_starfish_speed_adaptive_acknowledgments:
                Parameters::default_enable_starfish_speed_adaptive_acknowledgments(),
            enable_peer_responsiveness_ranking:
                Parameters::default_enable_peer_responsiveness_ranking(),
            enable_bounded_header_advertisement:
                Parameters::default_enable_bounded_header_advertisement(),
            enable_shard_peer_selection: Parameters::default_enable_shard_peer_selection(),
            dag_visualizer_port: None,
            solid_commit_lag_threshold: Parameters::default_solid_commit_lag_threshold(),
            shard_budget_per_authority: Parameters::default_shard_budget_per_authority(),
            max_fast_commit_sync_transaction_bytes:
                Parameters::default_max_fast_commit_sync_transaction_bytes(),
        }
    }
}

#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct TonicParameters {
    /// Keepalive interval and timeouts for both client and server.
    ///
    /// If unspecified, this will default to 5s.
    #[serde(default = "TonicParameters::default_keepalive_interval")]
    pub keepalive_interval: Duration,

    /// Size of various per-connection buffers.
    ///
    /// If unspecified, this will default to 32MiB.
    #[serde(default = "TonicParameters::default_connection_buffer_size")]
    pub connection_buffer_size: usize,

    /// Response messages over this wire size, prefix plus compressed payload,
    /// increment a counter.
    ///
    /// If unspecified, this will default to 16MiB.
    #[serde(default = "TonicParameters::default_excessive_message_size")]
    pub excessive_message_size: usize,

    /// Hard message size limit for both requests and responses.
    /// This value is higher than strictly necessary, to allow overheads.
    /// Message size targets and soft limits are computed based on this value.
    ///
    /// If unspecified, this will default to 64MiB.
    #[serde(default = "TonicParameters::default_message_size_limit")]
    pub message_size_limit: usize,

    /// Maximum number of concurrent HTTP/2 streams a peer may open on a single
    /// connection. Bounds per-connection request fan-out.
    ///
    /// If unspecified, this will default to 64. `0` disables the limit, leaving
    /// the transport default.
    #[serde(default = "TonicParameters::default_max_concurrent_streams")]
    pub max_concurrent_streams: u32,

    /// Server-side fallback deadline for requests that omit a `grpc-timeout`
    /// header. The long-lived block-subscription stream is always exempt.
    ///
    /// If unspecified, this will default to 120s. A zero duration disables the
    /// fallback deadline.
    #[serde(default = "TonicParameters::default_request_timeout")]
    pub request_timeout: Duration,

    /// Hard size limit for request messages: inbound requests when decoding
    /// and outbound requests when encoding. Consensus requests are small (ref
    /// lists); large payloads belong to responses, bounded by
    /// `message_size_limit`. A smaller request bound shrinks the memory a
    /// single in-flight request can pin before its handler runs.
    ///
    /// If unspecified, this will default to 1MiB. `0` falls back to
    /// `message_size_limit`.
    #[serde(
        default = "TonicParameters::default_max_request_message_size",
        alias = "max_inbound_message_size"
    )]
    pub max_request_message_size: usize,

    /// Per-peer, per-RPC admission caps for the inbound consensus server.
    #[serde(default)]
    pub admission: AdmissionParameters,

    /// Deadline for receiving the request message that opens a block
    /// subscription stream. A peer that opens the stream and withholds the
    /// request is disconnected once it expires; the stream itself stays exempt
    /// from `request_timeout`.
    ///
    /// If unspecified, this will default to 30s. A zero duration disables the
    /// deadline.
    #[serde(default = "TonicParameters::default_subscribe_request_timeout")]
    pub subscribe_request_timeout: Duration,
}

impl TonicParameters {
    /// Hard size limit for request messages, `message_size_limit` when
    /// `max_request_message_size` is `0`.
    pub fn request_message_size_limit(&self) -> usize {
        if self.max_request_message_size == 0 {
            self.message_size_limit
        } else {
            self.max_request_message_size
        }
    }

    fn default_keepalive_interval() -> Duration {
        Duration::from_secs(5)
    }

    fn default_connection_buffer_size() -> usize {
        32 << 20
    }

    fn default_excessive_message_size() -> usize {
        16 << 20
    }

    fn default_message_size_limit() -> usize {
        64 << 20
    }

    fn default_max_concurrent_streams() -> u32 {
        64
    }

    fn default_request_timeout() -> Duration {
        Duration::from_secs(120)
    }

    fn default_max_request_message_size() -> usize {
        1 << 20
    }

    fn default_subscribe_request_timeout() -> Duration {
        Duration::from_secs(30)
    }
}

impl Default for TonicParameters {
    fn default() -> Self {
        Self {
            keepalive_interval: TonicParameters::default_keepalive_interval(),
            connection_buffer_size: TonicParameters::default_connection_buffer_size(),
            excessive_message_size: TonicParameters::default_excessive_message_size(),
            message_size_limit: TonicParameters::default_message_size_limit(),
            max_concurrent_streams: TonicParameters::default_max_concurrent_streams(),
            request_timeout: TonicParameters::default_request_timeout(),
            max_request_message_size: TonicParameters::default_max_request_message_size(),
            admission: AdmissionParameters::default(),
            subscribe_request_timeout: TonicParameters::default_subscribe_request_timeout(),
        }
    }
}

/// Per-peer, per-RPC concurrency caps for the inbound consensus gRPC server.
///
/// Each cap bounds how many concurrent requests of one RPC group a single
/// committee peer (keyed on its authenticated authority index) may have in
/// flight; a peer cannot consume another peer's budget. These are local,
/// non-protocol parameters — heterogeneous values across authorities are safe,
/// so they can be rolled out and tuned per node.
///
/// The defaults are sized for ~100-validator committees and the local
/// synchronizer fan-out toward one server. `0` turns a cap off; each cap is
/// checked on its own.
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct AdmissionParameters {
    /// Max concurrent block-subscription streams per peer.
    ///
    /// If unspecified, this will default to 2.
    #[serde(default = "AdmissionParameters::default_max_subscriptions_per_peer")]
    pub max_subscriptions_per_peer: u32,

    /// Max concurrent header fetches per peer
    /// (`fetch_block_headers` + `fetch_latest_block_headers`).
    ///
    /// If unspecified, this will default to 32.
    #[serde(default = "AdmissionParameters::default_max_header_fetches_per_peer")]
    pub max_header_fetches_per_peer: u32,

    /// Max concurrent transaction fetches per peer (`fetch_transactions`).
    ///
    /// If unspecified, this will default to 16.
    #[serde(default = "AdmissionParameters::default_max_transaction_fetches_per_peer")]
    pub max_transaction_fetches_per_peer: u32,

    /// Max concurrent commit fetches per peer
    /// (`fetch_commits` + `fetch_commits_and_transactions`).
    ///
    /// If unspecified, this will default to 8.
    #[serde(default = "AdmissionParameters::default_max_commit_fetches_per_peer")]
    pub max_commit_fetches_per_peer: u32,

    /// Max concurrent commit fetches across all peers, beyond which a peer is
    /// still granted its first. A fast commit-sync response holds its commits
    /// and certifier headers until it has been sent, and reads its transactions
    /// from the store while it is being sent, so this caps what serving them
    /// can cost the node at once, short of one response per peer.
    ///
    /// If unspecified, this will default to 16.
    #[serde(default = "AdmissionParameters::default_max_commit_fetches_total")]
    pub max_commit_fetches_total: u32,
}

impl AdmissionParameters {
    fn default_max_subscriptions_per_peer() -> u32 {
        2
    }

    fn default_max_header_fetches_per_peer() -> u32 {
        32
    }

    fn default_max_transaction_fetches_per_peer() -> u32 {
        16
    }

    fn default_max_commit_fetches_per_peer() -> u32 {
        Parameters::default_commit_sync_parallel_fetches() as u32
    }

    fn default_max_commit_fetches_total() -> u32 {
        2 * AdmissionParameters::default_max_commit_fetches_per_peer()
    }
}

impl Default for AdmissionParameters {
    fn default() -> Self {
        Self {
            max_subscriptions_per_peer: AdmissionParameters::default_max_subscriptions_per_peer(),
            max_header_fetches_per_peer: AdmissionParameters::default_max_header_fetches_per_peer(),
            max_transaction_fetches_per_peer:
                AdmissionParameters::default_max_transaction_fetches_per_peer(),
            max_commit_fetches_per_peer: AdmissionParameters::default_max_commit_fetches_per_peer(),
            max_commit_fetches_total: AdmissionParameters::default_max_commit_fetches_total(),
        }
    }
}