feat: pack ProperQF PackedProject into 1 slot (uint96 + uint160)

Compress per-project storage from 2 slots to 1 by using asymmetric
field widths with inline shift-based quantization:

- sumContributions: uint96 with shift=32 (lossy, step ~4.3 nanotoken)
- sumSquareRoots: uint160 lossless (sqrt-compressed range needs full resolution)

Global sums (totalLinearSum, totalQuadraticSum) stay exact because
quantization errors cancel in the delta update pattern. Test vote
weights scaled by W=65536 so weight^2 aligns to the quantization step.

Author: 0xferit

src/mechanisms/voting-strategy/ProperQF.sol

@@ -10,10 +10,40 @@ 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 : uint96, shift=32 (lossy quantization)
+ *        sumSquareRoots   : uint160, no quantization (plain checked downcast)
+ *
+ *      sumContributions quantization:
+ *        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^96 - 1) << 32     (~3.40e38 wei = ~3.40e20 tokens at 18 decimals)
+ *
+ *        Contribution values entering ProperQF are dimensionless quadratic costs
+ *        (weight^2) from the mechanism layer, NOT raw token amounts. For any
+ *        realistic deposit the resulting contributions are well above the step size.
+ *
+ *        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 uint160, plain checked downcast from uint256.
+ *        Solidity 0.8+ reverts on truncation. No quantization applied.
  */
 abstract contract ProperQF {
     using Math for uint256;
 
+    // ── Quantization constants for sumContributions ────────────────────────
+    /// @dev Right-shift applied when encoding sumContributions into uint96
+    uint256 internal constant CONTRIBUTIONS_SHIFT = 32;
+    /// @dev Minimum non-zero representable value for sumContributions
+    uint256 internal constant CONTRIBUTIONS_STEP = uint256(1) << CONTRIBUTIONS_SHIFT;
+    /// @dev Maximum representable value for sumContributions after decode
+    uint256 internal constant CONTRIBUTIONS_MAX = uint256(type(uint96).max) << CONTRIBUTIONS_SHIFT;
+
     // Custom Errors
     error ContributionMustBePositive();
     error VoteWeightMustBePositive();
@@ -24,24 +54,33 @@ abstract contract ProperQF {
     error LinearSumUnderflow();
     error DenominatorMustBePositive();
     error AlphaMustBeLessOrEqualToOne();
+    error ContributionsOverflow(uint256 value, uint256 max);
 
     /// @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: 96 + 160 = 256 bits = 1 slot
+    struct PackedProject {
+        /// @notice Sum of contributions, quantized: stored = value >> 32
+        uint96 sumContributions;
+        /// @notice Sum of square roots, stored without quantization
+        uint160 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)
@@ -78,10 +117,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
@@ -137,34 +177,29 @@ 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
+     * @dev Skips input validation for gas optimization when caller guarantees correctness.
+     *      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 voteWeight Vote weight (dimensionless; sqrt of contribution)
      */
     function _processVoteUnchecked(uint256 projectId, uint256 contribution, uint256 voteWeight) internal {
         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;
-
-        s.totalQuadraticSum = newTotalQuadraticSum;
-        s.totalLinearSum = newTotalLinearSum;
+        if (s.totalLinearSum < oldSumContributions) revert LinearSumUnderflow();
 
-        project.sumSquareRoots = newSumSquareRoots;
-        project.sumContributions = newSumContributions;
+        s.totalQuadraticSum = s.totalQuadraticSum - oldQuadraticFunding + newQuadraticFunding;
+        s.totalLinearSum = s.totalLinearSum - oldSumContributions + newSumContributions;
 
-        s.projects[projectId] = project;
+        _writeProject(projectId, newSumContributions, newSumSquareRoots);
 
         s.totalFunding = _calculateWeightedTotalFunding();
     }
@@ -201,18 +236,39 @@ 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 = uint256(packed.sumContributions) << CONTRIBUTIONS_SHIFT;
+        sumSquareRoots = uint256(packed.sumSquareRoots);
+    }
+
+    /// @notice Encode and store full-width values into packed project storage
+    /// @dev sumContributions is right-shifted (lossy floor) then checked against uint96.
+    ///      sumSquareRoots uses a plain checked downcast to uint160.
+    function _writeProject(uint256 projectId, uint256 sumContributions, uint256 sumSquareRoots) internal {
+        uint256 encoded = sumContributions >> CONTRIBUTIONS_SHIFT;
+        if (encoded > type(uint96).max) revert ContributionsOverflow(sumContributions, CONTRIBUTIONS_MAX);
+        _getProperQFStorage().projects[projectId] = PackedProject({
+            sumContributions: uint96(encoded),
+            sumSquareRoots: uint160(sumSquareRoots)
+        });
+    }
+
     /**
      * @notice Set alpha parameter determining ratio between quadratic and linear funding
      * @param newNumerator Numerator of new alpha (0 ≤ numerator ≤ denominator)

test/unit/mechanisms/allocation/MechanismBranchCoverage.t.sol

@@ -1034,13 +1034,14 @@ contract ProperQFBranchCoverageTest is Test {
 
     // _processVote: valid vote (success path - contributes to branch coverage of all checks passing)
     function test_processVote_validVote_succeeds() public {
-        // contribution = 10000, sqrt(10000) = 100, voteWeight = 100
-        qf.exposed_processVote(1, 10000, 100);
+        // contribution = 10000e18, sqrt(10000e18) = 100e9, voteWeight = 100e9
+        qf.exposed_processVote(1, 10000e18, 100e9);
 
-        // Verify it was recorded
+        // Verify it was recorded (sumContributions is lossy due to quantization)
+        uint256 step = uint256(1) << 32;
         ProperQF.Project memory project = qf.projects(1);
-        assertEq(project.sumContributions, 10000);
-        assertEq(project.sumSquareRoots, 100);
+        assertApproxEqAbs(project.sumContributions, 10000e18, step);
+        assertEq(project.sumSquareRoots, 100e9);
     }
 
     // _calculateOptimalAlpha: quadraticSum == linearSum exactly (edge case)
@@ -1098,7 +1099,7 @@ contract ProperQFBranchCoverageTest is Test {
 
     // totalFunding getter
     function test_totalFunding_afterVotes() public {
-        qf.exposed_processVote(1, 10000, 100);
+        qf.exposed_processVote(1, 10000e18, 100e9);
         assertTrue(qf.totalFunding() > 0);
     }
 }
@@ -1990,6 +1991,7 @@ contract QVMBranchCoverageTest is Test {
     uint256 constant QUORUM = 10;
     uint256 constant TIMELOCK_DELAY = 1 days;
     uint256 constant GRACE_PERIOD = 7 days;
+    uint256 constant W = 65536;
 
     function _tam() internal view returns (TokenizedAllocationMechanism) {
         return TokenizedAllocationMechanism(address(mechanism));
@@ -2009,7 +2011,7 @@ contract QVMBranchCoverageTest is Test {
             symbol: "QVB",
             votingDelay: VOTING_DELAY,
             votingPeriod: VOTING_PERIOD,
-            quorumShares: QUORUM,
+            quorumShares: QUORUM * W * W,
             timelockDelay: TIMELOCK_DELAY,
             gracePeriod: GRACE_PERIOD,
             owner: address(0)
@@ -2060,7 +2062,7 @@ contract QVMBranchCoverageTest is Test {
 
         vm.warp(block.timestamp + VOTING_DELAY + 1);
         vm.prank(alice);
-        _tam().castVote(pid, TokenizedAllocationMechanism.VoteType.For, 20, recipient1);
+        _tam().castVote(pid, TokenizedAllocationMechanism.VoteType.For, 20 * W, recipient1);
 
         // Call calculateOptimalAlpha through the mechanism
         (, uint256 den) = mechanism.calculateOptimalAlpha(50_000e18, DEPOSIT);
@@ -2082,7 +2084,7 @@ contract QVMBranchCoverageTest is Test {
 
         vm.prank(alice);
         vm.expectRevert(abi.encodeWithSelector(TokenizedAllocationMechanism.InvalidProposal.selector, 0));
-        _tam().castVote(0, TokenizedAllocationMechanism.VoteType.For, 10, recipient1);
+        _tam().castVote(0, TokenizedAllocationMechanism.VoteType.For, 10 * W, recipient1);
     }
 
     // ===== getProposalFunding: canceled proposal returns zeros =====
@@ -2094,7 +2096,7 @@ contract QVMBranchCoverageTest is Test {
 
         vm.warp(block.timestamp + VOTING_DELAY + 1);
         vm.prank(alice);
-        _tam().castVote(pid, TokenizedAllocationMechanism.VoteType.For, 10, recipient1);
+        _tam().castVote(pid, TokenizedAllocationMechanism.VoteType.For, 10 * W, recipient1);
 
         // Cancel the proposal
         vm.prank(alice);
@@ -2116,7 +2118,7 @@ contract QVMBranchCoverageTest is Test {
 
         vm.warp(block.timestamp + VOTING_DELAY + 1);
         vm.prank(alice);
-        _tam().castVote(pid, TokenizedAllocationMechanism.VoteType.For, 20, recipient1);
+        _tam().castVote(pid, TokenizedAllocationMechanism.VoteType.For, 20 * W, recipient1);
 
         (uint256 sumC, uint256 sumSq, uint256 qf, uint256 lf) = mechanism.getProposalFunding(pid);
         assertTrue(sumC > 0, "Should have contributions");
@@ -3013,35 +3015,40 @@ contract ProperQFDeepBranchTest is Test {
 
     // ===== _processVote: exact boundary - voteWeight^2 == contribution (success) =====
     function test_processVote_exactSqrt_succeeds() public {
-        qf.exposed_processVote(1, 100, 10);
+        // 100e18 = (10e9)^2
+        qf.exposed_processVote(1, 100e18, 10e9);
 
+        uint256 step = uint256(1) << 32;
         ProperQF.Project memory project = qf.projects(1);
-        assertEq(project.sumContributions, 100);
-        assertEq(project.sumSquareRoots, 10);
+        assertApproxEqAbs(project.sumContributions, 100e18, step);
+        assertEq(project.sumSquareRoots, 10e9);
     }
 
     // ===== _processVote: voteWeight at lower tolerance boundary =====
     function test_processVote_voteWeightAtLowerTolerance() public {
-        qf.exposed_processVote(1, 10000, 90);
+        // sqrt(10000e18) = 100e9, tolerance = 100e9/10 = 10e9, lower = 90e9
+        qf.exposed_processVote(1, 10000e18, 90e9);
 
         ProperQF.Project memory project = qf.projects(1);
-        assertEq(project.sumSquareRoots, 90);
+        assertEq(project.sumSquareRoots, 90e9);
     }
 
     // ===== _processVote: voteWeight below lower tolerance =====
     function test_processVote_voteWeightBelowLowerTolerance_reverts() public {
         vm.expectRevert(ProperQF.VoteWeightOutsideTolerance.selector);
-        qf.exposed_processVote(1, 10000, 89);
+        qf.exposed_processVote(1, 10000e18, 89e9);
     }
 
     // ===== _processVote: multiple votes on same project =====
     function test_processVote_multipleVotesSameProject() public {
-        qf.exposed_processVote(1, 10000, 100);
-        qf.exposed_processVote(1, 40000, 200);
+        qf.exposed_processVote(1, 10000e18, 100e9);
+        qf.exposed_processVote(1, 40000e18, 200e9);
 
+        uint256 step = uint256(1) << 32;
         ProperQF.Project memory project = qf.projects(1);
-        assertEq(project.sumContributions, 50000);
-        assertEq(project.sumSquareRoots, 300);
+        // 2 votes: tolerance = 2 * STEP
+        assertApproxEqAbs(project.sumContributions, 50000e18, 2 * step);
+        assertEq(project.sumSquareRoots, 300e9);
     }
 }
 
@@ -3359,7 +3366,7 @@ contract ProperQFUnderflowBranchTest is Test {
         qf.exposed_setAlpha(50, 100);
 
         // Process a vote - this internally calls _calculateWeightedTotalFunding
-        qf.exposed_processVote(1, 10000, 100);
+        qf.exposed_processVote(1, 10000e18, 100e9);
 
         // totalFunding should be updated
         uint256 totalFunding = qf.totalFunding();
@@ -3909,29 +3916,32 @@ contract ProperQFStorageUnderflowTest is Test {
     // ===== ProperQF line 156: QuadraticSumUnderflow =====
     // When totalQuadraticSum < oldQuadraticFunding (project.sumSquareRoots^2)
     function test_processVoteUnchecked_quadraticSumUnderflow_reverts() public {
+        uint256 step = uint256(1) << 32;
         // Set up a project with sumSquareRoots = 10, so oldQuadraticFunding = 100
-        qf.setProject(1, 100, 10);
+        // sumContributions must be step-aligned for exact round-trip
+        qf.setProject(1, 100 * step, 10);
         // Set totalQuadraticSum to a value less than 100
         qf.setTotalQuadraticSum(50);
-        qf.setTotalLinearSum(200);
+        qf.setTotalLinearSum(200 * step);
 
         // Now calling _processVoteUnchecked should trigger QuadraticSumUnderflow
         // because totalQuadraticSum (50) < oldQuadraticFunding (10*10 = 100)
         vm.expectRevert(ProperQF.QuadraticSumUnderflow.selector);
-        qf.exposed_processVoteUnchecked(1, 400, 20);
+        qf.exposed_processVoteUnchecked(1, 400 * step, 20);
     }
 
     // ===== ProperQF line 157: LinearSumUnderflow =====
     // When totalLinearSum < project.sumContributions
     function test_processVoteUnchecked_linearSumUnderflow_reverts() public {
-        // Set up a project with sumContributions = 500, sumSquareRoots = 10
-        qf.setProject(1, 500, 10);
+        uint256 step = uint256(1) << 32;
+        // Set up a project with sumContributions = 500*STEP, sumSquareRoots = 10
+        qf.setProject(1, 500 * step, 10);
         // Set totalQuadraticSum correctly (>= 10^2 = 100) but totalLinearSum too low
         qf.setTotalQuadraticSum(200);
-        qf.setTotalLinearSum(100); // 100 < 500 = project.sumContributions
+        qf.setTotalLinearSum(100 * step); // 100*STEP < 500*STEP = project.sumContributions
 
         vm.expectRevert(ProperQF.LinearSumUnderflow.selector);
-        qf.exposed_processVoteUnchecked(1, 400, 20);
+        qf.exposed_processVoteUnchecked(1, 400 * step, 20);
     }
 
     // ===== ProperQF: alphaNumerator() view function coverage =====