From caccabd4e517116f6a12f223765a7f20f7aafa66 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Wed, 27 Dec 2017 15:14:49 -0500 Subject: [PATCH] spec: fixes from review --- docs/specification/new-spec/README.md | 42 ++++++++++++++++++++++- docs/specification/new-spec/blockchain.md | 16 +++++---- 2 files changed, 50 insertions(+), 8 deletions(-) diff --git a/docs/specification/new-spec/README.md b/docs/specification/new-spec/README.md index 18ad457ec..a5061e62e 100644 --- a/docs/specification/new-spec/README.md +++ b/docs/specification/new-spec/README.md @@ -10,7 +10,47 @@ It contains the following components: - [Blockchain](blockchain.md) - [State](state.md) -TODO: +## Overview + +Tendermint provides Byzantine Fault Tolerant State Machine Replication using +hash-linked batches of transactions. Such transaction batches are called "blocks". +Hence Tendermint defines a "blockchain". + +Each block in Tendermint has a unique index - its Height. +A block at `Height == H` can only be committed *after* the +block at `Height == H-1`. +Each block is committed by a known set of weighted Validators. +Membership and weighting within this set may change over time. +Tendermint guarantees the safety and liveness of the blockchain +so long as less than 1/3 of the total weight of the Validator set +is malicious. + +A commit in Tendermint is a set of signed messages from more than 2/3 of +the total weight of the current Validator set. Validators take turns proposing +blocks and voting on them. Once enough votes are received, the block is considered +committed. These votes are included in the *next* block as proof that the previous block +was committed - they cannot be included in the current block, as that block has already been +created. + +Once a block is committed, it can be executed against an application. +The application returns results for each of the transactions in the block. +The application can also return changes to be made to the validator set, +as well as a cryptographic digest of its latest state. + +Tendermint is designed to enable efficient verification and authentication +of the latest state of the blockchain. To achieve this, it embeds +cryptographic commitments to certain information in the block "header". +This information includes the contents of the block (eg. the transactions), +the validator set committing the block, as well as the various results returned by the application. +Note, however, that block execution only occurs *after* a block is committed. +Thus, application results can only be included in the *next* block. + +Also note that information like the transaction results and the validator set are never +directly included in the block - only their cryptographic digests (Merkle roots) are. +Hence, verification of a block requires a separate data structure to store this information. +We call this the `State`. Block verification also requires access to the previous block. + +## TODO - Light Client - P2P diff --git a/docs/specification/new-spec/blockchain.md b/docs/specification/new-spec/blockchain.md index de78b81df..ce2529f80 100644 --- a/docs/specification/new-spec/blockchain.md +++ b/docs/specification/new-spec/blockchain.md @@ -184,7 +184,9 @@ The height is an incrementing integer. The first block has `block.Header.Height The median of the timestamps of the valid votes in the block.LastCommit. Corresponds to the number of nanoseconds, with millisecond resolution, since January 1, 1970. -Increments with every new block. + +Note the timestamp in a vote must be greater by at least one millisecond than that of the +block being voted on. ### NumTxs @@ -226,12 +228,12 @@ The first block has `block.Header.TotalTxs = block.Header.NumberTxs`. ### LastBlockID ``` -parts := MakeParts(block, state.ConsensusParams.BlockGossip.BlockPartSize) -block.HeaderLastBlockID == BlockID{ - SimpleMerkleRoot(block.Header), +prevBlockParts := MakeParts(prevBlock, state.LastConsensusParams.BlockGossip.BlockPartSize) +block.Header.LastBlockID == BlockID { + Hash: SimpleMerkleRoot(prevBlock.Header), PartsHeader{ - SimpleMerkleRoot(parts), - len(parts), + Hash: SimpleMerkleRoot(prevBlockParts), + Total: len(prevBlockParts), }, } ``` @@ -274,7 +276,7 @@ May be updated by the application. ### ConsensusParamsHash ``` -block.ValidatorsHash == SimpleMerkleRoot(state.ConsensusParams) +block.ConsensusParamsHash == SimpleMerkleRoot(state.ConsensusParams) ``` Simple Merkle root of the consensus parameters.