You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

431 lines
11 KiB

7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
  1. # Tendermint Blockchain
  2. Here we describe the data structures in the Tendermint blockchain and the rules for validating them.
  3. ## Data Structures
  4. The Tendermint blockchains consists of a short list of basic data types:
  5. - `Block`
  6. - `Header`
  7. - `Vote`
  8. - `BlockID`
  9. - `Signature`
  10. - `Evidence`
  11. ## Block
  12. A block consists of a header, a list of transactions, a list of votes (the commit),
  13. and a list of evidence of malfeasance (ie. signing conflicting votes).
  14. ```go
  15. type Block struct {
  16. Header Header
  17. Txs [][]byte
  18. LastCommit []Vote
  19. Evidence []Evidence
  20. }
  21. ```
  22. ## Header
  23. A block header contains metadata about the block and about the consensus, as well as commitments to
  24. the data in the current block, the previous block, and the results returned by the application:
  25. ```go
  26. type Header struct {
  27. // block metadata
  28. Version string // Version string
  29. ChainID string // ID of the chain
  30. Height int64 // Current block height
  31. Time int64 // UNIX time, in millisconds
  32. // current block
  33. NumTxs int64 // Number of txs in this block
  34. TxHash []byte // SimpleMerkle of the block.Txs
  35. LastCommitHash []byte // SimpleMerkle of the block.LastCommit
  36. // previous block
  37. TotalTxs int64 // prevBlock.TotalTxs + block.NumTxs
  38. LastBlockID BlockID // BlockID of prevBlock
  39. // application
  40. ResultsHash []byte // SimpleMerkle of []abci.Result from prevBlock
  41. AppHash []byte // Arbitrary state digest
  42. ValidatorsHash []byte // SimpleMerkle of the ValidatorSet
  43. ConsensusParamsHash []byte // SimpleMerkle of the ConsensusParams
  44. // consensus
  45. Proposer []byte // Address of the block proposer
  46. EvidenceHash []byte // SimpleMerkle of []Evidence
  47. }
  48. ```
  49. Further details on each of these fields is described below.
  50. ## BlockID
  51. The `BlockID` contains two distinct Merkle roots of the block.
  52. The first, used as the block's main hash, is the Merkle root
  53. of all the fields in the header. The second, used for secure gossipping of
  54. the block during consensus, is the Merkle root of the complete serialized block
  55. cut into parts. The `BlockID` includes these two hashes, as well as the number of
  56. parts.
  57. ```go
  58. type BlockID struct {
  59. Hash []byte
  60. Parts PartsHeader
  61. }
  62. type PartsHeader struct {
  63. Hash []byte
  64. Total int32
  65. }
  66. ```
  67. ## Vote
  68. A vote is a signed message from a validator for a particular block.
  69. The vote includes information about the validator signing it.
  70. ```go
  71. type Vote struct {
  72. Timestamp int64
  73. Address []byte
  74. Index int
  75. Height int64
  76. Round int
  77. Type int8
  78. BlockID BlockID
  79. Signature Signature
  80. }
  81. ```
  82. There are two types of votes:
  83. a *prevote* has `vote.Type == 1` and
  84. a *precommit* has `vote.Type == 2`.
  85. ## Signature
  86. Tendermint allows for multiple signature schemes to be used by prepending a single type-byte
  87. to the signature bytes. Different signatures may also come with fixed or variable lengths.
  88. Currently, Tendermint supports Ed25519 and Secp256k1.
  89. ### ED25519
  90. An ED25519 signature has `Type == 0x1`. It looks like:
  91. ```go
  92. // Implements Signature
  93. type Ed25519Signature struct {
  94. Type int8 = 0x1
  95. Signature [64]byte
  96. }
  97. ```
  98. where `Signature` is the 64 byte signature.
  99. ### Secp256k1
  100. A `Secp256k1` signature has `Type == 0x2`. It looks like:
  101. ```go
  102. // Implements Signature
  103. type Secp256k1Signature struct {
  104. Type int8 = 0x2
  105. Signature []byte
  106. }
  107. ```
  108. where `Signature` is the DER encoded signature, ie:
  109. ```hex
  110. 0x30 <length of whole message> <0x02> <length of R> <R> 0x2 <length of S> <S>.
  111. ```
  112. ## Evidence
  113. TODO
  114. ## Validation
  115. Here we describe the validation rules for every element in a block.
  116. Blocks which do not satisfy these rules are considered invalid.
  117. We abuse notation by using something that looks like Go, supplemented with English.
  118. A statement such as `x == y` is an assertion - if it fails, the item is invalid.
  119. We refer to certain globally available objects:
  120. `block` is the block under consideration,
  121. `prevBlock` is the `block` at the previous height,
  122. and `state` keeps track of the validator set, the consensus parameters
  123. and other results from the application.
  124. Elements of an object are accessed as expected,
  125. ie. `block.Header`. See [here](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/state.md) for the definition of `state`.
  126. ### Header
  127. A Header is valid if its corresponding fields are valid.
  128. ### Version
  129. Arbitrary string.
  130. ### ChainID
  131. Arbitrary constant string.
  132. ### Height
  133. ```go
  134. block.Header.Height > 0
  135. block.Header.Height == prevBlock.Header.Height + 1
  136. ```
  137. The height is an incrementing integer. The first block has `block.Header.Height == 1`.
  138. ### Time
  139. The median of the timestamps of the valid votes in the block.LastCommit.
  140. Corresponds to the number of nanoseconds, with millisecond resolution, since January 1, 1970.
  141. Note: the timestamp of a vote must be greater by at least one millisecond than that of the
  142. block being voted on.
  143. ### NumTxs
  144. ```go
  145. block.Header.NumTxs == len(block.Txs)
  146. ```
  147. Number of transactions included in the block.
  148. ### TxHash
  149. ```go
  150. block.Header.TxHash == SimpleMerkleRoot(block.Txs)
  151. ```
  152. Simple Merkle root of the transactions in the block.
  153. ### LastCommitHash
  154. ```go
  155. block.Header.LastCommitHash == SimpleMerkleRoot(block.LastCommit)
  156. ```
  157. Simple Merkle root of the votes included in the block.
  158. These are the votes that committed the previous block.
  159. The first block has `block.Header.LastCommitHash == []byte{}`
  160. ### TotalTxs
  161. ```go
  162. block.Header.TotalTxs == prevBlock.Header.TotalTxs + block.Header.NumTxs
  163. ```
  164. The cumulative sum of all transactions included in this blockchain.
  165. The first block has `block.Header.TotalTxs = block.Header.NumberTxs`.
  166. ### LastBlockID
  167. LastBlockID is the previous block's BlockID:
  168. ```go
  169. prevBlockParts := MakeParts(prevBlock, state.LastConsensusParams.BlockGossip.BlockPartSize)
  170. block.Header.LastBlockID == BlockID {
  171. Hash: SimpleMerkleRoot(prevBlock.Header),
  172. PartsHeader{
  173. Hash: SimpleMerkleRoot(prevBlockParts),
  174. Total: len(prevBlockParts),
  175. },
  176. }
  177. ```
  178. Note: it depends on the ConsensusParams,
  179. which are held in the `state` and may be updated by the application.
  180. The first block has `block.Header.LastBlockID == BlockID{}`.
  181. ### ResultsHash
  182. ```go
  183. block.ResultsHash == SimpleMerkleRoot(state.LastResults)
  184. ```
  185. Simple Merkle root of the results of the transactions in the previous block.
  186. The first block has `block.Header.ResultsHash == []byte{}`.
  187. ### AppHash
  188. ```go
  189. block.AppHash == state.AppHash
  190. ```
  191. Arbitrary byte array returned by the application after executing and commiting the previous block.
  192. The first block has `block.Header.AppHash == []byte{}`.
  193. ### ValidatorsHash
  194. ```go
  195. block.ValidatorsHash == SimpleMerkleRoot(state.Validators)
  196. ```
  197. Simple Merkle root of the current validator set that is committing the block.
  198. This can be used to validate the `LastCommit` included in the next block.
  199. May be updated by the application.
  200. ### ConsensusParamsHash
  201. ```go
  202. block.ConsensusParamsHash == SimpleMerkleRoot(state.ConsensusParams)
  203. ```
  204. Simple Merkle root of the consensus parameters.
  205. May be updated by the application.
  206. ### Proposer
  207. ```go
  208. block.Header.Proposer in state.Validators
  209. ```
  210. Original proposer of the block. Must be a current validator.
  211. NOTE: we also need to track the round.
  212. ## EvidenceHash
  213. ```go
  214. block.EvidenceHash == SimpleMerkleRoot(block.Evidence)
  215. ```
  216. Simple Merkle root of the evidence of Byzantine behaviour included in this block.
  217. ## Txs
  218. Arbitrary length array of arbitrary length byte-arrays.
  219. ## LastCommit
  220. The first height is an exception - it requires the LastCommit to be empty:
  221. ```go
  222. if block.Header.Height == 1 {
  223. len(b.LastCommit) == 0
  224. }
  225. ```
  226. Otherwise, we require:
  227. ```go
  228. len(block.LastCommit) == len(state.LastValidators)
  229. talliedVotingPower := 0
  230. for i, vote := range block.LastCommit{
  231. if vote == nil{
  232. continue
  233. }
  234. vote.Type == 2
  235. vote.Height == block.LastCommit.Height()
  236. vote.Round == block.LastCommit.Round()
  237. vote.BlockID == block.LastBlockID
  238. val := state.LastValidators[i]
  239. vote.Verify(block.ChainID, val.PubKey) == true
  240. talliedVotingPower += val.VotingPower
  241. }
  242. talliedVotingPower > (2/3) * TotalVotingPower(state.LastValidators)
  243. ```
  244. Includes one (possibly nil) vote for every current validator.
  245. Non-nil votes must be Precommits.
  246. All votes must be for the same height and round.
  247. All votes must be for the previous block.
  248. All votes must have a valid signature from the corresponding validator.
  249. The sum total of the voting power of the validators that voted
  250. must be greater than 2/3 of the total voting power of the complete validator set.
  251. ### Vote
  252. A vote is a signed message broadcast in the consensus for a particular block at a particular height and round.
  253. When stored in the blockchain or propagated over the network, votes are encoded in TMBIN.
  254. For signing, votes are encoded in JSON, and the ChainID is included, in the form of the `CanonicalSignBytes`.
  255. We define a method `Verify` that returns `true` if the signature verifies against the pubkey for the CanonicalSignBytes
  256. using the given ChainID:
  257. ```go
  258. func (v Vote) Verify(chainID string, pubKey PubKey) bool {
  259. return pubKey.Verify(v.Signature, CanonicalSignBytes(chainID, v))
  260. }
  261. ```
  262. where `pubKey.Verify` performs the appropriate digital signature verification of the `pubKey`
  263. against the given signature and message bytes.
  264. ## Evidence
  265. There is currently only one kind of evidence:
  266. ```
  267. // amino: "tendermint/DuplicateVoteEvidence"
  268. type DuplicateVoteEvidence struct {
  269. PubKey crypto.PubKey
  270. VoteA *Vote
  271. VoteB *Vote
  272. }
  273. ```
  274. DuplicateVoteEvidence `ev` is valid if
  275. - `ev.VoteA` and `ev.VoteB` can be verified with `ev.PubKey`
  276. - `ev.VoteA` and `ev.VoteB` have the same `Height, Round, Address, Index, Type`
  277. - `ev.VoteA.BlockID != ev.VoteB.BlockID`
  278. - `(block.Height - ev.VoteA.Height) < MAX_EVIDENCE_AGE`
  279. # Execution
  280. Once a block is validated, it can be executed against the state.
  281. The state follows this recursive equation:
  282. ```go
  283. state(1) = InitialState
  284. state(h+1) <- Execute(state(h), ABCIApp, block(h))
  285. ```
  286. where `InitialState` includes the initial consensus parameters and validator set,
  287. and `ABCIApp` is an ABCI application that can return results and changes to the validator
  288. set (TODO). Execute is defined as:
  289. ```go
  290. Execute(s State, app ABCIApp, block Block) State {
  291. TODO: just spell out ApplyBlock here
  292. and remove ABCIResponses struct.
  293. abciResponses := app.ApplyBlock(block)
  294. return State{
  295. LastResults: abciResponses.DeliverTxResults,
  296. AppHash: abciResponses.AppHash,
  297. Validators: UpdateValidators(state.Validators, abciResponses.ValidatorChanges),
  298. LastValidators: state.Validators,
  299. ConsensusParams: UpdateConsensusParams(state.ConsensusParams, abci.Responses.ConsensusParamChanges),
  300. }
  301. }
  302. type ABCIResponses struct {
  303. DeliverTxResults []Result
  304. ValidatorChanges []Validator
  305. ConsensusParamChanges ConsensusParams
  306. AppHash []byte
  307. }
  308. ```