Struct Db 

pub struct Db<E: Storage + Clock + Metrics, C: Contiguous<Item: CodecShared>, I: UnorderedIndex<Value = Location>, H: Hasher, U: Send + Sync, const N: usize, S: State<DigestOf<H>> = Merkleized<DigestOf<H>>, D: DurabilityState = Durable> { /* private fields */ }

A Current QMDB implementation generic over ordered/unordered keys and variable/fixed values.

Implementations

impl<E, K, V, C, I, H, U, const N: usize, S, D> Db<E, C, I, H, U, N, S, D>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: Contiguous<Item = Operation<K, V, U>>, I: UnorderedIndex<Value = Location>, H: Hasher, S: State<DigestOf<H>>, D: DurabilityState, Operation<K, V, U>: Codec,

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 const fn is_empty(&self) -> bool

Whether the snapshot currently has no active keys.

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

Get the metadata associated with the last commit.

pub const fn grafting_height() -> u32

Get the level of the base MMR into which we are grafting.

This value is log2 of the chunk size in bits. Since we assume the chunk size is a power of 2, we compute this from trailing_zeros.

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

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 mmr::Error::LocationOverflow if start_loc > mmr::MAX_LOCATION. Returns mmr::Error::RangeOutOfBounds if start_loc >= number of leaves in the MMR. Return true if the given sequence of ops were applied starting at location start_loc in the log with the provided root.

impl<E, K, V, U, C, I, H, D, const N: usize> Db<E, C, I, H, U, N, Merkleized<DigestOf<H>>, D>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: MutableContiguous<Item = Operation<K, V, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location>, H: Hasher, D: DurabilityState, Operation<K, V, U>: Codec,

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

pub async fn range_proof( &self, hasher: &mut H, start_loc: Location, max_ops: NonZeroU64, ) -> Result<(RangeProof<H::Digest>, Vec<Operation<K, V, U>>, 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 mmr::Error::LocationOverflow if start_loc > mmr::MAX_LOCATION. Returns mmr::Error::RangeOutOfBounds if start_loc >= number of leaves in the MMR.

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

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

Errors

• Returns Error::PruneBeyondMinRequired if prune_loc > inactivity floor.
• Returns mmr::Error::LocationOverflow if prune_loc > mmr::MAX_LOCATION.

impl<E, K, V, U, C, I, H, const N: usize> Db<E, C, I, H, U, N, Merkleized<DigestOf<H>>, Durable>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: MutableContiguous<Item = Operation<K, V, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location>, H: Hasher, Operation<K, V, U>: Codec,

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, C, I, H, U, N, Unmerkleized, NonDurable>

Convert this database into a mutable state.

impl<E, K, V, U, C, I, H, const N: usize, D> Db<E, C, I, H, U, N, Unmerkleized, D>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: Contiguous<Item = Operation<K, V, U>>, I: UnorderedIndex<Value = Location>, H: Hasher, D: DurabilityState, Operation<K, V, U>: Codec,

pub async fn into_merkleized( self, ) -> Result<Db<E, C, I, H, U, N, Merkleized<DigestOf<H>>, D>, Error>

Merkleize the database and transition to the provable state.

impl<E, K, V, U, C, I, H, const N: usize> Db<E, C, I, H, U, N, Unmerkleized, Durable>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: Contiguous<Item = Operation<K, V, U>>, I: UnorderedIndex<Value = Location>, H: Hasher, Operation<K, V, U>: Codec,

pub fn into_mutable(self) -> Db<E, C, I, H, U, N, Unmerkleized, NonDurable>

Convert this database into a mutable state.

impl<E, K, V, U, C, I, H, const N: usize> Db<E, C, I, H, U, N, Unmerkleized, NonDurable>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: MutableContiguous<Item = Operation<K, V, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location>, H: Hasher, Operation<K, V, U>: Codec,

pub async fn commit( self, metadata: Option<V::Value>, ) -> Result<(Db<E, C, I, H, U, 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.

impl<E, K, V, U, C, I, H, const N: usize> Db<E, C, I, H, U, N, Merkleized<DigestOf<H>>, NonDurable>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: MutableContiguous<Item = Operation<K, V, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location>, H: Hasher, Operation<K, V, U>: Codec,

pub fn into_mutable(self) -> Db<E, C, I, H, U, N, Unmerkleized, NonDurable>

Convert this database into a mutable state.

impl<E: Storage + Clock + Metrics, C: Contiguous<Item = Operation<K, V>>, K: Array, V: ValueEncoding, H: Hasher, T: Translator, const N: usize, S: State<DigestOf<H>>, D: DurabilityState> Db<E, C, Index<T, Location>, H, Update<K, V>, N, S, D>

where Operation<K, V>: Codec, V::Value: Send + Sync,

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

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

pub fn verify_key_value_proof( hasher: &mut H, key: K, value: V::Value, 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::Value), Error>> + 'a, Error>

where V: 'a,

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.

impl<E: Storage + Clock + Metrics, C: MutableContiguous<Item = Operation<K, V>>, K: Array, V: ValueEncoding, H: Hasher, T: Translator, const N: usize, D: State> Db<E, C, Index<T, Location>, H, Update<K, V>, N, Merkleized<<H as Hasher>::Digest>, D>

where Operation<K, V>: Codec, V::Value: Send + Sync,

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.

impl<E: Storage + Clock + Metrics, C: MutableContiguous<Item = Operation<K, V>>, K: Array, V: ValueEncoding, H: Hasher, T: Translator, const N: usize> Db<E, C, Index<T, Location>, H, Update<K, V>, N, Unmerkleized, NonDurable>

where Operation<K, V>: Codec, V::Value: Send + Sync,

pub async fn update(&mut self, key: K, value: V::Value) -> 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::Value) -> 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.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> Db<E, Journal<E, Operation<K, FixedEncoding<V>, Update<K, FixedEncoding<V>>>>, Index<T, Location>, H, Update<K, FixedEncoding<V>>, N>

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.

impl<E: RStorage + Clock + Metrics, K: Array, V: VariableValue, H: Hasher, T: Translator, const N: usize> Db<E, Journal<E, Operation<K, VariableEncoding<V>, Update<K, VariableEncoding<V>>>>, Index<T, Location>, H, Update<K, VariableEncoding<V>>, N>

where Operation<K, V>: Read,

pub async fn init( context: E, config: Config<T, <Operation<K, V> as Read>::Cfg>, ) -> Result<Self, Error>

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

impl<E: Storage + Clock + Metrics, C: Contiguous<Item = Operation<K, V>>, K: Array, V: ValueEncoding, H: Hasher, T: Translator, const N: usize, S: State<DigestOf<H>>, D: DurabilityState> Db<E, C, Index<T, Location>, H, Update<K, V>, N, S, D>

where Operation<K, V>: Codec, V::Value: Send + Sync,

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

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

pub fn verify_key_value_proof( hasher: &mut H, key: K, value: V::Value, proof: &KeyValueProof<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.

impl<E: Storage + Clock + Metrics, C: MutableContiguous<Item = Operation<K, V>>, K: Array, V: ValueEncoding, H: Hasher, T: Translator, const N: usize, D: State> Db<E, C, Index<T, Location>, H, Update<K, V>, N, Merkleized<<H as Hasher>::Digest>, D>

where Operation<K, V>: Codec, V::Value: Send + Sync,

pub async fn key_value_proof( &self, hasher: &mut H, key: K, ) -> Result<KeyValueProof<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.

impl<E: Storage + Clock + Metrics, C: MutableContiguous<Item = Operation<K, V>>, K: Array, V: ValueEncoding, H: Hasher, T: Translator, const N: usize> Db<E, C, Index<T, Location>, H, Update<K, V>, N, Unmerkleized, NonDurable>

where Operation<K, V>: Codec, V::Value: Send + Sync,

pub async fn update(&mut self, key: K, value: V::Value) -> 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::Value) -> 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.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> Db<E, Journal<E, Operation<K, FixedEncoding<V>, Update<K, FixedEncoding<V>>>>, Index<T, Location>, H, Update<K, FixedEncoding<V>>, N>

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

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

impl<E: RStorage + Clock + Metrics, K: Array, V: VariableValue, H: Hasher, T: Translator, const N: usize> Db<E, Journal<E, Operation<K, VariableEncoding<V>, Update<K, VariableEncoding<V>>>>, Index<T, Location>, H, Update<K, VariableEncoding<V>>, N>

where Operation<K, V>: Read,

pub async fn init( context: E, config: Config<T, <Operation<K, V> as Read>::Cfg>, ) -> Result<Self, Error>

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

Trait Implementations

impl<E, K, V, U, C, I, H, const N: usize, S, D> LogStore for Db<E, C, I, H, U, N, S, D>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: Contiguous<Item = Operation<K, V, U>>, I: UnorderedIndex<Value = Location>, H: Hasher, S: State<DigestOf<H>>, D: DurabilityState, Operation<K, V, U>: Codec,

type Value = <V as ValueEncoding>::Value

fn bounds(&self) -> Range<Location>

Return [start, end) where start and end - 1 are the Locations of the oldest and newest retained operations respectively.

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::Value>, 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.

fn size(&self) -> Location

Return the Location of the next operation appended to this db.

impl<E, K, V, U, C, I, H, D, const N: usize> MerkleizedStore for Db<E, C, I, H, U, N, Merkleized<DigestOf<H>>, D>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: MutableContiguous<Item = Operation<K, V, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location>, H: Hasher, D: DurabilityState, Operation<K, V, U>: Codec,

type Digest = <H as Hasher>::Digest

The digest type used for authentication.

type Operation = Operation<K, V, U>

The operation type stored in the log.

fn root(&self) -> H::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, K, V, U, C, I, H, const N: usize> Persistable for Db<E, C, I, H, U, N, Merkleized<DigestOf<H>>, Durable>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: MutableContiguous<Item = Operation<K, V, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location>, H: Hasher, Operation<K, V, U>: Codec,

type Error = Error

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

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

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

async fn sync(&mut self) -> Result<(), 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<(), Error>

Destroy the structure, removing all associated storage.

impl<E, K, V, U, C, I, H, const N: usize, D> PrunableStore for Db<E, C, I, H, U, N, Merkleized<DigestOf<H>>, D>

where E: Storage + Clock + Metrics, K: Array, V: ValueEncoding, U: Update<K, V>, C: MutableContiguous<Item = Operation<K, V, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location>, H: Hasher, D: DurabilityState, Operation<K, V, U>: Codec,

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

Prune historical operations prior to loc.