README

Introduction

This node package contains the core Solidity host contracts needed to deploy an FHEVM instance on a host EVM blockchain.

Getting started

run

npm install

To run forge tests:

npm run forge:soldeer
npm run test:forge

Prepare-only executor upgrade

Use task:prepareUpgradeFHEVMExecutor when you need to deploy a new FHEVMExecutor implementation without upgrading the proxy yet.

This task is meant for DAO-driven upgrades:

• it imports the existing proxy into the OpenZeppelin manifest
• it deploys the new implementation with prepareUpgrade
• it prints the implementation address and reinitializeV* calldata
• it does not mutate the proxy

Run it from a checkout containing the exact new host-contract code you want to deploy. For a backport hotfix, that means the checked-out branch/tag should match the new release.

The task still needs the current deployment addresses on disk because contracts/FHEVMExecutor.sol imports addresses/FHEVMHostAddresses.sol. Generate them first with the existing setter tasks. If you are switching environments, restart from task:setACLAddress so both generated files are rewritten from scratch before the remaining addresses are appended:

npx hardhat task:setACLAddress --address <acl>
npx hardhat task:setFHEVMExecutorAddress --address <executor-proxy>
npx hardhat task:setKMSVerifierAddress --address <kms>
npx hardhat task:setInputVerifierAddress --address <input-verifier>
npx hardhat task:setHCULimitAddress --address <hcu-limit>
npx hardhat task:setPauserSetAddress --address <pauser-set>

Those commands generate:

• addresses/.env.host
• addresses/FHEVMHostAddresses.sol

The values to feed into those setter tasks should come from the currently deployed environment you are upgrading. A practical source of truth is the verified source bundle of the implementation currently behind the proxy, specifically addresses/FHEVMHostAddresses.sol.

If the upgrade baseline predates ProtocolConfig and KMSGeneration (for example UPGRADE_FROM_TAG=v0.11.1 in CI), run:

npx hardhat task:deployEmptyProxiesProtocolConfigKMSGeneration

This compatibility task deploys only the empty UUPS proxies for missing address keys and appends the missing generated constants so prepare-upgrade tasks can compile against the current source tree. Keep it as a forward-compat safeguard if a manifest contract starts importing those generated addresses before the baseline tag catches up. DEPLOYER_PRIVATE_KEY is only required when the task actually needs to bootstrap missing proxies. Once the baseline tag includes those contracts, the task becomes a no-op and the bootstrap step can be removed.

Then run:

npx hardhat task:prepareUpgradeFHEVMExecutor \
  --network sepolia \
  --current-implementation previous-contracts/FHEVMExecutor.sol:FHEVMExecutor \
  --new-implementation contracts/FHEVMExecutor.sol:FHEVMExecutor \
  --verify-contract true

Notes:

• --network selects where the implementation deployment transaction is sent.
• --current-implementation points to the old implementation source available on disk.
• --new-implementation comes from your current checkout.
• if you want the proxy address from addresses/.env.host, add --use-internal-proxy-address true
• the task runs hardhat clean before recompiling so the implementation is not built from stale artifacts compiled against another environment

Breaking changes for event consumers

KMSVerifier no longer emits context-lifecycle events after the migration to canonical ProtocolConfig state. Off-chain consumers should move to the ProtocolConfig emitter at protocolConfigAdd (addresses/FHEVMHostAddresses.sol):

• KMSVerifier.NewContextSet(uint256,address[],uint256) -> ProtocolConfig.NewKmsContext(uint256,KmsNode[],KmsThresholds)
• KMSVerifier.KMSContextDestroyed(uint256) -> ProtocolConfig.KmsContextDestroyed(uint256)

Host Deployment Role

task:deployAllHostContracts requires an explicit --with-kms-generation value:

npx hardhat task:deployAllHostContracts --with-kms-generation true   # canonical host
npx hardhat task:deployAllHostContracts --with-kms-generation false  # non-canonical host

KMSGeneration is deployed only on the canonical host chain. Non-canonical host chains deploy the common host contracts only.

Non-canonical host chains

KMSGeneration is NOT deployed on non-canonical host chains. ProtocolConfig on non-canonical chains is a replica whose state is mirrored manually (Phase 1) or via LayerZero / LzRead (Phase 2) from the canonical chain. Operators mirroring a canonical rotation to non-canonical chains call defineNewKmsContext directly on each non-canonical ProtocolConfig, using the same kmsNodes and thresholds as the canonical rotation.

No on-chain guard prevents a non-canonical replica from drifting if a mirror transaction is skipped. Operators are responsible for fan-out correctness.