feat: add IRegistrar and IValidatorManager interfaces

src/interfaces/IRegistrar.sol

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.0 <0.9.0;
+
+/// @title IRegistrar
+/// @notice Interface for the Registrar contract.
+interface IRegistrar {
+    // =========================================================================
+    // Types
+    // =========================================================================
+
+    /// @notice Storage struct for key-value entries.
+    struct Entry {
+        bytes32 value;
+        uint64 epochFrom; // 0 = genesis value
+    }
+
+    // =========================================================================
+    // Events
+    // =========================================================================
+
+    /// @notice Emitted when a key-value pair is updated.
+    /// @param key The key that was updated.
+    /// @param value The new value associated with the key.
+    /// @param epochFrom The epoch from which the new value is active.
+    event Updated(bytes32 indexed key, bytes32 value, uint64 epochFrom);
+
+    // =========================================================================
+    // Errors
+    // =========================================================================
+
+    /// @notice Error when keys and values arrays have different lengths.
+    error LengthMismatch();
+
+    // =========================================================================
+    // Functions
+    // =========================================================================
+
+    /// @notice Gets the value associated with a key at the current epoch.
+    /// @param key The key to look up.
+    /// @return value The value associated with the key.
+    function get(bytes32 key) external view returns (bytes32 value);
+
+    /// @notice Gets the value associated with a key at the next epoch.
+    /// @param key The key to look up.
+    /// @return value The value associated with the key.
+    function getNext(bytes32 key) external view returns (bytes32 value);
+
+    /// @notice Batch gets the values associated with keys at the current epoch.
+    /// @param keys The keys to look up.
+    /// @return values The values associated with the keys.
+    function batchGet(bytes32[] calldata keys) external view returns (bytes32[] memory values);
+
+    /// @notice Batch gets the values associated with keys at the next epoch.
+    /// @param keys The keys to look up.
+    /// @return values The values associated with the keys.
+    function batchGetNext(bytes32[] calldata keys) external view returns (bytes32[] memory values);
+
+    /// @notice Gets all historical entries for a key.
+    /// @param key The key to look up.
+    /// @return entries The entries associated with the key.
+    function getEntries(bytes32 key) external view returns (Entry[] memory entries);
+
+    /// @notice Sets a key-value pair, applied from the next epoch.
+    /// @param key The key to set.
+    /// @param value The value to set.
+    function set(bytes32 key, bytes32 value) external;
+
+    /// @notice Batch sets key-value pairs, applied from the next epoch.
+    /// @param keys The keys to set.
+    /// @param values The values to set.
+    function batchSet(bytes32[] calldata keys, bytes32[] calldata values) external;
+}

src/interfaces/IValidatorManager.sol

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.0 <0.9.0;
+
+/// @title IValidatorManager
+/// @notice Interface for the Validator Manager contract.
+interface IValidatorManager {
+    // =========================================================================
+    // Types
+    // =========================================================================
+
+    /// @notice Storage struct for validators.
+    struct Validator {
+        uint64 index;
+        uint64 epochAdded; // 0 = genesis validator
+        uint64 epochRemoved; // 0 = active validator
+        uint32 ip;
+        uint16 port;
+        bytes32 publicKey;
+        bytes32 name;
+    }
+
+    /// @notice Return struct for view functions.
+    struct ValidatorInfo {
+        uint64 index;
+        bytes32 publicKey;
+        string name;
+        string socketAddress;
+    }
+
+    /// @notice Input struct for genesis validators.
+    struct GenesisValidator {
+        bytes32 publicKey;
+        bytes32 name;
+        uint32 ip;
+        uint16 port;
+    }
+
+    // =========================================================================
+    // Events
+    // =========================================================================
+
+    /// @notice Emitted when a validator is added.
+    event ValidatorAdded(uint64 indexed index, bytes32 indexed publicKey, string name, uint64 epochAdded);
+
+    /// @notice Emitted when a validator is removed.
+    event ValidatorRemoved(uint64 indexed index, bytes32 indexed publicKey, string name, uint64 epochRemoved);
+
+    // =========================================================================
+    // Errors
+    // =========================================================================
+
+    /// @notice Error when a validator is already added.
+    error ValidatorAlreadyAdded(bytes32 publicKey);
+
+    /// @notice Error when a validator is already removed.
+    error ValidatorAlreadyRemoved(bytes32 publicKey);
+
+    /// @notice Error when a validator does not exist.
+    error ValidatorNotFound(bytes32 publicKey);
+
+    // =========================================================================
+    // Functions
+    // =========================================================================
+
+    /// @notice Adds a new validator to the set, applied from the next epoch.
+    /// @param publicKey The validator's public key.
+    /// @param name The validator's name.
+    /// @param ip The validator's IPv4 address.
+    /// @param port The validator's port.
+    function addValidator(bytes32 publicKey, bytes32 name, uint32 ip, uint16 port) external;
+
+    /// @notice Removes a validator from the set, applied from the next epoch.
+    /// @param publicKey The validator's public key.
+    function removeValidator(bytes32 publicKey) external;
+
+    /// @notice Returns validators active in the current epoch.
+    function getCurrentValidators() external view returns (ValidatorInfo[] memory);
+
+    /// @notice Returns validators that will be active in the next epoch.
+    function getNextValidators() external view returns (ValidatorInfo[] memory);
+
+    /// @notice Returns validators active at a specific epoch.
+    /// @param epoch The epoch number.
+    function getValidatorsAtEpoch(uint64 epoch) external view returns (ValidatorInfo[] memory);
+}