Struct Journal 

pub struct Journal<E, C, H, S: State<H::Digest> = Dirty>
where
    E: Storage + Clock + Metrics,
    C: Contiguous<Item: Encode>,
    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, S> Journal<E, C, H, S>

where E: Storage + Clock + Metrics, C: Contiguous<Item: Encode>, H: Hasher, S: State<DigestOf<H>>,

pub fn size(&self) -> Location

Returns the number of items in the journal.

pub fn oldest_retained_loc(&self) -> Option<Location>

Returns the oldest retained location in the journal.

pub fn pruning_boundary(&self) -> Location

Returns the pruning boundary for the journal.

pub async fn read(&self, loc: Location) -> Result<C::Item, Error>

Read an item from the journal at the given location.

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

where E: Storage + Clock + Metrics, C: MutableContiguous<Item: Encode>, H: Hasher, S: State<DigestOf<H>>,

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

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

where E: Storage + Clock + Metrics, C: PersistableContiguous<Item: Encode>, H: Hasher, S: State<DigestOf<H>>,

pub async fn commit(&mut 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() or close().

impl<E, C, H> Journal<E, C, H, Clean<H::Digest>>

where E: Storage + Clock + Metrics, C: MutableContiguous<Item: Encode>, H: Hasher,

pub async fn from_components( mmr: CleanMmr<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 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, Clean<H::Digest>>

where E: Storage + Clock + Metrics, C: Contiguous<Item: Encode>, 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 crate::mmr::Error::LocationOverflow if start_loc > crate::mmr::MAX_LOCATION.
• Returns Error::Mmr with crate::mmr::Error::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_size: 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_size items.

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_size and start_loc + max_ops.

Errors

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

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

Return the root of the MMR.

pub fn into_dirty(self) -> Journal<E, C, H, Dirty>

Convert this journal into its dirty counterpart for batched updates.

impl<E, C, H> Journal<E, C, H, Clean<H::Digest>>

where E: Storage + Clock + Metrics, C: PersistableContiguous<Item: Encode>, H: Hasher,

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

Close the authenticated journal, syncing all pending writes.

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

Destroy the authenticated journal, removing all data from disk.

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

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

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

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

pub fn merkleize(self) -> Journal<E, C, H, Clean<H::Digest>>

Merkleize the journal and compute the root digest.

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

where E: Storage + Clock + Metrics, C: MutableContiguous<Item: Encode>, H: Hasher,

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

Create a new dirty journal from aligned components.

impl<E, O, H> Journal<E, Journal<E, O>, H, Clean<H::Digest>>

where E: Storage + Clock + Metrics, O: CodecFixed<Cfg = ()>, 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, Clean<H::Digest>>

where E: Storage + Clock + Metrics, O: Codec + Encode, 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, S> Contiguous for Journal<E, C, H, S>

where E: Storage + Clock + Metrics, C: MutableContiguous<Item: Encode>, H: Hasher, S: State<DigestOf<H>>,

type Item = <C as Contiguous>::Item

The type of items stored in the journal.

fn size(&self) -> u64

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

fn oldest_retained_pos(&self) -> Option<u64>

Return the position of the oldest item still retained in the journal.

fn pruning_boundary(&self) -> u64

Return the location before which all items have been pruned.

async fn replay( &self, start_pos: u64, buffer: NonZeroUsize, ) -> Result<impl Stream<Item = Result<(u64, Self::Item), JournalError>> + '_, JournalError>

Return a stream of all items in the journal starting from start_pos.

async fn read(&self, position: u64) -> Result<Self::Item, JournalError>

Read the item at the given position.

impl<E, C, H> MutableContiguous for Journal<E, C, H, Dirty>

where E: Storage + Clock + Metrics, C: MutableContiguous<Item: Encode>, 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>> + 'a

where P: FnMut(&Self::Item) -> bool + '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> MutableContiguous for Journal<E, C, H, Clean<H::Digest>>

where E: Storage + Clock + Metrics, C: MutableContiguous<Item: Encode>, 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>> + 'a

where P: FnMut(&Self::Item) -> bool + '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> PersistableContiguous for Journal<E, C, H, Clean<H::Digest>>

where E: Storage + Clock + Metrics, C: PersistableContiguous<Item: Encode>, H: Hasher,

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

Durably persist the journal but does not write all data, potentially leaving recovery required on startup.

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

Durably persist the journal and write all data, guaranteeing no recovery will be required on startup.

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

Close the journal, syncing all pending writes and releasing resources.

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

Destroy the journal, removing all associated storage.