Skip to content

Commit 3c38269

Browse files
0xClandestine0xClandestine
committed
docs: natspec IndexRegistry 
1 parent f1e0776 commit 3c38269

File tree

3 files changed

+119
-111
lines changed

3 files changed

+119
-111
lines changed

‎src/IndexRegistry.sol

Lines changed: 10 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -26,18 +26,7 @@ contract IndexRegistry is IndexRegistryStorage {
2626
*
2727
*/
2828

29-
/**
30-
* @notice Registers the operator with the specified `operatorId` for the quorums specified by `quorumNumbers`.
31-
* @param operatorId is the id of the operator that is being registered
32-
* @param quorumNumbers is the quorum numbers the operator is registered for
33-
* @return numOperatorsPerQuorum is a list of the number of operators (including the registering operator) in each of the quorums the operator is registered for
34-
* @dev access restricted to the RegistryCoordinator
35-
* @dev Preconditions (these are assumed, not validated in this contract):
36-
* 1) `quorumNumbers` has no duplicates
37-
* 2) `quorumNumbers.length` != 0
38-
* 3) `quorumNumbers` is ordered in ascending order
39-
* 4) the operator is not already registered
40-
*/
29+
/// @inheritdoc IIndexRegistry
4130
function registerOperator(
4231
bytes32 operatorId,
4332
bytes calldata quorumNumbers
@@ -68,18 +57,7 @@ contract IndexRegistry is IndexRegistryStorage {
6857
return numOperatorsPerQuorum;
6958
}
7059

71-
/**
72-
* @notice Deregisters the operator with the specified `operatorId` for the quorums specified by `quorumNumbers`.
73-
* @param operatorId is the id of the operator that is being deregistered
74-
* @param quorumNumbers is the quorum numbers the operator is deregistered for
75-
* @dev access restricted to the RegistryCoordinator
76-
* @dev Preconditions (these are assumed, not validated in this contract):
77-
* 1) `quorumNumbers` has no duplicates
78-
* 2) `quorumNumbers.length` != 0
79-
* 3) `quorumNumbers` is ordered in ascending order
80-
* 4) the operator is not already deregistered
81-
* 5) `quorumNumbers` is a subset of the quorumNumbers that the operator is registered for
82-
*/
60+
/// @inheritdoc IIndexRegistry
8361
function deregisterOperator(
8462
bytes32 operatorId,
8563
bytes calldata quorumNumbers
@@ -109,10 +87,7 @@ contract IndexRegistry is IndexRegistryStorage {
10987
}
11088
}
11189

112-
/**
113-
* @notice Initialize a quorum by pushing its first quorum update
114-
* @param quorumNumber The number of the new quorum
115-
*/
90+
/// @inheritdoc IIndexRegistry
11691
function initializeQuorum(
11792
uint8 quorumNumber
11893
) public virtual onlyRegistryCoordinator {
@@ -293,7 +268,7 @@ contract IndexRegistry is IndexRegistryStorage {
293268
/**
294269
* @return operatorId at the given `operatorIndex` at the given `blockNumber` for the given `quorumNumber`
295270
* Precondition: requires that the operatorIndex was used active at the given block number for quorum
296-
*/
271+
*/
297272
function _operatorIdForIndexAtBlockNumber(
298273
uint8 quorumNumber,
299274
uint32 operatorIndex,
@@ -322,8 +297,7 @@ contract IndexRegistry is IndexRegistryStorage {
322297
*
323298
*/
324299

325-
/// @notice Returns the _operatorIndexHistory entry for the specified `operatorIndex` and `quorumNumber`
326-
/// at the specified `arrayIndex`
300+
/// @inheritdoc IIndexRegistry
327301
function getOperatorUpdateAtIndex(
328302
uint8 quorumNumber,
329303
uint32 operatorIndex,
@@ -332,32 +306,30 @@ contract IndexRegistry is IndexRegistryStorage {
332306
return _operatorIndexHistory[quorumNumber][operatorIndex][arrayIndex];
333307
}
334308

335-
/// @notice Returns the _operatorCountHistory entry for the specified `quorumNumber` at the specified `quorumIndex`
309+
/// @inheritdoc IIndexRegistry
336310
function getQuorumUpdateAtIndex(
337311
uint8 quorumNumber,
338312
uint32 quorumIndex
339313
) external view returns (QuorumUpdate memory) {
340314
return _operatorCountHistory[quorumNumber][quorumIndex];
341315
}
342316

343-
/// @notice Returns the most recent QuorumUpdate entry for the specified quorumNumber
344-
/// @dev Reverts if the quorum does not exist
317+
/// @inheritdoc IIndexRegistry
345318
function getLatestQuorumUpdate(
346319
uint8 quorumNumber
347320
) external view returns (QuorumUpdate memory) {
348321
return _latestQuorumUpdate(quorumNumber);
349322
}
350323

351-
/// @notice Returns the most recent OperatorUpdate entry for the specified quorumNumber and operatorIndex
352-
/// @dev Reverts if there is no update for the given operatorIndex
324+
/// @inheritdoc IIndexRegistry
353325
function getLatestOperatorUpdate(
354326
uint8 quorumNumber,
355327
uint32 operatorIndex
356328
) external view returns (OperatorUpdate memory) {
357329
return _latestOperatorIndexUpdate(quorumNumber, operatorIndex);
358330
}
359331

360-
/// @notice Returns an ordered list of operators of the services for the given `quorumNumber` at the given `blockNumber`
332+
/// @inheritdoc IIndexRegistry
361333
function getOperatorListAtBlockNumber(
362334
uint8 quorumNumber,
363335
uint32 blockNumber
@@ -371,8 +343,7 @@ contract IndexRegistry is IndexRegistryStorage {
371343
return operatorList;
372344
}
373345

374-
/// @notice Returns the total number of operators for a given `quorumNumber`
375-
/// @dev This will revert if the quorum does not exist
346+
/// @inheritdoc IIndexRegistry
376347
function totalOperatorsForQuorum(
377348
uint8 quorumNumber
378349
) external view returns (uint32) {

‎src/interfaces/IIndexRegistry.sol

Lines changed: 108 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -4,116 +4,153 @@ pragma solidity ^0.8.27;
44
import {IRegistry} from "./IRegistry.sol";
55

66
interface IIndexRegistryErrors {
7-
/// @dev Thrown when a function is called by an address that is not the RegistryCoordinator
7+
/// @notice Thrown when a function is called by an address that is not the RegistryCoordinator.
88
error OnlyRegistryCoordinator();
9-
/// @dev Thrown when a quorum has 0 length history and thus does not exist
9+
/// @notice Thrown when attempting to query a quorum that has no history.
1010
error QuorumDoesNotExist();
11-
/// @dev Thrown when an operatorId is not found in the registry at a given block number
11+
/// @notice Thrown when attempting to look up an operator that does not exist at the specified block number.
1212
error OperatorIdDoesNotExist();
1313
}
1414

15-
/**
16-
* @title Interface for a `Registry`-type contract that keeps track of an ordered list of operators for up to 256 quorums.
17-
* @author Layr Labs, Inc.
18-
*/
19-
interface IIndexRegistry is IRegistry, IIndexRegistryErrors {
20-
// EVENTS
21-
22-
// emitted when an operator's index in the ordered operator list for the quorum with number `quorumNumber` is updated
23-
event QuorumIndexUpdate(
24-
bytes32 indexed operatorId, uint8 quorumNumber, uint32 newOperatorIndex
25-
);
26-
27-
// DATA STRUCTURES
28-
29-
// struct used to give definitive ordering to operators at each blockNumber.
15+
interface IIndexRegistryTypes {
16+
/// @notice Represents an update to an operator's status at a specific index.
17+
/// @param fromBlockNumber The block number from which this update takes effect.
18+
/// @param operatorId The unique identifier of the operator.
3019
struct OperatorUpdate {
31-
// blockNumber number from which `operatorIndex` was the operators index
32-
// the operator's index is the first entry such that `blockNumber >= entry.fromBlockNumber`
3320
uint32 fromBlockNumber;
34-
// the operator at this index
3521
bytes32 operatorId;
3622
}
3723

38-
// struct used to denote the number of operators in a quorum at a given blockNumber
24+
/// @notice Represents an update to the total number of operators in a quorum.
25+
/// @param fromBlockNumber The block number from which this update takes effect.
26+
/// @param numOperators The total number of operators after the update.
3927
struct QuorumUpdate {
40-
// The total number of operators at a `blockNumber` is the first entry such that `blockNumber >= entry.fromBlockNumber`
4128
uint32 fromBlockNumber;
42-
// The number of operators at `fromBlockNumber`
4329
uint32 numOperators;
4430
}
31+
}
32+
33+
interface IIndexRegistryEvents is IIndexRegistryTypes {
34+
/// @notice Emitted when an operator's index in a quorum is updated.
35+
/// @param operatorId The unique identifier of the operator.
36+
/// @param quorumNumber The identifier of the quorum.
37+
/// @param newOperatorIndex The new index assigned to the operator.
38+
event QuorumIndexUpdate(
39+
bytes32 indexed operatorId,
40+
uint8 quorumNumber,
41+
uint32 newOperatorIndex
42+
);
43+
}
4544

46-
/**
47-
* @notice Registers the operator with the specified `operatorId` for the quorums specified by `quorumNumbers`.
48-
* @param operatorId is the id of the operator that is being registered
49-
* @param quorumNumbers is the quorum numbers the operator is registered for
50-
* @return numOperatorsPerQuorum is a list of the number of operators (including the registering operator) in each of the quorums the operator is registered for
51-
* @dev access restricted to the RegistryCoordinator
52-
* @dev Preconditions (these are assumed, not validated in this contract):
53-
* 1) `quorumNumbers` has no duplicates
54-
* 2) `quorumNumbers.length` != 0
55-
* 3) `quorumNumbers` is ordered in ascending order
56-
* 4) the operator is not already registered
57-
*/
45+
interface IIndexRegistry is IRegistry, IIndexRegistryErrors, IIndexRegistryEvents {
46+
/// @notice Returns the special identifier used to indicate a non-existent operator.
47+
/// @return The bytes32 constant OPERATOR_DOES_NOT_EXIST_ID.
48+
function OPERATOR_DOES_NOT_EXIST_ID() external pure returns (bytes32);
49+
50+
/// @notice Returns the address of the RegistryCoordinator contract.
51+
/// @return The address of the RegistryCoordinator.
52+
function registryCoordinator() external view returns (address);
53+
54+
/// @notice Returns the current index of an operator with ID `operatorId` in quorum `quorumNumber`.
55+
/// @dev This mapping is NOT updated when an operator is deregistered,
56+
/// so it's possible that an index retrieved from this mapping is inaccurate.
57+
/// If you're querying for an operator that might be deregistered, ALWAYS
58+
/// check this index against the latest `_operatorIndexHistory` entry.
59+
/// @param quorumNumber The identifier of the quorum.
60+
/// @param operatorId The unique identifier of the operator.
61+
/// @return The current index of the operator.
62+
function currentOperatorIndex(uint8 quorumNumber, bytes32 operatorId)
63+
external
64+
view
65+
returns (uint32);
66+
67+
// ACTIONS
68+
69+
/// @notice Registers the operator with the specified `operatorId` for the quorums specified by `quorumNumbers`.
70+
/// @param operatorId The unique identifier of the operator.
71+
/// @param quorumNumbers The quorum numbers to register for.
72+
/// @return An array containing the updated number of operators per quorum.
73+
/// @dev Access restricted to the RegistryCoordinator.
74+
/// @dev Preconditions:
75+
/// 1) `quorumNumbers` has no duplicates
76+
/// 2) `quorumNumbers.length` != 0
77+
/// 3) `quorumNumbers` is ordered in ascending order
78+
/// 4) the operator is not already registered
5879
function registerOperator(
5980
bytes32 operatorId,
6081
bytes calldata quorumNumbers
6182
) external returns (uint32[] memory);
6283

63-
/**
64-
* @notice Deregisters the operator with the specified `operatorId` for the quorums specified by `quorumNumbers`.
65-
* @param operatorId is the id of the operator that is being deregistered
66-
* @param quorumNumbers is the quorum numbers the operator is deregistered for
67-
* @dev access restricted to the RegistryCoordinator
68-
* @dev Preconditions (these are assumed, not validated in this contract):
69-
* 1) `quorumNumbers` has no duplicates
70-
* 2) `quorumNumbers.length` != 0
71-
* 3) `quorumNumbers` is ordered in ascending order
72-
* 4) the operator is not already deregistered
73-
* 5) `quorumNumbers` is a subset of the quorumNumbers that the operator is registered for
74-
*/
75-
function deregisterOperator(bytes32 operatorId, bytes calldata quorumNumbers) external;
76-
77-
/**
78-
* @notice Initialize a quorum by pushing its first quorum update
79-
* @param quorumNumber The number of the new quorum
80-
*/
81-
function initializeQuorum(
82-
uint8 quorumNumber
84+
/// @notice Deregisters the operator with the specified `operatorId` for the quorums specified by `quorumNumbers`.
85+
/// @param operatorId The unique identifier of the operator.
86+
/// @param quorumNumbers The quorum numbers to deregister from.
87+
/// @dev Access restricted to the RegistryCoordinator.
88+
/// @dev Preconditions:
89+
/// 1) `quorumNumbers` has no duplicates
90+
/// 2) `quorumNumbers.length` != 0
91+
/// 3) `quorumNumbers` is ordered in ascending order
92+
/// 4) the operator is not already deregistered
93+
/// 5) `quorumNumbers` is a subset of the quorumNumbers that the operator is registered for
94+
function deregisterOperator(
95+
bytes32 operatorId,
96+
bytes calldata quorumNumbers
8397
) external;
8498

85-
/// @notice Returns the OperatorUpdate entry for the specified `operatorIndex` and `quorumNumber` at the specified `arrayIndex`
99+
/// @notice Initializes a new quorum `quorumNumber`.
100+
/// @param quorumNumber The identifier of the quorum to initialize.
101+
function initializeQuorum(uint8 quorumNumber) external;
102+
103+
// VIEW
104+
105+
/// @notice Returns the operator update at index `arrayIndex` for operator at index `operatorIndex` in quorum `quorumNumber`.
106+
/// @param quorumNumber The identifier of the quorum.
107+
/// @param operatorIndex The index of the operator.
108+
/// @param arrayIndex The index in the update history.
109+
/// @return The operator update entry.
86110
function getOperatorUpdateAtIndex(
87111
uint8 quorumNumber,
88112
uint32 operatorIndex,
89113
uint32 arrayIndex
90114
) external view returns (OperatorUpdate memory);
91115

92-
/// @notice Returns the QuorumUpdate entry for the specified `quorumNumber` at the specified `quorumIndex`
116+
/// @notice Returns the quorum update at index `quorumIndex` for quorum `quorumNumber`.
117+
/// @param quorumNumber The identifier of the quorum.
118+
/// @param quorumIndex The index in the quorum's update history.
119+
/// @return The quorum update entry.
93120
function getQuorumUpdateAtIndex(
94121
uint8 quorumNumber,
95122
uint32 quorumIndex
96123
) external view returns (QuorumUpdate memory);
97124

98-
/// @notice Returns the most recent OperatorUpdate entry for the specified quorumNumber and operatorIndex
99-
function getLatestOperatorUpdate(
100-
uint8 quorumNumber,
101-
uint32 operatorIndex
102-
) external view returns (OperatorUpdate memory);
103-
104-
/// @notice Returns the most recent QuorumUpdate entry for the specified quorumNumber
125+
/// @notice Returns the latest quorum update for quorum `quorumNumber`.
126+
/// @param quorumNumber The identifier of the quorum.
127+
/// @return The most recent quorum update.
105128
function getLatestQuorumUpdate(
106129
uint8 quorumNumber
107130
) external view returns (QuorumUpdate memory);
108131

109-
/// @notice Returns the current number of operators of this service for `quorumNumber`.
110-
function totalOperatorsForQuorum(
111-
uint8 quorumNumber
112-
) external view returns (uint32);
132+
/// @notice Returns the latest operator update for operator at index `operatorIndex` in quorum `quorumNumber`.
133+
/// @param quorumNumber The identifier of the quorum.
134+
/// @param operatorIndex The index of the operator.
135+
/// @return The most recent operator update.
136+
function getLatestOperatorUpdate(
137+
uint8 quorumNumber,
138+
uint32 operatorIndex
139+
) external view returns (OperatorUpdate memory);
113140

114-
/// @notice Returns an ordered list of operators of the services for the given `quorumNumber` at the given `blockNumber`
141+
/// @notice Returns the list of operators in quorum `quorumNumber` at block `blockNumber`.
142+
/// @param quorumNumber The identifier of the quorum.
143+
/// @param blockNumber The block number to query.
144+
/// @return An array of operator IDs.
115145
function getOperatorListAtBlockNumber(
116146
uint8 quorumNumber,
117147
uint32 blockNumber
118148
) external view returns (bytes32[] memory);
119-
}
149+
150+
/// @notice Returns the total number of operators in quorum `quorumNumber`.
151+
/// @param quorumNumber The identifier of the quorum.
152+
/// @return The total number of operators.
153+
function totalOperatorsForQuorum(
154+
uint8 quorumNumber
155+
) external view returns (uint32);
156+
}

‎test/unit/IndexRegistryUnit.t.sol

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ pragma solidity ^0.8.27;
44
import "../../src/interfaces/IIndexRegistry.sol";
55
import "../../src/IndexRegistry.sol";
66
import "../harnesses/BitmapUtilsWrapper.sol";
7-
import {IIndexRegistryEvents} from "../events/IIndexRegistryEvents.sol";
7+
import {IIndexRegistryEvents} from "../../src/interfaces/IIndexRegistry.sol";
88

99
import "../utils/MockAVSDeployer.sol";
1010

0 commit comments

Comments
 (0)