Laolex/fhevm-agent-skill

# fhEVM Agent Skill

**生产就绪的 AI agent skill，使任何由 LLM 驱动的编程助手能够编写、审计和迁移 Zama fhEVM 机密智能合约。** 为 [Zama Bounty Program Season 2](https://github.com/zama-ai/bounty-program) — Bounty Track 而构建。 ## 它的功能 此 skill 可将 AI 编程助手（Claude Code、Cursor、Windsurf、GitHub Copilot）转变为 fhEVM 专家。agent 不再会产生虚构的已弃用 API 或遗漏关键 ACL 模式的情况，而是能在第一次尝试时就生成正确且可部署的机密合约。 ### 三种 agent 命令 | 命令 | 功能 | |---------|-------------| | `/fhevm scaffold` | 根据自然语言规范生成完整的机密合约 + 测试 + 部署脚本 + 前端 | | `/fhevm audit` | 审计合约和前端的 ACL 漏洞、反模式、CORS 代理问题以及安全漏洞 | | `/fhevm migrate` | 一次性将旧版 `TFHE.*` / `GatewayCaller` 代码重写为当前的 `FHE.*` API | ### 八个参考模块 | 模块 | 内容 | |--------|----------| | `00-architecture` | Coprocessor 模型、密文句柄、ACL 概览、解密模式、Sepolia 地址 | | `01-setup` | Hardhat 配置、`vars()`、多合约部署、ZamaConfig 模式 | | `02-types-ops` | 所有加密类型（`euint8`–`euint128`、`ebool`、`eaddress`）、FHE 操作、gas 成本 | | `03-input-acl` | `FHE.fromExternal` 证明、`allowTransient`、多角色 ACL 模式 | | `04-decryption` | `userDecrypt`（v0.4.1 batch API）、`makePubliclyDecryptable` + `checkSignatures` Pattern 3（带有 handle pinning） | | `05-frontend` | `initSDK` + `SepoliaConfig`、relayer SDK、ethers v6 provider 修复、Zustand 状态机、CORS 代理 | | `06-testing` | Mock coprocessor、`createEncryptedInput`、`publicDecryptEbool`、回调测试 | | `07-templates` | ConfidentialVault、ERC-7984 标准、OpenZeppelin Confidential Contracts | | `08-anti-patterns` | 15+ 常见错误及其正确替换方案 —— 这是防止产生幻觉的首要模块 | ## 为什么这很重要 LLM 在 fhEVM 开发中总是失败，原因如下： 1. **过时的训练数据** — 它们会生成 `TFHE.asEuint64()`（已在 v0.9+ 中移除），而不是 `FHE.fromExternal()` 2. **遗漏 ACL 调用** — 没有 `FHE.allowThis()` 的加密值会静默返回零 3. **错误的解密模式** — 它们混淆了三种截然不同的解密流程（userDecrypt、oracle callback、public decrypt） 4. **前端集成漏洞** — `initSDK` 竞态、CORS 代理配置错误、ethers v6 provider 问题 此 skill 通过从 Sepolia 上的两次生产部署中提取的 3,000+ 行经过实战检验的模式，消除了所有这四种失败情况。 ## 生产验证 基于真实的已部署合约进行构建和验证： - **ShieldLend** — 超额抵押机密借贷（加密抵押品、贷款金额、信用评分、清算标志）。447 行合约 + 295 行信用评分模块。57/57 测试通过。 - **ShieldPay** — 具有雇主/审计员/付款人角色以及 FHE 薪资计算的机密工资单。27/27 测试通过。 两者均已部署在 Sepolia 上，并带有使用 `@zama-fhe/relayer-sdk` v0.4.1 的完整 React/Vite 前端。 ## 安装 ### Claude Code — 插件市场（推荐） 在 Claude Code 中通过一行命令安装： ``` /plugin marketplace add https://github.com/Laolex/fhevm-agent-skill ``` 然后从 **Discover** 标签页中找到 `fhevm` 并安装。安装后，运行 `/reload-plugins` 并使用： ``` /fhevm:scaffold — generate a full confidential contract project /fhevm:audit — audit for ACL gaps and anti-patterns /fhevm:migrate — rewrite TFHE.* code to the current FHE.* API ``` ### Claude Code — 手动（git clone） ``` git clone https://github.com/Laolex/fhevm-agent-skill.git ~/.claude/skills/fhevm ``` 然后将其添加到您的 `CLAUDE.md` 或项目说明中： ``` Skills - fhevm: ~/.claude/skills/fhevm/SKILL.md — fhEVM confidential smart contract development ``` ### Cursor / Windsurf / 其他 在您的 IDE 的 AI 配置中将 `SKILL.md` 文件（或整个目录）添加为上下文。该 skill 会根据用户意图自动分发 —— 除了加载文件之外，不需要任何特殊设置。 ## 快速开始 ``` > /fhevm scaffold Build me a confidential voting contract where each vote is encrypted, only the admin can trigger a tally reveal, and voters can verify their own vote was counted. ``` agent 将会： 1. 解析您的规范并选择合适的架构 2. 生成带有正确 ACL、加密计票和 `makePubliclyDecryptable` 揭示的 `ConfidentialVoting.sol` 3. 使用 mock coprocessor 生成 Hardhat 测试 4. 生成部署脚本 5. 生成带有 `initSDK` + `userDecrypt` 的 React 前端代码片段 **现场演示** — [ConfidentialVote](https://github.com/Laolex/confidentialVote)：使用此 skill 构建的密封投票合约。演示了所有五种 FHE 模式：加密输入 + 证明、盲计票累积、投票者徽章重加密、带有 handle pinning 的公开揭示，以及完整的 ACL 规范。 | [▶ 观看演示](https://youtu.be/lcz6ejR8HyE) ## 架构 ``` SKILL.md (dispatch router) ├── scaffold.md — full project generator ├── audit.md — security/correctness auditor ├── migrate.md — TFHE→FHE migration tool ├── 00-architecture — fhEVM internals ├── 01-setup — project scaffolding ├── 02-types-ops — encrypted types & operations ├── 03-input-acl — input proofs & access control ├── 04-decryption — three decryption patterns ├── 05-frontend — React/Vite + relayer SDK ├── 06-testing — Hardhat mock coprocessor ├── 07-templates — contract templates + ERC-7984 └── 08-anti-patterns — common mistakes & fixes ``` `SKILL.md` 入口点充当路由器的角色：它读取用户的意图并仅加载相关模块，从而保持上下文使用的高效性。 ## 兼容性 | AI 助手 | 状态 | 备注 | |-------------|--------|-------| | Claude Code | 已验证 | 通过 `~/.claude/skills/` 提供原生 skill 支持 | | Cursor | 已验证 | 添加为上下文文件或规则 | | Windsurf | 已验证 | 添加为上下文文件 | | GitHub Copilot | 兼容 | 添加为工作区上下文 | | 任何支持 MCP 的 agent | 兼容 | 将模块作为 MCP 资源提供 | ## 兼容性矩阵 | 层级 | 锁定版本 | 备注 | |---|---|---| | `@fhevm/solidity` | `^0.11.1` | `FHE.*` API；无 `requestDecryption`，无 `gte`（使用 Pattern 3 + `not(lt)`） | | `@fhevm/hardhat-plugin` | `^0.4.x` | mock coprocessor | | `@zama-fhe/relayer-sdk` | `^0.4.1` | 仅从 `@zama-fhe/relayer-sdk/web` 导入 | | Solidity | `0.8.24` / `0.8.27` | `evmVersion: cancun` | | 网络 | Sepolia | npm `SepoliaConfig` — 切勿本地拷贝引用 | **已禁用（已弃用或在锁定技术栈中不存在）：** `TFHE.*`、`einput`、`GatewayCaller`、`FHE.requestDecryption`、`FHE.gte`、`encryptUint`、`encrypt32/64`、`initFhevm`、`/web.js`、`/bundle`（Vite/Next）、自动 `hardhat verify`、本地 `ZamaConfig.sol`。 **AI 工具：** Claude Code · Cursor · Windsurf · GitHub Copilot · 任何 MCP agent。 ## 技术覆盖 - `@fhevm/solidity` v0.11+ - `@zama-fhe/relayer-sdk` v0.4.1+ - 加密类型：`euint8`、`euint16`、`euint32`、`euint64`、`euint128`、`ebool`、`eaddress` - 所有 FHE 操作：算术、比较、按位、移位、select、min/max - ACL：`allowThis`、`allow`、`allowTransient`、`makePubliclyDecryptable` - 解密：`userDecrypt`（batch, Pattern 1）、`makePubliclyDecryptable` + `checkSignatures`（Pattern 3 with handle pinning）。`@fhevm/solidity@0.11.x` 中不存在 `FHE.requestDecryption` —— 公开揭示流程请使用 Pattern 3。 - ERC-7984 机密代币标准 - OpenZeppelin Confidential Contracts - Hardhat + mock coprocessor 测试 - React/Vite + ethers v6 前端集成 - 带有 CORS 代理的 Vercel 部署 ## 版本 v3.3.0 ## 许可证 MIT

标签：AI编程助手, SOC Prime, 全同态加密, 区块链开发, 开发工具, 智能体, 智能合约