Update Staking Docs - Bags-list

docs/learn/learn-nominator.md

@@ -49,18 +49,91 @@ nomination. However, the election algorithm attempts to minimize this situation,
 occur often, so you should almost always see only a single active nomination per era. See the
 [section on Phragmén optimization](learn-phragmen.md#optimizations) for more details.
 
+### Bags-list
+
+Nominating accounts are placed in a semi-sorted list called bags-list. This sorting functionality is
+extremely important for the
+[long-term improvements](https://gist.github.com/kianenigma/aa835946455b9a3f167821b9d05ba376) of the
+staking/election system. Bags-list allows up to 50,000 nominators to set their _intention_ to
+nominate, of which, the stake of the top 22,500 nominators is considered for elections that
+eventually determine the active validators. The bags-list can be previewed on
+[Polkadot JS Apps > Network > Staking > Bags > All Bags](https://polkadot.js.org/apps/#/staking/bags).
+
+![Bags list](../assets/staking/bags-list.png)
+
+:::info Minimum DOT required to earn staking rewards
+
+Minimum DOT required to submit intent to nominate is 10 DOT, but the minimum active nomination
+required to earn staking rewards is dynamic and may be much higher, which can be viewed on
+[Polkadot JS Apps > Network > Staking > Targets page](https://polkadot.js.org/apps/#/staking/targets).
+
+:::
+
+![Minimum Active Nomination](../assets/staking/min-active-nomination.png)
+
+Bonding additional tokens or unbonding the staked tokens will automatically place the nominating
+account in the appropriate bag. While the system tries its best to ensure nominators are always
+represented in the correct bag, certain changes in bonded funds (e.g. a slash in the negative
+direction, or rewards in the positive direction) can cause an account to be in the wrong bag, and
+for scalability reasons the system will not automatically self-adjust.
+
+:::caution `bagsList.putInFrontOf` and `bagsList.rebag` extrinsics
+
+The nominator accounts in a bag are sorted based on their insertion order, not by their nomination
+stake. `bagsList.putInFrontOf` extrinsic can be issued to move up in the bag, which might be very
+useful for the accounts in the last bag eligible for receiving staking rewards. Also, balance
+changes due to staking rewards or slashing do not automatically re-bag the account. Whenever
+applicable, Polkadot JS Apps UI prompts the nominator account to rebag or move-up and the
+instructions are available in this
+[support article](https://support.polkadot.network/support/solutions/articles/65000181018-i-have-more-than-the-minimum-bonded-but-i-m-not-getting-rewards).
+
+:::
+
+To demonstrate how bags-list works, let's imagine a simple bag system with 7 accounts and 3 bags:
+
+Alice: 10 DOT, Bob: 11 DOT, Charlie: 15 DOT, Dave: 20 DOT, Eve: 100 DOT, Frank 1000 DOT, Georgina:
+2000 DOT
+
+Bag1: Max 2000, Min 1000 - Frank, Georgina
+
+Bag2: Max 1000, Min 20 - Eve, Dave
+
+Bag3: Max 20, Min 10 - Alice, Bob, Charlie
+
+The bags are iterated based on _insertion_ order, not _amount at stake_. So if only five nominating
+accounts are picked for the electing set, it will be Frank, Georgina, Eve, Dave, Alice. Even though
+Alice has only 10 DOT, she is first in line in Bag3.
+
+Charlie can put himself in front (move up in the bag) using the , since he has 15 DOT (more than
+Alice does at 10). Now if nothing changes for the next era, Frank, Georgina, Eve, Dave, and Charlie
+will get rewards. Bag3 now has: Charlie, Alice, Bob. The `bagsList.putInFrontOf` extrinsic can be
+issued through Polkadot JS Apps UI by clicking on the Move up button.
+
+![PutInFrontOf Extrinsic](../assets/staking/put-infront-of.png)
+
+Alice gets upset, but she cannot move herself up, since Charlie has more DOT than her. Bob _could_
+move himself in front of Alice, since he has 11 DOT (> 10), but he still wouldn't get rewards.
+
+Let us consider a hypothetical scenario where Charlie set the staking rewards to be bonded
+automatically and Charlie's stash crosses 20 DOT after rewards from several staking eras. As changes
+in bonded balance due to staking rewards or slashing do not automatically re-bag the account,
+Charlie has to issue `bagsList.rebag` extrinsic to place his nominator node in the right bag. The
+re-bag button will appear on Polkadot JS Apps UI if any of the nominator nodes in the bag needs to
+be re-bagged. This permissionless extrinsic can be signed and submitted by anyone on chain.
+
+![Rebag](../assets/staking/rebag.png)
+
 ### Staking Election Stages
 
-The staking election system has 3 stages for both validators and nominators, namely "intention", 
 "electable/electing", and "active".
 
-- **intention to nominate:** an account that has stated the intention to nominate; also called simply 
-a "nominator".
-- **electing nominator:** a nominator who is selected to be a part of the input to the [NPoS election 
-algorithm](learn-phragmen.md). This selection is based on stake, and is done using the 
-[bags-list pallet](https://paritytech.github.io/substrate/master/pallet_bags_list/).
-- **active nominator:** a nominator who came out of the NPoS election algorithm backing an active validator, 
-sharing their rewards (if among the top 256 backers) and slashes.
+- **intention to nominate:** an account that has stated the intention to nominate; also called
+  simply a "nominator".
+- **electing nominator:** a nominator who is selected to be a part of the input to the
+  [NPoS election algorithm](learn-phragmen.md). This selection is based on stake, and is done using
+  the [bags-list pallet](https://paritytech.github.io/substrate/master/pallet_bags_list/).
+- **active nominator:** a nominator who came out of the NPoS election algorithm backing an active
+  validator, sharing their rewards (if among the top 256 backers) and slashes.
 
 ![Nominator Election](../assets/staking/nominator-election.png)
 
@@ -119,8 +192,14 @@ and you are nominating with enough stake to get into the solution set, your bond
 fully distributed to one or more validators. That being said, you may not receive rewards if you
 nominated very few validator candidates and no one got elected, or your stake is small and you only
 selected oversubscribed validators, or the validator you are nominating has 100% commission. It is
-generally wise to choose as many trustworthy validators as you can (up to 16) to reduce the risk of
-none of your nominated validators being elected.
+generally wise to choose as many trustworthy validators as you can (up to {{ polkadot_max_nominations }}) 
+to reduce the risk of none of your nominated validators being elected.
+
+:::info Not receiving Staking Rewards?
+
+To explore the possible reasons for not receiving staking rewards, check out the [Staking FAQ](learn-staking-faq#3-why-am-i-not-receiving-staking-rewards)
+
+:::
 
 Rewards are *lazy* - somebody must trigger a payout for a validator for rewards to go all of the
 validator's nominators. Any account can do this, although in practice validator operators often do

docs/learn/learn-staking.md

@@ -7,19 +7,19 @@ keywords: [staking, stake, nominate, nominating, NPoS]
 slug: ../learn-staking
 ---
 
-Polkadot uses NPoS (Nominated Proof-of-Stake) as its [consensus](learn-consensus.md) mechanism.
-The system encourages DOT holders to participate as nominators. Nominators may back up to 16
-validators as trusted validator candidates. Both validators and nominators lock their tokens as
-collateral and receive staking rewards.
+Polkadot uses NPoS (Nominated Proof-of-Stake) as its [consensus](learn-consensus.md) mechanism. The
+system encourages DOT holders to participate as nominators. Nominators may back up to 16 validators
+as trusted validator candidates. Both validators and nominators lock their tokens as collateral and
+receive staking rewards.
 
 The staking system pays out rewards essentially equally to all validators regardless of stake.
 Having more stake on a validator does not influence the amount of block rewards it receives.
 However, there is a probabilistic component to reward calculation (discussed below), so rewards may
 not be exactly equal for all validators in a given era.
 
-Distribution of the rewards are pro-rata to all stakers after the validator's commission is deducted.
-In this way, the network creates incentives for the nomination of lower-staked validators to create
-an equally-staked validator set.
+Distribution of the rewards are pro-rata to all stakers after the validator's commission is
+deducted. In this way, the network creates incentives for the nomination of lower-staked validators
+to create an equally-staked validator set.
 
 ## How does staking work in Polkadot?
 
@@ -29,35 +29,91 @@ In staking, you can be either a [nominator or a validator](#validators-and-nomin
 
 As a nominator, you can nominate validator candidates that you trust to help you earn rewards in the
 chain's native token. The earned rewards can be bonded (locked) immediately for staking on your
-account, which would effectively compound the rewards you receive over time. You could also choose 
-to have them deposited to your account or a different account as free (transferable) balance. You can 
-take a look at the [nominator guide](learn-nominator.md) to understand your responsibilities as a 
-nominator, and the [validator docs](learn-validator.md) to understand what you need to do as a validator.
+account, which would effectively compound the rewards you receive over time. You could also choose
+to have them deposited to your account or a different account as free (transferable) balance. You
+can take a look at the [nominator guide](learn-nominator.md) to understand your responsibilities as
+a nominator, and the [validator docs](learn-validator.md) to understand what you need to do as a
+validator.
 
 If you are a beginner and would like to securely stake your tokens using Polkadot JS Apps, watch the
 video below
 
 [![Staking on Polkadot JS](https://img.youtube.com/vi/FCXC0CDhyS4/0.jpg)](https://youtu.be/FCXC0CDhyS4)
 
-### 2. Nomination period
+### 2. Staking System Overview
 
 Any potential validators can indicate their intention to be a validator candidate. Their candidacies
-are made public to all nominators, and a nominator in turn submits a list of any number of
-candidates that it supports. In the next era, a certain number of validators having the most DOT
-backing get elected and become active.
-
-There are no particular requirements to become a nominator, though we expect each nominator to
-carefully track the performance and reputation of the validators they back. Nominating is *not* a
-"set and forget" operation.
-
-Once the nomination period ends, the NPoS election mechanism takes the nominators and their
-associated votes as input, and outputs a set of validators. This "election solution" has to meet
-certain requirements, such as maximizing the amount of stake to nominate validators and distributing
-the stake backing validators as evenly as possible. The objectives of this election mechanism are to
-maximize the security of the network, and achieve fair representation of the nominators. If you want
-to know more about how NPoS works (e.g. election, running time complexity, etc.), please read
+are made public to all nominators, and a nominator in turn submits a list of up to
+{{ polkadot_max_nominations }} candidates that it supports. In the next era, a certain number of
+validators having the most DOT backing get elected and become active. As a nominator, a minimum of
+{{ min_nominator_intention }} is required to submit an intention to nominate. The nomination intents
+are placed in a semi-sorted list called
+[bags-list](https://github.com/paritytech/substrate/pull/9507). The bags list has two primary
+components, bags and nodes. The list is composed of bags that each describe a range of active bonded
+funds (e.g. the 1st bag will have nominators with 0 → 10 DOT, 2nd bag 11 → 20 DOT, etc). In each bag
+is a list of nodes that correspond to a nominator and their staked funds.
+
+The bags-list pallet is designed to be self-maintaining, with minimal effort from the blockchain,
+making it extremely scalable. Let us explore the sorting functionality of the bags list with an
+example. In the bags list below, there are 8 nodes placed in 3 bags. It can be observed that the
+list of nodes within the bags are arranged based on their insertion order and not based on the
+number of tokens bonded. For instance, the nodes in bag 1 are arranged in this order: 15 → 12 → 19
+
+![bags list example 1](../assets/staking/bags-list-example-1.png)
+
+Let's say the nominator with the stake of 19 DOT bonds 2 DOT additionally. This action would place
+that nominator node in bag 2, right after the node with 27 DOT.
+
+:::info
+
+Actions like bonding/unbonding tokens automatically rebags the nominator node, but events like
+staking rewards/slashing do not! The bags-list pallet comes with an important permissionless
+extrinsic: `rebag`. This allows anyone to specify another account that is in the wrong bag, and
+place it in the correct one. Check the [bags-list](learn-nominator.md#bags-list) section for more
+information.
+
+:::
+
+![bags list example 2](../assets/staking/bags-list-example-2.png)
+
+This sorting functionality is extremely important for the
+[long-term improvements](https://gist.github.com/kianenigma/aa835946455b9a3f167821b9d05ba376) of the
+staking/election system. The bags-list is capable of including an unlimited number of nodes, subject
+to the chain's runtime storage. In the current staking system configuration, the bags list keeps
+{{ max_nominator_count }} nomination intents, of which, 22,500 come out as the electing nominators.
+Check [Staking Election Stages](learn-nominator.md#staking-election-stages) section for more info.
+
+:::caution Minimum active nomination threshold to earn rewards is dynamic
+
+Submitting a nomination intent does not guarantee staking rewards. The stake of the top 22,500
+nominators is applied to the validators in the active set. To avail staking rewards, ensure that the
+number of tokens bonded is higher than the minimum active nomination. For more information, check
+the [nominator guide](learn-nominator.md)
+
+:::
+
+Once the nomination period ends, the NPoS election mechanism takes the nomination intents and their
+associated votes as input, and outputs a set of validators. The bags are iterated from the most
+staked to the least staked. This could leave the last touched bag to only be partially iterated.
+This means that in some edge cases, the order of members within a bag is also important. Recall that
+within each bag, the iteration order is simply the insertion order. If only 7 nodes have to be
+picked for the electing set, the nodes with 5 and 7 DOT will be selected and will the node with 8
+DOT will be left out. The bags-list pallet comes with an extrinsic: `putInFrontOf` which helps the
+node to move up in the bag. Check the [bags-list](learn-nominator.md#bags-list) section for more
+information.
+
+![bags list example 3](../assets/staking/bags-list-example-3.png)
+
+The "election solution" has to meet certain requirements, such as maximizing the amount of stake to
+nominate validators and distributing the stake backing validators as evenly as possible. The
+objectives of this election mechanism are to maximize the security of the network, and achieve fair
+representation of the nominators. If you want to know more about how NPoS works (e.g. election,
+running time complexity, etc.), please read
 [here](http://research.web3.foundation/en/latest/polkadot/NPoS.html).
 
+We expect each nominator to carefully track the performance and reputation of the validators they
+back. Nominating is _not_ a "set and forget" operation.
+
 ### 3. Staking Rewards Distribution
 
 To explain how rewards are paid to validators and nominators, we need to consider **validator