eip-7251: process_pending_balance_deposits (#14002)

* eip-7251: process_pending_balance_deposits

* Update beacon-chain/core/electra/balance_deposits_test.go

Co-authored-by: Radosław Kapka <rkapka@wp.pl>

* Remove defensive check. A unit test shows nothing bad happens

* Safe sub to protect from underflow

* Use @kasey's idea for safer subtraction

---------

Co-authored-by: Radosław Kapka <rkapka@wp.pl>

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 = [
+        "balance_deposits.go",
         "churn.go",
         "consolidations.go",
         "transition.go",
@@ -35,6 +36,7 @@ go_library(
 go_test(
     name = "go_default_test",
     srcs = [
+        "balance_deposits_test.go",
         "churn_test.go",
         "consolidations_test.go",
         "upgrade_test.go",

beacon-chain/core/electra/balance_deposits.go

@@ -0,0 +1,77 @@
+package electra
+
+import (
+	"context"
+	"errors"
+
+	"github.com/prysmaticlabs/prysm/v5/beacon-chain/core/helpers"
+	"github.com/prysmaticlabs/prysm/v5/beacon-chain/state"
+	"github.com/prysmaticlabs/prysm/v5/math"
+	"go.opencensus.io/trace"
+)
+
+// ProcessPendingBalanceDeposits implements the spec definition below. This method mutates the state.
+//
+// Spec definition:
+//
+//	def process_pending_balance_deposits(state: BeaconState) -> None:
+//	    available_for_processing = state.deposit_balance_to_consume + get_activation_exit_churn_limit(state)
+//	    processed_amount = 0
+//	    next_deposit_index = 0
+//
+//	    for deposit in state.pending_balance_deposits:
+//	        if processed_amount + deposit.amount > available_for_processing:
+//	            break
+//	        increase_balance(state, deposit.index, deposit.amount)
+//	        processed_amount += deposit.amount
+//	        next_deposit_index += 1
+//
+//	    state.pending_balance_deposits = state.pending_balance_deposits[next_deposit_index:]
+//
+//	    if len(state.pending_balance_deposits) == 0:
+//	        state.deposit_balance_to_consume = Gwei(0)
+//	    else:
+//	        state.deposit_balance_to_consume = available_for_processing - processed_amount
+func ProcessPendingBalanceDeposits(ctx context.Context, st state.BeaconState, activeBalance math.Gwei) error {
+	_, span := trace.StartSpan(ctx, "electra.ProcessPendingBalanceDeposits")
+	defer span.End()
+
+	if st == nil || st.IsNil() {
+		return errors.New("nil state")
+	}
+
+	depBalToConsume, err := st.DepositBalanceToConsume()
+	if err != nil {
+		return err
+	}
+
+	availableForProcessing := depBalToConsume + helpers.ActivationExitChurnLimit(activeBalance)
+	nextDepositIndex := 0
+
+	deposits, err := st.PendingBalanceDeposits()
+	if err != nil {
+		return err
+	}
+
+	for _, deposit := range deposits {
+		if math.Gwei(deposit.Amount) > availableForProcessing {
+			break
+		}
+		if err := helpers.IncreaseBalance(st, deposit.Index, deposit.Amount); err != nil {
+			return err
+		}
+		availableForProcessing -= math.Gwei(deposit.Amount)
+		nextDepositIndex++
+	}
+
+	deposits = deposits[nextDepositIndex:]
+	if err := st.SetPendingBalanceDeposits(deposits); err != nil {
+		return err
+	}
+
+	if len(deposits) == 0 {
+		return st.SetDepositBalanceToConsume(0)
+	} else {
+		return st.SetDepositBalanceToConsume(availableForProcessing)
+	}
+}

beacon-chain/core/electra/balance_deposits_test.go

@@ -0,0 +1,129 @@
+package electra_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/prysmaticlabs/prysm/v5/beacon-chain/core/electra"
+	"github.com/prysmaticlabs/prysm/v5/beacon-chain/core/helpers"
+	"github.com/prysmaticlabs/prysm/v5/beacon-chain/state"
+	"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"
+)
+
+func TestProcessPendingBalanceDeposits(t *testing.T) {
+	tests := []struct {
+		name    string
+		state   state.BeaconState
+		wantErr bool
+		check   func(*testing.T, state.BeaconState)
+	}{
+		{
+			name:    "nil state fails",
+			state:   nil,
+			wantErr: true,
+		},
+		{
+			name: "no deposits resets balance to consume",
+			state: func() state.BeaconState {
+				st := stateWithActiveBalanceETH(t, 1_000)
+				require.NoError(t, st.SetDepositBalanceToConsume(100))
+				return st
+			}(),
+			check: func(t *testing.T, st state.BeaconState) {
+				res, err := st.DepositBalanceToConsume()
+				require.NoError(t, err)
+				require.Equal(t, math.Gwei(0), res)
+			},
+		},
+		{
+			name: "more deposits than balance to consume processes partial deposits",
+			state: func() state.BeaconState {
+				st := stateWithActiveBalanceETH(t, 1_000)
+				require.NoError(t, st.SetDepositBalanceToConsume(100))
+				amountAvailForProcessing := helpers.ActivationExitChurnLimit(1_000 * 1e9)
+				deps := make([]*eth.PendingBalanceDeposit, 20)
+				for i := 0; i < len(deps); i += 1 {
+					deps[i] = &eth.PendingBalanceDeposit{
+						Amount: uint64(amountAvailForProcessing) / 10,
+						Index:  primitives.ValidatorIndex(i),
+					}
+				}
+				require.NoError(t, st.SetPendingBalanceDeposits(deps))
+				return st
+			}(),
+			check: func(t *testing.T, st state.BeaconState) {
+				amountAvailForProcessing := helpers.ActivationExitChurnLimit(1_000 * 1e9)
+				res, err := st.DepositBalanceToConsume()
+				require.NoError(t, err)
+				require.Equal(t, math.Gwei(100), res)
+				// Validators 0..9 should have their balance increased
+				for i := primitives.ValidatorIndex(0); i < 10; i++ {
+					b, err := st.BalanceAtIndex(i)
+					require.NoError(t, err)
+					require.Equal(t, params.BeaconConfig().MinActivationBalance+uint64(amountAvailForProcessing)/10, b)
+				}
+
+				// Half of the balance deposits should have been processed.
+				remaining, err := st.PendingBalanceDeposits()
+				require.NoError(t, err)
+				require.Equal(t, 10, len(remaining))
+			},
+		},
+		{
+			name: "less deposits than balance to consume processes all deposits",
+			state: func() state.BeaconState {
+				st := stateWithActiveBalanceETH(t, 1_000)
+				require.NoError(t, st.SetDepositBalanceToConsume(0))
+				amountAvailForProcessing := helpers.ActivationExitChurnLimit(1_000 * 1e9)
+				deps := make([]*eth.PendingBalanceDeposit, 5)
+				for i := 0; i < len(deps); i += 1 {
+					deps[i] = &eth.PendingBalanceDeposit{
+						Amount: uint64(amountAvailForProcessing) / 5,
+						Index:  primitives.ValidatorIndex(i),
+					}
+				}
+				require.NoError(t, st.SetPendingBalanceDeposits(deps))
+				return st
+			}(),
+			check: func(t *testing.T, st state.BeaconState) {
+				amountAvailForProcessing := helpers.ActivationExitChurnLimit(1_000 * 1e9)
+				res, err := st.DepositBalanceToConsume()
+				require.NoError(t, err)
+				require.Equal(t, math.Gwei(0), res)
+				// Validators 0..4 should have their balance increased
+				for i := primitives.ValidatorIndex(0); i < 4; i++ {
+					b, err := st.BalanceAtIndex(i)
+					require.NoError(t, err)
+					require.Equal(t, params.BeaconConfig().MinActivationBalance+uint64(amountAvailForProcessing)/5, b)
+				}
+
+				// All of the balance deposits should have been processed.
+				remaining, err := st.PendingBalanceDeposits()
+				require.NoError(t, err)
+				require.Equal(t, 0, len(remaining))
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var tab uint64
+			var err error
+			if tt.state != nil {
+				// The caller of this method would normally have the precompute balance values for total
+				// active balance for this epoch. For ease of test setup, we will compute total active
+				// balance from the given state.
+				tab, err = helpers.TotalActiveBalance(tt.state)
+			}
+			require.NoError(t, err)
+			err = electra.ProcessPendingBalanceDeposits(context.TODO(), tt.state, math.Gwei(tab))
+			require.Equal(t, tt.wantErr, err != nil, "wantErr=%v, got err=%s", tt.wantErr, err)
+			if tt.check != nil {
+				tt.check(t, tt.state)
+			}
+		})
+	}
+}

beacon-chain/core/electra/consolidations_test.go

@@ -259,8 +259,8 @@ func TestProcessConsolidations(t *testing.T) {
 			wantErr: "nil state",
 		},
 		{
-			name: "nil consolidation in slice",
-			state: stateWithActiveBalanceETH(t, 19_000_000),
+			name:    "nil consolidation in slice",
+			state:   stateWithActiveBalanceETH(t, 19_000_000),
 			scs:     []*eth.SignedConsolidation{nil, nil},
 			wantErr: "nil consolidation",
 		},

testing/spectest/mainnet/electra/epoch_processing/BUILD.bazel

@@ -8,6 +8,7 @@ go_test(
         "inactivity_updates_test.go",
         "justification_and_finalization_test.go",
         "participation_flag_updates_test.go",
+        "pending_balance_updates_test.go",
         "pending_consolidations_test.go",
         "randao_mixes_reset_test.go",
         "rewards_and_penalties_test.go",

testing/spectest/mainnet/electra/epoch_processing/pending_balance_updates_test.go

@@ -0,0 +1,11 @@
+package epoch_processing
+
+import (
+	"testing"
+
+	"github.com/prysmaticlabs/prysm/v5/testing/spectest/shared/electra/epoch_processing"
+)
+
+func TestMainnet_Electra_EpochProcessing_PendingBalanceDeposits(t *testing.T) {
+	epoch_processing.RunPendingBalanceDepositsTests(t, "mainnet")
+}

testing/spectest/minimal/electra/epoch_processing/BUILD.bazel

@@ -8,6 +8,7 @@ go_test(
         "inactivity_updates_test.go",
         "justification_and_finalization_test.go",
         "participation_flag_updates_test.go",
+        "pending_balance_updates_test.go",
         "pending_consolidations_test.go",
         "randao_mixes_reset_test.go",
         "rewards_and_penalties_test.go",

testing/spectest/minimal/electra/epoch_processing/pending_balance_updates_test.go

@@ -0,0 +1,11 @@
+package epoch_processing
+
+import (
+	"testing"
+
+	"github.com/prysmaticlabs/prysm/v5/testing/spectest/shared/electra/epoch_processing"
+)
+
+func TestMinimal_Electra_EpochProcessing_PendingBalanceDeposits(t *testing.T) {
+	epoch_processing.RunPendingBalanceDepositsTests(t, "minimal")
+}

testing/spectest/shared/electra/epoch_processing/BUILD.bazel

@@ -10,6 +10,7 @@ go_library(
         "inactivity_updates.go",
         "justification_and_finalization.go",
         "participation_flag_updates.go",
+        "pending_balance_updates.go",
         "pending_consolidations.go",
         "randao_mixes_reset.go",
         "rewards_and_penalties.go",
@@ -25,6 +26,7 @@ go_library(
         "//beacon-chain/state:go_default_library",
         "//beacon-chain/state/state-native:go_default_library",
         "//config/params:go_default_library",
+        "//math:go_default_library",
         "//proto/prysm/v1alpha1:go_default_library",
         "//testing/require:go_default_library",
         "//testing/spectest/utils:go_default_library",

testing/spectest/shared/electra/epoch_processing/pending_balance_updates.go

@@ -0,0 +1,35 @@
+package epoch_processing
+
+import (
+	"context"
+	"path"
+	"testing"
+
+	"github.com/prysmaticlabs/prysm/v5/beacon-chain/core/electra"
+	"github.com/prysmaticlabs/prysm/v5/beacon-chain/core/helpers"
+	"github.com/prysmaticlabs/prysm/v5/beacon-chain/state"
+	"github.com/prysmaticlabs/prysm/v5/math"
+	"github.com/prysmaticlabs/prysm/v5/testing/require"
+	"github.com/prysmaticlabs/prysm/v5/testing/spectest/utils"
+)
+
+func RunPendingBalanceDepositsTests(t *testing.T, config string) {
+	require.NoError(t, utils.SetConfig(t, config))
+
+	testFolders, testsFolderPath := utils.TestFolders(t, config, "electra", "epoch_processing/pending_balance_deposits/pyspec_tests")
+	for _, folder := range testFolders {
+		t.Run(folder.Name(), func(t *testing.T) {
+			folderPath := path.Join(testsFolderPath, folder.Name())
+			RunEpochOperationTest(t, folderPath, processPendingBalanceDeposits)
+		})
+	}
+}
+
+func processPendingBalanceDeposits(t *testing.T, st state.BeaconState) (state.BeaconState, error) {
+	// The caller of this method would normally have the precompute balance values for total
+	// active balance for this epoch. For ease of test setup, we will compute total active
+	// balance from the given state.
+	tab, err := helpers.TotalActiveBalance(st)
+	require.NoError(t, err)
+	return st, electra.ProcessPendingBalanceDeposits(context.TODO(), st, math.Gwei(tab))
+}