Rename shift/targetBits to discardedBitWidth/encodedBitWidth across library, tests, and docs

Author: 0xferit

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-`uint-quantization-lib` is a pure-function Solidity library for shift-based `uint256` lossy compression. The core mechanism is floor quantization via right-shifting via the `UintQuantizationLib` library. A `Quant` value packs `(shift, targetBits)` into a single `uint16`, making the compression scheme explicit and reusable. The recommended pattern is `immutable` + `create(shift, targetBits)` for readability.
+`uint-quantization-lib` is a pure-function Solidity library for shift-based `uint256` lossy compression. The core mechanism is floor quantization via right-shifting via the `UintQuantizationLib` library. A `Quant` value packs `(discardedBitWidth, encodedBitWidth)` into a single `uint16`, making the compression scheme explicit and reusable. The recommended pattern is `immutable` + `create(discardedBitWidth, encodedBitWidth)` for readability.
 
 ## Commands
 
@@ -37,13 +37,13 @@ forge test --match-path test/showcase/ShowcaseGas.t.sol --gas-report -vv
 
 ### Source: `src/`
 
-- `UintQuantizationLib.sol`: UDT `Quant` packing `(shift, targetBits)` into `uint16` (bits 0-7 = shift, bits 8-15 = targetBits). All functions are `internal pure`. Errors are file-level (not inside the library) and attached to the type. `using UintQuantizationLib for Quant global` at the bottom of the file propagates method-call binding to all importers automatically.
+- `UintQuantizationLib.sol`: UDT `Quant` packing `(discardedBitWidth, encodedBitWidth)` into `uint16` (bits 0-7 = discardedBitWidth, bits 8-15 = encodedBitWidth). All functions are `internal pure`. Errors are file-level (not inside the library) and attached to the type. `using UintQuantizationLib for Quant global` at the bottom of the file propagates method-call binding to all importers automatically.
 
 - `src/showcase/ShowcaseSolidityFixtures.sol`: Production-style showcase contracts demonstrating gas savings. `RawETHStakingShowcase` vs `QuantizedETHStakingShowcase` (real-life staking) and `RawExtremePackingShowcase` vs `QuantizedExtremePackingShowcase` (12 slots -> 1 slot). Used only for benchmarking. Both quantized contracts use `UintQuantizationLib`.
 
 ### Tests: `test/`
 
-- `test/UintQuantizationLib.t.sol`: Foundry test file. Contains `QuantHarness` (exposes method-call syntax) and `UintQuantizationLibSmokeTest`. Smoke tests cover `create` validation and all revert paths. Fuzz tests use `uint8` for shift and targetBits and use `bound()` instead of `vm.assume` for value-in-range constraints.
+- `test/UintQuantizationLib.t.sol`: Foundry test file. Contains `QuantHarness` (exposes method-call syntax) and `UintQuantizationLibSmokeTest`. Smoke tests cover `create` validation and all revert paths. Fuzz tests use `uint8` for discardedBitWidth and encodedBitWidth and use `bound()` instead of `vm.assume` for value-in-range constraints.
 
 - `test/showcase/ShowcaseGas.t.sol`: Benchmark assertions. Enforces quantized paths save >= 32% (real-life) and >= 80% (extreme) gas vs raw paths on zero-to-nonzero writes.
 

README.md

@@ -38,32 +38,32 @@ The `Quant` value type is a `uint16` with the following bit layout:
 
 | Bits | Field | Notes |
 |---|---|---|
-| 0-7 | `shift` | LSBs discarded during encoding |
-| 8-15 | `targetBits` | Bit-width of the encoded value |
+| 0-7 | `discardedBitWidth` | LSBs discarded during encoding |
+| 8-15 | `encodedBitWidth` | Bit-width of the encoded value |
 
 ### API
 
 | Function | Description |
 |---|---|
-| `UintQuantizationLib.create(shift, targetBits)` | Creates a `Quant` scheme from readable parameters. Reverts with `BadConfig` when shift >= 256, targetBits == 0, targetBits >= 256, or shift + targetBits > 256. |
-| `q.shift()` | Number of low bits discarded during encoding (set at creation). |
-| `q.targetBits()` | Bit-width of the encoded value (set at creation). |
-| `q.encode(value)` | Floor-encodes `value`. Reverts with `Overflow` when `value > max(q)`. |
-| `q.encode(value, true)` | Strict mode: also reverts with `NotAligned` when `value` is not step-aligned. |
-| `q.decode(encoded)` | Left-shifts `encoded` by shift, restoring discarded bits as zeros (lower bound). |
-| `q.decodeMax(encoded)` | Like `decode` but fills discarded bits with ones (upper bound within the step). |
-| `q.fits(value)` | Returns `true` when `value <= max(q)`. |
+| `UintQuantizationLib.create(discardedBitWidth, encodedBitWidth)` | Creates a `Quant` scheme. Reverts with `BadConfig` on invalid parameters. |
+| `q.discardedBitWidth()` | Number of low bits discarded during encoding (set at creation). |
+| `q.encodedBitWidth()` | Bit-width of the encoded value (set at creation). |
+| `q.encode(value)` | Compresses `value` by discarding the low bits (floor). Reverts with `Overflow` if `value > max(q)`. |
+| `q.encode(value, true)` | Same as `encode(value)`, but also reverts with `NotAligned` if `value` is not step-aligned. |
+| `q.decode(encoded)` | Decompresses `encoded` back to the original scale. Discarded bits are restored as zeros (lower bound). |
+| `q.decodeMax(encoded)` | Like `decode`, but fills discarded bits with ones (upper bound within the step). |
+| `q.fits(value)` | True if `value` fits within the scheme's representable range. |
 | `q.floor(value)` | Rounds `value` down to the nearest step boundary. |
 | `q.ceil(value)` | Rounds `value` up to the nearest step boundary. |
-| `q.remainder(value)` | Returns discarded low bits (`value mod stepSize`). |
-| `q.isAligned(value)` | Returns `true` when `value` is exactly representable (step-aligned). |
-| `q.stepSize()` | Returns `2^shift`. |
-| `q.max()` | Returns the maximum original value representable: `(2^targetBits - 1) << shift`. |
+| `q.remainder(value)` | Resolution lost if `value` were floor-encoded (`value mod stepSize`). |
+| `q.isAligned(value)` | True if `value` is step-aligned (no resolution loss on encode). |
+| `q.stepSize()` | Smallest non-zero value the scheme can represent (`2^discardedBitWidth`). |
+| `q.max()` | Largest value the scheme can represent: `(2^encodedBitWidth - 1) << discardedBitWidth`. |
 
 ### Errors
 
 ```solidity
-error BadConfig(uint256 shift, uint256 targetBits);
+error BadConfig(uint256 discardedBitWidth, uint256 encodedBitWidth);
 error Overflow(uint256 value, uint256 max);
 error NotAligned(uint256 value, uint256 stepSize);
 ```
@@ -132,8 +132,8 @@ contract StakingVault {
 ```
 
 > `encode(value)` and `encode(value, true)` return `uint256` due to Solidity type constraints. The encoded
-> result is guaranteed to fit in `2^targetBits - 1`, so store it using the matching `uintN` for
-> your scheme (for example, `uint16` for `targetBits=16`, `uint24` for `targetBits=24`). Using a
+> result is guaranteed to fit in `2^encodedBitWidth - 1`, so store it using the matching `uintN` for
+> your scheme (for example, `uint16` for `encodedBitWidth=16`, `uint24` for `encodedBitWidth=24`). Using a
 > smaller type will silently truncate.
 
 ## Which encode function should I use?

src/UintQuantizationLib.sol

@@ -7,11 +7,11 @@ pragma solidity ^0.8.25;
  * @custom:security-contact ferit@cryptolab.net
  * @notice Pure-function library for shift-based uint256 compression using a bundled config type.
  *
- *         The `Quant` value type packs a `(shift, targetBits)` scheme into a single `uint16`,
+ *         The `Quant` value type packs a `(discardedBitWidth, encodedBitWidth)` scheme into a single `uint16`,
  *         allowing callers to define the compression config once and invoke methods on it.
  *         Type layout (uint16):
- *           bits 0-7  → shift      (LSBs discarded during encoding)
- *           bits 8-15 → targetBits (bit-width of the encoded value)
+ *           bits 0-7  → discardedBitWidth (LSBs discarded during encoding)
+ *           bits 8-15 → encodedBitWidth   (bit-width of the encoded value)
  *
  *         Usage:
  *         ```solidity
@@ -31,8 +31,8 @@ error Overflow(uint256 value, uint256 max);
 /// @notice Thrown by `encode` (precise mode) when a value is not aligned to the step size.
 error NotAligned(uint256 value, uint256 stepSize);
 
-/// @notice Thrown by `create` when the (shift, targetBits) pair is invalid.
-error BadConfig(uint256 shift, uint256 targetBits);
+/// @notice Thrown by `create` when the (discardedBitWidth, encodedBitWidth) pair is invalid.
+error BadConfig(uint256 discardedBitWidth, uint256 encodedBitWidth);
 
 library UintQuantizationLib {
     string internal constant VERSION = "1.1.0";
@@ -41,44 +41,47 @@ library UintQuantizationLib {
     // Factory
     // -------------------------------------------------------------------------
 
-    /// @notice Creates a `Quant` scheme from shift and targetBits.
-    /// @dev    Reverts when shift >= 256, targetBits == 0, targetBits >= 256, or
-    ///         shift + targetBits > 256. Any of these conditions would produce a scheme
+    /// @notice Creates a `Quant` scheme from discardedBitWidth and encodedBitWidth.
+    /// @dev    Reverts when discardedBitWidth >= 256, encodedBitWidth == 0, encodedBitWidth >= 256, or
+    ///         discardedBitWidth + encodedBitWidth > 256. Any of these conditions would produce a scheme
     ///         where the computed max overflows or the step size is undefined.
-    function create(uint256 shift_, uint256 targetBits_) internal pure returns (Quant) {
-        if (shift_ >= 256 || targetBits_ == 0 || targetBits_ >= 256 || shift_ + targetBits_ > 256) {
-            revert BadConfig(shift_, targetBits_);
+    function create(uint256 discardedBitWidth_, uint256 encodedBitWidth_) internal pure returns (Quant) {
+        if (
+            discardedBitWidth_ >= 256 || encodedBitWidth_ == 0 || encodedBitWidth_ >= 256
+                || discardedBitWidth_ + encodedBitWidth_ > 256
+        ) {
+            revert BadConfig(discardedBitWidth_, encodedBitWidth_);
         }
-        // casting to uint16 is safe: create guard above ensures shift_ < 256 and targetBits_ < 256,
-        // so (targetBits_ << 8) | shift_ <= 0xFF00 | 0xFF = 0xFFFF, which fits in uint16.
+        // casting to uint16 is safe: create guard above ensures discardedBitWidth_ < 256 and encodedBitWidth_ < 256,
+        // so (encodedBitWidth_ << 8) | discardedBitWidth_ <= 0xFF00 | 0xFF = 0xFFFF, which fits in uint16.
         // forge-lint: disable-next-line(unsafe-typecast)
-        return Quant.wrap(uint16((targetBits_ << 8) | shift_));
+        return Quant.wrap(uint16((encodedBitWidth_ << 8) | discardedBitWidth_));
     }
 
     // -------------------------------------------------------------------------
     // Accessors
     // -------------------------------------------------------------------------
 
-    /// @notice Returns the shift component of the scheme (bits 0-7).
-    function shift(Quant q) internal pure returns (uint256) {
+    /// @notice Returns the discardedBitWidth component of the scheme (bits 0-7).
+    function discardedBitWidth(Quant q) internal pure returns (uint256) {
         return uint256(Quant.unwrap(q)) & 0xFF;
     }
 
-    /// @notice Returns the targetBits component of the scheme (bits 8-15).
-    function targetBits(Quant q) internal pure returns (uint256) {
+    /// @notice Returns the encodedBitWidth component of the scheme (bits 8-15).
+    function encodedBitWidth(Quant q) internal pure returns (uint256) {
         return uint256(Quant.unwrap(q)) >> 8;
     }
 
-    /// @notice Returns 2^shift: the quantization step size.
+    /// @notice Returns 2^discardedBitWidth: the quantization step size.
     function stepSize(Quant q) internal pure returns (uint256) {
-        return uint256(1) << shift(q);
+        return uint256(1) << discardedBitWidth(q);
     }
 
     /// @notice Returns the maximum original value representable by this scheme.
-    /// @dev    Safe when the scheme was created via `create`: shift + targetBits <= 256 and
-    ///         targetBits < 256 guarantee the result fits in uint256.
+    /// @dev    Safe when the scheme was created via `create`: discardedBitWidth + encodedBitWidth <= 256 and
+    ///         encodedBitWidth < 256 guarantee the result fits in uint256.
     function max(Quant q) internal pure returns (uint256) {
-        return ((uint256(1) << targetBits(q)) - 1) << shift(q);
+        return ((uint256(1) << encodedBitWidth(q)) - 1) << discardedBitWidth(q);
     }
 
     // -------------------------------------------------------------------------
@@ -89,15 +92,15 @@ library UintQuantizationLib {
     function encode(Quant q, uint256 value) internal pure returns (uint256) {
         uint256 m = max(q);
         if (value > m) revert Overflow(value, m);
-        return value >> shift(q);
+        return value >> discardedBitWidth(q);
     }
 
     /// @notice Encodes `value`. When `precise` is true, reverts if value is not step-aligned.
     ///         Always reverts if value exceeds `max(q)`.
     function encode(Quant q, uint256 value, bool precise) internal pure returns (uint256) {
         uint256 m = max(q);
         if (value > m) revert Overflow(value, m);
-        uint256 s = shift(q);
+        uint256 s = discardedBitWidth(q);
         if (precise) {
             uint256 step = uint256(1) << s;
             if (value & (step - 1) != 0) revert NotAligned(value, step);
@@ -109,21 +112,21 @@ library UintQuantizationLib {
     // Decoding
     // -------------------------------------------------------------------------
 
-    /// @notice Left-shifts `encoded` by shift, restoring discarded bits as zeros (lower bound).
-    /// @dev    The caller must ensure `encoded < 2**targetBits(q)`. Passing a larger value
+    /// @notice Left-shifts `encoded` by discardedBitWidth, restoring discarded bits as zeros (lower bound).
+    /// @dev    The caller must ensure `encoded < 2**encodedBitWidth(q)`. Passing a larger value
     ///         produces a result that may silently wrap or exceed the scheme's representable range.
     ///         Values returned by `encode` always satisfy this constraint.
     function decode(Quant q, uint256 encoded) internal pure returns (uint256) {
         unchecked {
-            return encoded << shift(q);
+            return encoded << discardedBitWidth(q);
         }
     }
 
     /// @notice Like `decode` but fills the discarded bits with ones (upper bound within the step).
-    /// @dev    Same precondition as `decode`: `encoded` must be less than `2**targetBits(q)`.
+    /// @dev    Same precondition as `decode`: `encoded` must be less than `2**encodedBitWidth(q)`.
     function decodeMax(Quant q, uint256 encoded) internal pure returns (uint256) {
         unchecked {
-            uint256 s = shift(q);
+            uint256 s = discardedBitWidth(q);
             return (encoded << s) | ((uint256(1) << s) - 1);
         }
     }
@@ -134,7 +137,7 @@ library UintQuantizationLib {
 
     /// @notice Returns the bits discarded during floor encoding (value mod stepSize).
     function remainder(Quant q, uint256 value) internal pure returns (uint256) {
-        return value & ((uint256(1) << shift(q)) - 1);
+        return value & ((uint256(1) << discardedBitWidth(q)) - 1);
     }
 
     /// @notice Returns true when `value` is exactly representable (step-aligned).
@@ -147,17 +150,17 @@ library UintQuantizationLib {
         return value <= max(q);
     }
 
-    /// @notice Rounds `value` down to the nearest step boundary (clears low `shift` bits).
+    /// @notice Rounds `value` down to the nearest step boundary (clears low `discardedBitWidth` bits).
     function floor(Quant q, uint256 value) internal pure returns (uint256) {
-        return value & ~((uint256(1) << shift(q)) - 1);
+        return value & ~((uint256(1) << discardedBitWidth(q)) - 1);
     }
 
     /// @notice Rounds `value` up to the nearest step boundary. Returns `value` unchanged when
-    ///         shift is 0 or `value` is already aligned.
+    ///         discardedBitWidth is 0 or `value` is already aligned.
     /// @dev    Callers must ensure `value + stepSize - 1 <= type(uint256).max` to avoid overflow
     ///         on non-aligned inputs. This function does not perform that check.
     function ceil(Quant q, uint256 value) internal pure returns (uint256) {
-        uint256 s = shift(q);
+        uint256 s = discardedBitWidth(q);
         if (s == 0) return value;
         uint256 mask = (uint256(1) << s) - 1;
         if (value & mask == 0) return value;