Paxon Qiao's Tech Blog

Zama Protocol 实战：基于全同态加密（FHE）的 Web3 开发入门与环境搭建

· 11min · Paxon Qiao
Table of Contents

Zama Protocol 实战：基于全同态加密（FHE）的 Web3 开发入门与环境搭建

在 Web3 开发中，我们长期面临一个悖论：为了去中心化，规则必须上链公开执行；但为了保护隐私，敏感数据又不能轻易上链。Zama Protocol 通过全同态加密（FHE）技术给出了答案——让计算直接在加密数据上进行。

本文将带你跳出传统的 Solidity 开发思维，理解 FHE 应用的核心心智模型，并手把手完成从环境配置到本地部署的全流程实战。对于追求极致隐私与安全性的开发者来说，这或许是开启下一代 Web3 应用大门的钥匙。

本文深入探讨 Zama Protocol 的 FHEVM 技术，对比普通 dApp 与 FHE 应用在数据状态、计算逻辑及权限设计上的核心差异。提供从 Node.js 环境检查到 Hardhat 模板部署的完整实战步骤，助力开发者快速上手全同态加密开发。

Zama Protocol 基于全同态加密（FHE）技术，使计算可以在加密数据上直接进行，从而实现既保密又可验证的链上金融系统。

Web3 开发中一个普遍存在的矛盾——“规则必须上链执行，但敏感数据不能公开”。

应用不是为了存储而存在，应用是为了计算而存在。

建议尽早建立两个习惯：

  • 每次只验证一小段完整路径
  • 先保证数据流正确，再追求功能堆叠

核心心智模型转变：普通 dApp vs. Zama FHE 应用

维度普通 Solidity dAppZama FHE 应用 (基于 FHEVM)关键提醒
数据状态默认公开，任何人可读。明文/密文并存，密文状态不可直接解读。某个值即使已经进入合约状态，也不意味着任何人都能直接读到它的原始内容。
核心计算对明文直接计算。对密文进行计算，结果仍可为密文。让系统有机会对密文状态继续进行计算，而不是每次一计算就必须先把原文暴露出来。
输入处理前端参数直接作为公开输入。需要前端将用户输入转化为加密输入。“输入参数”这件事本身也分成两种思路：普通输入 vs. 加密输入。
状态读取view 函数直接返回可读值。读取权限需要单独设计和授权。读取能力本身不再是默认公共能力，而更像一种需要被设计和授予的权限。
调试方式直接读取状态变量、查看事件日志，非常直观。调试更间接，不能直接“打印”密文值，需依赖数据流分析。交易成功了，但你不能直接肉眼确认某个内部值。
设计重点聚焦于业务逻辑和安全性。在业务逻辑之上，必须显式设计数据生命周期（来源、输入、计算、查看权限）。“系统设计问题”，而不只是“写几个合约函数”。
错误观念常认为“数据公开是默认的”。容易陷入“所有状态都加密才好”或“把它当加密版Solidity”的误区。好的设计是分层设计：流程公开，敏感数据私密。

建立四步分析框架

在分析或设计任何一个 FHE 应用时，都主动套用这四步：

  1. 数据从哪里来？ (用户输入、其他合约、链下预言机)
  2. 以什么形式进入合约？ (明文参数、ebool/euint 等加密类型)
  3. 合约如何在不暴露原文的前提下处理它？ (使用了哪些 FHE 操作符，如 FHE.add, FHE.select)
  4. 最终谁、在什么条件下能看到什么结果？ (用户本人、合约 owner、或者完全公开？通过 FHE.allow 如何实现？)

接受新的调试习惯：别再指望 console.log 密文变量。从这一刻起，学习依赖：

  • 流程拆解：把复杂逻辑拆成最小可验证单元。
  • 公开状态作为辅助：用公开的状态变量（如 votingEnded）来辅助判断流程节点。
  • 预期输出验证：不直接看值，而是验证“在给定加密输入下，最终公开或允许查看的结果是否符合预期”。

区分“权限”的两个层面：

  • 执行权限：onlyOwner 这类，谁能调用函数。
  • 查看权限 (Decryption Permission)：谁能看到特定密文的真实值。这是 FHE 应用引入的全新维度，必须显式管理。

环境搭建

基础环境：

  • Node.js LTS 版本
  • 偶数版本的 Node.js，例如 v18.x 或 v20.x
  • npm、pnpm 或 yarn 中任选其一
  • Git

第一步：检查本机基础环境

node -v
npm -v
v24.15.0
11.12.1

第二步：使用 FHEVM Hardhat 模板创建一个新的 GitHub 存储库

  1. 打开官方模板仓库
  2. 点击 Use this template
  3. 创建你自己的新仓库
  4. 再克隆到本地

第三步：将您新创建的 GitHub 仓库克隆到本地

mcd zama
/Users/qiaopengjun/Code/zama
git clone git@github.com:qiaopengjun5162/fhevm-voting-tutorial.git
Cloning into 'fhevm-voting-tutorial'...
remote: Enumerating objects: 33, done.
remote: Counting objects: 100% (33/33), done.
remote: Compressing objects: 100% (29/29), done.
remote: Total 33 (delta 4), reused 22 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (33/33), 98.19 KiB | 59.00 KiB/s, done.
Resolving deltas: 100% (4/4), done.
cd fhevm-voting-tutorial/

ls
LICENSE           contracts         eslint.config.mjs package-lock.json tasks             tsconfig.json
README.md         deploy            hardhat.config.ts package.json      test
`

第四步：安装 FHEVM Hardhat 项目依赖项

npm install

理解本地开发和真实网络的区别

开发流程拆成两层：

  • 本地开发层：以快速迭代、跑测试、验证合约逻辑为主
  • 真实网络层：以真实部署、真实交互、真实链路验证为主

第五步：编译

npm run compile

实操

npm run compile

> fhevm-hardhat-template@0.4.1 compile
> cross-env TS_NODE_TRANSPILE_ONLY=true hardhat compile

✖ Help us improve Hardhat with anonymous crash reports & basic usage data? (Y/n) · y
Downloading compiler 0.8.27

Generating typings for: 10 artifacts in dir: types for target: ethers-v6
Successfully generated 40 typings!
Compiled 7 Solidity files successfully (evm target: cancun).

> fhevm-hardhat-template@0.4.1 postcompile
> npm run typechain


> fhevm-hardhat-template@0.4.1 typechain
> cross-env TS_NODE_TRANSPILE_ONLY=true hardhat typechain

✔ Help us improve Hardhat with anonymous crash reports & basic usage data? (Y/n) · y

🎉 完美！环境搭建彻底成功！

编译日志里藏着几个让你放心的重要信息：

  • Compiled 7 Solidity files successfully：这是核心。这意味着 Solidity 编译器 0.8.27 成功编译了 7 个合约文件（包含模板自带的 FHECounter.sol 及其它辅助合约），你的 FHEVM 环境在代码层面完全就绪。
  • evm target: cancun：编译目标是最新的以太坊坎昆升级版，教程面向未来，稳了。
  • Successfully generated 40 typings!：这步是后台生成了 TypeScript 类型定义，让你以后在脚本和测试里操作合约时，IDE 能自动补全。对教程写作极其友好。

第六步：测试

npm run test

> fhevm-hardhat-template@0.4.1 test
> hardhat test



  FHECounter
    ✔ encrypted count should be uninitialized after deployment
    ✔ increment the counter by 1 (42ms)
    ✔ decrement the counter by 1

  FHECounterSepolia
This hardhat test suite can only run on Sepolia Testnet
    - increment the counter by 1


  3 passing (92ms)
  1 pending

完美！测试也跑通了！🎉

从输出可以看到：

  • 3 passing：3 个测试用例全部通过，耗时仅 92ms
  • 1 pending：那个 FHECounterSepolia 的测试被自动跳过，因为它只能在 Sepolia 测试网上跑——这正好印证了“本地优先，Sepolia 是可选进阶路径”。

📊 环境验证最终成绩单

步骤状态说明
Node.js 版本✅ v24.15.0偶数 LTS，符合要求
仓库创建✅从 Zama 官方模板创建
依赖安装✅ 776 packages警告是正常的，不影响开发
编译✅ 7 filesSolidity 0.8.27，目标 cancun
测试✅ 3 passing本地 mocked mode 完全跑通

到此为止已经说明：

  • Hardhat 工程结构基本正常
  • 依赖已经安装完整
  • 合约和测试框架可以工作
  • 你已经拥有继续改造示例的最小基础

本地节点与部署

终端 ①：启动本地链

image-20260502170404502

这会启动一个本地 Hardhat 开发链，默认监听 localhost:8545。启动成功后，你会看到一串私钥地址和 Started HTTP and WebSocket JSON-RPC server。

这个窗口不要关，让它一直跑着。

终端 ②：部署合约到本地链

打开一个新终端窗口，执行：

npx hardhat deploy --network localhost

Nothing to compile
No need to generate any newer typings.
reusing "FHECounter" at 0x5FbDB2315678afecb367f032d93F642f64180aa3
FHECounter contract:  0x5FbDB2315678afecb367f032d93F642f64180aa3

最终成绩单

步骤命令状态
编译检查npm run compile✅
测试npm run test✅ 3 passing
启动本地链npx hardhat node✅ 出块正常，10个测试账户各持10000 ETH
部署合约npx hardhat deploy --network localhost✅ 合约已在 0x5FbDB231...

清理模版

rm -rf test/* contracts/* deploy ./fhevmTemp ./artifacts ./cache ./coverage ./types ./coverage.json ./dist

总结

掌握 Zama Protocol 的开发，不仅仅是学会几个新的 FHE 操作符，更是一场关于“数据生命周期”和“查看权限管理”的思维革命。通过本文的实战演练，我们成功搭建了基础开发环境并跑通了本地测试。

隐私计算是区块链走向主流金融与复杂应用的必经之路。虽然 FHE 的调试和逻辑拆解比传统开发更具挑战，但随着工具链的日益完善，开发者已经可以开始在这个充满潜力的新领域中构建属于自己的保密验证系统。

参考