eip-7251: New compute_consolidation_epoch_and_update_churn

beacon-chain/core/electra/BUILD.bazel

@@ -3,6 +3,7 @@ load("@prysm//tools/go:def.bzl", "go_library", "go_test")
 go_library(
  name = "go_default_library",
  srcs = [
+ "churn.go",
  "transition.go",
  "upgrade.go",
  ],
@@ -28,11 +29,16 @@ go_library(
 
 go_test(
  name = "go_default_test",
- srcs = ["upgrade_test.go"],
+ srcs = [
+ "churn_test.go",
+ "upgrade_test.go",
+ ],
  deps = [
  ":go_default_library",
  "//beacon-chain/core/helpers:go_default_library",
  "//beacon-chain/core/time:go_default_library",
+ "//beacon-chain/state:go_default_library",
+ "//beacon-chain/state/state-native:go_default_library",
  "//config/params:go_default_library",
  "//consensus-types/primitives:go_default_library",
  "//encoding/bytesutil:go_default_library",

beacon-chain/core/electra/churn.go

@@ -0,0 +1,85 @@
+package electra
+
+import (
+ "context"
+
+ "github.com/prysmaticlabs/prysm/v5/beacon-chain/core/helpers"
+ "github.com/prysmaticlabs/prysm/v5/beacon-chain/state"
+ "github.com/prysmaticlabs/prysm/v5/consensus-types/primitives"
+ "github.com/prysmaticlabs/prysm/v5/math"
+ "github.com/prysmaticlabs/prysm/v5/time/slots"
+)
+
+// ComputeConsolidationEpochAndUpdateChurn fulfills the consensus spec definition below. This method
+// calls mutating methods to the beacon state.
+//
+// Spec definition:
+//
+// def compute_consolidation_epoch_and_update_churn(state: BeaconState, consolidation_balance: Gwei) -> Epoch:
+// earliest_consolidation_epoch = max(
+// state.earliest_consolidation_epoch, compute_activation_exit_epoch(get_current_epoch(state)))
+// per_epoch_consolidation_churn = get_consolidation_churn_limit(state)
+// # New epoch for consolidations.
+// if state.earliest_consolidation_epoch < earliest_consolidation_epoch:
+// consolidation_balance_to_consume = per_epoch_consolidation_churn
+// else:
+// consolidation_balance_to_consume = state.consolidation_balance_to_consume
+//
+// # Consolidation doesn't fit in the current earliest epoch.
+// if consolidation_balance > consolidation_balance_to_consume:
+// balance_to_process = consolidation_balance - consolidation_balance_to_consume
+// additional_epochs = (balance_to_process - 1) // per_epoch_consolidation_churn + 1
+// earliest_consolidation_epoch += additional_epochs
+// consolidation_balance_to_consume += additional_epochs * per_epoch_consolidation_churn
+//
+// # Consume the balance and update state variables.
+// state.consolidation_balance_to_consume = consolidation_balance_to_consume - consolidation_balance
+// state.earliest_consolidation_epoch = earliest_consolidation_epoch
+//
+// return state.earliest_consolidation_epoch
+func ComputeConsolidationEpochAndUpdateChurn(ctx context.Context, s state.BeaconState, consolidationBalance math.Gwei) (primitives.Epoch, error) {
+ earliestEpoch, err := s.EarliestConsolidationEpoch()
+ if err != nil {
+ return 0, err
+ }
+ earliestConsolidationEpoch := max(earliestEpoch, helpers.ActivationExitEpoch(slots.ToEpoch(s.Slot())))
+ activeBal, err := helpers.TotalActiveBalance(s)
+ if err != nil {
+ return 0, err
+ }
+ perEpochConsolidationChurn := helpers.ConsolidationChurnLimit(math.Gwei(activeBal))
+
+ // New epoch for consolidations.
+ var consolidationBalanceToConsume math.Gwei
+ if earliestEpoch < earliestConsolidationEpoch {
+ consolidationBalanceToConsume = perEpochConsolidationChurn
+ } else {
+ consolidationBalanceToConsume, err = s.ConsolidationBalanceToConsume()
+ if err != nil {
+ return 0, err
+ }
+ }
+
+ // Consolidation doesn't fit in the current earliest epoch.
+ if consolidationBalance > consolidationBalanceToConsume {
+ balanceToProcess := consolidationBalance - consolidationBalanceToConsume
+ // additional_epochs = (balance_to_process - 1) // per_epoch_consolidation_churn + 1
+ additionalEpochs, err := math.Div64(uint64(balanceToProcess-1), uint64(perEpochConsolidationChurn))
+ if err != nil {
+ return 0, err
+ }
+ additionalEpochs++
+ earliestConsolidationEpoch += primitives.Epoch(additionalEpochs)
+ consolidationBalanceToConsume += math.Gwei(additionalEpochs) * perEpochConsolidationChurn
+ }
+
+ // Consume the balance and update state variables.
+ if err := s.SetConsolidationBalanceToConsume(consolidationBalanceToConsume - consolidationBalance); err != nil {
+ return 0, err
+ }
+ if err := s.SetEarliestConsolidationEpoch(earliestConsolidationEpoch); err != nil {
+ return 0, err
+ }
+
+ return earliestConsolidationEpoch, nil
+}

beacon-chain/core/electra/churn_test.go

@@ -0,0 +1,142 @@
+package electra_test
+
+import (
+ "context"
+ "testing"
+
+ "github.com/prysmaticlabs/prysm/v5/beacon-chain/core/electra"
+ "github.com/prysmaticlabs/prysm/v5/beacon-chain/state"
+ state_native "github.com/prysmaticlabs/prysm/v5/beacon-chain/state/state-native"
+ "github.com/prysmaticlabs/prysm/v5/config/params"
+ "github.com/prysmaticlabs/prysm/v5/consensus-types/primitives"
+ "github.com/prysmaticlabs/prysm/v5/math"
+ eth "github.com/prysmaticlabs/prysm/v5/proto/prysm/v1alpha1"
+ "github.com/prysmaticlabs/prysm/v5/testing/require"
+ "github.com/prysmaticlabs/prysm/v5/time/slots"
+)
+
+func createValidatorsWithTotalActiveBalance(totalBal math.Gwei) []*eth.Validator {
+ num := totalBal / math.Gwei(params.BeaconConfig().MinActivationBalance)
+ vals := make([]*eth.Validator, num)
+ for i := range vals {
+ vals[i] = &eth.Validator{
+ ActivationEpoch: primitives.Epoch(0),
+ ExitEpoch: params.BeaconConfig().FarFutureEpoch,
+ EffectiveBalance: params.BeaconConfig().MinActivationBalance,
+ }
+ }
+ if totalBal%math.Gwei(params.BeaconConfig().MinActivationBalance) != 0 {
+ vals = append(vals, &eth.Validator{
+ ActivationEpoch: primitives.Epoch(0),
+ ExitEpoch: params.BeaconConfig().FarFutureEpoch,
+ EffectiveBalance: uint64(totalBal) % params.BeaconConfig().MinActivationBalance,
+ })
+ }
+ return vals
+}
+
+func TestComputeConsolidationEpochAndUpdateChurn(t *testing.T) {
+ // Test setup: create a state with 32M ETH total active balance.
+ // In this state, the churn is expected to be 232 ETH per epoch.
+ tests := []struct {
+ name string
+ state state.BeaconState
+ consolidationBalance math.Gwei
+ expectedEpoch primitives.Epoch
+ expectedConsolidationBalanceToConsume math.Gwei
+ }{
+ {
+ name: "compute consolidation with no consolidation balance",
+ state: func(t *testing.T) state.BeaconState {
+ s, err := state_native.InitializeFromProtoUnsafeElectra(&eth.BeaconStateElectra{
+ Slot: slots.UnsafeEpochStart(10),
+ EarliestConsolidationEpoch: 9,
+ Validators: createValidatorsWithTotalActiveBalance(32000000000000000), // 32M ETH
+ })
+ require.NoError(t, err)
+ return s
+ }(t),
+ consolidationBalance: 0, // 0 ETH
+ expectedEpoch: 15, // current epoch + 1 + MaxSeedLookahead
+ expectedConsolidationBalanceToConsume: 232000000000, // 232 ETH
+ },
+ {
+ name: "new epoch for consolidations",
+ state: func(t *testing.T) state.BeaconState {
+ s, err := state_native.InitializeFromProtoUnsafeElectra(&eth.BeaconStateElectra{
+ Slot: slots.UnsafeEpochStart(10),
+ EarliestConsolidationEpoch: 9,
+ Validators: createValidatorsWithTotalActiveBalance(32000000000000000), // 32M ETH
+ })
+ require.NoError(t, err)
+ return s
+ }(t),
+ consolidationBalance: 32000000000, // 32 ETH
+ expectedEpoch: 15, // current epoch + 1 + MaxSeedLookahead
+ expectedConsolidationBalanceToConsume: 200000000000, // 200 ETH
+ },
+ {
+ name: "flows into another epoch",
+ state: func(t *testing.T) state.BeaconState {
+ s, err := state_native.InitializeFromProtoUnsafeElectra(&eth.BeaconStateElectra{
+ Slot: slots.UnsafeEpochStart(10),
+ EarliestConsolidationEpoch: 9,
+ Validators: createValidatorsWithTotalActiveBalance(32000000000000000), // 32M ETH
+ })
+ require.NoError(t, err)
+ return s
+ }(t),
+ consolidationBalance: 235000000000, // 235 ETH
+ expectedEpoch: 16, // Flows into another epoch.
+ expectedConsolidationBalanceToConsume: 229000000000, // 229 ETH
+ },
+ {
+ name: "not a new epoch, fits in remaining balance of current epoch",
+ state: func(t *testing.T) state.BeaconState {
+ s, err := state_native.InitializeFromProtoUnsafeElectra(&eth.BeaconStateElectra{
+ Slot: slots.UnsafeEpochStart(10),
+ EarliestConsolidationEpoch: 15,
+ ConsolidationBalanceToConsume: 200000000000, // 200 ETH
+ Validators: createValidatorsWithTotalActiveBalance(32000000000000000), // 32M ETH
+ })
+ require.NoError(t, err)
+ return s
+ }(t),
+ consolidationBalance: 32000000000, // 32 ETH
+ expectedEpoch: 15, // Fits into current earliest consolidation epoch.
+ expectedConsolidationBalanceToConsume: 168000000000, // 126 ETH
+ },
+ {
+ name: "not a new epoch, fits in remaining balance of current epoch",
+ state: func(t *testing.T) state.BeaconState {
+ s, err := state_native.InitializeFromProtoUnsafeElectra(&eth.BeaconStateElectra{
+ Slot: slots.UnsafeEpochStart(10),
+ EarliestConsolidationEpoch: 15,
+ ConsolidationBalanceToConsume: 200000000000, // 200 ETH
+ Validators: createValidatorsWithTotalActiveBalance(32000000000000000), // 32M ETH
+ })
+ require.NoError(t, err)
+ return s
+ }(t),
+ consolidationBalance: 232000000000, // 232 ETH
+ expectedEpoch: 16, // Flows into another epoch.
+ expectedConsolidationBalanceToConsume: 200000000000, // 200 ETH
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ gotEpoch, err := electra.ComputeConsolidationEpochAndUpdateChurn(context.TODO(), tt.state, tt.consolidationBalance)
+ require.NoError(t, err)
+ require.Equal(t, tt.expectedEpoch, gotEpoch)
+ // Check consolidation balance to consume is set on the state.
+ cbtc, err := tt.state.ConsolidationBalanceToConsume()
+ require.NoError(t, err)
+ require.Equal(t, tt.expectedConsolidationBalanceToConsume, cbtc)
+ // Check earliest consolidation epoch was set on the state.
+ gotEpoch, err = tt.state.EarliestConsolidationEpoch()
+ require.NoError(t, err)
+ require.Equal(t, tt.expectedEpoch, gotEpoch)
+ })
+ }
+}