使用 zama-fhe/relayer-sdk 构建 fhEVM Web 应用从 CDN 引入到实例初始化的完整指南【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm导读本文基于 fhevm 仓库的 Web 应用开发指南 展开系统讲解如何在浏览器端使用zama-fhe/relayer-sdk构建基于 fhEVM全同态加密虚拟机的 dApp。你将掌握三种引入 SDK 的方式UMD CDN、ESM CDN、npm 包、WASM 初始化initSDK与实例创建createInstance的完整流程并理解FhevmInstance与 SepoliaConfig 在加密输入、用户解密、公开解密三大核心场景中的承接关系从而直接上手开发可加密、可解密的前端应用。为什么选择 Relayer SDK 构建 Web 应用fhEVM 的完整架构包含 FHEVM Host Chain承载 ACL、KMSVerifier、InputVerifier 等合约的链与 Gateway Chain执行解密与输入验证的链。如果前端直接与 Gateway Chain 交互客户端必须同时拥有两条链上的钱包与代币这对普通用户与开发者都极为繁琐。zama-fhe/relayer-sdk正是为了解决这一问题而设计借助 SDK 总览 中描述的 Relayer 架构FHEVM 客户端只需要在 FHEVM Host Chain 上持有钱包所有与 Gateway Chain 的交互都由 SDK 通过 HTTP 调用 Zama 维护的 Relayer 完成Relayer 在 Gateway Chain 上代为支付相关费用。因此在前端集成时你只需关注浏览器环境下的加密、签名与调用复杂的跨链交互被完全屏蔽在 SDK 内部。在开始编码前建议先阅读 初始化Setup指南理解FhevmInstance对象承载的全部配置与方法。Step 1以正确的方式引入 SDKzama-fhe/relayer-sdk由多个文件组成包括 WASM 文件与 Web Workers如果手动配置打包器Webpack、Vite、Rollup 等将这些组件正确打进构建产物过程会相当繁琐——尤其是开发带服务端渲染SSR的 dApp 时。官方文档为此提供了三种引入方式按场景任选其一。方式一UMD CDN推荐用于快速上手在你的项目入口 HTML 顶部引入 UMD 构建产物script srchttps://cdn.zama.ai/relayer-sdk-js/0.2.0/relayer-sdk-js.umd.cjs typetext/javascript/script引入后SDK 会以全局对象window.fhevm的形式暴露。如果你同时通过 npm 安装了zama-fhe/relayer-sdk包也可以直接使用 bundle 导入import { initSDK, createInstance, SepoliaConfig } from zama-fhe/relayer-sdk/bundle;UMD 方式的最大价值在于彻底绕开打包器对 WASM 与 Worker 的处理问题。关于这一点常见 Webpack 错误指南 中专门提到当使用 SSR 框架打包库失败时官方推荐直接使用 bundle 预打包版本以script标签嵌入库并按如下方式初始化const start async () { await window.fhevm.initSDK(); // load wasm needed const config { ...SepoliaConfig, network: window.ethereum }; config.network window.ethereum; const instance window.fhevm.createInstance(config).then((instance) { console.log(instance); }); };方式二ESM CDN零构建体验如果你更喜欢 ES Module 语法可以直接从 CDN 以模块方式加载script typemodule import { initSDK, createInstance, SepoliaConfig } from https://cdn.zama.ai/relayer-sdk-js/0.2.0/relayer-sdk-js.js; await initSDK(); const config { ...SepoliaConfig, network: window.ethereum }; config.network window.ethereum; const instance await createInstance(config); /script这种方式适合原型验证或不需要打包器的轻量页面initSDK()负责加载 TFHE 相关的 WASMcreateInstance(config)负责构造实例两步都完成后即可使用实例的加密与解密能力。方式三npm 包正式项目集成在正式项目中使用 npm / Yarn / pnpm 安装# Using npm npm install zama-fhe/relayer-sdk # Using Yarn yarn add zama-fhe/relayer-sdk # Using pnpm pnpm add zama-fhe/relayer-sdkzama-fhe/relayer-sdk使用ESM 格式因此你的package.json需要设置type: module参见 Node.js 官方对package.jsontype 字段的说明。如果你的 Node 项目使用type: commonjs或未声明 type可以通过强制加载 Web 版本解决import { createInstance } from zama-fhe/relayer-sdk/web;正常 ESM 场景下的导入方式为import { initSDK, createInstance, SepoliaConfig } from zama-fhe/relayer-sdk;从仓库结构看zama-fhe/relayer-sdk的源码位于 sdk/js-sdk/src其中 index.ts 为包的统一入口wasm/目录下分别维护了tfhe与tkms两套 WASM 模块sdk/js-sdk/src/wasm这也解释了为何 SDK 必须通过initSDK()显式加载 WASM 后才能工作。Step 2用 initSDK 加载 TFHE WASMTFHE 加密运算依赖 WebAssembly。使用库内任何加密功能之前必须先调用initSDK()加载 WASMimport { initSDK } from zama-fhe/relayer-sdk/bundle; const init async () { await initSDK(); // Load needed WASM };注意若跳过此步骤直接调用加密相关 API通常会因为 WASM 尚未就绪而抛出与 TFHE 运行时相关的错误。initSDK()是异步函数务必await完成后再进入后续流程。Step 3创建 FhevmInstance 实例WASM 加载完成后即可创建实例。FhevmInstance是 SDK 的核心对象它持有与 fhEVM 交互所需的全部配置与方法。最小示例import { initSDK, createInstance, SepoliaConfig } from zama-fhe/relayer-sdk/bundle; const init async () { await initSDK(); // Load FHE const config { ...SepoliaConfig, network: window.ethereum }; return createInstance(config); }; init().then((instance) { console.log(instance); });其中SepoliaConfig是 SDK 为 Zama 维护的 Sepolia 测试网 FHEVM 与 Relayer 预置的配置对象可直接使用network: window.ethereum覆盖为浏览器钱包注入的 Provider如 MetaMask这样实例即可用用户钱包发起签名请求。SepoliaConfig 背后的完整配置项如果你不依赖预设配置也可以参考 初始化Setup指南 手动传入全部参数。createInstance接受的核心配置如下import { createInstance } from zama-fhe/relayer-sdk; const instance await createInstance({ // ACL_CONTRACT_ADDRESS (FHEVM Host chain) aclContractAddress: 0x687820221192C5B662b25367F70076A37bc79b6c, // KMS_VERIFIER_CONTRACT_ADDRESS (FHEVM Host chain) kmsContractAddress: 0x1364cBBf2cDF5032C47d8226a6f6FBD2AFCDacAC, // INPUT_VERIFIER_CONTRACT_ADDRESS (FHEVM Host chain) inputVerifierContractAddress: 0xbc91f3daD1A5F19F8390c400196e58073B6a0BC4, // DECRYPTION_ADDRESS (Gateway chain) verifyingContractAddressDecryption: 0xb6E160B1ff80D67Bfe90A85eE06Ce0A2613607D1, // INPUT_VERIFICATION_ADDRESS (Gateway chain) verifyingContractAddressInputVerification: 0x7048C39f048125eDa9d678AEbaDfB22F7900a29F, // FHEVM Host chain id chainId: 11155111, // Gateway chain id gatewayChainId: 55815, // Optional RPC provider to host chain network: https://eth-sepolia.public.blastapi.io, // Relayer URL relayerUrl: https://relayer.testnet.zama.cloud, });这些参数的含义配置项作用备注aclContractAddressFHEVM Host Chain 上的 ACL访问控制列表合约地址控制谁可以解密 / 操作特定 ciphertextkmsContractAddressHost Chain 上的 KMSVerifier 合约地址用于验证 KMS 签名与密钥材料inputVerifierContractAddressHost Chain 上的 InputVerifier 合约地址验证新加密输入及其零知识证明verifyingContractAddressDecryptionGateway Chain 上的解密验证合约地址供 Relayer 侧做解密请求的 EIP-712 签名验证verifyingContractAddressInputVerificationGateway Chain 上的输入验证合约地址供 Relayer 侧做输入注册的 EIP-712 签名验证chainIdFHEVM Host Chain 的 chain idSepolia 为11155111gatewayChainIdGateway Chain 的 chain id固定为55815networkHost Chain 的 RPC Provider 或 RPC URL可选浏览器中通常传window.ethereumrelayerUrlRelayer 服务的 HTTP 地址测试网为https://relayer.testnet.zama.cloud简化写法等价于import { createInstance, SepoliaConfig } from zama-fhe/relayer-sdk; const instance await createInstance(SepoliaConfig);Sepolia 相关合约地址、chain id 等信息都封装在SepoliaConfig对象中无需记忆。实例就绪之后三大核心能力创建好FhevmInstance后实例即可用于以下三类操作均已有独立指南本文只做承接说明加密输入Input registration使用instance.createEncryptedInput(contractAddress, userAddress)创建加密缓冲区通过add8/add16/add32/add64/add128/add256/addBool/addAddress等类型化方法填充明文最后buffer.encrypt()得到 ciphertext handles 与 inputProof可传给链上合约的FHE.fromExternal使用。完整流程见 输入注册指南。用户解密User decryption当需要让某个用户用自己的密钥查看自己的私有数据如余额、计数而不暴露明文时通过instance.generateKeypair()、instance.createEIP712(...)配合钱包signTypedData签名最后instance.userDecrypt(...)在客户端完成用用户 NaCl 公钥重新加密的流程只有该用户能解密。前置条件是合约中已通过FHE.allow(ciphertext, address)正确设置 ACL 权限。详见 用户解密指南。公开解密Public decryption当需要让所有人看到某个 ciphertext 的明文如拍卖结果时调用instance.publicDecrypt(handles)通过 Relayer 的 HTTP 端点请求解密返回明文值及可在链上验证的密码学证明链上可用FHE.checkSignatures()验证。详见 公开解密指南。常见问题排查与打包器注意事项在前端集成zama-fhe/relayer-sdk时最常遇到的问题集中在打包环节官方 常见 Webpack 错误指南 给出了四类典型场景的解决方案Cant resolve tfhe_bg.wasmSDK 内部使用new URL(tfhe_bg.wasm)触发 Webpack 解析需在webpack.config.js中添加 fallbackresolve: { fallback: { tfhe_bg.wasm: require.resolve(tfhe/tfhe_bg.wasm), }, },Buffer is not defined浏览器环境缺少 Node.js 核心模块需安装并配置 browserify 版 fallbackresolve: { fallback: { buffer: require.resolve(buffer/), crypto: require.resolve(crypto-browserify), stream: require.resolve(stream-browserify), path: require.resolve(path-browserify), }, },ESM 版本导入的 typing 问题打包器会依据package.json的browser字段替换导入版本若出现类型问题可强制导入浏览器包或参考 React 模板的tsconfig.jsonTypeScript 5配置。SSR 框架打包失败直接改用 bundle 预打包版本zama-fhe/relayer-sdk/bundle并以script标签嵌入初始化时通过window.fhevm.initSDK()与window.fhevm.createInstance(...)调用示例见上文方式一。小结与推荐阅读路径在 Web 应用中集成 fhEVM 的核心链路可以概括为三步引入 SDKCDN 或 npm→await initSDK()加载 WASM →createInstance(config)创建实例。之后所有加密、解密能力都由该实例统一提供。建议按以下顺序继续深入SDK 总览理解 Relayer 架构与 SDK 定位初始化指南完整的配置项与 SepoliaConfig 说明输入注册将明文加密注册为链上 ciphertext用户解密 与 公开解密两类解密场景的完整代码Webpack 调试指南打包与 SSR 场景排障CLI 指南命令行方式使用 SDK如果希望在浏览器环境中提前调试 SDK 的加密与解密行为还可以结合仓库中的 JS SDK 测试用例 与 SDK 示例 进行本地验证。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考