refactored fee mechanism (#1409)

Author: LandauRaz

components/Starknet/modules/architecture-and-concepts/pages/network-architecture/fee-mechanism.adoc

@@ -1,20 +1,66 @@
 [id="gas-and-transaction-fees"]
-= Gas and transaction fees
+= Fee mechanism
 :--auto-ids:
 
 This section describes fees that are paid on L2 starting in Starknet 0.13.0. For information about messaging fees that are paid on L1, see xref:network-architecture/messaging-mechanism.adoc#l1-l2-message-fees[L1 → L2 message fees].
 
+[#what_do_we_pay_for]
+== What do we price?
+
+At the time of writing, the following components are contributing to the transaction fee:
+
+* xref:#computation_without_builtins[Computational complexity]: The marginal cost of verifying the transaction on L1, measured in L1 gas.
+* xref:#onchain_data_components[Onchain data]: The cost of posting  the state diffs induced by the transaction to L1 (for more details, see xref:network-architecture/data-availability.adoc[data availability]). This is measured in L1 gas or L1 data gas, depending on whether or not the L2 block in which the transaction was included uses calldata or blobs.
+* L2→L1 messages: Messages sent to L1 are eventually sent to the Starknet core contract as L1 calldata by the sequencer; therefore L2 transaction that send L2->L1 messages incur an additional L1 gas cost.
+* L2 calldata, events and code: From Starknet 0.13.1 onwards, there is a per-byte (or per felt) price for L2 payloads. For more details, see xref:#l2_calldata[].
+
+== When is the fee charged?
+
+The fee is charged atomically with the transaction execution on L2. The Starknet OS injects a transfer of the fee-related ERC-20, with an amount equal to the fee paid, the sender equal to the transaction submitter, and the sequencer as a receiver.
+
+== Fee units
+
+Each transaction is associated with an estimate of the amount of gas used. Combining this estimate with the price of gas yields the estimated fee.
+
+For transactions prior to v3, the fee is denominated in WEI. For transactions v3 and later, the fee is denominated in STRK.
+
+[#fee_limitations]
+== Transaction Fee limits
+
+[#v3_fee_limitations]
+=== v3 transactions
+
+With v3 transactions, users specify the max amount and max price for each resource. At the time of writing, the only available resource is L1 gas. In the future, we will introduce L2 gas which will be used to price L2 work (as opposed to only charging for the proof verification in L1 gas, which is what happens today).
+
+[#deprecated_fee_limitations]
+=== Deprecated transactions (version < 3)
+
+With older transaction versions, users specify the maximum fee that they are willing to pay for a transaction.
+
+The only limitation on the sequencer, which is enforced by the Starknet OS, is that the actual fee charged is bounded by `max_fee`. While not enforced in the proof, the Starknet sequencer usually charges less than `max_fee`, as it charges in accordance with the above fee formula.
+
+[id="v3-fee-estimation"]
+== Estimating fees
+
+The fee of transactions can be estimated with using `starknet_estimateFee` API call, which is part of Starknet's API v0.7.0 and above. For more information, see the link:https://github.com/starkware-libs/starknet-specs/blob/v0.7.1/api/starknet_api_openrpc.json#L612[Starknet JSON RPC specification]. For more information on how to construct the appropriate `resource_bounds` based on the response of `starknet_estimateFee`, see link:https://community.starknet.io/t/starknet-v0-13-1-pre-release-notes/113664#sdkswallets-how-to-use-the-new-fee-estimates-7[How to use the new fee estimates?] on the Starknet community forum.
+
+[#fee_calculation]
+== Fee calculation
+
 [#overall_fee]
-== Overall transaction fee
+=== Overall
+
+This section shows the formula for determining a transaction's fee. The following sections describe how this formula was derived.
+
+[#blobs-vs-calldata]
+==== Blobs vs. calldata
 
 Starting with Starknet v0.13.1, Starknet distinguishes between blocks whose state diffs are sent to L1 as calldata and blocks whose state diffs are sent to L1 as blobs. The `l1_da_mode` property in the Starknet block header contains this information. The cost of computation remains the same on both options, but the cost related to data availability differs.
 
 [#overall_fee_blob]
-=== Overall transaction fee with blobs
+==== Overall fee with blobs
 
-This section shows the formula for determining a transaction's fee. The following sections describe how this formula was derived.
-
-The following formula describes the overall fee, stem:[F], for a transaction:
+The following formula describes the overall fee, stem:[F], for a transaction in blocks whose state diffs are sent to L1 as blobs:
 
 [stem]
 ++++
@@ -52,11 +98,9 @@ For more information, see xref:#l_2-l_1_messages[].
 * stem:[$\text{felt_size_in_bytes}$] is 32, which is the number of bytes required to encode a single STARK field element.
 
 [#overall_fee_calldata]
-=== Overall transaction fee with calldata
-
-This section shows the formula for determining a transaction's fee. The following sections describe how this formula was derived.
+==== Overall fee with calldata
 
-The following formula describes the overall fee, stem:[F], for a transaction:
+The following formula describes the overall fee, stem:[F], for a transaction in blocks whose state diffs are sent to L1 as calldata:
 
 [stem]
 ++++
@@ -84,55 +128,20 @@ where:
 * stem:[$240$] is the gas discount for updating the sender's balance, for the derivation of this number see xref:#storage_updates[].
 * stem:[$\text{contract_update_discount}$] is 312 gas, for the derivation of this discount see xref:#storage_updates[].
 
-== When is the fee charged?
-
-The fee is charged atomically with the transaction execution on L2. The Starknet OS injects a transfer of the fee-related ERC-20, with an amount equal to the fee paid, the sender equal to the transaction submitter, and the sequencer as a receiver.
-
-[#fee_limitations]
-== Transaction Fee limits
-
-[#v3_fee_limitations]
-=== v3 transactions
-
-With v3 transactions, users specify the max amount and max price for each resource. At the time of writing, the only available resource is L1 gas. In the future, we will introduce L2 gas which will be used to price L2 work (as opposed to only charging for the proof verification in L1 gas, which is what happens today).
-
-[#deprecated_fee_limitations]
-=== Deprecated transactions (version < 3)
-
-With older transaction versions, users specify the maximum fee that they are willing to pay for a transaction.
-
-The only limitation on the sequencer, which is enforced by the Starknet OS, is that the actual fee charged is bounded by `max_fee`. While not enforced in the proof, the Starknet sequencer usually charges less than `max_fee`, as it charges in accordance with the above fee formula.
-
-[#what_do_we_pay_for]
-== What do we price
-
-At the time of writing, the following components are contributing to the transaction fee:
-
-* xref:#computation_without_builtins[Computational complexity]: The marginal cost of verifying the transaction on L1, measured in L1 gas.
-* xref:#onchain_data_components[Onchain data]: The cost of posting  the state diffs induced by the transaction to L1 (for more details, see xref:network-architecture/data-availability.adoc[data availability]). This is measured in L1 gas or L1 data gas, depending on whether or not the L2 block in which the transaction was included uses calldata or blobs.
-* L2→L1 messages: Messages sent to L1 are eventually sent to the Starknet core contract as L1 calldata by the sequencer; therefore L2 transaction that send L2->L1 messages incur an additional L1 gas cost.
-* L2 calldata, events and code: From Starknet 0.13.1 onwards, there is a per-byte (or per felt) price for L2 payloads. For more details, see xref:#l2_calldata[].
-
-== Fee units
-
-Each transaction is associated with an estimate of the amount of gas used. Combining this estimate with the price of gas yields the estimated fee.
-
-For transactions prior to v3, the fee is denominated in WEI. For transactions v3 and later, the fee is denominated in STRK.
-
-[#fee_calculation]
-== Fee calculation
-
 [#calculation_of_gas_costs]
-=== Calculation of gas prices
+=== Gas
 
 Every 60 seconds, Starknet samples the base price of gas and data gas on L1.
 
 The price of gas on Starknet is set to the average of the last 60 gas price samples, plus 1 gwei.
 
 The price of data gas on Starknet is set to the average of the last 60 data gas price samples. The data gas price on Ethereum is derived from the value of `excess_blob_gas`. For more information, see link:https://github.com/ethereum/EIPs/blob/master/EIPS/eip-4844.md[EIP-4844].
 
+[#computation]
+=== Computation
+
 [#computation_without_builtins]
-=== Computation without builtins
+==== Without builtins
 
 Let's analyze the correct metric for measuring transaction complexity. For simplicity, we will ignore Cairo's builtins, and address them later.
 
@@ -144,7 +153,7 @@ Tracking the execution trace length associated with each transaction is simple.
 Each assertion over field elements, such as verifying addition/multiplication over the field, requires the same, constant number of trace cells, which is where our "no-builtins" assumption kicks in: Pedersen occupies more trace cells than addition. Therefore, in a world without builtins, the fee of the transaction stem:[$tx$] is correlated with stem:[$\text{TraceCells}[tx\]/L$].
 
 [#computation_with_builtins]
-=== Computation with builtins
+==== With builtins
 
 In the Cairo execution trace each builtin has its own slot, which is important to consider when determining the fee.
 
@@ -172,7 +181,7 @@ This safeguards fairness and prevents manipulation, ensuring integrity in proof
 ====
 
 [#calculation_of_computation_costs]
-=== Calculation of computation costs
+==== Overall
 
 For each transaction, the sequencer calculates a vector, `CairoResourceUsage`, that contains the following:
 
@@ -192,13 +201,12 @@ The sequencer charges only according to the limiting factor. Therefore the fee i
 
 where stem:[$k$] enumerates the Cairo resource components, that is the number of Cairo steps and builtins used.
 
-The weights are listed in the table xref:#gas_cost_per_cairo_step_or_builtin_step[].
+The weights are listed in the following table:
 
 [#gas_cost_per_cairo_step_or_builtin_step]
-.Amount of gas used per Cairo step or per each time a Cairo builtin is applied
-[width=80%,cols="1,2",options="header",stripes=even]
+[%autowidth.stretch,options="header"]
 |===
-| Step or builtin | Gas cost
+| Resource | Gas cost
 
 | Cairo step | 0.0025 gas/step
 | Pedersen | 0.08 gas/application
@@ -212,7 +220,7 @@ The weights are listed in the table xref:#gas_cost_per_cairo_step_or_builtin_ste
 
 
 [id="onchain_data_components"]
-=== Onchain data components
+=== Onchain data
 
 The onchain data associated with a transaction is composed of three parts
 
@@ -222,7 +230,7 @@ The onchain data associated with a transaction is composed of three parts
 * Declared classes (only relevant for `DECLARE` transactions, and adds two additional words)
 
 [#storage_updates]
-=== Onchain data: Storage updates
+==== Storage updates
 
 Whenever a transaction updates some value in the storage of some contract, the following data is sent to L1:
 
@@ -271,7 +279,7 @@ For example, if different transactions within the same block update the same sto
 ====
 
 [#l_2-l_1_messages]
-=== Onchain data: L2->L1 messages
+==== L2->L1 messages
 
 When a transaction that raises the `send_message_to_l1` syscall is included in a state update, the following data reaches L1:
 
@@ -301,7 +309,7 @@ Where:
 * stem:[$\text{l1_storage_write_cost}$] is 20,000 gas per message which is paid in order to store the message hash on the Starknet core contract. This recording of the message is what later enables the intended L1 contract to consume the message.
 
 [#deployed_contracts]
-=== Onchain data: Deployed contracts
+==== Deployed contracts
 
 When a transaction that raises the `deploy` syscall is included in a state update, the following data reaches L1:
 
@@ -312,7 +320,7 @@ When a transaction that raises the `deploy` syscall is included in a state updat
 The first two elements are counted in the number of unique modified contracts, denoted by stem:[$n$] throughout this page. So the only additional word comes from publishing the class hash, which adds 551 gas. For more information, see stem:[$\text{da_calldata_cost}$] in the xref:#overall_fee[final formula].
 
 [#l2_calldata]
-=== L2 payloads: calldata, events, and code
+=== L2 payloads
 
 As of Starknet v0.13.1 onwards, L2 data is taken into account during pricing. This includes:
 

components/Starknet/modules/architecture-and-concepts/pages/network-architecture/transactions.adoc

@@ -465,11 +465,6 @@ The generator used in the ECDSA algorithm is stem:[G=\left(g_x, g_y\right)] wher
 
 stem:[g_x=874739451078007766457464989774322083649278607533249481151382481072868806602] stem:[g_y=152666792071518830868575557812948353041420400780739481342941381225525861407]
 
-[id="v3-fee-estimation"]
-== v3 transaction fee estimation
-
-Estimate the fees of transactions with the `starknet_estimateFee` API call, which is part of Starknet's API v0.7.0 and above. For more information, see the link:https://github.com/starkware-libs/starknet-specs/blob/v0.7.1/api/starknet_api_openrpc.json#L612[Starknet JSON RPC specification]. For more information on how to construct the appropriate `resource_bounds` based on the response of `starknet_estimateFee`, see link:https://community.starknet.io/t/starknet-v0-13-1-pre-release-notes/113664#sdkswallets-how-to-use-the-new-fee-estimates-7[How to use the new fee estimates?] on the Starknet community forum.
-
 [id="chain-id"]
 == Chain ID