@ -8,36 +8,36 @@ But what exactly is stored in these blocks?
### Block
A [Block](/docs/specs/tendermint-types#Block) contains:
A [Block](https://godoc.org/github.com/tendermint/tendermint/types#Block) contains:
* a [Header](#header) contains merkle hashes for various chain states
* the [Data]((/docs/specs/tendermint-types#Data) is all transactions which are to be processed
* the [Data](https://godoc.org/github.com/tendermint/tendermint/types#Data) is all transactions which are to be processed
* the [LastCommit](#commit) > 2/3 signatures for the last block
The signatures returned along with block `H` are those validating block `H-1`.
This can be a little confusing, but we must also consider that the
[Header](/docs/specs/tendermint-types#Header) also contains the `LastCommitHash`.
`Header` also contains the `LastCommitHash`.
It would be impossible for a Header to include the commits that sign it, as it
would cause an infinite loop here. But when we get block `H`, we find
`Header.LastCommitHash`, which must match the hash of `LastCommit`.
### Header
The [Header](/docs/specs/tendermint-types#Header) contains lots of information (follow
The [Header](https://godoc.org/github.com/tendermint/tendermint/types#Header) contains lots of information (follow
link for up-to-date info). Notably, it maintains the `Height`, the `LastBlockID`
(to make it a chain), and hashes of the data, the app state, and the validator set.
This is important as the only item that is signed by the validators is the `Header`,
and all other data must be validated against one of the merkle hashes in the `Header`.
The `DataHash` can provide a nice check on the [Data](/docs/specs/tendermint-types#Data)
The `DataHash` can provide a nice check on the [Data](https://godoc.org/github.com/tendermint/tendermint/types#Data)
returned in this same block. If you are subscribed to new blocks, via tendermint RPC, in order to display or process the new transactions
you should at least validate that the `DataHash` is valid.
If it is important to verify autheniticity, you must wait for the `LastCommit` from the next block to make sure the block header (including `DataHash`) was properly signed.
The `ValidatorHash` contains a hash of the current
[Validators](/docs/specs/tendermint-types#Validator). Tracking all changes in the
[Validators](https://godoc.org/github.com/tendermint/tendermint/types#Validator). Tracking all changes in the
validator set is complex, but a client can quickly compare this hash
with the [hash of the currently known validators](/docs/specs/tendermint-types#ValidatorSet.Hash)
with the [hash of the currently known validators](https://godoc.org/github.com/tendermint/tendermint/types#ValidatorSet.Hash)
to see if there have been changes.
The `AppHash` serves as the basis for validating any merkle proofs that come
@ -58,29 +58,28 @@ immutability of the block chain, as the application only applies transactions
### Commit
The [Commit](/docs/specs/tendermint-types#Commit) contains a set of
[Votes](/docs/specs/tendermint-types#Vote) that were made by the validator set to
The [Commit](https://godoc.org/github.com/tendermint/tendermint/types#Commit) contains a set of
[Votes](https://godoc.org/github.com/tendermint/tendermint/types#Vote) that were made by the validator set to
reach consensus on this block. This is the key to the security in any PoS
system, and actually no data that cannot be traced back to a block header
with a valid set of Votes can be trusted. Thus, getting the Commit data
and verifying the votes is extremely important.
As mentioned above, in order to find the `precommit votes` for block header `H`,
we need to query block `H+1`. Then we need to check the votes, make sure they
we need to query block `H+1`. Then we need to check the votes, make sure they
really are for that block, and properly formatted. Much of this code is implemented
in Go in the [light-client](https://github.com/tendermint/light-client) package,
especially [Node.SignedHeader](https://github.com/tendermint/light-client/blob/develop/rpc/node.go#L117).
in Go in the [light-client](https://github.com/tendermint/light-client) package.
If you look at the code, you will notice that we need to provide the `chainID`
of the blockchain in order to properly calculate the votes. This is to protect
of the blockchain in order to properly calculate the votes. This is to protect
anyone from swapping votes between chains to fake (or frame) a validator.
Also note that this `chainID` is in the `genesis.json` from _Tendermint_,
not the `genesis.json` from the basecoin app ([that is a different chainID...](https://github.com/tendermint/basecoin/issues/32)).
Once we have those votes,
and we calculated the proper [sign bytes](/docs/specs/tendermint-types#Vote.WriteSignBytes)
using the chainID and a [nice helper function](/docs/specs/tendermint-types#SignBytes),
we can verify them. The light client is responsible for maintaining a set of
validators that we trust. Each vote only stores the validators `Address`, as well
and we calculated the proper [sign bytes](https://godoc.org/github.com/tendermint/tendermint/types#Vote.WriteSignBytes)
using the chainID and a [nice helper function](https://godoc.org/github.com/tendermint/tendermint/types#SignBytes),
we can verify them. The light client is responsible for maintaining a set of
validators that we trust. Each vote only stores the validators `Address`, as well
as the `Signature`. Assuming we have a local copy of the trusted validator set,
we can look up the `Public Key` of the validator given its `Address`, then
verify that the `Signature` matches the `SignBytes` and `Public Key`.
@ -89,13 +88,6 @@ all these stringent requirements. If the total number of voting power for a sing
than 2/3 of all voting power, then we can finally trust the
block header, the AppHash, and the proof we got from the ABCI application.
To make this a bit more concrete, you can take a look at a
to see how this logic works, given a static set of validators. And you can see
an example of how one can perform the entire chain of validation in the
proxy server [proof call](https://github.com/tendermint/light-client/blob/develop/proxy/viewer.go#L61)
or the [test code for auditing](https://github.com/tendermint/light-client/blob/develop/rpc/tests/node_test.go#L102).
#### Vote Sign Bytes
The `sign-bytes` of a vote is produced by taking a [`stable-json`](https://github.com/substack/json-stable-stringify)-like deterministic JSON [`wire`](/docs/specs/wire-protocol) encoding of the vote (excluding the `Signature` field), and wrapping it with `{"chain_id":"my_chain","vote":...}`.
@ -107,15 +99,15 @@ For example, a precommit vote might have the following `sign-bytes`:
### Block Hash
The [block hash](/docs/specs/tendermint-types#Block.Hash) is the [Simple Tree hash](Merkle-Trees#simple-tree-with-dictionaries) of the fields of the block `Header` encoded as a list of `KVPair`s.
The [block hash](https://godoc.org/github.com/tendermint/tendermint/types#Block.Hash) is the [Simple Tree hash](Merkle-Trees#simple-tree-with-dictionaries) of the fields of the block `Header` encoded as a list of `KVPair`s.
### Transaction
A transaction is any sequence of bytes. It is up to your [ABCI](https://github.com/tendermint/abci) application to accept or reject transactions.
A transaction is any sequence of bytes. It is up to your [ABCI](https://github.com/tendermint/abci) application to accept or reject transactions.
### BlockID
Many of these data structures refer to the [BlockID](/docs/specs/tendermint-types#BlockID),
Many of these data structures refer to the [BlockID](https://godoc.org/github.com/tendermint/tendermint/types#BlockID),
which is the `BlockHash` (hash of the block header, also referred to by the next block)
along with the `PartSetHeader`. The `PartSetHeader` is explained below and is used internally
to orchestrate the p2p propogation. For clients, it is basically opaque bytes,
@ -123,7 +115,7 @@ but they must match for all votes.
### PartSetHeader
The [PartSetHeader](/docs/specs/tendermint-types#PartSetHeader) contains the total number of pieces in a [PartSet](/docs/specs/tendermint-types#PartSet), and the Merkle root hash of those pieces.
The [PartSetHeader](https://godoc.org/github.com/tendermint/tendermint/types#PartSetHeader) contains the total number of pieces in a [PartSet](https://godoc.org/github.com/tendermint/tendermint/types#PartSet), and the Merkle root hash of those pieces.
### PartSet
@ -137,7 +129,7 @@ PartSet was inspired by the LibSwift project.
@ -7,7 +7,7 @@ _The draft 0.6 whitepaper is outdated. The new algorithm is detailed below. See
- The consensus process in deciding the next block (at some _height_`H`) is composed of one or many _rounds_.
- `NewHeight`, `Propose`, `Prevote`, `Precommit`, and `Commit` represent state machine states of a round. (aka `RoundStep` or just "step").
- A node is said to be _at_ a given height, round, and step, or at `(H,R,S)`, or at `(H,R)` in short to omit the step.
- To _prevote_ or _precommit_ something means to broadcast a [prevote vote](/docs/specs/block-structure#vote) or [precommit vote](/docs/specs/block-structure#precommit-vote) for something.
- To _prevote_ or _precommit_ something means to broadcast a [prevote vote](https://godoc.org/github.com/tendermint/tendermint/types#Vote) or [first precommit vote](https://godoc.org/github.com/tendermint/tendermint/types#FirstPrecommit) for something.
- A vote _at_`(H,R)` is a vote signed with the bytes for `H` and `R` included in its [`sign-bytes`](/docs/specs/block-structure#vote-sign-bytes).
- _+2/3_ is short for "more than 2/3"
- _1/3+_ is short for "1/3 or more"
@ -20,11 +20,12 @@ the next block. Each round is composed of three _steps_ (`Propose`, `Prevote`, a
`Precommit`), along with two special steps `Commit` and `NewHeight`.
The sequence `(Propose -> Prevote -> Precommit)` is called a _round_. There may be more than one round required to commit a block at a given height. Examples for why more rounds may be required include:
The sequence `(Propose -> Prevote -> Precommit)` is called a _round_. There may be more than one round required to commit a block at a given height. Examples for why more rounds may be required include:
- The designated proposer was not online.
- The block proposed by the designated proposer was not valid.
@ -35,6 +36,7 @@ The sequence `(Propose -> Prevote -> Precommit)` is called a _round_. There may
Some of these problems are resolved by moving onto the next round & proposer. Others are resolved by increasing certain round timeout parameters over each successive round.
## State Machine Diagram
```
+-------------------------------------+
v |(Wait til `CommmitTime+timeoutCommit`)
@ -58,14 +60,14 @@ Some of these problems are resolved by moving onto the next round & proposer. O
## Background Gossip
A node may not have a corresponding validator private key, but it nevertheless plays an active role in the consensus process by relaying relevant meta-data, proposals, blocks, and votes to its peers. A node that has the private keys of an active validator and is engaged in signing votes is called a _validator-node_. All nodes (not just validator-nodes) have an associated state (the current height, round, and step) and work to make progress.
A node may not have a corresponding validator private key, but it nevertheless plays an active role in the consensus process by relaying relevant meta-data, proposals, blocks, and votes to its peers. A node that has the private keys of an active validator and is engaged in signing votes is called a _validator-node_. All nodes (not just validator-nodes) have an associated state (the current height, round, and step) and work to make progress.
Between two nodes there exists a `Connection`, and multiplexed on top of this connection are fairly throttled `Channel`s of information. An epidemic gossip protocol is implemented among some of these channels to bring peers up to speed on the most recent state of consensus. For example,
Between two nodes there exists a `Connection`, and multiplexed on top of this connection are fairly throttled `Channel`s of information. An epidemic gossip protocol is implemented among some of these channels to bring peers up to speed on the most recent state of consensus. For example,
- Nodes gossip `PartSet` parts of the current round's proposer's proposed block. A LibSwift inspired algorithm is used to quickly broadcast blocks across the gossip network.
- Nodes gossip prevote/precommit votes. A node NODE_A that is ahead of NODE_B can send NODE_B prevotes or precommits for NODE_B's current (or future) round to enable it to progress forward.
- Nodes gossip prevotes for the proposed PoLC (proof-of-lock-change) round if one is proposed.
- Nodes gossip to nodes lagging in blockchain height with block [commits](/docs/specs/block-structure/commit) for older blocks.
- Nodes gossip to nodes lagging in blockchain height with block [commits](https://godoc.org/github.com/tendermint/tendermint/types#Commit) for older blocks.
- Nodes opportunistically gossip `HasVote` messages to hint peers what votes it already has.
- Nodes broadcast their current state to all neighboring peers. (but is not gossiped further)
@ -73,7 +75,7 @@ There's more, but let's not get ahead of ourselves here.
## Proposals
A proposal is signed and published by the designated proposer at each round. The proposer is chosen by a deterministic and non-choking round robin selection algorithm that selects proposers in proportion to their voting power. (see [implementation](https://github.com/tendermint/tendermint/blob/develop/types/validator_set.go#L49))
A proposal is signed and published by the designated proposer at each round. The proposer is chosen by a deterministic and non-choking round robin selection algorithm that selects proposers in proportion to their voting power. (see [implementation](https://github.com/tendermint/tendermint/blob/develop/types/validator_set.go))
A proposal at `(H,R)` is composed of a block and an optional latest `PoLC-Round < R` which is included iff the proposer knows of one. This hints the network to allow nodes to unlock (when safe) to ensure the liveness property.
@ -187,9 +189,3 @@ there are no significant network partitions, to avoid situations where two
conflicting reorg-proposals are signed.
Assuming that the external coordination medium and protocol is robust, it follows that forks are less of a concern than [censorship attacks](#censorship-attacks).
### Revisions
#### 0.6 -> 0.7 (current)
1. Reduced the minimum number of signature steps from 3 to 2 by removing the "commit" vote and step.
2. The protocol is more asynchronous: instead of each round taking a predetermined duration of time, each step of a round progresses after +2/3 of the step's votes are found and a timeout is reached, or immediately after +2/3 of matching votes (e.g. a PoLC for prevotes, or a commit for precommits).
@ -8,6 +8,6 @@ In a proof of work blockchain, syncing with the chain is the same process as sta
To support faster syncing, tendermint offers a `fast-sync` mode, which is enabled by default, and can be toggled in the `config.toml` or via `--fast_sync=false`.
In this mode, the tendermint daemon will sync hundreds of times faster than if it used the real-time consensus process. Once caught up, the daemon will switch out of fast sync and into the normal consensus mode. After running for some time, the node is considered `caught up` if it has at least one peer and it's height is at least as high as the max reported peer height. See [the IsCaughtUp method](https://github.com/tendermint/tendermint/blob/master/blockchain/pool.go#L128).
In this mode, the tendermint daemon will sync hundreds of times faster than if it used the real-time consensus process. Once caught up, the daemon will switch out of fast sync and into the normal consensus mode. After running for some time, the node is considered `caught up` if it has at least one peer and it's height is at least as high as the max reported peer height. See [the IsCaughtUp method](https://github.com/tendermint/tendermint/blob/b467515719e686e4678e6da4e102f32a491b85a0/blockchain/pool.go#L128).
If we're lagging sufficiently, we should go back to fast syncing, but this is an open issue: https://github.com/tendermint/tendermint/issues/129
@ -16,7 +16,8 @@ NOTE: This does not (yet) specify the application state (e.g. initial distributi
### Sample genesis.json
This example is from the Basecoin mintnet example ([link to file](https://github.com/tendermint/mintnet/blob/master/examples/basecoin/mach1/core/genesis.json)).
This example is from the Basecoin mintnet example:
Light clients are an important part of the complete blockchain system for most applications. Tendermint provides unique speed and security properties for light client applications.
See our developing [light-client repository](github.com/tendermint/light-client).
See our developing [light-client repository](https://github.com/tendermint/light-client).
## Overview
The objective of the light client protocol is to get a [commit](/docs/specs/validators#committing-a-block) for a recent [block hash](/docs/specs/block-structure#block-hash) where the commit includes a majority of signatures from the last known validator set. From there, all the application state is verifiable with [merkle proofs](/docs/specs/merkle-trees#iavl-tree).
### Syncing the Validator Set
TODO
## Properties
- You get the full collateralized security benefits of Tendermint; No need to wait for confirmations.
Ethan Buchman
7 years ago
GitHub