From 56029b934f21aadc2e92d1411e72b4a7c15ba011 Mon Sep 17 00:00:00 2001
From: Bri <92327786+briwylde08@users.noreply.github.com>
Date: Tue, 26 Mar 2024 09:54:18 -0600
Subject: [PATCH 01/21] combine fees documentation
---
.../transaction-lifecycle.mdx | 1 -
.../fees-resource-limits-metering.mdx | 212 ++++++++++++++++++
static/assets/soroban_fees.png | Bin 0 -> 99373 bytes
3 files changed, 212 insertions(+), 1 deletion(-)
rename docs/learn/{fundamentals => encyclopedia}/transaction-lifecycle.mdx (99%)
create mode 100644 docs/learn/fundamentals/fees-resource-limits-metering.mdx
create mode 100644 static/assets/soroban_fees.png
diff --git a/docs/learn/fundamentals/transaction-lifecycle.mdx b/docs/learn/encyclopedia/transaction-lifecycle.mdx
similarity index 99%
rename from docs/learn/fundamentals/transaction-lifecycle.mdx
rename to docs/learn/encyclopedia/transaction-lifecycle.mdx
index 086aeb435..292a5aa8a 100644
--- a/docs/learn/fundamentals/transaction-lifecycle.mdx
+++ b/docs/learn/encyclopedia/transaction-lifecycle.mdx
@@ -1,6 +1,5 @@
---
title: Transaction Lifecycle
-sidebar_position: 65
---
:::note
diff --git a/docs/learn/fundamentals/fees-resource-limits-metering.mdx b/docs/learn/fundamentals/fees-resource-limits-metering.mdx
new file mode 100644
index 000000000..35b71234a
--- /dev/null
+++ b/docs/learn/fundamentals/fees-resource-limits-metering.mdx
@@ -0,0 +1,212 @@
+---
+title: Fees, Resource Limits, and Metering
+sidebar_position: 65
+---
+
+## Fees overview
+
+Stellar requires a fee for all transactions to make it to the ledger. This helps prevent spam and prioritizes transactions during traffic surges. All fees are paid using the native Stellar token, the [lumen (or XLM)](./lumens.mdx).
+
+There are two types of fees on Stellar:
+
+**Resource fee:** **_only applies to smart contract transactions_**. The amount the submitter must pay for their transaction to execute. This amount is based on a transaction’s resource consumption and the state of network storage (described in the [Storage Dynamic Pricing section](#dynamic-pricing-for-storage)). Read about resource fees [below](#resource-fee).
+
+**Inclusion fee:** the maximum amount the submitter is willing to pay for the transaction to be included in the ledger. Read more [below](#inclusion-fee).
+
+When competing for space on the ledger, smart contract transactions are _only_ competing with other smart contract transactions, and transactions that do not execute a smart contract are _only_ competing with other transactions that do not execute a smart contract.
+
+The lumens collected from transaction fees go into a locked account and are not given to or used by anyone.
+
+## Resource fee
+
+All smart contract transactions require a resource fee in addition to an inclusion fee:
+
+`Transaction Fee (Tx.fee) = Resource Fee (sorobanData.resourceFee) + Inclusion Fee`
+
+ _\* Chart: Solid line boxes are what is actually present in the transaction, while dotted lines are derivable._
+
+Smart contracts on Stellar use a multidimensional resource fee model that charges fees for several resource types using [network-defined rates](../../reference/resource-limits-fees.mdx). The resource fee is calculated based on the resource consumption declared in the transaction and can fluctuate based on a mutable storage write fee (more on that in the [Storage Dynamic Pricing section](#dynamic-pricing-for-storage) below). If the transaction attempts to exceed the declared resource limits, it will fail. If the transaction uses fewer resources than declared, there will be no refunds [(with a couple of exceptions)](#refundable-and-non-refundable-resource-fees).
+
+The resource fee depends on the following resources:
+
+- **Instructions:** the number of CPU instructions the transaction uses, metered by the host environment;
+- **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;
+- **Events & return value size:** the size of the events produced by the contract and the return value of the top-level contract function — both events and return value are included in transaction metadata;
+- **Ledger space rent** the payment for the ledger entry TTL extensions (i.e., rent payments) and rent payments for increasing ledger entry size. Refer to the [state archival] section for more information about smart contract rent.
+
+:::note
+
+Some parameters may contribute to multiple fee components. For example, the transaction size is charged for network propagation (as network bandwidth is limited) and for historical storage (as storing ledger history is not free).
+
+:::
+
+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 consensus from the network validators.
+
+Find current resource fees in the [Resource Limits & Fees](../../reference/resource-limits-fees.mdx) page in the Reference section.
+
+### Refundable and non-refundable resource fees
+
+The resource fee is calculated with a non-refundable fees portion and a refundable fees portion: `ResourceFee(sorobanData.resourceFee) = Non-refundable resource fee + Refundable resource fees`.
+
+**Non-refundable fees:** calculated from CPU instructions, read bytes, write bytes, and bandwidth (transaction size, including its signatures).
+
+**Refundable fees:** 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 actual usage. However, the transaction will fail if `refundableFee` is not enough to cover the actual resource usage.
+
+### Find a transaction’s resource fee
+
+The best way to find the required resource fee for any smart contract transaction is to use the [`simulateTransaction` endpoint](../smart-contract-internals/contract-interactions/transaction-simulation) from the RPC, which enables you to send a preflight transaction that will return the necessary resource values and resource fee.
+
+### Resource limitations
+
+:::note
+
+Only smart contract transactions are subject to resource limitations.
+
+:::
+
+Stellar’s ledger close time is constrained to a few seconds, preventing the execution of arbitrarily large transactions, regardless of the resource fees involved. All resources mentioned in the prior section are subject to a per-transaction limit. A transaction’s memory (RAM) is also capped, though not subject to any charge.
+
+Resource limits are determined by a validator vote and can be adjusted based on network usage and ecosystem needs with a validator consensus.
+
+Find current resource limits in the [Resource Limits & Fees](../../reference/resource-limits-fees.mdx) page in the Reference section.
+
+## Inclusion fee
+
+The inclusion fee is the maximum bid (a bid denotes a dynamic fee, meaning it varies based on certain network conditions) the submitter is willing to pay for the transaction to be included in the ledger. The inclusion fee equals the number of operations in the transaction multiplied by the effective base fee for the given ledger:
+
+inclusion fee = # of operations \* effective base fee
+
+**Effective base fee:** the fee required per operation for a transaction to make it to the ledger. This cannot be lower than 100 stroops per operation (the network minimum).
+
+**Stroop:** the smallest unit of a lumen, one ten-millionth of a lumen (.0000001 XLM).
+
+:::note
+
+Transactions can have up to 100 operations per transaction except for transactions that execute a smart contract. Smart contract transactions are only allowed one operation per transaction (unless the transaction is getting [fee-bumped](../encyclopedia/fee-bump-transactions.mdx); this would add another operation), and the limits are instead specified in CPU instructions and other limits.
+
+:::
+
+When you set a base fee for a transaction, you are specifying the maximum amount you are willing to pay per operation in that transaction. This doesn’t necessarily mean you’ll pay that amount. You’ll only be charged the lowest amount needed for your transaction to make it to the ledger. If network traffic is light and the number of submitted operations or transactions is below the network ledger limit (configured by validators: currently 1,000 "classic" Stellar operations and 100 smart contract transactions), you will only pay the network minimum (configured by validators, currently 100 stroops).
+
+Alternatively, your transaction may not make it to the ledger if the effective base fee is higher than your base fee bid. When network traffic exceeds the ledger limit, the network enters into [surge pricing mode](#surge-pricing), and your effective base fee becomes your maximum bid.
+
+Fees are deducted from the source account unless there is a fee-bump transaction that states otherwise. Learn about fee-bump transactions in the [Fee-Bump Transaction section](../encyclopedia/fee-bump-transactions.mdx).
+
+## Surge and dynamic pricing
+
+### Surge pricing
+
+The network can enter surge pricing mode under two circumstances: 1. when the number of operations submitted to a ledger exceeds the network capacity (on Mainnet: 1,000 operations for transactions that do not execute smart contracts), or 2. if there is competition between smart contract transactions for a particular resource (instructions, ledger entry accesses (reads and writes), ledger IO (bytes read and bytes written), and the total size of transactions to be applied). During this time, the network uses market dynamics to decide which transactions to include in the ledger. Transactions that offer a higher maximum base fee bid make it to the ledger first.
+
+During surge pricing mode, transactions are sorted based on their inclusion fee amount, and the user pays the minimum inclusion fee in their transaction set. For example, if there are five transactions with respective inclusion fees of 2, 3, 4, 4, and 5 XLM, and only four of them make it to the ledger, then all included transactions pay the inclusion fee of 3 XLM. If all five transactions made it to the ledger (which would take it out of surge pricing mode), each would pay the minimum inclusion fee of 100 stroops (.0001 XLM).
+
+If there are multiple transactions offering the same inclusion fee, but they cannot all fit into the ledger, transactions are picked randomly so that the total operations for the entire set don’t exceed 1,000. The rest of the transactions are pushed to the next ledger or discarded if they’ve been waiting for too long. If your transaction is discarded, Horizon will return a timeout error.
+
+:::note
+
+It is recommended to apply [ledger bounds](./stellar-data-structures/operations-and-transactions#ledger-bounds) or [time bounds](./stellar-data-structures/operations-and-transactions#time-bounds) to transactions — either your transaction makes it to the ledger or fails, depending on your time and/or ledger parameters.
+
+:::
+
+**You are more likely to pay a higher inclusion fee when submitting smart contract transactions.** Smart contract transactions have tighter ledger limits than transactions that don’t interact with smart contracts and will therefore experience surge pricing more often. You are more likely to pay your maximum inclusion fee bid or, at least, the minimum inclusion fee bid in your transaction set. So, you must plan your fee bidding strategy accordingly.
+
+### Dynamic pricing for storage
+
+Stellar’s storage database size is determined by two forces: the rate of addition (writes) and the rate of deletions (evictions). Stellar has set a ledger growth threshold to some constant (the `BucketListTargetSizeBytes` network parameter, implemented to prevent explosive state growth and subject to change based on validator vote). Because there is a fixed capacity, write fees are based on the ledger size and can alter dynamically based on that size.
+
+When the ledger size is large, there is a higher demand for storage space, which causes a higher write fee. Over time, entries are evicted, reducing the size and, thereby, reducing storage pricing. This fee model is designed as if the database represents the current demand for storage at any given instant.
+
+Write fees will grow gradually over time when the database size is below the ledger growth threshold and will grow linearly, but with a 1,000x factor after exceeding that threshold. This is a safeguard against spam and should not happen under normal circumstances.
+
+## Metering
+
+Metering is a mechanism in the host environment that accounts for the resource costs incurred during the execution of a smart contract. The outcomes of metering act as the canonical truth of a smart contract’s execution cost and serve as an input for fee computations.
+
+Stellar’s smart contract execution environment comprises a host and a guest. The host encapsulates shared functionalities for all contracts, including host objects, functions, and a Wasm interpreter (VM). The guest environment is where the compiled Wasm contract is interpreted and executed. A detailed discussion of these environments can be found in [Environment Concepts](https://developers.stellar.org/docs/learn/smart-contract-internals/environment-concepts).
+
+The division between the host and guest environments and their shared functionalities necessitates a unique approach to resource accounting. In particular, the resources required for executing Wasm instructions and running host functions must be accounted for uniformly, with costs in terms of CPU instructions and memory bytes.
+
+Consider two contracts: A and B, both comprising the same number of Wasm instructions. If Contract A repeatedly calls host functions for complex computations while Contract B executes pure arithmetic operations within the VM, Contract A should be more costly, and this difference should be accurately represented in the metering process.
+
+Metering ensures fairness, thwarts resource manipulation and attacks, and generates a deterministic and reproducible measure of runtime resource costs.
+
+### Methodology
+
+To maintain equivalence in metering between the host and guest, computation costs on both sides are expressed in terms of CPU instructions and memory bytes (representing CPU and RAM usage). Metering and limit-checking occur within the host environment, and pre-calibrated numerical models ensure results are deterministic.
+
+### Cost types
+
+Metering is segmented into host components, referred to as **cost types**. Each cost type can be viewed as a “meta instruction” symbolizing a specific host operation with a known complexity that depends on a runtime input. For instance, cost type `ComputeSha256Hash` represents the cost of computing the SHA256 hash of a byte array.
+
+:::info
+
+Execution of Wasm instructions is accounted for as a host cost type `WasmInsnExec`, which has a constant CPU cost per Wasm instruction. This methodology treats guest instructions and host executions equivalently.
+
+:::
+
+Find a complete list of host cost types and their definitions here: [`ContractCostType`](https://github.com/stellar/stellar-xdr/blob/e372df9f677961aac04c5a4cc80a3667f310b29f/Stellar-contract-config-setting.x#L92-L155).
+
+### Cost parameters
+
+Cost types are carefully selected to:
+
+1. Serve as comprehensive building blocks for all significant contract execution costs;
+2. Ensure each component cost increases at most linearly (i.e., constant or linear) with respect to its input. That is, y = a + bx, where y is the cost output, x is the input, and a & b are the constant and linear model parameters, respectively.
+
+Each cost type has a separate model for both resource types (CPU and memory).
+
+The parameters for each model, a and b, are calibrated and fitted offline against inputs of various sizes. The collection of all model cost parameters from the network configurable entries (see [ConfigSettingsEntry](https://github.com/stellar/stellar-xdr/blob/e372df9f677961aac04c5a4cc80a3667f310b29f/Stellar-contract-config-setting.x#L223-L226) can be updated through network consensus.
+
+### Metering process
+
+Before contract execution, the host environment is prepared with the cost parameters and a budget defining the resource limits. Metering is then implemented to measure the cumulative resource consumption during host execution.
+
+During execution, whenever a component (a code block defining a cost type) is encountered, the corresponding model computes the resource output from the runtime input and increments the meter accordingly. The meter checks the cumulative consumption against the budget limit. If the limit is exceeded, an error is produced, and execution is terminated.
+
+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. While memory usage is not included in the fee computation, it is nevertheless subject to the resource limits.
+
+## Inclusion fee pricing strategies
+
+There are three primary methods to deal with inclusion fee fluctuations and surge pricing:
+
+- [**Method 1:**](#set-the-highest-fee-youre-comfortable-paying) set the highest fee you’re comfortable paying. This does not mean that you’ll pay that amount on every transaction — you will only pay what’s necessary to get into the ledger. Under normal (non-surge) circumstances, you will only pay the standard fee even with a higher maximum fee set. This method is simple, convenient, and efficient but can still potentially fail.
+- [**Method 2:**](#fee-bumps-on-past-transactions) resubmit a transaction with a higher fee using a fee-bump transaction
+
+### Set the highest fee you’re comfortable paying
+
+In general, it’s a good idea to choose the highest fee you’re willing to pay per operation for your transaction to make it to the ledger. Wallet developers may want to offer users a chance to specify their own base fee, though it may make more sense to set a persistent global base fee that’s above the market rate since the average user probably doesn’t care if they’re paying 0.8 cents or 0.00008 cents.
+
+Remember that you’re more likely to pay your maximum fee bid with smart contract transactions.
+
+### Fee-bumps on past transactions
+
+Even with a liberal fee-paying policy, your transaction may fail to make it into the ledger due to insufficient funds or untimely surges. Fee-bump transactions can solve this problem. The following snippet shows you how to resubmit a transaction with a higher fee (as long as you have the original transaction envelope):
+
+
+
+```js
+// Let `lastTx` be some transaction that fails submission due to high fees, and
+// `lastFee` be the maximum fee (expressed as an int) willing to be paid by
+// `account` for `lastTx`.
+server.submitTransaction(lastTx).catch(function (error) {
+ if (isFeeError(error)) {
+ let bump = sdk.TransactionBuilder.buildFeeBumpTransaction(
+ account, // account that will PAY the new fee
+ lastFee * 10, // new fee
+ lastTx, // the (entire) failing transaction
+ server.networkPassphrase
+ );
+ bump.sign(someAccount);
+ return server.submitTransaction(bump);
+ }
+ // ...other error conditions...
+}).then(...);
+```
+
+
+
+Suppose you submit two distinct transactions with the same source account and sequence number; the second transaction is a fee-bump transaction. In that case, the second transaction will be included in the transaction queue, replacing the first transaction if and only if the fee bid of the second transaction is at least 10x the fee bid of the first transaction.
+
+This value can typically be found in the fee_charged field of the transaction response under the `tx_insufficient_fee` error case.
diff --git a/static/assets/soroban_fees.png b/static/assets/soroban_fees.png
new file mode 100644
index 0000000000000000000000000000000000000000..6d9c864d52955a9202adbefc67c2ebc873a68489
GIT binary patch
literal 99373
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