Crate penumbra_storage

source ·
Expand description

Storage and management of chain state.

This crate provides a versioned, verifiable key-value store that also supports lightweight, copy-on-write snapshots and transactional semantics. The Storage type is a handle for an instance of a backing store, implemented using RocksDB. The storage records a sequence of versioned States. The State type is a lightweight snapshot of a particular version of the chain state.

Each State instance can also be used as a copy-on-write fork to build up changes before committing them to persistent storage. The StateTransaction type collects a group of writes, which can then be applied to the (in-memory) State fork. Finally, the changes accumulated in the State instance can be committed to the persistent Storage.

Reads are performed with the StateRead trait, implemented by both State and StateTransaction, and reflect any currently cached writes. Writes are performed with the StateWrite trait, which is only implemented for StateTransaction.

The storage system provides two data stores:

  • A verifiable key-value store, with UTF-8 keys and byte values, backed by the Jellyfish Merkle Tree. The JMT is a sparse merkle tree that records hashed keys, so we also record an index of the keys themselves to allow range queries on keys rather than key hashes. This index, however, is not part of the verifiable consensus state.

  • A secondary, non-verifiable key-value store with byte keys and byte values, backed directly by RocksDB. This is intended for use building application-specific indexes of the verifiable consensus state.

While the primary key-value store records byte values, it is intended for use with Protobuf-encoded data. To this end, the StateRead and StateWrite traits have provided methods that use the [penumbra_proto::Protobuf] trait to automatically (de)serialize into proto or domain types, allowing its use as an object store.


A snapshot of the underlying storage at a specific state version, suitable for read-only access by multiple threads, e.g., RPC calls.
A lightweight snapshot of a particular version of the chain state.
A notification of a new state version.
A set of pending changes to a State instance, supporting both writes and reads.
A handle for a storage instance, backed by RocksDB.
A Storage instance backed by a tempfile::TempDir for testing.


Extension trait providing try_begin_transaction() on Arc<State>.
Read access to chain state.
Write access to chain state.


Registers all metrics used by this crate.