Skip to content

feat(consensus)!: specify full consensus parameter commitment and remove app version parameter - #1593

Draft
lklimek wants to merge 17 commits into
devfrom
docs/v2-consensus-params-commitment
Draft

lklimek wants to merge 17 commits into
devfrom
docs/v2-consensus-params-commitment

Conversation

@lklimek

@lklimek lklimek commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

TL;DR: Specify how every consensus parameter becomes verifiable from signed block headers, activated by consensus version 2, and remove the deprecated application version from consensus parameters.

User story

As a node operator, I want a node that joins the network through state sync to verify every network setting it receives, so that a malicious or compromised source cannot make it halt, vote differently or diverge.

As an application developer, I want one place that sets the application version, so that blocks and node state cannot disagree about it.

Scenario

Base flow

A node bootstraps with state sync and receives the network's consensus parameters from an RPC server or peers.

Actual behavior

Only block size, block gas and the consensus version are covered by the signed parameter hash. All other settings (evidence limits, validator key types, synchrony bounds, timeouts, mempool recheck) are accepted without verification and stay in the node's state; a forged value typically makes the node halt later, and nothing detects it. The application version can come from two places that may disagree.

Expected behavior

Once a network switches to consensus version 2, the signed hash covers every parameter, so forged settings are rejected at bootstrap. The application version comes only from the application's block proposal response.

Detailed discussion

What was done

  • Specification spec/consensus/consensus-params-commitment.md (linked from the spec index, consensus page and book):
    • full, domain-separated parameter snapshot HashedParamsV2 (15 fields, canonical encoding);
    • selection by VersionParams.consensus_version: version 2 and higher use the full hash, lower versions keep the legacy hash; each parameter set is hashed by its own version, so block H-1 already signs the full next-parameter hash;
    • consensus version must never decrease (today any change is accepted, including 1 to 0), and unknown versions are rejected; validation is specified, not implemented here;
    • version.BlockProtocol is not bumped: activation is only through the consensus version;
    • impact of forged parameters today, per parameter, including the risk of a voting-power threshold below 2/3 (minority polkas can unlock honest validators across rounds);
    • remaining implementation steps and acceptance scenarios.
  • Protobuf: HashedParamsV2 and CONSENSUS_VERSION_2 added; VersionParams.app_version removed with field 1 and its name reserved. Bindings and spec/abci/api.md regenerated.
  • Go (application version only): State.Version.Consensus.App follows the committed block header instead of consensus parameters; rollback takes it from the block it rolls back to; kvstore and the e2e app no longer set the removed field. InitChain no longer resets the state application version to the parameter value, and kvstore InitChain no longer returns a version group (which reset a genesis consensus version to 0).
  • Not implemented here: computing or verifying the full hash, the consensus-version validation rules, taking NodeInfo application version from Info, relaxing state-sync verifyApp to >=.

Follow-up outside this repository

  • Dash Platform (rs-drive-abci InitChain): determine the initial protocol version per network or from configuration instead of RequestInitChain.consensus_params.version.app_version; required before Platform upgrades to this Tenderdash.
  • dashmate status: stop reading the active protocol version from /consensus_params.

Coordination

#1572 and #1583 also use CONSENSUS_VERSION_2. The number stays 2 for now; consensus-version numbering must be reconciled before any of them is activated.

Breaking changes

  • ABCI: ConsensusParams.version.app_version no longer exists; applications must stop setting it (old applications sending it are ignored by protobuf decoding). Genesis files containing it still load, but the value is ignored.
  • InitChain no longer carries an application version, and Tenderdash provides no replacement: the application must determine its initial protocol version itself. Dash Platform reads it from RequestInitChain.consensus_params.version.app_version today and must switch (e.g. per network or from its configuration) before upgrading; otherwise a node syncing from genesis starts at the wrong protocol version and halts on an app-hash mismatch.
  • /consensus_params RPC no longer reports an application version; tools reading it (e.g. dashmate status) must use another source.
  • Activating consensus version 2 changes consensus hashes from that height and requires a coordinated upgrade before height H-1. Historical blocks keep the legacy hash.

Testing

  • New tests (each failed before the change, or against an injected regression): TestStateUpdateTakesAppVersionFromCommittedHeader, extended TestRollback, TestGenesisDocFromJSON_IgnoresRemovedAppVersion, TestHandshakeInitChainKeepsInfoAppVersion, TestConsensusParamsDecodeIgnoresRemovedAppVersion.
  • go test on internal/state/..., types, abci/example/kvstore, internal/rpc/core, proto/tendermint/types, internal/statesync, internal/blocksync, test/e2e/app, node, and replay/handshake/rollback tests in internal/consensus pass.
  • go build ./... and go vet pass after merging dev; protobuf regeneration is reproducible (second run leaves the tree clean); buf lint, make prepare-docs and markdownlint pass.
  • Not run locally: golangci-lint (local versions do not support Go 1.27) and clang-format for protobuf files.

🤖 Co-authored by Claudius the Magnificent AI Agent

🤖 Generated with Claude Code

lklimek and others added 2 commits October 21, 2026 12:25
* refactor(db)!: own GoLevelDB and memory database adapters

Retain the GoLevelDB, MemDB and PrefixDB adapters from cometbft-db v1.0.4
under libs/db, with their license, provenance and contract tests. Upstream
plans to retire the shared wrapper and discourages new dependencies on it.

Preserve engine versions, persistence behavior, node configuration and SQL
indexing while removing unused backend registrations and dependencies.
Verify old-to-local-to-old persisted data compatibility and storage race tests.

BREAKING CHANGE: exported DB APIs now use Tenderdash's libs/db interfaces;
custom providers must update imports or adapt their Batch/Iterator return types.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Codex GPT-6 <noreply@openai.com>

* fix(db): retain upstream attribution and modification notices

Mark the eight modified upstream files and preserve cometbft-db's tm-db
ancestry while retaining the original Apache license verbatim.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Claude GPT-6 <noreply@anthropic.com>

* fix(db): release debug iterators and characterize empty values

Release the GoLevelDB Print iterator before returning. Replace the skipped
empty-value check with explicit backend Get/Has expectations and document
the inherited difference tracked in issue #1554.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Claude GPT-6 <noreply@anthropic.com>

---------

Co-authored-by: Codex GPT-6 <noreply@openai.com>
Co-authored-by: Claude GPT-6 <noreply@anthropic.com>
Define a draft canonical full snapshot, independent commitment selector,
activation boundary, historical verification and state-sync trust rules.
Add the source protobuf schema and an implementation and verification plan.
Runtime support and generated bindings are intentionally deferred.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Codex GPT-6 <noreply@openai.com>
@coderabbitai

coderabbitai Bot commented Nov 4, 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

@lklimek
lklimek changed the base branch from v1.9-dev to v1.8-dev November 4, 2026 16:28
@thepastaclaw

thepastaclaw commented Nov 4, 2026 •

Copy link
Copy Markdown

🕓 Review not started yet because this PR is a draft.

  • Request normal review — click when the PR is ready for review.
  • Request priority review — click to move this review to the front of the queue.

Commit f3a81c2. Normal review starts when eligible; priority review starts as soon as a slot is available.

Retain v1.8-dev runtime and dependency state and its current specification,
with only the full-commitment proposal and its two discovery links added.
Conflict resolutions approved by the maintainer.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Codex GPT-6 <noreply@openai.com>
@lklimek
lklimek marked this pull request as ready for review November 4, 2026 16:31
@lklimek
lklimek marked this pull request as draft November 4, 2026 16:31
@Claudius-Maginificent Claudius-Maginificent added priority: low Low priority — nice to have priority: medium Medium priority and removed priority: low Low priority — nice to have labels Nov 5, 2026
@lklimek lklimek added this to the v2.0 milestone Nov 6, 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 draft clearly separates proposed consensus behavior from current runtime behavior, but the production protobuf changes leave checked-in bindings inconsistent with their source schema. Exact-head CI confirms that this change causes check-proto to fail; the other build, test, lint, and documentation checks pass, while PR Hygiene remains pending. Static verification also confirmed a minor navigation omission; no builds or tests were run locally.

🔴 1 blocking | 💬 1 nitpick(s)

1 finding(s) not shown inline (the lines are not part of this PR's diff)

💬 Nitpick: Add the draft to the consensus section's contents
spec/consensus/readme.md:15-22

The new chapter is linked from spec/README.md, spec/consensus/consensus.md, and book/SUMMARY.md, but is missing from this consensus-section Contents list. Add a direct link here as well so the section index exposes the new design alongside the other consensus documents. The chapter remains reachable through the overview, so this is a navigation consistency issue rather than a publication blocker.

source: muse-spark-1.3-contributor (phase1-reviewer: general)

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); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)

  • Triage: normal by gpt-6.1-sol (effort low) — The normative commitment specification and protobuf source schema require substantive design review, but the diff does not implement runtime consensus, hashing, or activation changes and therefore does not meet the critical tier.
  • 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)
  • 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
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `proto/tendermint/types/params.proto`:
- [BLOCKING] proto/tendermint/types/params.proto:24-27: Keep production protobuf sources and generated bindings consistent
  This adds ConsensusParams.commitment_version and HashedParamsV2 to the production schema, but params.pb.go contains neither addition. Consumers generating from the source therefore receive a different API from consumers using the checked-in Go bindings. AGENTS.md identifies proto/ as the source of truth and directs protobuf changes to be regenerated with make proto-gen. The exact-head check-proto log independently confirms the mismatch: Actions run 42231728858 reports changes to canonical.pb.go, params.pb.go, and types.pb.go, totaling 1,232 insertions and 143 deletions, then exits with "Protobuf generated code requires update". Deferring runtime implementation is reasonable for this design draft, but does not justify introducing inconsistent production schema artifacts. Include the regenerated bindings without enabling FULL behavior, or move the proposed schema into an inert specification example until generation is ready.

In `spec/consensus/readme.md`:
- [NITPICK] spec/consensus/readme.md:15-22: Add the draft to the consensus section's contents
  The new chapter is linked from spec/README.md, spec/consensus/consensus.md, and book/SUMMARY.md, but is missing from this consensus-section Contents list. Add a direct link here as well so the section index exposes the new design alongside the other consensus documents. The chapter remains reachable through the overview, so this is a navigation consistency issue rather than a publication blocker.

Comment thread proto/tendermint/types/params.proto Resolved
…e labels

Specify complete removal of ConsensusParams.Version.AppVersion: reserve
VersionParams field 1 and HashedParamsV2 tag 9, make
ResponsePrepareProposal.app_version the only source of Header.Version.App,
remove State.Version.Consensus.App, source NodeInfo app version from Info and
relax state-sync verifyApp to Info.app_version >= header app version.

Rename the spec to consensus-params-commitment.md and remove release labels
from the chapter, links and proto comments; HashedParamsV2 names the snapshot
schema only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lklimek lklimek modified the milestones: v2.0, v3.0 Nov 6, 2026
lklimek and others added 8 commits November 6, 2026 15:29
Drop the separate commitment_version selector. CONSENSUS_VERSION_2 keeps
version 1 proposer selection and hashes the complete HashedParamsV2
snapshot; lower versions keep the legacy hash. Specify the missing range
and no-downgrade checks and activation through consensus_param_updates.

Renumber HashedParamsV2 contiguously with consensus_version at tag 1.
Keep VersionParams.app_version as deprecated until the implementation
reserves it, and regenerate Go bindings and the ABCI API reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reserve VersionParams field 1 (app_version) and drop
types.VersionParams.AppVersion with its conversions. State takes its
application version from the committed block header, which the proposer's
PrepareProposal response sets, and rollback takes it from the header of
the block rolled back to. The kvstore example and e2e app stop sending
the field. Genesis JSON with consensus_params.version.app_version still
loads; the key is ignored.

BREAKING CHANGE: ABCI applications can no longer set the application
version through consensus parameter updates; field 1 is ignored on decode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…l bump

Reject any consensus-version decrease, not only below 2, and record that
this changes today's behavior. State that activation must not bump
version.BlockProtocol and why. Describe which parts of the app version
removal this change implements and which remain.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
State-synced nodes take every consensus parameter except block size,
gas, consensus version and the pinned voting threshold on trust. List
per-parameter effects of forged values, why they persist and go
undetected, and how the full commitment closes the gap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Precommit finalization needs the DKG recovery threshold, but prevote
polkas use the configurable threshold, so a low threshold lets a
minority unlock honest validators across rounds. Record why the
state-sync pin must not be dropped before the full commitment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Point to the #1052 override that permits thresholds below 2/3 through
genesis or consensus_param_updates, and state that state sync cannot
forge the threshold because it is pinned to the trusted local value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lklimek lklimek changed the title docs(consensus): define full parameter commitments for v2.0 feat(consensus)!: specify full consensus parameter commitment and remove app version parameter Nov 6, 2026
lklimek and others added 2 commits November 6, 2026 16:29
Check that the handshake keeps the application version from
ResponseInfo when InitChain returns a version parameter group, and that
ConsensusParams encoded with VersionParams field 1 still decode with the
field dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sion

InitChain carries no application version and Tenderdash adds no
replacement, so the application determines its initial protocol version
itself. Record the Dash Platform dependency and the required order of
upgrades, and stop documenting app_version as a genesis consensus
parameter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

priority: medium Medium priority

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants