Update fee page, close #710 (#745)

* Update fee page, close #710 * Apply suggestions from code review Co-authored-by: Elliot Voris <[email protected]> Co-authored-by: Leigh McCulloch <[email protected]> --------- Co-authored-by: Jane Wang <[email protected]> Co-authored-by: Elliot Voris <[email protected]> Co-authored-by: Leigh McCulloch <[email protected]>
stellar-deprecated · Feb 23, 2024 · 92d404f · 92d404f
1 parent 0a6834b
commit 92d404f
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 15 deletions.
diff --git a/docs/soroban-internals/fees-and-metering.mdx b/docs/soroban-internals/fees-and-metering.mdx
@@ -4,6 +4,8 @@ title: Fees and Metering
 description: Smart contract fees and metering on Soroban.
 ---
 
+import soroban_fees from "../../static/img/soroban_fees.png";
+
 <head>
   <title>Smart contract fees and metering on Soroban.</title>
   <meta charSet="utf-8" />
@@ -13,7 +15,7 @@ description: Smart contract fees and metering on Soroban.
   />
   <meta
     property="og:description"
-    content="Learn about how the smart contract resource fees, resource limits, and metering system works on Soroban and methodology behind it."
+    content="Learn about how the smart contract resources fees, resource limits, and metering system works on Soroban and methodology behind it."
   />
   <link
     rel="canonical"
@@ -23,25 +25,33 @@ description: Smart contract fees and metering on Soroban.
 
 # Fee Model
 
-Executing a Soroban transaction on the Stellar network requires a fee. This measure helps prevent spam and allows multiple parties to compete for inclusion in the ledger in case of traffic surges. The fee is paid using the native Stellar token (lumens, also known as XLM).
+Executing a Soroban transaction on the Stellar network requires a fee. This measure helps prevent spam and allows multiple parties to compete for inclusion in the ledger in case of traffic surges. The fee is paid using the native Stellar token (Lumens, also known as XLM).
+
+## Transaction Fee
+
+The Soroban transaction fee is the sum of two parts:
 
-The Soroban transaction fee comprises two parts: the resource fee and the inclusion fee.
+- the Resource Fee
+- the Inclusion Fee
 
-The resource fee is the amount of lumens the submitter must pay for their transaction to be included in the ledger. It depends solely on the amount of resources the transaction needs for execution. There is no auction for the resource fee; it simply must be paid if the transaction is included in the ledger.
+`Transaction Fee (Tx.fee) = Resource Fee (sorobanData.resourceFee) + Inclusion Fee`
 
-The inclusion fee is the maximum fee bid the submitter is willing to pay for inclusion. It is used to prioritize transactions — the transaction with the higher inclusion fee is included in the ledger before those with lower inclusion fees. The inclusion fee can be discounted depending on the traffic. If the ledger is not at capacity, only the minimal base fee is charged (100 stroops or 10^-5 XLM). If the ledger is at capacity, then the lowest inclusion fee bid is charged. In general, the behavior of the inclusion fee and bidding strategies align with the [classic Stellar fees].
+![Soroban Fees](/img/soroban_fees.png)
+_\* Chart: Solid line boxes are what is actually present in the transaction, while dotted lines are derivable._
 
-[classic Stellar fees]: https://developers.stellar.org/docs/encyclopedia/fees-surge-pricing-fee-strategies
+### Inclusion Fee
 
-The remainder of this chapter focuses on resource fees, as they are specific to Soroban.
+- The inclusion fee is the maximum bid the submitter is willing to pay for inclusion of the transaction. The network uses market dynamics to decide which transaction to include in the ledger — transactions that offer a higher fee are included in the ledger before those with lower inclusion fees. Therefore, inclusion fee is used to prioritize transactions. The inclusion fee can be discounted depending on the traffic. If the ledger is not at capacity, only the minimal base inclusion fee is charged (100 stroops or 10^-5 XLM). If the ledger is at capacity, then the lowest inclusion fee bid is charged. In general, the behavior of the inclusion fee and bidding strategies align with the [classic Stellar fees](https://developers.stellar.org/docs/encyclopedia/fees-surge-pricing-fee-strategies).
 
-## Resource fee
+### Resource Fee
 
-Soroban uses a multi-dimensional fee model that charges fees for several resource types using network-defined rates. The resource fee is calculated based on the resource consumption declared in the transaction. If the transaction attempts to exceed the declared resource limit, it will fail. If the transaction uses fewer resources than declared, there will be no refunds, with a few exceptions.
+- The resource fee is the amount of Lumens the submitter must pay for their transaction to be executed. It depends solely on the amount of resources the transaction needs for execution. There is no auction for the resources fee; it simply must be paid if the transaction is included in the ledger.
+
+Soroban uses a multi-dimensional resource fee model that charges fees for several resource types using network-defined rates. The resources fee is calculated based on the resources consumption declared in the transaction. If the transaction attempts to exceed the declared resource limits, the transaction will fail. If the transaction uses fewer resources than declared, there will be no refunds, with a few exceptions.
 
 The resource fee depends on the following:
 
-- Instructions: the number of CPU instructions the transaction uses, metered by the Soroban host.
+- Instructions: The number of CPU instructions the transaction uses, metered by the Soroban host.
 - Ledger entry accesses: Reading or writing any single ledger entry (any storage key in the contract context).
 - Ledger I/O: The number of bytes read from or written to the ledger.
 - Transaction size: The size of the transaction submitted to the network in bytes.
@@ -52,13 +62,22 @@ Some parameters may contribute to multiple fee components. For example, the tran
 
 The implementation details for fee computation are provided by the following [library](https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-host/src/fees.rs). This library is used by the protocol to compute the fees and thus can be considered canonical. The resource fee rates may be updated based on network validator consensus.
 
-The best way to find the required fees for any Soroban transaction is to use the [`simulateTransaction` mechanism](contract-interactions/transaction-simulation.mdx).
+### Understanding the Resource Fee
+
+ResourceFee is calculated with a non-refundable fees portion and a refundable fees portion.
+`Resource Fee(sorobanData.resourceFee) = Non-refundable resource fees + Refundable resource fees`
 
-Currently defined fee rates can be found in [the "Resource Limits & Fees" page] in the Reference section.
+#### Non-refundable Fees
 
-### Refundable resources
+The non-refundable fees is calculated from CPU instructions, Read Bytes, Write Bytes, and Bandwidth (size of transaction including its signatures).
 
-Fees for events and return value, as well as rent fees are refundable, which means that they are a part of transaction's `refundableFee`. Refundable fees are charged from the source account before the transaction is executed and then refunded based on the actual usage. The transaction will fail if `refundableFee` is not enough to cover the actual resource usage though.
+#### Refundable Fees
+
+The refundable fees is calculated from rent, events, and return value. Refundable fees are charged from the source account before the transaction is executed and then refunded based on the actual usage. The transaction will fail if `refundableFee` is not enough to cover the actual resource usage though.
+
+### Where to find Resource Fee Info for the Transaction
+
+The best way to find the required resource fee for any Soroban transaction is to use the [`simulateTransaction`](contract-interactions/transaction-simulation.mdx) endpoint from the RPC, which enables you to send a preflight transaction that will return resource fees.
 
 ## Resource limits
 
@@ -115,4 +134,6 @@ During execution, whenever a component (a code block defining a cost type) is en
 
 If the contract execution concludes within the specified resource limits, the metered total of CPU instructions is recorded and utilized as the input for fee calculation. Note that while memory usage is not included in the fee computation, it is nevertheless subject to the resource limits.
 
-[the "Resource Limits & Fees" page]: ../reference/resource-limits-fees.mdx
+### Current Fee Rates
+
+Currently defined fee rates can be found in the [Resource Limits & Fees](../reference/resource-limits-fees.mdx) page.
diff --git a/static/img/soroban_fees.png b/static/img/soroban_fees.png