interface-lint

# Interface Lint Format Solidity interface files following EigenLayer's established conventions for organization, documentation, and error code generation. ## Interface Structure Every interface file should contain four interface contracts in this order: 1. **`I{ContractName}Errors`** - All custom errors 2. **`I{ContractName}Types`** - All structs and enums 3. **`I{ContractName}Events`** - All events (inherits Types for struct access) 4. **`I{ContractName}`** - Main interface (inherits Errors and Events) ```solidity // SPDX-License-Identifier: BUSL-1.1 pragma solidity ^0.8.27; // Imports interface I{ContractName}Errors { // All errors with error codes } interface I{ContractName}Types { // All structs and enums } interface I{ContractName}Events is I{ContractName}Types { // All events } interface I{ContractName} is I{ContractName}Errors, I{ContractName}Events { // All function declarations } ``` ## Error Documentation Each error MUST include: 1. `@notice` describing when the error is thrown 2. `@dev Error code: 0x...` with the 4-byte selector from `cast sig` ### Generating Error Codes Use `cast sig` to generate the error code: ```bash cast sig "InvalidOperatorSet()" # Output: 0x7ec5c154 ``` ### Error Format ```solidity interface IContractNameErrors { /// @notice Thrown when the operator set is not valid /// @dev Error code: 0x7ec5c154 error InvalidOperatorSet(); /// @notice Thrown when the chainId is invalid /// @dev Error code: 0x7a47c9a2 error InvalidChainId(); /// @notice Thrown when the key type is not set for the operatorSet /// @dev Error code: 0xe57cacbd /// @dev Additional context about why this is required error KeyTypeNotSet(); } ``` ## Types Documentation Each struct/enum MUST include: 1. `@notice` with a brief description 2. `@param` for each field in structs ```solidity interface IContractNameTypes { /// @notice A per-operatorSet configuration struct /// @param owner the permissioned owner of the OperatorSet /// @param maxStalenessPeriod the maximum staleness period in seconds struct OperatorSetConfig { address owner; uint32 maxStalenessPeriod; } /// @notice Represents the status of an operator's registration /// @param registered Whether the operator is currently registered /// @param slashableUntil Block until which the operator remains slashable struct RegistrationStatus { bool registered; uint32 slashableUntil; } } ``` ## Event Documentation Each event MUST include a singular `@notice` describing when the event is emitted: ```solidity interface IContractNameEvents is IContractNameTypes { /// @notice Emitted when a generation reservation is created event GenerationReservationCreated(OperatorSet operatorSet); /// @notice Emitted when an operator set config is set event OperatorSetConfigSet(OperatorSet operatorSet, OperatorSetConfig config); /// @notice Emitted when a chainID is added to the whitelist event ChainIDAddedToWhitelist(uint256 chainID, address operatorTableUpdater); } ``` ## Function Documentation Each function in the main interface MUST include: 1. `@notice` - What the function does 2. `@param` - Description for each parameter 3. `@return` - Description for each return value (for view functions) 4. `@dev` - Additional context (optional, but include caller requirements) 5. `@dev Reverts for:` - List ALL revert conditions 6. `@dev Emits the following events:` - List ALL events emitted ### Function Documentation Format ```solidity interface IContractName is IContractNameErrors, IContractNameEvents { /// @notice Creates a generation reservation for cross-chain transport /// @param operatorSet the operatorSet to make a reservation for /// @param operatorTableCalculator the calculator contract address /// @param config the config containing owner and staleness period /// @dev msg.sender must be an authorized caller for operatorSet.avs /// @dev Reverts for: /// - CurrentlyPaused: Generation reservations are paused /// - InvalidPermissions: Caller is not authorized /// - InvalidOperatorSet: The operatorSet does not exist /// - GenerationReservationAlreadyExists: Reservation already exists /// - InvalidStalenessPeriod: The maxStalenessPeriod is invalid /// @dev Emits the following events: /// - GenerationReservationCreated: When the reservation is created /// - OperatorTableCalculatorSet: When the calculator is set /// - OperatorSetConfigSet: When the config is set function createGenerationReservation( OperatorSet calldata operatorSet, IOperatorTableCalculator operatorTableCalculator, OperatorSetConfig calldata config ) external; /// @notice Gets the operator set config /// @param operatorSet the operatorSet to query /// @return The OperatorSetConfig for the given operatorSet /// @dev You should check if an operatorSet has an active reservation first function getOperatorSetConfig( OperatorSet memory operatorSet ) external view returns (OperatorSetConfig memory); } ``` ## Revert Conditions Format List each revert condition with the error name and when it occurs: ```solidity /// @dev Reverts for: /// - CurrentlyPaused: Generation reservations are paused /// - InvalidPermissions: Caller is not an authorized caller for operatorSet.avs /// - InvalidOperatorSet: The operatorSet does not exist in the AllocationManager /// - GenerationReservationAlreadyExists: A generation reservation already exists ``` For Ownable errors, use the string format: ```solidity /// @dev Reverts for: /// - "Ownable: caller is not the owner": Caller is not the owner ``` ## Events Emitted Format List each event with a brief description of when it's emitted: ```solidity /// @dev Emits the following events: /// - GenerationReservationCreated: When the reservation is successfully created /// - OperatorTableCalculatorSet: When the calculator is set for the operatorSet /// - OperatorSetConfigSet: When the config is set for the operatorSet ``` ## View Functions View functions typically don't revert (except for input validation) and don't emit events. Document them simpler: ```solidity /// @notice Gets the active generation reservations /// @return An array of operatorSets with active generationReservations function getActiveGenerationReservations() external view returns (OperatorSet[] memory); /// @notice Gets reservations by range for pagination /// @param startIndex the start index of the range, inclusive /// @param endIndex the end index of the range, exclusive /// @return An array of operatorSets in the specified range /// @dev Reverts for: /// - InvalidRange: startIndex is greater than endIndex /// - InvalidEndIndex: endIndex exceeds array length function getActiveGenerationReservationsByRange( uint256 startIndex, uint256 endIndex ) external view returns (OperatorSet[] memory); ``` ## Complete Example Reference: `src/contracts/interfaces/ICrossChainRegistry.sol` This file demonstrates the full pattern with: - Errors interface with `cast sig` error codes - Types interface with documented structs - Events interface inheriting Types - Main interface with full function documentation ## Checklist for Linting an Interface 1. ☐ Split into Errors, Types, Events, and main interface contracts 2. ☐ Errors have `@notice` and `@dev Error code: 0x...` (use `cast sig`) 3. ☐ Types have `@notice` and `@param` for each field 4. ☐ Events have singular `@notice` describing when emitted 5. ☐ Events interface inherits Types interface 6. ☐ Main interface inherits Errors and Events interfaces 7. ☐ Functions have `@notice`, `@param`, and `@return` (for views) 8. ☐ Functions list ALL revert conditions under `@dev Reverts for:` 9. ☐ Functions list ALL events under `@dev Emits the following events:` 10. ☐ View functions document reverts only when they can revert ## Generating All Error Codes To generate error codes for an entire interface: ```bash # For each error in the interface, run: cast sig "ErrorName()" cast sig "ErrorName(uint256)" # Include params if error has them # Example output: # 0x7ec5c154 # InvalidOperatorSet() # 0x7a47c9a2 # InvalidChainId() ``` ## Common Error Patterns | Error | Typical Code | Usage | |-------|--------------|-------| | `InvalidOperatorSet()` | `0x7ec5c154` | OperatorSet doesn't exist | | `InvalidPermissions()` | varies | Caller not authorized | | `InvalidCaller()` | varies | Wrong msg.sender | | `ArrayLengthMismatch()` | `0xa24a13a6` | Input arrays have different lengths |