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），僅供參考