Whitelist Contract
Lesson 1
The purpose of this contract is to maintain the whitelist of all the staking pool contract account IDs and staking pool factory account IDs. Note that the NEAR Foundation approves all staking pool factory contract IDs and those contracts are then able to whitelist individual staking pool contract accounts.
Staking in 20 Seconds...
How Delegators, Validators, Staking Pool Contract, and the NEAR Foundation interact
NEAR Protocol uses Proof-of-Stake (PoS) to secure its blockchain. Validators are node operators that take care of blockchain consensus (aggregate transactions into blocks, execute them, and maintain state of the blockchain).
Validators get rewards at the end of each epoch (~12hrs) for doing this. Validators stake a certain amount of tokens as collateral against dishonest behaviour. If they screw up intentionally or otherwise, their stake gets slashed (bit by bit).
The amount they have staked determines the amount of rewards they receive. One way validators can increase their stake is by asking people to delegate tokens in return for a proportionate reward. Delegators lock their funds into a staking pool, receive rewards at the end of each epoch (less a fee paid to the validator).
In order for the lockup contracts to be able delegate to a staking pool, the staking pool should faithfully implement the spec. The staking pool should guarantee that the delegated tokens can not be lost or locked. The lockup contract should be able to recover delegated tokens back to the lockup from a staking pool. In order to enforce this, only approved (whitelisted) accounts of staking pool contracts can receive delegated tokens from lockup contracts.
If NEAR Foundation has to approve every single staking pool account it might lead to a bottleneck and centralization To address this NEAR Foundation can whitelist the account IDs of staking pool factory contracts.
The whitelisted staking pool factory contract will be able to whitelist accounts of staking pool contracts. A factory contract creates and initializes a staking pool contract in a secure and permission less way. This allows anyone on the network to be able to create a staking pool contract (account) for themselves without needing approval from the NEAR Foundation. This is important to maintain the decentralization of the decision making and network governance.
To be able to address mistakes, NEAR Foundation has the ability to remove staking pools and staking pool factories from the whitelists.
Requirements and Guarantees
- The account of the whitelist contract should not contain any access keys, to avoid it from being deleted.
- If the account runs out of tokens for storage, any account can fund it. In theory the gas rebates may cover the storage in the long term.
is_whitelistedcall doesn't panic, unless it's given insufficient amount of gas or the invalid account ID.- The contract maintains two separate whitelists, one for staking pools and one for factories.
API
The methods are split into:
- getters (view methods)
- methods that can be called by both an approved factory and the foundation; and
- methods that can only be called by the foundation.
Whitelist Contract Walkthrough
You can find all the code talked about here in its Github Repo.