Struct Immutable 

pub struct Immutable<F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable<Item = Operation<F, K, V>>, H: Hasher, T: Translator, S: Strategy>
where
    C::Item: EncodeShared,
{ /* private fields */ }

An authenticated database that only supports adding new keyed values (no updates or deletions).

Invariant

A key must be set at most once across the database history.

Use fixed::Db or variable::Db for concrete instantiations.

Implementations

impl<F, E, K, V, C, H, T, S> Immutable<F, E, K, V, C, H, T, S>

where F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable<Item = Operation<F, K, V>>, C::Item: EncodeShared, H: Hasher, T: Translator, S: Strategy,

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

Create an initial MerkleizedBatch from the DB’s current state.

impl<F, E, K, V, C, H, T, S> Immutable<F, E, K, V, C, H, T, S>

where F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable<Item = Operation<F, K, V>>, C::Item: EncodeShared, H: Hasher, T: Translator, S: Strategy,

pub async fn init( context: E, cfg: Config<T, C::Config, S>, max_size: Option<Location<F>>, ) -> Result<Self, Error<F>>

where C: Backing<E>,

Initialize from the latest retained commit, discarding every operation after it. Some(max_size) selects the latest retained commit with at most max_size operations. None selects the latest retained state.

pub const fn inactivity_floor_loc(&self) -> Location<F>

Return the inactivity floor location declared by the last committed batch.

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

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

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

Return the retained operation range [start, end).

Proof generation also requires the necessary Merkle nodes to be retained.

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

Return the most recent location from which this database can safely be synced, and the upper bound on Self::prune’s loc. For immutable databases, this equals the inactivity floor declared by the last committed batch.

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 or its corresponding operation has been pruned.

Unlike batch reads, this may return a value written below the inactivity floor, until the database prunes that operation or rebuilds its index from the floor on restart or sync.

pub async fn get_many( &self, keys: &[&K], ) -> Result<Vec<Option<V::Value>>, Error<F>>

Batch read multiple keys.

Returns results in the same order as the input keys. Like Self::get, this may return values written below the inactivity floor.

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

Get the metadata associated with the last commit.

pub async fn historical_proof( &self, op_count: Location<F>, start_loc: Location<F>, max_ops: NonZeroU64, ) -> Result<(Proof<F, H::Digest>, Vec<Operation<F, K, V>>), Error<F>>

Analogous to proof but with respect to the state of the database when it had op_count operations.

Contract

op_count must be a commit-boundary size: the operation at op_count - 1 must itself be a commit op. Non-commit-boundary sizes are not supported because the inactivity floor governing them is not directly retrievable.

Errors

Returns crate::merkle::Error::RangeOutOfBounds if op_count > number of operations, or if start_loc >= op_count. Returns Error::Journal with crate::journal::Error::ItemPruned or Error::Merkle with crate::merkle::Error::ElementPruned if a required operation or Merkle node has been pruned. Returns Error::HistoricalFloorPruned if op_count - 1 is retained but is not a commit op, either because the caller passed a non-commit-boundary op_count or because pruning removed the commit that would have governed op_count.

pub async fn proof( &self, start_index: Location<F>, max_ops: NonZeroU64, ) -> Result<(Proof<F, H::Digest>, Vec<Operation<F, K, V>>), Error<F>>

Generate and return:

1. a proof of all operations applied to the db in the range starting at (and including) location start_loc, and ending at the first of either:
   • the last operation performed, or
   • the operation max_ops from the start.
2. the operations corresponding to the leaves in this range.

pub async fn prune(self, loc: Location<F>) -> Result<Self, Error<F>>

Prune operations prior to loc without changing the db’s root. Keys whose operations are no longer retained cannot be retrieved.

The retained start in Self::bounds can remain below loc.

Pruning is irreversible and requires no prior commit. After a crash, the database remains recoverable; uncommitted operations are not guaranteed to survive.

Errors

• Returns Error::PruneBeyondMinRequired if loc > inactivity floor.

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

Return the canonical QMDB root of the db.

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

Return a reference to the merkleization strategy.

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

Return the pinned Merkle nodes at the given location.

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

Sync all database state to disk. While this isn’t necessary to ensure durability of committed operations, periodic invocation may reduce memory usage and the time required to recover the database on restart.

pub async fn start_sync(self) -> Result<(Self, Handle<()>), Error<F>>

Begin durably persisting the journal state published by prior Immutable::apply_batch calls.

Awaiting the returned Handle provides the same durability guarantee as Self::commit, plus a best-effort attempt to bound the recovery needed on startup. Use Self::sync to guarantee none is needed. A new sync waits for the prior sync before starting. Failures of the deferred durability work surface on the returned handle. A failed data sync also fails the next durability operation. A failed recovery-watermark sync is not observed by Self::commit, and a failed merkle-node sync may not be. Both resurface on the next Self::sync.

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

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

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

Destroy the db, removing all data from disk.

pub fn new_batch(&self) -> UnmerkleizedBatch<F, H, K, V, S>

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

pub fn validate_batch( &self, batch: &MerkleizedBatch<F, H::Digest, K, V, S>, ) -> Result<(), Error<F>>

Check that batch can be applied to the database in its current state, without applying it.

Self::apply_batch runs the same validation but consumes the database when it fails; callers that want to reject a bad batch and keep the handle can check first.

pub async fn apply_batch( self, batch: Arc<MerkleizedBatch<F, H::Digest, K, V, S>>, ) -> Result<Self, Error<F>>

Apply a batch::MerkleizedBatch to the database.

This publishes the batch to the in-memory database state and appends it to the journal. Call Immutable::commit or Immutable::sync, or await the handle returned by Immutable::start_sync, to make the applied state durable.

Errors

Returns Error::StaleBatch if the database is at neither the batch’s recorded database boundary nor an ancestor’s tip.

Trait Implementations

impl<F, E, K, V, C, H, T, S> Database for Immutable<F, E, K, V, C, H, T, S>

where F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable<Item = Operation<F, K, V>> + Journal<F, Context = E, Op = Operation<F, K, V>>, C::Item: EncodeShared, H: Hasher, T: Translator, S: Strategy,

async fn from_sync_result( context: Self::Context, db_config: Self::Config, log: Self::Journal, pinned_nodes: Option<Vec<Self::Digest>>, range: NonEmptyRange<Location<F>>, apply_batch_size: NonZeroU64, ) -> Result<Self, Error<F>>

Returns an Immutable initialized from data collected in the sync process.

Behavior

This method handles different initialization scenarios based on existing data:

• If the Merkle journal is empty or the last item is before the range start, it creates a fresh Merkle structure from the provided pinned_nodes
• If the Merkle journal has data but is incomplete (has length < range end), missing operations from the log are applied to bring it up to the target state
• If the Merkle journal has data beyond the range end, initialization truncates it to the sync target

Returns

A super::Immutable db populated with the state from the given range. Its inactivity floor comes from the final commit, while the Merkle pruning boundary is the range start.

type Family = F

type Op = Operation<F, K, V>

type Journal = C

type Hasher = H

type Config = Config<T, <C as Journal<F>>::Config, S>

type Digest = <H as Hasher>::Digest

type Context = E

async fn persist_sync_result(self) -> Result<Self, Error<F>>

Persist any state that must remain provisional until the engine verifies the rebuilt root.

async fn local_pinned_nodes( context: Self::Context, config: &Self::Config, target: &Target<F, Self::Digest>, journal: &Self::Journal, ) -> Result<Option<Vec<Self::Digest>>, Error<F>>

Return locally available pinned nodes for the target, if persisted local state can authenticate them.

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

Get the root digest of the database for verification

impl<F, E, K, V, C, H, T, S> Debug for Immutable<F, E, K, V, C, H, T, S>

where F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable<Item = Operation<F, K, V>>, C::Item: EncodeShared, H: Hasher, T: Translator, S: Strategy,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F, E, K, V, C, H, T, S> Source for Immutable<F, E, K, V, C, H, T, S>

where F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable<Item = Operation<F, K, V>>, Operation<F, K, V>: EncodeShared, H: Hasher, T: Translator, S: Strategy,

type Family = F

The merkle family backing this source’s proofs.

type Digest = <H as Hasher>::Digest

The digest type used in this source’s proofs.

type Op = Operation<F, K, V>

The type of operations this source yields.

type Error = Error<F>

Why this source could not answer.

async fn serve(&self, request: Request<F>) -> Result<Self>

Serves a response with optional Feedback for reporting its validity.