ACP-226: Apply Min Block Delay to Block Builder

RELEASES.md

@@ -4,9 +4,11 @@
 
 - Removed deprecated flags `coreth-admin-api-enabled`, `coreth-admin-api-dir`, `tx-regossip-frequency`, `tx-lookup-limit`. Use `admin-api-enabled`, `admin-api-dir`, `regossip-frequency`, `transaction-history` instead.
 - Enabled RPC batch limits by default, and configurable with `batch-request-limit` and `batch-max-response-size`.
-- Implement ACP-226: Set expected block gas cost to 0 in Granite network upgrade, removing block gas cost requirements for block building.
-- Implement ACP-226: Add `timeMilliseconds` (Unix uint64) timestamp to block header for Granite upgrade.
-- Implement ACP-226: Add `minDelayExcess` (uint64) to block header for Granite upgrade.
+- ACP-226:
+  - Set expected block gas cost to 0 in Granite network upgrade, removing block gas cost requirements for block building.
+  - Add `timeMilliseconds` (Unix uint64) timestamp to block header for Granite upgrade.
+  - Add `minDelayExcess` (uint64) to block header for Granite upgrade.
+  - Add minimum block building delays to conform the block builder to ACP-226 requirements.
 - Update go version to 1.24.7
 
 ## [v0.15.3](https://github.com/ava-labs/coreth/releases/tag/v0.15.3)

plugin/evm/block_builder.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/ava-labs/avalanchego/snow"
 	"github.com/ava-labs/avalanchego/utils/lock"
+	"github.com/ava-labs/avalanchego/utils/timer/mockable"
 	"github.com/ava-labs/libevm/common"
 	"github.com/ava-labs/libevm/core/types"
 	"github.com/ava-labs/libevm/log"
@@ -18,17 +19,25 @@ import (
 
 	"github.com/ava-labs/coreth/core"
 	"github.com/ava-labs/coreth/core/txpool"
+	"github.com/ava-labs/coreth/params/extras"
+	"github.com/ava-labs/coreth/plugin/evm/customheader"
+	"github.com/ava-labs/coreth/plugin/evm/customtypes"
 	"github.com/ava-labs/coreth/plugin/evm/extension"
 
 	commonEng "github.com/ava-labs/avalanchego/snow/engine/common"
 )
 
-// Minimum amount of time to wait after building a block before attempting to build a block
-// a second time without changing the contents of the mempool.
-const MinBlockBuildingRetryDelay = 500 * time.Millisecond
+const (
+	// Minimum amount of time to wait after attempting/build a block before attempting to build another block
+	// This is only applied for retrying to build a block after a initial minimum delay has passed.
+	// The initial minimum delay is applied according to parent minDelayExcess (if available)
+	RetryDelay = 100 * time.Millisecond
+)
 
 type blockBuilder struct {
-	ctx *snow.Context
+	clock       *mockable.Clock
+	ctx         *snow.Context
+	chainConfig *extras.ChainConfig
 
 	txPool       *txpool.TxPool
 	extraMempool extension.BuilderMempool
@@ -51,10 +60,12 @@ type blockBuilder struct {
 func (vm *VM) NewBlockBuilder(extraMempool extension.BuilderMempool) *blockBuilder {
 	b := &blockBuilder{
 		ctx:          vm.ctx,
+		chainConfig:  vm.chainConfigExtra(),
 		txPool:       vm.txPool,
 		extraMempool: extraMempool,
 		shutdownChan: vm.shutdownChan,
 		shutdownWg:   &vm.shutdownWg,
+		clock:        vm.clock,
 	}
 	b.pendingSignal = lock.NewCond(&b.buildBlockLock)
 	return b
@@ -64,7 +75,7 @@ func (vm *VM) NewBlockBuilder(extraMempool extension.BuilderMempool) *blockBuild
 func (b *blockBuilder) handleGenerateBlock(currentParentHash common.Hash) {
 	b.buildBlockLock.Lock()
 	defer b.buildBlockLock.Unlock()
-	b.lastBuildTime = time.Now()
+	b.lastBuildTime = b.clock.Time()
 	b.lastBuildParentHash = currentParentHash
 }
 
@@ -124,20 +135,19 @@ func (b *blockBuilder) waitForEvent(ctx context.Context, currentHeader *types.He
 	if err != nil {
 		return 0, err
 	}
-	timeSinceLastBuildTime := time.Since(lastBuildTime)
-	isRetry := lastBuildParentHash == currentHeader.ParentHash
-	// 1. if this is not a retry
-	// 2. if this is the first time we try to build a block
-	// 3. if the time since the last build is greater than the minimum retry delay
-	// then we can build a block immediately.
-	if !isRetry || lastBuildTime.IsZero() || timeSinceLastBuildTime >= MinBlockBuildingRetryDelay {
-		b.ctx.Log.Debug("Last time we built a block was long enough ago or this is not a retry, no need to wait",
-			zap.Duration("timeSinceLastBuildTime", timeSinceLastBuildTime),
-			zap.Bool("isRetry", isRetry),
-		)
+	timeUntilNextBuild, err := b.calculateBlockBuildingDelay(
+		lastBuildTime,
+		lastBuildParentHash,
+		currentHeader,
+	)
+	if err != nil {
+		return 0, err
+	}
+	if timeUntilNextBuild <= 0 {
+		b.ctx.Log.Debug("Last time we built a block was long enough ago or this is not a retry, no need to wait")
 		return commonEng.PendingTxs, nil
 	}
-	timeUntilNextBuild := MinBlockBuildingRetryDelay - timeSinceLastBuildTime
+
 	b.ctx.Log.Debug("Last time we built a block was too recent, waiting",
 		zap.Duration("timeUntilNextBuild", timeUntilNextBuild),
 	)
@@ -161,3 +171,49 @@ func (b *blockBuilder) waitForNeedToBuild(ctx context.Context) (time.Time, commo
 	}
 	return b.lastBuildTime, b.lastBuildParentHash, nil
 }
+
+// minNextBlockTime calculates the minimum next block time based on the current header and the chain config.
+func (b *blockBuilder) minNextBlockTime(parent *types.Header, config *extras.ChainConfig) (time.Time, error) {
+	parentExtra := customtypes.GetHeaderExtra(parent)
+	// If the parent header has no min delay excess, there is nothing to wait for, because the rule does not apply
+	// to the block to be built.
+	if parentExtra.MinDelayExcess == nil {
+		return time.Time{}, nil
+	}
+	acp226DelayExcess, err := customheader.MinDelayExcess(config, parent, b.clock.Unix(), nil)
+	if err != nil {
+		return time.Time{}, err
+	}
+	// This should not happen because parent header is in Granite,
+	// but just checking nil pointer to be safe.
+	if acp226DelayExcess == nil {
+		return time.Time{}, nil
+	}
+	parentTime := customtypes.BlockTime(parent)
+	requiredDelay := time.Duration(acp226DelayExcess.Delay()) * time.Millisecond
+	return parentTime.Add(requiredDelay), nil
+}
+
+// calculateBlockBuildingDelay calculates the delay needed before building the next block.
+func (b *blockBuilder) calculateBlockBuildingDelay(
+	lastBuildTime time.Time,
+	lastBuildParentHash common.Hash,
+	currentHeader *types.Header,
+) (time.Duration, error) {
+	var nextBuildTime time.Time
+	isRetry := lastBuildParentHash == currentHeader.ParentHash && !lastBuildTime.IsZero() // if last build time is zero, this is not a retry
+	// If this is a retry, we already have waited for the minimum next block time in a previous attempt,
+	// and only need to wait for the retry delay.
+	if isRetry {
+		nextBuildTime = lastBuildTime.Add(RetryDelay)
+	} else {
+		// If this is not a retry, we need to wait for the minimum next block time.
+		var err error
+		nextBuildTime, err = b.minNextBlockTime(currentHeader, b.chainConfig)
+		if err != nil {
+			return 0, err
+		}
+	}
+	remainingDelay := nextBuildTime.Sub(b.clock.Time())
+	return max(remainingDelay, 0), nil
+}

plugin/evm/block_builder_test.go

@@ -0,0 +1,182 @@
+// Copyright (C) 2019-2025, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+package evm
+
+import (
+	"testing"
+	"time"
+
+	"github.com/ava-labs/avalanchego/utils/timer/mockable"
+	"github.com/ava-labs/avalanchego/vms/evm/acp226"
+	"github.com/ava-labs/libevm/common"
+	"github.com/ava-labs/libevm/core/types"
+	"github.com/stretchr/testify/require"
+
+	"github.com/ava-labs/coreth/params/extras"
+	"github.com/ava-labs/coreth/plugin/evm/customtypes"
+)
+
+func TestCalculateBlockBuildingDelay(t *testing.T) {
+	now := time.UnixMilli(10000)
+	nowSecUint64 := uint64(now.Unix())
+	nowMilliUint64 := uint64(now.UnixMilli())
+	clock := &mockable.Clock{}
+	clock.Set(now)
+	tests := []struct {
+		name                string
+		config              *extras.ChainConfig
+		currentHeader       *types.Header
+		lastBuildTime       time.Time
+		lastBuildParentHash common.Hash
+		expectedTimeToWait  time.Duration
+	}{
+		{
+			name:   "pre_granite_returns_build_immediately_zero_time",
+			config: extras.TestFortunaChainConfig, // Pre-Granite config
+			currentHeader: &types.Header{
+				ParentHash: common.Hash{1},
+				Time:       nowSecUint64,
+			},
+			lastBuildTime:       time.Time{}, // Zero time means not a retry
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  0,
+		},
+		{
+			name:   "pre_granite_returns_build_immediately_different_parent_hash",
+			config: extras.TestFortunaChainConfig, // Pre-Granite config
+			currentHeader: &types.Header{
+				ParentHash: common.Hash{2},
+				Time:       nowSecUint64,
+			},
+			lastBuildTime:       now,
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  0,
+		},
+		{
+			name:   "pre_granite_returns_build_delays_with_same_parent_hash",
+			config: extras.TestFortunaChainConfig, // Pre-Granite config
+			currentHeader: &types.Header{
+				ParentHash: common.Hash{1},
+				Time:       nowSecUint64,
+			},
+			lastBuildTime:       now,
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  RetryDelay,
+		},
+		{
+			name:   "pre_granite_returns_build_returns_immediately_if_enough_time_passed",
+			config: extras.TestFortunaChainConfig, // Pre-Granite config
+			currentHeader: &types.Header{
+				ParentHash: common.Hash{1},
+				Time:       nowSecUint64,
+			},
+			lastBuildTime:       now.Add(-RetryDelay), // Less than retry delay ago
+			lastBuildParentHash: common.Hash{1},       // Same as current parent
+			expectedTimeToWait:  0,
+		},
+		{
+			name:   "pre_granite_returns_build_delays_only_remaining_min_delay",
+			config: extras.TestFortunaChainConfig, // Pre-Granite config
+			currentHeader: &types.Header{
+				ParentHash: common.Hash{1},
+				Time:       nowSecUint64,
+			},
+			lastBuildTime:       now.Add(-RetryDelay / 2), // Less than retry delay ago
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  RetryDelay / 2,
+		},
+		{
+			name:   "first_granite_block_build_immediately",
+			config: extras.TestGraniteChainConfig,
+			currentHeader: &types.Header{
+				ParentHash: common.Hash{1},
+				Time:       nowSecUint64,
+			},
+			lastBuildTime:       now,
+			lastBuildParentHash: common.Hash{2},
+			expectedTimeToWait:  0,
+		},
+		{
+			name:                "granite_block_with_now_time",
+			config:              extras.TestGraniteChainConfig,
+			currentHeader:       createGraniteTestHeader(common.Hash{1}, nowMilliUint64, acp226.InitialDelayExcess),
+			lastBuildTime:       time.Time{},
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  2000 * time.Millisecond, // should wait for initial delay
+		},
+		{
+			name:                "granite_block_with_2_seconds_before_clock_no_retry",
+			config:              extras.TestGraniteChainConfig,
+			currentHeader:       createGraniteTestHeader(common.Hash{1}, nowMilliUint64-2000, acp226.InitialDelayExcess),
+			lastBuildTime:       time.Time{}, // Zero time means not a retry
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  0, // should not wait for initial delay
+		},
+		{
+			name:                "granite_block_with_2_seconds_before_clock_with_retry",
+			config:              extras.TestGraniteChainConfig,
+			currentHeader:       createGraniteTestHeader(common.Hash{1}, nowMilliUint64-2000, acp226.InitialDelayExcess),
+			lastBuildTime:       now,
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  RetryDelay,
+		},
+		{
+			name:                "granite_with_2_seconds_before_clock_only_waits_for_retry_delay",
+			config:              extras.TestGraniteChainConfig,
+			currentHeader:       createGraniteTestHeader(common.Hash{1}, nowMilliUint64-2000, 0), // 0 means min delay excess which is 1
+			lastBuildTime:       now,
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  RetryDelay,
+		},
+		{
+			name:                "granite_with_2_seconds_before_clock_only_waits_for_remaining_retry_delay",
+			config:              extras.TestGraniteChainConfig,
+			currentHeader:       createGraniteTestHeader(common.Hash{1}, nowMilliUint64-2000, 0), // 0 means min delay excess which is 1
+			lastBuildTime:       now.Add(-RetryDelay / 2),                                        // Less than retry delay ago
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  RetryDelay / 2,
+		},
+		{
+			name:                "granite_with_2_seconds_after_clock",
+			config:              extras.TestGraniteChainConfig,
+			currentHeader:       createGraniteTestHeader(common.Hash{1}, nowMilliUint64+2000, acp226.InitialDelayExcess),
+			lastBuildTime:       time.Time{}, // Zero time means not a retry
+			lastBuildParentHash: common.Hash{1},
+			expectedTimeToWait:  4000 * time.Millisecond,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			b := &blockBuilder{
+				clock:       clock,
+				chainConfig: tt.config,
+			}
+
+			timeToWait, err := b.calculateBlockBuildingDelay(
+				tt.lastBuildTime,
+				tt.lastBuildParentHash,
+				tt.currentHeader,
+			)
+
+			require.NoError(t, err)
+			require.Equal(t, tt.expectedTimeToWait, timeToWait)
+		})
+	}
+}
+
+func createGraniteTestHeader(parentHash common.Hash, timeMilliseconds uint64, minDelayExcess acp226.DelayExcess) *types.Header {
+	header := &types.Header{
+		Time: timeMilliseconds / 1000,
+	}
+	header.ParentHash = parentHash
+
+	extra := &customtypes.HeaderExtra{
+		TimeMilliseconds: &timeMilliseconds,
+		MinDelayExcess:   &minDelayExcess,
+	}
+	customtypes.SetHeaderExtra(header, extra)
+
+	return header
+}

plugin/evm/customheader/min_delay_excess.go

@@ -77,7 +77,7 @@ func VerifyMinDelayExcess(
 		}
 	default:
 		// Prior to Granite there was no expected min delay excess.
-		// TODO (ceyonur): this can be removed after Granite is activated.
+		// TODO (ceyonur): this can be removed after Granite is activated. (See https://github.com/ava-labs/coreth/issues/1318)
 		if customtypes.GetHeaderExtra(header).MinDelayExcess != nil {
 			return fmt.Errorf("%w: %s", errRemoteMinDelayExcessSet, header.Hash())
 		}

plugin/evm/customtypes/block_ext.go

@@ -6,6 +6,7 @@ package customtypes
 import (
 	"math/big"
 	"slices"
+	"time"
 
 	"github.com/ava-labs/avalanchego/vms/evm/acp226"
 	"github.com/ava-labs/libevm/common"
@@ -155,6 +156,13 @@ func CalcExtDataHash(extdata []byte) common.Hash {
 	return ethtypes.RLPHash(extdata)
 }
 
+func BlockTime(eth *ethtypes.Header) time.Time {
+	if t := GetHeaderExtra(eth).TimeMilliseconds; t != nil {
+		return time.UnixMilli(int64(*t))
+	}
+	return time.Unix(int64(eth.Time), 0)
+}
+
 func NewBlockWithExtData(
 	header *ethtypes.Header, txs []*ethtypes.Transaction, uncles []*ethtypes.Header, receipts []*ethtypes.Receipt,
 	hasher ethtypes.TrieHasher, extdata []byte, recalc bool,