feat: stable block time

consensus/cometbft/service/block_delay.go

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: BUSL-1.1
+//
+// Copyright (C) 2025, Berachain Foundation. All rights reserved.
+// Use of this software is governed by the Business Source License included
+// in the LICENSE file of this repository and at www.mariadb.com/bsl11.
+//
+// ANY USE OF THE LICENSED WORK IN VIOLATION OF THIS LICENSE WILL AUTOMATICALLY
+// TERMINATE YOUR RIGHTS UNDER THIS LICENSE FOR THE CURRENT AND ALL OTHER
+// VERSIONS OF THE LICENSED WORK.
+//
+// THIS LICENSE DOES NOT GRANT YOU ANY RIGHT IN ANY TRADEMARK OR LOGO OF
+// LICENSOR OR ITS AFFILIATES (PROVIDED THAT YOU MAY USE A TRADEMARK OR LOGO OF
+// LICENSOR AS EXPRESSLY REQUIRED BY THIS LICENSE).
+//
+// TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+// AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+// EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+// TITLE.
+
+package cometbft
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/berachain/beacon-kit/primitives/encoding/json"
+)
+
+// maxDelayBetweenBlocks is the maximum delay between two consecutive blocks.
+// If the last block time minus the previous block time is greater than
+// maxDelayBetweenBlocks, then we reset `FinalizeBlockResponse.NextBlockDelay`
+// to default.
+//
+// This is needed because the network may stall for a long time and we don't
+// want to rush in new blocks as the network resumes its operation.
+const maxDelayBetweenBlocks = 30 * time.Minute
+
+type blockDelay struct {
+	// - genesis time if height is 0 OR
+	// - block time of the last block if height > 0 and time between blocks is
+	// greater than maxDelayBetweenBlocks.
+	InitialTime time.Time `json:"initial_time"`
+
+	// - InitChainRequest.InitialHeight OR
+	// - last block height if time between blocks is greater than maxDelayBetweenBlocks.
+	InitialHeight int64 `json:"initial_height"`
+
+	// PreviousBlockTime is the time of the previous block.
+	PreviousBlockTime time.Time `json:"previous_block_time"`
+}
+
+// CONTRACT: called only once upon genesis during or after InitChain.
+func blockDelayUponGenesis(genesisTime time.Time, initialHeight int64) *blockDelay {
+	return &blockDelay{
+		InitialTime:       genesisTime,
+		InitialHeight:     initialHeight,
+		PreviousBlockTime: genesisTime,
+	}
+}
+
+func blockDelayFromBytes(
+	bz []byte,
+) *blockDelay {
+	var d blockDelay
+	if err := json.Unmarshal(bz, &d); err != nil {
+		panic(fmt.Errorf("failed to unmarshal blockDelay: %w", err))
+	}
+	return &d
+}
+
+// Next returns the duration to wait before proposing the next block.
+func (d *blockDelay) Next(curBlockTime time.Time, curBlockHeight int64,
+	targetBlockTime time.Duration) time.Duration {
+	// Until `timeout_commit` is removed from the CometBFT config,
+	// `FinalizeBlockResponse.NextBlockDelay` can't be exactly 0. If it's set to
+	// 0, then `timeout_commit` from the config will be used, which is not what
+	// we want since we're trying to control the block time.
+	const noDelay = 1 * time.Microsecond
+
+	// Reset the initial time and height if the time between blocks is greater
+	// than maxDelayBetweenBlocks.
+	if curBlockTime.Sub(d.PreviousBlockTime) > maxDelayBetweenBlocks {
+		d.InitialTime = curBlockTime
+		d.InitialHeight = curBlockHeight - 1
+	}
+
+	t := d.InitialTime.Add(targetBlockTime * time.Duration(curBlockHeight-d.InitialHeight))
+	if curBlockTime.Before(t) {
+		return t.Sub(curBlockTime)
+	}
+
+	// Update the previous block time.
+	d.PreviousBlockTime = curBlockTime
+
+	return noDelay
+}
+
+// ToBytes converts the blockDelay to bytes.
+func (d *blockDelay) ToBytes() []byte {
+	bz, err := json.Marshal(d)
+	if err != nil {
+		panic(fmt.Errorf("failed to marshal blockDelay: %w", err))
+	}
+	return bz
+}

consensus/cometbft/service/block_delay_test.go

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: BUSL-1.1
+//
+// Copyright (C) 2025, Berachain Foundation. All rights reserved.
+// Use of this software is governed by the Business Source License included
+// in the LICENSE file of this repository and at www.mariadb.com/bsl11.
+//
+// ANY USE OF THE LICENSED WORK IN VIOLATION OF THIS LICENSE WILL AUTOMATICALLY
+// TERMINATE YOUR RIGHTS UNDER THIS LICENSE FOR THE CURRENT AND ALL OTHER
+// VERSIONS OF THE LICENSED WORK.
+//
+// THIS LICENSE DOES NOT GRANT YOU ANY RIGHT IN ANY TRADEMARK OR LOGO OF
+// LICENSOR OR ITS AFFILIATES (PROVIDED THAT YOU MAY USE A TRADEMARK OR LOGO OF
+// LICENSOR AS EXPRESSLY REQUIRED BY THIS LICENSE).
+//
+// TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+// AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+// EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+// TITLE.
+
+package cometbft
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestBlockDelayUponGenesis(t *testing.T) {
+	genesisTime := time.Now()
+	initialHeight := int64(1)
+
+	d := blockDelayUponGenesis(genesisTime, initialHeight)
+
+	assert.Equal(t, genesisTime, d.InitialTime)
+	assert.Equal(t, initialHeight, d.InitialHeight)
+	assert.Equal(t, genesisTime, d.PreviousBlockTime)
+}
+
+func TestBlockDelayFromBytes(t *testing.T) {
+	d1 := &blockDelay{
+		InitialTime:       time.Now().Add(-10 * time.Minute),
+		InitialHeight:     5,
+		PreviousBlockTime: time.Now().Add(-5 * time.Minute),
+	}
+
+	b := d1.ToBytes()
+	d2 := blockDelayFromBytes(b)
+
+	assert.Equal(t, d1.InitialTime.Unix(), d2.InitialTime.Unix())
+	assert.Equal(t, d1.InitialHeight, d2.InitialHeight)
+	assert.Equal(t, d1.PreviousBlockTime.Unix(), d2.PreviousBlockTime.Unix())
+}
+
+func TestBlockDelayNext_NoDelay(t *testing.T) {
+	genesisTime := time.Now()
+	initialHeight := int64(1)
+	d := blockDelayUponGenesis(genesisTime, initialHeight)
+
+	curBlockTime := genesisTime.Add(10 * time.Second)
+	curBlockHeight := int64(2)
+	targetBlockTime := 5 * time.Second
+	delay := d.Next(curBlockTime, curBlockHeight, targetBlockTime)
+
+	assert.Equal(t, 1*time.Microsecond, delay)
+}
+
+func TestBlockDelayNext_WithDelay(t *testing.T) {
+	genesisTime := time.Now()
+	initialHeight := int64(1)
+	d := blockDelayUponGenesis(genesisTime, initialHeight)
+
+	curBlockTime := genesisTime.Add(8 * time.Second)
+	curBlockHeight := int64(3)
+	targetBlockTime := 5 * time.Second
+	delay := d.Next(curBlockTime, curBlockHeight, targetBlockTime)
+
+	assert.Equal(t, delay, 2*time.Second)
+}
+
+func TestBlockDelayNext_ResetOnStall(t *testing.T) {
+	genesisTime := time.Now()
+	initialHeight := int64(1)
+	d := blockDelayUponGenesis(genesisTime, initialHeight)
+
+	curBlockTime := genesisTime.Add(maxDelayBetweenBlocks + 1*time.Minute)
+	curBlockHeight := int64(10)
+	targetBlockTime := 5 * time.Second
+
+	delay := d.Next(curBlockTime, curBlockHeight, targetBlockTime)
+
+	assert.Equal(t, d.InitialTime, curBlockTime)
+	assert.Equal(t, d.InitialHeight, curBlockHeight-1)
+	assert.Equal(t, delay, targetBlockTime)
+}
+
+func TestBlockDelaySerialization(t *testing.T) {
+	d := &blockDelay{
+		InitialTime:       time.Now(),
+		InitialHeight:     10,
+		PreviousBlockTime: time.Now().Add(-1 * time.Minute),
+	}
+
+	b := d.ToBytes()
+	var d2 blockDelay
+	err := json.Unmarshal(b, &d2)
+	assert.NoError(t, err)
+	assert.Equal(t, d.InitialTime.Unix(), d2.InitialTime.Unix())
+	assert.Equal(t, d.InitialHeight, d2.InitialHeight)
+	assert.Equal(t, d.PreviousBlockTime.Unix(), d2.PreviousBlockTime.Unix())
+}

consensus/cometbft/service/commit.go

@@ -48,6 +48,10 @@ func (s *Service[LoggerT]) commit(
 
 	s.finalizeBlockState = nil
 
+	if err := s.sm.SaveBlockDelay(s.blockDelay.ToBytes()); err != nil {
+		panic(fmt.Errorf("failed to save block delay: %w", err))
+	}
+
 	return &cmtabci.CommitResponse{
 		RetainHeight: retainHeight,
 	}, nil

consensus/cometbft/service/configs.go

@@ -37,7 +37,6 @@ const ( // appeases mnd
 	minTimeoutPropose   = 2000 * time.Millisecond
 	minTimeoutPrevote   = 2000 * time.Millisecond
 	minTimeoutPrecommit = 2000 * time.Millisecond
-	minTimeoutCommit    = 500 * time.Millisecond
 
 	maxBlockSize = 100 * 1024 * 1024
 
@@ -80,7 +79,8 @@ func DefaultConfig() *cmtcfg.Config {
 	consensus.TimeoutPropose = minTimeoutPropose
 	consensus.TimeoutPrevote = minTimeoutPrevote
 	consensus.TimeoutPrecommit = minTimeoutPrecommit
-	consensus.TimeoutCommit = minTimeoutCommit
+	// DEPRECATED: we use NextBlockDelay now
+	consensus.TimeoutCommit = 0
 
 	cfg.Storage.DiscardABCIResponses = true
 
@@ -149,13 +149,6 @@ func validateConfig(cfg *cmtcfg.Config) error {
 		)
 	}
 
-	if cfg.Consensus.TimeoutCommit < minTimeoutCommit {
-		return fmt.Errorf("%w, config timeout propose %v, min requested %v",
-			ErrInvalidaConfig,
-			cfg.Consensus.TimeoutCommit,
-			minTimeoutCommit,
-		)
-	}
 	return nil
 }
 

consensus/cometbft/service/finalize_block.go

@@ -89,11 +89,29 @@ func (s *Service[LoggerT]) finalizeBlockInternal(
 		return nil, err
 	}
 
+	// Special case: height > 0, but blockDelay record doesn't exist in DB.
+	//
+	// NOTE: all nodes must enable this feature from the same height (requires
+	// coordinated upgrade).
+	if s.blockDelay == nil {
+		s.blockDelay = blockDelayUponGenesis(
+			req.Time,
+			req.Height-1,
+		)
+	}
+
+	// Calculate the delay for the next block.
+	delay := s.blockDelay.Next(
+		req.Time,
+		req.Height,
+		s.targetBlockTime)
+
 	cp := s.cmtConsensusParams.ToProto()
 	return &cmtabci.FinalizeBlockResponse{
 		TxResults:             txResults,
 		ValidatorUpdates:      valUpdates,
 		ConsensusParamUpdates: &cp,
+		NextBlockDelay:        delay,
 	}, nil
 }
 

consensus/cometbft/service/init_chain.go

@@ -93,6 +93,11 @@ func (s *Service[LoggerT]) initChain(
 		return nil, err
 	}
 
+	s.blockDelay = blockDelayUponGenesis(
+		req.Time,
+		req.InitialHeight,
+	)
+
 	// NOTE: We don't commit, but FinalizeBlock for block InitialHeight starts
 	// from
 	// this FinalizeBlockState.

consensus/cometbft/service/options.go

@@ -21,6 +21,8 @@
 package cometbft
 
 import (
+	"time"
+
 	pruningtypes "cosmossdk.io/store/pruning/types"
 	storetypes "cosmossdk.io/store/types"
 	"github.com/berachain/beacon-kit/log"
@@ -81,3 +83,13 @@ func SetChainID[
 ](chainID string) func(*Service[LoggerT]) {
 	return func(s *Service[LoggerT]) { s.chainID = chainID }
 }
+
+// SetTargetBlockTime returns a Service option function that sets the desired
+// block time (e.g., 2s). Note that it CAN'T be lower than the minimal (floor)
+// block time in the network, which is comprised of the time to a) propose a
+// new block b) gather 2/3+ prevotes c) gather 2/3+ precommits.
+func SetTargetBlockTime[
+	LoggerT log.AdvancedLogger[LoggerT],
+](t time.Duration) func(*Service[LoggerT]) {
+	return func(bs *Service[LoggerT]) { bs.setTargetBlockTime(t) }
+}

consensus/cometbft/service/service.go

@@ -24,6 +24,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"time"
 
 	storetypes "cosmossdk.io/store/types"
 	"github.com/berachain/beacon-kit/beacon/blockchain"
@@ -98,6 +99,12 @@ type Service[
 	minRetainBlocks uint64
 
 	chainID string
+
+	// calculates block delay for the next block
+	blockDelay *blockDelay
+
+	// targetBlockTime is the desired block time. Doesn't change after start.
+	targetBlockTime time.Duration
 }
 
 func NewService[
@@ -147,6 +154,15 @@ func NewService[
 		panic(fmt.Errorf("failed loading latest version: %w", err))
 	}
 
+	// Load block delay
+	bz, err := s.sm.LoadBlockDelay()
+	if err != nil {
+		panic(fmt.Errorf("failed loading block delay: %w", err))
+	}
+	if bz != nil {
+		s.blockDelay = blockDelayFromBytes(bz)
+	}
+
 	return s
 }
 
@@ -262,6 +278,11 @@ func (s *Service[_]) setMinRetainBlocks(minRetainBlocks uint64) {
 	s.minRetainBlocks = minRetainBlocks
 }
 
+// setTargetBlockTime sets the desired block time.
+func (s *Service[_]) setTargetBlockTime(t time.Duration) {
+	s.targetBlockTime = t
+}
+
 func (s *Service[_]) setInterBlockCache(
 	cache storetypes.MultiStorePersistentCache,
 ) {

consensus/cometbft/service/state/state.go

@@ -92,3 +92,19 @@ func (sm *Manager) Close() error {
 func (sm *Manager) CommitMultiStore() storetypes.CommitMultiStore {
 	return sm.cms
 }
+
+var blockDelayKey = []byte("blockDelay")
+
+// LoadBlockDelay loads the block delay bytes from the database.
+//
+// see next_block_delay.go
+func (sm *Manager) LoadBlockDelay() ([]byte, error) {
+	return sm.db.Get(blockDelayKey)
+}
+
+// SaveBlockDelay saves the block delay bytes to the database.
+//
+// see next_block_delay.go
+func (sm *Manager) SaveBlockDelay(bz []byte) error {
+	return sm.db.Set(blockDelayKey, bz)
+}