From 3f168017d82bc4ef08b1160d766223fded0fe408 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Thu, 22 Feb 2024 09:57:00 -0600 Subject: [PATCH 1/5] add an announcement bar about the docs merge, and supporting styles --- docusaurus.config.js | 4 ++++ src/css/custom.scss | 23 +++++++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/docusaurus.config.js b/docusaurus.config.js index f415ceda..407195f0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -85,6 +85,10 @@ const config = { themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ + announcementBar: { + id: 'announcementBar-migration', + content: "🎉️ We're moving!! 🎉️ We're merging the Soroban documentation into the Stellar Developers documentation. Please check this GH issue for progress and updates.", + }, image: 'img/meta.png', docs: { sidebar: { diff --git a/src/css/custom.scss b/src/css/custom.scss index c63fec03..c89bfb29 100644 --- a/src/css/custom.scss +++ b/src/css/custom.scss @@ -20,6 +20,7 @@ /* You can override the default Infima variables here. */ :root { + --site-primary-hue-saturation: 179 68%; --ifm-color-primary: #4daaa9; // --ifm-background-color: #ffffff; // --ifm-background-surface-color: #fafafa; @@ -49,6 +50,7 @@ /* For readability concerns, you should choose a lighter palette in dark mode. */ [data-theme="dark"] { + --site-primary-hue-saturation: 50 94%; --ifm-color-primary: #f9db4a; --ifm-color-secondary: #4daaa9; --ifm-navbar-background-color: #1b1b1d; @@ -177,3 +179,24 @@ select[data-testid="example-pairing-select"] { .sidebar-category-items-hidden ul { display: none !important; } + +/* Announcement Bar(s) */ + +div[class^='announcementBar_'] { + font-size: 18px; + + --site-announcement-bar-stripe-color1: hsl( + var(--site-primary-hue-saturation) 85% + ); + --site-announcement-bar-stripe-color2: hsl( + var(--site-primary-hue-saturation) 95% + ); + + background: repeating-linear-gradient( + 35deg, + var(--site-announcement-bar-stripe-color1), + var(--site-announcement-bar-stripe-color1) 20px, + var(--site-announcement-bar-stripe-color2) 10px, + var(--site-announcement-bar-stripe-color2) 40px + ); +} From 3f57b1fb5093503ab742a85cc5f171a56d6c16f5 Mon Sep 17 00:00:00 2001 From: shawn Date: Thu, 22 Feb 2024 08:03:52 -0800 Subject: [PATCH 2/5] updated link to rpc helm chart values (#738) --- docs/reference/rpc.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/rpc.mdx b/docs/reference/rpc.mdx index 384bb671..2f3cabec 100644 --- a/docs/reference/rpc.mdx +++ b/docs/reference/rpc.mdx @@ -226,10 +226,10 @@ This example of Helm chart usage highlights some key aspects: By default, this is disabled (`sorobanRpc.persistence.enabled=false`) and the RPC deployment will use ephemeral pod storage via `emptyDir`, which will likely be adequate for `futurenet` and `testnet` transaction volumes. However, it's worth highlighting the trade-off of not having storage limitations of the cluster enforced (likely below 100MB). -- Network presets are defined in [`values.yaml`](https://github.com/stellar/helm-charts/blob/main/charts/soroban-rpc/values.yaml), which currently sets network configuration specific to `futurenet`. You can override this default and use other "canned" `values.yaml` files which have been published for other networks. For example, there is a [`testnet-values.yaml`](https://github.com/stellar/helm-charts/blob/main/charts/soroban-rpc/testnet-values.yaml) file to configure the deployment of the RPC server with the `testnet` network. Include this `--values` parameter in your `helm install` to specify the desired network: +- Network presets are defined in [`values.yaml`](https://github.com/stellar/helm-charts/blob/main/charts/soroban-rpc/values.yaml), which currently sets network configuration specific to `futurenet`. You can override this default and use other "canned" `values.yaml` files which have been published for other networks. For example, there is a [`values-testnet.yaml`](https://github.com/stellar/helm-charts/blob/main/charts/soroban-rpc/values-testnet.yaml) file to configure the deployment of the RPC server with the `testnet` network. Include this `--values` parameter in your `helm install` to specify the desired network: ```bash ---values https://raw.githubusercontent.com/stellar/helm-charts/main/charts/soroban-rpc/testnet-values.yaml +--values https://raw.githubusercontent.com/stellar/helm-charts/main/charts/soroban-rpc/values-testnet.yaml ``` - Configuring RPC to use other custom networks can be accomplished by downloading the [`values.yaml`](https://github.com/stellar/helm-charts/blob/main/charts/soroban-rpc/values.yaml) locally and updating settings under `sorobanRpc.sorobanRpcConfig` and `sorobanRpc.coreConfig`. This is applicable when connecting to specific networks other than the existing files like `values.yaml` available, such as your own standalone network. Include the local `values.yaml` in `helm install`: From 927478f72bf56e48e399d4139bce13261a2996a8 Mon Sep 17 00:00:00 2001 From: Julian Martinez <73849597+Julian-dev28@users.noreply.github.com> Date: Thu, 22 Feb 2024 08:04:52 -0800 Subject: [PATCH 3/5] Add v20.2.0 release to `releases.mdx` (#737) * Update releases.mdx * use latest versions * add changelog * update title --- docs/releases.mdx | 102 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) diff --git a/docs/releases.mdx b/docs/releases.mdx index 657be50a..fe63090d 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -14,6 +14,108 @@ Release candidates are software releases that are also released to the [Testnet] [Testnet]: reference/networks.mdx +## Protocol 20 (February 5, 2024): Mainnet Edition (Phase 0) + +### Software + +| Software | Version | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| XDR | [8b9d623ef40423a8462442b86997155f2c04d3a1](https://github.com/stellar/rs-stellar-xdr/commit/8b9d623ef40423a8462442b86997155f2c04d3a1) | +| Soroban Environment | `v20.2.2` | +| Soroban Interface Version | `0` | +| Stellar Core | `v20.2.0` | +| Soroban Rust SDK | `v20.3.2` | +| Soroban CLI | `v20.3.0` | +| Soroban RPC | `v20.3.1` | +| Stellar Horizon | `v2.28.3` | +| Stellar Friendbot | `TBD` | +| Stellar Quickstart | `docker.io/stellar/quickstart:latest@sha256:8d6f6520ad3842042bfe4e271f8b2324ec2f128564487abedd3876cea83af4f1` | +| Stellar JS Stellar Base | [`v11.0.0`](https://github.com/stellar/js-stellar-base/releases/tag/v11.0.0) | +| Stellar JS Stellar SDK | [`v11.2.2`](https://github.com/stellar/js-stellar-sdk/releases/tag/v11.2.2) | +| Freighter | `5.16.0` | +| Laboratory | `v4.1.0` | +| Soroban React Payment dapp | `v3.0.0` | +| Soroban Mint Token dapp | `v3.0.0` | +| Soroban Swap Token dapp | `TBD` | +| Futurenet Network Passphrase | `Test SDF Future Network ; October 2022` | +| Testnet Network Passphrase | `Test SDF Network ; September 2015` | + +### Changelog + +#### XDR + +Run CI for the msrv and latest rust version +Backfill changes to next for json rendering +Bump XDR +Bump version to 20.1.0 + +#### Soroban Environment + +Allow small version-range wiggle room on curve25519-dalek to enable docs.rs nightly build +Bump version to 20.2.2 +Enable publish of soroban-simulation crate +Add a function to invoke host function 'end-to-end' in recording mode. +Bug 1283 asset code rendering +Use strkeys for contract IDs and addresses in diagnostic events. +Turn off wasm_reference_types in Wasmi +Prng tests +Remove ConversionError from ScVal/Val conversions +Tightening up metering in auth +Bump XDR to 20.1 +Allow negative fee1 kb low +Bump version to 20.2.0 +Cover various Symbol conversion code paths with various valid/invalid cases +Run CI for the msrv and latest rust version +Add protocol version method to invoke_contract +Enable VM execution in a WASM environment by guarding time track behind time feature +Add test for checking VM stack depth. +Migrate preflight computations from soroban-rpc +soroban-simulate: Misc fixes +Add CI job to run cargo-semver-checks +Tracing +Add some basic test coverage for e2e_invoke. +Add test vectors for ed25519 edge cases +Trace should not emit diagnostic errors +Bump wasmi to 0.31.1-soroban.20.0.1 +Bump version to 20.1.1 + +#### Soroban Rust SDK + +Update soroban-env-\* +Bump version to 20.3.2 +Update extend_ttl docs +Bug 1076 conversion error flattening + +#### Soroban RPC + +Migrate Soroban Tools to Soroban RPC +Use soroban-tools Crates +Pull in Recent Soroban RPC changes from soroban-tools +Mirror Last Remaining PRs from soroban-tools Repo +Add Workflow to Publish soroban-rpc Crate +added user agent config on ha archive pool +Update getTxn rpc with events data +Remove publish-dry-run Workflow +Use external soroban-simulation library for preflight computations +Store and serve the event transaction ID +Reduce event memory footprint +Add diagnostic events to sendTransaction response +Remove panics from internal codebase + +#### Soroban CLI + +feat: soroban init command +Bump dependencies for pubnet release +Upgrade Ubuntu to 22.04 from 20.04 +Bump Go, Rust and Core dependencies +feat/cli: Move config commands to top level +bindings-ts: update to latest SDK & TypeScript, add CI test +TypeScript bindings have been updated to use the latest stellar-sdk +Support multi-auth workflows in typescript bindings +Replace cli xdr command with stellar-xdr cli +Update typescript bindings for latest versions +Warn about RC versions only when using pubnet + ## Stable v20.1.0 (January 11, 2024) ### Software From 51705b5c0fcaf1b2c85f81ab797991a6aeea54d3 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Thu, 22 Feb 2024 12:01:55 -0600 Subject: [PATCH 4/5] Update resource limits and make a new reference page for them (#736) * 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 --- docs/reference/resource-limits-fees.mdx | 82 ++++++++++++++++++++ docs/soroban-internals/fees-and-metering.mdx | 46 +---------- 2 files changed, 86 insertions(+), 42 deletions(-) create mode 100644 docs/reference/resource-limits-fees.mdx diff --git a/docs/reference/resource-limits-fees.mdx b/docs/reference/resource-limits-fees.mdx new file mode 100644 index 00000000..b205aaf6 --- /dev/null +++ b/docs/reference/resource-limits-fees.mdx @@ -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 | diff --git a/docs/soroban-internals/fees-and-metering.mdx b/docs/soroban-internals/fees-and-metering.mdx index 0f8ecff7..bdaecc56 100644 --- a/docs/soroban-internals/fees-and-metering.mdx +++ b/docs/soroban-internals/fees-and-metering.mdx @@ -21,12 +21,6 @@ description: Smart contract fees and metering on Soroban. /> -:::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). @@ -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 @@ -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 @@ -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 From 941e9ce6f9a199420189d45d8097770b1d944129 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Thu, 22 Feb 2024 15:02:07 -0600 Subject: [PATCH 5/5] use by-name params in pagination example (#743) Refs: #728 --- api/pagination.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/api/pagination.mdx b/api/pagination.mdx index 3ac52f5a..3da84ce1 100644 --- a/api/pagination.mdx +++ b/api/pagination.mdx @@ -18,6 +18,12 @@ For example, calling a method with pagination parameter set: "jsonrpc": "2.0", "id": "1", "method": "exampleMethod", - "params": ["other", "arguments", { "cursor": "1234-1", "limit": 100 }] + "params": { + "some": "argument", + "pagination": { + "cursor": "1234-1", + "limit": 100 + } + } } ```