Struct Journal 

pub struct Journal<F, E, C, H, S>
where
    F: Family,
    E: Context,
    C: Contiguous<Item: EncodeShared>,
    H: Hasher,
    S: Strategy,
{ /* private fields */ }

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

Implementations

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

where F: Family, E: Context, C: Contiguous<Item: EncodeShared>, H: Hasher, S: Strategy,

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

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

pub fn root(&self, inactive_peaks: usize) -> Result<H::Digest, Error<F>>

Compute the root of the Merkle structure using inactive_peaks and the bagging carried by the journal’s hasher.

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

Return a reference to the merkleization strategy.

pub fn new_batch(&self) -> UnmerkleizedBatch<F, H, C::Item, S>

where C::Item: Encode,

Create a speculative batch atop this journal.

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

where F: Family, E: Context, C: Mutable<Item: EncodeShared>, H: Hasher, S: Strategy,

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

Durably persist the journal. This is faster than sync() but does not guarantee that the Merkle structure is durably persisted, meaning recovery may be required on startup in the event of a crash.

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

where F: Family, E: Context, C: Mutable<Item: EncodeShared>, H: Hasher, S: Strategy,

pub async fn from_components( merkle: Merkle<F, E, H::Digest, S>, journal: C, hasher: StandardHasher<H>, apply_batch_size: u64, ) -> Result<Self, Error<F>>

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

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

Append an item to the journal and update the Merkle structure.

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

Apply a batch to the journal.

A batch is valid if the journal has not been modified since the batch chain was created, or if only ancestors of this batch have been applied. Already-committed ancestors are skipped automatically. Applying a batch from a different fork returns an error.

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

Rewind the journal and Merkle structure.

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

Prune both the Merkle structure and journal to the given location.

Returns

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

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

where F: Family, E: Context, C: Contiguous<Item: EncodeShared>, H: Hasher, S: Strategy,

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

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::Merkle with merkle::Error::LocationOverflow if start_loc > Family::MAX_LEAVES.
• Returns Error::Merkle with merkle::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_leaves: Location<F>, start_loc: Location<F>, max_ops: NonZeroU64, inactive_peaks: usize, ) -> Result<(Proof<F, H::Digest>, Vec<C::Item>), Error<F>>

Generate a historical proof with respect to the state of the Merkle structure 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::Merkle with merkle::Error::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<F, E, C, H, S> Journal<F, E, C, H, S>

where F: Family, E: Context, C: Mutable<Item: EncodeShared>, H: Hasher, S: Strategy,

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

Destroy the authenticated journal, removing all data from disk.

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

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

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

where F: Family, E: Context, O: CodecFixedShared, H: Hasher, S: Strategy,

pub async fn new( context: E, merkle_cfg: Config<S>, journal_cfg: Config, rewind_predicate: fn(&O) -> bool, bagging: Bagging, ) -> Result<Self, Error<F>>

Create a new authenticated Journal.

The inner journal will be rewound to the last item matching rewind_predicate, and the merkle structure will be aligned to match.

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

where F: Family, E: Context, O: CodecShared, H: Hasher, S: Strategy,

pub async fn new( context: E, merkle_cfg: Config<S>, journal_cfg: Config<O::Cfg>, rewind_predicate: fn(&O) -> bool, bagging: Bagging, ) -> Result<Self, Error<F>>

Create a new authenticated Journal.

The inner journal will be rewound to the last item matching rewind_predicate, and the merkle structure will be aligned to match.

Trait Implementations

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

where F: Family, E: Context, C: Contiguous<Item: EncodeShared>, H: Hasher, S: Strategy,

type Item = <C as Contiguous>::Item

The type of items stored in the journal.

fn bounds(&self) -> Range<u64>

Returns [start, end) with a guaranteed stable pruning boundary.

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

Read the item at the given position.

async fn read_many( &self, positions: &[u64], ) -> Result<Vec<C::Item>, JournalError>

Read multiple items at the given positions, which must be strictly increasing.

fn try_read_sync(&self, position: u64) -> Option<C::Item>

Read an item if it can be done synchronously (e.g. without I/O), returning None otherwise. Decode failures surface as None and the async read path reports the error.

fn try_read_many_sync(&self, positions: &[u64]) -> Vec<Option<C::Item>>

Probe multiple strictly increasing positions, serving those that can be read synchronously (e.g. from a page cache) and returning one slot per position. Positions that require I/O, fail to decode, or fall outside bounds() decline to None. The async read paths are the sole error authority for declined positions.

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

Return a stream of all items starting from start_pos, bounded by bounds().

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

where F: Family, E: Context, C: Mutable<Item: EncodeShared>, H: Hasher, S: Strategy,

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

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

async fn append_many<'a>( &'a mut self, items: Many<'a, Self::Item>, ) -> Result<u64, JournalError>

Append items to the journal, returning the position of the last item appended.

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.

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

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

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

Durably persist the journal, 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 journal, removing all associated storage.

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.