Skip to content
This repository has been archived by the owner on Aug 21, 2024. It is now read-only.

Commit

Permalink
Update resource limits and make a new reference page for them (#736)
Browse files Browse the repository at this point in the history 
* add a reference page on resource limits and fees

* remove resource fee/limit tables from "explainer" page

* removing some unnecessary comments and entries

Some of the comments are more applicable in the discussion doc,
than they are for developer documentation. So, let's get rid of
those.

* remove unnecessary "current is..." language from resource fees
  • Loading branch information
@ElliotFriend
ElliotFriend committed Feb 23, 2024
1 parent 927478f commit 51705b5
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 42 deletions.
82 changes: 82 additions & 0 deletions docs/reference/resource-limits-fees.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
sidebar_position: 35
title: Resource Limits & Fees
---

## Resource Limits

| Network Setting | Phase 0 (current) | Phase 1 |
| :------------------------------------------------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------- |
| Soroban Txn per ledger | 1 | 100 |
| Max CPU Instructions per Txn | 2.5 million (2M instructions for max Wasm) | 100 million (VM instantiation consumes up to 23M for a 64KB Wasm, and 46M for multiple Wasms of 130KB) |
| Memory limit per Txn | 2 MB | 40 MB |
| Ledger entry size (including Wasm entries) per Txn | 2 KB | 64 KB |
| Read/Write Ledger entries per Txn | 3 read; 2 write | 40 read; 25 write |
| Read/Write bytes per Txn | 3.2 KB read; 3.2 KB write | 130 KB read; 65 KB write |
| Transaction size | 10 KB | 70 KB |
| Persistent entry minimal/initial lifetime | 4,096 ledgers (~5.68 hours) | 120 days |
| Temporary entry minimal/initial lifetime | 16 ledgers | 1 day |
| Max ledger entry expiration bump | 61 days | 6 months |
| Events+return value size bytes | 200 B | 8 KB |

## Resource Fees

Note, that write fees grow linearly from empty ledger to ledger "target size", and then grow linearly, but with a 1000x factor after exceeding the target. This is to bound the ledger size growth.

The ledger rent cost ('Write 1KB' entries in the table) is based on the write fee, rent period and some coefficient. For the temporary storage, the coefficient is 10 months (in ledgers), thus 1 month of temporary entry rent is 1/10 of the rent fee. For persistent storage the coefficient is 1 month (in ledgers) and thus 1 month of rent is equivalent to the write fee.

### Phase 0 (current)

| Network Setting | Phase 0 Cost (stroops) |
| :-------------------------------------------- | :---------------------- |
| 10,000 instructions | 100 (1,000,000/tx) |
| Read 1 ledger entry | 1,000 (20,000/tx) |
| Write 1 ledger entry | 3,000 (30,000/tx) |
| Read 1KB from ledger | 1,000 (127,000/tx) |
| 1KB of transaction (bandwidth) | 500 (34,000/tx) |
| 1KB of transaction (history) | 5,000 (340,000/tx) |
| 1KB of Events/return value | 300 (1,500/tx) |
| “Target” ledger size | 14.5 GB |
| Fee multiplier after reaching the target size | 1,000 |
| Write 1KB to ledger (empty) | 1,000 |
| Write 1KB to ledger (current, 12 GB) | 0.356 XLM (17.4 XLM/tx) |
| Write 1KB to ledger (target, 14 GB) | 0.4 XLM (2.26 XLM/tx) |
| Temp entry rent period | 10 months |
| Persistent entry rent period | 1 month |
| 1 KB of temp storage per month | 400,000 |
| 1 KB of persistent storage per month | 4,000,000 |

### Phase 1

| Network setting | Phase 1 Cost (stroops) |
| :-------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
| 10,000 instructions | 25 (250,000/max tx) |
| Read 1 ledger entry | 6,250 (250,000/max tx) |
| Write 1 ledger entry | 10,000 (250,000/max tx) |
| Read 1KB from ledger | 1,786 (250,000/max tx) |
| 1KB of transaction size (bandwidth) | 1,624 (113,642/max tx) |
| 1KB of transaction size (history) | 16,235 (1,136,418/max tx) |
| 1KB of Events/return value | 10,000 (80,000/max tx) |
| “Target” ledger size | 13 GB |
| Fee multiplier after reaching the target size | 1,000 |
| Write 1KB to ledger, stroops (empty) | -1,234,673 (the write cost is always positive; this value is used only for the effective write fee computations) |
| Write 1KB to ledger, stroops (current, 12 GB) | 11,539 (750,000/max tx) |
| Write 1KB to ledger, stroops (target, 13 GB) | 115,390 (7,500,000/max tx) |
| Temp entry rent period, ledgers | 2,804 |
| Persistent entry rent period, ledgers | 1,402 |
| Minimum persistent entry TTL, ledgers | 2,073,600 (120 days) |
| Minimum temp entry TTL, ledgers | 17,280 (~1 day) |

## Phase 1 Examples

Here are some examples to put things in perspective (the fees are computed at "current" ledger size and would grow as ledger size increases):

| Scenario | Phase 1 Cost |
| :------------------------------------------------------------------------------------- | :----------- |
| Upload a new 64KB Wasm (includes 120 day rent payment) | 109.2 XLM |
| 1 year of 64KB Wasm storage rent | 327.7 XLM |
| Bump 64KB Wasm rent by 1 day | 0.91 XLM |
| Modify 64 KB contract data entry without increasing the size | 0.075 XLM |
| Create 100 byte contract data entry, e.g. user balance (includes 120 day rent payment) | 0.17 XLM |
| 1 year of 100 byte storage rent | 0.512 XLM |
| Modify 100 byte contract data entry without increasing the size | 1150 stroops |
46 changes: 4 additions & 42 deletions docs/soroban-internals/fees-and-metering.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,6 @@ description: Smart contract fees and metering on Soroban.
/>
</head>

:::caution

Soroban is still under active development. While the fee model described here is unlikely to change, the exact values of the fee rates and limits remain undetermined.

:::

# 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).
Expand Down Expand Up @@ -60,28 +54,7 @@ The implementation details for fee computation are provided by the following [li

The best way to find the required fees for any Soroban transaction is to use the [`simulateTransaction` mechanism](contract-interactions/transaction-simulation.mdx).

The fee rates are currently defined for the Testnet as follows:

| Description | Cost (stroops) |
| ----------------------------------------------------- | -------------- |
| 10000 CPU instructions | 100 |
| Read 1 ledger entry | 1000 |
| Write 1 ledger entry | 3000 |
| Read 1KB from ledger | 1000 |
| 1KB of transaction (bandwidth) | 500 |
| 1KB of transaction (history) | 5000 |
| 1KB of Events/return value | 300 |
| Write 1KB to empty ledger | 1000 |
| Write 1KB to 2GB ledger | 4_000_000 |
| Write 1KB to 4GB ledger | 4_000_000_000 |
| Store 1KB temp entry for 1 month (empty ledger) | 100 |
| Store 1KB temp entry for 1 month (2GB ledger) | 400_000 |
| Store 1KB persistent entry for 1 month (empty ledger) | 1000 |
| Store 1KB persistent entry for 1 month (2GB ledger) | 4_000_000 |

Note, that write fees grow linearly from empty ledger to 2 GB (ledger "target size"), and then grow linearly, but with a 1000x factor after exceeding the target. This is to bound the ledger size growth. As Testnet is a small, test network, the target size is set to just 2 GB.

The ledger rent cost ('Store 1KB' entries in the table) is based on the write fee, rent period and some coefficient. For the temporary storage, the coefficient is 10 months (in ledgers), thus 1 month of temporary entry rent is 1/10 of the rent fee. For persistent storage the coefficient is 1 month (in ledgers) and thus 1 month of rent is equivalent to the write fee.
Currently defined fee rates can be found in [the "Resource Limits & Fees" page] in the Reference section.

### Refundable resources

Expand All @@ -93,20 +66,7 @@ Ledger close time is constrained to a few seconds, thus preventing the execution

These resource limits may change in the Mainnet release. They can also be updated, usually increased, based on the network validator vote and consensus.

The current (Testnet) limits are as follows:

| Resource | Limit |
| -------------------------- | ----------- |
| CPU Instructions | 100,000,000 |
| RAM | 40 MB |
| Ledger Entry Reads | 30 |
| Ledger Entry Writes | 20 |
| Ledger Read Bytes | 130 KB |
| Ledger Write Bytes | 65 KB |
| Transaction Size | 70 KB |
| Events & return value size | 2 KB |
| Ledger entry size | 64 KB |
| Maximum TTL | 6 months |
Currently defined resource limits can be found in [the "Resource Limits & Fees" page] in the Reference section.

# Metering

Expand Down Expand Up @@ -154,3 +114,5 @@ Before contract execution, the host environment is prepared with the cost parame
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. 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

0 comments on commit 51705b5

Please sign in to comment.