企业官网建设流程全解析

fhevm CLI 加密工具使用指南：用relayer encrypt为机密智能合约加密输入数据

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

fhevm生态提供的relayer命令行工具，让开发者无需编写任何 JavaScript 代码，即可直接为链上全同态加密（FHE）系统加密整数与布尔值。本指南以当前仓库 docs/sdk-guides/cli.md 为主线，完整讲解该 CLI 的安装、命令语法、类型规则与实战示例，并结合 sdk/js-sdk 与 relayer 的源码实现，说明加密背后的公钥机制与数据流转过程。读完本文，你将能在本地 RPC 节点或测试网上，用一行命令为机密合约生成可用的密文。

一、CLI 定位：为 FHEVM 合约准备"新鲜密文"

在 FHEVM 协议中，所有用于链上计算的值都在协议的 FHE 公钥下加密。CLI 的角色与 docs/sdk-guides/input.md 中描述的 SDKcreateEncryptedInput流程一致：它获取链上协议的公钥，用其对明文执行 TFHE 加密，得到可直接交给合约使用的密文。区别仅在于 SDK 以代码方式完成这一过程，而 CLI 以命令行方式完成，适合脚本化、自动化与快速调试场景。

从架构上看，这一过程依赖 Relayer 服务。如 relayer/README.md 所述，Relayer 是 fhevm host chain（如 Ethereum）与 Gateway 之间的桥梁，其能力之一就是暴露密钥材料 URL（FHE 公钥与 CRS URL），CLI 正是通过查询这些 URL 取得加密所需的公钥材料。

二、安装：全局安装@zama-fhe/relayer-sdk

使用 CLI 前，请确保系统已安装 Node.js（CLI 基于 npm 包分发与运行）。然后全局安装@zama-fhe/relayer-sdk包：

npm install -g @zama-fhe/relayer-sdk

安装完成后，即可通过relayer命令访问 CLI。验证安装是否成功，并查看所有可用命令：

relayer help

relayer help会列出relayer支持的全部子命令及其用法摘要。若命令未找到，请检查 npm 全局安装目录（npm root -g）是否已加入系统PATH。

三、加密数据：relayer encrypt命令详解

CLI 的核心功能是加密整数与布尔值，供智能合约使用。加密使用区块链的 FHE 公钥完成，从而保证数据的机密性——即明文在链下被加密，只有持有相应解密能力的实体才能还原。

3.1 命令语法

relayer encrypt --node <NODE_URL> <CONTRACT_ADDRESS> <USER_ADDRESS> <DATA:TYPE>...

3.2 参数说明

其中<DATA:TYPE>的类型后缀支持两种取值：

• :64—— 64 位整数（对应 FHE 类型euint64）；
• :1—— 布尔值（对应 FHE 类型ebool）。

3.3 实战示例

为合约0x8Fdb26641d14a80FCCBE87BF455338Dd9C539a50与用户0xa5e1defb98EFe38EBb2D958CEe052410247F4c80分别加密 64 位整数71721075与布尔值1：

relayer encrypt 0x8Fdb26641d14a80FCCBE87BF455338Dd9C539a50 0xa5e1defb98EFe38EBb2D958CEe052410247F4c80 71721075:64 1:1

该命令一次调用同时加密两个值，适合为合约的单次调用准备多个输入。指定--node时，则显式指定节点 URL，例如：

relayer encrypt --node http://localhost:8545 0x8Fdb26641d14a80FCCBE87BF455338Dd9C539a50 0xa5e1defb98EFe38EBb2D958CEe052410247F4c80 71721075:64 1:1

3.4 参数背后的契约含义

• <CONTRACT_ADDRESS>与<USER_ADDRESS>共同构成密文的访问边界。这与 docs/sdk-guides/input.md 中createEncryptedInput(contractAddress, userAddress)的两个参数一一对应：合约地址是允许与该"新鲜密文"交互的合约，用户地址是允许将该密文导入合约的实体。
• 密文与公钥 URL 的分发细节可参考 relayer/src/http/endpoints/v2/handlers/keyurl.rs：Relayer 通过GET /v2/keyurl端点返回fhe_key_info（含fhe_public_key的下载 URL）与crs参数材料。CLI 加密所用的 FHE 公钥正是来源于此端点，其响应结构在 relayer/openapi.yml 中亦有定义。

四、深入原理：类型后缀与 TFHE 位宽的对应关系

CLI 的:64与:1并非任意约定，而是与 FHEVM 的 FHE 类型系统严格对应。在 sdk/js-sdk/src/core/handle/FheType.ts 中可以找到完整的类型映射：

由此可以得出两点关键结论：

1. :64对应euint64（加密位宽 64 bit），：1对应ebool（加密位宽 2 bit）。从源码注释可见，TFHE 加密每个值最少需要 2 bit，因此布尔值虽然只需 1 bit 有效信息，仍占用 2 bit 加密粒度（见 FheType.ts 中MINIMUM_ENCRYPTION_BIT_WIDTH = 2及FheTypeIdToEncryptionBits映射）。
2. 位宽越大，密文越大、同态运算开销越高，因此实际使用中应根据业务需求选择最小的合适类型。CLI 当前暴露:64与:1两种后缀，覆盖了最常见的"数值 + 布尔"输入场景。

五、从 CLI 到 SDK：同一加密能力的两条调用路径

CLI 底层复用的正是 JavaScript SDK 的加密实现。在 sdk/js-sdk/src/core/actions/encrypt/encryptValue.ts 中，encryptValue函数的参数结构为：

export type EncryptValueParameters = { readonly value: { readonly type: string; readonly value: boolean | bigint | number | string }; readonly contractAddress: string; readonly userAddress: string; readonly options?: RelayerInputProofOptions | undefined; };

其内部流程为：

1. 校验contractAddress与userAddress为合法地址（assertIsAddress）；
2. 通过initPublicAction(fhevm)初始化上下文（含从 Relayer 获取的公钥材料）；
3. 调用 sdk/js-sdk/src/core/coprocessor/encrypt.ts 中的encrypt()完成加密并生成输入证明（inputProof）；
4. 返回密文句柄encryptedValue与inputProof。

因此，CLI 中relayer encrypt的参数（合约地址、用户地址、数据与类型）与 SDK 中createEncryptedInput(contractAddress, userAddress).add64(...)/addBool(...)的调用语义完全等价。若需要在应用代码中自动化执行相同操作，可参考 docs/sdk-guides/input.md 的完整示例：

const buffer = instance.createEncryptedInput(contractAddress, userAddress); buffer.add64(BigInt(23393893233)); buffer.addBool(false); const ciphertexts = await buffer.encrypt();

随后即可将密文句柄与输入证明交给合约，通过FHE.fromExternal将"新鲜密文"引入链上计算。

六、使用前提与注意事项

1. 节点必须已接入 FHEVM 协议：--node指向的 RPC 节点需能访问协议配置与密钥材料。本地开发可运行仓库提供的 Anvil 节点（见 charts/anvil-node 的 Helm Chart 或 test-suite 的 docker-compose 配置），确保 Relayer 的/v2/keyurl已就绪——否则加密将因取不到公钥而失败。
2. 地址必须真实存在：CLI 只负责加密，不负责部署合约或创建账户。传入的合约地址与用户地址应来自已部署的 FHEVM 合约与实际账户。
3. 类型后缀必须与合约参数类型匹配：合约函数若声明euint64参数，应使用:64加密；布尔参数应使用:1。
4. 密文的链上使用仍需输入证明：CLI/SDK 加密后产生的inputProof是FHE.fromExternal(a, proof)验证所必需的材料，缺少证明将无法在链上通过InputVerifier的校验。

七、小结

relayer encrypt提供了一条从命令行直接走向 FHE 加密的捷径：安装@zama-fhe/relayer-sdk后，一条命令即可完成 64 位整数与布尔值的加密，且与 SDK 的createEncryptedInput流程共享同一套加密实现与公钥来源。配合本文梳理的类型位宽映射与 relayer 的密钥材料端点，你可以快速为机密合约批量准备密文输入，或将其嵌入 CI 脚本完成端到端的加密数据供给。更完整的 SDK 初始化与输入注册流程，可继续阅读 docs/sdk-guides/initialization.md 与 docs/sdk-guides/input.md。

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