feat(rpcv10): new INCLUDE_LAST_UPDATE_BLOCK flag for the starknet_getStorageAt method method (#3470)

* feat: add StorageAt to the v10 handler (direct copy from v9 for now)

* test: copy TestStorageAt and some test utilities from rpcv9

* chore: update v10 handler to use v10.StorageAt method

* feat: AI template for the new feature + tests

* feat: implement JSON marshal/unmarshal logic to the StorageAtResult type + tests

* docs: add comments for historical bucket constants in buckets.go to clarify purpose and usage

* feat: add HistoryBlockNumber method to Reader interface and implement it in Blockchain

* test: add unit tests for HistoryLastUpdateBlock function in schema_test.go

* refactor: remove useless resolveBlockNumber func  and add last update block retrieval logic with HistoryBlockNumber

* test: update StorageAt tests with new test cases

* test: fix TestStorageAt test case

* ci: fix linters

* refactor: update StorageAt method to return pointers for result

* chore: nitpicks from PR comments

* test: remove dedicated JSON marshal/unmarshal tests, create a new validation logic

* ci: fix linter conflict

* docs: update Iterator interface comments to clarify return values for First, Prev, and Seek methods (based on pebble original docs)

* chore: simplify iterator checks in HistoryLastUpdateBlock function

* chore: add comment in the linter file explaining the new config

* test: replace custom block ID helper functions with direct calls to rpc package methods

* refactor: rename StorageAtResult to StorageAtResponse and update related tests

* chore: update error messages for unknown storage response flags in JSON unmarshalling

* test: add test case for StorageAt with pre-confirmed block ID handling

* ci: fix linter in tests

Author: thiagodeev

.golangci.yaml

@@ -98,7 +98,8 @@ linters:
         - "24"
         - "32"
     nolintlint:
-      allow-unused: false
+      # permissive here and strict in .golangci_diff.yaml to avoid conflicts
+      allow-unused: true
       require-explanation: false # todo(rdr): this should be switched to true for non test files
       require-specific: true
     prealloc:

blockchain/blockchain.go

@@ -35,6 +35,7 @@ type Reader interface {
 	BlockNumberAndIndexByTxHash(
 		hash *felt.TransactionHash,
 	) (blockNumber uint64, index uint64, err error)
+	HistoryBlockNumber(historyKeyPrefix []byte, upToBlock uint64) (uint64, bool, error)
 
 	TransactionByHash(hash *felt.Felt) (transaction core.Transaction, err error)
 	TransactionByBlockNumberAndIndex(
@@ -636,6 +637,15 @@ func (b *Blockchain) StateAtBlockHash(
 	), noopStateCloser, nil
 }
 
+// HistoryBlockNumber finds the most recent block number (up to upToBlock) recorded
+// in a history bucket for the given key prefix.
+func (b *Blockchain) HistoryBlockNumber(
+	historyKeyPrefix []byte, upToBlock uint64,
+) (uint64, bool, error) {
+	b.listener.OnRead("HistoryBlockNumber")
+	return db.HistoryLastUpdateBlock(b.database, historyKeyPrefix, upToBlock)
+}
+
 // EventFilter returns an EventFilter object that is tied to a snapshot of the blockchain
 func (b *Blockchain) EventFilter(
 	addresses []felt.Address,

db/buckets.go

@@ -23,10 +23,15 @@ const (
 	ReceiptsByBlockNumberAndIndex           // maps block number and index to transaction receipt
 	StateUpdatesByBlockNumber
 	ClassesTrie
+	// ContractStorageHistory + Contract address + storage location + block number -> old value.
+	// For these three history buckets, the block number is when the current value was set, and
+	// the old value is the value before that.
 	ContractStorageHistory
+	// ContractNonceHistory + Contract address + block number -> old nonce.
 	ContractNonceHistory
+	// ContractClassHashHistory + Contract address + block number -> old class hash.
 	ContractClassHashHistory
-	ContractDeploymentHeight
+	ContractDeploymentHeight // maps contract addresses to their deployment block number
 	L1Height
 	DeprecatedSchemaVersion
 	Unused // Previously used for storing Pending Block

db/iterator.go

@@ -11,10 +11,12 @@ type Iterator interface {
 	// Valid returns true if the iterator is positioned at a valid key/value pair.
 	Valid() bool
 
-	// First moves the iterator to the first key/value pair.
+	// First moves the iterator to the first key/value pair. Returns true
+	// if the iterator is pointing at a valid entry and false otherwise.
 	First() bool
 
-	// Prev moves the iterator to the previous key/value pair
+	// Prev moves the iterator to the previous key/value pair. Returns true
+	// if the iterator is pointing at a valid entry and false otherwise.
 	Prev() bool
 
 	// Next moves the iterator to the next key/value pair. It returns whether the
@@ -38,6 +40,7 @@ type Iterator interface {
 	UncopiedValue() ([]byte, error)
 
 	// Seek would seek to the provided key if present. If absent, it would seek to the next
-	// key in lexicographical order
+	// key in lexicographical order. Returns true if the iterator is pointing at a valid entry
+	// and false otherwise.
 	Seek(key []byte) bool
 }

db/schema.go

@@ -161,3 +161,40 @@ func uint64ToBytes(num uint64) [8]byte {
 func StateHashToTrieRootsKey(stateCommitment *felt.StateRootHash) []byte {
 	return StateHashToTrieRoots.Key(stateCommitment.Marshal())
 }
+
+// HistoryLastUpdateBlock finds the most recent block number (up to upToBlock) recorded in
+// a history bucket for the given key prefix. All history buckets ([ContractStorageHistory],
+// [ContractNonceHistory], and [ContractClassHashHistory]) share the same key layout:
+// prefix + uint64 block number in big-endian.
+//
+// Returns (blockNumber, true, nil) if found, or (0, false, nil) if no history entry
+// exists for the prefix.
+func HistoryLastUpdateBlock(
+	reader KeyValueReader,
+	historyKeyPrefix []byte,
+	upToBlock uint64,
+) (uint64, bool, error) {
+	it, err := reader.NewIterator(historyKeyPrefix, true)
+	if err != nil {
+		return 0, false, err
+	}
+	defer it.Close()
+
+	seekKey := binary.BigEndian.AppendUint64(historyKeyPrefix, upToBlock)
+
+	if it.Seek(seekKey) {
+		seekedKey := it.Key()
+		seekedBlock := binary.BigEndian.Uint64(seekedKey[len(historyKeyPrefix):])
+		if seekedBlock == upToBlock {
+			return upToBlock, true, nil
+		}
+	}
+
+	if !it.Prev() {
+		return 0, false, nil
+	}
+
+	foundKey := it.Key()
+	blockNum := binary.BigEndian.Uint64(foundKey[len(historyKeyPrefix):])
+	return blockNum, true, nil
+}

db/schema_test.go

@@ -0,0 +1,111 @@
+package db_test
+
+import (
+	"testing"
+
+	"github.com/NethermindEth/juno/core/felt"
+	"github.com/NethermindEth/juno/db"
+	"github.com/NethermindEth/juno/db/memory"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestHistoryLastUpdateBlock(t *testing.T) {
+	addr := felt.NewFromUint64[felt.Felt](1)
+	loc := felt.NewFromUint64[felt.Felt](2)
+	prefix := db.ContractStorageHistoryKey(addr, loc)
+
+	putAt := func(t *testing.T, database db.KeyValueStore, blockNum uint64) {
+		t.Helper()
+		key := db.ContractStorageHistoryAtBlockKey(addr, loc, blockNum)
+		require.NoError(t, database.Put(key, []byte("value")))
+	}
+
+	t.Run("empty db returns not found", func(t *testing.T) {
+		database := memory.New()
+		defer database.Close()
+
+		blockNum, found, err := db.HistoryLastUpdateBlock(database, prefix, 10)
+		require.NoError(t, err)
+		assert.False(t, found)
+		assert.Equal(t, uint64(0), blockNum)
+	})
+
+	t.Run("exact match returns upToBlock", func(t *testing.T) {
+		database := memory.New()
+		defer database.Close()
+
+		putAt(t, database, 5)
+
+		blockNum, found, err := db.HistoryLastUpdateBlock(database, prefix, 5)
+		require.NoError(t, err)
+		assert.True(t, found)
+		assert.Equal(t, uint64(5), blockNum)
+	})
+
+	t.Run("returns latest block before upToBlock", func(t *testing.T) {
+		database := memory.New()
+		defer database.Close()
+
+		putAt(t, database, 3)
+		putAt(t, database, 7)
+		putAt(t, database, 10)
+
+		blockNum, found, err := db.HistoryLastUpdateBlock(database, prefix, 8)
+		require.NoError(t, err)
+		assert.True(t, found)
+		assert.Equal(t, uint64(7), blockNum)
+	})
+
+	t.Run("all entries are after upToBlock returns not found", func(t *testing.T) {
+		database := memory.New()
+		defer database.Close()
+
+		putAt(t, database, 5)
+		putAt(t, database, 10)
+
+		blockNum, found, err := db.HistoryLastUpdateBlock(database, prefix, 3)
+		require.NoError(t, err)
+		assert.False(t, found)
+		assert.Equal(t, uint64(0), blockNum)
+	})
+
+	t.Run("multiple entries with exact match at upToBlock", func(t *testing.T) {
+		database := memory.New()
+		defer database.Close()
+
+		putAt(t, database, 1)
+		putAt(t, database, 5)
+		putAt(t, database, 9)
+
+		blockNum, found, err := db.HistoryLastUpdateBlock(database, prefix, 9)
+		require.NoError(t, err)
+		assert.True(t, found)
+		assert.Equal(t, uint64(9), blockNum)
+	})
+
+	t.Run("different contract prefix does not affect result", func(t *testing.T) {
+		database := memory.New()
+		defer database.Close()
+
+		otherAddr := new(felt.Felt).SetUint64(99)
+		otherPrefix := db.ContractStorageHistoryKey(otherAddr, loc)
+
+		putAt(t, database, 5)
+
+		// Write entries under a different prefix
+		otherKey := db.ContractStorageHistoryAtBlockKey(otherAddr, loc, 3)
+		require.NoError(t, database.Put(otherKey, []byte("other")))
+
+		blockNum, found, err := db.HistoryLastUpdateBlock(database, prefix, 10)
+		require.NoError(t, err)
+		assert.True(t, found)
+		assert.Equal(t, uint64(5), blockNum)
+
+		// Query the other prefix
+		blockNum, found, err = db.HistoryLastUpdateBlock(database, otherPrefix, 10)
+		require.NoError(t, err)
+		assert.True(t, found)
+		assert.Equal(t, uint64(3), blockNum)
+	})
+}

mocks/mock_blockchain.go

@@ -218,9 +218,12 @@ func (h *Handler) MethodsV0_10() ([]jsonrpc.Method, string) {
 		{
 			Name: "starknet_getStorageAt",
 			Params: []jsonrpc.Parameter{
-				{Name: "contract_address"}, {Name: "key"}, {Name: "block_id"},
+				{Name: "contract_address"},
+				{Name: "key"},
+				{Name: "block_id"},
+				{Name: "response_flags", Optional: true},
 			},
-			Handler: h.rpcv9Handler.StorageAt,
+			Handler: h.rpcv10Handler.StorageAt,
 		},
 		{
 			Name:    "starknet_getClassHashAt",