Module exonum::storage

A module that provides a high-level interface for working with stored data.

Database

A Database is the underlying type for working with stored data. Internally Database is a key-value storage with reading isolation and atomic writing. This is an embedded database, which means that only the Exonum process can access it. You can interact with a Database from different threads by cloning its instance.

Exonum provides two types of database: LevelDB and MemoryDB. However, you can make your own implementations of Database trait. See its documentation for more.

Snapshot and Fork

There is no way to directly interact with data in the database.

If you need to read the data, you can create a Snapshot using method snapshot of the Database instance. Snapshots provide a 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 &Storage is used as a storage view for creating read-only indices representation.

If you need to make any changes to the data, you need to create a Fork using method fork of the Database instance. As well as Snapshot, Fork provides read isolation and also allows you to create a sequence of changes to the database that are specified as Patch. Later you can atomically merge a patch into the database using method merge.

StorageKey and StorageValue traits

If you need to use your own data types as keys or values in storage, you need to implement the StorageKey or StorageValue traits respectively. These traits are already implemented for most standard types. See their documentation for more.

Indices

Indexes are structures that represent high-level data collections that are stored in a database. This concept is similar to tables in relational databases. All indexes are stored in a single key-value table, but internally the keys of each index will be prefixed with the unique index prefixes, so the data of the different indexes do not conflict with each other. The interfaces of the indexes are similar to ordinary collections (like arrays, maps and sets), but their data is located in persistent storage.

Merklized indices support the ability to generate the cryptographic proofs about the inclusion of data in them. Having such proof external client may verify locally that received data was really authorized by the validators without having to replicate the entire blockchain contents.

Exonum implements the following indices:

• Entry is a specific index that stores only one value. Useful for global values, such as configuration. Similar to combination of Box and Option from standard library.
• ListIndex is a list of items stored in sequential order. Similar to Vec collection from standard library.
• MapIndex is a map of keys and values. Similar to BTreeMap collection from standard library.
• ProofListIndex is a Merklized version of ListIndex which supports the cryptographic proofs of existence and is implemented as a Merkle tree.
• ProofMapIndex is a Merklized version of MapIndex which supports the cryptographic proofs of existence and is implemented as a Merkle Patricia tree.
• KeySetIndex and ValueSetIndex is a set of items, similar to BTreeSet and HashSet from standard library.

If necessary, it's possible to implement new specific types of indexes. To do this, you need to create a wrapper over BaseIndex structure. See their documentation for more.

Reexports

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::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 StorageKey trait.
list_index	An implementation of array list of items.
map_index	An implementation of key-value map.
proof_list_index	An implementation of a Merklized version of an array list (Merkle tree).
proof_map_index	An implementation of a Merklized version of a map (Merkle Patricia tree).
value_set_index	An implementation of set for items that implement StorageValue trait.

Structs

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.
LevelDB	Database implementation on the top of LevelDB backend.
LevelDBCache	Represents a leveldb cache
LevelDBOptions	Options to consider when opening a new or pre-existing database.
MemoryDB	Database implementation that stores all the data in memory.

Enums

Change	An enum that represents a kind of change to some key in 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	A trait that defines a low-level storage backend.
Iterator	A trait that defines streaming iterator over storage view entries.
Snapshot	A trait that defines a snapshot of storage backend.
StorageKey	A trait that defines serialization of corresponding types as storage keys.
StorageValue	A trait that defines serialization of corresponding types as storage values.

Type Definitions

Iter	A generalized iterator over the storage views.
Patch	A set of serial changes that should be applied to a storage atomically.
Result	A specialized Result type for I/O operations with storage.