chore: move cache from pkg, add tests and benchmrks and remove unneeded mutexs (#2648)

<!--
Please read and fill out this form before submitting your PR.

Please make sure you have reviewed our contributors guide before
submitting your
first PR.

NOTE: PR titles should follow semantic commits:
https://www.conventionalcommits.org/en/v1.0.0/
-->

## Overview

<!-- 
Please provide an explanation of the PR, including the appropriate
context,
background, goal, and rationale. If there is an issue with this
information,
please provide a tl;dr and link the issue. 

Ex: Closes #<issue number>
-->

---------

Co-authored-by: julienrbrt <julien@rbrt.fr>

Author: tac0turtle

.github/workflows/claude.yml

@@ -47,3 +47,4 @@ jobs:
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
           # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'
+          use_sticky_comment: true

block/internal/cache/bench_test.go

@@ -0,0 +1,129 @@
+package cache
+
+import (
+	"context"
+	"testing"
+
+	"github.com/rs/zerolog"
+
+	"github.com/evstack/ev-node/pkg/config"
+	"github.com/evstack/ev-node/pkg/store"
+	"github.com/evstack/ev-node/types"
+)
+
+/*
+goos: darwin
+goarch: arm64
+pkg: github.com/evstack/ev-node/block/internal/cache
+cpu: Apple M1 Pro
+BenchmarkManager_GetPendingHeaders/N=1000-10 	     278	   3922717 ns/op	5064666 B/op	70818 allocs/op
+BenchmarkManager_GetPendingHeaders/N=10000-10         	      28	  40704543 ns/op	50639803 B/op	709864 allocs/op
+BenchmarkManager_GetPendingData/N=1000-10             	     279	   4258291 ns/op	5869716 B/op	73824 allocs/op
+BenchmarkManager_GetPendingData/N=10000-10            	      26	  45428974 ns/op	58719067 B/op	  739926 allocs/op
+BenchmarkManager_PendingEventsSnapshot-10             	     336	   3251530 ns/op	 2365497 B/op	     285 allocs/op
+PASS
+ok  	github.com/evstack/ev-node/block/internal/cache	25.834s
+*/
+
+func benchSetupStore(b *testing.B, n int, txsPer int, chainID string) store.Store {
+	ds, err := store.NewDefaultInMemoryKVStore()
+	if err != nil {
+		b.Fatal(err)
+	}
+	st := store.New(ds)
+	ctx := context.Background()
+	for i := 1; i <= n; i++ {
+		h, d := types.GetRandomBlock(uint64(i), txsPer, chainID)
+		if err := st.SaveBlockData(ctx, h, d, &types.Signature{}); err != nil {
+			b.Fatal(err)
+		}
+	}
+	if err := st.SetHeight(ctx, uint64(n)); err != nil {
+		b.Fatal(err)
+	}
+	return st
+}
+
+func benchNewManager(b *testing.B, st store.Store) Manager {
+	cfg := config.DefaultConfig
+	cfg.RootDir = b.TempDir()
+	m, err := NewManager(cfg, st, zerolog.Nop())
+	if err != nil {
+		b.Fatal(err)
+	}
+	return m
+}
+
+func BenchmarkManager_GetPendingHeaders(b *testing.B) {
+	for _, n := range []int{1_000, 10_000} {
+		b.Run(benchName(n), func(b *testing.B) {
+			st := benchSetupStore(b, n, 1, "bench-headers")
+			m := benchNewManager(b, st)
+			ctx := context.Background()
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				hs, err := m.GetPendingHeaders(ctx)
+				if err != nil {
+					b.Fatal(err)
+				}
+				if len(hs) == 0 {
+					b.Fatal("unexpected empty headers")
+				}
+			}
+		})
+	}
+}
+
+func BenchmarkManager_GetPendingData(b *testing.B) {
+	for _, n := range []int{1_000, 10_000} {
+		b.Run(benchName(n), func(b *testing.B) {
+			st := benchSetupStore(b, n, 2, "bench-data") // ensure data not filtered
+			m := benchNewManager(b, st)
+			ctx := context.Background()
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				ds, err := m.GetPendingData(ctx)
+				if err != nil {
+					b.Fatal(err)
+				}
+				if len(ds) == 0 {
+					b.Fatal("unexpected empty data")
+				}
+			}
+		})
+	}
+}
+
+func BenchmarkManager_PendingEventsSnapshot(b *testing.B) {
+	st := benchSetupStore(b, 1_000, 1, "bench-events")
+	m := benchNewManager(b, st)
+	for i := 1; i <= 50_000; i++ {
+		h, d := types.GetRandomBlock(uint64(i), 1, "bench-events")
+		m.SetPendingEvent(uint64(i), &DAHeightEvent{Header: h, Data: d, DaHeight: uint64(i)})
+	}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		ev := m.GetPendingEvents()
+		if len(ev) == 0 {
+			b.Fatal("unexpected empty events")
+		}
+	}
+}
+
+func benchName(n int) string {
+	// simple itoa without fmt to avoid allocations
+	if n == 0 {
+		return "N=0"
+	}
+	var buf [20]byte
+	i := len(buf)
+	for n > 0 {
+		i--
+		buf[i] = byte('0' + n%10)
+		n /= 10
+	}
+	return "N=" + string(buf[i:])
+}

pkg/cache/cache.go block/internal/cache/generic_cache.gopkg/cache/cache.go renamed to block/internal/cache/generic_cache.go

@@ -10,54 +10,60 @@ import (
 
 // Cache is a generic cache that maintains items that are seen and hard confirmed
 type Cache[T any] struct {
-	items      *sync.Map
-	hashes     *sync.Map
+	// itemsByHeight stores items keyed by uint64 height
+	itemsByHeight *sync.Map
+	// hashes tracks whether a given hash has been seen
+	hashes *sync.Map
+	// daIncluded tracks the DA inclusion height for a given hash
 	daIncluded *sync.Map
 }
 
 // NewCache returns a new Cache struct
 func NewCache[T any]() *Cache[T] {
 	return &Cache[T]{
-		items:      new(sync.Map),
-		hashes:     new(sync.Map),
-		daIncluded: new(sync.Map),
+		itemsByHeight: new(sync.Map),
+		hashes:        new(sync.Map),
+		daIncluded:    new(sync.Map),
 	}
 }
 
-// GetItem returns an item from the cache by height
+// GetItem returns an item from the cache by height.
+// Returns nil if not found or type mismatch.
 func (c *Cache[T]) GetItem(height uint64) *T {
-	item, ok := c.items.Load(height)
+	item, ok := c.itemsByHeight.Load(height)
+	if !ok {
+		return nil
+	}
+	val, ok := item.(*T)
 	if !ok {
 		return nil
 	}
-	val := item.(*T)
 	return val
 }
 
 // SetItem sets an item in the cache by height
 func (c *Cache[T]) SetItem(height uint64, item *T) {
-	c.items.Store(height, item)
+	c.itemsByHeight.Store(height, item)
 }
 
 // DeleteItem deletes an item from the cache by height
 func (c *Cache[T]) DeleteItem(height uint64) {
-	c.items.Delete(height)
+	c.itemsByHeight.Delete(height)
 }
 
-// RangeByHeight iterates over all items keyed by uint64 height and calls fn for each.
+// RangeByHeight iterates over items keyed by height in an unspecified order and calls fn for each.
 // If fn returns false, iteration stops early.
-// Non-uint64 keys (e.g. string hash entries) are ignored.
 func (c *Cache[T]) RangeByHeight(fn func(height uint64, item *T) bool) {
-	c.items.Range(func(k, v any) bool {
+	c.itemsByHeight.Range(func(k, v any) bool {
 		height, ok := k.(uint64)
 		if !ok {
 			return true
 		}
-		item, ok := v.(*T)
+		it, ok := v.(*T)
 		if !ok {
 			return true
 		}
-		return fn(height, item)
+		return fn(height, it)
 	})
 }
 
@@ -81,23 +87,13 @@ func (c *Cache[T]) IsDAIncluded(hash string) bool {
 	return ok
 }
 
-// GetDAIncludedHeight returns the DA height at which the hash was DA included
-func (c *Cache[T]) GetDAIncludedHeight(hash string) (uint64, bool) {
-	daIncluded, ok := c.daIncluded.Load(hash)
-	if !ok {
-		return 0, false
-	}
-	return daIncluded.(uint64), true
-}
-
 // SetDAIncluded sets the hash as DA-included with the given DA height
 func (c *Cache[T]) SetDAIncluded(hash string, daHeight uint64) {
 	c.daIncluded.Store(hash, daHeight)
 }
 
 const (
 	itemsByHeightFilename = "items_by_height.gob"
-	itemsByHashFilename   = "items_by_hash.gob"
 	hashesFilename        = "hashes.gob"
 	daIncludedFilename    = "da_included.gob"
 )
@@ -147,34 +143,19 @@ func (c *Cache[T]) SaveToDisk(folderPath string) error {
 
 	// prepare items maps
 	itemsByHeightMap := make(map[uint64]*T)
-	itemsByHashMap := make(map[string]*T)
 
-	var invalidItemsErr error
-	c.items.Range(func(k, v any) bool {
-		itemVal, ok := v.(*T)
-		if !ok {
-			invalidItemsErr = fmt.Errorf("invalid item type: %T", v)
-			return false // early exit if the value is not of type *T
-		}
-		switch key := k.(type) {
-		case uint64:
-			itemsByHeightMap[key] = itemVal
-		case string:
-			itemsByHashMap[key] = itemVal
+	c.itemsByHeight.Range(func(k, v any) bool {
+		if hk, ok := k.(uint64); ok {
+			if it, ok := v.(*T); ok {
+				itemsByHeightMap[hk] = it
+			}
 		}
 		return true
 	})
 
-	if invalidItemsErr != nil {
-		return invalidItemsErr
-	}
-
 	if err := saveMapGob(filepath.Join(folderPath, itemsByHeightFilename), itemsByHeightMap); err != nil {
 		return err
 	}
-	if err := saveMapGob(filepath.Join(folderPath, itemsByHashFilename), itemsByHashMap); err != nil {
-		return err
-	}
 
 	// prepare hashes map
 	hashesToSave := make(map[string]bool)
@@ -214,16 +195,7 @@ func (c *Cache[T]) LoadFromDisk(folderPath string) error {
 		return fmt.Errorf("failed to load items by height: %w", err)
 	}
 	for k, v := range itemsByHeightMap {
-		c.items.Store(k, v)
-	}
-
-	// load items by hash
-	itemsByHashMap, err := loadMapGob[string, *T](filepath.Join(folderPath, itemsByHashFilename))
-	if err != nil {
-		return fmt.Errorf("failed to load items by hash: %w", err)
-	}
-	for k, v := range itemsByHashMap {
-		c.items.Store(k, v)
+		c.itemsByHeight.Store(k, v)
 	}
 
 	// load hashes