Add 'zcash_history/' from commit 'e2c131fdc308265adcab774e54d4d5804c23b368'

git-subtree-dir: zcash_history
git-subtree-mainline: be0ee9eb82
git-subtree-split: e2c131fdc3

zcash_history/src/entry.rs

@@ -0,0 +1,121 @@
+use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
+
+use crate::{EntryKind, NodeData, Error, EntryLink, MAX_NODE_DATA_SIZE};
+
+/// Max serialized length of entry data.
+pub const MAX_ENTRY_SIZE: usize = MAX_NODE_DATA_SIZE + 9;
+
+/// MMR Entry.
+#[derive(Debug)]
+pub struct Entry {
+    pub(crate) kind: EntryKind,
+    pub(crate) data: NodeData,
+}
+
+impl Entry {
+    /// New entry of type node.
+    pub fn new(data: NodeData, left: EntryLink, right: EntryLink) -> Self {
+        Entry {
+            kind: EntryKind::Node(left, right),
+            data,
+        }
+    }
+
+    /// Returns if is this node complete (has total of 2^N leaves)
+    pub fn complete(&self) -> bool {
+        let leaves = self.leaf_count();
+        leaves & (leaves - 1) == 0
+    }
+
+    /// Number of leaves under this node.
+    pub fn leaf_count(&self) -> u64 {
+        self.data.end_height - (self.data.start_height - 1)
+    }
+
+    /// Is this node a leaf.
+    pub fn leaf(&self) -> bool {
+        if let EntryKind::Leaf = self.kind { true } else { false }
+    }
+
+    /// Left child
+    pub fn left(&self) -> Result<EntryLink, Error> {
+        match self.kind {
+            EntryKind::Leaf => { Err(Error::node_expected()) }
+            EntryKind::Node(left, _) => Ok(left)
+        }
+    }
+
+    /// Right child.
+    pub fn right(&self) -> Result<EntryLink, Error> {
+        match self.kind {
+            EntryKind::Leaf => { Err(Error::node_expected()) }
+            EntryKind::Node(_, right) => Ok(right)
+        }
+    }
+
+    /// Read from byte representation.
+    pub fn read<R: std::io::Read>(consensus_branch_id: u32, r: &mut R) -> std::io::Result<Self> {
+        let kind = {
+            match r.read_u8()? {
+                0 => {
+                    let left = r.read_u32::<LittleEndian>()?;
+                    let right = r.read_u32::<LittleEndian>()?;
+                    EntryKind::Node(EntryLink::Stored(left), EntryLink::Stored(right))
+                },
+                1 => {
+                    EntryKind::Leaf
+                },
+                _ => {
+                    return Err(std::io::Error::from(std::io::ErrorKind::InvalidData))
+                },
+            }
+        };
+
+        let data = NodeData::read(consensus_branch_id, r)?;
+
+        Ok(Entry {
+            kind,
+            data,
+        })
+    }
+
+    /// Write to byte representation.
+    pub fn write<W: std::io::Write>(&self, w: &mut W) -> std::io::Result<()> {
+        match self.kind {
+            EntryKind::Node(EntryLink::Stored(left), EntryLink::Stored(right)) => {
+                w.write_u8(0)?;
+                w.write_u32::<LittleEndian>(left)?;
+                w.write_u32::<LittleEndian>(right)?;
+            },
+            EntryKind::Leaf => {
+                w.write_u8(1)?;
+            },
+            _ => { return Err(std::io::Error::from(std::io::ErrorKind::InvalidData)); }
+        }
+
+        self.data.write(w)?;
+
+        Ok(())
+    }
+
+    /// Convert from byte representation.
+    pub fn from_bytes<T: AsRef<[u8]>>(consensus_branch_id: u32, buf: T) -> std::io::Result<Self> {
+        let mut cursor = std::io::Cursor::new(buf);
+        Self::read(consensus_branch_id, &mut cursor)
+    }
+}
+
+impl From<NodeData> for Entry {
+    fn from(s: NodeData) -> Self {
+        Entry { kind: EntryKind::Leaf, data: s }
+    }
+}
+
+impl std::fmt::Display for Entry {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self.kind {
+            EntryKind::Node(l, r) => write!(f, "node({}, {}, ..)", l, r),
+            EntryKind::Leaf => write!(f, "leaf(..)"),
+        }
+    }
+}

zcash_history/src/lib.rs

@@ -0,0 +1,77 @@
+//! MMR library for Zcash
+//!
+//! To be used in zebra and via FFI bindings in zcashd
+#![warn(missing_docs)]
+
+mod tree;
+mod node_data;
+mod entry;
+
+
+pub use tree::Tree;
+pub use node_data::{NodeData, MAX_NODE_DATA_SIZE};
+pub use entry::{Entry, MAX_ENTRY_SIZE};
+
+/// Crate-level error type
+#[derive(Debug)]
+pub enum Error {
+    /// Entry expected to be presented in the tree view while it was not.
+    ExpectedInMemory(EntryLink),
+    /// Entry expected to be a node (specifying for which link this is not true).
+    ExpectedNode(Option<EntryLink>),
+}
+
+impl std::fmt::Display for Error {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match *self {
+            Self::ExpectedInMemory(l) => write!(f, "Node/leaf expected to be in memory: {}", l),
+            Self::ExpectedNode(None) => write!(f, "Node expected"),
+            Self::ExpectedNode(Some(l)) => write!(f, "Node expected, not leaf: {}", l),
+        }
+    }
+}
+
+/// Reference to to the tree node.
+#[repr(C)]
+#[derive(Clone, Copy, Debug)]
+pub enum EntryLink {
+    /// Reference to the stored (in the array representation) leaf/node.
+    Stored(u32),
+    /// Reference to the generated leaf/node.
+    Generated(u32),
+}
+
+impl std::fmt::Display for EntryLink {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match *self {
+            Self::Stored(v) => write!(f, "stored({})", v),
+            Self::Generated(v) => write!(f, "generated({})", v),
+        }
+    }
+}
+
+/// MMR Node. It is leaf when `left`, `right` are `None` and node when they are not.
+#[repr(C)]
+#[derive(Debug)]
+pub enum EntryKind {
+    /// Leaf entry.
+    Leaf,
+    /// Node entry with children links.
+    Node(EntryLink, EntryLink),
+}
+
+impl Error {
+    /// Entry expected to be a node (specifying for which link this is not true).
+    pub fn link_node_expected(link: EntryLink) -> Self { Self::ExpectedNode(Some(link)) }
+
+    /// Some entry is expected to be node
+    pub fn node_expected() -> Self { Self::ExpectedNode(None) }
+
+    pub (crate) fn augment(self, link: EntryLink) -> Self {
+        match self {
+            Error::ExpectedNode(_) => Error::ExpectedNode(Some(link)),
+            val => val
+        }
+    }
+}
+

zcash_history/src/node_data.rs

@@ -0,0 +1,239 @@
+use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt, ByteOrder};
+use bigint::U256;
+use blake2::Params as Blake2Params;
+
+/// Maximum serialized size of the node metadata.
+pub const MAX_NODE_DATA_SIZE: usize =
+    32 + // subtree commitment
+    4 +  // start time
+    4 +  // end time
+    4 +  // start target
+    4 +  // end target
+    32 + // start sapling tree root
+    32 + // end sapling tree root
+    32 + // subtree total work
+    9 +  // start height (compact uint)
+    9 +  // end height (compact uint)
+    9;   // shielded tx count (compact uint)
+    // = total of 171
+
+/// Node metadata.
+#[repr(C)]
+#[derive(Debug, Clone, Default)]
+#[cfg_attr(test, derive(PartialEq))]
+pub struct NodeData {
+    /// Consensus branch id, should be provided by deserializing node.
+    pub consensus_branch_id: u32,
+    /// Subtree commitment - either block hash for leaves or hashsum of children for nodes.
+    pub subtree_commitment: [u8; 32],
+    /// Start time.
+    pub start_time: u32,
+    /// End time.
+    pub end_time: u32,
+    /// Start target.
+    pub start_target: u32,
+    /// End target.
+    pub end_target: u32,
+    /// Start sapling tree root.
+    pub start_sapling_root: [u8; 32],
+    /// End sapling tree root.
+    pub end_sapling_root: [u8; 32],
+    /// Part of tree total work.
+    pub subtree_total_work: U256,
+    /// Start height.
+    pub start_height: u64,
+    /// End height
+    pub end_height: u64,
+    /// Number of shielded transactions.
+    pub shielded_tx: u64,
+}
+
+fn blake2b_personal(personalization: &[u8], input: &[u8]) -> [u8; 32] {
+    let hash_result = Blake2Params::new()
+        .hash_length(32)
+        .personal(personalization)
+        .to_state()
+        .update(input)
+        .finalize();
+    let mut result = [0u8; 32];
+    result.copy_from_slice(hash_result.as_bytes());
+    result
+}
+
+fn personalization(branch_id: u32) -> [u8; 16] {
+    let mut result = [0u8; 16];
+    result[..12].copy_from_slice(b"ZcashHistory");
+    LittleEndian::write_u32(&mut result[12..], branch_id);
+    result
+}
+
+impl NodeData {
+    /// Combine two nodes metadata.
+    pub fn combine(left: &NodeData, right: &NodeData) -> NodeData {
+        assert_eq!(left.consensus_branch_id, right.consensus_branch_id);
+
+        let mut hash_buf = [0u8; MAX_NODE_DATA_SIZE * 2];
+        let size = {
+            let mut cursor = ::std::io::Cursor::new(&mut hash_buf[..]);
+            left.write(&mut cursor).expect("Writing to memory buf with enough length cannot fail; qed");
+            right.write(&mut cursor).expect("Writing to memory buf with enough length cannot fail; qed");
+            cursor.position() as usize
+        };
+
+        let hash = blake2b_personal(
+            &personalization(left.consensus_branch_id),
+            &hash_buf[..size]
+        );
+
+        NodeData {
+            consensus_branch_id: left.consensus_branch_id,
+            subtree_commitment: hash,
+            start_time: left.start_time,
+            end_time: right.end_time,
+            start_target: left.start_target,
+            end_target: right.end_target,
+            start_sapling_root: left.start_sapling_root,
+            end_sapling_root: right.end_sapling_root,
+            subtree_total_work: left.subtree_total_work + right.subtree_total_work,
+            start_height: left.start_height,
+            end_height: right.end_height,
+            shielded_tx: left.shielded_tx + right.shielded_tx,
+        }
+    }
+
+    fn write_compact<W: std::io::Write>(w: &mut W, compact: u64) -> std::io::Result<()> {
+        match compact {
+            0..=0xfc => {
+                w.write_all(&[compact as u8])?
+            },
+            0xfd..=0xffff => {
+                w.write_all(&[0xfd])?;
+                w.write_u16::<LittleEndian>(compact as u16)?;
+            },
+            0x10000..=0xffff_ffff => {
+                w.write_all(&[0xfe])?;
+                w.write_u32::<LittleEndian>(compact as u32)?;
+            },
+            _ => {
+                w.write_all(&[0xff])?;
+                w.write_u64::<LittleEndian>(compact)?;
+            }
+        }
+        Ok(())
+    }
+
+    fn read_compact<R: std::io::Read>(reader: &mut R) -> std::io::Result<u64> {
+        let result = match reader.read_u8()? {
+            i @ 0..=0xfc => i.into(),
+            0xfd => reader.read_u16::<LittleEndian>()?.into(),
+            0xfe => reader.read_u32::<LittleEndian>()?.into(),
+            _ => reader.read_u64::<LittleEndian>()?,
+        };
+
+        Ok(result)
+    }
+
+    /// Write to the byte representation.
+    pub fn write<W: std::io::Write>(&self, w: &mut W) -> std::io::Result<()> {
+        w.write_all(&self.subtree_commitment)?;
+        w.write_u32::<LittleEndian>(self.start_time)?;
+        w.write_u32::<LittleEndian>(self.end_time)?;
+        w.write_u32::<LittleEndian>(self.start_target)?;
+        w.write_u32::<LittleEndian>(self.end_target)?;
+        w.write_all(&self.start_sapling_root)?;
+        w.write_all(&self.end_sapling_root)?;
+
+        let mut work_buf = [0u8; 32];
+        self.subtree_total_work.to_little_endian(&mut work_buf[..]);
+        w.write_all(&work_buf)?;
+
+        Self::write_compact(w, self.start_height)?;
+        Self::write_compact(w, self.end_height)?;
+        Self::write_compact(w, self.shielded_tx)?;
+        Ok(())
+    }
+
+    /// Read from the byte representation.
+    pub fn read<R: std::io::Read>(consensus_branch_id: u32, r: &mut R) -> std::io::Result<Self> {
+        let mut data = Self::default();
+        data.consensus_branch_id = consensus_branch_id;
+        r.read_exact(&mut data.subtree_commitment)?;
+        data.start_time = r.read_u32::<LittleEndian>()?;
+        data.end_time = r.read_u32::<LittleEndian>()?;
+        data.start_target= r.read_u32::<LittleEndian>()?;
+        data.end_target= r.read_u32::<LittleEndian>()?;
+        r.read_exact(&mut data.start_sapling_root)?;
+        r.read_exact(&mut data.end_sapling_root)?;
+
+        let mut work_buf = [0u8; 32];
+        r.read_exact(&mut work_buf)?;
+        data.subtree_total_work = U256::from_little_endian(&work_buf);
+
+        data.start_height = Self::read_compact(r)?;
+        data.end_height = Self::read_compact(r)?;
+        data.shielded_tx = Self::read_compact(r)?;
+
+        Ok(data)
+    }
+
+    /// Convert to byte representation.
+    pub fn to_bytes(&self) -> Vec<u8> {
+        let mut buf = [0u8; MAX_NODE_DATA_SIZE];
+        let pos = {
+            let mut cursor = std::io::Cursor::new(&mut buf[..]);
+            self.write(&mut cursor).expect("Cursor cannot fail");
+            cursor.position() as usize
+        };
+
+        buf[0..pos].to_vec()
+    }
+
+    /// Convert from byte representation.
+    pub fn from_bytes<T: AsRef<[u8]>>(consensus_branch_id: u32, buf: T) -> std::io::Result<Self> {
+        let mut cursor = std::io::Cursor::new(buf);
+        Self::read(consensus_branch_id, &mut cursor)
+    }
+
+    /// Hash node metadata
+    pub fn hash(&self) -> [u8; 32] {
+        let bytes = self.to_bytes();
+
+        blake2b_personal(&personalization(self.consensus_branch_id), &bytes)
+    }
+}
+
+#[cfg(test)]
+impl quickcheck::Arbitrary for NodeData {
+    fn arbitrary<G: quickcheck::Gen>(gen: &mut G) -> Self {
+        let mut node_data = NodeData::default();
+        node_data.consensus_branch_id = 0;
+        gen.fill_bytes(&mut node_data.subtree_commitment[..]);
+        node_data.start_time = gen.next_u32();
+        node_data.end_time = gen.next_u32();
+        node_data.start_target = gen.next_u32();
+        node_data.end_target = gen.next_u32();
+        gen.fill_bytes(&mut node_data.start_sapling_root[..]);
+        gen.fill_bytes(&mut node_data.end_sapling_root[..]);
+        let mut number = [0u8; 32];
+        gen.fill_bytes(&mut number[..]);
+        node_data.subtree_total_work = U256::from_little_endian(&number[..]);
+        node_data.start_height = gen.next_u64();
+        node_data.end_height = gen.next_u64();
+        node_data.shielded_tx = gen.next_u64();
+
+        node_data
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::NodeData;
+    use quickcheck::{quickcheck, TestResult};
+
+
+    quickcheck! {
+        fn serialization_round_trip(node_data: NodeData) -> TestResult {
+            TestResult::from_bool(NodeData::from_bytes(0, &node_data.to_bytes()).unwrap() == node_data)
+        }
+    }
+}

zcash_history/src/tree.rs

@@ -0,0 +1,756 @@
+use std::collections::HashMap;
+
+use crate::{Entry, EntryLink, NodeData, Error, EntryKind};
+
+/// Represents partially loaded tree.
+///
+/// Some kind of "view" into the array representation of the MMR tree.
+/// With only some of the leaves/nodes pre-loaded / pre-generated.
+/// Exact amount of the loaded data can be calculated by the constructing party,
+/// depending on the length of the tree and maximum amount of operations that are going
+/// to happen after construction. `Tree` should not be used as self-contained data structure,
+/// since it's internal state can grow indefinitely after serial operations.
+/// Intended use of this `Tree` is to instantiate it based on partially loaded data (see example
+/// how to pick right nodes from the array representation of MMR Tree), perform several operations
+/// (append-s/delete-s) and then drop it.
+pub struct Tree {
+    stored: HashMap<u32, Entry>,
+
+    // This can grow indefinitely if `Tree` is misused as a self-contained data structure
+    generated: Vec<Entry>,
+
+    // number of persistent(!) tree entries
+    stored_count: u32,
+
+    root: EntryLink,
+}
+
+impl Tree {
+    /// Resolve link originated from this tree
+    pub fn resolve_link(&self, link: EntryLink) -> Result<IndexedNode, Error> {
+         match link {
+             EntryLink::Generated(index) => self.generated.get(index as usize),
+             EntryLink::Stored(index) => self.stored.get(&index),
+         }
+         .map(|node| IndexedNode {
+             node,
+             link,
+         })
+         .ok_or(Error::ExpectedInMemory(link))
+    }
+
+    fn push(&mut self, data: Entry) -> EntryLink {
+        let idx = self.stored_count;
+        self.stored_count += 1;
+        self.stored.insert(idx, data);
+        EntryLink::Stored(idx)
+    }
+
+    fn push_generated(&mut self, data: Entry) -> EntryLink {
+        self.generated.push(data);
+        EntryLink::Generated(self.generated.len() as u32 - 1)
+    }
+
+    /// Populate tree with plain list of the leaves/nodes. For now, only for tests,
+    /// since this `Tree` structure is for partially loaded tree (but it might change)
+    #[cfg(test)]
+    pub fn populate(loaded: Vec<Entry>, root: EntryLink) -> Self {
+        let mut result = Tree::invalid();
+        result.stored_count = loaded.len() as u32;
+        for (idx, item) in loaded.into_iter().enumerate() {
+            result.stored.insert(idx as u32, item);
+        }
+        result.root = root;
+
+        result
+    }
+
+    // Empty tree with invalid root
+    fn invalid() -> Self {
+        Tree {
+            root: EntryLink::Generated(0),
+            generated: Default::default(),
+            stored: Default::default(),
+            stored_count: 0,
+        }
+    }
+
+    /// New view into the the tree array representation
+    ///
+    /// `length` is total length of the array representation (is generally not a sum of
+    ///     peaks.len + extra.len)
+    /// `peaks` is peaks of the mmr tree
+    /// `extra` is some extra nodes that calculated to be required during next one or more
+    /// operations on the tree.
+    ///
+    /// # Panics
+    ///
+    /// Will panic if `peaks` is empty.
+    pub fn new(
+        length: u32,
+        peaks: Vec<(u32, Entry)>,
+        extra: Vec<(u32, Entry)>,
+    ) -> Self {
+        assert!(peaks.len() > 0);
+
+        let mut result = Tree::invalid();
+
+        result.stored_count = length;
+
+        let mut gen = 0;
+        let mut root = EntryLink::Stored(peaks[0].0);
+        for (idx, node) in peaks.into_iter() {
+            result.stored.insert(idx, node);
+            if gen != 0 {
+                let next_generated =
+                    combine_nodes(result.
+                        resolve_link(root).expect("Inserted before, cannot fail; qed"),
+                      result.resolve_link(EntryLink::Stored(idx)).expect("Inserted before, cannot fail; qed")
+                    );
+                root = result.push_generated(next_generated);
+            }
+            gen += 1;
+        }
+
+        for (idx, node) in extra {
+            result.stored.insert(idx, node);
+        }
+
+        result.root = root;
+
+        result
+    }
+
+    fn get_peaks(&self, root: EntryLink, target: &mut Vec<EntryLink>) -> Result<(), Error> {
+
+        let (left_child_link, right_child_link) = {
+            let root = self.resolve_link(root)?;
+            if root.node.complete() {
+                target.push(root.link);
+                return Ok(());
+            }
+            (
+                root.left()?,
+                root.right()?,
+            )
+        };
+
+        self.get_peaks(left_child_link, target)?;
+        self.get_peaks(right_child_link, target)?;
+        Ok(())
+    }
+
+    /// Append one leaf to the tree.
+    ///
+    /// Returns links to actual nodes that has to be persisted as the result of the append.
+    /// If completed without error, at least one link to the appended
+    /// node (with metadata provided in `new_leaf`) will be returned.
+    pub fn append_leaf(&mut self, new_leaf: NodeData) -> Result<Vec<EntryLink>, Error> {
+        let root = self.root;
+        let new_leaf_link = self.push(new_leaf.into());
+        let mut appended = Vec::new();
+        appended.push(new_leaf_link);
+
+        let mut peaks = Vec::new();
+        self.get_peaks(root, &mut peaks)?;
+
+        let mut merge_stack = Vec::new();
+        merge_stack.push(new_leaf_link);
+
+        // Scan the peaks right-to-left, merging together equal-sized adjacent
+        // complete subtrees. After this, merge_stack only contains peaks of
+        // unequal-sized subtrees.
+        while let Some(next_peak) = peaks.pop() {
+            let next_merge = merge_stack.pop().expect("there should be at least one, initial or re-pushed");
+
+            if let Some(stored) = {
+                let peak = self.resolve_link(next_peak)?;
+                let m = self.resolve_link(next_merge)?;
+                if peak.node.leaf_count() == m.node.leaf_count() {
+                    Some(combine_nodes(peak, m))
+                } else { None }
+            } {
+                let link = self.push(stored);
+                merge_stack.push(link);
+                appended.push(link);
+                continue;
+            } else {
+                merge_stack.push(next_merge);
+                merge_stack.push(next_peak);
+            }
+        }
+
+        let mut new_root = merge_stack.pop().expect("Loop above cannot reduce the merge_stack");
+        // Scan the peaks left-to-right, producing new generated nodes that
+        // connect the subtrees
+        while let Some(next_child) = merge_stack.pop() {
+            new_root = self.push_generated(
+                combine_nodes(
+                    self.resolve_link(new_root)?,
+                    self.resolve_link(next_child)?,
+                )
+            )
+        }
+
+        self.root = new_root;
+
+        Ok(appended)
+    }
+
+    #[cfg(test)]
+    fn for_children<F: Fn(EntryLink, EntryLink)>(&self, node: EntryLink, f: F) {
+        let (left, right) = {
+            let link = self.resolve_link(node).expect("Failed to resolve link in test");
+            (
+                link.left().expect("Failed to find node in test"),
+                link.right().expect("Failed to find node in test"),
+            )
+        };
+        f(left, right);
+    }
+
+    fn pop(&mut self) {
+        self.stored.remove(&(self.stored_count-1));
+        self.stored_count = self.stored_count - 1;
+    }
+
+    /// Truncate one leaf from the end of the tree.
+    ///
+    /// Returns actual number of nodes that should be removed by the caller
+    /// from the end of the array representation.
+    pub fn truncate_leaf(&mut self) -> Result<u32, Error> {
+        let root = {
+            let (leaves, root_left_child) = {
+                let n = self.resolve_link(self.root)?;
+                (
+                    n.node.leaf_count(),
+                    n.node.left()?,
+                )
+            };
+            if leaves & 1 != 0 {
+                self.pop();
+                self.root = root_left_child;
+                return Ok(1);
+            } else {
+                self.resolve_link(self.root)?
+            }
+        };
+
+        let mut peaks = vec![root.left()?];
+        let mut subtree_root_link = root.right()?;
+        let mut truncated = 1;
+
+        loop {
+            let left_link = self.resolve_link(subtree_root_link)?.node;
+            if let EntryKind::Node(left, right) = left_link.kind {
+                peaks.push(left);
+                subtree_root_link = right;
+                truncated += 1;
+            } else {
+                if root.node.complete() { truncated += 1; }
+                break;
+            }
+        }
+
+        let mut new_root = *peaks.get(0).expect("At lest 1 elements in peaks");
+
+        for next_peak in peaks.into_iter().skip(1) {
+            new_root = self.push_generated(
+                combine_nodes(
+                self.resolve_link(new_root)?,
+                self.resolve_link(next_peak)?,
+                )
+            );
+        }
+
+        for _ in 0..truncated { self.pop(); }
+
+        self.root = new_root;
+
+        Ok(truncated)
+    }
+
+    /// Length of array representation of the tree.
+    pub fn len(&self) -> u32 {
+        self.stored_count
+    }
+
+    /// Link to the root node
+    pub fn root(&self) -> EntryLink { self.root }
+
+    /// Reference to the root node.
+    pub fn root_node(&self) -> Result<IndexedNode, Error> {
+        self.resolve_link(self.root)
+    }
+
+    /// If this tree is empty.
+    pub fn is_empty(&self) -> bool {
+        self.stored_count == 0
+    }
+}
+
+/// Reference to the node with link attached.
+#[derive(Debug)]
+pub struct IndexedNode<'a> {
+    node: &'a Entry,
+    link: EntryLink,
+}
+
+impl<'a> IndexedNode<'a> {
+
+    fn left(&self) -> Result<EntryLink, Error> {
+        self.node.left().map_err(|e| e.augment(self.link))
+    }
+
+    fn right(&self) -> Result<EntryLink, Error> {
+        self.node.right().map_err(|e| e.augment(self.link))
+    }
+
+    /// Reference to the entry struct.
+    pub fn node(&self) -> &Entry {
+        self.node
+    }
+
+    /// Reference to the entry metadata.
+    pub fn data(&self) -> &NodeData {
+        &self.node.data
+    }
+
+    /// Actual link by what this node was resolved.
+    pub fn link(&self) -> EntryLink {
+        self.link
+    }
+}
+
+fn combine_nodes<'a>(left: IndexedNode<'a>, right: IndexedNode<'a>) -> Entry {
+    Entry {
+        kind: EntryKind::Node(left.link, right.link),
+        data: NodeData::combine(&left.node.data, &right.node.data),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+
+    use super::{Entry, NodeData, Tree, EntryLink, EntryKind};
+    use quickcheck::{quickcheck, TestResult};
+    use assert_matches::assert_matches;
+
+    fn leaf(height: u32) -> NodeData {
+        NodeData {
+            consensus_branch_id: 1,
+            subtree_commitment: [0u8; 32],
+            start_time: 0,
+            end_time: 0,
+            start_target: 0,
+            end_target: 0,
+            start_sapling_root: [0u8; 32],
+            end_sapling_root: [0u8; 32],
+            subtree_total_work: 0.into(),
+            start_height: height as u64,
+            end_height: height as u64,
+            shielded_tx: 7,
+        }
+    }
+
+    fn initial() -> Tree {
+        let node1: Entry = leaf(1).into();
+        let node2: Entry = leaf(2).into();
+
+        let node3 = Entry {
+            data: NodeData::combine(&node1.data, &node2.data),
+            kind: EntryKind::Leaf,
+        };
+
+        Tree::populate(vec![node1, node2, node3], EntryLink::Stored(2))
+    }
+
+    // returns tree with specified number of leafs and it's root
+    fn generated(length: u32) -> Tree {
+        assert!(length >= 3);
+        let mut tree = initial();
+        for i in 2..length {
+            tree.append_leaf(leaf(i+1).into()).expect("Failed to append");
+        }
+
+        tree
+    }
+
+    #[test]
+    fn discrete_append() {
+        let mut tree = initial();
+
+        // ** APPEND 3 **
+        let appended = tree
+            .append_leaf(leaf(3))
+            .expect("Failed to append");
+        let new_root = tree.root_node().expect("Failed to resolve root").node;
+
+        // initial tree:  (2)
+        //               /   \
+        //             (0)   (1)
+        //
+        // new tree:
+        //                (4g)
+        //               /   \
+        //             (2)    \
+        //             /  \    \
+        //           (0)  (1)  (3)
+        //
+        // so only (3) is added as real leaf
+        // while new root, (4g) is generated one
+        assert_eq!(new_root.data.end_height, 3);
+        assert_eq!(appended.len(), 1);
+
+        // ** APPEND 4 **
+        let appended = tree
+            .append_leaf(leaf(4))
+            .expect("Failed to append");
+
+        let new_root = tree.root_node().expect("Failed to resolve root").node;
+
+        // intermediate tree:
+        //                (4g)
+        //               /   \
+        //             (2)    \
+        //             /  \    \
+        //           (0)  (1)  (3)
+        //
+        // new tree:
+        //                 ( 6 )
+        //                /     \
+        //             (2)       (5)
+        //             /  \     /   \
+        //           (0)  (1) (3)   (4)
+        //
+        // so (4), (5), (6) are added as real leaves
+        // and new root, (6) is stored one
+        assert_eq!(new_root.data.end_height, 4);
+        assert_eq!(appended.len(), 3);
+        assert_matches!(tree.root(), EntryLink::Stored(6));
+
+        // ** APPEND 5 **
+
+        let appended = tree
+            .append_leaf(leaf(5))
+            .expect("Failed to append");
+        let new_root = tree.root_node().expect("Failed to resolve root").node;
+
+        // intermediate tree:
+        //                 ( 6 )
+        //                /     \
+        //             (2)       (5)
+        //             /  \     /   \
+        //           (0)  (1) (3)   (4)
+        //
+        // new tree:
+        //                     ( 8g )
+        //                    /      \
+        //                 ( 6 )      \
+        //                /     \      \
+        //             (2)       (5)    \
+        //             /  \     /   \    \
+        //           (0)  (1) (3)   (4)  (7)
+        //
+        // so (7) is added as real leaf
+        // and new root, (8g) is generated one
+        assert_eq!(new_root.data.end_height, 5);
+        assert_eq!(appended.len(), 1);
+        assert_matches!(tree.root(), EntryLink::Generated(_));
+        tree.for_children(tree.root(), |l, r| {
+            assert_matches!(l, EntryLink::Stored(6));
+            assert_matches!(r, EntryLink::Stored(7));
+        });
+
+        // *** APPEND #6 ***
+        let appended = tree
+            .append_leaf(leaf(6))
+            .expect("Failed to append");
+        let new_root = tree.root_node().expect("Failed to resolve root").node;
+
+        // intermediate tree:
+        //                     ( 8g )
+        //                    /      \
+        //                 ( 6 )      \
+        //                /     \      \
+        //             (2)       (5)    \
+        //             /  \     /   \    \
+        //           (0)  (1) (3)   (4)  (7)
+        //
+        // new tree:
+        //                     (---10g--)
+        //                    /          \
+        //                 ( 6 )          \
+        //                /     \          \
+        //             (2)       (5)       (9)
+        //             /  \     /   \     /   \
+        //           (0)  (1) (3)   (4)  (7)  (8)
+        //
+        // so (7) is added as real leaf
+        // and new root, (10g) is generated one
+        assert_eq!(new_root.data.end_height, 6);
+        assert_eq!(appended.len(), 2);
+        assert_matches!(tree.root(), EntryLink::Generated(_));
+        tree.for_children(tree.root(), |l, r| {
+            assert_matches!(l, EntryLink::Stored(6));
+            assert_matches!(r, EntryLink::Stored(9));
+        });
+
+        // *** APPEND #7 ***
+
+        let appended = tree
+            .append_leaf(leaf(7))
+            .expect("Failed to append");
+        let new_root = tree
+            .root_node()
+            .expect("Failed to resolve root")
+            .node;
+
+        // intermediate tree:
+        //                     (---8g---)
+        //                    /          \
+        //                 ( 6 )          \
+        //                /     \          \
+        //             (2)       (5)       (9)
+        //             /  \     /   \     /   \
+        //           (0)  (1) (3)   (4)  (7)  (8)
+        //
+        // new tree:
+        //                          (---12g--)
+        //                         /          \
+        //                    (---11g---)      \
+        //                   /           \      \
+        //                 ( 6 )          \      \
+        //                /     \          \      \
+        //             (2)       (5)       (9)     \
+        //             /  \     /   \     /   \     \
+        //           (0)  (1) (3)   (4) (7)   (8)  (10)
+        //
+        // so (10) is added as real leaf
+        // and new root, (12g) is generated one
+        assert_eq!(new_root.data.end_height, 7);
+        assert_eq!(appended.len(), 1);
+        assert_matches!(tree.root(), EntryLink::Generated(_));
+        tree.for_children(tree.root(), |l, r| {
+            assert_matches!(l, EntryLink::Generated(_));
+            tree.for_children(l, |l, r|
+                assert_matches!((l, r), (EntryLink::Stored(6), EntryLink::Stored(9)))
+            );
+            assert_matches!(r, EntryLink::Stored(10));
+        });
+    }
+
+    #[test]
+    fn truncate_simple() {
+        let mut tree = generated(9);
+        let total_truncated = tree.truncate_leaf().expect("Failed to truncate");
+
+        // initial tree:
+        //
+        //                               (-------16g------)
+        //                              /                  \
+        //                    (--------14-------)           \
+        //                   /                   \           \
+        //                 ( 6 )              (  13  )        \
+        //                /     \            /        \        \
+        //             (2)       (5)       (9)        (12)      \
+        //             /  \     /   \     /   \      /    \      \
+        //           (0)  (1) (3)   (4) (7)   (8)  (10)  (11)    (15)
+        //
+        // new tree:
+        //                    (--------14-------)
+        //                   /                   \
+        //                 ( 6 )              (  13  )
+        //                /     \            /        \
+        //             (2)       (5)       (9)        (12)
+        //             /  \     /   \     /   \      /    \
+        //           (0)  (1) (3)   (4) (7)   (8)  (10)  (11)
+        //
+        // so (15) is truncated
+        // and new root, (14) is a stored one now
+
+        assert_matches!(tree.root(), EntryLink::Stored(14));
+        assert_eq!(total_truncated, 1);
+        assert_eq!(tree.len(), 15);
+    }
+
+    #[test]
+    fn truncate_generated() {
+        let mut tree = generated(10);
+        let deleted = tree.truncate_leaf().expect("Failed to truncate");
+
+        // initial tree:
+        //
+        //                               (--------18g--------)
+        //                              /                     \
+        //                    (--------14-------)              \
+        //                   /                   \              \
+        //                 ( 6 )              (  13  )           \
+        //                /     \            /        \           \
+        //             (2)       (5)       (9)        (12)        (17)
+        //             /  \     /   \     /   \      /    \      /    \
+        //           (0)  (1) (3)   (4) (7)   (8)  (10)  (11)  (15)  (16)
+        //
+        // new tree:
+        //                               (-------16g------)
+        //                              /                  \
+        //                    (--------14-------)           \
+        //                   /                   \           \
+        //                 ( 6 )              (  13  )        \
+        //                /     \            /        \        \
+        //             (2)       (5)       (9)        (12)      \
+        //             /  \     /   \     /   \      /    \      \
+        //           (0)  (1) (3)   (4) (7)   (8)  (10)  (11)    (15)
+
+        // new root is generated
+
+        assert_matches!(tree.root(), EntryLink::Generated(_));
+
+        tree.for_children(tree.root(),|left, right|
+            assert_matches!(
+                (left, right),
+                (EntryLink::Stored(14), EntryLink::Stored(15))
+            )
+        );
+
+        // two stored nodes should leave us (leaf 16 and no longer needed node 17)
+        assert_eq!(deleted, 2);
+        assert_eq!(tree.len(), 16);
+    }
+
+    #[test]
+    fn tree_len() {
+        let mut tree = initial();
+
+        assert_eq!(tree.len(), 3);
+
+        for i in 0..2 {
+            tree.append_leaf(leaf(i+3)).expect("Failed to append");
+        }
+        assert_eq!(tree.len(), 7);
+
+        tree.truncate_leaf().expect("Failed to truncate");
+
+        assert_eq!(tree.len(), 4);
+    }
+
+    #[test]
+    fn tree_len_long() {
+        let mut tree = initial();
+
+        assert_eq!(tree.len(), 3);
+
+        for i in 0..4094 {
+            tree.append_leaf(leaf(i+3)).expect("Failed to append");
+        }
+        assert_eq!(tree.len(), 8191); // 4096*2-1 (full tree)
+
+        for _ in 0..2049 {
+            tree.truncate_leaf().expect("Failed to truncate");
+        }
+
+        assert_eq!(tree.len(), 4083); // 4095 - log2(4096)
+    }
+
+
+    quickcheck! {
+        fn there_and_back(number: u32) -> TestResult {
+            if number > 1024*1024 {
+                TestResult::discard()
+            } else {
+                let mut tree = initial();
+                for i in 0..number {
+                    tree.append_leaf(leaf(i+3)).expect("Failed to append");
+                }
+                for _ in 0..number {
+                    tree.truncate_leaf().expect("Failed to truncate");
+                }
+
+                TestResult::from_bool(if let EntryLink::Stored(2) = tree.root() { true } else { false })
+            }
+        }
+
+        fn leaf_count(number: u32) -> TestResult {
+            if number > 1024 * 1024 || number < 3 {
+                TestResult::discard()
+            } else {
+                let mut tree = initial();
+                for i in 1..(number-1) {
+                    tree.append_leaf(leaf(i+2)).expect("Failed to append");
+                }
+
+                TestResult::from_bool(
+                    tree.root_node().expect("no root").node.leaf_count() == number as u64
+                )
+            }
+        }
+
+        fn parity(number: u32) -> TestResult {
+            if number > 2048 * 2048 || number < 3 {
+                TestResult::discard()
+            } else {
+                let mut tree = initial();
+                for i in 1..(number-1) {
+                    tree.append_leaf(leaf(i+2)).expect("Failed to append");
+                }
+
+                TestResult::from_bool(
+                    if number & (number - 1) == 0 {
+                        if let EntryLink::Stored(_) = tree.root() { true }
+                        else { false }
+                    } else {
+                        if let EntryLink::Generated(_) = tree.root() { true }
+                        else { false }
+                    }
+                )
+            }
+        }
+
+        fn parity_with_truncate(add: u32, delete: u32) -> TestResult {
+            // First we add `add` number of leaves, then delete `delete` number of leaves
+            // What is left should be consistent with generated-stored structure
+            if add > 2048 * 2048 || add < delete {
+                TestResult::discard()
+            } else {
+                let mut tree = initial();
+                for i in 0..add {
+                    tree.append_leaf(leaf(i+3)).expect("Failed to append");
+                }
+                for _ in 0..delete {
+                    tree.truncate_leaf().expect("Failed to truncate");
+                }
+
+                let total = add - delete + 2;
+
+                TestResult::from_bool(
+                    if total & total - 1 == 0 {
+                        if let EntryLink::Stored(_) = tree.root() { true }
+                        else { false }
+                    } else {
+                        if let EntryLink::Generated(_) = tree.root() { true }
+                        else { false }
+                    }
+                )
+            }
+        }
+
+        // Length of tree is always less than number of leaves squared
+        fn stored_length(add: u32, delete: u32) -> TestResult {
+            if add > 2048 * 2048 || add < delete {
+                TestResult::discard()
+            } else {
+                let mut tree = initial();
+                for i in 0..add {
+                    tree.append_leaf(leaf(i+3)).expect("Failed to append");
+                }
+                for _ in 0..delete {
+                    tree.truncate_leaf().expect("Failed to truncate");
+                }
+
+                let total = add - delete + 2;
+
+                TestResult::from_bool(total * total > tree.len())
+            }
+        }
+    }
+}