fhEVM Gateway API 详解keyurl、密文证明验证与重加密的完整接口规范【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevmfhEVMFully Homomorphic Encryption EVM在将链上数据保持加密状态的同时仍能支持合约逻辑计算而 Gateway网关正是连接 dApp、FHEVM 网络与 TKMSThreshold Key Management System阈值密钥管理系统的桥梁。本文基于仓库中 Gateway API 规范文档系统讲解 Gateway 暴露的三大核心端点——GET /keyurl密钥与 CRS 分发、POST /verify_proven_ct批量验证带证明的密文、POST /reencrypt在用户私钥下解密包括请求/响应字段、EIP-712 多签校验模型、阈值恢复机制与错误码并结合 relayer 网关服务的源码实现给出底层证据。读完本文你将能够理解并实现一个与 fhEVM Gateway 正确交互的客户端掌握密文输入、私密解密与密钥分发三类关键交互的完整协议细节。Gateway 在 fhEVM 架构中的角色在 fhEVM 生态中Gateway 承担 Oracle 与流量网关双重职责它监听链上事件、为密文生成存储证明、向 TKMS 转发解密/重加密请求并将 TKMS 返回的阈值签名结果回传给调用方。仓库中的 relayer 即是一套完整的 Gateway 参考实现其 HTTP 层位于 relayer/src/http采用 axum 框架构建并通过/v2/前缀暴露与本文档对应的能力如/v2/keyurl。本文档描述的端点即为该服务对外暴露的 API 契约。文档定义的所有签名类字段均为EIP-712 类型化签名用于绑定请求/响应内容与调用上下文所有序列化数据均采用 TFHE-RS 的safe_serialization格式这是一种便于跨语言、跨平台安全传输的确定性序列化方案。端点总览方法路径用途GET/keyurl获取系统内公钥、CRS、bootstrap key 以及各 TKMS MPC 节点的签名公钥与地址下载链接POST/verify_proven_ct批量提交带零知识证明的密文由 TKMS 验证并签名POST/reencrypt将 FHE 密文在用户临时公钥下解密密文私密解密客户端可用私钥本地解密三个端点均返回统一的{status: ..., response: ...}包装结构。多签与阈值安全模型贯穿三端点的核心机制在详细讲解每个端点之前必须先理解贯穿整个 API 的阈值多签模型TKMS 由 n 个 MPC 服务器构成每个服务器持有私钥份额对于密钥文件、验证结果等关键内容每个 MPC 节点都会生成一个 EIP-712 签名客户端验证时无需全部签名只要收集到超过总数 1/3即 n/3的有效签名即可认为内容合法——这是 Shamir 秘密共享与阈值密码学的直接体现重加密响应的恢复同理每个服务器返回自己份额的 signcryption签名加密客户端只需超过 1/3 的份额即可重构出最终明文结果前提是这些份额都通过了签名校验。这一模型意味着只要恶意合谋的服务器数量不超过 1/3系统的机密性和完整性就得以保持同时客户端对单点故障具有天然容忍度。GET /keyurl获取 FHE 密钥与 CRS 分发信息端点语义GET /keyurl无需任何查询参数和请求头——Gateway 在部署时已为特定区块链预配置完成。其返回的 JSON 中包含指向 S3 bucket 的下载 URL客户端据此获取区块链公钥用于加密输入CRS 文件Common Reference String用于生成输入证明 proofbootstrap keyFHE 计算所需的重线性化密钥每个运行 TKMS 的 MPC 服务器的地址与签名验证公钥。除验证公钥与地址之外每个文件都附带一份多签签名列表以保障下载内容的完整性与真实性。响应结构200 OK响应体由status与response两部分组成response包含三个字段crsCRS 信息映射以「该 CRS 能支持的证明最大比特数」为 key 的映射value 包含字段说明data_id20 字节小写hex 编码的 CRS 句柄/IDparam_choice整数表示与该 CRS 配合使用的公钥参数选择signatures每个 MPC 节点对PublicParamBls12_446的safe_serialization的 EIP-712 签名列表urls可下载数据的 URL 列表端点数据为PublicParamBls12_446的safe_serializationfhe_key_infoFHE 密钥集信息列表每个元素描述系统中的一个密钥集包含两个对象fhe_public_keyFHE 密钥集的加密公钥。字段包括data_id20 字节小写 hex、param_choice生成密钥所用参数选择、signatures对CompactPublicKey的safe_serialization的 EIP-712 签名列表、urls数据端点为CompactPublicKey序列化。fhe_server_key服务端密钥用于对密文执行 FHE 运算。字段结构同fhe_public_key但urls数据端点为ServerKey序列化。verf_public_key已弃用Deprecated该字段将被移除应改为直接从 TKMS 区块链上的配置合约获取。该列表描述每个 TKMS MPC 服务器的签名公钥服务器用于给请求签名的密钥每个元素包含字段说明key_id20 字节小写 hex 的密钥 ID签名密钥当前为固定值408d8cbaa51dece7f782fe04ba0b1c1d017b1088server_id服务器整数 ID范围 [1; n]n 为 MPC 服务器数量verf_public_key_url服务器上签名密钥序列化PublicSigKey的safe_serialization的下载端点verf_public_key_address服务器签名密钥对应人类可读 Ethereum 地址文件的下载端点完整响应示例{ response: { crs: { 256: { data_id: d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906, param_choice: 1, signatures: [ 0d13..., 4250..., a42c..., fhb5... ], urls: [ https://s3.amazonaws.com/bucket-name-1/PUB-p1/CRS/d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906, https://s3.amazonaws.com/bucket-name-4/PUB-p4/CRS/d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906 ] } }, fhe_key_info: [ { fhe_public_key: { data_id: 408d8cbaa51dece7f782fe04ba0b1c1d017b1088, param_choice: 1, signatures: [cdff..., 123c..., 00ff..., a367...], urls: [ https://s3.amazonaws.com/bucket-name-1/PUB-p1/PublicKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088 ] }, fhe_server_key: { data_id: 408d8cbaa51dece7f782fe04ba0b1c1d017b1088, param_choice: 1, signatures: [839b..., baef..., 55cc..., 81a4...], urls: [ https://s3.amazonaws.com/bucket-name-1/PUB-p1/ServerKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088 ] } } ], verf_public_key: [ { key_id: 408d8cbaa51dece7f782fe04ba0b1c1d017b1088, server_id: 1, verf_public_key_address: https://s3.amazonaws.com/bucket-name-1/PUB-p1/VerfAddress/408d8cbaa51dece7f782fe04ba0b1c1d017b1088, verf_public_key_url: https://s3.amazonaws.com/bucket-name-1/PUB-p1/VerfKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088 } ] }, status: success }注意示例中多个 MPC 服务器server_id 1~4各自托管在不同 bucket体现了「密钥材料分散存储 多签背书」的设计。源码层面的实现佐证relayer 网关以/v2/keyurl暴露该能力处理函数见 relayer/src/http/endpoints/v2/handlers/keyurl.rsKeyUrlHandler通过tokio::sync::watch通道持有最新响应请求到达时直接borrow()当前值返回 200响应类型定义见 relayer/src/http/endpoints/v2/types/keyurl.rsKeyUrlResponseJson使用#[serde(rename_all camelCase)]输出 camelCase JSON与文档字段命名一致如fhe_key_info、data_id其中常量CRS_PARAM_SIZE_KEY 2048表明当前实现固定使用 2048 比特参数规模的 CRS。该端点支持两种数据来源配置见 relayer/src/config/settings.rs 的keyurl配置块source: chain通过轮询 host 链上的 KMS 生成合约KMSGeneration保持/keyurl数据同步需配置kms_generation_address与poll_interval_mssource: config直接从静态配置读取公钥与 CRS 数据不运行链上轮询器。因此客户端每次启动时都应先调用/keyurl获取当前生效的密钥材料并校验签名数量超过总数 1/3后再下载使用。POST /verify_proven_ct批量验证带证明的密文输入端点语义该端点用于向 TKMS 提交一批带零知识证明的密文即用户在链下加密并证明其知晓明文且密文在期望公钥下生成。TKMS 验证通过后返回各服务器的签名同时返回元信息以区分响应属于co-processor协处理器模式还是FHEVM native原生模式co-processor 模式下响应额外包含密文存储句柄以及协处理器对正确存储的背书签名FHEVM native 模式下proof_of_storage为空字符串。与/keyurl相同TKMS 返回的签名按阈值多签处理只需超过 1/3 的签名即可验证内容合法。请求体JSON参数说明contract_addressEIP-55 编码含0x前缀的目标合约地址密文将提交至该合约caller_addressEIP-55 编码含0x前缀的输入提供者用户地址crs_id20 字节小写 hex 的 CRS 句柄标识生成证明所用 CRSkey_id20 字节小写 hex 的公钥句柄标识加密该密文所用的公钥ct_proof带证明密文的序列化 hex 编码即 TFHE-RS 对象ProvenCompactCiphertextList的safe_serialization请求示例{ contract_address: 0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed, caller_address: 0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb, crs_id: d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906, key_id: 408d8cbaa51dece7f782fe04ba0b1c1d017b1088, ct_proof: cdff... }响应结构200 OK字段说明handles每个被证明知晓的密文的句柄向量句柄为 32 字节小写 hex IDkms_signatures每个响应 TKMS 服务器对ProvenCompactCiphertextList的safe_serialization的 EIP-712 签名列表listener_type枚举FHEVM_NATIVE原生模式或COPROCESSOR协处理器模式proof_of_storage可选的协处理器存储证明签名native 模式为空字符串否则为对请求的 EIP-712 签名 hex 编码响应示例{ response: { handles: [ 0748b542afe2353c86cb707e3d21044b0be1fd18efc7cbaa6a415af055bfb358, 054ab4515b1541878723431005054f154e15e45e15800adb67879679df670456 ], kms_signatures: [ 15a4f9a8eb61459cfba7d103d8f911fb04ce91ecf841b34c49c0d56a70b896d20cbc31986188f91efc3842b7df215cee8acb40178daedb8b63d0ba5d199bce121c, 118165165165423465234414c4c468a4d9684d8e18186d6f786161b4b436c58787cc68418186d6f786161b4b98461166a6a6668e8e118542c154867aab238abd79 ], listener_type: COPROCESSOR, proof_of_storage: 17acd15648740c00849f489498489e4600a60a06068d484b084894988333000cff798751651498d68768753567a4356787c45787e79i8f64d128218927897c8789 }, status: success }handles是客户端后续在链上操作密文如传给 FHEVM 合约执行计算时使用的标识符因此该端点是链下加密输入上链的前置验证步骤。源码层面的实现佐证relayer 网关对应实现为POST /v2/input-proof见 relayer/src/http/endpoints/v2/handlers/input_proof.rsInputProofHandler通过Orchestrator编排证明验证流程将请求持久化到InputProofRepository并接入TxThrottlingSender交易节流器与RetryAfterState排队状态——这体现了 Gateway 在输入洪峰下的背压处理。请求类型InputProofRequestJson与响应类型定义于 relayer/src/http/endpoints/v2/types/input_proof.rs。POST /reencrypt在客户端私钥下私密解密端点语义/reencrypt实现重加密TKMS 对 FHE 密文执行不经意解密得到明文的秘密份额每个服务器将各自份额用客户端提供的临时公钥进行 signcryption签名 加密客户端收集超过 1/3 的响应后用自己的私钥即可本地恢复明文——第三方全程无法看到明文这适用于个人敏感数据的读取区别于公开解密。相关流程说明在 reencryption 文档 中客户端侧流程为dApp 从 view 函数如balanceOf取回密文 → 为用户生成密钥对并让用户对公钥签名 → 调用 Gateway 提交密文、公钥、用户地址、合约地址与签名 → 用私钥解密返回值。与之相对decryption 文档 强调公开解密是所有人可见的敏感数据必须走重加密路径。请求体JSON参数说明signature对加密公钥enc_key的 EIP-712 签名小写 hex绑定用户授权client_addressEIP-55 编码含0x前缀的最终用户地址enc_key重加密结果应签密到的目标公钥libsodium 格式小写 hexciphertext_handle32 字节小写 hex 的密文句柄Gateway 据此取回密文eip712_verifying_contractEIP-55 编码含0x前缀的持有该密文的合约地址用于 EIP-712 域校验请求示例{ signature: 15a4f9a8eb61459cfba7d103d8f911fb04ce91ecf841b34c49c0d56a70b896d20cbc31986188f91efc3842b7df215cee8acb40178daedb8b63d0ba5d199bce121c, client_address: 0x17853A630aAe15AED549B2B874de08B73C0F59c5, enc_key: 2000000000000000df2fcacb774f03187f3802a27259f45c06d33cefa68d9c53426b15ad531aa822, ciphertext_handle: 0748b542afe2353c86cb707e3d21044b0be1fd18efc7cbaa6a415af055bfb358, eip712_verifying_contract: 0x66f9664f97F2b50F62D13eA064982f936dE76657 }响应结构200 OKresponse为每个 TKMS 服务器响应的列表每个元素包含字段说明payload单个服务器的 signcryption 的 bincode 编码附带元信息服务器 ID、阈值参数、加密值类型、该服务器的公钥signature小写 hex 编码的 EIP-712 签名响应示例{ response: [ { payload: 161c5..., signature: 15a4f9a8eb61459cfba7d103d8f911fb04ce91ecf841b34c49c0d56a70b896d20cbc31986188f91efc3842b7df215cee8acb40178daedb8b63d0ba5d199bce121c }, { payload: 44546..., signature: 118165165165423465234414c4c468a4d9684d8e18186d6f786161b4b436c58787cc68418186d6f786161b4b98461166a6a6668e8e118542c154867aab238abd79 } ], status: success }由于 payload 基于秘密共享客户端只需超过总数 1/3 的响应即可重构结果假设所有返回的 signcryption 均正确。源码层面的实现佐证relayer 网关对应实现为POST /v2/user-decrypt与POST /v3/user-decrypt处理函数见 relayer/src/http/endpoints/v2/handlers/user_decrypt.rs 与 relayer/src/http/endpoints/v3/handlers/user_decrypt.rs底层由 relayer/src/gateway/user_decrypt_handler.rs 驱动并配合ciphertext_checker密文可解密性检查与节流器throttlers.rs保证服务稳定性。错误响应规范三个端点共享同一套错误码状态码错误码说明400BadRequest请求无效或缺少必要参数404NotFound请求的资源不存在500ServerError网关内部服务器错误错误响应统一采用如下 JSON 结构{ error: BadRequest, message: The request is invalid or missing required parameters. }{ error: NotFound, message: The requested resource was not found. }{ error: ServerError, message: An internal server error occurred. Please try again later. }客户端应根据 400/404 直接修复请求参数对 500 采取重试或降级策略。relayer 的错误类型定义见 relayer/src/http/endpoints/v2/types/error.rs。实战要点总结围绕这三个端点客户端接入 fhEVM Gateway 的关键流程可归纳为启动引导调用GET /keyurl获取 CRS、FHE 公钥、server key 与 TKMS 验证公钥校验各文件签名超过 1/3 阈值后下载safe_serialization材料加密输入使用fhe_public_key与选定param_choice加密明文使用 CRS 生成零知识证明构造ProvenCompactCiphertextList调用POST /verify_proven_ct提交验证返回的kms_signatures后取得handles再以 handle 在链上合约中完成输入提交私密读取对敏感数据调用POST /reencrypt传入用户签名、libsodium 公钥与密文句柄收集超过 1/3 的 signcryption 份额后在本地用私钥解密。始终注意listener_typeFHEVM_NATIVEvsCOPROCESSOR会改变verify_proven_ct响应中proof_of_storage的语义verf_public_key已弃用应改从 TKMS 区块链上的配置合约读取 MPC 节点签名公钥所有涉及签名的校验都应遵循「 总数 1/3 的签名即有效」的阈值规则这也是 fhEVM 去中心化信任模型在 API 层的直接体现。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考