chore: copying back name change to selfMintingOffset

Author: RembrandtK

packages/issuance/contracts/allocate/IssuanceAllocator.sol

@@ -82,7 +82,7 @@ import { ERC165Upgradeable } from "@openzeppelin/contracts-upgradeable/utils/int
  * This provides protection against potential issues if the multi-sig governor role were to have known
  * signatures that could be exploited by malicious actors to trigger reentrant calls.
  *
- * The `distributeIssuance()` function intentionally does NOT have reentrancy protection to allow
+ * The `distributeIssuance()` function intentionally does NOT have a reentrancy guard to allow
  * legitimate use cases where targets call it during notifications (e.g., to claim pending issuance
  * before allocation changes). This is safe because distributeIssuance() has built-in block-tracking
  * protection (preventing double-distribution in the same block), makes no external calls that could
@@ -109,7 +109,7 @@ contract IssuanceAllocator is
     /// @param issuancePerBlock Total issuance per block across all targets
     /// @param lastDistributionBlock Last block when allocator-minting issuance was distributed
     /// @param lastSelfMintingBlock Last block when self-minting was advanced
-    /// @param accumulatedSelfMinting Accumulated self-minting during undistributed periods
+    /// @param selfMintingOffset Self-minting that offsets allocator-minting budget (accumulates during pause, clears on distribution)
     /// @param allocationTargets Mapping of target addresses to their allocation data
     /// @param targetAddresses Array of all target addresses (including default target at index 0)
     /// @param totalSelfMintingRate Total self-minting rate (tokens per block) across all targets
@@ -122,7 +122,7 @@ contract IssuanceAllocator is
         uint256 issuancePerBlock;
         uint256 lastDistributionBlock;
         uint256 lastSelfMintingBlock;
-        uint256 accumulatedSelfMinting;
+        uint256 selfMintingOffset;
         mapping(address => AllocationTarget) allocationTargets;
         address[] targetAddresses;
         uint256 totalSelfMintingRate;
@@ -239,10 +239,11 @@ contract IssuanceAllocator is
      * @param _governor Address that will have the GOVERNOR_ROLE
      * @dev Initializes with a default target at index 0 set to address(0)
      * @dev default target will receive all unallocated issuance (initially 0 until rate is set)
-     * @dev Security: lastDistributionBlock and lastSelfMintingBlock default to 0. First distribution
+     * @dev Accounting: lastDistributionBlock and lastSelfMintingBlock default to 0. First distribution
      * call will calculate for all blocks from 0 to block.number, which is safe because issuancePerBlock
      * is 0 at initialization. Once setIssuancePerBlock() is called, it triggers _distributeIssuance()
      * which updates lastDistributionBlock to current block, preventing large block ranges in future calls.
+     * Governance must exercise caution when changing issuancePerBlock while paused to ensure applied to correct block range, see setIssuancePerBlock() documentation.
      */
     function initialize(address _governor) external virtual initializer {
         __BaseUpgradeable_init(_governor);
@@ -317,7 +318,7 @@ contract IssuanceAllocator is
         // Once accumulation starts (during pause), continue through any unpaused periods
         // until distribution clears the accumulation. This is conservative and allows
         // better recovery when distribution is delayed through pause/unpause cycles.
-        if (paused() || 0 < $.accumulatedSelfMinting) $.accumulatedSelfMinting += $.totalSelfMintingRate * blocks;
+        if (paused() || 0 < $.selfMintingOffset) $.selfMintingOffset += $.totalSelfMintingRate * blocks;
         $.lastSelfMintingBlock = block.number;
 
         // Emit self-minting allowance events
@@ -350,7 +351,7 @@ contract IssuanceAllocator is
 
         if (paused()) return $.lastDistributionBlock;
 
-        if (0 < $.accumulatedSelfMinting) return _distributePendingIssuance(block.number);
+        if (0 < $.selfMintingOffset) return _distributePendingIssuance(block.number);
         else return _performNormalDistribution();
     }
 
@@ -439,9 +440,9 @@ contract IssuanceAllocator is
         // ~1e33, well below uint256 max (~1e77). Similar multiplications throughout this contract operate
         // under the same range assumptions.
         uint256 totalForPeriod = $.issuancePerBlock * blocks;
-        uint256 accumulatedSelfMinting = $.accumulatedSelfMinting;
+        uint256 selfMintingOffset = $.selfMintingOffset;
 
-        uint256 available = accumulatedSelfMinting < totalForPeriod ? totalForPeriod - accumulatedSelfMinting : 0;
+        uint256 available = selfMintingOffset < totalForPeriod ? totalForPeriod - selfMintingOffset : 0;
 
         if (0 < available) {
             // Calculate non-default allocated rate using the allocation invariant.
@@ -463,11 +464,8 @@ contract IssuanceAllocator is
         // Update accumulated self-minting after distribution.
         // Subtract the period budget used (min of accumulated and totalForPeriod).
         // When caught up to current block, clear all since nothing remains to distribute.
-        if (toBlockNumber == block.number) $.accumulatedSelfMinting = 0;
-        else
-            $.accumulatedSelfMinting = totalForPeriod < accumulatedSelfMinting
-                ? accumulatedSelfMinting - totalForPeriod
-                : 0;
+        if (toBlockNumber == block.number) $.selfMintingOffset = 0;
+        else $.selfMintingOffset = totalForPeriod < selfMintingOffset ? selfMintingOffset - totalForPeriod : 0;
 
         return toBlockNumber;
     }
@@ -725,36 +723,8 @@ contract IssuanceAllocator is
         return _setTargetAllocation(address(target), allocatorMintingRate, selfMintingRate, minDistributedBlock);
     }
 
-    /**
-     * @notice Internal implementation for setting target allocation
-     * @param target Address of the target to update
-     * @param allocatorMintingRate Allocator-minting rate for the target (tokens per block)
-     * @param selfMintingRate Self-minting rate for the target (tokens per block)
-     * @param minDistributedBlock Minimum block number that distribution must have reached
-     * @return True if the value is applied (including if already the case), false if not applied due to paused state
-     */
-    function _setTargetAllocation(
-        address target,
-        uint256 allocatorMintingRate,
-        uint256 selfMintingRate,
-        uint256 minDistributedBlock
-    ) internal returns (bool) {
-        if (!_validateTargetAllocation(target, allocatorMintingRate, selfMintingRate)) return true;
-
-        if (_distributeIssuance() < minDistributedBlock) return false;
-
-        _notifyTarget(target);
-        _validateAndUpdateTotalAllocations(target, allocatorMintingRate, selfMintingRate);
-        _updateTargetAllocationData(target, allocatorMintingRate, selfMintingRate);
-
-        emit TargetAllocationUpdated(target, allocatorMintingRate, selfMintingRate);
-        return true;
-    }
-
     /**
      * @inheritdoc IIssuanceAllocationAdministration
-     * @dev Delegates to internal implementation with block.number
-     * TODO: Intead of talking about implementation, talk about behavior that requires distribution to current block
      */
     function setDefaultTarget(
         address newAddress
@@ -820,6 +790,42 @@ contract IssuanceAllocator is
         return true;
     }
 
+    /**
+     * @notice Internal implementation for setting target allocation
+     * @param target Address of the target to update
+     * @param allocatorMintingRate Allocator-minting rate for the target (tokens per block)
+     * @param selfMintingRate Self-minting rate for the target (tokens per block)
+     * @param minDistributedBlock Minimum block number that distribution must have reached
+     * @return True if the value is applied (including if already the case), false if not applied due to paused state
+     */
+    function _setTargetAllocation(
+        address target,
+        uint256 allocatorMintingRate,
+        uint256 selfMintingRate,
+        uint256 minDistributedBlock
+    ) internal returns (bool) {
+        if (!_validateTargetAllocation(target, allocatorMintingRate, selfMintingRate)) return true;
+
+        if (_distributeIssuance() < minDistributedBlock) return false;
+
+        _notifyTarget(target);
+
+        // Total allocation calculation and check is delayed until after notifications.
+        // Distributing and notifying unnecessarily is harmless, but we need to prevent
+        // reentrancy from looping and changing allocations mid-calculation.
+        // (Would not be likely to be exploitable due to only governor being able to
+        // make a call to set target allocation, but better to be paranoid.)
+        // Validate totals and auto-adjust default allocation BEFORE updating target data
+        // so we can read the old allocation values
+        _validateAndUpdateTotalAllocations(target, allocatorMintingRate, selfMintingRate);
+
+        // Then update the target's allocation data
+        _updateTargetAllocationData(target, allocatorMintingRate, selfMintingRate);
+
+        emit TargetAllocationUpdated(target, allocatorMintingRate, selfMintingRate);
+        return true;
+    }
+
     /**
      * @notice Validates target address and interface support, returns false if allocation is unchanged
      * @param target Address of the target to validate
@@ -963,7 +969,7 @@ contract IssuanceAllocator is
             DistributionState({
                 lastDistributionBlock: $.lastDistributionBlock,
                 lastSelfMintingBlock: $.lastSelfMintingBlock,
-                accumulatedSelfMinting: $.accumulatedSelfMinting
+                selfMintingOffset: $.selfMintingOffset
             });
     }
 
@@ -1039,27 +1045,15 @@ contract IssuanceAllocator is
      * @dev When default is a real address: returns issuancePerBlock
      * @dev Note: Internally, the contract always maintains 100% allocation invariant, even when default is address(0)
      */
-    function getTotalAllocation() external view override returns (Allocation memory) {
+    function getTotalAllocation() external view override returns (Allocation memory allocation) {
         IssuanceAllocatorData storage $ = _getIssuanceAllocatorStorage();
 
-        uint256 totalAllocatorMinting = $.issuancePerBlock - $.totalSelfMintingRate;
-        uint256 totalAllocation = $.issuancePerBlock;
-
         // If default is address(0), exclude its allocation from reported totals
-        // since it doesn't actually receive minting (effectively unallocated)
-        address defaultAddress = $.targetAddresses[0];
-        if (defaultAddress == address(0)) {
-            AllocationTarget storage defaultTarget = $.allocationTargets[defaultAddress];
-            uint256 defaultAllocation = defaultTarget.allocatorMintingRate;
-            totalAllocatorMinting -= defaultAllocation;
-            totalAllocation -= defaultAllocation;
-        }
-
-        return
-            Allocation({
-                totalAllocationRate: totalAllocation,
-                allocatorMintingRate: totalAllocatorMinting,
-                selfMintingRate: $.totalSelfMintingRate
-            });
+        // since it doe not receive minting (so it is considered unallocated).
+        // Address(0) will only have non-zero allocation when it is the default target,
+        // so we can directly subtract zero address allocation.
+        allocation.totalAllocationRate = $.issuancePerBlock - $.allocationTargets[address(0)].allocatorMintingRate;
+        allocation.selfMintingRate = $.totalSelfMintingRate;
+        allocation.allocatorMintingRate = allocation.totalAllocationRate - allocation.selfMintingRate;
     }
 }