Enum Element 

pub enum Element {
    Item(Vec<u8>, Option<Vec<u8>>),
    Reference(ReferencePathType, Option<u8>, Option<Vec<u8>>),
    Tree(Option<Vec<u8>>, Option<Vec<u8>>),
    SumItem(i64, Option<Vec<u8>>),
    SumTree(Option<Vec<u8>>, i64, Option<Vec<u8>>),
    BigSumTree(Option<Vec<u8>>, i128, Option<Vec<u8>>),
    CountTree(Option<Vec<u8>>, u64, Option<Vec<u8>>),
    CountSumTree(Option<Vec<u8>>, u64, i64, Option<Vec<u8>>),
    ProvableCountTree(Option<Vec<u8>>, u64, Option<Vec<u8>>),
    ItemWithSumItem(Vec<u8>, i64, Option<Vec<u8>>),
    ProvableCountSumTree(Option<Vec<u8>>, u64, i64, Option<Vec<u8>>),
    CommitmentTree(u64, u8, Option<Vec<u8>>),
    MmrTree(u64, Option<Vec<u8>>),
    BulkAppendTree(u64, u8, Option<Vec<u8>>),
    DenseAppendOnlyFixedSizeTree(u16, u8, Option<Vec<u8>>),
    NonCounted(Box<Element>),
    NotSummed(Box<Element>),
}

Variants of GroveDB stored entities

ONLY APPEND TO THIS LIST!!! Because of how serialization works.

serde::Deserialize is implemented manually (under the serde feature) so it can enforce the same wrapper invariants as Element::deserialize: NonCounted and NotSummed may not nest in any combination, and NotSummed may only wrap a sum-tree variant. serde::Serialize is derived; serialization of valid Element values is always safe.

Variants

Item(Vec<u8>, Option<Vec<u8>>)

An ordinary value

Reference(ReferencePathType, Option<u8>, Option<Vec<u8>>)

A reference to an object by its path

Tree(Option<Vec<u8>>, Option<Vec<u8>>)

A subtree, contains the prefixed key representing the root of the subtree.

SumItem(i64, Option<Vec<u8>>)

Signed integer value that can be totaled in a sum tree

SumTree(Option<Vec<u8>>, i64, Option<Vec<u8>>)

Same as Element::Tree but underlying Merk sums value of it’s summable nodes

BigSumTree(Option<Vec<u8>>, i128, Option<Vec<u8>>)

Same as Element::Tree but underlying Merk sums value of it’s summable nodes in big form i128 The big sum tree is valuable if you have a big sum tree of sum trees

CountTree(Option<Vec<u8>>, u64, Option<Vec<u8>>)

Same as Element::Tree but underlying Merk counts value of its countable nodes

CountSumTree(Option<Vec<u8>>, u64, i64, Option<Vec<u8>>)

Combines Element::SumTree and Element::CountTree

ProvableCountTree(Option<Vec<u8>>, u64, Option<Vec<u8>>)

Same as Element::CountTree but includes counts in cryptographic state

ItemWithSumItem(Vec<u8>, i64, Option<Vec<u8>>)

An ordinary value with a sum value

ProvableCountSumTree(Option<Vec<u8>>, u64, i64, Option<Vec<u8>>)

Same as Element::CountSumTree but includes counts in cryptographic state (sum is tracked but NOT included in hash, only count is)

CommitmentTree(u64, u8, Option<Vec<u8>>)

Orchard-style commitment tree: combines a BulkAppendTree (for efficient append-only storage of cmx||encrypted_note payloads with epoch compaction) and a Sinsemilla Frontier (for anchor computation). Items are stored in the data namespace via BulkAppendTree; the frontier is stored in data storage.

Fields: (total_count, chunk_power, flags)

• total_count: Number of notes appended so far.
• chunk_power: Log2 of the chunk size (actual size = 1 << chunk_power).
• flags: Optional per-element metadata.

The Sinsemilla frontier root hash is not stored in the Element; it is persisted in data storage and verified by opening the frontier. The BulkAppendTree state_root flows as the Merk child hash.

MmrTree(u64, Option<Vec<u8>>)

MMR (Merkle Mountain Range) tree: append-only authenticated data structure with zero rotations, O(N) total hashes, sequential I/O.

The MMR root hash is stored as the Merk child hash (not in the Element).

Fields: (mmr_size, flags)

• mmr_size: Total number of MMR nodes (internal + leaves).
• flags: Optional per-element metadata.

BulkAppendTree(u64, u8, Option<Vec<u8>>)

Bulk-append tree: two-level structure with a dense Merkle buffer that compacts into chunk blobs stored in an MMR.

Fields: (total_count, chunk_power, flags)

• total_count: Number of items appended so far.
• chunk_power: Log2 of the chunk size (actual size = 1 << chunk_power).
• flags: Optional per-element metadata.

The state root (blake3(mmr_root || buffer_hash)) flows through the Merk child hash mechanism (insert_subtree’s subtree_root_hash parameter).

DenseAppendOnlyFixedSizeTree(u16, u8, Option<Vec<u8>>)

Dense fixed-sized Merkle tree: a complete binary tree of height h with 2^h - 1 positions. Nodes are filled sequentially in level-order (BFS). Root hash flows through the Merk child hash mechanism (insert_subtree’s subtree_root_hash parameter).

Fields: (count, height, flags)

• count: Number of values inserted so far.
• height: Tree height h; the tree has 2^h - 1 positions.
• flags: Optional per-element metadata.

NonCounted(Box<Element>)

Non-counted wrapper: contains any other Element type and behaves identically to it for storage, hashing, and internal aggregation, but contributes 0 to its parent count tree’s aggregate count when inserted. Sums still propagate to parent sum trees.

May only be inserted into count-bearing trees (CountTree, ProvableCountTree, CountSumTree, ProvableCountSumTree).

Invariant: a NonCounted may not wrap another NonCounted. Enforced at construction and at deserialization.

NotSummed(Box<Element>)

Not-summed wrapper: contains a sum-bearing tree variant (SumTree, BigSumTree, CountSumTree, ProvableCountSumTree) and behaves identically to it for storage, hashing, and its own internal sum aggregate, but contributes 0 to its parent sum tree’s running sum when inserted. Counts still propagate.

May only be inserted into sum-bearing trees (SumTree, BigSumTree, CountSumTree, ProvableCountSumTree).

Invariants (enforced at construction, serialization, and deserialization):

• The inner element MUST be one of the four sum-tree variants above.
• A NotSummed may not wrap another NotSummed, a NonCounted, or any non-tree element.

Implementations

impl Element

pub fn empty_tree() -> Element

Set element to default empty tree without flags

pub fn empty_tree_with_flags(flags: Option<Vec<u8>>) -> Element

Set element to default empty tree with flags

pub fn empty_sum_tree() -> Element

Set element to default empty sum tree without flags

pub fn empty_big_sum_tree() -> Element

Set element to default empty big sum tree without flags

pub fn empty_count_tree() -> Element

Set element to default empty count tree without flags

pub fn empty_count_sum_tree() -> Element

Set element to default empty count sum tree without flags

pub fn empty_sum_tree_with_flags(flags: Option<Vec<u8>>) -> Element

Set element to default empty sum tree with flags

pub fn empty_big_sum_tree_with_flags(flags: Option<Vec<u8>>) -> Element

Set element to default empty sum tree with flags

pub fn empty_count_tree_with_flags(flags: Option<Vec<u8>>) -> Element

Set element to default empty count tree with flags

pub fn empty_count_sum_tree_with_flags(flags: Option<Vec<u8>>) -> Element

Set element to default empty count sum tree with flags

pub fn new_item(item_value: Vec<u8>) -> Element

Set element to an item without flags

pub fn new_item_with_flags( item_value: Vec<u8>, flags: Option<Vec<u8>>, ) -> Element

Set element to an item with flags

pub fn new_sum_item(value: i64) -> Element

Set element to a sum item without flags

pub fn new_sum_item_with_flags(value: i64, flags: Option<Vec<u8>>) -> Element

Set element to a sum item with flags

pub fn new_item_with_sum_item(item_value: Vec<u8>, sum_value: i64) -> Element

Set element to an item with sum value (no flags)

pub fn new_item_with_sum_item_with_flags( item_value: Vec<u8>, sum_value: i64, flags: Option<Vec<u8>>, ) -> Element

Set element to an item with sum value and flags

pub fn new_reference(reference_path: ReferencePathType) -> Element

Set element to a reference without flags

pub fn new_reference_with_flags( reference_path: ReferencePathType, flags: Option<Vec<u8>>, ) -> Element

Set element to a reference with flags

pub fn new_reference_with_hops( reference_path: ReferencePathType, max_reference_hop: Option<u8>, ) -> Element

Set element to a reference with hops, no flags

pub fn new_reference_with_max_hops_and_flags( reference_path: ReferencePathType, max_reference_hop: Option<u8>, flags: Option<Vec<u8>>, ) -> Element

Set element to a reference with max hops and flags

pub fn new_tree(maybe_root_key: Option<Vec<u8>>) -> Element

Set element to a tree without flags

pub fn new_tree_with_flags( maybe_root_key: Option<Vec<u8>>, flags: Option<Vec<u8>>, ) -> Element

Set element to a tree with flags

pub fn new_sum_tree(maybe_root_key: Option<Vec<u8>>) -> Element

Set element to a sum tree without flags

pub fn new_sum_tree_with_flags( maybe_root_key: Option<Vec<u8>>, flags: Option<Vec<u8>>, ) -> Element

Set element to a sum tree with flags

pub fn new_sum_tree_with_flags_and_sum_value( maybe_root_key: Option<Vec<u8>>, sum_value: i64, flags: Option<Vec<u8>>, ) -> Element

Set element to a sum tree with flags and sum value

pub fn new_big_sum_tree(maybe_root_key: Option<Vec<u8>>) -> Element

Set element to a big sum tree without flags

pub fn new_big_sum_tree_with_flags( maybe_root_key: Option<Vec<u8>>, flags: Option<Vec<u8>>, ) -> Element

Set element to a big sum tree with flags

pub fn new_big_sum_tree_with_flags_and_sum_value( maybe_root_key: Option<Vec<u8>>, big_sum_value: i128, flags: Option<Vec<u8>>, ) -> Element

Set element to a big sum tree with flags and sum value

pub fn new_count_tree(maybe_root_key: Option<Vec<u8>>) -> Element

Set element to a count tree without flags

pub fn new_count_tree_with_flags( maybe_root_key: Option<Vec<u8>>, flags: Option<Vec<u8>>, ) -> Element

Set element to a count tree with flags

pub fn new_count_tree_with_flags_and_count_value( maybe_root_key: Option<Vec<u8>>, count_value: u64, flags: Option<Vec<u8>>, ) -> Element

Set element to a count tree with flags and sum value

pub fn new_count_sum_tree(maybe_root_key: Option<Vec<u8>>) -> Element

Set element to a count sum tree without flags

pub fn new_count_sum_tree_with_flags( maybe_root_key: Option<Vec<u8>>, flags: Option<Vec<u8>>, ) -> Element

Set element to a count sum tree with flags

pub fn new_count_sum_tree_with_flags_and_sum_and_count_value( maybe_root_key: Option<Vec<u8>>, count_value: u64, sum_value: i64, flags: Option<Vec<u8>>, ) -> Element

Set element to a count sum tree with flags and sum value

pub fn empty_provable_count_tree() -> Element

Set element to default empty provable count tree without flags

pub fn empty_provable_count_tree_with_flags(flags: Option<Vec<u8>>) -> Element

Set element to default empty provable count tree with flags

pub fn new_provable_count_tree(maybe_root_key: Option<Vec<u8>>) -> Element

Set element to a provable count tree without flags

pub fn new_provable_count_tree_with_flags( maybe_root_key: Option<Vec<u8>>, flags: Option<Vec<u8>>, ) -> Element

Set element to a provable count tree with flags

pub fn new_provable_count_tree_with_flags_and_count_value( maybe_root_key: Option<Vec<u8>>, count_value: u64, flags: Option<Vec<u8>>, ) -> Element

Set element to a provable count tree with flags and count value

pub fn empty_provable_count_sum_tree() -> Element

Set element to default empty provable count sum tree without flags

pub fn empty_provable_count_sum_tree_with_flags( flags: Option<Vec<u8>>, ) -> Element

Set element to default empty provable count sum tree with flags

pub fn new_provable_count_sum_tree(maybe_root_key: Option<Vec<u8>>) -> Element

Set element to a provable count sum tree without flags

pub fn new_provable_count_sum_tree_with_flags( maybe_root_key: Option<Vec<u8>>, flags: Option<Vec<u8>>, ) -> Element

Set element to a provable count sum tree with flags

pub fn new_provable_count_sum_tree_with_flags_and_sum_and_count_value( maybe_root_key: Option<Vec<u8>>, count_value: u64, sum_value: i64, flags: Option<Vec<u8>>, ) -> Element

Set element to a provable count sum tree with flags, count, and sum value

pub fn empty_commitment_tree(chunk_power: u8) -> Result<Element, ElementError>

Set element to an empty commitment tree.

Returns InvalidInput if chunk_power > 31.

pub fn empty_commitment_tree_with_flags( chunk_power: u8, flags: Option<Vec<u8>>, ) -> Result<Element, ElementError>

Set element to an empty commitment tree with flags.

Returns InvalidInput if chunk_power > 31.

pub fn new_commitment_tree( total_count: u64, chunk_power: u8, flags: Option<Vec<u8>>, ) -> Element

Set element to a commitment tree with all fields

pub fn empty_mmr_tree() -> Element

Set element to an empty MMR tree

pub fn empty_mmr_tree_with_flags(flags: Option<Vec<u8>>) -> Element

Set element to an empty MMR tree with flags

pub fn new_mmr_tree(mmr_size: u64, flags: Option<Vec<u8>>) -> Element

Set element to an MMR tree with the given size

pub fn empty_bulk_append_tree(chunk_power: u8) -> Result<Element, ElementError>

Set element to an empty bulk append tree without flags.

Returns InvalidInput if chunk_power > 31.

pub fn empty_bulk_append_tree_with_flags( chunk_power: u8, flags: Option<Vec<u8>>, ) -> Result<Element, ElementError>

Set element to an empty bulk append tree with flags.

Returns InvalidInput if chunk_power > 31.

pub fn new_bulk_append_tree( total_count: u64, chunk_power: u8, flags: Option<Vec<u8>>, ) -> Element

Set element to a bulk append tree with all fields

pub fn empty_dense_tree(height: u8) -> Element

Set element to an empty dense tree without flags

pub fn empty_dense_tree_with_flags( height: u8, flags: Option<Vec<u8>>, ) -> Element

Set element to an empty dense tree with flags

pub fn new_dense_tree(count: u16, height: u8, flags: Option<Vec<u8>>) -> Element

Set element to a dense tree with all fields

pub fn new_non_counted(inner: Element) -> Result<Element, ElementError>

Wrap an element in NonCounted so it contributes 0 to its parent count tree’s aggregate count when inserted. Sums (if any) still propagate.

Returns InvalidInput if inner is already wrapped in any wrapper variant (NonCounted or NotSummed) — the wrappers are mutually exclusive and may not nest in either direction. Use into_non_counted to wrap idempotently when inner may already be NonCounted; use that helper’s Result return for the cross-wrapper case.

pub fn into_non_counted(self) -> Result<Element, ElementError>

Wrap self in NonCounted. If self is already NonCounted, returns it unchanged (idempotent on NonCounted).

Returns InvalidInput if self is NotSummed — the two wrappers are mutually exclusive. Callers that need the unconditional wrapping path should ensure the input is a non-wrapper variant before calling.

pub fn new_not_summed(inner: Element) -> Result<Element, ElementError>

Wrap a sum-tree variant in NotSummed so it contributes 0 to its parent sum tree’s running sum when inserted. Counts (if any) still propagate.

Only the four sum-tree variants are accepted: SumTree, BigSumTree, CountSumTree, ProvableCountSumTree. Any other element — including items, sum items, references, non-sum trees, and any wrapper (NonCounted, NotSummed) — is rejected with InvalidInput.

pub fn into_not_summed(self) -> Result<Element, ElementError>

Wrap self in NotSummed. If self is already NotSummed, returns it unchanged (idempotent on NotSummed).

Returns InvalidInput if self is NonCounted (the two wrappers are mutually exclusive) or any non-sum-tree variant. Mirrors Element::into_non_counted.

impl Element

pub fn is_non_counted(&self) -> bool

Returns true if this element is wrapped in Element::NonCounted. The wrapper suppresses count propagation to the parent count tree but leaves all other behavior (storage, hashing, sum propagation, internal aggregation) unchanged.

pub fn is_not_summed(&self) -> bool

Returns true if this element is wrapped in Element::NotSummed. The wrapper suppresses sum propagation to the parent sum tree but leaves all other behavior (storage, hashing, count propagation, internal aggregation) unchanged.

pub fn underlying(&self) -> &Element

Returns the wrapped element if self is a wrapper (NonCounted or NotSummed), else self. Use this when you need to inspect the actual element type and don’t care whether it is wrapped.

Only unwraps one level — the constructors and (de)serializers reject any wrapper nesting, so a single unwrap is always sufficient.

pub fn underlying_mut(&mut self) -> &mut Element

Mutable variant of [underlying].

pub fn into_underlying(self) -> Element

Owned variant of [underlying].

pub fn sum_value_or_default(&self) -> i64

Decoded the integer value in the SumItem element type, returns 0 for everything else.

NonCounted delegates to its inner element — sums still propagate when the wrapper is inserted into a sum-bearing parent. NotSummed returns 0 — the wrapper’s whole purpose is to contribute nothing to the parent sum tree.

pub fn count_value_or_default(&self) -> u64

Decoded the integer value in the CountTree element type, returns 1 for everything else.

NonCounted returns 0 — the wrapper’s whole purpose is to contribute nothing to the parent count tree. NotSummed delegates to its inner — counts still propagate.

pub fn count_sum_value_or_default(&self) -> (u64, i64)

Decoded the count and sum values from the element type, returns (1, 0) for elements without count/sum semantics.

NonCounted returns (0, inner_sum) — count is suppressed, sum still propagates. NotSummed returns (inner_count, 0) — sum is suppressed, count still propagates.

pub fn big_sum_value_or_default(&self) -> i128

Decoded the integer value in the SumItem element type, returns 0 for everything else. NonCounted delegates to its inner. NotSummed returns 0.

pub fn as_sum_item_value(&self) -> Result<i64, ElementError>

Decoded the integer value in the SumItem element type. Looks through a NonCounted wrapper.

pub fn into_sum_item_value(self) -> Result<i64, ElementError>

Decoded the integer value in the SumItem element type. Looks through a NonCounted wrapper.

pub fn as_sum_tree_value(&self) -> Result<i64, ElementError>

Decoded the integer value in the SumTree element type. Looks through a NonCounted wrapper.

pub fn into_sum_tree_value(self) -> Result<i64, ElementError>

Decoded the integer value in the SumTree element type. Looks through a NonCounted wrapper.

pub fn as_item_bytes(&self) -> Result<&[u8], ElementError>

Gives the item value in the Item element type. Looks through a NonCounted wrapper.

pub fn into_item_bytes(self) -> Result<Vec<u8>, ElementError>

Gives the item value in the Item element type. Looks through a NonCounted wrapper.

pub fn into_reference_path_type(self) -> Result<ReferencePathType, ElementError>

Gives the reference path type in the Reference element type. Looks through a NonCounted wrapper.

pub fn is_sum_tree(&self) -> bool

Check if the element is a sum tree. Looks through NonCounted.

pub fn is_big_sum_tree(&self) -> bool

Check if the element is a big sum tree. Looks through NonCounted.

pub fn is_basic_tree(&self) -> bool

Check if the element is a tree but not a sum tree. Looks through NonCounted.

pub fn is_any_tree(&self) -> bool

Check if the element is a tree. Looks through NonCounted.

pub fn is_commitment_tree(&self) -> bool

Check if the element is a commitment tree. Looks through NonCounted.

pub fn is_mmr_tree(&self) -> bool

Check if the element is an MMR tree. Looks through NonCounted.

pub fn is_bulk_append_tree(&self) -> bool

Check if the element is a bulk append tree. Looks through NonCounted.

pub fn is_dense_tree(&self) -> bool

Check if the element is a dense append-only fixed-size tree. Looks through NonCounted.

pub fn uses_non_merk_data_storage(&self) -> bool

Check if the element is a tree type that stores data in the data namespace as non-Merk entries. These tree types have an always-empty Merk (root_key = None) and never contain child subtrees. The data namespace must be cleared directly rather than iterated as Merk elements.

Note: This must be kept in sync with TreeType::uses_non_merk_data_storage() in the merk crate. Looks through NonCounted.

pub fn non_merk_entry_count(&self) -> Option<u64>

Returns the entry count for non-Merk data tree types, or None for regular Merk trees and non-tree elements. This is used by delete and is_empty_tree operations to determine emptiness without iterating the data namespace. Looks through NonCounted.

pub fn is_non_empty_tree(&self) -> bool

Check if the element is a non-empty tree that should have child data.

For merk-backed trees this means the root key is Some(_) (at least one node). Non-merk tree types (MmrTree, BulkAppendTree, CommitmentTree, DenseAppendOnlyFixedSizeTree) always carry their own data and are considered non-empty regardless of their count field. Looks through NonCounted.

pub fn is_non_empty_merk_tree(&self) -> bool

Check if the element is a non-empty Merk-backed tree.

Returns true only for standard Merk trees (Tree, SumTree, BigSumTree, CountTree, CountSumTree, ProvableCountTree, ProvableCountSumTree) with a Some(_) root key. Excludes non-Merk tree types (MmrTree, BulkAppendTree, CommitmentTree, DenseAppendOnlyFixedSizeTree). Looks through NonCounted.

pub fn is_reference(&self) -> bool

Check if the element is a reference. Looks through NonCounted.

pub fn is_any_item(&self) -> bool

Check if the element is an item. Looks through NonCounted.

pub fn is_basic_item(&self) -> bool

Check if the element is a basic item. Looks through NonCounted.

pub fn has_basic_item(&self) -> bool

Check if the element has a basic item value (Item or ItemWithSumItem). Looks through NonCounted.

pub fn is_sum_item(&self) -> bool

Check if the element is a sum item. Looks through NonCounted.

pub fn is_item_with_sum_item(&self) -> bool

Check if the element is an item-with-sum-item. Looks through NonCounted.

pub fn get_flags(&self) -> &Option<Vec<u8>>

Grab the optional flag stored in an element. For NonCounted, returns the inner element’s flags.

pub fn get_flags_owned(self) -> Option<Vec<u8>>

Grab the optional flag stored in an element. For NonCounted, returns the inner element’s flags.

pub fn get_flags_mut(&mut self) -> &mut Option<Vec<u8>>

Grab the optional flag stored in an element as mutable. For NonCounted, returns a mutable reference to the inner element’s flags.

pub fn set_flags(&mut self, new_flags: Option<Vec<u8>>)

Sets the optional flag stored in an element. For NonCounted, sets the inner element’s flags.

pub fn required_item_space( len: u32, flag_len: u32, grove_version: &GroveVersion, ) -> Result<u32, ElementError>

Get the required item space

pub fn convert_if_reference_to_absolute_reference( self, path: &[&[u8]], key: Option<&[u8]>, ) -> Result<Element, ElementError>

Convert the reference to an absolute reference. Looks through a NonCounted wrapper, converting the inner reference and re-wrapping.

impl Element

pub fn serialize( &self, grove_version: &GroveVersion, ) -> Result<Vec<u8>, ElementError>

Serializes self. Returns vector of u8s.

Rejects:

• NonCounted(NonCounted(_)) — NonCounted cannot nest.
• NotSummed(NotSummed(_)), NotSummed(NonCounted(_)), NonCounted(NotSummed(_)) — wrappers cannot cross-nest.
• NotSummed(x) where x is not one of the four sum-tree variants (SumTree, BigSumTree, CountSumTree, ProvableCountSumTree).

Constructed via Element::new_non_counted / Element::new_not_summed these are impossible, but a caller could build them directly.

pub fn serialized_size( &self, grove_version: &GroveVersion, ) -> Result<usize, ElementError>

Serializes self. Returns usize.

pub fn deserialize( bytes: &[u8], grove_version: &GroveVersion, ) -> Result<Element, ElementError>

Deserializes given bytes and sets as self.

Pre-checks the leading bytes for any wrapper-byte combination and rejects before invoking bincode. This closes a stack-exhaustion vector: a hostile payload of repeated wrapper bytes would otherwise cause bincode to recursively decode the Box<Element> chain (and overflow the stack) before any post-decode check could fire. The pre-check is O(1) — only the first two bytes matter.

The four rejected leading byte pairs are:

• [15, 15, ..] — NonCounted(NonCounted(..))
• [15, 16, ..] — NonCounted(NotSummed(..))
• [16, 15, ..] — NotSummed(NonCounted(..))
• [16, 16, ..] — NotSummed(NotSummed(..))

impl Element

pub fn element_type(&self) -> ElementType

Returns the ElementType for this element.

For Element::NonCounted(inner), returns the matching NonCountedXxx twin of the inner element’s type (high bit set). Nested wrappers are disallowed at construction and serialization, so the inner is always a base element.

pub fn type_str(&self) -> &str

pub fn validate_wrapper_invariants(&self) -> Result<(), ElementError>

Verify the wrapper invariants for self:

• NonCounted and NotSummed may not nest in any combination.
• NotSummed may only wrap one of the four sum-tree variants (SumTree, BigSumTree, CountSumTree, ProvableCountSumTree).

Constructors and the serialize/deserialize paths already enforce these rules; this helper exists so external callers (most importantly the manual serde::Deserialize impl) can apply the same checks.

Only the immediate wrapper layer is checked — wrapper nesting is forbidden by these very rules, so deeper recursion is not needed.

Trait Implementations

impl<'__de, __Context> BorrowDecode<'__de, __Context> for Element

fn borrow_decode<__D>(decoder: &mut __D) -> Result<Element, DecodeError>

where __D: BorrowDecoder<'__de, Context = __Context>,

Attempt to decode this type with the given BorrowDecode.

impl Clone for Element

fn clone(&self) -> Element

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Element

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<__Context> Decode<__Context> for Element

fn decode<__D>(decoder: &mut __D) -> Result<Element, DecodeError>

where __D: Decoder<Context = __Context>,

Attempt to decode this type with the given Decode.

impl Display for Element

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl ElementAggregateSumQueryExtensions for Element

Available on crate feature minimal only.

fn get_aggregate_sum_query( storage: &RocksDbStorage, aggregate_sum_path_query: &AggregateSumPathQuery, query_options: AggregateSumQueryOptions, transaction: Option<&<RocksDbStorage as Storage<'_>>::Transaction>, grove_version: &GroveVersion, ) -> CostContext<Result<AggregateSumQueryResult, Error>>

Returns a vector of result elements based on given query

fn get_aggregate_sum_query_apply_function( storage: &RocksDbStorage, path: &[&[u8]], aggregate_sum_query: &AggregateSumQuery, query_options: AggregateSumQueryOptions, transaction: Option<&<RocksDbStorage as Storage<'_>>::Transaction>, add_element_function: fn(AggregateSumPathQueryPushArgs<'_, '_, '_>, &GroveVersion) -> CostContext<Result<(), Error>>, grove_version: &GroveVersion, ) -> CostContext<Result<AggregateSumQueryResult, Error>>

Returns a vector of result sum items with keys based on given aggregate sum query

fn aggregate_sum_path_query_push( args: AggregateSumPathQueryPushArgs<'_, '_, '_>, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

Push arguments to path query

fn aggregate_sum_query_item( storage: &RocksDbStorage, item: &QueryItem, results: &mut Vec<(Vec<u8>, i64)>, path: &[&[u8]], left_to_right: bool, transaction: Option<&<RocksDbStorage as Storage<'_>>::Transaction>, limit: &mut Option<u16>, sum_limit_left: &mut i64, query_options: AggregateSumQueryOptions, add_element_function: fn(AggregateSumPathQueryPushArgs<'_, '_, '_>, &GroveVersion) -> CostContext<Result<(), Error>>, elements_scanned: &mut u16, max_elements_scanned: u16, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

decrease_limit_on_range_with_no_sub_elements should generally be set to true, as having it false could mean very expensive queries. The queries would be expensive because we could go through many many trees where the sub elements have no matches, hence the limit would not decrease and hence we would continue on the increasingly expensive query.

fn basic_aggregate_sum_push( args: AggregateSumPathQueryPushArgs<'_, '_, '_>, grove_version: &GroveVersion, ) -> Result<(), Error>

Extracts the sum value from an element and appends it to the results.

impl ElementCostExtensions for Element

fn specialized_costs_for_key_value( key: &[u8], value: &[u8], node_type: NodeType, grove_version: &GroveVersion, ) -> Result<u32, Error>

Get tree costs for a key value

fn specialized_value_defined_cost( &self, grove_version: &GroveVersion, ) -> Option<u32>

Get the value defined cost for a serialized value item with sum item or sum item. Looks through NonCounted (the +1 wrapper-byte cost is already folded in by get_specialized_cost).

fn layered_value_defined_cost( &self, grove_version: &GroveVersion, ) -> Option<u32>

Get the value defined cost for a serialized value item with a tree. Looks through NonCounted.

fn value_defined_cost( &self, grove_version: &GroveVersion, ) -> Option<ValueDefinedCostType>

Get the value defined cost for a serialized value. Looks through NonCounted.

fn value_defined_cost_for_serialized_value( value: &[u8], grove_version: &GroveVersion, ) -> Option<ValueDefinedCostType>

Get the value defined cost for a serialized value

impl ElementCostPrivateExtensions for Element

fn get_specialized_cost( &self, grove_version: &GroveVersion, ) -> Result<u32, Error>

Get tree cost for the element. For NonCounted and NotSummed, delegates to the inner element and adds 1 byte for the wrapper discriminant.

impl ElementDecodeExtensions for Element

fn raw_decode( bytes: &[u8], grove_version: &GroveVersion, ) -> Result<Element, Error>

Decode from bytes

impl ElementDeleteFromStorageExtensions for Element

fn delete<'db, K, S>( merk: &mut Merk<S>, key: K, merk_options: Option<MerkOptions>, is_layered: bool, in_tree_type: TreeType, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Delete an element from Merk under a key

fn delete_with_sectioned_removal_bytes<'db, K, S>( merk: &mut Merk<S>, key: K, merk_options: Option<MerkOptions>, is_layered: bool, in_tree_type: TreeType, sectioned_removal: &mut impl FnMut(&Vec<u8>, u32, u32) -> Result<(StorageRemovedBytes, StorageRemovedBytes), Error>, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Delete an element from Merk under a key

fn delete_into_batch_operations<K>( key: K, is_layered: bool, in_tree_type: TreeType, batch_operations: &mut Vec<(K, Op)>, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

where K: AsRef<[u8]>,

Delete an element from Merk under a key to batch operations

impl ElementExistsInStorageExtensions for Element

fn element_at_key_already_exists<'db, K, S>( &self, merk: &mut Merk<S>, key: K, grove_version: &GroveVersion, ) -> CostContext<Result<bool, Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Helper function that returns whether an element at the key for the element already exists.

impl ElementExt for Element

fn value_hash( &self, grove_version: &GroveVersion, ) -> CostContext<Result<[u8; 32], ElementError>>

Computes the value hash for this element.

impl ElementFetchFromStorageExtensions for Element

fn get<'db, K, S>( merk: &Merk<S>, key: K, allow_cache: bool, grove_version: &GroveVersion, ) -> CostContext<Result<Element, Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Get an element from Merk under a key; path should be resolved and proper Merk should be loaded by this moment

fn get_optional<'db, K, S>( merk: &Merk<S>, key: K, allow_cache: bool, grove_version: &GroveVersion, ) -> CostContext<Result<Option<Element>, Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Get an element from Merk under a key; path should be resolved and proper Merk should be loaded by this moment

fn get_from_storage<'db, K, S>( storage: &S, key: K, grove_version: &GroveVersion, ) -> CostContext<Result<Element, Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Get an element directly from storage under a key Merk does not need to be loaded Errors if element doesn’t exist

fn get_optional_from_storage<'db, K, S>( storage: &S, key: K, grove_version: &GroveVersion, ) -> CostContext<Result<Option<Element>, Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Get an element directly from storage under a key Merk does not need to be loaded

fn get_with_absolute_refs<'db, K, S>( merk: &Merk<S>, path: &[&[u8]], key: K, allow_cache: bool, grove_version: &GroveVersion, ) -> CostContext<Result<Element, Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Get an element from Merk under a key; path should be resolved and proper Merk should be loaded by this moment

fn get_optional_with_absolute_refs<'db, K, S>( merk: &Merk<S>, path: &[&[u8]], key: K, allow_cache: bool, grove_version: &GroveVersion, ) -> CostContext<Result<Option<Element>, Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Get an element from Merk under a key; path should be resolved and proper Merk should be loaded by this moment

fn get_value_hash<'db, K, S>( merk: &Merk<S>, key: K, allow_cache: bool, grove_version: &GroveVersion, ) -> CostContext<Result<Option<[u8; 32]>, Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Get an element’s value hash from Merk under a key

fn get_with_value_hash<'db, K, S>( merk: &Merk<S>, key: K, allow_cache: bool, grove_version: &GroveVersion, ) -> CostContext<Result<(Element, [u8; 32]), Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Get an element and its value hash from Merk under a key

impl ElementInsertToStorageExtensions for Element

fn insert<'db, K, S>( &self, merk: &mut Merk<S>, key: K, options: Option<MerkOptions>, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Insert an element in Merk under a key; path should be resolved and proper Merk should be loaded by this moment If transaction is not passed, the batch will be written immediately. If transaction is passed, the operation will be committed on the transaction commit.

fn insert_into_batch_operations<K>( &self, key: K, batch_operations: &mut Vec<(K, Op)>, feature_type: TreeFeatureType, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

where K: AsRef<[u8]>,

Add to batch operations a “Put” op with key and serialized element. Return CostResult.

fn insert_if_not_exists<'db, S>( &self, merk: &mut Merk<S>, key: &[u8], options: Option<MerkOptions>, grove_version: &GroveVersion, ) -> CostContext<Result<bool, Error>>

where S: StorageContext<'db>,

Insert an element in Merk under a key if it doesn’t yet exist; path should be resolved and proper Merk should be loaded by this moment If transaction is not passed, the batch will be written immediately. If transaction is passed, the operation will be committed on the transaction commit.

fn insert_if_not_exists_into_batch_operations<'db, S, K>( &self, merk: &mut Merk<S>, key: K, batch_operations: &mut Vec<(K, Op)>, feature_type: TreeFeatureType, grove_version: &GroveVersion, ) -> CostContext<Result<bool, Error>>

where S: StorageContext<'db>, K: AsRef<[u8]>,

Adds a “Put” op to batch operations with the element and key if it doesn’t exist yet. Returns CostResult.

fn insert_if_changed_value<'db, S>( &self, merk: &mut Merk<S>, key: &[u8], options: Option<MerkOptions>, grove_version: &GroveVersion, ) -> CostContext<Result<(bool, Option<Element>), Error>>

where S: StorageContext<'db>,

Insert an element in Merk under a key if the value is different from what already exists; path should be resolved and proper Merk should be loaded by this moment If transaction is not passed, the batch will be written immediately. If transaction is passed, the operation will be committed on the transaction commit. The bool represents if we indeed inserted. If the value changed we return the old element.

fn insert_if_changed_value_into_batch_operations<'db, S, K>( &self, merk: &mut Merk<S>, key: K, batch_operations: &mut Vec<(K, Op)>, feature_type: TreeFeatureType, grove_version: &GroveVersion, ) -> CostContext<Result<(bool, Option<Element>), Error>>

where S: StorageContext<'db>, K: AsRef<[u8]>,

Adds a “Put” op to batch operations with the element and key if the value is different from what already exists; Returns CostResult. The bool represents if we indeed inserted. If the value changed we return the old element.

fn insert_reference<'db, K, S>( &self, merk: &mut Merk<S>, key: K, referenced_value: [u8; 32], options: Option<MerkOptions>, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Insert a reference element in Merk under a key; path should be resolved and proper Merk should be loaded by this moment If transaction is not passed, the batch will be written immediately. If transaction is passed, the operation will be committed on the transaction commit.

fn insert_reference_into_batch_operations<K>( &self, key: K, referenced_value: [u8; 32], batch_operations: &mut Vec<(K, Op)>, feature_type: TreeFeatureType, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

where K: AsRef<[u8]>,

Adds a “Put” op to batch operations with reference and key. Returns CostResult.

fn insert_subtree<'db, K, S>( &self, merk: &mut Merk<S>, key: K, subtree_root_hash: [u8; 32], options: Option<MerkOptions>, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

where K: AsRef<[u8]>, S: StorageContext<'db>,

Insert a tree element in Merk under a key; path should be resolved and proper Merk should be loaded by this moment If transaction is not passed, the batch will be written immediately. If transaction is passed, the operation will be committed on the transaction commit.

fn insert_subtree_into_batch_operations<K>( &self, key: K, subtree_root_hash: [u8; 32], is_replace: bool, batch_operations: &mut Vec<(K, Op)>, feature_type: TreeFeatureType, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

where K: AsRef<[u8]>,

Adds a “Put” op to batch operations for a subtree and key

impl ElementIteratorExtensions for Element

fn iterator<I>(raw_iter: I) -> CostContext<ElementsIterator<I>>

where I: RawIterator,

Iterator

impl ElementQueryExtensions for Element

fn get_query( storage: &RocksDbStorage, merk_path: &[&[u8]], query: &Query, query_options: QueryOptions, result_type: QueryResultType, transaction: Option<&<RocksDbStorage as Storage<'_>>::Transaction>, grove_version: &GroveVersion, ) -> CostContext<Result<QueryResultElements, Error>>

Returns a vector of result elements based on given query

fn get_query_values( storage: &RocksDbStorage, merk_path: &[&[u8]], query: &Query, query_options: QueryOptions, transaction: Option<&<RocksDbStorage as Storage<'_>>::Transaction>, grove_version: &GroveVersion, ) -> CostContext<Result<Vec<Element>, Error>>

Get values of result elements coming from given query

fn get_query_apply_function( storage: &RocksDbStorage, path: &[&[u8]], sized_query: &SizedQuery, query_options: QueryOptions, result_type: QueryResultType, transaction: Option<&<RocksDbStorage as Storage<'_>>::Transaction>, add_element_function: fn(PathQueryPushArgs<'_, '_, '_>, &GroveVersion) -> CostContext<Result<(), Error>>, grove_version: &GroveVersion, ) -> CostContext<Result<(QueryResultElements, u16), Error>>

Returns a vector of result elements and the number of skipped items based on given query

fn get_path_query( storage: &RocksDbStorage, path_query: &PathQuery, query_options: QueryOptions, result_type: QueryResultType, transaction: Option<&<RocksDbStorage as Storage<'_>>::Transaction>, grove_version: &GroveVersion, ) -> CostContext<Result<(QueryResultElements, u16), Error>>

Returns a vector of elements excluding trees, and the number of skipped elements

fn get_sized_query( storage: &RocksDbStorage, path: &[&[u8]], sized_query: &SizedQuery, query_options: QueryOptions, result_type: QueryResultType, transaction: Option<&<RocksDbStorage as Storage<'_>>::Transaction>, grove_version: &GroveVersion, ) -> CostContext<Result<(QueryResultElements, u16), Error>>

Returns a vector of elements, and the number of skipped elements

fn path_query_push( args: PathQueryPushArgs<'_, '_, '_>, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

Push arguments to path query

fn subquery_paths_and_value_for_sized_query( sized_query: &SizedQuery, key: &[u8], ) -> (Option<Vec<Vec<u8>>>, Option<Query>)

Takes a sized query and a key and returns subquery key and subquery as tuple

fn query_item( storage: &RocksDbStorage, item: &QueryItem, results: &mut Vec<QueryResultElement>, path: &[&[u8]], sized_query: &SizedQuery, transaction: Option<&<RocksDbStorage as Storage<'_>>::Transaction>, limit: &mut Option<u16>, offset: &mut Option<u16>, query_options: QueryOptions, result_type: QueryResultType, add_element_function: fn(PathQueryPushArgs<'_, '_, '_>, &GroveVersion) -> CostContext<Result<(), Error>>, grove_version: &GroveVersion, ) -> CostContext<Result<(), Error>>

decrease_limit_on_range_with_no_sub_elements should generally be set to true, as having it false could mean very expensive queries. The queries would be expensive because we could go through many trees where the sub elements have no matches, hence the limit would not decrease and hence we would continue on the increasingly expensive query.

fn basic_push( args: PathQueryPushArgs<'_, '_, '_>, grove_version: &GroveVersion, ) -> Result<(), Error>

Default push function that adds an element to the query results.

impl ElementReconstructExtensions for Element

fn reconstruct_with_root_key( &self, maybe_root_key: Option<Vec<u8>>, aggregate_data: AggregateData, ) -> Option<Element>

Reconstruct a tree element with updated root key and aggregate data, preserving flags and type-specific fields. Returns None for non-tree elements.

impl ElementTreeTypeExtensions for Element

fn root_key_and_tree_type_owned(self) -> Option<(Option<Vec<u8>>, TreeType)>

Check if the element is a tree and return the root_tree info and tree type. Looks through NonCounted.

fn root_key_and_tree_type(&self) -> Option<(&Option<Vec<u8>>, TreeType)>

Check if the element is a tree and return the root_tree info and the tree type. Looks through NonCounted.

fn tree_flags_and_type(&self) -> Option<(&Option<Vec<u8>>, TreeType)>

Check if the element is a tree and return the flags and the tree type. Looks through NonCounted.

fn tree_type(&self) -> Option<TreeType>

Check if the element is a tree and return the tree type. Looks through NonCounted.

fn tree_feature_type(&self) -> Option<TreeFeatureType>

Check if the element is a tree and return the aggregate of elements in the tree. Looks through NonCounted.

fn maybe_tree_type(&self) -> MaybeTree

Check if the element is a tree and return the tree type. Looks through NonCounted.

fn get_feature_type( &self, parent_tree_type: TreeType, ) -> Result<TreeFeatureType, Error>

Get the tree feature type.

count_value_or_default and count_sum_value_or_default already return 0 (resp. (0, inner_sum)) for Element::NonCounted, and sum_value_or_default / big_sum_value_or_default / count_sum_value_or_default already return 0 (resp. (inner_count, 0)) for Element::NotSummed. So the existing dispatch produces the right feature type for either wrapper without an explicit branch here.

impl Encode for Element

fn encode<__E>(&self, encoder: &mut __E) -> Result<(), EncodeError>

where __E: Encoder,

Encode a given type.

impl Hash for Element

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Element

fn eq(&self, other: &Element) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Visualize for Element

fn visualize<W>(&self, drawer: Drawer<W>) -> Result<Drawer<W>, Error>

where W: Write,

Visualize

impl Eq for Element

impl StructuralPartialEq for Element