Struct Db 

pub struct Db<F: Graftable, E: Context, C: Contiguous<Item: CodecShared>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, U: Send + Sync, const N: usize, S: Strategy> { /* private fields */ }

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

Implementations

impl<F, E, C, I, H, U, const N: usize, S> Db<F, E, C, I, H, U, N, S>

where F: Graftable, E: Context, U: Update + Send + Sync, C: Contiguous<Item = Operation<F, U>>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, S: Strategy, Operation<F, U>: Codec,

pub fn to_batch(&self) -> Arc<MerkleizedBatch<F, H::Digest, U, N, S>>

Create an initial MerkleizedBatch from the current committed DB state.

The returned batch is rooted at the current committed prefix, but it is not a persistent snapshot across later divergent commits. If some other branch is applied afterward, this batch is no longer valid and must not be read through, extended, or applied.

impl<F, E, C, I, H, U, const N: usize, S> Db<F, E, C, I, H, U, N, S>

where F: Graftable, E: Context, U: Update, C: Contiguous<Item = Operation<F, U>>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, S: Strategy, Operation<F, U>: Codec,

pub const fn is_empty(&self) -> bool

Whether the snapshot currently has no active keys.

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

Get the metadata associated with the last commit.

pub async fn bounds(&self) -> Range<Location<F>>

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

pub fn verify_range_proof( hasher: &StandardHasher<H>, proof: &RangeProof<F, H::Digest>, start_loc: Location<F>, ops: &[Operation<F, U>], 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, having the activity status described by chunks.

impl<F, E, U, C, I, H, const N: usize, S> Db<F, E, C, I, H, U, N, S>

where F: Graftable, E: Context, U: Update, C: Contiguous<Item = Operation<F, U>>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, S: Strategy, Operation<F, U>: Codec,

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

Returns the canonical root. See the Root structure section in the module documentation.

pub const fn strategy(&self) -> &S

Return a reference to the merkleization strategy.

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

Returns the ops tree root.

This is the root of the raw operations log, without the activity bitmap. It is used as the sync target because the sync engine verifies batches against the ops root, not the canonical root.

External consumers that receive a trusted canonical current root should use Self::ops_root_witness to authenticate this ops root against it.

See the Root structure section in the module documentation.

pub async fn ops_root_witness( &self, hasher: &StandardHasher<H>, ) -> Result<OpsRootWitness<F, H::Digest>, Error<F>>

Returns a witness that this database’s canonical root commits to its ops root.

This can be used to authenticate an ops root against a trusted canonical current root.

pub fn new_batch(&self) -> UnmerkleizedBatch<F, H, U, N, S>

Create a new speculative batch of operations with this database as its parent.

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

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 Error::OperationPruned if start_loc falls in a pruned bitmap chunk. Returns crate::merkle::Error::LocationOverflow if start_loc > crate::merkle::Family::MAX_LEAVES. Returns crate::merkle::Error::RangeOutOfBounds if start_loc >= number of leaves in the tree.

impl<F, E, U, C, I, H, const N: usize, S> Db<F, E, C, I, H, U, N, S>

where F: Graftable, E: Context, U: Update, C: Mutable<Item = Operation<F, U>>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, S: Strategy, Operation<F, U>: Codec,

pub async fn ops_historical_proof( &self, historical_size: Location<F>, start_loc: Location<F>, max_ops: NonZeroU64, ) -> Result<(Proof<F, H::Digest>, Vec<Operation<F, U>>), Error<F>>

Returns an ops-level historical proof for the specified range.

Unlike range_proof which returns grafted proofs incorporating the activity bitmap, this returns ops-tree Merkle proofs suitable for state sync. Direct verifiers should use crate::qmdb::hasher.

pub async fn pinned_nodes_at( &self, loc: Location<F>, ) -> Result<Vec<H::Digest>, Error<F>>

Return the pinned nodes for a lower operation boundary of loc.

pub fn sync_boundary(&self) -> Location<F>

Returns the most recent location from which this database can safely be synced, and the upper bound on Self::prune’s prune_loc.

Callers constructing a sync Target may use this value, or any earlier retained location, as range.start. Values above this boundary are unsafe: the receiver’s grafted-pin derivation requires absorption-settled state for every fully pruned chunk, which this value guarantees.

Computation

Starts from the inactivity floor (the most chunks we could possibly prune) and walks backward until two conditions hold for the youngest chunk that would be pruned:

1. Settled: the chunk’s ops subtree root at height gh has been born in the ops tree (its peak_birth_size <= ops_leaves).

2. Absorbed: the chunk-pair parent at height gh+1 has been born. This guarantees that the ops tree has no individual height-gh peaks for pruned chunks, so compute_grafted_root never queries a discarded grafted leaf.

Because older chunk-pairs have strictly earlier birth times, checking only the youngest pair is sufficient: if the youngest pair’s parent is born, all older pairs’ parents are too. In the worst case the loop decrements twice (once past the unsettled chunk, once to land on the older pair boundary).

For families without delayed merges (e.g. MMR), peak_birth_size at height gh equals the chunk’s last leaf, so condition (1) always holds and the function returns the inactivity floor rounded down to the nearest chunk boundary.

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

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

prune_loc must be at most Self::sync_boundary: the ops log’s lower bound must not advance past the point where the grafting overlay has been pruned. The bitmap and grafted tree advance to the sync boundary regardless of prune_loc.

Errors

• Returns Error::PruneBeyondMinRequired if prune_loc > Self::sync_boundary.
• Returns crate::merkle::Error::LocationOverflow if prune_loc > crate::merkle::Family::MAX_LEAVES.
• Returns Error::DataCorrupted if internal grafted-tree state is inconsistent (a pinned or retained node is missing, or the prune location overflows a Position).

pub async fn rewind(&mut self, size: Location<F>) -> Result<(), Error<F>>

Rewind the database to size operations, where size is the location of the next append.

This rewinds the underlying Any database and rebuilds the Current overlay state (bitmap, grafted tree, and canonical root) for the rewound size.

Errors

Returns an error when:

• size is not a valid rewind target
• the target’s required logical range is not fully retained (for Current, this includes the underlying Any inactivity-floor boundary and bitmap pruning boundary)
• size - 1 is not a commit operation
• size is below the bitmap pruning boundary

Any error from this method is fatal for this handle. Rewind may mutate state in the underlying Any database before this Current overlay finishes rebuilding. Callers must drop this database handle after any Err from rewind and reopen from storage.

A successful rewind is not restart-stable until a subsequent Db::commit or Db::sync.

impl<F, E, U, C, I, H, const N: usize, S> Db<F, E, C, I, H, U, N, S>

where F: Graftable, E: Context, U: Update, C: Mutable<Item = Operation<F, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, S: Strategy, Operation<F, U>: Codec,

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

Durably commit the journal state published by prior Db::apply_batch calls.

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

Sync all database state to disk.

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

Destroy the db, removing all data from disk.

impl<F, E, U, C, I, H, const N: usize, S> Db<F, E, C, I, H, U, N, S>

where F: Graftable, E: Context, U: Update + 'static, C: Mutable<Item = Operation<F, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, S: Strategy, Operation<F, U>: Codec,

pub async fn apply_batch( &mut self, batch: Arc<MerkleizedBatch<F, H::Digest, U, N, S>>, ) -> Result<Range<Location<F>>, Error<F>>

Apply a batch to the database, returning the range of written operations.

A batch is valid only if every batch applied to the database since this batch’s ancestor chain was created is an ancestor of this batch. Applying a batch from a different fork returns Error::StaleBatch.

This publishes the batch to the in-memory Current view and appends it to the journal, but does not durably persist it. Call Db::commit or Db::sync to guarantee durability.

impl<F: Graftable, E: Context, C: Contiguous<Item = Operation<F, K, V>>, K: Key, V: ValueEncoding, I: OrderedIndex<Value = Location<F>>, H: Hasher, const N: usize, S: Strategy> Db<F, E, C, I, H, Update<K, V>, N, S>

where Operation<F, K, V>: Codec,

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

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

pub fn verify_key_value_proof( hasher: &StandardHasher<H>, key: K, value: V::Value, proof: &KeyValueProof<F, 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<F>, Update<K, V>)>, Error<F>>

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<F>>> + 'a, Error<F>>

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: &StandardHasher<H>, key: &K, proof: &ExclusionProof<F, 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<F: Graftable, E: Context, C: Mutable<Item = Operation<F, K, V>>, K: Key, V: ValueEncoding, I: OrderedIndex<Value = Location<F>>, H: Hasher, const N: usize, S: Strategy> Db<F, E, C, I, H, Update<K, V>, N, S>

where Operation<F, K, V>: Codec,

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

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: &StandardHasher<H>, key: &K, ) -> Result<ExclusionProof<F, K, V, H::Digest, N>, Error<F>>

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<F: Graftable, E: Context, K: Array, V: FixedValue, H: Hasher, T: Translator, const P: usize, const N: usize, S: Strategy> Db<F, E, Journal<E, Operation<F, Update<K, FixedEncoding<V>>>>, Index<T, Location<F>, P>, H, Update<K, FixedEncoding<V>>, N, S>

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

Initializes a Db authenticated database from the given config. The configured Strategy is used to parallelize merkleization.

impl<F: Graftable, E: Context, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, S: Strategy> Db<F, E, Journal<E, Operation<F, Update<K, FixedEncoding<V>>>>, Index<T, Location<F>>, H, Update<K, FixedEncoding<V>>, N, S>

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

Initializes a Db from the given config. The configured Strategy is used to parallelize merkleization.

impl<F: Graftable, E: Context, K: Key, V: VariableValue, H: Hasher, T: Translator, const P: usize, const N: usize, S: Strategy> Db<F, E, Journal<E, Operation<F, Update<K, VariableEncoding<V>>>>, Index<T, Location<F>, P>, H, Update<K, VariableEncoding<V>>, N, S>

where Operation<F, K, V>: Codec,

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

Initializes a Db from the given config. The configured Strategy is used to parallelize merkleization.

impl<F: Graftable, E: Context, K: Key, V: VariableValue, H: Hasher, T: Translator, const N: usize, S: Strategy> Db<F, E, Journal<E, Operation<F, Update<K, VariableEncoding<V>>>>, Index<T, Location<F>>, H, Update<K, VariableEncoding<V>>, N, S>

where Operation<F, K, V>: Codec,

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

Initializes a Db from the given config. The configured Strategy is used to parallelize merkleization.

impl<F: Graftable, E: Context, C: Contiguous<Item = Operation<F, K, V>>, K: Array, V: ValueEncoding, I: UnorderedIndex<Value = Location<F>>, H: Hasher, const N: usize, S: Strategy> Db<F, E, C, I, H, Update<K, V>, N, S>

where Operation<F, K, V>: Codec,

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

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

pub fn verify_key_value_proof( hasher: &StandardHasher<H>, key: K, value: V::Value, proof: &KeyValueProof<F, 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<F: Graftable, E: Context, C: Mutable<Item = Operation<F, K, V>>, K: Array, V: ValueEncoding, I: UnorderedIndex<Value = Location<F>>, H: Hasher, const N: usize, S: Strategy> Db<F, E, C, I, H, Update<K, V>, N, S>

where Operation<F, K, V>: Codec,

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

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<F: Graftable, E: Context, K: Array, V: FixedValue, H: Hasher, T: Translator, const P: usize, const N: usize, S: Strategy> Db<F, E, Journal<E, Operation<F, Update<K, FixedEncoding<V>>>>, Index<T, Location<F>, P>, H, Update<K, FixedEncoding<V>>, N, S>

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

Initializes a Db authenticated database from the given config. The configured Strategy is used to parallelize merkleization.

impl<F: Graftable, E: Context, K: Array, V: FixedValue, H: Hasher, T: Translator, const N: usize, S: Strategy> Db<F, E, Journal<E, Operation<F, Update<K, FixedEncoding<V>>>>, Index<T, Location<F>>, H, Update<K, FixedEncoding<V>>, N, S>

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

Initializes a Db authenticated database from the given config. The configured Strategy is used to parallelize merkleization.

impl<F: Graftable, E: Context, K: Array, V: VariableValue, H: Hasher, T: Translator, const P: usize, const N: usize, S: Strategy> Db<F, E, Journal<E, Operation<F, Update<K, VariableEncoding<V>>>>, Index<T, Location<F>, P>, H, Update<K, VariableEncoding<V>>, N, S>

where Operation<F, K, V>: Read,

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

Initializes a Db from the given config. The configured Strategy is used to parallelize merkleization.

impl<F: Graftable, E: Context, K: Array, V: VariableValue, H: Hasher, T: Translator, const N: usize, S: Strategy> Db<F, E, Journal<E, Operation<F, Update<K, VariableEncoding<V>>>>, Index<T, Location<F>>, H, Update<K, VariableEncoding<V>>, N, S>

where Operation<F, K, V>: Read,

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

Initializes a Db from the given config. The configured Strategy is used to parallelize merkleization.

Trait Implementations

impl<F, E, U, C, I, H, const N: usize, S> Persistable for Db<F, E, C, I, H, U, N, S>

where F: Graftable, E: Context, U: Update, C: Mutable<Item = Operation<F, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, S: Strategy, Operation<F, U>: Codec,

type Error = Error<F>

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

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

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

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

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<F>>

Destroy the structure, removing all associated storage.