fhevm Hardhat 测试运行指南：三种 FHEVM 运行时模式的实战演练

fhevm Hardhat 测试运行指南三种 FHEVM 运行时模式的实战演练【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本篇指南聚焦于在 Hardhat 项目中运行 FHEVM 智能合约测试的完整流程覆盖 FHEVM 插件提供的三种运行时模式内存模式、本地节点模式与 Sepolia 测试网模式的选择依据、操作命令与实战步骤。读完本文你将掌握如何使用npx hardhat test、npx hardhat node、npx hardhat deploy等命令在三种环境中测试、部署并交互FHECounter合约并能结合仓库源码理解 FHEVM 运行时初始化与加密/解密 API 的底层机制。FHEVM 运行时模式FHEVM Runtime ModesFHEVM Hardhat 插件为合约开发与测试的不同阶段提供了三种FHEVM 运行时模式每种模式都在速度、加密强度与状态持久性之间做出取舍HardhatIn-Memory默认网络使用 Mock 加密。适用于常规测试、CI 测试覆盖率统计以及早期合约开发阶段的快速反馈。此模式不涉及任何真实加密计算运行速度极快。Hardhat Node本地服务器网络使用 Mock 加密。适用于需要持久化状态的场景例如测试前端交互、模拟完整用户流程或在贴近真实的环境中验证部署流程。该模式依然使用 Mock 加密但状态保存在本地节点进程中可跨多次调用保留。Sepolia 测试网使用真实加密。当合约逻辑在本地验证稳定后使用此模式。这是唯一运行在完整 FHEVM 技术栈之上、使用真实加密值的模式模拟真实生产环境条件但速度较慢且需要 Sepolia 测试网 ETH 支付 Gas。关于 Zama Testnet 的重要说明Zama Testnet 本身并非一条区块链而是一种协议使你能够在现有区块链如 Ethereum、Base 等上运行机密智能合约并提供加密类型的支持。目前 Zama Protocol 仅在Sepolia 测试网上可用未来会逐步支持更多链可参考仓库 docs/protocol 目录下的协议架构文档。三种模式速览模式加密持久化链速度适用场景Hardhat默认 Mock❌ 否In-Memory⚡⚡ 极快快速本地测试与覆盖率统计Hardhat Node Mock✅ 是本地服务器⚡ 快前端集成与本地持久化测试Sepolia 测试网 真实加密✅ 是远程服务器 慢使用真实加密数据的全栈验证FHEVM Hardhat Template三种测试模式的演示载体为演示上述三种测试模式原文档使用 fhevm-hardhat-template 模板项目。该模板预装了 FHEVM Hardhat Plugin内置一个基础FHECounter智能合约并附带一组现成的 Hardhat 任务task用于与已部署的合约实例交互。仓库 docs/examples/fhe-counter.md 提供了FHECounter.sol的完整参考实现其核心逻辑如下// SPDX-License-Identifier: BSD-3-Clause-Clear pragma solidity ^0.8.24; import { FHE, euint32, externalEuint32 } from fhevm/solidity/lib/FHE.sol; import { ZamaEthereumConfig } from fhevm/solidity/config/ZamaConfig.sol; /// title A simple FHE counter contract contract FHECounter is ZamaEthereumConfig { euint32 private _count; function getCount() external view returns (euint32) { return _count; } function increment(externalEuint32 inputEuint32, bytes calldata inputProof) external { euint32 encryptedEuint32 FHE.fromExternal(inputEuint32, inputProof); _count FHE.add(_count, encryptedEuint32); FHE.allowThis(_count); FHE.allow(_count, msg.sender); } function decrement(externalEuint32 inputEuint32, bytes calldata inputProof) external { euint32 encryptedEuint32 FHE.fromExternal(inputEuint32, inputProof); _count FHE.sub(_count, encryptedEuint32); FHE.allowThis(_count); FHE.allow(_count, msg.sender); } }注意两点FHECounter继承自ZamaEthereumConfig合约因此能在链上自动感知 Zama 协议在 Sepolia 上的部署地址这正是 docs/solidity-guides/foundry/deploy.md 中提到的合约通过ZamaEthereumConfig自动获取 FHEVM 地址机制同时increment/decrement的入参由单个uint32变为externalEuint32 bytes inputProof两个参数前者是被加密的值bytes32handle后者是证明加密有效性的零知识证明。在 Hardhat 默认网络In-Memory上运行测试使用 FHEVM Mock 值在内存中运行测试只需一条命令在项目根目录执行npx hardhat test --network hardhat这是日常开发中最常用的模式无需启动任何节点进程测试用例在每次运行后即被丢弃适合快速迭代与 CI 覆盖率收集。源码佐证仓库 library-solidity/hardhat.config.ts 展示了 FHEVM 项目为test任务做的运行时准备工作——在真正执行测试前它会从node_modules/fhevm/host-contracts/contracts复制宿主链合约到本地临时目录fhevmTemp/contracts并在hardhat网络下自动执行task:deployAllHostContracts含 KMS 生成与task:addHostPausers。这说明 FHEVM 测试并非只跑一个合约而是会在后台部署 ACL、KMS、InputVerifier 等宿主链基础设施合约为加密输入验证提供支撑。在 Hardhat Node本地服务器上运行当需要持久化状态如测试前端交互、模拟完整用户流程、验证部署流程时可将测试切换到本地 Hardhat 节点。完整流程分为四步。第 1 步启动 Hardhat Node 服务器打开一个新终端窗口在项目根目录执行npx hardhat node节点启动后会保持运行监听 RPC 请求所有部署与交互的状态都持久保存在该节点进程中。第 2 步运行测试套件可选另开终端在项目根目录执行npx hardhat test --network localhost测试将针对已启动的本地节点执行与 in-memory 模式不同这里的状态在节点存活期间可以跨测试文件、跨命令保留。第 3 步在 Hardhat Node 上部署FHECounter合约在项目根目录执行npx hardhat deploy --network localhost部署完成后可以检查已部署合约的 FHEVM 配置是否完备npx hardhat fhevm check-fhevm-compatibility --network localhost --address deployed contract address其中deployed contract address需替换为实际部署地址。该检查会验证合约是否已按 FHEVM 规范正确编译、其依赖的 FHEVM 基础设施地址是否配置完整。第 4 步与已部署的FHECounter合约交互在项目根目录依次执行以下命令完整走一遍解密当前值 → 加密递增 → 再次解密的闭环解密当前计数器值npx hardhat --network localhost task:decrypt-count将计数器递增 1npx hardhat --network localhost task:increment --value 1再次解密新的计数器值npx hardhat --network localhost task:decrypt-count第二次解密输出应比第一次多 1从而验证加密加法在链上正确执行。任务实现细节task:decrypt-count这类自定义任务的写法在 docs/solidity-guides/hardhat/write_task.md 中有逐行讲解关键点在于自定义任务必须在开头显式调用await fhevm.initializeCLIApi()——与内置的test、compile任务会自动初始化 FHEVM 运行时环境不同自定义任务需要手动完成初始化否则fhevmAPI 不可用。随后通过fhevm.userDecryptEuint(FhevmType.euint32, encryptedCount, contractAddress, signer)将链上密文句柄解密为明文。在 Sepolia 以太坊测试网上运行当合约逻辑在本地稳定后即可切换到真实加密环境进行全栈验证。完整流程同样分为四步。第 1 步为 Sepolia 重新构建项目在项目根目录执行npx hardhat clean npx hardhat compile --network sepoliaclean用于清除之前针对其他网络如本地 Mock 环境生成的 artifacts 与 cache确保合约针对 Sepolia 网络重新编译。第 2 步在 Sepolia 上部署FHECounter合约npx hardhat deploy --network sepolia部署交易需要消耗 Sepolia ETH请确保部署账户有足够余额。第 3 步检查已部署合约的 FHEVM 配置在项目根目录执行npx hardhat fhevm check-fhevm-compatibility --network sepolia --address deployed contract address如果抛出内部异常internal exception通常意味着合约没有针对 Sepolia 网络正确编译——此时需要回到第 1 步重新执行clean与针对sepolia的compile。第 4 步与已部署的FHECounter合约交互在项目根目录依次执行每步耗时较长请耐心等待解密当前计数器值⏳ 等待…npx hardhat --network sepolia task:decrypt-count将计数器递增 1⏳ 等待…npx hardhat --network sepolia task:increment --value 1解密新的计数器值⏳ 等待…npx hardhat --network sepolia task:decrypt-count与本地 Mock 模式的即时响应不同Sepolia 模式每一步都涉及真实 TFHE 加密/解密运算与链上交易确认延迟明显更高这正是真实生产环境下的体验。深入理解网络配置与运行环境的前提Hardhat 网络配置骨架FHEVM 项目的 library-solidity/hardhat.config.ts 展示了典型的网络配置结构hardhat内存、sepolia、mainnet、staging等网络共用同一个getChainConfig工厂函数通过RPC_URL环境变量指定 JSON-RPC 端点默认回退到http://127.0.0.1:8756并通过MNEMONIC环境变量派生账户。默认 mnemonic 仅用于避免本地部署时崩溃切勿用于真实网络部署。Sepolia 部署的必配环境变量参考 docs/solidity-guides/getting-started/quick-start-tutorial/setup.md若计划部署到 Sepolia需要配置两个 Hardhat 配置变量MNEMONIC12 词助记词用于生成以太坊钱包私钥可通过npx hardhat vars set MNEMONIC设置INFURA_API_KEYInfura 项目密钥用于连接 Sepolia 等以太坊测试网可通过npx hardhat vars set INFURA_API_KEY设置。若跳过配置Hardhat 会回退到默认值test test test test test test test test test test test junk与占位 API Key这些默认值不适用于真实部署。缺失变量时会报错Error HH1201: Cannot find a value for the configuration variable MNEMONIC按提示执行npx hardhat vars set MNEMONIC即可。Mock 与真实加密模式的机制差异从源码结构可以推断两种模式的本质区别Mock 模式hardhat/localhost下 FHEVM 在本地以模拟方式处理加密值无真实 TFHE 计算因此毫秒级响应Sepolia 模式则由 Zama 协处理器coprocessor集群在链下完成真实同态运算并通过链上验证见仓库 coprocessor 与 relayer 目录中的实现保证结果可信。这也是为什么 Sepolia 模式能够模拟真实生产环境条件而本地模式更适合快速开发反馈。结语本文完整复现了 FHEVM Hardhat 三种运行时模式的测试与部署流程用--network hardhat做快速迭代与覆盖率用--network localhost做持久化交互验证用--network sepolia做真实加密全栈验证。配合 docs/solidity-guides/hardhat/write_test.md 中的 FHEVM APIcreateEncryptedInput/userDecryptEuint与 docs/solidity-guides/hardhat/write_task.md 中的自定义任务写法你可以将任何 FHEVM 合约接入这套本地快速测试 → 节点持久化验证 → 测试网真实加密上线的完整工作流。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考