Adding support for CLZ opcode (upcoming Osaka hardfork)

[Syzygy106]

Describe the desired feature

Motivation

While auditing the Ekubo codebase, I noticed that Slither does not currently handle the new Yul builtin clz, which maps to the opcode introduced in the upcoming Osaka hardfork.

Since clz is being added specifically to support more accurate and efficient implementations of common mathematical models — such as MSB/log2 computations, normalization routines, and other bit-level operations — its semantics matter for correctness. The fact that clz(0) = 256 in particular can affect a number of invariants these patterns rely on.

Because Slither cannot yet interpret clz, there is a possibility that certain issues may go undetected, especially in codebases that adopt Osaka-related arithmetic patterns.

These include arithmetic mistakes around the 256 edge case, unsafe narrowing of the clz result, and logic that still assumes legacy MSB implementations.

Proposal

Add support for parsing and evaluating the clz Yul builtin so that Slither can:

understand expressions that make use of clz in Yul or inline assembly,

take its semantics and edge cases into account,

and enable detectors that catch arithmetic issues, invalid casts, and other correctness problems related to clz.

This would help Slither provide accurate analysis for projects targeting Osaka and beginning to rely on the new opcode.

I also have some preliminary work prepared. If the maintainers agree that this feature would be valuable, I’d be happy to implement it.

[Syzygy106]

CLZ Opcode Detectors Specification

Overview

This document specifies detectors for the clz (Count Leading Zeros) opcode introduced in EIP‑7939 for the Osaka hardfork.
The opcode returns the number of leading zero bits in a 256‑bit word, with a notable edge case:

• CLZ(0) = 256

These semantics create several classes of correctness issues that static analyzers can detect.

The following detectors are intended to catch high‑impact mistakes, unsafe patterns, and outdated MSB/log2 implementations that should be replaced with the native opcode.

---

Detectors Summary

ID	Name	Severity	Type
H‑1	Subtraction Pattern	🔴 HIGH	Security
H‑2	Normalization Pattern	🔴 HIGH	Security
H‑3	Unsafe Type Casting	🔴 HIGH	Security
L‑1	Signed Integer Usage	🟡 LOW	Security
L‑2	Legacy Implementations	🟡 LOW	Optimization

---

H‑1 — Subtraction Pattern

(HIGH severity – correctness & security)

Issue

Patterns of the form:

255 - clz(x)
sub(255, clz(x))

Underflow when x == 0 because clz(0) = 256.

Why this is critical

• Used heavily in MSB, log2, bitLength, and normalization math
• Off‑by‑256 wraparound produces mathematically invalid results
• Results propagate into pricing formulas, AMM math, and integer normalization

Vulnerable Patterns

Yul:

assembly {
    let msb := sub(255, clz(x))
    let bits := sub(256, clz(x))
    let k := sub(159, clz(x))
}

Solidity:

uint256 r;
assembly { r := clz(x) }
return 255 - r; // ❌ zero not checked

PoC

// x = 0:
// clz(0) = 256
// 255 - 256 = underflow → 2^256‑1
function brokenLog2(uint256 x) public pure returns (uint256) {
    uint256 r;
    assembly { r := clz(x) }
    return 255 - r;
}

Safe Pattern

function safeLog2(uint256 x) public pure returns (uint256) {
    require(x != 0);
    uint256 r;
    assembly { r := clz(x) }
    return 255 - r;
}

References

• Uniswap V3 BitMath: https://github.com/Uniswap/v3-core/blob/main/contracts/libraries/BitMath.sol
• PRBMath msb: https://github.com/PaulRBerg/prb-math/blob/main/src/Common.sol
• Solidity by Example: https://solidity-by-example.org/bitwise/
• EIP-7939: https://eips.ethereum.org/EIPS/eip-7939

---

H‑2 — Normalization Pattern

(HIGH severity – correctness & financial impact)

Issue

Patterns used in lnWad, expWad and normalization math:

shr(C, shl(clz(x), x))

Break when x == 0 because:

• clz(0) = 256
• shl(256, x) silently discards the shift and yields 0
• Downstream computations receive meaningless values

Vulnerable Pattern

assembly {
    let r := clz(x)
    let normalized := shr(159, shl(r, x))
    let k := sub(159, r)
}

PoC

// x = 0 → r = 256
// shl(256, 0) = 0
// k = sub(159, 256) = wraparound
function brokenLnWad(uint256 x) public pure returns (int256) {
    uint256 r;
    uint256 k;
    assembly {
        r := clz(x)
        k := sub(159, r)
    }
    return int256(k);
}

Safe Pattern

require(x != 0, "ln(0) undefined");

References

• Solady FixedPointMathLib: https://github.com/vectorized/solady/blob/main/src/utils/FixedPointMathLib.sol
• PRBMath log2/ln: https://github.com/PaulRBerg/prb-math/blob/main/src/Common.sol

---

H‑3 — Unsafe Type Casting

(HIGH severity – silent overflow)

Issue

Casting the result of clz(x) to uint8 or int8 is unsafe:

• clz(0) = 256
• uint8 can only represent 0‑255
• Overflow wraps silently to 0

Vulnerable Pattern

uint256 r;
assembly { r := clz(x) }
uint8 v = uint8(r); // ❌ silently wraps

PoC

// clz(0) = 256 → uint8(256) = 0
// clz(max) = 0 → uint8(0) = 0
// → indistinguishable

Safe Pattern

if (x == 0) revert();

Or cast to uint16.

Reference:

• Solidity Type Conversions: https://docs.soliditylang.org/en/latest/types.html

---

L‑1 — Signed Integer Usage

(LOW severity – logic errors)

Issue

Using clz(int256) produces misleading results:

• Negative numbers have highest bit = 1
• Thus clz(x) for negative x is always 0

Vulnerable Pattern

function badBitLength(int256 x) public pure returns (uint256) {
    uint256 r;
    assembly { r := clz(x) }
    return 256 - r;
}

PoC

badBitLength(100)    == 7
badBitLength(10)    == 4
badBitLength(1)    == 1
badBitLength(0)    == 0
badBitLength(-1)  = 256  
badBitLength(-10) = 256  
badBitLength(-100) = 256  

Safe Pattern

require(x >= 0);
uint256 ux = uint256(x);

Reference:

• Solidity Two's Complement: https://docs.soliditylang.org/en/latest/types.html#integers

---

L‑2 — Legacy Implementations

(LOW severity – optimization / modernization)

Before Osaka, developers implemented MSB/log2/bitLength manually:

• Uniswap V3, PRBMath, Frax, SushiSwap, etc.
• Linear scans in educational code
• Assembly mask‑based binary search
• EIP‑7939 fallback CLZ using large lookup tables

All should be replaced with a single CLZ opcode.

Legacy Pattern 1 — Uniswap/PRBMath Binary Search

if (x >= 2**128) { x >>= 128; r += 128; }
if (x >= 2**64)  { x >>= 64;  r += 64;  }
...

Legacy Pattern 2 — Linear Scan

while ((x >>= 1) > 0) {
    r++;
}

Legacy Pattern 3 — Assembly Binary Search

assembly {
    let f := shl(7, gt(x, 0xFFFFFFFF...))
    msb := or(msb, f)
    x := shr(f, x)
}

Legacy Pattern 4 — EIP‑7939 Fallback

Contains signature magic constants:

• 0x8421084210842108cc6318c6db6d54be
• 0xf8f9f9faf9fdfafb...

Modern Replacement

function mostSignificantBit(uint256 x) internal pure returns (uint256) {
    require(x > 0);
    uint256 r;
    assembly { r := clz(x) }
    return 255 - r;
}

References:

Pattern 1 (Uniswap/PRBMath Binary Search):

• Uniswap V3 BitMath: https://github.com/Uniswap/v3-core/blob/main/contracts/libraries/BitMath.sol
• PRBMath Common: https://github.com/PaulRBerg/prb-math/blob/main/src/Common.sol
• Solady FixedPointMathLib: https://github.com/Vectorized/solady/blob/main/src/utils/FixedPointMathLib.sol

Pattern 2 (Linear Scan):

• Solidity by Example: https://solidity-by-example.org/bitwise/
• https://ethereum.stackexchange.com/questions/8086/logarithm-math-operation-in-solidity

Pattern 4 (EIP-7939 Fallback):

• EIP-7939 Reference: https://eips.ethereum.org/EIPS/eip-7939

---