Polkadot Nomination Pools Implementation Guide

A short writeup on implementing Polkadot nomination pools for wallet and application builders in the Polkadot ecosystem.

By Polkadot•October 30, 2022

A short writeup for the Polkadot ecosystem on implementing the newly released nomination pools feature.

What?

Nomination pools are a new type of scaling solution that's being added to Polkadot staking. It mainly targets the stakers who do not have enough DOT to participate actively in the normal staking process, i.e. as a “nominator”. Learn more about pools at the following links:

How?

Pool members have a much simpler API compared to nominators: They join a pool, they can increase or decrease their stake in that pool, and they can claim their rewards whenever they want.

On the other hand, the process of creating and managing a pool is entirely new and we expect that to be the most work heavy part for our ecosystem, wanting to support pools. Nonetheless, you can focus on the “Pool member experience” at first, since most of those who want to manage a pool will be “power users” who can find their way in Polkadot JS Apps or other UIs with rough edges.

Here are some resources to help you with implementation:

Why?

Polkadot’s complicated taking system has been the subject of a lot of community feedback over the last year. A portion of these stakers have already migrated to other staking services. A number of them are nominating on Polkadot, but are not always earning rewards. Therefore, we expect a large number of end users to wish to move back to staking directly on the Relay Chain (as opposed to more centralized services) and pools are exactly the tool for that. This is a great opportunity for the entire ecosystem to help these users achieve this goal, while attracting more users.

We encourage all wallets in our ecosystem to identify nominators who are not earning rewards, and invite them to join nomination pools. See this issue as further information around this.

Common Mistakes / Notes

Here are a few mistakes that we realized over the last few months UI implementers should keep an eye on.

Pool Members

In general, whenever a pool member changes their total point, the chain will automatically claim all their pending rewards for them. This is not optional, and MUST happen for the reward calculation to remain correct (see the documentation of `bond` as an example). So, make sure you are warning your users about it. They might be surprised if they see that they bonded an extra 100 DOT, and now suddenly their 5.23 DOT in pending reward is gone. It is not gone, it has been paid out to you!
Joining a pool implies transferring funds to the pool account. So it might be (based on which wallet that you are using) that you no longer see the funds that are moved to the pool in your “free balance” section. Make sure the user is aware of this, and not surprised by seeing this. Also, the transfer that happens here is configured to to never accidentally destroy the sender account. So to join a pool, your sender account must remain alive with 1 DOT left in it. This means, with 1 DOT as existential deposit, and 1 DOT as minimum to join a pool, you need at least 2 DOT to join a pool. Consequently, if you are suggesting members to join a pool with “Maximum possible value”, you must subtract 1 DOT to remain in the sender account to not accidentally kill it.
Points and balance are not the same! Any pool member, at any point in time, can have points in either the bonded pool or any of the unbonding pools. The crucial fact is that in any of these pools, the ratio of point to balance is different and might not be 1. Each pool starts with a ratio of 1, but as time goes on, for reasons such as slashing, the ratio gets broken. Over time, 100 points in a bonded pool can be worth 90 DOT. Make sure you are either representing points as points (not as DOT), or even better, always display both: “You have x points in pool y which is worth z DOT”. See here and here for examples of how to calculate point to balance ratio of each pool (it is almost trivial ;))

Pool Management

The pool will be seen from the perspective of the rest of the system as a single nominator. Ergo, this nominator must always respect the `staking.minNominatorBond` limit. Similar to a normal nominator, who has to first `chill` before fully unbonding, the pool must also do the same. The pool’s bonded account will be fully unbonded only when the depositor wants to leave and dismantle the pool. All that said, the message is: the depositor can only leave the chain when they chill the pool first.