feat(blockchain): introducing validator size cap size

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

@@ -199,6 +199,10 @@ type Spec[
 
 	// Berachain Values
 
+	// GetValidatorSetCap retrieves the maximum number of
+	// validators allowed in the active set.
+	GetValidatorSetCap() uint32
+
 	// EVMInflationAddress returns the address on the EVM which will receive
 	// the inflation amount of native EVM balance through a withdrawal every
 	// block.
@@ -534,6 +538,14 @@ func (c chainSpec[
 	return c.Data.CometValues
 }
 
+// GetValidatorSetCapS retrieves the maximum number of
+// validators allowed in the active set.
+func (c chainSpec[
+	DomainTypeT, EpochT, ExecutionAddressT, SlotT, CometBFTConfigT,
+]) GetValidatorSetCap() uint32 {
+	return c.Data.ValidatorSetCap
+}
+
 // EVMInflationAddress returns the address on the EVM which will receive the
 // inflation amount of native EVM balance through a withdrawal every block.
 func (c chainSpec[

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

@@ -155,6 +155,10 @@ type SpecData[
 
 	// Berachain Values
 	//
+	// ValidatorSetCap is the maximum number of validators that can be active
+	// for a given epoch
+	// Note: ValidatorSetCap must be smaller than ValidatorRegistryLimit.
+	ValidatorSetCap uint32 `mapstructure:"validator-set-cap-size"`
 	// EVMInflationAddress is the address on the EVM which will receive the
 	// inflation amount of native EVM balance through a withdrawal every block.
 	EVMInflationAddress ExecutionAddressT `mapstructure:"evm-inflation-address"`

mod/config/pkg/spec/base.go

@@ -123,5 +123,8 @@ func BaseSpec() chain.SpecData[
 		KZGCommitmentInclusionProofDepth: 17,
 		// Comet values.
 		CometValues: cmtConsensusParams,
+
+		// Berachain Values
+		ValidatorSetCap: 256,
 	}
 }

mod/consensus-types/pkg/types/validator.go

@@ -325,6 +325,11 @@ func (v *Validator) SetEffectiveBalance(balance math.Gwei) {
 	v.EffectiveBalance = balance
 }
 
+// SetWithdrawableEpoch sets the epoch when the validator can withdraw.
+func (v *Validator) SetWithdrawableEpoch(e math.Epoch) {
+	v.WithdrawableEpoch = e
+}
+
 // GetWithdrawableEpoch returns the epoch when the validator can withdraw.
 func (v Validator) GetWithdrawableEpoch() math.Epoch {
 	return v.WithdrawableEpoch

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

@@ -301,3 +301,13 @@ func buildNextBlock(
 		Body:          nextBlkBody,
 	}
 }
+
+var (
+	dummyExecutionPayload = &types.ExecutionPayload{
+		Timestamp:     0,
+		ExtraData:     []byte("testing"),
+		Transactions:  [][]byte{},
+		Withdrawals:   []*engineprimitives.Withdrawal{},
+		BaseFeePerGas: math.NewU256(0),
+	}
+)

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

@@ -23,6 +23,10 @@ package core
 import "github.com/berachain/beacon-kit/mod/errors"
 
 var (
+	// ErrValidatorSetCapHit is returned when we try and add a validator
+	// that would breach validator set size cap.
+	ErrHitValidatorsSetCap = errors.New("hit validator set size cap")
+
 	// ErrBlockSlotTooLow is returned when the block slot is too low.
 	ErrBlockSlotTooLow = errors.New("block slot too low")
 

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

@@ -21,6 +21,9 @@
 package core
 
 import (
+	"bytes"
+	"slices"
+
 	"github.com/berachain/beacon-kit/mod/config/pkg/spec"
 	"github.com/berachain/beacon-kit/mod/errors"
 	"github.com/berachain/beacon-kit/mod/primitives/pkg/common"
@@ -154,6 +157,121 @@ func (sp *StateProcessor[
 		math.Gwei(sp.cs.MaxEffectiveBalance()),
 	)
 
+	// BeaconKit enforces a cap on the validator set size. If the deposit
+	// breaches the cap, we find the validator with the smallest stake and
+	// mark it as withdrawable so that it will be evicted next epoch and
+	// its deposits returned.
+
+	nextEpochVals, err := sp.nextEpochValidatorSet(st)
+	if err != nil {
+		return err
+	}
+	//#nosec:G701 // no overflow risk here
+	if uint32(len(nextEpochVals)) < sp.cs.GetValidatorSetCap() {
+		// cap not hit, just add the validator
+		return sp.addValidatorInternal(st, val, dep.GetAmount())
+	}
+
+	// Adding the validator would breach the cap. Find the validator
+	// with the smallest stake among current and candidate validators
+	// and kick it out.
+	smallestVal, err := sp.smallest(nextEpochVals)
+	if err != nil {
+		return err
+	}
+
+	slot, err := st.GetSlot()
+	if err != nil {
+		return err
+	}
+	nextEpoch := sp.cs.SlotToEpoch(slot) + 1
+
+	if val.GetEffectiveBalance() <= smallestVal.GetEffectiveBalance() {
+		// in case of tie-break among candidate validator we prefer
+		// existing one so we mark candidate as withdrawable
+		// We wait next epoch to return funds, as a way to curb spamming
+		val.SetWithdrawableEpoch(nextEpoch)
+		return sp.addValidatorInternal(st, val, dep.GetAmount())
+	}
+
+	// mark exiting validator for eviction and add candidate
+	smallestVal.SetWithdrawableEpoch(nextEpoch)
+	idx, err := st.ValidatorIndexByPubkey(smallestVal.GetPubkey())
+	if err != nil {
+		return err
+	}
+	if err = st.UpdateValidatorAtIndex(idx, smallestVal); err != nil {
+		return err
+	}
+	return sp.addValidatorInternal(st, val, dep.GetAmount())
+}
+
+// nextEpochValidatorSet returns the current estimation of what next epoch
+// validator set would be.
+func (sp *StateProcessor[
+	_, _, _, BeaconStateT, _, _, _, _, _, _, _, _, ValidatorT, _, _, _, _,
+]) nextEpochValidatorSet(st BeaconStateT) ([]ValidatorT, error) {
+	slot, err := st.GetSlot()
+	if err != nil {
+		return nil, err
+	}
+	withdrawEpoch := sp.cs.SlotToEpoch(slot) + 1
+
+	vals, err := st.GetValidators()
+	if err != nil {
+		return nil, err
+	}
+	activeVals := make([]ValidatorT, 0, len(vals))
+	for _, val := range vals {
+		if val.GetEffectiveBalance() <= math.U64(sp.cs.EjectionBalance()) {
+			continue
+		}
+		if val.GetWithdrawableEpoch() == withdrawEpoch {
+			continue
+		}
+		activeVals = append(activeVals, val)
+	}
+
+	return activeVals, nil
+}
+
+// TODO: consider moving this to BeaconState directly
+func (sp *StateProcessor[
+	_, _, _, _, _, _, _, _, _, _, _, _, ValidatorT, _, _, _, _,
+]) smallest(currentVals []ValidatorT) (
+	ValidatorT,
+	error,
+) {
+	// TODO: consider heapifying slice instead. We only care about the smallest
+	slices.SortFunc(currentVals, func(lhs, rhs ValidatorT) int {
+		var (
+			val1Stake = lhs.GetEffectiveBalance()
+			val2Stake = rhs.GetEffectiveBalance()
+		)
+		switch {
+		case val1Stake < val2Stake:
+			return -1
+		case val1Stake > val2Stake:
+			return 1
+		default:
+			// validators pks are guaranteed to be different
+			var (
+				val1Pk = lhs.GetPubkey()
+				val2Pk = rhs.GetPubkey()
+			)
+			return bytes.Compare(val1Pk[:], val2Pk[:])
+		}
+	})
+	return currentVals[0], nil
+}
+
+func (sp *StateProcessor[
+	_, _, _, BeaconStateT, _, _, _, _, _, _, _, _, ValidatorT, _, _, _, _,
+]) addValidatorInternal(
+	st BeaconStateT,
+	val ValidatorT,
+	depositAmount math.Gwei,
+) error {
 	// TODO: This is a bug that lives on bArtio. Delete this eventually.
 	if sp.cs.DepositEth1ChainID() == spec.BartioChainID {
 		// Note in AddValidatorBartio we implicitly increase
@@ -168,5 +286,5 @@ func (sp *StateProcessor[
 	if err != nil {
 		return err
 	}
-	return st.IncreaseBalance(idx, dep.GetAmount())
+	return st.IncreaseBalance(idx, depositAmount)
 }