FHEVM Foundry 开发环境搭建指南：Soldeer 依赖管理、forge-fhevm 集成与安装验证

FHEVM Foundry 开发环境搭建指南：Soldeer 依赖管理、forge-fhevm 集成与安装验证

【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm

本指南面向希望使用 Foundry 开发全同态加密（FHE）智能合约的 Solidity 工程师，系统讲解在 FHEVM 生态中搭建 Foundry 工程环境的两种途径：克隆官方 FHEVM Foundry 模板，或在已有 Foundry 项目中以 Soldeer 方式引入forge-fhevm。读完本文，你将掌握foundry.toml与remappings.txt的完整配置方法、forge soldeer install的依赖安装流程，以及如何用一个最小测试用例验证整套环境是否安装成功，并了解测试底层 FHEVM host 合约栈的部署原理。

环境前提

开始之前，请确保本机已安装最新版本的 [Foundry] 工具链（包含forge、cast、anvil三个核心命令）。推荐使用官方foundryup安装脚本完成安装，安装后可通过以下命令确认版本：

forge --version cast --version anvil --version

后续所有步骤均假设forge已在 PATH 中可用，并且当前网络环境能够访问 Soldeer 依赖仓库。

方案一：克隆官方 FHEVM Foundry 模板（推荐）

官方维护了一个开箱即用的 FHEVM Foundry 模板仓库（仓库名fhevm-foundry-template），它内置了完整的可运行工程：

• foundry.toml与remappings.txt两份关键配置文件；
• 一个示例FHECounter加密计数器合约；
• 配套的测试用例；
• 针对本地 Anvil 节点与 Sepolia 测试网的部署脚本。

对于初次接触 FHEVM 的开发者，这是最快、最稳妥的起步方式。

第一步：克隆模板

git clone <fhevm-foundry-template 仓库地址> cd fhevm-foundry-template

第二步：使用 Soldeer 安装依赖

模板使用 [Soldeer]（Foundry 官方依赖管理器）管理依赖，安装命令只有一条：

forge soldeer install

该命令会将以下依赖拉取到项目根目录下的dependencies/目录中：

第三步：编译并运行测试

forge build forge test -vvv

forge build会以foundry.toml中声明的 EVM 版本与编译器版本完成编译；forge test -vvv则会执行模板自带的示例FHECounter测试。如果环境配置正确，你会看到FHECounter相关测试全部通过，这表明 FHEVM host 合约栈已成功部署到 Foundry 的测试 EVM 中，加密输入、执行与解密断言的完整链路均可正常工作。

方案二：为已有 Foundry 项目集成 forge-fhevm

如果你已经有一个正在开发的 Foundry 项目，不需要迁移，只需以 Soldeer 依赖的方式把forge-fhevm加进来即可。官方模板中的foundry.toml与remappings.txt是经过验证的"标准答案"，精确的锁定版本请以模板仓库中的实际文件为准——本文下面给出的配置形态与模板保持一致，仅需将占位符替换为实际版本号。

1. 配置foundry.toml

forge-fhevm面向 Cancun EVM 和较新的 Solidity 编译器。一个典型的配置如下：

[profile.default] src = "src" out = "out" libs = ["dependencies"] test = "test" script = "script" evm_version = "cancun" # solc = "0.8.x" # 以模板中当前测试通过的版本为准 [dependencies] # 以模板 foundry.toml 中的当前版本为准 forge-std = "..." "@encrypted-types" = "..." "@fhevm-solidity" = "..." forge-fhevm = { git = "<forge-fhevm 仓库地址>", rev = "..." } [soldeer] remappings_version = false recursive_deps = true

各配置项的作用如下：

• libs = ["dependencies"]：告诉编译器 Soldeer 的依赖安装在dependencies/目录，编译时需要在导入解析中包含该目录；
• evm_version = "cancun"：forge-fhevm依赖 Cancun EVM 引入的字节码特性（如TSTORE瞬态存储），是 host 合约正常工作的硬性要求，不要随意降低；
• [dependencies]：声明依赖清单；其中forge-fhevm是 git 依赖，需要指定rev锁定提交；
• [soldeer] remappings_version = false：Soldeer 生成 remapping 时不携带版本号后缀，便于保持导入路径稳定；
• [soldeer] recursive_deps = true：允许递归解析依赖的依赖。

作为参考，本仓库内的真实工程也采用了类似的配置：host-contracts/foundry.toml将编译器锁定为solc = '0.8.24'，开启了optimizer = true与optimizer_runs = 200，并将forge-std版本固定为1.11.0（见[dependencies]段）；library-solidity/foundry.toml同样锁定solc = '0.8.24'并将forge-std固定为1.11.0。这些文件可以作为你挑选编译器与依赖版本时的参照。

2. 安装依赖

配置完成后执行：

forge soldeer install

Soldeer 会将[dependencies]中声明的包逐一物化到dependencies/目录下。

3. 添加 remappings

Soldeer 将每个依赖物化到dependencies/<name>-<version>/目录，因此remappings.txt需要为每个导入前缀建立一条映射。配置形态如下：

@fhevm/host-contracts/=dependencies/forge-fhevm-<rev>/src/fhevm-host/ @fhevm/solidity/=dependencies/@fhevm-solidity-<version>/ encrypted-types/=dependencies/@encrypted-types-<version>/ forge-fhevm/=dependencies/forge-fhevm-<rev>/src/ forge-std/=dependencies/forge-std-<version>/src

各条映射的含义：

• forge-fhevm/→dependencies/forge-fhevm-<rev>/src/：核心映射，使import {FhevmTest} from "forge-fhevm/FhevmTest.sol"可被正确解析；
• @fhevm/solidity/→dependencies/@fhevm-solidity-<version>/：解析@fhevm/solidity/lib/FHE.sol等合约库导入；
• encrypted-types/→dependencies/@encrypted-types-<version>/：解析EncryptedTypes.sol等加密类型导入；
• @fhevm/host-contracts/→dependencies/forge-fhevm-<rev>/src/fhevm-host/：暴露 FHEVM host 合约（ACL、FHEVMExecutor等）供测试基类引用；
• forge-std/→dependencies/forge-std-<version>/src：Foundry 标准库映射。

请把<version>/<rev>占位符替换为 Soldeer 实际写入dependencies/的目录名（查看该目录即可获得准确版本），也可以直接复制模板仓库的remappings.txt，在后续升级依赖时再按需调整。

验证安装：最小测试用例

环境是否真正可用，最快的方式是编写一个极简测试，验证FhevmTest基类能否在setUp()阶段把 FHEVM host 合约部署到测试 EVM 中。创建test/Setup.t.sol：

// test/Setup.t.sol // SPDX-License-Identifier: MIT pragma solidity ^0.8.27; import {FhevmTest} from "forge-fhevm/FhevmTest.sol"; contract SetupTest is FhevmTest { function test_setupDeploys() public view { // setUp() 会在确定性的地址上部署全部 FHEVM host 合约 assertTrue(address(_executor) != address(0)); assertTrue(address(_acl) != address(0)); } }

然后单独运行该测试：

forge test --match-test test_setupDeploys -vv

若测试通过，说明：

1. Soldeer 依赖安装无误，forge-fhevm/FhevmTest.sol导入解析成功；
2. FhevmTest.setUp()已按预期部署了FHEVMExecutor（_executor）与ACL（_acl）等 host 合约；
3. 当前 Solidity 编译器版本与evm_version = "cancun"组合可以正常编译运行。

底层原理：setUp() 究竟做了什么

理解了"验证用例为什么能通过"，才算真正吃透这套环境。FhevmTest继承自 Foundry 的Test，其setUp()的核心工作是把生产环境中的 FHEVM host 合约栈原样重建到测试 EVM 里。这一点在本仓库的host-contracts/fhevm-foundry/HostContractsDeployerTestUtils.sol中有完整的源码级实现，可作为理解forge-fhevm内部机制的参照：

• 确定性地址部署：host 合约（ACL、FHEVMExecutor、KMSVerifier、InputVerifier、HCULimit、PauserSet、ProtocolConfig、KMSGeneration）通过deployCodeTo写入固定的规范地址。这些地址由FHEVMHostAddresses.sol定义，例如仓库内sdk/js-sdk/contracts/src/v0.13.0/host-contracts/addresses/FHEVMHostAddresses.sol中记录了一批固定的规范地址常量（aclAdd、fhevmExecutorAdd、inputVerifierAdd、kmsVerifierAdd、hcuLimitAdd、protocolConfigAdd、kmsGenerationAdd、pauserSetAdd）。
• 模拟生产部署方式：_deployACL、_deployFHEVMExecutor等辅助函数按照生产环境的真实部署方式，先向规范地址写入空代理（Empty UUPS Proxy）的运行时代码，再以 owner 身份调用upgradeToAndCall完成实现合约的升级与初始化，最后通过vm.label为代理与实现打上标签便于调试。
• 交叉合约权限真实生效：由于 host 合约栈被完整重建，跨合约的权限校验（如ACLOwnable、槽位读取、Pauser 集合等）在测试中的行为与链上完全一致，而不是逐个 mock。
• 模拟签名者：测试环境与主网唯一的偏差在于输入签名者与 KMS 签名者使用了固定的 mock 私钥（MOCK_INPUT_SIGNER/MOCK_KMS_SIGNER），这使得测试中的 EIP-712 证明可以确定性生成。详细辅助函数清单见docs/solidity-guides/foundry/api.md。

因此，test_setupDeploys中_executor与_acl非空，正是"host 合约栈已按规范地址完成部署"的直接证据。需要提醒的是：被测合约自身必须继承 Zama 配置（例如ZamaEthereumConfig），这样合约内的FHE.*调用才会路由到setUp()部署的这些 host 合约上。

常见配置问题排查

• 编译报 "Source not found"：通常是remappings.txt缺失或映射路径与dependencies/实际目录名不一致，请核对版本占位符；
• evm_version相关报错：确认foundry.toml中evm_version = "cancun"未被覆盖，且 Solc 版本足够新以支持 Cancun 特性；
• forge soldeer install后 import 仍失败：检查libs是否包含"dependencies"，并确认[soldeer]段未被遗漏；
• 版本对齐：本仓库各工程当前锁定solc 0.8.24与forge-std 1.11.0（参见host-contracts/foundry.toml、library-solidity/foundry.toml），可优先以此为基准挑选版本。

后续进阶路径

• 环境就绪后，可参考 编写 FHEVM Foundry 测试，学习FhevmTest的加密辅助函数（encryptUint64等）与三种解密模式（decrypt/publicDecrypt/userDecrypt）；
• 部署环节请阅读 使用 Foundry 部署 FHEVM 合约，覆盖本地 Anvil 节点与 Sepolia 测试网两种部署流程；
• 完整的FhevmTest辅助函数速查表见 forge-fhevm API 参考；
• 各网络（主网 / Sepolia）FHEVM host 合约的规范地址清单见 合约地址；
• 对 Foundry 工作流的整体介绍可回看 Foundry 章节导读。

【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm