Issuance allocator audit responses (WIP)

packages/issuance/contracts/allocate/IssuanceAllocator.sol

@@ -2,21 +2,21 @@
 
 pragma solidity 0.8.27;
 
 import {
     TargetIssuancePerBlock,
     Allocation,
     AllocationTarget
 } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceAllocatorTypes.sol";
 import { IIssuanceAllocationDistribution } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceAllocationDistribution.sol";
 import { IIssuanceAllocationAdministration } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceAllocationAdministration.sol";
 import { IIssuanceAllocationStatus } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceAllocationStatus.sol";
 import { IIssuanceAllocationData } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceAllocationData.sol";
 import { IIssuanceTarget } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceTarget.sol";
 import { BaseUpgradeable } from "../common/BaseUpgradeable.sol";
 import { IERC165 } from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 
 // solhint-disable-next-line no-unused-import
 import { ERC165Upgradeable } from "@openzeppelin/contracts-upgradeable/utils/introspection/ERC165Upgradeable.sol"; // Used by @inheritdoc
 
 /**
  * @title IssuanceAllocator
@@ -283,10 +283,10 @@
         if (newIssuancePerBlock == $.issuancePerBlock) return true;
 
         if (_distributeIssuance() < block.number) {
-            if (evenIfDistributionPending) accumulatePendingIssuance();
+            if (evenIfDistributionPending) _accumulatePendingIssuance();
             else return false;
         }
-        notifyAllTargets();
+        _notifyAllTargets();
 
         uint256 oldIssuancePerBlock = $.issuancePerBlock;
         $.issuancePerBlock = newIssuancePerBlock;
@@ -332,7 +332,7 @@
      * @dev Each target is notified at most once per block.
      * Will revert if any target notification reverts.
      */
-    function notifyAllTargets() private {
+    function _notifyAllTargets() private {
         IssuanceAllocatorData storage $ = _getIssuanceAllocatorStorage();
 
         for (uint256 i = 0; i < $.targetAddresses.length; ++i) {
@@ -576,7 +576,7 @@
             // So for a self-minting change, accumulate pending issuance prior to the rate change.
             IssuanceAllocatorData storage $ = _getIssuanceAllocatorStorage();
             AllocationTarget storage targetData = $.allocationTargets[target];
-            if (selfMintingPPM != targetData.selfMintingPPM) accumulatePendingIssuance();
+            if (selfMintingPPM != targetData.selfMintingPPM) _accumulatePendingIssuance();
         }
 
         return true;
@@ -693,7 +693,7 @@
     function distributePendingIssuance(
         uint256 toBlockNumber
     ) external override onlyRole(GOVERNOR_ROLE) returns (uint256) {
-        accumulatePendingIssuance(toBlockNumber);
+        _accumulatePendingIssuance(toBlockNumber);
         return _distributePendingIssuance();
     }
 
@@ -739,8 +739,8 @@
      * @dev Used to accumulate pending issuance while paused prior to a rate or allocator-minting allocation change.
      * @return The block number that has been accumulated to
      */
-    function accumulatePendingIssuance() private returns (uint256) {
-        return accumulatePendingIssuance(block.number);
+    function _accumulatePendingIssuance() private returns (uint256) {
+        return _accumulatePendingIssuance(block.number);
     }
 
     /**
@@ -749,7 +749,7 @@
      * @param toBlockNumber The block number to accumulate to (must be >= lastIssuanceAccumulationBlock and <= current block).
      * @return The block number that has been accumulated to
      */
-    function accumulatePendingIssuance(uint256 toBlockNumber) private returns (uint256) {
+    function _accumulatePendingIssuance(uint256 toBlockNumber) private returns (uint256) {
         IssuanceAllocatorData storage $ = _getIssuanceAllocatorStorage();
 
         // solhint-disable-next-line gas-strict-inequalities
@@ -826,6 +826,9 @@
 
     /**
      * @inheritdoc IIssuanceAllocationStatus
+     * @dev Returns assigned allocation regardless of whether target is address(0) or the default.
+     * @dev For address(0), no minting occurs but the allocation represents the unallocated portion.
+     * @dev For effective allocations excluding unmintable portion, use getTotalAllocation().
      */
     function getTargetAllocation(address target) external view override returns (Allocation memory) {
         AllocationTarget storage targetData = _getIssuanceAllocatorStorage().allocationTargets[target];
@@ -839,6 +842,8 @@
 
     /**
      * @inheritdoc IIssuanceAllocationDistribution
+     * @dev Returns assigned issuance rates regardless of whether target is address(0) or the default.
+     * @dev For address(0), no minting occurs but rates reflect what would be issued if mintable.
      */
     function getTargetIssuancePerBlock(address target) external view override returns (TargetIssuancePerBlock memory) {
         IssuanceAllocatorData storage $ = _getIssuanceAllocatorStorage();