A Claude Code skill bundle for building confidential smart contracts on Zama's FHEVM — fully homomorphic-encryption EVM. Authored by BootNode for Zama Bounty Track Mainnet S2.
The bundle wraps the FHEVM v0.11.x stack into 12 routed skills covering protocol concepts, contract authoring, ERC-7984 confidential tokens, decryption flows, testing, static analysis, and React/Next.js + Vite frontends. A canonical Hardhat workspace ships alongside in project/, and /create-template scaffolds either contracts, frontend, or both into a fresh directory in seconds.
| Path | What it is |
|---|---|
skills/fhevm-overview/ |
Protocol mental model — coprocessor, KMS, gateway, relayer; ZKPoK input-proof flow; v0.9+ async decryption |
skills/fhevm-setup/ |
Hardhat workspace bootstrap; hardhat vars workflow; pinned versions |
skills/fhevm-contracts/ |
@fhevm/solidity@0.11.x API: encrypted types, FHE.* ops, ACL lifecycle, input proofs, control-flow patterns |
skills/fhevm-erc7984/ |
OpenZeppelin confidential tokens: IERC7984, FHESafeMath, the v0.4 extension family, 10 DeFi blueprints |
skills/fhevm-decryption/ |
User decryption + the v0.9 three-step public-decrypt pattern via @zama-fhe/sdk@3.0.0 |
skills/fhevm-testing/ |
Mocha + Hardhat patterns; hre.fhevm.isMock gating; mock KMS proof construction; three-gate ship checklist |
skills/fhevm-frontend/ |
React (Vite + Next.js App Router) integration; ZamaProvider; encrypt/decrypt hooks; ERC-7984 wrap/unwrap UI |
skills/fhevm-antipatterns/ |
v0.11-era rename catalogue, the 12 high-frequency footguns, debug checklist |
skills/fhevm-static-analysis/ |
Slither / Aderyn / Semgrep / Halmos integration on FHEVM contracts (incl. ZamaConfig source-map workaround) |
skills/create-template/ |
/create-template wizard — scaffold contracts-only / frontend-only / both into a new repo |
project/ |
Canonical Hardhat workspace — three flagship contracts (counter, ERC-7984 token, voting), Sepolia + mock tests, deploy scripts |
templates/frontend-next/, templates/frontend-vite/ |
React frontend skeletons consumed by /create-template |
This repo is packaged as a Claude Code plugin named bn-fhevm. Once installed, the ten skills surface as /bn-fhevm:fhevm-overview, /bn-fhevm:fhevm-contracts, etc. — namespaced so they don't collide with skills from other plugins.
From any Claude Code session:
/plugin marketplace add github:BootNodeDev/zama-s2-bounty-skills
/plugin install bn-fhevm
Copy the plugin into a target directory in one command:
mkdir -p /path/to/your/project
curl -fsSL https://raw.githubusercontent.com/BootNodeDev/zama-s2-bounty-skills/main/scripts/install.sh | bash -s /path/to/your/projectThe target's .claude-plugin/plugin.json + skills/ get populated. Per-file overwrite prompts; non-interactive runs (CI, piped) default to "no".
git clone https://github.com/BootNodeDev/zama-s2-bounty-skills.git
cd zama-s2-bounty-skills
./scripts/copy-plugin.sh /path/to/your/projectnpm --prefix project install
npm --prefix project test # mock-mode tests
npm --prefix project run test:sepolia # real Sepolia (requires hardhat vars)From inside Claude Code, with this plugin installed:
/bn-fhevm:create-template
/create-template is an interactive wizard. Choose:
contracts— copiesproject/into your target directoryfrontend (Next.js)orfrontend (Vite)— copies the matching templateboth— contracts + frontend in one shot
It customizes package.json metadata, .env defaults, and the Sepolia RPC URL via AskUserQuestion prompts — no hand-editing.
Three prompts that exercise different parts of the bundle. Drop any of them into a Claude Code session in a project with these skills available.
Scaffold a fresh FHEVM Hardhat workspace at
./encrypted-counterusing/create-template, then implement a counter whose value is aneuint64readable only by the deployer via user decryption. Grant ACL withFHE.allowThisafter every state write andFHE.allow(deployer)in the constructor. Add Mocha tests that pass in mock mode (hre.fhevm.isMock) anduserDecryptEuintthe value to assert it.
Exercises: create-template, fhevm-setup, fhevm-contracts, fhevm-testing, fhevm-decryption.
Implement an ERC-7984 confidential token with operator support (
setOperator, noapprove/allowance) and an ERC20-wrapper path usingERC7984ERC20Wrapper. UseFHESafeMath.tryIncrease/tryDecreasefor all balance mutations. Then add a Next.js App Router page usingZamaProviderfrom@zama-fhe/react-sdk@3.0.0with a wrap → transfer → unwrap flow. Include tests for the operator-pattern transfer path, and run Slither against the contracts (use the canonicalslither .invocation, notnpx slither).
Exercises: fhevm-erc7984, fhevm-frontend, fhevm-testing, fhevm-static-analysis.
Audit
contracts/for the 12 FHEVM antipatterns, the v0.11 rename catalogue (TFHE→FHE,SepoliaZamaFHEVMConfig→ZamaEthereumConfig,ConfidentialFungibleToken→ERC7984,TFHESafeMath→FHESafeMath,isUserAllowed→canTransact), and any remainingFHE.requestDecryptionoracle callbacks. List findings ordered by severity, then propose a migration patch that replacesFHE.requestDecryptionwith the v0.9 three-stepmakePubliclyDecryptable→ off-chainpublicDecrypt→FHE.checkSignaturesflow.
Exercises: fhevm-antipatterns (incl. references/v0.11-migration.md), fhevm-decryption, fhevm-contracts.
- Solidity
0.8.27(evmVersion: cancun) - Hardhat
2.28.x+@fhevm/hardhat-plugin@0.4.2(mock coprocessor onhardhatnetwork) @fhevm/solidity@0.11.1,@fhevm/mock-utils@0.4.2,@openzeppelin/confidential-contracts@0.4.0@zama-fhe/sdk@3.0.0(frontend),@zama-fhe/relayer-sdk@0.4.1exact (Hardhat-side)- Node
>= 20(contracts),>= 22(frontend SDK)
Full pinned table lives in skills/fhevm-overview/SKILL.md.
architecture.md— repo structure + FHEVM data flowCLAUDE.md— agent conventions for working in this repoproject/README.md— Hardhat workspace usage + customizations vs upstreamfhevm-hardhat-template
MIT — see LICENSE.