gloas: implement modified process withdrawals

This refactors `ExpectedWithdrawals` to use shared helpers for pending
partial withdrawals and the validator sweep. The goal is to keep the
logic spec-aligned while making it easier to reuse across future forks.
```
**Example (Gloas expected withdrawals order):**
builder withdrawals
pending partial withdrawals
builder sweep withdrawals
validator sweep withdrawals
```

Note to reviewers: the helpers take a `*[]*enginev1.Withdrawal` so we
can append efficiently without returning/re-appending slices.

beacon-chain/core/gloas/BUILD.bazel

@@ -4,8 +4,10 @@ go_library(
     name = "go_default_library",
     srcs = [
         "bid.go",
+        "builder.go",
         "pending_payment.go",
         "proposer_slashing.go",
+        "withdrawal.go",
     ],
     importpath = "github.com/OffchainLabs/prysm/v7/beacon-chain/core/gloas",
     visibility = ["//visibility:public"],
@@ -21,6 +23,7 @@ go_library(
         "//crypto/bls:go_default_library",
         "//crypto/bls/common:go_default_library",
         "//proto/prysm/v1alpha1:go_default_library",
+        "//runtime/version:go_default_library",
         "//time/slots:go_default_library",
         "@com_github_pkg_errors//:go_default_library",
     ],

beacon-chain/core/gloas/builder.go

@@ -0,0 +1,46 @@
+package gloas
+
+import (
+	"github.com/OffchainLabs/prysm/v7/config/params"
+	"github.com/OffchainLabs/prysm/v7/consensus-types/primitives"
+)
+
+// IsBuilderIndex returns true when the BuilderIndex flag is set on a validator index.
+// Spec v1.6.1 (pseudocode):
+// def is_builder_index(validator_index: ValidatorIndex) -> bool:
+//
+//	return (validator_index & BUILDER_INDEX_FLAG) != 0
+func IsBuilderIndex(validatorIndex primitives.ValidatorIndex) bool {
+	return uint64(validatorIndex)&params.BeaconConfig().BuilderIndexFlag != 0
+}
+
+// ConvertValidatorIndexToBuilderIndex strips the builder flag from a validator index.
+// Spec v1.6.1 (pseudocode):
+// def convert_validator_index_to_builder_index(validator_index: ValidatorIndex) -> BuilderIndex:
+//
+//	return BuilderIndex(validator_index & ~BUILDER_INDEX_FLAG)
+func ConvertValidatorIndexToBuilderIndex(validatorIndex primitives.ValidatorIndex) primitives.BuilderIndex {
+	return primitives.BuilderIndex(uint64(validatorIndex) & ^params.BeaconConfig().BuilderIndexFlag)
+}
+
+// ConvertBuilderIndexToValidatorIndex sets the builder flag on a builder index.
+// Spec v1.6.1 (pseudocode):
+// def convert_builder_index_to_validator_index(builder_index: BuilderIndex) -> ValidatorIndex:
+//
+//	return ValidatorIndex(builder_index | BUILDER_INDEX_FLAG)
+func ConvertBuilderIndexToValidatorIndex(builderIndex primitives.BuilderIndex) primitives.ValidatorIndex {
+	return primitives.ValidatorIndex(uint64(builderIndex) | params.BeaconConfig().BuilderIndexFlag)
+}
+
+// IsBuilderWithdrawalCredential returns true when the builder withdrawal prefix is set.
+// Spec v1.6.1 (pseudocode):
+// def is_builder_withdrawal_credential(withdrawal_credentials: Bytes32) -> bool:
+//
+//	return withdrawal_credentials[:1] == BUILDER_WITHDRAWAL_PREFIX
+func IsBuilderWithdrawalCredential(withdrawalCredentials []byte) bool {
+	if len(withdrawalCredentials) == 0 {
+		return false
+	}
+	return withdrawalCredentials[0] == params.BeaconConfig().BuilderWithdrawalPrefixByte
+}
+

beacon-chain/core/gloas/withdrawal.go

@@ -0,0 +1,89 @@
+package gloas
+
+import (
+	"fmt"
+
+	"github.com/OffchainLabs/prysm/v7/beacon-chain/core/helpers"
+	"github.com/OffchainLabs/prysm/v7/beacon-chain/state"
+	"github.com/OffchainLabs/prysm/v7/config/params"
+	"github.com/OffchainLabs/prysm/v7/consensus-types/primitives"
+	"github.com/OffchainLabs/prysm/v7/runtime/version"
+	"github.com/pkg/errors"
+)
+
+func ProcessWithdrawals(st state.BeaconState) error {
+	if st.Version() < version.Gloas {
+		return errors.New("Process withdrawals gloas cant be called in version xyz")
+	}
+
+	full, err := st.IsParentBlockFull()
+	if err != nil {
+		return errors.Wrap(err, "could not get parent block full status")
+	}
+	if !full {
+		return nil
+	}
+
+	expectedWithdrawals, processedBuilderWithdrawalsCount, processedPartialWithdrawalsCount, nextWithdrawalBuilderIndex, err := st.ExpectedWithdrawalsGloas()
+	if err != nil {
+		return errors.Wrap(err, "could not get expected withdrawals")
+	}
+
+	for _, withdrawal := range expectedWithdrawals {
+		if IsBuilderIndex(withdrawal.ValidatorIndex) {
+			builderIndex := ConvertValidatorIndexToBuilderIndex(withdrawal.ValidatorIndex)
+			err := st.DecreaseBuilderBalance(builderIndex, withdrawal.Amount)
+			if err != nil {
+				return errors.Wrap(err, "could not decrease builder balance")
+			}
+		} else {
+			err := helpers.DecreaseBalance(st, withdrawal.ValidatorIndex, withdrawal.Amount)
+			if err != nil {
+				return errors.Wrap(err, "could not decrease balance")
+			}
+		}
+	}
+
+	err = st.SetPayloadExpectedWithdrawals(expectedWithdrawals)
+	if err != nil {
+		return errors.Wrap(err, "could not set payload expected withdrawals")
+	}
+	err = st.DequeueBuilderPendingWithdrawals(processedBuilderWithdrawalsCount)
+	if err != nil {
+		return fmt.Errorf("unable to dequeue builder pending withdrawals from state: %w", err)
+	}
+	err = st.SetNextWithdrawalBuilderIndex(nextWithdrawalBuilderIndex)
+	if err != nil {
+		return errors.Wrap(err, "could not set next withdrawal builder index")
+	}
+
+	if err := st.DequeuePendingPartialWithdrawals(processedPartialWithdrawalsCount); err != nil {
+		return fmt.Errorf("unable to dequeue partial withdrawals from state: %w", err)
+	}
+
+	if len(expectedWithdrawals) > 0 {
+		if err := st.SetNextWithdrawalIndex(expectedWithdrawals[len(expectedWithdrawals)-1].Index + 1); err != nil {
+			return errors.Wrap(err, "could not set next withdrawal index")
+		}
+	}
+
+	var nextValidatorIndex primitives.ValidatorIndex
+	if uint64(len(expectedWithdrawals)) < params.BeaconConfig().MaxWithdrawalsPerPayload {
+		nextValidatorIndex, err = st.NextWithdrawalValidatorIndex()
+		if err != nil {
+			return errors.Wrap(err, "could not get next withdrawal validator index")
+		}
+		nextValidatorIndex += primitives.ValidatorIndex(params.BeaconConfig().MaxValidatorsPerWithdrawalsSweep)
+		nextValidatorIndex = nextValidatorIndex % primitives.ValidatorIndex(st.NumValidators())
+	} else {
+		nextValidatorIndex = expectedWithdrawals[len(expectedWithdrawals)-1].ValidatorIndex + 1
+		if nextValidatorIndex == primitives.ValidatorIndex(st.NumValidators()) {
+			nextValidatorIndex = 0
+		}
+	}
+	if err := st.SetNextWithdrawalValidatorIndex(nextValidatorIndex); err != nil {
+		return errors.Wrap(err, "could not set next withdrawal validator index")
+	}
+
+	return nil
+}

beacon-chain/state/interfaces_gloas.go

@@ -3,6 +3,7 @@ package state
 import (
 	"github.com/OffchainLabs/prysm/v7/consensus-types/interfaces"
 	"github.com/OffchainLabs/prysm/v7/consensus-types/primitives"
+	enginev1 "github.com/OffchainLabs/prysm/v7/proto/engine/v1"
 	ethpb "github.com/OffchainLabs/prysm/v7/proto/prysm/v1alpha1"
 )
 
@@ -13,6 +14,11 @@ type writeOnlyGloasFields interface {
 	RotateBuilderPendingPayments() error
 	AppendBuilderPendingWithdrawals([]*ethpb.BuilderPendingWithdrawal) error
 	UpdateExecutionPayloadAvailabilityAtIndex(idx uint64, val byte) error
+
+	SetPayloadExpectedWithdrawals(withdrawals []*enginev1.Withdrawal) error
+	DequeueBuilderPendingWithdrawals(num uint64) error
+	SetNextWithdrawalBuilderIndex(idx primitives.BuilderIndex) error
+	DecreaseBuilderBalance(builderIndex primitives.BuilderIndex, amount uint64) error
 }
 
 type readOnlyGloasFields interface {
@@ -21,4 +27,12 @@ type readOnlyGloasFields interface {
 	CanBuilderCoverBid(primitives.BuilderIndex, primitives.Gwei) (bool, error)
 	LatestBlockHash() ([32]byte, error)
 	BuilderPendingPayments() ([]*ethpb.BuilderPendingPayment, error)
+
+	IsParentBlockFull() (bool, error)
+	BuildersCount() int
+	Builders() ([]*ethpb.Builder, error)
+	NextWithdrawalBuilderIndex() (primitives.BuilderIndex, error)
+	BuilderPendingWithdrawals() ([]*ethpb.BuilderPendingWithdrawal, error)
+
+	ExpectedWithdrawalsGloas() ([]*enginev1.Withdrawal, uint64, uint64, primitives.BuilderIndex, error)
 }

beacon-chain/state/state-native/BUILD.bazel

@@ -15,6 +15,7 @@ go_library(
         "getters_eth1.go",
         "getters_exit.go",
         "getters_gloas.go",
+        "getters_gloas_withdrawals.go",
         "getters_misc.go",
         "getters_participation.go",
         "getters_payload_header.go",

beacon-chain/state/state-native/getters_gloas.go

@@ -1,6 +1,7 @@
 package state_native
 
 import (
+	"bytes"
 	"fmt"
 
 	fieldparams "github.com/OffchainLabs/prysm/v7/config/fieldparams"
@@ -10,6 +11,22 @@ import (
 	"github.com/OffchainLabs/prysm/v7/runtime/version"
 )
 
+// IsParentBlockFull returns true when the latest bid was fulfilled with a payload.
+func (b *BeaconState) IsParentBlockFull() (bool, error) {
+	if b.version < version.Gloas {
+		return false, errNotSupported("IsParentBlockFull", b.version)	
+	}
+
+	b.lock.RLock()
+	defer b.lock.RUnlock()
+
+	if b.latestExecutionPayloadBid == nil {
+		return false, nil
+	}
+
+	return bytes.Equal(b.latestExecutionPayloadBid.BlockHash, b.latestBlockHash), nil
+}
+
 // LatestBlockHash returns the hash of the latest execution block.
 func (b *BeaconState) LatestBlockHash() ([32]byte, error) {
 	if b.version < version.Gloas {
@@ -147,3 +164,56 @@ func (b *BeaconState) BuilderPendingPayments() ([]*ethpb.BuilderPendingPayment,
 
 	return b.builderPendingPaymentsVal(), nil
 }
+
+// BuilderPendingWithdrawals returns the builder pending withdrawals queue.
+func (b *BeaconState) BuilderPendingWithdrawals() ([]*ethpb.BuilderPendingWithdrawal, error) {
+	if b.version < version.Gloas {
+		return nil, errNotSupported("BuilderPendingWithdrawals", b.version)
+	}
+
+	b.lock.RLock()
+	defer b.lock.RUnlock()
+
+	return b.builderPendingWithdrawalsVal(), nil
+}
+
+// BuildersCount returns the number of builders in the registry.
+func (b *BeaconState) BuildersCount() int {
+	if b.version < version.Gloas {
+		return 0
+	}
+
+	b.lock.RLock()
+	defer b.lock.RUnlock()
+
+	return len(b.builders)
+}
+
+// Builders returns the builders registry.
+func (b *BeaconState) Builders() ([]*ethpb.Builder, error) {
+	if b.version < version.Gloas {
+		return nil, errNotSupported("Builders", b.version)
+	}
+
+	b.lock.RLock()
+	defer b.lock.RUnlock()
+
+	builders := make([]*ethpb.Builder, len(b.builders))
+	for i := range b.builders {
+		builders[i] = ethpb.CopyBuilder(b.builders[i])
+	}
+
+	return builders, nil
+}
+
+// NextWithdrawalBuilderIndex returns the next builder index for the withdrawals sweep.
+func (b *BeaconState) NextWithdrawalBuilderIndex() (primitives.BuilderIndex, error) {
+	if b.version < version.Gloas {
+		return 0, errNotSupported("NextWithdrawalBuilderIndex", b.version)
+	}
+
+	b.lock.RLock()
+	defer b.lock.RUnlock()
+
+	return b.nextWithdrawalBuilderIndex, nil
+}

beacon-chain/state/state-native/getters_gloas_withdrawals.go

@@ -0,0 +1,165 @@
+package state_native
+
+import (
+	"fmt"
+
+	"github.com/OffchainLabs/prysm/v7/config/params"
+	"github.com/OffchainLabs/prysm/v7/consensus-types/primitives"
+	"github.com/OffchainLabs/prysm/v7/encoding/bytesutil"
+	enginev1 "github.com/OffchainLabs/prysm/v7/proto/engine/v1"
+	"github.com/OffchainLabs/prysm/v7/runtime/version"
+	"github.com/OffchainLabs/prysm/v7/time/slots"
+)
+
+// ExpectedWithdrawalsGloas returns the withdrawals that a proposer will need to pack in the next block
+// applied to the current state. It is also used by validators to check that the execution payload carried
+// the right number of withdrawals.
+//
+// Spec v1.7.0-alpha.1:
+//
+//	def get_expected_withdrawals(state: BeaconState) -> ExpectedWithdrawals:
+//	    withdrawal_index = state.next_withdrawal_index
+//	    withdrawals: List[Withdrawal] = []
+//
+//	    # [New in Gloas:EIP7732]
+//	    # Get builder withdrawals
+//	    builder_withdrawals, withdrawal_index, processed_builder_withdrawals_count = (
+//	        get_builder_withdrawals(state, withdrawal_index, withdrawals)
+//	    )
+//	    withdrawals.extend(builder_withdrawals)
+//
+//	    # Get partial withdrawals
+//	    partial_withdrawals, withdrawal_index, processed_partial_withdrawals_count = (
+//	        get_pending_partial_withdrawals(state, withdrawal_index, withdrawals)
+//	    )
+//	    withdrawals.extend(partial_withdrawals)
+//
+//	    # [New in Gloas:EIP7732]
+//	    # Get builders sweep withdrawals
+//	    builders_sweep_withdrawals, withdrawal_index, processed_builders_sweep_count = (
+//	        get_builders_sweep_withdrawals(state, withdrawal_index, withdrawals)
+//	    )
+//	    withdrawals.extend(builders_sweep_withdrawals)
+//
+//	    # Get validators sweep withdrawals
+//	    validators_sweep_withdrawals, withdrawal_index, processed_validators_sweep_count = (
+//	        get_validators_sweep_withdrawals(state, withdrawal_index, withdrawals)
+//	    )
+//	    withdrawals.extend(validators_sweep_withdrawals)
+//
+//	    return ExpectedWithdrawals(
+//	        withdrawals,
+//	        # [New in Gloas:EIP7732]
+//	        processed_builder_withdrawals_count,
+//	        processed_partial_withdrawals_count,
+//	        # [New in Gloas:EIP7732]
+//	        processed_builders_sweep_count,
+//	        processed_validators_sweep_count,
+//	    )
+func (b *BeaconState) ExpectedWithdrawalsGloas() ([]*enginev1.Withdrawal, uint64, uint64, primitives.BuilderIndex, error) {
+	if b.version < version.Gloas {
+		return nil, 0, 0, 0, errNotSupported("ExpectedWithdrawalsGloas", b.version)
+	}
+
+	b.lock.RLock()
+	defer b.lock.RUnlock()
+
+	cfg := params.BeaconConfig()
+	withdrawals := make([]*enginev1.Withdrawal, 0, cfg.MaxWithdrawalsPerPayload)
+	withdrawalIndex := b.nextWithdrawalIndex
+
+	withdrawalIndex, processedBuilderWithdrawalsCount, err := b.appendBuilderWithdrawalsGloas(withdrawalIndex, &withdrawals)
+	if err != nil {
+		return nil, 0, 0, 0, err
+	}
+
+	withdrawalIndex, processedPartialWithdrawalsCount, err := b.appendPendingPartialWithdrawals(withdrawalIndex, &withdrawals)
+	if err != nil {
+		return nil, 0, 0, 0, err
+	}
+
+	withdrawalIndex, processedBuildersSweepCount, err := b.appendBuildersSweepWithdrawalsGloas(withdrawalIndex, &withdrawals)
+	if err != nil {
+		return nil, 0, 0, 0, err
+	}
+
+	err = b.appendValidatorsSweepWithdrawals(withdrawalIndex, &withdrawals)
+	if err != nil {
+		return nil, 0, 0, 0, err
+	}
+
+	return withdrawals, processedBuilderWithdrawalsCount, processedPartialWithdrawalsCount, b.nextWithdrawalBuilderIndex + primitives.BuilderIndex(processedBuildersSweepCount), nil
+}
+
+func (b *BeaconState) appendBuilderWithdrawalsGloas(withdrawalIndex uint64, withdrawals *[]*enginev1.Withdrawal) (uint64, uint64, error) {
+	cfg := params.BeaconConfig()
+	withdrawalsLimit := cfg.MaxWithdrawalsPerPayload - 1
+	ws := *withdrawals
+	var processedCount uint64
+	for _, w := range b.builderPendingWithdrawals {
+		if uint64(len(ws)) >= withdrawalsLimit {
+			break
+		}
+		if w == nil {
+			continue
+		}
+		ws = append(ws, &enginev1.Withdrawal{
+			Index: withdrawalIndex,
+			ValidatorIndex: primitives.ValidatorIndex(
+				uint64(primitives.BuilderIndex(w.BuilderIndex)) | cfg.BuilderIndexFlag,
+			),
+			Address: bytesutil.SafeCopyBytes(w.FeeRecipient),
+			Amount:  uint64(w.Amount),
+		})
+		withdrawalIndex++
+		processedCount++
+	}
+	*withdrawals = ws
+	return withdrawalIndex, processedCount, nil
+}
+
+func (b *BeaconState) appendBuildersSweepWithdrawalsGloas(withdrawalIndex uint64, withdrawals *[]*enginev1.Withdrawal) (uint64, uint64, error) {
+	cfg := params.BeaconConfig()
+	withdrawalsLimit := cfg.MaxWithdrawalsPerPayload - 1
+	priorWithdrawalCount := uint64(len(*withdrawals))
+
+	if priorWithdrawalCount >= withdrawalsLimit || len(b.builders) == 0 {
+		return withdrawalIndex, 0, nil
+	}
+
+	ws := *withdrawals
+	epoch := slots.ToEpoch(b.slot)
+
+	buildersLimit := len(b.builders)
+	if maxBuilders := int(cfg.MaxBuildersPerWithdrawalsSweep); buildersLimit > maxBuilders {
+		buildersLimit = maxBuilders
+	}
+
+	builderIndex := b.nextWithdrawalBuilderIndex
+	if uint64(builderIndex) >= uint64(len(b.builders)) {
+		return withdrawalIndex, 0, fmt.Errorf("next withdrawal builder index %d out of range", builderIndex)
+	}
+	var processedCount uint64
+	for i := 0; i < buildersLimit; i++ {
+		if uint64(len(ws)) >= withdrawalsLimit {
+			break
+		}
+
+		builder := b.builders[builderIndex]
+		if builder != nil && builder.WithdrawableEpoch <= epoch && builder.Balance > 0 {
+			ws = append(ws, &enginev1.Withdrawal{
+				Index:          withdrawalIndex,
+				ValidatorIndex: primitives.ValidatorIndex(uint64(builderIndex) | cfg.BuilderIndexFlag),
+				Address:        bytesutil.SafeCopyBytes(builder.ExecutionAddress),
+				Amount:         uint64(builder.Balance),
+			})
+			withdrawalIndex++
+		}
+
+		builderIndex = primitives.BuilderIndex((uint64(builderIndex) + 1) % uint64(len(b.builders)))
+		processedCount++
+	}
+
+	*withdrawals = ws
+	return withdrawalIndex, processedCount, nil
+}

beacon-chain/state/state-native/getters_withdrawal.go

@@ -113,77 +113,111 @@ func (b *BeaconState) ExpectedWithdrawals() ([]*enginev1.Withdrawal, uint64, err
 	defer b.lock.RUnlock()
 
 	withdrawals := make([]*enginev1.Withdrawal, 0, params.BeaconConfig().MaxWithdrawalsPerPayload)
-	validatorIndex := b.nextWithdrawalValidatorIndex
 	withdrawalIndex := b.nextWithdrawalIndex
-	epoch := slots.ToEpoch(b.slot)
 
-	// Electra partial withdrawals functionality.
-	var processedPartialWithdrawalsCount uint64
-	if b.version >= version.Electra {
-		for _, w := range b.pendingPartialWithdrawals {
-			if w.WithdrawableEpoch > epoch || len(withdrawals) >= int(params.BeaconConfig().MaxPendingPartialsPerWithdrawalsSweep) {
-				break
-			}
-
-			v, err := b.validatorAtIndexReadOnly(w.Index)
-			if err != nil {
-				return nil, 0, fmt.Errorf("failed to determine withdrawals at index %d: %w", w.Index, err)
-			}
-			vBal, err := b.balanceAtIndex(w.Index)
-			if err != nil {
-				return nil, 0, fmt.Errorf("could not retrieve balance at index %d: %w", w.Index, err)
-			}
-			hasSufficientEffectiveBalance := v.EffectiveBalance() >= params.BeaconConfig().MinActivationBalance
-			var totalWithdrawn uint64
-			for _, wi := range withdrawals {
-				if wi.ValidatorIndex == w.Index {
-					totalWithdrawn += wi.Amount
-				}
-			}
-			balance, err := mathutil.Sub64(vBal, totalWithdrawn)
-			if err != nil {
-				return nil, 0, errors.Wrapf(err, "failed to subtract balance %d with total withdrawn %d", vBal, totalWithdrawn)
-			}
-			hasExcessBalance := balance > params.BeaconConfig().MinActivationBalance
-			if v.ExitEpoch() == params.BeaconConfig().FarFutureEpoch && hasSufficientEffectiveBalance && hasExcessBalance {
-				amount := min(balance-params.BeaconConfig().MinActivationBalance, w.Amount)
-				withdrawals = append(withdrawals, &enginev1.Withdrawal{
-					Index:          withdrawalIndex,
-					ValidatorIndex: w.Index,
-					Address:        v.GetWithdrawalCredentials()[12:],
-					Amount:         amount,
-				})
-				withdrawalIndex++
-			}
-			processedPartialWithdrawalsCount++
-		}
+	withdrawalIndex, processedPartialWithdrawalsCount, err := b.appendPendingPartialWithdrawals(withdrawalIndex, &withdrawals)
+	if err != nil {
+		return nil, 0, err
 	}
 
+	err = b.appendValidatorsSweepWithdrawals(withdrawalIndex, &withdrawals)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	return withdrawals, processedPartialWithdrawalsCount, nil
+}
+
+func (b *BeaconState) appendPendingPartialWithdrawals(withdrawalIndex uint64, withdrawals *[]*enginev1.Withdrawal) (uint64, uint64, error) {
+	if b.version < version.Electra {
+		return withdrawalIndex, 0, nil
+	}
+
+	cfg := params.BeaconConfig()
+	withdrawalsLimit := min(
+		uint64(len(*withdrawals))+cfg.MaxPendingPartialsPerWithdrawalsSweep,
+		cfg.MaxWithdrawalsPerPayload-1,
+	)
+	if uint64(len(*withdrawals)) > withdrawalsLimit {
+		return withdrawalIndex, 0, fmt.Errorf("prior withdrawals length %d exceeds limit %d", len(*withdrawals), withdrawalsLimit)
+	}
+
+	ws := *withdrawals
+	epoch := slots.ToEpoch(b.slot)
+	var processedPartialWithdrawalsCount uint64
+	for _, w := range b.pendingPartialWithdrawals {
+		isWithdrawable := w.WithdrawableEpoch <= epoch
+		hasReachedLimit := uint64(len(ws)) >= withdrawalsLimit
+		if !isWithdrawable || hasReachedLimit {
+			break
+		}
+
+		v, err := b.validatorAtIndexReadOnly(w.Index)
+		if err != nil {
+			return withdrawalIndex, 0, fmt.Errorf("failed to determine withdrawals at index %d: %w", w.Index, err)
+		}
+		vBal, err := b.balanceAtIndex(w.Index)
+		if err != nil {
+			return withdrawalIndex, 0, fmt.Errorf("could not retrieve balance at index %d: %w", w.Index, err)
+		}
+		hasSufficientEffectiveBalance := v.EffectiveBalance() >= cfg.MinActivationBalance
+		var totalWithdrawn uint64
+		for _, wi := range ws {
+			if wi.ValidatorIndex == w.Index {
+				totalWithdrawn += wi.Amount
+			}
+		}
+		balance, err := mathutil.Sub64(vBal, totalWithdrawn)
+		if err != nil {
+			return withdrawalIndex, 0, errors.Wrapf(err, "failed to subtract balance %d with total withdrawn %d", vBal, totalWithdrawn)
+		}
+		hasExcessBalance := balance > cfg.MinActivationBalance
+		if v.ExitEpoch() == cfg.FarFutureEpoch && hasSufficientEffectiveBalance && hasExcessBalance {
+			amount := min(balance-cfg.MinActivationBalance, w.Amount)
+			ws = append(ws, &enginev1.Withdrawal{
+				Index:          withdrawalIndex,
+				ValidatorIndex: w.Index,
+				Address:        v.GetWithdrawalCredentials()[12:],
+				Amount:         amount,
+			})
+			withdrawalIndex++
+		}
+		processedPartialWithdrawalsCount++
+	}
+
+	*withdrawals = ws
+	return withdrawalIndex, processedPartialWithdrawalsCount, nil
+}
+
+func (b *BeaconState) appendValidatorsSweepWithdrawals(withdrawalIndex uint64, withdrawals *[]*enginev1.Withdrawal) error {
+	ws := *withdrawals
+	validatorIndex := b.nextWithdrawalValidatorIndex
 	validatorsLen := b.validatorsLen()
+	epoch := slots.ToEpoch(b.slot)
 	bound := min(uint64(validatorsLen), params.BeaconConfig().MaxValidatorsPerWithdrawalsSweep)
 	for range bound {
 		val, err := b.validatorAtIndexReadOnly(validatorIndex)
 		if err != nil {
-			return nil, 0, errors.Wrapf(err, "could not retrieve validator at index %d", validatorIndex)
+			return errors.Wrapf(err, "could not retrieve validator at index %d", validatorIndex)
 		}
 		balance, err := b.balanceAtIndex(validatorIndex)
 		if err != nil {
-			return nil, 0, errors.Wrapf(err, "could not retrieve balance at index %d", validatorIndex)
+			return errors.Wrapf(err, "could not retrieve balance at index %d", validatorIndex)
 		}
 		if b.version >= version.Electra {
 			var partiallyWithdrawnBalance uint64
-			for _, w := range withdrawals {
+			for _, w := range ws {
 				if w.ValidatorIndex == validatorIndex {
 					partiallyWithdrawnBalance += w.Amount
 				}
 			}
 			balance, err = mathutil.Sub64(balance, partiallyWithdrawnBalance)
 			if err != nil {
-				return nil, 0, errors.Wrapf(err, "could not subtract balance %d with partial withdrawn balance %d", balance, partiallyWithdrawnBalance)
+				return errors.Wrapf(err, "could not subtract balance %d with partial withdrawn balance %d", balance, partiallyWithdrawnBalance)
 			}
 		}
 		if helpers.IsFullyWithdrawableValidator(val, balance, epoch, b.version) {
-			withdrawals = append(withdrawals, &enginev1.Withdrawal{
+			ws = append(ws, &enginev1.Withdrawal{
 				Index:          withdrawalIndex,
 				ValidatorIndex: validatorIndex,
 				Address:        bytesutil.SafeCopyBytes(val.GetWithdrawalCredentials()[ETH1AddressOffset:]),
@@ -191,7 +225,7 @@ func (b *BeaconState) ExpectedWithdrawals() ([]*enginev1.Withdrawal, uint64, err
 			})
 			withdrawalIndex++
 		} else if helpers.IsPartiallyWithdrawableValidator(val, balance, epoch, b.version) {
-			withdrawals = append(withdrawals, &enginev1.Withdrawal{
+			ws = append(ws, &enginev1.Withdrawal{
 				Index:          withdrawalIndex,
 				ValidatorIndex: validatorIndex,
 				Address:        bytesutil.SafeCopyBytes(val.GetWithdrawalCredentials()[ETH1AddressOffset:]),
@@ -199,7 +233,7 @@ func (b *BeaconState) ExpectedWithdrawals() ([]*enginev1.Withdrawal, uint64, err
 			})
 			withdrawalIndex++
 		}
-		if uint64(len(withdrawals)) == params.BeaconConfig().MaxWithdrawalsPerPayload {
+		if uint64(len(ws)) == params.BeaconConfig().MaxWithdrawalsPerPayload {
 			break
 		}
 		validatorIndex += 1
@@ -208,7 +242,8 @@ func (b *BeaconState) ExpectedWithdrawals() ([]*enginev1.Withdrawal, uint64, err
 		}
 	}
 
-	return withdrawals, processedPartialWithdrawalsCount, nil
+	*withdrawals = ws
+	return nil
 }
 
 func (b *BeaconState) PendingPartialWithdrawals() ([]*ethpb.PendingPartialWithdrawal, error) {

beacon-chain/state/state-native/setters_gloas.go

@@ -1,6 +1,7 @@
 package state_native
 
 import (
+	"errors"
 	"fmt"
 
 	"github.com/OffchainLabs/prysm/v7/beacon-chain/state/state-native/types"
@@ -8,10 +9,32 @@ import (
 	"github.com/OffchainLabs/prysm/v7/config/params"
 	"github.com/OffchainLabs/prysm/v7/consensus-types/interfaces"
 	"github.com/OffchainLabs/prysm/v7/consensus-types/primitives"
+	enginev1 "github.com/OffchainLabs/prysm/v7/proto/engine/v1"
 	ethpb "github.com/OffchainLabs/prysm/v7/proto/prysm/v1alpha1"
 	"github.com/OffchainLabs/prysm/v7/runtime/version"
 )
 
+// SetPayloadExpectedWithdrawals stores the expected withdrawals for the next payload.
+func (b *BeaconState) SetPayloadExpectedWithdrawals(withdrawals []*enginev1.Withdrawal) error {
+	if b.version < version.Gloas {
+		return errNotSupported("SetPayloadExpectedWithdrawals", b.version)
+	}
+
+	if withdrawals == nil {
+		return errors.New("cannot set nil payload expected withdrawals")
+	}
+
+	b.lock.Lock()
+	defer b.lock.Unlock()
+
+	b.sharedFieldReferences[types.PayloadExpectedWithdrawals].MinusRef()
+	b.sharedFieldReferences[types.PayloadExpectedWithdrawals] = stateutil.NewRef(1)
+	b.payloadExpectedWithdrawals = withdrawals
+	b.markFieldAsDirty(types.PayloadExpectedWithdrawals)
+
+	return nil
+}
+
 // RotateBuilderPendingPayments rotates the queue by dropping slots per epoch payments from the
 // front and appending slots per epoch empty payments to the end.
 // This implements: state.builder_pending_payments = state.builder_pending_payments[SLOTS_PER_EPOCH:] + [BuilderPendingPayment() for _ in range(SLOTS_PER_EPOCH)]
@@ -69,6 +92,38 @@ func (b *BeaconState) AppendBuilderPendingWithdrawals(withdrawals []*ethpb.Build
 	return nil
 }
 
+// DequeueBuilderPendingWithdrawals removes processed builder withdrawals from the front of the queue.
+func (b *BeaconState) DequeueBuilderPendingWithdrawals(n uint64) error {
+	if b.version < version.Gloas {
+		return errNotSupported("DequeueBuilderPendingWithdrawals", b.version)
+	}
+
+	if n > uint64(len(b.builderPendingWithdrawals)) {
+		return errors.New("cannot dequeue more builder withdrawals than are in the queue")
+	}
+
+	if n == 0 {
+		return nil
+	}
+
+	b.lock.Lock()
+	defer b.lock.Unlock()
+
+	if b.sharedFieldReferences[types.BuilderPendingWithdrawals].Refs() > 1 {
+		withdrawals := make([]*ethpb.BuilderPendingWithdrawal, len(b.builderPendingWithdrawals))
+		copy(withdrawals, b.builderPendingWithdrawals)
+		b.builderPendingWithdrawals = withdrawals
+		b.sharedFieldReferences[types.BuilderPendingWithdrawals].MinusRef()
+		b.sharedFieldReferences[types.BuilderPendingWithdrawals] = stateutil.NewRef(1)
+	}
+
+	b.builderPendingWithdrawals = b.builderPendingWithdrawals[n:]
+	b.markFieldAsDirty(types.BuilderPendingWithdrawals)
+	b.rebuildTrie[types.BuilderPendingWithdrawals] = true
+
+	return nil
+}
+
 // SetExecutionPayloadBid sets the latest execution payload bid in the state.
 func (b *BeaconState) SetExecutionPayloadBid(h interfaces.ROExecutionPayloadBid) error {
 	if b.version < version.Gloas {
@@ -161,3 +216,65 @@ func (b *BeaconState) UpdateExecutionPayloadAvailabilityAtIndex(idx uint64, val
 	b.markFieldAsDirty(types.ExecutionPayloadAvailability)
 	return nil
 }
+
+// SetNextWithdrawalBuilderIndex sets the next builder index for the withdrawals sweep.
+func (b *BeaconState) SetNextWithdrawalBuilderIndex(index primitives.BuilderIndex) error {
+	if b.version < version.Gloas {
+		return errNotSupported("SetNextWithdrawalBuilderIndex", b.version)
+	}
+
+	b.lock.Lock()
+	defer b.lock.Unlock()
+
+	b.nextWithdrawalBuilderIndex = index
+	b.markFieldAsDirty(types.NextWithdrawalBuilderIndex)
+	return nil
+}
+
+// DecreaseBuilderBalance decreases the builder's balance by amount (saturating at 0).
+func (b *BeaconState) DecreaseBuilderBalance(builderIndex primitives.BuilderIndex, amount uint64) error {
+	if b.version < version.Gloas {
+		return errNotSupported("DecreaseBuilderBalance", b.version)
+	}
+	if amount == 0 {
+		return nil
+	}
+
+	b.lock.Lock()
+	defer b.lock.Unlock()
+
+	idx := uint64(builderIndex)
+	if idx >= uint64(len(b.builders)) {
+		return fmt.Errorf("builder index %d out of range (len=%d)", builderIndex, len(b.builders))
+	}
+
+	// Copy-on-write for shared builders registry.
+	if b.sharedFieldReferences[types.Builders].Refs() > 1 {
+		builders := make([]*ethpb.Builder, len(b.builders))
+		copy(builders, b.builders)
+		b.builders = builders
+		b.sharedFieldReferences[types.Builders].MinusRef()
+		b.sharedFieldReferences[types.Builders] = stateutil.NewRef(1)
+
+		// Ensure we don't mutate a shared builder pointer.
+		if b.builders[idx] != nil {
+			b.builders[idx] = ethpb.CopyBuilder(b.builders[idx])
+		}
+	}
+
+	builder := b.builders[idx]
+	if builder == nil {
+		return fmt.Errorf("builder at index %d is nil", builderIndex)
+	}
+
+	bal := uint64(builder.Balance)
+	if amount >= bal {
+		builder.Balance = 0
+	} else {
+		builder.Balance = primitives.Gwei(bal - amount)
+	}
+
+	b.markFieldAsDirty(types.Builders)
+	b.addDirtyIndices(types.Builders, []uint64{idx})
+	return nil
+}

beacon-chain/state/state-native/setters_gloas_test.go

@@ -318,6 +318,62 @@ func TestUpdateExecutionPayloadAvailabilityAtIndex_OutOfRange(t *testing.T) {
 	}
 }
 
+func TestDecreaseBuilderBalance(t *testing.T) {
+	t.Run("previous fork returns expected error", func(t *testing.T) {
+		st := &BeaconState{version: version.Fulu}
+		err := st.DecreaseBuilderBalance(0, 1)
+		require.ErrorContains(t, "DecreaseBuilderBalance", err)
+	})
+
+	t.Run("decreases and saturates", func(t *testing.T) {
+		st := &BeaconState{
+			version:     version.Gloas,
+			dirtyFields: make(map[types.FieldIndex]bool),
+			sharedFieldReferences: map[types.FieldIndex]*stateutil.Reference{
+				types.Builders: stateutil.NewRef(1),
+			},
+			builders: []*ethpb.Builder{
+				{Balance: 10},
+			},
+		}
+
+		require.NoError(t, st.DecreaseBuilderBalance(0, 3))
+		require.Equal(t, uint64(7), uint64(st.builders[0].Balance))
+		require.Equal(t, true, st.dirtyFields[types.Builders])
+
+		require.NoError(t, st.DecreaseBuilderBalance(0, 100))
+		require.Equal(t, uint64(0), uint64(st.builders[0].Balance))
+	})
+
+	t.Run("copy-on-write preserves shared state", func(t *testing.T) {
+		sharedRef := stateutil.NewRef(2)
+		sharedBuilders := []*ethpb.Builder{
+			{Balance: 10},
+		}
+
+		st1 := &BeaconState{
+			version:     version.Gloas,
+			dirtyFields: make(map[types.FieldIndex]bool),
+			sharedFieldReferences: map[types.FieldIndex]*stateutil.Reference{
+				types.Builders: sharedRef,
+			},
+			builders: sharedBuilders,
+		}
+		st2 := &BeaconState{
+			version:     version.Gloas,
+			dirtyFields: make(map[types.FieldIndex]bool),
+			sharedFieldReferences: map[types.FieldIndex]*stateutil.Reference{
+				types.Builders: sharedRef,
+			},
+			builders: sharedBuilders,
+		}
+
+		require.NoError(t, st1.DecreaseBuilderBalance(0, 3))
+		require.Equal(t, uint64(7), uint64(st1.builders[0].Balance))
+		require.Equal(t, uint64(10), uint64(st2.builders[0].Balance))
+	})
+}
+
 func newGloasStateWithAvailability(t *testing.T, availability []byte) *BeaconState {
 	t.Helper()
 

changelog/terencechain_refactor-expected-withdrawals.md

@@ -0,0 +1,2 @@
+### Ignored
+- Refactor expected withdrawals into reusable helpers for future forks.

config/params/config.go

@@ -47,6 +47,7 @@ type BeaconChainConfig struct {
 	HysteresisQuotient             uint64 `yaml:"HYSTERESIS_QUOTIENT" spec:"true"`                // HysteresisQuotient defines the hysteresis quotient for effective balance calculations.
 	HysteresisDownwardMultiplier   uint64 `yaml:"HYSTERESIS_DOWNWARD_MULTIPLIER" spec:"true"`     // HysteresisDownwardMultiplier defines the hysteresis downward multiplier for effective balance calculations.
 	HysteresisUpwardMultiplier     uint64 `yaml:"HYSTERESIS_UPWARD_MULTIPLIER" spec:"true"`       // HysteresisUpwardMultiplier defines the hysteresis upward multiplier for effective balance calculations.
+	BuilderIndexFlag               uint64 `yaml:"BUILDER_INDEX_FLAG" spec:"true"`                  // BuilderIndexFlag marks a ValidatorIndex as a BuilderIndex when the bit is set.
 
 	// Gwei value constants.
 	MinDepositAmount          uint64 `yaml:"MIN_DEPOSIT_AMOUNT" spec:"true"`          // MinDepositAmount is the minimum amount of Gwei a validator can send to the deposit contract at once (lower amounts will be reverted).
@@ -126,6 +127,7 @@ type BeaconChainConfig struct {
 	MaxWithdrawalsPerPayload         uint64 `yaml:"MAX_WITHDRAWALS_PER_PAYLOAD" spec:"true"`          // MaxWithdrawalsPerPayload defines the maximum number of withdrawals in a block.
 	MaxBlsToExecutionChanges         uint64 `yaml:"MAX_BLS_TO_EXECUTION_CHANGES" spec:"true"`         // MaxBlsToExecutionChanges defines the maximum number of BLS-to-execution-change objects in a block.
 	MaxValidatorsPerWithdrawalsSweep uint64 `yaml:"MAX_VALIDATORS_PER_WITHDRAWALS_SWEEP" spec:"true"` // MaxValidatorsPerWithdrawalsSweep bounds the size of the sweep searching for withdrawals per slot.
+	MaxBuildersPerWithdrawalsSweep   uint64 `yaml:"MAX_BUILDERS_PER_WITHDRAWALS_SWEEP" spec:"true"`   // MaxBuildersPerWithdrawalsSweep bounds the size of the builder withdrawals sweep per slot.
 
 	// BLS domain values.
 	DomainBeaconProposer              [4]byte `yaml:"DOMAIN_BEACON_PROPOSER" spec:"true"`                // DomainBeaconProposer defines the BLS signature domain for beacon proposal verification.

config/params/loader.go

@@ -194,6 +194,8 @@ func ConfigToYaml(cfg *BeaconChainConfig) []byte {
 		fmt.Sprintf("SHARD_COMMITTEE_PERIOD: %d", cfg.ShardCommitteePeriod),
 		fmt.Sprintf("MIN_VALIDATOR_WITHDRAWABILITY_DELAY: %d", cfg.MinValidatorWithdrawabilityDelay),
 		fmt.Sprintf("MAX_VALIDATORS_PER_WITHDRAWALS_SWEEP: %d", cfg.MaxValidatorsPerWithdrawalsSweep),
+		fmt.Sprintf("MAX_BUILDERS_PER_WITHDRAWALS_SWEEP: %d", cfg.MaxBuildersPerWithdrawalsSweep),
+		fmt.Sprintf("BUILDER_INDEX_FLAG: %d", cfg.BuilderIndexFlag),
 		fmt.Sprintf("MAX_SEED_LOOKAHEAD: %d", cfg.MaxSeedLookahead),
 		fmt.Sprintf("EJECTION_BALANCE: %d", cfg.EjectionBalance),
 		fmt.Sprintf("MIN_PER_EPOCH_CHURN_LIMIT: %d", cfg.MinPerEpochChurnLimit),

config/params/mainnet_config.go

@@ -83,6 +83,7 @@ var mainnetBeaconConfig = &BeaconChainConfig{
 	HysteresisQuotient:             4,
 	HysteresisDownwardMultiplier:   1,
 	HysteresisUpwardMultiplier:     5,
+	BuilderIndexFlag:               1099511627776,
 
 	// Gwei value constants.
 	MinDepositAmount:          1 * 1e9,
@@ -169,6 +170,7 @@ var mainnetBeaconConfig = &BeaconChainConfig{
 	MaxWithdrawalsPerPayload:         16,
 	MaxBlsToExecutionChanges:         16,
 	MaxValidatorsPerWithdrawalsSweep: 16384,
+	MaxBuildersPerWithdrawalsSweep:   16384,
 
 	// BLS domain values.
 	DomainBeaconProposer:              bytesutil.Uint32ToBytes4(0x00000000),

config/params/testnet_config_test.go

@@ -49,6 +49,7 @@ func compareConfigs(t *testing.T, expected, actual *params.BeaconChainConfig) {
 	require.DeepEqual(t, expected.HysteresisQuotient, actual.HysteresisQuotient)
 	require.DeepEqual(t, expected.HysteresisDownwardMultiplier, actual.HysteresisDownwardMultiplier)
 	require.DeepEqual(t, expected.HysteresisUpwardMultiplier, actual.HysteresisUpwardMultiplier)
+	require.DeepEqual(t, expected.BuilderIndexFlag, actual.BuilderIndexFlag)
 	require.DeepEqual(t, expected.MinDepositAmount, actual.MinDepositAmount)
 	require.DeepEqual(t, expected.MaxEffectiveBalance, actual.MaxEffectiveBalance)
 	require.DeepEqual(t, expected.EjectionBalance, actual.EjectionBalance)
@@ -94,6 +95,7 @@ func compareConfigs(t *testing.T, expected, actual *params.BeaconChainConfig) {
 	require.DeepEqual(t, expected.MaxDeposits, actual.MaxDeposits)
 	require.DeepEqual(t, expected.MaxVoluntaryExits, actual.MaxVoluntaryExits)
 	require.DeepEqual(t, expected.MaxWithdrawalsPerPayload, actual.MaxWithdrawalsPerPayload)
+	require.DeepEqual(t, expected.MaxBuildersPerWithdrawalsSweep, actual.MaxBuildersPerWithdrawalsSweep)
 	require.DeepEqual(t, expected.DomainBeaconProposer, actual.DomainBeaconProposer)
 	require.DeepEqual(t, expected.DomainRandao, actual.DomainRandao)
 	require.DeepEqual(t, expected.DomainBeaconAttester, actual.DomainBeaconAttester)