spec: typos & other fixes
This commit is contained in:
parent
6aa85357b6
commit
4b4a2029c4
|
@ -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,7 +24,9 @@ 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
|
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
|
- [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
|
||||||
|
@ -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
|
||||||
|
|
|
@ -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 *prevote* has `vote.Type == 1` and
|
||||||
a precommit has `vote.Type == 2`.
|
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,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
|
While the encoding was inspired by Go, it is easily implemented in other languages as well, given its intuitive design.
|
||||||
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…
Reference in New Issue