Skip to content

docs(consensus): document proposer liveness and round skipping - #1606

Merged
lklimek merged 5 commits into
devfrom
docs/consensus-proposer-liveness
Nov 10, 2026
Merged

lklimek merged 5 commits into
devfrom
docs/consensus-proposer-liveness

Conversation

@Claudius-Maginificent

@Claudius-Maginificent Claudius-Maginificent commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

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 Echo is 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

  • New 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 from consensus.md, spec/consensus/readme.md and book/SUMMARY.md.
  • spec/consensus/: consensus.md (terminology, receive-routine inputs, round state, step diagram, timeouts; source-of-truth branch is now dev), 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.md and wal.md (certificate WAL record, wal-skip-rounds-to-last ignored 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, Message fields 12–14.
  • spec/core/data_structures.md, spec/core/state.md and spec/core/genesis.md: signed message types 0x30/0x31, CONSENSUS_VERSION_2, TimeoutParams fields 7–8 (genesis version.consensus, timeout.proposer_heartbeat/proposer_silence), voting_power_threshold note. The round skip certificate threshold is described as +2/3, the mainnet value, with the quorum type and VotingPowerThreshold setting max(T, R).
  • spec/abci/*: Echo is also used as the proposer's application-readiness probe; ResponseFinalizeBlock.propose_next_block_immediately also skips the wait of a round entered after a skipped round (comment in types.proto, regenerated api.md and types.pb.go comment only).
  • docs/nodes/{metrics,remote-signer,configuration}.md and docs/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

Attribution

🤖 Generated with Claude Code

🤖 Co-authored by Claudius the Magnificent AI Agent

PR Hygiene · 90fcd88

  • Bots — thepastaclaw ✓
  • Self-review — not asked of a bot author
  • Build green
  • Approvals
    • files with no dedicated owner (abci/types/types.pb.go, book/SUMMARY.md, docs/nodes/configuration.md and 22 more) — approved by lklimek

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

lklimek and others added 2 commits November 10, 2026 08:23
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>
@coderabbitai

coderabbitai Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@thepastaclaw

thepastaclaw commented Nov 10, 2026 •

Copy link
Copy Markdown

✅ 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>
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added the waiting-bots Waiting for the review bots to report on this head label Nov 10, 2026
@lklimek lklimek added this to the v2.0 milestone Nov 10, 2026

@thepastaclaw thepastaclaw left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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: normal by gpt-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); agent phase1-reviewer
  • Phase 1 model: muse-spark-1.3-contributor — not quota-gated; passed over gemini-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; agent sol-verifier
  • Phase 2 reviewers: gpt-6.1-sol — general (completed, effort high); agent phase2-reviewer, gpt-6.1-sol — tenderdash-consensus-security (completed, effort high); agent phase2-reviewer, gpt-6.1-sol — general (completed, effort high); agent phase2-reviewer, gpt-6.1-sol — tenderdash-consensus-security (completed, effort high); agent phase2-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.

Comment thread spec/p2p/messages/consensus.md Resolved
@github-actions github-actions Bot removed the waiting-bots Waiting for the review bots to report on this head label Nov 10, 2026
@github-actions

Copy link
Copy Markdown

Policy satisfied — this can merge.
Full checklist in the description.

lklimek and others added 2 commits November 10, 2026 12:49
…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>
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added the waiting-bots Waiting for the review bots to report on this head label Nov 10, 2026

@thepastaclaw thepastaclaw left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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: trivial by gpt-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); agent phase1-reviewer
  • Phase 1 model: glm-5.3-flash — zai quota: 5h 96% left, weekly 90% left; passed over gemini-3.8-flash-high (antigravity quota lookup failed)
  • Fresh verifier: gpt-6.1-sol — final-verifier; agent sol-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.

@github-actions github-actions Bot removed the waiting-bots Waiting for the review bots to report on this head label Nov 10, 2026
@github-actions

Copy link
Copy Markdown

Ready for review — files with no dedicated owner: lklimek or shumkov.
Full checklist in the description.

@github-actions github-actions Bot added the ready-for-human PR Hygiene: bots done, author self-reviewed, awaiting human review label Nov 10, 2026
@github-actions
github-actions Bot requested review from lklimek and shumkov November 10, 2026 15:38
@lklimek
lklimek enabled auto-merge (squash) November 10, 2026 15:57
@github-actions

Copy link
Copy Markdown

Policy satisfied — this can merge.
Full checklist in the description.

@github-actions github-actions Bot removed the ready-for-human PR Hygiene: bots done, author self-reviewed, awaiting human review label Nov 10, 2026
@lklimek
lklimek merged commit 0055c91 into dev Nov 10, 2026
35 checks passed
@lklimek
lklimek deleted the docs/consensus-proposer-liveness branch November 10, 2026 16:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants