feat(blockdb): add lru cache for block entries

Author: DracoLi

x/blockdb/README.md

@@ -10,6 +10,7 @@ BlockDB is a specialized database optimized for blockchain blocks.
 - **Configurable Durability**: Optional `syncToDisk` mode guarantees immediate recoverability
 - **Automatic Recovery**: Detects and recovers unindexed blocks after unclean shutdowns
 - **Block Compression**: zstd compression for block data
+- **In-Memory Cache**: LRU cache for recently accessed blocks
 
 ## Design
 
@@ -167,7 +168,6 @@ if err != nil {
 
 ## TODO
 
-- Implement a block cache for recently accessed blocks
 - Use a buffered pool to avoid allocations on reads and writes
 - Add performance benchmarks
 - Consider supporting missing data files (currently we error if any data files are missing)

x/blockdb/database.go

@@ -41,6 +41,9 @@ const (
 
 	// BlockEntryVersion is the version of the block entry.
 	BlockEntryVersion uint16 = 1
+
+	// defaultEntryCacheSize is the default number of entries to cache in memory
+	defaultEntryCacheSize = 256
 )
 
 // BlockHeight defines the type for block heights.
@@ -176,6 +179,7 @@ type Database struct {
 	log        logging.Logger
 	closed     bool
 	fileCache  *lru.Cache[int, *os.File]
+	entryCache *lru.Cache[BlockHeight, BlockData]
 	compressor compression.Compressor
 
 	// closeMu prevents the database from being closed while in use and prevents
@@ -223,6 +227,7 @@ func New(config DatabaseConfig, log logging.Logger) (*Database, error) {
 				f.Close()
 			}
 		}),
+		entryCache: lru.NewCache[BlockHeight, BlockData](defaultEntryCacheSize),
 		compressor: compressor,
 	}
 
@@ -372,6 +377,11 @@ func (s *Database) Put(height BlockHeight, block BlockData) error {
 		return err
 	}
 
+	// Store a copy in cache to prevent external modifications from affecting the cached data
+	blockCopy := make([]byte, len(block))
+	copy(blockCopy, block)
+	s.entryCache.Put(height, blockCopy)
+
 	s.log.Debug("Block written successfully",
 		zap.Uint64("height", height),
 		zap.Uint32("blockSize", blockDataLen),
@@ -385,12 +395,6 @@ func (s *Database) Put(height BlockHeight, block BlockData) error {
 // It returns database.ErrNotFound if the block does not exist.
 func (s *Database) readBlockIndex(height BlockHeight) (indexEntry, error) {
 	var entry indexEntry
-	if s.closed {
-		s.log.Error("Failed to read block index: database is closed",
-			zap.Uint64("height", height),
-		)
-		return entry, database.ErrClosed
-	}
 
 	// Skip the index entry read if we know the block is past the max height.
 	maxHeight := s.maxBlockHeight.Load()
@@ -436,6 +440,20 @@ func (s *Database) Get(height BlockHeight) (BlockData, error) {
 	s.closeMu.RLock()
 	defer s.closeMu.RUnlock()
 
+	if s.closed {
+		s.log.Error("Failed to read block: database is closed",
+			zap.Uint64("height", height),
+		)
+		return nil, database.ErrClosed
+	}
+
+	if cachedData, ok := s.entryCache.Get(height); ok {
+		// Return a copy to prevent external modifications from affecting the cache
+		dataCopy := make([]byte, len(cachedData))
+		copy(dataCopy, cachedData)
+		return dataCopy, nil
+	}
+
 	indexEntry, err := s.readBlockIndex(height)
 	if err != nil {
 		return nil, err
@@ -486,6 +504,10 @@ func (s *Database) Get(height BlockHeight) (BlockData, error) {
 		return nil, fmt.Errorf("checksum mismatch: calculated %d, stored %d", calculatedChecksum, bh.Checksum)
 	}
 
+	cacheCopy := make([]byte, len(decompressed))
+	copy(cacheCopy, decompressed)
+	s.entryCache.Put(height, cacheCopy)
+
 	return decompressed, nil
 }
 
@@ -494,6 +516,14 @@ func (s *Database) Has(height BlockHeight) (bool, error) {
 	s.closeMu.RLock()
 	defer s.closeMu.RUnlock()
 
+	if s.closed {
+		return false, database.ErrClosed
+	}
+
+	if _, ok := s.entryCache.Get(height); ok {
+		return true, nil
+	}
+
 	_, err := s.readBlockIndex(height)
 	if err != nil {
 		if errors.Is(err, database.ErrNotFound) || errors.Is(err, ErrInvalidBlockHeight) {

x/blockdb/database_cache_test.go

@@ -0,0 +1,77 @@
+// Copyright (C) 2019-2025, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+package blockdb
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestEntryCache(t *testing.T) {
+	store, cleanup := newTestDatabase(t, DefaultConfig())
+	defer cleanup()
+
+	height := uint64(10)
+	expectedBlock := randomBlock(t)
+
+	// Write the block - this should populate the cache
+	require.NoError(t, store.Put(height, expectedBlock))
+
+	// First read should come from cache
+	block, err := store.Get(height)
+	require.NoError(t, err)
+	require.Equal(t, expectedBlock, block)
+
+	// Close all data files to ensure the next read cannot come from disk
+	store.fileCache.Flush()
+
+	// Read again - should still succeed because it comes from cache
+	cachedBlock, err := store.Get(height)
+	require.NoError(t, err)
+	require.Equal(t, expectedBlock, cachedBlock, "block should be retrieved from cache after files are closed")
+}
+
+func TestEntryCache_GetPopulatesCache(t *testing.T) {
+	store, cleanup := newTestDatabase(t, DefaultConfig())
+	defer cleanup()
+
+	height := uint64(20)
+	expectedBlock := randomBlock(t)
+
+	// Write the block
+	require.NoError(t, store.Put(height, expectedBlock))
+
+	// Evict the entry from cache to simulate a cache miss
+	store.entryCache.Evict(height)
+
+	// Read the block - this should read from disk and populate the cache
+	block, err := store.Get(height)
+	require.NoError(t, err)
+	require.Equal(t, expectedBlock, block)
+
+	// Verify it's now in cache
+	cachedBlock, ok := store.entryCache.Get(height)
+	require.True(t, ok, "entry should be in cache after Get")
+	require.Equal(t, expectedBlock, cachedBlock)
+}
+
+func TestEntryCacheHas(t *testing.T) {
+	store, cleanup := newTestDatabase(t, DefaultConfig())
+	defer cleanup()
+
+	height := uint64(30)
+	expectedBlock := randomBlock(t)
+
+	// Write the block - this populates the cache
+	require.NoError(t, store.Put(height, expectedBlock))
+
+	// Close all data files to ensure Has cannot read from disk
+	store.fileCache.Flush()
+
+	// Has should still return true because it checks cache first
+	has, err := store.Has(height)
+	require.NoError(t, err)
+	require.True(t, has, "Has should return true when block is in cache")
+}