Fhevm Agent

FHEVM Agent

Use this skill to help developers build working confidential dApps with Zama Protocol. Prefer the official FHEVM Hardhat/React templates and current APIs over invented patterns.

Source Of Truth

• FHEVM Solidity package: @fhevm/solidity
• Solidity imports: @fhevm/solidity/lib/FHE.sol, @fhevm/solidity/config/ZamaConfig.sol
• Relayer SDK package: @zama-fhe/relayer-sdk
• Local reference projects to inspect when available: zama/fhevm-react-template, zama/dapps, zama/FHEVM-Bootcamp-Code, zama/Hushroll, zama/Senza, zama/Filez
• Official template source when internet access is available: https://github.com/zama-ai/fhevm-react-template
• Official 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 examples: https://docs.zama.org/protocol/examples/openzeppelin-confidential-contracts/erc7984/erc7984-tutorial
• Bundled standalone Hardhat scaffold: templates/hardhat-app
• If API behavior is uncertain or the user asks for current docs, check the relevant official Zama docs page above before coding.

How To Work

1. Inspect the project first: package manager, Hardhat config, Solidity version, installed FHEVM packages, contract layout, frontend stack.
2. Choose the smallest working path:

• New app: use the bundled templates/hardhat-app scaffold or clone/copy the official FHEVM React/Hardhat template, then preserve its config shape.
• Existing Hardhat app: add @fhevm/hardhat-plugin, @fhevm/solidity, deployment/test patterns.
• Token app: prefer OpenZeppelin Confidential Contracts and ERC-7984.

1. Build contract logic around encrypted handles, not plaintext values.
2. Add Hardhat tests that encrypt inputs, call contracts, and decrypt only in tests or frontend flows.
3. Add frontend integration only after the contract API is stable.
4. Run compile/tests when possible. If network/API keys are required, document the exact missing requirement.

Project Scaffolding Rules

When creating a new Hardhat FHEVM app, do not generate a minimal Hardhat config from memory. Copy or mirror the official Zama template shape:

• imports: @fhevm/hardhat-plugin, @nomicfoundation/hardhat-chai-matchers, @nomicfoundation/hardhat-ethers, @nomicfoundation/hardhat-verify, @typechain/hardhat, hardhat-deploy, hardhat-gas-reporter, solidity-coverage
• networks: hardhat, anvil, sepolia; add mainnet only when the user asks or provides production RPC/API requirements
• namedAccounts.deployer = 0
• Solidity: 0.8.27, optimizer enabled, evmVersion: "cancun"
• TypeChain target: ethers-v6
• scripts: compile, test, chain, deploy:localhost, deploy:sepolia, verify:sepolia
• deploy folder: include a hardhat-deploy deployment script for every generated contract

For Hardhat 2, do not install the latest @nomicfoundation/hardhat-chai-matchers; use a Hardhat-2-compatible version such as @nomicfoundation/hardhat-chai-matchers@hh2 or the version pinned by the FHEVM template.

Reference Routing

Load only what matches the task:

• Architecture and lifecycle: references/architecture.md
• Solidity contract patterns: references/solidity-patterns.md
• Encrypted types, operations, casting, randomness, logic: references/encrypted-types-and-ops.md
• ACL permissions: references/access-control.md
• Input proofs and encrypted input builders: references/input-proofs.md
• User and public decryption: references/decryption.md
• React/web integration with Relayer SDK: references/frontend-relayer-sdk.md
• Hardhat setup, tests, tasks, deploy: references/testing-hardhat.md
• Network config and deployment: references/deployment.md
• OpenZeppelin Confidential Contracts and ERC-7984: references/erc7984-confidential-tokens.md
• Common mistakes to prevent: references/anti-patterns.md
• Agent validation prompts and demo checks: references/agent-evaluation.md
• Advanced x402-style agentic payments and confidential lending: references/agentic-payments-and-x402.md

For complete app shapes, copy from:

• examples/confidential-voting
• examples/confidential-token-erc7984
• examples/sealed-bid-auction
• examples/private-payroll

For copy-ready boilerplate, use:

• templates/hardhat-app
• templates/private-counter
• templates/frontend-hooks
• templates/hardhat-deploy

Non-Negotiable FHEVM Rules

• Encrypted inputs enter Solidity as externalEbool, externalEuintXX, or externalEaddress plus bytes calldata inputProof.
• Convert external inputs inside the contract with FHE.fromExternal(encryptedInput, inputProof).
• Persisted encrypted state must be authorized with FHE.allowThis(ciphertext).
• Users who need to decrypt a handle must be authorized with FHE.allow(ciphertext, userAddress).
• Use FHE.allowTransient(ciphertext, targetContract) when another contract needs the ciphertext only during the current transaction.
• Do not branch with Solidity if on encrypted values. Use FHE.select(condition, a, b).
• Do not reveal encrypted values in events, errors, or public storage by converting to plaintext.
• View functions may return encrypted handles, but decryption happens through user decryption or public decryption flows.
• For confidential tokens, prefer ERC-7984 from OpenZeppelin Confidential Contracts instead of hand-rolling balances/transfers.

Minimal Contract Skeleton

// 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 PrivateCounter is ZamaEthereumConfig {
    euint64 private count;

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

    function add(externalEuint64 encryptedAmount, bytes calldata inputProof) external {
        euint64 amount = FHE.fromExternal(encryptedAmount, inputProof);
        count = FHE.add(count, amount);
        FHE.allowThis(count);
        FHE.allow(count, msg.sender);
    }
}

Minimal Hardhat Test Shape

const encrypted = await fhevm
  .createEncryptedInput(contractAddress, user.address)
  .add64(42)
  .encrypt();

await contract.connect(user).add(encrypted.handles[0], encrypted.inputProof);
const handle = await contract.getCount();
const clear = await fhevm.userDecryptEuint(
  FhevmType.euint64,
  handle,
  contractAddress,
  user
);
expect(clear).to.equal(42);

Final Checklist Before Answering

• Code compiles against the installed FHEVM package versions.
• Every stored ciphertext has FHE.allowThis.
• Every user-readable ciphertext has FHE.allow.
• Every cross-contract encrypted value has FHE.allowTransient or an explicit ACL grant.
• Encrypted comparisons use FHE operations and encrypted conditionals.
• Tests cover encryption, contract call, ACL/decryption, and at least one negative path.
• Frontend examples include input encryption and EIP-712 user decryption when displaying private data.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Femtech-web
• Source: Femtech-web/FHEVM-Agent
• License: MIT

Install and usage instructions live in the source repository linked above.