Implement custom serialization for Opening

Resolves: #55

Author: moCello

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## Added
+
+- Add more comprehensive benchmarks for `blake3` tree [#54]
+- Add `to_var_bytes` and `from_slice` to `Opening` [#55]
+
 ## [0.4.0] - 2023-06-07
 
 ### Added
@@ -68,6 +75,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix `CheckBytes` derivation in `Node` [#15]
 
 <!-- ISSUES -->
+[#55]: https://github.com/dusk-network/merkle/issues/55
+[#54]: https://github.com/dusk-network/merkle/issues/54
 [#49]: https://github.com/dusk-network/merkle/issues/49
 [#44]: https://github.com/dusk-network/merkle/issues/44
 [#38]: https://github.com/dusk-network/merkle/issues/38

Cargo.toml

@@ -15,6 +15,7 @@ edition = "2021"
 license = "MPL-2.0"
 
 [dependencies]
+dusk-bytes = "0.1"
 rkyv = { version = "0.7", optional = true, default-features = false }
 bytecheck = { version = "0.6", optional = true, default-features = false }
 blake3 = { version = "1", optional = true, default-features = false }

src/opening.rs

@@ -6,8 +6,11 @@
 
 use crate::{init_array, Aggregate, Node, Tree};
 
+use alloc::vec::Vec;
+
 #[cfg(feature = "rkyv-impl")]
 use bytecheck::CheckBytes;
+use dusk_bytes::{DeserializableSlice, Error as BytesError, Serializable};
 #[cfg(feature = "rkyv-impl")]
 use rkyv::{Archive, Deserialize, Serialize};
 
@@ -91,6 +94,91 @@ where
 
         self.root == item
     }
+
+    /// Serialize an [`Opening`] to a vector of bytes.
+    // Once the new implementation of the `Serializable` trait becomes
+    // available, we will want that instead, but for the time being we use
+    // this implementation.
+    pub fn to_var_bytes<const T_SIZE: usize>(&self) -> Vec<u8>
+    where
+        T: Serializable<T_SIZE>,
+    {
+        let mut bytes = Vec::with_capacity(
+            (1 + H * A) * T_SIZE + H * (usize::BITS as usize / 8),
+        );
+
+        // serialize root
+        bytes.extend(&self.root.to_bytes());
+
+        // serialize branch
+        for level in self.branch.iter() {
+            for item in level.iter() {
+                bytes.extend(&item.to_bytes());
+            }
+        }
+
+        // serialize positions
+        for pos in self.positions.iter() {
+            // the positions will be in the range [0..A[, so casting to u32
+            // is never going to be a problem
+            #[allow(clippy::cast_possible_truncation)]
+            bytes.extend(&(*pos as u32).to_bytes());
+        }
+
+        bytes
+    }
+
+    /// Deserialize an [`Opening`] from a slice of bytes.
+    ///
+    /// # Errors
+    ///
+    /// Will return [`dusk_bytes::Error`] in case of a deserialization error.
+    // Once the new implementation of the `Serializable` trait becomes
+    // available, we will want that instead, but for the time being we use
+    // this implementation.
+    pub fn from_slice<const T_SIZE: usize>(
+        buf: &[u8],
+    ) -> Result<Self, BytesError>
+    where
+        T: Serializable<T_SIZE>,
+        <T as Serializable<T_SIZE>>::Error: dusk_bytes::BadLength,
+        dusk_bytes::Error: From<<T as Serializable<T_SIZE>>::Error>,
+    {
+        let expected_len =
+            (1 + H * A) * T_SIZE + H * (usize::BITS as usize / 8);
+        if buf.len() != expected_len {
+            return Err(BytesError::BadLength {
+                found: (buf.len()),
+                expected: (expected_len),
+            });
+        }
+
+        let mut bytes = buf;
+
+        // deserialize root
+        let root = T::from_reader(&mut bytes)?;
+
+        // deserialize branch
+        let mut branch: [[T; A]; H] =
+            init_array(|_| init_array(|_| T::EMPTY_SUBTREE));
+        for level in branch.iter_mut() {
+            for item in level.iter_mut() {
+                *item = T::from_reader(&mut bytes)?;
+            }
+        }
+
+        // deserialize positions
+        let mut positions = [0usize; H];
+        for pos in positions.iter_mut() {
+            *pos = u32::from_reader(&mut bytes)? as usize;
+        }
+
+        Ok(Self {
+            root,
+            branch,
+            positions,
+        })
+    }
 }
 
 fn fill_opening<T, const H: usize, const A: usize>(

tests/serializable_opening.rs

@@ -0,0 +1,152 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+//
+// Copyright (c) DUSK NETWORK. All rights reserved.
+
+use std::cmp;
+
+use dusk_bls12_381::BlsScalar;
+use dusk_bytes::{DeserializableSlice, Error, Serializable};
+use dusk_merkle::{Aggregate, Opening, Tree};
+
+use rand::rngs::StdRng;
+use rand::{RngCore, SeedableRng};
+
+const H: usize = 17;
+const A: usize = 4;
+
+#[derive(Clone, Copy, PartialEq, Debug)]
+struct Range {
+    start: u64,
+    end: u64,
+}
+
+#[derive(Clone, Copy, PartialEq, Debug)]
+struct Item {
+    hash: BlsScalar,
+    bh_range: Option<Range>,
+}
+
+const EMPTY_ITEM: Item = Item {
+    hash: BlsScalar::zero(),
+    bh_range: None,
+};
+
+impl Aggregate<A> for Item {
+    const EMPTY_SUBTREE: Self = EMPTY_ITEM;
+
+    fn aggregate(items: [&Self; A]) -> Self {
+        let mut bh_range = None;
+        let rng = &mut StdRng::seed_from_u64(0xbeef);
+
+        for item in items {
+            bh_range = match (bh_range, item.bh_range.as_ref()) {
+                (None, None) => None,
+                (None, Some(r)) => Some(*r),
+                (Some(r), None) => Some(r),
+                (Some(bh_range), Some(item_bh_range)) => {
+                    let start = cmp::min(item_bh_range.start, bh_range.start);
+                    let end = cmp::max(item_bh_range.end, bh_range.end);
+                    Some(Range { start, end })
+                }
+            };
+        }
+
+        Self {
+            hash: BlsScalar::random(rng),
+            bh_range,
+        }
+    }
+}
+
+// scalar + bh_range
+// 32     + 2 + 8 + 8
+const ITEM_SIZE: usize = 50;
+
+impl Serializable<ITEM_SIZE> for Item {
+    type Error = Error;
+
+    fn from_bytes(buf: &[u8; ITEM_SIZE]) -> Result<Self, Self::Error> {
+        let mut bytes = &buf[..];
+
+        // deserialize hash
+        let hash = BlsScalar::from_reader(&mut bytes)?;
+
+        // deserialize bh_range
+        let bh_range = match u16::from_reader(&mut bytes)? {
+            0 => None,
+            1 => {
+                let start = u64::from_reader(&mut bytes)?;
+                let end = u64::from_reader(&mut bytes)?;
+                Some(Range { start, end })
+            }
+            _ => {
+                return Err(Error::InvalidData);
+            }
+        };
+
+        Ok(Item { hash, bh_range })
+    }
+
+    fn to_bytes(&self) -> [u8; ITEM_SIZE] {
+        let mut buf = [0u8; ITEM_SIZE];
+
+        // serialize hash
+        buf[0..BlsScalar::SIZE].copy_from_slice(&self.hash.to_bytes());
+
+        // serialize bh_range
+        match self.bh_range {
+            // the buffer was initialized with zeros so there is nothing to be
+            // done for None
+            None => {}
+            Some(bh_range) => {
+                buf[BlsScalar::SIZE..BlsScalar::SIZE + 2]
+                    .copy_from_slice(&1u16.to_bytes());
+                buf[BlsScalar::SIZE + 2..BlsScalar::SIZE + 10]
+                    .copy_from_slice(&bh_range.start.to_bytes());
+                buf[BlsScalar::SIZE + 10..]
+                    .copy_from_slice(&bh_range.end.to_bytes());
+            }
+        };
+
+        buf
+    }
+}
+
+type MerkleTree = Tree<Item, H, A>;
+
+#[test]
+fn serialize_deserialize() {
+    let tree = &mut MerkleTree::new();
+    let rng = &mut StdRng::seed_from_u64(0xbeef);
+
+    const LEAVES: usize = 1000000;
+
+    let mut i = 0;
+    let (pos, leaf) = loop {
+        i += 1;
+        let block_height = rng.next_u64() % 1000;
+        let bh_range = Some(Range {
+            start: block_height,
+            end: block_height,
+        });
+        let leaf = Item {
+            hash: BlsScalar::random(rng),
+            bh_range,
+        };
+        let pos = rng.next_u64() % tree.capacity();
+        tree.insert(pos, leaf);
+        if i == LEAVES {
+            break (pos, leaf);
+        }
+    };
+
+    let opening = tree.opening(pos).unwrap();
+
+    let serialized = opening.to_var_bytes();
+    let deserialized = Opening::<Item, H, A>::from_slice(&serialized).unwrap();
+
+    assert!(deserialized.verify(leaf));
+    assert_eq!(opening, deserialized);
+}