Struct Db 

pub struct Db<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, S: State<DigestOf<H>> = Clean<DigestOf<H>>> { /* private fields */ }

A key-value QMDB based on an MMR over its log of operations, supporting authentication of whether a key ever had a specific value, and whether the key currently has that 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, S: State<DigestOf<H>>> Db<E, K, V, H, T, N, S>

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

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>

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.

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

Return the cached root of the db.

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<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 commit( &mut self, metadata: Option<V>, ) -> Result<Range<Location>, Error>

Commit any pending operations to the database, ensuring their durability upon return from this function. Also raises the inactivity floor according to the schedule. Returns the (start_loc, end_loc] location range of committed operations.

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

Sync all database state to disk.

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.

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

Close the db. Operations that have not been committed will be lost or rolled back on restart.

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

Destroy the db, removing all data from disk.

pub fn into_dirty(self) -> Db<E, K, V, H, T, N, Dirty>

Convert this clean database into its dirty counterpart for performing mutations.

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

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 merkleize( self, ) -> Result<Db<E, K, V, H, T, N, Clean<DigestOf<H>>>, Error>

Merkleize the bitmap and convert this dirty database into its clean counterpart. This computes the Merkle tree over any new bitmap entries but does NOT persist changes to storage. Use commit() for durable state transitions.

Trait Implementations

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

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

async fn write_batch( &mut self, iter: impl Iterator<Item = (K, Option<V>)>, ) -> Result<(), Error>

Writes a batch of changes to the database.

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

where Self: Sized,

Returns a new empty batch of changes.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> CleanAny for Db<E, K, V, H, T, N, Clean<DigestOf<H>>>

type Key = K

The key type for this database.

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

Get the value for a given key, or None if it has no value.

async fn commit( &mut self, metadata: Option<Self::Value>, ) -> Result<Range<Location>, Error>

Commit pending operations to the database, ensuring durability. Returns the location range of committed operations.

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

Sync all database state to disk.

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

Prune historical operations prior to prune_loc.

async fn close(self) -> Result<(), Error>

Close the db. Uncommitted operations will be lost or rolled back on restart.

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

Destroy the db, removing all data from disk.

impl<E: RStorage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize> CleanStore for Db<E, K, V, H, T, N, Clean<DigestOf<H>>>

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.

type Dirty = Db<E, K, V, H, T, N, Dirty>

The dirty state type that this clean store transitions to.

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

Returns the root digest of the authenticated store.

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

Generate and return:

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 into_dirty(self) -> Self::Dirty

Convert this clean store into its dirty counterpart for batched updates.

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

type Key = K

The key type for this database.

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

Get the value for a given key, or None if it has no value.

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

Update key to have value value. Subject to rollback until next commit.

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

Create a new key-value pair. Returns true if created, false if key already existed. Subject to rollback until next commit.

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

Delete key and its value. Returns true if deleted, false if already inactive. Subject to rollback until next commit.

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

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.

type Clean = Db<E, K, V, H, T, N>

The clean state type that this dirty store transitions to.

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

Merkleize the store and compute the root digest.

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

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> LogStorePrunable for Db<E, K, V, H, T, N>

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

Prune historical operations prior to prune_loc.

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

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> StoreDeletable for Db<E, K, V, H, T, N, Dirty>

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> StoreMut for Db<E, K, V, H, T, N, Dirty>

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

Update the value of a key.

fn upsert( &mut self, key: Self::Key, update: impl FnOnce(&mut Self::Value), ) -> impl Future<Output = Result<(), Self::Error>>

where Self::Value: Default,

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

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

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