docs/spec/abci: consensus params and general merkle (#2524)

* docs: links to dirs need a slash

* docs/spec/abci: consensus params and general merkle

docs/DOCS_README.md

@@ -35,6 +35,8 @@ of the sidebar.
 **NOTE:** Strongly consider the existing links - both within this directory
 and to the website docs - when moving or deleting files.
 
+Links to directories *MUST* end in a `/`.
+
 Relative links should be used nearly everywhere, having discovered and weighed the following:
 
 ### Relative

docs/README.md

@@ -14,10 +14,10 @@ Tendermint?](introduction/what-is-tendermint.md).
 
 To get started quickly with an example application, see the [quick start guide](introduction/quick-start.md).
 
-To learn about application development on Tendermint, see the [Application Blockchain Interface](spec/abci).
+To learn about application development on Tendermint, see the [Application Blockchain Interface](spec/abci/).
 
 For more details on using Tendermint, see the respective documentation for
-[Tendermint Core](tendermint-core), [benchmarking and monitoring](tools), and [network deployments](networks).
+[Tendermint Core](tendermint-core/), [benchmarking and monitoring](tools/), and [network deployments](networks/).
 
 ## Contribute
 

docs/spec/abci/abci.md

@@ -190,9 +190,9 @@ Commit are included in the header of the next block.
     of Path.
   - `Path (string)`: Path of request, like an HTTP GET path. Can be
     used with or in liue of Data.
-  - Apps MUST interpret '/store' as a query by key on the
+    - Apps MUST interpret '/store' as a query by key on the
     underlying store. The key SHOULD be specified in the Data field.
-  - Apps SHOULD allow queries over specific types like
+    - Apps SHOULD allow queries over specific types like
     '/accounts/...' or '/votes/...'
   - `Height (int64)`: The block height for which you want the query
     (default=0 returns data for the latest committed block). Note
@@ -209,7 +209,7 @@ Commit are included in the header of the next block.
   - `Index (int64)`: The index of the key in the tree.
   - `Key ([]byte)`: The key of the matching data.
   - `Value ([]byte)`: The value of the matching data.
-  - `Proof ([]byte)`: Serialized proof for the data, if requested, to be
+  - `Proof (Proof)`: Serialized proof for the value data, if requested, to be
     verified against the `AppHash` for the given Height.
   - `Height (int64)`: The block height from which data was derived.
     Note that this is the height of the block containing the
@@ -218,6 +218,8 @@ Commit are included in the header of the next block.
 - **Usage**:
   - Query for data from the application at current or past height.
   - Optionally return Merkle proof.
+  - Merkle proof includes self-describing `type` field to support many types
+  of Merkle trees and encoding formats.
 
 ### BeginBlock
 
@@ -413,3 +415,44 @@ Commit are included in the header of the next block.
   - `Round (int32)`: Commit round.
   - `Votes ([]VoteInfo)`: List of validators addresses in the last validator set
     with their voting power and whether or not they signed a vote.
+
+###  ConsensusParams
+
+- **Fields**:
+  - `BlockSize (BlockSize)`: Parameters limiting the size of a block.
+  - `EvidenceParams (EvidenceParams)`: Parameters limiting the validity of
+    evidence of byzantine behaviour.
+
+### BlockSize
+
+- **Fields**:
+  - `MaxBytes (int64)`: Max size of a block, in bytes.
+  - `MaxGas (int64)`: Max sum of `GasWanted` in a proposed block.
+    - NOTE: blocks that violate this may be committed if there are Byzantine proposers.
+        It's the application's responsibility to handle this when processing a
+        block!
+
+### EvidenceParams
+
+- **Fields**:
+  - `MaxAge (int64)`: Max age of evidence, in blocks. Evidence older than this
+    is considered stale and ignored.
+        - This should correspond with an app's "unbonding period" or other
+          similar mechanism for handling Nothing-At-Stake attacks.
+        - NOTE: this should change to time (instead of blocks)!
+
+### Proof
+
+- **Fields**:
+  - `Ops ([]ProofOp)`: List of chained Merkle proofs, of possibly different types
+    - The Merkle root of one op is the value being proven in the next op.
+    - The Merkle root of the final op should equal the ultimate root hash being
+      verified against.
+
+### ProofOp
+
+- **Fields**:
+  - `Type (string)`: Type of Merkle proof and how it's encoded.
+  - `Key ([]byte)`: Key in the Merkle tree that this proof is for.
+  - `Data ([]byte)`: Encoded Merkle proof for the key.
+

docs/spec/abci/apps.md

@@ -247,8 +247,12 @@ Must have `0 < MaxAge`.
 
 ### Updates
 
-The application may set the consensus params during InitChain, and update them during
-EndBlock.
+The application may set the ConsensusParams during InitChain, and update them during
+EndBlock. If the ConsensusParams is empty, it will be ignored. Each field
+that is not empty will be applied in full. For instance, if updating the
+BlockSize.MaxBytes, applications must also set the other BlockSize fields (like
+BlockSize.MaxGas), even if they are unchanged, as they will otherwise cause the
+value to be updated to 0.
 
 #### InitChain
 
@@ -312,6 +316,30 @@ their state as follows:
 For instance, this allows an application's lite-client to verify proofs of
 absence in the application state, something which is much less efficient to do using the block hash.
 
+Some applications (eg. Ethereum, Cosmos-SDK) have multiple "levels" of Merkle trees,
+where the leaves of one tree are the root hashes of others. To support this, and
+the general variability in Merkle proofs, the `ResponseQuery.Proof` has some minimal structure:
+
+```
+message Proof {
+  repeated ProofOp ops
+}
+
+message ProofOp {
+  string type = 1;
+  bytes key = 2;
+  bytes data = 3;
+}
+```
+
+Each `ProofOp` contains a proof for a single key in a single Merkle tree, of the specified `type`.
+This allows ABCI to support many different kinds of Merkle trees, encoding
+formats, and proofs (eg. of presence and absence) just by varying the `type`.
+The `data` contains the actual encoded proof, encoded according to the `type`.
+When verifying the full proof, the root hash for one ProofOp is the value being
+verified for the next ProofOp in the list. The root hash of the final ProofOp in
+the list should match the `AppHash` being verified against.
+
 ### Peer Filtering
 
 When Tendermint connects to a peer, it sends two queries to the ABCI application