FHEVM Agent

Production-ready AI coding agent skill for building confidential smart contracts and dApps with the Zama Protocol.

fhevm-agent gives AI coding agents the context, code patterns, templates, and guardrails they need to build, test, deploy, and integrate FHEVM applications correctly. It is designed for agents such as Codex, Claude Code, Cursor, Windsurf, and other coding assistants that can read a SKILL.md file or project-local instructions.

Why This Exists

Most AI coding agents do not reliably know FHEVM-specific development patterns:

• encrypted Solidity types such as euint64, ebool, and eaddress
• external encrypted inputs and input proofs
• FHE.allowThis, FHE.allow, and FHE.allowTransient
• user decryption and public decryption flows
• Relayer SDK frontend integration
• ERC-7984 confidential tokens and wrapping flows

This skill turns those patterns into a reusable agent operating guide, with examples and templates that produce working code.

What It Covers

• FHEVM architecture and on-chain encrypted computation
• Hardhat project setup using a bundled Zama-style scaffold
• Solidity encrypted types and FHE operations
• Input proofs with FHE.fromExternal
• ACL permissions with FHE.allow, FHE.allowThis, and FHE.allowTransient
• User decryption with EIP-712 signing
• Public decryption and proof verification
• Relayer SDK frontend integration
• Hardhat tests for encrypted contracts
• OpenZeppelin Confidential Contracts and ERC-7984
• ERC-7984 confidential transfers, balance decryption, wrapping, and unwrapping
• Advanced x402-style agentic payment patterns
• Common FHEVM anti-patterns and failure modes

Repository Structure

fhevm-agent/
|-- SKILL.md
|-- AGENTS.md
|-- CLAUDE.md
|-- agents/
|   `-- openai.yaml
|-- references/
|   |-- architecture.md
|   |-- solidity-patterns.md
|   |-- encrypted-types-and-ops.md
|   |-- access-control.md
|   |-- input-proofs.md
|   |-- decryption.md
|   |-- frontend-relayer-sdk.md
|   |-- testing-hardhat.md
|   |-- deployment.md
|   |-- erc7984-confidential-tokens.md
|   |-- agentic-payments-and-x402.md
|   |-- anti-patterns.md
|   `-- agent-evaluation.md
|-- examples/
|   |-- confidential-voting/
|   |-- confidential-token-erc7984/
|   |-- sealed-bid-auction/
|   `-- private-payroll/
|-- templates/
|   |-- hardhat-app/
|   |-- private-counter/
|   |-- frontend-hooks/
|   `-- hardhat-deploy/
`-- scripts/
    `-- validate-fhevm-agent.sh

Installation

Install directly from the public GitHub repository with the open skills CLI:

npx skills add Femtech-web/FHEVM-Agent

Or use the full GitHub URL:

npx skills add https://github.com/Femtech-web/FHEVM-Agent

To install to specific agents:

npx skills add Femtech-web/FHEVM-Agent -a codex -a claude-code

To install globally:

npx skills add Femtech-web/FHEVM-Agent -g

You can also copy the fhevm-agent folder into your agent's skill directory, or keep it in your repository and tell the agent where it lives.

Examples:

# Project-local usage
cp -R fhevm-agent ./skills/fhevm-agent

# Codex/OpenAI-style user skill directory
cp -R fhevm-agent ~/.codex/skills/fhevm-agent

# Generic agent skill directory
cp -R fhevm-agent ~/.agents/skills/fhevm-agent

If your tool does not have a formal skill system, paste or reference SKILL.md and allow the agent to read the references/, examples/, and templates/ folders as needed.

Quick Use

After installation, ask your AI coding agent to use the fhevm-agent skill by name.

Example prompt:

Using the fhevm-agent skill, create a confidential allowance vault with Zama FHEVM.

Users should be able to deposit encrypted allowance amounts, decrypt only their own balance, and privately spend from their allowance. If a user tries to spend more than they have, spend 0 using confidential logic instead of revealing anything or reverting.

Please include the smart contract, Hardhat tests, deployment scripts, and any frontend integration notes needed for encrypted inputs and user decryption. Run compile and tests, then summarize what passed and anything that still needs attention.

Short prompt:

Use the fhevm-agent skill to build a confidential voting dApp with tests and deployment scripts.

For tools without named skill invocation, point the agent at the installed SKILL.md file or this repository folder and ask it to follow the skill.

Standalone Hardhat Scaffold

The skill includes a bundled Hardhat app scaffold at:

templates/hardhat-app/

This is important for standalone use. Agents do not need access to any local Zama repository to create a proper FHEVM project. The scaffold includes:

• Zama/FHEVM Hardhat plugin setup
• Hardhat deploy
• TypeChain
• Sepolia and local network wiring
• Cancun EVM target
• FHEVM-compatible dependency versions
• deploy script template

Maintainer Validation

Run the built-in structure validator after changing this skill package:

./scripts/validate-fhevm-agent.sh

Expected output:

fhevm-agent skill structure looks good.

The skill has also been validated through manual and independent agent trials.

Manual trials:

Trial	Result
Confidential voting	3 passing
ERC-7984 confidential token	4 passing
Sealed-bid auction	2 passing

Independent agent trials:

• Codex generated a confidential voting project that compiled and passed tests.
• Claude Code generated working contract logic and tests, then exposed scaffolding/tooling issues that were patched back into the skill.

See references/agent-evaluation.md and the external evaluation logs for repeatable trial prompts and expected checks.

Example Capabilities

Ask an agent to build:

Write me a confidential voting contract using FHEVM.

Build an ERC-7984 confidential token with encrypted balances and private transfers.

Create a sealed-bid auction where only the winner is publicly revealed after the deadline.

Build a private payroll system using ERC-7984 confidential salary payments.

Create an x402-style confidential payment gate using ERC-7984 transfers.

Core Rules The Skill Enforces

• Use externalEuintXX, externalEbool, or externalEaddress plus bytes inputProof for encrypted user inputs.
• Convert external inputs with FHE.fromExternal.
• Call FHE.allowThis for stored encrypted state.
• Call FHE.allow for users who should decrypt a handle.
• Call FHE.allowTransient for cross-contract encrypted values.
• Use FHE.select instead of Solidity branching on encrypted conditions.
• Do not reveal private values in events, errors, or public state.
• Prefer ERC-7984 for confidential token accounting.
• Include compileable Hardhat tests and deploy scripts.

Official References

• Zama Protocol docs: https://docs.zama.org/protocol
• Solidity guides: https://docs.zama.org/protocol/solidity-guides
• Relayer SDK guides: https://docs.zama.org/protocol/relayer-sdk-guides
• FHEVM examples: https://docs.zama.org/protocol/examples
• ERC-7984 tutorial: https://docs.zama.org/protocol/examples/openzeppelin-confidential-contracts/erc7984/erc7984-tutorial
• React dApp template: https://github.com/zama-ai/fhevm-react-template
• OpenZeppelin Confidential Contracts: https://github.com/OpenZeppelin/openzeppelin-confidential-contracts

Notes

• Current target docs: FHEVM Solidity v0.11, Relayer SDK v0.4.
• Use Node.js 20 for the smoothest Hardhat 2 experience.
• Mainnet support should be added only when the user explicitly requests it and provides the required RPC/API configuration.

License

MIT