feat(core): add store API (#14227)

core/store/doc.go

@@ -0,0 +1,3 @@
+// Package store provides a basic API for modules to interact with kv-stores
+// independently of any implementation of that functionality.
+package store

core/store/service.go

@@ -0,0 +1,27 @@
+package store
+
+import "context"
+
+// KVStoreService represents a unique, non-forgeable handle to a regular merkle-tree
+// backed KVStore. It should be provided as a module-scoped dependency by the runtime
+// module being used to build the app.
+type KVStoreService interface {
+	// OpenKVStore retrieves the KVStore from the context.
+	OpenKVStore(context.Context) KVStore
+}
+
+// MemoryStoreService represents a unique, non-forgeable handle to a memory-backed
+// KVStore. It should be provided as a module-scoped dependency by the runtime
+// module being used to build the app.
+type MemoryStoreService interface {
+	// OpenMemoryStore retrieves the memory store from the context.
+	OpenMemoryStore(context.Context) KVStore
+}
+
+// TransientStoreService represents a unique, non-forgeable handle to a memory-backed
+// KVStore which is reset at the start of every block. It should be provided as
+// a module-scoped dependency by the runtime module being used to build the app.
+type TransientStoreService interface {
+	// OpenTransientStore retrieves the transient store from the context.
+	OpenTransientStore(context.Context) KVStore
+}

core/store/store.go

@@ -0,0 +1,37 @@
+package store
+
+import dbm "github.com/tendermint/tm-db"
+
+// KVStore describes the basic interface for interacting with key-value stores.
+type KVStore interface {
+
+	// Get returns nil iff key doesn't exist. Panics on nil key.
+	Get(key []byte) []byte
+
+	// Has checks if a key exists. Panics on nil key.
+	Has(key []byte) bool
+
+	// Set sets the key. Panics on nil key or value.
+	Set(key, value []byte)
+
+	// Delete deletes the key. Panics on nil key.
+	Delete(key []byte)
+
+	// Iterator iterates over a domain of keys in ascending order. End is exclusive.
+	// Start must be less than end, or the Iterator is invalid.
+	// Iterator must be closed by caller.
+	// To iterate over entire domain, use store.Iterator(nil, nil)
+	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
+	// Exceptionally allowed for cachekv.Store, safe to write in the modules.
+	Iterator(start, end []byte) Iterator
+
+	// ReverseIterator iterates over a domain of keys in descending order. End is exclusive.
+	// Start must be less than end, or the Iterator is invalid.
+	// Iterator must be closed by caller.
+	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
+	// Exceptionally allowed for cachekv.Store, safe to write in the modules.
+	ReverseIterator(start, end []byte) Iterator
+}
+
+// Iterator is an alias db's Iterator for convenience.
+type Iterator = dbm.Iterator