Updates to gas budget info

doc/src/learn/tokenomics/gas-budgets.md → doc/src/learn/tokenomics/gas-in-sui.md

@@ -1,29 +1,63 @@
 ---
-title: Sui Gas Budgets
+title: Gas in Sui
 ---
 
-Gas Budgets are important because they guarantee that an user never pays more transaction fees than what they budget for. Sui’s gas mechanism is such that users pay upfront for both the current computational cost of executing a transaction and the long-term cost of storing the data associated with a transaction’s objects. Thus, Gas Budgets need to cover both sets of fees.
+A Sui 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, [Sui’s Gas Pricing Mechanism](gas-pricing.md) is such that any transaction pays the following gas fees:
 
-Specifically, [Sui’s Gas Pricing Mechanism](https://docs.sui.io/learn/tokenomics/gas-pricing) is such that any transaction $\tau$ pays the following gas fees:
+`total_gas_fees = computation_units * reference_gas_price + storage_units * storage_price`
 
-$$
-\text{GasFees}[\tau] = \text{ComputationUnits}[\tau]\times \text{ReferenceGasPrice}\ + \ \text{StorageUnits}[\tau]\times \text{StoragePrice}
-$$
+This information displays in Sui Explorer for each transaction block:
+
+![Gas Fees displayed on Sui Explorer](../../static/gas-fees-explorer.png "The Gas Fees section displayed on Sui Explorer")
+*The Gas Fees section for a transaction block displayed on Sui Explorer*
 
 While computation and storage fees are separate, they are conceptually similar in that they each translate computation or storage into SUI terms by multiplying computation or storage units by the relevant price. 
 
 ### Gas Prices
 
-The [Reference Gas Price](gas-pricing.md#computation-gas-prices) translates the real-time cost of executing a transaction into SUI units and is updated at each epoch boundary by the validator set. Similarly, the [Storage Price](gas-pricing.md#storage-gas-prices)  translates the long-term cost of storing data on-chain into SUI units and is updated infrequently; often remaining constant for various consecutive epochs. During regular network operations, all Sui users should expect to pay the Reference Gas Price and Storage Price for computation and storage, respectively.
+The [Reference Gas Price](https://docs.sui.io/learn/tokenomics/gas-pricing#computation-gas-prices) translates the real-time cost of executing a transaction into SUI units and is updated at each epoch boundary by the validator set. Similarly, the [Storage Price](https://docs.sui.io/learn/tokenomics/gas-pricing#storage-gas-prices)  translates the long-term cost of storing data on-chain into SUI units and is updated infrequently; often remaining constant for various consecutive epochs. During regular network operations, all Sui users should expect to pay the Reference Gas Price and Storage Price for computation and storage, respectively.
 
 ### Gas Units
 
-Different Sui transactions require varying amounts of computational time in order to be processed and executed. Sui translates these varying operational loads into transaction fees by measuring each transaction in terms of Computation Units. All else equals, more complex transactions will require more Computation Units. 
+Different Sui transactions require varying amounts of computational time in order to be processed and executed. Sui translates these varying operational loads into transaction fees by measuring each transaction in terms of Computation Units. All else equals, more complex transactions will require more Computation Units.
+
+The minimum Gas Budget is 2000 MIST. This ensures validators can be compensated with at least 2000 MIST even if the Gas Budget is  incorrectly specified and the transaction aborts. Additionally, this protects the Sui Network from being spammed with a large number of transactions with minimal gas budgets. The maximum Gas Budget is 50 billion MIST or 50 SUI. This protects the network against overflow of internal multiplications and gas limits for denial of service attack
+
+Finally, Sui’s [Storage mechanics](https://docs.sui.io/learn/tokenomics/storage-fund#storage-fund-rewards) provide storage fee rebates 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:
+
+$$
+\text{NetGasFees}[\tau]\ =\ \text{GasFees}[\tau]\ -\text{StorageRebate}[\tau]
+$$
 
 Importantly, though, Sui’s gas schedule is built coarsely with a bucketing approach. Two relatively similar transactions will translate into the exact same amount of Computation Units if they are in the same bucket, whereas two relatively different transactions will translate into different amounts of Computation Units if they fall in separate buckets. The smallest bucket maps into 1000 Computation Units, meaning that all transactions that fall into the smallest bucket will cost 1000 Computation Units. The largest bucket maps into 5,000,000 Computation Units; if a transaction were to require more Computation Units it would simply abort.
 
+Using coarse bucketing accomplishes two important goals:
+* Frees developers from optimizing their smart contracts to deliver marginal gains in gas costs via "gas golfing"--instead, can focus on step-function improvements in their products and services.
+* Gives Sui protocol devs the freedom to adjust per-instruction gas costs and experiment with new gas metering schemes without creating significant disruption for builders. We expect this will happen frequently, so it's important that builders do *not* rely on a per-instruction gas costs remaining stable over time.
+
+| 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 |
+
+Coarse bucketing has important benefits relative to more fine grained gas schedules in that it accomplishes two important goals:
+
+- Frees developers from optimizing their smart contracts to deliver marginal gains in gas costs via "gas golfing" – instead, can focus on step-function improvements in their products and services.
+- Gives Sui protocol developers the freedom to adjust per-instruction gas costs and experiment with new gas metering schemes without creating significant disruption for builders. We expect this will happen frequently, so it's important that builders do not rely on per-instruction gas costs remaining stable over time.
+
+**Storage Units**
+
 Similarly, Sui transactions vary depending on the amount of new data written into on-chain storage. The variable Storage Units captures these difference by mapping the amount of bytes held in storage into storage units. Sui’s current schedule is linear and maps each byte into 100 storage units. So, for example, a transaction that stores 25 bytes will cost 2500 Storage Units while a transaction that stores 75 bytes will cost 7500 units.
 
+Importantly, in Sui’s [Storage Fund](https://docs.sui.io/learn/tokenomics/storage-fund) model users pay upfront for the cost of storing data in perpetuity but can also get a partial rebate on previously stored data if that data is deleted. Hence, the amount of storage fees that a user pays, equal to $\text{StorageFees}[\tau]=\ \text{StorageUnits}[\tau]\times \text{StoragePrice}$, can be split into a rebateable and non-rebateable amount. Initially, the rebateable amount equals 99% of the storage fees while the non-rebateble amount equals 1% of the storage fee.
+
 ### Gas Budgets
 
 All transactions need to be submitted together with a Gas Budget. This provides a cap to the amount of Gas Fees a user will pay, especially since in some cases it may be hard to perfectly forecast how much a transaction will cost before it is submitted to the Sui Network.
@@ -36,15 +70,7 @@ $$
 
 If the Gas Budget does not fulfill this condition — and thus is insufficient to cover a transaction’s gas fees — then the transaction will fail and the entire Gas Budget will be charged. 
 
-The minimum Gas Budget is 2000 MIST. This ensures validators can be compensated with at least 2000 MIST even if the Gas Budget is mis-specified and transaction aborts. Additionally, this protects the Sui Network from being spammed with a large number of transactions with minimal gas budgets. The maximum Gas Budget is 50 billion MIST or 50 SUI. This protects the network against overflow of internal multiplications and gas limits for denial of service attack
-
-Finally, Sui’s [Storage mechanics](https://docs.sui.io/learn/tokenomics/storage-fund#storage-fund-rewards) provide storage fee rebates 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:
-
-$$
-\text{NetGasFees}[\tau]\ =\ \text{GasFees}[\tau]\ -\text{StorageRebate}[\tau]
-$$
-
-Since the Gas Budget applies to the totality of Gas Fees, it will often be the case that a transaction will only go through if the Gas Budget is considerably higher than the Net Gas Fees that a user ultimately pays.
+As mentioned above, the Storage Rebate currently equals 99% of the originally paid Storage Fees. Since the Gas Budget applies to the totality of Gas Fees, it will often be the case that a transaction will only go through if the Gas Budget is considerably higher than the Net Gas Fees that a user ultimately pays.
 
 ### Gas Budget Examples
 
@@ -58,3 +84,15 @@ These examples also showcase the importance of the Gas Budget. The minimum Gas B
 | Simple transaction storing 10 bytes and deleting data | 500 MIST | 1,000 | 75 MIST | 1,000 | 100,000 MIST | 575,000 MIST | 475,000 MIST |
 | Complex transaction storing 120 bytes | 1,000 MIST | 5,000 | 200 MIST | 12,000 | 0 MIST | 7,400,000 MIST | 7,400,000 MIST |
 | Complex transaction storing 120 bytes and deleting data | 500 MIST | 5,000 |  200 MIST | 12,000 | 5,000,000 MIST | 2,400,000 MIST | -100,000 MIST |
+
+
+
+
+
+
+
+
+![Gas Fees displayed on Sui Explorer](../../static/gas-fees-explorer.png "The Gas Fees section displayed on Sui Explorer")
+*The Gas Fees section for a transaction block displayed on Sui Explorer*
+
+

doc/src/navconfig.json

@@ -90,8 +90,8 @@
 						"fileName": "learn/tokenomics/gas-pricing"
 					},
 					{
-						"label": "Sui Gas Budgets",
-						"fileName": "learn/tokenomics/gas-budgets"
+						"label": "Gas in Sui",
+						"fileName": "learn/tokenomics/gas-in-sui"
 					},
 					{
 						"label": "Sui Storage Fund",