Transitions and decision rules
This page is the formal core of the specification: for every action of the
state machine it gives the precondition (guard), the actions and the
postcondition, then the decision procedures that choose what to sign.
Dispatch(X) means Controller.Dispatch of event X; a dispatch whose guard
fails is a no-op.
Notation: h = rs.Height, r = rs.Round, step = rs.Step;
Prevotes(x) / Precommits(x) are rs.Votes.Prevotes(x) /
rs.Votes.Precommits(x); maj23(S) is S.TwoThirdsMajority();
any23(S) is S.HasTwoThirdsAny(); complete() is
StateData.isProposalComplete().
Inputs
| Input | Handler | Resulting dispatch |
|---|---|---|
Tock (H, R, NewHeight) | State.handleTimeout | EnterNewRound{H} (round 0) |
Tock (H, R, NewRound) | State.handleTimeout | EnterPropose{H, R} |
Tock (H, R, Propose) | State.handleTimeout | publish TimeoutPropose; EnterPrevote{H, R} |
Tock (H, R, PrevoteWait) | State.handleTimeout | publish TimeoutWait; EnterPrecommit{H, R} |
Tock (H, R, PrecommitWait) | State.handleTimeout | publish TimeoutWait; EnterPrecommit{H, R}; EnterNewRound{H, R + 1} |
TxsAvailable | State.handleTxsAvailable | sets TxsReported; acts only at r == 0 or in a round that may wait after a round skip (mayWaitAfterRoundSkip): at step NewHeight (and h ≠ InitialHeight) schedule tock (h, 0, NewRound) after StartTime − now + 1 ms; at step NewRound dispatch EnterPropose{h, r} |
ProposalMessage | proposalMessageHandler → Proposaler.Set | see Proposal acceptance; if accepted while waitingForTxs, EnterPropose{h, r} |
BlockPartMessage | blockPartMessageHandler | AddProposalBlockPart; on completion ProposalCompleted or AddCommit |
VoteMessage | voteMessageHandler | AddVote → vote-driven dispatch |
CommitMessage | commitMessageHandler | TryAddCommit (Commit handling) |
RoundSkipCertificateMessage | roundSkipCertificateMessageHandler | AddRoundSkipCertificate |
ProposerHeartbeatMessage, RoundSkipVoteMessage | State.handleLivenessMessage | none, or AddRoundSkipCertificate for a certificate the vote completed (Proposer liveness) |
| Proposer-silence report | State.handleProposerSilence | none; signs a round skip vote off the consensus goroutine |
| Signed round skip vote | State.handleSignedRoundSkipVote | none, or AddRoundSkipCertificate for a certificate the vote completed |
Every tock is written to the WAL before handling; handleTimeout drops a
tock when ti.Height ≠ h, ti.Round < r, or ti.Round == r && ti.Step < step
(internal/consensus/state.go).
Timer semantics
timeoutTicker (internal/consensus/ticker.go) owns one timer.
ScheduleTimeout(ti) replaces the pending timer unless ti is older than the
last scheduled (Height, Round, Step): a tick is ignored when its height is
lower, or its round is lower at the same height, or at the same height and
round its step is ≤ the pending step (and the pending step is non-zero).
Consequences:
- a
PrevoteWaittick supersedes a still-pendingProposetick for the same round, so the propose timeout never fires once a prevote wait started; - a tick for the same step as the pending one at the same
(h, r)is dropped even if the pending one already fired, because the ticker remembers the lastti(see Known issues); - durations may be zero or negative; such ticks fire immediately.
The receive routine handles the tock only if it still matches
(h, r, step) as described above.
Step actions
EnterNewRound(H, R)
EnterNewRoundAction.Execute (internal/consensus/state_enter_new_round.go).
- Guard:
h == H ∧ R ≥ r ∧ (R == r ⇒ step == NewHeight). - Actions:
updateRoundStep(R, NewRound)(alsoProposerSelector.UpdateHeightRound(h, R)).- If
R > 0:Proposal = nil,ProposalReceiveTime = 0; ifrs.Commit ≠ nilthenretargetTo(Commit.BlockID)(keep collecting the committed block), elseProposalBlock = nil,ProposalBlockParts = nil.LockedBlock,ValidBlockandCommitare kept. Votes.SetRound(R + 1);TriggeredTimeoutPrecommit = false; save.- Publish
NewRound; if a commit is parked also publish the step and aValidBlockevent so peers keep serving the committed block's parts. waitForTxs = config.WaitForTxs() ∧ (R == 0 ∨ waitsAfterRoundSkip(R)) ∧ h ≠ InitialHeight ∧ ¬ProposeNextBlockImmediately ∧ ¬(roundSkipping ∧ Proposal ≠ nil)whereWaitForTxs = ¬CreateEmptyBlocks ∨ CreateEmptyBlocksInterval > 0(config/config.go);roundSkippingis defined in When it applies andwaitsAfterRoundSkipin The round after a skip.waitForTxs ∧ R > 0 ∧ Commit == nil: publish theNewRoundstep.waitForTxs ∧ CreateEmptyBlocksInterval > 0: schedule tock(h, R, NewRound)after the interval (forR > 0, the interval minusnow − StartTime, at least 0); stay inNewRound.waitForTxs ∧ CreateEmptyBlocksInterval == 0: stay inNewRounduntilTxsAvailable.- otherwise (unless the test-only
DontAutoPropose):Dispatch(EnterPropose{h, R}).
- Postcondition:
r = R,step = NewRound(or beyond, ifEnterProposeran synchronously).
EnterPropose(H, R)
EnterProposeAction.Execute (internal/consensus/state_enter_propose.go).
- Guard:
h == H ∧ R ≥ r ∧ (R == r ⇒ step < Propose). - Actions:
isProposer ← ProposerSelector.GetProposer(h, r) == own pro-tx-hash;applyingCommit ← Commit ≠ nil ∧ holdsProposalBlock(Commit.BlockID).- If
isProposer ∧ ¬applyingCommit ∧ state.LastBlockTime > now: schedule tock(H, R, NewRound)afterLastBlockTime − nowand return without changing step (the guard admits the retry becausestepis stillNewRound). - Schedule tock
(H, R, Propose)afterproposeTimeout(R). - If
¬isProposer, orapplyingCommit, or replay mode, or¬catchup.mayPropose(h): do nothing more. - Else
wal.FlushAndSync()(a failure is only logged);Proposaler.Create(h, R, rs)(happy path §3a). A creation or signing error is logged and the round proceeds as if the proposer were silent. - Deferred:
updateRoundStep(R, Propose), publish step; ifcomplete()thenDispatch(EnterPrevote{H, R}).
- Postcondition:
step = Propose, propose timeout armed (except in the clock-wait case of action 2).
Proposal acceptance (Proposaler.Set)
Proposaler.Set (internal/consensus/state_proposaler.go) runs for every
ProposalMessage (own or peer's). The message must already pass
Proposal.ValidateBasic (types/proposal.go: type, non-negative height and
round, POLRound ≥ -1, complete BlockID, CoreChainLockedHeight ≠ MaxUint32,
signature present).
flowchart TD
A[ProposalMessage p] --> B{rs.Proposal != nil?}
B -- yes --> IGN[ignore]
B -- no --> C{p.Height == h and p.Round == r?}
C -- no --> IGN
C -- yes --> D{parked Commit whose part set is under way and p.BlockID != Commit.BlockID?}
D -- yes --> IGN
D -- no --> E{p.POLRound == -1 or 0 <= p.POLRound < p.Round?}
E -- no --> ERR1[ErrInvalidProposalPOLRound]
E -- yes --> F{p.CoreChainLockedHeight >= state.LastCoreChainLockedBlockHeight?}
F -- no --> ERR2[ErrInvalidProposalCoreHeight]
F -- yes --> G{block already assembled?}
G -- yes --> H{BlockID and CoreChainLockedHeight equal the block's?}
H -- no --> ERR3[ErrInvalidProposalBlockID / ErrInvalidProposalCoreHeight]
H -- yes --> I
G -- no --> I{roundStateRefusal: commit for same h,r names another block? part set under way has another header?}
I -- yes --> ERR4[ErrInvalidProposalForCommit / ErrInvalidProposalForPartSet]
I -- no --> J{proposer public key known?}
J -- no --> K{parked commit for same h,r with same BlockID?}
K -- no --> ERR5[ErrUnableToVerifyProposal]
K -- yes --> OK
J -- yes --> L{verification budget allows one signature check?}
L -- no --> ERR6[ErrVerificationBudgetExhausted - local drop]
L -- yes --> M{proposer.PubKey verifies ProposalBlockSignID?}
M -- no --> ERR7[ErrInvalidProposalSignature]
M -- yes --> OK[rs.Proposal = p; ProposalReceiveTime = enqueue time; part set created if none]
Properties:
- The proposer is
ProposerSelector.GetProposer(h, r); the signature is checked against that validator's key for the committed state'sQuorumType/QuorumHash(types.ProposalBlockSignID). - A proposal that fails is not stored, so a later valid one for the same round can still be accepted; a proposal that fails the signature check is verified again every time it is resent (bounded by the verification budget).
- Errors are returned to the message dispatcher; the sender is not evicted for any of them.
- Equivocating proposals: the first valid one is kept; later ones are ignored
while it occupies
rs.Proposal. The slot is freed within the round only when authenticated votes retarget the round to another block (StateData.retargetTo→dropStaleProposal: current-round polka, precommit-time polka for a block not held, parked or applied commit); a proposal for that block can then be accepted (invariant 5).
AddProposalBlockPart / ProposalCompleted
AddProposalBlockPartAction.Execute, ProposalCompletedAction.Execute
(internal/consensus/state_add_prop_block.go).
- Guard (part):
msg.Height == h;ProposalBlockParts ≠ nil; the peer's invalid-proof budget allows it (blockPartProofBudget). The message's round is not checked: parts of the same block from another round are accepted. - Actions (part):
ProposalBlockParts.AddPart(part)(Merkle proof against the part-set header;ErrPartSetInvalidProofcharges the sender's budget); if the accumulated size exceedsConsensusParams.Block.MaxBytes→ error. When complete: decode the block; ifrs.Proposal ≠ niland the block's hash or part-set header differ from the proposal's →rs.Proposal = nil(the block is kept); otherwise the proposal'sCoreChainLockedHeightandBlockID.StateIDare replaced by the block's;rs.ProposalBlock = block. If a commit is parked →selectParkedCommit(Commit handling). - ProposalCompleted:
- If
maj23(Prevotes(r))is a non-nil block idB,ValidRound < r, and the held block isB→updateValidBlock(). - If
step ≤ Propose ∧ complete()→Dispatch(EnterPrevote{h, r}); then if a polka exists →Dispatch(EnterPrecommit{h, r}). - Else if
step == ApplyCommit→Dispatch(TryFinalizeCommit{h}).
- If
complete() ≡ Proposal ≠ nil ∧ ProposalBlock ≠ nil ∧ (Proposal.POLRound < 0 ∨ Prevotes(POLRound).HasTwoThirdsMajority())(StateData.isProposalComplete).
EnterPrevote(H, R)
EnterPrevoteAction.Execute (internal/consensus/state_enter_prevote.go).
- Guard:
h == H ∧ R ≥ r ∧ (R == r ⇒ step < Prevote). - Actions: run the prevote decision and
sign exactly one prevote (block or nil); deferred
updateRoundStep(R, Prevote). - Postcondition:
step = Prevote; one prevote for(h, R)is on the internal queue (if the node is a validator and signing succeeded).
EnterPrevoteWait(H, R)
EnterPrevoteWaitAction.Execute (internal/consensus/state_enter_wait.go).
- Guard:
h == H ∧ R ≥ r ∧ (R == r ⇒ step < PrevoteWait); panics unlessany23(Prevotes(R)). - Actions: schedule tock
(H, R, PrevoteWait)aftervoteTimeout(R); deferredupdateRoundStep(R, PrevoteWait).
EnterPrecommit(H, R)
EnterPrecommitAction.Execute (internal/consensus/state_enter_precommit.go).
- Guard:
h == H ∧ R ≥ r ∧ (R == r ⇒ step < Precommit). - Actions: run the precommit decision
and sign exactly one precommit; deferred
updateRoundStep(R, Precommit). - Postcondition:
step = Precommit; lock possibly updated (only toR).
EnterPrecommitWait(H, R)
EnterPrecommitWaitAction.Execute (internal/consensus/state_enter_wait.go).
- Guard:
h == H ∧ R ≥ r ∧ (R == r ⇒ ¬TriggeredTimeoutPrecommit); panics unlessany23(Precommits(R)). - Actions: schedule tock
(H, R, PrecommitWait)aftervoteTimeout(R); deferredTriggeredTimeoutPrecommit = true, publish step. - Postcondition:
stepunchanged (see Known issues).
EnterCommit(H, CR)
EnterCommitAction.Execute (internal/consensus/state_enter_commit.go).
- Guard:
h == H ∧ step < ApplyCommit; panics unlessmaj23(Precommits(CR))exists. - Actions:
proposalUpdater.updateStateData(blockID): ifLockedBlockis the committed block, install it asProposalBlock(replaceProposalBlockOnLockedBlock); if the block is not held,retargetTo(blockID)and publishValidBlock(start fetching). Deferred:Step = ApplyCommit(round unchanged),CommitRound = CR,CommitTime = now, publish step,Dispatch(TryFinalizeCommit{h}). - Postcondition:
step = ApplyCommit,CommitRound = CR.
AddRoundSkipCertificate(cert)
AddRoundSkipCertificateAction.Execute (internal/consensus/state_add_round_skip.go).
- Guard:
roundSkipping ∧ cert.Height == h ∧ (RoundSkip == nil ∨ cert.Round > RoundSkip.Round) ∧ step < ApplyCommit(roundSkipCertificateWanted). - Actions: verify the certificate unless this node recovered it (budget,
quorum hash, threshold signature); write its message to the WAL (not on replay);
RoundSkip = cert; broadcast it; ifcert.Round ≥ r,Dispatch(EnterNewRound{h, cert.Round + 1}). - Postcondition:
RoundSkip = cert;r > cert.Round, orrunchanged when the certificate is for an earlier round.
TryFinalizeCommit(H) / ApplyCommit(commit)
See Commit handling.
Vote-driven dispatch
AddVoteAction.Execute (internal/consensus/state_add_vote.go) runs a
middleware chain. Order of execution for a prevote: validate → add to
vote set → addVoteUpdateValidBlockMw → addVoteDispatchPrevoteMw. For a
precommit: validate → addVoteVerifyVoteExtensionMw → add to vote set →
addVoteDispatchPrecommitMw. Errors pass through addVoteErrorMw
(evidence reporting).
Admission (addVoteValidateVoteMw, HeightVoteSet.addVote, VoteSet.addVote)
A vote is admitted to the set iff all hold:
vote.Height == h;rs.Validators.HasPublicKeys;0 ≤ vote.ValidatorIndex < |Validators|.- The round's vote set exists, or (
HeightVoteSet.checkVoteClaimpasses and) the validator has opened fewer than 2 catch-up rounds (peerCatchupRounds); a provisional round is discarded if its first vote is not admitted. vote.ValidatorProTxHashequals the validator's at that index.- Not a duplicate (same block key and identical block signature →
added = false, no error); a different signature for the same block key →ErrVoteNonDeterministicSignature. - The block signature (and, for non-nil precommits, every extension
signature) verifies against the validator's share public key for
(ChainID, QuorumType, QuorumHash)—Vote.Verify, or evidence fromaddVoteVerifyVoteExtensionMwthat this was done (VoteVerification). - For a non-nil precommit from a peer: ABCI
VerifyVoteExtensionreturnedACCEPT(afterblockExecutor.ensureOwnRound).
A vote by a validator who already voted for a different block id in the
same round is recorded as conflicting: NewConflictingVoteError is returned
and the later vote is kept only if a peer claimed +2/3 for its block id
(VoteSet.addVerifiedVote, VoteSet.SetPeerMaj23). addVoteErrorMw
reports the pair to the evidence pool (evidencePool.ReportConflictingVotes)
unless it is the node's own key.
After a prevote is added
addVoteUpdateValidBlockMw, with P = Prevotes(vote.Round) and
B = maj23(P) non-nil:
- if
ValidRound < vote.Round ∧ vote.Round == r: if the held block isBthenupdateValidBlock(); in all casesretargetTo(B)(drops a proposal for another block, replaces the part set unless its header isB's), save, publishValidBlock.
addVoteDispatchPrevoteMw:
| Condition | Dispatch |
|---|---|
r < vote.Round ∧ any23(P) | EnterNewRound{h, vote.Round} (round skip) |
r == vote.Round ∧ step ≥ Prevote ∧ maj23(P) = B ∧ (complete() ∨ B = nil) | EnterPrecommit{h, r} |
r == vote.Round ∧ step ≥ Prevote ∧ any23(P) (otherwise) | EnterPrevoteWait{h, r} |
Proposal ≠ nil ∧ Proposal.POLRound == vote.Round ≥ 0 ∧ complete() (and neither of the above) | EnterPrevote{h, r} (POL votes completed a proposal with POLRound) |
waitingForTxs ∧ (maj23(P) exists ∨ (vote.Round == r ∧ r > 0)) (and none of the above) | EnterPropose{h, r} (ends a wait for transactions; CONSENSUS_VERSION_2) |
After a precommit is added
addVoteDispatchPrecommitMw, with C = Precommits(vote.Round):
| Condition | Dispatch |
|---|---|
¬maj23(C) ∧ r ≤ vote.Round ∧ any23(C) | EnterNewRound{h, vote.Round}; EnterPrecommitWait{h, vote.Round} |
maj23(C) = nil | EnterNewRound{h, vote.Round}; EnterPrecommit{h, vote.Round}; EnterPrecommitWait{h, vote.Round} |
maj23(C) = B ≠ nil | EnterNewRound{h, vote.Round}; EnterPrecommit{h, vote.Round}; EnterCommit{h, vote.Round}; then EnterNewRound{Height: rs.Height} (which is h + 1 if the commit was applied synchronously) |
A precommit majority at a round below the current one is honoured: the
EnterNewRound/EnterPrecommit dispatches are no-ops and EnterCommit runs
with CommitRound = vote.Round (TestCommitFromPreviousRound).
Prevote decision (prevoter.Do)
prevoter.Do (internal/consensus/state_prevoter.go) with
StateData.isValidForPrevote (internal/consensus/state_data.go).
flowchart TD
S([EnterPrevote h,r]) --> A{ProposalBlock held?}
A -- no --> NIL[prevote nil]
A -- yes --> B{Proposal held?}
B -- no --> NIL
B -- yes --> C{Proposal.Timestamp == block.Time?}
C -- no --> NIL
C -- yes --> D{block == ValidBlock?}
D -- yes --> F
D -- no --> E{timely? InitialHeight: timestamp == genesis time; else receive time within window for round r, in replay only too early fails}
E -- no --> NIL
E -- yes --> F{ValidateBlockChainLock ok?}
F -- no --> NIL
F -- yes --> G{POLRound == -1 implies block.ProposerProTxHash == proposer h,r?}
G -- no --> NIL
G -- yes --> H[ensureProcess for round r unless already processed]
H --> V{ValidateBlock against committed state ok?}
V -- no --> NIL
V -- yes --> I{ABCI ProcessProposal: ACCEPT and header matches app result?}
I -- REJECT or mismatch --> NIL
I -- other error --> PANIC[panic]
I -- yes --> J[mustValidate]
J --> K{POLRound == -1?}
K -- yes --> L{LockedRound == -1 or block == LockedBlock?}
L -- yes --> VOTE[prevote block]
L -- no --> NIL
K -- no --> M{maj23 of Prevotes POLRound == block and 0 <= POLRound < r?}
M -- no --> NIL
M -- yes --> N{LockedRound <= POLRound or block == LockedBlock?}
N -- yes --> VOTE
N -- no --> NIL
Rules, in evaluation order:
- P-NoBlock / P-NoProposal. No block or no proposal held → nil
(
errPrevoteProposalBlockNil,errPrevoteProposalNil). This is the path taken ontimeoutPropose. No ABCI call is made. - P-Timestamp.
Proposal.Timestamp ≠ ProposalBlock.Time→ nil. - P-Timely. Skipped when the block is already
ValidBlock. AtInitialHeightthe timestamp must equal the genesis time; otherwiseProposal.CheckTimely(ProposalReceiveTime, SynchronyParams, r)must be 0 (checkTimelyintypes/validation.go):ts − Precision ≤ recv ≤ ts + MessageDelay·2^⌊r/10⌋ + Precision(the shift is capped to avoid overflow). In replay moderecvis the time of the proposal's WAL entry, which can lag its receipt, so onlyrecv < ts − Precision(too early) fails. - P-ChainLock.
sm.ValidateBlockChainLock(state, block)(internal/state/validation.go): with aCoreChainLockin the block,Header.CoreChainLockedHeight == CoreChainLock.CoreBlockHeightand> state.LastCoreChainLockedBlockHeight; without one,Header.CoreChainLockedHeight == state.LastCoreChainLockedBlockHeight. - P-Proposer. For
POLRound == -1the block header'sProposerProTxHashmust be this round's proposer. Re-proposals (POLRound ≥ 0) keep the original header's proposer and are exempt. - P-Process.
blockExecutor.ensureProcess(rs, r): ABCIProcessProposalfor roundrunlessCurrentRoundStatealready is the result for this block and round. The block is first validated against the committed state (BlockExecutor.ValidateBlock: version, chain ID, height,LastBlockID, core chain lock,LastCommit, proposer, evidence, …); a block that fails is never sent to the application and yieldsErrInvalidBlock.ErrBlockRejected(applicationREJECT) orErrInvalidBlock(also a well-formedACCEPTwhose contents disagree with the block: header fields differ from the application's answer,LastCommitinvalid —ValidateBlockWithRoundState) → nil prevote; any other error → panic (prevoter.handleError). A malformed application response is in the panic class, not the nil-prevote class:UNKNOWNstatus, anAppHashof the wrong size (ResponseProcessProposal.Validate), ortx_resultsnot matching the transactions (validateExecTxResults) are returned byBlockExecutor.ProcessProposalas plain errors before theErrInvalidBlockwrapper is reached. Note thatProcessProposalruns before the lock rules, so a locked validator still processes a different proposal and then prevotes nil. - P-Lock-NoPOL (paper line 22–24).
POLRound == -1: prevote the block iffLockedRound == -1 ∨ ProposalBlock.BlockID == LockedBlock.BlockID(prevoter.checkProposalBlock). - P-Lock-POL (paper line 28–30).
POLRound ≥ 0: prevote the block iffmaj23(Prevotes(POLRound)) == ProposalBlock.BlockID ∧ 0 ≤ POLRound < r ∧ (LockedRound ≤ POLRound ∨ ProposalBlock.BlockID == LockedBlock.BlockID)(prevoter.checkPrevoteMaj23). Block ids compare all three fields, includingStateID. - Otherwise prevote nil.
EnterPrevote is reached either because the proposal is complete or because
timeoutPropose fired. A proposal with POLRound ≥ 0 whose POL prevotes have
not arrived is not complete, so the node stays in Propose until those
prevotes arrive (addVoteDispatchPrevoteMw, last row) or the timeout fires;
in the latter case the block and proposal are held, rules 1–6 can pass, and
rule 8 yields nil because maj23(Prevotes(POLRound)) is absent.
Precommit decision (EnterPrecommitAction.Execute)
flowchart TD
S([EnterPrecommit h,r]) --> A{polka in Prevotes r?}
A -- no --> NIL[precommit nil, keep lock]
A -- yes --> B{polka is nil?}
B -- yes --> NIL
B -- no --> C{Proposal and ProposalBlock held?}
C -- no --> NIL
C -- yes --> D{Proposal.Timestamp == block.Time?}
D -- no --> NIL
D -- yes --> E{held block == polka block B?}
E -- no --> F{LockedBlock == B?}
F -- yes --> NIL2[precommit nil, keep lock]
F -- no --> RT[retargetTo B: fetch B; precommit nil]
E -- yes --> G[mustEnsureProcess r; mustValidate]
G --> H{LockedBlock == B?}
H -- yes --> RL[LockedRound = r; relock event; precommit B]
H -- no --> LK[lock B at r; lock event; precommit B; updateValidBlock]
Rules, in evaluation order:
- C-NoPolka.
¬maj23(Prevotes(r))→ precommit nil. Reached from thePrevoteWait/PrecommitWaittocks. The lock is unchanged. - C-POLInfo.
HeightVoteSet.POLInfo()returns the highest round with a polka; if it is< rthe node panics (cannot happen after rule 1). - C-NilPolka. Polka for nil → precommit nil.
- C-NoProposal.
Proposal == nil ∨ ProposalBlock == nil→ nil. No fetch is started here (the polka middleware already retargeted toB). - C-Timestamp.
Proposal.Timestamp ≠ ProposalBlock.Time→ nil. - C-LockedNotProposed. Polka block
BequalsLockedBlockbut this round's proposal block is different → nil, lock kept. Rationale in the code: the precommit's extensions are produced byExtendVotefor the block the application processed last at this round; a block locked earlier was processed for an earlier round, and an honest proposer would have re-proposedB. Consequence: a locked validator that misses the re-proposal of its locked block cannot relock in that round (TestStateLock_MissingProposalWhenPOLSeenDoesNotUpdateLock). - C-Lock / C-Relock.
Bis this round's proposal block:mustEnsureProcess(rs, r)(re-runsProcessProposalif the block was processed for another round; panics on failure),mustValidate; if already locked onB→LockedRound = r,Relockevent, precommitB; elseupdateLockedBlock()(LockedRound = r,LockedBlock = B),Lockevent, precommitB,updateValidBlock()(+ValidBlockevent if it changed). - C-Unknown. Polka for a block the node does not hold and is not locked
on →
retargetTo(B)(start collecting its parts; a proposal for another block is dropped) and precommit nil.
A non-nil precommit triggers ABCI ExtendVote inside voteSigner.signVote;
a nil precommit carries no extensions (Vote.ValidateBasic rejects
extensions on prevotes and nil precommits).
Proposal-validity summary
A block becomes prevotable when all of the following hold; the function that checks each is given.
| Check | Where |
|---|---|
Proposal signed by proposer(h, r) | Proposaler.verifyProposal |
POLRound ∈ {-1} ∪ [0, r) | Proposaler.Set |
Proposal BlockID hash and part-set header equal the assembled block's | AddProposalBlockPartAction.addProposalBlockPart |
Parts' Merkle proofs valid; total size ≤ Block.MaxBytes | PartSet.AddPart, addProposalBlockPart |
Proposal.Timestamp == Header.Time | isValidForPrevote, EnterPrecommitAction.Execute |
Timely (PBTS window; in replay, not too early), unless ValidBlock | StateData.proposalIsTimely |
| Core chain lock consistent with state | sm.ValidateBlockChainLock, validateBlock |
Header.ProposerProTxHash == proposer(h, r) when POLRound == -1 | isValidForPrevote |
Block.ValidateBasic; version, chain id, height, LastBlockID, ConsensusHash, ValidatorsHash, LastCommit threshold signature, proposer is a validator, Time > LastBlockTime (≥ genesis at initial height), evidence size | validateBlock in internal/state/validation.go |
ABCI ProcessProposal = ACCEPT; AppHash, ResultsHash, NextValidatorsHash, NextConsensusHash equal the application's; app hash size | BlockExecutor.ProcessProposal, ValidateBlockWithRoundState |
| Lock rules P-Lock-NoPOL / P-Lock-POL | prevoter.shouldVoteBeSent |