feature(state-processor): update validators EffectiveBalance only when epoch turns

mod/chain-spec/pkg/chain/chain_spec.go

@@ -45,6 +45,19 @@ type Spec[
 	// calculations.
 	EffectiveBalanceIncrement() uint64
 
+	// HysteresisQuotient returns the quotient used in effective balance
+	// calculations to create hysteresis. This provides resistance to small
+	// balance changes triggering effective balance updates.
+	HysteresisQuotient() uint64
+
+	// HysteresisDownwardMultiplier returns the multiplier used when checking
+	// if the effective balance should be decreased.
+	HysteresisDownwardMultiplier() uint64
+
+	// HysteresisUpwardMultiplier returns the multiplier used when checking
+	// if the effective balance should be increased.
+	HysteresisUpwardMultiplier() uint64
+
 	// Time parameters constants.
 
 	// SlotsPerEpoch returns the number of slots in an epoch.
@@ -245,6 +258,24 @@ func (c chainSpec[
 	return c.Data.EffectiveBalanceIncrement
 }
 
+func (c chainSpec[
+	DomainTypeT, EpochT, ExecutionAddressT, SlotT, CometBFTConfigT,
+]) HysteresisQuotient() uint64 {
+	return c.Data.HysteresisQuotient
+}
+
+func (c chainSpec[
+	DomainTypeT, EpochT, ExecutionAddressT, SlotT, CometBFTConfigT,
+]) HysteresisDownwardMultiplier() uint64 {
+	return c.Data.HysteresisDownwardMultiplier
+}
+
+func (c chainSpec[
+	DomainTypeT, EpochT, ExecutionAddressT, SlotT, CometBFTConfigT,
+]) HysteresisUpwardMultiplier() uint64 {
+	return c.Data.HysteresisUpwardMultiplier
+}
+
 // SlotsPerEpoch returns the number of slots per epoch.
 func (c chainSpec[
 	DomainTypeT, EpochT, ExecutionAddressT, SlotT, CometBFTConfigT,

mod/chain-spec/pkg/chain/data.go

@@ -43,6 +43,12 @@ type SpecData[
 	// EffectiveBalanceIncrement is the effective balance increment.
 	EffectiveBalanceIncrement uint64 `mapstructure:"effective-balance-increment"`
 
+	// HysteresisQuotient is the quotient used in effective balance calculations
+	HysteresisQuotient uint64 `mapstructure:"hysteresis-quotient"`
+	// HysteresisDownwardMultiplier is the multiplier for downward balance adjustments.
+	HysteresisDownwardMultiplier uint64 `mapstructure:"hysteresis-downward-multiplier"`
+	// HysteresisUpwardMultiplier is the multiplier for upward balance adjustments.
+	HysteresisUpwardMultiplier uint64 `mapstructure:"hysteresis-upward-multiplier"`
 	// Time parameters constants.
 	//
 	// SlotsPerEpoch is the number of slots per epoch.

mod/config/pkg/spec/special_cases.go

@@ -26,5 +26,5 @@ const (
 	BartioChainID uint64 = 80084
 
 	//nolint:lll // temporary.
-	BArtioValRoot = "0x9147586693b6e8faa837715c0f3071c2000045b54233901c2e7871b15872bc43"
+	BartioValRoot = "0x9147586693b6e8faa837715c0f3071c2000045b54233901c2e7871b15872bc43"
 )

mod/config/pkg/spec/testnet.go

@@ -60,10 +60,13 @@ func BaseSpec() chain.SpecData[
 		any,
 	]{
 		// // Gwei value constants.
-		MinDepositAmount:          uint64(1e9),
-		MaxEffectiveBalance:       uint64(32e9),
-		EjectionBalance:           uint64(16e9),
-		EffectiveBalanceIncrement: uint64(1e9),
+		MinDepositAmount:             uint64(1e9),
+		MaxEffectiveBalance:          uint64(32e9),
+		EjectionBalance:              uint64(16e9),
+		EffectiveBalanceIncrement:    uint64(1e9),
+		HysteresisQuotient:           uint64(4),
+		HysteresisDownwardMultiplier: uint64(1),
+		HysteresisUpwardMultiplier:   uint64(5),
 		// Time parameters constants.
 		SlotsPerEpoch:                32,
 		MinEpochsToInactivityPenalty: 4,

mod/state-transition/pkg/core/README.md

@@ -0,0 +1,11 @@
+# State Processor
+
+## Validators handling
+
+Currently:
+
+- Any validator whose effective balance is above `EjectionBalance` will stay a validator forever, as we have not (yet) implemented withdrawals facilities.
+- Withdrawals are automatically generated only if a validator effective balance goes beyond `MaxEffectiveBalance`. In this case enough balance is scheduled for withdrawal, just enough to make validator's effective balance equal to `MaxEffectiveBalance`. Since `MaxEffectiveBalance` > `EjectionBalance`, the validator will keep being a validator.
+- If a deposit is made for a validator with a balance smaller or equal to `EjectionBalance`, no validator will be created[^1] because of the insufficient balance. However currently the whole deposited balance is **not** scheduled for withdrawal at the next epoch.
+
+[^1]: Technically a validator is made in the BeaconKit state to track the deposit, but such a validator is never returned to the consensus engine. Moreover the deposit should be evicted at the next epoch.

mod/state-transition/pkg/core/errors.go

@@ -30,6 +30,8 @@ var (
 	// match the expected value.
 	ErrSlotMismatch = errors.New("slot mismatch")
 
+	// ErrProposerMismatch is returned when block builder does not match
+	// with the proposer reported by consensus.
 	ErrProposerMismatch = errors.New("proposer key mismatch")
 
 	// ErrParentRootMismatch is returned when the parent root in an execution

mod/state-transition/pkg/core/state_processor.go

@@ -23,6 +23,7 @@ package core
 import (
 	"bytes"
 
+	"github.com/berachain/beacon-kit/mod/consensus-types/pkg/types"
 	"github.com/berachain/beacon-kit/mod/errors"
 	"github.com/berachain/beacon-kit/mod/log"
 	"github.com/berachain/beacon-kit/mod/primitives/pkg/common"
@@ -202,34 +203,26 @@ func (sp *StateProcessor[
 ]) ProcessSlots(
 	st BeaconStateT, slot math.Slot,
 ) (transition.ValidatorUpdates, error) {
-	var (
-		validatorUpdates      transition.ValidatorUpdates
-		epochValidatorUpdates transition.ValidatorUpdates
-	)
-
+	var res transition.ValidatorUpdates
 	stateSlot, err := st.GetSlot()
 	if err != nil {
 		return nil, err
 	}
 
 	// Iterate until we are "caught up".
 	for ; stateSlot < slot; stateSlot++ {
-		// Process the slot
 		if err = sp.processSlot(st); err != nil {
 			return nil, err
 		}
 
 		// Process the Epoch Boundary.
 		boundary := (stateSlot.Unwrap()+1)%sp.cs.SlotsPerEpoch() == 0
 		if boundary {
-			if epochValidatorUpdates, err =
-				sp.processEpoch(st); err != nil {
+			var epochUpdates transition.ValidatorUpdates
+			if epochUpdates, err = sp.processEpoch(st); err != nil {
 				return nil, err
 			}
-			validatorUpdates = append(
-				validatorUpdates,
-				epochValidatorUpdates...,
-			)
+			res = append(res, epochUpdates...)
 		}
 
 		// We update on the state because we need to
@@ -239,7 +232,7 @@ func (sp *StateProcessor[
 		}
 	}
 
-	return validatorUpdates, nil
+	return res, nil
 }
 
 // processSlot is run when a slot is missed.
@@ -341,6 +334,9 @@ func (sp *StateProcessor[
 	if err := sp.processRewardsAndPenalties(st); err != nil {
 		return nil, err
 	}
+	if err := sp.processEffectiveBalanceUpdates(st); err != nil {
+		return nil, err
+	}
 	if err := sp.processSlashingsReset(st); err != nil {
 		return nil, err
 	}
@@ -367,13 +363,12 @@ func (sp *StateProcessor[
 	}
 	if blk.GetSlot() != slot {
 		return errors.Wrapf(
-			ErrSlotMismatch,
-			"expected: %d, got: %d",
+			ErrSlotMismatch, "expected: %d, got: %d",
 			slot, blk.GetSlot(),
 		)
 	}
 
-	// Verify the parent block root is correct.
+	// Verify that the block is newer than latest block header
 	latestBlockHeader, err := st.GetLatestBlockHeader()
 	if err != nil {
 		return err
@@ -385,14 +380,6 @@ func (sp *StateProcessor[
 		)
 	}
 
-	parentBlockRoot := latestBlockHeader.HashTreeRoot()
-	if parentBlockRoot != blk.GetParentBlockRoot() {
-		return errors.Wrapf(ErrParentRootMismatch,
-			"expected: %s, got: %s",
-			parentBlockRoot.String(), blk.GetParentBlockRoot().String(),
-		)
-	}
-
 	// Verify that proposer matches with what consensus declares as proposer
 	proposer, err := st.ValidatorByIndex(blk.GetProposerIndex())
 	if err != nil {
@@ -409,26 +396,24 @@ func (sp *StateProcessor[
 		)
 	}
 
-	// Check to make sure the proposer isn't slashed.
-	if proposer.IsSlashed() {
+	// Verify that the parent matches
+	parentBlockRoot := latestBlockHeader.HashTreeRoot()
+	if parentBlockRoot != blk.GetParentBlockRoot() {
 		return errors.Wrapf(
-			ErrSlashedProposer,
-			"index: %d",
-			blk.GetProposerIndex(),
+			ErrParentRootMismatch, "expected: %s, got: %s",
+			parentBlockRoot.String(), blk.GetParentBlockRoot().String(),
 		)
 	}
 
-	// Ensure the block is within the acceptable range.
-	// TODO: move this is in the wrong spot.
-	deposits := blk.GetBody().GetDeposits()
-	if uint64(len(deposits)) > sp.cs.MaxDepositsPerBlock() {
-		return errors.Wrapf(ErrExceedsBlockDepositLimit,
-			"expected: %d, got: %d",
-			sp.cs.MaxDepositsPerBlock(), len(deposits),
+	// Verify proposer is not slashed
+	if proposer.IsSlashed() {
+		return errors.Wrapf(
+			ErrSlashedProposer, "index: %d",
+			blk.GetProposerIndex(),
 		)
 	}
 
-	// Calculate the body root to place on the header.
+	// Cache current block as the new latest block
 	bodyRoot := blk.GetBody().HashTreeRoot()
 	var lbh BeaconBlockHeaderT
 	lbh = lbh.New(
@@ -521,3 +506,54 @@ func (sp *StateProcessor[
 
 	return nil
 }
+
+// processEffectiveBalanceUpdates as defined in the Ethereum 2.0 specification.
+// https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#effective-balances-updates
+//
+//nolint:lll
+func (sp *StateProcessor[
+	_, _, _, BeaconStateT, _, _, _, _, _, _, _, _, _, _, _, _, _,
+]) processEffectiveBalanceUpdates(
+	st BeaconStateT,
+) error {
+	// Update effective balances with hysteresis
+	validators, err := st.GetValidators()
+	if err != nil {
+		return err
+	}
+
+	var (
+		hysteresisIncrement = sp.cs.EffectiveBalanceIncrement() / sp.cs.HysteresisQuotient()
+		downwardThreshold   = math.Gwei(hysteresisIncrement * sp.cs.HysteresisDownwardMultiplier())
+		upwardThreshold     = math.Gwei(hysteresisIncrement * sp.cs.HysteresisUpwardMultiplier())
+
+		idx     math.U64
+		balance math.Gwei
+	)
+
+	for _, val := range validators {
+		idx, err = st.ValidatorIndexByPubkey(val.GetPubkey())
+		if err != nil {
+			return err
+		}
+
+		balance, err = st.GetBalance(idx)
+		if err != nil {
+			return err
+		}
+
+		if balance+downwardThreshold < val.GetEffectiveBalance() ||
+			val.GetEffectiveBalance()+upwardThreshold < balance {
+			updatedBalance := types.ComputeEffectiveBalance(
+				balance,
+				math.U64(sp.cs.EffectiveBalanceIncrement()),
+				math.U64(sp.cs.MaxEffectiveBalance()),
+			)
+			val.SetEffectiveBalance(updatedBalance)
+			if err = st.UpdateValidatorAtIndex(idx, val); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}

mod/state-transition/pkg/core/state_processor_committee.go

@@ -21,6 +21,7 @@
 package core
 
 import (
+	"github.com/berachain/beacon-kit/mod/primitives/pkg/math"
 	"github.com/berachain/beacon-kit/mod/primitives/pkg/transition"
 	"github.com/sourcegraph/conc/iter"
 )
@@ -36,8 +37,19 @@ func (sp *StateProcessor[
 		return nil, err
 	}
 
+	// filter out validators whose effective balance is not sufficient to validate
+	activeVals := make([]ValidatorT, 0, len(vals))
+	for _, val := range vals {
+		if val.GetEffectiveBalance() > math.U64(sp.cs.EjectionBalance()) {
+			activeVals = append(activeVals, val)
+		}
+	}
+
+	// TODO: a more efficient handling would be to only send back to consensus
+	// updated validators (including evicted ones), rather than the full list
+
 	return iter.MapErr(
-		vals,
+		activeVals,
 		func(val *ValidatorT) (*transition.ValidatorUpdate, error) {
 			v := (*val)
 			return &transition.ValidatorUpdate{