[][src]Crate exonum_merkledb

A module that provides interfaces to work with persisted blockchain data.

See also the documentation page on storage.


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 TemporaryDB.

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 creating a sequence of changes to the database that are specified as a Patch. A patch can be atomically merged into a database. Different threads may call merge concurrently.

BinaryKey and BinaryValue traits

If you need to use your own data types as keys or values in the storage, you need to implement the BinaryKey or BinaryValue traits respectively. These traits have already been implemented for most standard types.


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 column families; see new_in_family 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 of Box and Option.
  • ListIndex is a list of items stored in a sequential order. Similar to Vec.
  • SparseListIndex is a list of items stored in a sequential order. Similar to ListIndex, but may contain indices without elements.
  • MapIndex is a map of keys and values. Similar to BTreeMap.
  • ProofListIndex is a Merkelized version of ListIndex that supports cryptographic proofs of existence and is implemented as a Merkle tree.
  • ProofMapIndex is a Merkelized version of MapIndex that supports cryptographic proofs of existence and is implemented as a binary Merkle Patricia tree.
  • KeySetIndex and ValueSetIndex are sets of items, similar to BTreeSet and HashSet accordingly.


pub use self::proof_map_index::MapProof;
pub use self::proof_map_index::ProofMapIndex;
pub use self::key_set_index::KeySetIndex;
pub use self::list_index::ListIndex;
pub use self::map_index::MapIndex;
pub use self::proof_list_index::ProofListIndex;
pub use self::sparse_list_index::SparseListIndex;
pub use self::value_set_index::ValueSetIndex;



An implementation of a set for items that utilize the BinaryKey trait.


An implementation of an array list of items.


An implementation of a key-value map.


An implementation of a Merkelized version of an array list (Merkle tree).


An implementation of a Merkelized version of a map (Merkle Patricia tree).


An implementation of an array list of items with spaces.


An implementation of a set of items that utilize the BinaryValue trait.



Implement ObjectHash trait for any type that implements BinaryValue.



Map containing changes with a corresponding key.


Iterator over the Changes data.


Options for the database.


An index that may only contain one element.


The error type for I/O operations with storage.


A combination of a database snapshot and a sequence of changes on top of it.


Represents address of the index in the database.


Struct responsible for creating view and state for index with specified address. View contains changes, state contains metadata.


A set of serial changes that should be applied to a storage atomically.


Iterator over the Patch data.


Encapsulates a proof of absence for ProofListIndex.


Utility trait to provide immutable references to MerkleDB objects. Similar to core::cell::Ref, but with Deref implementation.


Utility trait to provide mutable references to MerkleDB objects.


Database implementation on top of RocksDB backend.


Wrapper over the RocksDB backend which stores data in the temporary directory using the tempfile crate.


Represents current view of the database by specified address and changes that took place after that view had been created. View implementation provides an interface to work with related changes.



An enum that represents a type of change made to some key in the storage.


MerkleDB hash prefixes.


An enum that represents a proof of existence for a proof list elements.



A type that can be (de)serialized as a key in the blockchain storage.


A type that can be (de)serialized as a value in the blockchain storage.


Low-level storage backend implementing a collection of named key-value stores (aka column families).


Base trait that allows to access and modify indexes.


A trait that defines a streaming iterator over storage view entries. Unlike the standard Iterator trait, Iterator in Exonum is low-level and, therefore, operates with bytes.


Trait used to obtain references to database objects.


A common trait for the ability to compute a unique hash.


A read-only snapshot of a storage backend.



Computes a Merkle root hash for a the given list of hashes.

Type Definitions


A generalized iterator over the storage views.


A specialized Result type for I/O operations with storage.