[Off-chain] feat: in-memory query cache(s)

pkg/client/interface.go

@@ -360,3 +360,23 @@ type BankQueryClient interface {
 	// GetBalance queries the chain for the uPOKT balance of the account provided
 	GetBalance(ctx context.Context, address string) (*cosmostypes.Coin, error)
 }
+
+// QueryCache is a key/value store style interface for a cache of a single type.
+// It is intended to be used to cache query responses (or derivatives thereof),
+// where each key uniquely indexes its most recent value.
+type QueryCache[T any] interface {
+	Get(key string) (T, error)
+	Set(key string, value T) error
+	Delete(key string)
+	Clear()
+}
+
+// HistoricalQueryCache extends QueryCache to support getting and setting values
+// at multiple heights for a given key.
+type HistoricalQueryCache[T any] interface {
+	QueryCache[T]
+	// GetAtHeight retrieves the nearest value <= the specified height
+	GetAtHeight(key string, height int64) (T, error)
+	// SetAtHeight adds or updates a value at a specific height
+	SetAtHeight(key string, value T, height int64) error
+}

pkg/client/query/cache/config.go

@@ -0,0 +1,69 @@
+package cache
+
+import (
+	"time"
+)
+
+// EvictionPolicy determines how items are removed when number of keys in the cache reaches MaxKeys.
+type EvictionPolicy int64
+
+const (
+	FirstInFirstOut = EvictionPolicy(iota)
+	LeastRecentlyUsed
+	LeastFrequentlyUsed
+)
+
+// queryCacheConfig is the configuration for query caches. It is intended to be
+// configured via QueryCacheOptionFn functions.
+type queryCacheConfig struct {
+	// MaxKeys is the maximum number of items (key/value pairs) the cache can
+	// hold before it starts evicting.
+	MaxKeys        int64
+	EvictionPolicy EvictionPolicy
+	// TTL is how long items should remain in the cache. Items older than the TTL
+	// MAY not be evicted but SHOULD not be considered as cache hits.
+	TTL time.Duration
+
+	// historical determines whether the cache will cache a single value for each
+	// key (false), or whether it will cache a history of values for each key (true).
+	historical bool
+	// pruneOlderThan is the number of past blocks for which to keep historical
+	// values. If 0, no historical pruning is performed. It only applies when
+	// historical is true.
+	pruneOlderThan int64
+}
+
+// QueryCacheOptionFn is a function which receives a queryCacheConfig for configuration.
+type QueryCacheOptionFn func(*queryCacheConfig)
+
+// WithHistoricalMode enables historical caching with the given pruneOlderThan
+// configuration; if 0, no historical pruning is performed.
+func WithHistoricalMode(pruneOlderThan int64) QueryCacheOptionFn {
+	return func(cfg *queryCacheConfig) {
+		cfg.historical = true
+		cfg.pruneOlderThan = pruneOlderThan
+	}
+}
+
+// WithMaxKeys sets the maximum number of distinct key/value pairs the cache will
+// hold before evicting according to the configured eviction policy.
+func WithMaxKeys(maxKeys int64) QueryCacheOptionFn {
+	return func(cfg *queryCacheConfig) {
+		cfg.MaxKeys = maxKeys
+	}
+}
+
+// WithEvictionPolicy sets the eviction policy.
+func WithEvictionPolicy(policy EvictionPolicy) QueryCacheOptionFn {
+	return func(cfg *queryCacheConfig) {
+		cfg.EvictionPolicy = policy
+	}
+}
+
+// WithTTL sets the time-to-live for cached items. Items older than the TTL
+// MAY not be evicted but SHOULD not be considered as cache hits.
+func WithTTL(ttl time.Duration) QueryCacheOptionFn {
+	return func(cfg *queryCacheConfig) {
+		cfg.TTL = ttl
+	}
+}

pkg/client/query/cache/errors.go

@@ -0,0 +1,10 @@
+package cache
+
+import "cosmossdk.io/errors"
+
+const codesace = "client/query/cache"
+
+var (
+	ErrCacheMiss                = errors.Register(codesace, 1, "cache miss")
+	ErrHistoricalModeNotEnabled = errors.Register(codesace, 2, "historical mode not enabled")
+)