Skip to content

feat: re-fork cometbft-bera onto the v0.39.x line#51

Draft
fridrik01 wants to merge 1 commit into
bera-v0.39.xfrom
refork-cometbft-bera-to-0.39
Draft

feat: re-fork cometbft-bera onto the v0.39.x line#51
fridrik01 wants to merge 1 commit into
bera-v0.39.xfrom
refork-cometbft-bera-to-0.39

Conversation

@fridrik01

@fridrik01 fridrik01 commented Jun 26, 2026

Copy link
Copy Markdown

Berachain's CometBFT fork (bera-v1.x) is built on upstream's v1.x line, which has been wound down in favor of v0.39. Security fixes and improvements such as the new libp2p networking layer now land only on v0.39, while our v1.x base is effectively unmaintained and ours to secure alone. Migrating onto v0.39 puts us back on a maintained line, and keeping PBTS and BLS aggregation preserves the block format so the move can be a rolling binary upgrade rather than a coordinated halt-and-swap.

This PR re-forks the berachain CometBFT customizations from the bera-v1.x line (CometBFT v1.x) onto a fresh v0.39.x base, built on tag v0.39.3. That establishes the new bera-v0.39.x line.

It is designed to be forward-compatible, so an existing bera-v1.x network can restart directly on this binary with no state migration. That works because the on-disk state and the consensus sign and wire bytes are kept byte-identical to bera-v1.x, which we verified against a bera-v1.x build (see Testing).

PBTS and BLS signature aggregation are always enabled on this fork.

What's in it

  • PBTS (Proposer-Based Timestamps). The block timestamp now comes from the proposer and is validated against the synchrony parameters, rather than being derived from the median of vote times. The per-vote timestamps are removed from the signed bytes.
  • BLS12-381 signature aggregation. When a validator set is entirely BLS, the individual precommit signatures are collapsed into a single aggregated commit. That commit is gossiped as a whole and lets lagging nodes catch up quickly.
  • NextBlockDelay (ADR-115). The application now sets the delay before the next height starts, replacing the static timeout_commit from config.
  • NextProposerAddress. ProcessProposal now carries the address of the next block's proposer.

One thing is deliberately left out. The #5860 blocksync fix (sender binding plus a signature-count cap) is excluded from this PR. It already lives on upstream cometbft v0.39.x and lands in this fork on the v0.39.4 rebase, described in Base and upstream syncing below.

How to review

Most of the diff is a faithful port of code that already runs in bera-v1.x production, so the review effort is best spent on the parts that had to change specifically for v0.39.

There is one caveat on method. Provenance cannot be shown with a mechanical diff, because the bera-v1.x line moved its packages under internal/ and api/ and renamed the proto packages from cometbft.* to tendermint.*. A file-to-file diff therefore does not line up, and the split below is curated by hand.

The following can be skimmed, since they are faithful ports and need little review:

The following deserve close review, since they exist only because of the back-port and are where bugs would hide:

  • LastCommit is now an interface (VoteSetReader) that holds either a *VoteSet or a whole aggregated *Commit. This required guarded type assertions at roughly six call sites, plus a cmtjson registration so that the /dump_consensus_state endpoint still works. See consensus/state.go, consensus/types/round_state.go, types/block.go, and types/vote_set.go.
  • BLS is build-tag optional, because v0.39 must still compile without blst. An aggregation_none.go stub and a canAggregateCommits fallback gate the aggregated path. See crypto/bls12381/aggregation_none.go and consensus/state.go.
  • ADR-115 is grafted onto a scheduler that previously only knew timeout_commit. The commit timeout is now derived from state.NextBlockDelay, with a fallback to config.TimeoutCommit. See consensus/state.go, state/state.go, and state/execution.go.
  • The proto and toolchain changes include gogofaster codegen, a mapping from wrappers to gogo, moving the authority field from 6 to 8, and a hand-written Wrap and Unwrap for the new Commit message. See buf.gen.yaml and proto/tendermint/consensus/message.go.
  • The validator key wire format changed so that ToProto and FromProto now write pub_key_bytes and pub_key_type, with a fallback to the legacy pub_key. See types/validator.go and crypto/encoding/codec.go.
  • PBTS is plumbed into existing v0.39 call sites. NewProposal now takes the block time, which is threaded through about twenty callers. In addition, privval/file.go drops the obsolete path that re-signed a vote when only its timestamp differed, and a ProposalTimestampDifference metric was added. See types/proposal.go, privval/file.go, and consensus/metrics.go.

The three features are coupled through the VoteSetReader change, which is why they ship as a single PR rather than three.

Wire and upgrade compatibility

  • The on-disk state and the consensus sign and wire bytes are byte-identical to bera-v1.x, so an existing network can restart on this binary.
  • An upgrade is restart-style rather than a mixed-set rollout. The old and new binaries use different p2p type-URLs (cometbft.* versus tendermint.*) and cannot gossip consensus messages to each other.
  • The change is state-breaking relative to a pristine v0.39.3, owing to the new parameters and the removal of vote timestamps. That is the intended bera shape.

Base and upstream syncing

The bera-v0.39.x line is branched from a tagged upstream release, the CometBFT v0.39.3 tag, which gives it a fixed and well-known starting point on the upstream v0.39.x line. It was created with:

git remote add upstream https://github.com/cometbft/cometbft.git
git fetch upstream --tags
git checkout -b bera-v0.39.x v0.39.3

Future upstream releases are adopted by rebasing onto the next release tag. For example, when upstream cuts v0.39.4:

git fetch upstream --tags
git rebase v0.39.4 bera-v0.39.x
# resolve any conflicts in favor of the bera customizations, then rebuild and test
git push --force-with-lease origin bera-v0.39.x

Rebasing onto a tagged release keeps the base at a known and vetted upstream version. Urgent fixes that land upstream between releases, such as #5860, are cherry-picked individually until the next tagged release includes them. Rebasing onto v0.39.4, which already contains #5860, is the hard gate before any production release.

Testing

  • The fork builds both with and without -tags bls12381.
  • The test suite is at parity with a pristine v0.39.3. The one remaining flake reproduces on the pristine tag as well, so it is not a regression.
  • Compatibility with bera-v1.x was verified out of tree. A one-time harness captured the exact bytes and hashes a bera-v1.x build produces and confirmed this port produces identical output, covering the vote and proposal sign bytes, the aggregated-commit hash and its proto encoding, the block header hash, the consensus params hash, the persisted state proto, and a full real aggregated commit. That harness is not part of this PR, so a committed vectors test could be added later to make it reproducible in CI.

New tests added by this PR:

@fridrik01 fridrik01 self-assigned this Jun 26, 2026
@fridrik01 fridrik01 force-pushed the refork-cometbft-bera-to-0.39 branch 2 times, most recently from c800213 to 518c996 Compare June 26, 2026 10:16
Re-forks the berachain CometBFT customizations from the bera-v1.x line
onto a fresh v0.39.x base (tag v0.39.3), establishing the bera-v0.39.x
line.

Brings over:
 - Proposer-Based Timestamps (PBTS) + removal of per-vote timestamps
 - BLS12-381 signature aggregation (aggregated commits + fast catch-up)
 - NextBlockDelay (ADR-115) and NextProposerAddress in ProcessProposal
 - validator pub-key wire format, Synchrony/Feature params, and supporting
   proto

Forward-compatible: existing bera-v1.x networks can restart on this
binary (on-disk state and consensus sign/wire bytes are byte-identical).

Upstream cometbft#5860 is intentionally excluded (arrives via the v0.39.4 rebase).
@fridrik01 fridrik01 force-pushed the refork-cometbft-bera-to-0.39 branch from 518c996 to ecb80ec Compare June 26, 2026 10:27
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.

1 participant