@ballkidz/defifa 0.0.12 → 0.0.14

package/src/DefifaGovernor.sol

@@ -12,6 +12,8 @@ import {DefifaGamePhase} from "./enums/DefifaGamePhase.sol";
 import {DefifaScorecardState} from "./enums/DefifaScorecardState.sol";
 import {IDefifaDeployer} from "./interfaces/IDefifaDeployer.sol";
 import {IDefifaGovernor} from "./interfaces/IDefifaGovernor.sol";
+import {IJB721TiersHookStore} from "@bananapus/721-hook-v6/src/interfaces/IJB721TiersHookStore.sol";
+import {JB721Tier} from "@bananapus/721-hook-v6/src/structs/JB721Tier.sol";
 import {IDefifaHook} from "./interfaces/IDefifaHook.sol";
 import {DefifaAttestations} from "./structs/DefifaAttestations.sol";
 import {DefifaScorecard} from "./structs/DefifaScorecard.sol";
@@ -30,6 +32,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     error DefifaGovernor_GameNotFound();
     error DefifaGovernor_IncorrectTierOrder();
     error DefifaGovernor_NotAllowed();
+    error DefifaGovernor_NotAttested();
     error DefifaGovernor_Uint48Overflow();
     error DefifaGovernor_UnknownProposal();
     error DefifaGovernor_UnownedProposedCashoutValue();
@@ -65,6 +68,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     //*********************************************************************//
 
     /// @notice The scorecard information, packed into a uint256.
+    /// @dev Bits 0-47: attestationStartTime, bits 48-95: attestationGracePeriod, bits 96-143: timelockDuration.
     /// @custom:param gameId The ID of the game for which the scorecard info applies.
     mapping(uint256 => uint256) internal _packedScorecardInfoOf;
 
@@ -78,6 +82,19 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     /// @custom:param scorecardId The ID of the scorecard that has been attested to.
     mapping(uint256 => mapping(uint256 => DefifaAttestations)) internal _scorecardAttestationsOf;
 
+    /// @notice Snapshot of pending reserves per tier at scorecard submission time.
+    /// @dev Prevents reserve dilution between submission and attestation.
+    /// @custom:param gameId The ID of the game.
+    /// @custom:param scorecardId The ID of the scorecard.
+    /// @custom:param tierId The tier ID (1-indexed).
+    mapping(uint256 => mapping(uint256 => mapping(uint256 => uint256))) internal _pendingReservesSnapshotOf;
+
+    /// @notice Tier weights per scorecard for BWA computation.
+    /// @custom:param gameId The ID of the game.
+    /// @custom:param scorecardId The ID of the scorecard.
+    /// @custom:param tierId The tier ID (0-indexed).
+    mapping(uint256 => mapping(uint256 => mapping(uint256 => uint256))) internal _scorecardTierWeightsOf;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -97,37 +114,48 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     function attestToScorecardFrom(uint256 gameId, uint256 scorecardId) external override returns (uint256 weight) {
         // Get the game's current funding cycle along with its metadata.
         // slither-disable-next-line unused-return
-        (, JBRulesetMetadata memory _metadata) = CONTROLLER.currentRulesetOf(gameId);
+        (, JBRulesetMetadata memory metadata) = CONTROLLER.currentRulesetOf(gameId);
 
         // Make sure the game is in its scoring phase.
-        if (IDefifaHook(_metadata.dataHook).gamePhaseReporter().currentGamePhaseOf(gameId) != DefifaGamePhase.SCORING) {
+        if (IDefifaHook(metadata.dataHook).gamePhaseReporter().currentGamePhaseOf(gameId) != DefifaGamePhase.SCORING) {
             revert DefifaGovernor_NotAllowed();
         }
 
         // Keep a reference to the scorecard being attested to.
-        DefifaScorecard storage _scorecard = _scorecardOf[gameId][scorecardId];
+        DefifaScorecard storage scorecard = _scorecardOf[gameId][scorecardId];
 
         // Keep a reference to the scorecard state.
-        DefifaScorecardState _state = stateOf({gameId: gameId, scorecardId: scorecardId});
+        DefifaScorecardState state = stateOf({gameId: gameId, scorecardId: scorecardId});
 
-        if (_state != DefifaScorecardState.ACTIVE && _state != DefifaScorecardState.SUCCEEDED) {
+        if (
+            state != DefifaScorecardState.ACTIVE && state != DefifaScorecardState.SUCCEEDED
+                && state != DefifaScorecardState.QUEUED
+        ) {
             revert DefifaGovernor_NotAllowed();
         }
 
         // Keep a reference to the attestations for the scorecard.
-        DefifaAttestations storage _attestations = _scorecardAttestationsOf[gameId][scorecardId];
+        DefifaAttestations storage attestations = _scorecardAttestationsOf[gameId][scorecardId];
 
         // Make sure the account isn't attesting to the same scorecard again.
-        if (_attestations.hasAttested[msg.sender]) revert DefifaGovernor_AlreadyAttested();
+        if (attestations.attestedWeightOf[msg.sender] != 0) revert DefifaGovernor_AlreadyAttested();
 
-        // Get a reference to the attestation weight.
-        weight = getAttestationWeight({gameId: gameId, account: msg.sender, timestamp: _scorecard.attestationsBegin});
+        // Get a reference to the BWA-adjusted attestation weight, snapshotted at one second before
+        // `attestationsBegin`. Using `attestationsBegin - 1` ensures the checkpoint is from before the
+        // attestation window opens, preventing same-block transfer/re-attest exploits.
+        weight = getBWAAttestationWeight({
+            gameId: gameId, scorecardId: scorecardId, account: msg.sender, timestamp: scorecard.attestationsBegin - 1
+        });
+
+        // Revert if BWA reduces this account's power to zero (e.g. 100% beneficiary of the scorecard).
+        // Without this guard, zero-weight attestors could call repeatedly since attestedWeightOf stays 0.
+        if (weight == 0) revert DefifaGovernor_NotAllowed();
 
         // Increase the attestation count.
-        _attestations.count += weight;
+        attestations.count += weight;
 
-        // Store the fact that the account has attested to the scorecard.
-        _attestations.hasAttested[msg.sender] = true;
+        // Store the BWA weight that was added (used for accurate subtraction on revoke).
+        attestations.attestedWeightOf[msg.sender] = weight;
 
         emit ScorecardAttested(gameId, scorecardId, weight, msg.sender);
     }
@@ -149,13 +177,13 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
 
         // Get the game's current funding cycle along with its metadata.
         // slither-disable-next-line unused-return
-        (, JBRulesetMetadata memory _metadata) = CONTROLLER.currentRulesetOf(gameId);
+        (, JBRulesetMetadata memory metadata) = CONTROLLER.currentRulesetOf(gameId);
 
         // Build the calldata to the target
-        bytes memory _calldata = _buildScorecardCalldataFor(tierWeights);
+        bytes memory scorecardCalldata = _buildScorecardCalldataFor(tierWeights);
 
         // Attempt to execute the proposal.
-        scorecardId = _hashScorecardOf({gameHook: _metadata.dataHook, calldataBytes: _calldata});
+        scorecardId = _hashScorecardOf({gameHook: metadata.dataHook, calldataBytes: scorecardCalldata});
 
         // Make sure the proposal being ratified has succeeded.
         if (stateOf({gameId: gameId, scorecardId: scorecardId}) != DefifaScorecardState.SUCCEEDED) {
@@ -166,7 +194,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         ratifiedScorecardIdOf[gameId] = scorecardId;
 
         // Execute the scorecard via low-level call since the governor is the delegate's owner.
-        (bool success, bytes memory returndata) = _metadata.dataHook.call(_calldata);
+        (bool success, bytes memory returndata) = metadata.dataHook.call(scorecardCalldata);
         // slither-disable-next-line unused-return
         Address.verifyCallResult({success: success, returndata: returndata});
 
@@ -178,6 +206,28 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         emit ScorecardRatified(gameId, scorecardId, msg.sender);
     }
 
+    /// @notice Revoke a previously submitted attestation. Only allowed during the ACTIVE phase.
+    /// @dev Once a scorecard enters QUEUED (grace period ended + quorum met), revocations are disabled.
+    /// This prevents the griefing loop (attest/revoke cycling) while allowing corrective action during debate.
+    /// @param gameId The ID of the game.
+    /// @param scorecardId The ID of the scorecard to revoke attestation from.
+    function revokeAttestationFrom(uint256 gameId, uint256 scorecardId) external virtual override {
+        // Only allow revocation during ACTIVE phase.
+        if (stateOf(gameId, scorecardId) != DefifaScorecardState.ACTIVE) revert DefifaGovernor_NotAllowed();
+
+        DefifaAttestations storage attestations = _scorecardAttestationsOf[gameId][scorecardId];
+        uint256 weight = attestations.attestedWeightOf[msg.sender];
+
+        // Must have previously attested.
+        if (weight == 0) revert DefifaGovernor_NotAttested();
+
+        // Subtract the weight and clear the attestation.
+        attestations.count -= weight;
+        attestations.attestedWeightOf[msg.sender] = 0;
+
+        emit AttestationRevoked(gameId, scorecardId, msg.sender, weight);
+    }
+
     /// @notice Submits a scorecard to be attested to.
     /// @param gameId The ID of the game.
     /// @param tierWeights The weights of each tier in the scorecard.
@@ -198,22 +248,22 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         if (_packedScorecardInfoOf[gameId] == 0) revert DefifaGovernor_GameNotFound();
 
         // Make sure no weight is assigned to an unowned tier.
-        uint256 _numberOfTierWeights = tierWeights.length;
+        uint256 numberOfTierWeights = tierWeights.length;
 
         // Get the game's current funding cycle along with its metadata.
         // slither-disable-next-line unused-return
-        (, JBRulesetMetadata memory _metadata) = CONTROLLER.currentRulesetOf(gameId);
+        (, JBRulesetMetadata memory metadata) = CONTROLLER.currentRulesetOf(gameId);
 
         // Make sure the game is in its scoring phase.
-        if (IDefifaHook(_metadata.dataHook).gamePhaseReporter().currentGamePhaseOf(gameId) != DefifaGamePhase.SCORING) {
+        if (IDefifaHook(metadata.dataHook).gamePhaseReporter().currentGamePhaseOf(gameId) != DefifaGamePhase.SCORING) {
             revert DefifaGovernor_NotAllowed();
         }
 
         // If there's a weight assigned to the tier, make sure there is a token backed by it.
-        for (uint256 _i; _i < _numberOfTierWeights; _i++) {
+        for (uint256 i; i < numberOfTierWeights; i++) {
             if (
-                tierWeights[_i].cashOutWeight > 0
-                    && IDefifaHook(_metadata.dataHook).currentSupplyOfTier(tierWeights[_i].id) == 0
+                tierWeights[i].cashOutWeight > 0
+                    && IDefifaHook(metadata.dataHook).currentSupplyOfTier(tierWeights[i].id) == 0
             ) {
                 revert DefifaGovernor_UnownedProposedCashoutValue();
             }
@@ -221,34 +271,81 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
 
         // Hash the scorecard.
         scorecardId =
-            _hashScorecardOf({gameHook: _metadata.dataHook, calldataBytes: _buildScorecardCalldataFor(tierWeights)});
+            _hashScorecardOf({gameHook: metadata.dataHook, calldataBytes: _buildScorecardCalldataFor(tierWeights)});
 
         // Store the scorecard
-        DefifaScorecard storage _scorecard = _scorecardOf[gameId][scorecardId];
-        if (_scorecard.attestationsBegin != 0) revert DefifaGovernor_DuplicateScorecard();
+        DefifaScorecard storage scorecard = _scorecardOf[gameId][scorecardId];
+        if (scorecard.attestationsBegin != 0) revert DefifaGovernor_DuplicateScorecard();
 
-        uint256 _attestationStartTime = attestationStartTimeOf(gameId);
-        uint256 _timeUntilAttestationsBegin =
-            block.timestamp > _attestationStartTime ? 0 : _attestationStartTime - block.timestamp;
+        uint256 attestationStartTime = attestationStartTimeOf(gameId);
+        uint256 timeUntilAttestationsBegin =
+            block.timestamp > attestationStartTime ? 0 : attestationStartTime - block.timestamp;
 
         // Casting to uint48 is safe because block.timestamp fits in uint48 until year 8921556.
         // forge-lint: disable-next-line(unsafe-typecast)
-        uint48 _attestationsBegin = uint48(block.timestamp + _timeUntilAttestationsBegin);
-        _scorecard.attestationsBegin = _attestationsBegin;
+        uint48 attestationsBegin = uint48(block.timestamp + timeUntilAttestationsBegin);
+        scorecard.attestationsBegin = attestationsBegin;
         // Grace period extends from when attestations begin, not from submission time.
         // This prevents the grace period from expiring before attestations even start
         // when a scorecard is submitted early.
-        _scorecard.gracePeriodEnds = uint48(_attestationsBegin + attestationGracePeriodOf(gameId));
+        scorecard.gracePeriodEnds = uint48(attestationsBegin + attestationGracePeriodOf(gameId));
+
+        // Store tier weights for BWA computation.
+        for (uint256 i; i < numberOfTierWeights; i++) {
+            _scorecardTierWeightsOf[gameId][scorecardId][tierWeights[i].id - 1] = tierWeights[i].cashOutWeight;
+        }
+
+        // Snapshot pending reserves for each tier at submission time.
+        // This prevents reserve minting between submission and attestation from diluting votes.
+        {
+            IJB721TiersHookStore _store = IDefifaHook(metadata.dataHook).store();
+            uint256 _numberOfTiers = _store.maxTierIdOf(metadata.dataHook);
+            for (uint256 i; i < _numberOfTiers; i++) {
+                uint256 tierId = i + 1;
+                _pendingReservesSnapshotOf[gameId][scorecardId][tierId] =
+                    _store.numberOfPendingReservesFor(metadata.dataHook, tierId);
+            }
+        }
+
+        // Concentration-adjusted quorum: penalty = headroom * maxShare².
+        // Headroom = max achievable BWA - base quorum = (N-2) * MAX / 2.
+        // This is the gap honest attestors can fill above base quorum.
+        // maxShare² is nonlinear: gentle for moderate concentration, steep for extreme.
+        // The penalty can never exceed headroom, so quorum is always reachable by non-beneficiaries.
+        uint256 baseQuorum = quorum(gameId);
+        uint256 adjustedQuorum = baseQuorum;
+
+        if (baseQuorum >= MAX_ATTESTATION_POWER_TIER) {
+            // headroom = maxBWA - baseQuorum = (N-1)*MAX - N*MAX/2 = (N-2)*MAX/2.
+            uint256 headroom = baseQuorum - MAX_ATTESTATION_POWER_TIER;
+            // Subtract numberOfTierWeights to account for per-tier mulDiv truncation in BWA.
+            if (headroom > numberOfTierWeights) headroom -= numberOfTierWeights;
+
+            // Find the largest tier weight.
+            uint256 totalCashOutWeight = IDefifaHook(metadata.dataHook).TOTAL_CASHOUT_WEIGHT();
+            uint256 maxWeight;
+            for (uint256 i; i < numberOfTierWeights; i++) {
+                if (tierWeights[i].cashOutWeight > maxWeight) maxWeight = tierWeights[i].cashOutWeight;
+            }
+
+            // maxShare² in totalCashOutWeight scale (nonlinear: gentle for moderate, steep for extreme).
+            uint256 maxShareSquared = mulDiv(maxWeight, maxWeight, totalCashOutWeight);
+
+            // Penalty fills headroom proportional to concentration².
+            adjustedQuorum += mulDiv(headroom, maxShareSquared, totalCashOutWeight);
+        }
+
+        scorecard.quorumSnapshot = adjustedQuorum;
 
         // Keep a reference to the default attestation delegate.
-        address _defaultAttestationDelegate = IDefifaHook(_metadata.dataHook).defaultAttestationDelegate();
+        address defaultAttestationDelegate = IDefifaHook(metadata.dataHook).defaultAttestationDelegate();
 
         // If the scorecard is being sent from the default attestation delegate, store it.
-        if (msg.sender == _defaultAttestationDelegate) {
+        if (msg.sender == defaultAttestationDelegate) {
             defaultAttestationDelegateProposalOf[gameId] = scorecardId;
         }
 
-        emit ScorecardSubmitted(gameId, scorecardId, tierWeights, msg.sender == _defaultAttestationDelegate, msg.sender);
+        emit ScorecardSubmitted(gameId, scorecardId, tierWeights, msg.sender == defaultAttestationDelegate, msg.sender);
     }
 
     //*********************************************************************//
@@ -269,7 +366,7 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     /// @param account The address to check the attestation status of.
     /// @return A flag indicating if the given account has already attested to the scorecard.
     function hasAttestedTo(uint256 gameId, uint256 scorecardId, address account) external view returns (bool) {
-        return _scorecardAttestationsOf[gameId][scorecardId].hasAttested[account];
+        return _scorecardAttestationsOf[gameId][scorecardId].attestedWeightOf[account] != 0;
     }
 
     /// @notice The ID of a scorecard representing the provided tier weights.
@@ -297,10 +394,12 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     /// @param attestationStartTime The amount of time between a scorecard being submitted and attestations to it being
     /// enabled, measured in seconds.
     /// @param attestationGracePeriod The amount of time that must go by before a scorecard can be ratified.
+    /// @param timelockDuration The cooling period after quorum is met before a scorecard can be ratified.
     function initializeGame(
         uint256 gameId,
         uint256 attestationStartTime,
-        uint256 attestationGracePeriod
+        uint256 attestationGracePeriod,
+        uint256 timelockDuration
     )
         public
         virtual
@@ -319,18 +418,21 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
         // Ensure values fit within their allocated 48-bit widths before packing.
         if (attestationStartTime > type(uint48).max) revert DefifaGovernor_Uint48Overflow();
         if (attestationGracePeriod > type(uint48).max) revert DefifaGovernor_Uint48Overflow();
+        if (timelockDuration > type(uint48).max) revert DefifaGovernor_Uint48Overflow();
 
         // Pack the values.
-        uint256 _packed;
+        uint256 packed;
         // attestation start time in bits 0-47 (48 bits).
-        _packed |= attestationStartTime;
+        packed |= attestationStartTime;
         // attestation grace period in bits 48-95 (48 bits).
-        _packed |= attestationGracePeriod << 48;
+        packed |= attestationGracePeriod << 48;
+        // timelock duration in bits 96-143 (48 bits).
+        packed |= timelockDuration << 96;
 
         // Store the packed value.
-        _packedScorecardInfoOf[gameId] = _packed;
+        _packedScorecardInfoOf[gameId] = packed;
 
-        emit GameInitialized(gameId, attestationStartTime, attestationGracePeriod, msg.sender);
+        emit GameInitialized(gameId, attestationStartTime, attestationGracePeriod, timelockDuration, msg.sender);
     }
 
     //*********************************************************************//
@@ -379,68 +481,173 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     {
         // Get the game's current funding cycle along with its metadata.
         // slither-disable-next-line unused-return
-        (, JBRulesetMetadata memory _metadata) = CONTROLLER.currentRulesetOf(gameId);
+        (, JBRulesetMetadata memory metadata) = CONTROLLER.currentRulesetOf(gameId);
+
+        // Get a reference to the hook and its store.
+        IDefifaHook hook = IDefifaHook(metadata.dataHook);
+        IJB721TiersHookStore store = hook.store();
 
         // Get a reference to the number of tiers.
-        uint256 _numberOfTiers = IDefifaHook(_metadata.dataHook).store().maxTierIdOf(_metadata.dataHook);
+        uint256 numberOfTiers = store.maxTierIdOf(metadata.dataHook);
 
         // slither-disable-next-line calls-inside-a-loop
-        for (uint256 _i; _i < _numberOfTiers; _i++) {
+        for (uint256 i; i < numberOfTiers; i++) {
             // Tiers are 1-indexed.
-            uint256 _tierId = _i + 1;
+            uint256 tierId = i + 1;
 
             // Get this account's attestation units within the tier (snapshot at timestamp).
-            uint256 _tierAttestationUnitsForAccount = IDefifaHook(_metadata.dataHook)
-                .getPastTierAttestationUnitsOf({account: account, tier: _tierId, timestamp: timestamp});
+            uint256 tierAttestationUnitsForAccount =
+                hook.getPastTierAttestationUnitsOf({account: account, tier: tierId, timestamp: timestamp});
+
+            // Get the total attestation units for this tier (snapshot at timestamp).
+            uint256 tierTotalAttestationUnits =
+                hook.getPastTierTotalAttestationUnitsOf({tier: tierId, timestamp: timestamp});
+
+            // Include unminted pending reserves in the total (denominator only). This ensures every
+            // token holder's voting power already accounts for reserves that will eventually be minted.
+            // When the reserve beneficiary later mints, their new NFTs add to the numerator while
+            // pending reserves decrease by the same amount — so no one's voting power shifts.
+            {
+                uint256 pendingReserves = store.numberOfPendingReservesFor(metadata.dataHook, tierId);
+                if (pendingReserves != 0) {
+                    JB721Tier memory tier =
+                        store.tierOf({hook: metadata.dataHook, id: tierId, includeResolvedUri: false});
+                    tierTotalAttestationUnits += pendingReserves * tier.votingUnits;
+                }
+            }
 
             // Scale the account's share of the tier to MAX_ATTESTATION_POWER_TIER.
             // e.g. holding 3 of 10 tokens → 3/10 * MAX_ATTESTATION_POWER_TIER attestation power from this tier.
             unchecked {
-                if (_tierAttestationUnitsForAccount != 0) {
+                if (tierAttestationUnitsForAccount != 0) {
                     attestationPower += mulDiv({
                         x: MAX_ATTESTATION_POWER_TIER,
-                        y: _tierAttestationUnitsForAccount,
-                        denominator: IDefifaHook(_metadata.dataHook)
-                            .getPastTierTotalAttestationUnitsOf({tier: _tierId, timestamp: timestamp})
+                        y: tierAttestationUnitsForAccount,
+                        denominator: tierTotalAttestationUnits
                     });
                 }
             }
         }
     }
 
+    /// @notice Gets an account's BWA-adjusted attestation power relative to a specific scorecard.
+    /// @dev BWA (Benefit-Weighted Attestation) reduces a tier's attestation power by how much
+    /// that tier benefits from the scorecard. Power is reduced by `(tierWeight / totalCashOutWeight)`.
+    /// This means a tier with 100% of the scorecard weight gets 0 attestation power for that scorecard,
+    /// while a tier with 0% weight retains full power. This prevents beneficiaries from self-attesting.
+    /// @param gameId The ID of the game.
+    /// @param scorecardId The ID of the scorecard (determines tier weight lookup).
+    /// @param account The account to compute BWA power for.
+    /// @param timestamp The snapshot timestamp.
+    /// @return bwaAttestationPower The BWA-adjusted attestation power.
+    // forge-lint: disable-next-line(mixed-case-function)
+    function getBWAAttestationWeight(
+        uint256 gameId,
+        uint256 scorecardId,
+        address account,
+        uint48 timestamp
+    )
+        public
+        view
+        virtual
+        override
+        returns (uint256 bwaAttestationPower)
+    {
+        // Get the game's current funding cycle along with its metadata.
+        // slither-disable-next-line unused-return
+        (, JBRulesetMetadata memory metadata) = CONTROLLER.currentRulesetOf(gameId);
+
+        // Get a reference to the hook and its store.
+        IDefifaHook hook = IDefifaHook(metadata.dataHook);
+        IJB721TiersHookStore store = hook.store();
+
+        // Get a reference to the number of tiers.
+        uint256 numberOfTiers = store.maxTierIdOf(metadata.dataHook);
+
+        // Cache the total cashout weight denominator from the hook.
+        uint256 totalCashOutWeight = hook.TOTAL_CASHOUT_WEIGHT();
+
+        // slither-disable-next-line calls-inside-a-loop
+        for (uint256 i; i < numberOfTiers; i++) {
+            // Tiers are 1-indexed.
+            uint256 tierId = i + 1;
+
+            // Get this account's attestation units within the tier (snapshot at timestamp).
+            uint256 tierAttestationUnitsForAccount =
+                hook.getPastTierAttestationUnitsOf({account: account, tier: tierId, timestamp: timestamp});
+
+            if (tierAttestationUnitsForAccount != 0) {
+                // Get the total attestation units for this tier (snapshot at timestamp).
+                uint256 tierTotalAttestationUnits =
+                    hook.getPastTierTotalAttestationUnitsOf({tier: tierId, timestamp: timestamp});
+
+                // Include unminted pending reserves in the total (denominator only).
+                // Uses the snapshot taken at scorecard submission time to prevent reserve
+                // minting between submission and attestation from diluting votes.
+                {
+                    uint256 pendingReserves = _pendingReservesSnapshotOf[gameId][scorecardId][tierId];
+                    if (pendingReserves != 0) {
+                        JB721Tier memory tier =
+                            store.tierOf({hook: metadata.dataHook, id: tierId, includeResolvedUri: false});
+                        tierTotalAttestationUnits += pendingReserves * tier.votingUnits;
+                    }
+                }
+
+                // Raw power for this tier.
+                uint256 rawPower =
+                    mulDiv(MAX_ATTESTATION_POWER_TIER, tierAttestationUnitsForAccount, tierTotalAttestationUnits);
+
+                // BWA reduction: power * (1 - tierWeight / totalCashOutWeight).
+                uint256 tierWeight = _scorecardTierWeightsOf[gameId][scorecardId][i];
+                uint256 bwaMultiplier = totalCashOutWeight - tierWeight;
+
+                bwaAttestationPower += mulDiv(rawPower, bwaMultiplier, totalCashOutWeight);
+            }
+        }
+    }
+
     /// @notice The number of attestation units that must have participated in a proposal for it to be ratified.
-    /// @dev Each tier with at least one minted token contributes MAX_ATTESTATION_POWER_TIER to the total
-    /// eligible weight. Quorum is 50% of this total. Because every tier has equal max attestation power
-    /// regardless of supply, each tier's community has equal influence — a tier with 1 token and a tier
-    /// with 100 tokens both cap at MAX_ATTESTATION_POWER_TIER when fully attested. This prevents
-    /// high-supply tiers from dominating governance, keeping the game fair across all outcomes.
-    /// @dev Note: quorum is computed from the live supply (currentSupplyOfTier) rather than a snapshot. This means
-    /// the quorum threshold can shift between when a scorecard is submitted and when it is evaluated, e.g. if
-    /// tokens are burned after attestation. In practice this is acceptable because attestation weights are
-    /// snapshotted and quorum only increases (new mints) or decreases (burns) — the latter makes ratification
-    /// easier, not harder.
+    /// @dev Each tier with participation contributes MAX_ATTESTATION_POWER_TIER to the total eligible weight.
+    /// A tier counts as "participated" if it has circulating tokens OR unminted pending reserves — the latter
+    /// means mints occurred (triggering reserve accrual) even if all paid tokens were later burned during REFUND.
+    /// Quorum is 50% of this total. Because every tier has equal max attestation power regardless of supply,
+    /// each tier's community has equal influence. This prevents high-supply tiers from dominating governance.
+    /// @dev No snapshot needed: during SCORING, supply is frozen (no new paid mints, no burns). Reserve minting
+    /// doesn't change which tiers are counted because tiers with pending reserves are already included.
     /// @return The quorum number of attestations.
     function quorum(uint256 gameId) public view override returns (uint256) {
         // Get the game's current funding cycle along with its metadata.
         // slither-disable-next-line unused-return
-        (, JBRulesetMetadata memory _metadata) = CONTROLLER.currentRulesetOf(gameId);
+        (, JBRulesetMetadata memory metadata) = CONTROLLER.currentRulesetOf(gameId);
+
+        // Get a reference to the hook and its store.
+        IDefifaHook hook = IDefifaHook(metadata.dataHook);
+        IJB721TiersHookStore store = hook.store();
 
         // Get a reference to the number of tiers.
-        uint256 _numberOfTiers = IDefifaHook(_metadata.dataHook).store().maxTierIdOf(_metadata.dataHook);
+        uint256 numberOfTiers = store.maxTierIdOf(metadata.dataHook);
 
         // Keep a reference to the total eligible tier weight.
-        uint256 _eligibleTierWeights;
+        uint256 eligibleTierWeights;
 
         // slither-disable-next-line calls-inside-a-loop
-        for (uint256 _i; _i < _numberOfTiers; _i++) {
-            // Each minted tier contributes MAX_ATTESTATION_POWER_TIER to the quorum denominator.
-            if (IDefifaHook(_metadata.dataHook).currentSupplyOfTier(_i + 1) != 0) {
-                _eligibleTierWeights += MAX_ATTESTATION_POWER_TIER;
+        for (uint256 i; i < numberOfTiers; i++) {
+            uint256 tierId = i + 1;
+
+            // A tier contributes to quorum if it has circulating tokens OR unminted pending reserves.
+            // Pending reserves exist when participation occurred (mints triggered reserve accrual),
+            // even if all paid tokens were later burned during REFUND. The reserve beneficiary still
+            // has a stake in that tier's outcome, so the tier should count toward governance quorum.
+            if (
+                hook.currentSupplyOfTier(tierId) != 0
+                    || store.numberOfPendingReservesFor(metadata.dataHook, tierId) != 0
+            ) {
+                eligibleTierWeights += MAX_ATTESTATION_POWER_TIER;
             }
         }
 
-        // Quorum = 50% of all minted tiers' attestation power.
-        return _eligibleTierWeights / 2;
+        // Quorum = 50% of all participated tiers' attestation power.
+        return eligibleTierWeights / 2;
     }
 
     /// @notice The state of a proposal.
@@ -450,45 +657,59 @@ contract DefifaGovernor is Ownable, IDefifaGovernor {
     /// @dev Boundary semantics (inclusive):
     ///   - At exactly `attestationsBegin`, the state transitions from PENDING to ACTIVE (attestations are open).
     ///   - At exactly `gracePeriodEnds`, the grace period has elapsed and the state transitions from ACTIVE to
-    ///     SUCCEEDED (if quorum is met) or remains ACTIVE (if not).
+    ///     QUEUED (if quorum met + timelock > 0) or SUCCEEDED (if quorum met + no timelock).
     function stateOf(uint256 gameId, uint256 scorecardId) public view virtual override returns (DefifaScorecardState) {
         // Keep a reference to the ratified scorecard ID.
-        uint256 _ratifiedScorecardId = ratifiedScorecardIdOf[gameId];
+        uint256 ratifiedScorecardId = ratifiedScorecardIdOf[gameId];
 
         // If the game has already ratified a scorecard, return succeeded if the ratified proposal is being checked.
         // Else return defeated.
-        if (_ratifiedScorecardId != 0) {
-            return _ratifiedScorecardId == scorecardId ? DefifaScorecardState.RATIFIED : DefifaScorecardState.DEFEATED;
+        if (ratifiedScorecardId != 0) {
+            return ratifiedScorecardId == scorecardId ? DefifaScorecardState.RATIFIED : DefifaScorecardState.DEFEATED;
         }
 
         // Get a reference to the scorecard.
-        DefifaScorecard memory _scorecard = _scorecardOf[gameId][scorecardId];
+        DefifaScorecard memory scorecard = _scorecardOf[gameId][scorecardId];
 
         // Make sure the proposal is known.
         // slither-disable-next-line incorrect-equality
-        if (_scorecard.attestationsBegin == 0) {
+        if (scorecard.attestationsBegin == 0) {
             revert DefifaGovernor_UnknownProposal();
         }
 
         // If the scorecard has attestations beginning in the future, the state is PENDING.
         // At exactly `attestationsBegin`, attestations are open so the state is ACTIVE.
-        if (_scorecard.attestationsBegin > block.timestamp) {
+        if (scorecard.attestationsBegin > block.timestamp) {
             return DefifaScorecardState.PENDING;
         }
 
         // If the scorecard's grace period has not yet ended, the state is ACTIVE.
         // At exactly `gracePeriodEnds`, the grace period has elapsed so we fall through to the quorum check.
-        if (_scorecard.gracePeriodEnds > block.timestamp) {
+        if (scorecard.gracePeriodEnds > block.timestamp) {
             return DefifaScorecardState.ACTIVE;
         }
 
-        // If quorum has been reached, the state is SUCCEEDED, otherwise it is ACTIVE.
-        // Note: scorecards that fail to reach quorum remain ACTIVE indefinitely — there is no DEFEATED
+        // If quorum has been reached (using the concentration-adjusted snapshot), check timelock.
+        if (scorecard.quorumSnapshot <= _scorecardAttestationsOf[gameId][scorecardId].count) {
+            uint256 _timelockDuration = timelockDurationOf(gameId);
+            if (_timelockDuration > 0 && block.timestamp < uint256(scorecard.gracePeriodEnds) + _timelockDuration) {
+                return DefifaScorecardState.QUEUED;
+            }
+            return DefifaScorecardState.SUCCEEDED;
+        }
+
+        // Scorecards that fail to reach quorum remain ACTIVE indefinitely — there is no DEFEATED
         // state transition for unratified scorecards. This is by design: new scorecards can always be
         // submitted and the game's no-contest timeout (scorecardTimeout) provides the ultimate backstop.
-        return quorum(gameId) <= _scorecardAttestationsOf[gameId][scorecardId].count
-            ? DefifaScorecardState.SUCCEEDED
-            : DefifaScorecardState.ACTIVE;
+        return DefifaScorecardState.ACTIVE;
+    }
+
+    /// @notice The timelock duration for a game (cooling period after quorum + grace period before ratification).
+    /// @param gameId The ID of the game.
+    /// @return The timelock duration in seconds.
+    function timelockDurationOf(uint256 gameId) public view override returns (uint256) {
+        // timelock duration in bits 96-143 (48 bits).
+        return uint256(uint48(_packedScorecardInfoOf[gameId] >> 96));
     }
 
     //*********************************************************************//