如何用 OpenZeppelin Contracts MerkleProof 在链上验证白名单 Merkle 证明【免费下载链接】openzeppelin-contractsOpenZeppelin Contracts is a library for secure smart contract development.项目地址: https://gitcode.com/GitHub_Trending/op/openzeppelin-contracts白名单空投、限量铸造等场景里完整的名单放在链上成本太高常见做法是把名单的 Merkle 树在链下构建好只把根哈希root写入合约用户上链时提交自己所在叶子的证明proof合约用 OpenZeppelin Contracts 的 MerkleProof 库验证这个叶子确实属于这棵树。本文基于当前仓库的实现Solidity 要求^0.8.20走一遍完整路径链下建树取证明 → 链上写验证合约 → 按项目测试用例的判断标准核对验证结果。链下构建白名单树并生成证明MerkleProof.sol 的文件头注释和 utilities.adoc 都指出树和证明可以用 OpenZeppelin 的merkle-treeJavaScript 库在链下生成该库开箱即用地规避了 64 字节叶子攻击见下文边界与限制。项目自己的测试 MerkleProof.test.js 演示了最直接的用法const { SimpleMerkleTree } require(openzeppelin/merkle-tree); const { ethers } require(hardhat); // 测试文件 toLeaves把每个白名单条目转成 keccak256 哈希作为叶子 const toLeaves (str, separator ) str.split(separator).map(e ethers.keccak256(ethers.toUtf8Bytes(e))); // 测试文件 defaultHash内部节点取排序后拼接的 keccak256 const concatSorted (...elements) Buffer.concat(elements.map(ethers.getBytes).sort(Buffer.compare)); const nodeHash (a, b) ethers.keccak256(concatSorted(a, b)); const merkleTree SimpleMerkleTree.of(toLeaves(abc), { nodeHash }); // abc 仅为文档示例实际替换为你的白名单条目 const root merkleTree.root; // 部署时写入合约 const hash merkleTree.at(0); // 第 0 个条目的叶子哈希即链上验证的 leaf 参数 const proof merkleTree.getProof(0); // 该叶子到根的兄弟哈希数组产出三样东西root上链、hash叶子的 keccak256 哈希、proof兄弟哈希数组。注意叶子不是条目原文而是ethers.keccak256(ethers.toUtf8Bytes(条目))——链上合约收到的leaf参数必须与这个构造方式一致否则验证必然失败。链上写入 root 并调用 verify 验证库提供两组等价函数均支持传入自定义哈希函数hasher的重载verify/processProofproof 在内存中处理默认哈希函数verifyCalldata/processProofCalldataproof 直接在 calldata 中处理调用方传入证明时优先用这一组MerkleProof.sol 的注释区分了二者。默认路径下未传hasher库内部用Hashes.commutativeKeccak256逐层把当前哈希与兄弟哈希排序后拼接再 keccak256与上面链下defaultHash的规则一致。仓库的 remappings.txt 已把openzeppelin/contracts/映射到contracts/可直接按包名导入。一个最小可部署的白名单验证合约示例中root_用链下merkleTree.root的值替换// SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import {MerkleProof} from openzeppelin/contracts/utils/cryptography/MerkleProof.sol; contract WhitelistMerkle { bytes32 public immutable merkleRoot; constructor(bytes32 root_) { merkleRoot root_; } /// proof 是链下 getProof 生成的兄弟哈希数组leaf 是白名单条目的 keccak256 哈希 function verifyWhitelist(bytes32[] calldata proof, bytes32 leaf) external view returns (bool) { return MerkleProof.verifyCalldata(proof, merkleRoot, leaf); } }如果你的业务需要一次提交多个白名单条目例如批量领取可选分支是使用 multiproof 系列multiProofVerifyCalldata(proof, proofFlags, root, leaves)参数对应链下getMultiProof的输出const { proof, proofFlags, leaves } merkleTree.getMultiProof(toLeaves(bdf)); const hashes leaves.map(e merkleTree.leafHash(e)); // 每个叶子的哈希作为链上 leaves 参数multiproof 有明确适用条件MerkleProof.sol 注释树必须是完整的complete但不必完美且待证明叶子按从最深层由右向左、逐层继续的逆序排列。如何判断验证成功或失败verify的判定逻辑是processProof从leaf出发、按proof逐层重建根哈希重建结果等于root即返回true。MerkleProof.test.js 覆盖了三种判断基准可直接作为自查标准合法证明processProof(proof, hash)的返回值等于rootverify(proof, root, hash)返回trueL26-L36别的树的证明用另一棵树makeTree(def)的 proof 去对第一棵树的 root 验证verify返回falseL47-L58长度不对的证明把 proof 截短一段proof.slice(0, -1)后验证verify返回falseL61-L73。注意单条verify对无效输入是返回false而不是 revert只有 multiproof 在参数个数不满足leaves.length proof.length proofFlags.length 1时才会以自定义错误MerkleProofInvalidMultiproofrevertMerkleProof.sol L216-L218。边界与限制64 字节叶子警告库头注释明确要求用 keccak256 哈希叶子时避免使用哈希前恰好 64 字节的叶子值否则两个内部节点排序拼接后可能被重新解释成另一个叶子从而为树外值构造出合法证明OpenZeppelin 的 JavaScript 库生成的树天然规避此问题MerkleProof.sol L16-L21。仅支持交换律哈希函数proof 验证只支持H(a, b) H(b, a)的哈希函数非交换律树需要库未提供的额外逻辑L26-L29。要使用自定义交换律哈希例如链下用sha256(abi.encode(a, b))的变体把hasher作为最后一个参数传入verify/verifyCalldata/multiProofVerify*仓库里的 MerkleProofCustomHashMock 是现成的接法示例。multiproof 的空叶子陷阱proof.length 1 leaves.length 0的空集合情形被视为合法 no-op 并返回proof[0]即 root若不在别处校验叶子攻击者可借此证明空名单库注释建议禁止该输入L199-L201。链上建树是另一条路线如果树本身需要维护在链上可追加、可更新叶子应使用 MerkleTree 库而非 MerkleProof本文场景白名单一次性写 root不需要它。验证合约部署后用链下生成的(proof, leaf)调用verifyWhitelist返回true即说明该条目在 root 对应的白名单树内对树外条目或篡改过的 proof按测试基准应得到false。如果你后续要把验证嵌入 mint 逻辑记得把verifyWhitelist的布尔结果接上 revert 或状态标记合约本身不会替你阻断调用。【免费下载链接】openzeppelin-contractsOpenZeppelin Contracts is a library for secure smart contract development.项目地址: https://gitcode.com/GitHub_Trending/op/openzeppelin-contracts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考