# Zama fhEVM AI Agent Skill Package

Give any AI coding assistant — Claude, Cursor, Windsurf, Copilot, Cline, Codex — accurate fhEVM knowledge and real executable tools for building confidential smart contracts on [Zama's fhEVM](https://docs.zama.org/protocol).

This package has three parts that work together:

1. **An MCP server** — a real npm package your AI agent can call to scaffold projects, compile contracts, deploy to Sepolia, check wallet balances, look up protocol addresses, verify contracts, encrypt values, check ACL, run tests, and decode errors
2. **Rules files** — drop-in config for every major AI coding tool so it stops hallucinating fhEVM code
3. **Error decoder** — a catalog of every known fhEVM error with root cause and exact fix

**npm:** [`@just-jelly/mcp-server`](https://www.npmjs.com/package/@just-jelly/mcp-server) — v2.2.6 — 32 tools

---

## 1. MCP Server

The MCP server is an npm package. Pick one of two ways to use it:

#### Option A — npx (no install, always latest)

```bash
npx -y @just-jelly/mcp-server
```

Use this config in your AI tool:

```json
{
  "mcpServers": {
    "fhevm": {
      "command": "npx",
      "args": ["-y", "@just-jelly/mcp-server"],
      "env": {
        "FHEVM_PRIVATE_KEY": "0x_your_deployer_private_key",
        "FHEVM_RPC_URL":     "https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY",
        "ETHERSCAN_API_KEY": "optional_for_auto_verification"
      }
    }
  }
}
```

#### Option B — Global install (faster startup, no npx delay)

```bash
npm install -g @just-jelly/mcp-server
```

Then use `fhevm-mcp` as the command instead of npx:

```json
{
  "mcpServers": {
    "fhevm": {
      "command": "fhevm-mcp",
      "args": [],
      "env": {
        "FHEVM_PRIVATE_KEY": "0x_your_deployer_private_key",
        "FHEVM_RPC_URL":     "https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY",
        "ETHERSCAN_API_KEY": "optional_for_auto_verification"
      }
    }
  }
}
```

### Connect to your AI tool

> **The two key fields:** `FHEVM_PRIVATE_KEY` and `FHEVM_RPC_URL` live in the MCP config `env` block — you never need a `.env` file in your project. When deploy/test tools run Hardhat, these are automatically forwarded to the subprocess.
>
> **RPC URL:** Use a private RPC endpoint (Alchemy, Infura, QuickNode). The public BlastAPI fallback works for basic contract calls but rate-limits `eth_getBalance`. A free Alchemy Sepolia key is all you need.
>
> **Prefer not to hardcode?** Set the vars in your shell profile (`export FHEVM_PRIVATE_KEY=0x...` in `~/.zshrc`) and use a tiny wrapper script instead. See [DEPLOYMENT.md](zama-fhevm-skill/DEPLOYMENT.md#avoiding-hardcoded-keys) for the exact pattern.

| AI Tool | Where to put the config |
|---|---|
| Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Code CLI | `claude mcp add fhevm -- npx -y @just-jelly/mcp-server` then `claude mcp set-env fhevm FHEVM_PRIVATE_KEY 0x...` |
| Cursor | `.cursor/mcp.json` in project root |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| OpenAI Codex | `~/.codex/config.json` |
| Cline (VS Code) | Cline sidebar → Settings → MCP Servers |

### 31 Tools

#### Wallet & Config
| Tool | What it does |
|---|---|
| `setup_mcp_config` | Generate exact config JSON for any AI tool — shows where to paste your FHEVM_PRIVATE_KEY |
| `check_wallet_balance` | Check ETH balance on Sepolia — auto-derives address from FHEVM_PRIVATE_KEY |
| `get_faucet_links` | All 5 Sepolia faucets with daily limits and requirements |

#### Protocol Addresses
| Tool | What it does |
|---|---|
| `get_protocol_addresses` | Full Sepolia address book: core fhEVM, Zama tokens, all 8 cToken wrappers, staking, governance, fees |
| `verify_on_etherscan` | Verify deployed contract source on Etherscan (uses ETHERSCAN_API_KEY from config) |
| `watch_decryption_callback` | Polling script + test pattern for FHE.requestDecryption() async callbacks |
| `get_confidential_wrapper_code` | Complete TypeScript for mint→wrap→transfer→balance on any cToken wrapper |

#### Project Setup
| Tool | What it does |
|---|---|
| `scaffold_fhevm_project` | Creates a complete Hardhat project — 4 templates: minimal, token, voting, auction |
| `generate_hardhat_config` | Generate hardhat.config.ts with all correct settings |
| `generate_vite_config` | Generate Vite config with required CORS headers for fhEVM WASM |
| `check_dependencies` | Scan package.json for common fhEVM dependency errors |

#### Compile & Deploy
| Tool | What it does |
|---|---|
| `compile_solidity` | Compiles contracts, returns fhEVM-specific error explanations |
| `deploy_contract` | Deploys to Sepolia or localhost — FHEVM_PRIVATE_KEY forwarded automatically |
| `run_hardhat_tests` | Runs tests with fhEVM failure analysis (mock + Sepolia modes) |

#### Code Generation
| Tool | What it does |
|---|---|
| `generate_confidential_contract` | Generates full contracts for 9 patterns: token, vault, voting, auction, payroll, lending, identity, game, **erc7984** |
| `generate_fhevm_test` | Test boilerplate with encrypt/decrypt patterns |
| `generate_frontend_dapp` | Complete React dApp with CORS config, balance reveal, transfer UI |

#### Encryption
| Tool | What it does |
|---|---|
| `encrypt_value` | Generates complete frontend + Node.js encryption code for any type |
| `encrypt_multiple_values` | Packs multiple values into one input proof (gas efficient) |
| `get_encrypted_balance` | Reads a ciphertext handle + generates full re-encryption frontend code |
| `read_contract_state` | Calls any view function on a deployed contract via your FHEVM_RPC_URL |

#### ACL
| Tool | What it does |
|---|---|
| `check_acl_permission` | Live on-chain ACL check — is this address allowed to use this handle? |
| `explain_acl_pattern` | Returns production Solidity for 6 ACL scenarios |

#### Analysis & Errors
| Tool | What it does |
|---|---|
| `verify_fhevm_contract` | Static analysis — finds missing `allowThis`, unverified inputs, wrong patterns |
| `decode_fhevm_error` | Decodes any fhEVM error → root cause + exact fix (55+ patterns, all Solidity custom errors) |

#### Network & Gas
| Tool | What it does |
|---|---|
| `get_network_config` | All Sepolia/mainnet addresses + SDK initialization code |
| `estimate_fhe_gas` | Gas cost model + optimization strategies |

#### Tutorials
| Tool | What it does |
|---|---|
| `get_fhevm_tutorial` | Step-by-step tutorials: quickstart, token, voting, frontend, re-encryption, on-chain-decryption, testing, deployment, OpenZeppelin |
| `explain_fhe_type` | Deep reference for every FHE type — euint8→256, ebool, eaddress, casting, ops table |
| `explain_coprocessor` | Architecture diagram, async flow, gas model, mock vs Sepolia |
| `explain_erc7984` | **New** — ERC-7984 + OZ Confidential Contracts reference: standard overview, IConfidentialERC20 interface, all OZ base contracts (Mintable/WithErrors/Votes/Vesting), wrap/unwrap Gateway pattern, PLACEHOLDER events, testing, migration from ERC-20 |
| `list_tools` | List all 32 tools with descriptions |

---

## 2. Rules Files

Drop-in rules for every major AI coding tool. Copy the right file(s) into your fhEVM project and the AI immediately knows how to write correct confidential contracts.

```
zama-fhevm-skill/
├── SKILL.md                          → Claude Code (load as a skill)
├── CLAUDE.md                         → Claude Code (auto-loaded in project)
├── AGENTS.md                         → OpenAI Codex (auto-loaded in project)
├── .cursor/rules/
│   ├── fhevm-core.mdc               → Cursor — always active (alwaysApply: true)
│   ├── fhevm-solidity.mdc           → Cursor — activates on *.sol files
│   ├── fhevm-frontend.mdc           → Cursor — activates on src/**/*.{ts,tsx}
│   └── fhevm-testing.mdc            → Cursor — activates on *.test.{ts,js}
├── .windsurfrules                    → Windsurf (auto-loaded in project)
├── .github/copilot-instructions.md  → GitHub Copilot (auto-loaded in project)
└── .clinerules/fhevm.md             → Cline / RooCode (auto-loaded in project)
```

**Copy what you need:**

```bash
# Cursor
cp -r zama-fhevm-skill/.cursor  your-project/.cursor

# Windsurf
cp zama-fhevm-skill/.windsurfrules  your-project/.windsurfrules

# GitHub Copilot
cp -r zama-fhevm-skill/.github  your-project/.github

# OpenAI Codex
cp zama-fhevm-skill/AGENTS.md  your-project/AGENTS.md

# Cline
cp -r zama-fhevm-skill/.clinerules  your-project/.clinerules

# Claude Code
cp zama-fhevm-skill/CLAUDE.md  your-project/CLAUDE.md
```

### What the rules teach every AI tool

The rules enforce 10 patterns that AI consistently gets wrong without them:

1. `FHE.allowThis()` after every ciphertext assignment — without this the next tx reverts with `ACL: Not allowed`
2. `FHE.fromExternal(enc, proof)` to verify inputs before use
3. `FHE.select(condition, a, b)` for branching — `if(ebool)` is a compile error
4. Initialize mapping slots before first FHE operation — `bytes32(0)` reverts immediately
5. `evmVersion: "cancun"` in hardhat.config.ts — missing this breaks deployment
6. Inherit the correct network config contract per chain
7. `chai@^4` only — v5 breaks `@fhevm/hardhat-plugin`
8. `@fhevm/hardhat-plugin` must be the first import in hardhat.config.ts
9. Plaintext divisors only — `FHE.div(a, 100)` not `FHE.div(a, b)`
10. Fresh `inputProof` per transaction — reusing a proof fails ZK verification

---

## 3. Error Decoder

`zama-fhevm-skill/errors/ERRORS.md` — 55+ fhEVM errors across 13 categories, each with root cause, exact code fix, and prevention rule. Sourced from real fhEVM Solidity contract source (`FHE.sol`, `ACL.sol`, `InputVerifier.sol`).

Also available as the `decode_fhevm_error` MCP tool — your AI can call it live during development.

**13 categories:**
- ACL / access control errors
- Handle and zero-handle errors (`HandlesAlreadySavedForRequestID`, `NoHandleFoundForRequestID`, `UnsupportedHandleType`)
- Input proof / ZK verification errors (`InputLengthAbove64Bytes/128Bytes/256Bytes`, `InvalidKMSSignatures`)
- Input length / type errors — real Solidity custom errors from fhEVM source
- Decryption / KMS / callback errors
- Hardhat and compilation errors
- Solidity type errors
- Gas / computation errors
- Frontend SDK / WASM errors
- Testing errors
- Deployment / network errors
- OpenZeppelin confidential contracts errors
- MCP server / config errors

---

## Sepolia Addresses

### Core fhEVM

| Contract | Address |
|---|---|
| ACL | `0x687820221192C5B662b25367F70076A37bc79b6c` |
| KMS Verifier | `0x1364cBBf2cDF5032C47d8226a6f6FBD2AFCDacAC` |
| Input Verifier | `0xbc91f3daD1A5F19F8390c400196e58073B6a0BC4` |
| Chain ID | `11155111` |
| Relayer | `https://relayer.testnet.zama.cloud` |

### Confidential Token Wrappers (Mock — freely mintable underlying)

| Symbol | Wrapper Address |
|---|---|
| `cUSDCMock` | `0x7c5BF43B851c1dff1a4feE8dB225b87f2C223639` |
| `cUSDTMock` | `0x4E7B06D78965594eB5EF5414c357ca21E1554491` |
| `cWETHMock` | `0x46208622DA27d91db4f0393733C8BA082ed83158` |
| `cBRONMock` | `0xaa5612FA27c927a0c7961f5AEFEE5ba3A0F9C891` |
| `cZAMAMock` | `0xf2D628d2598aF4eAF94CB76a437Ff86CA78FfbFB` |

Use `get_protocol_addresses` for the full book including staking, governance, and fee contracts.

---

## License

BSD-3-Clause-Clear — same as Zama's fhEVM codebase.