Tokenomics 2.0 docs (#553)

* Tokenomics 2.0

* Updates

* Fix broken link.

* Minor deployment update

* Update index.md

* Update index.md

fix link

* Review fixes

* clarification on voting era + extened info in example that follows

---------

Co-authored-by: Ivan Andrisek <ivan@Ivans-MBP.fritz.box>
Co-authored-by: Ivan <95318860+andabak@users.noreply.github.com>

docs/learn/index.md

@@ -19,7 +19,7 @@ To expand your knowledge about building applications or utilizing various tools
 [Smart Contracts](/docs/learn/smart-contracts)
 
 ## Advanced 
-[Tokenomics](/docs/learn/tokenomics/)
+[Tokenomics](/docs/learn/tokenomics2)
 
 [Networks](/docs/learn/networks)
 

docs/learn/tokenomics2/Inflation.md

@@ -2,33 +2,166 @@
 sidebar_position: 2
 ---
 
-## Hybdrid Inflation model
+Astar has a soft-capped 'yearly' inflation and uncapped max supply.
+Inflation is distributed amongst actors in the network, in varying proportions.
+Actors include:
+* stakers
+* dApp owners
+* collators
+* treasury
 
-The new inflation model will be preceded by an intermediate phase known as the hybrid inflation model. This transitional phase encompasses these modifications:
 
-### Inflation Adjustment
+## Basic Time Units
 
-Inflation rates have been lowered. The maximum token reward per block, reached based on the optimal staking rate or staking TVL (Total Value Locked), has been reduced from 253.08 to 231.20. Please note that this is temporary until the next phase of Tokenomics 2.0 coming with dApp Staking v3.
+### Cycles
+**Cycle** can be considered as a 'year' in the Astar Network.
+When a new cycle starts, new inflation configuration is calculated according to the total issuance at that point in time.
+E.g. if 'yearly' inflation is set to be 7%, and total issuance is 1,000,000 ASTR, then the soft-capped max inflation for that
+cycle will be 70,000 ASTR.
 
-### Treasury rewards
+Cycle length is configurable, but in practice it will resemble a 'year' off-chain.
 
-The dynamic treasury allocation has been removed in favor of a fixed annual inflation rate of 5%. Which correspond to a reward of 11.06 ASTR per block.
+ $inflation\_soft\_cap = inflation\_rate * total\_issuance$
 
-### Collators rewards
+### Periods
 
-Collators will now receive a steady 3.2% of the annual inflation which correspond to a reward of 7.07 ASTR per block. Although this represents a reduction from the previous model, the upcoming alignment of EVM fees and Substrate native fees is expected to increase overall fee earnings for collators.
+Each **cycle** consists of one or more **periods**.
+**Periods** are a core time unit in the dApp Staking protocol. Each period consists of a `Voting` and `Build&Earn` subperiods.
 
-### Stakers & dApp Rewards
+During the `Voting` subperiod, neither stakers nor dApp owners can earn any rewards, only _collators_ and _treasury_ continue earning.
+During the the `Build&Earn` subperiod, stakers earn staking rewards per **era** and have the opportunity to earn bonus reward at the end of a period.
+dApp owners also earn rewards, based on how well their dApp is performing in dApp staking, at the end of each **era**.
 
-The rewards for dApp staking, both for users and dApps, will remain unchanged in absolute terms. No immediate modifications will be implemented in this area. Future updates, including the introduction of dApp staking v3, will occur in the third phase of Tokenomics 2.0.
+### Eras
 
-We use the blockReward distribution to ensure those three requirements (and calculate them from the reward per block):
+Each **period** is divided up into multiple **eras**.
+**Era** is the core time unit in dApp staking, and its length is measured in the number of blocks.
 
-|                  | Percentage | Reward ASTR |
-|------------------|------------|-------------|
-| Block reward     | 100%       | 231.20      |
-| Treasury         | 4.78%      | 11.06       |
-| Collators        | 3.06%      | 7.07        |
-| dApp reward      | 17.27%     | 39.93       |
-| Base Staker      | 23.04%     | 53.27       |
-| Ajustable Staker | 51.84%     | 119.85      |
+`BuildAndEarn` subperiod consists of one or more _standard_ **eras**. Each era has a fixed length.
+`Voting` subperiod always consists of exactly **one era** and this _voting_ era is unique as its length (in blocks) can be longer than a _standard_ era length (but always a multiple of _standard_ era length).
+
+### Example
+
+* Block is produced every 12 seconds
+* **Era length** is 7200 blocks which equals 24 hours (1 day) (This is _standard_ era length)
+* `Voting` subperiod length is 10 eras (This is the single _voting_ era which lasts 10 x 7700 blocks)
+* `Build&Earn` subperiod length is 81 eras
+* Cycle length is **4 periods**
+
+With such configuration, we'd end up with a cycle lasting 364 days (roughly a year), and each period taking around 3 months to complete.
+
+## Recalculation
+
+When a new cycle begins, soft-inflation cap is recalculated, and according to the calculated value, rewards for all network actors are adjusted.
+
+The reason why it's a _soft-cap_, instead of a _hard-cap_ is how staker & dApp rewards are distributed.
+Rewards are only minted when they are claimed, and it is possible that at the time of reward recalculation, some rewards remain unclaimed.
+As a result, theoretically, it's possible for the cycle inflation to exceed the _soft-cap_ even though in practice it will be highly unlikely
+due to _lazy minting_ & _fee burn_ mechanisms.
+
+## Inflation Distribution
+
+Based on the calculated _soft-cap_, rewards for all network participants are adjusted.
+
+### Collators
+
+_Collators_ get a fixed amount of the cycle's _soft-capped_ inflation.
+This amount is equally divided by the number of blocks in the cycle.
+
+$collator\_reward\_per\_block = \frac{total\_collator\_cycle\_reward}{blocks\_per\_cycle}$
+
+### Treasury
+
+Similar to the _collators_, treasury gets a fixed amount of the cycle's _soft-capped_ inflation 
+distributed in equal amounts throughout all the blocks in the cycle.
+
+$treasury\_reward\_per\_block = \frac{total\_treasury\_cycle\_reward}{blocks\_per\_cycle}$
+
+### dApps
+
+dApp reward are _assigned_ at the end of each era during `Build&Earn` subperiod.
+This means that the total cycle's dApp reward amount has to be equally divided by the total number of `Build&Earn` eras in a cycle.
+
+$dapp\_reward\_pool\_per\_era = \frac{total\_dapp\_cycle\_reward}{periods\_per\_cycle * eras\_per\_build\_and\_earn}$
+
+The dApp staking protocol will calculate how much each staked dApp should get.
+
+### Stakers
+
+There are two components to the staker rewards - regular _staking_ rewards & the _bonus_ reward for loyal stakers.
+
+#### Regular Staker Rewards
+
+Regular staker rewards are awarded for staking native currency, **ASTR**, on a dApp.
+These rewards have two components - the _base_ reward and the _adjustable_ reward.
+
+Base reward is the amount assigned to the reward pool at the end of each era regardless of how much has been staked in total.
+
+$base\_staker\_reward\_pool\_per\_era = \frac{total\_base\_staker\_cycle\_reward}{number\_of\_cycles * eras\_per\_build\_and\_earn}$
+
+The adjustable part is the dynamic part, and depends on the _total value staked_ and the _target stake value_.
+This amount linearly increases as the _total value staked_ increases, and then saturates once the amount is reached or exceeded.
+With this component, _staker rewards_ are not a _zero-sum game_.
+
+$max_\_adjustable\_staker\_reward\_pool\_per\_era = \frac{total\_adjustable\_staker\_cycle\_reward}{number\_of\_cycles * eras\_per\_build\_and\_earn}$
+
+The adjustable part of the reward is calculated once an era ends, using the _total value staked_ at that point in time.
+
+$adjustable\_factor = min(1, \frac{total\_value\_staked\_percent}{ideal\_staking\_percent})$
+
+Using the _adjustable\_factor_, adjustable portion of the staker reward is:
+
+$adjustable\_staker\_reward\_pool = max_\_adjustable\_staker\_reward\_pool\_per\_era * adjustable\_factor$
+
+When the _adjustable factor_ is less than **1**, it means the remainder is never minted, reducing the overall inflation.
+
+With the above formulas, we can finally express how much staker _Alice_ earns in era **n**:
+
+$staker\_reward\_per\_era_{Alice} = \frac{staked\_value_{Alice,n}}{total\_staked\_value_n} * (base\_staker\_reward\_pool\_per\_era_n + adjustable\_staker\_reward\_pool_n)$
+
+#### Bonus Rewards
+
+In case a staker stakes during the `Voting` subperiod, and doesn't reduce their stake during the `Build&Earn` subperiod below what
+was staked at the end of the `Voting` subperiod, it will make them eligible for the bonus reward.
+
+Bonus reward pool is assigned per period, and can be expressed as:
+
+$bonus\_reward\_pool\_per\_period = \frac{total\_bonus\_cycle\_reward}{periods\_per\_cycle}$
+
+The bonus reward for a staker _Alice_ can then be expressed as:
+
+$bonus\_staker\_reward_{Alice} = \frac{voting\_subperiod\_staked\_value_{Alice}}{total\_voting\_subperiod\_staked\_value} * (bonus\_reward\_pool\_per\_period)$
+
+## Lazy Minting
+
+Both _staker_ and _dApp_ rewards are minted in a lazy fashion - when they are needed. Only collator & treasury rewards are minted per block.
+
+With the _adjustable staker reward_ and the dApp staking tier system, the inflation in practice will be much lower than the calculated _soft-cap_.
+Maximum adjustable award amounts is possible only if the ideal staking rate is reached or exceeded.
+For the dApp rewards, it's unlikely that all of the tiers will be filled with dApps - it might be that the tier capacity is larger than the demand,
+or that simply some dApps don't attract enough support to enter a tier. These rewards will never be even minted thus lowering the effective inflation rate.
+
+Rewards don't persist forever, and must be claimed before they _expire_.
+Although this is expected to be very lenient, it's still possible to happen.
+
+None of the aforementioned mechanism are _burn_ mechanisms, instead they just delay the _minting_ operation until it's needed.
+The major burn mechanism is part of the fee system, where a significant portion of fees get burned.
+Only due to this, it's practically impossible for the _soft-capped max inflation_ to be reached when considering rewards assigned & issued during
+a single cycle.
+
+## Parameters
+
+|                          | Shibuya       |
+|--------------------------|---------------|
+| Periods Per Cycle        | 2             |
+| Eras Per Voting Subperiod| 8             |
+| Eras Per Build&Earn Subperiod | 20      |
+| Blocks Per Era           | 1800 (~6 hours) |
+| Cycle Inflation Rate     | 1%            |
+| Treasury Part            | 5%            |
+| Collators Part           | 3%            |
+| dApps Part               | 20%           |
+| Base Staker Part         | 25%           |
+| Adjustable Staker Part   | 35%           |
+| Bonus Part               | 12%           |
+| Ideal Staking Rate       | 20%           |

docs/learn/tokenomics2/index.md

@@ -12,7 +12,7 @@ Astar Network is currently in a phased transition to a Tokenomics 2.0 model. The
 
 Content to this section will be added as changes get enacted (go live).
 
-Overview of current Astar Network's Tokenomics are documented **[here](../tokenomics)**
+Overview of current Astar Network's Tokenomics are documented **[here](../tokenomics2)**
 
 The outline of the phased approach to Tokenomics 2.0:
 - Phase 0 - Forum Discussion: 
@@ -26,7 +26,7 @@ The outline of the phased approach to Tokenomics 2.0:
     - ✅ Shiden - live since Decemeber 2023
     - ✅ Astar - live since December 2023
 - Phase 3 - Full Inflation Model (activation of dAppStaking v3 which affects block reward calculation, further reduction of inflation)
-    - Shibuya testnet - parameters defined, implementation in progress
+    - ✅ Shibuya testnet - live since December 2023
     - Shiden - parameters defined, implementation in progress
     - Astar - parameters defined, implementation in progress
 :::

docs/learn/tokenomics.md → docs/learn/tokenomics2/legacy_inflation.md

@@ -1,19 +1,22 @@
 ---
-sidebar_position: 10
-title: Tokenomics
+sidebar_position: 3
+title: Legacy Tokenomics
 ---
 
+:::note
+The following subchapters cover legacy Astar tokenomics models.
+For the latest, please refer to the _Tokenomics 2.0_ model.
+:::
+
+# Tokenomics 1.0
+
 import tokenomics from '/docs/learn/img/tokenomics_1.png'
 import inflation from '/docs/learn/img/inflation_1.png'
 
 [Astar Network]: https://astar.network/
 
-:::note
-This section includes content for advanced users.
-:::
-
 :::tip
-Astar and Shiden share the same economic model, though there were differences in their initial supply configurations.
+Astar and Shiden sharde the same economic model, though there were differences in their initial supply configurations.
 The following chapters focus on Astar and ASTR, however, this information also applies to Shiden and SDN token.
 :::
 
@@ -46,7 +49,7 @@ The reader might notice that Astar issues 95 times more tokens per block than Sh
 
 Each block reward is distributed to a set of beneficiaries.
 ​
-#### > Collators
+#### Collators
 
 The collator responsible for building the block will receive **collator's** portion of reward. This is the main financial incentive for the collators. Portion is configured as percentage of the block reward on-chain and is constant per block unless manually changed.
 
@@ -55,11 +58,11 @@ In addition, it will receive fees paid by the users for transactions that were i
 For **Shiden**, **100%** of the fees are burned, and the full tip is paid to the collator.
 For **Astar**, **20%** of the fees & tips are burned, and the rest is paid to the collator.
 
-#### > On-chain Treasury
+#### On-chain Treasury
 
 Treasury receives a variable portion of block reward. It is then allocated to a range of initiatives across the Astar ecosystem. This includes building reserves for parachain auctions, as well as supporting various projects and activities that help grow and strengthen our network. 
 
-#### > dApp Staking
+#### dApp Staking
 
 `dApp staking`, Astar's innovative developer incentive mechanism, receives a variable portion of the block rewards depending on current **total value locked** (or **TVL** in further text) in dApps staking.
 
@@ -154,3 +157,34 @@ The following graph is a visualization of the described model.
 </div>
 
 You can check this model and configure parameters yourself [here](https://www.desmos.com/calculator/cjjkt6smk5).
+
+# Hybrid Inflation
+
+The hybrid inflation model served as a step between the _Tokenomics 1.0_ and _Tokenomics 2.0_.
+
+### Inflation Adjustment
+
+Inflation rates have been lowered. The maximum token reward per block, reached based on the optimal staking rate or staking TVL (Total Value Locked), has been reduced from 253.08 to 231.20. Please note that this is temporary until the next phase of Tokenomics 2.0 coming with dApp Staking v3.
+
+### Treasury rewards
+
+The dynamic treasury allocation has been removed in favor of a fixed annual inflation rate of 5%. Which correspond to a reward of 11.06 ASTR per block.
+
+### Collators rewards
+
+Collators will now receive a steady 3.2% of the annual inflation which correspond to a reward of 7.07 ASTR per block. Although this represents a reduction from the previous model, the upcoming alignment of EVM fees and Substrate native fees is expected to increase overall fee earnings for collators.
+
+### Stakers & dApp Rewards
+
+The rewards for dApp staking, both for users and dApps, will remain unchanged in absolute terms. No immediate modifications will be implemented in this area. Future updates, including the introduction of dApp staking v3, will occur in the third phase of Tokenomics 2.0.
+
+We use the blockReward distribution to ensure those three requirements (and calculate them from the reward per block):
+
+|                  | Percentage | Reward ASTR |
+|------------------|------------|-------------|
+| Block reward     | 100%       | 231.20      |
+| Treasury         | 4.78%      | 11.06       |
+| Collators        | 3.06%      | 7.07        |
+| dApp reward      | 17.27%     | 39.93       |
+| Base Staker      | 23.04%     | 53.27       |
+| Adjustable Staker | 51.84%     | 119.85      |