Fix MerkleProof generation in tests and add some documentation (#2585)

contracts/utils/cryptography/MerkleProof.sol

@@ -3,7 +3,13 @@
 pragma solidity ^0.8.0;
 
 /**
- * @dev These functions deal with verification of Merkle trees (hash trees),
+ * @dev These functions deal with verification of Merkle Trees proofs.
+ *
+ * The proofs can be generated using the JavaScript library
+ * https://github.com/miguelmota/merkletreejs[merkletreejs].
+ * Note: the hashing algorithm should be keccak256 and pair sorting should be enabled.
+ *
+ * See `test/utils/cryptography/MerkleProof.test.js` for some examples.
  */
 library MerkleProof {
     /**

test/utils/cryptography/MerkleProof.test.js

@@ -14,8 +14,8 @@ contract('MerkleProof', function (accounts) {
 
   describe('verify', function () {
     it('returns true for a valid Merkle proof', async function () {
-      const elements = ['a', 'b', 'c', 'd'];
-      const merkleTree = new MerkleTree(elements, keccak256, { hashLeaves: true });
+      const elements = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/='.split('');
+      const merkleTree = new MerkleTree(elements, keccak256, { hashLeaves: true, sortPairs: true });
 
       const root = merkleTree.getHexRoot();
 
@@ -28,7 +28,7 @@ contract('MerkleProof', function (accounts) {
 
     it('returns false for an invalid Merkle proof', async function () {
       const correctElements = ['a', 'b', 'c'];
-      const correctMerkleTree = new MerkleTree(correctElements, keccak256, { hashLeaves: true });
+      const correctMerkleTree = new MerkleTree(correctElements, keccak256, { hashLeaves: true, sortPairs: true });
 
       const correctRoot = correctMerkleTree.getHexRoot();
 
@@ -37,14 +37,14 @@ contract('MerkleProof', function (accounts) {
       const badElements = ['d', 'e', 'f'];
       const badMerkleTree = new MerkleTree(badElements);
 
-      const badProof = badMerkleTree.getHexProof(badElements[0], keccak256, { hashLeaves: true });
+      const badProof = badMerkleTree.getHexProof(badElements[0], keccak256, { hashLeaves: true, sortPairs: true });
 
       expect(await this.merkleProof.verify(badProof, correctRoot, correctLeaf)).to.equal(false);
     });
 
     it('returns false for a Merkle proof of invalid length', async function () {
       const elements = ['a', 'b', 'c'];
-      const merkleTree = new MerkleTree(elements, keccak256, { hashLeaves: true });
+      const merkleTree = new MerkleTree(elements, keccak256, { hashLeaves: true, sortPairs: true });
 
       const root = merkleTree.getHexRoot();