Module exonum::storage
[−]
[src]
A module that provides interfaces to work with the persisted blockchain data.
See also the documentation page on storage.
Database
A Database
is a container for data persistence. Internally, a Database
is
a collection of named key-value stores (aka column families)
with reading isolation and atomic writes. The database is assumed to be embedded,
that is, the Exonum process has exclusive access to the DB during blockchain operation.
You can interact with the Database
from multiple threads by cloning its instance.
Exonum provides two database types: RocksDB
and MemoryDB
.
Snapshot and Fork
Snapshots and forks facilitate access to the database.
If you need to read the data, you can create a Snapshot
using the snapshot
method
of the Database
instance. Snapshots provide read isolation, so you are guaranteed to work
with consistent values even if the data in the database changes between reads. Snapshot
provides all the necessary methods for reading data from the database, so &Snapshot
is used as a storage view for creating a read-only representation of the indices.
If you need to make changes to the database, you need to create a Fork
using
the fork
method of the Database
. Like Snapshot
, Fork
provides read isolation,
but also allows to create a sequence of changes to the database that are specified
as a Patch
. A patch can be atomically merge
d into a database. Different threads
may call merge
concurrently.
StorageKey
and StorageValue
traits
If you need to use your own data types as keys or values in the storage, you need to implement
the StorageKey
or StorageValue
traits respectively. These traits are already
implemented for most standard types.
Indices
Indices are structures representing data collections stored in the database. This concept is similar to tables in relational databases. The interfaces of the indices are similar to ordinary collections (like arrays, maps and sets).
Each index occupies a certain set of keys in a single column family of the Database
.
On the other hand, multiple indices can be stored in the same column family, provided
that their key spaces do not intersect. Isolation is commonly achieved with the help
of prefixes; see with_prefix
constructor in the built-in index types.
Merkelized indices can generate cryptographic proofs about inclusion of entries. Having such a proof, an external client may verify locally that the received data was authorized by the blockchain validators without having to replicate the entire blockchain contents.
Exonum provides the following index types:
Entry
is a specific index that stores only one value. Useful for global values, such as configuration. Similar to a combination ofBox
andOption
.ListIndex
is a list of items stored in the sequential order. Similar toVec
.SparseListIndex
is a list of items stored in the sequential order. Similar toListIndex
, but may contain indices without elements.MapIndex
is a map of keys and values. Similar toBTreeMap
.ProofListIndex
is a Merkelized version ofListIndex
that supports cryptographic proofs of existence and is implemented as a Merkle tree.ProofMapIndex
is a Merkelized version ofMapIndex
that supports cryptographic proofs of existence and is implemented as a binary Merkle Patricia tree.KeySetIndex
andValueSetIndex
is a set of items, similar toBTreeSet
andHashSet
.
To implement a new index type, you should create a wrapper around BaseIndex
.
Re-exports
pub use self::base_index::BaseIndex; |
pub use self::base_index::BaseIndexIter; |
pub use self::map_index::MapIndex; |
pub use self::list_index::ListIndex; |
pub use self::sparse_list_index::SparseListIndex; |
pub use self::key_set_index::KeySetIndex; |
pub use self::value_set_index::ValueSetIndex; |
pub use self::proof_list_index::ProofListIndex; |
pub use self::proof_map_index::ProofMapIndex; |
Modules
base_index |
An implementation of base index with most common features. |
key_set_index |
An implementation of set for items that implement |
list_index |
An implementation of array list of items. |
map_index |
An implementation of key-value map. |
proof_list_index |
An implementation of a Merkelized version of an array list (Merkle tree). |
proof_map_index |
An implementation of a Merkelized version of a map (Merkle Patricia tree). |
sparse_list_index |
An implementation of array list of items with spaces. |
value_set_index |
An implementation of set for items that implement |
Structs
Changes |
Map containing changes with corresponding key. |
ChangesIterator |
Iterator over the |
Entry |
An index that may only contain one element. |
Error |
The error type for I/O operations with storage. |
Fork |
A combination of a database snapshot and a sequence of changes on top of it. |
MemoryDB |
Database implementation that stores all the data in memory. |
Patch |
A set of serial changes that should be applied to a storage atomically. |
PatchIterator |
Iterator over the |
RocksDB |
Database implementation on the top of |
RocksDBOptions |
Database-wide options around performance and behavior. |
Enums
Change |
An enum that represents a kind of change to some key in the storage. |
ListProof |
An enum that represents a proof of existence for a proof list elements. |
MapProof |
An enum that represents a proof of existence or non-existence for a proof map key. |
Traits
Database |
Low-level storage backend implementing a collection of named key-value stores (aka column families). |
Iterator |
A trait that defines streaming iterator over storage view entries. |
Snapshot |
A read-only snapshot of a storage backend. |
StorageKey |
A type that can be (de)serialized as a key in the blockchain storage. |
StorageValue |
A type that can be (de)serialized as a value in the blockchain storage. |
Type Definitions
Iter |
A generalized iterator over the storage views. |
Result |
A specialized |