Add multiProofVerify (#3276)

CHANGELOG.md

@@ -10,6 +10,7 @@
  * `EnumerableMap`: add new `UintToUintMap` map type. ([#3338](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3338))
  * `EnumerableMap`: add new `Bytes32ToUintMap` map type. ([#3416](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3416))
  * `SafeCast`: add support for many more types, using procedural code generation. ([#3245](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3245))
+ * `MerkleProof`: add `multiProofVerify` to prove multiple values are part of a Merkle tree. ([#3276](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3276))
 
 ## 4.6.0 (2022-04-26)
 

contracts/mocks/MerkleProofWrapper.sol

@@ -16,4 +16,21 @@ contract MerkleProofWrapper {
     function processProof(bytes32[] memory proof, bytes32 leaf) public pure returns (bytes32) {
         return MerkleProof.processProof(proof, leaf);
     }
+
+    function multiProofVerify(
+        bytes32 root,
+        bytes32[] memory leafs,
+        bytes32[] memory proofs,
+        bool[] memory proofFlag
+    ) public pure returns (bool) {
+        return MerkleProof.multiProofVerify(root, leafs, proofs, proofFlag);
+    }
+
+    function processMultiProof(
+        bytes32[] memory leafs,
+        bytes32[] memory proofs,
+        bool[] memory proofFlag
+    ) public pure returns (bytes32) {
+        return MerkleProof.processMultiProof(leafs, proofs, proofFlag);
+    }
 }

contracts/utils/cryptography/MerkleProof.sol

@@ -43,18 +43,75 @@ library MerkleProof {
     function processProof(bytes32[] memory proof, bytes32 leaf) internal pure returns (bytes32) {
         bytes32 computedHash = leaf;
         for (uint256 i = 0; i < proof.length; i++) {
-            bytes32 proofElement = proof[i];
-            if (computedHash <= proofElement) {
-                // Hash(current computed hash + current element of the proof)
-                computedHash = _efficientHash(computedHash, proofElement);
-            } else {
-                // Hash(current element of the proof + current computed hash)
-                computedHash = _efficientHash(proofElement, computedHash);
-            }
+            computedHash = _hashPair(computedHash, proof[i]);
         }
         return computedHash;
     }
 
+    /**
+     * @dev Returns true if a `leafs` can be proved to be a part of a Merkle tree
+     * defined by `root`. For this, `proofs` for each leaf must be provided, containing
+     * sibling hashes on the branch from the leaf to the root of the tree. Then
+     * 'proofFlag' designates the nodes needed for the multi proof.
+     *
+     * _Available since v4.7._
+     */
+    function multiProofVerify(
+        bytes32 root,
+        bytes32[] memory leafs,
+        bytes32[] memory proofs,
+        bool[] memory proofFlag
+    ) internal pure returns (bool) {
+        return processMultiProof(leafs, proofs, proofFlag) == root;
+    }
+
+    /**
+     * @dev Returns the rebuilt hash obtained by traversing a Merkle tree up
+     * from `leaf` using the multi proof as `proofFlag`. A multi proof is
+     * valid if the final hash matches the root of the tree.
+     *
+     * _Available since v4.7._
+     */
+    function processMultiProof(
+        bytes32[] memory leafs,
+        bytes32[] memory proofs,
+        bool[] memory proofFlag
+    ) internal pure returns (bytes32 merkleRoot) {
+        // This function rebuild the root hash by traversing the tree up from the leaves. The root is rebuilt by
+        // consuming and producing values on a queue. The queue starts with the `leafs` array, then goes onto the
+        // `hashes` array. At the end of the process, the last hash in the `hashes` array should contain the root of
+        // the merkle tree.
+        uint256 leafsLen = leafs.length;
+        uint256 proofsLen = proofs.length;
+        uint256 totalHashes = proofFlag.length;
+
+        // Check proof validity.
+        require(leafsLen + proofsLen - 1 == totalHashes, "MerkleProof: invalid multiproof");
+
+        // The xxxPos values are "pointers" to the next value to consume in each array. All accesses are done using
+        // `xxx[xxxPos++]`, which return the current value and increment the pointer, thus mimicking a queue's "pop".
+        bytes32[] memory hashes = new bytes32[](totalHashes);
+        uint256 leafPos = 0;
+        uint256 hashPos = 0;
+        uint256 proofPos = 0;
+        // At each step, we compute the next hash using two values:
+        // - a value from the "main queue". If not all leaves have been consumed, we get the next leaf, otherwise we
+        //   get the next hash.
+        // - depending on the flag, either another value for the "main queue" (merging branches) or an element from the
+        //   `proofs` array.
+        for (uint256 i = 0; i < totalHashes; i++) {
+            bytes32 a = leafPos < leafsLen ? leafs[leafPos++] : hashes[hashPos++];
+            bytes32 b = proofFlag[i] ? leafPos < leafsLen ? leafs[leafPos++] : hashes[hashPos++] : proofs[proofPos++];
+            hashes[i] = _hashPair(a, b);
+        }
+
+        return hashes[totalHashes - 1];
+    }
+
+    function _hashPair(bytes32 a, bytes32 b) private pure returns (bytes32) {
+        return a < b ? _efficientHash(a, b) : _efficientHash(b, a);
+    }
+
     function _efficientHash(bytes32 a, bytes32 b) private pure returns (bytes32 value) {
         /// @solidity memory-safe-assembly
         assembly {

docs/modules/ROOT/pages/utilities.adoc

@@ -26,7 +26,11 @@ WARNING: Getting signature verification right is not trivial: make sure you full
 
 === Verifying Merkle Proofs
 
-xref:api:cryptography.adoc#MerkleProof[`MerkleProof`] provides xref:api:cryptography.adoc#MerkleProof-verify-bytes32---bytes32-bytes32-[`verify`], which can prove that some value is part of a https://en.wikipedia.org/wiki/Merkle_tree[Merkle tree].
+xref:api:cryptography.adoc#MerkleProof[`MerkleProof`] provides:
+
+* xref:api:cryptography.adoc#MerkleProof-verify-bytes32---bytes32-bytes32-[`verify`] - can prove that some value is part of a https://en.wikipedia.org/wiki/Merkle_tree[Merkle tree].
+
+* xref:api:cryptography.adoc#MerkleProof-multiProofVerify-bytes32-bytes32---bytes32---bool---[`multiProofVerify`] - can prove multiple values are part of a Merkle tree.
 
 [[introspection]]
 == Introspection

test/utils/cryptography/MerkleProof.test.js

@@ -1,5 +1,6 @@
 require('@openzeppelin/test-helpers');
 
+const { expectRevert } = require('@openzeppelin/test-helpers');
 const { MerkleTree } = require('merkletreejs');
 const keccak256 = require('keccak256');
 
@@ -62,4 +63,69 @@ contract('MerkleProof', function (accounts) {
       expect(await this.merkleProof.verify(badProof, root, leaf)).to.equal(false);
     });
   });
+
+  describe('multiProofVerify', function () {
+    it('returns true for a valid Merkle multi proof', async function () {
+      const leaves = ['a', 'b', 'c', 'd', 'e', 'f'].map(keccak256).sort(Buffer.compare);
+      const merkleTree = new MerkleTree(leaves, keccak256, { sort: true });
+
+      const root = merkleTree.getRoot();
+      const proofLeaves = ['b', 'f', 'd'].map(keccak256).sort(Buffer.compare);
+      const proof = merkleTree.getMultiProof(proofLeaves);
+      const proofFlags = merkleTree.getProofFlags(proofLeaves, proof);
+
+      expect(await this.merkleProof.multiProofVerify(root, proofLeaves, proof, proofFlags)).to.equal(true);
+    });
+
+    it('returns false for an invalid Merkle multi proof', async function () {
+      const leaves = ['a', 'b', 'c', 'd', 'e', 'f'].map(keccak256).sort(Buffer.compare);
+      const merkleTree = new MerkleTree(leaves, keccak256, { sort: true });
+
+      const root = merkleTree.getRoot();
+      const badProofLeaves = ['g', 'h', 'i'].map(keccak256).sort(Buffer.compare);
+      const badMerkleTree = new MerkleTree(badProofLeaves);
+      const badProof = badMerkleTree.getMultiProof(badProofLeaves);
+      const badProofFlags = badMerkleTree.getProofFlags(badProofLeaves, badProof);
+
+      expect(await this.merkleProof.multiProofVerify(root, badProofLeaves, badProof, badProofFlags)).to.equal(false);
+    });
+
+    it('revert with invalid multi proof #1', async function () {
+      const fill = Buffer.alloc(32); // This could be anything, we are reconstructing a fake branch
+      const leaves = ['a', 'b', 'c', 'd'].map(keccak256).sort(Buffer.compare);
+      const badLeave = keccak256('e');
+      const merkleTree = new MerkleTree(leaves, keccak256, { sort: true });
+
+      const root = merkleTree.getRoot();
+
+      await expectRevert(
+        this.merkleProof.multiProofVerify(
+          root,
+          [ leaves[0], badLeave ], // A, E
+          [ leaves[1], fill, merkleTree.layers[1][1] ],
+          [ false, false, false ],
+        ),
+        'MerkleProof: invalid multiproof',
+      );
+    });
+
+    it('revert with invalid multi proof #2', async function () {
+      const fill = Buffer.alloc(32); // This could be anything, we are reconstructing a fake branch
+      const leaves = ['a', 'b', 'c', 'd'].map(keccak256).sort(Buffer.compare);
+      const badLeave = keccak256('e');
+      const merkleTree = new MerkleTree(leaves, keccak256, { sort: true });
+
+      const root = merkleTree.getRoot();
+
+      await expectRevert(
+        this.merkleProof.multiProofVerify(
+          root,
+          [ badLeave, leaves[0] ], // A, E
+          [ leaves[1], fill, merkleTree.layers[1][1] ],
+          [ false, false, false, false ],
+        ),
+        'reverted with panic code 0x32',
+      );
+    });
+  });
 });