Merge branch 'develop' into hdiff_start_database

When the state-diff feature is enabled but the database was created
without state-diff support, NewKVStore now returns the store along
with ErrStateDiffIncompatible. The caller (openDB) checks for this
error, logs a warning, disables the feature, and continues using
the returned store.

This prevents migrateToColdHdiff from being called on a database
that lacks the required state-diff infrastructure.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

beacon-chain/db/kv/error.go

@@ -22,6 +22,10 @@ var ErrNotFoundFeeRecipient = errors.Wrap(ErrNotFound, "fee recipient")
 // ErrNotFoundMetadataSeqNum is a not found error specifically for the metadata sequence number getter
 var ErrNotFoundMetadataSeqNum = errors.Wrap(ErrNotFound, "metadata sequence number")
 
+// ErrStateDiffIncompatible is returned when state-diff feature is enabled
+// but the database was created without state-diff support.
+var ErrStateDiffIncompatible = errors.New("state-diff feature enabled but database was created without state-diff support")
+
 var errEmptyBlockSlice = errors.New("[]blocks.ROBlock is empty")
 var errIncorrectBlockParent = errors.New("unexpected missing or forked blocks in a []ROBlock")
 var errFinalizedChildNotFound = errors.New("unable to find finalized root descending from backfill batch")

beacon-chain/db/kv/genesis.go

@@ -7,6 +7,7 @@ import (
 	"github.com/OffchainLabs/prysm/v7/beacon-chain/core/blocks"
 	dbIface "github.com/OffchainLabs/prysm/v7/beacon-chain/db/iface"
 	"github.com/OffchainLabs/prysm/v7/beacon-chain/state"
+	"github.com/OffchainLabs/prysm/v7/config/features"
 	"github.com/OffchainLabs/prysm/v7/encoding/ssz/detect"
 	"github.com/OffchainLabs/prysm/v7/genesis"
 	ethpb "github.com/OffchainLabs/prysm/v7/proto/prysm/v1alpha1"
@@ -42,6 +43,15 @@ func (s *Store) SaveGenesisData(ctx context.Context, genesisState state.BeaconSt
 	if err := s.SaveGenesisBlockRoot(ctx, genesisBlkRoot); err != nil {
 		return errors.Wrap(err, "could not save genesis block root")
 	}
+
+	// Initialize state-diff if enabled and not yet initialized.
+	if features.Get().EnableStateDiff && s.stateDiffCache == nil {
+		if err := s.initializeStateDiff(0, genesisState); err != nil {
+			return errors.Wrap(err, "failed to initialize state diff for genesis")
+		}
+		log.Info("Initialized state-diff with genesis state")
+	}
+
 	return nil
 }
 

beacon-chain/db/kv/kv.go

@@ -204,11 +204,31 @@ func NewKVStore(ctx context.Context, dirPath string, opts ...KVStoreOption) (*St
 	}
 
 	if features.Get().EnableStateDiff {
-		sdCache, err := newStateDiffCache(kv)
+		// Check if offset already exists (existing state-diff database).
+		hasOffset, err := kv.hasStateDiffOffset()
 		if err != nil {
 			return nil, err
 		}
-		kv.stateDiffCache = sdCache
+
+		if hasOffset {
+			// Existing state-diff database - restarts not yet supported.
+			return nil, errors.New("restarting with existing state-diff database not yet supported")
+		}
+
+		// Check if this is a new database (no head block).
+		headBlock, err := kv.HeadBlock(ctx)
+		if err != nil {
+			return nil, errors.Wrap(err, "could not get head block")
+		}
+
+		if headBlock == nil {
+			// New database - will be initialized later during checkpoint/genesis sync.
+			// stateDiffCache stays nil until SaveOrigin or SaveGenesisData initializes it.
+			log.Info("State-diff enabled: will be initialized during checkpoint or genesis sync")
+		} else {
+			// Existing database without state-diff - return store with error for caller to handle.
+			return kv, ErrStateDiffIncompatible
+		}
 	}
 
 	return kv, nil

beacon-chain/db/kv/state_diff_helpers.go

@@ -14,6 +14,7 @@ import (
 	"github.com/OffchainLabs/prysm/v7/math"
 	ethpb "github.com/OffchainLabs/prysm/v7/proto/prysm/v1alpha1"
 	"github.com/OffchainLabs/prysm/v7/runtime/version"
+	pkgerrors "github.com/pkg/errors"
 	"go.etcd.io/bbolt"
 )
 
@@ -119,6 +120,54 @@ func (s *Store) getOffset() uint64 {
 	return s.stateDiffCache.getOffset()
 }
 
+// hasStateDiffOffset checks if the state-diff offset has been set in the database.
+// This is used to detect if an existing database has state-diff enabled.
+func (s *Store) hasStateDiffOffset() (bool, error) {
+	var hasOffset bool
+	err := s.db.View(func(tx *bbolt.Tx) error {
+		bucket := tx.Bucket(stateDiffBucket)
+		if bucket == nil {
+			return nil
+		}
+		hasOffset = bucket.Get(offsetKey) != nil
+		return nil
+	})
+	return hasOffset, err
+}
+
+// initializeStateDiff sets up the state-diff schema for a new database.
+// This should be called during checkpoint sync or genesis sync.
+func (s *Store) initializeStateDiff(slot primitives.Slot, initialState state.ReadOnlyBeaconState) error {
+	// Write offset directly to the database (without using cache which doesn't exist yet).
+	err := s.db.Update(func(tx *bbolt.Tx) error {
+		bucket := tx.Bucket(stateDiffBucket)
+		if bucket == nil {
+			return bbolt.ErrBucketNotFound
+		}
+
+		offsetBytes := make([]byte, 8)
+		binary.LittleEndian.PutUint64(offsetBytes, uint64(slot))
+		return bucket.Put(offsetKey, offsetBytes)
+	})
+	if err != nil {
+		return pkgerrors.Wrap(err, "failed to set offset")
+	}
+
+	// Create the state diff cache (this will read the offset from the database).
+	sdCache, err := newStateDiffCache(s)
+	if err != nil {
+		return pkgerrors.Wrap(err, "failed to create state diff cache")
+	}
+	s.stateDiffCache = sdCache
+
+	// Save the initial state as a full snapshot.
+	if err := s.saveFullSnapshot(initialState); err != nil {
+		return pkgerrors.Wrap(err, "failed to save initial snapshot")
+	}
+
+	return nil
+}
+
 func keyForSnapshot(v int) ([]byte, error) {
 	switch v {
 	case version.Fulu:

beacon-chain/db/kv/wss.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/OffchainLabs/prysm/v7/config/features"
 	"github.com/OffchainLabs/prysm/v7/config/params"
 	"github.com/OffchainLabs/prysm/v7/consensus-types/primitives"
 	"github.com/OffchainLabs/prysm/v7/encoding/ssz/detect"
@@ -111,5 +112,13 @@ func (s *Store) SaveOrigin(ctx context.Context, serState, serBlock []byte) error
 		return errors.Wrap(err, "save finalized checkpoint")
 	}
 
+	// Initialize state-diff if enabled and not yet initialized.
+	if features.Get().EnableStateDiff && s.stateDiffCache == nil {
+		if err := s.initializeStateDiff(state.Slot(), state); err != nil {
+			return errors.Wrap(err, "failed to initialize state diff")
+		}
+		log.WithField("slot", state.Slot()).Info("Initialized state-diff with checkpoint state")
+	}
+
 	return nil
 }

beacon-chain/node/node.go

@@ -540,7 +540,12 @@ func openDB(ctx context.Context, dbPath string, clearer *dbClearer) (*kv.Store,
 	log.WithField("databasePath", dbPath).Info("Checking DB")
 
 	d, err := kv.NewKVStore(ctx, dbPath)
-	if err != nil {
+	if errors.Is(err, kv.ErrStateDiffIncompatible) {
+		log.WithError(err).Warn("Disabling state-diff feature")
+		cfg := features.Get()
+		cfg.EnableStateDiff = false
+		features.Init(cfg)
+	} else if err != nil {
 		return nil, errors.Wrapf(err, "could not create database at %s", dbPath)
 	}
 

cmd/beacon-chain/main.go

@@ -158,6 +158,7 @@ var appFlags = []cli.Flag{
 	dasFlags.BackfillOldestSlot,
 	dasFlags.BlobRetentionEpochFlag,
 	flags.BatchVerifierLimit,
+	flags.StateDiffExponents,
 	flags.DisableEphemeralLogFile,
 }
 

cmd/beacon-chain/usage.go

@@ -74,6 +74,7 @@ var appHelpFlagGroups = []flagGroup{
 			flags.RPCHost,
 			flags.RPCPort,
 			flags.BatchVerifierLimit,
+			flags.StateDiffExponents,
 		},
 	},
 	{

config/features/flags.go

@@ -280,6 +280,7 @@ var BeaconChainFlags = combinedFlags([]cli.Flag{
 	DisableQUIC,
 	EnableDiscoveryReboot,
 	enableExperimentalAttestationPool,
+	EnableStateDiff,
 	forceHeadFlag,
 	blacklistRoots,
 	enableHashtree,

testing/endtoend/BUILD.bazel

@@ -97,6 +97,7 @@ go_test(
         "endtoend_setup_test.go",
         "endtoend_test.go",
         "minimal_e2e_test.go",
+        "minimal_hdiff_e2e_test.go",
         "minimal_slashing_e2e_test.go",
         "slasher_simulator_e2e_test.go",
     ],

testing/endtoend/minimal_hdiff_e2e_test.go

@@ -0,0 +1,16 @@
+package endtoend
+
+import (
+	"testing"
+
+	"github.com/OffchainLabs/prysm/v7/config/params"
+	"github.com/OffchainLabs/prysm/v7/runtime/version"
+	"github.com/OffchainLabs/prysm/v7/testing/endtoend/types"
+)
+
+func TestEndToEnd_MinimalConfig_WithStateDiff(t *testing.T) {
+	r := e2eMinimal(t, types.InitForkCfg(version.Bellatrix, version.Electra, params.E2ETestConfig()),
+		types.WithStateDiff(),
+	)
+	r.run()
+}

testing/endtoend/types/types.go

@@ -76,6 +76,15 @@ func WithSSZOnly() E2EConfigOpt {
 	}
 }
 
+func WithStateDiff() E2EConfigOpt {
+	return func(cfg *E2EConfig) {
+		cfg.BeaconFlags = append(cfg.BeaconFlags,
+			"--enable-state-diff",
+			"--state-diff-exponents=6,5", // Small exponents for quick testing
+		)
+	}
+}
+
 // WithExitEpoch sets a custom epoch for voluntary exit submission.
 // This affects ProposeVoluntaryExit, ValidatorsHaveExited, SubmitWithdrawal, and ValidatorsHaveWithdrawn evaluators.
 func WithExitEpoch(e primitives.Epoch) E2EConfigOpt {