stellar · ElliotFriend · Mar 27, 2024 · Jul 29, 2022 · Jul 29, 2022 · Jul 29, 2022
diff --git a/docs/building-apps/example-application-tutorial/overview.mdx b/docs/building-apps/example-application-tutorial/overview.mdx
@@ -5,7 +5,7 @@ sidebar_position: 10
 
 :::note
 
-This tutorial walks through how to build an application with the [`js-stellar-sdk`], to build with the Wallet SDK, please follow the [Build a Wallet tutorial](../wallet/overview).
+This tutorial walks through how to build an application with the [`js-stellar-sdk`], to build with the Wallet SDK, please follow the [Build a Wallet tutorial](../wallet/overview). To build with smart contracts, navigate to the [Smart Contracts section](../../smart-contracts/getting-started/setup.mdx).
 
 :::
 

diff --git a/docs/building-apps/overview.mdx b/docs/building-apps/overview.mdx
@@ -3,6 +3,12 @@ title: Overview
 sidebar_position: 0
 ---
 
+:::note
+
+This section details how to build applications without smart contracts. Navigate to the [Smart Contracts section](../smart-contracts/getting-started/setup.mdx) to learn about writing contracts on Stellar.
+
+:::
+
 Stellar is an open-source distributed ledger that you can use as a backend to power various applications and services, such as wallets, payment apps, currency exchanges, micropayment services, platforms for in-game purchases, and more — check out projects being built on Stellar: [Stellar Ecosystem Projects](https://stellar.org/ecosystem/projects#Projects).
 
 Stellar has built-in logic for key storage, creating accounts, signing transactions, tracking balances, and queries to the Stellar database, and anyone can use the network to issue, store, transfer, and trade assets.
@@ -18,11 +24,3 @@ Many Stellar assets connect to real-world currencies, and Stellar has open proto
 Stellar-based products and services interoperate by implementing various Stellar Ecosystem Proposals (SEPs), which are publicly created, open-source documents that live in a [GitHub repository](https://github.com/stellar/stellar-protocol/tree/master/ecosystem#stellar-ecosystem-proposals-seps) and define how asset issuers, anchors, wallets, and other service providers interact with each other.
 
 As a wallet, the most important SEPs are [SEP-24: Hosted Deposit and Withdrawal](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md), and [SEP-31: Cross Border Payments API](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md), [SEP-10: Stellar Authentication](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md), [SEP-12: KYC API](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md), and [SEP-38: Anchor RFQ API](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md).
-
-**This documentation will walk you through how to build wallets using the Wallet SDK (Kotlin and Typescript are currently supported) and how to build a comprehensive basic payment application.**
-
-:::info
-
-This documentation is a work in progress and more will be added as it is created.
-
-:::
diff --git a/docs/building-apps/wallet/overview.mdx b/docs/building-apps/wallet/overview.mdx
@@ -10,8 +10,8 @@ import Header from "./component/header.mdx";
 
 In this guide we will use the Wallet SDK to integrate with the Stellar blockchain and connect to anchors.
 
-:::info
+:::note
 
-This documentation is a work in progress and more will be added as it is created.
+This documentation walks you through how to build a wallet without smart contracts. To build with smart contracts, navigate to the [Smart Contracts section](../../smart-contracts/getting-started/setup.mdx).
 
 :::
diff --git a/docs/issuing-assets/anatomy-of-an-asset.mdx b/docs/issuing-assets/anatomy-of-an-asset.mdx
@@ -9,6 +9,8 @@ Issuing assets is a core feature of Stellar: any asset can be tokenized (or mint
 
 Issuing an asset on Stellar is easy and only takes a few operations. However, there are additional considerations you may need to think about depending on your use case, such as publishing asset information, compliance, and asset supply, which we’ll cover in this documentation. 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.
 
+Assets issued on the Stellar network are accessible to smart contracts. Every Stellar asset has reserved a [Stellar Asset Contract](../smart-contracts/tokens/stellar-asset-contract.mdx) that can be deployed by anyone who wants to be able to interact with the asset from a contract.
+
 ## Stablecoins
 
 One major category of assets is the stablecoin. A stablecoin is a blockchain-based token whose value is tied to another asset, such as the US dollar, other fiat currencies, commodities like gold, or even cryptocurrencies. There are two types of stablecoin: 1) reserve-backed stablecoins that must have a mechanism for redeeming the asset backing them, and 2) algorithmic stablecoins that don’t have assets backing them and instead rely on an algorithm to control the stablecoin supply. When discussing stablecoins, our documentation will focus on reserve-backed stablecoins.

diff --git a/docs/issuing-assets/how-to-issue-an-asset.mdx b/docs/issuing-assets/how-to-issue-an-asset.mdx
@@ -8,6 +8,12 @@ import { Alert } from "@site/src/components/Alert";
 
 In this tutorial, we will walk through the steps to issue an asset on the Stellar test network.
 
+:::note
+
+If you'd like to interact with an asset issued on the Stellar network in smart contracts, you can create or deploy the [Stellar Asset Contract](../smart-contracts/tokens/stellar-asset-contract.mdx) for that asset.
+
+:::
+
 ## Prerequisites
 
 You must ensure you have the required amount of XLM to create your issuing and distribution accounts and cover the minimum balance and transaction fees. If you’re issuing an asset on the testnet, you can fund your account by getting test XLM from friendbot. If you’re issuing an asset in production, you will need to acquire XLM from another wallet or exchange.

diff --git a/docs/learn/glossary.mdx b/docs/learn/glossary.mdx
@@ -103,7 +103,7 @@ Flags control access to an asset on the account level. Learn more about flags in
 
 An automated test that rapidly stuffs massive amounts of randomized, malformed data into a system to reveal adverse or unexpected results that indicate vulnerabilities.
 
-Read more in the [Fuzz Testing Tutorial](https://soroban.stellar.org/docs/tutorials/fuzzing).
+Read more in the [Fuzz Testing Tutorial](../smart-contracts/example-contracts/fuzzing.mdx).
 
 ### GitHub
 

diff --git a/docs/learn/migrate/evm/solidity-and-rust-advanced-concepts.mdx b/docs/learn/migrate/evm/solidity-and-rust-advanced-concepts.mdx
@@ -170,7 +170,7 @@ impl AllocContract {
 
 In this example, the `alloc` crate is imported into the smart contract using the `extern crate alloc;` statement. The `alloc` crate is then used to create a temporary vector that holds values from 0 to `count`. The values in the vector are then summed and returned.
 
-For more details on how to use the `alloc` crate, including a hands-on practical exercise, visit the [alloc section](https://soroban.stellar.org/docs/tutorials/alloc#how-it-works) of the documentation.
+For more details on how to use the `alloc` crate, including a hands-on practical exercise, visit the [alloc example contract](../../../smart-contracts/example-contracts/alloc.mdx#how-it-works).
 
 #### Inheriting Functionality from Other Crates
 

diff --git a/docs/learn/smart-contract-internals/authorization.mdx b/docs/learn/smart-contract-internals/authorization.mdx
@@ -52,15 +52,15 @@ From the contract perspective `Address` is an opaque identifier type. The contra
 
 Both functions ensure that the `Address` has authorized the call of the current function within the current context (where context is defined by `require_auth` calls in the current call stack; see more formal definition in the [section below](#require_auth-implementation-details)). The authentication rules for this authorization are defined by the `Address` and are enforced by the Soroban host. Replay protection is also implemented in the host, i.e., there is normally no need for a contract to manage its own nonces.
 
-[auth example]: https://soroban.stellar.org/docs/tutorials/auth
+[auth example]: ../../smart-contracts/example-contracts/auth.mdx
 
 #### Authorizing Sub-contract Calls
 
 One of the key features of Soroban Authorization Framework is the ability to easily make authorized sub-contract calls. For example, it is possible for a contract to call `require_auth` for an `Address` and then call `token.xfer` authorized for the same `Address` (see [timelock example] that demonstrates this pattern).
 
 Contracts don't need to do anything special to benefit from this feature. Just calling a sub-contract that calls `require_auth` will ensure that the sub-contract call has been properly authorized.
 
-[timelock example]: https://soroban.stellar.org/docs/tutorials/timelock
+[timelock example]: ../../smart-contracts/example-contracts/timelock.mdx
 
 #### When to `require_auth`
 
@@ -74,7 +74,7 @@ The main authorization-related decision a contract writer needs to make for any
 
 There is no explicit restriction on how many `Address` entities the contract uses and how many `Address`es have `require_auth` called. That means that it is possible to authorize a contract call on behalf of multiple users, which may even have different authorization contexts (customized via arguments in `require_auth_for_args`). [Atomic swap] is an example that deals with authorization of two `Address`es.
 
-[atomic swap]: https://soroban.stellar.org/docs/tutorials/atomic-swap
+[atomic swap]: ../../smart-contracts/example-contracts/atomic-swap.mdx
 
 Note though, that contracts that deal with multiple authorized `Address`es need a bit more complex support on the client side (to collect and attach the proper signatures).
 
@@ -90,7 +90,7 @@ Account abstraction provides a convenient extension point for every contract tha
 
 Conceptually, every abstract account is a special contract that defines authentication rules and potentially some additional account-specific authorization policies. However, for the sake of optimization and integration with the existing Stellar accounts, Soroban supports 4 different kinds of the account implementations.
 
-Below are the general descriptions of these implementations. See the transaction [guide](contract-interactions/stellar-transaction.mdx) for the concrete information of how different accounts are represented.
+Below are the general descriptions of these implementations. See the transaction [guide](./contract-interactions/stellar-transaction.mdx) for the concrete information of how different accounts are represented.
 
 ##### Stellar Account
 
@@ -100,7 +100,7 @@ This is a special, built-in 'account contract' that handles all the Stellar acco
 
 This supports the Stellar multisig with medium threshold. See Stellar [documentation] for more details on multisig and thresholds.
 
-[documentation]: https://developers.stellar.org/docs/encyclopedia/signatures-multisig
+[documentation]: ../encyclopedia/signatures-multisig.mdx
 
 ##### Transaction Invoker
 
@@ -128,7 +128,7 @@ Custom account can also be treated as a custodial smart wallet. It holds the use
 
 For the exact interface and more details, see the [custom account example].
 
-[custom account example]: https://soroban.stellar.org/docs/tutorials/custom-account
+[custom account example]: ../../smart-contracts/example-contracts/custom-account.mdx
 
 ### Advanced Concepts
 

diff --git a/docs/learn/smart-contract-internals/errors.mdx b/docs/learn/smart-contract-internals/errors.mdx
@@ -20,10 +20,12 @@ One way is error enum types, that are defined by contracts and that map errors t
 
 :::info
 
-The [errors example] demonstrates how to define your own error types. [errors example]: https://soroban.stellar.org/docs/tutorials/errors
+The [errors example] demonstrates how to define your own error types.
 
 :::
 
+[errors example]: ../../smart-contracts/example-contracts/errors.mdx
+
 ## Error Enums
 
 Errors are a special type of enum integer type that are stored on ledger as `Status` values containing a `u32` code.

diff --git a/docs/learn/smart-contract-internals/events.mdx b/docs/learn/smart-contract-internals/events.mdx
@@ -21,7 +21,7 @@ Events are the mechanism that applications off-chain can use to monitor changes
 
 ## How are events emitted?
 
-`ContractEvents` are emitted in Stellar Core's `TransactionMeta`. You can see in the [TransactionMetaV3] XDR below that there is a list of `OperationEvents` called `events`. Each `OperationEvent` corresponds to an operation in a transaction, and itself contains a list of `ContractEvents`. Note that `events` will only be populated if the transaction succeeds. Take a look at [this example](https://soroban.stellar.org/docs/tutorials/events) to learn more about how to emit an event in your contract.
+`ContractEvents` are emitted in Stellar Core's `TransactionMeta`. You can see in the [TransactionMetaV3] XDR below that there is a list of `OperationEvents` called `events`. Each `OperationEvent` corresponds to an operation in a transaction, and itself contains a list of `ContractEvents`. Note that `events` will only be populated if the transaction succeeds. Take a look at [this example](../../smart-contracts/example-contracts/events.mdx) to learn more about how to emit an event in your contract.
 
 [transactionmetav3]: #transactionmetav3
 

diff --git a/docs/learn/smart-contract-internals/faq.mdx b/docs/learn/smart-contract-internals/faq.mdx
@@ -0,0 +1,54 @@
+---
+sidebar_position: 170
+title: FAQs
+description: Frequently asked questions about Soroban on Stellar.
+---
+
+<head>
+  <title>Frequently asked questions about Soroban on Stellar.</title>
+  <meta charSet="utf-8" />
+  <meta
+    property="og:title"
+    content="Frequently asked questions about Soroban on Stellar."
+  />
+  <meta
+    property="og:description"
+    content="Frequently asked questions about Soroban on Stellar."
+  />
+</head>
+
+### What is Soroban to Stellar? Is it a new blockchain?
+
+Soroban is not a new blockchain. Soroban is a smart contract platform that is integrated into the existing Stellar blockchain. It is an _additive_ feature that lives alongside, and doesn't replace, the existing set of Stellar operations.
+
+### How do I invoke a Soroban contract on Stellar?
+
+A Soroban contract can be invoked by submitting a transaction that contains the new operation: `InvokeHostFunctionOp`.
+
+### Can Soroban contracts use Stellar accounts for authentication?
+
+Yes. Stellar accounts are shared with Soroban. Smart contacts have access to Stellar account signer configuration and know the source account that directly invoked them in a transaction. Check out the Auth and Advanced Auth examples for more information.
+
+### Can Soroban contracts interact with Stellar assets?
+
+Yes. Soroban contains a built-in Stellar Asset Contract that is able to interact with classic trustlines. Read more about this [here](../../smart-contracts/tokens/stellar-asset-contract.mdx).
+
+### Do issuers of Stellar assets maintain their authorization over an asset that has been sent to a non-account identifier in Soroban? (AUTH_REQUIRED, AUTH_REVOCABLE, AUTH_CLAWBACK)
+
+Yes. Issuers retain the same level of control on Soroban as they have on Classic. This functionality is accessible through a set of admin functions (clawback, set_auth) on the built-in Stellar Asset Contract.
+
+### Can Soroban contracts interact with any other Stellar operations?
+
+No. Aside from the interactions with accounts and assets as mentioned above. This means that Soroban contracts can not interact with SDEX, AMMs, Claimable Balances, or Sponsorships.
+
+### Does the Stellar base reserve apply to Soroban contracts?
+
+No. Soroban has a different fee structure and ledger entries that are allocated by Soroban contracts do not add to an account's required minimal balance.
+
+### Should I issue my token as a Stellar asset or a custom Soroban token?
+
+We recommend, to the extent possible, issuing tokens as Stellar assets. These tokens will benefit from being interoperable with the existing ecosystem of tools available in the Stellar ecosystem, as well as being more performant because the Stellar Asset Contract is built into the host.
+
+### Haven't found what you're looking for?
+
+Join #soroban on the [Stellar Developer Discord](https://discord.gg/stellardev)
diff --git a/docs/learn/smart-contract-internals/types/custom-types.mdx b/docs/learn/smart-contract-internals/types/custom-types.mdx
@@ -23,7 +23,7 @@ Custom types are struct, union, and enum types defined by contracts. They are us
 
 The [custom types example] demonstrates how to define your own types.
 
-[custom types example]: https://soroban.stellar.org/docs/tutorials/custom-types
+[custom types example]: ../../../smart-contracts/example-contracts/custom-types.mdx
 
 :::
 

diff --git a/docs/reference/software-versions.mdx b/docs/reference/software-versions.mdx
@@ -1255,7 +1255,7 @@ See https://github.com/stellar/soroban-tools/releases v0.7.0 for more details.
 
 ### Breaking changes note
 
-This release comes with a revamp of authorization approach that is breaking for most of the contracts that did any sort of auth logic or used tokens. [example](https://soroban.stellar.org/docs/tutorials/auth) and [authorization overview](../learn/smart-contract-internals/authorization.mdx) for more details.
+This release comes with a revamp of authorization approach that is breaking for most of the contracts that did any sort of auth logic or used tokens. [example](../smart-contracts/example-contracts/auth.mdx) and [authorization overview](../learn/smart-contract-internals/authorization.mdx) for more details.
 
 ### Changelog
 

diff --git a/docs/smart-contracts/example-contracts/README.mdx b/docs/smart-contracts/example-contracts/README.mdx
@@ -0,0 +1,16 @@
+---
+title: Example Contracts
+sidebar_position: 30
+hide_table_of_contents: true
+sidebar_class_name: sidebar-category-items-hidden
+---
+
+import DocCardList from "@theme/DocCardList";
+
+The Soroban team has put together a large collection of [example contracts] to demonstrate use of the Soroban smart contracts platform. For many of these example contracts, we've written an accompanying tutorial that will walk you through the example contract and describe a bit more about its design.
+
+The examples listed below are provided in a sequential manner. The first listed example contracts create a solid foundation of concepts that will be required during the later examples. While you are absolutely free to choose, read, and use any of the example contracts you like, please keep in mind that the order you see is intentional.
+
+<DocCardList />
+
+[example contracts]: https://github.com/stellar/soroban-examples
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,7 +5,7 @@ sidebar_position: 10 @@
     :::note
-    This tutorial walks through how to build an application with the [`js-stellar-sdk`], to build with the Wallet SDK, please follow the [Build a Wallet tutorial](../wallet/overview).
+    This tutorial walks through how to build an application with the [`js-stellar-sdk`], to build with the Wallet SDK, please follow the [Build a Wallet tutorial](../wallet/overview). To build with smart contracts, navigate to the [Smart Contracts section](../../smart-contracts/getting-started/setup.mdx).
     :::
@@ Expand Down @@