comments + storage gap

contracts/contracts/interfaces/IMevCommitMiddleware.sol

@@ -6,24 +6,35 @@ import {IRegistry} from "symbiotic-core/interfaces/common/IRegistry.sol";
 
 interface IMevCommitMiddleware {
 
+    /// @notice Struct representing a registered operator.
     struct OperatorRecord {
+        /// @notice A possible occurrence of a deregistration request.
         TimestampOccurrence.Occurrence deregRequestOccurrence;
+        /// @notice Whether this operator record exists.
         bool exists;
+        /// @notice Whether this operator is blacklisted.
         bool isBlacklisted;
     }
 
+    /// @notice Struct representing a registered vault.
     struct VaultRecord {
+        /// @notice Whether this vault record exists.
         bool exists;
+        /// @notice A possible occurrence of a deregistration request.
         TimestampOccurrence.Occurrence deregRequestOccurrence;
+        /// @notice The slash amount per validator, relevant to this vault.
         uint256 slashAmount;
     }
 
+    /// @notice Struct representing a registered validator.
     struct ValidatorRecord {
         /// @notice The vault holding slashable stake which represents the validator.
         address vault;
         /// @notice The operator which registered this validator pubkey with a vault.
         address operator;
+        /// @notice Whether this validator record exists.
         bool exists;
+        /// @notice A possible occurrence of a deregistration request.
         TimestampOccurrence.Occurrence deregRequestOccurrence;
     }
 

contracts/contracts/validator-registry/middleware/MevCommitMiddlewareStorage.sol

@@ -7,18 +7,28 @@ import {IRegistry} from "symbiotic-core/interfaces/common/IRegistry.sol";
 
 abstract contract MevCommitMiddlewareStorage {
 
+    /// @notice The only subnetwork ID for mev-commit middleware. Ie. mev-commit doesn't implement multiple subnets.
     uint96 public constant SUBNETWORK_ID = 1;
 
+    /// @notice Enum TYPE for Symbiotic core NetworkRestakeDelegator.
     uint64 public constant NETWORK_RESTAKE_DELEGATOR_TYPE = 0;
+
+    /// @notice Enum TYPE for Symbiotic core FullRestakeDelegator.
     uint64 public constant FULL_RESTAKE_DELEGATOR_TYPE = 1;
 
+    /// @notice Enum TYPE for Symbiotic core InstantSlasher.
     uint64 public constant INSTANT_SLASHER_TYPE = 0;
+
+    /// @notice Enum TYPE for Symbiotic core VetoSlasher.
     uint64 public constant VETO_SLASHER_TYPE = 1;
 
+    /// @notice Symbiotic core network registry.
     IRegistry public networkRegistry;
 
+    /// @notice Symbiotic core operator registry.
     IRegistry public operatorRegistry;
 
+    /// @notice Symbiotic core vault factory.
     IRegistry public vaultFactory;
 
     /// @notice The network address, which must have registered with the NETWORK_REGISTRY.
@@ -29,14 +39,22 @@ abstract contract MevCommitMiddlewareStorage {
     /// @notice This also serves as the number of seconds that a registered Vault's epochDuration must be greater than.
     uint256 public slashPeriodSeconds;
 
+    /// @notice Address of the mev-commit slash oracle.
     address public slashOracle;
 
+    /// @notice Mapping of a validator's BLS public key to its validator record.
     mapping(bytes blsPubkey => IMevCommitMiddleware.ValidatorRecord) public validatorRecords;
 
+    /// @notice Mapping of an operator's address to its operator record.
     mapping(address operatorAddress => IMevCommitMiddleware.OperatorRecord) public operatorRecords;
 
+    /// @notice Mapping of a vault's address to its vault record.
     mapping(address vaultAddress => IMevCommitMiddleware.VaultRecord) public vaultRecords;
 
-    mapping(address vault =>
-        mapping(address operator => EnumerableSet.BytesSet)) internal _vaultAndOperatorToValset;
+    /// @notice Mapping of a vault to its representative operator, to a set of validator BLS public keys being secured
+    /// by the vault.
+    mapping(address vault => mapping(address operator => EnumerableSet.BytesSet)) internal _vaultAndOperatorToValset;
+
+    /// @dev See https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable#storage-gaps
+    uint256[48] private __gap;
 }