Browse Source

spec: typos & other fixes

pull/1178/head
Zach Ramsay 7 years ago
committed by Ethan Buchman
parent
commit
4b4a2029c4
3 changed files with 32 additions and 23 deletions
  1. +7
    -5
      docs/specification/new-spec/README.md
  2. +20
    -12
      docs/specification/new-spec/blockchain.md
  3. +5
    -6
      docs/specification/new-spec/encoding.md

+ 7
- 5
docs/specification/new-spec/README.md View File

@ -5,7 +5,7 @@ It defines the base data structures, how they are validated,
and how they are communicated over the network. and how they are communicated over the network.
XXX: this spec is a work in progress and not yet complete - see github 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) [pull requests](https://github.com/tendermint/tendermint/pulls)
for more details. for more details.
@ -24,8 +24,10 @@ please submit them to our [bug bounty](https://tendermint.com/security)!
### P2P and Network Protocols ### 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 - [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 - [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 - [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 Tendermint provides Byzantine Fault Tolerant State Machine Replication using
hash-linked batches of transactions. Such transaction batches are called "blocks". 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. Each block in Tendermint has a unique index - its Height.
A block at `Height == H` can only be committed *after* the 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. Membership and weighting within this set may change over time.
Tendermint guarantees the safety and liveness of the blockchain Tendermint guarantees the safety and liveness of the blockchain
so long as less than 1/3 of the total weight of the Validator set 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 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 the total weight of the current Validator set. Validators take turns proposing


+ 20
- 12
docs/specification/new-spec/blockchain.md View File

@ -5,7 +5,13 @@ Here we describe the data structures in the Tendermint blockchain and the rules
## Data Structures ## Data Structures
The Tendermint blockchains consists of a short list of basic data types: 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 ## Block
@ -31,7 +37,7 @@ type Header struct {
// block metadata // block metadata
Version string // Version string Version string // Version string
ChainID string // ID of the chain ChainID string // ID of the chain
Height int64 // current block height
Height int64 // Current block height
Time int64 // UNIX time, in millisconds Time int64 // UNIX time, in millisconds
// current block // 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 ## BlockID
@ -97,8 +103,8 @@ type Vote struct {
``` ```
There are two types of votes: 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 ## 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. 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. 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. block being voted on.
### NumTxs ### NumTxs
@ -226,6 +232,8 @@ The first block has `block.Header.TotalTxs = block.Header.NumberTxs`.
### LastBlockID ### LastBlockID
For the previous block's BlockID:
```go ```go
prevBlockParts := MakeParts(prevBlock, state.LastConsensusParams.BlockGossip.BlockPartSize) prevBlockParts := MakeParts(prevBlock, state.LastConsensusParams.BlockGossip.BlockPartSize)
block.Header.LastBlockID == BlockID { 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. which are held in the `state` and may be updated by the application.
The first block has `block.Header.LastBlockID == BlockID{}`. 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. 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 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 ### 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. against the given signature and message bytes.
## Evidence ## Evidence
@ -381,14 +389,14 @@ The votes must not be too old.
Once a block is validated, it can be executed against the state. 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 ```go
state(1) = InitialState state(1) = InitialState
state(h+1) <- Execute(state(h), ABCIApp, block(h)) 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 and `ABCIApp` is an ABCI application that can return results and changes to the validator
set (TODO). Execute is defined as: set (TODO). Execute is defined as:


+ 5
- 6
docs/specification/new-spec/encoding.md View File

@ -5,8 +5,7 @@
Tendermint aims to encode data structures in a manner similar to how the corresponding Go structs Tendermint aims to encode data structures in a manner similar to how the corresponding Go structs
are laid out in memory. are laid out in memory.
Variable length items are length-prefixed. 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. XXX: This is changing to use real varints and 4-byte-prefixes.
See https://github.com/tendermint/go-wire/tree/sdk2. See https://github.com/tendermint/go-wire/tree/sdk2.
@ -52,7 +51,7 @@ encode(int(0)) == [0x00]
### Strings ### 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 length-prefix is itself encoded as an `int`.
The empty string is encoded as `0x00`. It is not length-prefixed. 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) ### 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. its elements.
The length-prefix is itself encoded as an `int`. 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 For `struct` arguments, we compute a `[][]byte` by sorting elements of the `struct` according to
field name and then hashing them. field name and then hashing them.
For `[]struct` arguments, we compute a `[][]byte` by hashing the individual `struct` elements. 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 ### MakeParts
TMBIN encode an object and slice it into parts.
TMBIN encodes an object and slices it into parts.
```go ```go
MakeParts(object, partSize) MakeParts(object, partSize)


Loading…
Cancel
Save