Add a MerkleProof.processProof utility function

CHANGELOG.md

@@ -10,6 +10,7 @@
  * `Governor`: shift vote start and end by one block to better match Compound's GovernorBravo and prevent voting at the Governor level if the voting snapshot is not ready. ([#2892](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/#2892))
  * `PaymentSplitter`: now supports ERC20 assets in addition to Ether. ([#2858](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/#2858))
  * `ECDSA`: add a variant of `toEthSignedMessageHash` for arbitrary length message hashing. ([#2865](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/#2865))
+ * `MerkleProof`: add a `processProof` function that returns the rebuilt root hash, and a unique leaf indentifier, given a leaf and a proof. ([#2841](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2841))
 
 ## 4.3.2 (2021-09-14)
 

contracts/mocks/MerkleProofWrapper.sol

@@ -12,4 +12,8 @@ contract MerkleProofWrapper {
     ) public pure returns (bool) {
         return MerkleProof.verify(proof, root, leaf);
     }
+
+    function processProof(bytes32[] memory proof, bytes32 leaf) public pure returns (bytes32, uint256) {
+        return MerkleProof.processProof(proof, leaf);
+    }
 }

contracts/utils/cryptography/MerkleProof.sol

@@ -23,21 +23,40 @@ library MerkleProof {
         bytes32 root,
         bytes32 leaf
     ) internal pure returns (bool) {
-        bytes32 computedHash = leaf;
+        // Check if the computed hash (root) is equal to the provided root
+        (bytes32 computedHash, ) = processProof(proof, leaf);
+        return computedHash == root;
+    }
 
+    /**
+     * @dev Returns the rebuilt hash obtained by traversing a Merklee tree up
+     * from `leaf` using `proof`, and an index uniquelly identifying the leaf
+     * location in the tree. A `proof` is valid if and only if the rebuilt hash
+     * matches the root of the tree. When processing the proof, the pairs of
+     * leafs & pre-images are assumed to be sorted.
+     * The produced index is unique in the sens that processing two valid proofs
+     * will return the same indices if and only if the leaf at the same location
+     * in the tree. This helps distinguishing two leaves that have the same
+     * bytes32 identifier but are present in different locations in the merkle
+     * tree.
+     *
+     * _Available since v4.4._
+     */
+    function processProof(bytes32[] memory proof, bytes32 leaf) internal pure returns (bytes32, uint256) {
+        bytes32 computedHash = leaf;
+        uint256 index = 0;
         for (uint256 i = 0; i < proof.length; i++) {
             bytes32 proofElement = proof[i];
-
+            index <<= 1;
             if (computedHash <= proofElement) {
                 // Hash(current computed hash + current element of the proof)
                 computedHash = keccak256(abi.encodePacked(computedHash, proofElement));
             } else {
                 // Hash(current element of the proof + current computed hash)
                 computedHash = keccak256(abi.encodePacked(proofElement, computedHash));
+                index |= 1;
             }
         }
-
-        // Check if the computed hash (root) is equal to the provided root
-        return computedHash == root;
+        return (computedHash, index);
     }
 }

test/utils/cryptography/MerkleProof.test.js

@@ -56,4 +56,24 @@ contract('MerkleProof', function (accounts) {
       expect(await this.merkleProof.verify(badProof, root, leaf)).to.equal(false);
     });
   });
+
+  describe('processProof', function () {
+    it('create unique indices', async function () {
+      const elements = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/='.split('');
+      const merkleTree = new MerkleTree(elements, keccak256, { hashLeaves: true, sortPairs: true });
+
+      const root = merkleTree.getHexRoot();
+
+      const results = await Promise.all(elements
+        .map(element => keccak256(element))
+        .map(leaf => this.merkleProof.processProof(merkleTree.getHexProof(leaf), leaf)),
+      );
+
+      // All reconstructed roots are correct
+      expect(results.map(result => result[0])).to.have.members(Array(elements.length).fill(root));
+
+      // Indices are unique
+      expect(results.map(result => result[1].toNumber()).every((index, i, indices) => indices.indexOf(i) === index));
+    });
+  });
 });