IValidatorConfig.sol

// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity >=0.8.13 <0.9.0;

/// @title IValidatorConfig - Validator Config Precompile Interface
/// @notice Interface for managing consensus validators
/// @dev This precompile manages the set of validators that participate in consensus.
///      Validators can update their own information, rotate their identity to a new address,
///      and the owner can manage validator status.
interface IValidatorConfig {
    /// @notice Thrown when caller lacks authorization to perform the requested action
    error Unauthorized();

    /// @notice Thrown when trying to add a validator that already exists
    error ValidatorAlreadyExists();

    /// @notice Thrown when validator is not found
    error ValidatorNotFound();

    /// @notice Thrown when public key is invalid (zero)
    error InvalidPublicKey();

    /// @notice Thrown when inbound address is not in valid host:port format
    /// @param field The field name that failed validation
    /// @param input The invalid input that was provided
    /// @param backtrace Additional error context
    error NotHostPort(string field, string input, string backtrace);

    /// @notice Thrown when outbound address is not in valid ip:port format
    /// @param field The field name that failed validation
    /// @param input The invalid input that was provided
    /// @param backtrace Additional error context
    error NotIpPort(string field, string input, string backtrace);

    /// @notice Validator information
    /// @param publicKey The validator's communication public key
    /// @param active Whether the validator is active in consensus
    /// @param index The validator's index in the validators array
    /// @param validatorAddress The validator's address
    /// @param inboundAddress Address where other validators can connect to this validator (format: `<hostname|ip>:<port>`)
    /// @param outboundAddress IP address for firewall whitelisting by other validators (format: `<ip>:<port>`)
    struct Validator {
        bytes32 publicKey;
        bool active;
        uint64 index;
        address validatorAddress;
        string inboundAddress;
        string outboundAddress;
    }

    /// @notice Get the total number of validators
    /// @return The number of validators
    function validatorCount() external view returns (uint64);

    /// @notice Get validator info by address
    /// @param validatorAddress The validator's address
    /// @return publicKey The validator's communication public key
    /// @return active Whether the validator is active
    /// @return index The validator's index
    /// @return addr The validator's address
    /// @return inboundAddress The validator's inbound address
    /// @return outboundAddress The validator's outbound address
    function validators(address validatorAddress)
        external
        view
        returns (
            bytes32 publicKey,
            bool active,
            uint64 index,
            address addr,
            string memory inboundAddress,
            string memory outboundAddress
        );

    /// @notice Get validator address at a given array index
    /// @param index The index in the validators array
    /// @return The validator's address
    function validatorsArray(uint256 index) external view returns (address);

    /// @notice Get the complete set of validators
    /// @return validators Array of all validators with their information
    function getValidators() external view returns (Validator[] memory validators);

    /// @notice Add a new validator (owner only)
    /// @param newValidatorAddress The address of the new validator
    /// @param publicKey The validator's communication public key
    /// @param active Whether the validator should be active
    /// @param inboundAddress The validator's inbound address `<hostname|ip>:<port>` for incoming connections
    /// @param outboundAddress The validator's outbound IP address `<ip>:<port>` for firewall whitelisting (IP only, no hostnames)
    function addValidator(
        address newValidatorAddress,
        bytes32 publicKey,
        bool active,
        string calldata inboundAddress,
        string calldata outboundAddress
    ) external;

    /// @notice Update validator information (only validator)
    /// @param newValidatorAddress The new address for this validator
    /// @param publicKey The validator's new communication public key
    /// @param inboundAddress The validator's inbound address `<hostname|ip>:<port>` for incoming connections
    /// @param outboundAddress The validator's outbound IP address `<ip>:<port>` for firewall whitelisting (IP only, no hostnames)
    function updateValidator(
        address newValidatorAddress,
        bytes32 publicKey,
        string calldata inboundAddress,
        string calldata outboundAddress
    ) external;

    /// @notice Change validator active status (owner only)
    /// @param validator The validator address
    /// @param active Whether the validator should be active
    /// @dev Deprecated: Use changeValidatorStatusByIndex to prevent front-running attacks
    function changeValidatorStatus(address validator, bool active) external;

    /// @notice Change validator active status by index (owner only) - T1+
    /// @param index The validator index in the validators array
    /// @param active Whether the validator should be active
    /// @dev Added in T1 to prevent front-running attacks where a validator changes its address
    function changeValidatorStatusByIndex(uint64 index, bool active) external;

    /// @notice Get the owner of the precompile
    /// @return The owner address
    function owner() external view returns (address);

    /// @notice Change owner
    /// @param newOwner The new owner address
    function changeOwner(address newOwner) external;

    /// @notice Get the epoch at which a fresh DKG ceremony will be triggered
    ///
    /// @return The epoch number, or 0 if no fresh DKG is scheduled. The fresh DKG ceremony runs in epoch N, and epoch N+1 uses the new DKG polynomial.
    function getNextFullDkgCeremony() external view returns (uint64);

    /// @notice Set the epoch at which a fresh DKG ceremony will be triggered (owner only)
    /// @param epoch The epoch in which to run the fresh DKG ceremony. Epoch N runs the ceremony, and epoch N+1 uses the new DKG polynomial.
    function setNextFullDkgCeremony(uint64 epoch) external;
}