Validator Onboarding & Staking: ConsensusRegistry

[robriks]

Onchain validator onboarding, voter committee, epoch storage, and staking

In fleshing out Telcoin Network’s consensus mechanisms, it became apparent that a single source of truth is needed for nodes to agree on the network’s validators, voting committee, epoch information, and staking information. Several discussions led us to converge on using an onchain smart contract for these items, because the execution layer provides canonical shared state across nodes.

Roles

1. ConsensusNFT Whitelist To onboard, new validators must obtain a ConsensusNFT through Telcoin governance. The ConsensusRegistry contract manages this NFT ledger.
2. Managing TEL staking mechanisms, such as locking stake for governance-approved validators as well as tracking and distributing (pull-based) rewards for validation services
3. Managing the active validator set, autonomously bringing them through pending queues for activation and exit
4. Storing historical epoch information which includes epoch block heights and voting validator committees. Voter committees are predetermined by the protocol and stored two epochs in the future.

To keep this information up to date, the protocol maintains contract state via the use of a system call to ConsensusRegistry::concludeEpoch() at the end of each epoch. This action is what kickstarts the beginning of each new epoch.

Mechanisms

The contract’s most frequent entrypoint: concludeEpoch()

• Finalize Epoch: The concludeEpoch function is responsible for finalizing the previous epoch, updating the validator set, storing new epoch information, and incrementing staking rewards. Rewards may then be claimed by validators at their discretion.

• System Call Context concludeEpoch() may only be called by the client via system call, which occurs every epoch. This logic is abstracted into the SystemCallable module.

ConsensusNFT Whitelist

To join Telcoin Network as a validator, node operators first must be approved by Telcoin governance. Once approved, validators will be issued a ConsensusNFT serving as a permissioned validator whitelist. Only the contract owner, an address managed by Telcoin governance, can issue these NFTs via ConsensusRegistry::mint()

The ERC721 tokenId of each validator’s token corresponds to their validator uid, termed validatorIndex in the registry’s implementation.

Validator Registration and Staking

Once issued a ConsensusNFT, validators may enter the pending activation queue at their discretion by staking a fixed amount of native TEL and providing their public keys via ConsensusRegistry::stake()

Below, we follow the general lifecycle of a new validator in roughly chronological order.

1. Validator Registration

   • Stake: Validators with a ConsensusNFT call the stake() function along with the required stake amount, providing their BLS public key, BLS signature, and ED25519 public key.
   • Pending Activation: Upon successful staking, the validator’s status is set to PendingActivation, and its activation epoch is recorded to be 2 epochs in the future. After awaiting the remainder of the current epoch and then one full epoch, its status will automatically be updated to Active

2. Activation

   • Epoch Advancement: At the end of each epoch, the concludeEpoch() function is system called directly from the client. This function automatically processes the PendingActivation and PendingExit queues. Thus, validators in the PendingActivation (or PendingExit) state are set to Active (or Exited) state if their activation (or exit) epoch has been reached by advancing an epoch.

3. Reversible Exit

   • Exit Requests Once active, validators may call the exit() function to initiate an exit from the network. These exits are reversible and may be used for node maintenance or key rotation. To permanently forgoe validator status, exited validators must then reclaim their stake and burn their ConsensusNFT using unstake()
   • Pending Exit Upon calling exit(), the validator’s status is set to PendingExit, and their exit epoch is recorded to be 2 epochs in the future. The pending queue is handled identically to the PendingActivation process described above.

4. Rejoining

   • Rejoin Requests Once exited, validators may call the rejoin() function to initiate a rejoin request. They may provide new keys if desired.
   • Pending Activation Upon calling rejoin(), the validator will be entered into the PendingActivation queue

5. Unstaking

   • Withdraw Stake: Once in the Exited state, validators can call the unstake function to withdraw their original stake amount along with any accrued rewards.
   • Once unstaked, a validator can no longer rejoin(), as their ConsensusNFT is burned and their validator is set to UNSTAKED state, which is unrecoverable. Should an unstaked validator want to resume validating the network, they must reapply to Telcoin governance and be re-issued a new ConsensusNFT

[robriks]

ConsensusRegistry Contract Integrated into Protocol Genesis

The ConsensusRegistry contract, which handles permissioned validator onboarding, ephemeral storage of voter committees and epoch information, and network staking, has been inserted into Telcoin Network’s genesis on the protocol side. This was a necessary undertaking as the contract must be functional right away at genesis, even before any transactions can be submitted.

1. Integration of ConsensusRegistry Implementation and Proxy Contracts:

The ConsensusRegistry implementation and proxy contract pair are written directly into the genesis configuration as precompiles. This means they are now part of the initial setup of the protocol, including the proxy contract’s storage configurations which are required to ensure smooth operation.

By incorporating these elements into the genesis block, we ensure that our staking and validator onboarding processes are seamlessly integrated and ready to function at network launch to enhance the robustness and reliability of our consensus mechanism from the outset.

2. Design Decisions:

The flexibility offered by a proxy setup is crucial as we approach mainnet because it allows us to adapt to future requirements and changes without significant disruption of testnet. This foresight ensures that our system remains agile and can accommodate evolving needs or optimizations ahead of mainnet launch.

Note that the ConsensusRegistry proxy contract is currently assigned the address 0x07e17e17e17e17e17e17e17e17e17e17e17e17e1. However, this is not set in stone; the proxy address along with the RWTEL module can be modified to any 20byte address of our or the community’s choosing.

3. ConsensusRegistry Storage Requirements:

In order to function at genesis, even before any transactions are submitted to the network, the ConsensusRegistry contract requires certain storage configurations in order to function properly. These include dynamic variables which will not be known until Genesis or shortly before, such as MNO node operator validator ECDSA, ED25519, and BLS pubkeys. As such, using Solidity constants stored in contract bytecode is not possible.

To achieve the above, this integration makes use of a Solidity utility I’ve written called GenerateConsensusRegistryStorage.sol. This utility is instrumental in generating the storage outcomes of the ConsensusRegistry’s initializer, which involves about 80 storage slots, so they can be written programmatically at genesis time.

By using this utility, we generate and assign the required storage slots and their corresponding values to streamline the network launch process and minimizes potential errors from manual configuration.

4. Notes on Mainnet Validator Public Keys:

To accommodate the fact that the initial mainnet validator public keys will only be available at genesis time or shortly before the Solidity utility employs collision-resistant flags to label the output slots. These slots are then identified and populated by the protocol at genesis, when the public keys are known.

A noteworthy benefit of this approach is that Telcoin Network launches will not involve a need to fetch and manually integrate validator pubkeys. This helps smoothen out our transition from preparation, through the planned audit, and to mainnet launch.