utreexo

packages/utreexo/src/lib.cairo

@@ -1,11 +1,11 @@
-pub mod vanilla {
+pub mod stump {
     pub mod state;
     pub mod proof;
     pub mod accumulator;
     #[cfg(test)]
     mod accumulator_tests;
 }
-pub mod stump {
+pub mod vanilla {
     pub mod state;
     pub mod proof;
     pub mod accumulator;
@@ -14,10 +14,10 @@ pub mod stump {
 }
 pub mod test;
 
-use core::poseidon::PoseidonTrait;
 use core::hash::{HashStateTrait, HashStateExTrait};
+use core::poseidon::PoseidonTrait;
 
-/// Parent hash of two Utreexo nodes
+/// Parent hash of two Utreexo nodes.
 fn parent_hash(left: felt252, right: felt252) -> felt252 {
     return PoseidonTrait::new().update_with(left).update_with(right).finalize();
 }

packages/utreexo/src/stump/proof.cairo

@@ -13,6 +13,7 @@ pub struct UtreexoBatchProof {
     pub targets: Span<u64>,
 }
 
+/// `Display` implementation for `UtreexoBatchProof`.
 impl UtreexoBatchProofDisplay of Display<UtreexoBatchProof> {
     fn fmt(self: @UtreexoBatchProof, ref f: Formatter) -> Result<(), Error> {
         let mut targets: ByteArray = Default::default();
@@ -466,7 +467,7 @@ pub impl UtreexoBatchProofImpl of UtreexoBatchProofTrait {
 }
 
 /// Extracts all nodes with absolute positions in [row_start; row_end)
-/// and transforms their positions to relative
+/// and transforms their positions to relative.
 fn extract_row<T, +Copy<T>, +Drop<T>>(
     ref nodes: Array<(u64, T)>, row_start: u64, row_end: u64
 ) -> Array<(u64, T)> {
@@ -482,7 +483,7 @@ fn extract_row<T, +Copy<T>, +Drop<T>>(
     row
 }
 
-/// Merges two sorted arrays into a single sorted array
+/// Merges two sorted arrays into a single sorted array.
 fn merge_sorted<T, +Drop<T>>(
     ref arr1: Array<(u64, T)>, ref arr2: Array<(u64, T)>
 ) -> Array<(u64, T)> {
@@ -504,7 +505,7 @@ fn merge_sorted<T, +Drop<T>>(
 }
 
 /// Takes two nodes containing two values each: (L1, L2) and (R1, R2), and calculates
-/// a parent node, that also contains two values (P1 = h(L1, R1), P2 = h(L2, R2))
+/// a parent node, that also contains two values (P1 = h(L1, R1), P2 = h(L2, R2)).
 fn parent_hash_pair(
     left: (felt252, Option<felt252>), right: (felt252, Option<felt252>)
 ) -> (felt252, Option<felt252>) {
@@ -520,7 +521,7 @@ fn parent_hash_pair(
     (old_parent, new_parent)
 }
 
-/// PartialOrd implementation for tuple (u64, T).
+/// `PartialOrd` trait implementation for tuple (u64, T).
 impl PositionPartialOrd<T, +Drop<T>> of PartialOrd<(u64, T)> {
     fn lt(lhs: (u64, T), rhs: (u64, T)) -> bool {
         let (l, _) = lhs;

packages/utreexo/src/stump/state.cairo

@@ -12,12 +12,14 @@ pub struct UtreexoStumpState {
     pub num_leaves: u64,
 }
 
+/// `Default` trait implementation for `UtreexoStumpState`.
 pub impl UtreexoStumpStateDefault of Default<UtreexoStumpState> {
     fn default() -> UtreexoStumpState {
         UtreexoStumpState { roots: array![Option::None].span(), num_leaves: 0, }
     }
 }
 
+/// `Display` trait implementation for `UtreexoStumpState`.
 impl UtreexoStumpStateDisplay of Display<UtreexoStumpState> {
     fn fmt(self: @UtreexoStumpState, ref f: Formatter) -> Result<(), Error> {
         let str: ByteArray = format!(

packages/utreexo/src/test.cairo

@@ -1,7 +1,7 @@
+use core::testing::get_available_gas;
 use crate::stump::state::UtreexoStumpState;
 use crate::stump::proof::UtreexoBatchProof;
 use crate::stump::accumulator::StumpUtreexoAccumulator;
-use core::testing::get_available_gas;
 
 #[derive(Drop, Serde, Debug)]
 struct Args {

packages/utreexo/src/vanilla/accumulator.cairo

@@ -26,7 +26,7 @@ pub impl VanillaUtreexoAccumulatorImpl of VanillaUtreexoAccumulator {
                 }
             };
 
-        // Checks if terminates with Option::None
+        // Check if terminates with `Option::None`
         if (new_roots[new_roots.len() - 1].is_some()) {
             new_roots.append(Option::None);
         }

packages/utreexo/src/vanilla/accumulator_tests.cairo

@@ -2,7 +2,7 @@ use super::accumulator::VanillaUtreexoAccumulator;
 use super::proof::UtreexoProof;
 use super::state::UtreexoState;
 
-/// Test the basic functionality of the Utreexo accumulator
+/// Tests the basic functionality of the Utreexo accumulator.
 ///
 /// This test covers the following scenarios:
 /// 1. Adding a single leaf and verifying it
@@ -18,6 +18,7 @@ use super::state::UtreexoState;
 ///
 /// The test uses predefined txid values (0x111111..., 0x222222..., etc.) for simplicity.
 /// It checks the correct root values at each stage of the Utreexo tree's growth.
+
 #[test]
 fn test_verify_inclusion() {
     // Add the first leaf (0x111111111111111111111111)
@@ -141,7 +142,7 @@ fn test_utreexo_add() {
     let mut utreexo_state: UtreexoState = Default::default();
     let outpoint: felt252 = 0x291F8F5FC449D42C715B529E542F24A80136D18F4A85DE28829CD3DCAAC1B9C;
 
-    // add first leave to empty utreexo
+    // Add first leave to empty utreexo
     utreexo_state = utreexo_state.add(outpoint);
 
     let expected: Span<Option<felt252>> = array![
@@ -151,7 +152,7 @@ fn test_utreexo_add() {
         .span();
     assert_eq!(utreexo_state.roots, expected, "cannot add first leave");
 
-    // add second leave
+    // Add second leave
     utreexo_state = utreexo_state.add(outpoint);
 
     let expected: Span<Option<felt252>> = array![
@@ -162,7 +163,7 @@ fn test_utreexo_add() {
         .span();
     assert_eq!(utreexo_state.roots, expected, "cannot add second leave");
 
-    // add thirdth leave
+    // Add thirdth leave
     utreexo_state = utreexo_state.add(outpoint);
 
     let expected: Span<Option<felt252>> = array![
@@ -173,7 +174,7 @@ fn test_utreexo_add() {
         .span();
     assert_eq!(utreexo_state.roots, expected, "cannot add thirdth leave");
 
-    // add fourth leave
+    // Add fourth leave
     utreexo_state = utreexo_state.add(outpoint);
 
     let expected: Span<Option<felt252>> = array![
@@ -185,7 +186,7 @@ fn test_utreexo_add() {
         .span();
     assert_eq!(utreexo_state.roots, expected, "cannot add fourth leave");
 
-    // add fifth leave
+    // Add fifth leave
     utreexo_state = utreexo_state.add(outpoint);
 
     let expected: Span<Option<felt252>> = array![
@@ -197,7 +198,7 @@ fn test_utreexo_add() {
         .span();
     assert_eq!(utreexo_state.roots, expected, "cannot add fifth leave");
 
-    // add 3 leaves
+    // Add 3 leaves
     for _ in 1..4_u8 {
         utreexo_state = utreexo_state.add(outpoint);
     };
@@ -212,7 +213,7 @@ fn test_utreexo_add() {
         .span();
     assert_eq!(utreexo_state.roots, expected, "cannot add 3 leaves");
 
-    // add 22 leaves
+    // Add 22 leaves
     for _ in 1..23_u8 {
         utreexo_state = utreexo_state.add(outpoint);
     };
@@ -234,7 +235,7 @@ fn test_utreexo_delete() {
 
     let mut utreexo_state: UtreexoState = Default::default();
 
-    // adds 16 leaves to empty utreexo
+    // Adds 16 leaves to empty utreexo
     utreexo_state = utreexo_state
         .add(0x111111111111111111111111)
         .add(0x222222222222222222222222)
@@ -275,7 +276,7 @@ fn test_utreexo_delete() {
             .span()
     };
 
-    // deletes the 3rd leaf
+    // Deletes the 3rd leaf
     utreexo_state = utreexo_state.delete(@proof_for_3rd_leaf);
 
     let expected: Span<Option<felt252>> = array![
@@ -297,7 +298,7 @@ fn test_utreexo_delete_2() {
 
     let mut utreexo_state: UtreexoState = Default::default();
 
-    // adds 7 leaves to empty utreexo
+    // Adds 7 leaves to empty utreexo
     utreexo_state = utreexo_state
         .add(0x111111111111111111111111)
         .add(0x222222222222222222222222)
@@ -318,7 +319,7 @@ fn test_utreexo_delete_2() {
 
     let proof: UtreexoProof = UtreexoProof { leaf_index: 6, proof: array![].span() };
 
-    // deletes the last added leaf which corresponds to the root at h=0
+    // Deletes the last added leaf which corresponds to the root at h=0
     utreexo_state = utreexo_state.delete(@proof);
 
     let expected: Span<Option<felt252>> = array![

packages/utreexo/src/vanilla/proof.cairo

@@ -11,6 +11,7 @@ pub struct UtreexoProof {
     pub leaf_index: u64,
 }
 
+/// `Display` trait implementation for `UtreexoProof`.
 impl UtreexoProofDisplay of Display<UtreexoProof> {
     fn fmt(self: @UtreexoProof, ref f: Formatter) -> Result<(), Error> {
         let mut proofs: ByteArray = Default::default();
@@ -47,7 +48,7 @@ pub impl UtreexoProofImpl of UtreexoProofTrait {
                 curr_node = parent_hash(left, right);
                 node_index = next_node_index;
             };
-        // Returns the computed root (or the node itself if the proof is empty).
+        // Return the computed root (or the node itself if the proof is empty).
         curr_node
     }
 }

packages/utreexo/src/vanilla/state.cairo

@@ -10,12 +10,14 @@ pub struct UtreexoState {
     pub roots: Span<Option<felt252>>,
 }
 
+/// `Default` trait implement for `UtreexoState`.
 pub impl UtreexoStateDefault of Default<UtreexoState> {
     fn default() -> UtreexoState {
         UtreexoState { roots: array![Option::None].span() }
     }
 }
 
+/// `Display` trait implement for `UtreexoState`.
 impl UtreexoStateDisplay of Display<UtreexoState> {
     fn fmt(self: @UtreexoState, ref f: Formatter) -> Result<(), Error> {
         let str: ByteArray = format!("UtreexoState {{ roots: {} }}", (*self.roots).len(),);