github.com/ari-anchor/sei-tendermint@v0.0.0-20230519144642-dc826b7b56bb/docs/architecture/adr-074-timeout-params.md (about)

     1  # ADR 74: Migrate Timeout Parameters to Consensus Parameters
     2  
     3  ## Changelog
     4  
     5  - 03-Jan-2022: Initial draft (@williambanfield)
     6  - 13-Jan-2022: Updated to indicate work on upgrade path needed (@williambanfield)
     7  
     8  ## Status
     9  
    10  Proposed
    11  
    12  ## Context
    13  
    14  ### Background
    15  
    16  Tendermint's consensus timeout parameters are currently configured locally by each validator
    17  in the validator's [config.toml][config-toml].
    18  This means that the validators on a Tendermint network may have different timeouts
    19  from each other. There is no reason for validators on the same network to configure
    20  different timeout values. Proper functioning of the Tendermint consensus algorithm
    21  relies on these parameters being uniform across validators.
    22  
    23  The configurable values are as follows:
    24  
    25  * `TimeoutPropose`
    26  	* How long the consensus algorithm waits for a proposal block before issuing a prevote.
    27  	* If no prevote arrives by `TimeoutPropose`, then the consensus algorithm will issue a nil prevote.
    28  * `TimeoutProposeDelta`
    29  	* How much the `TimeoutPropose` grows each round.
    30  * `TimeoutPrevote`
    31  	* How long the consensus algorithm waits after receiving +2/3 prevotes with
    32  	no quorum for a value before issuing a precommit for nil.
    33  	(See the [arXiv paper][arxiv-paper], Algorithm 1, Line 34)
    34  * `TimeoutPrevoteDelta`
    35  	* How much the `TimeoutPrevote` increases with each round.
    36  * `TimeoutPrecommit`
    37  	* How long the consensus algorithm waits after receiving +2/3 precommits that
    38  	do not have a quorum for a value before entering the next round.
    39  	(See the [arXiv paper][arxiv-paper], Algorithm 1, Line 47)
    40  * `TimeoutPrecommitDelta`
    41  	* How much the `TimeoutPrecommit` increases with each round.
    42  * `TimeoutCommit`
    43  	* How long the consensus algorithm waits after committing a block but before starting the new height.
    44  	* This gives a validator a chance to receive slow precommits.
    45  * `SkipTimeoutCommit`
    46  	* Make progress as soon as the node has 100% of the precommits.
    47  
    48  
    49  ### Overview of Change
    50  
    51  We will consolidate the timeout parameters and migrate them from the node-local
    52  `config.toml` file into the network-global consensus parameters.
    53  
    54  The 8 timeout parameters will be consolidated down to 6. These will be as follows:
    55  
    56  * `TimeoutPropose`
    57  	* Same as current `TimeoutPropose`.
    58  * `TimeoutProposeDelta`
    59  	* Same as current `TimeoutProposeDelta`.
    60  * `TimeoutVote`
    61  	* How long validators wait for votes in both the prevote
    62  	 and precommit phase of the consensus algorithm. This parameter subsumes
    63  	 the current `TimeoutPrevote` and `TimeoutPrecommit` parameters.
    64  * `TimeoutVoteDelta`
    65  	* How much the `TimeoutVote` will grow each successive round.
    66  	 This parameter subsumes the current `TimeoutPrevoteDelta` and `TimeoutPrecommitDelta`
    67  	 parameters.
    68  * `TimeoutCommit`
    69  	* Same as current `TimeoutCommit`.
    70  * `BypassCommitTimeout`
    71  	* Same as current `SkipTimeoutCommit`, renamed for clarity.
    72  
    73  A safe default will be provided by Tendermint for each of these parameters and
    74  networks will be able to update the parameters as they see fit. Local updates
    75  to these parameters will no longer be possible; instead, the application will control
    76  updating the parameters. Applications using the Cosmos SDK will be automatically be
    77  able to change the values of these consensus parameters [via a governance proposal][cosmos-sdk-consensus-params].
    78  
    79  This change is low-risk. While parameters are locally configurable, many running chains
    80  do not change them from their default values. For example, initializing
    81  a node on Osmosis, Terra, and the Cosmos Hub using the their `init` command produces
    82  a `config.toml` with Tendermint's default values for these parameters.
    83  
    84  ### Why this parameter consolidation?
    85  
    86  Reducing the number of parameters is good for UX. Fewer superfluous parameters makes
    87  running and operating a Tendermint network less confusing.
    88  
    89  The Prevote and Precommit messages are both similar sizes, require similar amounts
    90  of processing so there is no strong need for them to be configured separately.
    91  
    92  The `TimeoutPropose` parameter governs how long Tendermint will wait for the proposed
    93  block to be gossiped. Blocks are much larger than votes and therefore tend to be
    94  gossiped much more slowly. It therefore makes sense to keep `TimeoutPropose` and
    95  the `TimeoutProposeDelta` as parameters separate from the vote timeouts.
    96  
    97  `TimeoutCommit` is used by chains to ensure that the network waits for the votes from
    98  slower validators before proceeding to the next height. Without this timeout, the votes
    99  from slower validators would consistently not be included in blocks and those validators
   100  would not be counted as 'up' from the chain's perspective. Being down damages a validator's
   101  reputation and causes potential stakers to think twice before delegating to that validator.
   102  
   103  `TimeoutCommit` also prevents the network from producing the next height as soon as validators
   104  on the fastest hardware with a summed voting power of +2/3 of the network's total have
   105  completed execution of the block. Allowing the network to proceed as soon as the fastest
   106  +2/3 completed execution would have a cumulative effect over heights, eventually
   107  leaving slower validators unable to participate in consensus at all. `TimeoutCommit`
   108  therefore allows networks to have greater variability in hardware. Additional
   109  discussion of this can be found in [tendermint issue 5911][tendermint-issue-5911-comment]
   110  and [spec issue 359][spec-issue-359].
   111  
   112  ## Alternative Approaches
   113  
   114  ### Hardcode the parameters
   115  
   116  Many Tendermint networks run on similar cloud-hosted infrastructure. Therefore,
   117  they have similar bandwidth and machine resources. The timings for propagating votes
   118  and blocks are likely to be reasonably similar across networks. As a result, the
   119  timeout parameters are good candidates for being hardcoded. Hardcoding the timeouts
   120  in Tendermint would mean entirely removing these parameters from any configuration
   121  that could be altered by either an application or a node operator. Instead,
   122  Tendermint would ship with a set of timeouts and all applications using Tendermint
   123  would use this exact same set of values.
   124  
   125  While Tendermint nodes often run with similar bandwidth and on similar cloud-hosted
   126  machines, there are enough points of variability to make configuring
   127  consensus timeouts meaningful. Namely, Tendermint network topologies are likely to be
   128  very different from chain to chain. Additionally, applications may vary greatly in
   129  how long the `Commit` phase may take. Applications that perform more work during `Commit`
   130  require a longer `TimeoutCommit` to allow the application to complete its work
   131  and be prepared for the next height.
   132  
   133  ## Decision
   134  
   135  The decision has been made to implement this work, with the caveat that the
   136  specific mechanism for introducing the new parameters to chains is still ongoing.
   137  
   138  ## Detailed Design
   139  
   140  ### New Consensus Parameters
   141  
   142  A new `TimeoutParams` `message` will be added to the [params.proto file][consensus-params-proto].
   143  This message will have the following form:
   144  
   145  ```proto
   146  message TimeoutParams {
   147   google.protobuf.Duration propose = 1;
   148   google.protobuf.Duration propose_delta = 2;
   149   google.protobuf.Duration vote = 3;
   150   google.protobuf.Duration vote_delta = 4;
   151   google.protobuf.Duration commit = 5;
   152   bool bypass_commit_timeout = 6;
   153  }
   154  ```
   155  
   156  This new message will be added as a field into the [`ConsensusParams`
   157  message][consensus-params-proto]. The same default values that are [currently
   158  set for these parameters][current-timeout-defaults] in the local configuration
   159  file will be used as the defaults for these new consensus parameters in the
   160  [consensus parameter defaults][default-consensus-params].
   161  
   162  The new consensus parameters will be subject to the same
   163  [validity rules][time-param-validation] as the current configuration values,
   164  namely, each value must be non-negative.
   165  
   166  ### Migration
   167  
   168  The new `ConsensusParameters` will be added during an upcoming release. In this
   169  release, the old `config.toml` parameters will cease to control the timeouts and
   170  an error will be logged on nodes that continue to specify these values. The specific
   171  mechanism by which these parameters will added to a chain is being discussed in
   172  [RFC-009][rfc-009] and will be decided ahead of the next release.
   173  
   174  The specific mechanism for adding these parameters depends on work related to
   175  [soft upgrades][soft-upgrades], which is still ongoing.
   176  
   177  ## Consequences
   178  
   179  ### Positive
   180  
   181  * Timeout parameters will be equal across all of the validators in a Tendermint network.
   182  * Remove superfluous timeout parameters.
   183  
   184  ### Negative
   185  
   186  ### Neutral
   187  
   188  * Timeout parameters require consensus to change.
   189  
   190  ## References
   191  
   192  [conseusus-params-proto]: https://github.com/tendermint/spec/blob/a00de7199f5558cdd6245bbbcd1d8405ccfb8129/proto/tendermint/types/params.proto#L11
   193  [hashed-params]: https://github.com/tendermint/tendermint/blob/7cdf560173dee6773b80d1c574a06489d4c394fe/types/params.go#L49
   194  [default-consensus-params]: https://github.com/tendermint/tendermint/blob/7cdf560173dee6773b80d1c574a06489d4c394fe/types/params.go#L79
   195  [current-timeout-defaults]: https://github.com/tendermint/tendermint/blob/7cdf560173dee6773b80d1c574a06489d4c394fe/config/config.go#L955
   196  [config-toml]: https://github.com/tendermint/tendermint/blob/5cc980698a3402afce76b26693ab54b8f67f038b/config/toml.go#L425-L440
   197  [cosmos-sdk-consensus-params]: https://github.com/cosmos/cosmos-sdk/issues/6197
   198  [time-param-validation]: https://github.com/tendermint/tendermint/blob/7cdf560173dee6773b80d1c574a06489d4c394fe/config/config.go#L1038
   199  [tendermint-issue-5911-comment]: https://github.com/tendermint/tendermint/issues/5911#issuecomment-973560381
   200  [spec-issue-359]: https://github.com/tendermint/spec/issues/359
   201  [arxiv-paper]: https://arxiv.org/pdf/1807.04938.pdf
   202  [soft-upgrades]: https://github.com/tendermint/spec/pull/222
   203  [rfc-009]: https://github.com/tendermint/tendermint/pull/7524