PartialMerkleTree
Keywords: net.corda.core.crypto.PartialMerkleTree class
Date: 2023-09-18

net.corda.core.crypto

## Class PartialMerkleTree

- net.corda.core.crypto.PartialMerkleTree

-     public class PartialMerkleTree

  Building and verification of Partial Merkle Tree. Partial Merkle Tree is a minimal tree needed to check that a given set of leaves belongs to a full Merkle Tree.

  Example of Merkle tree with 5 leaves.

  `

                   h15
                /       \
               h14       h55
              /  \      /  \
            h12  h34   h50 h00
           / \   / \   / \  / \
          l1 l2 l3 l4 l5 0 0  0

  `

  l* denote hashes of leaves, h* - hashes of nodes below. 0 denotes zero hash, we use it to pad not full binary trees, so the number of leaves is always a power of 2.

  Example of Partial tree based on the tree above.

  `

                 ___
              /       \
              _        _
            /  \      /  \
          h12   _     _   h00
               / \   / \
              I3 l4 I5 0

  `

  We want to check l3 and l5 - now turned into IncudedLeaf (I3 and I5 above). To verify that these two leaves belong to the tree with a hash root h15 we need to provide a Merkle branch (or partial tree). In our case we need hashes: h12, l4, 0 and h00. Verification is done by hashing the partial tree to obtain the root and checking it against the obtained h15 hash. Additionally we store included hashes used in calculation and compare them to leaves hashes we got (there can be a difference in obtained leaves ordering - that's why it's a set comparison not hashing leaves into a tree). If both equalities hold, we can assume that l3 and l5 belong to the transaction with root h15.

- - ### Field Detail

    - #### Companion

          public static net.corda.core.crypto.PartialMerkleTree.Companion Companion

  - ### Constructor Detail

    - #### PartialMerkleTree

          public PartialMerkleTree(@NotNull
                                   net.corda.core.crypto.PartialMerkleTree.PartialTree root)

      Building and verification of Partial Merkle Tree. Partial Merkle Tree is a minimal tree needed to check that a given set of leaves belongs to a full Merkle Tree.

      Example of Merkle tree with 5 leaves.

      `

                       h15
                    /       \
                   h14       h55
                  /  \      /  \
                h12  h34   h50 h00
               / \   / \   / \  / \
              l1 l2 l3 l4 l5 0 0  0

      `

      l* denote hashes of leaves, h* - hashes of nodes below. 0 denotes zero hash, we use it to pad not full binary trees, so the number of leaves is always a power of 2.

      Example of Partial tree based on the tree above.

      `

                     ___
                  /       \
                  _        _
                /  \      /  \
              h12   _     _   h00
                   / \   / \
                  I3 l4 I5 0

      `

      We want to check l3 and l5 - now turned into IncudedLeaf (I3 and I5 above). To verify that these two leaves belong to the tree with a hash root h15 we need to provide a Merkle branch (or partial tree). In our case we need hashes: h12, l4, 0 and h00. Verification is done by hashing the partial tree to obtain the root and checking it against the obtained h15 hash. Additionally we store included hashes used in calculation and compare them to leaves hashes we got (there can be a difference in obtained leaves ordering - that's why it's a set comparison not hashing leaves into a tree). If both equalities hold, we can assume that l3 and l5 belong to the transaction with root h15.

  - ### Method Detail

    - #### verify

          public boolean verify(@NotNull
                                SecureHash merkleRootHash,
                                @NotNull
                                java.util.List<? extends net.corda.core.crypto.SecureHash> hashesToCheck)

      Function to verify a `class PartialMerkleTree` against an input Merkle root and a list of leaves. The tree should only contain the leaves defined in `hashesToCheck`.

      Parameters:
        `merkleRootHash` - Hash that should be checked for equality with root calculated from this partial tree.
        `hashesToCheck` - List of included leaves hashes that should be found in this partial tree.
      See Also:
        `class PartialMerkleTree`, `hashesToCheck`

    - #### leafIndex

          @CordaInternal
          public int leafIndex(@NotNull
                                              SecureHash leaf)

      Method to return the index of the input leaf in the partial Merkle tree structure.

      Parameters:
        `leaf` - the component hash to check.
      Returns:
        leaf-index of this component (starting from zero).
      Throws:
        `MerkleTreeException` - if the provided hash is not in the tree.

    - #### getRoot

          @NotNull
          public net.corda.core.crypto.PartialMerkleTree.PartialTree getRoot()