Add some docs and tidy exports

ralexstokes · Mar 29, 2024 · 9128f39 · 9128f39
1 parent 3aff338
commit 9128f39
Show file tree

Hide file tree

Showing 10 changed files with 25 additions and 17 deletions.
diff --git a/ssz-rs-derive/src/lib.rs b/ssz-rs-derive/src/lib.rs
@@ -417,7 +417,7 @@ fn derive_generalized_indexable_impl(
                     quote! {
                         #selector => {
                             let chunk_position = #i;
-                            let child = parent * get_power_of_two_ceil(Self::chunk_count()) + chunk_position;
+                            let child = parent * ssz_rs::merkleization::get_power_of_two_ceil(Self::chunk_count()) + chunk_position;
                             <#field_ty as ssz_rs::GeneralizedIndexable>::compute_generalized_index(child, path)
                         }
                     }

diff --git a/ssz-rs/src/boolean.rs b/ssz-rs/src/boolean.rs
@@ -2,8 +2,8 @@ use crate::{
     de::{Deserialize, DeserializeError},
     lib::*,
     merkleization::{
-        prove_primitive, GeneralizedIndex, GeneralizedIndexable, HashTreeRoot, MerkleizationError,
-        Node, ProofAndWitness, Prove,
+        proofs::{prove_primitive, ProofAndWitness, Prove},
+        GeneralizedIndex, GeneralizedIndexable, HashTreeRoot, MerkleizationError, Node,
     },
     ser::{Serialize, SerializeError},
     Serializable, SimpleSerialize,

diff --git a/ssz-rs/src/lib.rs b/ssz-rs/src/lib.rs
@@ -115,7 +115,10 @@ mod exports {
         de::{Deserialize, DeserializeError},
         error::{Error as SimpleSerializeError, InstanceError, TypeError},
         list::List,
-        merkleization::*,
+        merkleization::{
+            multiproofs, proofs, GeneralizedIndex, GeneralizedIndexable, HashTreeRoot,
+            MerkleizationError, Node, Path, PathElement,
+        },
         ser::{Serialize, SerializeError},
         uint::U256,
         utils::{deserialize, serialize},

diff --git a/ssz-rs/src/merkleization/generalized_index.rs b/ssz-rs/src/merkleization/generalized_index.rs
@@ -1,13 +1,20 @@
+//! Support for generalized indices and computation over them.
 use crate::{
     lib::*,
     merkleization::{MerkleizationError as Error, BYTES_PER_CHUNK},
 };
 
+/// Describes part of a `GeneralizedIndexable` type.
 #[derive(Debug, Clone)]
 pub enum PathElement {
+    // Refers to either an element in a SSZ collection
+    // or a particular variant of a SSZ union.
     Index(usize),
+    // Refers to one of the members of a SSZ container
     Field(String),
+    // Refers to the length of a variably-sized SSZ collection
     Length,
+    // Refers to the "type tag" of a SSZ union
     Selector,
 }
 
@@ -23,6 +30,7 @@ impl From<usize> for PathElement {
     }
 }
 
+/// A collection of `PathElement`s that navigate a `GeneralizedIndexable` type.
 pub type Path<'a> = &'a [PathElement];
 
 /// Types that can compute generalized indices given a `Path`.
@@ -94,14 +102,6 @@ pub const fn sibling(index: GeneralizedIndex) -> GeneralizedIndex {
     index ^ 1
 }
 
-pub const fn child_left(index: GeneralizedIndex) -> GeneralizedIndex {
-    index * 2
-}
-
-pub const fn child_right(index: GeneralizedIndex) -> GeneralizedIndex {
-    index * 2 + 1
-}
-
 pub const fn parent(index: GeneralizedIndex) -> GeneralizedIndex {
     index / 2
 }

diff --git a/ssz-rs/src/merkleization/merkleize.rs b/ssz-rs/src/merkleization/merkleize.rs
@@ -1,3 +1,4 @@
+//! Support for computing Merkle trees.
 use crate::{
     lib::*,
     merkleization::{MerkleizationError as Error, Node, BYTES_PER_CHUNK},

diff --git a/ssz-rs/src/merkleization/mod.rs b/ssz-rs/src/merkleization/mod.rs
@@ -1,8 +1,8 @@
 pub mod generalized_index;
 mod merkleize;
-pub mod multiproof;
+pub mod multiproofs;
 mod node;
-mod proofs;
+pub mod proofs;
 
 use crate::{lib::*, ser::SerializeError};
 pub use generalized_index::{
@@ -11,7 +11,7 @@ pub use generalized_index::{
 };
 pub use merkleize::*;
 pub use node::*;
-pub use proofs::*;
+pub use proofs::is_valid_merkle_branch;
 
 pub(crate) const BYTES_PER_CHUNK: usize = 32;
 pub(crate) const BITS_PER_CHUNK: usize = BYTES_PER_CHUNK * (crate::BITS_PER_BYTE as usize);

diff --git a/ssz-rs/src/merkleization/multiproof.rs → ssz-rs/src/merkleization/multiproofs.rs b/ssz-rs/src/merkleization/multiproof.rs → ssz-rs/src/merkleization/multiproofs.rs
@@ -1,3 +1,4 @@
+//! Experimental support for multiproofs.
 use crate::{
     lib::*,
     merkleization::{

diff --git a/ssz-rs/src/merkleization/node.rs b/ssz-rs/src/merkleization/node.rs
@@ -1,5 +1,6 @@
 use crate::{
     lib::*,
+    merkleization::BYTES_PER_CHUNK,
     prelude::*,
     utils::{write_bytes_to_lower_hex, write_bytes_to_lower_hex_display},
 };

diff --git a/ssz-rs/src/merkleization/proofs.rs b/ssz-rs/src/merkleization/proofs.rs
@@ -1,3 +1,4 @@
+//! Support for constructing and verifying Merkle proofs.
 use crate::{
     lib::*,
     merkleization::{

diff --git a/ssz-rs/src/uint.rs b/ssz-rs/src/uint.rs
@@ -2,8 +2,9 @@ use crate::{
     de::{Deserialize, DeserializeError},
     lib::*,
     merkleization::{
-        pack_bytes, prove_primitive, GeneralizedIndex, GeneralizedIndexable, HashTreeRoot,
-        MerkleizationError, Node, ProofAndWitness, Prove,
+        pack_bytes,
+        proofs::{prove_primitive, ProofAndWitness, Prove},
+        GeneralizedIndex, GeneralizedIndexable, HashTreeRoot, MerkleizationError, Node,
     },
     ser::{Serialize, SerializeError},
     Serializable, SimpleSerialize, BITS_PER_BYTE,