Fhevm

fhEVM Confidential Smart Contract Development

Build Solidity contracts where on-chain data stays encrypted using Fully Homomorphic Encryption.

Validation: This skill has been A/B tested against 15 prompts (7 demo + 8 adversarial traps), with one live verification run on 2026-05-09. Without this skill, vanilla LLM output triggers 47 distinct anti-pattern occurrences across 14 of the 20 patterns in the catalog (predicted), plus 9 anti-pattern occurrences in a single live run (verified — full transcript at validation/transcripts/2026-05-09-vanilla-erc20.md); only 1/15 vanilla outputs both compile and have no privacy leak. With this skill loaded, all of these move to 0 and 15/15 respectively. Full report and reproducibility protocol: validation/agent-effectiveness.md.

When to Use

Use this skill when any of these apply:

• Writing or modifying a Solidity contract that imports @fhevm/solidity
• Adding encrypted state (euint, ebool, eaddress) to an existing contract
• Reviewing fhEVM code (your own or AI-generated) for correctness or privacy leaks
• Building or modifying a frontend that uses @zama-fhe/relayer-sdk for client-side encryption or async decryption
• Migrating a regular Solidity contract to fhEVM
• Writing or debugging Hardhat tests that use fhevm.createEncryptedInput
• Designing data flow for any application where on-chain values must stay encrypted under threshold MPC

Symptoms in chat or code that should trigger this skill:

• "encrypted balance / score / vote / bid"
• API references: FHE.add, FHE.select, FHE.fromExternal, FHE.allowThis, FHE.makePubliclyDecryptable, ZamaEthereumConfig, externalEuintXX
• File patterns: @fhevm/solidity imports, *.sol files declaring euint* state, test files importing fhevm from hardhat, relayer-sdk in frontend deps
• Error patterns: ACL access denied, "ebool cannot be evaluated", FHE.decrypt is not a function, decryption returning garbage

When NOT to Use

This skill is overkill or off-topic for:

• Regular Solidity contracts with no encrypted state — vanilla Solidity guidance is enough; loading this skill adds noise.
• ZK-SNARK / ZK-STARK circuits that aren't fhEVM-related — different paradigm (zero-knowledge ≠ fully homomorphic).
• Concrete ML / TFHE-rs Rust applications — those use Python/Rust APIs and a different deployment model; this skill is Solidity-only.
• Generic Ethereum security audits where FHE is not present — use general security review skills, not this one.
• Contracts that only call fhEVM contracts but hold no encrypted state themselves — usually only the references/access-control.md cross-contract section is needed; full skill is unnecessary.

Development Philosophy

Think in ciphertexts, not plaintexts. This is the fundamental shift from regular Solidity.

You are not writing "if this, then that" logic anymore. You are writing "compute both branches, select the correct result homomorphically." Every if/else becomes FHE.select. Every require becomes a guard that silently clamps to zero on failure. Your contract always succeeds at the EVM level — the question is what the encrypted result contains.

Four-step approach to every fhEVM task:

1. Understand the goal — What data must stay private? What can be public? Define the privacy boundary before writing code.
2. Choose the right pattern — Use the decision tables below. Don't branch on encrypted values. Don't try to decrypt synchronously. Don't forget ACL.
3. Verify at each step — After every FHE operation, ask: "Did I re-grant ACL on the new ciphertext? Did I use FHE.select instead of if? Did I validate the input with FHE.fromExternal?"
4. Test with mock mode — Run npx hardhat test locally. Mock FHE simulates all operations without a real coprocessor. Verify the logic works before deploying.

How fhEVM Works (Architecture)

Understanding the architecture prevents entire classes of bugs:

User encrypts value (client-side, ZKPoK generated)
    ↓
Transaction carries encrypted handle (bytes32) + proof
    ↓
Contract calls FHE.fromExternal() → validates ZKPoK
    ↓
FHE.add(a, b) → FHE.sol → Impl.sol → FHEVMExecutor (on-chain)
    ↓
FHEVMExecutor does SYMBOLIC execution only:
  - Generates new handle via keccak256(op, operands, chainId, blockhash...)
  - Grants transient ACL permission for result
  - Emits event (e.g., FheAdd)
  - Meters HCU cost
    ↓
Off-chain coprocessor watches events, performs REAL TFHE computation
    ↓
Result ciphertext stored off-chain, indexed by the same handle

Key insight: The on-chain system is entirely symbolic. Handles (bytes32) are NOT ciphertexts — they are deterministic identifiers computed via keccak256. The actual encrypted data lives in 5 off-chain coprocessor nodes. Decryption requires 9 of 13 KMS MPC nodes (run by Etherscan, Fireblocks, Ledger, OpenZeppelin, etc. in AWS Nitro Enclaves). This is why:

• Every operation creates a new handle → FHE math produces a new ciphertext (different noise/randomness), so you must re-grant ACL permissions on the new handle
• Handles cannot be evaluated as booleans → no node has the secret key; the EVM literally cannot evaluate if (eboolHandle)
• Decryption requires the off-chain KMS → 9/13 threshold MPC, always async, no FHE.decrypt()
• Uninitialized handles are bytes32(0) → not encrypted zero, just an invalid pointer
• Operations are expensive → each FHE op involves noise management on large polynomial structures; bootstrapping refreshes noise but costs HCU

See references/architecture.md for the full 6-component system, TFHE principles, handle format, and HCU metering details.

Quick Start

git clone https://github.com/zama-ai/fhevm-hardhat-template.git my-fhevm-project
cd my-fhevm-project && npm install
npm test        # Run tests in mock mode
npm run compile # Compile contracts

Minimal contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import { FHE, euint64, externalEuint64 } from "@fhevm/solidity/lib/FHE.sol";
import { ZamaEthereumConfig } from "@fhevm/solidity/config/ZamaConfig.sol";

contract EncryptedCounter is ZamaEthereumConfig {
    euint64 private _count;

    function increment(externalEuint64 encValue, bytes calldata proof) external {
        euint64 value = FHE.fromExternal(encValue, proof);
        _count = FHE.add(_count, value);
        FHE.allowThis(_count);
        FHE.allow(_count, msg.sender);
    }
}

Decision Tables

When to use which encrypted type

Solidity pattern → fhEVM equivalent

When to load reference files

Encrypted Types (Summary)

Import only what you use: import { FHE, euint64, ebool, externalEuint64 } from "@fhevm/solidity/lib/FHE.sol";

FHE Operations (Summary)

Arithmetic (euint8–128): FHE.add, FHE.sub, FHE.mul, FHE.div*, FHE.rem*, FHE.min, FHE.max, FHE.neg *div/rem require plaintext right operand — encrypted divisor is NOT supported.

Comparison (→ ebool): FHE.eq, FHE.ne, FHE.ge, FHE.gt, FHE.le, FHE.lt

Branching: FHE.select(ebool, ifTrue, ifFalse) — the ONLY way to do conditional logic.

Random: FHE.randEuint8() – FHE.randEuint256(). Bounded: FHE.randEuint16(upperBound) (power-of-2). Transactions only, not view functions.

Type casting: FHE.asEuint32(plaintext) to encrypt. FHE.asEuint64(euint32Value) to upcast.

Scalar operations (one plaintext operand) are significantly cheaper. Prefer FHE.add(enc, 5) over FHE.add(enc1, enc2) when possible.

Operator overloading: With using FHE for *, you can write a + b instead of FHE.add(a, b). Supports +, -, *, &, |, ^, ~.

Access Control (ACL) — The #1 Source of Bugs

Every FHE operation creates a NEW ciphertext handle with ZERO permissions. Re-grant after EVERY operation:

euint64 newBalance = FHE.add(balance, amount);
_balances[to] = newBalance;
FHE.allowThis(newBalance);      // Contract can use it in future txs
FHE.allow(newBalance, to);      // Owner can request decryption

Input Validation

Users encrypt values client-side. Contracts validate via externalEuintXX + FHE.fromExternal:

function deposit(externalEuint64 encAmount, bytes calldata inputProof) external {
    euint64 amount = FHE.fromExternal(encAmount, inputProof);  // Validates ZKPoK
    _balances[msg.sender] = FHE.add(_balances[msg.sender], amount);
    FHE.allowThis(_balances[msg.sender]);
    FHE.allow(_balances[msg.sender], msg.sender);
}

Never accept raw euintXX as function parameters — always use externalEuintXX + proof.

Decryption (Always Async)

There is no FHE.decrypt(). Decryption goes through the off-chain Gateway → KMS threshold MPC:

1. On-chain: FHE.makePubliclyDecryptable(ct) — mark for decryption
2. Off-chain: relayer-sdk.publicDecrypt(handles) — get cleartext + proof
3. On-chain (optional): FHE.checkSignatures(handles, clearValues, proof) — verify

Frontend SDK: fhevmjs is renamed to @zama-fhe/relayer-sdk

If you are reading older Zama tutorials, blog posts, or third-party guides, you will see the package name fhevmjs. This is the previous name for the official frontend SDK. The current package is @zama-fhe/relayer-sdk (sometimes called "relayer-sdk"). Same intent, refreshed API, native ESM, and handles client-side encryption + async decryption end-to-end.

If a search engine sends an agent to a fhevmjs snippet, mentally rename it to @zama-fhe/relayer-sdk and use the API table in references/frontend-integration.md. Don't npm install fhevmjs on a new project — the package is no longer maintained for current Zama Protocol releases.

Configuration

import { ZamaEthereumConfig } from "@fhevm/solidity/config/ZamaConfig.sol";
contract MyContract is ZamaEthereumConfig { ... }  // Auto-detects chainId

Hardhat: must set evmVersion: "cancun" in solidity settings.

Testing (Hardhat Mock)

import { ethers, fhevm } from "hardhat";

it("should work", async function () {
    if (!fhevm.isMock) { this.skip(); }
    const enc = await fhevm.createEncryptedInput(contractAddr, alice.address)
        .add64(1000).encrypt();
    await contract.connect(alice).deposit(enc.handles[0], enc.inputProof);
});

Input methods: .addBool, .add8, .add16, .add32, .add64, .add128, .add256, .addAddress

Foundry alternative: forge-fhevm (early-stage) supports pure Solidity tests with native fuzz testing. See references/testing-foundry.md.

Confidential Token Design (ERC-7984)

When building encrypted ERC20 tokens, these rules prevent critical bugs:

• Decimals MUST be 6, not 18. euint64 max ≈ 18.4 quintillion. With 18 decimals → max ~18.4 tokens. With 6 decimals → max ~18.4 trillion tokens.
• Transfers never revert on insufficient balance — they silently transfer 0 (privacy preservation).
• Events emit type(uint256).max as placeholder amount — not the real encrypted value.
• balanceOf() takes no arguments — returns caller's own encrypted balance handle.
• transferFrom checks both balance AND allowance: FHE.and(hasBalance, hasAllowance).
• Composability trap: When contract A calls B's confidential transfer and it silently returns 0, A must check the effective result before updating its own state:

  euint64 transferred = token.confidentialTransfer(to, amount);
  ebool didTransfer = FHE.gt(transferred, FHE.asEuint64(0));
  // Only update state if transfer actually happened
  

OpenZeppelin Confidential Contracts

For production-grade ERC-7984 tokens, prefer the audited base contracts from @openzeppelin/confidential-contracts (verified against 0.4.0) over rolling your own:

npm install @openzeppelin/confidential-contracts

Note: The earlier @openzeppelin/contracts-confidential package is deprecated and renamed. Use @openzeppelin/confidential-contracts for any new project.

import { ERC7984 } from "@openzeppelin/confidential-contracts/token/ERC7984/ERC7984.sol";
import { ZamaEthereumConfig } from "@fhevm/solidity/config/ZamaConfig.sol";

contract MyConfidentialToken is ERC7984, ZamaEthereumConfig {
    constructor() ERC7984("My Token", "MTK", "https://example.com/uri") {}
}

(Constructor signature: ERC7984(string name_, string symbol_, string contractURI_).)

What ERC7984 already gives you — so you don't reinvent it:

• Encrypted balanceOf(address) with proper ACL re-grants on every transfer
• confidentialTransfer(to, externalEuint64, proof) + confidentialTransferFrom(...) with FHE.and(hasBalance, hasAllowance) checks
• Silent-fail-on-insufficient-balance pattern (returns the actually-transferred amount as euint64)
• Transfer / Approval events that emit type(uint256).max as the value placeholder (anti-pattern #16 prevention)

Override only domain-specific logic (mint/burn rules, transfer hooks). Do not re-implement ACL re-grants by hand — the base contract already does it correctly.

Standard extensions in @openzeppelin/confidential-contracts/token/ERC7984/extensions/ (v0.4.0):

• ERC7984ERC20Wrapper — bidirectional wrap/unwrap with a plaintext ERC-20 (see next section)
• ERC7984Votes — votes-style governance hooks for confidential supply
• ERC7984Freezable — admin-controlled per-account freezes
• ERC7984Restricted — allowlist / denylist gating
• ERC7984Omnibus — multi-account omnibus accounting
• ERC7984Rwa — real-world-asset hooks (admin-pause, force-transfer)
• ERC7984ObserverAccess — third-party observer ACL grants

Our examples/ConfidentialERC20.sol is a from-scratch reference implementation for didactic purposes; for new dApps subclass ERC7984 instead.

Wrap / Unwrap: ERC-7984 ↔ ERC-20

ERC-7984 tokens commonly need to bridge in/out of plaintext ERC-20 liquidity. The pattern:

1. Wrap — user deposits N plaintext ERC-20, receives encrypted balance of N in the ERC-7984 wrapper. The deposit amount is public (visible in the ERC-20 Transfer event) — privacy starts after wrapping.
2. Unwrap — user burns an encrypted ERC-7984 balance, an async decryption resolves the cleartext, and the underlying ERC-20 is released to the recipient. The unwrap amount becomes public on settlement (it has to, to release ERC-20).

@openzeppelin/confidential-contracts ships ERC7984ERC20Wrapper (abstract — you subclass it):

import { ERC7984 } from "@openzeppelin/confidential-contracts/token/ERC7984/ERC7984.sol";
import { ERC7984ERC20Wrapper } from "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984ERC20Wrapper.sol";
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import { ZamaEthereumConfig } from "@fhevm/solidity/config/ZamaConfig.sol";

contract WrappedUSDC is ERC7984ERC20Wrapper, ZamaEthereumConfig {
    constructor(IERC20 underlying)
        ERC7984ERC20Wrapper(underlying)
        ERC7984("Confidential USDC", "cUSDC", "")
    {}
}

Real wrapper API (v0.4.0, verified):

• wrap(address to, uint256 amount) returns (euint64) — pulls plaintext ERC-20 via safeTransferFrom, mints encrypted token; returns the encrypted amount actually wrapped (after rate division).
• unwrap(address from, address to, euint64 amount) returns (bytes32 requestId) — burns encrypted balance and triggers async KMS decryption to release plaintext ERC-20 to to.
• unwrap(address from, address to, externalEuint64 encryptedAmount, bytes calldata inputProof) returns (bytes32 requestId) — variant that takes a fresh externalEuint64 + ZK proof.
• unwrapAmount(bytes32 requestId) returns (euint64) — view to read the encrypted amount handle for a pending unwrap.
• ERC-1363 onTransferReceived is supported, so ERC-1363 tokens can transferAndCall directly into the wrapper (one-tx wrap).

Frontend flow (relayer-sdk):

// 1. Wrap: amount is plaintext, public on-chain (the privacy boundary starts AFTER this).
await usdc.approve(wrapper.address, 1_000_000n);                  // 1 USDC (6 decimals)
const wrappedHandle = await wrapper.wrap(user.address, 1_000_000n);
// wrappedHandle is an euint64 — the actually-wrapped amount, encrypted.

// 2. Encrypted balance now lives inside the wrapper; only the user can decrypt off-chain.
const handle = await wrapper.balanceOf(user.address);
const cleartext = await fhevm.userDecrypt([handle], sig);          // off-chain only

// 3. Encrypted confidential transfer to another wrapper user — fully private.
const enc = fhevm.createEncryptedInput(wrapper.address, user.address);
enc.add64(50_000n);
const { handles, inputProof } = await enc.encrypt();
await wrapper.confidentialTransfer(recipient, handles[0], inputProof);

// 4. Unwrap: returns a requestId; KMS async-decrypts and releases plaintext ERC-20.
//    The unwrap amount IS public on settlement (necessary to move ERC-20).
const requestId = await wrapper.unwrap(user.address, recipient, handles[0], inputProof);
// Listen for the wrapper's settlement event; ERC-20 transfers to `recipient` once KMS finalises.

Privacy boundary reminder: wrap/unwrap amounts are public by necessity (they cross a plaintext boundary). What stays private is balances and intra-system transfers between wraps. Document this in your dApp UI so users don't assume wrapping is fully confidential.

Anti-Patterns — STOP and Read Before Writing Code

20 anti-patterns are catalogued in anti-patterns/ANTI-PATTERNS.md, organized in three layers:

• Logic correctness (#1–9) — won't run / won't compile / undefined behavior.
• Operational correctness (#10–14) — works in isolation, breaks under realistic conditions.
• Privacy boundary (#15–20) — works and tests pass, but state still leaks via off-chain side channels (calldata, events, ordering, mempool, AA bundles).

Top 12 quick reference (full list + production-grade #15–20 in the catalog):

Gas Budget (HCU)

Transaction limit: 20M HCU total, 5M HCU depth. Key costs (non-scalar, euint64):

• add/sub: 162K — max ~123/tx
• mul: 596K — max ~33/tx
• select: 55K (constant) — cheap
• trivialEncrypt/cast: 32 — free

Rule: use the smallest type that fits. Prefer scalar ops. Avoid rem.

Examples

examples/ConfidentialTreasury.test.ts — Complete test file (15 tests, verified passing) demonstrating all SKILL.md testing patterns.

Pre-Deployment Checklist

• No if/else/require on encrypted values — all use FHE.select + silent failure
• FHE.allowThis() after every operation storing a new ciphertext
• FHE.allow(ct, user) for every user needing decrypt access
• All inputs use externalEuintXX + FHE.fromExternal() + proof
• No encrypted divisors, no arithmetic on euint256/eaddress
• Encrypted state explicitly initialized (not relying on default)
• Contract inherits ZamaEthereumConfig
• HCU budget checked for loops and complex operations
• Decryption is async — no FHE.decrypt() calls
• Test signers match createEncryptedInput addresses
• Run node scripts/fhevm-lint.js path/to/Contract.sol — automated check of 12 of the 20 anti-patterns (regex-based, zero dependencies, <100ms)

File Index