Repository navigation
docs(consensus): document proposer liveness and round skipping - #1606
Conversation
Specify the CONSENSUS_VERSION_2 mechanism added in #1572: proposer heartbeats while a round waits for transactions, round skip votes and certificates, the round entered after a skip, WAL and replay handling, message admission and budgets, signer support, the new timeout parameters and their derivation, update and hashing rules, and metrics. Update the consensus overview, transitions, alternative flows, recovery, WAL, proposer-selection, p2p message, core data-structure, ABCI Echo and node operator docs that still described pre-version-2 behaviour. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fix peer-error classification of liveness messages, the WAL iterator note, the polka condition that ends a wait, signer implementation paths, the happy-path waitForTxs formula, link targets, and the conditions under which a post-skip round waits. Tighten the ABCI Echo probe description and extend the ticker known issue to post-skip rounds. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the
|
|
✅ Final review complete — Phase 1 only — no blockers (commit 90fcd88) · triage: trivial |
… wording - genesis.md lists version.consensus and the timeout.proposer_heartbeat / proposer_silence parameters. - The RoundSkipVote wire reference says a counted vote is relayed again on a later copy until the round is certified, as the collector does. - Drop the walMsgHeight clause from Recovery: it described a replay that cannot happen on a chain that records certificates. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post |
thepastaclaw
left a comment
There was a problem hiding this comment.
Final validation — Phase 1 + Phase 2
The documentation-only changes accurately describe the proposer-liveness implementation overall, and the supplied CI snapshot shows all build, test, lint, documentation, and vulnerability checks passing. Two documentation inaccuracies remain: the ABCI hint descriptions omit the consensus-version-2 post-skip wait, and several new references incorrectly describe certificates as requiring universally +2/3 voting power.
🟡 2 suggestion(s)
Approved: nothing here blocks the merge. The non-blocking findings are optional: fix them forward, in this PR or a follow-up, without waiting for another review round.
1 finding(s) not shown inline (the lines are not part of this PR's diff)
🟡 Suggestion: ABCI finalize hint omits post-skip waiting rounds
spec/abci/api.md:796
This description says propose_next_block_immediately only bypasses the transaction wait before round 0. In EnterNewRoundAction.Execute, consensus version 2 also waits when stateData.waitsAfterRoundSkip(round) is true, and the same hint clears that wait. The identical round-0-only wording appears in spec/abci/methods.md:585-588; update both references to mention round 0 and, on consensus version 2, a round entered after a silent proposer's round was skipped.
source: muse-spark-1.3-contributor (phase1-reviewer: general); gpt-6.1-sol (phase2-reviewer: general, tenderdash-consensus-security)
Review provenance
Source: reviewer 1: muse-spark-1.3-contributor (agent: phase1-reviewer, role: general); reviewer 2: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 3: gpt-6.1-sol (agent: phase2-reviewer, role: tenderdash-consensus-security); reviewer 4: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 5: gpt-6.1-sol (agent: phase2-reviewer, role: tenderdash-consensus-security); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)
- Triage:
normalbygpt-6.1-sol(effort low) — Although this is a documentation-only change with no behavioral diff, it is a large, cross-cutting update covering consensus liveness, wire-format messages, parameters, WAL/replay, and operational behavior, so a second review can still add value. - Phase 1 reviewers:
muse-spark-1.3-contributor— general (completed, effort xhigh); agentphase1-reviewer - Phase 1 model:
muse-spark-1.3-contributor— not quota-gated; passed overgemini-3.8-flash-high(antigravity quota lookup failed),glm-5.3-flash(not used above high effort; tier asks max) - Second Phase-2 pass: on this first full review every Phase-2 reviewer also ran a second, independent time, and the verifier weighed both sets
- Fresh verifier:
gpt-6.1-sol— final-verifier; agentsol-verifier - Phase 2 reviewers:
gpt-6.1-sol— general (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— tenderdash-consensus-security (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— general (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— tenderdash-consensus-security (completed, effort high); agentphase2-reviewer
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review (PastaClaw). How to work through them:
- Verify each finding against the code; fix only what is real, as narrowly as the finding.
- If a finding is wrong, decline it on its thread in one or two sentences; the bot answers once and stops.
- To defer one, link a tracking issue on its thread (or reply asking the bot to file one).
- Suggestions are optional: fix them forward in a later PR rather than pushing another round just for them.
- Address every current finding in one push: self-review the full diff first, and don't push piecemeal.
- Keep the PR's scope; don't grow it to satisfy hardening suggestions.
- Carried items were raised in an earlier round: read the thread first, and don't re-fix what you already fixed, declined or deferred there. Disputed and deferred items are already handled and are not listed.
In `spec/abci/api.md`:
- [SUGGESTION] spec/abci/api.md:796: ABCI finalize hint omits post-skip waiting rounds
This description says `propose_next_block_immediately` only bypasses the transaction wait before round 0. In `EnterNewRoundAction.Execute`, consensus version 2 also waits when `stateData.waitsAfterRoundSkip(round)` is true, and the same hint clears that wait. The identical round-0-only wording appears in `spec/abci/methods.md:585-588`; update both references to mention round 0 and, on consensus version 2, a round entered after a silent proposer's round was skipped.
In `spec/p2p/messages/consensus.md`:
- [SUGGESTION] spec/p2p/messages/consensus.md:221: Document the actual round-skip certificate threshold
The certificate is described as being recovered from skip votes holding universally +2/3 of validator power, but the implementation uses `RoundSkipThresholdPower = max(T, R)`, where `T` is the configured voting threshold and `R` is the quorum's BLS recovery threshold. Round skipping is enabled when `T <= R`, so valid certificates can require less than two-thirds for quorum types with lower recovery thresholds. The same inaccurate +2/3 wording appears in the new liveness diagram at `spec/consensus/consensus-proposer-liveness.md:187` and the metric description at `docs/nodes/metrics.md:68`; align all three descriptions with the implementation.
|
Policy satisfied — this can merge. |
…l hint The round skip certificate threshold is +2/3 on mainnet (LLMQ_100_67, no VotingPowerThreshold); state that the quorum type and VotingPowerThreshold set it. ResponseFinalizeBlock.propose_next_block_immediately also skips the wait of a round entered after a skipped round on consensus version 2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post |
thepastaclaw
left a comment
There was a problem hiding this comment.
Re-review — Final review — Phase 1 only (trivial change)
This documentation-only change accurately describes proposer liveness and round skipping across the consensus, wire-format, ABCI, operator, and recovery documentation. The reviewed CI checks are successful, with only the PR Hygiene check still in progress; no in-scope findings remain.
🔴 0 blocking | 🟡 0 suggestion(s) | 💬 0 nitpick(s)
Review provenance
Source: reviewer 1: glm-5.3-flash (agent: phase1-reviewer, role: general); final verifier: gpt-6.1-sol (agent: sol-gate-verifier, role: final-verifier)
- Triage:
trivialbygpt-6.1-sol(effort low) — This is a documentation-only change with comment and reference updates that does not alter consensus behavior, serialization, or runtime logic. - Phase 1 reviewers:
glm-5.3-flash— general (completed, effort high); agentphase1-reviewer - Phase 1 model:
glm-5.3-flash— zai quota: 5h 96% left, weekly 90% left; passed overgemini-3.8-flash-high(antigravity quota lookup failed) - Fresh verifier:
gpt-6.1-sol— final-verifier; agentsol-gate-verifier - Phase 2 reviewers: not run (triage rated this change trivial); this review comments and never approves
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review. Verify the current code and confirm that no unresolved issues remain.
No unresolved findings remain from the prior review on this head.
|
Ready for review — files with no dedicated owner: lklimek or shumkov. |
|
Policy satisfied — this can merge. |
TL;DR: Documents how validators detect a silent proposer on an idle chain and hand its round to the next proposer, and corrects docs that still describe the older behavior.
User story
As a node operator or protocol reviewer, I want the consensus documentation to describe how the network handles a proposer that goes offline while the chain waits for transactions, to understand, configure and audit that behavior without reading the code.
Scenario
Base flow
A chain enables consensus version 2. While it waits for transactions, the current proposer goes offline, and the other validators move the round on to the next proposer.
Actual behavior
#1572 added this mechanism, but its documentation covers only signing. The consensus specification, the wire-format reference, parameter tables, metrics, remote-signer and configuration guides make no mention of it. Some pages are now wrong, for example they say only round 0 waits for transactions, or that
Echois for debugging only.Expected behavior
The documentation explains when the mechanism applies, how it works end to end, which parameters, messages and metrics it adds, and what it changes for remote signers and configuration. Pages it made inaccurate are corrected.
Detailed discussion
What was done
spec/consensus/consensus-proposer-liveness.md: activation (roundSkipping= version 2 ∧RoundSkipsProvable), heartbeats, silence and skip votes, certificate recovery and application, the round after a skip, gossip, WAL/replay, verification budgets and peer errors, signers, timeout parameters, metrics. Linked fromconsensus.md,spec/consensus/readme.mdandbook/SUMMARY.md.spec/consensus/:consensus.md(terminology, receive-routine inputs, round state, step diagram, timeouts; source-of-truth branch is nowdev),consensus-transitions.md(waitForTxs,AddRoundSkipCertificate, prevote dispatch),consensus-alternative-flows.md(round skipping, mempool and empty blocks, signers, observers, DoS budgets),consensus-happy-path.md,consensus-recovery.mdandwal.md(certificate WAL record,wal-skip-rounds-to-lastignored on version 2),consensus-known-issues.md(ticker issue also covers a post-skip round),proposer-selection.md(version 2 uses the version 1 strategy).spec/p2p/messages/consensus.md:ProposerHeartbeat,RoundSkipVote,RoundSkipCertificate,Messagefields 12–14.spec/core/data_structures.md,spec/core/state.mdandspec/core/genesis.md: signed message types 0x30/0x31,CONSENSUS_VERSION_2,TimeoutParamsfields 7–8 (genesisversion.consensus,timeout.proposer_heartbeat/proposer_silence),voting_power_thresholdnote. The round skip certificate threshold is described as +2/3, the mainnet value, with the quorum type andVotingPowerThresholdsettingmax(T, R).spec/abci/*:Echois also used as the proposer's application-readiness probe;ResponseFinalizeBlock.propose_next_block_immediatelyalso skips the wait of a round entered after a skipped round (comment intypes.proto, regeneratedapi.mdandtypes.pb.gocomment only).docs/nodes/{metrics,remote-signer,configuration}.mdanddocs/tenderdash-core/using-tenderdash.md: new metrics, remote signers cannot sign liveness messages, which rounds wait for transactions.Testing
Docs only. All claims were checked against the code at
683b8ace9, then verified by two independent reviews (all added links and anchors resolve). markdownlint reports no new findings.Breaking changes
None.
Prior work
consensus.md,data_structures.mdandbook/SUMMARY.md, so expect small textual conflicts. This PR does not touch theHashedParamsfield list.Attribution
🤖 Generated with Claude Code
🤖 Co-authored by Claudius the Magnificent AI Agent
PR Hygiene ·
90fcd88abci/types/types.pb.go,book/SUMMARY.md,docs/nodes/configuration.mdand 22 more) — approved by lklimekWhen every merge requirement is met, the
PR Hygienecheck passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.