Tenderdash Consensus Protocol
This document and its companions specify the Tenderdash consensus protocol
as implemented in internal/consensus and the packages it depends on.
Every non-trivial rule cites the function that implements it. Where the
implementation diverges from the Tendermint algorithm it descends from, the
implementation wins and the divergence is recorded in
Known issues and discrepancies.
Audience: protocol engineers and auditors. Readers are expected to know the Tendermint consensus algorithm (consensus paper) and the ABCI interface (ABCI spec).
Documents
| Document | Content |
|---|---|
| Consensus Protocol (this page) | Scope, terminology, system model, round state, step state machine, invariants |
| Primary flow of a height | The happy path from NewHeight to the next NewHeight, with the ABCI calls it makes |
| Transitions and decision rules | Formal transition table: guards, actions and postconditions of every step action; timeout semantics; vote-driven dispatch; prevote, precommit and proposal-validity decision procedures |
| Alternative flows and edge cases | Missing or invalid proposals, locking, valid-block bookkeeping, round skipping, nil rounds, equivocation, vote extensions, timestamps, empty blocks, non-validators, panics, DoS budgets |
| Proposer liveness and round skipping | From CONSENSUS_VERSION_2: proposer heartbeats while a round waits for transactions, skip votes, round skip certificates, the round after a skip, their parameters and budgets |
| Commit handling | Commits built from local precommits and commits received from peers: verification, parking, candidates, application of a commit, gossip |
| Recovery and synchronisation | WAL, crash recovery, ABCI handshake replay, block-sync handover |
| Known issues and discrepancies | Behaviour that looks like a bug or diverges from the intended algorithm |
Related specifications that this one links to rather than restates:
- Proposer selection — which validator proposes at
(height, round). - Signing — sign bytes, request IDs and double-signing rules for proposals and votes.
- Write-ahead log — WAL file layout and replay.
- Evidence — evidence model for misbehaviour.
- Consensus channel messages — wire format of the messages exchanged.
- ABCI expected behaviour — the ABCI call sequence from the application's point of view.
- Proposer-based timestamps — pointers to current rules and retained historical research; the rules in force are in Proposal timestamps and time rules.
Scope
In scope: the consensus state machine of a single node (validator or full node), the rules that decide what it signs, the interaction with the application over ABCI, and the parts of message exchange that change consensus state. Out of scope: the p2p transport, mempool internals, block sync and state sync (except their handover to consensus), light clients, and the complete DoS-defence design. For operational monitoring, see DoS observability.
Source of truth: the code at the revision this document was written against
(branch dev). Citations use path/file.go and a function name; line
numbers are omitted because they drift.
Terminology
| Term | Definition | Source |
|---|---|---|
Height h | Index of the block being decided. State.LastBlockHeight + 1, or InitialHeight for the first block. | StateData.updateToState in internal/consensus/state_data.go |
Round r | Attempt number within a height, starting at 0. | RoundState.Round in internal/consensus/types/round_state.go |
| Step | Position within a round: one of the RoundStepType values listed in Round steps. | internal/consensus/types/round_state.go |
| Validator set | The members of the active Dash LLMQ quorum: ValidatorSet{Validators, QuorumType, QuorumHash, ThresholdPublicKey, VotingPowerThreshold, HasPublicKeys}. Every validator has voting power DefaultDashVotingPower = 100. | types/validator_set.go |
| Validator / observer | A node whose PrivValidator pro-tx-hash is in the validator set is a validator; any other node is an observer. Observers do not sign and ignore votes (see Non-validators). | StateData.isValidator, Reactor.handleVoteMessage in internal/consensus/reactor.go |
Commit threshold T | Voting power at or above which a vote set is treated as "+2/3". T = ValidatorSet.VotingPowerThreshold when that field is set (> 0), otherwise the LLMQ-type threshold QuorumTypeThresholdVotingPower() (threshold member count × 100). A configured T below the strict floor ⌊2·total/3⌋ + 1 is only warned about (BelowStrictThreshold). | ValidatorSet.QuorumVotingThresholdPower, ValidatorSet.BelowStrictThreshold in types/validator_set.go; warning logged in StateData.updateToState |
Recovery threshold R | Voting power whose BLS signature shares suffice to recover the quorum's threshold signature: QuorumTypeThresholdVotingPower(). It ignores the VotingPowerThreshold override. | ValidatorSet.QuorumTypeThresholdVotingPower in types/validator_set.go |
| "+2/3 any" | A vote set whose total admitted power ≥ T, regardless of which block ids the votes name. | VoteSet.HasTwoThirdsAny in types/vote_set.go |
| "+2/3 majority" / maj23 | A vote set whose votes for one block id (possibly nil) reach T. For precommit sets the majority is additionally recognised only once the threshold signature over the block has been recovered and verified (see Threshold recovery). | VoteSet.TwoThirdsMajority, VoteSet.addVerifiedVote in types/vote_set.go |
| Polka | A +2/3 majority of prevotes for one block id (nil included) in one round. | HeightVoteSet.POLInfo in internal/consensus/types/height_vote_set.go |
| POLRound | The round whose polka a proposal claims as justification; -1 when the proposal claims none. | types.Proposal.POLRound |
| BlockID | (Hash, PartSetHeader, StateID). Nil block id = all three empty. | types/block.go, types/block_meta.go |
| StateID | Hash of {AppVersion, Height, AppHash, CoreChainLockedHeight, Time} of the block header; the app hash is the state after executing that block (same-block execution). | Header.StateID in types/block.go |
| Commit | (Height, Round, BlockID, QuorumHash, ThresholdBlockSignature, ThresholdVoteExtensions): a single aggregate BLS threshold signature plus one threshold signature per threshold-recoverable vote extension. There are no per-validator signatures in a commit. | types.Commit in types/block.go |
| Locked block / round | The block the node precommitted most recently and the round it did so; -1/nil when none. | RoundState.LockedRound/LockedBlock |
| Valid block / round | The most recent block (and round) for which the node saw a polka in a round ≥ any previous one. | RoundState.ValidRound/ValidBlock |
| CurrentRoundState | The application's answer to the latest PrepareProposal/ProcessProposal for the block held in ProposalBlock, tagged with the round it was processed for. | RoundState.CurrentRoundState, RoundState.ProcessedBlockID; processedFor in internal/consensus/block_executor.go |
| Round skip certificate | A quorum threshold signature recovered from the skip votes of validators holding R, proving that they stopped hearing from the proposer of (h, r) while waiting for transactions; moves a node to r + 1. CONSENSUS_VERSION_2 only. | types.RoundSkipCertificate in types/round_skip.go; Proposer liveness |
| Parked commit | A verified commit for the current height whose block has not yet been assembled (RoundState.Commit != nil). | StateData.adoptCommit in internal/consensus/state_data.go |
| Timely | A proposal whose receive time lies within [ts − Precision, ts + MessageDelay·2^⌊round/10⌋ + Precision] of its timestamp ts. | checkTimely in types/validation.go |
Throughout, rs denotes the node's RoundState and state the committed
sm.State (state as of height h − 1).
System model as enforced by the code
- Single writer.
State.receiveRoutine(internal/consensus/state.go) is the only goroutine that mutatesRoundState. Itselects over five inputs: transactions becoming available in the mempool (txNotifier.TxsAvailable()), messages (msgInfoQueue.read(): the node's own proposal/votes on an internal queue, peers' messages on per-peer lanes), timer expiries (timeoutTicker.Chan()), proposer-silence reports (proposerLiveness.silent()) and signed round skip votes (roundSkipSigner.signed()). Go'sselectpicks randomly among ready cases, so there is no ordering guarantee between a timeout and a message that are both ready. - Actions and guards. Every transition is an
ActionHandlerregistered in theController(internal/consensus/state_controller.go) and invoked viaController.Dispatch. EachEnter*action begins with a staleness guard on(height, round, step); a dispatch that fails its guard is a silent no-op. Dispatches nest: an action may dispatch further actions before returning. - Copy-on-read state. Handlers work on a
StateDatacopy taken fromStateDataStoreand persist it withStateData.Save/StateDataStore.Update, which checks an optimistic version counter (StateDataStore.update). A version mismatch is only logged. - Equal voting power. Every validator has power 100; quorum arithmetic is therefore a member count × 100.
- Threshold signatures. Validators sign with BLS shares of the quorum key.
A commit is one recovered threshold signature, verifiable against
ValidatorSet.ThresholdPublicKeyalone. See Signing. - Same-block execution.
Header.AppHashis the application state after executing the block's own transactions; consensus validates it against theProcessProposalresult before voting (BlockExecutor.ValidateBlockWithRoundStateininternal/state/execution.go). - Safety assumption. Safety follows the Tendermint argument only while
T ≥ ⌊2·total/3⌋ + 1. The code does not enforce this: a lowerVotingPowerThreshold(or an LLMQ type with a 50 % threshold) is accepted with a warning (ValidatorSet.BelowStrictThreshold). - Time. The block timestamp is the proposer's local clock
(
State.makeBlockTimeininternal/state/state.go; genesis time for the initial height). Receivers judge timeliness withSynchronyParams(Precisiondefault 505 ms,MessageDelaydefault 12 s,types/params.go). There is no median/BFT time.
Round state
RoundState (internal/consensus/types/round_state.go) holds, per node:
| Field | Meaning |
|---|---|
Height, Round, Step, StartTime | Position in the protocol; StartTime is when round 0 of this height may start (= CommitTime of the previous height). |
CommitTime, CommitRound | When and in which round +2/3 precommits for a block were observed locally; CommitRound = -1 until then. |
Validators, LastValidators, ProposerSelector | Validator set for this height, for the previous height, and the proposer-selection strategy. |
Proposal, ProposalReceiveTime, ProposalBlock, ProposalBlockParts | The accepted proposal of the current round, when it was received, and the block being assembled from parts. |
LockedRound, LockedBlock, LockedBlockParts | Lock. |
ValidRound, ValidBlock, ValidBlockParts, ValidBlockRecvTime | Valid block. ValidBlockRecvTime is the receive time used when re-proposing. |
Commit | Parked commit (see Commit handling). |
Votes | HeightVoteSet: prevote and precommit VoteSets for rounds 0..Round+1 plus up to two catch-up rounds per validator. |
LastCommit | The commit of height h − 1, included in the next proposed block. There is no LastCommit vote set: late precommits for h − 1 are dropped. |
TriggeredTimeoutPrecommit | Whether the precommit-wait timeout was already scheduled for this round. |
RoundSkip | Round skip certificate for the highest skipped round of this height; kept for peers still in that round even after the node moved past it. |
TxsReported | Whether the mempool reported transactions at this height (it does so once per height). |
ProposeNextBlockImmediately | Hint from ResponseFinalizeBlock.propose_next_block_immediately of the previous height; consumed once, not persisted. |
CurrentRoundState, ProcessedBlockID | Latest application result for ProposalBlock (see Terminology). |
StateData.updateToState re-initialises Height, Validators,
LastValidators, LastCommit, ProposerSelector and StartTime for the
new height and resets every proposal, lock, valid-block, commit,
round-skip, vote and flag field. CurrentRoundState/ProcessedBlockID are left untouched; they
are compared against the new height's block by processedFor. Within a
height LockedRound/Block and ValidRound/Block are never reset; Commit
is cleared only when a parked commit is rejected (selectParkedCommit,
TryAddCommitAction.Execute).
Round steps
RoundStepType is an ordered enum (internal/consensus/types/round_state.go):
| Value | Step | Entered by |
|---|---|---|
| 1 | NewHeight | StateData.updateToState (after a block is applied, after block sync, at start) |
| 2 | NewRound | EnterNewRoundAction |
| 3 | Propose | EnterProposeAction |
| 4 | Prevote | EnterPrevoteAction |
| 5 | PrevoteWait | EnterPrevoteWaitAction |
| 6 | Precommit | EnterPrecommitAction |
| 7 | PrecommitWait | never assigned — EnterPrecommitWaitAction sets TriggeredTimeoutPrecommit but leaves Step at Precommit (see Known issues). The value is still used as the timeout's step and in peer-state comparisons. |
| 8 | ApplyCommit | EnterCommitAction, AddCommitAction |
stateDiagram-v2
direction TB
[*] --> NewHeight : updateToState (height h, round 0)
NewHeight --> NewRound : tock NewHeight / EnterNewRound(h,0)
NewRound --> NewRound : proposer waits for clock > LastBlockTime (NewRound tock rescheduled)
NewRound --> Propose : EnterPropose (immediately, or after txs available / empty-block interval / proposal or prevotes while waiting)
Propose --> Prevote : proposal + block (+ POL) complete, or tock Propose
Prevote --> PrevoteWait : prevotes reach +2/3 any without a usable majority
Prevote --> Precommit : polka (block held or nil)
PrevoteWait --> Precommit : polka, or tock PrevoteWait
Precommit --> Precommit : precommits reach +2/3 any (TriggeredTimeoutPrecommit, PrecommitWait tock scheduled)
Precommit --> NewRound : tock PrecommitWait / EnterNewRound(h, r+1)
Precommit --> ApplyCommit : +2/3 precommits for a block (threshold signature recovered)
state "any step" as Any
Any --> NewRound : +2/3 any prevotes or precommits at round r' > r (round skip)
Any --> NewRound : RoundSkipCertificate for round r' ≥ r, before ApplyCommit / EnterNewRound(h, r'+1)
Any --> ApplyCommit : verified CommitMessage for height h
ApplyCommit --> NewHeight : block applied (height h+1)
ApplyCommit --> ApplyCommit : waiting for block parts, or application rejected own commit
The precise guards of every arrow are in Transitions and decision rules.
Invariants
The following hold by construction of the code; each names the function that preserves it.
- Lock monotonicity.
LockedRoundonly increases within a height. It is written byStateData.updateLockedBlock(first lock) and by the relock branch ofEnterPrecommitAction.Execute(LockedRound = round), both at the current round, and reset to-1only byStateData.updateToState. There is no unlock: a nil polka at a later round does not clear the lock (TestStateLock_POLDoesNotUnlockininternal/consensus/state_test.go). - Lock implies polka. A node locks on block
Bat roundronly afterPrevotes(r).TwoThirdsMajority() == Band only whenBis this round's proposal block (EnterPrecommitAction.Execute). - Precommit implies processed. A non-nil precommit for
Bat roundris signed only afterProcessProposal(B, r)succeeded andValidateBlockWithRoundStatepassed for this round (blockExecutor.mustEnsureProcess,blockExecutor.mustValidatecalled fromEnterPrecommitAction.Execute). ConsequentlyExtendVoteis asked for the round the application processed last. - Valid-round monotonicity.
ValidRoundis set to the current round byStateData.updateValidBlock; callers only invoke it whenValidRound < Round(addVoteUpdateValidBlockMw,ProposalCompletedAction) or from the lock branch at the current round. - One proposal slot per round.
Proposaler.Setignores any proposal whilers.Proposal != nil, so the first proposal that verifies holds the slot. The slot is freed within the round only bydropStaleProposal(StateData.retargetTo), when authenticated votes name another block: a current-round polka (addVoteUpdateValidBlockMw), a polka at precommit time for a block the node does not hold (EnterPrecommitAction.Execute), or a commit (StateData.adoptCommit,proposalUpdater.updateStateData). A proposal for the retargeted block — and only that block, sinceSetrejects aBlockIDthat differs from the assembled block's — can then be accepted in the same round. A proposal that fails verification never occupies the slot. - Application result currency.
CurrentRoundStatedescribes the application's latest successfulProcessProposal/PrepareProposalforProposalBlock; a result for another round or block is never reused (blockExecutor.ensureProcess,processedFor,ensureOwnRound). - Commit = recovered threshold signature.
VoteSet.MakeCommitpanics unlessmaj23is set andthresholdBlockSigwas recovered; for precommit setsmaj23is set only after recovery and verification succeed (VoteSet.addVerifiedVote,VoteSet.recoverThresholdSignsAndVerify). - Commit matches held block. A commit is applied only when its
BlockID(hash, part-set header and state id) equals that of the block held (verifyCommitBlockininternal/consensus/state_try_add_commit.go, called by bothprepareCommitForApplyandApplyCommitAction.Execute). - WAL before signature. The WAL is flushed and fsynced before the node
signs a vote:
voteSigner.signVotereturns on aFlushAndSyncfailure and no vote is signed. On the proposal path the sync is best-effort:EnterProposeAction.Executelogs aFlushAndSyncfailure and still callsProposaler.Create, so a proposal may be signed over an unsynced WAL.EndHeightMessageis fsynced after the block is saved and beforeFinalizeBlock(ApplyCommitAction.Execute). - Height votes only. Votes and commits for any height other than
rs.Heightare dropped (addVoteValidateVoteMw,StateData.readyToApplyCommit).
Threshold recovery
VoteSet.addVerifiedVote (types/vote_set.go) sets maj23 for a block id
when the power behind it reaches T. For precommit sets it then calls
recoverThresholdSignsAndVerify:
- With a single validator the vote's own signatures are used.
- Otherwise
canonicalVoteExtensionGrouppicks the group of votes that carry an identical ordered vector of threshold-recoverable extensions and whose power is≥ R(ties broken by lexicographic order of the group identity, empty vector first). NewSignsRecoverer(...).Recover()recovers the block threshold signature from all votes for the block and the extension threshold signatures from the canonical group's votes.- The recovered signatures are verified against
ValidatorSet.ThresholdPublicKeyover the canonical vote's sign data.
If any step fails, maj23 and the recovered signatures are rolled back and
the attempt is repeated when a later vote makes the block cross T again or
makes an extension group cross R. Externally, therefore, a precommit
majority is observable only once a verifiable commit can be built from it.
Prevote sets set maj23 at T without recovery.
Timeouts and consensus parameters
Timeouts come from ConsensusParams.Timeout of the committed state (changes
proposed in block h apply from h + 1, CurrentRoundState in
internal/state/current_round_state.go), with zero fields replaced by defaults
(TimeoutParams.TimeoutParamsOrDefaults, types/params.go):
| Parameter | Default | Used for |
|---|---|---|
Propose | 3000 ms | proposeTimeout(r) = Propose + ProposeDelta·r |
ProposeDelta | 500 ms | |
Vote | 1000 ms | voteTimeout(r) = Vote + VoteDelta·r (prevote wait, precommit wait, and the signing deadline of a non-nil precommit) |
VoteDelta | 500 ms | |
Synchrony.Precision | 505 ms | Timeliness window |
Synchrony.MessageDelay | 12 s | Timeliness window; doubled every 10 rounds |
ProposerHeartbeat | 1 s, derived when only ProposerSilence is set | Heartbeat interval of the proposer of a waiting round (CONSENSUS_VERSION_2) |
ProposerSilence | 5 s, derived when only ProposerHeartbeat is set | ProposerSilenceTimeout(r) = ProposerSilence + ProposerHeartbeat·r; see Parameters |
Per-node Unsafe*TimeoutOverride settings in config.ConsensusConfig replace
the corresponding parameter locally (StateData.proposeTimeout,
StateData.voteTimeout); they desynchronise timing between nodes and are not
part of the protocol. There is no commit timeout: StartTime of the next
height equals CommitTime, so round 0 starts as soon as the block is applied
(StateData.updateToState, roundScheduler.ScheduleRound0). The
unsafe-commit-timeout-override / unsafe-bypass-commit-timeout-override
settings are deprecated no-ops that only produce a warning
(config.ConsensusConfig).
Escalation with the round is linear, not exponential.