Laolex/fhevm-agent-skill

# fhEVM Agent Skill **Production-ready AI agent skill that enables any LLM-powered coding assistant to write, audit, and migrate Zama fhEVM confidential smart contracts.** Built for the [Zama Bounty Program Season 2](https://github.com/zama-ai/bounty-program) — Bounty Track. ## 它做什么 This skill turns AI coding assistants (Claude Code, Cursor, Windsurf, GitHub Copilot) into fhEVM experts. Instead of hallucinating deprecated APIs or missing critical ACL patterns, the agent produces correct, deployable confidential contracts on the first try. ### 三个智能体命令 | Command | What it does | |---------|-------------| | `/fhevm scaffold` | Generates a complete confidential contract + tests + deploy script + frontend from a plain-language spec | | `/fhevm audit` | Audits contracts and frontends for ACL gaps, anti-patterns, CORS proxy issues, and security vulnerabilities | | `/fhevm migrate` | Rewrites legacy `TFHE.*` / `GatewayCaller` code to the current `FHE.*` API in one pass | ### 八个参考模块 | Module | Contents | |--------|----------| | `00-architecture` | Coprocessor model, ciphertext handles, ACL overview, decryption patterns, Sepolia addresses | | `01-setup` | Hardhat config, `vars()`, multi-contract deploy, ZamaConfig patterns | | `02-types-ops` | All encrypted types (`euint8`–`euint128`, `ebool`, `eaddress`), FHE operations, gas costs | | `03-input-acl` | `FHE.fromExternal` proofs, `allowTransient`, multi-role ACL patterns | | `04-decryption` | `userDecrypt` (v0.4.1 batch API), `requestDecryption` oracle, `makePubliclyDecryptable` | | `05-frontend` | `initSDK` + `SepoliaConfig`, relayer SDK, ethers v6 provider fix, Zustand state machine, CORS proxy | | `06-testing` | Mock coprocessor, `createEncryptedInput`, `publicDecryptEbool`, callback testing | | `07-templates` | ConfidentialVault, ERC-7984 standard, OpenZeppelin Confidential Contracts | | `08-anti-patterns` | 15+ common mistakes with correct replacements — the #1 module for preventing hallucinations | ## 为什么这很重要 LLMs consistently fail at fhEVM development because: 1. **Stale training data** — they generate `TFHE.asEuint64()` (removed in v0.9+) instead of `FHE.fromExternal()` 2. **Missing ACL calls** — encrypted values without `FHE.allowThis()` silently return zero 3. **Wrong decryption patterns** — they mix up three distinct decryption flows (userDecrypt, oracle callback, public decrypt) 4. **Frontend integration gaps** — `initSDK` races, CORS proxy misconfiguration, ethers v6 provider issues This skill eliminates all four failure modes through 3,000+ lines of battle-tested patterns extracted from two production deployments on Sepolia. ## 生产验证 Built and validated against real deployed contracts: - **ShieldLend** — Overcollateralized confidential lending (encrypted collateral, loan amounts, credit scores, liquidation flags). 447-line contract + 295-line credit score module. 57/57 tests passing. - **ShieldPay** — Confidential payroll with employer/auditor/paymaster roles and FHE salary math. 27/27 tests passing. Both deployed on Sepolia with full React/Vite frontends using `@zama-fhe/relayer-sdk` v0.4.1. ## 安装 ### Claude Code（推荐） The skill is a directory of markdown files. Point your AI assistant's skill/context system at this repo: ``` # 克隆到你的 Claude Code 技能目录 git clone https://github.com/Laolex/fhevm-agent-skill.git ~/.claude/skills/fhevm ``` Then add to your `CLAUDE.md` or project instructions: ``` Skills - fhevm: ~/.claude/skills/fhevm/SKILL.md — fhEVM confidential smart contract development ``` ### Cursor / Windsurf / 其他 Add the `SKILL.md` file (or the entire directory) as context in your IDE's AI configuration. The skill auto-dispatches based on user intent — no special setup beyond loading the files. ## 快速开始 ``` > /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. ``` The agent will: 1. Parse your spec and choose the right architecture 2. Generate `ConfidentialVoting.sol` with proper ACL, encrypted tallies, and `makePubliclyDecryptable` reveal 3. Generate Hardhat tests using mock coprocessor 4. Generate a deploy script 5. Generate a React frontend snippet with `initSDK` + `userDecrypt` ## 架构 ``` 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 ``` The `SKILL.md` entry point acts as a router: it reads the user's intent and loads only the relevant modules, keeping context usage efficient. ## 兼容性 | AI Assistant | Status | Notes | |-------------|--------|-------| | Claude Code | Validated | Native skill support via `~/.claude/skills/` | | Cursor | Validated | Add as context files or rules | | Windsurf | Validated | Add as context files | | GitHub Copilot | Compatible | Add as workspace context | | Any MCP-capable agent | Compatible | Serve modules as MCP resources | ## 技术覆盖 - `@fhevm/solidity` v0.11+ - `@zama-fhe/relayer-sdk` v0.4.1+ - Encrypted types: `euint8`, `euint16`, `euint32`, `euint64`, `euint128`, `ebool`, `eaddress` - All FHE operations: arithmetic, comparison, bitwise, shifts, select, min/max - ACL: `allowThis`, `allow`, `allowTransient`, `makePubliclyDecryptable` - Decryption: `userDecrypt` (batch), `requestDecryption` (oracle), public decrypt - ERC-7984 confidential token standard - OpenZeppelin Confidential Contracts - Hardhat + mock coprocessor testing - React/Vite + ethers v6 frontend integration - Vercel deployment with CORS proxy ## 版本 v3.3.0 ## 许可证 MIT

标签：ACL, AI代理, Bounty程序, CLI, CORS代理, ethers v6, fhEVM, FHEVM, Hardhat, LLM技能, Mock, SDK初始化, Sepolia, Solidity, Streamlit, WiFi技术, Zama, Zustand, 前端集成, 加密智能合约, 单元测试, 合约迁移, 同态加密, 安全漏洞, 数据可视化, 智能合约审计, 机密计算, 状态管理, 生产就绪, 访问控制