State machine <-> Client: interaction specification

[DmiSergeev]

Motivation

The interaction protocol between the State machine and the client primarily based on Tendermint protocol which is fairly clear and well-documented. At the same time, Tendermint architecture is rather flexible and doesn't restrict concrete solutions like RPC message formats, encoding, error handling, timeouts, etc.
The Fluence also introduces additional layers of interaction logic: transaction authentication, deduplication, and ordering.

These aspects make the current protocol rather complicated. Currently, there is no single source of some documentation/specification describing this protocol: there is implementation code only. Also, some interaction cases are not even implemented yet. Such a situation leaves the protocol unclear and tangled, obstructs the understanding of the whole picture of the interaction, which is quite important. It also slows down the future development of the new interaction features and alternative client implementations.

Proposition

To implement the interaction protocol specification. It would describe the interactions from different points of view and different levels:

• The client:
  • Language-specific client high-level API: how to use this API, what to expect, what guarantees it provides. Currently such API implemented in Python
  • Tendermint RPC message formats. It's primarily a specification for transaction (broadcact_tx_*) and query (abci_query) RPCs: what is request format, what response fields (Info, Result, Proof, etc.) mean.
• The state machine ABCI methods implementation specification: how they act depending on the current state and given arguments.

The specification must describe both normal behavior and various corner cases, including client/node failures and Byzantine behavior. The specification must explicitly inform what features are not actually implemented.

It's supposed that the required specification would be implemented as Markdown document(s) and placed in Fluence main repo.