Tendermint specification

[jmalicevic]

Tendermint consists of many protocols and interfaces that need to be very well understood. Currently, not all protocols are clearly specified. This issue is designed to track the current state of the specification of Tendermint protocols and provide a clear overview of the remaining work in that respect.

Definition of done

This issue will be considered done when each sub-issue (corresponding to individual protocols and interfaces) is completed.
For a sub-issue to be considered completed it needs to provide the following:

• (1) What properties does the protocol provide (externally visible variables, events, together with safety, liveness, "best effort" properties)
• (2) What does the protocol expect from other protocols: shared state, timing, transition properties (when the node transitions from blocksync to consensus it should be at most x heights behind the current height of the chain)
• (3) How is the protocol operating (protocol description)
• (4) Observations/shortcomings/potential issues (I guess when we do this work, we will find problems that eventually should be addressed. We might note them down here together with the version of the software they apply to)

Satisfaction criteria

For 1) and 2): The protocol team and the engineering team are confident that we have a complete list, and we understand the properties well enough to be sure that they can be formalized.

For 3) protocol team and engineering team agree that the description and the code are well aligned, and captures worst case scenarios / corner cases

For 4) we should provide some evaluation of the current state. Written constructively so that we can infer future steps. (perhaps describing scenarios where the implemented protocol behaves differently from what people think it might do).

Tendermint protocols

Here we provide a list of protocols that exist in Tendermint along with the existing documentation and its status.

Consensus

• Algorithm in arXiv: OK (except separation of proposal and block)
• PBTS extension
  • Port from retired 0.36 to main
• Detection of equivocation: missing
• Formal specification of the Gossip layer. #9851
• Interface between consensus and other Tendermint modules.
• Develop onboarding material explaining/answering some crucial parts of the Tendermint consensus algorithm (e.g., innovative Tendermint termination mechanism)

Accountability

• Detection of misbehavior - Amnesia: missing
• Light client detection: OK (perhaps re-organize lightclient)
• Evidence handling: missing
• Evidence gossiping: missing

Mempool

• Good coverage of parameters (in docs).
• Specifications missing. There is an ADR on the priority mempool. Open issue to write the spec for priority mempool.
• Interface
  • Documentation contains interface to clients - how to post transactions
  • Research: practical behavior, performance, (problems felt in mempool are actually problems of peer-to-peer)

Peer exchange (PEX) and p2p :

• Existing issue: Specify the operation of the P2P layer in v0.34 #9089
• p2p: Define a specification #9573

Block sync:

• Existing issue: spec: blocksync  #8586

State sync

• Existing issue

Light client

• Documentation adequate and exists here.

Tendermint interfaces

ABCI

• ABCI is well specified and understood. Ongoing issue.
• Tutorials
  • Old ABCI version
  • ABCI ++

Peer management

• : API + network properties are currently not clearly specified. Under this we can cover as well any related information on cryptography, encryption, authentication

Client facing

• Mempool (missing for non SDK users)
• RPC (missing for non SDK users)

Private key storare and use

• Spec of API? Secure?

Persistence, Data Availability

• Database
• Data availability implications of pruning, statesync, retain_height. What are the network-wide properties that we need?