bao_tree::io::fsm

Trait Outboard

pub trait Outboard {
    // Required methods
    fn root(&self) -> Hash;
    fn tree(&self) -> BaoTree;
    fn load(
        &mut self,
        node: TreeNode,
    ) -> impl Future<Output = Result<Option<(Hash, Hash)>>>;
}

Expand description

A binary merkle tree for blake3 hashes of a blob.

This trait contains information about the geometry of the tree, the root hash, and a method to load the hashes at a given node.

It is up to the implementor to decide how to store the hashes.

In the original bao crate, the hashes are stored in a file in pre order. This is implemented for a generic io object in super::outboard::PreOrderOutboard and for a memory region in super::outboard::PreOrderMemOutboard.

For files that grow over time, it is more efficient to store the hashes in post order. This is implemented for a generic io object in super::outboard::PostOrderOutboard and for a memory region in super::outboard::PostOrderMemOutboard.

If you use a different storage engine, you can implement this trait for it. E.g. you could store the hashes in a database and use the node number as the key.

The async version takes a mutable reference to load, not because it mutates the outboard (it doesn’t), but to ensure that there is at most one outstanding load at a time.

Dropping the load future without polling it to completion is safe, but will possibly render the outboard unusable.