fhEVM Relayer 公共解密Public Decryption跨链流程深度解析从 Ethereum L1 事件到 Gateway L2 回调的完整链路【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本文基于 fhEVM 仓库中 relayer/design-docs/decryption-flow/decryption_flow_sequence_diagram.md 展开围绕其中定义的跨链解密时序图结合同目录下的 decryption_flow_chart.md、decryption-flow-inside-relayer.plantuml 以及 relayer 与 gateway-contracts 的源码实现从事件类型、参与者、请求—响应全链路、内部状态机到错误处理逐一拆解。读完本文你将能完整掌握 fhEVM 公共解密请求从宿主任意链Host L1如 Ethereum发起、经 relayer 转发到网关链Gateway L2如 Arbitrum的 Decryption 合约、再由 KMS 多方门限解密后回传并在 L1 上触发回调交易的端到端机制并能在源码中准确对应每一步实现。背景与文档定位fhEVM 双链架构与解密场景fhEVM 的 relayer 是连接 fhEVM 宿主任意链Host chains例如 Ethereum与 Gateway网关链例如 Arbitrum之间的桥梁。在 FHE全同态加密场景中链上合约只持有密文句柄ciphertext handle而真正可以解读的明文保存在 FHE 网络中。当某个 DApp 合约需要把一个euint密文公开解密为明文时就会产生一次Public Decryption公共解密请求。relayer 对外提供四类核心能力见 relayer/README.mdPublic Decryption转发 HTTP 公共解密请求并返回明文响应Input Proof Verification转发输入证明验证请求并返回有效性证明User Decryption转发用户解密请求在用户公钥下重加密数据带句柄 ACL 控制Key Material暴露 FHE 公钥与 CRS 等密钥材料 URL。本文聚焦的关联文档所描述的正是其中Public Decryption这条跨链链路的时序一次解密请求如何穿越 Ethereum L1 → relayer → Arbitrum L2 → KMS → Arbitrum L2 → relayer → Ethereum L1 的完整闭环。关联文档三件套仓库relayer/design-docs/decryption-flow/目录下存在两份相互配套的设计文档加上同目录relayer/design-docs/下的一份 PlantUML三者共同刻画了同一条解密链路文件视角decryption_flow_sequence_diagram.md跨参与者L1 / Listener / Handler / L2的时序图本文主体decryption_flow_chart.mdrelayer 内部事件处理的流程图handle_event 状态机decryption-flow-inside-relayer.plantuml带错误分支与超时分支的细化时序图下面先从参与者与事件类型入手再逐步展开完整时序、状态机与源码对应。一、时序图全景参与者与整体脉络5 个核心参与者原时序图decryption_flow_sequence_diagram.md定义了 5 个参与者它们分别对应 relayer 代码中的具体组件时序图参与者缩写对应源码位置职责Ethereum L1L1—宿主任意链Ethereum发出 Decryption request 事件接收并执行回调交易ethereum_listenerELrelayer/src/host/ 下的 Host L1 事件监听订阅 L1 事件日志包装为 relayer 内部事件ethereum_host_l1_handlersEHHost L1 事件处理器解码、存储上下文、触发回调解码事件、关联请求上下文、执行回调arbitrum_gw_l2_handlerAGHrelayer/src/gateway/public_decrypt_handler.rs组装并发送 Gateway 交易、提取 decryption IDrollup_listenerRLrelayer/src/gateway/arbitrum/listener.rs 与 polling_listener.rs订阅 Gateway L2 的响应事件需要说明的是时序图中ethereum_listener/ethereum_host_l1_handlers是对 Host 侧组件在“本仓库 relayer”实现中的代号时序图本身把它们与arbitrum_gw_l2_handler、rollup_listener并列反映的是设计时的组件职责划分。一图读懂整个闭环时序图原文档核心内容此处完整保留并整理如下整个流程可以归纳为四个阶段请求进入L1 → relayerL1 上的合约发出 Decryption request 事件relayer 的 Host 监听器捕获并解码生成内部 request ID将(l1_req_id, contractCaller, selector)存入上下文转发网关relayer → L2relayer 组装交易提交到 Gateway L2 的 Decryption 合约从回执中提取public_decryption_id图中示例值0xAA并把(0xAA, 0x123)映射持久化响应返回L2 → relayerKMS 多方完成门限解密后将结果回帖到 L2L2 发出 Decryption Response 事件relayer 的 rollup 监听器收到事件反查read_uuid(0xAA) 0x123找到原始请求回调上链relayer → L1relayer 依据上下文中的contract_caller与selector在 L1 提交回调交易合约在链上读取明文并校验签名流程结束。注时序图中出现了 L1,L2 的Note over其本意是Ethereum L1与Arbitrum L2下文统一称为“L1 / L2”。二、事件类型体系relayer 内部的“事件总线”时序图里反复出现的relayerEvent:PubDecryptEventLogRcvdFromHostL1、DecryptRequestRcvd、DecryptionReqToGwL2Sent、DecryptResponseEventLogRcvdFromGwL2等在真实实现中统一收敛为一套带编号的事件枚举。relayer 采用事件驱动架构Orchestrator 作为中央协调者通过 TokioEventDispatcher 把事件分发给已注册的 Handler。事件枚举与编号源码 relayer/src/core/event.rs 定义了PublicDecryptEventId与GatewayChainEventId// PublicDecryptEventId —— Public Decrypt 流程的内部事件10~18 pub enum PublicDecryptEventId { ReqRcvdFromUser 10, // HTTP 收到公共解密请求 ReadinessCheckPassed 11, // 就绪检查通过 ReqSentToGw 12, // 已向 Gateway 发送请求 RespRcvdFromGw 13, // 从 Gateway 收到响应 RespSentToUser 15, // 已向用户返回响应 InternalFailure 16, ReadinessCheckTimedOut 17, ReadinessCheckFailed 18, } // GatewayChainEventId —— 来自 Gateway 链的事件50~54 pub enum GatewayChainEventId { UserDecryptionResponse 50, UserDecryptionResponseThresholdReached 51, PublicDecryptionResponse 52, // ← 公共解密响应事件 VerifyProofResponse 53, RejectProofResponse 54, }事件数据使用RelayerEventData枚举承载PublicDecrypt/UserDecrypt/InputProof/GatewayChain四类RelayerEvent则把job_id、api_version、timestamp与事件数据绑定为一个可分发单元。每次事件都带有稳定的job_id用于跨阶段关联同一笔请求。事件分发机制relayer/src/orchestrator/tokio_event_dispatcher.rs 实现了两级分发register_handler(event_ids, handler)Handler 按事件 ID 列表注册自己例如 public_decrypt_handler.rs 中GatewayHandler::new注册了ReqRcvdFromUser、ReqSentToGw、InternalFailure、ReadinessCheckPassed/TimedOut/Failed以及GatewayChainEventId::PublicDecryptionResponse共 7 个事件dispatch_event(event)按event.event_id()查订阅表为每个订阅的 Handler 派生一个tokio任务并行执行dispatch_event_and_wait则等待所有 Handler 完成用于需要同步确认的区块游标推进场景。这样设计的好处是监听器只负责“收日志、打包事件”Handler 只负责“消费事件、干具体活”两者通过事件解耦天然支持多 Handler 订阅同一事件例如响应事件同时被状态持久化、指标统计、HTTP 通知等多个消费者处理。三、请求阶段从 L1 事件到 Gateway 交易上链前3.1 Host L1 监听与事件解码时序图中L1-EL: Emit Decryption request Event与EL-EH: PubDecryptEventLogRcvdFromHostL1描述的是 Host 监听器捕获 L1 上 DApp 合约发出的解密请求事件。在实现上relayer/src/gateway/arbitrum/bindings.rs 定义了一张“网关事件签名表”fn gateway_chain_events() - [(FixedBytes32, IntoEvent); 5] { [ (Decryption::UserDecryptionResponse::SIGNATURE_HASH, ...), (Decryption::UserDecryptionResponseThresholdReached::SIGNATURE_HASH, ...), (Decryption::PublicDecryptionResponse::SIGNATURE_HASH, // ← 公共解密响应 |log, tx_hash| GatewayChainEventData::PublicDecryptionResponse { log, tx_hash }), (InputVerification::VerifyProofResponse::SIGNATURE_HASH, ...), (InputVerification::RejectProofResponse::SIGNATURE_HASH, ...), ] }监听器通过topic0与这张签名表匹配来决定事件归属record_and_dispatch见 arbitrum/listener.rs 与 polling_listener.rs负责把命中的日志连同tx_hash打包为RelayerEvent交给 Orchestrator 分发。关于“响应事件”Gateway 侧的PublicDecryptionResponse事件由 gateway-contracts/contracts/Decryption.sol 定义其publicDecryptionResponse函数在校验decryptionId合法、EIP-712 签名有效后记录已验证签名并触发该事件relayer 的GatewayHandler::process_decrypt_response用Decryption::PublicDecryptionResponse::decode_log_data(log.data())解码出decryptionId、decryptedResult、signatures、extraData。3.2 上下文数据存储时序图中Store (l1_req_id, contractCaller, selector)与Create new request ID 0x123描述的是relayer 在收到 L1 请求后把L1 请求 ID、回调合约地址contractCaller、回调函数选择器selector关联存储并生成一个新的内部请求 ID。在更细化的 decryption-flow-inside-relayer.plantuml 中这一步对应EthereumListener - EthereumListener: Generate Orchestrator Request ID以及EthereumHostL1Handler - EthereumHostL1Handler: Store to context data (Orchestrator Request ID, Callback selector, address)。plantuml 还强调了主题topic匹配逻辑只有 topic 匹配 Decryption Request 事件的日志才被解码处理否则直接忽略——这是事件过滤器filter在 Handler 层的体现。所谓“context data”在真实实现里是数据库持久化而非内存relayer 的 SQL 仓库relayer/src/store/sql/中的public_decrypt_repo等仓库负责把请求状态、gw_reference_id即时序图中的public_decryption_id/0xAA、回调信息等写入 PostgreSQL。这也是 relayer 重启后能从数据库与链游标chain cursor恢复未完成请求的基础。3.3 就绪检查readiness check与发送交易时序图中EH-AGH: DecryptRequestRcvd (ct_handles, operation_type)之后直接进入AGH-L2: Submit Transaction。真实实现中在真正上链之前还有一个就绪检查环节plantuml 与 chart 均未显式画出但源码确凿ReqRcvdFromUser事件触发 readiness_check_enqueue —— 把请求塞进PublicDecryptReadinessTask队列带信号量节流后台 PublicDecryptReadinessProcessor 消费队列调用ReadinessChecker检查所有密文句柄在 fhEVM 上已就绪、可解密结合 host/acl_checker.rs 的isAllowedForDecryption逐句柄 ACL 检查通过后派发ReadinessCheckPassed进入send_public_decrypt_request→send_to_gateway把ct_handles转成VecFixedBytes32用ComputeCalldata::public_decryption_req(handles, extra_data)生成 calldata构造GatewayTxTask交易类型TransactionType::PublicDecryptRequest推入交易节流队列tx_throttler。值得留意的是send_to_gateway中的队列满处理队列满时返回ProtocolOverload错误并提示 Relayer is full, retry later.而入口的 intake bouncer 会保持该场景不可达源码注释明确说明。四、交易确认与 decryption ID 提取时序图中Extract public_decryption_id 0xAA from receipt与Insert (public_decryption_id, original_event_request_id)/Insert (0xAA, 0x123)是请求—响应关联的关键一环relayer 必须以 Gateway 生成的public_decryption_id作为将来匹配响应的钥匙把它与内部 request ID0x123绑定。4.1 从回执中提取 gateway IDrelayer/src/gateway/arbitrum/transaction/helper.rs 的extract_gateway_id_from_receipt是通用提取器pub fn extract_gateway_id_from_receiptT: SolEvent( receipt: AnyTransactionReceipt, expected_signature: FixedBytes32, extract_id_fn: impl Fn(T) - U256, ) - ResultU256, EventProcessingError { for log in receipt.inner.logs() { if let Some(topic_0) log.topics().first() { if *topic_0 expected_signature { match T::decode_log_data(log.data()) { Ok(decoded_event) return Ok(extract_id_fn(decoded_event)), ... } } } } // 未找到目标事件 → ValidationFailed }在公共解密场景GatewayHandler的TxLifecycleHooks::on_receipt_received以Decryption::PublicDecryptionRequest_0为事件类型、以其SIGNATURE_HASH为签名、以|event| event.decryptionId为提取函数调用该工具拿到gw_reference_id后调用public_decrypt_repo.update_status_to_receipt_received_on_tx_success把tx_hash与gw_reference_id一并写入数据库。这正是时序图Insert (0xAA, 0x123)的实现落点。4.2 交易生命周期钩子TxLifecycleHooksGatewayHandler实现了TxLifecycleHookstrait同一文件内把交易生命周期与数据库状态机绑定钩子触发时机动作on_tx_in_flight交易即将广播状态置为tx_in_flight若被 epoch fence 拒绝则返回ClaimLost放弃本次发送on_receipt_received交易上链、收到回执提取gw_reference_id把tx_hashgw_reference_id落库on_failure交易失败revert 等提取 revert selector 并分类、记录指标更新状态为失败其中on_receipt_received的注释值得展开如果写入被拒rows_affected 0说明该行的tx_in_flight状态已被更新的 epoch 接管多 pod 场景下后继者抢占了归属此时gw_reference_id不会被写入——因为 Gateway 响应监听器正是靠它来匹配请求宁可让后继者重新驱动re-drive交易并记录自己的回执也不能把“半成功”状态误记为成功。4.3 Decryption 合约侧的 ID 生成Gateway 侧的 Decryption.sol 中publicDecryptionRequest函数会生成一个全局唯一的publicDecryptionId基于部署时初始化的计数器使得decryptionId首字节唯一并发出PublicDecryptionRequest(publicDecryptionId, ctHandles, extraData)事件对应的publicDecryptionResponse(decryptionId, ...)会校验decryptionId必须落在(PUBLIC_DECRYPT_COUNTER_BASE, publicDecryptionCounter]区间内防止伪造未请求过的解密 ID。这些约束保证了 relayer 在回执中提取到的decryptionId是可信的。五、响应阶段L2 事件回传与请求关联5.1 rollup 监听器收到响应事件时序图L2-RL: Emit Decryption Response Event描述 KMS 完成解密后L2 上发出响应事件。在更细化的 plantuml 中这一阶段被标注为Wait until request is picked up by k KMS Parties (threshold defined in Decryption Manager), processed and result is posted back.即Gateway 的 Decryption Manager 定义了门限k需要至少k个 KMS 参与方各自解密并提交后达成共识结果才会上链对应源码 Decryption.sol 中的verifiedPublicDecryptSignatures、decryptionConsensusDigest等状态以及publicDecryptionResponse中按(decryptionId, digest)聚合签名、达到门限才触发共识事件的设计。plantuml 还画出了一个超时分支Result not available within timeout — Yet to define how this should be handled. Maybe do nothing and Ethereum sends timed out error to user.即超时处理在文档写作时尚未定案可能的方案是 L1 侧直接向用户返回超时错误。这是文档中明确标注的“未决设计点”不是已实现行为。5.2 反查请求 IDread_uuid(0xAA) 0x123时序图Retrieve public_decryption_id (0xAA)→Read associated event request id, read_uuid(0xAA) 0x123描述的是响应与请求的关联correlation以事件中的public_decryption_id0xAA为键反查出最初生成的内部 request ID0x123。真实实现对应GatewayHandler::process_decrypt_responserelayer/src/gateway/public_decrypt_handler.rs解码PublicDecryptionResponse事件得到decryptionId、decryptedResult、signatures、extraData组装成PublicDecryptResponse调用public_decrypt_repo.complete_req_with_res(public_decryption_id, decrypt_response, tx_hash)以public_decryption_id为键更新数据库并把明文与签名写入根据更新结果分派Completed { int_job_id }→ 用拿到的job_id派发RespRcvdFromGw事件通知等待中的 HTTP handler 取结果AlreadyCompleted→ 重复事件跳过幂等AlreadyInFinalState→ 已在失败/超时等终态跳过NotFound→ 响应事件先于gw_reference_id落库到达高 RPC 延迟下的竞态进入带延迟的重试循环。5.3 竞态处理GwEventNotFound 重试NotFound分支的实现是当前代码中的一个重要工程细节源码注释明确标注TEMPORARY FIX配置项来自GwEventNotFoundRetryConfig见 relayer/src/config/settings.rs 附近包含max_retries与retry_delay_ms每次失败后tokio::time::sleep(retry_delay_ms)再重试complete_req_with_res达到最大重试次数仍NotFound时递增unmatched_gateway_event(public_decryption_response)指标并记录日志后放弃注释明确最终应以事件缓冲event buffering方案替换该临时重试方案。这一段与时序图中Insert (0xAA, 0x123)的时序紧密相关正因为 ID 映射写入与响应事件到达之间存在竞态窗口才需要此重试机制兜底。六、回调阶段在 L1 上执行合约回调6.1 上下文恢复与回调交易时序图Retrieve from contextual data → req.contract_caller, req.selector → Submit callback transaction to contract caller描述 relayer 在拿到明文与签名后从上下文取出请求时保存的回调合约地址contractCaller与回调选择器selector在 L1 上构造并提交回调交易。plantuml 补充了两个分支Transaction Succeededrelayer 派发DecryptResponseSentToHostL1事件L1 合约内部处理回调读取明文、校验签名Transaction failedrelayer 派发DecryptionFailed事件。6.2 响应数据与事件派发响应数据本身由PublicDecryptResponse结构体承载relayer/src/core/event.rspub struct PublicDecryptResponse { pub gateway_request_id: U256, // 即 public_decryption_id / 0xAA pub decrypted_value: Bytes, // 解密出的明文 pub signatures: VecBytes, // KMS 门限签名集合 pub extra_data: String, // 原样透传的附加数据 }process_decrypt_response成功关联请求后会以RespRcvdFromGw事件通知 HTTP 侧HTTP handlerrelayer/src/http/endpoints/v2/handlers/public_decrypt.rs 中的GET /v2/public-decrypt/{job_id}即可从数据库读取结果返回给调用方。6.3 流程终点链上读明文、验签名时序图最后Read plaintext and check signatures描述 L1 合约侧的动作回调交易在合约上下文里执行合约读取明文并校验 KMS 签名阈值签名集合校验通过后明文即被视为可信并可用于合约逻辑。至此Note over L1,L2: End of Flow一次公共解密闭环完成。七、状态机视角decryption_flow_chart.md 详解同目录下的 decryption_flow_chart.md 从 relayer 内部状态机视角复述了同一链路与本文第一、三、五章互为印证这张流程图把时序图未展开的两个内部细节补全了句柄转换Convert handles to Uint256—— 请求进入时ct_handles会被转换为Uint256形式再组装 calldata与源码中ComputeCalldata::public_decryption_req接收VecFixedBytes32的处理对应人工延迟Artificial delay—— 响应处理阶段存在一个有意的人为延迟用于等待decryption_id → request_id映射落库与 5.3 节竞态重试的设计意图一致属于文档层面记录的工程折中查找失败即记日志Found Request ID? → No → Log Error—— 映射缺失时当前流程图设计为仅记录错误不做其他处理。该流程图中出现的事件名DecryptRequestRcvd、DecryptResponseEventLog、DecryptionRequestSent与源码枚举存在命名演进差异但其语义与PublicDecryptEventId/GatewayChainEventId完全对应详见第二章。八、关键源码路径速查表为便于读者在仓库中快速定位汇总本文涉及的核心文件关注点路径设计文档时序图 / 流程图 / PlantUMLrelayer/design-docs/decryption-flow/、relayer/design-docs/decryption-flow-inside-relayer.plantuml事件枚举与事件数据定义relayer/src/core/event.rs事件分发Orchestrator / Dispatcherrelayer/src/orchestrator/tokio_event_dispatcher.rs、relayer/src/orchestrator/orchestrator.rs公共解密 Gateway Handlerrelayer/src/gateway/public_decrypt_handler.rs网关事件签名表与解码relayer/src/gateway/arbitrum/bindings.rsGateway L2 监听器WSS / 轮询relayer/src/gateway/arbitrum/listener.rs、relayer/src/gateway/arbitrum/polling_listener.rs回执 gateway ID 提取relayer/src/gateway/arbitrum/transaction/helper.rs就绪检查处理器relayer/src/readiness/public_decrypt_processor.rs、relayer/src/host/acl_checker.rsHTTP v2 公共解密端点relayer/src/http/endpoints/v2/handlers/public_decrypt.rsSQL 仓库与状态模型relayer/src/store/sql/含public_decrypt_repo、public_decrypt_req_modelGateway Decryption 合约gateway-contracts/contracts/Decryption.solRelayer 架构总览relayer/README.md九、工程要点与设计权衡小结把时序图、流程图、plantuml 与源码对照后可以提炼出这条解密链路几个值得借鉴的工程要点以 ID 为中心的双向关联请求方向用内部request_id0x123串起 L1 请求与 Gateway 交易响应方向用public_decryption_id0xAA反查request_id。(0xAA, 0x123)映射是整条链路的“关节”落库时机与事件到达时序之间的竞态由重试机制兜底。事件驱动 订阅分发监听器与业务 Handler 完全解耦topic0签名表统一了“该听什么”的规则注册机制决定了“谁来处理”天然支持幂等与多消费者。数据库即上下文所谓 context data 全部持久化到 PostgreSQL配合 epoch fence写入被拒即视为归属易主支持多 pod 高可用与重启恢复relayer/src/store/sql/repositories/public_decrypt_repo.rs中的update_status_to_*系列方法即状态机跃迁的具体执行者。事务生命周期钩子化交易发送、回执、失败通过TxLifecycleHooks三个钩子与状态机绑定失败时提取 revert selector 并归类便于监控与告警。未决设计点响应超时KMS 未在时限内回帖的处理在 decryption-flow-inside-relayer.plantuml 中明确标注为 Yet to define可能的方案是 L1 向用户返回超时错误而 Gateway 侧的门限共识行为k个 KMS 参与方由 Decryption Manager 与 Decryption.sol 的门限校验逻辑决定。理解这些标注有助于区分“已实现行为”与“设计中行为”避免把设计草案当成品。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
fhEVM Relayer 公共解密Public Decryption跨链流程深度解析从 Ethereum L1 事件到 Gateway L2 回调的完整链路【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本文基于 fhEVM 仓库中 relayer/design-docs/decryption-flow/decryption_flow_sequence_diagram.md 展开围绕其中定义的跨链解密时序图结合同目录下的 decryption_flow_chart.md、decryption-flow-inside-relayer.plantuml 以及 relayer 与 gateway-contracts 的源码实现从事件类型、参与者、请求—响应全链路、内部状态机到错误处理逐一拆解。读完本文你将能完整掌握 fhEVM 公共解密请求从宿主任意链Host L1如 Ethereum发起、经 relayer 转发到网关链Gateway L2如 Arbitrum的 Decryption 合约、再由 KMS 多方门限解密后回传并在 L1 上触发回调交易的端到端机制并能在源码中准确对应每一步实现。背景与文档定位fhEVM 双链架构与解密场景fhEVM 的 relayer 是连接 fhEVM 宿主任意链Host chains例如 Ethereum与 Gateway网关链例如 Arbitrum之间的桥梁。在 FHE全同态加密场景中链上合约只持有密文句柄ciphertext handle而真正可以解读的明文保存在 FHE 网络中。当某个 DApp 合约需要把一个euint密文公开解密为明文时就会产生一次Public Decryption公共解密请求。relayer 对外提供四类核心能力见 relayer/README.mdPublic Decryption转发 HTTP 公共解密请求并返回明文响应Input Proof Verification转发输入证明验证请求并返回有效性证明User Decryption转发用户解密请求在用户公钥下重加密数据带句柄 ACL 控制Key Material暴露 FHE 公钥与 CRS 等密钥材料 URL。本文聚焦的关联文档所描述的正是其中Public Decryption这条跨链链路的时序一次解密请求如何穿越 Ethereum L1 → relayer → Arbitrum L2 → KMS → Arbitrum L2 → relayer → Ethereum L1 的完整闭环。关联文档三件套仓库relayer/design-docs/decryption-flow/目录下存在两份相互配套的设计文档加上同目录relayer/design-docs/下的一份 PlantUML三者共同刻画了同一条解密链路文件视角decryption_flow_sequence_diagram.md跨参与者L1 / Listener / Handler / L2的时序图本文主体decryption_flow_chart.mdrelayer 内部事件处理的流程图handle_event 状态机decryption-flow-inside-relayer.plantuml带错误分支与超时分支的细化时序图下面先从参与者与事件类型入手再逐步展开完整时序、状态机与源码对应。一、时序图全景参与者与整体脉络5 个核心参与者原时序图decryption_flow_sequence_diagram.md定义了 5 个参与者它们分别对应 relayer 代码中的具体组件时序图参与者缩写对应源码位置职责Ethereum L1L1—宿主任意链Ethereum发出 Decryption request 事件接收并执行回调交易ethereum_listenerELrelayer/src/host/ 下的 Host L1 事件监听订阅 L1 事件日志包装为 relayer 内部事件ethereum_host_l1_handlersEHHost L1 事件处理器解码、存储上下文、触发回调解码事件、关联请求上下文、执行回调arbitrum_gw_l2_handlerAGHrelayer/src/gateway/public_decrypt_handler.rs组装并发送 Gateway 交易、提取 decryption IDrollup_listenerRLrelayer/src/gateway/arbitrum/listener.rs 与 polling_listener.rs订阅 Gateway L2 的响应事件需要说明的是时序图中ethereum_listener/ethereum_host_l1_handlers是对 Host 侧组件在“本仓库 relayer”实现中的代号时序图本身把它们与arbitrum_gw_l2_handler、rollup_listener并列反映的是设计时的组件职责划分。一图读懂整个闭环时序图原文档核心内容此处完整保留并整理如下整个流程可以归纳为四个阶段请求进入L1 → relayerL1 上的合约发出 Decryption request 事件relayer 的 Host 监听器捕获并解码生成内部 request ID将(l1_req_id, contractCaller, selector)存入上下文转发网关relayer → L2relayer 组装交易提交到 Gateway L2 的 Decryption 合约从回执中提取public_decryption_id图中示例值0xAA并把(0xAA, 0x123)映射持久化响应返回L2 → relayerKMS 多方完成门限解密后将结果回帖到 L2L2 发出 Decryption Response 事件relayer 的 rollup 监听器收到事件反查read_uuid(0xAA) 0x123找到原始请求回调上链relayer → L1relayer 依据上下文中的contract_caller与selector在 L1 提交回调交易合约在链上读取明文并校验签名流程结束。注时序图中出现了 L1,L2 的Note over其本意是Ethereum L1与Arbitrum L2下文统一称为“L1 / L2”。二、事件类型体系relayer 内部的“事件总线”时序图里反复出现的relayerEvent:PubDecryptEventLogRcvdFromHostL1、DecryptRequestRcvd、DecryptionReqToGwL2Sent、DecryptResponseEventLogRcvdFromGwL2等在真实实现中统一收敛为一套带编号的事件枚举。relayer 采用事件驱动架构Orchestrator 作为中央协调者通过 TokioEventDispatcher 把事件分发给已注册的 Handler。事件枚举与编号源码 relayer/src/core/event.rs 定义了PublicDecryptEventId与GatewayChainEventId// PublicDecryptEventId —— Public Decrypt 流程的内部事件10~18 pub enum PublicDecryptEventId { ReqRcvdFromUser 10, // HTTP 收到公共解密请求 ReadinessCheckPassed 11, // 就绪检查通过 ReqSentToGw 12, // 已向 Gateway 发送请求 RespRcvdFromGw 13, // 从 Gateway 收到响应 RespSentToUser 15, // 已向用户返回响应 InternalFailure 16, ReadinessCheckTimedOut 17, ReadinessCheckFailed 18, } // GatewayChainEventId —— 来自 Gateway 链的事件50~54 pub enum GatewayChainEventId { UserDecryptionResponse 50, UserDecryptionResponseThresholdReached 51, PublicDecryptionResponse 52, // ← 公共解密响应事件 VerifyProofResponse 53, RejectProofResponse 54, }事件数据使用RelayerEventData枚举承载PublicDecrypt/UserDecrypt/InputProof/GatewayChain四类RelayerEvent则把job_id、api_version、timestamp与事件数据绑定为一个可分发单元。每次事件都带有稳定的job_id用于跨阶段关联同一笔请求。事件分发机制relayer/src/orchestrator/tokio_event_dispatcher.rs 实现了两级分发register_handler(event_ids, handler)Handler 按事件 ID 列表注册自己例如 public_decrypt_handler.rs 中GatewayHandler::new注册了ReqRcvdFromUser、ReqSentToGw、InternalFailure、ReadinessCheckPassed/TimedOut/Failed以及GatewayChainEventId::PublicDecryptionResponse共 7 个事件dispatch_event(event)按event.event_id()查订阅表为每个订阅的 Handler 派生一个tokio任务并行执行dispatch_event_and_wait则等待所有 Handler 完成用于需要同步确认的区块游标推进场景。这样设计的好处是监听器只负责“收日志、打包事件”Handler 只负责“消费事件、干具体活”两者通过事件解耦天然支持多 Handler 订阅同一事件例如响应事件同时被状态持久化、指标统计、HTTP 通知等多个消费者处理。三、请求阶段从 L1 事件到 Gateway 交易上链前3.1 Host L1 监听与事件解码时序图中L1-EL: Emit Decryption request Event与EL-EH: PubDecryptEventLogRcvdFromHostL1描述的是 Host 监听器捕获 L1 上 DApp 合约发出的解密请求事件。在实现上relayer/src/gateway/arbitrum/bindings.rs 定义了一张“网关事件签名表”fn gateway_chain_events() - [(FixedBytes32, IntoEvent); 5] { [ (Decryption::UserDecryptionResponse::SIGNATURE_HASH, ...), (Decryption::UserDecryptionResponseThresholdReached::SIGNATURE_HASH, ...), (Decryption::PublicDecryptionResponse::SIGNATURE_HASH, // ← 公共解密响应 |log, tx_hash| GatewayChainEventData::PublicDecryptionResponse { log, tx_hash }), (InputVerification::VerifyProofResponse::SIGNATURE_HASH, ...), (InputVerification::RejectProofResponse::SIGNATURE_HASH, ...), ] }监听器通过topic0与这张签名表匹配来决定事件归属record_and_dispatch见 arbitrum/listener.rs 与 polling_listener.rs负责把命中的日志连同tx_hash打包为RelayerEvent交给 Orchestrator 分发。关于“响应事件”Gateway 侧的PublicDecryptionResponse事件由 gateway-contracts/contracts/Decryption.sol 定义其publicDecryptionResponse函数在校验decryptionId合法、EIP-712 签名有效后记录已验证签名并触发该事件relayer 的GatewayHandler::process_decrypt_response用Decryption::PublicDecryptionResponse::decode_log_data(log.data())解码出decryptionId、decryptedResult、signatures、extraData。3.2 上下文数据存储时序图中Store (l1_req_id, contractCaller, selector)与Create new request ID 0x123描述的是relayer 在收到 L1 请求后把L1 请求 ID、回调合约地址contractCaller、回调函数选择器selector关联存储并生成一个新的内部请求 ID。在更细化的 decryption-flow-inside-relayer.plantuml 中这一步对应EthereumListener - EthereumListener: Generate Orchestrator Request ID以及EthereumHostL1Handler - EthereumHostL1Handler: Store to context data (Orchestrator Request ID, Callback selector, address)。plantuml 还强调了主题topic匹配逻辑只有 topic 匹配 Decryption Request 事件的日志才被解码处理否则直接忽略——这是事件过滤器filter在 Handler 层的体现。所谓“context data”在真实实现里是数据库持久化而非内存relayer 的 SQL 仓库relayer/src/store/sql/中的public_decrypt_repo等仓库负责把请求状态、gw_reference_id即时序图中的public_decryption_id/0xAA、回调信息等写入 PostgreSQL。这也是 relayer 重启后能从数据库与链游标chain cursor恢复未完成请求的基础。3.3 就绪检查readiness check与发送交易时序图中EH-AGH: DecryptRequestRcvd (ct_handles, operation_type)之后直接进入AGH-L2: Submit Transaction。真实实现中在真正上链之前还有一个就绪检查环节plantuml 与 chart 均未显式画出但源码确凿ReqRcvdFromUser事件触发 readiness_check_enqueue —— 把请求塞进PublicDecryptReadinessTask队列带信号量节流后台 PublicDecryptReadinessProcessor 消费队列调用ReadinessChecker检查所有密文句柄在 fhEVM 上已就绪、可解密结合 host/acl_checker.rs 的isAllowedForDecryption逐句柄 ACL 检查通过后派发ReadinessCheckPassed进入send_public_decrypt_request→send_to_gateway把ct_handles转成VecFixedBytes32用ComputeCalldata::public_decryption_req(handles, extra_data)生成 calldata构造GatewayTxTask交易类型TransactionType::PublicDecryptRequest推入交易节流队列tx_throttler。值得留意的是send_to_gateway中的队列满处理队列满时返回ProtocolOverload错误并提示 Relayer is full, retry later.而入口的 intake bouncer 会保持该场景不可达源码注释明确说明。四、交易确认与 decryption ID 提取时序图中Extract public_decryption_id 0xAA from receipt与Insert (public_decryption_id, original_event_request_id)/Insert (0xAA, 0x123)是请求—响应关联的关键一环relayer 必须以 Gateway 生成的public_decryption_id作为将来匹配响应的钥匙把它与内部 request ID0x123绑定。4.1 从回执中提取 gateway IDrelayer/src/gateway/arbitrum/transaction/helper.rs 的extract_gateway_id_from_receipt是通用提取器pub fn extract_gateway_id_from_receiptT: SolEvent( receipt: AnyTransactionReceipt, expected_signature: FixedBytes32, extract_id_fn: impl Fn(T) - U256, ) - ResultU256, EventProcessingError { for log in receipt.inner.logs() { if let Some(topic_0) log.topics().first() { if *topic_0 expected_signature { match T::decode_log_data(log.data()) { Ok(decoded_event) return Ok(extract_id_fn(decoded_event)), ... } } } } // 未找到目标事件 → ValidationFailed }在公共解密场景GatewayHandler的TxLifecycleHooks::on_receipt_received以Decryption::PublicDecryptionRequest_0为事件类型、以其SIGNATURE_HASH为签名、以|event| event.decryptionId为提取函数调用该工具拿到gw_reference_id后调用public_decrypt_repo.update_status_to_receipt_received_on_tx_success把tx_hash与gw_reference_id一并写入数据库。这正是时序图Insert (0xAA, 0x123)的实现落点。4.2 交易生命周期钩子TxLifecycleHooksGatewayHandler实现了TxLifecycleHookstrait同一文件内把交易生命周期与数据库状态机绑定钩子触发时机动作on_tx_in_flight交易即将广播状态置为tx_in_flight若被 epoch fence 拒绝则返回ClaimLost放弃本次发送on_receipt_received交易上链、收到回执提取gw_reference_id把tx_hashgw_reference_id落库on_failure交易失败revert 等提取 revert selector 并分类、记录指标更新状态为失败其中on_receipt_received的注释值得展开如果写入被拒rows_affected 0说明该行的tx_in_flight状态已被更新的 epoch 接管多 pod 场景下后继者抢占了归属此时gw_reference_id不会被写入——因为 Gateway 响应监听器正是靠它来匹配请求宁可让后继者重新驱动re-drive交易并记录自己的回执也不能把“半成功”状态误记为成功。4.3 Decryption 合约侧的 ID 生成Gateway 侧的 Decryption.sol 中publicDecryptionRequest函数会生成一个全局唯一的publicDecryptionId基于部署时初始化的计数器使得decryptionId首字节唯一并发出PublicDecryptionRequest(publicDecryptionId, ctHandles, extraData)事件对应的publicDecryptionResponse(decryptionId, ...)会校验decryptionId必须落在(PUBLIC_DECRYPT_COUNTER_BASE, publicDecryptionCounter]区间内防止伪造未请求过的解密 ID。这些约束保证了 relayer 在回执中提取到的decryptionId是可信的。五、响应阶段L2 事件回传与请求关联5.1 rollup 监听器收到响应事件时序图L2-RL: Emit Decryption Response Event描述 KMS 完成解密后L2 上发出响应事件。在更细化的 plantuml 中这一阶段被标注为Wait until request is picked up by k KMS Parties (threshold defined in Decryption Manager), processed and result is posted back.即Gateway 的 Decryption Manager 定义了门限k需要至少k个 KMS 参与方各自解密并提交后达成共识结果才会上链对应源码 Decryption.sol 中的verifiedPublicDecryptSignatures、decryptionConsensusDigest等状态以及publicDecryptionResponse中按(decryptionId, digest)聚合签名、达到门限才触发共识事件的设计。plantuml 还画出了一个超时分支Result not available within timeout — Yet to define how this should be handled. Maybe do nothing and Ethereum sends timed out error to user.即超时处理在文档写作时尚未定案可能的方案是 L1 侧直接向用户返回超时错误。这是文档中明确标注的“未决设计点”不是已实现行为。5.2 反查请求 IDread_uuid(0xAA) 0x123时序图Retrieve public_decryption_id (0xAA)→Read associated event request id, read_uuid(0xAA) 0x123描述的是响应与请求的关联correlation以事件中的public_decryption_id0xAA为键反查出最初生成的内部 request ID0x123。真实实现对应GatewayHandler::process_decrypt_responserelayer/src/gateway/public_decrypt_handler.rs解码PublicDecryptionResponse事件得到decryptionId、decryptedResult、signatures、extraData组装成PublicDecryptResponse调用public_decrypt_repo.complete_req_with_res(public_decryption_id, decrypt_response, tx_hash)以public_decryption_id为键更新数据库并把明文与签名写入根据更新结果分派Completed { int_job_id }→ 用拿到的job_id派发RespRcvdFromGw事件通知等待中的 HTTP handler 取结果AlreadyCompleted→ 重复事件跳过幂等AlreadyInFinalState→ 已在失败/超时等终态跳过NotFound→ 响应事件先于gw_reference_id落库到达高 RPC 延迟下的竞态进入带延迟的重试循环。5.3 竞态处理GwEventNotFound 重试NotFound分支的实现是当前代码中的一个重要工程细节源码注释明确标注TEMPORARY FIX配置项来自GwEventNotFoundRetryConfig见 relayer/src/config/settings.rs 附近包含max_retries与retry_delay_ms每次失败后tokio::time::sleep(retry_delay_ms)再重试complete_req_with_res达到最大重试次数仍NotFound时递增unmatched_gateway_event(public_decryption_response)指标并记录日志后放弃注释明确最终应以事件缓冲event buffering方案替换该临时重试方案。这一段与时序图中Insert (0xAA, 0x123)的时序紧密相关正因为 ID 映射写入与响应事件到达之间存在竞态窗口才需要此重试机制兜底。六、回调阶段在 L1 上执行合约回调6.1 上下文恢复与回调交易时序图Retrieve from contextual data → req.contract_caller, req.selector → Submit callback transaction to contract caller描述 relayer 在拿到明文与签名后从上下文取出请求时保存的回调合约地址contractCaller与回调选择器selector在 L1 上构造并提交回调交易。plantuml 补充了两个分支Transaction Succeededrelayer 派发DecryptResponseSentToHostL1事件L1 合约内部处理回调读取明文、校验签名Transaction failedrelayer 派发DecryptionFailed事件。6.2 响应数据与事件派发响应数据本身由PublicDecryptResponse结构体承载relayer/src/core/event.rspub struct PublicDecryptResponse { pub gateway_request_id: U256, // 即 public_decryption_id / 0xAA pub decrypted_value: Bytes, // 解密出的明文 pub signatures: VecBytes, // KMS 门限签名集合 pub extra_data: String, // 原样透传的附加数据 }process_decrypt_response成功关联请求后会以RespRcvdFromGw事件通知 HTTP 侧HTTP handlerrelayer/src/http/endpoints/v2/handlers/public_decrypt.rs 中的GET /v2/public-decrypt/{job_id}即可从数据库读取结果返回给调用方。6.3 流程终点链上读明文、验签名时序图最后Read plaintext and check signatures描述 L1 合约侧的动作回调交易在合约上下文里执行合约读取明文并校验 KMS 签名阈值签名集合校验通过后明文即被视为可信并可用于合约逻辑。至此Note over L1,L2: End of Flow一次公共解密闭环完成。七、状态机视角decryption_flow_chart.md 详解同目录下的 decryption_flow_chart.md 从 relayer 内部状态机视角复述了同一链路与本文第一、三、五章互为印证这张流程图把时序图未展开的两个内部细节补全了句柄转换Convert handles to Uint256—— 请求进入时ct_handles会被转换为Uint256形式再组装 calldata与源码中ComputeCalldata::public_decryption_req接收VecFixedBytes32的处理对应人工延迟Artificial delay—— 响应处理阶段存在一个有意的人为延迟用于等待decryption_id → request_id映射落库与 5.3 节竞态重试的设计意图一致属于文档层面记录的工程折中查找失败即记日志Found Request ID? → No → Log Error—— 映射缺失时当前流程图设计为仅记录错误不做其他处理。该流程图中出现的事件名DecryptRequestRcvd、DecryptResponseEventLog、DecryptionRequestSent与源码枚举存在命名演进差异但其语义与PublicDecryptEventId/GatewayChainEventId完全对应详见第二章。八、关键源码路径速查表为便于读者在仓库中快速定位汇总本文涉及的核心文件关注点路径设计文档时序图 / 流程图 / PlantUMLrelayer/design-docs/decryption-flow/、relayer/design-docs/decryption-flow-inside-relayer.plantuml事件枚举与事件数据定义relayer/src/core/event.rs事件分发Orchestrator / Dispatcherrelayer/src/orchestrator/tokio_event_dispatcher.rs、relayer/src/orchestrator/orchestrator.rs公共解密 Gateway Handlerrelayer/src/gateway/public_decrypt_handler.rs网关事件签名表与解码relayer/src/gateway/arbitrum/bindings.rsGateway L2 监听器WSS / 轮询relayer/src/gateway/arbitrum/listener.rs、relayer/src/gateway/arbitrum/polling_listener.rs回执 gateway ID 提取relayer/src/gateway/arbitrum/transaction/helper.rs就绪检查处理器relayer/src/readiness/public_decrypt_processor.rs、relayer/src/host/acl_checker.rsHTTP v2 公共解密端点relayer/src/http/endpoints/v2/handlers/public_decrypt.rsSQL 仓库与状态模型relayer/src/store/sql/含public_decrypt_repo、public_decrypt_req_modelGateway Decryption 合约gateway-contracts/contracts/Decryption.solRelayer 架构总览relayer/README.md九、工程要点与设计权衡小结把时序图、流程图、plantuml 与源码对照后可以提炼出这条解密链路几个值得借鉴的工程要点以 ID 为中心的双向关联请求方向用内部request_id0x123串起 L1 请求与 Gateway 交易响应方向用public_decryption_id0xAA反查request_id。(0xAA, 0x123)映射是整条链路的“关节”落库时机与事件到达时序之间的竞态由重试机制兜底。事件驱动 订阅分发监听器与业务 Handler 完全解耦topic0签名表统一了“该听什么”的规则注册机制决定了“谁来处理”天然支持幂等与多消费者。数据库即上下文所谓 context data 全部持久化到 PostgreSQL配合 epoch fence写入被拒即视为归属易主支持多 pod 高可用与重启恢复relayer/src/store/sql/repositories/public_decrypt_repo.rs中的update_status_to_*系列方法即状态机跃迁的具体执行者。事务生命周期钩子化交易发送、回执、失败通过TxLifecycleHooks三个钩子与状态机绑定失败时提取 revert selector 并归类便于监控与告警。未决设计点响应超时KMS 未在时限内回帖的处理在 decryption-flow-inside-relayer.plantuml 中明确标注为 Yet to define可能的方案是 L1 向用户返回超时错误而 Gateway 侧的门限共识行为k个 KMS 参与方由 Decryption Manager 与 Decryption.sol 的门限校验逻辑决定。理解这些标注有助于区分“已实现行为”与“设计中行为”避免把设计草案当成品。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
