KIP 277: Self Validator Registration

Abstract

Introduce a self validator registration process that accepts validator-initiated requests (onboarding, offboarding, add/remove staking contracts) and validates request data under strict invariants. Upon explicitly approved by the Kaia team, it’ll register the validator information to corresponding smart contracts. This KIP won’t bring any changes to the existing smart contracts, such as AddressBook and SimpleBlsRegistry.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Terminology

Adding a new staking contract requires a unique Node ID to be assigned, so a validator needs to assign multiple node IDs to the multiple staking contracts. But among all node IDs, only one node ID will be participating in the consensus and other node IDs will be dummy addresses. In this KIP, we call the node ID that participates in the consensus as Consensus Node ID and the other node IDs as Node IDs.

ValidatorManager

A new ValidatorManager smart contract (VMC for short) is introduced, which implements the self registration processes for validators. The possible requests are:

1. Onboarding: Request to register a new validator to AddressBook and SimpleBlsRegistry.
2. Offboarding: Request to unregister a validator from AddressBook and SimpleBlsRegistry.
3. AddStakingContract: Request to add a new staking contract to a AddressBook.
4. RemoveStakingContract: Request to remove a staking contract from a AddressBook.

When onboarding/adding a new staking contract, the StakingContract MUST be CnStakingV3 introduced by KIP-163.

The VMC must implement the IValidatorManager interface.

interface IValidatorManager {
    enum RequestType {
        NoRequest,
        Onboarding,
        Offboarding,
        AddStakingContract,
        RemoveStakingContract
    }

    struct OnboardingRequest {
        address manager;
        address consensusNodeId;
        address stakingContract;
        address rewardAddress;
        IKIP113.BlsPublicKeyInfo blsPublicKeyInfo;
    }

    struct Request {
        /// @dev the manager that submitted the request
        address manager;
        /// @dev requestIndex is used to prevent request-replacement attack when approving or rejecting a pending request
        uint256 requestIndex;
        /// @dev the type of request
        RequestType requestType;
        /// @dev the ABI-encoded request data (abi.encode)
        ///  - Onboarding: struct OnboardingRequest
        ///  - Offboarding: N.A. (no request data required)
        ///  - AddStakingContract: (address nodeId, address stakingContract, address rewardAddress)
        ///  - RemoveStakingContract: (address nodeId)
        bytes requestData;
    }

    /// @notice Request a new validator onboarding, offboarding, adding a new staking contract, or removing a staking contract
    /// @param consensusNodeId The consensus node id that the request is for
    /// @param requestType The type of request
    /// @param requestData The encoded request data
    /// @dev Callable by validator manager
    /// @dev Note that this only allows to submit one request at a time
    function request(address consensusNodeId, RequestType requestType, bytes memory requestData) external;

    /// @notice Cancel existing request for the given consensus node id
    /// @param consensusNodeId The consensus node id that the request is for
    /// @dev Callable by validator manager
    function cancelRequest(address consensusNodeId) external;

    /// @notice Transfer the validator manager to a new address
    /// @dev Callable by validator manager
    ///      Can't transfer manager if there is a pending request
    function transferManager(address consensusNodeId, address newManager) external;

    /// @notice Approve a request
    /// @dev Callable by owner
    /// @param consensusNodeId The consensus node id that has a request to be approved
    function approveRequest(address consensusNodeId, uint256 requestIndex) external;

    /// @notice Reject request of a validator manager
    /// @dev Callable by owner
    /// @param consensusNodeId The consensus node id that has a request to be rejected
    function rejectRequest(address consensusNodeId, uint256 requestIndex) external;
}

After the activation of VMC, all validators must manage their own registration process through VMC. For onboarding of existing validators, the Kaia team will initially backfill the validator information at the deployment of VMC.

Prerequisites

Since the VMC will execute calls to the AddressBook and SimpleBlsRegistry, the following prerequisites should be satisfied to ensure the execution of requests:

1. VMC is registered as an admin of AddressBook. It can include more than one admin for backup purposes.
2. AddressBook has requirement set to 1.
   • This is required since AddressBook internally implements a multisig mechanism for the admin list.
3. VMC is the owner of SimpleBlsRegistry.

If any of the prerequisites are not met, the VMC MUST revert the request approval. (not prevent request submission)

Self Registration Process

Onboarding

1. Prepare a manager account.
2. Manager deploys a new consensus staking contract (CnStakingV3MultiSig) through the staking factory in Registry.
3. Candidate finishes the initialization of staking contract.
4. Candidate submits an onboarding request to VMC.
5. Kaia team reviews the request.
6. Kaia team approves the request.
   • a. VMC MUST execute AddressBook.submitRegisterCnStakingContract to register the validator information.
   • b. VMC MUST execute SimpleBlsRegistry.register to register the BLS public key information.

Offboarding

1. Manager submits an offboarding request to VMC.
2. Kaia team reviews the request.
3. Kaia team approves the request.
   • a. VMC MUST execute AddressBook.submitUnregisterCnStakingContract to unregister the validator information of staking contracts.
   • b. VMC MUST execute SimpleBlsRegistry.unregister to unregister the BLS public key information.

AddStakingContract

1. Manager deploys a new staking contract through the staking factory in Registry.
2. Validator finishes the initialization of staking contract.
3. Validator submits an add staking contract request to VMC.
4. Kaia team reviews the request.
5. Kaia team approves the request.
   • a. VMC MUST execute AddressBook.submitRegisterCnStakingContract to register a new staking contract.

RemoveStakingContract

1. Manager submits a remove staking contract request to VMC.
2. Kaia team reviews the request.
3. Kaia team approves the request.
   • a. VMC MUST execute AddressBook.submitUnregisterCnStakingContract to unregister the staking contract.

Request validation

The VMC MUST implement the following validation rules for each request type and MUST revert for both request submission and approval if any of the rules are not met:

Common Validation Rules

1. Request for ConsensusNodeId MUST be submitted by the corresponding Manager.
   • When onboarding, the Request.manager MUST be msg.sender.
2. Request for ConsensusNodeId can be cancelled by only the Manager that submitted the request.
3. Manager can have only one pending request at a time.
4. Request.requestData MUST be encoded correctly.

Onboarding Request Validation

1. ConsensusNodeId MUST NOT exist in VMC.
2. BlsPublicKeyInfo MUST be valid.
3. ConsensusNodeId MUST have a balance of at least MIN_CONSENSUS_NODE_BALANCE.
4. Node entry MUST be valid.
   • a. ConsensusNodeId MUST NOT exist in AddressBook.
   • b. StakingContract MUST be deployed by the Manager via the registered staking factory.
   • c. StakingContract MUST be initialized.
   • d. StakingContract MUST have nodeId() equal to RequestData.consensusNodeId
   • e. StakingContract MUST have rewardAddress() equal to RequestData.rewardAddress.
   • f. If PublicDelegation is enabled, PublicDelegation MUST be deployed by the StakingContract via the registered public delegation factory.

Offboarding Request Validation

1. ConsensusNodeId MUST exist in VMC.

AddStakingContract Request Validation

1. ConsensusNodeId MUST exist in VMC.
2. NodeId MUST NOT be managed by current Manager.
3. Node entry MUST be valid.
   • a. NodeId MUST NOT exist in AddressBook.
   • b. StakingContract MUST be deployed by the Manager via the registered staking factory.
   • c. StakingContract MUST be initialized.
   • d. StakingContract MUST have nodeId() equal to RequestData.consensusNodeId
   • e. StakingContract MUST have rewardAddress() equal to RequestData.rewardAddress.
4. New staking contract MUST be compatible with the consensus node’s staking contract.
   • a. PublicDelegation MUST NOT be enabled.
   • b. gcId MUST be the same.
   • c. rewardAddress MUST be the same.

RemoveStakingContract Request Validation

1. ConsensusNodeId MUST exist in VMC.
2. NodeId MUST NOT be current ConsensusNodeId.
3. NodeId MUST be managed by current Manager.

Rationale

Maintain existing smart contracts

The AddressBook provides a trusted source of validator information, deployed at 0x0000000000000000000000000000000000000400 since the genesis block. Migrating the existing AddressBook will essentially require a major effort and cost to entire ecosystem. The Kaia team decided to implement VMC, which doesn’t require any changes to the existing smart contracts but can meet all the requirements for the self validator registration process.

Request-Approval flow

Both validators and the Kaia team need time to be aware of the new validator registration process. This Request-Approval flow prevents any accidental or malicious requests from being executed directly without proper review process.

One request at a time

The validator registration process is critical for the network and should be done in a secure and reliable manner. Allowing multiple requests at a time would introduce unnecessary complexity for both validators and network.

Consensus Node ID as a request argument

The request function requires ConsensusNodeId as an argument to explicitly use ConsensusNodeId as a unique identifier of a validator. The Manager is only responsible for sending the request transaction on its ConsensusNodeId, and should not play as a unique identifier for a validator.

Lack of staking amount requirement for onboarding

Currently there’re validators operating multiple staking contracts with different staking amounts. In this case, it’s possible that the staking contract has less than 5M KAIA staked. If a validator has less than 5M KAIA staked in total, the Kaia network automatically demotes the validator and it doesn’t affect to network stability. But in the future permissionless system, it’ll be necessary to introduce strict staking amount requirement for onboarding to prevent any spamming.

No Public Delegation for an additional staking contract

Since AddStakingContract request doesn’t allow PublicDelegation to be enabled, the validator should offboard and onboard again to migrate staking contract to enable PublicDelegation. This is intended to prevent any unintentional reward distribution. We can consider the following scenario:

1. Validator A first has a staking contract with PublicDelegation disabled.
2. Validator A deploys a new staking contract with PublicDelegation enabled.
3. Validator A updates the reward address of existing staking contract to the PublicDelegation address.

Right after (3), all rewards will go to PublicDelegation address, which only tracks the staking amount of new staking contract. If there’s not enough staking amount, than small shareholders will receive massive rewards, which is not intentional.

Backwards Compatibility

CnStakingContract

The VMC contract will be backward compatible with the existing CnStakingContractV2 and CnStakingContractV3, but not compatible with the previous deprecated CnStakingContractV1. Please note that the CnStakingContractV2 compatibility is required for the existing validators (when backfilling the validator information).

Forward Compatibility

Forward compatibility might be considered since self registration process is essential for a permissionless network. During the future progress, the Kaia team is expecting fundamental changes to the existing smart contracts, which means VMC can be deprecated once the new smart contracts are deployed. The Kaia team should provide a proper migration plan for the existing validators and keep the interface compatible with the new smart contracts to ensure seamless transition.

Security Considerations

In an emergency situation which requires instant recovery through direct access to the AddressBook or SimpleBlsRegistry, it can cause state inconsistency between VMC and the AddressBook or SimpleBlsRegistry. In this case, the Kaia team should perform a state recovery process through manual intervention and implement a proper recovery function to ensure the network can recover from the emergency situation.

Reference

• KIP-163
• KIP-113

Copyright

Copyright and related rights waived via CC0.