FHEVM v0.9 introduces major architectural changes, including:

• Removal of the Zama Oracle
• Introduction of a self-relaying public decryption workflow
• Unified ZamaEthereumConfig replacing SepoliaConfig

This guide explains what changed and how to migrate your project smoothly.

What Changed in FHEVM v0.9?

Before diving into migration steps, it’s important to understand the main breaking change: public decryption is no longer handled by a Zama Oracle, but by your dApp’s off-chain logic.

FHEVM v0.8 Oracle-Based Decryption

In FHEVM v0.8, the decryption process relies on a trusted Oracle to relay the decryption request and proof between the dApp and the Zama Key Management System (KMS). This approach abstracts the complexity but introduces an external dependency.

Decryption Steps:

Key takeaway for v0.8: The Oracle is the trusted intermediary responsible for performing the off-chain decryption and submitting the result back to the dApp contract.

FHEVM v0.9 Self-Relaying Decryption & dApp Responsibility

The FHEVM v0.9 architecture shifts to a self-relaying model, empowering the dApp client (the user) to execute the off-chain decryption and re-submission. This decentralizes the process and removes the dependency on a general-purpose Oracle.

Example Scenario: Checking a Player's Encrypted Score

Consider a Game contract where Alice's final score is stored encrypted on-chain. Alice needs to prove her clear score to claim a reward.

Key takeaway for FHEVM v0.9: Decryption is a user-driven, off-chain process. The dApp client is responsible for off-chain decryption, fetching the proof, and relaying the result back on-chain for verification.

Why this matters: If your dApp previously relied on the Oracle, you must rewrite your decryption flow. The migration steps below guide you through this change.

Migration Checklist

Here is a brief, ordered list of the steps required to successfully migrate your project to FHEVM v0.9:

1. Update Dependencies: Upgrade all key Zama FHE packages to their FHEVM v0.9 versions.
2. Update Solidity Config: Replace the removed SepoliaConfig with the unified ZamaEthereumConfig.
3. Update Solidity Code: Remove all calls to the discontinued Oracle-based FHE library functions.
4. Re-compile & Re-deploy: Due to new FHEVM addresses, all affected contracts must be re-compiled and re-deployed on Sepolia.
5. Rewrite Public Decryption Logic: Eliminate reliance on the discontinued Zama Oracle and implement the self-relaying workflow using the @zama-fhe/relayer-sdk and FHE.verifySignatures().

Follow these steps for a smooth transition to FHEVM v0.9:

Step 1: Update Core Dependencies

Ensure your project uses the latest versions of the FHEVM development tools.

Step 2: Update Network Configuration in Solidity

The Solidity contracts now use a unified configuration contract defined in @fhevm/solidity/config/ZamaConfig.sol.

• ⚠️ Removal: The SepoliaConfig contract is now removed.
• ✅ New Standard: Update your imports and usages to use the new standard ZamaEthereumConfig contract. This change simplifies future cross-chain compatibility.

The new ZamaEthereumConfig abstract contract now dynamically resolves the FHEVM host addresses according to the block.chainid.

Replace:

import { SepoliaConfig } from "@fhevm/solidity/config/ZamaConfig.sol";

With:

import { ZamaEthereumConfig } from "@fhevm/solidity/config/ZamaConfig.sol";

You can read more about Configuration on the dedicated page.

Step 3: Update Solidity Code

The Zama public decryption Oracle is discontinued. The following functions are no more available in the FHE Solidity library:

• FHE.loadRequestedHandles
• FHE.requestDecryptionWithoutSavingHandles
• FHE.requestDecryption

Step 4: Re-compile and Re-deploy Smart Contracts

Due to fundamental changes in the FHEVM implementation and underlying infrastructure:

• New FHEVM Addresses: The contract addresses for core FHE components have changed.
• Action: You must re-compile your entire Solidity codebase and re-deploy all affected contracts to the Sepolia network.

Step 5: Adjust Public Decryption Logic (Crucial Architectural Change)

The most significant change is the discontinuation of the Zama Oracle. This requires substantial adjustments to how your dApp handles decryption on-chain.

Action: Thoroughly review your Solidity code, dApp logic, and backend services. Any code relying on the external Oracle must be rewritten to implement the self-relaying workflow using the @zama-fhe/relayer-sdk.

FHEVM v0.9 Code Examples: Public Decryption Logic

The following code examples illustrate the new public decryption logic introduced in v0.9. This new workflow uses the combination of:

• On-chain public decyption permission via FHE.makePubliclyDecryptable
• Off-chain decryption via publicDecrypt using the @zama-fhe/relayer-sdk or the FHEVM Hardhat Plugin
• On-chain signature verification via FHE.checkSignatures

Code Examples

• HeadsOrTails: Demonstrates the complete public decryption workflow where a cipher text is first marked as decryptable on-chain via FHE.makePubliclyDecryptable, and its cleartext value is subsequently verified on-chain using FHE.checkSignatures after being fetched off-chain via publicDecrypt.
• HighestDieRoll: Extends the public decryption workflow to a multi-input scenario, demonstrating how the on-chain FHE.checkSignatures function ensures the authenticity of multiple cleartext values derived from multiple encrypted on-chain cypher texts.