FHEVM Gateway 部署环境变量完全指南：从 `.env.example` 到链上配置的实战解析-北京尧图网络

FHEVM Gateway 部署环境变量完全指南从.env.example到链上配置的实战解析【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本指南以gateway-contracts/docs/getting-started/deployment/env_variables.md为骨架系统讲解 FHEVM Gateway网关链部署时全部环境变量的含义、类型、默认值与约束并结合.env.example、GatewayConfig 合约与部署脚本等仓库源码说明每个变量如何被解析、写入链上并被合约校验。读完本文你将能够独立编写一份可在本地或测试网运行的完整.env文件理解部署期写入链上与部署后单独设置两类变量的区别并掌握阈值threshold与节点node数量约束的底层校验逻辑。完整的环境变量示例见仓库根目录下的.env.example文件本文所有示例值均取自该文件用于本地测试。环境变量总体划分FHEVM Gateway 部署所用的环境变量可以划分为三大类GatewayConfig 值GatewayConfigvalues协议元数据、KMS 阈值、协处理器阈值、KMS 节点、协处理器、宿主机链、暂停者等。绝大多数会在部署时被写入GatewayConfig合约ProtocolPayment 值ProtocolPaymentvalues输入验证、公开解密、用户解密三种操作的初始定价部署设置Deployment settings仅用于 Hardhat 部署流程本身包括私钥、网络名、链 ID、助记词、RPC URL以及生产环境部署后动态填入的合约地址等。需要注意除部署设置外其余变量的值会被存储进已部署的合约中且并非总是允许在部署后更新。因此部署前必须严格确认每一个值的正确性。下面给出的示例值大多来自.env.example用于本地测试每个变量的预期类型必须被遵守类型以注释形式标注否则部署预期会失败。此外.env.example中的账户是已经注资的 Hardhat 测试账户可通过以下命令生成make get-accounts该命令在 Makefile 中定义为DOTENV_CONFIG_PATH$(ENV_PATH) npx hardhat get-accounts即读取指定.env路径后执行 Hardhat 的get-accounts任务来输出派生账户及其私钥。环境变量速查总表下表完整列出 FHEVM Gateway 部署使用的全部环境变量。Solidity 类型定义参见 Solidity 官方类型文档。环境变量描述Solidity 类型默认值备注PROTOCOL_NAME展示用协议名称string--PROTOCOL_WEBSITE展示用协议网站string--MPC_THRESHOLDMPC 阈值密码学参数uint256-必须严格小于已注册 KMS 节点数PUBLIC_DECRYPTION_THRESHOLD公开解密阈值uint256-必须非零且小于等于已注册 KMS 节点数USER_DECRYPTION_THRESHOLD用户解密阈值uint256-必须非零且小于等于已注册 KMS 节点数KMS_GENERATION_THRESHOLDKMS 公钥材料生成阈值uint256-必须非零且小于等于已注册 KMS 节点数COPROCESSOR_THRESHOLD协处理器阈值uint256-必须非零且小于等于已注册协处理器数NUM_KMS_NODES要注册的 KMS 节点数--必须至少等于下方实际注册的 KMS 节点数KMS_TX_SENDER_ADDRESS_{i}KMS 节点i的交易发送地址address-若iNUM_KMS_NODES则忽略KMS_SIGNER_ADDRESS_{i}KMS 节点i的签名者地址address-若iNUM_KMS_NODES则忽略KMS_NODE_IP_ADDRESS_{i}KMS 节点i的 IP 地址string-若iNUM_KMS_NODES则忽略NUM_COPROCESSORS要注册的协处理器数--必须至少等于下方实际注册的协处理器数COPROCESSOR_TX_SENDER_ADDRESS_{j}协处理器j的交易发送地址address-若jNUM_COPROCESSORS则忽略COPROCESSOR_SIGNER_ADDRESS_{j}协处理器j的签名者地址address-若jNUM_COPROCESSORS则忽略COPROCESSOR_S3_BUCKET_URL_{j}协处理器j的 S3 桶 URLstring-若jNUM_COPROCESSORS则忽略NUM_HOST_CHAINS要注册的宿主机链数--必须至少等于下方实际注册的宿主机链数HOST_CHAIN_CHAIN_ID_{k}宿主机链k的链 IDuint256-若kNUM_HOST_CHAINS则忽略HOST_CHAIN_FHEVM_EXECUTOR_{k}宿主机链k的 FHEVM 执行器address-若kNUM_HOST_CHAINS则忽略HOST_CHAIN_ACL_ADDRESS_{k}宿主机链k的 ACL 地址address-若kNUM_HOST_CHAINS则忽略HOST_CHAIN_NAME_{k}宿主机链k的名称string-若kNUM_HOST_CHAINS则忽略HOST_CHAIN_WEBSITE_{k}宿主机链k的网站string-若kNUM_HOST_CHAINS则忽略NUM_PAUSERS要注册的暂停者数--必须至少等于下方实际注册的暂停者数PAUSER_ADDRESS_{l}暂停者l的地址address-若lNUM_PAUSERS则忽略INPUT_VERIFICATION_PRICE输入验证价格uint256-价格以 $ZAMA 基础单位计18 位小数PUBLIC_DECRYPTION_PRICE公开解密价格uint256-价格以 $ZAMA 基础单位计18 位小数USER_DECRYPTION_PRICE用户解密价格uint256-价格以 $ZAMA 基础单位计18 位小数ZAMA_OFT_ADDRESSZamaOFT 合约地址address-真实环境要求该合约已预先部署FEES_SENDER_TO_BURNER_ADDRESSFeesSenderToBurner 合约地址address-真实环境要求该合约已预先部署DEPLOYER_PRIVATE_KEY合约部署私钥bytes32--HARDHAT_NETWORK合约部署目标网络stringhardhat可选值hardhat、localGateway、staging、zwsDev、testnetCHAIN_ID_GATEWAY网关链的链 IDuint25631337应与HARDHAT_NETWORK取值一致MNEMONIC地址生成助记词stringadapt mosquito move limb mobile illegal tree voyage juice mosquito burger raise father hope layer-RPC_URLRPC 节点 URLstringhttp://127.0.0.1:8757-GATEWAY_CONFIG_ADDRESSGatewayConfig 合约地址address-仅生产环境设置使用PAUSER_SET_ADDRESSPauserSet 合约地址address-仅生产环境设置使用NEW_OWNER_PRIVATE_KEY新 owner 接受所有权用私钥bytes32-仅用于将网关所有权转移给新 EOA owner 的任务详细解析GatewayConfig 值这部分变量对 FHEVM Gateway 协议至关重要大多数在部署时被写入GatewayConfig合约。关于每个值在协议中的具体用途可参考 GatewayConfig 合约文档。部署时写入的值以下值在部署时写入合约是一次写入、事后难改的核心配置。协议元数据PROTOCOL_NAMEProtocol # (string) PROTOCOL_WEBSITEhttps://protocol.com # (string)这两个值构成了 GatewayConfig.sol 存储结构中的ProtocolMetadata protocolMetadata。在部署任务 contracts.ts 中它们通过getRequiredEnvVar(PROTOCOL_NAME)与getRequiredEnvVar(PROTOCOL_WEBSITE)读取——注意这里使用getRequiredEnvVar意味着只要缺失或为空部署立即报错终止校验逻辑见 loadVariables.ts。KMS 阈值MPC_THRESHOLD1 # (uint256)MPC_THRESHOLD必须小于或等于下方注册的 KMS 节点数量。PUBLIC_DECRYPTION_THRESHOLD3 # (uint256) USER_DECRYPTION_THRESHOLD3 # (uint256)PUBLIC_DECRYPTION_THRESHOLD和USER_DECRYPTION_THRESHOLD必须非零且小于或等于下方注册的 KMS 节点数量。在实际 FHEVM 协议中这两个阈值通常按以下公式计算设t为 MPC 阈值公开解密阈值t 1用户解密阈值2*t 1这些公式在当前版本中适用未来可能调整。KMS_GENERATION_THRESHOLD3 # (uint256)KMS_GENERATION_THRESHOLD必须非零且小于或等于下方注册的 KMS 节点数量。底层校验逻辑以上四个阈值最终都会经由 contracts.ts 组装成Thresholds结构体传入GatewayConfig.initializeFromEmptyProxy。合约内部调用_setMpcThreshold、_setPublicDecryptionThreshold、_setUserDecryptionThreshold、_setKmsGenThreshold分别完成校验与存储见 GatewayConfig.solMPC 阈值要求t n严格小于 KMS 节点数否则触发InvalidHighMpcThreshold公开/用户解密阈值要求1 t n否则触发InvalidNullPublicDecryptionThreshold/InvalidHighPublicDecryptionThreshold用户解密同理KMS 生成阈值要求1 t n否则触发InvalidNullKmsGenThreshold/InvalidHighKmsGenThreshold所有阈值还受MAX_KMS_SIGNERStype(uint8).max即 255上限约束超出会触发ThresholdExceedsProofFormatLimit——该上限与宿主机KMSVerifier.verifyDecryptionEIP712KMSSignatures中单字节签名计数的证明格式保持一致见 GatewayConfig.sol。值得注意的是阈值校验发生在 KMS 节点注册之后_setKmsContext内部先注册节点再设置阈值见 GatewayConfig.sol因此校验函数可以引用实际注册的节点数量作为比较基准。协处理器阈值COPROCESSOR_THRESHOLD2 # (uint256)COPROCESSOR_THRESHOLD必须非零且小于或等于下方注册的协处理器数量。合约端在_setCoprocessorThreshold中校验1 t nn 为已注册协处理器数违反则触发InvalidNullCoprocessorThreshold或InvalidHighCoprocessorThreshold见 GatewayConfig.sol。KMS 节点NUM_KMS_NODES1 # (number)NUM_KMS_NODES是在GatewayConfig合约中注册的 KMS 节点数量。它不会存储在合约中仅被部署脚本使用。下方每个 KMS 节点的元数据变量按从 0 开始的节点编号索引。若设置的变量不足部署将失败若变量过多部署会成功但多余变量被忽略。KMS_TX_SENDER_ADDRESS_00xc1d91b49A1B3D1324E93F86778C44a03f1063f1b # (address) KMS_SIGNER_ADDRESS_00x305F1F471e9baCFF2b3549F9601f9A4BEafc94e1 # (address) KMS_NODE_IP_ADDRESS_0127.0.0.1 # (string) KMS_NODE_STORAGE_URL_0s3://kms-bucket-1 # (string)源码级消费方式部署脚本以NUM_KMS_NODES为上限循环读取KMS_TX_SENDER_ADDRESS_{idx}、KMS_SIGNER_ADDRESS_{idx}、KMS_NODE_IP_ADDRESS_{idx}、KMS_NODE_STORAGE_URL_{idx}见 contracts.ts任一缺失都会因getRequiredEnvVar抛错。这些元数据组装为KmsNode[]传入初始化函数合约在_setKmsContext中注册节点并检查同一上下文内的交易发送者与签名者重复违反则分别触发KmsTxSenderAlreadyRegistered、KmsSignerAlreadyRegistered同时要求节点列表非空EmptyKmsNodes且数量不超过MAX_KMS_SIGNERS见 GatewayConfig.sol。合约还要求初始 KMS 上下文 ID 非零否则触发InvalidNullKmsContextId。注意当前仓库版本还引入了KMS_CONTEXT_ID变量见.env.example用作部署时的初始上下文 ID同时也是 KMS 上下文切换tasks/kmsContext.ts时的新上下文 IDKMS_*节点与阈值变量在切换场景下需指向切换后的委员会。KMS 节点、阈值等状态在合约内均按上下文context维度存储mpcThresholdForContext、kmsNodesForContext等 mapping见 GatewayConfig.sol并支持通过updateKmsContext、destroyKmsContext等 owner 操作进行后续轮换。协处理器NUM_COPROCESSORS3 # (number)NUM_COPROCESSORS是要在GatewayConfig合约中注册的协处理器数量。它不存储在合约中仅被部署脚本使用。下方每个协处理器的元数据变量按从 0 开始的编号索引。变量不足则部署失败变量过多则忽略多余部分。COPROCESSOR_TX_SENDER_ADDRESS_00x6518D50aDc9036Df37119eA465a8159E34417E2E # (address) COPROCESSOR_SIGNER_ADDRESS_00xa5eE8292dA52d8234248709F3E217ffEBA5E8312 # (address) COPROCESSOR_S3_BUCKET_URL_0s3://coprocessor-bucket-1 # (string)部署脚本以NUM_COPROCESSORS为上限循环读取上述三个变量见 contracts.ts组装为Coprocessor[]。合约端_setCoprocessors同样检查空列表EmptyCoprocessors与重复地址CoprocessorTxSenderAlreadyRegistered/CoprocessorSignerAlreadyRegistered见 GatewayConfig.sol。协处理器的注册信息用于网关侧共识COPROCESSOR_THRESHOLD定义了达成协处理器多数共识所需的签名数量。部署后写入的值以下值在部署之后通过单独脚本设置但同样是 FHEVM Gateway 协议完整运行所必需的。宿主机链NUM_HOST_CHAINS1 # (number)NUM_HOST_CHAINS是要在GatewayConfig合约中注册的宿主机链数量。它不存储在合约中仅被部署脚本使用。下方每个宿主机链的元数据变量按从 0 开始的编号索引。变量不足则脚本失败变量过多则忽略多余部分。HOST_CHAIN_CHAIN_ID_02025 # (uint256) HOST_CHAIN_FHEVM_EXECUTOR_00xbb8ab3d75fd306ce85c90e899a2db850490cd697 # (address) HOST_CHAIN_ACL_ADDRESS_00xabcdef1234567890abcdef1234567890abcdef12 # (address) HOST_CHAIN_NAME_0Host chain 2025 # (string) HOST_CHAIN_WEBSITE_0https://host-chain-2025.com # (string)约束所有宿主机链的HOST_CHAIN_CHAIN_ID必须互不相同否则脚本会失败。合约端校验GatewayConfig.addHostChain要求链 ID 非零InvalidNullChainId、不超过type(uint64).maxChainIdNotUint64、且未被注册HostChainAlreadyRegistered见 GatewayConfig.sol。宿主机链注册由 addHostChains.ts 任务单独执行。从当前.env.example可见实际示例中注册了 4 条宿主机链chain ID 2025~2028且均使用同一个 ACL 占位地址。暂停者NUM_PAUSERS1 # (number)NUM_PAUSERS是要在GatewayConfig合约中注册的暂停者数量。它不存储在合约中仅被部署脚本使用。下方每个暂停者按从 0 开始的编号索引。变量不足则脚本失败变量过多则忽略多余部分。暂停者数量应与协议中注册的运营者总数一致即注册的 KMS 节点数与协处理器数之和PAUSER_ADDRESS_00x6591319B97979Acc59b7191A8B4Ec381375bFc92 # (address)暂停者被记录在独立的PauserSet合约中由 pauserSet.ts 部署GatewayConfig通过PAUSER_SET.isPauser(account)判断调用者是否为暂停者见 GatewayConfig.sol并据此授权pauseAllGatewayContracts等暂停操作。暂停者管理另有 addPausers.ts、pauseContracts.ts 等任务。在.env.example中还额外提供了PAUSER_PRIVATE_KEY用于本地测试与暂停任务的私钥签名它必须对应某个暂停者的私钥。详细解析ProtocolPayment 值部署ProtocolPayment合约时需要定义每种操作的初始价格INPUT_VERIFICATION_PRICE10000000000000000000 # (uint256, 10 $ZAMA) PUBLIC_DECRYPTION_PRICE1000000000000000000 # (uint256, 1 $ZAMA) USER_DECRYPTION_PRICE1000000000000000000 # (uint256, 1 $ZAMA)价格以$ZAMA计使用 18 位小数。它们之后可以由 owner 更新。在部署任务 contracts.ts 中三个价格变量被读取并作为initializeFromEmptyProxy的初始化参数传入ProtocolPayment合约。详细解析部署设置以下设置用于通过 Hardhat 部署合约。支付桥接合约地址ZAMA_OFT_ADDRESS0xc1D733116990ce3D9e54F9eCf48a1cdD441Af4f9 FEES_SENDER_TO_BURNER_ADDRESS0xa50F5243C70c80a8309e3D39d8c9d958cDa83979在真实环境中部署常规网关合约之前需要先在以下链上部署好若干配套合约宿主机链ZamaERC20$ZAMA代币FeesBurner用于销毁操作手续费网关链ZamaOFTLayerZero OFT 合约用于与ZamaERC20交互FeesSenderToBurner带 LayerZero 端点的合约用于将费用发送至FeesBurner这些地址通过setPaymentBridgingContractAddresses()在task:deploySetupContracts中注册见 contracts.ts。在模拟测试环境中ZamaOFT地址对应部署者模拟合约的地址而FeesSenderToBurner可为任意非零地址无需部署模拟合约详见.env.example中的注释与 paymentBridging 目录下的实现。部署者私钥DEPLOYER_PRIVATE_KEY0x7136d8dc72f873124f4eded25f3525a20f6cee4296564c76b44f1d582c57640f # (bytes32)这是部署者账户的私钥用于部署合约。部署脚本通过new Wallet(deployerPrivateKey).connect(ethers.provider)构造部署者钱包见 contracts.ts。在.env.example中该私钥对应accounts[1]。Hardhat 网络HARDHAT_NETWORKhardhat # (string)这是合约预期部署的网络。可选值为hardhat、localGateway、staging、devnet、testnet文档原文中写作zwsDev而 hardhat.config.ts 与.env.example实际使用的网络名为devnet二者指向同一套部署目标。各网络在 hardhat.config.ts 中分别配置了accounts基于助记词、chainId与url读取RPC_URL。链 IDCHAIN_ID_GATEWAY31337 # (uint256)这是合约预期部署网络的链 ID应与HARDHAT_NETWORK取值一致对应关系如下hardhat31337localGateway123456staging54321devnet10900testnet10901这些默认链 ID 定义在 hardhat.config.ts 的chainIds常量中。配置中的chainId优先取CHAIN_ID_GATEWAY环境变量未设置时才回退到上述默认值。助记词MNEMONICadapt mosquito move limb mobile illegal tree voyage juice mosquito burger raise father hope layer # (string)用于生成部署者地址与公钥的助记词对应 Hardhat 网络配置中的accounts: { mnemonic }。RPC URLRPC_URLhttp://127.0.0.1:8757 # (string)FHEVM 网关网络的 RPC 节点 URL被各非hardhat网络配置中的url字段引用见 hardhat.config.ts。生产环境部署后的附加设置在生产环境中部署合约后还需要以下额外设置。GatewayConfig 地址GATEWAY_CONFIG_ADDRESS0xC7D45661a345eC5cA0e8521CFEF7e32FDA0Daa68 # (address)该静态地址用于单独向GatewayConfig合约添加宿主机链。在生产环境中该环境变量需要在部署合约后动态设置。在.env.example中注明对于测试场景这些地址直接从addresses/.env.gateway文件读取因此下方取值会被忽略。PauserSet 地址PAUSER_SET_ADDRESS0xc1D733116990ce3D9e54F9eCf48a1cdD441Af4f9 # (address)该静态地址用于单独管理PauserSet合约中的暂停者。同样在生产环境中需要在部署合约后动态设置。新 owner 私钥NEW_OWNER_PRIVATE_KEY0x7136d8dc72f873124f4eded25f3525a20f6cee4296564c76b44f1d582c57640f # (bytes32)目标新 owner EOA 的私钥用于接受网关合约的所有权当所有权未直接转移给多签账户时。在.env.example中对应accounts[2]与部署者私钥accounts[1]不同。所有权转移相关任务见 ownership.ts。从环境变量到链上状态一次部署的完整数据流将上述内容串联起来一次完整的网关合约部署task:deployAllGatewayContracts见 contracts.ts中的数据流如下读取.env所有环境变量通过 loadVariables.ts 中的getRequiredEnvVar按需读取缺失或为空立即报错部署设置合约task:deploySetupContracts部署 UUPS 空代理、PauserSet注册支付桥接地址测试模式下可选部署 mockedZamaOFT部署实现合约task:deployImplementationContracts按顺序执行task:deployGatewayConfig→task:deployInputVerification→task:deployCiphertextCommits→task:deployDecryption→task:deployProtocolPayment写入链上GatewayConfig.initializeFromEmptyProxy将协议元数据、阈值、KMS 节点、协处理器、托管人custodians一次性写入并按上文所述约束逐项校验ProtocolPayment写入三项操作初始价格部署后补充通过 addHostChains.ts、addPausers.ts 等任务分别注册宿主机链与暂停者生产环境还需回填GATEWAY_CONFIG_ADDRESS、PAUSER_SET_ADDRESS。需要注意的是从当前.env.example可以看出部署脚本还会读取文档未展开的NUM_CUSTODIANS与CUSTODIAN_*交易发送者地址、签名者地址、加密公钥变量组装为Custodian[]传入GatewayConfig.initializeFromEmptyProxy见 contracts.ts托管人在合约内同样有重复地址与空列表校验GatewayConfig.sol。这是文档之后版本迭代中新增的配置维度编写.env时可参照示例文件一并补齐。小结与最佳实践区分两类配置GatewayConfig值与ProtocolPayment值一旦写入链上后续更新能力受限阈值可通过 owner 调用update*系列函数调整但需遵循 KMS_CONTEXT_SWITCH_RUNBOOK.md 等运维手册避免与在途解密请求竞态部署设置只作用于部署过程本身可自由调整。尊重数量与阈值的硬约束MPC_THRESHOLD必须严格小于 KMS 节点数PUBLIC_DECRYPTION_THRESHOLD、USER_DECRYPTION_THRESHOLD、KMS_GENERATION_THRESHOLD、COPROCESSOR_THRESHOLD必须非零且不超过对应节点数。违反这些约束会导致部署回滚。索引变量必须连续KMS_*、COPROCESSOR_*、HOST_CHAIN_*、PAUSER_*系列按 0 起编号连续填充缺失任意一项都会使部署失败多余项虽被忽略但建议保持整洁。生产与测试的环境差异真实环境要求ZamaOFT、FeesSenderToBurner等桥接合约已预先部署且部署后需动态回填GATEWAY_CONFIG_ADDRESS、PAUSER_SET_ADDRESS测试环境则使用 mock 合约与addresses/.env.gateway文件中的地址。以示例文件为起点直接复制.env.example并修改为本地/目标网络所需的值是搭建 FHEVM Gateway 部署环境最稳妥的路径文档中make get-accounts生成的 Hardhat 测试账户含注资与示例中的账户索引一一对应便于快速核对地址归属。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

FHEVM Gateway 部署环境变量完全指南：从 `.env.example` 到链上配置的实战解析

相关推荐

Web端流媒体JS播放器开源库

Repomix 使用指南：将仓库打包为 AI 友好的单一文件（CLI、配置与输出格式全解析）

Python手势识别实战：MediaPipe关键点检测与数字识别全流程

更多资讯

团子翻译器：免费的开源屏幕翻译工具

LDPC MinSum译码算法仿真：从校验矩阵到误码率验证的完整链路

Label Studio 配置 Redis 数据库作为标注任务源存储与目标存储（Source/Target Storage）实战指南

vue-vben-admin容器化部署实战指南

Lithe-IDEA：轻量开源版Spring Boot专用IDE

PLC与组态王在混凝土搅拌站自动化配料系统中的应用

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？