docs: describe operator set registration / deregistration

nadir-akhtar · nadir-akhtar · commit dd48e637866c · 2024-12-06T11:30:09.000-08:00
diff --git a/docs/core/AllocationManager.md b/docs/core/AllocationManager.md
@@ -6,31 +6,26 @@
 
 ## Prerequisites
 
-- [The Mechanics of Allocating and Slashing Unique Stake](https://forum.eigenlayer.xyz/t/the-mechanics-of-allocating-and-slashing-unique-stake/13870)
+* [The Mechanics of Allocating and Slashing Unique Stake](https://forum.eigenlayer.xyz/t/the-mechanics-of-allocating-and-slashing-unique-stake/13870)
 
 ## Overview
 
 The AllocationManager contract manages the allocation and slashing of operators' slashable stake across various strategies and operator sets. It also enforces allocation and deallocation delays and handles the slashing process initiated by AVSs.
 
-## Parameterization
-
-- `ALLOCATION_CONFIGURATION_DELAY`: The delay in blocks (estimated) before allocations take effect.
-<!-- TODO: remove these "Very TBD" etc statements and get clarity here -->
-    - Mainnet: `21 days`. Very TBD
-    - Testnet: `1 hours`. Very TBD
-    - Public Devnet: `10 minutes`
-- `DEALLOCATION_DELAY`: The delay in blocks (estimated) before deallocations take effect.
-    - Mainnet: `17.5 days`. Slightly TBD
-    - Testnet: `3 days`. Very TBD
-    - Public Devnet: `1 days`
-
-## Roles
-
 Two types of users interact directly with the AllocationManager:
 * [Operators](#operators)
 * [AVSs](#avss)
 
----
+## Parameterization
+
+* `ALLOCATION_CONFIGURATION_DELAY`: The delay in blocks (estimated) before allocations take effect.
+    * Mainnet: `126000 blocks` (17.5 days).
+    * Testnet: `90 blocks` (15 minutes).
+    * Public Devnet: `90 blocks` (15 minutes).
+* `DEALLOCATION_DELAY`: The delay in blocks (estimated) before deallocations take effect.
+    * Mainnet: `100800 blocks` (14 days).
+    * Testnet: `60 blocks` (10 minutes).
+    * Public Devnet: `60 blocks` (10 minutes).
 
 ## Operators
 
@@ -41,31 +36,40 @@ Operators interact with the AllocationManager to join operator sets, modify thei
 An operator set is defined as below:
 
 ```solidity
+/**
+ * @notice An operator set identified by the AVS address and an identifier
+ * @param avs The address of the AVS this operator set belongs to
+ * @param id The unique identifier for the operator set
+ */
 struct OperatorSet {
     address avs;
     uint32 id;
 }
 ```
 
-Every `operatorSet` corresponds to a single AVS, as indicated by the `avs` parameter. Each `operatorSet` is then given a specific `id` upon creation, which must be unique per `avs`. Together, the `avs` and `id` form the `key` that uniquely identifies a given `operatorSet`.
+Every `OperatorSet` corresponds to a single AVS, as indicated by the `avs` parameter. Each `OperatorSet` is then given a specific `id` upon creation, which must be unique per `avs`. Together, the `avs` and `id` form the `key` that uniquely identifies a given `OperatorSet`.
 
-Operator registrations are tracked with the struct defined below:
+All members of an operator set are stored in the below mapping:
 
 ```solidity
-/**
-* @notice Parameters used to register for an AVS's operator sets
-* @param avs the AVS being registered for
-* @param operatorSetIds the operator sets within the AVS to register for
-* @param data extra data to be passed to the AVS to complete registration
-*/
-struct RegisterParams {
-    address avs;
-    uint32[] operatorSetIds;
-    bytes data;
-}
+/// @dev Lists the members of an AVS's operator set
+    mapping(bytes32 operatorSetKey => EnumerableSet.AddressSet) internal _operatorSetMembers;
 ```
 
-The registration for an operator as part of a given operator set is captured with the below struct:
+### Operator Set Registration
+
+The following mapping tracks operator registrations for operator sets:
+
+```solidity
+/// @dev Lists the operator sets the operator is registered for. Note that an operator
+/// can be registered without allocated stake. Likewise, an operator can allocate
+/// without being registered.
+mapping(address operator => EnumerableSet.Bytes32Set) internal registeredSets;
+```
+
+The `Bytes32Set` value saves a list of `key` values from `OperatorSet` instances. Each operator [registration](#registerforoperatorsets) and [deregistration](#deregisterfromoperatorsets) respectively adds and removes the relevant `key` for a given operator.
+
+The below struct captures the registration status for an operator regarding a given operator set:
 
 ```solidity
 /**
@@ -80,14 +84,17 @@ struct RegistrationStatus {
 }
 ```
 
-This data is split across two different mappings:
+Note that the `RegistrationStatus` for an operator of an operator set is expected to be in one of three states:
+* `registered: false` and `registeredUntil: 0`
+  * Before any registrations or deregistrations.
+* `registered: true` and `registeredUntil: 0`
+  * After an operator has successfully registered for an operator set.
+* `registered: false` and `registeredUntil: block.number + DEALLOCATION_DELAY`
+  * A deregistered operator. Operators may be slashed for any slashable behavior until the delay has passed.
 
-```solidity
-/// @dev Lists the operator sets the operator is registered for. Note that an operator
-/// can be registered without allocated stake. Likewise, an operator can allocate
-/// without being registered.
-mapping(address operator => EnumerableSet.Bytes32Set) internal registeredSets;
+The below mapping stores that data, where the `operatorSetKey` refers to the `key` described above for a given operator set:
 
+```solidity
 /// @dev Contains the operator's registration status for an operator set.
 mapping(address operator => mapping(bytes32 operatorSetKey => RegistrationStatus)) internal registrationStatus;
 ```
@@ -104,21 +111,70 @@ onlyWhenNotPaused(PAUSED_OPERATOR_SET_REGISTRATION_AND_DEREGISTRATION)
 checkCanCall(operator);
 ```
 
+An operator may call this function to register for any number of operator sets of a given AVS at once. Operator registrations are provided in the form of the struct defined below:
+
+```solidity
+/**
+* @notice Parameters used to register for an AVS's operator sets
+* @param avs the AVS being registered for
+* @param operatorSetIds the operator sets within the AVS to register for
+* @param data extra data to be passed to the AVS to complete registration
+*/
+struct RegisterParams {
+    address avs;
+    uint32[] operatorSetIds;
+    bytes data;
+}
+```
+
+The `data` is arbitrary information passed onto the AVS's specific `AVSRegistrar` for the AVS's particular considerations for acceptance. If the AVS reverts, registration will fail.
+
 *Effects*:
-* The proposed operator sets are added to the operator's list of registered sets
-* The operator is marked as registered for the given operator sets
+* The proposed operator sets are added to the operator's list of registered sets (`registeredSets`)
+* The operator is added to `_operatorSetMembers` for each operator set
+* The operator is marked as registered for the given operator sets (in `registrationStatus`)
+* The `params` for registration are passed to the AVS's `AVSRegistrar`, which can arbitrarily handle the registration request
 
 *Requirements*:
+* Operator registration/deregistration MUST NOT be paused
 * Address MUST be registered as an operator
 * Caller MUST be the operator
   * An admin and/or appointee for the account can also call this function (see the [PermissionController](../permissions/PermissionController.md))
-* Function MUST NOT be paused
-* Proposed operator sets MUST be registered for a given AVS
-* Operator MUST NOT be registered for any given operator sets
+* Each operator set ID MUST exist for the given AVS
+* Operator MUST NOT already be registered for any proposed operator sets
+* The AVS's `AVSRegistrar` MUST NOT revert
+<!-- There is no explict check that the AVS exists -- presumably captured by checking that the opeartor set ID exists for the AVS? -->
 
 #### `deregisterFromOperatorSets`
 
-### Modify Allocations
+```solidity
+function deregisterFromOperatorSets(
+    DeregisterParams calldata params
+)
+external
+onlyWhenNotPaused(PAUSED_OPERATOR_SET_REGISTRATION_AND_DEREGISTRATION)
+```
+
+Operators may desire to deregister from operator sets; this function generally inverts the effects of `registerForOperatorSets` with some specific exceptions.
+
+*Effects*:
+* The proposed operator sets are removed from the operator's list of registered sets (`registeredSets`)
+* The operator is removed from `_operatorSetMembers` for each operator set
+* The operator is marked as deregistered for the given operator sets (in `registrationStatus`)
+* The operator's `registeredUntil` value is set to `uint32(block.number) + DEALLOCATION_DELAY`
+  * As mentioned above, this allows for AVSs to slash deregistered operators that performed slashable behavior, until the delay expires
+* The `params` for registration are passed to the AVS's `AVSRegistrar`, which can arbitrarily handle the registration request
+
+*Requirements*:
+<!-- * Address MUST be registered as an operator -->
+* Operator registration/deregistration MUST NOT be paused
+* Caller MUST be the operator OR the AVS
+  * An admin and/or appointee for either can also call this function (see the [PermissionController](../permissions/PermissionController.md))
+* Each operator set ID MUST exist for the given AVS
+* Operator MUST be registered for the given operator sets
+* Note that, unlike `registerForOperatorSets`, the AVS's `AVSRegistrar` MAY revert and the deregistration will still succeed
+
+### Allocation Modifications
 
 #### `modifyAllocations`
 
@@ -182,7 +238,7 @@ This function is used to complete pending deallocations for a list of strategies
 
 Completing a deallocation decreases the encumbered magnitude for the strategy, allowing them to make allocations with that magnitude. Encumbered magnitude must be decreased only upon completion because pending deallocations can be slashed before they are completable.
 
-### Changing Allocation Delays
+### Allocation Delays Changes
 
 #### `setAllocationDelay`
 
diff --git a/src/contracts/libraries/OperatorSetLib.sol b/src/contracts/libraries/OperatorSetLib.sol
@@ -1,6 +1,11 @@
 // SPDX-License-Identifier: BUSL-1.1
 pragma solidity ^0.8.27;
 
+/**
+ * @notice An operator set identified by the AVS address and an identifier
+ * @param avs The address of the AVS this operator set belongs to
+ * @param id The unique identifier for the operator set
+ */
 struct OperatorSet {
     address avs;
     uint32 id;
