diff --git a/src/interfaces/IBN254TableCalculator.sol b/src/interfaces/IBN254TableCalculator.sol index 5383bdaf..938fcc63 100644 --- a/src/interfaces/IBN254TableCalculator.sol +++ b/src/interfaces/IBN254TableCalculator.sol @@ -9,19 +9,21 @@ import { interface IBN254TableCalculator is IOperatorTableCalculator, IOperatorTableCalculatorTypes { /** - * @notice calculates the operatorInfos for a given operatorSet - * @param operatorSet the operatorSet to calculate the operator table for - * @return operatorSetInfo the operatorSetInfo for the given operatorSet + * @notice Calculates the BN254 operator table info for a given operatorSet + * @param operatorSet The operatorSet to calculate the operator table for + * @return operatorSetInfo The BN254OperatorSetInfo containing merkle root, aggregate pubkey, and total weights * @dev The output of this function is used by the multichain protocol to transport operator stake weights to destination chains + * @dev This function aggregates operator weights, creates a merkle tree of operator info, and calculates the aggregate BN254 public key */ function calculateOperatorTable( OperatorSet calldata operatorSet ) external view returns (BN254OperatorSetInfo memory operatorSetInfo); /** - * @notice Get the operatorInfos for a given operatorSet - * @param operatorSet the operatorSet to get the operatorInfos for - * @return operatorInfos the operatorInfos for the given operatorSet + * @notice Get the individual operator infos for a given operatorSet + * @param operatorSet The operatorSet to get the operatorInfos for + * @return operatorInfos The array of BN254OperatorInfo structs containing pubkeys and weights for registered operators + * @dev Only returns operators that have registered their BN254 keys with the KeyRegistrar */ function getOperatorInfos( OperatorSet calldata operatorSet diff --git a/src/interfaces/IECDSATableCalculator.sol b/src/interfaces/IECDSATableCalculator.sol index d7f843cf..2db2c747 100644 --- a/src/interfaces/IECDSATableCalculator.sol +++ b/src/interfaces/IECDSATableCalculator.sol @@ -9,10 +9,11 @@ import { interface IECDSATableCalculator is IOperatorTableCalculator, IOperatorTableCalculatorTypes { /** - * @notice calculates the operatorInfos for a given operatorSet - * @param operatorSet the operatorSet to calculate the operator table for - * @return operatorInfos the list of operatorInfos for the given operatorSet + * @notice Calculates the ECDSA operator infos for a given operatorSet + * @param operatorSet The operatorSet to calculate the operator table for + * @return operatorInfos The array of ECDSAOperatorInfo structs containing ECDSA addresses and weights for registered operators * @dev The output of this function is used by the multichain protocol to transport operator stake weights to destination chains + * @dev Only returns operators that have registered their ECDSA keys with the KeyRegistrar and have non-zero stake */ function calculateOperatorTable( OperatorSet calldata operatorSet diff --git a/src/middlewareV2/tableCalculator/BN254TableCalculator.sol b/src/middlewareV2/tableCalculator/BN254TableCalculator.sol index 19e7ce4b..98f70cfa 100644 --- a/src/middlewareV2/tableCalculator/BN254TableCalculator.sol +++ b/src/middlewareV2/tableCalculator/BN254TableCalculator.sol @@ -21,6 +21,13 @@ contract BN254TableCalculator is BN254TableCalculatorBase { /// @notice The default lookahead blocks for the slashable stake lookup uint256 public immutable LOOKAHEAD_BLOCKS; + /** + * @notice Constructor to initialize the BN254TableCalculator + * @param _keyRegistrar The KeyRegistrar contract for managing operator BN254 keys + * @param _allocationManager The AllocationManager contract for operator allocations and slashable stake + * @param _LOOKAHEAD_BLOCKS The number of blocks to look ahead when calculating minimum slashable stake + * @dev The lookahead blocks parameter helps ensure stake calculations account for future slashing events + */ constructor( IKeyRegistrar _keyRegistrar, IAllocationManager _allocationManager, @@ -31,11 +38,14 @@ contract BN254TableCalculator is BN254TableCalculatorBase { } /** - * @notice Get the operator weights for a given operatorSet based on the slashable stake. + * @notice Get the operator weights for a given operatorSet based on the minimum slashable stake. * @param operatorSet The operatorSet to get the weights for - * @return operators The addresses of the operators in the operatorSet + * @return operators The addresses of the operators in the operatorSet with non-zero slashable stake * @return weights The weights for each operator in the operatorSet, this is a 2D array where the first index is the operator * and the second index is the type of weight. In this case its of length 1 and returns the slashable stake for the operatorSet. + * @dev This implementation sums the minimum slashable stake across all strategies for each operator + * @dev Only includes operators with non-zero total slashable stake to optimize gas usage + * @dev The weights array contains only one element per operator representing their total slashable stake */ function _getOperatorWeights( OperatorSet calldata operatorSet diff --git a/src/middlewareV2/tableCalculator/BN254TableCalculatorBase.sol b/src/middlewareV2/tableCalculator/BN254TableCalculatorBase.sol index 13c2d0d6..72edc802 100644 --- a/src/middlewareV2/tableCalculator/BN254TableCalculatorBase.sol +++ b/src/middlewareV2/tableCalculator/BN254TableCalculatorBase.sol @@ -23,6 +23,10 @@ abstract contract BN254TableCalculatorBase is IBN254TableCalculator { /// @notice KeyRegistrar contract for managing operator keys IKeyRegistrar public immutable keyRegistrar; + /** + * @notice Constructor to initialize the BN254TableCalculatorBase + * @param _keyRegistrar The KeyRegistrar contract for managing operator BN254 public keys + */ constructor( IKeyRegistrar _keyRegistrar ) { @@ -68,6 +72,9 @@ abstract contract BN254TableCalculatorBase is IBN254TableCalculator { } /// @inheritdoc IBN254TableCalculator + /** + * @dev Only returns operators that have registered their BN254 keys with the KeyRegistrar + */ function getOperatorInfos( OperatorSet calldata operatorSet ) external view virtual returns (BN254OperatorInfo[] memory) { @@ -109,13 +116,14 @@ abstract contract BN254TableCalculatorBase is IBN254TableCalculator { /** * @notice Calculates the operator table for a given operatorSet, also calculates the aggregate pubkey for the operatorSet * @param operatorSet The operatorSet to calculate the operator table for - * @return operatorSetInfo The operator table for the given operatorSet + * @return operatorSetInfo The BN254OperatorSetInfo containing merkle root, operator count, aggregate pubkey, and total weights * @dev This function: * 1. Gets operator weights from the weight calculator * 2. Collates weights into total weights * 3. Creates a merkle tree of operator info * - assumes that the operator has a registered BN254 key * 4. Calculates the aggregate public key + * @dev Returns empty operator set info if no operators have registered keys or non-zero weights */ function _calculateOperatorTable( OperatorSet calldata operatorSet diff --git a/src/middlewareV2/tableCalculator/ECDSATableCalculator.sol b/src/middlewareV2/tableCalculator/ECDSATableCalculator.sol index 44f2c1c6..e7e658ce 100644 --- a/src/middlewareV2/tableCalculator/ECDSATableCalculator.sol +++ b/src/middlewareV2/tableCalculator/ECDSATableCalculator.sol @@ -21,6 +21,13 @@ contract ECDSATableCalculator is ECDSATableCalculatorBase { /// @notice The default lookahead blocks for the slashable stake lookup uint256 public immutable LOOKAHEAD_BLOCKS; + /** + * @notice Constructor to initialize the ECDSATableCalculator + * @param _keyRegistrar The KeyRegistrar contract for managing operator ECDSA keys + * @param _allocationManager The AllocationManager contract for operator allocations and slashable stake + * @param _LOOKAHEAD_BLOCKS The number of blocks to look ahead when calculating minimum slashable stake + * @dev The lookahead blocks parameter helps ensure stake calculations account for future slashing events + */ constructor( IKeyRegistrar _keyRegistrar, IAllocationManager _allocationManager, @@ -31,11 +38,14 @@ contract ECDSATableCalculator is ECDSATableCalculatorBase { } /** - * @notice Get the operator weights for a given operatorSet based on the slashable stake. + * @notice Get the operator weights for a given operatorSet based on the minimum slashable stake. * @param operatorSet The operatorSet to get the weights for - * @return operators The addresses of the operators in the operatorSet + * @return operators The addresses of the operators in the operatorSet with non-zero slashable stake * @return weights The weights for each operator in the operatorSet, this is a 2D array where the first index is the operator * and the second index is the type of weight. In this case it's of length 1 and returns the slashable stake for the operatorSet. + * @dev This implementation sums the minimum slashable stake across all strategies for each operator + * @dev Only includes operators with non-zero total slashable stake to optimize gas usage + * @dev The weights array contains only one element per operator representing their total slashable stake */ function _getOperatorWeights( OperatorSet calldata operatorSet diff --git a/src/middlewareV2/tableCalculator/ECDSATableCalculatorBase.sol b/src/middlewareV2/tableCalculator/ECDSATableCalculatorBase.sol index 7d365bbf..c9db86b4 100644 --- a/src/middlewareV2/tableCalculator/ECDSATableCalculatorBase.sol +++ b/src/middlewareV2/tableCalculator/ECDSATableCalculatorBase.sol @@ -21,6 +21,10 @@ abstract contract ECDSATableCalculatorBase is IECDSATableCalculator { /// @notice KeyRegistrar contract for managing operator keys IKeyRegistrar public immutable keyRegistrar; + /** + * @notice Constructor to initialize the ECDSATableCalculatorBase + * @param _keyRegistrar The KeyRegistrar contract for managing operator ECDSA public keys + */ constructor( IKeyRegistrar _keyRegistrar ) { @@ -28,6 +32,9 @@ abstract contract ECDSATableCalculatorBase is IECDSATableCalculator { } /// @inheritdoc IECDSATableCalculator + /** + * @dev Only returns operators that have registered their ECDSA keys with the KeyRegistrar and have non-zero stake + */ function calculateOperatorTable( OperatorSet calldata operatorSet ) external view virtual returns (ECDSAOperatorInfo[] memory operatorInfos) { @@ -84,10 +91,11 @@ abstract contract ECDSATableCalculatorBase is IECDSATableCalculator { /** * @notice Calculates the operator table for a given operatorSet * @param operatorSet The operatorSet to calculate the operator table for - * @return operatorInfos The operator table for the given operatorSet + * @return operatorInfos The array of ECDSAOperatorInfo structs for operators with registered ECDSA keys * @dev This function: * 1. Gets operator weights from the weight calculator * 2. Creates ECDSAOperatorInfo structs for each operator with registered ECDSA keys + * @dev Returns empty array if no operators have registered keys or non-zero weights */ function _calculateOperatorTable( OperatorSet calldata operatorSet