FHEVM 全栈实战指南掌握 fhevm-sdk CLI 的加密输入、公开解密与用户解密全流程【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm导读fhevm-sdk是 fhEVMFully Homomorphic Encryption Virtual Machine生态提供的命令行工具它把fhevm/sdk的 viem 流程封装成可直接执行的 CLI 命令围绕FHETest合约覆盖了加密输入与输入证明生成、公开解密、用户解密、委托用户解密、FHETest 状态初始化和 ERC-7984 机密代币转账等核心场景。阅读本文后你将能完成从环境配置、首次冒烟测试到在任意合约 handle 上执行解密、校验 relayer 解密响应、运行机密代币转账的完整实战闭环并理解每条命令背后的源码实现与数据流。本文基于 sdk/cli-js-sdk/README.md 编写所有命令、参数与地址均以当前仓库为准。项目概览pnpm workspace 的三层结构cli-fhevm-sdk是一个 pnpm workspace位于 sdk/cli-js-sdk 目录由三个包组成职责边界非常清晰包职责特点packages/toolkit可导入的库层封装fhevm/sdk网络配置、加密、解密流程、FHETest 辅助函数不依赖任何 CLI 代码可被其他程序直接复用packages/clifhevm-sdkcommander 命令行本体通过workspace:*依赖 toolkitpackages/load-test私有 relayer 压测应用包含验证场景、持久化句柄池、收集器、报告与显式基线不是 SDK 库也不是发布包这种toolkit 纯逻辑、cli 薄壳的分层设计从 packages/toolkit/src/flows 的目录结构可以看得很清楚input-proof.ts、public-decrypt/、user-decrypt/、delegated-user-decrypt/、fhe-test/、token/各自独立成模块而 CLI 侧的 packages/cli/src/cli/commands 仅做参数解析与结果输出真正的业务逻辑全部下沉到 toolkit。从源码结构看CLI 的核心设计原则是进度日志走 stderr最终结果以 JSON 输出到 stdout因此所有命令都可以通过管道pipe串联使用例如把token balance的结果直接喂给user-decrypt。快速开始安装、构建与全局链接安装依赖与构建仓库根目录sdk/cli-js-sdk执行pnpm install cp .env.example .env pnpm run buildpnpm run build使用tsdown将 TypeScript CLI 编译到packages/cli/dist/随后全局链接cd packages/cli pnpm add -g . fhevm-sdk --help全局链接后fhevm-sdk这个可执行文件实际运行的就是编译产物。如果不想全局链接可用以下等价命令替换pnpm --silent run cli开发调试场景下希望免构建直接跑源码则使用pnpm --silent run cli:dev若日后需要移除全局链接执行pnpm remove --global cli-fhevm-sdk环境变量的自动加载机制一个容易被忽略但很实用的设计仓库根目录的.env会被自动加载即使你在其他目录运行 CLI 也能读到。实现位于 packages/cli/src/env.ts它通过fileURLToPath(new URL(../../../.env, import.meta.url))从编译入口向上回溯到 workspace 根目录因此从源码src/env.ts和编译产物dist/index.mjs解析出的路径完全一致。变量优先级从低到高为.env文件中的值当前 shell 环境变量覆盖.env显式的凭据参数如--private-key优先级最高首次冒烟测试RPC 与钱包环境就绪后这四条命令是很好的自检序列fhevm-sdk fhe-test info fhevm-sdk input-proof --type uint64 --value 42 fhevm-sdk fhe-test init --type uint32 fhevm-sdk public-decrypt fresh --type uint8 fhevm-sdk user-decrypt fresh --type uint16需要特别说明的是-n devnet、--rpc-url、--relayer-url等全局选项可以放在子命令之前或之后两种写法等价。其实现依据在 packages/cli/src/cli/options.tscommander 通过command.optsWithGlobals()从当前 action 上下文读取继承的全局选项network缺省时取DEFAULT_NETWORK即testnet。命令全景图CLI 的全部能力可以浓缩为下表Needs wallet? 列表示该命令是否依赖钱包私钥/助记词命令功能需要钱包input-proof加密明文值并请求经过验证的输入证明不写 FHETest否public-decrypt direct直接公开解密任意合约中已有的--handle--contract指定 ACL 配对合约默认 FHETest仅当配对合约需要 caller 时public-decrypt fresh加密一个值以makePublictrue存入 FHETest再公开解密是public-decrypt stored公开解密显式--account/--type槽位中的 FHETest handle或钱包默认槽位仅使用钱包默认槽位时public-decrypt make-public把调用者已存储的 FHETest handle 标记为公开再公开解密是user-decrypt direct用户解密任意合约中已有的--handle--contract指定 ACL 配对合约默认 FHETest是user-decrypt fresh加密一个值以makePublicfalse存入 FHETest再以所有者身份解密是user-decrypt stored用户解密调用者在 FHETest 中各--type槽位的 handle是delegated-user-decrypt direct委托解密任意合约中已有的--handle--contract指定 ACL 配对合约默认 FHETest需要委托方仅在创建 ACL 权限时需要被委托方delegated-user-decrypt fresh被委托方创建私有 handle委托方获得 ACL 权限并解密委托方与被委托方都需要delegated-user-decrypt stored委托方解密被委托方在 FHETest 中各--type槽位的 handle需要委托方仅在创建 ACL 权限时需要被委托方verify-user-decrypt用保存的验证产物artifact解密并比对 relayer 的 user-decrypt GET 响应GET URL 从产物推导无钱包但需要 RPCfhe-test info显示解析后的网络、宿主链、relayer 与 FHETest 元数据否fhe-test inspect读取 FHETest 状态裸 handle、显式 account/type 槽位或钱包默认 account/type 槽位仅使用钱包默认槽位时fhe-test init为一个、多个或全部受支持类型创建公开 FHETest handle是fhe-test op operation对调用者已存储的 handle 运行 FHETest 运算演示是token transfer加密金额并执行 ERC-7984 机密转账--from走confidentialTransferFrom--verify解密转账前后发送方余额以确认转账是token balance读取钱包或显式账户的机密 ERC-7984 余额 handle仅使用钱包默认账户时completion install/completion uninstall安装/卸载 shell 补全否任何命令都可以用--help查看精确选项fhevm-sdk public-decrypt stored --help fhevm-sdk delegated-user-decrypt fresh --help fhevm-sdk fhe-test op --help网络与全局选项六个预置网络CLI 内置六个网络通过-n, --network选择默认是testnet网络宿主链FHETest 地址relayer 配置testnetEthereum Sepolia0x94B9d3aF050687D1F76251aD7D09a1F216a19845测试网 relayer默认testnet-amoyPolygon Amoy0xa66bCEd74D1Df0736d0eb8E52371b1b1AAA1F0F0测试网 relayerdevnetEthereum Sepolia0xf56a7990E63a63eC75aD9Aa07De8cB6bF7baa805devnet relayerdevnet-amoyPolygon Amoy0x7553CB9124f974Ee475E5cE45482F90d5B6076BCdevnet relayermainnetEthereum Mainnet0xba4d707745689eD409d4Afac8722224f5FD78C63mainnet relayerpolygonPolygon PoS0xFb10eda9e9b4f3f7dd928B6F32fBB94E2a20451dmainnet relayer这些配置在源码中有完整定义见 packages/toolkit/src/config/networks.ts每个网络都包含fhevmChainfhevm/sdk/chains定义与hostChainviem 定义的双链映射devnet 系列还通过defineFhevmChain单独声明了 ACL、inputVerifier、kmsVerifier、protocolConfig、gatewaydecryption / inputVerification等全套合约地址。全局选项选项含义-n, --network testnet选择预置网络见上表--rpc-url url宿主链 RPC 覆盖--relayer-url urlrelayer 基础 URL 覆盖localhost:3000会被规范化为http://localhost:3000--contract addressFHETest 合约地址覆盖注意这是命令级选项不是全局选项值得展开的是 RPC 与 relayer 的解析顺序源码 packages/toolkit/src/config/resolve.ts 明确给出了三层回退RPC--rpc-url→ 网络对应环境变量 → 公共兜底 RPChttps://sepolia.drpc.org、https://eth.drpc.org、https://polygon.drpc.org、https://polygon-amoy.drpc.orgRelayernormalizeRelayerUrl会把localhost:3000自动补上http://前缀并剥离/v1、/v2后缀——因为 SDK 期望的是 relayer origin 而不是带版本号的路径。受支持的 FHETest 值类型CLI 完整支持以下 8 种加密类型bool、uint8、uint16、uint32、uint64、uint128、uint256、address。定义在 packages/toolkit/src/types.ts 的FHE_VALUE_TYPES同时FHE_TYPE_IDS记录了与 FHETest 合约一致的数值类型 IDbool0、uint82、uint163、uint324、uint645、uint1286、address7、uint2568这些 ID 会被嵌入 handle 的最后一个字节——这也是 FHETest 合约_setHandleOf里require(_typeOf(handle) fheType, FheType mismatch)校验的依据见 FHETest.sol。环境变量速查表变量用途MAINNET_RPC_URLmainnet网络的 RPCPOLYGON_RPC_URLpolygon网络的 RPCSEPOLIA_RPC_URLtestnet与devnet网络的 RPCPOLYGON_AMOY_RPC_URLtestnet-amoy与devnet-amoy网络的 RPCZAMA_FHEVM_API_KEYSDK relayer 鉴权目标环境要求 API key 时可选PRIVATE_KEY默认钱包私钥交易类命令、用户解密、委托解密作为委托方都会用到MNEMONIC未设置PRIVATE_KEY时的默认钱包助记词DELEGATOR_PRIVATE_KEY委托解密流程中加密数据所有者的私钥DELEGATOR_MNEMONIC未设置DELEGATOR_PRIVATE_KEY时的数据所有者助记词完整示例见仓库 .env.example其中还包含了 load-test 专用的LOAD_TEST_*配置项。委托流程的凭据规则委托delegated流程涉及两个角色凭据对应关系如下委托方delegate签署解密 permit 的一方--private-key/--mnemonic或PRIVATE_KEY/MNEMONIC被委托方delegator加密数据所有者--delegator-private-key/--delegator-mnemonic或DELEGATOR_PRIVATE_KEY/DELEGATOR_MNEMONIC--delegator address当不需要凭据或凭据单独提供时用它标识加密数据所有者加密输入与输入证明input-proofinput-proof是纯 SDK/relayer 交互命令不产生任何链上交易是体验 FHE 加密流程的最低成本入口fhevm-sdk input-proof fhevm-sdk input-proof --type uint32 fhevm-sdk input-proof --type uint64 --value 42 --user 0x0000000000000000000000000000000000000002不传--value时会生成随机值--user指定加密面向的账户地址。从 packages/toolkit/src/flows/input-proof.ts 和类型定义InputProofResult可以看出输出包含contractAddress、userAddress、明文values、encryptedValues加密后的 handle以及inputProof证明本身——这套输出可以被下游合约如 FHETest 的写入、token 转账直接复用。公开解密public-decrypt公开解密有四种形态direct、fresh、stored、make-public。direct解密任意合约的现有 handledirect接受可重复的--handle参数并在一次 SDK 解密请求中发送全部 handle。它不局限于 FHETest可以解密代币 handle 或你自己合约的 handlefhevm-sdk public-decrypt direct --handle 0x... --handle 0x...--contract address是 handle 用于 ACL 校验的配对合约默认是 FHETest。同一条命令中的所有 handle 必须属于同一个配对合约因此解密代币或其他合约的 handle 时必须显式传--contractfhevm-sdk public-decrypt direct --handle 0x... --contract 0xtoken or other contractfresh新建公开 handle 并立即解密fhevm-sdk public-decrypt fresh --type uint8 fhevm-sdk public-decrypt fresh --type uint64 --value 42该流程在 packages/toolkit/src/flows/public-decrypt/fresh.ts 中实现加密一个值 → 以makePublictrue写入 FHETest → 对存储的 handle 走公开解密 API。源码显示其依赖createStoredFheTestHandle完成输入证明 加密 链上存储随后readPublicValues调用 relayer 公开解密并返回abiEncodedCleartexts与decryptionProof——后者可以交给链上做签名验证。stored解密 FHETest 槽位中的 handlefhevm-sdk public-decrypt stored --type uint8 fhevm-sdk public-decrypt stored --account 0x... --type uint8 fhevm-sdk public-decrypt stored --type uint16 --type uint32stored接受可重复的--type每个 account/type 槽位读取一个 handle 并批量发送。不传--type时默认读取bool槽位。make-public把已有 handle 标记为公开当调用者已有存储的 FHETest handle、希望把它变成可公开解密时使用fhevm-sdk public-decrypt make-public --type uint64用户解密user-decryptfresh创建私有 handle 并作为所有者解密fhevm-sdk user-decrypt fresh --type uint8 fhevm-sdk user-decrypt fresh --type uint64 --value 42 --duration-days 7 fhevm-sdk user-decrypt fresh --type uint64 --value 42 --artifact ./artifacts/user-decrypt.json对应实现 packages/toolkit/src/flows/user-decrypt/fresh.ts 展示的完整调用链createStoredFheTestHandlemakePublicfalse→decryptUserValues签署用户解密 permit 并请求 relayer。返回结果中除了解密值还包含permit摘要和可选的validationArtifact。direct解密钱包拥有的现有私有 handlefhevm-sdk user-decrypt direct --handle 0x... --handle 0x... fhevm-sdk user-decrypt direct --handle 0x... --contract 0xtoken or other contract前提是这些 handle 必须能被钱包所有者解密。stored解密钱包的 FHETest 槽位fhevm-sdk user-decrypt stored --type uint8 fhevm-sdk user-decrypt stored --type uint16 --type uint32验证产物artifact与 permit 语义--artifact path会写入一个敏感验证产物其中包含该次解密请求的传输私钥transport private key。它只用于排查 relayer 重复响应的场景必须像密钥材料一样保护绝不能提交到源码库或输出到 stdout——类型定义UserDecryptValidationArtifactschemaVersion 2在 packages/toolkit/src/types.ts 中明确标注了这条安全约束。两个值得注意的版本细节permit 摘要会报告 SDK permit 的version和durationSeconds验证产物使用 schema version 2这样fhevm/sdk0.13.2 引入的协议版本化 permit 不会被误认为旧请求材料。CLI 保留--duration-days作为便利参数在调用 toolkit 前会先转换为秒。委托用户解密delegated-user-decrypt在委托解密中被委托方delegator拥有加密数据委托方delegate签署解密 permit。这是一个典型的数据所有者离线、授权代理代操作场景。fresh创建被委托方数据并作为委托方解密fhevm-sdk delegated-user-decrypt fresh --type uint8 fhevm-sdk delegated-user-decrypt fresh --type uint64 --value 42 --duration-days 7 --delegation-days 30 fhevm-sdk delegated-user-decrypt fresh --type uint64 --artifact ./artifacts/delegated-user-decrypt.json说明README 原文此处为--delegation-duration-days 30CLI 实际以--delegation-duration-days指定 ACL 委托的持续天数具体以各命令--help输出为准。该流程会创建被委托方拥有的数据 → 如需创建 ACL 委托 → 以委托方身份解密。如果已存在有效的 ACL 委托delegated-user-decrypt根命令或stored只需委托方凭据加--delegator否则需要同时提供被委托方凭据让 CLI 自动创建委托。direct 与 storedfhevm-sdk delegated-user-decrypt direct --delegator 0x... --handle 0x... --handle 0x... fhevm-sdk delegated-user-decrypt stored --delegator 0x... --type uint8 fhevm-sdk delegated-user-decrypt stored --delegator 0x... --type uint16 --type uint32direct模式要求 handle 能通过同一个 delegator/delegate 关系解密。Relayer 结果验证verify-user-decryptuser-decrypt或delegated-user-decrypt会保存验证产物verify-user-decrypt用它来事后校验 relayer 的终态 GET 响应fhevm-sdk verify-user-decrypt --artifact ./artifacts/user-decrypt.jsonGET URL 的推导规则验证器不要求你手动拼 URL而是从产物推导relayer 基础 URL来自产物的network字段路径段来自产物的flowv2/user-decrypt或v2/delegated-user-decryptjob id来自产物的relayer.jobId三个覆盖出口全局--relayer-url覆盖基础 URL、--job-id id覆盖 job、--url full-url直接指定完整 URL用于特殊 relayer。当设置了ZAMA_FHEVM_API_KEY时会以x-api-keyGET 头发送devnet 免 keymainnet 必须带 key。验证过程与 provenance 语义验证器的工作链条是获取 GET URL → 恢复传输密钥对 → 校验保存的 permit → 解密 KMS 签名加密的 shares → 若产物含期望明文则比对明文。两点语义必须理解provenance字段区分密码学验证与产物断言KMS shares、请求 handle、传输密钥、permit 签名属于密码学校验而期望明文只是本地产物提供的调试值并非独立认证的事实。若产物由裸--handle解密创建可能不含期望明文此时只报告解密值、不输出valuesMatch。协议 v2 委托 permit由于序列化的 permit 不保留历史 ACL 状态保存的 owner/delegation 标签也属于产物断言。验证器会拒绝与可推导的已签名 permit 材料不一致的产物字段。响应身份绑定验证器会在协议暴露的任何地方绑定 relayer 响应身份比对响应requestId与产物、将保存的jobId与响应字段或最终 URL 路径段比对。返回的responseIdentity字段会显式报告哪些身份维度因产物/响应/URL 缺失而标记为unbound。兼容性限制已保存响应重建使用了一个精确版本兼容层专门处理fhevm/sdk0.13.2的私有品牌对象private branded objects。它仅支持本仓库未打包unbundled的 Node ESM 执行模型如果打包bundling或混用 CJS/ESM 两种 SDK 实例品牌检查可能失败属于不支持的用法。FHETest 工具fhe-testinfo查看网络与合约元数据fhevm-sdk fhe-test info输出解析后的网络、宿主链、relayer 与 FHETest 合约元数据是定位环境问题最快的命令。init初始化 FHETest handlefhevm-sdk fhe-test init --type uint64 fhevm-sdk fhe-test init --type uint64 --type uint128 fhevm-sdk fhe-test init --bulk fhevm-sdk fhe-test init --type uint256 --force不传--type默认初始化所有支持类型--bulk在一笔FHETest.initFheTest交易内初始化全部类型与--type互斥源码中对此有显式校验fhe-test init --bulk cannot be used with --type见 packages/cli/src/cli/commands/fhe-test.ts--force覆盖已存在的 handle返回 JSON 包含transactionHashes因为非 bulk 模式可能为每个类型各写一笔交易。inspect查看 FHETest 状态fhevm-sdk fhe-test inspect --type uint64 fhevm-sdk fhe-test inspect --account 0x... --type uint64 fhevm-sdk fhe-test inspect --handle 0x...--handle与 account/type 选项互斥混用会报错Use either --handle, or account/type inspection options, not both.--type缺省时--account默认取钱包地址结果类型FheTestHandle中的clearText是 FHETest 保存的可检视明文镜像_db[handle]并非 relayer 解密结果——两者不要混淆。op运行链上 FHE 运算演示fhevm-sdk fhe-test op add-uint64 --value 42 fhevm-sdk fhe-test op xor-bool --value true --public fhevm-sdk fhe-test op eq-address --value 0x0000000000000000000000000000000000000001支持的 8 种运算与 FHETest 合约函数的映射关系定义在 packages/toolkit/src/types.ts 的FHE_TEST_OPERATION_CONFIGCLI 运算FHETest 函数类型xor-boolxorEboolbooladd-uint8addEuint8uint8add-uint16addEuint16uint16add-uint32addEuint32uint32add-uint64addEuint64uint64add-uint128addEuint128uint128xor-uint256xorEuint256uint256eq-addresseqEaddressaddress运算的右操作数--value会被加密--public让结果 handle 可公开解密不传--value时使用随机值。ERC-7984 机密代币工具tokentoken transfer与token balance面向的是 ERC-7984 机密代币而非 FHETest因此每次调用都必须传--contract——CLI 不提供任何按网络的默认代币地址。机密转账fhevm-sdk token transfer --contract 0x... --to 0x... --amount 1000金额以基础单位计约束为0 amount 2^64在客户端加密为euint64并附带输入证明源码中EUINT64_UPPER_BOUND 1n 64n的边界校验见 packages/toolkit/src/flows/token/transfer.ts加--from则改为通过confidentialTransferFrom花费已存在的 operator 授权额度fhevm-sdk token transfer --contract 0x... --from 0x... --to 0x... --amount 1000关键机制ERC-7984 在余额不足时不会 revert所以转账结果包含transferredHandle——即实际转移的加密金额 handle。代币合约的 ACL 只把该 handle 的解密权限授予接收方以及代币授权的其他账户不授予发送方。因此接收方可以这样解密注意必须把配对合约指回代币合约默认配对是 FHETest 对代币 handle 是错的fhevm-sdk user-decrypt direct --handle transferredHandle --contract 0xtoken address--verify从发送方侧确认转账fhevm-sdk token transfer --contract 0x... --to 0x... --amount 1000 --verify--verify会在转账前后各解密一次发送方余额并在 JSON 输出中追加balanceBefore、balanceAfter和布尔值deltaMatches校验balanceBefore - balanceAfter 请求金额。注意它额外增加两轮用户解密且与--from互斥——operator 钱包在 ACL 下无法解密--from账户的余额源码同样有显式报错。读取机密余额fhevm-sdk token balance --contract 0x... fhevm-sdk token balance --contract 0x... --account 0x...--account缺省时取PRIVATE_KEY/MNEMONIC加载的钱包地址。由于输出是 JSON可以配合jq管道直接把余额 handle 送入user-decrypt查看明文TOKEN0xtoken address fhevm-sdk user-decrypt direct --contract $TOKEN --handle $(fhevm-sdk token balance --contract $TOKEN | jq -r .balanceHandle)Shell 补全fhevm-sdk completion install fhevm-sdk completion install --shell zsh fhevm-sdk completion uninstall支持的 shell 为bash、zsh、fish、pwsh安装后需重启 shell 或重新 source 配置文件。补全采用轻量静态解析器——按 Tab 不会加载 SDK、连接网络或执行命令流程因此响应极快且无副作用。尚未暴露的 FHETest 能力README 明确列出了FHETest.sol中目前尚未成为一等 CLI 命令的能力可作为后续扩展方向的参考FHETest 能力可能的 CLI 扩展verify(handles, cleartexts, decryptionProof)链上验证公开解密的证明材料createPublicHandle(inputHandle, inputProof)验证外部创建的加密输入并让该 handle 可公开解密而无需按 account/type 存储类型化 getter如getEuint64()、getEuint64Of(account)直接读取类型化加密 handle而非仅用通用 account/type 检查getHandle(type)不传 account 直接读取调用者的原始 handle当前 CLI 的定位是 SDK 演示流程输入证明、公开解密、用户解密、委托用户解密、FHETest 初始化、检查与选定的运算演示。开发与测试workspace 提供以下开发命令在sdk/cli-js-sdk根目录执行pnpm run typecheck # 全工作区类型检查 pnpm run test # 全工作区测试压测应用单独从源码运行pnpm load-test --help在运行压测套件之前请务必先阅读 packages/load-test/README.md生成句柄池与运行套件的前置条件都在其中。总结fhevm-sdkCLI 的价值在于把 fhEVM 最核心、最容易出错的操作——加密输入与证明、三类解密流程、FHETest 初始化、机密代币转账——收敛成一组可脚本化、可管道的 JSON 输出命令。理解它的网络解析顺序选项 → 环境变量 → 公共兜底、direct/fresh/stored三种形态的差异任意合约 handle / 新建 handle / FHETest 槽位、以及验证产物的安全边界传输私钥按密钥材料对待就能把这套工具稳定地接入你的 FHE 应用开发、测试与运维流程。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考