Adding Soroban to Stellar Fundamentals

api/horizon/introduction/index.mdx

@@ -16,7 +16,7 @@ Horizon is a [RESTful API](https://en.wikipedia.org/wiki/Representational_state_
 The Stellar Development Foundation (SDF) runs two instances of Horizon:
 
 - [https://horizon.stellar.org/](https://horizon.stellar.org/) for interacting with the public network
-- [https://horizon-testnet.stellar.org/](https://horizon-testnet.stellar.org/) for interacting with the [testnet](/docs/fundamentals-and-concepts/testnet-and-pubnet)
+- [https://horizon-testnet.stellar.org/](https://horizon-testnet.stellar.org/) for interacting with the [testnet](/docs/fundamentals-and-concepts/networks)
 
 <MethodTable title="API Reference Sections">
 

docs/fundamentals-and-concepts/list-of-operations.mdx

@@ -685,20 +685,56 @@ Note that Soroban transactions can only contain one operation per transaction.
 
 Learn more in the [Soroban docs](https://soroban.stellar.org/docs/fundamentals-and-concepts/invoking-contracts-with-transactions#invokehostfunctionop).
 
-## Bump Footprint Expiration
+**Threshold**: Medium  
+**Result**: `InvokeHostFunctionResult`  
+**Parameters**:
+
+| Parameters | Type | Description |
+| --- | --- | --- |
+| Host Function | HostFunction | The host function to invoke |
+| Auth | Soroban Authorization Entry | Per-address authorizations for this host function. |
+
+**Possible errors**:
+
+| Error | Code | Description |
+| --- | --- | --- |
+| INVOKE_HOST_FUNCTION_MALFORMED | -1 | One or more of the inputs to the operation was malformed. |
+| INVOKE_HOST_FUNCTION_TRAPPED | -2 | The function invocation trapped in the Soroban runtime. |
+| INVOKE_HOST_FUNCTION_RESOURCE_LIMIT_EXCEEDED | -3 | The function invocation could not complete within the currently configured resource constraints of the network. |
+| INVOKE_HOST_FUNCTION_ENTRY_ARCHIVED | -4 | A ledger entry required for this function's footprint is in an archived state, and must be restored. |
+| INVOKE_HOST_FUNCTION_INSUFFICIENT_REFUNDABLE_FEE | -5 | The refundable Soroban fee provided was not sufficient to pay for the compute resources required by this function invocation. |
+
+## Extend Footprint TTL
 
 :::info
 
 Soroban is currently live on Testnet, so this operation is only usable on Testnet.
 
 :::
 
-Bump the expiration ledger of entries for Soroban smart contracts with the `BumpFootprintExpirationOp`.
+Extend the time to live (TTL) of entries for Soroban smart contracts with the `ExtendFootprintTTLOp`. This operation extends the TTL of the entries specified in the `readOnly` footprint of the transaction so that they will live at least until the `extendTo` ledger sequence number is reached.
 
 Note that Soroban transactions can only contain one operation per transaction.
 
 Learn more in the [Soroban docs](https://soroban.stellar.org/docs/fundamentals-and-concepts/state-expiration#bumpfootprintexpirationop).
 
+**Threshold**: Medium  
+**Result**: `ExtendFootprintTTLResult`  
+**Parameters**:
+
+| Parameters | Type | Description |
+| --- | --- | --- |
+| Ext | ExtensionPoint | Reserved for later use. |
+| Extend To | integer | The ledger sequence number the entries will live until. |
+
+**Possible errors**:
+
+| Error | Code | Description |
+| --- | --- | --- |
+| EXTEND_FOOTPRINT_TTL_MALFORMED | -1 | One or more of the inputs to the operation was malformed. |
+| EXTEND_FOOTPRINT_TTL_RESOURCE_LIMIT_EXCEEDED | -2 | The TTL extension could not be completed within the currently configured resource constraints of the network. |
+| EXTEND_FOOTPRINT_TTL_INSUFFICIENT_REFUNDABLE_FEE | -3 | The refundable Soroban fee provided was not sufficient to pay for TTL extension of the specified ledger entries. |
+
 ## Restore Footprint
 
 :::info
@@ -707,8 +743,24 @@ Soroban is currently live on Testnet, so this operation is only usable on Testne
 
 :::
 
-Make expired Soroban smart contract entries accessible again by restoring them with `RestoreFootprintOp`.
+Make archived Soroban smart contract entries accessible again by restoring them with `RestoreFootprintOp`. This operation restores the archived entries specified in the `readWrite` footprint.
 
 Note that Soroban transactions can only contain one operation per transaction.
 
 Learn more in the [Soroban docs](https://soroban.stellar.org/docs/fundamentals-and-concepts/state-expiration#restorefootprintop).
+
+**Threshold**: Medium  
+**Result**: `RestoreFootprintResult`  
+**Parameters**:
+
+| Parameters | Type           | Description             |
+| ---------- | -------------- | ----------------------- |
+| Ext        | ExtensionPoint | Reserved for later use. |
+
+**Possible errors**:
+
+| Error | Code | Description |
+| --- | --- | --- |
+| RESTORE_FOOTPRINT_MALFORMED | -1 | One or more of the inputs to the operation was malformed. |
+| RESTORE_FOOTPRINT_RESOURCE_LIMIT_EXCEEDED | -2 | The archive restoration could not be completed within the currently configured resource constraints of the network. |
+| RESTORE_FOOTPRINT_INSUFFICIENT_REFUNDABLE_FEE | -3 | The refundable Soroban fee provided was not sufficient to pay for archive restoration of the specified ledger entries. |

docs/fundamentals-and-concepts/lumens.mdx

@@ -3,22 +3,28 @@ title: Lumens (XLM)
 sidebar_position: 60
 ---
 
-Lumens (XLM) are the native currency of the Stellar network. The lumen is the only token that doesn’t require an issuer or trustline, and it pays all transaction fees and covers minimum balances on the network.
+Lumens (XLM) are the native currency of the Stellar network. The lumen is the only token that doesn’t require an issuer or trustline, and it is used to pay all transaction fees, rent, and covers minimum balances on the network.
 
 To read up on the basics of lumens, head over to our Stellar Learn site: [Stellar Learn: Lumens](https://www.stellar.org/lumens)
 
 ## Transaction fees
 
 Stellar requires a small fee for all transactions to prevent ledger spam and prioritize transactions during surge pricing. Transaction fees are paid in lumens.
 
-To learn about fees on Stellar, see our [Fees, Surge Pricing, and Fee Strategies Encyclopedia Entry](../encyclopedia/fees-surge-pricing-fee-strategies)
+To learn about fees on Stellar, see our [Fees, Surge Pricing, and Fee Strategies Encyclopedia Entry](../encyclopedia/fees-surge-pricing-fee-strategies).
+
+Smart contract transactions on Stellar employ a different fee structure based on an inclusion fee and resource consumption (which includes [rent](#rent)). Read more in the [Fees and Metering section](https://soroban.stellar.org/docs/fundamentals-and-concepts/fees-and-metering) in the Soroban docs.
 
 ## Base reserves
 
 A unit of measurement used to calculate an account’s minimum balance. One base reserve is currently 0.5 XLM.
 
 Validators can vote to change the base reserve, but that’s uncommon and should only happen every few years.
 
+## Rent
+
+Smart contract data does not require any base reserves in order to live on the ledger, so every smart contract entry must pay rent instead. The rent charged for an entry to exist on the ledger is based on how big the entry is and how long the it should be live on the ledger before being archived. There are different rent requirements for each storage type `Persistent`, `Temporary`, and `Instance`, which you can read about in the [Fees and Metering section](https://soroban.stellar.org/docs/fundamentals-and-concepts/fees-and-metering#refundable-resources) of the Soroban docs.
+
 ## Minimum balance
 
 Stellar accounts must maintain a minimum balance to exist, which is calculated using the base reserve. An account must always maintain a minimum balance of two base reserves (currently 1 XLM). Every subentry after that requires an additional base reserve (currently 0.5 XLM) and increases the account’s minimum balance. Subentries include trustlines (for both traditional assets and pool shares), offers, signers, and data entries. An account cannot have more than 1,000 subentries.

docs/fundamentals-and-concepts/networks.mdx

@@ -0,0 +1,103 @@
+---
+title: Networks
+sidebar_position: 30
+---
+
+Stellar has three networks: the public network (Mainnet, also called Pubnet or the Public Network), the test network (Testnet), and a dev network (Futurenet). Mainnet is the main network used by applications in production. It connects to real financial rails and requires XLM to cover minimum balances, transaction fees, and rent. The Testnet is a smaller, free-to-use network maintained by SDF that functions like the Mainnet but doesn’t connect to real money. It has a built-in testnet XLM faucet (called Friendbot), and it's the best place for developers to test their applications. Futurenet is a dev network you can use to test more bleeding edge features that also has access to its own Friendbot.
+
+## Stats: Mainnet versus Testnet versus Futurenet
+
+### Mainnet
+
+- Validator nodes are run by the public
+- SDF offers a free [Horizon instance](https://horizon.stellar.org/) to interact with the Mainnet with a limited set of history, or you can [run your own](https://developers.stellar.org/docs/run-api-server)
+- You need to fund your account with XLM from another account
+- Mainnet is limited to 1,000 operations per ledger and will be limited to a maximum of 30 smart contract transactions per ledger (the precise amount of smart contract txs per ledger can vary greatly depending on transaction [resource limits](https://soroban.stellar.org/docs/fundamentals-and-concepts/fees-and-metering#resource-limits))
+  - See more detailed smart contract network settings in the section on [Fees and Metering](https://soroban.stellar.org/docs/fundamentals-and-concepts/fees-and-metering) in the Soroban docs
+- No publicly available RPC, see RPC service providers [here](https://soroban.stellar.org/docs/reference/rpc-list)
+
+### Testnet
+
+- SDF runs three core validator nodes
+- SDF offers a free [Horizon instance](https://horizon-testnet.stellar.org/) you can use to interact with the Testnet
+- Friendbot is a faucet you can use for free Testnet XLM
+- Testnet is limited to 100 operations per ledger and one smart contract transaction per ledger
+- SDF offers free RPC endpoints, more information [here](https://soroban.stellar.org/docs/reference/rpc-list#sdf-futurenet-and-testnet-only)
+
+### Futurenet
+
+- SDF runs core validator nodes
+- SDF offers a free [Horizon instance](https://horizon-futurenet.stellar.org) you can use to interact with the Futurenet
+- Friendbot is a faucet you can use for free Futurenet XLM
+- Futurenet is limited to 100 operations per ledger and one smart contract transaction per ledger
+- SDF offers free RPC endpoints, more information [here](https://soroban.stellar.org/docs/reference/rpc-list#sdf-futurenet-and-testnet-only)
+
+## Friendbot
+
+Friendbot is a bot that funds accounts with fake XLM on Testnet or Futurenet. You can request XLM from Friendbot using the Stellar Laboratory or with various SDKs. Requests to Friendbot are rate limited, so use it wisely. Friendbot provides 10,000 fake XLM when funding a new account.
+
+If you are creating multiple accounts, you can fund your first account with Friendbot and then use that first account to fund your subsequent accounts using the Create Account operation.
+
+## Testnet and Futurenet data reset
+
+Testnet and Futurenet are reset periodically to the genesis ledger to declutter the network, remove spam, reduce the time needed to catch up on the latest ledger, and help maintain the system. Resets clear all ledger entries (accounts, trustlines, offers, smart contract data, etc.), transactions, and historical data from Stellar Core, Horizon, and the Soroban RPC- which is why developers should not rely on the persistence of accounts or the state of any balances when using Testnet or Futurenet.
+
+Futurenet resets are on a less regular cadence than Testnet resets and don't have a set schedule.
+
+Testnet resets happen once per quarter at 17:00 UTC and are announced at least two weeks in advance on the [Stellar Dashboard](http://dashboard.stellar.org/) and through several developer community channels. Here are the 2023 dates:
+
+March 15, 2023  
+June 14, 2023  
+~~September 13, 2023~~ Note: this reset was skipped due to its proximity to the Protocol 20 Testnet upgrade.  
+December 18, 2023
+
+If you run a Testnet or Futurenet Horizon instance, you need to re-join and re-sync to the network after a reset. Check out how to do that here: [Testnet Reset](https://github.com/stellar/packages/blob/master/docs/testnet-reset.md).
+
+## Test data automation
+
+It is recommended that you have testing infrastructure that can repopulate the Testnet and Futurenet with useful data after a reset. This will make testing more reliable and will help you scale your testing infrastructure to a private network if you choose to do so. For example, you may want to:
+
+- Generate issuers of assets for testing the development of a wallet;
+- Generate orders on the order book (both current and historical) for testing the development of a trading client;
+- Recreate liquidity pools;
+- Redeploy smart contracts.
+
+If you maintain an application, you should think about creating a data set that is representative enough to test your primary use cases, and allow for robust testing even when Testnet or Futurenet are not available.
+
+A script can automate this entire process by creating an account with Friendbot and submitting a set of transactions that are predefined as a part of your testing infrastructure.
+
+## What Testnet and Futurenet should and should not be used for
+
+### Testnet and Futurenet are good for
+
+- Creating test accounts (with funding from Friendbot);
+- Developing applications and contracts and exploring tutorials on Stellar without the potential to lose any assets;
+- Testing existing applications against new releases or release candidates of Stellar Core, Horizon, and the Soroban RPC;
+- Performing data analysis on a smaller, non-trivial data set compared to the Mainnet.
+
+### Testnet and Futurenet are bad for
+
+- Load and stress testing;
+- High availability test infrastructure- SDF does not guarantee Testnet availability;
+- Long-term storage of data on the network since the network resets periodically;
+- A testing infrastructure that requires more control over the test environment, such as:
+  - The ability to control the data reset frequency;
+  - The need to secure private or sensitive data (before launching on the Mainnet). You can always run your own test network for use cases that don’t work well with SDF’s Testnet.
+
+## Moving your project from Testnet or Futurenet to production
+
+Mainnet, Testnet, and Futurenet each have their own unique passphrase, which is used to validate signatures on a given transaction.
+
+The current passphrases for the Stellar Mainnet, Testnet, and Futurenet are:
+
+**Mainnet (Pubnet)**: `Public Global Stellar Network ; September 2015`
+
+**Testnet**: `Test SDF Network ; September 2015`
+
+**Futurenet**: `Test SDF Future Network ; October 2022`
+
+For applications that don’t rely on the state of the network (such as specific accounts needing to exist), you move to production by changing the network passphrase and ensuring your Horizon instance is connected to Mainnet.
+
+If you’ve been running a Stellar Core or Horizon instance against the Testnet and want to switch to production, changing the passphrase will require both respective databases to be completely reinitialized. If you run your own RPC on Testnet or Futurenet, you may want to use an RPC service when you move to Mainnet. Check out the RPC service providers [here](https://soroban.stellar.org/docs/reference/rpc-list).
+
+To learn more about network passphrases, see our [Network Passphrase Encyclopedia Entry](../encyclopedia/network-passphrases)

docs/fundamentals-and-concepts/stellar-data-structures/accounts.mdx

@@ -36,7 +36,7 @@ Account data is stored in subentries, each of which increases an account’s min
 - Trustlines (includes traditional assets and pool shares)
 - Offers
 - Additional signers
-- Data entries
+- Data entries (includes data made with the `manageData` operation, not smart contract ledger entries)
 
 ## Trustlines
 

docs/fundamentals-and-concepts/stellar-data-structures/assets.mdx

@@ -9,6 +9,8 @@ Accounts on the Stellar network can be used to track, hold, and transfer any typ
 
 Assets on Stellar have two identifying characteristics: the asset code and the issuer. Since more than one organization can issue a credit representing the same asset, asset codes often overlap (for example, multiple companies offer a USD token on Stellar). Assets are uniquely identified by the combination of their asset code and issuer.
 
+Stellar assets differ from smart contract tokens, which you can read about in the [Tokens section](https://soroban.stellar.org/docs/reference/interfaces/token-interface) in the Soroban docs.
+
 ## Asset components
 
 ### Asset code
@@ -25,6 +27,12 @@ There is no dedicated operation to create an asset on Stellar. Instead, assets a
 
 The public key of the issuing account is linked on the ledger to the asset. Responsibility for and control over an asset resides with the issuing account. Since settings are stored at the account level on the ledger, the issuing account is where you use set_options operations to link to meta-information about an asset and set authorization flags.
 
+## Wrapping Stellar assets
+
+Assets issued on the Stellar network can be used in smart contracts with the Stellar Asset Contract (SAC), which is an implementation of [CAP-46-6: Smart Contract Standardized Asset](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0046-06.md). The SAC allows users to use their Stellar account and trustline balances in Soroban and is a primary intersection where smart contracts interact with the rest of the Stellar network.
+
+Learn more in the [SAC section in the Soroban docs](https://soroban.stellar.org/docs/advanced-tutorials/stellar-asset-contract).
+
 ## Representation
 
 In Horizon, assets are represented in a JSON object: