feat: named mapping params

src/contracts/core/AVSDirectoryStorage.sol

@@ -41,40 +41,37 @@ abstract contract AVSDirectoryStorage is IAVSDirectory {
 
     // Mutatables
 
-    /**
-     * @notice Original EIP-712 Domain separator for this contract.
-     * @dev The domain separator may change in the event of a fork that modifies the ChainID.
-     * Use the getter function `domainSeparator` to get the current domain separator for this contract.
-     */
+    /// @dev Do not remove, deprecated storage.
     bytes32 internal __deprecated_DOMAIN_SEPARATOR;
 
-    /// @notice Mapping: avs => operator => OperatorAVSRegistrationStatus struct
-    /// @dev This storage will be deprecated once M2 based deregistration is deprecated.
-    mapping(address => mapping(address => OperatorAVSRegistrationStatus)) public avsOperatorStatus;
+    /// @notice Returns the registration status of each `operator` for a given `avs`.
+    /// @dev This storage will be deprecated once M2-based deregistration is removed.
+    mapping(address avs => mapping(address operator => OperatorAVSRegistrationStatus)) public avsOperatorStatus;
 
-    /// @notice Mapping: operator => salt => Whether the salt has been used or not.
-    mapping(address => mapping(bytes32 => bool)) public operatorSaltIsSpent;
+    /// @notice Returns whether a `salt` has been used by a given `operator`.
+    mapping(address operator => mapping(bytes32 salt => bool)) public operatorSaltIsSpent;
 
-    /// @notice Mapping: avs => Whether it is a an operator set AVS or not.
-    mapping(address => bool) public isOperatorSetAVS;
+    /// @notice Returns whether a given `avs` is an operator set avs.
+    mapping(address avs => bool) public isOperatorSetAVS;
 
-    /// @notice Mapping: avs => operatorSetId => Whether or not an operator set is valid.
-    mapping(address => mapping(uint32 => bool)) public isOperatorSet;
+    /// @notice Returns whether an `operatorSetId` has been created for a given `avs`.
+    mapping(address avs => mapping(uint32 operatorSetId => bool)) public isOperatorSet;
 
-    /// @notice Mapping: operator => List of operator sets that operator is registered to.
-    /// @dev Each item is formatted as such: bytes32(abi.encodePacked(avs, uint96(operatorSetId)))
-    mapping(address => EnumerableSet.Bytes32Set) internal _operatorSetsMemberOf;
+    /// @notice Returns the list of operator sets that an `operator` is registered to.
+    /// @dev Each item is formatted as `bytes32(abi.encodePacked(avs, uint96(operatorSetId)))`.
+    mapping(address operator => EnumerableSet.Bytes32Set) internal _operatorSetsMemberOf;
 
-    /// @notice Mapping: operatorSet => List of operators that are registered to the operatorSet
-    /// @dev Each key is formatted as such: bytes32(abi.encodePacked(avs, uint96(operatorSetId)))
-    mapping(bytes32 => EnumerableSet.AddressSet) internal _operatorSetMembers;
+    /// @notice Returns the list of `operators` that are members of a given operator set.
+    /// @dev Each key is formatted as `bytes32(abi.encodePacked(avs, uint96(operatorSetId)))`.
+    mapping(bytes32 operatorSetKey => EnumerableSet.AddressSet) internal _operatorSetMembers;
 
-    /// @notice Mapping: operatorSet => List of strategies that the operatorSet contains
-    /// @dev Each key is formatted as such: bytes32(abi.encodePacked(avs, uint96(operatorSetId)))
-    mapping(bytes32 => EnumerableSet.AddressSet) internal _operatorSetStrategies;
+    /// @notice Returns the list of `strategies` associated with a given operator set.
+    /// @dev Each key is formatted as `bytes32(abi.encodePacked(avs, uint96(operatorSetId)))`.
+    mapping(bytes32 operatorSetKey => EnumerableSet.AddressSet) internal _operatorSetStrategies;
 
-    /// @notice Mapping: operator => avs => operatorSetId => operator registration status
-    mapping(address => mapping(address => mapping(uint32 => OperatorSetRegistrationStatus))) public operatorSetStatus;
+    /// @notice Returns the registration status of an `operator` for a given `avs` and `operatorSetId`.
+    mapping(address operator => mapping(address avs => mapping(uint32 operatorSetId => OperatorSetRegistrationStatus)))
+        public operatorSetStatus;
 
     // Construction
 

src/contracts/core/AllocationManagerStorage.sol

@@ -36,27 +36,29 @@ abstract contract AllocationManagerStorage is IAllocationManager {
     /// In this window, deallocations still remain slashable by the operatorSet they were allocated to.
     uint32 public immutable DEALLOCATION_DELAY;
 
-    /// @dev Delay before alloaction delay modifications take effect.
-    uint32 public immutable ALLOCATION_CONFIGURATION_DELAY; // QUESTION: 21 days?
+    /// @notice Delay before alloaction delay modifications take effect.
+    uint32 public immutable ALLOCATION_CONFIGURATION_DELAY;
 
     // Mutatables
 
-    /// @notice Mapping: operator => strategy => snapshotted maxMagnitude
-    /// Note that maxMagnitude is monotonically decreasing and is decreased on slashing
-    mapping(address => mapping(IStrategy => Snapshots.DefaultWadHistory)) internal _maxMagnitudeHistory;
+    /// @notice Returns snapshots of max magnitude for each `operator` for a given `strategy`.
+    /// @dev This value starts at 100% (1e18) and decreases with slashing.
+    mapping(address operator => mapping(IStrategy strategy => Snapshots.DefaultWadHistory)) internal
+        _maxMagnitudeHistory;
 
-    /// @notice Mapping: operator => strategy => the amount of magnitude that is not available for allocation
-    mapping(address => mapping(IStrategy => uint64)) public encumberedMagnitude;
+    /// @notice Returns the amount of magnitude that is not available for allocation for each `operator` for a given `strategy`.
+    /// @dev This value increases with allocations and slashing, and decreases with deallocations; should never exceed 100% (1e18).
+    mapping(address operator => mapping(IStrategy strategy => uint64)) public encumberedMagnitude;
 
-    /// @notice Mapping: operator => strategy => operatorSet (encoded) => MagnitudeInfo
-    mapping(address => mapping(IStrategy => mapping(bytes32 => MagnitudeInfo))) internal _operatorMagnitudeInfo;
+    /// @notice Returns the magnitude info for each `operator` for a given `strategy` and operator set (`operatorSetKey`).
+    mapping(address operator => mapping(IStrategy strategy => mapping(bytes32 operatorSetKey => MagnitudeInfo)))
+        internal _operatorMagnitudeInfo;
 
-    /// @notice Mapping: operator => strategy => operatorSet[] (encoded) to keep track of pending deallocations
-    mapping(address => mapping(IStrategy => DoubleEndedQueue.Bytes32Deque)) internal deallocationQueue;
+    /// @notice Returns pending deallocations for each `operator` for a given `strategy`.
+    mapping(address operator => mapping(IStrategy strategy => DoubleEndedQueue.Bytes32Deque)) internal deallocationQueue;
 
-    /// @notice Mapping: operator => allocation delay (in seconds) for the operator.
-    /// This determines how long it takes for allocations to take effect in the future.
-    mapping(address => AllocationDelayInfo) internal _allocationDelayInfo;
+    /// @notice Returns the allocation delay info for each `operator`; the delay and whether or not it's previously been set.
+    mapping(address operator => AllocationDelayInfo) internal _allocationDelayInfo;
 
     // Construction
 

src/contracts/core/DelegationManagerStorage.sol

@@ -68,73 +68,51 @@ abstract contract DelegationManagerStorage is IDelegationManager {
 
     // Mutatables
 
+    /// @dev Do not remove, deprecated storage.
     bytes32 internal __deprecated_DOMAIN_SEPARATOR;
 
     /**
-     * @notice returns the total number of shares of the operator
-     * @notice Mapping: operator => strategy => total number of shares of the operator
+     * @notice Returns the total number of shares owned by an `operator` for a given `strategy`.
      *
      * @dev By design, the following invariant should hold for each Strategy:
+     *
      * (operator's delegatedShares in delegation manager) = sum (delegatedShares above zero of all stakers delegated to operator)
      * = sum (delegateable delegatedShares of all stakers delegated to the operator)
      */
-    mapping(address => mapping(IStrategy => uint256)) public operatorShares;
+    mapping(address operator => mapping(IStrategy strategy => uint256 shares)) public operatorShares;
 
-    /**
-     * @notice Mapping: operator => OperatorDetails struct
-     * @dev This struct is internal with an external getter so we can return an `OperatorDetails memory` object
-     */
-    mapping(address => OperatorDetails) internal _operatorDetails;
+    /// @notice Returns the operator details for a given `operator`.
+    mapping(address operator => OperatorDetails) internal _operatorDetails;
 
-    /**
-     * @notice Mapping: staker => operator whom the staker is currently delegated to.
-     * @dev Note that returning address(0) indicates that the staker is not actively delegated to any operator.
-     */
-    mapping(address => address) public delegatedTo;
+    /// @notice Returns the `operator` a `staker` is delgated to, address(0) if not delegated.
+    mapping(address staker => address operator) public delegatedTo;
 
-    /// @notice Mapping: staker => number of signed messages (used in `delegateToBySignature`) from the staker that this contract has already checked.
-    mapping(address => uint256) public stakerNonce;
+    /// @notice Returns the number of EIP-712 signatures validated via `delegateToBySignature` for a given `staker`.
+    mapping(address staker => uint256 nonce) public stakerNonce;
 
-    /**
-     * @notice Mapping: delegationApprover => 32-byte salt => whether or not the salt has already been used by the delegationApprover.
-     * @dev Salts are used in the `delegateTo` and `delegateToBySignature` functions. Note that these functions only process the delegationApprover's
-     * signature + the provided salt if the operator being delegated to has specified a nonzero address as their `delegationApprover`.
-     */
-    mapping(address => mapping(bytes32 => bool)) public delegationApproverSaltIsSpent;
+    /// @notice Returns whether `delegationApprover` has already used the given `salt`.
+    mapping(address delegationApprover => mapping(bytes32 salt => bool spent)) public delegationApproverSaltIsSpent;
 
-    /**
-     * @notice Global minimum withdrawal delay for all strategy withdrawals.
-     * In a prior Goerli release, we only had a global min withdrawal delay across all strategies.
-     * In addition, we now also configure withdrawal delays on a per-strategy basis.
-     * To withdraw from a strategy, max(minWithdrawalDelayBlocks, strategyWithdrawalDelayBlocks[strategy]) number of blocks must have passed.
-     * See mapping strategyWithdrawalDelayBlocks below for per-strategy withdrawal delays.
-     */
+    /// @dev Do not remove, deprecated storage.
     uint256 private __deprecated_minWithdrawalDelayBlocks;
 
-    /// @notice Mapping: hash of withdrawal inputs, aka 'withdrawalRoot' => whether the withdrawal is pending
-    mapping(bytes32 => bool) public pendingWithdrawals;
+    /// @notice Returns whether a given `withdrawalRoot` has a pending withdrawal.
+    mapping(bytes32 withdrawalRoot => bool pending) public pendingWithdrawals;
 
-    /// @notice Mapping: staker => cumulative number of queued withdrawals they have ever initiated.
+    /// @notice Returns the total number of withdrawals that have been queued for a given `staker`.
     /// @dev This only increments (doesn't decrement), and is used to help ensure that otherwise identical withdrawals have unique hashes.
-    mapping(address => uint256) public cumulativeWithdrawalsQueued;
+    mapping(address staker => uint256 total) public cumulativeWithdrawalsQueued;
 
-    /// @notice Deprecated from an old Goerli release
+    /// @dev Do not remove, deprecated storage.
     /// See conversation here: https://github.com/Layr-Labs/eigenlayer-contracts/pull/365/files#r1417525270
     address private __deprecated_stakeRegistry;
 
-    /**
-     * @notice Minimum delay enforced by this contract per Strategy for completing queued withdrawals. Measured in blocks, and adjustable by this contract's owner,
-     * up to a maximum of `MAX_WITHDRAWAL_DELAY_BLOCKS`. Minimum value is 0 (i.e. no delay enforced).
-     */
-    mapping(IStrategy => uint256) private __deprecated_strategyWithdrawalDelayBlocks;
-
-    /// @notice Mapping: staker => strategy =>
-    ///    (
-    ///       scaling factor used to calculate the staker's shares in the strategy,
-    ///       beacon chain scaling factor used to calculate the staker's withdrawable shares in the strategy.
-    ///    )
-    /// Note that we don't need the beaconChainScalingFactor for non beaconChainETHStrategy strategies, but it's nicer syntactically to keep it.
-    mapping(address => mapping(IStrategy => StakerScalingFactors)) public stakerScalingFactor;
+    /// @dev Do not remove, deprecated storage.
+    mapping(IStrategy strategy => uint256 delayBlocks) private __deprecated_strategyWithdrawalDelayBlocks;
+
+    /// @notice Returns the scaling factors for a `staker` for a given `strategy`.
+    /// @dev We do not need the `beaconChainScalingFactor` for non-beaconchain strategies, but it's nicer syntactically to keep it.
+    mapping(address staker => mapping(IStrategy strategy => StakerScalingFactors)) public stakerScalingFactor;
 
     // Construction
 

src/contracts/core/RewardsCoordinatorStorage.sol

@@ -60,6 +60,7 @@ abstract contract RewardsCoordinatorStorage is IRewardsCoordinator {
 
     // Mutatables
 
+    /// @dev Do not remove, deprecated storage.
     bytes32 internal __deprecated_DOMAIN_SEPARATOR;
 
     /**
@@ -78,27 +79,27 @@ abstract contract RewardsCoordinatorStorage is IRewardsCoordinator {
     /// @notice the commission for all operators across all avss
     uint16 public globalOperatorCommissionBips;
 
-    /// @notice Mapping: earner => the address of the entity who can call `processClaim` on behalf of the earner
-    mapping(address => address) public claimerFor;
+    /// @notice Returns the `claimer` for a given `earner`.
+    /// @dev The claimer is able to call `processClaim` on behalf of the `earner`.
+    mapping(address earner => address claimer) public claimerFor;
 
-    /// @notice Mapping: earner => token => total amount claimed
-    mapping(address => mapping(IERC20 => uint256)) public cumulativeClaimed;
+    /// @notice Returns the total claimed amount for an `earner` for a given `token`.
+    mapping(address earner => mapping(IERC20 token => uint256 claimed)) public cumulativeClaimed;
 
-    /// @notice Used for unique rewardsSubmissionHashes per AVS and for RewardsForAllSubmitters and the tokenHopper
-    mapping(address => uint256) public submissionNonce;
+    /// @notice Returns the submission `nonce` for an `avs`.
+    mapping(address avs => uint256 nonce) public submissionNonce;
 
-    /// @notice Mapping: avs => avsRewardsSubmissionHash => bool to check if rewards submission hash has been submitted
-    mapping(address => mapping(bytes32 => bool)) public isAVSRewardsSubmissionHash;
+    /// @notice Returns whether a `hash` is a `valid` rewards submission hash for a given `avs`.
+    mapping(address avs => mapping(bytes32 hash => bool valid)) public isAVSRewardsSubmissionHash;
 
-    /// @notice Mapping: avs => rewardsSubmissionForAllHash => bool to check if rewards submission hash for all has been submitted
-    mapping(address => mapping(bytes32 => bool)) public isRewardsSubmissionForAllHash;
+    /// @notice Returns whether a `hash` is a `valid` rewards submission for all hash for a given `avs`.
+    mapping(address avs => mapping(bytes32 hash => bool valid)) public isRewardsSubmissionForAllHash;
 
-    /// @notice Mapping: address => bool to check if the address is permissioned to call createRewardsForAllSubmission
-    mapping(address => bool) public isRewardsForAllSubmitter;
+    /// @notice Returns whether a `submitter` is a `valid` rewards for all submitter.
+    mapping(address submitter => bool valid) public isRewardsForAllSubmitter;
 
-    /// @notice Mapping: avs => rewardsSubmissionForAllEarnersHash => bool to check
-    /// if rewards submission hash for all stakers and operators has been submitted
-    mapping(address => mapping(bytes32 => bool)) public isRewardsSubmissionForAllEarnersHash;
+    /// @notice Returns whether a `hash` is a `valid` rewards submission for all earners hash for a given `avs`.
+    mapping(address avs => mapping(bytes32 hash => bool valid)) public isRewardsSubmissionForAllEarnersHash;
 
     // Construction