From ccd04587ff3f8806af7f3af10a187520e4defd29 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sun, 30 Sep 2018 15:08:01 -0400 Subject: [PATCH] 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 | 2 ++ docs/README.md | 4 ++-- docs/spec/abci/abci.md | 49 +++++++++++++++++++++++++++++++++++++++--- docs/spec/abci/apps.md | 32 +++++++++++++++++++++++++-- 4 files changed, 80 insertions(+), 7 deletions(-) diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md index e2f22ff6..a7671c36 100644 --- a/docs/DOCS_README.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index 15ce74e3..c3293547 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/spec/abci/abci.md b/docs/spec/abci/abci.md index 0e9b3d78..1306128f 100644 --- a/docs/spec/abci/abci.md +++ b/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. + diff --git a/docs/spec/abci/apps.md b/docs/spec/abci/apps.md index a8f37771..acf2c4e6 100644 --- a/docs/spec/abci/apps.md +++ b/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