julienrbrt · Apr 29, 2026 · Apr 28, 2026 · Apr 28, 2026 · Apr 28, 2026 · Apr 28, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changes
 
 - Optimization of mutex usage in cache for reaper [#3286](https://github.com/evstack/ev-node/pull/3286)
+- Optimize metadata writes by making it async in cache store [#3298](https://github.com/evstack/ev-node/pull/3298)
 
 ## v1.1.1
 

diff --git a/pkg/store/cached_store.go b/pkg/store/cached_store.go
@@ -2,8 +2,10 @@
 
 import (
 	"context"
+	"sync"
 
 	lru "github.com/hashicorp/golang-lru/v2"
+	"github.com/rs/zerolog"
 
 	"github.com/evstack/ev-node/types"
 )
@@ -14,15 +16,32 @@
 
 	// DefaultBlockDataCacheSize is the default number of block data entries to cache.
 	DefaultBlockDataCacheSize = 200_000
+
+	asyncWriteBufferSize = 8192
 )
 
+type asyncWriteOp struct {
+	key      string
+	value    []byte
+	isDelete bool
+}
+
 // CachedStore wraps a Store with LRU caching for frequently accessed data.
 // The underlying LRU cache is thread-safe, so no additional synchronization is needed.
+// Metadata writes (SetMetadata, DeleteMetadata) are processed asynchronously via a
+// buffered channel to avoid blocking Badger's write pipeline for critical operations
+// like block production (batch commits).
 type CachedStore struct {
 	Store
 
 	headerCache    *lru.Cache[uint64, *types.SignedHeader]
 	blockDataCache *lru.Cache[uint64, *blockDataEntry]
+
+	writeCh chan asyncWriteOp
+	done    chan struct{}
+	stopMu  sync.RWMutex
+	stopped bool
+	logger  zerolog.Logger
 }
 
 type blockDataEntry struct {
@@ -73,6 +92,9 @@
 		Store:          store,
 		headerCache:    headerCache,
 		blockDataCache: blockDataCache,
+		writeCh:        make(chan asyncWriteOp, asyncWriteBufferSize),
+		done:           make(chan struct{}),
+		logger:         zerolog.Nop(),
 	}
 
 	for _, opt := range opts {
@@ -81,9 +103,47 @@
 		}
 	}
 
+	cs.startWriteLoop()
+
 	return cs, nil
 }
 
+func (cs *CachedStore) startWriteLoop() {
+	go func() {
+		defer close(cs.done)
+		for op := range cs.writeCh {
+			ops := []asyncWriteOp{op}
+		drain:
+			for {
+				select {
+				case op := <-cs.writeCh:
+					ops = append(ops, op)
+				default:
+					break drain
+				}
+			}
+
+			var puts []MetadataKV
+			var deletes []string
+			for _, o := range ops {
+				if o.isDelete {
+					deletes = append(deletes, o.key)
+				} else {
+					puts = append(puts, MetadataKV{Key: o.key, Value: o.value})
+				}
+			}
+
+			if err := cs.Store.BatchMetadata(context.Background(), puts, deletes); err != nil {
+				for _, o := range ops {
+					cs.logger.Error().Err(err).Str("key", o.key).
+						Bool("delete", o.isDelete).
+						Msg("async metadata batch write failed")
+				}
+			}
+		}
+	}()
+}
+
 // GetHeader returns the header at the given height, using the cache if available.
 func (cs *CachedStore) GetHeader(ctx context.Context, height uint64) (*types.SignedHeader, error) {
 	// Try cache first
@@ -173,8 +233,51 @@
 	return nil
 }
 
-// Close closes the underlying store.
+// SetMetadata queues an asynchronous metadata write. The write is persisted
+// by the background goroutine. If the buffer is full or the store has been
+// stopped, the write falls back to synchronous execution on the underlying store.
+func (cs *CachedStore) SetMetadata(ctx context.Context, key string, value []byte) error {
+	cs.stopMu.RLock()
+	if cs.stopped {
+		cs.stopMu.RUnlock()
+		return cs.Store.SetMetadata(ctx, key, value)
+	}
+	select {
+	case cs.writeCh <- asyncWriteOp{key: key, value: value}:
+		cs.stopMu.RUnlock()
+		return nil
+	default:
+		cs.stopMu.RUnlock()
+		return cs.Store.SetMetadata(ctx, key, value)
+	}
+}
+
+// DeleteMetadata queues an asynchronous metadata delete. If the buffer is full
+// or the store has been stopped, the delete falls back to synchronous execution.
+func (cs *CachedStore) DeleteMetadata(ctx context.Context, key string) error {
+	cs.stopMu.RLock()
+	if cs.stopped {
+		cs.stopMu.RUnlock()
+		return cs.Store.DeleteMetadata(ctx, key)
+	}
+	select {
+	case cs.writeCh <- asyncWriteOp{key: key, isDelete: true}:
+		cs.stopMu.RUnlock()
+		return nil
+	default:
+		cs.stopMu.RUnlock()
+		return cs.Store.DeleteMetadata(ctx, key)
+	}
+}
+
+// Close drains pending async writes, then closes the underlying store.
 func (cs *CachedStore) Close() error {
+	cs.stopMu.Lock()
+	cs.stopped = true
+	close(cs.writeCh)
+	cs.stopMu.Unlock()
+	<-cs.done
+
 	cs.ClearCache()
 	return cs.Store.Close()
 }
diff --git a/pkg/store/cached_store_test.go b/pkg/store/cached_store_test.go
@@ -3,6 +3,7 @@ package store
 import (
 	"context"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -270,3 +271,86 @@ func TestCachedStore_Close(t *testing.T) {
 	err = cachedStore.Close()
 	require.NoError(t, err)
 }
+
+func TestCachedStore_AsyncSetMetadata(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+
+	kv, err := NewTestInMemoryKVStore()
+	require.NoError(t, err)
+
+	base := New(kv)
+	cs, err := NewCachedStore(base)
+	require.NoError(t, err)
+	t.Cleanup(func() { cs.Close() })
+
+	require.NoError(t, cs.SetMetadata(ctx, "key1", []byte("value1")))
+
+	require.Eventually(t, func() bool {
+		v, err := base.GetMetadata(ctx, "key1")
+		return err == nil && string(v) == "value1"
+	}, time.Second, 10*time.Millisecond)
+}
+
+func TestCachedStore_AsyncDeleteMetadata(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+
+	kv, err := NewTestInMemoryKVStore()
+	require.NoError(t, err)
+
+	base := New(kv)
+	require.NoError(t, base.SetMetadata(ctx, "key1", []byte("value1")))
+
+	cs, err := NewCachedStore(base)
+	require.NoError(t, err)
+	t.Cleanup(func() { cs.Close() })
+
+	require.NoError(t, cs.DeleteMetadata(ctx, "key1"))
+
+	require.Eventually(t, func() bool {
+		_, err := base.GetMetadata(ctx, "key1")
+		return err != nil
+	}, time.Second, 10*time.Millisecond)
+}
+
+func TestCachedStore_Close_FlushesPendingWrites(t *testing.T) {
+	kv, err := NewTestInMemoryKVStore()
+	require.NoError(t, err)
+
+	base := New(kv)
+	cs, err := NewCachedStore(base)
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	const n = 100
+	for i := 0; i < n; i++ {
+		k := []byte{byte(i)}
+		require.NoError(t, cs.SetMetadata(ctx, string(k), k))
+	}
+
+	// Wait for the last key to land via pass-through read
+	require.Eventually(t, func() bool {
+		v, err := cs.GetMetadata(ctx, string([]byte{byte(n - 1)}))
+		return err == nil && len(v) == 1 && v[0] == byte(n-1)
+	}, 2*time.Second, 10*time.Millisecond)
+
+	require.NoError(t, cs.Close())
+}
+
+func TestCachedStore_WriteAfterClose_FallsBack(t *testing.T) {
+	kv, err := NewTestInMemoryKVStore()
+	require.NoError(t, err)
+
+	base := New(kv)
+	cs, err := NewCachedStore(base)
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	require.NoError(t, cs.SetMetadata(ctx, "before", []byte("ok")))
+
+	require.NoError(t, cs.Close())
+
+	err = cs.SetMetadata(ctx, "after", []byte("sync"))
+	require.Error(t, err)
+}
diff --git a/pkg/store/store.go b/pkg/store/store.go
@@ -190,6 +190,30 @@ func (s *DefaultStore) SetMetadata(ctx context.Context, key string, value []byte
 	return nil
 }
 
+func (s *DefaultStore) BatchMetadata(ctx context.Context, puts []MetadataKV, deletes []string) error {
+	if len(puts) == 0 && len(deletes) == 0 {
+		return nil
+	}
+	batch, err := s.db.Batch(ctx)
+	if err != nil {
+		return fmt.Errorf("failed to create metadata batch: %w", err)
+	}
+	for _, kv := range puts {
+		if err := batch.Put(ctx, ds.NewKey(GetMetaKey(kv.Key)), kv.Value); err != nil {
+			return fmt.Errorf("failed to batch-put metadata key '%s': %w", kv.Key, err)
+		}
+	}
+	for _, key := range deletes {
+		if err := batch.Delete(ctx, ds.NewKey(GetMetaKey(key))); err != nil {
+			return fmt.Errorf("failed to batch-delete metadata key '%s': %w", key, err)
+		}
+	}
+	if err := batch.Commit(ctx); err != nil {
+		return fmt.Errorf("failed to commit metadata batch: %w", err)
+	}
+	return nil
+}
+
 // GetMetadata returns values stored for given key with SetMetadata.
 func (s *DefaultStore) GetMetadata(ctx context.Context, key string) ([]byte, error) {
 	data, err := s.db.Get(ctx, ds.NewKey(GetMetaKey(key)))

diff --git a/pkg/store/tracing.go b/pkg/store/tracing.go
@@ -211,6 +211,25 @@ func (t *tracedStore) DeleteMetadata(ctx context.Context, key string) error {
 	return nil
 }
 
+func (t *tracedStore) BatchMetadata(ctx context.Context, puts []MetadataKV, deletes []string) error {
+	ctx, span := t.tracer.Start(ctx, "Store.BatchMetadata",
+		trace.WithAttributes(
+			attribute.Int("puts", len(puts)),
+			attribute.Int("deletes", len(deletes)),
+		),
+	)
+	defer span.End()
+
+	err := t.inner.BatchMetadata(ctx, puts, deletes)
+	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	return nil
+}
+
 func (t *tracedStore) DeleteStateAtHeight(ctx context.Context, height uint64) error {
 	ctx, span := t.tracer.Start(ctx, "Store.DeleteStateAtHeight",
 		trace.WithAttributes(attribute.Int64("height", int64(height))),

diff --git a/pkg/store/tracing_test.go b/pkg/store/tracing_test.go
@@ -28,6 +28,7 @@ type tracingMockStore struct {
 	getMetadataFn      func(ctx context.Context, key string) ([]byte, error)
 
 	setMetadataFn         func(ctx context.Context, key string, value []byte) error
+	batchMetadataFn       func(ctx context.Context, puts []MetadataKV, deletes []string) error
 	deleteMetadataFn      func(ctx context.Context, key string) error
 	rollbackFn            func(ctx context.Context, height uint64, aggregator bool) error
 	pruneBlocksFn         func(ctx context.Context, height uint64) error
@@ -105,6 +106,13 @@ func (m *tracingMockStore) SetMetadata(ctx context.Context, key string, value []
 	return nil
 }
 
+func (m *tracingMockStore) BatchMetadata(ctx context.Context, puts []MetadataKV, deletes []string) error {
+	if m.batchMetadataFn != nil {
+		return m.batchMetadataFn(ctx, puts, deletes)
+	}
+	return nil
+}
+
 func (m *tracingMockStore) DeleteMetadata(ctx context.Context, key string) error {
 	if m.deleteMetadataFn != nil {
 		return m.deleteMetadataFn(ctx, key)

diff --git a/pkg/store/types.go b/pkg/store/types.go
@@ -54,6 +54,12 @@ type Store interface {
 	NewBatch(ctx context.Context) (Batch, error)
 }
 
+// MetadataKV is a key-value pair for batched metadata operations.
+type MetadataKV struct {
+	Key   string
+	Value []byte
+}
+
 type Metadata interface {
 	// SetMetadata saves arbitrary value in the store.
 	//
@@ -62,6 +68,10 @@ type Metadata interface {
 
 	// DeleteMetadata removes a metadata key from the store.
 	DeleteMetadata(ctx context.Context, key string) error
+
+	// BatchMetadata writes and deletes metadata keys in a single Badger
+	// WriteBatch transaction, reducing contention on the write pipeline.
+	BatchMetadata(ctx context.Context, puts []MetadataKV, deletes []string) error
 }
 
 type Reader interface {