diff --git a/docs/specification/new-spec/README.md b/docs/specification/new-spec/README.md index 5b2f50cdd..f3b9e3c29 100644 --- a/docs/specification/new-spec/README.md +++ b/docs/specification/new-spec/README.md @@ -5,7 +5,7 @@ It defines the base data structures, how they are validated, and how they are communicated over the network. XXX: this spec is a work in progress and not yet complete - see github -[isses](https://github.com/tendermint/tendermint/issues) and +[issues](https://github.com/tendermint/tendermint/issues) and [pull requests](https://github.com/tendermint/tendermint/pulls) for more details. @@ -24,8 +24,10 @@ please submit them to our [bug bounty](https://tendermint.com/security)! ### P2P and Network Protocols -- [The Base P2P Layer](p2p/README.md): multiplex the protocols ("reactors") on authenticated and encrypted TCP conns -- [Peer Exchange (PEX)](pex/README.md): gossip known peer addresses so peers can find eachother +TODO: update links + +- [The Base P2P Layer](p2p/README.md): multiplex the protocols ("reactors") on authenticated and encrypted TCP connections +- [Peer Exchange (PEX)](pex/README.md): gossip known peer addresses so peers can find each other - [Block Sync](block_sync/README.md): gossip blocks so peers can catch up quickly - [Consensus](consensus/README.md): gossip votes and block parts so new blocks can be committed - [Mempool](mempool/README.md): gossip transactions so they get included in blocks @@ -39,7 +41,7 @@ please submit them to our [bug bounty](https://tendermint.com/security)! 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". +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 @@ -48,7 +50,7 @@ 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. +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 diff --git a/docs/specification/new-spec/blockchain.md b/docs/specification/new-spec/blockchain.md index 93e4df6db..3f8849b15 100644 --- a/docs/specification/new-spec/blockchain.md +++ b/docs/specification/new-spec/blockchain.md @@ -5,7 +5,13 @@ Here we describe the data structures in the Tendermint blockchain and the rules ## Data Structures The Tendermint blockchains consists of a short list of basic data types: -`Block`, `Header`, `Vote`, `BlockID`, `Signature`, and `Evidence`. + +- `Block` +- `Header` +- `Vote` +- `BlockID` +- `Signature` +- `Evidence` ## Block @@ -31,7 +37,7 @@ type Header struct { // block metadata Version string // Version string ChainID string // ID of the chain - Height int64 // current block height + Height int64 // Current block height Time int64 // UNIX time, in millisconds // current block @@ -55,7 +61,7 @@ type Header struct { } ``` -Further details on each of this fields is taken up below. +Further details on each of these fields is described below. ## BlockID @@ -97,8 +103,8 @@ type Vote struct { ``` There are two types of votes: -a prevote has `vote.Type == 1` and -a precommit has `vote.Type == 2`. +a *prevote* has `vote.Type == 1` and +a *precommit* has `vote.Type == 2`. ## Signature @@ -184,7 +190,7 @@ 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. -Note the timestamp in a vote must be greater by at least one millisecond than that of the +Note: the timestamp of a vote must be greater by at least one millisecond than that of the block being voted on. ### NumTxs @@ -226,6 +232,8 @@ The first block has `block.Header.TotalTxs = block.Header.NumberTxs`. ### LastBlockID +For the previous block's BlockID: + ```go prevBlockParts := MakeParts(prevBlock, state.LastConsensusParams.BlockGossip.BlockPartSize) block.Header.LastBlockID == BlockID { @@ -237,7 +245,7 @@ block.Header.LastBlockID == BlockID { } ``` -Previous block's BlockID. Note it depends on the ConsensusParams, +Note: it depends on the ConsensusParams, which are held in the `state` and may be updated by the application. The first block has `block.Header.LastBlockID == BlockID{}`. @@ -289,9 +297,9 @@ block.Header.Proposer in state.Validators Original proposer of the block. Must be a current validator. -NOTE: this field can only be further verified by real-time participants in the consensus. +**Note:** this field can only be further verified by real-time participants in the consensus. This is because the same block can be proposed in multiple rounds for the same height -and we do not track the initial round the block was proposed. +and we do not track the initial round that the block was proposed. ### EvidenceHash @@ -361,7 +369,7 @@ func (v Vote) Verify(chainID string, pubKey PubKey) bool { } ``` -where `pubKey.Verify` performs the approprioate digital signature verification of the `pubKey` +where `pubKey.Verify` performs the appropriate digital signature verification of the `pubKey` against the given signature and message bytes. ## Evidence @@ -381,14 +389,14 @@ The votes must not be too old. Once a block is validated, it can be executed against the state. -The state follows the recursive equation: +The state follows this recursive equation: ```go state(1) = InitialState state(h+1) <- Execute(state(h), ABCIApp, block(h)) ``` -Where `InitialState` includes the initial consensus parameters and validator set, +where `InitialState` includes the initial consensus parameters and validator set, and `ABCIApp` is an ABCI application that can return results and changes to the validator set (TODO). Execute is defined as: diff --git a/docs/specification/new-spec/encoding.md b/docs/specification/new-spec/encoding.md index 205b8574e..97dbf0477 100644 --- a/docs/specification/new-spec/encoding.md +++ b/docs/specification/new-spec/encoding.md @@ -5,8 +5,7 @@ Tendermint aims to encode data structures in a manner similar to how the corresponding Go structs are laid out in memory. Variable length items are length-prefixed. -While the encoding was inspired by Go, it is easily implemented in other languages as well given its -intuitive design. +While the encoding was inspired by Go, it is easily implemented in other languages as well, given its intuitive design. XXX: This is changing to use real varints and 4-byte-prefixes. See https://github.com/tendermint/go-wire/tree/sdk2. @@ -52,7 +51,7 @@ encode(int(0)) == [0x00] ### Strings -An encoded string is a length prefix followed by the underlying bytes of the string. +An encoded string is length-prefixed followed by the underlying bytes of the string. The length-prefix is itself encoded as an `int`. The empty string is encoded as `0x00`. It is not length-prefixed. @@ -82,7 +81,7 @@ encode([2]string{"abc", "efg"}) == [0x01, 0x03, 0x61, 0x62, 0x63, 0x01, 0x03, 0x ### Slices (variable length) -An encoded variable-length array is a length prefix followed by the concatenation of the encoding of +An encoded variable-length array is length-prefixed followed by the concatenation of the encoding of its elements. The length-prefix is itself encoded as an `int`. @@ -165,7 +164,7 @@ func SimpleMerkleRoot(hashes [][]byte) []byte{ } ``` -Note we abuse notion and call `SimpleMerkleRoot` with arguments of type `struct` or type `[]struct`. +Note: we abuse notion and call `SimpleMerkleRoot` with arguments of type `struct` or type `[]struct`. For `struct` arguments, we compute a `[][]byte` by sorting elements of the `struct` according to field name and then hashing them. For `[]struct` arguments, we compute a `[][]byte` by hashing the individual `struct` elements. @@ -190,7 +189,7 @@ Note how the fields within each level are sorted. ### MakeParts -TMBIN encode an object and slice it into parts. +TMBIN encodes an object and slices it into parts. ```go MakeParts(object, partSize)