feat(chain): implement BRIP-0008 hysteresis update for Fulu fork

chain/data.go

@@ -102,6 +102,8 @@ type SpecData struct {
 	ElectraForkTime uint64 `mapstructure:"electra-fork-time"`
 	// Electra1ForkTime is the time at which the Electra1 fork is activated.
 	Electra1ForkTime uint64 `mapstructure:"electra-one-fork-time"`
+	// FuluForkTime is the time at which the Fulu fork is activated (Fusaka CL fork).
+	FuluForkTime uint64 `mapstructure:"fulu-fork-time"`
 
 	// State list lengths
 	//
@@ -170,4 +172,17 @@ type SpecData struct {
 	// MinValidatorWithdrawabilityDelay is defined in the Electra spec and introduces
 	// withdrawability delays to allow for slashing.
 	MinValidatorWithdrawabilityDelay uint64 `mapstructure:"min-validator-withdrawability-delay"`
+
+	// Fulu Value Changes
+	//
+	// HysteresisQuotientFulu is the hysteresis quotient for the Fulu fork (BRIP-0008).
+	HysteresisQuotientFulu uint64 `mapstructure:"hysteresis-quotient-fulu"`
+	// HysteresisUpwardMultiplierFulu is the hysteresis upward multiplier for the Fulu fork.
+	HysteresisUpwardMultiplierFulu uint64 `mapstructure:"hysteresis-upward-multiplier-fulu"`
+	// EVMInflationAddressFulu is the address on the EVM which will receive the
+	// inflation amount of native EVM balance through a withdrawal every block in the Fulu fork.
+	EVMInflationAddressFulu common.ExecutionAddress `mapstructure:"evm-inflation-address-fulu"`
+	// EVMInflationPerBlockFulu is the amount of native EVM balance (in Gwei) to be
+	// minted to the EVMInflationAddressFulu via a withdrawal every block in the Fulu fork.
+	EVMInflationPerBlockFulu uint64 `mapstructure:"evm-inflation-per-block-fulu"`
 }

chain/helpers.go

@@ -29,6 +29,9 @@ import (
 // ActiveForkVersionForTimestamp returns the active fork version for a given timestamp.
 func (s spec) ActiveForkVersionForTimestamp(timestamp math.U64) common.Version {
 	time := timestamp.Unwrap()
+	if time >= s.FuluForkTime() {
+		return version.Fulu()
+	}
 	if time >= s.Electra1ForkTime() {
 		return version.Electra1()
 	}

chain/helpers_test.go

@@ -38,6 +38,7 @@ var spec, _ = chain.NewSpec(
 		Deneb1ForkTime:                   9 * 32 * 2,
 		ElectraForkTime:                  10 * 32 * 2,
 		Electra1ForkTime:                 11 * 32 * 2,
+		FuluForkTime:                     12 * 32 * 2,
 		SlotsPerEpoch:                    32,
 		MinEpochsForBlobsSidecarsRequest: 5,
 		MaxWithdrawalsPerPayload:         2,

chain/spec.go

@@ -48,15 +48,17 @@ type HysteresisSpec interface {
 	// HysteresisQuotient returns the quotient used in effective balance
 	// calculations to create hysteresis. This provides resistance to small
 	// balance changes triggering effective balance updates.
-	HysteresisQuotient() math.U64
+	// The value is fork-gated by timestamp (updated in Fulu per BRIP-0008).
+	HysteresisQuotient(timestamp math.U64) math.U64
 
 	// HysteresisDownwardMultiplier returns the multiplier used when checking
 	// if the effective balance should be decreased.
 	HysteresisDownwardMultiplier() math.U64
 
 	// HysteresisUpwardMultiplier returns the multiplier used when checking
 	// if the effective balance should be increased.
-	HysteresisUpwardMultiplier() math.U64
+	// The value is fork-gated by timestamp (updated in Fulu per BRIP-0008).
+	HysteresisUpwardMultiplier(timestamp math.U64) math.U64
 }
 
 type DepositSpec interface {
@@ -109,6 +111,9 @@ type ForkSpec interface {
 
 	// Electra1ForkTime returns the time at which the Electra1 fork takes effect.
 	Electra1ForkTime() uint64
+
+	// FuluForkTime returns the time at which the Fulu fork takes effect.
+	FuluForkTime() uint64
 }
 
 type BlobSpec interface {
@@ -269,6 +274,7 @@ func (s spec) validate() error {
 		s.Data.Deneb1ForkTime,
 		s.Data.ElectraForkTime,
 		s.Data.Electra1ForkTime,
+		s.Data.FuluForkTime,
 	}
 	for i := 1; i < len(orderedForkTimes); i++ {
 		prev, cur := orderedForkTimes[i-1], orderedForkTimes[i]
@@ -332,15 +338,23 @@ func (s spec) EffectiveBalanceIncrement() math.Gwei {
 	return math.Gwei(s.Data.EffectiveBalanceIncrement)
 }
 
-func (s spec) HysteresisQuotient() math.U64 {
+func (s spec) HysteresisQuotient(timestamp math.U64) math.U64 {
+	fv := s.ActiveForkVersionForTimestamp(timestamp)
+	if version.EqualsOrIsAfter(fv, version.Fulu()) {
+		return math.U64(s.Data.HysteresisQuotientFulu)
+	}
 	return math.U64(s.Data.HysteresisQuotient)
 }
 
 func (s spec) HysteresisDownwardMultiplier() math.U64 {
 	return math.U64(s.Data.HysteresisDownwardMultiplier)
 }
 
-func (s spec) HysteresisUpwardMultiplier() math.U64 {
+func (s spec) HysteresisUpwardMultiplier(timestamp math.U64) math.U64 {
+	fv := s.ActiveForkVersionForTimestamp(timestamp)
+	if version.EqualsOrIsAfter(fv, version.Fulu()) {
+		return math.U64(s.Data.HysteresisUpwardMultiplierFulu)
+	}
 	return math.U64(s.Data.HysteresisUpwardMultiplier)
 }
 
@@ -447,6 +461,11 @@ func (s spec) Electra1ForkTime() uint64 {
 	return s.Data.Electra1ForkTime
 }
 
+// FuluForkTime returns the timestamp of the Fulu fork.
+func (s spec) FuluForkTime() uint64 {
+	return s.Data.FuluForkTime
+}
+
 // EpochsPerHistoricalVector returns the number of epochs per historical vector.
 func (s spec) EpochsPerHistoricalVector() uint64 {
 	return s.Data.EpochsPerHistoricalVector
@@ -518,10 +537,12 @@ func (s spec) ValidatorSetCap() uint64 {
 // inflation amount of native EVM balance through a withdrawal every block.
 func (s spec) EVMInflationAddress(timestamp math.U64) common.ExecutionAddress {
 	fv := s.ActiveForkVersionForTimestamp(timestamp)
-	switch fv {
-	case version.Deneb1(), version.Electra(), version.Electra1():
+	switch {
+	case version.EqualsOrIsAfter(fv, version.Fulu()):
+		return s.Data.EVMInflationAddressFulu
+	case version.EqualsOrIsAfter(fv, version.Deneb1()):
 		return s.Data.EVMInflationAddressDeneb1
-	case version.Deneb():
+	case version.Equals(fv, version.Deneb()):
 		return s.Data.EVMInflationAddressGenesis
 	default:
 		panic(fmt.Sprintf("EVMInflationAddress not supported for this fork version: %d", fv))
@@ -532,10 +553,12 @@ func (s spec) EVMInflationAddress(timestamp math.U64) common.ExecutionAddress {
 // be minted to the EVMInflationAddress via a withdrawal every block.
 func (s spec) EVMInflationPerBlock(timestamp math.U64) math.Gwei {
 	fv := s.ActiveForkVersionForTimestamp(timestamp)
-	switch fv {
-	case version.Deneb1(), version.Electra(), version.Electra1():
+	switch {
+	case version.EqualsOrIsAfter(fv, version.Fulu()):
+		return math.Gwei(s.Data.EVMInflationPerBlockFulu)
+	case version.EqualsOrIsAfter(fv, version.Deneb1()):
 		return math.Gwei(s.Data.EVMInflationPerBlockDeneb1)
-	case version.Deneb():
+	case version.Equals(fv, version.Deneb()):
 		return math.Gwei(s.Data.EVMInflationPerBlockGenesis)
 	default:
 		panic(fmt.Sprintf("EVMInflationPerBlock not supported for this fork version: %d", fv))

chain/spec_test.go

@@ -43,6 +43,7 @@ func TestValidate_ForkOrder_Success(t *testing.T) {
 	data.Deneb1ForkTime = 20
 	data.ElectraForkTime = 30
 	data.Electra1ForkTime = 40
+	data.FuluForkTime = 50
 
 	_, err := chain.NewSpec(data)
 	require.NoError(t, err)
@@ -55,6 +56,7 @@ func TestValidate_ForkOrder_GenesisAfterDeneb(t *testing.T) {
 	data.Deneb1ForkTime = 20
 	data.ElectraForkTime = 60
 	data.Electra1ForkTime = 70
+	data.FuluForkTime = 80
 
 	_, err := chain.NewSpec(data)
 	require.Error(t, err)
@@ -68,6 +70,7 @@ func TestValidate_ForkOrder_DenebAfterElectra(t *testing.T) {
 	data.Deneb1ForkTime = 80
 	data.ElectraForkTime = 40
 	data.Electra1ForkTime = 50
+	data.FuluForkTime = 90
 
 	_, err := chain.NewSpec(data)
 	require.Error(t, err)

cli/commands/genesis/payload.go

@@ -148,8 +148,8 @@ func executableDataToExecutionPayloadHeader(
 ) (*types.ExecutionPayloadHeader, error) {
 	eph := &types.ExecutionPayloadHeader{}
 
-	// We do not support fork versions before Deneb and after Electra1.
-	if version.IsAfter(forkVersion, version.Electra1()) ||
+	// We do not support fork versions before Deneb and after Fulu.
+	if version.IsAfter(forkVersion, version.Fulu()) ||
 		version.IsBefore(forkVersion, version.Deneb()) {
 		return nil, types.ErrForkVersionNotSupported
 	}

config/spec/devnet.go

@@ -61,6 +61,14 @@ const (
 
 	// devnetMinValidatorWithdrawabilityDelay is the delay (in epochs) before a validator can withdraw their stake.
 	devnetMinValidatorWithdrawabilityDelay = 32
+
+	// devnetFuluForkTime is the timestamp at which the Fulu fork occurs on devnet.
+	// Set to 0 so devnet starts with Fulu active.
+	devnetFuluForkTime = 0
+
+	// devnetEVMInflationPerBlockFulu is the amount of native EVM balance (in units
+	// of Gwei) to be minted per EL block after the Fulu fork on devnet.
+	devnetEVMInflationPerBlockFulu = 12 * params.GWei
 )
 
 // DevnetChainSpecData is the chain.SpecData for a devnet. It is similar to mainnet but
@@ -79,6 +87,7 @@ func DevnetChainSpecData() *chain.SpecData {
 	specData.Deneb1ForkTime = devnetDeneb1ForkTime
 	specData.ElectraForkTime = devnetElectraForkTime
 	specData.Electra1ForkTime = devnetElectra1ForkTime
+	specData.FuluForkTime = devnetFuluForkTime
 
 	// EVM inflation is different from mainnet to test.
 	specData.EVMInflationAddressGenesis = common.MustNewExecutionAddressFromHex(devnetEVMInflationAddress)
@@ -95,6 +104,10 @@ func DevnetChainSpecData() *chain.SpecData {
 	specData.SlotsPerEpoch = defaultSlotsPerEpoch
 	specData.MinValidatorWithdrawabilityDelay = devnetMinValidatorWithdrawabilityDelay
 
+	// EVM inflation for the Fulu fork on devnet. The address remains the same as the Deneb1 fork.
+	specData.EVMInflationAddressFulu = common.MustNewExecutionAddressFromHex(devnetEVMInflationAddressDeneb1)
+	specData.EVMInflationPerBlockFulu = devnetEVMInflationPerBlockFulu
+
 	return specData
 }
 

config/spec/mainnet.go

@@ -102,6 +102,26 @@ const (
 	// These are the heights at which SBT is activated on mainnet.
 	mainnetSBTConsensusUpdateHeight = 9_983_085
 	mainnetSBTConsensusEnableHeight = 9_983_086
+
+	// mainnetFuluForkTime is the timestamp at which the Fulu fork occurs.
+	// TODO: Set to actual fork time before Fulu activation.
+	mainnetFuluForkTime = 9_999_999_999_999_999
+
+	// mainnetHysteresisQuotientFulu is the hysteresis quotient for the Fulu fork (BRIP-0008).
+	mainnetHysteresisQuotientFulu = 100
+
+	// mainnetHysteresisUpwardMultiplierFulu is the hysteresis upward multiplier for the Fulu fork.
+	mainnetHysteresisUpwardMultiplierFulu = 10
+
+	// mainnetEVMInflationAddressFulu is the address on the EVM which will receive the
+	// inflation amount of native EVM balance through a withdrawal every block in the Fulu fork.
+	// TODO: Set to actual address before Fulu activation.
+	mainnetEVMInflationAddressFulu = "0x0000000000000000000000000000000000000000"
+
+	// mainnetEVMInflationPerBlockFulu is the amount of native EVM balance (in Gwei) to be
+	// minted to the EVMInflationAddressFulu via a withdrawal every block in the Fulu fork.
+	// TODO: Set to actual value before Fulu activation.
+	mainnetEVMInflationPerBlockFulu = 0
 )
 
 // MainnetChainSpecData is the chain.SpecData for the Berachain mainnet.
@@ -144,6 +164,7 @@ func MainnetChainSpecData() *chain.SpecData {
 		Deneb1ForkTime:   mainnetDeneb1ForkTime,
 		ElectraForkTime:  mainnetElectraForkTime,
 		Electra1ForkTime: mainnetElectra1ForkTime,
+		FuluForkTime:     mainnetFuluForkTime,
 
 		// State list length constants.
 		EpochsPerHistoricalVector: defaultEpochsPerHistoricalVector,
@@ -174,6 +195,12 @@ func MainnetChainSpecData() *chain.SpecData {
 		// Electra values.
 		MinActivationBalance:             mainnetMinActivationBalance,
 		MinValidatorWithdrawabilityDelay: mainnetMinValidatorWithdrawabilityDelay,
+
+		// Fulu values (BRIP-0008 hysteresis + PoL vNext).
+		HysteresisQuotientFulu:         mainnetHysteresisQuotientFulu,
+		HysteresisUpwardMultiplierFulu: mainnetHysteresisUpwardMultiplierFulu,
+		EVMInflationAddressFulu:        common.MustNewExecutionAddressFromHex(mainnetEVMInflationAddressFulu),
+		EVMInflationPerBlockFulu:       mainnetEVMInflationPerBlockFulu,
 	}
 
 	specData.Config.ConsensusUpdateHeight = mainnetSBTConsensusUpdateHeight

config/spec/testnet.go

@@ -49,6 +49,10 @@ func TestnetChainSpecData() *chain.SpecData {
 	// Timestamp of the Electra1 fork on Bepolia.
 	specData.Electra1ForkTime = 1_754_496_000
 
+	// Timestamp of the Fulu fork on Bepolia.
+	// TODO: Set to actual fork time before Fulu activation.
+	specData.FuluForkTime = 9_999_999_999_999_999
+
 	return specData
 }
 

consensus-types/types/block.go

@@ -61,7 +61,7 @@ func NewBeaconBlockWithVersion(
 	forkVersion common.Version,
 ) (*BeaconBlock, error) {
 	switch forkVersion {
-	case version.Deneb(), version.Deneb1(), version.Electra(), version.Electra1():
+	case version.Deneb(), version.Deneb1(), version.Electra(), version.Electra1(), version.Fulu():
 		block := NewEmptyBeaconBlockWithVersion(forkVersion)
 		block.Slot = slot
 		block.ProposerIndex = proposerIndex

consensus-types/types/payload.go

@@ -575,7 +575,7 @@ func (p *ExecutionPayload) GetExcessBlobGas() math.U64 {
 // ToHeader converts the ExecutionPayload to an ExecutionPayloadHeader.
 func (p *ExecutionPayload) ToHeader() (*ExecutionPayloadHeader, error) {
 	switch p.GetForkVersion() {
-	case version.Deneb(), version.Deneb1(), version.Electra(), version.Electra1():
+	case version.Deneb(), version.Deneb1(), version.Electra(), version.Electra1(), version.Fulu():
 		return &ExecutionPayloadHeader{
 			Versionable:      p.Versionable,
 			ParentHash:       p.GetParentHash(),

consensus-types/types/signed_beacon_block.go

@@ -70,7 +70,7 @@ func NewSignedBeaconBlock(
 
 func NewEmptySignedBeaconBlockWithVersion(forkVersion common.Version) (*SignedBeaconBlock, error) {
 	switch forkVersion {
-	case version.Deneb(), version.Deneb1(), version.Electra(), version.Electra1():
+	case version.Deneb(), version.Deneb1(), version.Electra(), version.Electra1(), version.Fulu():
 		return &SignedBeaconBlock{
 			BeaconBlock: NewEmptyBeaconBlockWithVersion(forkVersion),
 		}, nil

execution/client/ethclient/engine.go

@@ -70,8 +70,9 @@ func (s *Client) NewPayload(
 			executionRequests,
 		)
 
-	case version.Equals(forkVersion, version.Electra1()):
-		// Use V4P11 for Electra1 versions.
+	case version.Equals(forkVersion, version.Electra1()),
+		version.Equals(forkVersion, version.Fulu()):
+		// Use V4P11 for Electra1 and Fulu versions.
 		executionRequests, err := req.GetEncodedExecutionRequests()
 		if err != nil {
 			return nil, err
@@ -164,8 +165,9 @@ func (s *Client) ForkchoiceUpdated(
 		// Deneb versions and Electra use ForkchoiceUpdatedV3.
 		return s.ForkchoiceUpdatedV3(ctx, state, attrs)
 
-	case version.Equals(forkVersion, version.Electra1()):
-		// Electra1 uses ForkchoiceUpdatedV3P11.
+	case version.Equals(forkVersion, version.Electra1()),
+		version.Equals(forkVersion, version.Fulu()):
+		// Electra1 and Fulu use ForkchoiceUpdatedV3P11.
 		return s.ForkchoiceUpdatedV3P11(ctx, state, attrs)
 
 	default:
@@ -234,7 +236,8 @@ func (s *Client) GetPayload(
 	case version.Equals(forkVersion, version.Electra()):
 		return s.GetPayloadV4(ctx, payloadID, forkVersion)
 
-	case version.Equals(forkVersion, version.Electra1()):
+	case version.Equals(forkVersion, version.Electra1()),
+		version.Equals(forkVersion, version.Fulu()):
 		return s.GetPayloadV4P11(ctx, payloadID, forkVersion)
 
 	default:

execution/client/ethclient/engine_test.go

@@ -76,7 +76,7 @@ func TestNewPayloadWithInvalidVersion(t *testing.T) {
 	ctx := t.Context()
 
 	n := mocks.NewPayloadRequest{}
-	n.On("GetForkVersion").Return(version.Electra2())
+	n.On("GetForkVersion").Return(version.Capella())
 	_, err := c.NewPayload(ctx, &n)
 	require.ErrorIs(t, err, ethclient.ErrInvalidVersion)
 }

primitives/version/name.go

@@ -41,6 +41,8 @@ func Name(v common.Version) string {
 		return "electra"
 	case electra1:
 		return "electra1"
+	case fulu:
+		return "fulu"
 	default:
 		return "unknown"
 	}

primitives/version/supported.go

@@ -28,6 +28,7 @@ var supportedVersions = []common.Version{
 	deneb1,
 	electra,
 	electra1,
+	fulu,
 }
 
 // GetSupportedVersions returns the supported versions of beacon-kit.

primitives/version/versions.go

@@ -44,8 +44,8 @@ var (
 	electra = common.Version{0x05, 0x00, 0x00, 0x00}
 	// electra1 is the first hardfork of Electra on Berachain mainnet.
 	electra1 = common.Version{0x05, 0x01, 0x00, 0x00}
-	// TBD if used but kept as an example.
-	electra2 = common.Version{0x05, 0x02, 0x00, 0x00}
+	// fulu is the first version of the Fulu hardfork on Berachain mainnet.
+	fulu = common.Version{0x06, 0x00, 0x00, 0x00}
 )
 
 // Phase0 returns phase0 as a common.Version.
@@ -89,7 +89,8 @@ func Electra1() common.Version {
 	return electra1
 }
 
-// Electra2 returns electra2 as a common.Version.
-func Electra2() common.Version {
-	return electra2
+// Fulu returns fulu as a common.Version. Fulu is the CL component of the
+// Fusaka hardfork on Berachain mainnet.
+func Fulu() common.Version {
+	return fulu
 }