diff --git a/CHANGELOG.md b/CHANGELOG.md index fbaecfb1bc3..5d73a30d241 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/contracts/mocks/MerkleProofWrapper.sol b/contracts/mocks/MerkleProofWrapper.sol index 1e188df36ba..a58e69f3b0e 100644 --- a/contracts/mocks/MerkleProofWrapper.sol +++ b/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); + } } diff --git a/contracts/utils/cryptography/MerkleProof.sol b/contracts/utils/cryptography/MerkleProof.sol index 23ef1f077e3..ea4217c8e79 100644 --- a/contracts/utils/cryptography/MerkleProof.sol +++ b/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 { diff --git a/docs/modules/ROOT/pages/utilities.adoc b/docs/modules/ROOT/pages/utilities.adoc index 81839c16b56..e2649098cff 100644 --- a/docs/modules/ROOT/pages/utilities.adoc +++ b/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 diff --git a/test/utils/cryptography/MerkleProof.test.js b/test/utils/cryptography/MerkleProof.test.js index 61fa45c3ee6..069d7922179 100644 --- a/test/utils/cryptography/MerkleProof.test.js +++ b/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', + ); + }); + }); });