flatkv cache

sei-db/common/metrics/phase_timer.go

@@ -30,6 +30,7 @@ func NewPhaseTimerFactory(meter metric.Meter, timerName string) *PhaseTimerFacto
 		timerName+"_phase_latency_seconds",
 		metric.WithDescription("Latency per phase (seconds); use for p99, p95, etc."),
 		metric.WithUnit("s"),
+		metric.WithExplicitBucketBoundaries(LatencyBuckets...),
 	)
 	return &PhaseTimerFactory{
 		phaseDurationTotal: phaseDurationTotal,

sei-db/common/threading/fixed_pool.go

@@ -26,6 +26,10 @@ func NewFixedPool(
 	queueSize int,
 ) Pool {
 
+	if workers <= 0 {
+		workers = 1
+	}
+
 	workQueue := make(chan func(), queueSize)
 	fp := &fixedPool{
 		workQueue: workQueue,

sei-db/config/sc_config.go

@@ -67,7 +67,7 @@ func DefaultStateCommitConfig() StateCommitConfig {
 		ReadMode:          CosmosOnlyRead,
 		EnableLatticeHash: false,
 		MemIAVLConfig:     memiavl.DefaultConfig(),
-		FlatKVConfig:      flatkv.DefaultConfig(),
+		FlatKVConfig:      *flatkv.DefaultConfig(),
 
 		HistoricalProofMaxInFlight: DefaultSCHistoricalProofMaxInFlight,
 		HistoricalProofRateLimit:   DefaultSCHistoricalProofRateLimit,

sei-db/db_engine/dbcache/cache.go

@@ -3,7 +3,6 @@ package dbcache
 import (
 	"context"
 	"fmt"
-	"time"
 
 	"github.com/sei-protocol/sei-chain/sei-db/common/threading"
 	"github.com/sei-protocol/sei-chain/sei-db/db_engine/types"
@@ -93,32 +92,18 @@ func (u *CacheUpdate) IsDelete() bool {
 	return u.Value == nil
 }
 
-// BuildCache creates a new Cache.
+// BuildCache creates a new Cache. When cfg.MaxSize is 0 a no-op (passthrough) cache is returned.
 func BuildCache(
 	ctx context.Context,
-	shardCount uint64,
-	maxSize uint64,
+	cfg *CacheConfig,
 	readPool threading.Pool,
 	miscPool threading.Pool,
-	estimatedOverheadPerEntry uint64,
-	cacheName string,
-	metricsScrapeInterval time.Duration,
 ) (Cache, error) {
-
-	if maxSize == 0 {
+	if cfg.MaxSize == 0 {
 		return NewNoOpCache(), nil
 	}
 
-	cache, err := NewStandardCache(
-		ctx,
-		shardCount,
-		maxSize,
-		readPool,
-		miscPool,
-		estimatedOverheadPerEntry,
-		cacheName,
-		metricsScrapeInterval,
-	)
+	cache, err := NewStandardCache(ctx, cfg, readPool, miscPool)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create cache: %w", err)
 	}

sei-db/db_engine/dbcache/cache_config.go

@@ -0,0 +1,43 @@
+package dbcache
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/sei-protocol/sei-chain/sei-db/common/unit"
+)
+
+// CacheConfig defines configuration for a sharded LRU read-through cache.
+type CacheConfig struct {
+	// The number of shards in the cache. Must be a power of two and greater than 0.
+	ShardCount uint64
+	// The maximum size of the cache, in bytes. 0 disables the cache.
+	MaxSize uint64
+	// The estimated overhead per entry, in bytes. Used to calculate effective cache
+	// capacity. Derive experimentally; may differ between builds and architectures.
+	EstimatedOverheadPerEntry uint64
+	// Name used as the "cache" attribute on OTel metrics. Empty string disables metrics.
+	MetricsName string
+	// How often to scrape cache size for metrics. Ignored if MetricsName is empty.
+	MetricsScrapeInterval time.Duration
+}
+
+// DefaultCacheConfig returns a CacheConfig with sensible defaults.
+func DefaultCacheConfig() CacheConfig {
+	return CacheConfig{
+		ShardCount:                8,
+		MaxSize:                   512 * unit.MB,
+		EstimatedOverheadPerEntry: DefaultEstimatedOverheadPerEntry,
+	}
+}
+
+// Validate checks that the configuration is sane and returns an error if it is not.
+func (c *CacheConfig) Validate() error {
+	if c.MaxSize > 0 && (c.ShardCount == 0 || (c.ShardCount&(c.ShardCount-1)) != 0) {
+		return fmt.Errorf("shard count must be a non-zero power of two")
+	}
+	if c.MetricsName != "" && c.MetricsScrapeInterval <= 0 {
+		return fmt.Errorf("metrics scrape interval must be positive when metrics name is set")
+	}
+	return nil
+}

sei-db/db_engine/dbcache/cache_impl.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 	"sync"
-	"time"
 
 	"github.com/sei-protocol/sei-chain/sei-db/common/threading"
 	"github.com/sei-protocol/sei-chain/sei-db/db_engine/types"
@@ -29,45 +28,33 @@ type cache struct {
 	miscPool threading.Pool
 }
 
-// Creates a new Cache. If cacheName is non-empty, OTel metrics are enabled and the
-// background size scrape runs every metricsScrapeInterval.
+// Creates a new Cache. If cfg.MetricsName is non-empty, OTel metrics are enabled and the
+// background size scrape runs every cfg.MetricsScrapeInterval.
 func NewStandardCache(
 	ctx context.Context,
-	// The number of shards in the cache. Must be a power of two and greater than 0.
-	shardCount uint64,
-	// The maximum size of the cache, in bytes.
-	maxSize uint64,
-	// A work pool for reading from the DB.
+	cfg *CacheConfig,
 	readPool threading.Pool,
-	// A work pool for miscellaneous operations that are neither computationally intensive nor IO bound.
 	miscPool threading.Pool,
-	// The estimated overhead per entry, in bytes. This is used to calculate the maximum size of the cache.
-	// This value should be derived experimentally, and may differ between different builds and architectures.
-	estimatedOverheadPerEntry uint64,
-	// Name used as the "cache" attribute on metrics. Empty string disables metrics.
-	cacheName string,
-	// How often to scrape cache size for metrics. Ignored if cacheName is empty.
-	metricsScrapeInterval time.Duration,
 ) (Cache, error) {
-	if shardCount == 0 || (shardCount&(shardCount-1)) != 0 {
+	if cfg.ShardCount == 0 || (cfg.ShardCount&(cfg.ShardCount-1)) != 0 {
 		return nil, ErrNumShardsNotPowerOfTwo
 	}
-	if maxSize == 0 {
+	if cfg.MaxSize == 0 {
 		return nil, fmt.Errorf("maxSize must be greater than 0")
 	}
 
-	shardManager, err := newShardManager(shardCount)
+	shardManager, err := newShardManager(cfg.ShardCount)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create shard manager: %w", err)
 	}
-	sizePerShard := maxSize / shardCount
+	sizePerShard := cfg.MaxSize / cfg.ShardCount
 	if sizePerShard == 0 {
 		return nil, fmt.Errorf("maxSize must be greater than shardCount")
 	}
 
-	shards := make([]*shard, shardCount)
-	for i := uint64(0); i < shardCount; i++ {
-		shards[i], err = NewShard(ctx, readPool, sizePerShard, estimatedOverheadPerEntry)
+	shards := make([]*shard, cfg.ShardCount)
+	for i := uint64(0); i < cfg.ShardCount; i++ {
+		shards[i], err = NewShard(ctx, readPool, sizePerShard, cfg.EstimatedOverheadPerEntry)
 		if err != nil {
 			return nil, fmt.Errorf("failed to create shard: %w", err)
 		}
@@ -81,8 +68,8 @@ func NewStandardCache(
 		miscPool:     miscPool,
 	}
 
-	if cacheName != "" {
-		metrics := newCacheMetrics(ctx, cacheName, metricsScrapeInterval, c.getCacheSizeInfo)
+	if cfg.MetricsName != "" {
+		metrics := newCacheMetrics(ctx, cfg.MetricsName, cfg.MetricsScrapeInterval, c.getCacheSizeInfo)
 		for _, s := range c.shards {
 			s.metrics = metrics
 		}

sei-db/db_engine/dbcache/cache_impl_test.go

@@ -31,7 +31,9 @@ func newTestCache(t *testing.T, store map[string][]byte, shardCount, maxSize uin
 		return v, true, nil
 	}
 	pool := threading.NewAdHocPool()
-	c, err := NewStandardCache(context.Background(), shardCount, maxSize, pool, pool, 16, "", 0)
+	c, err := NewStandardCache(context.Background(), &CacheConfig{
+		ShardCount: shardCount, MaxSize: maxSize, EstimatedOverheadPerEntry: 16,
+	}, pool, pool)
 	require.NoError(t, err)
 	return c, read
 }
@@ -42,50 +44,64 @@ func newTestCache(t *testing.T, store map[string][]byte, shardCount, maxSize uin
 
 func TestNewStandardCacheValid(t *testing.T) {
 	pool := threading.NewAdHocPool()
-	c, err := NewStandardCache(context.Background(), 4, 1024, pool, pool, 16, "", 0)
+	c, err := NewStandardCache(context.Background(), &CacheConfig{
+		ShardCount: 4, MaxSize: 1024, EstimatedOverheadPerEntry: 16,
+	}, pool, pool)
 	require.NoError(t, err)
 	require.NotNil(t, c)
 }
 
 func TestNewStandardCacheSingleShard(t *testing.T) {
 	pool := threading.NewAdHocPool()
-	c, err := NewStandardCache(context.Background(), 1, 1024, pool, pool, 16, "", 0)
+	c, err := NewStandardCache(context.Background(), &CacheConfig{
+		ShardCount: 1, MaxSize: 1024, EstimatedOverheadPerEntry: 16,
+	}, pool, pool)
 	require.NoError(t, err)
 	require.NotNil(t, c)
 }
 
 func TestNewStandardCacheShardCountZero(t *testing.T) {
 	pool := threading.NewAdHocPool()
-	_, err := NewStandardCache(context.Background(), 0, 1024, pool, pool, 16, "", 0)
+	_, err := NewStandardCache(context.Background(), &CacheConfig{
+		ShardCount: 0, MaxSize: 1024, EstimatedOverheadPerEntry: 16,
+	}, pool, pool)
 	require.Error(t, err)
 }
 
 func TestNewStandardCacheShardCountNotPowerOfTwo(t *testing.T) {
 	pool := threading.NewAdHocPool()
 	for _, n := range []uint64{3, 5, 6, 7, 9, 10} {
-		_, err := NewStandardCache(context.Background(), n, 1024, pool, pool, 16, "", 0)
+		_, err := NewStandardCache(context.Background(), &CacheConfig{
+			ShardCount: n, MaxSize: 1024, EstimatedOverheadPerEntry: 16,
+		}, pool, pool)
 		require.Error(t, err, "shardCount=%d", n)
 	}
 }
 
 func TestNewStandardCacheMaxSizeZero(t *testing.T) {
 	pool := threading.NewAdHocPool()
-	_, err := NewStandardCache(context.Background(), 4, 0, pool, pool, 16, "", 0)
+	_, err := NewStandardCache(context.Background(), &CacheConfig{
+		ShardCount: 4, MaxSize: 0, EstimatedOverheadPerEntry: 16,
+	}, pool, pool)
 	require.Error(t, err)
 }
 
 func TestNewStandardCacheMaxSizeLessThanShardCount(t *testing.T) {
 	pool := threading.NewAdHocPool()
 	// shardCount=4, maxSize=3 → sizePerShard=0
-	_, err := NewStandardCache(context.Background(), 4, 3, pool, pool, 16, "", 0)
+	_, err := NewStandardCache(context.Background(), &CacheConfig{
+		ShardCount: 4, MaxSize: 3, EstimatedOverheadPerEntry: 16,
+	}, pool, pool)
 	require.Error(t, err)
 }
 
 func TestNewStandardCacheWithMetrics(t *testing.T) {
 	pool := threading.NewAdHocPool()
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
-	c, err := NewStandardCache(ctx, 2, 1024, pool, pool, 0, "test-cache", time.Hour)
+	c, err := NewStandardCache(ctx, &CacheConfig{
+		ShardCount: 2, MaxSize: 1024, MetricsName: "test-cache", MetricsScrapeInterval: time.Hour,
+	}, pool, pool)
 	require.NoError(t, err)
 	require.NotNil(t, c)
 }
@@ -144,7 +160,7 @@ func TestCacheGetDBError(t *testing.T) {
 	dbErr := errors.New("db fail")
 	readFunc := func(key []byte) ([]byte, bool, error) { return nil, false, dbErr }
 	pool := threading.NewAdHocPool()
-	c, _ := NewStandardCache(context.Background(), 1, 4096, pool, pool, 0, "", 0)
+	c, _ := NewStandardCache(context.Background(), &CacheConfig{ShardCount: 1, MaxSize: 4096}, pool, pool)
 
 	_, _, err := c.Get(readFunc, []byte("k"), true)
 	require.Error(t, err)
@@ -158,7 +174,7 @@ func TestCacheGetSameKeyConsistentShard(t *testing.T) {
 		return []byte("val"), true, nil
 	}
 	pool := threading.NewAdHocPool()
-	c, _ := NewStandardCache(context.Background(), 4, 4096, pool, pool, 0, "", 0)
+	c, _ := NewStandardCache(context.Background(), &CacheConfig{ShardCount: 4, MaxSize: 4096}, pool, pool)
 
 	val1, _, _ := c.Get(readFunc, []byte("key"), true)
 	val2, _, _ := c.Get(readFunc, []byte("key"), true)
@@ -327,7 +343,7 @@ func TestCacheBatchSetEmpty(t *testing.T) {
 
 func TestCacheBatchSetPoolFailure(t *testing.T) {
 	readPool := threading.NewAdHocPool()
-	c, _ := NewStandardCache(context.Background(), 1, 4096, readPool, &failPool{}, 0, "", 0)
+	c, _ := NewStandardCache(context.Background(), &CacheConfig{ShardCount: 1, MaxSize: 4096}, readPool, &failPool{})
 
 	err := c.BatchSet([]CacheUpdate{
 		{Key: []byte("k"), Value: []byte("v")},
@@ -405,7 +421,7 @@ func TestCacheBatchGetDBError(t *testing.T) {
 	dbErr := errors.New("broken")
 	readFunc := func(key []byte) ([]byte, bool, error) { return nil, false, dbErr }
 	pool := threading.NewAdHocPool()
-	c, _ := NewStandardCache(context.Background(), 1, 4096, pool, pool, 0, "", 0)
+	c, _ := NewStandardCache(context.Background(), &CacheConfig{ShardCount: 1, MaxSize: 4096}, pool, pool)
 
 	keys := map[string]types.BatchGetResult{"fail": {}}
 	require.NoError(t, c.BatchGet(readFunc, keys), "BatchGet itself should not fail")
@@ -420,7 +436,7 @@ func TestCacheBatchGetEmpty(t *testing.T) {
 
 func TestCacheBatchGetPoolFailure(t *testing.T) {
 	readPool := threading.NewAdHocPool()
-	c, _ := NewStandardCache(context.Background(), 1, 4096, readPool, &failPool{}, 0, "", 0)
+	c, _ := NewStandardCache(context.Background(), &CacheConfig{ShardCount: 1, MaxSize: 4096}, readPool, &failPool{})
 
 	keys := map[string]types.BatchGetResult{"k": {}}
 	err := c.BatchGet(noopRead, keys)
@@ -429,7 +445,7 @@ func TestCacheBatchGetPoolFailure(t *testing.T) {
 
 func TestCacheBatchGetShardReadPoolFailure(t *testing.T) {
 	miscPool := threading.NewAdHocPool()
-	c, _ := NewStandardCache(context.Background(), 1, 4096, &failPool{}, miscPool, 0, "", 0)
+	c, _ := NewStandardCache(context.Background(), &CacheConfig{ShardCount: 1, MaxSize: 4096}, &failPool{}, miscPool)
 
 	keys := map[string]types.BatchGetResult{"a": {}, "b": {}}
 	require.NoError(t, c.BatchGet(noopRead, keys))
@@ -505,7 +521,9 @@ func TestCacheGetCacheSizeInfoAggregatesShards(t *testing.T) {
 func TestCacheSizeInfoIncludesOverhead(t *testing.T) {
 	const overhead = 200
 	pool := threading.NewAdHocPool()
-	c, err := NewStandardCache(context.Background(), 1, 100_000, pool, pool, overhead, "", 0)
+	c, err := NewStandardCache(context.Background(), &CacheConfig{
+		ShardCount: 1, MaxSize: 100_000, EstimatedOverheadPerEntry: overhead,
+	}, pool, pool)
 	require.NoError(t, err)
 	impl := c.(*cache)
 
@@ -523,7 +541,9 @@ func TestCacheOverheadCausesEarlierEviction(t *testing.T) {
 	pool := threading.NewAdHocPool()
 	// Single shard, maxSize=500. Each 10-byte value entry costs 1+10+200=211 bytes.
 	// Two entries = 422 < 500. Three entries = 633 > 500, so one must be evicted.
-	c, err := NewStandardCache(context.Background(), 1, 500, pool, pool, overhead, "", 0)
+	c, err := NewStandardCache(context.Background(), &CacheConfig{
+		ShardCount: 1, MaxSize: 500, EstimatedOverheadPerEntry: overhead,
+	}, pool, pool)
 	require.NoError(t, err)
 	impl := c.(*cache)
 
@@ -731,7 +751,7 @@ func TestCacheBatchGetAfterBatchSetWithDeletes(t *testing.T) {
 func TestNewStandardCachePowerOfTwoShardCounts(t *testing.T) {
 	pool := threading.NewAdHocPool()
 	for _, n := range []uint64{1, 2, 4, 8, 16, 32, 64} {
-		c, err := NewStandardCache(context.Background(), n, n*100, pool, pool, 0, "", 0)
+		c, err := NewStandardCache(context.Background(), &CacheConfig{ShardCount: n, MaxSize: n * 100}, pool, pool)
 		require.NoError(t, err, "shardCount=%d", n)
 		require.NotNil(t, c, "shardCount=%d", n)
 	}