feat: pack ProperQF PackedProject into 1 slot (uint128 + uint128)

Compress per-project storage from 2 slots to 1 using symmetric uint128
field widths with lossy quantization for sumContributions via
uint-quantization-lib v7.0.1.

Layout: uint128 sumContributions (shift=32, lossy) + uint128 sumSquareRoots (lossless)

sumContributions: quantized via CONTRIBUTIONS_SCHEME (step=2^32, max~2^160).
sumSquareRoots: uint128 ceiling matches its arithmetic constraint (squared
on-chain, which overflows uint256 at 2^128).

Enforce weight alignment to MIN_VOTE_WEIGHT=2^16 so contribution=weight^2
is always step-aligned, making per-project sums lossless. Enforce
18-decimal input assumption via ProperQF constructor parameter to prevent
miscalibration by future inheritors.

Author: 0xferit

foundry.toml

@@ -68,5 +68,6 @@ staker = { version = "1.0.1", git = "https://github.com/withtally/staker", tag =
 surl = { version = "0.0.0", git = "https://github.com/memester-xyz/surl", rev = "5f92a5260c8e0198ca3ee6a16255d6cda4e0887a" }
 tokenized-strategy = { version = "3.0.4", git = "https://github.com/yearn/tokenized-strategy", tag = "v3.0.4" }
 tokenized-strategy-periphery = { version = "3.0.2", git = "https://github.com/yearn/tokenized-strategy-periphery", tag = "v3.0.2" }
+uint-quantization-lib = "7.0.1"
 
 # See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

remappings.txt

@@ -15,4 +15,5 @@ solmate/=dependencies/solmate-6.8.0/
 staker/=dependencies/staker-1.0.1/src/
 surl/=dependencies/surl-0.0.0/src/
 tokenized-strategy/=dependencies/tokenized-strategy-3.0.4/
+uint-quantization-lib/=dependencies/uint-quantization-lib-7.0.1/
 zodiac/=dependencies/gnosisguild-zodiac-4.1.1/contracts/

soldeer.lock

@@ -98,3 +98,10 @@ name = "tokenized-strategy-periphery"
 version = "3.0.2"
 git = "https://github.com/yearn/tokenized-strategy-periphery"
 rev = "d732e918b208a9b2c33c71ea0ea9e8eb880cfc6e"
+
+[[dependencies]]
+name = "uint-quantization-lib"
+version = "7.0.1"
+url = "https://soldeer-revisions.s3.amazonaws.com/uint-quantization-lib/7_0_1_13-03-2026_21:14:08_uint-quantization-lib.zip"
+checksum = "653124bc51721b850fe4bbb737b76fba234d1bee4f29ac970cb693898e568a6d"
+integrity = "b96a0a9995bc836ff598aae62177af294ce68a4d417d2abdbf54a1f7b9256869"

src/mechanisms/mechanism/QuadraticVotingMechanism.sol

@@ -19,10 +19,10 @@ import { IERC20Metadata } from "@openzeppelin/contracts/token/ERC20/extensions/I
  *      - Prevents whale dominance (expensive to cast many votes)
  *      - Benefits: Small contributors have proportionally more impact
  *
- *      VOTE COST EXAMPLES:
- *      - 10 votes costs 100 voting power (10²)
- *      - 20 votes costs 400 voting power (20²)
- *      - 100 votes costs 10,000 voting power (100²)
+ *      VOTE COST EXAMPLES (voting power is in 18-decimal-normalized space):
+ *      - weight 65536 costs ~4.3e9 voting power (65536²) : minimum vote
+ *      - weight 1e9    costs 1e18 voting power (1e9²)     : ~1 token
+ *      - weight 1e12   costs 1e24 voting power (1e12²)    : ~1M tokens
  *
  *      ONE-TIME VOTING:
  *      ⚠️  Users can only vote ONCE per proposal
@@ -46,9 +46,17 @@ contract QuadraticVotingMechanism is BaseAllocationMechanism, ProperQF {
     error ZeroAddressCannotPropose();
     error OnlyForVotesSupported();
     error InsufficientVotingPowerForQuadraticCost();
+    error WeightBelowMinimum(uint256 weight, uint256 minimum);
+    error WeightNotAligned(uint256 weight, uint256 alignment);
 
     error AlreadyVoted(address voter, uint256 pid);
 
+    /// @notice Minimum vote weight, derived from sumContributions quantization.
+    /// @dev contribution = weight^2 must be >= CONTRIBUTIONS_SCHEME.stepSize() = 2^32,
+    ///      therefore weight >= 2^16 = 65536. Since voting power is normalized to 18 decimals
+    ///      (see _getVotingPowerHook), this costs ~4.3 nanotoken regardless of the asset.
+    uint256 public constant MIN_VOTE_WEIGHT = 1 << 16;
+
     // ============================================
     // STATE VARIABLES
     // ============================================
@@ -71,7 +79,7 @@ contract QuadraticVotingMechanism is BaseAllocationMechanism, ProperQF {
         AllocationConfig memory _config,
         uint256 _alphaNumerator,
         uint256 _alphaDenominator
-    ) BaseAllocationMechanism(_implementation, _config) {
+    ) BaseAllocationMechanism(_implementation, _config) ProperQF(18) {
         _setAlpha(_alphaNumerator, _alphaDenominator);
     }
 
@@ -204,6 +212,8 @@ contract QuadraticVotingMechanism is BaseAllocationMechanism, ProperQF {
         uint256 oldPower
     ) internal virtual override returns (uint256) {
         if (choice != TokenizedAllocationMechanism.VoteType.For) revert OnlyForVotesSupported();
+        if (weight < MIN_VOTE_WEIGHT) revert WeightBelowMinimum(weight, MIN_VOTE_WEIGHT);
+        if (weight % MIN_VOTE_WEIGHT != 0) revert WeightNotAligned(weight, MIN_VOTE_WEIGHT);
 
         // Check if voter has already voted on this proposal
         if (hasVoted[pid][voter]) revert AlreadyVoted(voter, pid);

src/mechanisms/voting-strategy/ProperQF.sol

@@ -2,6 +2,7 @@
 pragma solidity ^0.8.0;
 
 import { Math } from "@openzeppelin/contracts/utils/math/Math.sol";
+import { Quant, UintQuantizationLib as QuantLib } from "uint-quantization-lib/src/UintQuantizationLib.sol";
 
 /**
  * @title Proper Quadratic Funding (QF) math and tallying
@@ -10,10 +11,55 @@ import { Math } from "@openzeppelin/contracts/utils/math/Math.sol";
  * @notice Incremental QF tallying utilities with alpha-weighted quadratic/linear funding.
  * @dev Provides storage isolation via deterministic slot, input validation helpers,
  *      and funding aggregation with well-defined rounding behavior.
+ *
+ *      Storage packing: each project occupies exactly 1 slot (256 bits):
+ *        sumContributions : uint128, shift=32 (lossy quantization via UintQuantizationLib)
+ *        sumSquareRoots   : uint128, shift=0  (lossless, no quantization)
+ *
+ *      sumContributions quantization (CONTRIBUTIONS_SCHEME):
+ *        encode: stored = value >> 32  (floors to nearest step)
+ *        decode: value  = stored << 32
+ *        step   = 2^32 = 4,294,967,296 wei (~4.3 nanotoken at 18 decimals)
+ *        max    = (2^128 - 1) << 32    (~1.46e48 wei = ~1.46e30 tokens at 18 decimals)
+ *
+ *        Contribution values entering ProperQF are quadratic costs (weight^2) in the
+ *        18-decimal-normalized voting-power space (see QuadraticVotingMechanism
+ *        ._normalizeToDecimals). Since voting power is always normalized to 18 decimals
+ *        regardless of the underlying asset, the step size of ~4.3 nanotoken applies
+ *        uniformly. Minimum weight = sqrt(step) = 2^16 = 65536, enforced by the
+ *        ContributionBelowMinimum guard in _processVoteUnchecked.
+ *
+ *        Per-project sumContributions readback is lossy (floored to step boundary).
+ *        Global totalLinearSum stays exact: the delta update pattern in
+ *        _processVoteUnchecked computes (old - decoded + (decoded + contribution)),
+ *        so the quantization errors cancel.
+ *
+ *      sumSquareRoots: stored as uint128, no quantization.
+ *        The uint128 ceiling matches the arithmetic constraint: sumSquareRoots is
+ *        squared on-chain (sumSR * sumSR), which overflows uint256 at 2^128.
+ *        Overflow protection comes from Solidity 0.8's checked uint128() downcast
+ *        in _writeProject (defense-in-depth; the squaring catches it first).
  */
 abstract contract ProperQF {
     using Math for uint256;
 
+    /// @notice Quantization scheme for sumContributions: stored as uint128, shift=32.
+    /// @dev Contributions are quadratic costs (weight^2) in 18-decimal-normalized voting-power
+    ///      space (see QuadraticVotingMechanism._normalizeToDecimals), so these bounds hold
+    ///      uniformly regardless of the underlying asset's native decimals.
+    ///      Step size: 2^32 ~= 4.3e9 wei (~4.3 nanotoken) : floor-rounding error per encode.
+    ///      Max value: (2^128 - 1) << 32 ~= 1.46e48 wei (~1.46e30 tokens).
+    ///      Global sums (totalLinearSum) stay exact because quantization errors cancel in the
+    ///      delta update pattern of _processVoteUnchecked; only per-project readback is lossy.
+    /// Equivalent to QuantLib.create(32, 128); constant required to avoid immutable bloat.
+    Quant internal constant CONTRIBUTIONS_SCHEME = Quant.wrap(uint16((128 << 8) | 32));
+
+    /// @dev sumSquareRoots is stored as uint128 with no quantization.
+    ///      Max value: 2^128 - 1 ~= 3.40e38.
+    ///      The uint128 ceiling matches the arithmetic constraint: sumSquareRoots is squared
+    ///      on-chain (sumSR * sumSR), which overflows uint256 at 2^128.
+    ///      Overflow protection comes from Solidity 0.8's checked uint128() downcast in _writeProject.
+
     // Custom Errors
     error ContributionMustBePositive();
     error VoteWeightMustBePositive();
@@ -24,24 +70,40 @@ abstract contract ProperQF {
     error LinearSumUnderflow();
     error DenominatorMustBePositive();
     error AlphaMustBeLessOrEqualToOne();
+    error ContributionBelowMinimum(uint256 contribution, uint256 minimum);
+    error UnsupportedInputDecimals(uint8 provided, uint8 expected);
+
+    /// @notice Expected decimal precision for all contribution/voting-power inputs.
+    /// @dev CONTRIBUTIONS_SCHEME's step size (2^32 ~= 4.3 nanotoken) and MIN_VOTE_WEIGHT (2^16)
+    ///      are calibrated for 18-decimal-normalized values. Feeding lower-precision inputs
+    ///      (e.g., raw 6-decimal USDC) would cause the step to silently swallow entire contributions.
+    uint8 internal constant INPUT_DECIMALS = 18;
 
     /// @notice Storage slot for ProperQF storage (ERC-7201 namespaced storage)
     /// @dev https://eips.ethereum.org/EIPS/eip-7201
     bytes32 private constant STORAGE_SLOT =
         bytes32(uint256(keccak256(abi.encode(uint256(keccak256(bytes("proper.qf.storage"))) - 1))) & ~uint256(0xff));
 
-    /// @notice Per-project aggregated sums
+    /// @notice Per-project aggregated sums (public return type, decoded)
     struct Project {
-        /// @notice Sum of contributions for this project (asset base units)
+        /// @notice Sum of contributions for this project (asset base units, lossy: floored to CONTRIBUTIONS_STEP)
         uint256 sumContributions;
         /// @notice Sum of square roots of all contributions (dimensionless)
         uint256 sumSquareRoots;
     }
 
+    /// @notice Packed per-project storage: 128 + 128 = 256 bits = 1 slot
+    struct PackedProject {
+        /// @notice Sum of contributions, quantized: stored = value >> 32
+        uint128 sumContributions;
+        /// @notice Sum of square roots, stored without quantization (ceiling matches squaring constraint)
+        uint128 sumSquareRoots;
+    }
+
     /// @notice Main storage struct containing all mutable state for ProperQF
     struct ProperQFStorage {
-        /// @notice Mapping of project IDs to project data
-        mapping(uint256 => Project) projects;
+        /// @notice Mapping of project IDs to packed project data (1 slot each)
+        mapping(uint256 => PackedProject) projects;
         /// @notice Numerator for alpha (dimensionless; 1.0 = denominator)
         uint256 alphaNumerator;
         /// @notice Denominator for alpha (must be > 0)
@@ -62,8 +124,11 @@ abstract contract ProperQF {
     /// @param newDenominator New alpha denominator
     event AlphaUpdated(uint256 oldNumerator, uint256 oldDenominator, uint256 newNumerator, uint256 newDenominator);
 
-    /// @notice Constructor initializes default alpha values in storage
-    constructor() {
+    /// @notice Constructor validates input decimal precision and initializes default alpha values.
+    /// @param inputDecimals Must be 18. Forces inheritors to explicitly acknowledge the
+    ///        decimal precision that CONTRIBUTIONS_SCHEME and MIN_VOTE_WEIGHT are calibrated for.
+    constructor(uint8 inputDecimals) {
+        if (inputDecimals != INPUT_DECIMALS) revert UnsupportedInputDecimals(inputDecimals, INPUT_DECIMALS);
         ProperQFStorage storage s = _getProperQFStorage();
         s.alphaNumerator = 10000; // Default alpha = 1.0 (10000/10000)
         s.alphaDenominator = 10000;
@@ -78,10 +143,11 @@ abstract contract ProperQF {
         }
     }
 
-    /// @notice Returns project aggregated sums
+    /// @notice Returns project aggregated sums (decoded from packed storage)
     /// @param projectId ID of the project to query
     function projects(uint256 projectId) public view returns (Project memory) {
-        return _getProperQFStorage().projects[projectId];
+        (uint256 sumC, uint256 sumSR) = _readProject(projectId);
+        return Project({ sumContributions: sumC, sumSquareRoots: sumSR });
     }
 
     /// @notice Returns alpha numerator
@@ -136,35 +202,35 @@ abstract contract ProperQF {
     }
 
     /**
-     * @notice Process vote without validation - for trusted callers who have already validated
-     * @dev Skips input validation for gas optimization when caller guarantees correctness
+     * @notice Process vote without full validation - only enforces the quantization minimum.
+     * @dev Skips sqrt-tolerance checks for gas optimization when caller guarantees correctness.
+     *      Enforces contribution >= CONTRIBUTIONS_SCHEME.stepSize() to prevent silent zeroing
+     *      of per-project sumContributions due to floor quantization.
+     *      Delta update pattern ensures totalLinearSum stays exact despite lossy per-project storage.
      * @param projectId ID of project to update
-     * @param contribution Contribution amount (asset base units)
+     * @param contribution Contribution amount (must be >= CONTRIBUTIONS_SCHEME.stepSize())
      * @param voteWeight Vote weight (dimensionless; sqrt of contribution)
      */
     function _processVoteUnchecked(uint256 projectId, uint256 contribution, uint256 voteWeight) internal {
+        uint256 minContribution = CONTRIBUTIONS_SCHEME.stepSize();
+        if (contribution < minContribution) revert ContributionBelowMinimum(contribution, minContribution);
+
         ProperQFStorage storage s = _getProperQFStorage();
-        Project memory project = s.projects[projectId];
+        (uint256 oldSumContributions, uint256 oldSumSquareRoots) = _readProject(projectId);
 
-        uint256 newSumSquareRoots = project.sumSquareRoots + voteWeight;
-        uint256 newSumContributions = project.sumContributions + contribution;
+        uint256 newSumSquareRoots = oldSumSquareRoots + voteWeight;
+        uint256 newSumContributions = oldSumContributions + contribution;
 
-        uint256 oldQuadraticFunding = project.sumSquareRoots * project.sumSquareRoots;
+        uint256 oldQuadraticFunding = oldSumSquareRoots * oldSumSquareRoots;
         uint256 newQuadraticFunding = newSumSquareRoots * newSumSquareRoots;
 
         if (s.totalQuadraticSum < oldQuadraticFunding) revert QuadraticSumUnderflow();
-        if (s.totalLinearSum < project.sumContributions) revert LinearSumUnderflow();
-
-        uint256 newTotalQuadraticSum = s.totalQuadraticSum - oldQuadraticFunding + newQuadraticFunding;
-        uint256 newTotalLinearSum = s.totalLinearSum - project.sumContributions + newSumContributions;
+        if (s.totalLinearSum < oldSumContributions) revert LinearSumUnderflow();
 
-        s.totalQuadraticSum = newTotalQuadraticSum;
-        s.totalLinearSum = newTotalLinearSum;
+        s.totalQuadraticSum = s.totalQuadraticSum - oldQuadraticFunding + newQuadraticFunding;
+        s.totalLinearSum = s.totalLinearSum - oldSumContributions + newSumContributions;
 
-        project.sumSquareRoots = newSumSquareRoots;
-        project.sumContributions = newSumContributions;
-
-        s.projects[projectId] = project;
+        _writeProject(projectId, newSumContributions, newSumSquareRoots);
 
         s.totalFunding = _calculateWeightedTotalFunding();
     }
@@ -201,18 +267,37 @@ abstract contract ProperQF {
         returns (uint256 sumContributions, uint256 sumSquareRoots, uint256 quadraticFunding, uint256 linearFunding)
     {
         ProperQFStorage storage s = _getProperQFStorage();
-        Project storage project = s.projects[projectId];
+        (uint256 sumC, uint256 sumSR) = _readProject(projectId);
 
-        uint256 rawQuadraticFunding = project.sumSquareRoots * project.sumSquareRoots;
+        uint256 rawQuadraticFunding = sumSR * sumSR;
 
         return (
-            project.sumContributions,
-            project.sumSquareRoots,
+            sumC,
+            sumSR,
             (rawQuadraticFunding * s.alphaNumerator) / s.alphaDenominator,
-            (project.sumContributions * (s.alphaDenominator - s.alphaNumerator)) / s.alphaDenominator
+            (sumC * (s.alphaDenominator - s.alphaNumerator)) / s.alphaDenominator
         );
     }
 
+    // ── Pack/unpack helpers ──────────────────────────────────────────────
+
+    /// @notice Decode packed project storage into full-width uint256 values
+    function _readProject(uint256 projectId) internal view returns (uint256 sumContributions, uint256 sumSquareRoots) {
+        PackedProject storage packed = _getProperQFStorage().projects[projectId];
+        sumContributions = CONTRIBUTIONS_SCHEME.decode(uint256(packed.sumContributions));
+        sumSquareRoots = uint256(packed.sumSquareRoots);
+    }
+
+    /// @notice Encode and store full-width values into packed project storage
+    /// @dev sumContributions: reverts with Overflow(value, max) if it exceeds CONTRIBUTIONS_SCHEME.max().
+    ///      sumSquareRoots: reverts via Solidity 0.8 checked downcast if it exceeds type(uint128).max.
+    function _writeProject(uint256 projectId, uint256 sumContributions, uint256 sumSquareRoots) internal {
+        _getProperQFStorage().projects[projectId] = PackedProject({
+            sumContributions: uint128(CONTRIBUTIONS_SCHEME.encode(sumContributions)),
+            sumSquareRoots: uint128(sumSquareRoots)
+        });
+    }
+
     /**
      * @notice Set alpha parameter determining ratio between quadratic and linear funding
      * @param newNumerator Numerator of new alpha (0 ≤ numerator ≤ denominator)

test/integration/regen/RegenERC1271Integration.t.sol

@@ -248,7 +248,7 @@ contract RegenERC1271IntegrationTest is Test {
         vm.warp(block.timestamp + VOTING_DELAY + 1);
 
         // Prepare vote signature - use sqrt of voting power for quadratic voting
-        uint256 voteWeight = 1; // Start with a small weight
+        uint256 voteWeight = 1 << 16; // MIN_VOTE_WEIGHT: quadratic cost = 2^32
         uint256 voteDeadline = block.timestamp + 1 hours;
         uint256 voteNonce = TokenizedAllocationMechanism(address(allocationMechanism)).nonces(address(contractSigner));