docs: Tokenomics (#1726)

* New diagram and reviews * Some typos and higher resolution diagram * update economic model * Validator Requirement * Update docs/content/about-iota/tokenomics/proof-of-stake.mdx Co-authored-by: Philipp Gackstatter <[email protected]> * Update docs/content/about-iota/tokenomics/proof-of-stake.mdx Co-authored-by: Philipp Gackstatter <[email protected]> * addressing comments * Philipp review suggestions * Update validator pool rewards description * remove unrelated pdfs * add fee burning to explanation * remove info about distribution of fees * rephrase tallying rule (from total slashing to possibly a partial slashing) * remove mention of gas fees * feat(docs): gas-in-iota.mdx was corrected (#1769) * feat(docs): gas-in-iota.mdx was corrected * fix(docs): review comments were corrected * fix(docs): review comments were fixed * Fix Rewards Formula * gas budget formula fix * Update docs/content/about-iota/tokenomics/iota-token.mdx Co-authored-by: Levente Pap <[email protected]> * fix(docs): wrong md link --------- Co-authored-by: oliviasaa <[email protected]> Co-authored-by: Luigi Vigneri <[email protected]> Co-authored-by: Philipp Gackstatter <[email protected]> Co-authored-by: Valerii Reutov <[email protected]> Co-authored-by: Thibault Martinez <[email protected]> Co-authored-by: Levente Pap <[email protected]>
iotaledger · Aug 27, 2024 · b6e3b7e · b6e3b7e
1 parent eb3797b
commit b6e3b7e
Show file tree

Hide file tree

Showing 10 changed files with 67 additions and 73 deletions.
diff --git a/docs/content/about-iota/tokenomics/gas-in-iota.mdx b/docs/content/about-iota/tokenomics/gas-in-iota.mdx
@@ -1,17 +1,19 @@
 ---
 title: Gas in IOTA
-description: A IOTA transaction must pay for both the computational cost of execution and the long-term cost of storing the objects a transaction creates or mutates.
+description: An IOTA transaction must both pay for the computational cost of execution and pay a deposit for storing the objects a transaction creates or mutates.
 ---
 
-An IOTA transaction must pay for both the computational cost of execution and the long-term cost of storing the objects a transaction creates or mutates. Specifically, [IOTA Gas Pricing](gas-pricing.mdx) is such that any transaction pays the following gas fees:
+An IOTA transaction must both pay for the computational cost of execution and pay a deposit for storing the objects a transaction creates or mutates. Specifically, [IOTA Gas Pricing](gas-pricing.mdx) is such that any transaction pays the following gas fees:
 
 `total_gas_fees = computation_units * reference_gas_price + storage_units * storage_price`
 
-While computation and storage fees are separate, they are conceptually similar in that they each translate computation or storage into IOTA terms by multiplying computation or storage units by the relevant price.
+The storage component is 100% rebated upon deletion of the corresponding object from storage, and for this reason, the terms `storage fee` and `storage deposit` are used interchangeably.
 
-Finally, storage fee rebates are provided whenever a transaction deletes previously stored objects. Hence, the net fees that a user pays equals gas fees minus the rebates associated with data deletion:
+While computation fees and storage deposits are separate, they are conceptually similar in that they each translate computation or storage into IOTA terms by multiplying computation or storage units by the relevant price.
 
-`net_gas_fees = computation_gas_fee + storage_gas_fee - storage_rebate`
+Finally, storage rebates are provided whenever a transaction deletes previously stored objects. Hence, the net fees that a user pays equals gas fees minus the rebates associated with data deletion:
+
+`net_gas_fees = computation_fee + storage_deposit - storage_rebate`
 
 The information on net gas fees displays in the [IOTA network explorer](https://explorer.iota.cafe/) for each transaction block.
 
@@ -30,46 +32,36 @@ Gas units include both
 
 Different IOTA transactions require varying amounts of computational time for processing and execution. IOTA translates these varying operational loads into transaction fees by measuring each transaction in terms of computation units. In general, more complex transactions require more computation units.
 
-Importantly, though, IOTA computation gas schedule is built coarsely with a bucketing approach. Two relatively similar transactions translate into the exact same amount of computation units if they are in the same bucket, whereas two relatively different transactions translate into different amounts of computation units if they fall in separate buckets. The smallest bucket maps into 1,000 computation units, meaning that all transactions that fall into the smallest bucket cost 1,000 computation units. The largest bucket maps into 5,000,000 computation units; if a transaction requires more computation units, it aborts.
+Importantly, though, IOTA computation gas schedule is built with a bucketing/step approach. Two reasonably similar transactions translate into the exact same amount of computation units if they are in the same bucket, whereas two relatively different transactions translate into different amounts of computation units if they fall in separate buckets. The smallest bucket maps into 1,000 computation units, meaning that all transactions that fall into the smallest bucket cost 1,000 computation units. The largest bucket maps into 5,000,000 computation units; if a transaction requires more computation units, it aborts.
 
-Using coarse bucketing accomplishes two important goals:
+Buckets start at 1000 units and increment in steps up to 5,000,000, where the step value is set as a protocol parameter (currently the step is equal to 1000, effectively rounding up to the nearest 1000).
 
-    - Frees you from optimizing your smart contracts to deliver marginal gains in gas costs via "gas golfing" — instead, you can focus on step-function improvements in your products and services.
-    - Gives you the freedom to adjust per-instruction gas costs and experiment with new gas metering schemes without creating significant development disruption. This can happen frequently, so it's important that you do not rely on per-instruction gas costs remaining stable over time.
+Using bucketing accomplishes two important goals:
 
-| Bucket Lower Threshold | Bucket Upper Threshold | Computation Units      |
-| ---------------------- | ---------------------- | ---------------------- |
-| 0                      | 1,000                  | 1,000                  |
-| 1,001                  | 5,000                  | 5,000                  |
-| 5,001                  | 10,000                 | 10,000                 |
-| 10,001                 | 20,000                 | 20,000                 |
-| 20,001                 | 50,000                 | 50,000                 |
-| 50,001                 | 200,000                | 200,000                |
-| 200,001                | 1,000,000              | 1,000,000              |
-| 1,000,001              | 5,000,000              | 5,000,000              |
-| 5,000,001              | Infinity               | transaction will abort |
+    - Frees users from optimizing their smart contracts to deliver marginal gains in gas costs via "gas golfing" — instead, they can focus on step-function improvements in their products and services.
+    - Gives users the freedom to adjust per-instruction gas costs and experiment with new gas metering schemes without creating significant development disruption. This can happen frequently, so it's important that they do not rely on per-instruction gas costs remaining stable over time.
 
 ### Storage units {#storage}
 
 Similarly, IOTA transactions vary depending on the amount of new data written into on-chain storage. The variable storage units capture these differences by mapping the amount of bytes held in storage into storage units. The current IOTA schedule is linear and maps each byte into 100 storage units. So, for example, a transaction that stores 25 bytes costs 2,500 storage units, while a transaction that stores 75 bytes costs 7,500 units.
 
-Importantly, in the storage model users pay storage deposit fees for storing data in perpetuity but can also get a full rebate on previously stored data, if that data is deleted. Hence, the amount of storage fees that you pay are 100% rebateable.
+Importantly, in IOTA's storage model users pay storage deposit fees for storing data in perpetuity but can also get a full rebate on previously stored data, if that data is deleted. Hence, the amount of storage fees that users pay are 100% rebateable. This storage deposit mechanism incentivizes users to minimize the storage burden they place on all nodes by reducing their storage requirements and cleaning up unused objects. 
 
 ### Gas budgets {#gas-budgets}
 
-You must submit all transactions need together with a gas budget. This provides a cap to the amount of gas fees you pay, especially because sometimes it might be hard to perfectly forecast how much a transaction costs before you submit it to the IOTA network.
+Users must submit all transactions they need together with a gas budget. This provides a cap to the amount of gas fees paid, especially because sometimes it might be hard to perfectly forecast how much a transaction costs before the user submits it to the IOTA network.
 
 The gas budget for an IOTA transaction is defined in IOTA units and transactions are successfully executed if:
 
-`gas_budget >= max{computation_fees,total_gas_fees}`
+`gas_budget >= max{computation_fees,net_gas_fees}`
 
-If the gas budget does not fulfill this condition, then the transaction fails and a portion of the gas budget is charged. In cases where the `gas_budget` is insufficient for covering `computation_fees`, then the entirety of the `gas_budget` is charged. In cases where `gas_budget` is sufficient for covering `computation_fees` but not the `total_gas_fees`, then a portion of the `gas_budget` corresponding to `computation_fees` and the fees associated with mutating the transaction's input objects are charged.
+If the gas budget does not fulfill this condition, then the transaction fails and a portion of the gas budget is charged. In cases where the `gas_budget` is insufficient for covering `computation_fees`, then the entirety of the `gas_budget` is charged. In cases where `gas_budget` is sufficient for covering `computation_fees` but not the `net_gas_fees`, then a portion of the `gas_budget` corresponding to `computation_fees` and the fees associated with mutating the transaction's input objects are charged.
 
-Ultimately, a successful transaction requires the end user to pay the transaction's `total_gas_fees`. However, since it is challenging to perfectly forecast computation time before the transaction is processed, the `gas_budget` condition also requires the `gas_budget` to be at least as large as the transaction's `computation_fees` in case the transaction aborts. In some cases -- especially in the presence of high storage rebates, and, thus negative net storage fees -- the gas budget might be higher than the total gas fees you pay.
+Ultimately, a successful transaction requires the end user to pay the transaction's `net_gas_fees`. However, since it is challenging to perfectly forecast computation time before the transaction is processed, the `gas_budget` condition also requires the `gas_budget` to be at least as large as the transaction's `computation_fees` in case the transaction aborts. In some cases -- especially in the presence of high storage rebates, and, thus negative net storage fees -- the gas budget might be higher than the total gas fees the user pays.
 
-Importantly, the minimum gas budget is 1000 NANOS (.000001 IOTA). This ensures validators are compensated with at least 1,000 NANOS even if the gas budget is incorrectly specified and the transaction aborts. Additionally, this protects the IOTA network from being spammed with a large number of transactions with minimal gas budgets. The maximum gas budget is 50 billion NANOS or 50 IOTA. This protects the network against overflow of internal multiplications and gas limits for denial of service attacks.
+Importantly, the minimum gas budget is 1000 NANOS (.000001 IOTA). This protects the IOTA network from being spammed with a large number of transactions with minimal gas budgets. The maximum gas budget is 50 billion NANOS or 50 IOTA. This protects the network against overflow of internal multiplications and prevents excessively large gas budgets being used for denial of service attacks.
 
-As mentioned previously, the storage rebate currently equals 99% of the originally paid storage fees. Because the gas budget applies to the totality of gas fees, it is often the case that a transaction only goes through if the gas budget is considerably higher than the net gas fees that a user ultimately pays.
+As mentioned previously, the storage rebate is 100% of the originally paid storage fees. Because the gas budget applies to the totality of gas fees, it is often the case that a transaction only goes through if the gas budget is considerably higher than the net gas fees that a user ultimately pays.
 
 ### Gas budget examples {#gas-budget-examples}
 

diff --git a/docs/content/about-iota/tokenomics/iota-token.mdx b/docs/content/about-iota/tokenomics/iota-token.mdx
@@ -5,8 +5,8 @@ description: The native asset on IOTA is called IOTA.
 
 The native asset on IOTA is called IOTA. 
 
-At Mainnet launch, **4,600,000,000** IOTA tokens were minted, a portion of which will vest over the coming years, or distributed as future stake reward subsidies.
-There is no maximum supply of IOTA - the total supply will increase over time through a given certain inflation rate.
+At the launch of IOTA Rebased, **4,600,000,000** IOTA tokens were migrated from the previous network called Stardust.
+There is no maximum supply of IOTA - the total supply will fluctuate over time according to the combination of a given inflation rate and the burning of fees.
 
 :::info Decimals