feat(dursto): construction of MerkleLayer

 - Removes unnecessary `empty` constructor.
 - Changes `new` to be infallible.
 - Updates references of the fallible `new` and `empty` to use the
   infallible `new`.
 - Adds `Debug` derivation to `PersistenceLayer`.
 - Fills in `new` implementation to take a `PersistenceLayer`.

Author: kurtisc

data/src/lib.rs

@@ -10,3 +10,4 @@ pub mod merkle_proof;
 pub mod merkle_tree;
 pub mod mode;
 pub mod serialisation;
+pub mod tree;

data/src/merkle_proof.rs

@@ -5,6 +5,10 @@
 
 //! Merkle proofs
 
+pub mod proof_tree;
+pub mod tag;
+pub mod transform;
+
 use std::error;
 
 use bincode::Decode;

data/src/merkle_proof/proof_tree.rs

@@ -0,0 +1,156 @@
+// SPDX-FileCopyrightText: 2025 TriliTech <contact@trili.tech>
+// SPDX-License-Identifier: MIT
+
+use bincode::enc::write::Writer;
+
+use super::tag::LeafTag;
+use super::tag::Tag;
+use super::transform::ModifyResult;
+use super::transform::impl_modify_map_collect;
+use crate::hash::Hash;
+use crate::tree::Tree;
+
+/// Merkle proof tree structure.
+///
+/// Leaves can be read and/or written to.
+/// If a read was done, the content will be stored in the proof.
+/// If a write was done, the written content is not necessary since the semantics of running the step will
+/// deduce the written contents.
+///
+/// A proof will have the shape of a subtree of a [`MerkleTree`].
+/// The structure of the full [`MerkleTree`] is known statically (since it represents the whole state of the PVM)
+/// so the number of children of a node and the sizes of the leaves
+/// do not need to be stored in either the proof or its encoding.
+///
+/// [`MerkleTree`]: crate::merkle_tree::MerkleTree
+pub type MerkleProof = Tree<MerkleProofLeaf>;
+
+impl bincode::Encode for MerkleProof {
+    fn encode<E: bincode::enc::Encoder>(
+        &self,
+        encoder: &mut E,
+    ) -> Result<(), bincode::error::EncodeError> {
+        let mut nodes = vec![self];
+
+        while let Some(node) = nodes.pop() {
+            match node {
+                Self::Node(trees) => {
+                    Tag::Node.encode(encoder)?;
+
+                    // We add the children in reverse order so that when we pop them from the
+                    // `nodes` stack, they are in the original order.
+                    nodes.extend(trees.iter().rev());
+                }
+
+                Self::Leaf(MerkleProofLeaf::Read(data)) => {
+                    Tag::Leaf(LeafTag::Read).encode(encoder)?;
+
+                    // We want to write the raw data, and avoid the bincode length prefix. The decoder
+                    // will know how many bytes to read.
+                    encoder.writer().write(data.as_slice())?;
+                }
+
+                Self::Leaf(MerkleProofLeaf::Blind(hash)) => {
+                    Tag::Leaf(LeafTag::Blind).encode(encoder)?;
+                    hash.encode(encoder)?;
+                }
+            }
+        }
+
+        Ok(())
+    }
+}
+
+/// Type used to describe the leaves of a [`MerkleProof`].
+/// For more details see the documentation of [`MerkleProof`].
+#[derive(Clone, Debug, PartialEq)]
+pub enum MerkleProofLeaf {
+    /// A leaf that is not read. It may be written.
+    /// Contains the hash of the contents from initial state.
+    ///
+    /// Note: a blinded leaf can correspond to a blinded subtree
+    /// in a [`crate::merkle_tree::MerkleTree`] due to compression.
+    Blind(Hash),
+    /// A leaf that is read. It may also be written.
+    /// Contains the read data from the initial state.
+    /// The initial hash can be deduced based on the read data.
+    Read(Vec<u8>),
+}
+
+impl MerkleProof {
+    /// Create a new Merkle proof as a read leaf.
+    pub fn leaf_read(data: Vec<u8>) -> Self {
+        MerkleProof::Leaf(MerkleProofLeaf::Read(data))
+    }
+
+    /// Create a new Merkle proof as a blind leaf.
+    pub fn leaf_blind(hash: Hash) -> Self {
+        MerkleProof::Leaf(MerkleProofLeaf::Blind(hash))
+    }
+
+    /// Compute the root hash of the Merkle proof.
+    pub fn root_hash(&self) -> Hash {
+        impl_modify_map_collect(
+            self,
+            |subtree| match subtree {
+                Tree::Node(vec) => ModifyResult::NodeContinue((), vec.iter().collect()),
+                Tree::Leaf(data) => ModifyResult::LeafStop(data),
+            },
+            |leaf| match leaf {
+                MerkleProofLeaf::Blind(hash) => *hash,
+                MerkleProofLeaf::Read(data) => Hash::blake3_hash_bytes(data.as_slice()),
+            },
+            |(), leaves| Hash::combine(leaves),
+        )
+    }
+}
+
+impl From<&MerkleProof> for Tag {
+    fn from(value: &MerkleProof) -> Self {
+        match value {
+            MerkleProof::Node(_) => Tag::Node,
+            MerkleProof::Leaf(MerkleProofLeaf::Blind(_)) => Tag::Leaf(LeafTag::Blind),
+            MerkleProof::Leaf(MerkleProofLeaf::Read(_)) => Tag::Leaf(LeafTag::Read),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn get_bincode_config() -> bincode::config::Configuration {
+        bincode::config::standard()
+    }
+
+    #[test]
+    fn merkle_proofs_can_be_encoded() {
+        let merkle_proofs = [
+            MerkleProof::leaf_read([1, 2, 3].to_vec()),
+            MerkleProof::leaf_blind(Hash::blake3_hash_bytes(&[1, 3, 4])),
+            Tree::Node(
+                [
+                    MerkleProof::leaf_read([1, 2, 3].to_vec()),
+                    MerkleProof::leaf_blind(Hash::blake3_hash_bytes(&[1, 3, 4])),
+                ]
+                .to_vec(),
+            ),
+        ];
+        for merkle_proof in merkle_proofs.iter() {
+            bincode::encode_to_vec(merkle_proof, get_bincode_config())
+                .expect("Failed to encode the merkle proof");
+        }
+    }
+
+    #[test]
+    fn we_can_take_the_merkle_proof_of_the_root_hash() {
+        let node = Tree::Node(
+            [
+                MerkleProof::leaf_read([1, 2, 3].to_vec()),
+                MerkleProof::leaf_blind(Hash::blake3_hash_bytes(&[1, 3, 4])),
+            ]
+            .to_vec(),
+        );
+        let _ = node.root_hash();
+    }
+}

data/src/merkle_proof/tag.rs

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2025 TriliTech <contact@trili.tech>
+// SPDX-License-Identifier: MIT
+
+use bincode::Encode;
+
+/// Get the bitmask formed of `n` ones.
+pub const fn ones(n: u64) -> u64 {
+    // This function should not panic
+    let sh_amt = 64_u64.saturating_sub(n);
+    match n {
+        0 => 0,
+        _ => !0 >> sh_amt,
+    }
+}
+
+/// Tag of a node
+pub const TAG_NODE: u8 = 0b00;
+/// Tag of a blind leaf
+pub const TAG_BLIND: u8 = 0b10;
+/// Tag of a read leaf
+pub const TAG_READ: u8 = 0b11;
+
+/// Number of bits used to represent a tag
+const TAG_BITS: u32 = 2;
+/// Number of tags that can fit in a single byte
+const TAGS_PER_BYTE: usize = u8::BITS as usize / TAG_BITS as usize;
+/// Bitmask for tags
+const TAG_MASK: u8 = ones(TAG_BITS as u64) as u8;
+
+/// Return the offset of the `index`-th tag in a byte.
+const fn tag_offset(index: usize) -> usize {
+    debug_assert!(index < TAGS_PER_BYTE);
+    u8::BITS as usize - (index + 1) * TAG_BITS as usize
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum LeafTag {
+    Blind,
+    Read,
+}
+
+impl Encode for LeafTag {
+    fn encode<E: bincode::enc::Encoder>(
+        &self,
+        encoder: &mut E,
+    ) -> Result<(), bincode::error::EncodeError> {
+        match self {
+            LeafTag::Blind => TAG_BLIND,
+            LeafTag::Read => TAG_READ,
+        }
+        .encode(encoder)
+    }
+}
+
+/// The tag is invalid.
+#[derive(Debug, Clone, PartialEq, thiserror::Error)]
+#[error("Invalid tag")]
+pub struct InvalidTagError;
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Tag {
+    Node,
+    Leaf(LeafTag),
+}
+
+impl Tag {
+    /// Obtain the parsed tags from the most significant bits to the lower ones.
+    pub fn ordered_tags_from_u8(byte: u8) -> [Result<Tag, InvalidTagError>; TAGS_PER_BYTE] {
+        core::array::from_fn(tag_offset)
+            .map(|offset| (byte >> offset) & TAG_MASK)
+            .map(Tag::try_from)
+    }
+}
+
+impl bincode::Encode for Tag {
+    fn encode<E: bincode::enc::Encoder>(
+        &self,
+        encoder: &mut E,
+    ) -> Result<(), bincode::error::EncodeError> {
+        match self {
+            Tag::Node => TAG_NODE.encode(encoder),
+            Tag::Leaf(leaf_tag) => leaf_tag.encode(encoder),
+        }
+    }
+}
+
+impl<'de, C> bincode::BorrowDecode<'de, C> for Tag {
+    fn borrow_decode<D: bincode::de::BorrowDecoder<'de, Context = C>>(
+        decoder: &mut D,
+    ) -> Result<Self, bincode::error::DecodeError> {
+        let byte = u8::borrow_decode(decoder)?;
+        Tag::try_from(byte)
+            .map_err(|error| bincode::error::DecodeError::OtherString(error.to_string()))
+    }
+}
+
+impl<C> bincode::Decode<C> for Tag {
+    fn decode<D: bincode::de::Decoder<Context = C>>(
+        decoder: &mut D,
+    ) -> Result<Self, bincode::error::DecodeError> {
+        let byte = u8::decode(decoder)?;
+        Tag::try_from(byte)
+            .map_err(|error| bincode::error::DecodeError::OtherString(error.to_string()))
+    }
+}
+
+impl From<Tag> for u8 {
+    fn from(value: Tag) -> Self {
+        match value {
+            Tag::Node => TAG_NODE,
+            Tag::Leaf(leaf_tag) => match leaf_tag {
+                LeafTag::Blind => TAG_BLIND,
+                LeafTag::Read => TAG_READ,
+            },
+        }
+    }
+}
+
+impl From<LeafTag> for Tag {
+    fn from(value: LeafTag) -> Self {
+        Tag::Leaf(value)
+    }
+}
+
+impl TryFrom<u8> for Tag {
+    type Error = InvalidTagError;
+
+    fn try_from(value: u8) -> Result<Self, Self::Error> {
+        match value {
+            TAG_NODE => Ok(Self::Node),
+            TAG_BLIND => Ok(Self::Leaf(LeafTag::Blind)),
+            TAG_READ => Ok(Self::Leaf(LeafTag::Read)),
+            _ => Err(InvalidTagError),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn get_bincode_config() -> bincode::config::Configuration {
+        bincode::config::standard()
+    }
+
+    fn tag_encode_cycle_checker(tag: &Tag) {
+        let mut encoded =
+            bincode::encode_to_vec(tag, get_bincode_config()).expect("Failed to encode the tag");
+        let (decoded, _): (Tag, usize) =
+            bincode::decode_from_slice(encoded.as_mut_slice(), get_bincode_config())
+                .expect("Failed to decode the tag");
+        assert_eq!(*tag, decoded);
+    }
+
+    #[test]
+    fn can_encode_and_decode_tags() {
+        let tags = [
+            Tag::Node,
+            Tag::Leaf(LeafTag::Blind),
+            Tag::Leaf(LeafTag::Read),
+        ];
+        for tag in tags.iter() {
+            tag_encode_cycle_checker(tag);
+        }
+    }
+}