Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/build/guides/archival/test-ttl-extension.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ fn create_env() -> Env {
}
```

You could also use the current [network settings](../../../networks/resource-limits-fees.mdx#resource-fees) when setting up the tests, but keep in mind that these are subject to change, and the contract should be able to work with any values of these settings.
You could also use the current [network settings](https://lab.stellar.org/network-limits) when setting up the tests, but keep in mind that these are subject to change, and the contract should be able to work with any values of these settings.

Now we run a test scenario that verifies the TTL extension logic (see [`test_extend_ttl_behavior`](https://github.com/stellar/soroban-examples/blob/v23.0.0/ttl/src/test.rs#L38) test for the full scenario). First, we setup the data and ensure that the initial TTL values correspond to the network settings we've defined above:

Expand Down
4 changes: 2 additions & 2 deletions docs/build/guides/storage/choosing-the-right-storage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ Like persistent storage, instance storage stores data permanently. However, it h

- Pro: Data TTL is tied to the contract instance, thus making state archival behavior much easier
- Pro/Con: Data is loaded automatically together with the contract, thus reducing the transaction footprint size, but increasing the number of bytes read every time the contract is loaded (_usually_ this still will result in a lower fee)
- Con: The total size of all the keys and values in the instance storage is limited by the ledger entry size limit. See the current value of the limit [here](../../../networks/resource-limits-fees.mdx). The total number of keys supported is on the order of tens to hundreds depending on the underlying data size and the current network limit. Keep in mind, that the network limit can never go down, so the instance can't ever become non-valid.
- Con: The total size of all the keys and values in the instance storage is limited by the ledger entry size limit. See the current value of the limit [on the Stellar Lab](https://lab.stellar.org/network-limits). The total number of keys supported is on the order of tens to hundreds depending on the underlying data size and the current network limit. Keep in mind, that the network limit can never go down, so the instance can't ever become non-valid.

Instance storage is best suited for data that has a well-known size limit and is either very small, or is necessary for every contract invocation. For example, contract administrator entry (small and should be maintained together with the contract instance), or a token pair for a liquidity pool (necessary for almost every operation on a liquidity pool).

Expand Down Expand Up @@ -133,7 +133,7 @@ impl LoyaltyPointsContract {

As the name implies, temporary storage stores data only for a certain time period, and then discards it automatically when TTL expires. **Temporary entries are gone forever when their TTL expires**.

The benefit of temporary storage is the smaller cost and the ability to set a very low TTL, both of which result in lower rent fees compared to persistent storage. See the current information on the minimal lifetimes and rent fees [here](../../../networks/resource-limits-fees.mdx).
The benefit of temporary storage is the smaller cost and the ability to set a very low TTL, both of which result in lower rent fees compared to persistent storage. See the current information on the minimal lifetimes and rent fees [on the Stellar Lab](https://lab.stellar.org/network-limits).

Temporary storage is suitable for data that is only necessary for a relatively short and well-defined time period. 'Well-defined' here means that when creating an entry, the contract should be able to define its maximum necessary TTL.

Expand Down
2 changes: 1 addition & 1 deletion docs/data/apis/horizon/api-reference/structure/xdr.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ When you post a transaction, a client will encode the transaction as XDR before

When you request a transaction, Horizon returns some data about the transaction in human-readable JSON. The full canonical data about the transaction is encoded in machine-readable XDR, available in XDR attributes at the end of the response.

You can decode this XDR in the Stellar Lab’s [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;).
You can decode this XDR on the Stellar Lab’s [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;).

<AttributeTable>

Expand Down
2 changes: 1 addition & 1 deletion docs/data/apis/rpc/api-reference/structure/data-format.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ In the Stellar network, transactions are encoded using a standardized protocol c

In RPC, you will encounter XDR when [simulating](../methods/simulateTransaction) and [sending](../methods/sendTransaction) transactions, as well as when retrieving [transactions](../methods/getTransactions), [ledgers](../methods/getLedgers), and [ledger entries](../methods/getLedgerEntries).

By default, RPC will return all XDR attributes as the machine-readable base64-encoded string. XDR-encoded response fields are usually suffixed with `Xdr`. You can decode this XDR in the Stellar Lab’s [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;).
By default, RPC will return all XDR attributes as the machine-readable base64-encoded string. XDR-encoded response fields are usually suffixed with `Xdr`. You can decode this XDR on the Stellar Lab’s [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;).

### JSON Format

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ In addition to the types of state, it is also helpful to consider the type of co
### Best Practices

- Prefer `Temporary` over `Persistent` and `Instance` storage
- Anything that can have a timeout should be `Temporary` with TTL set to the timeout. See the [resource limits table](../../../../networks/resource-limits-fees.mdx) for the current maximum TTL/timeout.
- Anything that can have a timeout should be `Temporary` with TTL set to the timeout. See the [resource limits table](https://lab.stellar.org/network-limits) on the Stellar Lab for the current maximum TTL/timeout.
- Ideally, `Temporary` entries should be associated with an absolute ledger boundary and thus never need a TTL extension
- Example: Soroban Auth signatures have an absolute expiration ledger, so nonces can be stored in `Temporary` entries without security risks
- Example: SAC allowance that lives only until a given ledger (so that some old allowance signature can not be used in the future if not exhausted)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -111,11 +111,11 @@ An entry's Time To Live (TTL) is defined as how many ledgers remain until the en

For each entry type, there is a minimum TTL that the entry will have when being created or restored. This TTL minimum is enforced automatically at the protocol level.

Minimum TTL is a network parameter. Refer to the [resource reference](../../../../networks/resource-limits-fees.mdx) to find the current values.
Minimum TTL is a network parameter. Refer to the [resource reference](https://lab.stellar.org/network-limits) on the Stellar Lab to find the current values.

### Maximum TTL

On any given ledger, an entry's TTL can be extended up to the maximum TTL. This is a network parameter (see the [resource limits table](../../../../networks/resource-limits-fees.mdx) for the current maximum TTL). Maximum TTL is not enforced based on when an entry was created, but based on the current ledger. For example, if an entry is created on January 1st, 2024, its TTL could initially be extended up to January 1st, 2025. After this initial TTL extension, if the entry received another TTL extension later on January 10th, 2024, the TTL could be extended up to January 10th, 2025. The `max_ttl()` function can be used to determine the current maximum allowed TTL.
On any given ledger, an entry's TTL can be extended up to the maximum TTL. This is a network parameter (see the [resource limits table](https://lab.stellar.org/network-limits) on the Stellar Lab for the current maximum TTL). Maximum TTL is not enforced based on when an entry was created, but based on the current ledger. For example, if an entry is created on January 1st, 2024, its TTL could initially be extended up to January 1st, 2025. After this initial TTL extension, if the entry received another TTL extension later on January 10th, 2024, the TTL could be extended up to January 10th, 2025. The `max_ttl()` function can be used to determine the current maximum allowed TTL.

## Operations

Expand Down
6 changes: 3 additions & 3 deletions docs/learn/fundamentals/fees-resource-limits-metering.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Transactions that do not execute a smart contract can be thought of as having a

![Soroban Fees](/assets/diagrams/soroban_fees.png) _\* Diagram: 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](../../networks/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).
Smart contracts on Stellar use a multidimensional resource fee model that charges fees for several resource types using [network-defined rates](https://lab.stellar.org/network-limits) on the Stellar Lab. 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:

Expand All @@ -50,7 +50,7 @@ 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 consensus from the network validators.

Find current resource fees in the [Resource Limits & Fees](../../networks/resource-limits-fees.mdx) page in the Networks section.
Find current resource fees in the [Resource Limits & Fees](https://lab.stellar.org/network-limits) on the Stellar Lab.

For help in analyzing smart contract cost and efficiency, see this [How-To Guide](../../build/guides/fees/analyzing-smart-contract-cost.mdx).

Expand Down Expand Up @@ -78,7 +78,7 @@ Stellar’s ledger close time is constrained to a few seconds, preventing the ex

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](../../networks/resource-limits-fees.mdx) page in the Networks section.
Find current resource limits in the [Resource Limits & Fees](https://lab.stellar.org/network-limits) on the Stellar Lab.

## Inclusion fee

Expand Down
75 changes: 9 additions & 66 deletions docs/networks/resource-limits-fees.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,75 +3,18 @@ sidebar_position: 30
title: Resource Limits & Fees
---

:::info
## Where to find the current resource limits and fees

The values below are for reference. For current resource limits and fees on the live network, see Stellar Lab's [Network Limits](https://lab.stellar.org/network-limits) page.
### [Stellar Lab](https://lab.stellar.org/)

:::
The Stellar Lab's [Network Limits](https://lab.stellar.org/network-limits) page displays real-time network settings for [Testnet](https://lab.stellar.org/network-limits?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;), [Mainnet](https://lab.stellar.org/network-limits?$=network$id=mainnet&label=Mainnet&horizonUrl=https:////horizon.stellar.org&rpcUrl=https:////mainnet.sorobanrpc.com&passphrase=Public%20Global%20Stellar%20Network%20/;%20September%202015;;), and [Futurenet](https://lab.stellar.org/network-limits?$=network$id=futurenet&label=Futurenet&horizonUrl=https:////horizon-futurenet.stellar.org&rpcUrl=https:////rpc-futurenet.stellar.org&passphrase=Test%20SDF%20Future%20Network%20/;%20October%202022;;). The page offers both `table` and `JSON` display options for easy viewing.

## Resource Limits
### [Stellar CLI](https://github.com/stellar/stellar-cli)

:::note
You can also query current network settings directly from the command line using:

Resource limitations and fees only apply to smart contract transactions. Read more about the inner workings of fees on Stellar in the [Fees section](../learn/fundamentals/fees-resource-limits-metering.mdx).
```bash
stellar network settings
```

:::

### Per-transaction limits

These define the maximum amount of work a single Smart contract transaction can do.

| Network Setting | Value |
| ----------------------------------------------------- | ------------------ |
| Max CPU instructions | 100 million |
| Max memory (RAM) | 40 MB |
| Max number of keys in the footprint | 100 |
| Disk reads\* | 100 entries/200 KB |
| Disk writes | 50 entries/132 KB |
| Transaction size | 132 KB |
| Events+return value size bytes | 16 KB |
| Individual ledger key size (contract storage key) | 250 bytes |
| Individual ledger entry size (including Wasm entries) | 128 KiB |

\* Most transactions don't perform any disk reads, as only archived entries and 'classic' entries (G-accounts, trustlines) are considered to be disk reads. Live smart contract state is in-memory and is not counted towards this limit.

### TTL extension parameters

These define TTL extension parameters.

| Network Setting | Value |
| -------------------------------- | -------- |
| Persistent entry TTL on creation | 120 days |
| Temporary entry TTL on creation | 1 day |
| Max ledger entry TTL extension | 6 months |

### Ledger-wide limits

These define the maximum amount of work done by all the transactions in a single ledger (single block).

| Network Setting | Value |
| ----------------------------------- | ------------------ |
| Max CPU instructions | 600 million |
| Max memory (RAM) | no explicit limit |
| Max number of keys in the footprint | no explicit limit |
| Disk reads | 1000 entries/7 MB |
| Disk writes | 500 entries/143 KB |
| Transactions size | 133 KB |
| Events+return value size bytes | no explicit limit |

## Resource Fees

| Network Setting | Cost (stroops) |
| :--------------------------------------------- | :------------------------ |
| 10,000 CPU instructions | 25 (250,000/max tx) |
| Read 1 ledger entry from disk | 6,250 (625,000/max tx) |
| Read 1KB from disk | 1,786 (357,200/max tx) |
| Write 1 ledger entry | 10,000 (500,000/max tx) |
| Write 1KB to disk | 3,500 (462'000/max tx) |
| 1KB of transaction size (bandwidth) | 1,624 (214,368/max tx) |
| 1KB of transaction size (history) | 16,235 (2,143,020/max tx) |
| 1KB of Events/return value | 10,000 (160,000/max tx) |
| 30 days of rent for 1 KB of persistent storage | ~427,000 |
| 30 days of rent for 1 KB of temporary storage | ~213,500 |

Note, that the rent fees provided here may go up in case if a lot of contract data is written to the ledger within a short time period. This happens because the rent fees are designed in such a way that the closer the state size to some validator-defined threshold, the more expensive it gets to write new data or extend the TTLs.
For more details on using this command, see the [Stellar CLI documentation](https://developers.stellar.org/docs/tools/cli/stellar-cli#stellar-network-settings).
12 changes: 6 additions & 6 deletions docs/networks/software-versions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -458,8 +458,8 @@ This is the first version of the Soroban SDK that supports protocol 21. It is ma
| XDR | [3da6ebcbd8afa01d5c94dbc7f0475f4c00089420](https://github.com/stellar/rs-stellar-xdr/commit/3da6ebcbd8afa01d5c94dbc7f0475f4c00089420) |
| Soroban Environment | `v20.2.2` |
| Soroban Interface Version | `0` |
| Soroban Resource Limits | [Phase 2 Limits](./resource-limits-fees.mdx#resource-limits) |
| Soroban Resource Fees | [Phase 2 Fees](./resource-limits-fees.mdx#resource-fees) |
| Soroban Resource Limits | Phase 2 Limits |
| Soroban Resource Fees | Phase 2 Fees |
| Stellar Core | `v20.3.0` |
| Soroban Rust SDK | `v20.4.0` |
| Soroban CLI | `v20.3.1` |
Expand Down Expand Up @@ -521,8 +521,8 @@ This is the first version of the Soroban SDK that supports protocol 21. It is ma
| XDR | [8b9d623ef40423a8462442b86997155f2c04d3a1](https://github.com/stellar/rs-stellar-xdr/commit/8b9d623ef40423a8462442b86997155f2c04d3a1) |
| Soroban Environment | `v20.2.2` |
| Soroban Interface Version | `0` |
| Soroban Resource Limits | [Phase 1 Limits](./resource-limits-fees.mdx#resource-limits) |
| Soroban Resource Fees | [Phase 1 Fees](./resource-limits-fees.mdx#resource-fees) |
| Soroban Resource Limits | Phase 1 Limits |
| Soroban Resource Fees | Phase 1 Fees |
| Stellar Core | `v20.2.0` |
| Soroban Rust SDK | `v20.3.2` |
| Soroban CLI | `v20.3.1` |
Expand Down Expand Up @@ -585,8 +585,8 @@ This is the first version of the Soroban SDK that supports protocol 21. It is ma
| XDR | [8b9d623ef40423a8462442b86997155f2c04d3a1](https://github.com/stellar/rs-stellar-xdr/commit/8b9d623ef40423a8462442b86997155f2c04d3a1) |
| Soroban Environment | `v20.2.2` |
| Soroban Interface Version | `0` |
| Soroban Resource Limits | [Phase 0 Limits](./resource-limits-fees.mdx#resource-limits) |
| Soroban Resource Fees | [Phase 0 Fees](./resource-limits-fees.mdx#resource-fees) |
| Soroban Resource Limits | Phase 0 Limits |
| Soroban Resource Fees | Phase 0 Fees |
| Stellar Core | `v20.2.0` |
| Soroban Rust SDK | `v20.3.2` |
| Soroban CLI | `v20.3.0` |
Expand Down