From 41780f3a0eafba77098307587f6f385820a1dd64 Mon Sep 17 00:00:00 2001 From: BGluth Date: Fri, 2 Feb 2024 10:11:07 -0700 Subject: [PATCH] Added documentation for the debug tooling --- src/debug_tools/diff.rs | 36 +++++++++++++++++++++++++++++++++++- src/debug_tools/mod.rs | 3 +++ src/debug_tools/query.rs | 15 ++++++++------- 3 files changed, 46 insertions(+), 8 deletions(-) diff --git a/src/debug_tools/diff.rs b/src/debug_tools/diff.rs index 570860b..04cc48c 100644 --- a/src/debug_tools/diff.rs +++ b/src/debug_tools/diff.rs @@ -1,3 +1,30 @@ +//! Diffing tools to compare two tries against each other. Useful when you want +//! to find where the tries diverge from one other. +//! +//! There are a few considerations when implementing the logic to create a trie +//! diff: +//! - What should be reported when the trie node structures diverge (eg. two +//! different node types proceeding a given common node)? +//! - If there are multiple structural differences, how do we discover the +//! smallest difference to report back? +//! +//! If the node types between the tries (structure) are identical but some +//! values are different, then these types of diffs are easy to detect and +//! report the lowest difference. Structural differences are more challenging +//! and a bit hard to report well. There are two approaches (only one currently +//! is implemented) in how to detect structural differences: +//! - Top-down search +//! - Bottom-up search +//! +//! These two searches are somewhat self-explanatory: +//! - Top-down will find the highest point of a structural divergence and report +//! it. If there are multiple divergences, then only the one that is the +//! highest in the trie will be reported. +//! - Bottom-up (not implemented) is a lot more complex to implement, but will +//! attempt to find the smallest structural trie difference between the trie. +//! If there are multiple differences, then this will likely be what you want +//! to use. + use std::fmt::{self, Debug}; use std::{fmt::Display, ops::Deref}; @@ -53,6 +80,7 @@ impl DiffDetectionState { } } +/// A point (node) between the two tries where the children differ. #[derive(Clone, Debug, Eq, Hash, PartialEq)] pub struct DiffPoint { pub depth: usize, @@ -82,6 +110,7 @@ impl DiffPoint { } } +// TODO: Redo display method so this is more readable... impl Display for DiffPoint { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "Point Diff {{depth: {}, ", self.depth)?; @@ -92,6 +121,7 @@ impl Display for DiffPoint { } } +/// Meta information for a node in a trie. #[derive(Clone, Debug, Eq, Hash, PartialEq)] pub struct NodeInfo { key: Nibbles, @@ -103,6 +133,7 @@ pub struct NodeInfo { hash: H256, } +// TODO: Redo display method so this is more readable... impl Display for NodeInfo { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "(key: {:x} ", self.key)?; @@ -128,6 +159,8 @@ impl NodeInfo { } } +/// Create a diff between two tries. Will perform both types of diff searches +/// (top-down & bottom-up). pub fn create_diff_between_tries(a: &HashedPartialTrie, b: &HashedPartialTrie) -> TrieDiff { TrieDiff { latest_diff_res: find_latest_diff_point_where_tries_begin_to_diff(a, b), @@ -198,7 +231,7 @@ impl DepthNodeDiffState { } } -// State that is copied per recursive call. +/// State that is copied per recursive call. #[derive(Clone, Debug)] struct DepthDiffPerCallState<'a> { a: &'a HashedPartialTrie, @@ -429,6 +462,7 @@ mod tests { assert_eq!(diff.latest_diff_res, Some(expected)); } + // TODO: Will finish these tests later (low-priority). #[test] #[ignore] fn depth_single_node_node_diffs_work() { diff --git a/src/debug_tools/mod.rs b/src/debug_tools/mod.rs index 7e49ab1..c05eb26 100644 --- a/src/debug_tools/mod.rs +++ b/src/debug_tools/mod.rs @@ -1,3 +1,6 @@ +//! Additional methods that may be useful when diagnosing tries from this +//! library. + pub mod common; pub mod diff; pub mod query; diff --git a/src/debug_tools/query.rs b/src/debug_tools/query.rs index e370d39..63ede35 100644 --- a/src/debug_tools/query.rs +++ b/src/debug_tools/query.rs @@ -1,3 +1,6 @@ +//! Query tooling to report info on the path taken when searching down a trie +//! with a given key. + use std::fmt::{self, Display}; use ethereum_types::H256; @@ -10,6 +13,7 @@ use crate::{ partial_trie::{Node, PartialTrie, WrappedNode}, }; +/// Params controlling how much information is reported in the query output. #[derive(Clone, Debug)] pub struct DebugQueryParams { include_key_piece_per_node: bool, @@ -59,6 +63,7 @@ impl DebugQueryParamsBuilder { } } +/// The payload to give to the query function. Construct this from the builder. #[derive(Debug)] pub struct DebugQuery { k: Nibbles, @@ -185,6 +190,7 @@ impl DebugQueryOutput { } } + // TODO: Make the output easier to read... fn fmt_query_header(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { writeln!(f, "Query Result {{")?; @@ -194,6 +200,7 @@ impl DebugQueryOutput { writeln!(f, "}}") } + // TODO: Make the output easier to read... fn fmt_node_based_on_debug_params( f: &mut fmt::Formatter<'_>, seg: &PathSegment, @@ -230,6 +237,7 @@ impl DebugQueryOutput { } } +/// Get debug information on the path taken when querying a key in a given trie. pub fn get_path_from_query>( trie: &Node, q: Q, @@ -248,9 +256,6 @@ fn get_path_from_query_rec( query_out: &mut DebugQueryOutput, ) { let key_piece = get_key_piece_from_node(node, curr_key); - - println!("key piece: {:x}", key_piece); - let seg = get_segment_from_node_and_key_piece(node, &key_piece); query_out.node_path.append(seg); @@ -263,10 +268,6 @@ fn get_path_from_query_rec( Node::Branch { children, value: _ } => { let nib = curr_key.pop_next_nibble_front(); - println!("NIB: {:x}", nib); - - // println!("CHILDREN: {:#?}", children); - get_path_from_query_rec(&children[nib as usize], curr_key, query_out) } Node::Extension { nibbles, child } => {