0xe1337/fhevm-skill/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: