Struct Journal 

pub struct Journal<E, C, H>
where
    E: Storage + Clock + Metrics,
    C: Contiguous<Item: EncodeShared>,
    H: Hasher,
{ /* private fields */ }

An append-only data structure that maintains a sequential journal of items alongside a Merkle Mountain Range (MMR). The item at index i in the journal corresponds to the leaf at Location i in the MMR. This structure enables efficient proofs that an item is included in the journal at a specific location.

Implementations

impl<E, C, H> Journal<E, C, H>

where E: Storage + Clock + Metrics, C: Contiguous<Item: EncodeShared>, H: Hasher,

pub async fn size(&self) -> Location

Returns the Location of the next item appended to the journal.

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

Return the root of the MMR.

pub fn new_batch(&self) -> UnmerkleizedBatch<'_, H, Mmr<E, H::Digest>, C::Item>

Create a speculative batch atop this journal.

impl<E, C, H> Journal<E, C, H>

where E: Storage + Clock + Metrics, C: Contiguous<Item: EncodeShared> + Persistable<Error = Error>, H: Hasher,

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

Durably persist the journal. This is faster than sync() but does not persist the MMR, meaning recovery will be required on startup if we crash before sync().

impl<E, C, H> Journal<E, C, H>

where E: Storage + Clock + Metrics, C: Mutable<Item: EncodeShared>, H: Hasher,

pub async fn from_components( mmr: Mmr<E, H::Digest>, journal: C, hasher: StandardHasher<H>, apply_batch_size: u64, ) -> Result<Self, Error>

Create a new Journal from the given components after aligning the MMR with the journal.

pub async fn append(&mut self, item: &C::Item) -> Result<Location, Error>

Append an item to the journal and update the MMR.

pub async fn apply_batch( &mut self, batch: Changeset<H::Digest, C::Item>, ) -> Result<(), Error>

Apply a changeset to the journal.

A changeset is only valid if the journal has not been modified since the batch that produced it was created. Multiple batches can be forked from the same parent for speculative execution, but only one may be applied. Applying a stale changeset returns an error.

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

Prune both the MMR and journal to the given location.

Returns

The new pruning boundary, which may be less than the requested prune_loc.

impl<E, C, H> Journal<E, C, H>

where E: Storage + Clock + Metrics, C: Contiguous<Item: EncodeShared>, H: Hasher,

pub async fn proof( &self, start_loc: Location, max_ops: NonZeroU64, ) -> Result<(Proof<H::Digest>, Vec<C::Item>), Error>

Generate a proof of inclusion for items starting at start_loc.

Returns a proof and the items corresponding to the leaves in the range start_loc..end_loc, where end_loc is the minimum of the current item count and start_loc + max_ops.

Errors

• Returns Error::Mmr with MmrError::LocationOverflow if start_loc > crate::mmr::MAX_LOCATION.
• Returns Error::Mmr with MmrError::RangeOutOfBounds if start_loc >= current item count.
• Returns Error::Journal with crate::journal::Error::ItemPruned if start_loc has been pruned.

pub async fn historical_proof( &self, historical_leaves: Location, start_loc: Location, max_ops: NonZeroU64, ) -> Result<(Proof<H::Digest>, Vec<C::Item>), Error>

Generate a historical proof with respect to the state of the MMR when it had historical_leaves leaves.

Returns a proof and the items corresponding to the leaves in the range start_loc..end_loc, where end_loc is the minimum of historical_leaves and start_loc + max_ops.

Errors

• Returns Error::Mmr with MmrError::RangeOutOfBounds if start_loc >= historical_leaves or historical_leaves > number of items in the journal.
• Returns Error::Journal with crate::journal::Error::ItemPruned if start_loc has been pruned.

impl<E, C, H> Journal<E, C, H>

where E: Storage + Clock + Metrics, C: Contiguous<Item: EncodeShared> + Persistable<Error = Error>, H: Hasher,

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

Destroy the authenticated journal, removing all data from disk.

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

Durably persist the journal, ensuring no recovery is required on startup.

impl<E, O, H> Journal<E, Journal<E, O>, H>

where E: Storage + Clock + Metrics, O: CodecFixedShared, H: Hasher,

pub async fn new( context: E, mmr_cfg: Config, journal_cfg: Config, rewind_predicate: fn(&O) -> bool, ) -> Result<Self, Error>

Create a new Journal for fixed-length items.

The journal will be rewound to the last item that matches the rewind_predicate on initialization.

impl<E, O, H> Journal<E, Journal<E, O>, H>

where E: Storage + Clock + Metrics, O: CodecShared, H: Hasher,

pub async fn new( context: E, mmr_cfg: Config, journal_cfg: Config<O::Cfg>, rewind_predicate: fn(&O) -> bool, ) -> Result<Self, Error>

Create a new Journal for variable-length items.

The journal will be rewound to the last item that matches the rewind_predicate on initialization.

Trait Implementations

impl<E, C, H> Contiguous for Journal<E, C, H>

where E: Storage + Clock + Metrics, C: Contiguous<Item: EncodeShared>, H: Hasher,

type Item = <C as Contiguous>::Item

The type of items stored in the journal.

async fn reader(&self) -> impl Reader<Item = C::Item> + '_

Acquire a reader guard that holds a consistent view of the journal.

async fn size(&self) -> u64

Return the total number of items that have been appended to the journal.

impl<E, C, H> Mutable for Journal<E, C, H>

where E: Storage + Clock + Metrics, C: Mutable<Item: EncodeShared>, H: Hasher,

async fn append(&mut self, item: &Self::Item) -> Result<u64, JournalError>

Append a new item to the journal, returning its position.

async fn prune(&mut self, min_position: u64) -> Result<bool, JournalError>

Prune items at positions strictly less than min_position.

async fn rewind(&mut self, size: u64) -> Result<(), JournalError>

Rewind the journal to the given size, discarding items from the end.

fn rewind_to<'a, P>( &'a mut self, predicate: P, ) -> impl Future<Output = Result<u64, Error>> + Send + 'a

where P: FnMut(&Self::Item) -> bool + Send + 'a,

Rewinds the journal to the last item matching predicate. If no item matches, the journal is rewound to the pruning boundary, discarding all unpruned items.

impl<E, C, H> Persistable for Journal<E, C, H>

where E: Storage + Clock + Metrics, C: Contiguous<Item: EncodeShared> + Persistable<Error = Error>, H: Hasher,

type Error = Error

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

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

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

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

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<(), JournalError>

Destroy the structure, removing all associated storage.