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.

212 lines
7.3 KiB

  1. # Tendermint Consensus Reactor
  2. Tendermint Consensus is a distributed protocol executed by validator processes to agree on
  3. the next block to be added to the Tendermint blockchain. The protocol proceeds in rounds, where
  4. each round is a try to reach agreement on the next block. A round starts by having a dedicated
  5. process (called proposer) suggesting to other processes what should be the next block with
  6. the `ProposalMessage`.
  7. The processes respond by voting for a block with `VoteMessage` (there are two kinds of vote
  8. messages, prevote and precommit votes). Note that a proposal message is just a suggestion what the
  9. next block should be; a validator might vote with a `VoteMessage` for a different block. If in some
  10. round, enough number of processes vote for the same block, then this block is committed and later
  11. added to the blockchain. `ProposalMessage` and `VoteMessage` are signed by the private key of the
  12. validator. The internals of the protocol and how it ensures safety and liveness properties are
  13. explained in a forthcoming document.
  14. For efficiency reasons, validators in Tendermint consensus protocol do not agree directly on the
  15. block as the block size is big, i.e., they don't embed the block inside `Proposal` and
  16. `VoteMessage`. Instead, they reach agreement on the `BlockID` (see `BlockID` definition in
  17. [Blockchain](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/blockchain.md#blockid) section) that uniquely identifies each block. The block itself is
  18. disseminated to validator processes using peer-to-peer gossiping protocol. It starts by having a
  19. proposer first splitting a block into a number of block parts, that are then gossiped between
  20. processes using `BlockPartMessage`.
  21. Validators in Tendermint communicate by peer-to-peer gossiping protocol. Each validator is connected
  22. only to a subset of processes called peers. By the gossiping protocol, a validator send to its peers
  23. all needed information (`ProposalMessage`, `VoteMessage` and `BlockPartMessage`) so they can
  24. reach agreement on some block, and also obtain the content of the chosen block (block parts). As
  25. part of the gossiping protocol, processes also send auxiliary messages that inform peers about the
  26. executed steps of the core consensus algorithm (`NewRoundStepMessage` and `CommitStepMessage`), and
  27. also messages that inform peers what votes the process has seen (`HasVoteMessage`,
  28. `VoteSetMaj23Message` and `VoteSetBitsMessage`). These messages are then used in the gossiping
  29. protocol to determine what messages a process should send to its peers.
  30. We now describe the content of each message exchanged during Tendermint consensus protocol.
  31. ## ProposalMessage
  32. ProposalMessage is sent when a new block is proposed. It is a suggestion of what the
  33. next block in the blockchain should be.
  34. ```go
  35. type ProposalMessage struct {
  36. Proposal Proposal
  37. }
  38. ```
  39. ### Proposal
  40. Proposal contains height and round for which this proposal is made, BlockID as a unique identifier
  41. of proposed block, timestamp, and two fields (POLRound and POLBlockID) that are needed for
  42. termination of the consensus. The message is signed by the validator private key.
  43. ```go
  44. type Proposal struct {
  45. Height int64
  46. Round int
  47. Timestamp Time
  48. BlockID BlockID
  49. POLRound int
  50. POLBlockID BlockID
  51. Signature Signature
  52. }
  53. ```
  54. NOTE: In the current version of the Tendermint, the consensus value in proposal is represented with
  55. PartSetHeader, and with BlockID in vote message. It should be aligned as suggested in this spec as
  56. BlockID contains PartSetHeader.
  57. ## VoteMessage
  58. VoteMessage is sent to vote for some block (or to inform others that a process does not vote in the
  59. current round). Vote is defined in the [Blockchain](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/blockchain.md#blockid) section and contains validator's
  60. information (validator address and index), height and round for which the vote is sent, vote type,
  61. blockID if process vote for some block (`nil` otherwise) and a timestamp when the vote is sent. The
  62. message is signed by the validator private key.
  63. ```go
  64. type VoteMessage struct {
  65. Vote Vote
  66. }
  67. ```
  68. ## BlockPartMessage
  69. BlockPartMessage is sent when gossipping a piece of the proposed block. It contains height, round
  70. and the block part.
  71. ```go
  72. type BlockPartMessage struct {
  73. Height int64
  74. Round int
  75. Part Part
  76. }
  77. ```
  78. ## ProposalHeartbeatMessage
  79. ProposalHeartbeatMessage is sent to signal that a node is alive and waiting for transactions
  80. to be able to create a next block proposal.
  81. ```go
  82. type ProposalHeartbeatMessage struct {
  83. Heartbeat Heartbeat
  84. }
  85. ```
  86. ### Heartbeat
  87. Heartbeat contains validator information (address and index),
  88. height, round and sequence number. It is signed by the private key of the validator.
  89. ```go
  90. type Heartbeat struct {
  91. ValidatorAddress []byte
  92. ValidatorIndex int
  93. Height int64
  94. Round int
  95. Sequence int
  96. Signature Signature
  97. }
  98. ```
  99. ## NewRoundStepMessage
  100. NewRoundStepMessage is sent for every step transition during the core consensus algorithm execution.
  101. It is used in the gossip part of the Tendermint protocol to inform peers about a current
  102. height/round/step a process is in.
  103. ```go
  104. type NewRoundStepMessage struct {
  105. Height int64
  106. Round int
  107. Step RoundStepType
  108. SecondsSinceStartTime int
  109. LastCommitRound int
  110. }
  111. ```
  112. ## CommitStepMessage
  113. CommitStepMessage is sent when an agreement on some block is reached. It contains height for which
  114. agreement is reached, block parts header that describes the decided block and is used to obtain all
  115. block parts, and a bit array of the block parts a process currently has, so its peers can know what
  116. parts it is missing so they can send them.
  117. ```go
  118. type CommitStepMessage struct {
  119. Height int64
  120. BlockID BlockID
  121. BlockParts BitArray
  122. }
  123. ```
  124. TODO: We use BlockID instead of BlockPartsHeader (in current implementation) for symmetry.
  125. ## ProposalPOLMessage
  126. ProposalPOLMessage is sent when a previous block is re-proposed.
  127. It is used to inform peers in what round the process learned for this block (ProposalPOLRound),
  128. and what prevotes for the re-proposed block the process has.
  129. ```go
  130. type ProposalPOLMessage struct {
  131. Height int64
  132. ProposalPOLRound int
  133. ProposalPOL BitArray
  134. }
  135. ```
  136. ## HasVoteMessage
  137. HasVoteMessage is sent to indicate that a particular vote has been received. It contains height,
  138. round, vote type and the index of the validator that is the originator of the corresponding vote.
  139. ```go
  140. type HasVoteMessage struct {
  141. Height int64
  142. Round int
  143. Type byte
  144. Index int
  145. }
  146. ```
  147. ## VoteSetMaj23Message
  148. VoteSetMaj23Message is sent to indicate that a process has seen +2/3 votes for some BlockID.
  149. It contains height, round, vote type and the BlockID.
  150. ```go
  151. type VoteSetMaj23Message struct {
  152. Height int64
  153. Round int
  154. Type byte
  155. BlockID BlockID
  156. }
  157. ```
  158. ## VoteSetBitsMessage
  159. VoteSetBitsMessage is sent to communicate the bit-array of votes a process has seen for a given
  160. BlockID. It contains height, round, vote type, BlockID and a bit array of
  161. the votes a process has.
  162. ```go
  163. type VoteSetBitsMessage struct {
  164. Height int64
  165. Round int
  166. Type byte
  167. BlockID BlockID
  168. Votes BitArray
  169. }
  170. ```