By Kian Paimani, Parity Technologies
Nomination Pools Explained
The nomination pools are still in the review process. To see the most up to date code and docs check out the primary feature PR and the extracted slashing logic PR.
Problem
The number of nominators in elections is bounded due to memory constraints in the runtime and offchain context.
Solution
Nomination pools have been designed to alleviate this bottleneck by allowing users (pool members) to pool their funds together and act as a single nominator.
All operations are constant space and time complexity relative to the number of members, eliminating any theoretical upper bound on the quantity of members the system can handle.
The earnings of the pool are split pro rata to a members stake in the bonded pool (and thus APY for members will be the same as if they were a nominator). Importantly, slashes are also applied proportionally to members who may have been actively bonded when a validator committed a slash-able offence.
Key Components
- Bonded Pool: Tracks the distribution of actively staked funds.
- Reward Pool: Tracks rewards earned by actively staked funds.
- Unbonding Sub Pools: Collection of pools at different phases (i.e. eras) of the unbonding lifecycle.
- Members: Accounts that are members of pools.
- Point: A unit of measure for a member’s portion of a pool's funds.
Member Lifecycle
Join a pool
A user delegates funds to a pool by transferring some amount to the pool’s bonded account with the join extrinsic. The pool then increases its bond in the staking system with the new funds. A member is afforded the ability to bond additional funds and rewards as long as they are already actively bonded. Note that a member may only belong to one pool at a time.
To be more specific, when joining a pool, a member transfers some funds to the pool’s account and in return receives some points in the “Bonded pool”.
Claim rewards
The member can claim their portion of any rewards that have accumulated since the previous time they claimed (or in the case that they have never claimed, any rewards that have accumulated since the era after they joined). Rewards are split pro rata among the actively bonded members.
Unbond funds
At any point in time after joining the pool, a member can start the process of exiting by unbonding. The unbond transaction will unbond either all or a portion of the members' funds.
When unbonding, a portion of the member’s points are burnt in the Bonded pool and are moved to a corresponding “Unbonding sub-pool”.
If a member no longer has any points in the bonded pool (i.e. they are fully unbonded), then they can no longer claim rewards. To prevent accidental loss of rewards, all unbond transactions will automatically claim any pending rewards as well.
Withdraw unbonded funds
After unbond has been called and the unbonding duration has passed (e.g. 28 days on Polkadot), a member may withdraw their funds with withdraw_unbonded. Withdrawing effectively ends a member’s relationship with their pool, allowing them to join a different pool if desired.
Limitations
- A member cannot vote with their delegated funds. This can be changed in the future once accounts are afforded the ability to split votes.
- In order for a member to switch pools they must wait for the normal 28 day unbonding process.
- A member cannot partially unbond funds. This functionality may be added in the future. This feature has been added.
Pool Administration
States
- Open: The pool is open to be joined by anyone.
- Blocked: The pool is blocked; no joiners are permitted.
- Destroying: The pool is in the process of being destroyed. Once in this state the pool may never revert to any other state; it can only proceed to being destroyed. All members can be permissionlesly unbonded; this allows the pool to be dismantled regardless of any individual member’s proactivity.
Roles:
- Depositor: Creates the pool and is the initial member. The depositor can only leave the pool once all other members have left. Once they leave by withdrawing, the pool is fully removed from the system.
- Nominator: Can select the validators the pool nominates.
- State-Toggler: Can change the pool’s state and kick (permissionlessly unbond/withdraw) members if the pool is blocked.
- Root: Can change the nominator, state-toggler, or itself. Further, it can perform any of the actions the nominator or state-toggler can.
Pool Lifecycle
Creation 👶
- The depositor calls the create extrinsic, setting the administrative roles and transferring some funds to the pool in order to add themselves as the first member. As stated above, the depositor must always be a member as long as the pool exists; they will be the last member to leave, ensuring they always have some skin in the game.
- The pool’s ‘nominator role’ selects validators with the nominate extrinsic.
Upkeep 🧹
- The nominator can update the pool’s validator selection.
- The state-toggler can update the pool’s state to blocked, then kick members by calling unbond and withdraw_unbonded. (The state can also be toggled back to open).
- The root can change itself, the state-toggler or the nominator at any time.
Destruction ☠️
A pool can be pushed into the “destroying” state via one of:
- The state-toggler sets the pool to “destroying”.
- Any account can set the pool to destroying if over 90% of the pool's active bonded balance has been slashed.
Dismantling a destroying pool:
- When a pool is in ‘destroying’ state, unbond and withdraw_unbonded become permissionless, so anyone can help all the members exit.
- Once the depositor withdraws, no members belong to the pool, and all the pool’s resources are wiped from state.
Slashing
If a pool’s underlying nomination account is slashed by the staking system, then the slash is distributed evenly across the bonded pool and the unbonding pools. To be more specific, the staking system will slash proportionally the active, and the unlocking chunks of the nominator account, except for chunks who’s unlock era is strictly smaller than `slash_era + bonding_duration`. The slash is then reflected in the pools system by mirroring the slash to the active ledger to the bonded pool, and similarly the slash to each unlocking chunk to its corresponding unbonding pool.
NOTE: why the chunks with an unlock era less than “slash_era + bonding_duration” are exempt? Imagine Alice has 40 DOT. She unbonds 10 at era 99, 10 at era 100, and 10 at era 101. Her unlocking eras are therefore 127, 128 and 129.
A slash is then known to happen at era 100.
Assuming a slash defer duration of 27, this slash will be enacted at the beginning of era 128, and Alice can withdraw the first chunk (127), leaving only two chunks (128 and 129) and her active ledger exposed.
But, even if the slash defer duration was 10, and the slash was applied at era 111, the staking system would look at the above condition: since the slash happened at era 100, chunks that will be unlocked before era 128 remain untouched. This means that even in this scenario, the 127 chunk will not get slashed.
In both scenarios, the 10 DOT that are left active remain exposed to slashing.
Thus, any member who either a) was unbonding or b) was actively bonded in the aforementioned range of eras will be affected by the slash. In other words, a member who may have been actively bonded when the offence happened is slashed pro rata based on its stake relative to the total slash amount.
Unbonding pools need to be slashed to ensure all nominators who were in the bonded pool while it was backing a validator that committed an offence are punished. Without these measures a nominator could unbond right after a validator equivocated with no consequences.
This strategy is slightly unfair to members who joined right after the slash, because they get slashed as well, but spares members who unbond. The latter is much more important for security: if a pool's validators are attacking the network, their members need to unbond fast! Avoiding additional slashes gives them an incentive to do that if validators get repeatedly slashed.
Notable Contributors
The staking team would like to highlight the work of a couple external contributors:
- @georgesdib has been on an impressive tear with 20 PRs, contributing, among other things, major refactors to parts of the election code.
- @Doordashcon has contributed 2 PRs, including one that will add the ability for faulty election solution submissions to be challenged.
Thinking about contributing? Look for issues in the Substrate repo with the mentor tag, or the NPoS and Elections project. All successful contributions will get an on-chain tip initiated by the staking team.
Also, if you are interested in contributing long-term, there’s a “Staking / PoS Engineer” position available at Parity Technologies.
Miscellaneous
- The staking team put up a proposal at the beginning of the month to set a minimum bond for setting the intention to validate. However, after putting this up the staking team decided this was not the best approach to determine the electable validators; instead the team is looking into sorting validators by the sum of their self stake + the total stake of all their nominations. See the WIP PR about this.
- A PR was merged that lowered the max electing voters (nominators + validators self vote) in Kusama to 12,500. This number is lower than the equivalent on Polkadot because nominators on Kusama take up more space as they have 24 nominations as opposed to 16 on Polkadot.
- In this Polkadot referendum, the minimum nomination intention threshold was lowered to 10 DOT and the max number of nomination intentions was raised to 50,000. As a reminder, the bags list is now enabled on Polkadot, so while the chain can store a large amount of intentions to nominate, while only the top 22,500 nominators by stake will be electing.
By The Numbers
Confused by the meaning of all these terms? What is “intention”? What is “electing/electable”? Then checkout the February update, in which we explained the new staking terminology.
Polkadot
Kusama