tendermint/docs/spec/README.md

# Tendermint Specification

This is a markdown specification of the Tendermint blockchain.
It defines the base data structures, how they are validated,
and how they are communicated over the network.

If you find discrepancies between the spec and the code that
do not have an associated issue or pull request on github,
please submit them to our [bug bounty](https://tendermint.com/security)!

## Contents

- [Overview](#overview)

### Data Structures

- [Encoding and Digests](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/encoding.md)
- [Blockchain](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/blockchain.md)
- [State](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/state.md)

### Consensus Protocol

- [Consensus Algorithm](/docs/spec/consensus/consensus.md)
- [Creating a proposal](/docs/spec/consensus/creating-proposal.md)
- [Time](/docs/spec/consensus/bft-time.md)
- [Light-Client](/docs/spec/consensus/light-client.md)

### P2P and Network Protocols

- [The Base P2P Layer](https://github.com/tendermint/tendermint/tree/master/docs/spec/p2p): multiplex the protocols ("reactors") on authenticated and encrypted TCP connections
- [Peer Exchange (PEX)](https://github.com/tendermint/tendermint/tree/master/docs/spec/reactors/pex): gossip known peer addresses so peers can find each other
- [Block Sync](https://github.com/tendermint/tendermint/tree/master/docs/spec/reactors/block_sync): gossip blocks so peers can catch up quickly
- [Consensus](https://github.com/tendermint/tendermint/tree/master/docs/spec/reactors/consensus): gossip votes and block parts so new blocks can be committed
- [Mempool](https://github.com/tendermint/tendermint/tree/master/docs/spec/reactors/mempool): gossip transactions so they get included in blocks
- Evidence: Forthcoming, see [this issue](https://github.com/tendermint/tendermint/issues/2329).

### Software

- [ABCI](/docs/spec/software/abci.md): Details about interactions between the
  application and consensus engine over ABCI
- [Write-Ahead Log](/docs/spec/software/wal.md): Details about how the consensus
  engine preserves data and recovers from crash failures

## 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.
Height's in the blockchain are monotonic.
Each block is committed by a known set of weighted Validators.
Membership and weighting within this validator 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 or faulty.

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.
state 2017-12-26 15:43:03 -08:00			`# Tendermint Specification`

			`This is a markdown specification of the Tendermint blockchain.`
docs consolidation 2018-01-21 15:19:38 -08:00			`It defines the base data structures, how they are validated,`
			`and how they are communicated over the network.`
state 2017-12-26 15:43:03 -08:00
add warnings about new spec 2018-01-19 14:51:09 -08:00			`If you find discrepancies between the spec and the code that`
			`do not have an associated issue or pull request on github,`
			`please submit them to our [bug bounty](https://tendermint.com/security)!`
state 2017-12-26 15:43:03 -08:00
add warnings about new spec 2018-01-19 14:51:09 -08:00			`## Contents`

docs/spec: blockchain and consensus dirs 2018-05-19 21:28:47 -07:00			`- [Overview](#overview)`

docs consolidation 2018-01-21 15:19:38 -08:00			`### Data Structures`

docs: use absolute links (#1617) 2018-05-23 07:01:32 -07:00			`- [Encoding and Digests](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/encoding.md)`
			`- [Blockchain](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/blockchain.md)`
			`- [State](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/state.md)`
docs/spec: blockchain and consensus dirs 2018-05-19 21:28:47 -07:00
			`### Consensus Protocol`

docs/spec: some organizational cleanup 2018-06-15 22:56:26 -07:00			`- [Consensus Algorithm](/docs/spec/consensus/consensus.md)`
conesnsu: follow up to removing some consensus params (#2427) * follow up to removing some consensus params Refs #2382 * change args type to int64 in state#makeParams * make valsCount and evidenceCount ints again * MaxEvidenceBytesPerBlock: include magic number in godoc * [spec] creating a proposal * test state#TxFilter * panic if MaxDataBytes is less than 0 * fixes after review * use amino#UvarintSize to calculate overhead https://github.com/tendermint/go-amino/blob/0c74291f3bb61e24f8ea1d13148cece479f79d35/encoder.go#L85-L90 * avoid cyclic imports * you can do better Go, come on * remove testdouble package 2018-09-21 02:00:36 -07:00			`- [Creating a proposal](/docs/spec/consensus/creating-proposal.md)`
docs/spec: some organizational cleanup 2018-06-15 22:56:26 -07:00			`- [Time](/docs/spec/consensus/bft-time.md)`
			`- [Light-Client](/docs/spec/consensus/light-client.md)`
docs consolidation 2018-01-21 15:19:38 -08:00
			`### P2P and Network Protocols`

docs: use absolute links (#1617) 2018-05-23 07:01:32 -07:00			`- [The Base P2P Layer](https://github.com/tendermint/tendermint/tree/master/docs/spec/p2p): multiplex the protocols ("reactors") on authenticated and encrypted TCP connections`
			`- [Peer Exchange (PEX)](https://github.com/tendermint/tendermint/tree/master/docs/spec/reactors/pex): gossip known peer addresses so peers can find each other`
			`- [Block Sync](https://github.com/tendermint/tendermint/tree/master/docs/spec/reactors/block_sync): gossip blocks so peers can catch up quickly`
			`- [Consensus](https://github.com/tendermint/tendermint/tree/master/docs/spec/reactors/consensus): gossip votes and block parts so new blocks can be committed`
			`- [Mempool](https://github.com/tendermint/tendermint/tree/master/docs/spec/reactors/mempool): gossip transactions so they get included in blocks`
Several minor docs & spec cleanup (#2330) * addr_book_strick=false on local nets * link to spec * spec: remove TODO, see #1749 instead * spec: make issues from TODOs * update docs on addr_book_strict option 2018-09-04 23:30:36 -07:00			`- Evidence: Forthcoming, see [this issue](https://github.com/tendermint/tendermint/issues/2329).`
docs consolidation 2018-01-21 15:19:38 -08:00
docs/spec: some organizational cleanup 2018-06-15 22:56:26 -07:00			`### Software`

			`- [ABCI](/docs/spec/software/abci.md): Details about interactions between the`
			`application and consensus engine over ABCI`
			`- [Write-Ahead Log](/docs/spec/software/wal.md): Details about how the consensus`
			`engine preserves data and recovers from crash failures`
state 2017-12-26 15:43:03 -08:00
spec: fixes from review 2017-12-27 12:14:49 -08:00			`## Overview`

			`Tendermint provides Byzantine Fault Tolerant State Machine Replication using`
			`hash-linked batches of transactions. Such transaction batches are called "blocks".`
spec: typos & other fixes 2018-01-24 18:11:07 -08:00			`Hence, Tendermint defines a "blockchain".`
spec: fixes from review 2017-12-27 12:14:49 -08:00
			`Each block in Tendermint has a unique index - its Height.`
docs/spec: some organizational cleanup 2018-06-15 22:56:26 -07:00			`Height's in the blockchain are monotonic.`
spec: fixes from review 2017-12-27 12:14:49 -08:00			`Each block is committed by a known set of weighted Validators.`
docs/spec: some organizational cleanup 2018-06-15 22:56:26 -07:00			`Membership and weighting within this validator set may change over time.`
spec: fixes from review 2017-12-27 12:14:49 -08:00			`Tendermint guarantees the safety and liveness of the blockchain`
			`so long as less than 1/3 of the total weight of the Validator set`
spec: typos & other fixes 2018-01-24 18:11:07 -08:00			`is malicious or faulty.`
spec: fixes from review 2017-12-27 12:14:49 -08:00
			`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`
lint markdown docs using a stop-words and write-good linters (#2195) * lint docs with write-good, stop-words * remove package-lock.json * update changelog * fix wrong paragraph formatting * fix some docs formatting * fix docs format * fix abci spec format 2018-08-27 00:33:46 -07:00			`committed. These votes are included in the _next_ block as proof that the previous block`
spec: fixes from review 2017-12-27 12:14:49 -08:00			`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.`
lint markdown docs using a stop-words and write-good linters (#2195) * lint docs with write-good, stop-words * remove package-lock.json * update changelog * fix wrong paragraph formatting * fix some docs formatting * fix docs format * fix abci spec format 2018-08-27 00:33:46 -07:00			`Note, however, that block execution only occurs _after_ a block is committed.`
			`Thus, application results can only be included in the _next_ block.`
spec: fixes from review 2017-12-27 12:14:49 -08:00
			`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.