hardhat-fhe-profiler

hardhat-gas-reporter, but for HCU — the per-transaction Homomorphic Complexity Unit budget that silently breaks fhEVM (Zama) confidential contracts and that no block explorer or gas reporter measures.

A confidential contract has two budgets: on-chain EVM gas (every explorer shows it) and per-transaction HCU, the off-chain coprocessor compute cap. Blow the HCU cap and the tx is mined but the FHE compute silently fails. This plugin profiles HCU per function, statically, and gates it in CI.

Built on Zama's own HCU primitives (@fhevm/mock-utils) — not a reimplementation.

Install

npm i -D hardhat-fhe-profiler
# or: pnpm add -D hardhat-fhe-profiler

// hardhat.config.ts
import "hardhat-fhe-profiler";

Use

npx hardhat fhe-profile                      # static HCU table for all your contracts
npx hardhat fhe-profile --json               # machine-readable reports
npx hardhat fhe-profile --update-baseline    # write .fhe-profile-baseline.json
npx hardhat fhe-profile --ci                 # gate: HCU regression / confidence regression / unknown
npx hardhat fhe-profile --ci --threshold 30  # allow +30% HCU drift

function                       txHCU      ownHCU  conf   why
placeBet                     813,130     813,130  LOW    unresolved edge: confidentialTransferFrom()
claim                      1,080,032   1,080,032  LOW    unresolved edge: confidentialTransfer()
createMarket                      64           0  HIGH   straight-line
_initMarket                       64          64  HIGH   straight-line

Confidence is the minimum of three axes (semantic · control-flow · graph-completeness); the why column names the binding one. An under-count is never silent and never HIGH — a function that calls an external body the analyzer can't see (e.g. an ERC-7984 confidentialTransfer) reports its txHCU as an explicit lower bound and names the excluded edge, rather than under-counting at HIGH.

CI gating

npx hardhat fhe-profile --update-baseline    # commit .fhe-profile-baseline.json
npx hardhat fhe-profile --ci                 # in CI — exit 1 on a blocking finding

The --ci gate fails on:

• HCU_REGRESSION — a function's txHCU rose past the baseline by more than --threshold (default 0).
• CONFIDENCE_REGRESSION — a function that was HIGH/MEDIUM at baseline dropped to LOW (a new unanalyzable edge crept in; its txHCU silently stopped being trustworthy). A function already LOW at baseline is an accepted, known limitation and passes — so a contract built on external confidential transfers can still run a meaningful gate. --no-fail-on-low disables this check.
• UNKNOWN_OP / RESOLUTION_LOST — an FHE op the cost model can't price.

It warns (non-blocking) on VERSION_DRIFT (cost-model versions changed since baseline) and NEW_FUNCTION.

Trace mode (optional)

A runtime helper for tests, wrapping Zama's own receipt primitives — no instrumentation:

import { traceTx, reconcile } from "hardhat-fhe-profiler";
const row = await traceTx(hre, "placeBet", contract.placeBet(...));   // live globalHCU + ops
const rec = reconcile(staticReport, "placeBet", row);                 // static / trace / delta

Compatibility

Pinned to the @fhevm/mock-utils cost model. Validated against @fhevm/solidity 0.11.x, @fhevm/mock-utils 0.4.2, solc 0.8.28. Every report carries a version fingerprint; the --ci gate warns on drift.

Part of the fhe-gas-profiler monorepo — see the repo for the confidence model (CONFIDENCE.md), cross-project validation (VALIDATION.md), and the analysis engine (fhe-gas-profiler).

MIT © Laolex