FHEVM: a full-stack framework for confidential smart contracts on EVM chains

What FHEVM solves, and who it is actually for

A normal EVM contract cannot keep a secret. Every storage slot, every argument and every intermediate value is public, and that is not a bug in Solidity, it is how the execution model works. The usual workarounds (commit-reveal, mixers, offchain computation with an oracle) each trade away something: timing, composability, or the ability to compute on hidden values at all.

FHEVM attacks the problem at the data level. The README describes it as "the core framework of the Zama Confidential Blockchain Protocol", enabling confidential smart contracts on EVM-compatible chains by processing encrypted data directly onchain through Fully Homomorphic Encryption. The stated guarantees are end-to-end encryption of transactions and state, composability with onchain data availability, and no impact on existing dApps because encrypted state coexists with public state.

The audience is Solidity developers who want privacy without learning cryptography. The README is explicit that you "write FHEVM contracts like any standard Solidity contract". That framing matters: the intended user is not a cryptographer, it is a contract author who wants a balance, a bid or a vote to stay hidden while the contract logic still runs. The listed use cases follow from that: confidential transfers, tokenization of RWAs, blind auctions, onchain games, confidential voting and encrypted DIDs.

There is a second audience, smaller and more technical: people who deploy and operate the stack. The repository is not a single library you import. It is a set of contracts, a Rust coprocessor, a key-management connector, Helm charts and a docker-compose test suite. Someone has to run that.

How encrypted state is executed: symbolic onchain, real FHE offchain

The most interesting design decision is where the arithmetic happens. FHE operations are expensive, so FHEVM does not perform them inside EVM execution. The README states that "all FHE operations are executed symbolically on the host chain", which reduces execution time, while "the actual computations on encrypted data are offloaded asynchronously to our coprocessor".

That split defines the whole architecture. A transaction touching encrypted values does not compute a result synchronously. It records the operation, and the result arrives later through the coprocessor path. Any contract logic that assumes the encrypted value is final within the same transaction will not work, and the documentation does not present a synchronous alternative.

The repository layout reflects the split. On the contract side, host-contracts/ holds the contracts deployed on the host chain for orchestrating FHE workflows, and gateway-contracts/ manages the gateway between onchain and offchain components. On the compute side, coprocessor/ is the Rust implementation of FHE operations, and kms-connector/ integrates with Key Management Services to handle encryption keys. Supporting directories include charts/ for Helm deployment, golden-container-images/ for the Node.js and Rust base images the stack builds on, and test-suite/ for docker-compose integration tests.

Decryption is deliberately not a single point of trust. The README says decryption is managed via a KMS using multi-party computation, so security holds "even if some parties are compromised or misbehaving". The underlying scheme is described as quantum-resistant. Those are claims from the project; the whitepaper (fhevm-whitepaper.pdf in the repository) is where the cryptographic detail lives, and it is the document to read before trusting any of it.

The Solidity surface: precision, operators and access control

From a contract author's perspective the API is narrow. The README lists encrypted integers up to 256 bits of precision and the full range of typical operators: +, -, *, /, <, >, ==, ternary-if and boolean operations. It also states that consecutive FHE operations are not limited, which is a meaningful constraint to have lifted: chained encrypted arithmetic is exactly where homomorphic schemes tend to hit noise or performance walls.

Access control is the part worth pausing on. The README describes "programmable privacy": you define which data is encrypted and write the access control logic directly in your smart contracts. That puts the burden of deciding who may decrypt what on the contract author, in Solidity, rather than in an external policy engine. It is a reasonable choice for composability, but it means a mistake in your own contract is a privacy bug, not a framework bug.

Toolchain support is asymmetric. The README claims compatibility with existing toolchains such as Hardhat, while Foundry support is marked "coming soon". If your team lives in Foundry, that line is the one to check first, because it is the difference between reusing your existing test setup and rebuilding it.

The library-solidity/ directory is where the Solidity-facing library lives, and it is one of the npm workspaces declared in package.json, alongside host-contracts and test-suite/e2e. That is a good signal about where the developer-facing surface is maintained.

Building the stack from source and running the test suite

The README does not give a step-by-step install guide. It points to the documentation at docs.zama.ai/protocol and to the community channel at zama.ai/community. What the repository itself shows is a Node/npm workspace root and a test suite driven through Bun inside test-suite/fhevm.

The root package.json defines the workspace layout and a single test script. This is the entry point the repository itself exposes:

{
  "name": "fhevm",
  "private": true,
  "scripts": {
    "test": "cd test-suite/fhevm && bun run test"
  },
  "workspaces": [
    "host-contracts",
    "library-solidity",
    "library-solidity/codegen",
    "test-suite/e2e"
  ]
}

Running the root test script therefore delegates into test-suite/fhevm and invokes Bun, not npm, for the actual test run. Install the workspace dependencies first, then run the suite:

npm install
npm test

What you should expect is not a unit test run. The README describes test-suite/ as integration with docker-compose and tests covering end-to-end FHEVM stack behavior, so the suite exercises the contracts, the coprocessor and the surrounding services together. Budget for a container-based environment rather than a laptop-only loop.

For deployment, charts/ holds the Helm charts and deployment configurations for the stack. That is the supported path for standing the components up in a cluster, and it is the directory to read before writing your own orchestration.

Where FHEVM is the wrong tool

The first limitation is structural, not a bug: encrypted computation is asynchronous. Because FHE operations are offloaded to the coprocessor, any workflow that needs an encrypted result inside the same transaction is out of scope. A synchronous encrypted AMM or an atomic swap whose price depends on a hidden value is not something this architecture expresses. If your contract cannot tolerate a delayed result, FHEVM is the wrong layer.

The second is operational weight. Deploying the framework means host contracts, gateway contracts, a Rust coprocessor, a KMS connector and the infrastructure that ties them together. The README lists relayer/, listener/ and sdk/ among the top-level entries, which confirms the surface area. A team that wants a library and nothing else will find this is a platform, not a dependency.

The third is that privacy is not free at the contract level. Programmable privacy means you write the access control, and the framework will not catch a policy mistake for you. Combined with the asynchronous model, that makes the review burden on your own contract higher than on a typical Solidity contract of the same size.

Finally, the README does not document rollback or upgrade behavior for encrypted state, and it does not document what happens to pending coprocessor operations if a component is unavailable. Those are real questions for production use, and the README is silent on them. The whitepaper and the documentation site are the places to look; do not assume an answer.

FHEVM against TFHE-rs and general-purpose FHE libraries

The natural comparison is TFHE-rs, the Rust FHE library that appears alongside FHEVM in searches about Zama. The difference is scope, and it is large. TFHE-rs is a library: you write Rust, you call FHE primitives, you own the entire execution environment. FHEVM is the opposite end of the stack. It wraps FHE in Solidity, an EVM host chain, a gateway, a coprocessor and a KMS, and it makes the privacy guarantee composable with onchain state.

That difference decides the choice. If you are building a confidential computation that never needs to touch a blockchain, or you need direct control over the FHE parameters and the noise budget, a library gives you that control and FHEVM does not. If what you need is a contract whose storage is encrypted and whose logic other contracts can call, a library gives you nothing at all, because the hard part is the integration with consensus, state and key management, not the arithmetic.

Within the blockchain space the comparison is with approaches that hide data by not putting it onchain: commit-reveal schemes, mixers and offchain computation with proofs. Those avoid the coprocessor entirely, but they lose the property FHEVM is built around, which is computing on encrypted values while the state remains available onchain. The README frames this as confidentiality plus composability, and that combination is the actual claim being made.

Maintenance, licence and the cost of tracking releases

The repository is not archived, and the last push was on 2026-09-19. Releases have been frequent: v0.13.4 on 2026-09-04, v0.13.5 on 2026-09-14 and v0.13.6-0 on 2026-09-18. The version numbers are worth reading carefully. Everything is still in the 0.13.x line, and one of the three most recent tags carries a -0 suffix, which reads as a pre-release or a packaging variant rather than a stable cut. For anyone pinning dependencies, that cadence means upgrade work is a recurring line item, not a one-time task.

The licence needs attention rather than assumption. The repository metadata reports the licence as NOASSERTION, while the README badge and the README text state BSD-3-Clause-Clear. Those two signals disagree, and the LICENSE file at the repository root is the authoritative artifact. This article is not legal advice; if you are shipping a product on top of FHEVM, read LICENSE and, where it matters, get counsel to read it too. The BSD-3-Clause-Clear family is a permissive licence with an explicit patent clause, which is a different posture from plain BSD-3-Clause, and the distinction is exactly the kind of thing that surfaces late in a procurement review.

Contributions are gated. The README states that only approved contributors can send pull requests, that becoming one involves signing a Contributor License Agreement, and that you should email [email protected] before opening a PR. If you plan to patch the coprocessor or the contracts locally, plan for a fork rather than an upstream PR unless you go through that process.

Editorial conclusion

Adopt FHEVM if you need onchain state that stays encrypted and you are willing to run or connect to the full stack: host contracts, gateway contracts, coprocessor, KMS connector and relayer. Do not adopt it for a public DeFi contract where every value is meant to be visible, or for a team that cannot operate a multi-service deployment. Before committing, verify two things: which contracts are actually deployed on your target chain, and how the coprocessor and KMS connector are configured in charts/ for your environment. Those two answers decide most of the integration work.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. zama-ai/fhevm on GitHub