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

* docs: links to dirs need a slash

* docs/spec/abci: consensus params and general merkle
This commit is contained in:
Ethan Buchman 2018-09-30 15:08:01 -04:00 committed by GitHub
parent 52e21cebcf
commit ccd04587ff
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 80 additions and 7 deletions

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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