feat: various helper functions and fixes for platform contested resources PR

costs/src/lib.rs

@@ -93,6 +93,11 @@ pub struct OperationCost {
 }
 
 impl OperationCost {
+    /// Is Nothing
+    pub fn is_nothing(&self) -> bool {
+        self == &Self::default()
+    }
+
     /// Helper function to build default `OperationCost` with different
     /// `seek_count`.
     pub fn with_seek_count(seek_count: u16) -> Self {

grovedb/src/element/get.rs

@@ -59,8 +59,12 @@ impl Element {
             let value = result?;
             value.ok_or_else(|| {
                 Error::PathKeyNotFound(format!(
-                    "key not found in Merk for get: {}",
-                    hex::encode(key)
+                    "get: key \"{}\" not found in Merk that has a root key [{}] and is of type {}",
+                    hex::encode(key),
+                    merk.root_key()
+                        .map(|key| hex::encode(key))
+                        .unwrap_or("None".to_string()),
+                    merk.merk_type
                 ))
             })
         })

grovedb/src/element/helpers.rs

@@ -43,12 +43,13 @@ use grovedb_merk::{
 #[cfg(feature = "full")]
 use integer_encoding::VarInt;
 
+#[cfg(any(feature = "full", feature = "verify"))]
+use crate::reference_path::{path_from_reference_path_type, ReferencePathType};
 #[cfg(any(feature = "full", feature = "verify"))]
 use crate::{element::SUM_ITEM_COST_SIZE, Element, Error};
 #[cfg(feature = "full")]
 use crate::{
     element::{SUM_TREE_COST_SIZE, TREE_COST_SIZE},
-    reference_path::{path_from_reference_path_type, ReferencePathType},
     ElementFlags,
 };
 
@@ -64,15 +65,41 @@ impl Element {
     }
 
     #[cfg(any(feature = "full", feature = "verify"))]
-    /// Decoded the integer value in the SumItem element type, returns 0 for
-    /// everything else
+    /// Decoded the integer value in the SumItem element type
     pub fn as_sum_item_value(&self) -> Result<i64, Error> {
         match self {
             Element::SumItem(value, _) => Ok(*value),
             _ => Err(Error::WrongElementType("expected a sum item")),
         }
     }
 
+    #[cfg(any(feature = "full", feature = "verify"))]
+    /// Decoded the integer value in the SumItem element type
+    pub fn into_sum_item_value(self) -> Result<i64, Error> {
+        match self {
+            Element::SumItem(value, _) => Ok(value),
+            _ => Err(Error::WrongElementType("expected a sum item")),
+        }
+    }
+
+    #[cfg(any(feature = "full", feature = "verify"))]
+    /// Decoded the integer value in the SumTree element type
+    pub fn as_sum_tree_value(&self) -> Result<i64, Error> {
+        match self {
+            Element::SumTree(_, value, _) => Ok(*value),
+            _ => Err(Error::WrongElementType("expected a sum tree")),
+        }
+    }
+
+    #[cfg(any(feature = "full", feature = "verify"))]
+    /// Decoded the integer value in the SumTree element type
+    pub fn into_sum_tree_value(self) -> Result<i64, Error> {
+        match self {
+            Element::SumTree(_, value, _) => Ok(value),
+            _ => Err(Error::WrongElementType("expected a sum tree")),
+        }
+    }
+
     #[cfg(any(feature = "full", feature = "verify"))]
     /// Gives the item value in the Item element type
     pub fn as_item_bytes(&self) -> Result<&[u8], Error> {
@@ -91,6 +118,15 @@ impl Element {
         }
     }
 
+    #[cfg(any(feature = "full", feature = "verify"))]
+    /// Gives the reference path type in the Reference element type
+    pub fn into_reference_path_type(self) -> Result<ReferencePathType, Error> {
+        match self {
+            Element::Reference(value, ..) => Ok(value),
+            _ => Err(Error::WrongElementType("expected a reference")),
+        }
+    }
+
     #[cfg(any(feature = "full", feature = "verify"))]
     /// Check if the element is a sum tree
     pub fn is_sum_tree(&self) -> bool {
@@ -103,6 +139,12 @@ impl Element {
         matches!(self, Element::SumTree(..) | Element::Tree(..))
     }
 
+    #[cfg(any(feature = "full", feature = "verify"))]
+    /// Check if the element is a reference
+    pub fn is_reference(&self) -> bool {
+        matches!(self, Element::Reference(..))
+    }
+
     #[cfg(any(feature = "full", feature = "verify"))]
     /// Check if the element is an item
     pub fn is_item(&self) -> bool {

grovedb/src/element/query.rs

@@ -53,7 +53,7 @@ use crate::{
             QueryPathKeyElementTrioResultType,
         },
     },
-    util::{merk_optional_tx, storage_context_optional_tx},
+    util::{merk_optional_tx, merk_optional_tx_internal_error, storage_context_optional_tx},
     Error, PathQuery, TransactionArg,
 };
 #[cfg(any(feature = "full", feature = "verify"))]
@@ -563,7 +563,7 @@ impl Element {
         if !item.is_range() {
             // this is a query on a key
             if let QueryItem::Key(key) = item {
-                let element_res = merk_optional_tx!(
+                let element_res = merk_optional_tx_internal_error!(
                     &mut cost,
                     storage,
                     subtree_path,

grovedb/src/lib.rs

@@ -164,7 +164,6 @@ pub mod replication;
 mod tests;
 #[cfg(feature = "full")]
 mod util;
-#[cfg(any(feature = "full", feature = "verify"))]
 mod versioning;
 #[cfg(feature = "full")]
 mod visualize;

grovedb/src/operations.rs

@@ -40,3 +40,6 @@ pub mod insert;
 pub(crate) mod is_empty_tree;
 #[cfg(any(feature = "full", feature = "verify"))]
 pub mod proof;
+
+#[cfg(feature = "full")]
+pub use get::{QueryItemOrSumReturnType, MAX_REFERENCE_HOPS};

grovedb/src/operations/get/mod.rs

@@ -32,6 +32,8 @@
 mod average_case;
 #[cfg(feature = "full")]
 mod query;
+#[cfg(feature = "full")]
+pub use query::QueryItemOrSumReturnType;
 #[cfg(feature = "estimated_costs")]
 mod worst_case;
 

grovedb/src/operations/get/query.rs

@@ -36,6 +36,8 @@ use grovedb_costs::{
 #[cfg(feature = "full")]
 use integer_encoding::VarInt;
 
+#[cfg(feature = "full")]
+use crate::element::SumValue;
 use crate::{element::QueryOptions, query_result_type::PathKeyOptionalElementTrio};
 #[cfg(feature = "full")]
 use crate::{
@@ -44,6 +46,16 @@ use crate::{
     Element, Error, GroveDb, PathQuery, TransactionArg,
 };
 
+#[cfg(feature = "full")]
+#[derive(Debug, Eq, PartialEq, Clone)]
+/// A return type for query_item_value_or_sum
+pub enum QueryItemOrSumReturnType {
+    /// an Item in serialized form
+    ItemData(Vec<u8>),
+    /// A sum item or a sum tree value
+    SumValue(SumValue),
+}
+
 #[cfg(feature = "full")]
 impl GroveDb {
     /// Encoded query for multiple path queries
@@ -190,10 +202,8 @@ where {
                     )),
                 }
             }
-            Element::Item(..) | Element::SumItem(..) => Ok(element),
-            Element::Tree(..) | Element::SumTree(..) => Err(Error::InvalidQuery(
-                "path_queries can only refer to items and references",
-            )),
+            Element::Item(..) | Element::SumItem(..) | Element::SumTree(..) => Ok(element),
+            Element::Tree(..) => Err(Error::InvalidQuery("path_queries can not refer to trees")),
         }
     }
 
@@ -309,6 +319,94 @@ where {
         Ok((results, skipped)).wrap_with_cost(cost)
     }
 
+    /// Queries the backing store and returns element items by their value,
+    /// Sum Items are returned
+    pub fn query_item_value_or_sum(
+        &self,
+        path_query: &PathQuery,
+        allow_cache: bool,
+        decrease_limit_on_range_with_no_sub_elements: bool,
+        error_if_intermediate_path_tree_not_present: bool,
+        transaction: TransactionArg,
+    ) -> CostResult<(Vec<QueryItemOrSumReturnType>, u16), Error> {
+        let mut cost = OperationCost::default();
+
+        let (elements, skipped) = cost_return_on_error!(
+            &mut cost,
+            self.query_raw(
+                path_query,
+                allow_cache,
+                decrease_limit_on_range_with_no_sub_elements,
+                error_if_intermediate_path_tree_not_present,
+                QueryResultType::QueryElementResultType,
+                transaction
+            )
+        );
+
+        let results_wrapped = elements
+            .into_iterator()
+            .map(|result_item| match result_item {
+                QueryResultElement::ElementResultItem(element) => {
+                    match element {
+                        Element::Reference(reference_path, ..) => {
+                            match reference_path {
+                                ReferencePathType::AbsolutePathReference(absolute_path) => {
+                                    // While `map` on iterator is lazy, we should accumulate costs
+                                    // even if `collect` will
+                                    // end in `Err`, so we'll use
+                                    // external costs accumulator instead of
+                                    // returning costs from `map` call.
+                                    let maybe_item = self
+                                        .follow_reference(
+                                            absolute_path.as_slice().into(),
+                                            allow_cache,
+                                            transaction,
+                                        )
+                                        .unwrap_add_cost(&mut cost)?;
+
+                                    match maybe_item {
+                                        Element::Item(item, _) => {
+                                            Ok(QueryItemOrSumReturnType::ItemData(item))
+                                        }
+                                        Element::SumItem(sum_value, _) => {
+                                            Ok(QueryItemOrSumReturnType::SumValue(sum_value))
+                                        }
+                                        Element::SumTree(_, sum_value, _) => {
+                                            Ok(QueryItemOrSumReturnType::SumValue(sum_value))
+                                        }
+                                        _ => Err(Error::InvalidQuery(
+                                            "the reference must result in an item",
+                                        )),
+                                    }
+                                }
+                                _ => Err(Error::CorruptedCodeExecution(
+                                    "reference after query must have absolute paths",
+                                )),
+                            }
+                        }
+                        Element::Item(item, _) => Ok(QueryItemOrSumReturnType::ItemData(item)),
+                        Element::SumItem(sum_value, _) => {
+                            Ok(QueryItemOrSumReturnType::SumValue(sum_value))
+                        }
+                        Element::SumTree(_, sum_value, _) => {
+                            Ok(QueryItemOrSumReturnType::SumValue(sum_value))
+                        }
+                        Element::Tree(..) => Err(Error::InvalidQuery(
+                            "path_queries can only refer to items, sum items, references and sum \
+                             trees",
+                        )),
+                    }
+                }
+                _ => Err(Error::CorruptedCodeExecution(
+                    "query returned incorrect result type",
+                )),
+            })
+            .collect::<Result<Vec<QueryItemOrSumReturnType>, Error>>();
+
+        let results = cost_return_on_error_no_add!(&cost, results_wrapped);
+        Ok((results, skipped)).wrap_with_cost(cost)
+    }
+
     /// Retrieves only SumItem elements that match a path query
     pub fn query_sums(
         &self,

grovedb/src/operations/proof/util.rs

@@ -38,9 +38,9 @@
 #[cfg(any(feature = "full", feature = "verify"))]
 use integer_encoding::{VarInt, VarIntReader};
 
-use crate::operations::proof::verify::ProvedKeyValues;
 #[cfg(any(feature = "full", feature = "verify"))]
 use crate::Error;
+use crate::{operations::proof::verify::ProvedKeyValues, reference_path::ReferencePathType};
 
 #[cfg(any(feature = "full", feature = "verify"))]
 pub const EMPTY_TREE_HASH: [u8; 32] = [0; 32];

grovedb/src/query_result_type.rs

@@ -187,6 +187,85 @@ impl QueryResultElements {
             })
             .collect()
     }
+
+    /// To last path to keys btree map
+    /// This is useful if for example the element is a sum item and isn't
+    /// important Used in Platform Drive for getting voters for multiple
+    /// contenders
+    pub fn to_last_path_to_keys_btree_map(self) -> BTreeMap<Key, Vec<Key>> {
+        let mut map: BTreeMap<Vec<u8>, Vec<Key>> = BTreeMap::new();
+
+        for result_item in self.elements.into_iter() {
+            if let QueryResultElement::PathKeyElementTrioResultItem((mut path, key, _)) =
+                result_item
+            {
+                if let Some(last) = path.pop() {
+                    map.entry(last).or_insert_with(Vec::new).push(key);
+                }
+            }
+        }
+
+        map
+    }
+
+    /// To last path to key, elements btree map
+    pub fn to_last_path_to_key_elements_btree_map(self) -> BTreeMap<Key, BTreeMap<Key, Element>> {
+        let mut map: BTreeMap<Vec<u8>, BTreeMap<Key, Element>> = BTreeMap::new();
+
+        for result_item in self.elements.into_iter() {
+            if let QueryResultElement::PathKeyElementTrioResultItem((mut path, key, element)) =
+                result_item
+            {
+                if let Some(last) = path.pop() {
+                    map.entry(last)
+                        .or_insert_with(BTreeMap::new)
+                        .insert(key, element);
+                }
+            }
+        }
+
+        map
+    }
+
+    /// To last path to elements btree map
+    /// This is useful if the key is not import
+    pub fn to_last_path_to_elements_btree_map(self) -> BTreeMap<Key, Vec<Element>> {
+        let mut map: BTreeMap<Vec<u8>, Vec<Element>> = BTreeMap::new();
+
+        for result_item in self.elements.into_iter() {
+            if let QueryResultElement::PathKeyElementTrioResultItem((mut path, _, element)) =
+                result_item
+            {
+                if let Some(last) = path.pop() {
+                    map.entry(last).or_insert_with(Vec::new).push(element);
+                }
+            }
+        }
+
+        map
+    }
+
+    /// To last path to keys btree map
+    /// This is useful if for example the element is a sum item and isn't
+    /// important Used in Platform Drive for getting voters for multiple
+    /// contenders
+    pub fn to_previous_of_last_path_to_keys_btree_map(self) -> BTreeMap<Key, Vec<Key>> {
+        let mut map: BTreeMap<Vec<u8>, Vec<Key>> = BTreeMap::new();
+
+        for result_item in self.elements.into_iter() {
+            if let QueryResultElement::PathKeyElementTrioResultItem((mut path, key, _)) =
+                result_item
+            {
+                if let Some(_) = path.pop() {
+                    if let Some(last) = path.pop() {
+                        map.entry(last).or_insert_with(Vec::new).push(key);
+                    }
+                }
+            }
+        }
+
+        map
+    }
 }
 
 impl Default for QueryResultElements {