企业官网建设流程全解析

fhEVM Gateway API 详解：keyurl、密文证明验证与重加密的完整接口规范

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

fhEVM（Fully Homomorphic Encryption EVM）在将链上数据保持加密状态的同时，仍能支持合约逻辑计算，而 Gateway（网关）正是连接 dApp、FHEVM 网络与 TKMS（Threshold 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格式，这是一种便于跨语言、跨平台安全传输的确定性序列化方案。

端点总览

三个端点均返回统一的{"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，用于生成输入证明 proof）；
• bootstrap key（FHE 计算所需的重线性化密钥）；
• 每个运行 TKMS 的 MPC 服务器的地址与签名验证公钥。

除验证公钥与地址之外，每个文件都附带一份多签签名列表，以保障下载内容的完整性与真实性。

响应结构（200 OK）

响应体由status与response两部分组成，response包含三个字段：

crs：CRS 信息映射

以「该 CRS 能支持的证明最大比特数」为 key 的映射，value 包含：

fhe_key_info：FHE 密钥集信息列表

每个元素描述系统中的一个密钥集，包含两个对象：

• fhe_public_key：FHE 密钥集的加密公钥。字段包括data_id（20 字节小写 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 服务器的签名公钥（服务器用于给请求签名的密钥），每个元素包含：

完整响应示例

{ "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.rs：KeyUrlHandler通过tokio::sync::watch通道持有最新响应，请求到达时直接borrow()当前值返回 200；
• 响应类型定义见 relayer/src/http/endpoints/v2/types/keyurl.rs：KeyUrlResponseJson使用#[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_ms）；
• source: 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_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed", "caller_address": "0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb", "crs_id": "d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906", "key_id": "408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "ct_proof": "cdff..." }

响应结构（200 OK）

响应示例：

{ "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.rs：InputProofHandler通过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": "15a4f9a8eb61459cfba7d103d8f911fb04ce91ecf841b34c49c0d56a70b896d20cbc31986188f91efc3842b7df215cee8acb40178daedb8b63d0ba5d199bce121c", "client_address": "0x17853A630aAe15AED549B2B874de08B73C0F59c5", "enc_key": "2000000000000000df2fcacb774f03187f3802a27259f45c06d33cefa68d9c53426b15ad531aa822", "ciphertext_handle": "0748b542afe2353c86cb707e3d21044b0be1fd18efc7cbaa6a415af055bfb358", "eip712_verifying_contract": "0x66f9664f97F2b50F62D13eA064982f936dE76657" }

响应结构（200 OK）

response为每个 TKMS 服务器响应的列表，每个元素包含：

响应示例：

{ "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）保证服务稳定性。

错误响应规范

三个端点共享同一套错误码：

错误响应统一采用如下 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 的关键流程可归纳为：

1. 启动引导：调用GET /keyurl获取 CRS、FHE 公钥、server key 与 TKMS 验证公钥；校验各文件签名超过 1/3 阈值后下载safe_serialization材料；
2. 加密输入：使用fhe_public_key与选定param_choice加密明文，使用 CRS 生成零知识证明，构造ProvenCompactCiphertextList；调用POST /verify_proven_ct提交，验证返回的kms_signatures后取得handles，再以 handle 在链上合约中完成输入提交；
3. 私密读取：对敏感数据调用POST /reencrypt，传入用户签名、libsodium 公钥与密文句柄，收集超过 1/3 的 signcryption 份额后在本地用私钥解密。

始终注意：listener_type（FHEVM_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