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
- ConsensusNFT Whitelist To onboard, new validators must obtain a
ConsensusNFT
through Telcoin governance. The ConsensusRegistry contract manages this NFT ledger. - Managing TEL staking mechanisms, such as locking stake for governance-approved validators as well as tracking and distributing (pull-based) rewards for validation services
- Managing the active validator set, autonomously bringing them through pending queues for activation and exit
- 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 viasystem call
, which occurs every epoch. This logic is abstracted into theSystemCallable
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.
-
Validator Registration
- Stake: Validators with a
ConsensusNFT
call thestake()
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 toActive
- Stake: Validators with a
-
Activation
- Epoch Advancement: At the end of each epoch, the
concludeEpoch()
function is system called directly from the client. This function automatically processes thePendingActivation
andPendingExit
queues. Thus, validators in thePendingActivation
(orPendingExit
) state are set toActive
(orExited
) state if their activation (or exit) epoch has been reached by advancing an epoch.
- Epoch Advancement: At the end of each epoch, the
-
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 usingunstake()
- Pending Exit Upon calling
exit()
, the validator’s status is set toPendingExit
, and their exit epoch is recorded to be 2 epochs in the future. The pending queue is handled identically to thePendingActivation
process described above.
- Exit Requests Once active, validators may call the
-
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 thePendingActivation
queue
- Rejoin Requests Once exited, validators may call the
-
Unstaking
- Withdraw Stake: Once in the
Exited
state, validators can call theunstake
function to withdraw their original stake amount along with any accrued rewards. - Once unstaked, a validator can no longer
rejoin()
, as theirConsensusNFT
is burned and their validator is set toUNSTAKED
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 newConsensusNFT
- Withdraw Stake: Once in the