Mx docs stakingv4 updates

docs/sdk-and-tools/sdk-py/sdk-py-cookbook-v1.md

@@ -2087,7 +2087,7 @@ tx_hash = entrypoint.send_transaction(transaction)
 
 #### Saving a key-value pair to an account using the controller
 
-We can store key-value pairs for an acoount on the network. To do so, we create the following transaction:
+We can store key-value pairs for an account on the network. To do so, we create the following transaction:
 
 ```py
 from pathlib import Path

docs/validators/staking-v4-revised.md

@@ -0,0 +1,253 @@
+---
+id: staking-v4
+title: Staking v4
+---
+
+[comment]: # (mx-context-auto)
+
+# **1. Introduction**
+
+
+## What is MultiversX staking?
+
+Staking on MultiversX has reached its fourth iteration; also known as Staking v4 it now offers improved validator security and introduces a few new features 
+designed to improve the staking experience and provide a non-biased validator rotation.
+
+The core benefits Staking v4 offers for staking providers are include the intuitive validator dashboard, 
+easy node management, and quick staking provider identity creation. Staking providers also have the ability to add 
+or remove validator nodes easily and change network fees on the fly.
+
+Compared to traditional staking mechanisms, MultiversX staking offers staking providers easy access, developer and technical support with the ability
+ to participate in protocol governance.
+
+
+## Audience and Purpose
+
+This document is intended for new staking providers that would like to start their journey with MultiversX and be part
+ of our growing community of validators and staking providers.
+
+While reading this document, you will be able to quickly understand and grasp the advantages of starting your journey as a Staking Provider 
+on the MultiversX protocol and fully reap the benefits, while participating in one of the most stable protocols in web3.
+
+
+## Key Features and Advantages
+
+### Security 
+
+Ensured by our Auction List mechanism - that randomly selects 320 nodes, 80 nodes from each shard at every epoch start - the nodes are shuffled randomly 
+to avoid collusion and to distribute the nodes randomly across the four shards. This contributes to the protocol security by maintaining a balanced network 
+and avoiding concentration of power. 
+
+
+### Scalability 
+
+MultiversX's sharded architecture allows the network to scale by distributing the workload across multiple shards that allows the parallel processing of 
+transactions. This design improves throughput and reduces latency, benefiting staking providers with a robust and responsive network. Sharding allows the 
+network to grow seamlessly scaling performance and security.  
+
+### Rewards
+
+#### APR (Annual Percentage Rate)
+
+The APR of a Staking Provider is influenced by a few factors. The most important is how their Node NQT is aligned with the Network NQT. That means, the closer your Node NQT is to the Network NQT the better your APR.
+
+An easy way to calculate this is to divide the total amount of EGLD locked in your Staking Provider contract by the number of nodes and compare it to the Network NQT. If your Staking Provider has a very high NQT compare to the Network, then your APR will be lower because the proportion of EGLD per node is not optimized.
+
+![](/validators/stakingV4/LowAPRDetail.png)
+
+The APR is also directly influenced by the service fee decided by the Staking Provider, more about this in the dedicated section below.
+
+
+#### Service Fee
+
+This fee represents the percentage of validator rewards the Staking Provider is gaining in order to kept heir service up, nodes updated, infrastructure paid and more. This is calculated directly from each Epoch reward and influences the overall Staking Provider APR. A high Service Fee will lower the APR and a lower or zero Service Fee will maximize APR.
+
+For example if at the end of the Epoch, the Staking Provider delegators will receive a total of 100 EGLD in rewards, and the Staking Provider Service Fee is set at 10%, 10 EGLD will go to the Staking Provider Rewards Address and the 90 EGLD will be split between the delegators accordingly.
+
+The Service Fee can be changed at any time by the owner of the Staking Provider wallet. This can range between 0% and 100%.
+However, we recommend a service fee between 10% and 12% but every Staking Provider should keep and eye on the others and adjust as it is a competitive space and we do not impose any restrictions, only suggest fair fees to our Staking Providers.
+
+#### Service Fee Examples
+
+Here are a few examples from our current setup of Staking Providers and their APR according to their NQT and Service Fee:
+
+#### Delegator Optimized Staking Provider 0% Service Fee for 4,018 EGLD Network NQT
+
+In this case for 36 Nodes with 145,910 EGLD Stake the Node NQT is 4,053 EGLD very close to 4,018.
+Also, the Service Fee is set at 0% so the optimization is maximized to favor delegator rewards the Staking Provider taking zero rewards but offering the highest APR to their delegators of 7.74%.
+
+![](/validators/stakingV4/DelegatorOptimized0Fees.png)
+
+
+#### Balanced Optimized Staking Provider 10% Service Fee for 4,018 EGLD Network NQT
+
+Here is another example where this Staking Provider has chosen a 10% Service Fee. Although the screenshot shows 50 nodes, because of the Network NQT they can only run 47 but the optimization is good with 47 Nodes as well offering their delegators 
+6.9% APR. The calculation is the same, 196,805 staked EGLD for 47 Eligible Nodes gives a Node NQT of 4,187 EGLD very close to the Network NQT, but here the Service Fee is lowering the APR as you see compared to the previous example, is 0.84% lower.
+This is how the Service Fee can impact as Staking Provider's APR.
+
+![](/validators/stakingV4/Balanced10Fees.png)
+
+
+#### Delegation Cap
+
+The Delegation Cap is an option a Staking Provider can choose to use. This gives the Staking Provider mode granular control over the amount that can be delegated
+ to their contract. 
+
+ This could potentially help prevent over-delegating which in turn could mean a lower APR if the overall EGLD staked per Node is much higher than the Network NQT.
+
+
+# **2. Staking Protocol Overview**
+
+
+## Core concepts
+
+### Staking Providers
+
+A Staking Provider can be a company or an individual, someone that wants to start their journey with MultiversX from the perspective of running validator nodes,
+investing or contributing to the Decentralization of the protocol.
+
+The main aspect of becoming a Staking Provider is offering users on the MultiversX protocol the possibility of Staking their EGLD for rewards and participating
+to the protocol's safety.
+
+Either a company or individual running a Staking Provider, MultiversX is offering Technical and Business support for new and existing Staking Providers. 
+
+In Staking v4, there is a 50 Validator Node limit for each new Staking Provider joining the network. 
+
+
+### Validators 
+
+A Validator is crucial Node running on the MultiversX protocol, it serves as a processor of transactions, securing the network and participating in consensus
+while earning rewards. In simple terms it is a server running the MultiversX protocol through a WASM virtual machine.
+
+From a Staking Provider's perspective, validators play a key role in maintaining network decentralization and performance. The Adaptive State Sharding model makes 
+validators operate efficiently by distributing load dynamically, optimizing resources while maintaining high throughput and low latency.
+
+This enables Staking Providers to scale their operations ensuring reliable a reliable staking experience for delegators.
+
+
+### Delegators
+
+A Delegator is someone that choses to Stake their EGLD to secure the network and earn rewards, by using the service of existing Staking Providers but without 
+having to run their own Validator node.
+
+From a Staking Provider's perspective, a Delegator is essential for decentralization and network security but also in a way a customer that trusts the 
+stability and reliability of a Staking Provider to have their Nodes running the latest protocol version and optimizing their rewards based on their Staking.
+
+
+### Reward Distribution
+
+Rewards distributed from Validators participating in Consensus are received at each Epoch end, roughly once per day at 18:45 GMT+1. 
+
+The rewards are automatically distributed to Delegators according to their Stake and to the Staking Provider according to their set Service Fee.
+
+
+
+# **3. Staking Mechanisms**
+
+## Node Qualification Threshold
+
+Also known as NQT, it is a dynamically calculated number by the network approximately every 10 minutes. It is directly influenced by the numbers of validator nodes leaving or joining the network and the overall EGLD staked in the protocol. 
+
+From a Staking Provider perspective you can calculate this as an average between the total EGLD staked, adding the top-up and dividing it by the number of nodes for your Staking Provider. This will show your status or customized NQT that you can compare against the network NQT.
+
+For example, let's assume this fictional Staking Provider with the following parameters:
+
+Number of Nodes: 10
+EGLD Stake: 40,000
+
+We can split the Stake like so:
+
+EGLD: 25,000 Node Stake
+EGLD: 15,000 Top-up
+
+The NQT calculation is fairly simple as we divide the overall 40,000 EGLD stake by the number of nodes 10 and results in an NQT of 4,000. This examples is simplified for the sake of the example. Now this NQT can be compared to the actual network NQT so that the Staking Provider owner can decide on whether to adjust top-up or nodes.
+
+
+## Auction List
+
+The Auction List has been introduced with Staking v4, below an example from our explorer.
+
+
+### Auction List Explorer Example**
+
+The mechanism of the Auction List selects a list of 320 random nodes, 80 from each shard, at epoch start.
+These selected nodes remain in the Auction List for one epoch. 
+
+The Auction List was devised with security in mind , randomly selecting nodes with the point being to avoid colluding, 
+giving Staking Providers a fair change for validating and also keeps the Shards healthy with shuffling nodes every epoch.
+
+There are three different status titles for nodes in the Auction List, Qualified, Danger and Not Qualified.
+
+![](/validators/stakingV4/AuctionList.png)
+
+
+## Epoch Start
+
+Every Epoch Start 320 Nodes are randomly shuffled out from the consensus and moved to the Auction List.
+
+This includes jailed nodes, but the mechanism compensates for each jailed node by selecting the same number of nodes that are not jailed.  
+
+
+## Qualified Status
+
+A Node gets the Qualified status if the Node NQT calculated for it, from the stake of Staking Provider and top-up, is the same or higher as compared to the Network NQT.
+
+![](/validators/stakingV4/QualifiedSimple.png)
+
+![](/validators/stakingV4/QualifiedDetail.png)
+
+
+## Danger Status 
+
+A Node gets the Danger status if the Node NQT calculated for it, from the stake of Staking Provider and top-up, is dangerously close or exactly the same as the Network NQT.
+
+![](/validators/stakingV4/DangerSimple.png)
+
+![](/validators/stakingV4/DangerDetail.png)
+
+
+## Not Qualified Status
+
+A Node gets the Not Qualified status when the Node NQT calculated for it, from the stake of Staking Provider and top-up,
+is lower as compared to the Network NQT, the active period for the Validator Node.
+
+![](/validators/stakingV4/NotQualifiedSimple.png)
+
+![](/validators/stakingV4/NotQualifiedDetail.png)
+
+
+## Waiting List
+
+The Waiting List represents the list of nodes that have been Qualified from the Auction List.
+All the nodes that have passed the Qualified Status will then go to the Waiting List, they will remain in the Waiting List for 4 epochs which represents roughly four days.
+
+After the 4 epochs, these nodes are moved to participate in the consensus for validating.
+As a side note, even if the Network NQT changes in the 4 waiting Epochs the already selected nodes will still participate in the consensus even if they would presumably have lower Node NQT after the aforementioned 4 epochs in the Waiting List.
+
+
+## Waiting Status
+
+This Status means that the Validator Node has been Qualified from the Auction List and is in the 4 Epoch waiting time before joining the consensus to start validating.
+
+![](/validators/stakingV4/WaitingDetail.png)
+
+
+## Eligible Status
+
+This Status means that the Validator Node can validate or propose blocks in the current Epoch. It can be part of the Consensus in certain rounds.
+
+![](/validators/stakingV4/EligibleDetail.png)
+
+
+## Automatic Node Qualification
+
+This mechanism automatically distributes a Staking Provider's total top-up amount to the Validator Nodes they own.
+It focuses on redistributing the top-up based on the Network NQT in order to Qualify as many Nodes as possible from each staking provider.
+
+
+## Top-up Balancing
+
+The point of this mechanism is to show Staking Providers their Nodes' status based on the Network NQT allowing them to adjust their number of nodes or the amount of top-up, either manually or automatically.
+
+This allows for monitoring the status of the nodes and preparing for the Epoch Start.
+

docs/validators/staking-v4.md

@@ -5,23 +5,12 @@ title: Staking v4
 
 [comment]: # (mx-context-auto)
 
-# **Introduction**
+# **Staking v4. Introduction**
 
 Staking and delegation are processes that evolve over time. No system has to remain static. Our assumptions about how
-the market works and reacts can change, just as user behavior and market dynamics may evolve. Currently, we have
-approximately 400 validators, with some acting as staking providers and others as individual validator operators. While
-most nodes have a comfortable top-up on the base stake of 2.500 eGLD, some do not contribute to the network's security by
-adding more top-up.
+the market works and reacts can change, just as user behavior and market dynamics may evolve.
 
-[comment]: # (mx-context-auto)
-
-# **Limitations of the Current Implementation**
-
-- Limiting the number of nodes to 3200, creating an additional queue. New validators can join the network only if
-  someone leaves the system.
-- Concentration of power among large providers, hindering decentralization. Top 11 staking agencies control 33%.
-
-One of our primary objectives is to eliminate the additional queue and leverage the top-up value per node to determine
+One of our primary objectives with staking v4 is to eliminate the additional queue and leverage the top-up value per node to determine
 the best nodes. This ensures that we do not restrict the entry of new validators, as the current system requires an old
 validator to leave for a new one to enter. The market will determine the actual node price, operating as a soft auction
 where anyone paying the node price (2.500 eGLD) can register, but the node becomes a validator only if it has sufficient
@@ -51,42 +40,13 @@ Since this selection occurs at the end of every epoch, staking providers near th
 and adjust their nodes, unstaking or staking nodes based on the topUp per node of other providers. Sorting nodes based
 on topUp does not provide adequate protection for staking providers, requiring constant supervision and action.
 
-**The second version**, currently implemented and explained in the following chapters, addresses the shortcomings of the
-first version.
-
 [comment]: # (mx-context-auto)
 
-# **Current Implementation**
 
 :::note
 Please note that the numbers below are indicative and only used to better exemplify the model.
 :::
 
-In the current implementation (staking 3.5), we have:
-
-1. A capped number of 3200 **nodes in the network**, including:
-    - 1600 active/eligible validators globally, split into 400 nodes per shard
-    - 1600 waiting validators globally, split into 400 nodes per shard
-2. An uncapped `FIFO` queue where newly staked nodes are placed and await participation in the network.
-
-:::important
-
-Currently, a queued node can participate in the network only if an existing node is either unstaked or jailed.
-
-:::
-
-![Current Staking](/validators/stakingV4/current-staking.png)
-
-Nodes are distributed in the following steps:
-
-1. Randomly shuffle out 80 eligible validators for each shard, resulting in 320 (80 validators per 4 shards)
-   shuffled-out validators.
-2. Select these 320 shuffled-out validators to be randomly but evenly distributed at the end of each shard's waiting
-   list.
-3. For each shard, replace the previously shuffled-out validators with 80 waiting validators from the top of each
-   shard's waiting list.
-
-In the current implementation, each node, regardless of its top-up, has equal chances of participating in the consensus.
 Starting with staking phase 4, the probability of validators entering the validation process will be significantly
 influenced by the amount of their staked top-up. Validators with a higher staked top-up will have considerably greater
 chances of participation, while those with little or no top-up will find their chances of entering into validation
@@ -96,21 +56,12 @@ markedly reduced.
 
 # **Staking V4**
 
-Staking phase 4 will unfold in three consecutive steps, each corresponding to a specific epoch.
-
 [comment]: # (mx-context-auto)
 
-## Staking v4. Step 1.
-
-In the first step, we will completely **remove the staking queue** and place all nodes in an **auction list**. This
-process will occur automatically at the end of the epoch and requires no interaction from validators. Nodes'
-distribution remains unchanged.
-
-![Staking V4 Step 1](/validators/stakingV4/stakingV4-step1.png)
 
 :::important Important notes
 
-Starting with this epoch:
+Each epoch:
 
 - Every **newly staked** node will be placed in the **auction list**.
 - Every **unjailed** node will be placed in the **auction list**.
@@ -124,34 +75,15 @@ For example, if an owner has insufficient base stake for their nodes, the nodes
 end of the epoch based on the order: `auction` -> `waiting` -> `eligible`. This ensures that nodes contributing to the
 ecosystem with a healthy top-up will not be adversely affected.
 
-Below is an example of how nodes are unstaked based on insufficient base stake. Suppose an owner has four nodes:
-
-- 1 eligible: `node1`
-- 2 waiting: `node2`, `node3`
-- 1 auction: `node4`
-
-Assuming a minimum price of 2500 EGLD per staked node, the owner should have a minimum base stake of 10,000 EGLD (4 *
-2500 EGLD). If, during the epoch, the owner unstakes 4000 EGLD, resulting in a base stake of 6000 EGLD, only two staked
-nodes can be covered. At the end of the epoch, the nodes `node4` and `node3` will be unstaked in the specified order.
 
 [comment]: # (mx-context-auto)
 
-## Staking v4. Step 2.
-
-In the second step, all **shuffled-out** nodes from the **eligible list** will be sent to the **auction list**. Waiting
-lists will not be filled by any shuffled-out nodes.
-
-Using the example above, this will resize each waiting list per shard from 400 nodes to 320 nodes.
-
-![Staking V4 Step 2](/validators/stakingV4/stakingV4-step2.png)
-
-[comment]: # (mx-context-auto)
 
-## Staking v4. Step 3.
+## Staking v4.
 
-Starting with this epoch:
+Each epoch:
 
-- Maximum number of nodes in the network will be changed from 3200 to 2880 (3200 - 320), consisting of:
+- The maximum number of nodes in the network will be:
     - a global number of 1600 active/eligible validators, split into 400 nodes/shard
     - a global number of 1280 waiting validators to join the active list, split into 320 nodes/shard
 - All **shuffled out** nodes from the eligible list will be sent to the auction list to take part in the auction