Known issues and discrepancies
Behaviour found while deriving this specification that looks like a bug, diverges from the Tendermint algorithm, or is otherwise surprising. Each entry describes and cites; none is fixed here. "Inferred" marks conclusions drawn from reading the code without a reproducing test.
An untimely ValidBlock is never re-proposed
Proposaler.Create (internal/consensus/state_proposaler.go) re-proposes
ValidBlock only when checkValidBlock finds it timely for ValidRound
(ValidBlock.IsTimely(ValidBlockRecvTime, SynchronyParams, ValidRound));
otherwise it builds a fresh block and proposes it with POLRound = -1. The
PBTS algorithm checks timeliness only for proposals without a POL round, so a
block that already gathered a polka would be re-proposed regardless of its
timestamp.
A proposer sees its ValidBlock as untimely when it learned the block late.
updateValidBlock dates a block with tmtime.Now() when the node learned it
without a matching proposal, which puts the receive time well after
block.Time. The proposer logs proposal block is not timely at ERROR level
when this happens.
Effect: validators locked on ValidBlock prevote nil for the fresh block,
since a lock is cleared only at a new height (see
No unlock within a height). If the voting power
locked on that block exceeds TotalVotingPower - QuorumVotingThresholdPower
and every subsequent proposer sees it as untimely, no block can gather a
polka and the height stalls (inferred; no reproducing test).
PrecommitWait step is never entered
RoundStepPrecommitWait exists in RoundStepType
(internal/consensus/types/round_state.go) and is used as the step of the
precommit-wait timeout and in peer-state comparisons
(pickVoteForGossip), but EnterPrecommitWaitAction.Execute
(internal/consensus/state_enter_wait.go) only sets
TriggeredTimeoutPrecommit and never calls updateRoundStep(round, RoundStepPrecommitWait). A node waiting for the precommit timeout reports
step Precommit. Consequences are cosmetic (events, metrics, peer state
comparisons), and handleTimeout accepts the PrecommitWait tock because
its step is greater than Precommit.
Proposer clock-wait can be swallowed by the ticker
EnterProposeAction.Execute reschedules a (h, r, NewRound) tock when the
proposer's clock is behind state.LastBlockTime. The ticker
(timeoutTicker.timeoutRoutine) ignores a tick whose step is ≤ the step of
the last scheduled tick for the same height and round, and it does not forget
the last tick after it fires. When EnterPropose itself was triggered by a
(h, r, NewRound) tock — the empty-block interval
(EnterNewRoundAction.Execute) or the transactions-available path
(State.handleTxsAvailable) — the rescheduled tick is dropped and nothing
else moves the node out of NewRound for that round. The node recovers only
when the other validators' nil precommits reach +2/3-any
(addVoteDispatchPrecommitMw → EnterPrecommitWait → EnterNewRound(r + 1)),
costing the network one round. Preconditions: WaitForTxs() true, round 0
(on CONSENSUS_VERSION_2 chains also a round entered on a round skip
certificate that waits, whose empty-block interval schedules the same
NewRound tock), the node is the proposer, and its clock is behind the previous block time by
more than the time since that block was produced. (Inferred; not reproduced.)
Precommit requires this round's proposal even when locked
EnterPrecommitAction.Execute, rule C-LockedNotProposed: a validator locked
on B that sees a polka for B in round r' > LockedRound precommits nil
unless B is also round r''s proposal block. The Tendermint paper (line
36) also requires a proposal for v in the same round, so this is faithful
to the algorithm, but it is stricter than the pre-vote-extension Tendermint
implementation, which relocked on the polka alone. The code's rationale is the
application contract: ExtendVote is answered for the round the application
processed last, and Dash Drive refuses any other. Liveness cost: a locked
validator that missed the round's proposal cannot help commit B in that
round.
No unlock within a height
LockedRound/LockedBlock are only replaced by a new lock at a later round
or reset at the next height (StateData.updateLockedBlock,
StateData.updateToState). The paper's unlock-on-nil-polka rule from the
original Tendermint implementation is absent by design
(TestStateLock_POLDoesNotUnlock), relying on P-Lock-POL to move the lock
forward instead.
Commit threshold is configurable below the BFT bound
ValidatorSet.QuorumVotingThresholdPower honours VotingPowerThreshold,
which may be lower than ⌊2n/3⌋ + 1 validators; several devnet LLMQ types
have a 50 % threshold. The code only warns
(ValidatorSet.BelowStrictThreshold, logged by StateData.updateToState).
Safety of the protocol is not guaranteed below the strict floor.
Proposer selection v0 skips the first validator after quorum rotation
heightProposerSelector.proposerFromStore
(internal/consensus/versioned/selectproposer/height_proposer.go) deliberately
sets the proposer to index 1 after a validator-set change ("bug preserved
to avoid breaking consensus"); the v1 selector uses index 0. See
Proposer selection.
FilePV repeated proposal returns sign bytes as the signature
FilePV.signProposal (privval/file.go) checks for an identical persisted
height/round/step and identical canonical proposal bytes. In that branch it assigns
proposal.Signature = lss.BlockSignBytes, rather than lss.BlockSignature.
The vote path instead reuses BlockSignature. The repeated-proposal path therefore
returns serialized sign bytes in a signature field; verification failure is the
inferred effect (no reproducing test). This differs from a guarantee of successful
signature reuse during recovery. WAL replay itself does not create proposals.
Code/comment drift and dead code
-
BlockExecutor.ProcessProposal(internal/state/execution.go) checkslen(resp.AppHash) != appHashSizeafterNewStateChangeset, butResponseProcessProposal.Validatealready returned for any size other thancrypto.DefaultAppHashSize; the later check is unreachable unlessSetAppHashSizechanges the size, which no non-test caller does. -
EnterNewRoundAction's doc comment mentionstimeoutNewHeight,timeoutCommitandSkipTimeoutCommit, none of which exist; round 0 starts atCommitTime(StateData.updateToState,roundScheduler.ScheduleRound0). -
EnterPrevoteEvent.AllowOldBlocksis set byProposalCompletedActionand never read (internal/consensus/state_enter_prevote.go). -
ErrInvalidProposalNotSetandErrAddingVote(internal/consensus/state.go) have no non-comment users. -
ApplyCommitAction.Executehandlescommit == nil, but every caller passes a commit. -
config.ConsensusConfig.DoubleSignCheckHeightis exposed as a CLI flag (cmd/tenderdash/commands/run_node.go) but no consumer was found underinternal/consensus(inferred from grep). -
blockExecutor.createreturns(nil, nil)whenLastCommit == nilaboveInitialHeight("shouldn't happen");Proposaler.Createwould then dereference a nil block inmakeProposal. Unreachable in normal operation becauseupdateToStatepanics on a missingLastCommit. -
EnterPrecommitAction.Executelogs routine nil precommits (no polka, nil polka) at error level, including the ordinary timeout path.
Non-fatal optimistic-concurrency errors
State.receiveRoutine persists StateData after each handler with a version
check (StateDataStore.update); a mismatch is only logged, after the
handler's side effects (signed votes, WAL records) already happened. No
concurrent writer exists today, so the check is a latent guard rather than a
protection.