feat(withdrawals): Allow for Disabling Withdrawals [DO NOT MERGE]

chain/data.go

@@ -95,6 +95,10 @@ type SpecData struct {
 	Deneb1ForkTime uint64 `mapstructure:"deneb-one-fork-time"`
 	// ElectraForkTime is the time at which the Electra fork is activated.
 	ElectraForkTime uint64 `mapstructure:"electra-fork-time"`
+	// ElectraDisableWithdrawalsForkTime is the time at which withdrawals were first disabled (if disabled).
+	ElectraDisableWithdrawalsForkTime uint64 `mapstructure:"electra-disable-withdrawals-fork-time"`
+	// ElectraEnableWithdrawalsForkTime is the time at which withdrawals were enabled after disabling
+	ElectraEnableWithdrawalsForkTime uint64 `mapstructure:"electra-enable-withdrawals-fork-time"`
 
 	// State list lengths
 	//

chain/helpers.go

@@ -27,6 +27,12 @@ import (
 )
 
 // ActiveForkVersionForTimestamp returns the active fork version for a given timestamp.
+// Note that ActiveForkVersionForTimestamp will NOT check for
+//   - ElectraDisableWithdrawalsForkTime
+//   - ElectraEnableWithdrawalsForkTime
+//
+// As there is no logic that relies on the above forks that goes through ActiveForkVersionForTimestamp.
+// It also gives flexibility for these forks to occur at any point after Electra, e.g. after Electra1.
 func (s spec) ActiveForkVersionForTimestamp(timestamp math.U64) common.Version {
 	time := timestamp.Unwrap()
 	if time >= s.ElectraForkTime() {
@@ -38,6 +44,13 @@ func (s spec) ActiveForkVersionForTimestamp(timestamp math.U64) common.Version {
 	return version.Deneb()
 }
 
+// WithdrawalsDisabled is a switch that can be used to freeze withdrawals in an emergency scenario.
+// An exception is made for the EVM inflation withdrawal which is always active.
+func (s spec) WithdrawalsDisabled(timestamp math.U64) bool {
+	time := timestamp.Unwrap()
+	return time >= s.ElectraDisableWithdrawalsForkTime() && time < s.ElectraEnableWithdrawalsForkTime()
+}
+
 // GenesisForkVersion returns the fork version at genesis.
 func (s spec) GenesisForkVersion() common.Version {
 	return s.ActiveForkVersionForTimestamp(math.U64(s.GenesisTime()))

chain/spec.go

@@ -164,6 +164,10 @@ type WithdrawalsSpec interface {
 	// which is set to MIN_VALIDATOR_WITHDRAWABILITY_DELAY epochs after its exit_epoch.
 	// This is to allow some extra time for any slashable offences by the validator to be detected and reported.
 	MinValidatorWithdrawabilityDelay() math.Epoch
+
+	// WithdrawalsDisabled is a switch that can be used to freeze withdrawals in an emergency scenario.
+	// An exception is made for the EVM inflation withdrawal which is always active.
+	WithdrawalsDisabled(timestamp math.U64) bool
 }
 
 // Spec defines an interface for accessing chain-specific parameters.
@@ -365,16 +369,26 @@ func (s spec) GenesisTime() uint64 {
 	return s.Data.GenesisTime
 }
 
-// Deneb1ForkTime returns the epoch of the Deneb1 fork.
+// Deneb1ForkTime returns the timestamp of the Deneb1 fork.
 func (s spec) Deneb1ForkTime() uint64 {
 	return s.Data.Deneb1ForkTime
 }
 
-// ElectraForkTime returns the epoch of the Electra fork.
+// ElectraForkTime returns the timestamp of the Electra fork.
 func (s spec) ElectraForkTime() uint64 {
 	return s.Data.ElectraForkTime
 }
 
+// ElectraDisableWithdrawalsForkTime returns the timestamps of the ElectraDisableWithdrawalsForkTime fork.
+func (s spec) ElectraDisableWithdrawalsForkTime() uint64 {
+	return s.Data.ElectraDisableWithdrawalsForkTime
+}
+
+// ElectraEnableWithdrawalsForkTime returns the timestamps of the ElectraEnableWithdrawalsForkTime fork.
+func (s spec) ElectraEnableWithdrawalsForkTime() uint64 {
+	return s.Data.ElectraEnableWithdrawalsForkTime
+}
+
 // EpochsPerHistoricalVector returns the number of epochs per historical vector.
 func (s spec) EpochsPerHistoricalVector() uint64 {
 	return s.Data.EpochsPerHistoricalVector

config/spec/defaults.go

@@ -55,6 +55,11 @@ const (
 	defaultEth1FollowDistance        = 1 // Berachain specific.
 	defaultTargetSecondsPerEth1Block = 2 // Berachain specific.
 
+	// Fork-related values.
+	defaultFarFutureTimestamp                = 9999999999999999 // a future timestamp as not yet determined.
+	defaultElectraDisableWithdrawalsForkTime = defaultFarFutureTimestamp
+	defaultElectraEnableWithdrawalsForkTime  = defaultFarFutureTimestamp
+
 	// State list length constants.
 	defaultEpochsPerHistoricalVector = 8
 	defaultEpochsPerSlashingsVector  = 8

config/spec/devnet.go

@@ -48,6 +48,11 @@ const (
 	// devnet is configured to start on electra.
 	devnetElectraForkTime = 0
 
+	// devnetElectraDisableWithdrawalsForkTime is the start time at which withdrawals are disabled
+	devnetElectraDisableWithdrawalsForkTime = defaultFarFutureTimestamp
+	// devnetElectraEnableWithdrawalsForkTime is the start time at which withdrawals are re-enabled
+	devnetElectraEnableWithdrawalsForkTime = defaultFarFutureTimestamp
+
 	// devnetEVMInflationAddressDeneb1 is the address of the EVM inflation contract
 	// after the Deneb1 fork.
 	devnetEVMInflationAddressDeneb1 = "0x4206942069420694206942069420694206942069"
@@ -72,6 +77,8 @@ func DevnetChainSpecData() *chain.SpecData {
 	specData.GenesisTime = devnetGenesisTime
 	specData.Deneb1ForkTime = devnetDeneb1ForkTime
 	specData.ElectraForkTime = devnetElectraForkTime
+	specData.ElectraDisableWithdrawalsForkTime = devnetElectraDisableWithdrawalsForkTime
+	specData.ElectraEnableWithdrawalsForkTime = devnetElectraEnableWithdrawalsForkTime
 
 	// EVM inflation is different from mainnet to test.
 	specData.EVMInflationAddressGenesis = common.NewExecutionAddressFromHex(devnetEVMInflationAddress)

config/spec/mainnet.go

@@ -130,9 +130,11 @@ func MainnetChainSpecData() *chain.SpecData {
 		TargetSecondsPerEth1Block: defaultTargetSecondsPerEth1Block,
 
 		// Fork-related values.
-		GenesisTime:     mainnetGenesisTime,
-		Deneb1ForkTime:  mainnetDeneb1ForkTime,
-		ElectraForkTime: mainnetElectraForkTime,
+		GenesisTime:                       mainnetGenesisTime,
+		Deneb1ForkTime:                    mainnetDeneb1ForkTime,
+		ElectraForkTime:                   mainnetElectraForkTime,
+		ElectraDisableWithdrawalsForkTime: defaultElectraDisableWithdrawalsForkTime,
+		ElectraEnableWithdrawalsForkTime:  defaultElectraEnableWithdrawalsForkTime,
 
 		// State list length constants.
 		EpochsPerHistoricalVector: defaultEpochsPerHistoricalVector,

config/spec/testnet.go

@@ -40,6 +40,10 @@ func TestnetChainSpecData() *chain.SpecData {
 	// Timestamp of the Electra fork on Bepolia.
 	specData.ElectraForkTime = 1746633600
 
+	// Override the mainnet configuration for timestamps so it is not accidentally set on testnet a mainnet update.
+	specData.ElectraDisableWithdrawalsForkTime = defaultFarFutureTimestamp
+	specData.ElectraEnableWithdrawalsForkTime = defaultFarFutureTimestamp
+
 	return specData
 }
 

state-transition/core/state/statedb.go

@@ -116,6 +116,16 @@ func (s *StateDB) ExpectedWithdrawals(timestamp math.U64) (engineprimitives.With
 	// The first withdrawal is fixed to be the EVM inflation withdrawal.
 	withdrawals = append(withdrawals, s.EVMInflationWithdrawal(timestamp))
 
+	// If withdrawals are not enabled, return only the inflation withdrawal.
+	// Once withdrawals are re-enabled, all pending withdrawals will be processed.
+	// 1. Partial Withdrawal Requests will remain untouched and will be handled after re-enabling.
+	// 2. Validators whose balance is above MAX_EFFECTIVE_BALANCE will not be withdrawn till re-enabled.
+	// 3. Validators who have initiated a full withdrawal will not be withdrawn till re-enabled.
+	// 4. Validators who have been kicked out due to validator set cap will not be withdrawn till re-enabled.
+	if s.cs.WithdrawalsDisabled(timestamp) {
+		return withdrawals, processedPartialWithdrawals, nil
+	}
+
 	withdrawalIndex, err := s.GetNextWithdrawalIndex()
 	if err != nil {
 		return nil, 0, err

state-transition/core/state_processor_staking.go

@@ -67,8 +67,8 @@ func (sp *StateProcessor) processOperations(
 		}
 	}
 
+	// After Electra, validators can request withdrawals through execution requests which must be handled.
 	if version.EqualsOrIsAfter(blk.GetForkVersion(), version.Electra()) {
-		// After Electra, validators can request withdrawals through execution requests which must be handled.
 		requests, err := blk.GetBody().GetExecutionRequests()
 		if err != nil {
 			return err

testing/files/spec.toml

@@ -35,6 +35,8 @@ target-seconds-per-eth1-block = 2
 genesis-time = 0
 deneb-one-fork-time = 0
 electra-fork-time = 0
+electra-disable-withdrawals-fork-time = 9_999_999_999_999_999
+electra-enable-withdrawals-fork-time = 9_999_999_999_999_999
 
 # State list lengths
 epochs-per-historical-vector = 8

testing/networks/80069/spec.toml

@@ -35,6 +35,8 @@ target-seconds-per-eth1-block = 2
 genesis-time = 1_739_976_735
 deneb-one-fork-time = 1_740_090_694
 electra-fork-time = 1_746_633_600
+electra-disable-withdrawals-fork-time = 9_999_999_999_999_999
+electra-enable-withdrawals-fork-time = 9_999_999_999_999_999
 
 # State list lengths
 epochs-per-historical-vector = 8

testing/networks/80094/spec.toml

@@ -35,6 +35,8 @@ target-seconds-per-eth1-block = 2
 genesis-time = 1_737_381_600
 deneb-one-fork-time = 1_738_415_507
 electra-fork-time = 1_748_451_600
+electra-disable-withdrawals-fork-time = 9_999_999_999_999_999
+electra-enable-withdrawals-fork-time = 9_999_999_999_999_999
 
 # State list lengths
 epochs-per-historical-vector = 8

testing/simulated/components.go

@@ -144,3 +144,30 @@ func ProvidePectraWithdrawalTestChainSpec() (chain.Spec, error) {
 	}
 	return chainSpec, nil
 }
+
+// ProvideFreezeWithdrawalsChainSpec provides a chain spec with pectra as the genesis, but with the
+// withdrawals disabled and then re-enabled.
+func ProvideFreezeWithdrawalsChainSpec() (chain.Spec, error) {
+	specData := spec.TestnetChainSpecData()
+	// Both Deneb1 and Electra happen in genesis.
+	specData.GenesisTime = 0
+	specData.Deneb1ForkTime = 0
+	specData.ElectraForkTime = 0
+	// We set slots per epoch to 1 for faster observation of withdrawal behaviour
+	specData.SlotsPerEpoch = 1
+	// We set this to 4 so tests are faster
+	specData.MinValidatorWithdrawabilityDelay = 4
+	// Reduced validator set cap so eviction withdrawals are easier to trigger
+	specData.ValidatorSetCap = 1
+
+	// Disable and Enable withdrawals.
+	specData.ElectraDisableWithdrawalsForkTime = 10
+	specData.ElectraEnableWithdrawalsForkTime = 30
+
+	chainSpec, err := chain.NewSpec(specData)
+	if err != nil {
+		return nil, err
+	}
+
+	return chainSpec, nil
+}