ethclient: add GetBlockAccessList

Author: VanshSahay

ethclient/block_access_list.go

@@ -0,0 +1,81 @@
+// 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 ethclient
+
+import (
+	"context"
+
+	"github.com/ethereum/go-ethereum"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/rpc"
+)
+
+// BlockAccessListEntry describes the state changes of a single account within
+// a block access list, keyed by the transaction that caused them.
+type BlockAccessListEntry struct {
+	Address        common.Address        `json:"address"`
+	BalanceChanges []BalanceChangeEntry  `json:"balanceChanges"`
+	CodeChanges    []CodeChangeEntry     `json:"codeChanges"`
+	NonceChanges   []NonceChangeEntry    `json:"nonceChanges"`
+	StorageChanges []StorageChangesEntry `json:"storageChanges"`
+	StorageReads   []common.Hash         `json:"storageReads"`
+}
+
+// BalanceChangeEntry records the post-state balance of an account at a block
+// access index.
+type BalanceChangeEntry struct {
+	Index hexutil.Uint64 `json:"index"`
+	Value *hexutil.Big   `json:"value"`
+}
+
+// CodeChangeEntry records the code deployed to an account at a block access
+// index.
+type CodeChangeEntry struct {
+	Index hexutil.Uint64 `json:"index"`
+	Code  hexutil.Bytes  `json:"code"`
+}
+
+// NonceChangeEntry records the post-state nonce of an account at a block
+// access index.
+type NonceChangeEntry struct {
+	Index hexutil.Uint64 `json:"index"`
+	Value hexutil.Uint64 `json:"value"`
+}
+
+// StorageChangeEntry records the post-state value of a storage slot at a
+// block access index.
+type StorageChangeEntry struct {
+	Index hexutil.Uint64 `json:"index"`
+	Value common.Hash    `json:"value"`
+}
+
+// StorageChangesEntry pairs a storage key with the writes performed on it.
+type StorageChangesEntry struct {
+	Key     common.Hash          `json:"key"`
+	Changes []StorageChangeEntry `json:"changes"`
+}
+
+// GetBlockAccessList returns the block access list of the given block.
+func (ec *Client) GetBlockAccessList(ctx context.Context, blockNrOrHash rpc.BlockNumberOrHash) ([]BlockAccessListEntry, error) {
+	var r []BlockAccessListEntry
+	err := ec.c.CallContext(ctx, &r, "eth_getBlockAccessList", blockNrOrHash)
+	if err == nil && r == nil {
+		return nil, ethereum.NotFound
+	}
+	return r, err
+}

ethclient/ethclient_test.go

@@ -29,6 +29,7 @@ import (
 	"github.com/ethereum/go-ethereum"
 	"github.com/ethereum/go-ethereum/accounts/abi"
 	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
 	"github.com/ethereum/go-ethereum/consensus/beacon"
 	"github.com/ethereum/go-ethereum/consensus/ethash"
 	"github.com/ethereum/go-ethereum/core"
@@ -1058,3 +1059,76 @@ func genesisAlloc() types.GenesisAlloc {
 	alloc[revertContractAddr] = types.Account{Code: revertCode}
 	return alloc
 }
+
+type blockAccessListTestService struct {
+	calls chan rpc.BlockNumberOrHash
+}
+
+func (s *blockAccessListTestService) GetBlockAccessList(ctx context.Context, block rpc.BlockNumberOrHash) ([]ethclient.BlockAccessListEntry, error) {
+	s.calls <- block
+	return []ethclient.BlockAccessListEntry{
+		{
+			Address:        common.HexToAddress("0x000f3df6d732807ef1319fb7b8bb8522d0beac02"),
+			BalanceChanges: []ethclient.BalanceChangeEntry{},
+			CodeChanges:    []ethclient.CodeChangeEntry{},
+			NonceChanges:   []ethclient.NonceChangeEntry{},
+			StorageChanges: []ethclient.StorageChangesEntry{
+				{
+					Key: common.HexToHash("0x152f"),
+					Changes: []ethclient.StorageChangeEntry{
+						{Index: 0, Value: common.HexToHash("0x01")},
+					},
+				},
+			},
+			StorageReads: []common.Hash{},
+		},
+		{
+			Address: common.HexToAddress("0x8943545177806ed17b9f23f0a21ee5948ecaa776"),
+			BalanceChanges: []ethclient.BalanceChangeEntry{
+				{Index: 1, Value: (*hexutil.Big)(big.NewInt(1e18))},
+			},
+			CodeChanges:    []ethclient.CodeChangeEntry{},
+			NonceChanges:   []ethclient.NonceChangeEntry{{Index: 1, Value: 1}},
+			StorageChanges: []ethclient.StorageChangesEntry{},
+			StorageReads:   []common.Hash{},
+		},
+	}, nil
+}
+
+func TestGetBlockAccessList(t *testing.T) {
+	srv := rpc.NewServer()
+	service := &blockAccessListTestService{calls: make(chan rpc.BlockNumberOrHash, 1)}
+	if err := srv.RegisterName("eth", service); err != nil {
+		t.Fatalf("failed to register service: %v", err)
+	}
+	defer srv.Stop()
+
+	client := rpc.DialInProc(srv)
+	defer client.Close()
+
+	ec := ethclient.NewClient(client)
+	defer ec.Close()
+
+	hash := common.HexToHash("0x01")
+	ref := rpc.BlockNumberOrHashWithHash(hash, true)
+
+	entries, err := ec.GetBlockAccessList(context.Background(), ref)
+	if err != nil {
+		t.Fatalf("GetBlockAccessList returned error: %v", err)
+	}
+	if len(entries) != 2 {
+		t.Fatalf("expected 2 entries, got %d", len(entries))
+	}
+	if entries[0].Address != common.HexToAddress("0x000f3df6d732807ef1319fb7b8bb8522d0beac02") {
+		t.Fatalf("unexpected first entry address: %s", entries[0].Address)
+	}
+	if len(entries[0].StorageChanges) != 1 || entries[0].StorageChanges[0].Changes[0].Index != 0 {
+		t.Fatalf("unexpected storage changes: %+v", entries[0].StorageChanges)
+	}
+	if entries[1].BalanceChanges[0].Value.ToInt().Cmp(big.NewInt(1e18)) != 0 {
+		t.Fatalf("unexpected balance change: %v", entries[1].BalanceChanges[0].Value)
+	}
+	if entries[1].NonceChanges[0].Value != 1 {
+		t.Fatalf("unexpected nonce change: %+v", entries[1].NonceChanges)
+	}
+}