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-fhevmFoundry 原生的 FHEVM 测试库提供FhevmTest基类与加密/解密辅助函数fhevm/solidityFHEVM Solidity 合约库含FHE.sol等核心模块encrypted-types加密类型定义euint8、euint64、ebool等OpenZeppelin contracts标准库依赖代理、工具库等forge-stdFoundry 标准测试库第三步编译并运行测试forge build forge test -vvvforge 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.tomlforge-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 cancunforge-fhevm依赖 Cancun EVM 引入的字节码特性如TSTORE瞬态存储是 host 合约正常工作的硬性要求不要随意降低[dependencies]声明依赖清单其中forge-fhevm是 git 依赖需要指定rev锁定提交[soldeer] remappings_version falseSoldeer 生成 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 installSoldeer 会将[dependencies]中声明的包逐一物化到dependencies/目录下。3. 添加 remappingsSoldeer 将每个依赖物化到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/srcFoundry 标准库映射。请把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若测试通过说明Soldeer 依赖安装无误forge-fhevm/FhevmTest.sol导入解析成功FhevmTest.setUp()已按预期部署了FHEVMExecutor_executor与ACL_acl等 host 合约当前 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 参考各网络主网 / SepoliaFHEVM host 合约的规范地址清单见 合约地址对 Foundry 工作流的整体介绍可回看 Foundry 章节导读。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考