Merge pull request #268 from tendermint/xla/resolve-divergence

Resolve divergence

Author: ValarDragon

CHANGELOG.md

@@ -2,14 +2,27 @@
 
 ## 0.11.0
 
-*TBD*
+*June 6, 2018*
 
 BREAKING CHANGES:
 
-- [types] Added `type` field to `Evidence` (opaque bytes indicating kind of fraud)
-- [types] Added `time` field to `Evidence` (note that this is the timestamp of the block which was double-signed, not the time the evidence was received)
+- [example/dummy] Remove. See example/kvstore
+- [types] Upgrade many messages:
+    - RequestInitChain takes all fields from a Genesis file
+    - RequestBeginBlock provides a list of all validators and whether or not
+      they signed
+    - Header: remove some fields, add proposer
+    - BlockID, PartSetHeader: remove
+    - Validator: includes address
+    - PubKey: new message with `type` and `data`
+    - Evidence: add type and more fields
 
-TODO
+FEATURES:
+
+- [types] Add some fields
+    - ResponseInitChain includes ConsensusParams and Validators
+    - ResponseBeginBlock includes tags
+    - ResponseEndBlock includes tags
 
 ## 0.10.3 (April 9, 2018)
 

Makefile

@@ -171,4 +171,4 @@ devdoc_clean:
 # To avoid unintended conflicts with file names, always add to .PHONY
 # unless there is a reason not to.
 # https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html
-.PHONY: check protoc build dist install check_tools get_tools get_protoc update_tools get_vendor_deps test test_race test_integrations fmt metalinter metalinter_all docker_build docker_run docker_run_rm devdoc_init devdoc devdoc_save devdoc_clean
+.PHONY: check protoc build dist install check_tools get_tools get_protoc update_tools get_vendor_deps test test_race fmt metalinter metalinter_all docker_build docker_run docker_run_rm devdoc_init devdoc devdoc_save devdoc_clean

README.md

@@ -5,20 +5,28 @@
 Blockchains are systems for multi-master state machine replication.
 **ABCI** is an interface that defines the boundary between the replication engine (the blockchain),
 and the state machine (the application).
-By using a socket protocol, we enable a consensus engine running in one process
-to manage an application state running in another.
-
-For background information on ABCI, motivations, and tendermint, please visit [the documentation](http://tendermint.readthedocs.io/en/master/).
-The two guides to focus on are the `Application Development Guide` and `Using ABCI-CLI`.
+Using a socket protocol, a consensus engine running in one process
+can manage an application state running in another.
 
 Previously, the ABCI was referred to as TMSP.
 
 The community has provided a number of addtional implementations, see the [Tendermint Ecosystem](https://tendermint.com/ecosystem)
 
 ## Specification
 
-The [primary specification](https://github.com/tendermint/abci/blob/master/types/types.proto)
-is made using Protocol Buffers. To build it, run
+A detailed description of the ABCI methods and message types is contained in:
+
+- [A prose specification](specification.md)
+- [A protobuf file](https://github.com/tendermint/abci/blob/master/types/types.proto)
+- [A Go interface](https://github.com/tendermint/abci/blob/master/types/application.go).
+
+For more background information on ABCI, motivations, and tendermint, please visit [the documentation](http://tendermint.readthedocs.io/en/master/).
+The two guides to focus on are the `Application Development Guide` and `Using ABCI-CLI`.
+
+
+## Protocl Buffers
+
+To compile the protobuf file, run:
 
 ```
 make protoc
@@ -28,12 +36,10 @@ See `protoc --help` and [the Protocol Buffers site](https://developers.google.co
 for details on compiling for other languages. Note we also include a [GRPC](http://www.grpc.io/docs)
 service definition.
 
-For the specification as an interface in Go, see the
-[types/application.go file](https://github.com/tendermint/abci/blob/master/types/application.go).
-
-See the [spec file](specification.rst) for a detailed description of the message types.
+## Install ABCI-CLI
 
-## Install
+The `abci-cli` is a simple tool for debugging ABCI servers and running some
+example apps. To install it:
 
 ```
 go get github.com/tendermint/abci

specification.md

@@ -50,11 +50,13 @@ connection. They may be referred to as the `DeliverTx state`, the
 
 See below for more details on the message types and how they are used.
 
+## Request/Response Messages
+
 ### Echo
 
--   **Arguments**:
+-   **Request**:
     -   `Message (string)`: A string to echo back
--   **Returns**:
+-   **Response**:
     -   `Message (string)`: The input string
 -   **Usage**:
     -   Echo a string to test an abci client/server implementation
@@ -70,9 +72,9 @@ See below for more details on the message types and how they are used.
 
 ### Info
 
--   **Arguments**:
+-   **Request**:
     -   `Version (string)`: The Tendermint version
--   **Returns**:
+-   **Response**:
     -   `Data (string)`: Some arbitrary information
     -   `Version (Version)`: Version information
     -   `LastBlockHeight (int64)`: Latest block for which the app has
@@ -88,10 +90,10 @@ See below for more details on the message types and how they are used.
 
 ### SetOption
 
--   **Arguments**:
+-   **Request**:
     -   `Key (string)`: Key to set
     -   `Value (string)`: Value to set for key
--   **Returns**:
+-   **Response**:
     -   `Code (uint32)`: Response code
     -   `Log (string)`: The output of the application's logger. May
         be non-deterministic.
@@ -105,15 +107,19 @@ See below for more details on the message types and how they are used.
 
 ### InitChain
 
--   **Arguments**:
+-   **Request**:
     -   `Validators ([]Validator)`: Initial genesis validators
     -   `AppStateBytes ([]byte)`: Serialized initial application state
+-   **Response**:
+    -   `ConsensusParams (ConsensusParams)`: Initial
+        consensus-critical parameters.
+    -   `Validators ([]Validator)`: Initial validator set.
 -   **Usage**:
     -   Called once upon genesis.
 
 ### Query
 
--   **Arguments**:
+-   **Request**:
     -   `Data ([]byte)`: Raw query bytes. Can be used with or in lieu
         of Path.
     -   `Path (string)`: Path of request, like an HTTP GET path. Can be
@@ -128,7 +134,7 @@ See below for more details on the message types and how they are used.
         application's Merkle root hash, which represents the state as it
         was after committing the block at Height-1
     -   `Prove (bool)`: Return Merkle proof with response if possible
--   **Returns**:
+-   **Response**:
     -   `Code (uint32)`: Response code.
     -   `Log (string)`: The output of the application's logger. May
         be non-deterministic.
@@ -148,26 +154,28 @@ See below for more details on the message types and how they are used.
 
 ### BeginBlock
 
--   **Arguments**:
+-   **Request**:
     -   `Hash ([]byte)`: The block's hash. This can be derived from the
         block header.
     -   `Header (struct{})`: The block header
-    -   `AbsentValidators ([]int32)`: List of indices of validators not
-        included in the LastCommit
+    -   `Validators ([]SigningValidator)`: List of validators in the current validator
+        set and whether or not they signed a vote in the LastCommit
     -   `ByzantineValidators ([]Evidence)`: List of evidence of
         validators that acted maliciously
+-   **Response**:
+    -   `Tags ([]cmn.KVPair)`: Key-Value tags for filtering and indexing
 -   **Usage**:
     -   Signals the beginning of a new block. Called prior to
         any DeliverTxs.
     -   The header is expected to at least contain the Height.
-    -   The `AbsentValidators` and `ByzantineValidators` can be used to
+    -   The `Validators` and `ByzantineValidators` can be used to
         determine rewards and punishments for the validators.
 
 ### CheckTx
 
--   **Arguments**:
+-   **Request**:
     -   `Tx ([]byte)`: The request transaction bytes
--   **Returns**:
+-   **Response**:
     -   `Code (uint32)`: Response code
     -   `Data ([]byte)`: Result bytes, if any.
     -   `Log (string)`: The output of the application's logger. May
@@ -201,9 +209,9 @@ See below for more details on the message types and how they are used.
 
 ### DeliverTx
 
--   **Arguments**:
+-   **Request**:
     -   `Tx ([]byte)`: The request transaction bytes.
--   **Returns**:
+-   **Response**:
     -   `Code (uint32)`: Response code.
     -   `Data ([]byte)`: Result bytes, if any.
     -   `Log (string)`: The output of the application's logger. May
@@ -224,13 +232,14 @@ See below for more details on the message types and how they are used.
 
 ### EndBlock
 
--   **Arguments**:
+-   **Request**:
     -   `Height (int64)`: Height of the block just executed.
--   **Returns**:
+-   **Response**:
     -   `ValidatorUpdates ([]Validator)`: Changes to validator set (set
         voting power to 0 to remove).
     -   `ConsensusParamUpdates (ConsensusParams)`: Changes to
         consensus-critical time, size, and other parameters.
+    -   `Tags ([]cmn.KVPair)`: Key-Value tags for filtering and indexing
 -   **Usage**:
     -   Signals the end of a block.
     -   Called prior to each Commit, after all transactions.
@@ -239,11 +248,77 @@ See below for more details on the message types and how they are used.
 
 ### Commit
 
--   **Returns**:
+-   **Response**:
     -   `Data ([]byte)`: The Merkle root hash
 -   **Usage**:
     -   Persist the application state.
     -   Return a Merkle root hash of the application state.
     -   It's critical that all application instances return the
         same hash. If not, they will not be able to agree on the next
         block, because the hash is included in the next block!
+
+## Data Messages
+
+### Header
+
+- **Fields**:
+    - `ChainID (string)`: ID of the blockchain
+    - `Height (int64)`: Height of the block in the chain
+    - `Time (int64)`: Unix time of the block
+    - `NumTxs (int32)`: Number of transactions in the block
+    - `TotalTxs (int64)`: Total number of transactions in the blockchain until
+      now
+    - `LastBlockHash ([]byte)`: Hash of the previous (parent) block
+    - `ValidatorsHash ([]byte)`: Hash of the validator set for this block
+    - `AppHash ([]byte)`: Data returned by the last call to `Commit` - typically the
+      Merkle root of the application state after executing the previous block's
+      transactions
+    - `Proposer (Validator)`: Original proposer for the block
+- **Usage**:
+    - Provided in RequestBeginBlock
+    - Provides important context about the current state of the blockchain -
+      especially height and time.
+    - Provides the proposer of the current block, for use in proposer-based
+      reward mechanisms.
+
+### Validator
+
+- **Fields**:
+    - `Address ([]byte)`: Address of the validator (hash of the public key)
+    - `PubKey (PubKey)`:  Public key of the validator
+    - `Power (int64)`: Voting power of the validator
+- **Usage**:
+    - Provides all identifying information about the validator
+
+### SigningValidator
+
+- **Fields**:
+    - `Validator (Validator)`: A validator
+    - `SignedLastBlock (bool)`: Indicated whether or not the validator signed
+      the last block
+- **Usage**:
+    - Indicates whether a validator signed the last block, allowing for rewards
+      based on validator availability
+
+### PubKey
+
+- **Fields**:
+    - `Type (string)`: Type of the public key. A simple string like `"ed25519"`.
+      In the future, may indicate a serialization algorithm to parse the `Data`,
+      for instance `"amino"`.
+    - `Data ([]byte)`: Public key data. For a simple public key, it's just the
+      raw bytes. If the `Type` indicates an encoding algorithm, this is the
+      encoded public key.
+- **Usage**:
+    - A generic and extensible typed public key
+
+### Evidence
+
+- **Fields**:
+    - `Type (string)`: Type of the evidence. A hierarchical path like
+      "duplicate/vote".
+    - `Validator (Validator`: The offending validator
+    - `Height (int64)`: Height when the offense was committed
+    - `Time (int64)`: Unix time of the block at height `Height`
+    - `TotalVotingPower (int64)`: Total voting power of the validator set at
+      height `Height`