Struct Db 

pub struct Db<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, M: MerkleizationState<DigestOf<H>> = Merkleized<H>, D: DurabilityState = Durable> { /* private fields */ }

A key-value QMDB based on an MMR over its log of operations, supporting key exclusion proofs and authentication of whether a currently has a specific value.

Note: The generic parameter N is not really generic, and must be manually set to double the size of the hash digest being produced by the hasher. A compile-time assertion is used to prevent any other setting.

Implementations

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, M: MerkleizationState<DigestOf<H>>, D: DurabilityState> Db<E, K, V, H, T, N, M, D>

pub fn op_count(&self) -> Location

The number of operations that have been applied to this db, including those that have been pruned and those that are not yet committed.

pub const fn inactivity_floor_loc(&self) -> Location

Return the inactivity floor location. This is the location before which all operations are known to be inactive. Operations before this point can be safely pruned.

pub async fn get(&self, key: &K) -> Result<Option<V>, Error>

Get the value of key in the db, or None if it has no value.

pub async fn get_metadata(&self) -> Result<Option<V>, Error>

Get the metadata associated with the last commit.

pub const fn is_empty(&self) -> bool

Whether the db currently has no active keys.

pub fn verify_key_value_proof( hasher: &mut H, key: K, value: V, proof: &KeyValueProof<K, H::Digest, N>, root: &H::Digest, ) -> bool

Return true if the proof authenticates that key currently has value value in the db with the provided root.

pub async fn get_span( &self, key: &K, ) -> Result<Option<(Location, Update<K, V>)>, Error>

Get the operation that currently defines the span whose range contains key, or None if the DB is empty.

pub async fn stream_range<'a>( &'a self, start: K, ) -> Result<impl Stream<Item = Result<(K, V), Error>> + 'a, Error>

Streams all active (key, value) pairs in the database in key order, starting from the first active key greater than or equal to start.

pub fn verify_exclusion_proof( hasher: &mut H, key: &K, proof: &ExclusionProof<K, V, H::Digest, N>, root: &H::Digest, ) -> bool

Return true if the proof authenticates that key does not exist in the db with the provided root.

pub fn verify_range_proof( hasher: &mut H, proof: &RangeProof<H::Digest>, start_loc: Location, ops: &[Operation<K, V>], chunks: &[[u8; N]], root: &H::Digest, ) -> bool

Return true if the given sequence of ops were applied starting at location start_loc in the log with the provided root.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> Db<E, K, V, H, T, N, Merkleized<H>, Durable>

pub async fn init(context: E, config: Config<T>) -> Result<Self, Error>

Initializes a Db from the given config. Leverages parallel Merkleization to initialize the bitmap MMR if a thread pool is provided.

pub const fn root(&self) -> H::Digest

Return the cached root of the db.

pub async fn sync(&mut self) -> Result<(), Error>

Sync all database state to disk.

pub async fn destroy(self) -> Result<(), Error>

Destroy the db, removing all data from disk.

pub fn into_mutable(self) -> Db<E, K, V, H, T, N, Unmerkleized, NonDurable>

Transition into the mutable state.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, D: State> Db<E, K, V, H, T, N, Merkleized<H>, D>

pub async fn range_proof( &self, hasher: &mut H, start_loc: Location, max_ops: NonZeroU64, ) -> Result<(RangeProof<H::Digest>, Vec<Operation<K, V>>, Vec<[u8; N]>), Error>

Returns a proof that the specified range of operations are part of the database, along with the operations from the range. A truncated range (from hitting the max) can be detected by looking at the length of the returned operations vector. Also returns the bitmap chunks required to verify the proof.

Errors

Returns crate::mmr::Error::LocationOverflow if start_loc > crate::mmr::MAX_LOCATION. Returns crate::mmr::Error::RangeOutOfBounds if start_loc >= number of leaves in the MMR.

pub async fn key_value_proof( &self, hasher: &mut H, key: K, ) -> Result<KeyValueProof<K, H::Digest, N>, Error>

Generate and return a proof of the current value of key, along with the other KeyValueProof required to verify the proof. Returns KeyNotFound error if the key is not currently assigned any value.

Errors

Returns Error::KeyNotFound if the key is not currently assigned any value.

pub async fn exclusion_proof( &self, hasher: &mut H, key: &K, ) -> Result<ExclusionProof<K, V, H::Digest, N>, Error>

Generate and return a proof that the specified key does not exist in the db.

Errors

Returns Error::KeyExists if the key exists in the db.

pub async fn prune(&mut self, prune_loc: Location) -> Result<(), Error>

Prune historical operations prior to prune_loc. This does not affect the db’s root or current snapshot.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> Db<E, K, V, H, T, N, Unmerkleized, NonDurable>

pub async fn update(&mut self, key: K, value: V) -> Result<(), Error>

Updates key to have value value. The operation is reflected in the snapshot, but will be subject to rollback until the next successful commit.

pub async fn create(&mut self, key: K, value: V) -> Result<bool, Error>

Creates a new key-value pair in the db. The operation is reflected in the snapshot, but will be subject to rollback until the next successful commit. Returns true if the key was created, false if it already existed.

pub async fn delete(&mut self, key: K) -> Result<bool, Error>

Delete key and its value from the db. Deleting a key that already has no value is a no-op. The operation is reflected in the snapshot, but will be subject to rollback until the next successful commit. Returns true if the key was deleted, false if it was already inactive.

pub async fn commit( self, metadata: Option<V>, ) -> Result<(Db<E, K, V, H, T, N, Unmerkleized, Durable>, Range<Location>), Error>

Commit any pending operations to the database, ensuring their durability upon return. This transitions to the Durable state without merkleizing. Returns the committed database and the [start_loc, end_loc) range of committed operations. Note that even if no operations were added since the last commit, this is a root-state changing operation.

pub async fn into_merkleized( self, ) -> Result<Db<E, K, V, H, T, N, Merkleized<H>, NonDurable>, Error>

Merkleize the database and transition to the provable state without committing. This enables proof generation while keeping the database in the non-durable state.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> Db<E, K, V, H, T, N, Merkleized<H>, NonDurable>

pub fn into_mutable(self) -> Db<E, K, V, H, T, N, Unmerkleized, NonDurable>

Transition into the mutable state.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> Db<E, K, V, H, T, N, Unmerkleized, Durable>

pub async fn into_merkleized( self, ) -> Result<Db<E, K, V, H, T, N, Merkleized<H>, Durable>, Error>

Merkleize the database, transitioning to the provable state.

pub fn into_mutable(self) -> Db<E, K, V, H, T, N, Unmerkleized, NonDurable>

Transition into the mutable state.

Trait Implementations

impl<E, K, V, T, H, const N: usize> Batchable for Db<E, K, V, H, T, N, Unmerkleized, NonDurable>

where E: RStorage + Clock + Metrics, K: Array, V: FixedValue, T: Translator, H: Hasher,

async fn write_batch<'a, Iter>(&'a mut self, iter: Iter) -> Result<(), Error>

where Iter: Iterator<Item = (K, Option<V>)> + Send + 'a,

Writes a batch of changes to the store.

fn start_batch(&self) -> Batch<'_, Self::Key, Self::Value, Self>

where Self: Sized + Sync, Self::Value: Send + Sync,

Returns a new empty batch of changes.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> Deletable for Db<E, K, V, H, T, N, Unmerkleized, NonDurable>

async fn delete(&mut self, key: Self::Key) -> Result<bool, Self::Error>

Delete the value of a key.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, M: MerkleizationState<DigestOf<H>>, D: DurabilityState> Gettable for Db<E, K, V, H, T, N, M, D>

type Key = K

type Value = V

type Error = Error

async fn get(&self, key: &Self::Key) -> Result<Option<Self::Value>, Self::Error>

Get the value of a key.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, M: MerkleizationState<DigestOf<H>>, D: DurabilityState> LogStore for Db<E, K, V, H, T, N, M, D>

type Value = V

fn op_count(&self) -> Location

The number of operations that have been applied to this db, including those that have been pruned and those that are not yet committed.

fn inactivity_floor_loc(&self) -> Location

Return the inactivity floor location. This is the location before which all operations are known to be inactive. Operations before this point can be safely pruned.

async fn get_metadata(&self) -> Result<Option<V>, Error>

Get the metadata associated with the last commit.

fn is_empty(&self) -> bool

Returns true if there are no active keys in the database.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, D: State> MerkleizedStore for Db<E, K, V, H, T, N, Merkleized<H>, D>

type Digest = <H as Hasher>::Digest

The digest type used for authentication.

type Operation = Operation<K, FixedEncoding<V>, Update<K, FixedEncoding<V>>>

The operation type stored in the log.

fn root(&self) -> Self::Digest

Returns the root digest of the authenticated store.

async fn historical_proof( &self, historical_size: Location, start_loc: Location, max_ops: NonZeroU64, ) -> Result<(Proof<Self::Digest>, Vec<Self::Operation>), Error>

Generate and return:

fn proof( &self, start_loc: Location, max_ops: NonZeroU64, ) -> impl Future<Output = Result<(Proof<Self::Digest>, Vec<Self::Operation>), Error>> + Send

Generate and return:

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> Persistable for Db<E, K, V, H, T, N, Merkleized<H>, Durable>

type Error = Error

The error type returned when there is a failure from the underlying storage system.

async fn commit(&mut self) -> Result<(), Self::Error>

Durably persist the structure, guaranteeing the current state will survive a crash.

async fn sync(&mut self) -> Result<(), Self::Error>

Durably persist the structure, guaranteeing the current state will survive a crash, and that no recovery will be needed on startup.

async fn destroy(self) -> Result<(), Self::Error>

Destroy the structure, removing all associated storage.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, D: DurabilityState> PrunableStore for Db<E, K, V, H, T, N, Merkleized<H>, D>

async fn prune(&mut self, prune_loc: Location) -> Result<(), Error>

Prune historical operations prior to loc.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> Updatable for Db<E, K, V, H, T, N, Unmerkleized, NonDurable>

async fn update( &mut self, key: Self::Key, value: Self::Value, ) -> Result<(), Self::Error>

Update the value of a key.

fn create<'a>( &'a mut self, key: Self::Key, value: Self::Value, ) -> impl Future<Output = Result<bool, Self::Error>> + Send + use<'a, Self>

where Self: Send,

Creates a new key-value pair in the db. Returns true if the key was created, false if it already existed. The key is not modified if it already existed.

fn upsert<'a, F>( &'a mut self, key: Self::Key, update: F, ) -> impl Future<Output = Result<(), Self::Error>> + Send + use<'a, Self, F>

where Self: Send, Self::Value: Default, F: FnOnce(&mut Self::Value) + Send + 'a,

Updates the value associated with the given key in the store, inserting a default value if the key does not already exist.