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 Modes）

FHEVM Hardhat 插件为合约开发与测试的不同阶段提供了三种FHEVM 运行时模式，每种模式都在速度、加密强度与状态持久性之间做出取舍：

1. Hardhat（In-Memory）默认网络：🧪使用 Mock 加密。适用于常规测试、CI 测试覆盖率统计以及早期合约开发阶段的快速反馈。此模式不涉及任何真实加密计算，运行速度极快。

2. Hardhat Node（本地服务器）网络：🧪使用 Mock 加密。适用于需要持久化状态的场景，例如测试前端交互、模拟完整用户流程，或在贴近真实的环境中验证部署流程。该模式依然使用 Mock 加密，但状态保存在本地节点进程中，可跨多次调用保留。

3. Sepolia 测试网：🔐使用真实加密。当合约逻辑在本地验证稳定后使用此模式。这是唯一运行在完整 FHEVM 技术栈之上、使用真实加密值的模式，模拟真实生产环境条件，但速度较慢，且需要 Sepolia 测试网 ETH 支付 Gas。

关于 Zama Testnet 的重要说明Zama Testnet 本身并非一条区块链，而是一种协议，使你能够在现有区块链（如 Ethereum、Base 等）上运行机密智能合约，并提供加密类型的支持。目前 Zama Protocol 仅在Sepolia 测试网上可用，未来会逐步支持更多链（可参考仓库 docs/protocol 目录下的协议架构文档）。

三种模式速览

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合约交互

在项目根目录依次执行以下命令，完整走一遍"解密当前值 → 加密递增 → 再次解密"的闭环：

1. 解密当前计数器值：

npx hardhat --network localhost task:decrypt-count

2. 将计数器递增 1：

npx hardhat --network localhost task:increment --value 1

3. 再次解密新的计数器值：

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 sepolia

clean用于清除之前针对其他网络（如本地 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合约交互

在项目根目录依次执行（每步耗时较长，请耐心等待）：

1. 解密当前计数器值（⏳ 等待…）：

npx hardhat --network sepolia task:decrypt-count

2. 将计数器递增 1（⏳ 等待…）：

npx hardhat --network sepolia task:increment --value 1

3. 解密新的计数器值（⏳ 等待…）：

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 配置变量：

• MNEMONIC：12 词助记词，用于生成以太坊钱包私钥，可通过npx hardhat vars set MNEMONIC设置；
• INFURA_API_KEY：Infura 项目密钥，用于连接 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 API（createEncryptedInput/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