Commit handling
A commit for height h is (Height, Round, BlockID, QuorumHash, ThresholdBlockSignature, ThresholdVoteExtensions) (types.Commit). A node
obtains one in two ways:
- locally, from its own precommit vote set once the threshold signature
is recovered (
VoteSet.MakeCommit); - from a peer or the WAL, as a
CommitMessage.
In both cases the block must be held, processed by the application for the commit's round, validated, and its extension vector accepted by the application before it is saved and finalized.
Commit verification
ValidatorSet.verifyCommit (types/validator_set.go) checks:
commit.Height == heightandcommit.BlockID == blockID(hash, part-set header, state id);commit.QuorumHash == Validators.QuorumHash(ErrInvalidCommitQuorumHash);- the number of extension signatures matches the number of extensions and is
≤ MaxVoteExtensions(ErrVoteExtensionCountMismatch); - the block threshold signature and every extension threshold signature
verify against
ThresholdPublicKeyover the canonical vote sign items (QuorumSignData.Verify); failure →ErrInvalidCommitSignature.
Only ErrInvalidCommitSignature identifies a dishonest sender (an honest
node stores a commit only after verifying it) and leads to eviction
(TryAddCommitAction.handleCommitVerifyError); every other failure is only
counted in CommitVerifyFailures{reason}. Replayed commits never evict.
Consensus verifies a received commit against the commit's own BlockID
(StateData.readyToApplyCommit), not against the proposal it holds: a
proposal the network never committed proves nothing about the commit, and
checking against it rejected genuine commits (dashpay/tenderdash#1414). Step 1
above is therefore tautological on this path and the block is matched to the
commit afterwards by verifyCommitBlock.
Applying a commit built from local precommits
Entered through EnterCommitAction → TryFinalizeCommitAction
(internal/consensus/state_try_finalize_commit.go).
- Precondition:
Step == ApplyCommit,maj23(Precommits(CommitRound))is a non-nilB. - If the node does not hold
B(!ProposalBlock.HashesTo(B.Hash)) the action returns quietly;EnterCommithas already retargeted the part set toBand published aValidBlockevent, so peers sendB's parts; when the last part arrivesProposalCompletedAction(stepApplyCommit) dispatchesTryFinalizeCommitagain. finalizeCommit:seenCommit = Precommits(CommitRound).MakeCommit();refuseUnprocessedCommit;mustEnsureProcess(rs, seenCommit.Round);verifyCommitExtensions(ABCIVerifyVoteExtensionon the canonical commit vote). If the application rejects its own quorum's extension vector, nothing is persisted, the failure is counted, and the node stays inApplyCommitwaiting for a peer's commit (a panic would restart into the same commit). OtherwiseDispatch(ApplyCommit{seenCommit}).
ApplyCommitAction.Execute is specified in
happy path §9. Note that it
re-runs ProcessProposal if the block was last processed for a different
round than commit.Round (mustEnsureProcess), so the number of
ProcessProposal calls per height is not bounded by one.
Commits received from peers
CommitMessage (vote channel) → commitMessageHandler →
TryAddCommitAction.Execute (internal/consensus/state_try_add_commit.go).
flowchart TD
A[CommitMessage c] --> B{rs.Commit parked?}
B -- yes --> Q{c.Height == h?}
Q -- yes --> QC[queueCandidate: ValidateBasic, dedupe, verify threshold signature, keep in sender's slot]
Q -- no --> IGN[ignore]
B -- no --> C{c.Height == h and c.Round > r?}
C -- yes --> FR[readyToApplyCommit ignoreProposalBlock=true]
FR --> FRV{verified?}
FRV -- no --> ERR[handleCommitVerifyError]
FRV -- yes --> HELD{block held?}
HELD -- yes --> VH{verifyHeldCommit ok?}
VH -- no --> RB[rs.Commit = nil; error]
VH -- yes --> NR
HELD -- no --> NR[EnterNewRound h, c.Round]
NR --> AC{block still held?}
AC -- yes --> ADD[AddCommit c]
AC -- no --> PARK[parked; wait for parts]
C -- no --> P[prepareCommitForApply]
P --> PV{verified and block held?}
PV -- error --> ERR
PV -- not ready --> PK[parked via adoptCommit; publish ValidBlock]
PV -- yes --> SET[rs.Commit = c] --> ADD
readyToApplyCommit (internal/consensus/state_data.go)
commit.ValidateBasic()(non-nil block id, signature size, known extension types).commit.Height + 1 == h→ ignored ("old commit");commit.Height ≠ h→ ignored. There is noLastCommitvote set to feed.verifyCommitSignatures(commit.BlockID, commit)— the threshold signature check, charged to the sender's verification budget.- If a complete block is held whose part set has the commit's header but whose hash differs → error ("retained block does not hash to commit hash"): parts determine the block, so waiting cannot resolve it.
- With
ignoreProposalBlock(future round):adoptCommitand return ready. - If
holdsProposalBlock(commit.BlockID)→ ready. - Else
adoptCommit(commit):retargetTo(commit.BlockID, park)— drops a proposal for another block, replaces the part set unless it already has the commit's header — andrs.Commit = commit; return not ready (parked).
Held block: verifyCommitBlock and verifyProcessedCommit
verifyCommitBlock: part-set header, block hash and state id of the commit must equal the held block's. A state-id mismatch is fatal for the commit: applied anyway, it would be recorded with a block id the next height'sLastBlockIDcould never match.verifyProcessedCommit:refuseUnprocessedCommit(expectations cache),ensureProcess(rs, commit.Round)(ProcessProposalfor the commit's round if not already processed;ErrClientStoppedpanics),validate,verifyCommitExtensions(ABCI). A failure returns an error; the commit is not applied.
Commit for the current round (or earlier)
prepareCommitForApply(ignoreProposalBlock = false): readyToApplyCommit,
then verifyCommitBlock, then verifyProcessedCommit. On success
rs.Commit = commit and Dispatch(AddCommit{commit}). When the block is not
held the commit is parked and a ValidBlock event is published so peers
serve the block.
Commit for a later round
commit.Round > r: readyToApplyCommit(ignoreProposalBlock = true) verifies
the signature and parks the commit. If the block is already held it is
verified first (verifyHeldCommit), so that a rejected commit does not move
the round (on rejection rs.Commit is reset — the retarget could at most
have dropped a proposal whose state id differed, which such a commit could
not have matched anyway). Then EnterNewRound(h, commit.Round) — which keeps
the committed block as the download target — and, if the block is held,
AddCommit.
AddCommitAction.Execute (internal/consensus/state_add_commit.go)
proposalUpdater.updateStateData(commit.BlockID): install the locked block if it is the committed one, else retarget.- If
ProposalBlock == nil(not held): return; the completing part will dispatchAddCommitagain viaselectParkedCommit. Step = ApplyCommit(round kept),CommitRound = commit.Round,CommitTime = now;Dispatch(ApplyCommit{commit})(happy path §9);PublishCommitEvent(peers receiveHasCommit);Dispatch(EnterNewRound{Height: rs.Height})for the new height.
Parked commit and replacement candidates
While rs.Commit ≠ nil, further commits for the height are not applied but
queued (TryAddCommitAction.queueCandidate,
internal/consensus/commit_candidates.go): after ValidateBasic and
deduplication against the parked commit and the sender's previous candidate,
the threshold signature is verified and the commit is stored in the sender's
single slot (overwritten by that sender's later commits; freed on
disconnect). Candidates are keyed by (height, round, blockID, hash of the extension vector) because the application's verdict depends on all four.
When the block completes (addProposalBlockPart with rs.Commit ≠ nil),
selectParkedCommit tries the parked commit and then the candidates, grouped
by round (the round already processed first, then rounds in arrival order),
calling verifyHeldCommit for each; the first accepted becomes rs.Commit
and is dispatched as AddCommit. If none is accepted, rs.Commit = nil and
the completed block continues through the ordinary flow
(ProposalCompleted).
commitExpectations (internal/consensus/commit_expectations.go) remembers,
per (height, round, block), the extension vector the application's own
ExtendVote returns after a rejection, and whether that vector was itself
rejected. A later commit for the same (round, block) with a different
vector, or with the rejected one, is refused without re-processing the block
(blockExecutor.refuseUnprocessedCommit, verifyCommitExtensions). The
block and round are authenticated by the threshold signature, the vector is
not, so this bounds ProcessProposal re-executions per height to roughly one
per foreign round plus returns to the node's own round.
Commit validity depends on the application
A commit's acceptability includes an ABCI verdict (VerifyVoteExtension on
the commit vote). Two signature-valid commits for the same block can differ
in round or extension vector and receive different verdicts; liveness
therefore depends on the application answering deterministically for the
round the quorum signed.
Interaction with the step machine
Proposaler.Setrefuses a proposal that disagrees with a parked commit for the same round and ignores a later-round proposal that would disrupt the download of a parked commit's block.EnterNewRoundkeeps the part set targeted at a parked commit's block and re-announces it (ValidBlockevent).EnterProposedoes not propose while a verified commit for a held block is about to be applied (applyingCommit).AddProposalBlockPartdispatchesProposalCompletedonly when no commit is parked or the parked one was just rejected.
Commit gossip
(internal/consensus/gossip_handlers.go, gossiper.go, reactor.go)
- After applying a commit the node broadcasts
HasCommit(PublishCommitEvent→ reactor broadcast) and every step change broadcastsNewRoundStep. - Per peer, the vote/commit gossip loop sends
CommitMessage:rs.LastCommitwhen the peer is exactly one height behind and has not announced the commit (shouldCommitBeGossiped);- the stored commit for the peer's height when it is two or more heights
behind (
shouldCommitBeGossipedForCatchup,blockStore.LoadBlockCommit/LoadSeenCommit).
- Block parts for a lagging peer come from the block store, one per tick,
with a quiet gap of
catchupResendIntervalbetween passes (GossipBlockPartsForCatchup); a non-validator peer at the current height receives parts once it announced a commit (shouldBlockPartsBeGossiped). VoteSetMaj23for the stored commit is sent to validator peers that announced a catch-up commit round (GossipVoteSetMaj23).