FHEVM Gateway 智能合约套件完全指南：多链密文解密、KMS 编排与协议配置实战

FHEVM Gateway 智能合约套件完全指南：多链密文解密、KMS 编排与协议配置实战

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

本文以 fhevm 仓库中的 gateway-contracts/README.md 及其配套文档（gateway-contracts/docs/SUMMARY.md）为主体，系统讲解 FHEVM Gateway 这一组部署在网关链上的智能合约：它如何验证解密请求的合法性、集中管理来自多条 host chain 的密文与密文承诺、编排 KMS 密钥材料与协议支付，并给出基于 Hardhat 与 Docker 的完整部署、环境变量配置和应急暂停操作指南。读完本文，你将掌握 Gateway 六大合约的职责边界与内部原理，能够独立完成本地/容器化部署，并能正确配置阈值、操作者与 host chain 参数。

FHEVM Gateway 在协议中的定位

FHEVM（Fully Homomorphic Encryption Virtual Machine）是一个将全同态加密与区块链应用整合的全栈框架：用户在其他链（host chain）上提交加密密文，由 coprocessor 在密文上执行同态计算，最终由 KMS 完成解密。FHEVM Gateway 正是介于 host chain、KMS 与 coprocessor 之间的中间层合约集合，部署在专门的网关链上。

从 gateway-contracts/README.md 的定义看，这些合约共同承担五类职责：

• 验证解密请求的合法性（legitimacy of decryption requests）
• 集中管理多链密文访问（centralizing multi-chain ciphertexts access）
• 集中管理多链密文承诺（centralizing multi-chain ciphertexts commitments）
• 编排 KMS 材料（orchestrating KMS materials）
• 编排协议支付（orchestrating protocol payments）

从源码结构看，这一设计体现在合约的继承关系上：例如 Decryption.sol 同时继承EIP712Upgradeable（用于响应签名校验）、UUPSUpgradeableEmptyProxy（可升级）、GatewayOwnable（网关所有权）、GatewayConfigChecks（从 GatewayConfig 读取配置并做权限检查）、ProtocolPaymentUtils（费用收取）与Pausable（暂停能力）；GatewayConfig.sol 则基于 OpenZeppelin 的Ownable2StepUpgradeable与UUPSUpgradeableEmptyProxy。这种模块化继承正是「Gateway 统一持有配置、各业务合约通过GatewayConfigChecks动态读取」的实现基础。

智能合约总览

其中PauserSet与其他合约不同：从源码看它部署为不可升级的不可变合约（PauserSet.sol，继承IPauserSet, GatewayOwnable），其地址被存储在GatewayConfig合约中；而其余业务合约均基于UUPSUpgradeableEmptyProxy实现 UUPS 可升级代理模式。每个合约都通过getVersion()、initializeFromEmptyProxy()等函数支持空代理初始化与版本升级，完整的函数选择器清单见 gateway-contracts/selectors.txt。

仓库在 gateway-contracts/test/ 下为每个合约都提供了独立的测试文件（CiphertextCommits.ts、Decryption.ts、GatewayConfig.ts、InputVerification.ts、KMSGeneration.ts、PauserSet.ts、ProtocolPayment.ts），是理解各合约行为边界的直接参考。

GatewayConfig：协议配置中心

GatewayConfig是 FHEVM Gateway 的配置中枢（详见 gateway-config 文档）。除 host chain 之外，绝大多数配置项都在合约部署时一次性写入，之后只有部分配置可由 owner 更新。

配置可分为四类：协议元数据（Protocol metadata）、操作者（Operators）、治理（Governance）与Host chains。

协议元数据

包含两项展示用信息：

• name：协议名称
• website：协议官网

它们只在部署时设置，之后无法更新。

操作者：KMS 节点与 Coprocessor

操作者分为 KMS 节点与 coprocessor 两类，每个操作者都必须先在GatewayConfig中注册才能参与 fhevm 协议。

KMS 节点

KMS（Key Management Service）本质上是一组节点共同运行的多方计算（MPC）协议，用于去中心化地管理 FHE 密钥。KMS 节点的职责是：

• 根据Decryption合约的请求解密密文
• 根据KMSGeneration合约的请求生成 KMS 公共材料

每个 KMS 节点存储以下元数据：

• txSenderAddress：向 Gateway 发送交易的账户地址，协议中通常称为KMS connector
• signerAddress：用于签署发往 Gateway 结果的公钥对应地址
• ipAddress：KMS 节点的 IP 地址
• storageUrl：KMS 公共材料存储 URL，coprocessor 通过它下载 FHE 计算所需的公共材料

FHEVM Gateway 只有一个 KMS 集合，至少包含 1 个节点。当前节点在部署时设置，部署后不能增删 KMS 节点。

KMS 阈值

MPC 阈值（mpcThreshold）：KMS 节点执行 MPC 协议所需的密码学参数，可通过getMpcThreshold视图函数读取。要求严格小于注册的 KMS 节点数量。部署时设置，之后 owner 可在满足条件的前提下更新。

解密阈值（decryption thresholds）：决定Decryption合约中「达成解密共识所需的最少 KMS 有效响应数」：

• publicDecryptionThreshold：公开解密达成共识所需的最少有效响应数
• userDecryptionThreshold：用户解密达成共识所需的最少有效响应数

两者都必须非零且不大于注册的 KMS 节点数量。部署时设置，owner 可后续更新。

KMS 生成阈值（kmsGenThreshold）：决定 KMS 公共材料（FHE 密钥、CRS）生成达成共识所需的最少有效响应数，约束条件同上（非零且不大于 KMS 节点数）。

关于解密阈值的取值，部署文档（env_variables.md）给出了协议中的实践经验公式（设t为 MPC 阈值）：

• 公开解密阈值：t + 1
• 用户解密阈值：2*t + 1

Coprocessor

Coprocessor 是一个多节点集合，职责是：

• 在密文上执行 FHE 同态计算
• 根据InputVerification合约的请求验证输入的 ZKPoK
• 为所有已注册 host chain 处理密文的访问控制

每个 coprocessor 存储的元数据：

• txSenderAddress：发送交易的账户地址
• signerAddress：签名结果对应的地址
• s3BucketUrl：密文存储的 S3 bucket URL，KMS connector 通过它下载解密所需密文

FHEVM Gateway 只有一个 coprocessor 集合，至少包含 1 个 coprocessor，同样在部署时设定、部署后不可增删。

Coprocessor 阈值（coprocessorThreshold）：Gateway 达成 coprocessor 共识（例如CiphertextCommits的密文承诺或InputVerification的输入验证）所需的最少 coprocessor 同意数，要求非零且不大于注册 coprocessor 数量。

关于 drift auto-reversal 的告警（需特别留意）：coprocessor 可以选择在自身状态偏离 Gateway 共识时自动回滚。由于这以共识为唯一事实来源，只有当「少数故障方无法独立达成共识」时才安全——即至少注册 3 个 coprocessor 且coprocessorThreshold设为严格多数。切勿在 coprocessor 数量 ≤2 或非多数阈值下开启 drift auto-reversal。合约只强制约束1 ≤ threshold ≤ coprocessor 数量，因此保证合理的 quorum 是 DAO 与操作者的责任，合约本身并不替你做这个判断。

Sender 与 Signer

尽管上述两类操作者元数据不同，但每个操作者都同时拥有一个交易发送者与一个签名者：

• txSenderAddress：向 FHEVM Gateway 发送交易的账户地址
• signerAddress：用于签署发往 Gateway 结果的公钥对应地址

可通过以下视图函数查询：

• getKmsTxSenders()：获取所有 KMS 节点的交易发送者
• getKmsSigners()：获取所有 KMS 节点的签名者
• getCoprocessorTxSenders()：获取所有 coprocessor 的交易发送者
• getCoprocessorSigners()：获取所有 coprocessor 的签名者

同一操作者的交易发送者与签名者允许相同。此外，交易发送者地址被用作操作者的身份标识（identity），可作为以下视图函数的入参：

• getKmsNode(address kmsTxSenderAddress)：查询某个 KMS 节点的元数据
• getCoprocessor(address coprocessorTxSenderAddress)：查询某个 coprocessor 的元数据

治理角色

协议由以下角色治理：

• owner：可执行受限操作的账户
• pausers：可暂停合约函数的账户

Owner：最初为合约部署者，可执行：升级合约、更新 pausers、添加 host chain、触发 KMS 公共材料生成。Owner 由 OpenZeppelin 的Ownable2StepUpgradeable管理，意味着部署者可通过两步流程将所有权转移给其他账户（先transferOwnership提名，再由新 owneracceptOwnership接受）。

Pausers：详见 PauserSet 文档 与 暂停机制文档。

Host chains

Host chain 是注册到协议中的宿主链，只有在已注册 host chain 上生成的密文才允许被 coprocessor 验证、被 KMS 解密。每个 host chain 存储：

• chainId：host chain 的唯一标识。与常见链 ID 不同，其值被限制在64 位（uint64）内，源码中对应错误ChainIdNotUint64（见 selectors.txt）
• fhevmExecutorAddress：部署在 host chain 上的FHEVMExecutor合约地址
• aclAddress：部署在 host chain 上的ACL合约地址
• name：host chain 名称
• website：host chain 官网

Host chain不在部署时设置，而是由 owner 通过addHostChain函数（源码位于 GatewayConfig.sol#L454）逐个添加；当前不支持移除。不过在仓库的部署任务中，还提供了disableHostChain/enableHostChain/removeHostChain等生命周期管理能力（见下文「管理 host chain」）。

KMSGeneration：编排 FHE 密钥与 CRS

KMSGeneration合约（详见 kms_generation 文档）负责编排协议所需的公共 KMS 材料。所有非视图函数均仅限合约 owner 或 KMS 节点的交易发送者调用，源码见 KMSGeneration.sol。

生成 FHE 密钥

KMS 会生成一个新的公钥，同时以**私密共享（key shares）**的方式在各 KMS 节点间分散持有 FHE 私钥分片：私钥分片用于 KMS 解密密文，而公钥供 coprocessor 在密文上执行同态运算。

触发方式：owner 调用KMSGeneration合约的keygen函数。生成的公共 FHE 密钥以唯一的keyId标识。

生成 CRS

CRS（Common Reference String）是 KMS 以安全方式生成的相关随机材料，用于构造某些 ZKPoK，特别是证明「知道某个在 FHE 密钥下加密的明文的明文知识」。

触发方式：owner 调用KMSGeneration合约的crsgen函数。生成的 CRS 以唯一的crsId标识。

PauserSet 与暂停机制

PauserSet 合约

PauserSet管理被允许暂停部分 Gateway 合约的地址（详见 pauser_set 文档）。Pauser 通常是由协议操作者（KMS 节点 / coprocessor）控制的 hot wallet。

PauserSet提供四个操作：

• addPauser：添加 pauser
• removePauser：移除 pauser
• swapPauser：用另一个地址交换 pauser
• isPauser：检查某地址是否为 pauser

它部署为不可变合约，地址存储在GatewayConfig合约中。

暂停机制

暂停机制（详见 pausing 文档）用于紧急情况：暂停协议以阻止任何新请求（输入证明、解密）被处理。Gateway 只能手动暂停与恢复。

涉及两个合约：PauserSet（管理 pauser 地址）与Pausable（抽象合约，提供暂停/恢复功能）。只有Decryption与InputVerification两个合约可被暂停。

被暂停的合约意味着：触发其请求（request）函数的任何交易都会被 revert。但：

• 已发送请求的响应仍会被接受，进行中的共识可以继续完成
• 其他视图函数仍可调用

具体影响：

暂停状态在源码层面通过 Decryption.sol 与 InputVerification.sol 继承的Pausable实现，暂停/恢复事件为Paused(address)与Unpaused(address)。

通过 Hardhat 任务暂停与恢复

仓库提供了定义于 tasks/pauseContracts.ts 的 Hardhat 任务：

暂停任务：

• pauseAllGatewayContracts：暂停所有 Gateway 合约
• pauseInputVerification：仅暂停InputVerification
• pauseDecryption：仅暂停Decryption

执行暂停任务需要在本地设置PAUSER_PRIVATE_KEY环境变量（即某个已注册 pauser 的私钥）。

恢复任务：

• unpauseAllGatewayContracts：恢复所有 Gateway 合约
• unpauseInputVerification：仅恢复InputVerification
• unpauseDecryption：仅恢复Decryption

重要：恢复任务仅在GatewayConfig所有权仍由部署者持有（需本地设置DEPLOYER_PRIVATE_KEY）时才可用。一旦GatewayConfig所有权转移到多签（multi-sig）owner，这些任务将无法恢复合约；此时需要通过多签合约调用GatewayConfig的unpause函数来恢复。

部署 FHEVM Gateway

环境变量全景

部署所需的环境变量完整清单定义在 env_variables.md 中。按类别整理如下（Solidity 类型与默认值均以仓库文档为准）：

不同网络的链 ID 约定：hardhat→31337，localGateway→123456，staging→54321，devnet→10900，testnet→10901。

关键配置示例（本地测试值）

部署时写入GatewayConfig的值：

# 协议元数据（部署后不可更新） PROTOCOL_NAME="Protocol" # (string) PROTOCOL_WEBSITE="https://protocol.com" # (string) # KMS 阈值（uint256） MPC_THRESHOLD="1" PUBLIC_DECRYPTION_THRESHOLD="3" USER_DECRYPTION_THRESHOLD="3" KMS_GENERATION_THRESHOLD="3" # Coprocessor 阈值（uint256） COPROCESSOR_THRESHOLD="2" # KMS 节点（索引从 0 开始） NUM_KMS_NODES="1" KMS_TX_SENDER_ADDRESS_0="0xc1d91b49A1B3D1324E93F86778C44a03f1063f1b" # (address) KMS_SIGNER_ADDRESS_0="0x305F1F471e9baCFF2b3549F9601f9A4BEafc94e1" # (address) KMS_NODE_IP_ADDRESS_0="127.0.0.1" # (string) KMS_NODE_STORAGE_URL_0="s3://kms-bucket-1" # (string) # Coprocessor（索引从 0 开始） NUM_COPROCESSORS="3" COPROCESSOR_TX_SENDER_ADDRESS_0="0x6518D50aDc9036Df37119eA465a8159E34417E2E" # (address) COPROCESSOR_SIGNER_ADDRESS_0="0xa5eE8292dA52d8234248709F3E217ffEBA5E8312" # (address) COPROCESSOR_S3_BUCKET_URL_0="s3://coprocessor-bucket-1" # (string)

部署后再通过单独脚本写入的值（host chain 与 pauser）：

# Host chains（索引从 0 开始；chain ID 必须互不相同） NUM_HOST_CHAINS="1" HOST_CHAIN_CHAIN_ID_0="2025" # (uint256) HOST_CHAIN_FHEVM_EXECUTOR_0="0xbb8ab3d75fd306ce85c90e899a2db850490cd697" # (address) HOST_CHAIN_ACL_ADDRESS_0="0xabcdef1234567890abcdef1234567890abcdef12" # (address) HOST_CHAIN_NAME_0="Host chain 2025" # (string) HOST_CHAIN_WEBSITE_0="https://host-chain-2025.com" # (string) # Pausers（数量建议等于操作者总数 = KMS 节点数 + coprocessor 数） NUM_PAUSERS="1" PAUSER_ADDRESS_0="0x6591319B97979Acc59b7191A8B4Ec381375bFc92" # (address)

ProtocolPayment的初始价格（单位 $ZAMA，18 位小数，owner 可后续更新）：

INPUT_VERIFICATION_PRICE="10000000000000000000" # 10 $ZAMA PUBLIC_DECRYPTION_PRICE="1000000000000000000" # 1 $ZAMA USER_DECRYPTION_PRICE="1000000000000000000" # 1 $ZAMA

支付桥接的前提条件

在真实环境部署前，需要先在以下链上部署配套合约（本地测试环境除外）：

• host chain：ZamaERC20（$ZAMA 代币）、FeesBurner（用于销毁操作费用）
• gateway chain：ZamaOFT（LayerZero OFT 合约，与ZamaERC20交互）、FeesSenderToBurner（带 LayerZero endpoint，用于将费用发送至FeesBurner）

从源码看，费用流转闭环在 ProtocolPayment.sol 中实现：合约持有FEES_SENDER_TO_BURNER_ADDRESS、DECRYPTION_ADDRESS、INPUT_VERIFICATION_ADDRESS三个常量地址，并直接以IERC20(zamaOFTAddress)形式操作 $ZAMA OFT 代币——即费用从Decryption与InputVerification收取后，通过 $ZAMA OFT 转账给FeesSenderToBurner，再由 LayerZero 跨链发送至 host chain 的FeesBurner销毁。

本地部署（Hardhat）

前置条件：克隆仓库并安装依赖：

npm install

本地部署的 Makefile 目标会自动将.env.example复制为.env并填入正确值。注意：默认使用的账户已预充值；若更换地址，需自行保证账户有足够余额。

第一步：启动本地节点（默认运行在端口 8757）：

make start-local-node

第二步：部署合约（使用localGateway网络）：

make deploy-contracts-local

该命令会完成两件事：

1. 通过 tasks/deployment/contracts.ts 中的deployAllGatewayContracts任务部署全部合约
2. 通过 tasks/addHostChains.ts 中的addHostChainsToGatewayConfig任务将 host chain 注册到GatewayConfig

第三步：管理 host chain。host chain 注册后的生命周期管理由 tasks/manageHostChains.ts 中的三个 owner-only 任务完成。每个任务都使用DEPLOYER_PRIVATE_KEY签名，并按与addHostChainsToGatewayConfig相同的方式解析GatewayConfig地址——默认读取GATEWAY_CONFIG_ADDRESS环境变量，当传入--use-internal-proxy-address true（本地/CI 流程）时则从addresses/目录解析：

# 禁用某个已注册的 host chain（保持注册但标记为禁用） npx hardhat task:disableHostChainOnGatewayConfig --chain-id <id> # 重新启用之前被禁用的 host chain npx hardhat task:enableHostChainOnGatewayConfig --chain-id <id> # 彻底移除 host chain（必须先禁用） npx hardhat task:removeHostChainOnGatewayConfig --chain-id <id>

每个任务都带有预检（chain 是否注册 / 是否已禁用），让操作者在提交本会 revert 的交易前就能得到清晰的错误提示。

第四步：运行测试：

make test-local

测试使用--skip-setup标志以避免重复部署合约。

Docker 部署

仓库的 docker-compose.yml 提供容器化部署路径（详见 docker_deploy 文档）：

# 构建镜像 make docker-compose-build # 启动容器 make docker-compose-up

启动后主要产生三个容器：

• anvil-node：本地以太坊网络，链 ID54321，端口8546
• deploy-gateway-contracts：部署合约
• add-host-chains：在合约部署完成后将 host chain 注册到GatewayConfig

验证部署是否成功：

docker logs deploy-gateway-contracts

若日志显示Contract deployment done!，则合约部署成功。接着检查：

docker logs add-host-chains

若日志显示Host chains registration done!，则 host chain 注册成功。

两个步骤都必须按顺序完成才能与合约交互；特别是若 host chain 未正确注册，会有大量交易预期地 revert。

清理：

make docker-compose-down

生产环境补充配置

生产部署后还需要设置（需在部署后动态获取实际地址）：

GATEWAY_CONFIG_ADDRESS="0xC7D45661a345eC5cA0e8521CFEF7e32FDA0Daa68" # (address) PAUSER_SET_ADDRESS="0xc1D733116990ce3D9e54F9eCf48a1cdD441Af4f9" # (address) NEW_OWNER_PRIVATE_KEY="0x7136d8dc72f873124f4eded25f3525a20f6cee4296564c76b44f1d582c57640f" # (bytes32)

• GATEWAY_CONFIG_ADDRESS：用于单独执行 add host chain 等任务
• PAUSER_SET_ADDRESS：用于单独管理 PauserSet 中的 pauser
• NEW_OWNER_PRIVATE_KEY：当所有权不直接转移给多签时，新 owner EAO 用它接受网关合约的所有权

暂停相关任务则需要设置 暂停环境变量：

PAUSER_PRIVATE_KEY="0x3588ffb4f4d9bea785a012b895543fe68f2d580a9d449decc91a25878064079a" # (bytes32) DEPLOYER_PRIVATE_KEY="0x7136d8dc72f873124f4eded25f3525a20f6cee4296564c76b44f1d582c57640f" # (bytes32)

其中PAUSER_PRIVATE_KEY必须是已注册在PauserSet中的某个 pauser 的私钥，用于执行暂停任务；DEPLOYER_PRIVATE_KEY仅在所有权仍由部署者持有时用于恢复任务。

深入源码：请求-共识-响应的关键调用链

将文档中的职责描述与源码对应起来，可以勾勒出两条核心调用链：

解密调用链：用户/合约调用Decryption.publicDecryptionRequest(bytes32[], bytes)（Decryption.sol#L332）或userDecryptionRequest（Decryption.sol#L466、Decryption.sol#L670）或delegatedUserDecryptionRequest（Decryption.sol#L560）发起请求；各 KMS 节点通过publicDecryptionResponse/userDecryptionResponse提交签名响应；Decryption依据GatewayConfig中读取的解密阈值（getPublicDecryptionThresholdForContext/getUserDecryptionThresholdForContext）统计有效签名，达到阈值后即视为达成共识。EIP-712 签名校验与ctHandles的 host chain 归属检查（错误如CtHandleChainIdDiffersFromContractChainId、KmsNodeAlreadySigned）保证只有注册 KMS 节点的有效响应才能进入共识计数。

密文承诺调用链：coprocessor 调用CiphertextCommits.addCiphertextMaterial(bytes32, uint256, bytes32, bytes32)（CiphertextCommits.sol#L123）提交密文承诺，并可通过getAddCiphertextMaterialConsensusTxSenders查询当前共识状态；只有达到 coprocessor 阈值后承诺才生效。错误定义（如CoprocessorAlreadyAdded、HostChainNotRegistered、HostChainDisabled）表明该合约同时校验 coprocessor 身份与 host chain 注册状态——这正是「只有注册 host chain 上的密文才被接受」策略的具体实现。

输入验证调用链：InputVerification.verifyProofRequest（InputVerification.sol#L184）接收用户提交的 ZKPoK，由注册 coprocessor 验证并签名，达到 coprocessor 阈值后通过/拒绝。

所有合约共用的权限原语可见于GatewayConfigChecks（错误如NotKmsTxSender、NotKmsSigner、NotCoprocessorTxSender、NotCoprocessorSigner、KmsSignerDoesNotMatchTxSender等，见 selectors.txt），而合约升级通过UPGRADE_INTERFACE_VERSION（selector0xad3cb1cc）、upgradeToAndCall与各reinitializeVX函数完成——selectors.txt中记录的reinitializeV6、reinitializeV7、reinitializeV9等即为历史升级版本号。

结语与延伸阅读

FHEVM Gateway 通过「配置集中、业务解耦」的合约架构，把多链密文管理、KMS 共识、协议支付与紧急暂停统一收敛到网关链上：GatewayConfig是唯一的配置事实来源，Decryption/InputVerification/CiphertextCommits/KMSGeneration通过共享检查模块动态读取配置并校验调用者身份，PauserSet提供应急暂停能力，ProtocolPayment则打通了 $ZAMA 的费用闭环。无论你是要部署网关、接入新的 host chain，还是审计解密共识逻辑，本文梳理的配置项、阈值公式、任务命令与源码调用链都可以作为直接的实操参考。

进一步阅读：

• Gateway 文档总览
• GatewayConfig 合约详解
• KMSGeneration 合约详解
• PauserSet 合约详解
• 暂停机制详解
• 环境变量完整说明
• 本地部署指南
• Docker 部署指南
• 合约函数选择器清单

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