Clean up the stellar asset contract overview (#771)

Co-authored-by: Elliot Voris <[email protected]>

docs/tokens/stellar-asset-contract.mdx

@@ -18,21 +18,60 @@ description: Use Stellar assets on Soroban.
   />
 </head>
 
-The Stellar Asset Contract is an implementation of [CAP-46-6 Smart Contract Standardized Asset].
-
-[CAP-46-6 Smart Contract Standardized Asset]: https://stellar.org/protocol/cap-46-06
+The Stellar Asset Contract is an implementation of [CAP-46-6 Smart Contract Standardized Asset]
+and [SEP-41 Token Interface] for Stellar [Assets].
 
 ## Overview
 
-Stellar has numerous assets on its classic network, and being able to use them
-in Soroban would give users much more flexibility with how they can use their
-assets. For this reason, we introduced the Stellar Asset Contract, or SAC for
-short, which allows users to use their Stellar account and trustline balances in
-Soroban.
+Stellar assets are issued by Stellar accounts.
+
+The Stellar Asset Contract (SAC) allows users and contracts to
+make payments with, and interact with, assets. The SAC can
+interact with assets held by Stellar accounts or contracts.
+
+The SAC is a special built-in contract that has access to functionality
+of the Stellar network that allows it to use Stellar assets directly.
+
+Each Stellar Asset has an instance of the SAC reserved on the network.
+To use the SAC reserved for an asset, the instance just needs to be
+deployed.
+
+When the SAC transfers assets between accounts, the same debit and
+credits occur as they do when a Stellar Payment operation is used,
+because the SAC interacts directly with Stellar account trust lines.
+When the SAC transfers assets between contracts, it uses Contract
+Data ledger entries to store the balances for contracts.
+
+Stellar account balances for the native asset are always stored on
+the account, and Stellar contract balances for the native asset are
+always stored in a contract data entry.
+
+Stellar account balances for issued assets are always stored in trust
+lines, and Stellar contract balances for issued assets are always
+stored in a contract data entry.
+
+For example, when transferring from a Stellar account to a Stellar
+contract, the Stellar account's trust line entry is debited, and a
+contract data entry is credited.
+
+And for example, when transferring from a Stellar contract to a Stellar
+account, a contract data entry is debited, and the account's trust line
+entry is credited.
+
+In both those examples it is a single asset that is transferring from
+the account to the contract and back again. No bridging is required and
+no intermediary tokens are needed. An asset on Stellar and it's Stellar
+Asset Contract represent the same asset. The SAC for an asset is simply
+an API for interacting with the asset.
+
+The SAC implements the [SEP-41 Token Interface], which is similar to the
+widely used ERC-20 token standard. Contracts that depend on only the
+SEP-41 portion of the SAC's interface, are also compatible with any
+custom token that implements SEP-41.
 
-The SAC implements the SEP-41 [Token Interface], which is similar to the
-widely used ERC-20 token standard. This should make it easier for existing
-smart contract developers to get started on Stellar.
+Some functionality available on the Stellar network in transaction
+operations, such as the order book, do not have any functions exposed
+on the Stellar Asset Contract in the current protocol.
 
 ## Deployment
 
@@ -56,9 +95,8 @@ contract has been deployed.
 
 ## Interacting with classic Stellar assets
 
-The Stellar Asset Contract is the only way to interact with 'classic' Stellar
-assets in Soroban. 'Classic' assets include native Stellar token (lumens) and
-all the existing trustlines.
+The Stellar Asset Contract is the only way for contracts to interact with
+Stellar assets, either the native XLM asset, or those issued by Stellar accounts.
 
 The issuer of the asset will be the administrator
 of the deployed contract. Because the Native Stellar token doesn't have an
@@ -169,7 +207,7 @@ impl MyContract {
 :::info Clients
 
 A client created by [`token::Client`] implements the functions defined by any
-contract that implements the SEP-41 [Token Interface]. But the Stellar Asset
+contract that implements the [SEP-41 Token Interface]. But the Stellar Asset
 Contract exposes additional functions such as `mint`. To access the additional
 functions, another client needs to be used: [`token::StellarAssetClient`]. This
 client only implements the functions which are not part of the SEP-41.
@@ -213,10 +251,12 @@ implementation.
 ## Contract Interface
 
 This interface can be found in the [SDK]. It extends the common
-[Token Interface].
+[SEP-41 Token Interface].
 
-[SDK]: https://github.com/stellar/rs-soroban-sdk/blob/v20.0.0/soroban-sdk/src/token.rs
-[Token Interface]: token-interface.mdx
+[Assets]: https://developers.stellar.org/docs/fundamentals-and-concepts/stellar-data-structures/assets
+[SDK]: https://docs.rs/soroban-sdk/latest/soroban_sdk/token/index.html
+[CAP-46-6 Smart Contract Standardized Asset]: https://github.com/stellar/stellar-protocol/blob/master/core/cap-0046-06.md
+[SEP-41 Token Interface]: token-interface.mdx
 [`soroban_sdk::token`]: https://docs.rs/soroban-sdk/latest/soroban_sdk/token/
 [`token::TokenClient`]: https://docs.rs/soroban-sdk/latest/soroban_sdk/token/struct.TokenClient.html
 [`token::StellarAssetClient`]: https://docs.rs/soroban-sdk/latest/soroban_sdk/token/struct.StellarAssetClient.html