Fhevm

FHEVM Development Skill

Build confidential smart contracts with Fully Homomorphic Encryption on EVM chains using the Zama Protocol.

Installation

Copy the fhevm-skill/ directory to your AI tool's skills folder:

• Claude Code: ~/.claude/skills/fhevm/
• Cursor: .cursor/skills/fhevm/
• Windsurf: .windsurf/skills/fhevm/
• Copilot: .github/skills/fhevm/

Architecture

FHEVM uses a coprocessor model with 4 components:

User (browser)                          Coprocessor (FHE engine)
  │ encrypt via Relayer SDK                  │ executes actual FHE math
  ▼                                          ▲
Contract (Host Chain, EVM)  ──handles──►     │
  │ stores handles (bytes32)                 │
  │ symbolic execution only                  │
  ▼                                          │
ACL Contract ◄──── who can read what ──────► │
  │                                          │
  ▼                                          │
Gateway Chain ──── orchestrates ──────► KMS (Key Management Service)
                   decryption            │ threshold decryption
                                         │ multi-party computation
                                         │ no single party has the full key

How it works:

1. Host Chain (Ethereum/Sepolia): Your contracts live here. FHE operations are symbolic — when you call FHE.add(a, b), the chain produces a new handle but the real encrypted computation happens asynchronously in the coprocessor.

2. Coprocessor: Rust-based engine that executes the actual FHE math offchain. Receives operations from the host chain, processes ciphertexts, returns result handles.

3. ACL Contract: On-chain registry tracking who can access each encrypted handle. Every FHE.allow(), FHE.allowThis(), and FHE.allowTransient() writes to this contract.

4. KMS (Key Management Service): Handles decryption via threshold multi-party computation — the FHE secret key is split across multiple KMS nodes. No single node can decrypt alone. When FHE.makePubliclyDecryptable() is called, the KMS nodes cooperatively produce a decryption proof that can be verified on-chain via FHE.checkSignatures().

5. Gateway Chain (chainId 10901 for Sepolia): Orchestrates communication between the host chain and KMS for decryption requests.

6. Relayer SDK (@zama-fhe/relayer-sdk): Frontend library that handles client-side encryption (ZK proof generation) and coordinates decryption requests with the KMS via the Gateway.

Key implications:

• You NEVER see plaintext in contract logic (except at system boundaries like wrap/unwrap)
• All branching on encrypted values uses FHE.select(), not if/else
• Decryption is asynchronous — mark a value as decryptable, then verify the KMS proof separately
• The FHE key is never held by a single entity — threshold security via KMS

Picking the Right SDK Layer

Solidity has one current library (@fhevm/solidity); the off-chain stack has two layers, both first-class but for different jobs.

Solidity (on-chain)

Warning: fhevm-contracts was archived in 2025 and used the OLD TFHE library. It has been replaced by @openzeppelin/confidential-contracts which uses the new FHE library. Use the new package for all development.

Off-chain (tests + frontends)

Two layers cooperate — pick by the job, not by "which is newer". The high-level layer is built on top of the foundational layer; they aren't substitutes.

Rule of thumb: The foundational SDK is mandatory at the test layer (the hardhat-plugin pins it). Add the high-level Token API on top whenever you build a token UI. They're independent and can coexist in one app.

See references/sdk-v3-guide.md and references/react-sdk-guide.md for the Token API. See references/frontend-integration.md for the foundational SDK (which every test relies on).

Migrating from fhevmjs (deprecated)

If you have existing code using fhevmjs, migrate via this map. Do NOT mix fhevmjs and the new SDK in the same project — they target different protocol versions and will produce incompatible handles.

Migration checklist:

1. npm uninstall fhevmjs && npm install --save-exact @zama-fhe/relayer-sdk@0.4.1 (foundational; mandatory for tests). For new browser token UIs, additionally npm install @zama-fhe/sdk@3.x @zama-fhe/react-sdk@3.x.
2. Replace every import { ... } from "fhevmjs" with the right new import (see table above).
3. Update Solidity contracts: replace einput with externalEuintXX, TFHE.* with FHE.*. See the Solidity migration table at the top of this section.
4. Replace Gateway.requestDecryption(...) with FHE.makePubliclyDecryptable(...) + FHE.checkSignatures(...).
5. Run scripts/validate-fhevm.sh against contracts/ to catch any leftover legacy patterns.
6. Run npx hardhat test — every test must still pass.

Self-Correction Table

If you just generated code containing any of these, STOP and fix:

Agent Workflow

CRITICAL REMINDERS (read before writing ANY code):

• ERC-7984 tokens use confidentialTransfer/confidentialBalanceOf — NOT transfer/balanceOf
• Use Hardhat 2 (^2.28.4) — NOT Hardhat 3
• Call FHE.allowThis() + FHE.allow() after EVERY FHE operation that stores a value
• Functions receiving encrypted handles from other contracts need FHE.isSenderAllowed() check
• Encrypted operations NEVER revert — they silently return 0

When a user asks to create a new FHEVM project:

1. Scaffold: Clone fhevm-hardhat-template or create Hardhat project with FHEVM deps
2. Configure: Set evmVersion: "cancun" in hardhat.config.ts (use templates/hardhat.config.ts)
3. Write contract: Use templates/ as starting points. Always use the NEW FHE library
4. Apply ACL pattern: After every FHE operation that stores a value: allowThis + allow
5. Write tests: Use templates/test-template.ts as boilerplate. Test silent failures
6. Validate: Run scripts/validate-fhevm.sh against the contracts directory
7. Deploy: npx hardhat run scripts/deploy.ts --network sepolia then verify (use templates/deploy-template.ts — plain ethers, no hardhat-deploy)

When a user asks to add FHE to an existing contract:

1. Add @fhevm/solidity dependency
2. Inherit ZamaEthereumConfig — mandatory. This abstract contract's constructor calls FHE.setCoprocessor(...) with the canonical Ethereum mainnet + Sepolia coprocessor address. Without it, every FHE.* call reverts with "coprocessor not initialized" (the coprocessor address is address(0) by default). One contract, one inheritance — ZamaEthereumConfig covers both Sepolia and Mainnet because they share the same coprocessor topology. Do NOT look for a SepoliaConfig Solidity contract; only the ZamaEthereumConfig abstract base exists in @fhevm/solidity@0.11.x. (There IS a JS export named SepoliaConfig in @zama-fhe/relayer-sdk/{web,node} — that's the off-chain SDK config object passed to createInstance, a different layer. See references/frontend-integration.md.)
3. Replace plaintext state variables with encrypted types (uint256 balance → euint64 balance)
4. Replace if/require conditions with FHE.select patterns
5. Add ACL calls after every state mutation
6. Run scripts/validate-fhevm.sh

Quick Start

Node.js compatibility: Hardhat 2 officially supports Node 18 / 20 / 22. Node 24+ prints WARNING: ... not supported but generally works. Use nvm use 20 or nvm use 22 if you hit unexplained Hardhat errors. Drop tsconfig.json from templates/tsconfig.json into your project root to avoid TS5011 rootDir errors during npx hardhat test.

1. Project Setup

git clone https://github.com/zama-ai/fhevm-hardhat-template.git my-fhevm-project
cd my-fhevm-project && npm install
# Template does NOT include OpenZeppelin. Install for Ownable2Step, ReentrancyGuard, etc.:
npm install @openzeppelin/contracts@^5.6.1
# For ERC-7984 tokens, also install:
npm install @openzeppelin/confidential-contracts@^0.4.0

Key deps: @fhevm/solidity ^0.11.1, @fhevm/hardhat-plugin ^0.4.2, @zama-fhe/relayer-sdk EXACT 0.4.1 (no caret), @typechain/hardhat + @typechain/ethers-v6.

CRITICAL: Use Hardhat 2 (^2.22.0), NOT Hardhat 3. The @fhevm/hardhat-plugin is incompatible with Hardhat 3. If setting up from scratch instead of cloning the template:

# Two-step install. Step 1 uses --save-exact so that @zama-fhe/relayer-sdk
# lands as exactly "0.4.1" in package.json (default `npm install x@0.4.1`
# silently writes "^0.4.1" which can later resolve to 0.4.3 → plugin breaks).
npm install --save-dev --save-exact --legacy-peer-deps \
  @zama-fhe/relayer-sdk@0.4.1

# Step 2: everything else (carets are fine here).
npm install --save-dev --legacy-peer-deps \
  hardhat@^2.28.4 \
  @fhevm/solidity@^0.11.1 @fhevm/hardhat-plugin@^0.4.2 @fhevm/mock-utils@^0.4.2 \
  encrypted-types@^0.0.4 \
  @nomicfoundation/hardhat-chai-matchers@^2.1.0 @nomicfoundation/hardhat-ethers@^3.1.3 \
  @nomicfoundation/hardhat-verify@^2.0.0 \
  @typechain/hardhat @typechain/ethers-v6@^0.5.1 typechain@^8.3.2 \
  ethers@^6.16.0 \
  @openzeppelin/contracts@^5.6.1 @openzeppelin/confidential-contracts@^0.4.0

# Smoke test BEFORE writing any contracts — catches the most common install issues.
npx hardhat init    # if no project yet, otherwise skip
echo > contracts/Smoke.sol  # any minimal .sol file
npx hardhat compile  # MUST exit 0

Critical version pins (other versions silently break the toolchain):

• @zama-fhe/relayer-sdk@0.4.1 — exact, NOT caret. Use --save-exact (step 1 above) or your package.json will say ^0.4.1 and a future npm install may resolve 0.4.3, after which the plugin hard-fails: Invalid @zama-fhe/relayer-sdk version. Expecting 0.4.1. Got 0.4.3 instead.
• @nomicfoundation/hardhat-verify@^2.0.0 — the 2-series pin matters. Without it, npm install resolves to 3.0.17+ whose peerDep hardhat: ^3.4.0 silently requires Hardhat 3, breaking the smoke compile with Error: Cannot find module '.../hardhat/config' ... Did you mean to import "hardhat/config.js"?. Same Hardhat 2/3 split trap as hardhat-ethers.
• @typechain/ethers-v6@^0.5.1 AND typechain@^8.3.2 — both required. @typechain/hardhat has typechain as a peer dep that npm does not auto-install. Without @typechain/ethers-v6: Couldn't find ethers-v6. Without bare typechain: HH801: Plugin @typechain/hardhat requires the following dependencies to be installed: typechain.
• encrypted-types@^0.0.4 — transitive peer dep surfaced explicitly so newer plugin versions resolve cleanly. You don't import it directly; safe to keep, no direct usage in your code.
• hardhat-deploy is NOT installed by default. It transitively pulls zksync-web3@0.14.4, which crashes on ethers v6 at module load with Cannot read 'JsonRpcSigner' of undefined. Only install it if you need named-account deployment scripts, and pin a version compatible with your ethers major.
• Smoke test: run npx hardhat compile in an empty project right after install. If this fails, fix the install before writing any contracts.

Config must set evmVersion: "cancun" and viaIR: true (avoids stack-too-deep in complex FHE contracts).

ERC-7984 operator setup (replaces ERC-20 approve)

If your contract calls confidentialTransferFrom(user, …), the user must FIRST authorize your contract as an operator on the token (one tx, separate from the actual call):

// User-side, separate transaction:
token.setOperator(myContract, uint48(block.timestamp + 1 days));  // expiry = "until" timestamp
// Now myContract can call token.confidentialTransferFrom(user, ...) until that timestamp.

This is the ERC-7984 equivalent of approve(spender, amount) — but time-based, not amount-based. To revoke: setOperator(spender, 0).

Sepolia Deployment

For deploying to Sepolia testnet, you need:

RPC URLs (no API key needed for public RPCs):

https://ethereum-sepolia-rpc.publicnode.com
https://rpc.ankr.com/eth_sepolia
https://sepolia.infura.io/v3/YOUR_KEY  (if you have Infura)

Sepolia ETH faucets:

• https://www.alchemy.com/faucets/ethereum-sepolia
• https://cloud.google.com/application/web3/faucet/ethereum/sepolia
• https://faucets.chain.link/sepolia

2. 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 ConfidentialCounter is ZamaEthereumConfig {
    euint64 private _count;

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

    function getCount() external view returns (euint64) {
        return _count;
    }
}

3. Test It

import { ethers, fhevm } from "hardhat";
import { FhevmType } from "@fhevm/hardhat-plugin";

it("increments encrypted counter", async function () {
    const encrypted = await fhevm
        .createEncryptedInput(contractAddress, signer.address)
        .add64(42)
        .encrypt();
    await contract.add(encrypted.handles[0], encrypted.inputProof);

    const handle = await contract.getCount();
    const clear = await fhevm.userDecryptEuint(FhevmType.euint64, handle, contractAddress, signer);
    expect(clear).to.equal(42n);
});

Decision Trees

"Which encrypted type should I use?"

Is the value a boolean (true/false)?
  └─ Yes → ebool
  └─ No → Is it an Ethereum address?
       └─ Yes → eaddress
       └─ No → What's the value range?
            └─ 0-255 → euint8  (ages, scores, small enums)
            └─ 0-65535 → euint16  (years, small counts)
            └─ 0-4B → euint32  (timestamps, medium counts)
            └─ 0-18.4×10¹⁸ → euint64  (token amounts, balances — MOST COMMON)
            └─ Larger → euint128 or euint256
                 ⚠️ euint256: only eq/ne comparisons, no ordering (gt/lt/ge/le)

"How should I handle decryption?"

Who needs to see the plaintext?
  └─ Only the data owner (private) → User Decryption (EIP-712 flow)
       See: references/decryption-guide.md#user-decryption
  └─ Everyone / contract logic needs it → Public Decryption
       See: references/decryption-guide.md#public-decryption
  └─ A backend service on behalf of user → Delegated Decryption
       See: references/decryption-guide.md#delegated-decryption

"Which ACL function do I need?"

When is the encrypted value needed?
  └─ In a FUTURE transaction (stored in state) → FHE.allow(value, account)
       Also call: FHE.allowThis(value) so the contract can access it later
  └─ Only within THIS transaction (cross-contract call) → FHE.allowTransient(value, account)
       Cheaper gas (EIP-1153 transient storage), cleared after tx
  └─ Anyone should be able to decrypt it → FHE.makePubliclyDecryptable(value)

"Which library/import should I use?"

Using @openzeppelin/confidential-contracts (ERC-7984)? → FHE + ZamaEthereumConfig + ERC7984 base
Writing a standalone contract from scratch? → FHE + ZamaEthereumConfig

"Cross-contract encrypted value?"

Same transaction? → FHE.allowTransient(value, target) before the call
Future transaction? → FHE.allow(value, target)
Forwarding user's input proof? → STOP: proofs bound to msg.sender. Use 2-tx flow.

"My FHEVM code doesn't work — what's wrong?"

Is it a compilation error?
  └─ "type not found" → Check imports: use @fhevm/solidity/lib/FHE.sol
  └─ "div/rem type mismatch" → Divisor must be plaintext: FHE.div(enc, uint64)
  └─ "gt/lt not found for euint256" → euint256 only supports eq/ne
  └─ "cannot be declared as view" → FHE ops modify state. Remove view/pure modifier
  └─ "Cannot determine a test runner" → You have Hardhat 3 — downgrade to Hardhat 2
  └─ "invalid: ^2.0.0 from @fhevm/hardhat-plugin" → Same: npm install hardhat@^2.22.0
Is it a runtime revert?
  └─ "Sender not allowed" → Missing FHE.allowTransient() before cross-contract call
  └─ Reverts on FHE.rand → Random must be in non-view function
  └─ "evmVersion" errors → Set evmVersion: "cancun" in hardhat.config
Is it a silent failure (no revert, but wrong result)?
  └─ Transfer sends 0 → Insufficient balance (by design). Check with handle comparison
  └─ Contract can't read its own data → Missing FHE.allowThis() after operation
  └─ Decryption returns nothing → Missing FHE.allow(value, user)

Core Patterns

Pattern 1: The ACL Triple (MANDATORY after every FHE operation that produces a stored value)

balances[user] = FHE.add(balances[user], amount);
FHE.allowThis(balances[user]);    // Contract can use it in future tx
FHE.allow(balances[user], user);  // User can decrypt their own balance

Forgetting allowThis is the #1 FHEVM bug — the contract creates a new handle but loses access to it because each FHE operation produces a NEW handle with NO inherited permissions.

Pattern 2: Silent Transfer (no-revert on insufficient balance)

function _transfer(address from, address to, euint64 amount) internal {
    ebool canTransfer = FHE.le(amount, balances[from]);
    euint64 transferValue = FHE.select(canTransfer, amount, FHE.asEuint64(0));

    balances[from] = FHE.sub(balances[from], transferValue);
    FHE.allowThis(balances[from]);
    FHE.allow(balances[from], from);

    balances[to] = FHE.add(balances[to], transferValue);
    FHE.allowThis(balances[to]);
    FHE.allow(balances[to], to);
}

FHE transfers NEVER revert on insufficient balance — reverting would leak balance information. They silently transfer 0. This is by design, not a bug.

⚠ Asymmetry — uninitialised handles DO revert. OpenZeppelin's ERC7984._transfer reverts with ERC7984ZeroBalance(from) if the sender's balance handle has never been written (slot is bytes32(0)). The "silent transfer 0" rule applies only after the slot has been initialised at least once. To exercise the silent-fail path in tests, mint at least 1 unit to the sender first, then test with amount > balance. See references/common-pitfalls.md §6c. Selector for the revert: 0x5ff91cdc.

Pattern 3: Encrypted Conditional Logic (use select, never if)

// WRONG — leaks which branch was taken
if (FHE.decrypt(condition)) { x = a; } else { x = b; }

// CORRECT — preserves confidentiality
euint64 result = FHE.select(condition, a, b);

Pattern 4: Input Validation

// Single encrypted input:
function deposit(externalEuint64 encAmount, bytes calldata inputProof) external {
    euint64 amount = FHE.fromExternal(encAmount, inputProof);
}

// Multiple encrypted inputs share ONE proof:
function swap(externalEuint64 encIn, externalEuint64 encOut, bytes calldata inputProof) external {
    euint64 amountIn = FHE.fromExternal(encIn, inputProof);   // Same proof
    euint64 amountOut = FHE.fromExternal(encOut, inputProof); // Same proof
}

// For already-verified handles (e.g., from another contract):
function processHandle(euint64 amount) external {
    require(FHE.isSenderAllowed(amount), "Sender not allowed");
}

Pattern 5: Cross-Contract FHE (the 5-step pattern)

// 1. Encrypt amount
euint64 encAmount = FHE.asEuint64(amount);
// 2. Grant transient access to the receiving contract
FHE.allowTransient(encAmount, address(token));
// 3. Call the other contract
euint64 transferred = token.confidentialTransferFrom(msg.sender, address(this), encAmount);
// 4. Grant persistent access to THIS contract for future use
FHE.allowThis(transferred);  // equivalent to FHE.allow(transferred, address(this))
// 5. Store the handle
escrow.budget = transferred;

Step 2 uses allowTransient (cheaper, same-tx only). Step 4 uses allow (persistent, needed for future transactions).

For collecting ERC-7984 token payments (lottery, escrow, payroll), see the step-by-step recipe in references/erc7984-guide.md#recipe-fund-a-contract.

Pattern 6: ERC-7984 Confidential Token (Zama's core standard)

ERC-7984 is the FHE equivalent of ERC-20. Use @openzeppelin/confidential-contracts:

npm install @openzeppelin/confidential-contracts@^0.4.0 @fhevm/solidity@^0.11.1 @openzeppelin/contracts@^5.6.1

Key differences from ERC-20:

• Function names: confidentialTransfer, confidentialBalanceOf, confidentialTotalSupply (NOT transfer/balanceOf)
• Operator model: setOperator(address, uint48 until) — time-based, NOT amount-based approval
• Transfers return euint64 (actual transferred amount), NOT bool
• Silently sends 0 on insufficient balance (no revert)
• Default decimals: 6 (not 18)
• Events: ConfidentialTransfer(from, to, encAmount) with encrypted handle

import {ERC7984} from "@openzeppelin/confidential-contracts/token/ERC7984/ERC7984.sol";

contract MyToken is ZamaEthereumConfig, ERC7984, Ownable2Step {
    constructor() ERC7984("MyToken", "MTK", "https://example.com/token.json") Ownable(msg.sender) {}
    function mint(address to, uint64 amount) external onlyOwner { _mint(to, FHE.asEuint64(amount)); }
}

Warning: The old fhevm-contracts package was archived in June 2025. Use @openzeppelin/confidential-contracts for all new development.

See references/erc7984-guide.md for complete interface, operator model, wrap/unwrap, extensions, and cross-contract patterns.

Pattern 7: Snapshot-Then-Reveal (long-lived public decryption)

Whenever you have an encrypted aggregate that mutates between request and finalize (running tally, max-of-N, monthly volume, all-time-highest, leaderboard top-K, lifetime tip total, jar balance), you MUST snapshot the handle at request time. Use the snapshot — not the live storage value — in FHE.checkSignatures at finalize time.

Why: every FHE op produces a fresh handle. If a user action mutates the aggregate during the seconds-long KMS roundtrip, the storage handle is now different from the one the KMS signed. FHE.checkSignatures reverts with a signature mismatch.

contract MonthlyReveal is ZamaEthereumConfig {
    euint64 private _monthlyTotal;        // mutates on every contribution()
    bytes32 private _pendingRevealHandle; // captured at request time
    uint64  public  revealedTotal;

    function requestReveal() external {
        FHE.makePubliclyDecryptable(_monthlyTotal);
        _pendingRevealHandle = FHE.toBytes32(_monthlyTotal);  // ← SNAPSHOT
    }

    function finalizeReveal(bytes calldata cleartexts, bytes calldata proof) external {
        require(_pendingRevealHandle != bytes32(0), "no reveal pending");
        bytes32[] memory handles = new bytes32[](1);
        handles[0] = _pendingRevealHandle;                     // ← snapshotted, not live
        FHE.checkSignatures(handles, cleartexts, proof);
        revealedTotal = uint64(abi.decode(cleartexts, (uint256)));
        _pendingRevealHandle = bytes32(0);                     // clear so a stale finalize can't re-fire
    }

    function contribute(externalEuint64 enc, bytes calldata p) external {
        _monthlyTotal = FHE.add(_monthlyTotal, FHE.fromExternal(enc, p));
        FHE.allowThis(_monthlyTotal);  // re-grant ACL on the new handle (the snapshot still works)
    }
}

KMS hardening note: a handle that was produced ONLY by FHE.asEuint64(0) (constructor init, never touched by a real FHE op) will fail publicDecrypt with KMSInvalidSigner. Guard requestReveal with a if (eventCount == 0) revert NoActivityYet(); check, or pre-mutate the aggregate before exposing it.

For concurrent in-flight reveals (multiple requestIds outstanding) key the snapshot by request id — mapping(uint256 => bytes32) — see the unwrap recipe in references/decryption-guide.md. Also see templates/confidential-tip-jar.sol and templates/confidential-lottery.sol for the full shape in production templates.

Privileged-Role Pattern Selection

Most FHEVM contracts need an admin role (mint, end auction, settle, slash, etc.). Pick by lifecycle:

See references/security-checklist.md for the full table with code examples.

Critical Anti-Patterns

1. Branching on encrypted values [CRITICAL — leaks confidential data]

// WRONG: if (FHE.decrypt(isEligible)) { grant(); }
// CORRECT:
euint64 reward = FHE.select(isEligible, fullReward, FHE.asEuint64(0));

if/require/assert with encrypted booleans reveals the value to validators by observing which branch executes.

2. Forgetting FHE.allowThis() [CRITICAL — contract loses access to its data]

// WRONG: balances[user] = FHE.add(balances[user], amount);
// CORRECT:
balances[user] = FHE.add(balances[user], amount);
FHE.allowThis(balances[user]);
FHE.allow(balances[user], user);

3. Dividing by encrypted value [CRITICAL — does not compile]

// WRONG: FHE.div(amount, encDivisor);
// CORRECT:
euint64 result = FHE.div(amount, uint64(100));  // Plaintext divisor only

4. Using require() for balance checks [CRITICAL — leaks balance info]

// WRONG: require(balance >= amount, "Insufficient");
// CORRECT:
ebool sufficient = FHE.ge(balance, amount);
euint64 actual = FHE.select(sufficient, amount, FHE.asEuint64(0));

Plaintext role checks are FINE. This anti-pattern is specifically about require/if on a decrypted encrypted value. Plaintext checks on plaintext state are correct and safe: if (msg.sender != creator) revert NotCreator();, Ownable.onlyOwner, setOperator(address, expiry) reverting with ERC7984UnauthorizedSpender, block.timestamp >= deadline, and similar — these reveal nothing confidential because the role / address / timestamp / operator relationship was never private to begin with. The leak only happens when a plaintext branch decision is derived from an encrypted comparison.

5. Random in view functions [HIGH — runtime revert]

Random generation mutates on-chain PRNG state. Must be a state-changing function.

6. Bounded random with non-power-of-2 [HIGH — runtime revert]

FHE.randEuint8(6) reverts at runtime ("upperBound must be a power of 2"). Use FHE.randEuint8(8) (power of 2), then FHE.rem(result, uint8(6)) to project into [0, 6).

7. Deprecated TFHE library for new contracts [HIGH — wrong API]

Use FHE from @fhevm/solidity/lib/FHE.sol, not TFHE from fhevm/lib/TFHE.sol.

8. Unprotected view function returning encrypted handles [MEDIUM]

Always check FHE.isAllowed(value, msg.sender) before returning encrypted handles.

9. Ordering comparisons on euint256 [HIGH — does not compile]

euint256 only supports eq/ne. Use euint128 or smaller for gt/lt/ge/le.

10. Exceeding 2048-bit decryption limit [MEDIUM]

Max per request: 32 × euint64, or 16 × euint128, or 256 × euint8. Total ≤ 2048 bits.

Do NOT Generate These (Common AI Hallucinations)

Battle Scars (Real-World Lessons)

1. "Why did 0 tokens arrive?": We deployed a confidential ERC-20 and tested a transfer of 1000 tokens from an account with 500. No revert, no error, transaction succeeded. The recipient got 0. We spent hours debugging before realizing: confidential transfers (ERC-7984 and any sound FHE token) NEVER revert on insufficient balance — the select(ge(balance, amount), amount, 0) pattern quietly substitutes 0 to avoid leaking the balance. Detection: comparing handles before/after does not work — every FHE op produces a fresh non-deterministic ciphertext, so handles always change. Real detection requires (a) decrypting the recipient's balance and verifying it grew by amount, or (b) parsing the ConfidentialTransfer event's amount handle and decrypting that.

2. "Why does the proof fail cross-contract?": Our vault contract received an encrypted input from a user and forwarded it to a token contract via confidentialTransferFrom. Proof validation failed every time. Root cause: input proofs are bound to msg.sender. When the vault forwarded the call, msg.sender changed from user to vault. Fix: 2-transaction flow — user sends to token directly, then vault triggers logic separately.

3. "Why can't the contract read its own storage?": Contract stored an encrypted treasury balance. First transaction worked. Second transaction reverted with "not allowed." Root cause: FHE.add() creates a NEW handle — the old handle's ACL doesn't carry over. We were missing FHE.allowThis() after the operation. Rule: every FHE operation + state store = must call allowThis.

4. "Gas doesn't change with amount?": We benchmarked FHE.add(1, 2) vs FHE.add(MAX_UINT64, MAX_UINT64) — identical gas. This is intentional: variable gas would leak information about encrypted values. Don't try to optimize around amount-based gas.

5. "Same amount, different ciphertext?": Frontend test encrypted 100 twice and compared handles — they differed. This is correct: encryption is non-deterministic by design. Deterministic encryption would leak information through ciphertext equality comparison.

Supported Types & Operations Quick Reference

…(truncated)