From aafd06ed9130cd0586a456477d6da5c6db673f02 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sat, 16 Jun 2018 21:13:55 -0700 Subject: [PATCH] update store.md --- docs/sdk/core/store.md | 83 +++++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 45 deletions(-) diff --git a/docs/sdk/core/store.md b/docs/sdk/core/store.md index b0ebb306c75b..a96eca90fb95 100644 --- a/docs/sdk/core/store.md +++ b/docs/sdk/core/store.md @@ -1,69 +1,62 @@ - ## Storage -### MultiStore - -MultiStore is like a root filesystem of an operating system, except -all the entries are fully Merkleized. You mount onto a MultiStore -any number of Stores. Currently only KVStores are supported, but in -the future we may support more kinds of stores, such as a HeapStore -or a NDStore for multidimensional storage. +## MultiStore -The MultiStore as well as all mounted stores provide caching (aka -cache-wrapping) for intermediate state (aka software transactional -memory) during the execution of transactions. In the case of the -KVStore, this also works for iterators. For example, after running -the app's AnteHandler, the MultiStore is cache-wrapped (and each -store is also cache-wrapped) so that should processing of the -transaction fail, at least the transaction fees are paid and -sequence incremented. +The Cosmos-SDK provides a special Merkle database called a `MultiStore` to be used for all application +storage. The MultiStore consists of multiple Stores that must be mounted to the +MultiStore during application setup. Stores are mounted to the MultiStore using a capabilities key, +ensuring that only parts of the program with access to the key can access the store. -The MultiStore as well as all stores support (or will support) -historical state pruning and snapshotting and various kinds of -queries with proofs. +The goals of the MultiStore are as follows: -### KVStore +- Enforce separation of concerns at the storage level +- Restrict access to storage using capabilities +- Support multiple Store implementations in a single MultiStore, for instance the Tendermint IAVL tree and + the Ethereum Patricia Trie +- Merkle proofs for various queries (existence, absence, range, etc.) on current and retained historical state +- Allow for iteration within Stores +- Provide caching for intermediate state during execution of blocks and transactions (including for iteration) +- Support historical state pruning and snapshotting -Here we'll focus on the IAVLStore, which is a kind of KVStore. +Currently, all Stores in the MultiStore must satisfy the `KVStore` interface, +which defines a simple key-value store. In the future, +we may support more kinds of stores, such as a HeapStore +or a NDStore for multidimensional storage. -IAVLStore is a fast balanced dynamic Merkle store that also supports -iteration, and of course cache-wrapping, state pruning, and various -queries with proofs, such as proofs of existence, absence, range, -and so on. +## Mounting Stores -Here's how you mount them to a MultiStore. +Stores are mounted during application setup. To mount some stores, first create +their capability-keys: -```go -mainDB, catDB := dbm.NewMemDB(), dbm.NewMemDB() +``` fooKey := sdk.NewKVStoreKey("foo") barKey := sdk.NewKVStoreKey("bar") catKey := sdk.NewKVStoreKey("cat") +``` + +Stores can either specify there own database, or share a primary one. +In this example, `foo` and `bar` will share a primary database, while `cat` will +specify its own: + +``` +mainDB, catDB := dbm.NewMemDB(), dbm.NewMemDB() ms := NewCommitMultiStore(mainDB) ms.MountStoreWithDB(fooKey, sdk.StoreTypeIAVL, nil) ms.MountStoreWithDB(barKey, sdk.StoreTypeIAVL, nil) ms.MountStoreWithDB(catKey, sdk.StoreTypeIAVL, catDB) ``` +## Accessing Stores + +In the Cosmos-SDK, the only way to access a store is with a capability-key. +Only modules given explicit access to the capability-key will +be able to access the corresponding store. + +## Notes + In the example above, all IAVL nodes (inner and leaf) will be stored in mainDB with the prefix of "s/k:foo/" and "s/k:bar/" respectively, thus sharing the mainDB. All IAVL nodes (inner and leaf) for the cat KVStore are stored separately in catDB with the prefix of "s/\_/". The "s/k:KEY/" and "s/\_/" prefixes are there to disambiguate store items from other items of non-storage concern. - - - -## - -Mounting an IAVLStore -TODO: - -IAVLStore: Fast balanced dynamic Merkle store. -supports iteration. -MultiStore: multiple Merkle tree backends in a single store -allows using Ethereum Patricia Trie and Tendermint IAVL in same app -Provide caching for intermediate state during execution of blocks and -transactions (including for iteration) -Historical state pruning and snapshotting. -Query proofs (existence, absence, range, etc.) on current and retained -historical state.