enhances the merkle tree implementation

src/main/java/modules/ads/AuthenticatedDataStructure.java

@@ -7,9 +7,28 @@
  * Models AuthenticatedDataStructure (ADS) and a key-value store of entities supported with membership proofs.
  */
 public interface AuthenticatedDataStructure {
+  /**
+   * Adds an entity to the ADS.
+   *
+   * @param e the entity to add
+   *
+   * @return AuthenticatedEntity containing the entity and its membership proof
+   */
   AuthenticatedEntity put(Entity e);
 
+  /**
+   * Returns the AuthenticatedEntity corresponding to the given identifier.
+   *
+   * @param id the identifier of the entity to retrieve
+   *
+   * @return the AuthenticatedEntity corresponding to the given identifier
+   */
   AuthenticatedEntity get(Identifier id);
 
+  /**
+   * Returns the size of the ADS.
+   *
+   * @return the size of the ADS
+   */
   int size();
 }

src/main/java/modules/ads/MembershipProof.java

@@ -1,8 +1,7 @@
 package modules.ads;
 
-import java.util.ArrayList;
-
 import model.crypto.Sha3256Hash;
+import modules.ads.merkletree.MerklePath;
 
 /**
  * Represents a Merkle Proof of membership against a certain root identifier.
@@ -16,11 +15,9 @@ public interface MembershipProof {
   Sha3256Hash getRoot();
 
   /**
-   * Returns the path of the proof of membership.
+   * Returns the merkle path of the proof of membership.
    *
-   * @return path of the proof of membership.
+   * @return merkle path of the proof of membership.
    */
-  ArrayList<Sha3256Hash> getPath();
-
-  ArrayList<Boolean> getIsLeftNode();
+  MerklePath getMerklePath();
 }

src/main/java/modules/ads/merkletree/MerkleNode.java

@@ -70,34 +70,69 @@ public MerkleNode(Sha3256Hash hash, MerkleNode left, MerkleNode right) {
     this.hash = hash;
   }
 
+  /**
+   * Returns the left child of the node.
+   *
+   * @return the left child of the node
+   */
   @SuppressFBWarnings(value = "EI_EXPOSE_REP", justification = "internal representation is intentionally returned")
   public MerkleNode getLeft() {
     return left;
   }
 
+  /**
+   * Returns the right child of the node.
+   *
+   * @return the right child of the node
+   */
   @SuppressFBWarnings(value = "EI_EXPOSE_REP", justification = "internal representation is intentionally returned")
   public MerkleNode getRight() {
     return right;
   }
 
+  /**
+   * Returns the parent of the node.
+   *
+   * @return the parent of the node
+   */
   @SuppressFBWarnings(value = "EI_EXPOSE_REP", justification = "internal representation is intentionally returned")
   public MerkleNode getParent() {
     return parent;
   }
 
+  /**
+   * Sets the parent of the node.
+   *
+   * @param parent the parent of the node
+   */
   @SuppressFBWarnings(value = "EI_EXPOSE_REP2", justification = "parent is intentionally mutable externally")
   public void setParent(MerkleNode parent) {
     this.parent = parent;
   }
 
+  /**
+   * Returns the hash corresponding to the node.
+   *
+   * @return the hash corresponding to the node
+   */
   public Sha3256Hash getHash() {
     return hash;
   }
 
+  /**
+   * Returns true if the node is a left child, false otherwise.
+   *
+   * @return true if the node is a left child, false otherwise
+   */
   public boolean isLeft() {
     return isLeft;
   }
 
+  /**
+   * Sets if the node is a left child.
+   *
+   * @param isLeft true if the node is a left child, false otherwise
+   */
   public void setLeft(boolean isLeft) {
     this.isLeft = isLeft;
   }

src/main/java/modules/ads/merkletree/MerklePath.java

@@ -0,0 +1,102 @@
+package modules.ads.merkletree;
+
+import java.util.ArrayList;
+import java.util.Objects;
+
+import model.crypto.Sha3256Hash;
+
+/**
+ * A MerklePath is a list of hashes that represents the path from the node to the root and an arraylist which
+ * contains which child (left or right) the nodes in the path is.
+ */
+public class MerklePath {
+  private ArrayList<Sha3256Hash> path;
+  private ArrayList<Boolean> isLeftNode;
+
+  /**
+   * Default constructor for a MerklePath.
+   */
+  public MerklePath() {
+    this.path = new ArrayList<>();
+    this.isLeftNode = new ArrayList<>();
+  }
+
+  /**
+   * Constructor for a MerklePath from another MerklePath.
+   *
+   * @param merklePath the MerklePath to copy.
+   */
+  public MerklePath(MerklePath merklePath) {
+    this.path = new ArrayList<>(merklePath.path);
+    this.isLeftNode = new ArrayList<>(merklePath.isLeftNode);
+  }
+
+  /**
+   * Constructor with path and isLeftNode.
+   *
+   * @param path       the path of the proof.
+   * @param isLeftNode the isLeftNode of the MerklePath.
+   */
+  public MerklePath(ArrayList<Sha3256Hash> path, ArrayList<Boolean> isLeftNode) {
+    this.path = new ArrayList<>(path);
+    this.isLeftNode = new ArrayList<>(isLeftNode);
+  }
+
+  /**
+   * Adds a new node and its isLeft boolean to the merklePath.
+   *
+   * @param hash       the hash of the node.
+   * @param isLeftNode the isLeftNode of the node.
+   */
+  public void add(Sha3256Hash hash, boolean isLeftNode) {
+    this.path.add(hash);
+    this.isLeftNode.add(isLeftNode);
+  }
+
+  /**
+   * Returns the path of the MerklePath.
+   *
+   * @return the path of the MerklePath.
+   */
+  public ArrayList<Sha3256Hash> getPath() {
+    return new ArrayList<>(path);
+  }
+
+  /**
+   * Returns the isLeftNode of the MerklePath.
+   *
+   * @return the isLeftNode of the MerklePath.
+   */
+  public ArrayList<Boolean> getIsLeftNode() {
+    return new ArrayList<>(isLeftNode);
+  }
+
+  /**
+   * Checks if two MerklePaths are equal.
+   *
+   * @param o the other MerklePath.
+   *
+   * @return true if the MerklePaths are equal, false otherwise.
+   */
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+    MerklePath that = (MerklePath) o;
+    return path.equals(that.path) && isLeftNode.equals(that.isLeftNode);
+  }
+
+  /**
+   * Returns the hashcode of the MerklePath.
+   *
+   * @return the hashcode of the MerklePath.
+   */
+  @Override
+  public int hashCode() {
+    return Objects.hash(path, isLeftNode);
+  }
+}

src/main/java/modules/ads/merkletree/MerkleProof.java

@@ -1,52 +1,54 @@
 package modules.ads.merkletree;
 
-import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Objects;
 
-import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import model.crypto.Sha3256Hash;
 import modules.ads.MembershipProof;
 
 /**
  * A proof of membership in a Merkle tree.
  */
 public class MerkleProof implements MembershipProof {
-  private ArrayList<Sha3256Hash> path;
-  private final ArrayList<Boolean> isLeftNode;
+  private final MerklePath merklePath;
   private final Sha3256Hash root;
 
   /**
    * Constructs a proof from a list of hashes and a root.
    *
-   * @param path       the list of hashes
    * @param root       the root
-   * @param isLeftNode the list of isLeft Boolean values of the hashes
+   * @param merklePath the merkle path of the proof and their isLeft booleans
    */
-  public MerkleProof(ArrayList<Sha3256Hash> path, Sha3256Hash root, ArrayList<Boolean> isLeftNode) {
-    this.path = new ArrayList<>(path);
+  public MerkleProof(Sha3256Hash root, MerklePath merklePath) {
     this.root = root;
-    this.isLeftNode = new ArrayList<>(isLeftNode);
-  }
-
-  @Override
-  public ArrayList<Sha3256Hash> getPath() {
-    return new ArrayList<>(path);
-  }
-
-  public void setPath(ArrayList<Sha3256Hash> path) {
-    this.path = new ArrayList<>(path);
-  }
-
-  @SuppressFBWarnings(value = "EI_EXPOSE_REP", justification = "internal representation is intentionally returned")
-  public ArrayList<Boolean> getIsLeftNode() {
-    return isLeftNode;
+    this.merklePath = new MerklePath(merklePath);
   }
 
+  /**
+   * Return the root of the Merkle tree.
+   *
+   * @return the root of the Merkle tree.
+   */
   public Sha3256Hash getRoot() {
     return root;
   }
 
+  /**
+   * Returns the merkle path of the proof of membership.
+   *
+   * @return merkle path of the proof of membership.
+   */
+  @Override
+  public MerklePath getMerklePath() {
+    return new MerklePath(merklePath);
+  }
+
+  /**
+   * Checks if two MerkleProofs are equal.
+   *
+   * @param o the other MerkleProof
+   *
+   * @return true if the MerkleProofs are equal, false otherwise
+   */
   @Override
   public boolean equals(Object o) {
     if (this == o) {
@@ -55,17 +57,17 @@ public boolean equals(Object o) {
     if (o == null || getClass() != o.getClass()) {
       return false;
     }
-    MerkleProof proof = (MerkleProof) o;
-    for (int i = 0; i < path.size(); i++) {
-      if (!Arrays.equals(path.get(i).getBytes(), proof.path.get(i).getBytes())) {
-        return false;
-      }
-    }
-    return root.equals(proof.root);
+    MerkleProof that = (MerkleProof) o;
+    return merklePath.equals(that.merklePath) && root.equals(that.root);
   }
 
+  /**
+   * Returns the hash code of the MerkleProof.
+   *
+   * @return the hash code of the MerkleProof.
+   */
   @Override
   public int hashCode() {
-    return Objects.hash(path, root);
+    return Objects.hash(merklePath, root);
   }
 }