diff --git a/KIPs/kip-290.md b/KIPs/kip-290.md index d221085..e08e12b 100644 --- a/KIPs/kip-290.md +++ b/KIPs/kip-290.md @@ -84,6 +84,8 @@ struct NodeInfo { uint256 gcId; /// @dev BLS public key and proof-of-possession (immutable) BlsPublicKeyInfo blsInfo; + /// @dev Human-readable node name (mutable) + string name; /// @dev Validator metadata in JSON format (mutable) string metadata; /// @dev Current state of the node @@ -118,9 +120,10 @@ enum State { The `metadata` field in `NodeInfo` is a JSON-encoded string. All fields are optional. Unrecognized fields SHOULD be ignored by readers. +> **Note**: The node operator name is stored as the top-level `name` field in `NodeInfo` (a required parameter of `createNode`), not inside `metadata`. + | Field | Type | Description | | ------------- | -------- | ---------------------------------- | -| `name` | string | Human-readable node operator name | | `thumbnail` | string | URL to operator thumbnail/logo | | `summary` | string | Short description | | `description` | string | Long description | @@ -132,7 +135,6 @@ Example: ```json { - "name": "Kaia Foundation", "thumbnail": "https://cdn.prod.website-files.com/66a8ba5239a3fbe8e678da2a/69866193d03bf54b81aa0283_66ce395e60f880698890073dcc91fa28_kaia-logo.svg", "summary": "The organization behind the Kaia blockchain.", "description": "The Kaia Foundation is the organization behind the Kaia blockchain, an EVM-compatible Layer 1 built for stablecoin settlement and onchain finance across Asia.", @@ -144,7 +146,7 @@ Example: #### Interface -AddressBookV2 replaces the existing AddressBook at `0x0000000000000000000000000000000000000400` starting from `FORK_BLOCK`. The interface is divided into user functions (called by node manager), system functions (called by core client via system transaction following [EIP-4788](https://eips.ethereum.org/EIPS/eip-4788) convention), and admin functions (called by contract owner). +AddressBookV2 replaces the existing AddressBook at `0x0000000000000000000000000000000000000400` starting from `FORK_BLOCK`. The interface is divided into user functions (called by node manager), system functions (called by core client via system transaction following [EIP-4788](https://eips.ethereum.org/EIPS/eip-4788) convention), and admin functions (called by contract owner or designated roles). ```solidity pragma solidity ^0.8.0; @@ -152,19 +154,45 @@ pragma solidity ^0.8.0; import {State, BlsPublicKeyInfo, NodeInfo, Profile} from "./types/Node.sol"; interface IAddressBookV2 { + // ── Errors ── + error OnlySuspender(); + error OnlyConfigurator(); + error InvalidState(); + error SlotsFull(); + error InvalidInput(); + error StakingTooLow(); + error NodeAlreadyExists(); + error NodeNotFound(); + error TimeoutExpired(); + error AlreadySuspended(); + error NotSuspended(); + error PDEnabled(); + error InsufficientNodeBalance(); + error GcIdAlreadyAssigned(); + error GcIdNotAssigned(); + // ── Events ── event StateChanged(address indexed nodeId, State indexed fromState, State indexed toState); - event NodeCreated(address indexed nodeId, uint256 gcId); + event NodeCreated(address indexed nodeId); + event GcIdAssigned(address indexed nodeId, uint256 gcId); event NodeDeleted(address indexed nodeId); + event ValidatorSuspended(address indexed nodeId); + event ValidatorUnsuspended(address indexed nodeId); + event CandidateReadied(address indexed nodeId); + event CandidateUnreadied(address indexed nodeId); + event ValidatorsInitialized(address[] nodeIds); event SystemTransitionProcessed(address[] nodeIds, State[] newStates); event EpochTransitionProcessed(uint256 epochVACount); + event UintConfigUpdated(uint8 indexed configId, uint256 oldValue, uint256 newValue); + event AddressConfigUpdated(uint8 indexed configId, address oldValue, address newValue); // ── User Functions (called by node manager) ── - /// @notice Register a new node in Registered state + /// @notice Register a new node in Registered state; name must be non-empty function createNode( address nodeId, address stakingContract, address rewardAddress, - address voterAddress, BlsPublicKeyInfo memory blsInfo, string memory metadata + address voterAddress, BlsPublicKeyInfo memory blsInfo, + string memory name, string memory metadata ) external; /// @notice Remove a Registered node entirely @@ -207,10 +235,21 @@ interface IAddressBookV2 { uint256 epochVACount ) external; - // ── Admin Functions (called by contract owner) ── + // ── Admin Functions ── + /// @notice Emergency suspension (called by suspender) function suspendValidator(address nodeId) external; + /// @notice Lift suspension (called by suspender) function unsuspendValidator(address nodeId) external; + /// @notice Update suspender address (called by owner) + function updateSuspender(address newSuspender) external; + /// @notice Update configurator address (called by owner) + function updateConfigurator(address newConfigurator) external; + /// @notice Assign auto-incremented gcId to a node (called by configurator) + function assignGcId(address nodeId) external; + /// @notice Revoke gcId from a node, setting it back to 0 (called by configurator) + function revokeGcId(address nodeId) external; + function updatePauseTimeout(uint256 newPauseTimeout) external; function updateIdleTimeout(uint256 newIdleTimeout) external; function updateMaxNodeCount(uint256 newMaxNodeCount) external; @@ -221,6 +260,8 @@ interface IAddressBookV2 { // ── Getters ── + function getSuspender() external view returns (address); + function getConfigurator() external view returns (address); function getNodeInfo(address nodeId) external view returns (NodeInfo memory); function getNodeInfos(address[] calldata nodeIds) external view returns (NodeInfo[] memory); function getAllProfiles() external view returns (Profile[] memory);