docs: natspec ECDSAStakeRegistry

Author: 0xClandestine

src/interfaces/IECDSAStakeRegistry.sol

@@ -1,56 +1,99 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.27;
 
+import {IERC1271Upgradeable} from
+    "@openzeppelin-upgrades/contracts/interfaces/IERC1271Upgradeable.sol";
 import {IStrategy} from "eigenlayer-contracts/src/contracts/interfaces/IStrategy.sol";
+import {ISignatureUtils} from "eigenlayer-contracts/src/contracts/interfaces/ISignatureUtils.sol";
+import {IDelegationManager} from
+    "eigenlayer-contracts/src/contracts/interfaces/IDelegationManager.sol";
 
-struct StrategyParams {
-    IStrategy strategy; // The strategy contract reference
-    uint96 multiplier; // The multiplier applied to the strategy
+// TODO: many of these errors do not have test coverage.
+
+interface IECDSAStakeRegistryErrors {
+    /// @notice Thrown when the lengths of the signers array and signatures array do not match.
+    error LengthMismatch();
+    /// @notice Thrown when encountering an invalid length for the signers or signatures array.
+    error InvalidLength();
+    /// @notice Thrown when encountering an invalid signature.
+    error InvalidSignature();
+    /// @notice Thrown when the threshold update is greater than BPS.
+    error InvalidThreshold();
+    /// @notice Thrown when missing operators in an update.
+    error MustUpdateAllOperators();
+    /// @notice Thrown when reference blocks must be for blocks that have already been confirmed.
+    error InvalidReferenceBlock();
+    /// @notice Thrown when operator weights were out of sync and the signed weight exceed the total.
+    error InvalidSignedWeight();
+    /// @notice Thrown when the total signed stake fails to meet the required threshold.
+    error InsufficientSignedStake();
+    /// @notice Thrown when an individual signer's weight fails to meet the required threshold.
+    error InsufficientWeight();
+    /// @notice Thrown when the quorum is invalid.
+    error InvalidQuorum();
+    /// @notice Thrown when the system finds a list of items unsorted.
+    error NotSorted();
+    /// @notice Thrown when registering an already registered operator.
+    error OperatorAlreadyRegistered();
+    /// @notice Thrown when de-registering or updating the stake for an unregisted operator.
+    error OperatorNotRegistered();
 }
 
-struct Quorum {
-    StrategyParams[] strategies; // An array of strategy parameters to define the quorum
+interface IECDSAStakeRegistryTypes {
+    /// @notice Parameters for a strategy and its weight multiplier.
+    /// @param strategy The strategy contract reference.
+    /// @param multiplier The multiplier applied to the strategy.
+    struct StrategyParams {
+        IStrategy strategy;
+        uint96 multiplier;
+    }
+
+    /// @notice Configuration for a quorum's strategies.
+    /// @param strategies An array of strategy parameters defining the quorum.
+    struct Quorum {
+        StrategyParams[] strategies;
+    }
 }
 
-interface IECDSAStakeRegistry {
+interface IECDSAStakeRegistryEvents is IECDSAStakeRegistryTypes {
     /// @notice Emitted when the system registers an operator
-    /// @param _operator The address of the registered operator
-    /// @param _avs The address of the associated AVS
-    event OperatorRegistered(address indexed _operator, address indexed _avs);
+    /// @param operator The address of the registered operator
+    /// @param avs The address of the associated AVS
+    event OperatorRegistered(address indexed operator, address indexed avs);
 
     /// @notice Emitted when the system deregisters an operator
-    /// @param _operator The address of the deregistered operator
-    /// @param _avs The address of the associated AVS
-    event OperatorDeregistered(address indexed _operator, address indexed _avs);
+    /// @param operator The address of the deregistered operator
+    /// @param avs The address of the associated AVS
+    event OperatorDeregistered(address indexed operator, address indexed avs);
 
     /// @notice Emitted when the system updates the quorum
-    /// @param _old The previous quorum configuration
-    /// @param _new The new quorum configuration
-    event QuorumUpdated(Quorum _old, Quorum _new);
+    /// @param previous The previous quorum configuration
+    /// @param current The new quorum configuration
+    event QuorumUpdated(Quorum previous, Quorum current);
 
     /// @notice Emitted when the weight to join the operator set updates
-    /// @param _old The previous minimum weight
-    /// @param _new The new minimumWeight
-    event MinimumWeightUpdated(uint256 _old, uint256 _new);
+    /// @param previous The previous minimum weight
+    /// @param current The new minimumWeight
+    event MinimumWeightUpdated(uint256 previous, uint256 current);
 
     /// @notice Emitted when the weight required to be an operator changes
     /// @param oldMinimumWeight The previous weight
     /// @param newMinimumWeight The updated weight
     event UpdateMinimumWeight(uint256 oldMinimumWeight, uint256 newMinimumWeight);
 
     /// @notice Emitted when the system updates an operator's weight
-    /// @param _operator The address of the operator updated
+    /// @param operator The address of the operator updated
     /// @param oldWeight The operator's weight before the update
     /// @param newWeight The operator's weight after the update
-    event OperatorWeightUpdated(address indexed _operator, uint256 oldWeight, uint256 newWeight);
+    event OperatorWeightUpdated(address indexed operator, uint256 oldWeight, uint256 newWeight);
 
     /// @notice Emitted when the system updates the total weight
     /// @param oldTotalWeight The total weight before the update
     /// @param newTotalWeight The total weight after the update
     event TotalWeightUpdated(uint256 oldTotalWeight, uint256 newTotalWeight);
 
     /// @notice Emits when setting a new threshold weight.
-    event ThresholdWeightUpdated(uint256 _thresholdWeight);
+    event ThresholdWeightUpdated(uint256 thresholdWeight);
 
     /// @notice Emitted when an operator's signing key is updated
     /// @param operator The address of the operator whose signing key was updated
@@ -63,43 +106,145 @@ interface IECDSAStakeRegistry {
         address indexed newSigningKey,
         address oldSigningKey
     );
-    /// @notice Indicates when the lengths of the signers array and signatures array do not match.
-
-    error LengthMismatch();
-
-    /// @notice Indicates encountering an invalid length for the signers or signatures array.
-    error InvalidLength();
-
-    /// @notice Indicates encountering an invalid signature.
-    error InvalidSignature();
-
-    /// @notice Thrown when the threshold update is greater than BPS
-    error InvalidThreshold();
-
-    /// @notice Thrown when missing operators in an update
-    error MustUpdateAllOperators();
-
-    /// @notice Reference blocks must be for blocks that have already been confirmed
-    error InvalidReferenceBlock();
-
-    /// @notice Indicates operator weights were out of sync and the signed weight exceed the total
-    error InvalidSignedWeight();
-
-    /// @notice Indicates the total signed stake fails to meet the required threshold.
-    error InsufficientSignedStake();
-
-    /// @notice Indicates an individual signer's weight fails to meet the required threshold.
-    error InsufficientWeight();
-
-    /// @notice Indicates the quorum is invalid
-    error InvalidQuorum();
-
-    /// @notice Indicates the system finds a list of items unsorted
-    error NotSorted();
-
-    /// @notice Thrown when registering an already registered operator
-    error OperatorAlreadyRegistered();
+}
 
-    /// @notice Thrown when de-registering or updating the stake for an unregisted operator
-    error OperatorNotRegistered();
+interface IECDSAStakeRegistry is
+    IECDSAStakeRegistryErrors,
+    IECDSAStakeRegistryEvents,
+    IERC1271Upgradeable
+{
+    /// ACTIONS
+
+    /// @notice Registers a new operator using a provided operators signature and signing key.
+    /// @param operatorSignature Contains the operator's signature, salt, and expiry.
+    /// @param signingKey The signing key to add to the operator's history.
+    function registerOperatorWithSignature(
+        ISignatureUtils.SignatureWithSaltAndExpiry memory operatorSignature,
+        address signingKey
+    ) external;
+
+    /// @notice Deregisters an existing operator.
+    function deregisterOperator() external;
+
+    /// @notice Updates the signing key for an operator.
+    /// @param newSigningKey The new signing key to set for the operator.
+    /// @dev Only callable by the operator themselves.
+    function updateOperatorSigningKey(
+        address newSigningKey
+    ) external;
+
+    /// @notice Updates the StakeRegistry's view of operators' stakes.
+    /// @param operators A list of operator addresses to update.
+    /// @dev Queries stakes from the Eigenlayer core DelegationManager contract.
+    function updateOperators(
+        address[] memory operators
+    ) external;
+
+    /// @notice Updates the quorum configuration and the set of operators.
+    /// @param quorum The new quorum configuration, including strategies and their new weights.
+    /// @param operators The list of operator addresses to update stakes for.
+    function updateQuorumConfig(
+        IECDSAStakeRegistryTypes.Quorum memory quorum,
+        address[] memory operators
+    ) external;
+
+    /// @notice Updates the weight an operator must have to join the operator set.
+    /// @param newMinimumWeight The new weight an operator must have to join the operator set.
+    /// @param operators The list of operators to update after changing the minimum weight.
+    function updateMinimumWeight(
+        uint256 newMinimumWeight,
+        address[] memory operators
+    ) external;
+
+    /// @notice Sets a new cumulative threshold weight for message validation.
+    /// @param thresholdWeight The updated threshold weight required to validate a message.
+    function updateStakeThreshold(
+        uint256 thresholdWeight
+    ) external;
+
+    /// VIEW
+
+    /// @notice Retrieves the current stake quorum details.
+    /// @return The current quorum of strategies and weights.
+    function quorum() external view returns (IECDSAStakeRegistryTypes.Quorum memory);
+
+    /// @notice Retrieves the latest signing key for a given operator.
+    /// @param operator The address of the operator.
+    /// @return The latest signing key of the operator.
+    function getLatestOperatorSigningKey(
+        address operator
+    ) external view returns (address);
+
+    /// @notice Retrieves the signing key for an operator at a specific block.
+    /// @param operator The address of the operator.
+    /// @param blockNumber The block number to query at.
+    /// @return The signing key of the operator at the given block.
+    function getOperatorSigningKeyAtBlock(
+        address operator,
+        uint256 blockNumber
+    ) external view returns (address);
+
+    /// @notice Retrieves the last recorded weight for a given operator.
+    /// @param operator The address of the operator.
+    /// @return The latest weight of the operator.
+    function getLastCheckpointOperatorWeight(
+        address operator
+    ) external view returns (uint256);
+
+    /// @notice Retrieves the last recorded total weight across all operators.
+    /// @return The latest total weight.
+    function getLastCheckpointTotalWeight() external view returns (uint256);
+
+    /// @notice Retrieves the last recorded threshold weight.
+    /// @return The latest threshold weight.
+    function getLastCheckpointThresholdWeight() external view returns (uint256);
+
+    /// @notice Returns whether an operator is currently registered.
+    /// @param operator The operator address to check.
+    /// @return Whether the operator is registered.
+    function operatorRegistered(
+        address operator
+    ) external view returns (bool);
+
+    /// @notice Returns the minimum weight required for operator participation.
+    /// @return The minimum weight threshold.
+    function minimumWeight() external view returns (uint256);
+
+    /// @notice Retrieves the operator's weight at a specific block number.
+    /// @param operator The address of the operator.
+    /// @param blockNumber The block number to query at.
+    /// @return The weight of the operator at the given block.
+    function getOperatorWeightAtBlock(
+        address operator,
+        uint32 blockNumber
+    ) external view returns (uint256);
+
+    /// @notice Retrieves the operator's weight.
+    /// @param operator The address of the operator.
+    /// @return The current weight of the operator.
+    function getOperatorWeight(
+        address operator
+    ) external view returns (uint256);
+
+    /// @notice Updates operators for a specific quorum.
+    /// @param operatorsPerQuorum Array of operator addresses per quorum.
+    /// @param data Additional data (unused but kept for interface compatibility).
+    function updateOperatorsForQuorum(
+        address[][] memory operatorsPerQuorum,
+        bytes memory data
+    ) external;
+
+    /// @notice Retrieves the total weight at a specific block number.
+    /// @param blockNumber The block number to query at.
+    /// @return The total weight at the given block.
+    function getLastCheckpointTotalWeightAtBlock(
+        uint32 blockNumber
+    ) external view returns (uint256);
+
+    /// @notice Retrieves the threshold weight at a specific block number.
+    /// @param blockNumber The block number to query at.
+    /// @return The threshold weight at the given block.
+    function getLastCheckpointThresholdWeightAtBlock(
+        uint32 blockNumber
+    ) external view returns (uint256);
 }

src/unaudited/ECDSAServiceManagerBase.sol

@@ -12,7 +12,7 @@ import {IStrategy} from "eigenlayer-contracts/src/contracts/interfaces/IStrategy
 import {IStakeRegistry} from "../interfaces/IStakeRegistry.sol";
 import {IRewardsCoordinator} from
     "eigenlayer-contracts/src/contracts/interfaces/IRewardsCoordinator.sol";
-import {Quorum} from "../interfaces/IECDSAStakeRegistry.sol";
+import {IECDSAStakeRegistryTypes} from "../interfaces/IECDSAStakeRegistry.sol";
 import {ECDSAStakeRegistry} from "../unaudited/ECDSAStakeRegistry.sol";
 import {IAVSRegistrar} from "eigenlayer-contracts/src/contracts/interfaces/IAVSRegistrar.sol";
 import {IAllocationManager} from
@@ -197,7 +197,7 @@ abstract contract ECDSAServiceManagerBase is IServiceManager, OwnableUpgradeable
      * @return strategies An array of addresses representing the strategies in the current quorum.
      */
     function _getRestakeableStrategies() internal view virtual returns (address[] memory) {
-        Quorum memory quorum = ECDSAStakeRegistry(stakeRegistry).quorum();
+        IECDSAStakeRegistryTypes.Quorum memory quorum = ECDSAStakeRegistry(stakeRegistry).quorum();
         address[] memory strategies = new address[](quorum.strategies.length);
         for (uint256 i = 0; i < quorum.strategies.length; i++) {
             strategies[i] = address(quorum.strategies[i].strategy);
@@ -226,7 +226,7 @@ abstract contract ECDSAServiceManagerBase is IServiceManager, OwnableUpgradeable
     function _getOperatorRestakedStrategies(
         address _operator
     ) internal view virtual returns (address[] memory) {
-        Quorum memory quorum = ECDSAStakeRegistry(stakeRegistry).quorum();
+        IECDSAStakeRegistryTypes.Quorum memory quorum = ECDSAStakeRegistry(stakeRegistry).quorum();
         uint256 count = quorum.strategies.length;
         IStrategy[] memory strategies = new IStrategy[](count);
         for (uint256 i; i < count; i++) {