Alternative flows and edge cases
Each section states the situation, the behaviour the code implements, and the implementing function. Commit-related flows are in Commit handling; crash recovery and sync handover in Recovery and synchronisation.
Proposal missing, late or invalid
Proposer silent or slow
timeoutPropose (proposeTimeout(r)) fires → EnterPrevote.
isValidForPrevote fails with errPrevoteProposalBlockNil → nil prevote,
no ABCI call (prevoter.Do). When every validator prevotes nil, the +2/3
nil majority dispatches EnterPrecommit directly — no PrevoteWait, no
voteTimeout(r) (addVoteDispatchPrevoteMw: TwoThirdsMajority() returns
the nil block id, and blockID.IsNil() satisfies the precommit condition) →
nil precommit → +2/3 nil precommits → EnterPrecommitWait → voteTimeout(r)
→ EnterNewRound(r + 1). EnterPrevoteWait is reached only when the
prevotes hold +2/3-any without a majority (some validators did receive
and prevote the block), in which case voteTimeout(r) precedes
EnterPrecommit.
sequenceDiagram
participant T as timeoutTicker
participant V as Validator
participant N as Other validators
T->>V: tock Propose(h,r)
V->>V: EnterPrevote: no block → prevote nil
V-->>N: prevote nil
N-->>V: prevotes nil
V->>V: +2/3 nil prevotes → EnterPrecommit: polka nil → precommit nil
N-->>V: precommits nil
V->>V: maj23 nil → EnterPrecommitWait (voteTimeout r)
T->>V: tock PrecommitWait(h,r)
V->>V: EnterPrecommit (no-op) → EnterNewRound(h,r+1) → EnterPropose(h,r+1)
A proposer that is silent while its round waits for transactions is handled
before the propose step on CONSENSUS_VERSION_2 chains: validators that stop
hearing its heartbeats skip the round with a round skip certificate
(Proposer liveness and round skipping).
Proposal arrives after the node prevoted
Proposaler.Set has no step check, so the proposal is still stored and parts
are still collected. ProposalCompletedAction.Execute enters prevote only
while step ≤ Propose, so the node does not prevote it. The block can still:
- become
ValidBlockif a polka for it exists or forms (ProposalCompletedAction.Execute,addVoteUpdateValidBlockMw); - be precommitted if a polka for it forms while the node is in
Prevote(addVoteDispatchPrevoteMw→EnterPrecommit; rule C-Lock); - be re-proposed in a later round as
ValidBlock.
Proposal for another height or round
Ignored silently (Proposaler.Set). Block parts for another round of the
current height are accepted into the current part set when their proofs match
its header ("blocks might be reused", addProposalBlockPart); parts for
another height are ignored; parts when no part set is expected are ignored.
blockPartMessageHandler swallows errors for parts whose round differs from
the current one.
Invalid POLRound, bad signature, wrong proposer
ErrInvalidProposalPOLRound, ErrInvalidProposalSignature (counted in
ProposalVerifyFailures), see
Proposal acceptance.
A proposal signed by a validator other than proposer(h, r) fails the
signature check because the signature is verified against the expected
proposer's key only. The round proceeds as if no proposal had been received.
Proposal contradicts the round's target block
Refused with ErrInvalidProposalForCommit (a verified commit for the same
(h, r) names another block), ErrInvalidProposalForPartSet (a part set is
already being collected under another header), or ErrInvalidProposalBlockID
/ ErrInvalidProposalCoreHeight (a block is already assembled and differs)
(roundStateRefusal, Proposaler.Set). Rationale: a part-set header is a
Merkle root over exactly one block's bytes, so a disagreeing proposal could
never be acted on and would make the node reject the parts it is waiting for.
Block id mismatch discovered when the block completes
If the assembled block's hash or part-set header differ from the proposal's,
the proposal is dropped (rs.Proposal = nil) but the block is kept
(addProposalBlockPart). The node later prevotes nil
(errPrevoteProposalNil). The fields not covered by the proposal signature
(CoreChainLockedHeight, BlockID.StateID) are instead taken from the
authenticated block bytes.
Oversized or malformed block
Accumulated parts above ConsensusParams.Block.MaxBytes → error; an
undecodable block → error (addProposalBlockPart). Parts with invalid Merkle
proofs are charged to the sender's blockPartProofBudget and dropped
silently once it is exhausted (internal/consensus/block_part_budget.go).
Block is invalid, application rejects it, or the header does not match
BlockExecutor.ProcessProposal first validates the block against the
committed state (ValidateBlock); a block that fails is never sent to the
application. That failure (sm.ErrInvalidBlock), the application returning
REJECT (sm.ErrBlockRejected), or a well-formed ACCEPT whose contents
disagree with the block — header mismatch / invalid LastCommit
(sm.ErrInvalidBlock) — → nil prevote (prevoter.handleError). A failed ProcessProposal clears
CurrentRoundState, so no round counts as processed until a later call
succeeds (blockExecutor.ensureProcess). Any other error panics
the node: transport failure, UNKNOWN status, or a malformed response — an
AppHash of the wrong size fails ResponseProcessProposal.Validate and
tx_results not matching the transactions fails validateExecTxResults,
both returned by BlockExecutor.ProcessProposal as plain errors, not as
ErrInvalidBlock. The same block
reaching EnterPrecommit via a polka would call mustEnsureProcess, which
panics on failure — a node that could not process a block cannot have a
polka-matching proposal block for it unless the application is
non-deterministic.
During WAL replay a mismatch between a stored block's AppHash and the
application's result stops the node (checkAppHashEqualsOneFromBlock in
internal/consensus/replayer.go).
Proposal timestamp differs from block time
Nil prevote (errPrevoteTimestampNotEqual) and nil precommit
(rule C-Timestamp).
Locking
The lock is defined by LockedRound/LockedBlock and the rules
P-Lock-NoPOL, P-Lock-POL
and C-Lock, C-Relock, C-LockedNotProposed.
| Situation | Behaviour | Evidence |
|---|---|---|
Locked on B at r; round r + k proposes B with POLRound ≥ LockedRound or without POL | Prevote B (lock match) | prevoter.checkProposalBlock, checkPrevoteMaj23; TestStateLock_POLRelock |
Locked on B; round r + k proposes C ≠ B with POLRound = -1 | Prevote nil (ProcessProposal still runs for C) | TestStateLock_PrevoteNilWhenLockedAndDifferentProposal |
Locked on B; proposal C with POLRound = p ≥ LockedRound and a polka for C at p | Prevote C; if a polka for C forms this round → lock moves to C (updateLockedBlock) | TestStateLock_POLUpdateLock |
Locked on B; proposal C with POLRound = p < LockedRound | Prevote nil | checkPrevoteMaj23 |
| Polka for nil in a later round | Lock unchanged — no unlock | TestStateLock_POLDoesNotUnlock |
Polka for B (the locked block) in round r + k but no proposal for B in that round | Precommit nil, lock unchanged | rule C-LockedNotProposed; TestStateLock_MissingProposalWhenPOLSeenDoesNotUpdateLock |
Polka for B in round r + k and proposal for B | Relock: LockedRound = r + k, precommit B after re-processing for r + k | TestStateLock_POLRelock |
Proposal for an old block (POLRound pointing at a polka for another block) | Not prevoted, not locked | TestStateLock_DoesNotLockOnOldProposal |
Liveness consequence of C-LockedNotProposed: when a round's proposer is slow
or faulty, validators locked on B do not relock even if the other
validators prevote B; the network must wait for a later proposer to
re-propose B with POLRound set.
Valid-block bookkeeping
StateData.updateValidBlock sets ValidRound = Round, and when the block
differs from the current ValidBlock, ValidBlock = ProposalBlock,
ValidBlockParts, and ValidBlockRecvTime = ProposalReceiveTime when the
proposal names this block, else now. It is called from:
addVoteUpdateValidBlockMw: a prevote completes a polka for non-nilBin the current round withValidRound < Round, and the node holdsB. Whether or not it holdsB,retargetTo(B, polka)then drops a proposal for another block, replaces the part set unless its header isB's, and aValidBlockevent is published so peers sendB's parts (NewValidBlockMessage).ProposalCompletedAction.Execute: the block completes while a polka for it already exists in the current round.EnterPrecommitAction.Execute: after a first lock.
ValidRound/ValidBlock are never reset within a height and survive
EnterNewRound.
Re-proposal. Proposaler.Create reuses ValidBlock iff
checkValidBlock: at InitialHeight its time equals the genesis time;
otherwise ValidBlock.IsTimely(ValidBlockRecvTime, SynchronyParams, ValidRound).
A re-proposal keeps the original header (proposer, time) and carries
POLRound = ValidRound. Receivers skip the timeliness check for a block that
is their own ValidBlock (isValidForPrevote) and skip the proposer check
when POLRound ≥ 0. When ValidBlock is not timely a fresh block is
built and proposed with POLRound = -1, so receivers judge it like any new
proposal (timeliness, proposer check, rule P-Lock-NoPOL). A validator locked
on another block prevotes nil for it; see
Known issues.
Round skipping and nil rounds
- Future-round prevotes.
+2/3-any prevotes atvote.Round > r→EnterNewRound(vote.Round)(addVoteDispatchPrevoteMw). The node skips the intermediate rounds without voting in them. - Future-round precommits.
+2/3-any precommits without a majority atvote.Round ≥ r→EnterNewRound(vote.Round)+EnterPrecommitWait(addVoteDispatchPrecommitMw); the node then waitsvoteTimeoutbeforer + 1. A precommit majority for a block at any round (including a round below the current one) →EnterCommitwith that round (TestCommitFromPreviousRound). - Future-round commit. If its block is already held, a verified
CommitMessageforcommit.Round > ris checked against the block and application before advancing the round; rejection does not move the round. If the block is absent, signature verification can park the commit and advance to its round before the later application check. See Commit handling. - Round skip certificate (
CONSENSUS_VERSION_2). A verified certificate for roundr' ≥ r→EnterNewRound(r' + 1), unless the node is atApplyCommit; one forr' < ris only kept and gossiped (AddRoundSkipCertificateAction). See Proposer liveness and round skipping. - Round bookkeeping.
HeightVoteSetkeeps vote sets for rounds0 .. Round + 1(SetRound(round + 1)inEnterNewRoundAction) plus at most two "catch-up" rounds per validator pro-tx-hash (HeightVoteSet.addVote,ErrGotVoteFromUnwantedRound). Vote sets are never released within a height. - All-nil round. Nil polka → nil precommit → nil precommit majority →
EnterPrecommitWait— the node still waitsvoteTimeout(r)even though the round is decided — →EnterNewRound(r + 1). - Idempotence.
TriggeredTimeoutPrecommitmakesEnterPrecommitWaitrun once per round; the step guards do the same for the other actions. - What survives a round change.
LockedBlock,ValidBlock, parkedCommit, and all vote sets;Proposaland the proposal block/parts are cleared unless a commit is parked (EnterNewRoundAction.Execute).
Equivocation, duplicates and conflicting votes
Implemented in VoteSet.addVote / addVerifiedVote (types/vote_set.go)
and addVoteErrorMw (internal/consensus/state_add_vote.go).
- Identical vote (same validator, block key and block signature): not added, no error.
- Same validator and block key, different signature:
ErrVoteNonDeterministicSignature(BLS signatures are deterministic; logged at error level). - Same validator, different block id: the second vote is recorded only in
votesByBlockwhen some peer claimed +2/3 for that block id (peerMaj23, set byVoteSetMaj23Message→VoteSet.SetPeerMaj23); it replaces the first invotesonly if it matchesmaj23. The pair is returned asErrVoteConflictingVotesand reported to the evidence pool (evidencePool.ReportConflictingVotes) unless the key is the node's own (logged: "did you unsafe_reset a validator?") or no private validator is set (ErrPrivValidatorNotSet). The evidence pool stores it unverified; it reaches the application asMisbehavioronly if a proposer includes it (evpool.PendingEvidenceinCreateProposalBlock). - Conflicting proposals by the same proposer: the first valid one is
kept and the second ignored while the first occupies
rs.Proposal; a current-round polka or a commit for the second block drops the first (StateData.retargetTo→dropStaleProposal) and the second is then accepted (invariant 5). No evidence is produced.
Vote extensions
- The node normally asks ABCI
ExtendVotewhen signing a non-nil precommit (voteSigner.signVote). The one exception signs nothing: whenVerifyVoteExtensionrejects a commit's extensions, no expectation is known for its block and round, and the block is processed forcommit.Round,blockExecutor.verifyCommitExtensionscallsExtendVotefor that block and round to learn the expected vector. This can happen on any node, validator or not (Parked commit). On both paths the response must parse (NewVoteExtensionsFromABCIExtended); otherwise the node panics. - Supported extension types (
types/vote_extension.go):THRESHOLD_RECOVERandTHRESHOLD_RECOVER_RAW(threshold-recoverable;RAWmay carry an application-supplied sign request id that binds no height or round).DEFAULTexists in the enum but is not supported:NewVoteExtensionsFromABCIExtendedrejects it in anExtendVoteresponse (ErrUnsupportedVoteExtensionType), andVoteExtension.Validate(proto/tendermint/types/dash.go) rejects it in a peer's vote (Vote.ValidateBasic). A prevote or nil precommit carrying extensions failsVote.ValidateBasic. - Each peer precommit's extension signatures are verified after the block
signature (
types.VerifyVoteSignatures), then ABCIVerifyVoteExtensionis called with the validator's pro-tx-hash. A rejected vote is not stored (addVoteVerifyVoteExtensionMw). Own votes skip the ABCI call. - At most
MaxVoteExtensions = 32extensions are accepted on verification paths (types/quorum_sign_data.go); the signing path is not capped. - The commit carries only the threshold-recovered extensions of the
canonical group (Threshold recovery).
Before a block is saved the application sees them once more as a single
VerifyVoteExtensionwith an emptyValidatorProTxHash(sm.VerifyCommitExtensions).
Proposal timestamps and time rules
- The proposer sets
Header.Time = now(genesis time atInitialHeight,State.makeBlockTime). Before proposing, a proposer whose clock is behindstate.LastBlockTimewaits for the difference (EnterProposeAction.Execute,proposerWaitTime). - Validity:
Time > state.LastBlockTimeforh > InitialHeight,Time ≥ genesisatInitialHeight(validateBlock). - Timeliness is checked only at prevote time, against the proposal's
receive time (
ProposalReceiveTime= enqueue time of theProposalMessage,chanMsgSender.send), with the window ofcheckTimely(rule P-Timely). It is skipped for a block that is the node'sValidBlock, so re-proposals of an already polka'd block are not re-judged. In replay mode the receive time is the time of the proposal's WAL entry, and only a proposal received too early fails. The entry is never earlier than the receipt, so replay refuses only what the node refused when it received the proposal, not always all of it. That time also becomesValidBlockRecvTimefor a block made valid during replay, which decides whether the node re-proposes it after a restart (Proposaler.checkValidBlock), and feedsProposalTimestampDifference. - Timeliness governs re-proposal (
Proposaler.checkValidBlock). - Metric
ProposalTimestampDifference{is_timely}is recorded for proposals withPOLRound = -1(Proposaler.proposalTimestampDifferenceMetric).
Mempool and empty blocks
EnterNewRoundAction.Execute waits for transactions when
WaitForTxs() = ¬CreateEmptyBlocks ∨ CreateEmptyBlocksInterval > 0, at
round 0 or in a round entered on a round skip certificate that satisfies
StateData.waitsAfterRoundSkip
(The round after a skip),
above InitialHeight, unless ProposeNextBlockImmediately
(set from ResponseFinalizeBlock.propose_next_block_immediately of the
previous height by ApplyCommitAction.Execute; consumed by the next
updateToState; not persisted, so a restart falls back to the configured
wait).
State.handleTxsAvailable records the report in TxsReported (the mempool
reports once per height) and acts only at round 0 or in a round that may wait
after a round skip (StateData.mayWaitAfterRoundSkip): at step NewHeight
(and not at InitialHeight) it schedules a NewRound tock for
StartTime − now + 1 ms; at step NewRound it dispatches EnterPropose.
With CreateEmptyBlocksInterval > 0 the interval tock calls EnterPropose
even without transactions (empty block); in a round after a skip the interval
counts from StartTime. Other rounds ≥ 1 never wait. On
CONSENSUS_VERSION_2 chains a proposal or prevotes can also end the wait
(When it applies).
Validator-set and parameter changes
- Changes come from the application's
ValidatorSetUpdatein thePrepareProposal/ProcessProposalresponse and are reflected in the header'sNextValidatorsHash, which every validator checks against its own application's answer (ValidateBlockWithRoundState). With an unchangedQuorumHashthe update is applied as a change set; with a newQuorumHashthe new set replaces the old one (CurrentRoundState.valsetUpdateininternal/state/current_round_state.go). State.UpdatemakesValidators ← NextValidators,LastValidators ← Validators; the new set votes from heighth + 1(updateToStatebuilds the nextHeightVoteSetfrom it and logs "Updating validators" when the quorum hash or threshold changes).- Consensus parameters (timeouts, synchrony, block limits, proposer-selection
version) proposed in block
htake effect ath + 1(LastHeightConsensusParamsChanged). - Proposer selection version is
ConsensusParams.Version.ConsensusVersion(Proposer selection); version 2 also enables proposer liveness.
Core chain locks
- Header fields:
CoreChainLockedHeight; optionalCoreChainLockin the block (andCoreChainLockUpdatein the proposal, not signed). ValidateBlockChainLock(prevote) andvalidateCoreChainLock(validateBlock, before the application call): with a lock, the header height equals the lock's and exceedsstate.LastCoreChainLockedBlockHeight; without one, it equals it.Proposaler.Setrejectsproposal.CoreChainLockedHeightbelow the committed height; after the block completes the proposal's value is overwritten from the block.state.LastCoreChainLockedBlockHeightadvances only when the block carries aCoreChainLock(CurrentRoundState.UpdateState).
Non-validators and signer problems
- Observers (node not in
Validators): the reactor drops incomingVotemessages (Reactor.handleVoteMessage); the consensus state still runsEnter*actions on timeouts, butvoteSigner.signAddVotereturns without signing (!Validators.HasProTxHash(own)). Observers progress to the next height only throughCommitMessages and block parts (Commit handling). Peers gossip proposals, votes andVoteSetMaj23only to validator peers, and block parts to non-validators once they announce a commit (gossip_handlers.go). - No private validator (
privValidator.IsZero()): no votes (ErrPrivValidatorNotSetlogged);blockExecutor.createfails with "cannot create proposal block on non-validator", so a proposer without a key is silent and the round times out. - Validator set without public keys (
HasPublicKeys = false):HeightVoteSet.addRoundcreates no vote sets andaddVotedrops every vote; proposals can only be accepted when a verified commit for the same(h, r)names the same block (Proposaler.verifyProposalForNonValidatorSet). - Signing failure (
PrivValidator.SignVote/SignProposalerror or deadline): logged; no vote/proposal and no retry within the step (voteSigner.signAddVote,Proposaler.Create). A failed round skip vote is retried after another silence timeout. - Remote signers (socket, gRPC) cannot sign proposer heartbeats or round
skip votes (
RemoteSignerError501,types.ErrSigningNotSupported): a validator using one sends neither, so its waiting rounds are skipped (Signers). - Observers and liveness messages: a node without the validators' key shares neither verifies nor relays heartbeats and skip votes; it verifies and applies round skip certificates against the quorum public key.
- Block sync just finished: proposing is suppressed until the node has
passed the handover target height or 10 minutes elapsed
(
catchupTracker.mayPropose,maxCatchupSuppression); voting is not. - WAL replay: the node never proposes (
EnterProposeAction.Execute,replayMode).
Panics that halt the node
State.receiveRoutine re-panics any panic from a handler except
autofile.ErrAutoFileClosed and panics during context cancellation, so the
following stop the node (liveness-relevant for operators):
| Trigger | Function |
|---|---|
WAL WriteSync failure for own messages or EndHeightMessage | walMiddleware, ApplyCommitAction.Execute |
PrepareProposal error | blockExecutor.create |
ProcessProposal unknown error at prevote; any failure in mustEnsureProcess (precommit, commit, apply) | prevoter.handleError, blockExecutor.mustEnsureProcess |
Validation failure after a successful ProcessProposal | blockExecutor.mustValidate |
ExtendVote / VerifyVoteExtension transport error or invalid extension | BlockExecutor.ExtendVote, BlockExecutor.VerifyVoteExtension |
FinalizeBlock failure | ApplyCommitAction.Execute |
| ABCI client stopped during commit verification | verifyProcessedCommit |
Internal invariant violations: EnterPrevoteWait/EnterPrecommitWait without +2/3-any, EnterCommit/finalizeCommit without a majority or without the block, POLInfo round below the current, updateToState height mismatch, non-monotonic HeightVoteSet.SetRound, proposer-selector construction failure | respective Execute functions, StateData.updateToState, HeightVoteSet.SetRound |
Errors from message handlers invoked by the reactor are recovered and
logged (Reactor.handleMessage), not panicked.
Rate limits and budgets that change protocol timing
These mechanisms never change what a node signs, but they decide whether a message is processed at all (dropped messages are local decisions, not peer faults, unless stated). For operational monitoring, see DoS observability.
- Reactor admission (
internal/consensus/reactor.go,message_cost.go): per-peer token buckets on the vote channel (cost 1 per vote plus one per extension for non-nil precommits; 1 + extensions per commit), the data channel (proposals weigh more than parts) and the state channel;VoteSetMaj23answers are deduplicated (PeerState.ShouldAnswerVoteSetMaj23). Over budget → silent drop. - Peer lanes (
internal/consensus/peer_lanes.go): one FIFO per peer (laneCapacity = 512messages, 64 MiB aggregate), served round-robin by verification cost. The node's own messages bypass lanes via the internal queue (chanMsgSender.send). - Verification budget (
internal/consensus/verification_budget.go,config.VerificationRateLimit): a global BLS-verification rate; a message waits until its full cost is affordable, andverificationBudgetMiddlewaredrops what cannot be afforded. It is the outermost middleware so a dropped message is not written to the WAL.ErrVerificationBudgetExhaustednever evicts a peer (isPeerFloodableError). - Block-part proof budget (
block_part_budget.go): per-peer allowance for parts whose Merkle proof fails. - Liveness messages (
CONSENSUS_VERSION_2): heartbeats, round skip votes and certificates pay extra state-channel tokens only when new, go through the peer lanes and the verification budget, and are sent through a bounded reactor outbox; heartbeats are paced per round (Message admission and budgets). - Bounded memory per height: commit candidate slots (one per peer),
commitExpectations,MaxVoteExtensions,HeightVoteSetcatch-up rounds,maxPeerMaj23sclaims per vote set.
Under load a precommit carrying many extensions can wait in a lane for seconds, which is within the propose timeout but may exceed the vote timeout.