fhEVM 协议中的 Relayer 与 Oracle连接链上合约与链下 Gateway/KMS 的可信桥梁【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm导读本指南基于 docs/protocol/architecture/relayer_oracle.md 展开系统讲解 fhEVMFHEVM全栈框架中两个面向使用者的轻量链下组件——Oracle预言机与Relayer中继器。它们是智能合约、普通用户与 Gateway网关/KMS密钥管理服务之间的最后一公里连接器Oracle 替合约取回链下解密结果Relayer 替用户提交加密输入并取回私有解密值。读完本文你将掌握这两类组件的职责边界、安全模型、完整的工作流含公共解密与用户解密的逐步拆解以及当前仓库中 relayer 服务的真实工程实现——从事件驱动架构、V2 API 端点、核心配置项到部署命令。一、为什么需要 Relayer 与 Oracle在 FHE 上链协议总览 中fhEVM 由 Solidity 库、宿主链合约、Coprocessor协处理器、Gateway、KMS 以及 Relayer Oracle 六大组件构成。其中前几者负责加密、计算与密钥管理而Oracle 和 Relayer 负责连接性——它们是对接 Gateway 的轻量服务让用户与合约无需自己实现复杂的集成逻辑即可与加密值顺畅交互。relayer_oracle.md 对此给出了一个关键定性These components are not part of the trusted base of the protocol; their actions are fully verifiable, and their misbehavior does not compromise confidentiality or correctness.即Oracle 与 Relayer 不属于协议的信任基trusted base。它们的行为完全可验证即使作恶也不会破坏机密性与正确性。理解这一点是把握整套安全模型的前提协议的安全并不依赖这两个组件诚实而是依赖密码学验证。二、Oracle替智能合约取回明文2.1 定义Oracle 是一个链下服务代表智能合约从 FHEVM 协议中取回解密值acts on behalf of smart contracts to retrieve decrypted values。由于 FHEVM 不允许合约直接在链上解密当合约需要一个加密计算结果的明文例如揭示投票结果、确定赢家、触发转账时就必须借助 Oracle 完成链上请求 → 链下解密 → 链上回调的闭环。2.2 四项职责原文给出了 Oracle 的完整职责清单监听链上解密请求监听宿主链上合约发出的解密请求事件向 Gateway 转发解密请求以合约的名义将解密请求提交给 Gateway等待 KMS 产出签名明文通过 Gateway 等待 KMS阈值 MPC 网络产出带签名的明文回调宿主链上的合约将解密结果传回合约。值得强调的是第 3、4 步的信任基础解密值由 KMS 签名因此接收方智能合约可以直接验证结果无需信任 Oracle 本身Since the decrypted values are signed by the KMS, the receiving smart contract can verify the result, removing any need to trust the oracle itself。2.3 安全模型Oracle 是不受信任的untrusted它最多只能延迟delay请求无法伪造falsify请求结果所有结果链上可验每个结果都带签名可在链上验证可替换性如果某个 Oracle 不响应另一个 Oracle 可以接管If one oracle fails to respond, another can take over。其目标被原文精炼为让合约无需内嵌解密逻辑即可异步、安全地访问解密值Enable contracts to access decrypted values asynchronously and securely, without embedding decryption logic。2.4 仓库中的完整调用链公共解密三步流程Oracle 代表合约取回明文这一角色在仓库中落地为一条异步三步骤公共解密流程完整教程见 docs/solidity-guides/decryption/oracle.md。它把工作拆分为链上与链下两部分正是 Oracle 职责的逐字实现Step 1链上开启永久公共访问权限合约使用 FHE Solidity 库将某个密文句柄标记为公开可解密全局且永久授权任意实体请求其明文FHE.makePubliclyDecryptable(_encryptedFoo); FHE.makePubliclyDecryptable(_encryptedBar);Step 2链下解密与证明生成链下客户端Oracle 角色把密文句柄提交给 Gateway/RelayerKMS 完成阈值解密后返回三样东西明文cleartext——解密出的原始值明文的 ABI 编码——供链上 ABI 解码使用解密证明decryption proof——由 KMS 签名与元数据组成的字节数组是明文确为 KMS 对原始密文的真实解密结果的密码学保证。Step 3链上验证并执行业务逻辑调用方把明文与证明提交回合约函数合约调用FHE.checkSignatures验证若证明无效或与明文/密文对不匹配则整个交易回滚FHE.checkSignatures(ciphertextEfooEbar, abiClearFooClearBar, publicDecryptionProof);只有验证通过合约才能安全地执行后续业务逻辑揭示投票、转移资金、更新状态。端到端示例FooBarContractoracle.md 给出了完整的FooBarContract示例源码可在仓库的示例合约中找到同款模式如 examples/Counter.sol 与 host-contracts/examples/MakePubliclyDecryptable.sol。核心骨架如下pragma solidity ^0.8.24; import fhevm/solidity/lib/FHE.sol; import { ZamaEthereumConfig } from fhevm/solidity/config/ZamaConfig.sol; contract FooBarContract is ZamaEthereumConfig { ebool _encryptedFoo; euint8 _encryptedBar; bool _clearFoo; uint8 _clearBar; bool _isFinalized; event ClearFooBarRequested(ebool encryptedFoo, euint8 encryptedBar); function runFooBarConfidentialLogic() external { require(!FHE.isInitialized(_encryptedFoo) || !FHE.isInitialized(_encryptedBar), foobar confidential logic already executed!); _encryptedFoo FHE.randEbool(); _encryptedBar FHE.randEuint8(); } function requestClearFooBar() external { FHE.makePubliclyDecryptable(_encryptedFoo); FHE.makePubliclyDecryptable(_encryptedBar); emit ClearFooBarRequested(_encryptedFoo, _encryptedBar); } function finalizeClearFooBar(bool clearFoo, uint8 clearBar, bytes memory publicDecryptionProof) external { require(!_isFinalized, foo is already revealed); // 关键约束解密证明与句柄数组的【顺序】密码学绑定 bytes32[] memory ciphertextEfooEbar new bytes32[](2); ciphertextEfooEbar[0] FHE.toBytes32(_encryptedFoo); ciphertextEfooEbar[1] FHE.toBytes32(_encryptedBar); bytes memory abiClearFooClearBar abi.encode(clearFoo, clearBar); FHE.checkSignatures(ciphertextEfooEbar, abiClearFooClearBar, publicDecryptionProof); _isFinalized true; _runFooBarClearBusinessLogicFinalization(); } }对应的链下 TypeScript 客户端即 Oracle 侧动作const tx await contract.runFooBarConfidentialLogic(); await tx.wait(); const tx2 await contract.requestClearFooBar(); const txReceipt await tx2.wait(); const { efoo, ebar } parseClearFooBarRequestedEvent(contract, txReceipt); // 链下解密获取明文 ABI 编码 KMS 解密证明 const instance: FhevmInstance await createInstance(); const results: PublicDecryptResults await instance.publicDecrypt([efoo, ebar]); const clearFoo results.values[efoo]; const clearBar results.values[ebar]; // 注意证明是针对 [efoo, ebar] 顺序生成的而非 [ebar, efoo] const decryptionProof: 0x${string} results.decryptionProof; // 回链上验证并终结流程 const tx3 await contract.finalizeClearFooBar(clearFoo, clearBar, results.decryptionProof); await tx3.wait();三个核心 API 的签名层函数作用链上FHE.makePubliclyDecryptable(ebool/euint8/.../euint256 value)将句柄标记为全局永久公开可解密调用方需对该句柄具备 ACL 权限链下instance.publicDecrypt(handles: (string \| Uint8Array)[])返回{ clearValues, abiEncodedClearValues, decryptionProof }链上FHE.checkSignatures(bytes32[] handlesList, bytes abiEncodedCleartexts, bytes decryptionProof)验证 KMS 签名handlesList与abiEncodedCleartexts数量必须一致、顺序必须严格对应验证失败即回滚从源码结构看这条链下链路正是 relayer 服务中public-decrypt处理器所中继的请求类型见下文第六节而FHE.makePubliclyDecryptable与FHE.checkSignatures的 Solidity 实现可分别在 library-solidity/lib/FHE.sol 与 library-solidity/lib/Impl.sol 中查看。三、Relayer面向用户的 Gateway 接口3.1 定义Relayer 是面向用户的服务a user-facing service简化用户与 Gateway 的交互尤其是那些必须发生在链下的加密encryption与解密decryption操作。文档中的描述This allows users to interact with encrypted smart contracts without having to run their own Gateway interface, validator, or FHE tooling.即用户无需自建 Gateway 接口、验证器或 FHE 工具链就能与加密智能合约交互。3.2 四项职责注册加密输入把用户生成的加密输入ciphertext提交给 Gateway 进行登记注册发起用户侧解密请求发起带EIP-712 认证的用户解密请求收集重加密结果从 KMS 收集用用户公钥重加密后的结果回传密文把密文交给用户由用户在浏览器/App 中本地解密。3.3 安全模型Relayer 无状态且不受信任stateless and untrusted所有数据流可签名、可由用户审计All data flows are signed and auditable by the user可替代性用户始终可以自建 Relayer或直接与 Gateway 交互Users can always run their own relayer or interact with the Gateway directly if needed。其目标是让用户无需管理基础设施就能轻松提交加密输入并取回私有解密结果。3.4 用户解密User Decryption工作流结合 docs/protocol/d_re_ecrypt_compute.mdRelayer 承载的用户解密完整流程如下取密文句柄dApp 通过 view 函数如balanceOf从合约拿到待解密密文的句柄生成并签名密钥对dApp 为用户生成密钥对用户对公钥签名以证明真实性提交用户解密请求dApp 向 Gateway 发出交易携带密文句柄、用户公钥、用户地址、合约地址、用户签名等信息。这笔交易既可由客户端直接发给 Gateway 链也可经 Relayer 的 HTTP 端点转发——Relayer 在此抽象了交易处理细节本地解密dApp 从 Gateway/Relayer 收到用用户公钥加密的密文后用用户私钥在本地解密。整个过程保证只有请求用户能看到明文、KMS 绝不泄露解密值、解密结果不会写入区块链。EIP-712 签名保证了请求确实来自该用户FHE 密钥重加密保证了密文只能被该用户打开。四、两者如何协同完整链路一图流原文 How they fit in 一节给出了定位总结可归纳为下表维度OracleRelayer服务对象智能合约终端用户dApp主要动作监听链上请求 → 向 Gateway 转发 → 取回 KMS 签名明文 → 回调合约提交加密输入 → 发起 EIP-712 解密请求 → 取回重加密密文 → 交还用户信任假设不受信任可延迟不可伪造无状态、不受信任、可审计安全底座KMS 签名 链上checkSignatures验证EIP-712 签名 FHE 密钥重加密失败处理其他 Oracle 可接管用户可自建 Relayer 或直连 Gateway在 Gateway 架构文档 中可以看到 Gateway 侧的配合动作当合约或用户请求解密时Gateway 先验证 ACL 权限再触发 KMS 解密公开或私有KMS 返回签名结果后Gateway 发出事件——该事件可被 Oracle 拾取用于合约解密或直接返回给用户用于私有解密。而 KMS 文档 给出的公共解密工作流示例则完整串联了五步合约经 Oracle 请求解密 → Gateway 验证权限并发事件 → KMS 各节点 MPC 解密并签名 → 达到阈值后发布带签名结果 →Oracle 将明文回帖上链合约用 KMS 签名验证真实性。五、Relayer 的工程实现事件驱动架构当前仓库的 relayer 目录就是文档所述 Relayer 服务的完整 Rust 实现二进制入口为 relayer/src/startup.rs 中的run_fhevm_relayer。其 README 明确了四项核心能力Public Decryption中继 HTTP 公共解密请求并返回明文响应Input Proof Verification中继 HTTP 输入证明验证请求并返回有效性证明attestationUser Decryption中继 HTTP 用户解密请求在用户提供的公钥下重加密数据带密文句柄访问控制Key Material暴露密钥材料 URLFHE 公钥与 CRS 的 URL。5.1 事件驱动组件系统采用事件驱动架构核心组件包括Orchestrator事件流与处理的中央协调器Gateway 监听器/处理器监听并处理 Gateway 链上事件WSSHTTP Handlers处理 V2 API 请求SQL Repositories持久化请求状态支持状态轮询Transaction Engine Throttlers可靠的交易管理与背压backpressure控制Metrics TracingAPI、队列与区块链流程的运行时可观测性。对应源码结构为 relayer/src/orchestrator/事件编排、relayer/src/gateway/监听器与交易引擎、relayer/src/http/HTTP 服务与 V2 处理器、relayer/src/store/sql/状态持久化。5.2 HTTP API 端点健康检查端点端点说明GET /liveness存活探针GET /healthz就绪/健康检查GET /version构建版本信息GET /docsOpenAPI 文档密文操作与密钥 URL 端点异步任务语义POST提交请求并返回job_id随后GET .../{job_id}轮询结果操作端点输入证明验证POST /v2/input-proof公共解密POST /v2/public-decrypt用户解密POST /v2/user-decrypt委托用户解密POST /v2/delegated-user-decrypt密钥材料 URLGET /v2/keyurl管理端点GET /admin/config与POST /admin/config由enable_admin_endpoint控制默认关闭时返回 403用于运行时调整节流 TPS 与 retry-after 字段主要面向测试与基准场景。注意 README 特别提示这些端点默认禁用且无应用层认证启用时必须通过网络层控制访问范围绑定回环地址或内网子网或置于认证层之后。六、Relayer 关键配置解析配置加载支持三种途径见 relayer/README.mdYAML 文件默认config/local.yaml、CLI 参数--config-file、以及带APP_前缀的环境变量用__表示嵌套层级可覆盖文件值例如APP_GATEWAY__BLOCKCHAIN_RPC__HTTP_URL...。完整可参考 relayer/config/local.yaml.example。核心配置块如下配置块关键参数说明host_chainschain_id/url/acl_address宿主链 RPC 与 ACL 合约地址protocol_configethereum_http_rpc_url/address/retry协议配置合约地址与重试策略keyurlsourcechain|config/kms_generation_address/poll_interval_ms/v2/keyurl数据来源轮询宿主链或提供静态值user_decrypt_signature_checkerc1271_gas_limitERC-1271isValidSignature静态调用的 gas 上限gateway.blockchain_rpchttp_url/read_http_url/chain_idGateway 链 RPChttp_url必须支持eth_sendRawTransactionSyncgateway.listener_poollistenerssubscription/polling/reconnect_config/poll_interval_ms/max_blocks_per_query/dedup_ttl_seconds/dedup_max_capacity统一监听器池去重 TTL、分块追块、交错回收gateway.tx_enginesignerprivate_key|aws_kms/max_concurrency/retry/tx_throttlers交易签名与每类请求的节流参数如input_proof/user_decrypt/public_decrypt的per_seconds、capacitygateway.contractsdecryption_address/input_verification_address/user_decrypt_shares_thresholdGateway 链上合约地址与用户解密份额阈值httpendpoint/enable_admin_endpoint/retry_after动态 Retry-Aftermin_seconds、max_seconds、safety_margin、nominal_times、copro_kms_backoff_intervalsHTTP 服务与排队响应策略metricsendpoint默认0.0.0.0:9898与各类直方图桶Prometheus 指标storagesql_database_url/app_pool/cron_pool/cronPostgreSQL 连接池与后台任务其中storage.cron下的请求超时策略默认值如下由后台 worker 将长时间停留在receipt_received状态的请求标记为timed_out该 worker 始终启用实现见 relayer/src/store/sql/repositories/timeout_repo.rs配置键默认值说明storage.cron.timeout_cron_interval60s超时扫描间隔storage.cron.public_decrypt_timeout30m公共解密请求超时storage.cron.user_decrypt_timeout30m用户解密请求超时storage.cron.input_proof_timeout30m输入证明请求超时数据保留策略清理已完成请求以控制存储增长实现见 relayer/src/store/sql/repositories/expiry_repo.rsexpiry worker默认关闭需设置expiry_enabled: true开启并要求数据库用户具有DELETE权限保留窗口示例public_decrypt_expiry: 365d、user_decrypt_expiry: 7d、input_proof_expiry: 7d。七、部署与快速开始relayer/README.md 给出了 Mainnet / Testnet 两条等价的快速启动路径完整的生产部署与安全考量见 自托管指南make db-start # 启动本地 PostgresDocker Compose端口 5433 make db-migrate # 应用数据库迁移 make preflight-mainnet # 交互式配置、私钥、余额检查、授权Testnet 用 preflight-testnet make run-mainnet # 启动 relayerTestnet 用 run-testnet make health # 验证健康端点开发环境可先执行make setupdb-start db-migrate 复制本地 mock 配置其余构建、测试、lint 与 CI 说明见 开发指南。README 中还包含若干排障要点本地 Postgres 映射在5433端口而非 5432连接被拒时先核对端口新增或修改 SQL 查询后需先运行make sqlx-prepare再构建 Docker 镜像构建依赖.sqlx/预计算查询元数据config/local.yaml.example内置localhost:8757RPC 与0.0.0.0:3001key URL仅适用于本地 mock 栈面向 Testnet/Mainnet 时应使用make preflight-*自动复制正确的示例配置运行完整本地栈./fhevm-cli deploy需要至少12 GBDocker 内存。结语Relayer 与 Oracle 是 fhEVM 协议中小而关键的连接件它们把协议的能力边界从链上扩展到链下让合约能够异步、安全地消费解密结果让用户能够在不运行任何 FHE 基础设施的前提下提交加密输入、取回私有明文。由于它们被刻意排除在信任基之外所有行为都落在可验证、可替换、可审计的框架内——这正是整个系统能够在保持去中心化与安全性的同时维持良好可用性的关键设计。若需继续深入建议依次阅读 Gateway、KMS 与 公共解密教程并在 relayer 源码中追踪POST /v2/user-decrypt与POST /v2/public-decrypt从 HTTP 入口到交易引擎的完整调用链。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
