fhe-gas-profiler

The static analysis engine behind hardhat-fhe-profiler — HCU-aware cost analysis for fhEVM (Zama) confidential contracts, with no hardhat dependency.

Looking for the CLI / CI gate? Install hardhat-fhe-profiler instead. This package is for tools that want to embed the analyzer directly (indexers, custom reporters, dashboards).

What it does

Given a solc build-info, it prices every FHE.* operation in HCU (Homomorphic Complexity Units) and returns a per-function cost report with a three-axis confidence grade.

The cost model does not infer semantics from syntax — it recovers them from the compiler's binding decisions:

MemberAccess.referencedDeclaration → FunctionDefinition → canonical signature → cost rule

Pricing is a constant lookup against @fhevm/mock-utils's getHCU table, so the analyzer is built on Zama's own HCU primitives rather than reimplementing them.

Use

npm i fhe-gas-profiler

import { analyzeBuildInfo, renderTable } from "fhe-gas-profiler";

const report = analyzeBuildInfo(buildInfo, {
  sourceFile: "contracts/MyContract.sol",
  contractName: "MyContract",
  projectRoot: ".",
});

console.log(renderTable(report));
for (const fn of report.functions) {
  console.log(fn.fn, fn.txHcu, fn.confidence, fn.confidenceReason);
}

Confidence (three orthogonal axes)

A function is HIGH only when all three are high; the report takes the minimum.

• Semantic — every op is a resolved signature with a known, priced rule.
• Control-flow — straight-line, or bounded? A loop (lower bound) or branch (upper bound) → MEDIUM.
• Graph-completeness — are all in-tx call edges accounted for? An edge whose callee has no analyzable body (interface / external / abstract) → LOW + UNRESOLVED_CALL_EDGE.

An under-count is never silent and never HIGH. Every report carries a version fingerprint (@fhevm/solidity, @fhevm/mock-utils, solc).

Part of the fhe-gas-profiler monorepo.

MIT © Laolex