Configurable SCP Timing Parameters

Preamble

CAP: 0070
Title: Configurable SCP Timing Parameters
Working Group:
    Owner: Garand Tyson <@SirTyson>
    Authors: Garand Tyson <@SirTyson>
    Consulted: Nicolas Barry <@MonsieurNicolas>
Status: Final
Created: 2025-04-28
Discussion: https://github.com/orgs/stellar/discussions/1719
Protocol version: 23

Simple Summary

This CAP introduces ledger configuration settings allowing the Stellar network to dynamically adjust ledger close times, nomination timeouts, and ballot timeouts to facilitate controlled, incremental improvements to block time performance.

Motivation

Currently, Stellar's ledger close time and SCP timeout settings are hardcoded. This restricts the network's ability to gradually test and implement shorter block times, limiting improvements in performance and responsiveness. Additionally, as other network parameters such as ledger limits and transaction throughput evolve, SCP nomination and ballot phase timings may need to be adjusted to maintain efficiency and resilience.

This CAP addresses these issues by making these parameters configurable, enabling small, incremental adjustments and performance tuning.

Goals Alignment

The proposal aligns with Stellar’s goals of scalability, resilience, and performance by enabling iterative improvements in ledger close time and consensus efficiency.

Abstract

We define new network configuration settings for:

• Target ledger close time (milliseconds)
• Initial nomination timeout (milliseconds)
• Initial ballot timeout (milliseconds)
• Per-round nomination timeout increment (milliseconds)
• Per-round ballot timeout increment (milliseconds)

These settings are introduced as ledger config parameters, allowing the Stellar network to adjust consensus timings incrementally.

Specification

XDR Changes

diff --git a/Stellar-contract-config-setting.x b/Stellar-contract-config-setting.x
index 30e41ad..5fc19f3 100644
--- a/Stellar-contract-config-setting.x
+++ b/Stellar-contract-config-setting.x
@@ -302,6 +302,14 @@ struct EvictionIterator {
     uint64 bucketFileOffset;
 };
 
+struct ConfigSettingSCPTiming {
+    uint32 ledgerTargetCloseTimeMilliseconds;
+    uint32 nominationTimeoutInitialMilliseconds;
+    uint32 nominationTimeoutIncrementMilliseconds;
+    uint32 ballotTimeoutInitialMilliseconds;
+    uint32 ballotTimeoutIncrementMilliseconds;
+};
+
 // limits the ContractCostParams size to 20kB
 const CONTRACT_COST_COUNT_LIMIT = 1024;
 
@@ -325,7 +333,8 @@ enum ConfigSettingID
     CONFIG_SETTING_LIVE_SOROBAN_STATE_SIZE_WINDOW = 12,
     CONFIG_SETTING_EVICTION_ITERATOR = 13,
     CONFIG_SETTING_CONTRACT_PARALLEL_COMPUTE_V0 = 14,
-    CONFIG_SETTING_CONTRACT_LEDGER_COST_EXT_V0 = 15
+    CONFIG_SETTING_CONTRACT_LEDGER_COST_EXT_V0 = 15,
+    CONFIG_SETTING_SCP_TIMING = 16
 };
 
 union ConfigSettingEntry switch (ConfigSettingID configSettingID)
@@ -362,5 +371,7 @@ case CONFIG_SETTING_CONTRACT_PARALLEL_COMPUTE_V0:
     ConfigSettingContractParallelComputeV0 contractParallelCompute;
 case CONFIG_SETTING_CONTRACT_LEDGER_COST_EXT_V0:
     ConfigSettingContractLedgerCostExtV0 contractLedgerCostExt;
+case CONFIG_SETTING_SCP_TIMING:
+    ConfigSettingSCPTiming contractSCPTiming;
 };
 }

Semantics

All initial values will match the current hardcoded values. The initial upgrade to protocol 23 should have no actual effect on SCP, but will open the door for future changes.

Note: All ranges are approximate values for sanity checking, but are untested. Actual upgrades should be within these ranges, but must still be tested and validated.

• ledgerTargetCloseTimeMilliseconds
  • Target ledger close time in milliseconds. Validators will use this value to set the nextLedgerTrigger timer.
  • Initial value: 5000
  • Range: [4000, 5000]
• nominationTimeoutInitialMilliseconds
  • Initial timeout for SCP nomination phase in milliseconds.
  • Initial value: 1000
  • Range: [750, 2500]
• nominationTimeoutIncrementMilliseconds
  • Incremental timeout increase per additional nomination round in milliseconds.
  • Initial value: 1000
  • Range: [500, 2000]
• ballotTimeoutInitialMilliseconds
  • Initial timeout for SCP ballot phase in milliseconds
  • Initial value: 1000
  • Range: [750, 2500]
• ballotTimeoutIncrementMilliseconds
  • Incremental timeout increase per additional ballot round in milliseconds
  • Initial value: 1000
  • Range: [500, 2000] For some ballot/nomination round i, the timeout for that round is calculated as:

round_timeout(i) = initial_timeout + (i * increment_timeout)

Design Rationale

Introducing configurable consensus parameters provides essential flexibility, allowing the network to incrementally test and adopt shorter ledger close times without large, disruptive protocol updates. While significant changes, such as going from 5 seconds to 2.5 seconds, will require significant protocol work, smaller latency gains can be more easily achieved. While the network of Stellar validators may be able to achieve shorter block times, downstream systems may assume a consistent 5 second block time or not be performant enough to handle shorter block times. By making gradual changes via SLP instead of protocol upgrades, the network can slowly test small changes and adapt over time to faster ledgers.

When changing ledgerTargetCloseTimeMilliseconds, corresponding adjustments to smart contract ledger limits must be made proportionally. This ensures consistent resource utilization per second, preventing overload and maintaining network stability. For example, if ledger close times decrease by 20%, ledger limits must also decrease by approximately 20% to keep resource usage constant. This proportional adjustment is crucial to avoid excessive validator workloads or performance degradation as block times decrease.

As block times decrease, or smart contract limits increase, nomination and ballot timeouts may need to be adjusted for optimal performance. Increased performance does not necessarily mean that timeouts should be decreased. For example, shortening the nomination timeout can lead to more timeouts if there are slower nodes on the network. These additional nomination timeouts cause more bandwidth and CPU load on the network, which can further degrade slow nodes. This results in a "snowball" effect, where the network becomes more and more congested and slow nodes fall further and further behind. As TPS increases and transaction set size increases, longer nomination timeouts may actually improve network performance and decrease overall block times, as less values are nominated. While longer nomination timeouts can increase network latency on average, they can also cause larger latency spikes if certain nodes are offline or slow.

Given these complexities, it is vital that timeout adjustments be incrementally tested and validated through simulation to identify safe and optimal settings. Only small, gradual changes should be proposed.

Config Setting Limits

Unlike Soroban TX limit values, SCP timing values are nuanced and complicated to test. Additionally, a bad value could cause significant harm to the network, such as a network wide halt, out of sync downstream systems, etc. To prevent a bad value being introduced by mistake or by an uninformed proposal, SCP timing values will be limited to a tight range at the implementation level. As the Stellar Network becomes more efficient, these ranges can be changed on protocol boundaries, i.e. for protocol 23 ledgerTargetCloseTimeMilliseconds can only be reduced to 4000, but a future protocol may lower this limit further. It is important for these limits to change on protocol boundaries. Should a limit be reduced in a minor point release, it is possible for an SCP timing upgrade to occur for older nodes on the network that are not capable of keeping up with these new timings. Note that these limits are untested sanity checks and may still cause harm to the network. However, these bounds appear tight enough to not cause substantial network failure.

Test Cases

For the implementation of this CAP, no testing will be required outside of unit tests, as the default values will be identical to the current hardcoded values. However, changes to these configs should be thoroughly tested via supercluster simulation. When it comes to testing network timing changes, it is important to test on large topologies that are most similar to the mainnet topology with installed latency to simulate slow nodes. This can be achieved via the "SimulatePubnet" and "SimulatePubnetMixedLoad" missions. On an ideal network, where all nodes are fast, it is likely that shorter timeouts will improve network performance. However, on a network with slow nodes, shorter timeouts may cause more values to be nominated, resulting in more work for all validators on the network and decreased performance. Network performance can be very sensitive to these timing parameters, so it is important to propose small, gradual changes that have been thoroughly simulated.