Documentation for Timing parameter updates.

[williambanfield]

Problem Definition and Summary

v0.36 of Tendermint plans to add proposer-based timestamps, a new algorithm for calculating the timestamp that will be placed into the block header. Part of this change involves adding a new set of Timing consensus parameters that will determine the validity of the block timestamp. The parameters indicate how close a validator's clock must be to the proposed time for the block to be considered valid.

The parameters are slowly relaxed as rounds progress so that networks can make progress if they pick bad values. If a network has chosen bad values for these Timing parameters, they will want to update them to relax the constraints and allow the network to make progress faster.

Proposal

We should document how a network will be able to detect that the values may be misconfigured and document the steps by which a network will be able to update the misconfigured parameters.

To detect that these values may be misconfigured, Tendermint is adding a metric that indicates that a block was received by a validator but that did not satisfy the Timing constraints. See tendermint/tendermint#7460. Networks will therefore be able to examine this metric to determine that the reason a network is proceeding to multiple rounds is due to the timing constraints not being met.

To update these timing parameters when a network notices that they are not being met, a network will need to issue a governance proposal that updates the corresponding consensus parameters. The ability to update consensus parameters was added in #5952 and generally take the form of:

<app-cli> tx gov submit-proposal param-change <path/to/proposal.json>

Where proposal.json contains the parameters to change. Examples of this can be found in the governance client specification

We should add this as a standalone 'how-to' document that guides users end-to-end through the flow of discovering the issue and fixing it.

cc: @alexanderbez @ancazamfir

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned

[alexanderbez]

@williambanfield thanks for creating this issue. Can you outline what additional parameters will be coming in? They will need to be added to BaseApp.

[williambanfield]

Thanks @alexanderbez
Currently we are going to be adding 2 new parameters: SynchronyParams.MessageDelay and SynchronyParams.Precision
They're present in the wb/proposer-based-timestamps branch of the spec repo: https://github.com/tendermint/spec/blob/wb/proposer-based-timestamps/proto/tendermint/types/params.proto#L70-L75

[williambanfield]

Hey @alexanderbez, has there been any progress on this? Thanks!

[tac0turtle]

Can we add sentences pointing to Tendermint documentation on this? I want to avoid duplicating data for this and begin diverging in information in the future.

[williambanfield]

@marbar3778 Got it, I don't think we should duplicate documentation but I do think that having documentation specific to different use-cases makes sense. This issue is discussing how to create a governance proposal to update the parameters, which isn't a part of Tendermint. We can definitely link to documentation on the Tendermint side describing what these new parameters are and how to detect that they are wrong, but I think we should still have a document that spells out what cosmos-sdk chains should do if they configured the parameters incorrectly.

[alexanderbez]

Sorry just saw this, what exactly do we need to do here?

[williambanfield]

@alexanderbez We need the SDK to document the process of updating the Precision and MessageDelay consensus parameters via a governance proposal in the case that the values selected for those were too small. This, I would imagine, would take the form of a runbook that application developers / node operators can use to pick a value and create the proposal at the command line.

[tac0turtle]

This issue is discussing how to create a governance proposal to update the parameters, which isn't a part of Tendermint.

for this there is general documentation on how to do gov proposals. Is there anything different we need to document than any other param change?

the case that the values selected for those were too small. This, I would imagine, would take the form of a runbook that application developers / node operators can use to pick a value and create the proposal at the command line.

the values should be on the tendermint side right? Then we can add a few notes for setting this in genesis. Does that work?

[alexanderbez]

Yeah my question was going to be, where exactly do you want this documented? The CLI or somewhere else?

[williambanfield]

the values should be on the tendermint side right? Then we can add a few notes for setting this in genesis. Does that work?

Got it, the values being updated would be Tendermint values. The idea here is to directly document a user flow. I.e. The user/operator notices an issue with liveness, searches for documentation and finds information on how to diagnose and an easy command that helps the get out of the issue they are experiencing without having to get too lost in all of the details of the algorithm and SDK. What documentation exists at the moment for the governance proposals?

Perhaps we can link to that from a runbook.

They will need to be added to BaseApp.

@alexanderbez should we open a separate issue for this, or does any more work need to be completed for the parameters to work in the SDK?

[tac0turtle]

perfect that works. I can tackle this as the time comes closer!! thanks for opening the issue.

I can add them to Baseapp as well. the change is simple but I may ping you to help recreate the current settings.

[williambanfield]

Thanks @marbar3778 ! Please reach out with any questions.

[tac0turtle]

closing as 0.35 was reverted