Meaning of different application versions

[faustbrian]

There are 3 references in the documentation to various versions that the application has to specify but some of them seem to have ambiguous naming. For example there are 2 references to app_version but one references the protocol version and the other references the ABCI version.

Are those app_version properties actually distinct values that should be set independently or are they talking about the same value? Both of them are called app_version and are expected to be uint64 but they have different descriptions depending on the context.

References

• https://github.com/tendermint/tendermint/blob/main/spec/abci/abci%2B%2B_methods.md#info
• https://github.com/tendermint/tendermint/blob/main/spec/core/data_structures.md#versionparams

Info

• app_version The application protocol version
• version The application software semantic version

ConsensusParams

• app_version The ABCI application version

[sergio-mena]

Hi,

Let me first explain the difference between version and app_version in ResponseInfo. According to ADR016, field app_version is a field proposed by that ADR whereas field version was a pre-existing string that was left for backwards compatibility.

As far as I could track, version is a SemVer string field describing the Application's version, used for informational purposes (it is logged by Tendermint upon its handshake with the application).

ADR016 explains the role of app_version (a uint64), which can be summarized as follows. Given a block of height h, app_version is used to track which version of the application was used to execute the block h - 1, and thus produce the app hash present in block h. This version number is stored in block h's header. So, app_version essentially defines how the app app_hash and last_results are computed.

In a long-standing chain, with several application upgrades, this version, stored in the block headers, can be used to re-process all blocks from genesis, making sure we always use the right version of the application software to do so.

According to the spec, ABCI method Info is called at handshake time (or just after state-sync is done) and then Tendermint must ensure that the version that the application returns in ResponseInfo matches the version in the current height's block header. I also checked the code and this check doesn't seem to be taking place. So I guess we need to do some digging to understand why the spec does not match the implementation.

Also according to ADR016, if the application updated its logic in a way it may affect the calculation of app_hash or tx_results, it can change the app_version (which will be stored in the header of subsequent blocks) via a consensus param called version.app (using ResponseEndblock, or ResponseFinalizeBlock).

Finally, note that there is still another place where the app version is stored: State.Version.Consensus.App, but this seems to be redundant since we have the version.app consensus param. There is an open issue to deal with this.

I hope this clarifies the different occurrences of application version and their role in Tendermint.