core: track the state access footprint (#34776)

This is a pre-requisite PR for landing the BAL construction

core/state/state_object.go

@@ -180,6 +180,9 @@ func (s *stateObject) getState(key common.Hash) (common.Hash, common.Hash) {
 // GetCommittedState retrieves the value associated with the specific key
 // without any mutations caused in the current execution.
 func (s *stateObject) GetCommittedState(key common.Hash) common.Hash {
+	// Record slot access regardless of whether the storage slot exists.
+	s.db.stateReadList.AddState(s.address, key)
+
 	// If we have a pending write or clean cached, return that
 	if value, pending := s.pendingStorage[key]; pending {
 		return value
@@ -194,19 +197,6 @@ func (s *stateObject) GetCommittedState(key common.Hash) common.Hash {
 	//      have been handles via pendingStorage above.
 	//   2) we don't have new values, and can deliver empty response back
 	if _, destructed := s.db.stateObjectsDestruct[s.address]; destructed {
-		// Invoke the reader regardless and discard the returned value.
-		// The returned value may not be empty, as it could belong to a
-		// self-destructed contract.
-		//
-		// The read operation is still essential for correctly building
-		// the block-level access list.
-		//
-		// TODO(rjl493456442) the reader interface can be extended with
-		// Touch, recording the read access without the actual disk load.
-		_, err := s.db.reader.Storage(s.address, key)
-		if err != nil {
-			s.db.setError(err)
-		}
 		s.originStorage[key] = common.Hash{} // track the empty slot as origin value
 		return common.Hash{}
 	}

core/state/statedb.go

@@ -31,6 +31,7 @@ import (
 	"github.com/ethereum/go-ethereum/core/stateless"
 	"github.com/ethereum/go-ethereum/core/tracing"
 	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/core/types/bal"
 	"github.com/ethereum/go-ethereum/crypto"
 	"github.com/ethereum/go-ethereum/log"
 	"github.com/ethereum/go-ethereum/params"
@@ -126,6 +127,9 @@ type StateDB struct {
 	accessList   *accessList
 	accessEvents *AccessEvents
 
+	// Per-transaction state access footprint for EIP-7928
+	stateReadList *bal.StateAccessList
+
 	// Transient storage
 	transientStorage transientStorage
 
@@ -317,6 +321,11 @@ func (s *StateDB) Empty(addr common.Address) bool {
 	return so == nil || so.empty()
 }
 
+// Touch accesses the specific account without returning anything.
+func (s *StateDB) Touch(addr common.Address) {
+	s.getStateObject(addr)
+}
+
 // GetBalance retrieves the balance from the given address or 0 if object not found
 func (s *StateDB) GetBalance(addr common.Address) *uint256.Int {
 	stateObject := s.getStateObject(addr)
@@ -579,6 +588,9 @@ func (s *StateDB) deleteStateObject(addr common.Address) {
 // getStateObject retrieves a state object given by the address, returning nil if
 // the object is not found or was deleted in this execution context.
 func (s *StateDB) getStateObject(addr common.Address) *stateObject {
+	// Record state access regardless of whether the account exists.
+	s.stateReadList.AddAccount(addr)
+
 	// Prefer live objects if any is available
 	if obj := s.stateObjects[addr]; obj != nil {
 		return obj
@@ -784,7 +796,7 @@ func (s *StateDB) LogsForBurnAccounts() []*types.Log {
 // Finalise finalises the state by removing the destructed objects and clears
 // the journal as well as the refunds. Finalise, however, will not push any updates
 // into the tries just yet. Only IntermediateRoot or Commit will do that.
-func (s *StateDB) Finalise(deleteEmptyObjects bool) {
+func (s *StateDB) Finalise(deleteEmptyObjects bool) *bal.StateAccessList {
 	addressesToPrefetch := make([]common.Address, 0, len(s.journal.dirties))
 	for addr := range s.journal.dirties {
 		obj, exist := s.stateObjects[addr]
@@ -800,6 +812,7 @@ func (s *StateDB) Finalise(deleteEmptyObjects bool) {
 		if obj.selfDestructed || (deleteEmptyObjects && obj.empty()) {
 			delete(s.stateObjects, obj.address)
 			s.markDelete(addr)
+
 			// We need to maintain account deletions explicitly (will remain
 			// set indefinitely). Note only the first occurred self-destruct
 			// event is tracked.
@@ -822,6 +835,8 @@ func (s *StateDB) Finalise(deleteEmptyObjects bool) {
 	}
 	// Invalidate journal because reverting across transactions is not allowed.
 	s.clearJournalAndRefund()
+
+	return s.stateReadList
 }
 
 // IntermediateRoot computes the current root hash of the state trie.
@@ -1415,6 +1430,10 @@ func (s *StateDB) Prepare(rules params.Rules, sender, coinbase common.Address, d
 	}
 	// Reset transient storage at the beginning of transaction execution
 	s.transientStorage = newTransientStorage()
+
+	if rules.IsAmsterdam {
+		s.stateReadList = bal.NewStateAccessList()
+	}
 }
 
 // AddAddressToAccessList adds the given address to the access list

core/state/statedb_hooked.go

@@ -25,6 +25,7 @@ import (
 	"github.com/ethereum/go-ethereum/core/stateless"
 	"github.com/ethereum/go-ethereum/core/tracing"
 	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/core/types/bal"
 	"github.com/ethereum/go-ethereum/crypto"
 	"github.com/ethereum/go-ethereum/params"
 	"github.com/holiman/uint256"
@@ -114,6 +115,10 @@ func (s *hookedStateDB) Exist(addr common.Address) bool {
 	return s.inner.Exist(addr)
 }
 
+func (s *hookedStateDB) Touch(addr common.Address) {
+	s.inner.Touch(addr)
+}
+
 func (s *hookedStateDB) Empty(addr common.Address) bool {
 	return s.inner.Empty(addr)
 }
@@ -229,11 +234,10 @@ func (s *hookedStateDB) LogsForBurnAccounts() []*types.Log {
 	return s.inner.LogsForBurnAccounts()
 }
 
-func (s *hookedStateDB) Finalise(deleteEmptyObjects bool) {
+func (s *hookedStateDB) Finalise(deleteEmptyObjects bool) *bal.StateAccessList {
 	if s.hooks.OnBalanceChange == nil && s.hooks.OnNonceChangeV2 == nil && s.hooks.OnNonceChange == nil && s.hooks.OnCodeChangeV2 == nil && s.hooks.OnCodeChange == nil {
 		// Short circuit if no relevant hooks are set.
-		s.inner.Finalise(deleteEmptyObjects)
-		return
+		return s.inner.Finalise(deleteEmptyObjects)
 	}
 
 	// Collect all self-destructed addresses first, then sort them to ensure
@@ -282,6 +286,5 @@ func (s *hookedStateDB) Finalise(deleteEmptyObjects bool) {
 			s.hooks.OnCodeChange(addr, prevCodeHash, s.inner.GetCode(addr), types.EmptyCodeHash, nil)
 		}
 	}
-
-	s.inner.Finalise(deleteEmptyObjects)
+	return s.inner.Finalise(deleteEmptyObjects)
 }

core/types/bal/access_list.go

@@ -0,0 +1,80 @@
+// Copyright 2026 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// The go-ethereum library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>
+
+package bal
+
+import (
+	"maps"
+
+	"github.com/ethereum/go-ethereum/common"
+)
+
+// StorageAccessList represents a set of storage slots accessed within an account.
+type StorageAccessList map[common.Hash]struct{}
+
+// StateAccessList records the set of accounts and storage slots that have been
+// accessed. An entry with an empty StorageAccessList denotes an account access
+// without any storage slot access.
+type StateAccessList struct {
+	list map[common.Address]StorageAccessList
+}
+
+// NewStateAccessList returns an empty StateAccessList ready for use.
+func NewStateAccessList() *StateAccessList {
+	return &StateAccessList{
+		list: make(map[common.Address]StorageAccessList),
+	}
+}
+
+// AddAccount records an access to the given account. It is a no-op if the
+// account is already present.
+func (s *StateAccessList) AddAccount(addr common.Address) {
+	if s == nil {
+		return
+	}
+	if _, exists := s.list[addr]; !exists {
+		s.list[addr] = make(StorageAccessList)
+	}
+}
+
+// AddState records an access to the given storage slot. The owning account is
+// implicitly recorded as well.
+func (s *StateAccessList) AddState(addr common.Address, slot common.Hash) {
+	if s == nil {
+		return
+	}
+	slots, exists := s.list[addr]
+	if !exists {
+		slots = make(StorageAccessList)
+		s.list[addr] = slots
+	}
+	slots[slot] = struct{}{}
+}
+
+// Merge merges the entries from other into the receiver.
+func (s *StateAccessList) Merge(other *StateAccessList) {
+	if s == nil || other == nil {
+		return
+	}
+	for addr, otherSlots := range other.list {
+		slots, exists := s.list[addr]
+		if !exists {
+			s.list[addr] = otherSlots
+			continue
+		}
+		maps.Copy(slots, otherSlots)
+	}
+}

core/vm/contracts.go

@@ -262,7 +262,7 @@ func ActivePrecompiles(rules params.Rules) []common.Address {
 // - the returned bytes,
 // - the remaining gas budget,
 // - any error that occurred
-func RunPrecompiledContract(stateDB StateDB, p PrecompiledContract, address common.Address, input []byte, gas GasBudget, logger *tracing.Hooks) (ret []byte, remaining GasBudget, err error) {
+func RunPrecompiledContract(stateDB StateDB, p PrecompiledContract, address common.Address, input []byte, gas GasBudget, logger *tracing.Hooks, rules params.Rules) (ret []byte, remaining GasBudget, err error) {
 	gasCost := p.RequiredGas(input)
 	prior, ok := gas.Charge(GasCosts{RegularGas: gasCost})
 	if !ok {
@@ -274,8 +274,8 @@ func RunPrecompiledContract(stateDB StateDB, p PrecompiledContract, address comm
 	}
 	// Touch the precompile for block-level accessList recording once Amsterdam
 	// fork is activated.
-	if stateDB != nil {
-		stateDB.Exist(address)
+	if rules.IsAmsterdam {
+		stateDB.Touch(address)
 	}
 	output, err := p.Run(input)
 	return output, gas, err

core/vm/contracts_fuzz_test.go

@@ -20,6 +20,7 @@ import (
 	"testing"
 
 	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/params"
 )
 
 func FuzzPrecompiledContracts(f *testing.F) {
@@ -36,7 +37,7 @@ func FuzzPrecompiledContracts(f *testing.F) {
 			return
 		}
 		inWant := string(input)
-		RunPrecompiledContract(nil, p, a, input, NewGasBudget(gas), nil)
+		RunPrecompiledContract(nil, p, a, input, NewGasBudget(gas), nil, params.Rules{})
 		if inHave := string(input); inWant != inHave {
 			t.Errorf("Precompiled %v modified input data", a)
 		}

core/vm/contracts_test.go

@@ -25,6 +25,7 @@ import (
 	"time"
 
 	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/params"
 )
 
 // precompiledTest defines the input/output pairs for precompiled contract tests.
@@ -99,7 +100,7 @@ func testPrecompiled(addr string, test precompiledTest, t *testing.T) {
 	in := common.Hex2Bytes(test.Input)
 	gas := p.RequiredGas(in)
 	t.Run(fmt.Sprintf("%s-Gas=%d", test.Name, gas), func(t *testing.T) {
-		if res, _, err := RunPrecompiledContract(nil, p, common.HexToAddress(addr), in, NewGasBudget(gas), nil); err != nil {
+		if res, _, err := RunPrecompiledContract(nil, p, common.HexToAddress(addr), in, NewGasBudget(gas), nil, params.Rules{}); err != nil {
 			t.Error(err)
 		} else if common.Bytes2Hex(res) != test.Expected {
 			t.Errorf("Expected %v, got %v", test.Expected, common.Bytes2Hex(res))
@@ -121,7 +122,7 @@ func testPrecompiledOOG(addr string, test precompiledTest, t *testing.T) {
 	gas := test.Gas - 1
 
 	t.Run(fmt.Sprintf("%s-Gas=%d", test.Name, gas), func(t *testing.T) {
-		_, _, err := RunPrecompiledContract(nil, p, common.HexToAddress(addr), in, NewGasBudget(gas), nil)
+		_, _, err := RunPrecompiledContract(nil, p, common.HexToAddress(addr), in, NewGasBudget(gas), nil, params.Rules{})
 		if err.Error() != "out of gas" {
 			t.Errorf("Expected error [out of gas], got [%v]", err)
 		}
@@ -138,7 +139,7 @@ func testPrecompiledFailure(addr string, test precompiledFailureTest, t *testing
 	in := common.Hex2Bytes(test.Input)
 	gas := p.RequiredGas(in)
 	t.Run(test.Name, func(t *testing.T) {
-		_, _, err := RunPrecompiledContract(nil, p, common.HexToAddress(addr), in, NewGasBudget(gas), nil)
+		_, _, err := RunPrecompiledContract(nil, p, common.HexToAddress(addr), in, NewGasBudget(gas), nil, params.Rules{})
 		if err.Error() != test.ExpectedError {
 			t.Errorf("Expected error [%v], got [%v]", test.ExpectedError, err)
 		}
@@ -169,7 +170,7 @@ func benchmarkPrecompiled(addr string, test precompiledTest, bench *testing.B) {
 		start := time.Now()
 		for bench.Loop() {
 			copy(data, in)
-			res, _, err = RunPrecompiledContract(nil, p, common.HexToAddress(addr), data, NewGasBudget(reqGas), nil)
+			res, _, err = RunPrecompiledContract(nil, p, common.HexToAddress(addr), data, NewGasBudget(reqGas), nil, params.Rules{})
 		}
 		elapsed := uint64(time.Since(start))
 		if elapsed < 1 {

core/vm/evm.go

@@ -287,11 +287,7 @@ func (evm *EVM) Call(caller common.Address, addr common.Address, input []byte, g
 	}
 
 	if isPrecompile {
-		var stateDB StateDB
-		if evm.chainRules.IsAmsterdam {
-			stateDB = evm.StateDB
-		}
-		ret, gas, err = RunPrecompiledContract(stateDB, p, addr, input, gas, evm.Config.Tracer)
+		ret, gas, err = RunPrecompiledContract(evm.StateDB, p, addr, input, gas, evm.Config.Tracer, evm.chainRules)
 	} else {
 		// Initialise a new contract and set the code that is to be used by the EVM.
 		code := evm.resolveCode(addr)
@@ -354,11 +350,7 @@ func (evm *EVM) CallCode(caller common.Address, addr common.Address, input []byt
 
 	// It is allowed to call precompiles, even via delegatecall
 	if p, isPrecompile := evm.precompile(addr); isPrecompile {
-		var stateDB StateDB
-		if evm.chainRules.IsAmsterdam {
-			stateDB = evm.StateDB
-		}
-		ret, gas, err = RunPrecompiledContract(stateDB, p, addr, input, gas, evm.Config.Tracer)
+		ret, gas, err = RunPrecompiledContract(evm.StateDB, p, addr, input, gas, evm.Config.Tracer, evm.chainRules)
 	} else {
 		// Initialise a new contract and set the code that is to be used by the EVM.
 		// The contract is a scoped environment for this execution context only.
@@ -401,11 +393,7 @@ func (evm *EVM) DelegateCall(originCaller common.Address, caller common.Address,
 
 	// It is allowed to call precompiles, even via delegatecall
 	if p, isPrecompile := evm.precompile(addr); isPrecompile {
-		var stateDB StateDB
-		if evm.chainRules.IsAmsterdam {
-			stateDB = evm.StateDB
-		}
-		ret, gas, err = RunPrecompiledContract(stateDB, p, addr, input, gas, evm.Config.Tracer)
+		ret, gas, err = RunPrecompiledContract(evm.StateDB, p, addr, input, gas, evm.Config.Tracer, evm.chainRules)
 	} else {
 		// Initialise a new contract and make initialise the delegate values
 		//
@@ -457,11 +445,7 @@ func (evm *EVM) StaticCall(caller common.Address, addr common.Address, input []b
 	evm.StateDB.AddBalance(addr, new(uint256.Int), tracing.BalanceChangeTouchAccount)
 
 	if p, isPrecompile := evm.precompile(addr); isPrecompile {
-		var stateDB StateDB
-		if evm.chainRules.IsAmsterdam {
-			stateDB = evm.StateDB
-		}
-		ret, gas, err = RunPrecompiledContract(stateDB, p, addr, input, gas, evm.Config.Tracer)
+		ret, gas, err = RunPrecompiledContract(evm.StateDB, p, addr, input, gas, evm.Config.Tracer, evm.chainRules)
 	} else {
 		// Initialise a new contract and set the code that is to be used by the EVM.
 		// The contract is a scoped environment for this execution context only.

core/vm/interface.go

@@ -22,6 +22,7 @@ import (
 	"github.com/ethereum/go-ethereum/core/stateless"
 	"github.com/ethereum/go-ethereum/core/tracing"
 	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/core/types/bal"
 	"github.com/ethereum/go-ethereum/params"
 	"github.com/holiman/uint256"
 )
@@ -63,6 +64,9 @@ type StateDB interface {
 	// Notably this also returns true for self-destructed accounts within the current transaction.
 	Exist(common.Address) bool
 
+	// Touch accesses the state without returning anything.
+	Touch(common.Address)
+
 	// IsNewContract reports whether the contract at the given address was deployed
 	// during the current transaction.
 	IsNewContract(addr common.Address) bool
@@ -94,5 +98,5 @@ type StateDB interface {
 	AccessEvents() *state.AccessEvents
 
 	// Finalise must be invoked at the end of a transaction
-	Finalise(bool)
+	Finalise(bool) *bal.StateAccessList
 }