Skip to content

Commit

Permalink
docs: natspec IServiceManager
Browse files Browse the repository at this point in the history
  • Loading branch information
@0xClandestine
0xClandestine committed Jan 24, 2025
1 parent 2bf7961 commit 3768612
Show file tree
Hide file tree
Showing 5 changed files with 97 additions and 170 deletions.
3 changes: 0 additions & 3 deletions src/BLSApkRegistryStorage.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,15 @@ abstract contract BLSApkRegistryStorage is Initializable, IBLSApkRegistry {

/// @inheritdoc IBLSApkRegistry
mapping(address operator => bytes32 operatorId) public operatorToPubkeyHash;

/// @inheritdoc IBLSApkRegistry
mapping(bytes32 pubkeyHash => address operator) public pubkeyHashToOperator;

/// @inheritdoc IBLSApkRegistry
mapping(address operator => BN254.G1Point pubkeyG1) public operatorToPubkey;

/// AGGREGATE PUBLIC KEY STORAGE

/// @inheritdoc IBLSApkRegistry
mapping(uint8 quorumNumber => IBLSApkRegistryTypes.ApkUpdate[]) public apkHistory;

/// @inheritdoc IBLSApkRegistry
mapping(uint8 quorumNumber => BN254.G1Point) public currentApk;

Expand Down
30 changes: 5 additions & 25 deletions src/EjectionManager.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ pragma solidity ^0.8.27;
import {OwnableUpgradeable} from "@openzeppelin-upgrades/contracts/access/OwnableUpgradeable.sol";
import {
EjectionManagerStorage,
IEjectionManager,
IRegistryCoordinator,
IStakeRegistry
} from "./EjectionManagerStorage.sol";
Expand All @@ -22,11 +23,6 @@ contract EjectionManager is OwnableUpgradeable, EjectionManagerStorage {
_disableInitializers();
}

/**
* @param _owner will hold the owner role
* @param ejectors will hold the ejector role
* @param _quorumEjectionParams are the ratelimit parameters for the quorum at each index
*/
function initialize(
address _owner,
address[] memory ejectors,
Expand All @@ -41,12 +37,7 @@ contract EjectionManager is OwnableUpgradeable, EjectionManagerStorage {
}
}

/**
* @notice Ejects operators from the AVSs RegistryCoordinator under a ratelimit
* @param operatorIds The ids of the operators 'j' to eject for each quorum 'i'
* @dev This function will eject as many operators as possible prioritizing operators at the lower index
* @dev The owner can eject operators without recording of stake ejection
*/
/// @inheritdoc IEjectionManager
function ejectOperators(
bytes32[][] memory operatorIds
) external {
Expand Down Expand Up @@ -98,23 +89,15 @@ contract EjectionManager is OwnableUpgradeable, EjectionManagerStorage {
}
}

/**
* @notice Sets the ratelimit parameters for a quorum
* @param quorumNumber The quorum number to set the ratelimit parameters for
* @param _quorumEjectionParams The quorum ratelimit parameters to set for the given quorum
*/
/// @inheritdoc IEjectionManager
function setQuorumEjectionParams(
uint8 quorumNumber,
QuorumEjectionParams memory _quorumEjectionParams
) external onlyOwner {
_setQuorumEjectionParams(quorumNumber, _quorumEjectionParams);
}

/**
* @notice Sets the address permissioned to eject operators under a ratelimit
* @param ejector The address to permission
* @param status The status to set for the given address
*/
/// @inheritdoc IEjectionManager
function setEjector(address ejector, bool status) external onlyOwner {
_setEjector(ejector, status);
}
Expand All @@ -139,10 +122,7 @@ contract EjectionManager is OwnableUpgradeable, EjectionManagerStorage {
emit EjectorUpdated(ejector, status);
}

/**
* @notice Returns the amount of stake that can be ejected for a quorum at the current block.timestamp
* @param quorumNumber The quorum number to view ejectable stake for
*/
/// @inheritdoc IEjectionManager
function amountEjectableForQuorum(
uint8 quorumNumber
) public view returns (uint256) {
Expand Down
64 changes: 23 additions & 41 deletions src/IndexRegistry.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,11 @@ import {IRegistryCoordinator} from "./interfaces/IRegistryCoordinator.sol";
* @author Layr Labs, Inc.
*/
contract IndexRegistry is IndexRegistryStorage {
/// @notice when applied to a function, only allows the RegistryCoordinator to call it
modifier onlyRegistryCoordinator() {
_checkRegistryCoordinator();
_;
}

/// @notice sets the (immutable) `registryCoordinator` address
constructor(
IRegistryCoordinator _registryCoordinator
) IndexRegistryStorage(_registryCoordinator) {}
Expand Down Expand Up @@ -104,9 +102,7 @@ contract IndexRegistry is IndexRegistryStorage {
*
*/

/**
* @notice Increases the historical operator count by 1 and returns the new count
*/
/// @notice Increases the historical operator count by 1 and returns the new count.
function _increaseOperatorCount(
uint8 quorumNumber
) internal returns (uint32) {
Expand All @@ -129,9 +125,7 @@ contract IndexRegistry is IndexRegistryStorage {
return newOperatorCount;
}

/**
* @notice Decreases the historical operator count by 1 and returns the new count
*/
/// @notice Decreases the historical operator count by 1 and returns the new count.
function _decreaseOperatorCount(
uint8 quorumNumber
) internal returns (uint32) {
Expand All @@ -143,11 +137,9 @@ contract IndexRegistry is IndexRegistryStorage {
return newOperatorCount;
}

/**
* @notice Update `_operatorCountHistory` with a new operator count
* @dev If the lastUpdate was made in the this block, update the entry.
* Otherwise, push a new historical entry.
*/
/// @notice Updates `_operatorCountHistory` with a new operator count.
/// @dev If the lastUpdate was made in this block, update the entry.
/// Otherwise, push a new historical entry.
function _updateOperatorCountHistory(
uint8 quorumNumber,
QuorumUpdate storage lastUpdate,
Expand All @@ -162,11 +154,9 @@ contract IndexRegistry is IndexRegistryStorage {
}
}

/**
* @notice For a given quorum and operatorIndex, pop and return the last operatorId in the history
* @dev The last entry's operatorId is updated to OPERATOR_DOES_NOT_EXIST_ID
* @return The removed operatorId
*/
/// @notice For a given quorum and operatorIndex, pop and return the last operatorId in the history.
/// @dev The last entry's operatorId is updated to OPERATOR_DOES_NOT_EXIST_ID.
/// @return The removed operatorId.
function _popLastOperator(
uint8 quorumNumber,
uint32 operatorIndex
Expand All @@ -182,12 +172,10 @@ contract IndexRegistry is IndexRegistryStorage {
return removedOperatorId;
}

/**
* @notice Assign an operator to an index and update the index history
* @param operatorId operatorId of the operator to update
* @param quorumNumber quorumNumber of the operator to update
* @param operatorIndex the latest index of that operator in the list of operators registered for this quorum
*/
/// @notice Assigns an operator to an index and updates the index history.
/// @param operatorId operatorId of the operator to update.
/// @param quorumNumber quorumNumber of the operator to update.
/// @param operatorIndex the latest index of that operator in the list of operators registered for this quorum.
function _assignOperatorToIndex(
bytes32 operatorId,
uint8 quorumNumber,
Expand All @@ -202,11 +190,9 @@ contract IndexRegistry is IndexRegistryStorage {
emit QuorumIndexUpdate(operatorId, quorumNumber, operatorIndex);
}

/**
* @notice Update `_operatorIndexHistory` with a new operator id for the current block
* @dev If the lastUpdate was made in the this block, update the entry.
* Otherwise, push a new historical entry.
*/
/// @notice Updates `_operatorIndexHistory` with a new operator id for the current block.
/// @dev If the lastUpdate was made in this block, update the entry.
/// Otherwise, push a new historical entry.
function _updateOperatorIndexHistory(
uint8 quorumNumber,
uint32 operatorIndex,
Expand All @@ -222,17 +208,17 @@ contract IndexRegistry is IndexRegistryStorage {
}
}

/// @notice Returns the most recent operator count update for a quorum
/// @dev Reverts if the quorum does not exist (history length == 0)
/// @notice Returns the most recent operator count update for a quorum.
/// @dev Reverts if the quorum does not exist (history length == 0).
function _latestQuorumUpdate(
uint8 quorumNumber
) internal view returns (QuorumUpdate storage) {
uint256 historyLength = _operatorCountHistory[quorumNumber].length;
return _operatorCountHistory[quorumNumber][historyLength - 1];
}

/// @notice Returns the most recent operator id update for an index
/// @dev Reverts if the index has never been used (history length == 0)
/// @notice Returns the most recent operator id update for an index.
/// @dev Reverts if the index has never been used (history length == 0).
function _latestOperatorIndexUpdate(
uint8 quorumNumber,
uint32 operatorIndex
Expand All @@ -241,10 +227,8 @@ contract IndexRegistry is IndexRegistryStorage {
return _operatorIndexHistory[quorumNumber][operatorIndex][historyLength - 1];
}

/**
* @notice Returns the total number of operators of the service for the given `quorumNumber` at the given `blockNumber`
* @dev Reverts if the quorum does not exist, or if the blockNumber is from before the quorum existed
*/
/// @notice Returns the total number of operators of the service for the given `quorumNumber` at the given `blockNumber`.
/// @dev Reverts if the quorum does not exist, or if the blockNumber is from before the quorum existed.
function _operatorCountAtBlockNumber(
uint8 quorumNumber,
uint32 blockNumber
Expand All @@ -265,10 +249,8 @@ contract IndexRegistry is IndexRegistryStorage {
);
}

/**
* @return operatorId at the given `operatorIndex` at the given `blockNumber` for the given `quorumNumber`
* Precondition: requires that the operatorIndex was used active at the given block number for quorum
*/
/// @notice Returns the operatorId at the given `operatorIndex` at the given `blockNumber` for the given `quorumNumber`.
/// @dev Requires that the operatorIndex was active at the given block number for quorum.
function _operatorIdForIndexAtBlockNumber(
uint8 quorumNumber,
uint32 operatorIndex,
Expand Down
102 changes: 41 additions & 61 deletions src/interfaces/IServiceManager.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,93 +13,73 @@ import {IStrategy} from "eigenlayer-contracts/src/contracts/interfaces/IStrategy
import {IAVSRegistrar} from "eigenlayer-contracts/src/contracts/interfaces/IAVSRegistrar.sol";

interface IServiceManagerErrors {
/// @dev Thrown when a function is called by an address that is not the RegistryCoordinator
/// @notice Thrown when a function is called by an address that is not the RegistryCoordinator.
error OnlyRegistryCoordinator();
/// @dev Thrown when a function is called by an address that is not the RewardsInitiator
/// @notice Thrown when a function is called by an address that is not the RewardsInitiator.
error OnlyRewardsInitiator();
/// @dev Thrown when a function is called by an address that is not the Slasher
/// @notice Thrown when a function is called by an address that is not the StakeRegistry.
error OnlyStakeRegistry();
/// @dev Thrown when a function is called by an address that is not the Slasher
/// @notice Thrown when a function is called by an address that is not the Slasher.
error OnlySlasher();
/// @dev Thrown when a slashing proposal delay has not been met yet.
/// @notice Thrown when a slashing proposal delay has not been met yet.
error DelayPeriodNotPassed();
}

/**
* @title Minimal interface for a ServiceManager-type contract that forms the single point for an AVS to push updates to EigenLayer
* @author Layr Labs, Inc.
*/
interface IServiceManager is IServiceManagerUI, IServiceManagerErrors {
// EVENTS
interface IServiceManagerEvents {
/// @notice Emitted when the rewards initiator address is updated.
/// @param prevRewardsInitiator The previous rewards initiator address.
/// @param newRewardsInitiator The new rewards initiator address.
event RewardsInitiatorUpdated(address prevRewardsInitiator, address newRewardsInitiator);
}

/**
* @notice Creates a new rewards submission to the EigenLayer RewardsCoordinator contract, to be split amongst the
* set of stakers delegated to operators who are registered to this `avs`
* @param rewardsSubmissions The rewards submissions being created
* @dev Only callable by the permissioned rewardsInitiator address
* @dev The duration of the `rewardsSubmission` cannot exceed `MAX_REWARDS_DURATION`
* @dev The tokens are sent to the `RewardsCoordinator` contract
* @dev Strategies must be in ascending order of addresses to check for duplicates
* @dev This function will revert if the `rewardsSubmission` is malformed,
* e.g. if the `strategies` and `weights` arrays are of non-equal lengths
*/
interface IServiceManager is IServiceManagerUI, IServiceManagerErrors, IServiceManagerEvents {
/// @notice Creates a new rewards submission to the EigenLayer RewardsCoordinator contract.
/// @dev Only callable by the permissioned rewardsInitiator address.
/// @dev The duration of the `rewardsSubmission` cannot exceed `MAX_REWARDS_DURATION`.
/// @dev The tokens are sent to the `RewardsCoordinator` contract.
/// @dev Strategies must be in ascending order of addresses to check for duplicates.
/// @dev This function will revert if the `rewardsSubmission` is malformed,
/// e.g. if the `strategies` and `weights` arrays are of non-equal lengths.
/// @param rewardsSubmissions The rewards submissions to be split amongst the set of stakers
/// delegated to operators who are registered to this `avs`.
function createAVSRewardsSubmission(
IRewardsCoordinator.RewardsSubmission[] calldata rewardsSubmissions
) external;

/**
*
* PERMISSIONCONTROLLER FUNCTIONS
*
*/
/**
* @notice Calls `addPendingAdmin` on the `PermissionController` contract
* with `account` being the address of this contract.
* @param admin The address of the admin to add
* @dev Only callable by the owner of the contract
*/
/// @notice PERMISSIONCONTROLLER FUNCTIONS

/// @notice Calls `addPendingAdmin` on the `PermissionController` contract.
/// @dev Only callable by the owner of the contract.
/// @param admin The address of the admin to add.
function addPendingAdmin(
address admin
) external;

/**
* @notice Calls `removePendingAdmin` on the `PermissionController` contract
* with `account` being the address of this contract.
* @param pendingAdmin The address of the pending admin to remove
* @dev Only callable by the owner of the contract
*/
/// @notice Calls `removePendingAdmin` on the `PermissionController` contract.
/// @dev Only callable by the owner of the contract.
/// @param pendingAdmin The address of the pending admin to remove.
function removePendingAdmin(
address pendingAdmin
) external;

/**
* @notice Calls `removeAdmin` on the `PermissionController` contract
* with `account` being the address of this contract.
* @param admin The address of the admin to remove
* @dev Only callable by the owner of the contract
*/
/// @notice Calls `removeAdmin` on the `PermissionController` contract.
/// @dev Only callable by the owner of the contract.
/// @param admin The address of the admin to remove.
function removeAdmin(
address admin
) external;

/**
* @notice Calls `setAppointee` on the `PermissionController` contract
* with `account` being the address of this contract.
* @param appointee The address of the appointee to set
* @param target The address of the target to set the appointee for
* @param selector The function selector to set the appointee for
* @dev Only callable by the owner of the contract
*/
/// @notice Calls `setAppointee` on the `PermissionController` contract.
/// @dev Only callable by the owner of the contract.
/// @param appointee The address of the appointee to set.
/// @param target The address of the target to set the appointee for.
/// @param selector The function selector to set the appointee for.
function setAppointee(address appointee, address target, bytes4 selector) external;

/**
* @notice Calls `removeAppointee` on the `PermissionController` contract
* with `account` being the address of this contract.
* @param appointee The address of the appointee to remove
* @param target The address of the target to remove the appointee for
* @param selector The function selector to remove the appointee for
* @dev Only callable by the owner of the contract
*/
/// @notice Calls `removeAppointee` on the `PermissionController` contract.
/// @dev Only callable by the owner of the contract.
/// @param appointee The address of the appointee to remove.
/// @param target The address of the target to remove the appointee for.
/// @param selector The function selector to remove the appointee for.
function removeAppointee(address appointee, address target, bytes4 selector) external;
}
Loading

0 comments on commit 3768612

Please sign in to comment.