ADR-016: Add versions to Block and State

CHANGELOG_PENDING.md

@@ -12,10 +12,13 @@ BREAKING CHANGES:
   * [rpc] \#2298 `/abci_query` takes `prove` argument instead of `trusted` and switches the default
     behaviour to `prove=false`
   * [privval] \#2459 Split `SocketPVMsg`s implementations into Request and Response, where the Response may contain a error message (returned by the remote signer)
+  * [state] \#2644 Add Version field to State, breaking the format of State as
+    encoded on disk.
 
 * Apps
   * [abci] \#2298 ResponseQuery.Proof is now a structured merkle.Proof, not just
     arbitrary bytes
+  * [abci] \#2644 Add Version to Header and shift all fields by one
 
 * Go API
   * [node] Remove node.RunForever
@@ -25,7 +28,8 @@ BREAKING CHANGES:
   * [crypto/merkle & lite] \#2298 Various changes to accomodate General Merkle trees
   * [crypto/merkle] \#2595 Remove all Hasher objects in favor of byte slices
   * [crypto/merkle] \#2635 merkle.SimpleHashFromTwoHashes is no longer exported
-  * [types] \#2598 `VoteTypeXxx` are now
+  * [types] \#2598 `VoteTypeXxx` are now of type `SignedMsgType byte` and named `XxxType`, eg. `PrevoteType`,
+    `PrecommitType`.
 
 * Blockchain Protocol
   * [types] Update SignBytes for `Vote`/`Proposal`/`Heartbeat`:
@@ -34,7 +38,9 @@ BREAKING CHANGES:
     * \#2598 Change `Type` field fromt `string` to `byte` and use new
       `SignedMsgType` to enumerate.
   * [types] \#2512 Remove the pubkey field from the validator hash
+  * [types] \#2644 Add Version struct to Header
   * [state] \#2587 Require block.Time of the fist block to be genesis time
+  * [state] \#2644 Require block.Version to match state.Version
 
 * P2P Protocol
 

abci/types/types.proto

@@ -231,31 +231,38 @@ message LastCommitInfo {
 
 message Header {
   // basic block info
-  string chain_id = 1 [(gogoproto.customname)="ChainID"];
-  int64 height = 2;
-  google.protobuf.Timestamp time = 3 [(gogoproto.nullable)=false, (gogoproto.stdtime)=true];
-  int64 num_txs = 4;
-  int64 total_txs = 5;
+  Version version = 1 [(gogoproto.nullable)=false];
+  string chain_id = 2 [(gogoproto.customname)="ChainID"];
+  int64 height = 3;
+  google.protobuf.Timestamp time = 4 [(gogoproto.nullable)=false, (gogoproto.stdtime)=true];
+  int64 num_txs = 5;
+  int64 total_txs = 6;
 
   // prev block info
-  BlockID last_block_id = 6 [(gogoproto.nullable)=false];
+  BlockID last_block_id = 7 [(gogoproto.nullable)=false];
 
   // hashes of block data
-  bytes last_commit_hash = 7; // commit from validators from the last block
-  bytes data_hash = 8;        // transactions
+  bytes last_commit_hash = 8; // commit from validators from the last block
+  bytes data_hash = 9;        // transactions
 
   // hashes from the app output from the prev block
-  bytes validators_hash = 9;   // validators for the current block
-  bytes next_validators_hash = 10;   // validators for the next block
-  bytes consensus_hash = 11;   // consensus params for current block
-  bytes app_hash = 12;         // state after txs from the previous block
-  bytes last_results_hash = 13;// root hash of all results from the txs from the previous block
+  bytes validators_hash = 10;   // validators for the current block
+  bytes next_validators_hash = 11;   // validators for the next block
+  bytes consensus_hash = 12;   // consensus params for current block
+  bytes app_hash = 13;         // state after txs from the previous block
+  bytes last_results_hash = 14;// root hash of all results from the txs from the previous block
 
   // consensus info
-  bytes evidence_hash = 14;    // evidence included in the block
-  bytes proposer_address = 15; // original proposer of the block
+  bytes evidence_hash = 15;    // evidence included in the block
+  bytes proposer_address = 16; // original proposer of the block
 }
 
+message Version {
+  uint64 Block = 1;
+  uint64 App = 2;
+}
+
+
 message BlockID {
   bytes hash = 1;
   PartSetHeader parts_header = 2 [(gogoproto.nullable)=false];

docs/spec/abci/abci.md

@@ -338,6 +338,7 @@ Commit are included in the header of the next block.
 ### Header
 
 - **Fields**:
+  - `Version (Version)`: Version of the blockchain and the application
   - `ChainID (string)`: ID of the blockchain
   - `Height (int64)`: Height of the block in the chain
   - `Time (google.protobuf.Timestamp)`: Time of the block. It is the proposer's
@@ -363,6 +364,15 @@ Commit are included in the header of the next block.
   - Provides the proposer of the current block, for use in proposer-based
     reward mechanisms.
 
+### Version
+
+- **Fields**:
+  - `Block (uint64)`: Protocol version of the blockchain data structures.
+  - `App (uint64)`: Protocol version of the application.
+- **Usage**:
+  - Block version should be static in the life of a blockchain.
+  - App version may be updated over time by the application.
+
 ### Validator
 
 - **Fields**:

docs/spec/blockchain/blockchain.md

@@ -8,6 +8,7 @@ The Tendermint blockchains consists of a short list of basic data types:
 
 - `Block`
 - `Header`
+- `Version`
 - `BlockID`
 - `Time`
 - `Data` (for transactions)
@@ -38,6 +39,7 @@ the data in the current block, the previous block, and the results returned by t
 ```go
 type Header struct {
 	// basic block info
+	Version  Version
 	ChainID  string
 	Height   int64
 	Time     Time
@@ -65,6 +67,19 @@ type Header struct {
 
 Further details on each of these fields is described below.
 
+## Version
+
+The `Version` contains the protocol version for the blockchain and the
+application as two `uint64` values:
+
+```go
+type Version struct {
+    Block   uint64
+    App     uint64
+}
+```
+
+
 ## BlockID
 
 The `BlockID` contains two distinct Merkle roots of the block.
@@ -200,6 +215,15 @@ See [here](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockc
 
 A Header is valid if its corresponding fields are valid.
 
+### Version
+
+```
+block.Version.Block == state.Version.Block
+block.Version.App == state.Version.App
+```
+
+The block version must match the state version.
+
 ### ChainID
 
 ```

docs/spec/blockchain/state.md

@@ -15,6 +15,7 @@ validation.
 
 ```go
 type State struct {
+    Version     Version
     LastResults []Result
     AppHash []byte
 

node/node.go

@@ -208,6 +208,15 @@ func NewNode(config *cfg.Config,
 	// reload the state (it may have been updated by the handshake)
 	state = sm.LoadState(stateDB)
 
+	if state.Version.Consensus.Block != version.BlockProtocol {
+		return nil, fmt.Errorf(
+			"Block version of the software does not match that of the state.\n"+
+				"Got version.BlockProtocol=%v, state.Version.Consensus.Block=%v",
+			version.BlockProtocol,
+			state.Version.Consensus.Block,
+		)
+	}
+
 	// If an address is provided, listen on the socket for a
 	// connection from an external signing process.
 	if config.PrivValidatorListenAddr != "" {

state/execution.go

@@ -398,9 +398,13 @@ func updateState(
 		lastHeightParamsChanged = header.Height + 1
 	}
 
+	// TODO: allow app to upgrade version
+	nextVersion := state.Version
+
 	// NOTE: the AppHash has not been populated.
 	// It will be filled on state.Save.
 	return State{
+		Version:                          nextVersion,
 		ChainID:                          state.ChainID,
 		LastBlockHeight:                  header.Height,
 		LastBlockTotalTx:                 state.LastBlockTotalTx + header.NumTxs,