EIP-7939 CLZ Opcode for FEVM

[snissn]

Hi all — we’d like to propose a FIP adding support for Ethereum EIP-7939 (“Count Leading Zeros”) to the Filecoin EVM (FEVM).

EIP-7939 introduces a new opcode, CLZ (0x1e), which returns the number of leading zero bits in a 256-bit word. This opcode is activated on Ethereum mainnet as part of the Fusaka upgrade (see announcement: https://blog.ethereum.org/2025/11/06/fusaka-mainnet-announcement).

Draft FIP: FIPS/fip-draft_eip-7939-clz.md

Implementation: filecoin-project/builtin-actors#1709

Motivation / Why now

Counting leading zeros is a common primitive used in:

• math and bit-twiddling utilities (e.g., normalization, bit-length)
• compression and bitmap navigation
• ZK circuits and proving systems (where emulating CLZ via shifts/branches can be expensive)

Without a dedicated opcode, contracts must emulate CLZ using SHR/comparisons, which increases bytecode size, complexity, and runtime cost. Supporting EIP-7939 in FEVM improves portability with modern EVM environments and lowers costs for these workloads.

Specification (high level)

• Opcode: CLZ
• Byte: 0x1e
• Stack: pops x, pushes r
• Semantics:
  • CLZ(0) = 256
  • otherwise CLZ(x) is the number of leading zero bits in the 256-bit representation of x
• Gas: EIP-7939 specifies 5 gas (matching MUL) on Ethereum. However, the FEVM uses Filecoin gas accounting (FIP-0054) rather than Ethereum’s opcode gas schedule, so we don’t need to define a new FEVM “opcode gas cost” constant; CLZ execution is metered under Filecoin gas like other opcodes.

Implementation status

A reference implementation is ready in builtin-actors and includes:

• opcode table wiring for CLZ at 0x1e
• unit + bytecode-level tests matching the EIP-7939 test vectors
• end-to-end tests executing CLZ inside a deployed EVM actor

Backwards Compatibility

Before activation, byte 0x1e is an undefined opcode that aborts execution. After activation it will execute CLZ. This is backwards-incompatible for any contract that intentionally depended on 0x1e being invalid.

Feedback requested

1. Any concerns about introducing 0x1e as a new opcode in FEVM (backwards compatibility / upgrade timing)?
2. Any additional real-world workloads (especially ZK/proving-related) we should highlight?
3. Any test vectors or edge cases beyond those in EIP-7939 that we should include?

Thanks in advance for reviews and feedback.

— Aarav Mehta (@aaravm), Michael Seiler (@snissn)