From ac5b8ead510818ea28c5278b3cc876ba185e52c4 Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Mon, 13 May 2024 12:19:52 -0600 Subject: [PATCH 01/24] Adding Tokens Overview (wayfinding) --- .../tokens/stellar-asset-contract.mdx | 2 +- .../tokens/token-interface.mdx | 2 +- docs/smart-contracts/tokens/wayfinding.mdx | 66 +++++++++++++++++++ 3 files changed, 68 insertions(+), 2 deletions(-) create mode 100644 docs/smart-contracts/tokens/wayfinding.mdx diff --git a/docs/smart-contracts/tokens/stellar-asset-contract.mdx b/docs/smart-contracts/tokens/stellar-asset-contract.mdx index 518c10db5..bb039420e 100644 --- a/docs/smart-contracts/tokens/stellar-asset-contract.mdx +++ b/docs/smart-contracts/tokens/stellar-asset-contract.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 20 +sidebar_position: 10 title: Stellar Asset Contract description: Use Stellar assets on Soroban. --- diff --git a/docs/smart-contracts/tokens/token-interface.mdx b/docs/smart-contracts/tokens/token-interface.mdx index 90f7c0e20..3dd083ffb 100644 --- a/docs/smart-contracts/tokens/token-interface.mdx +++ b/docs/smart-contracts/tokens/token-interface.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 20 title: Token Interface description: The common interface implemented by tokens that are compatible with Soroban's built-in tokens. --- diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx new file mode 100644 index 000000000..093149f0d --- /dev/null +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -0,0 +1,66 @@ +--- +sidebar_position: 5 +title: Tokens Overview +description: Choose between the Stellar Asset Contract and Custom Tokens +--- + +Tokens exist in two forms on Stellar: 1) assets issued by Stellar accounts (Stellar assets can have a [Stellar Asset Contract (SAC)](./stellar-asset-contract.mdx) implementation), and 2) as a [custom token](./token-interface.mdx) created by a smart contract. + +Several factors (such as project-specific requirements and network capabilities) can help you determine whether to issue an asset on Stellar or create a custom token with a smart contract for your project. + +However: + +### TL;DR + +If possible, we recommend issuing a Stellar asset and (if needed) using the SAC to interact with that asset in smart contracts. More on why below. + +## Issuing assets on Stellar + +Stellar is first-class in asset tokenization — issuing an asset can be done in [just one single transaction](https://developers.stellar.org/docs). + +Stellar’s transactions are fast and cost-effective, making the network great for remittances and micropayments. It also has built-in features for compliance, asset management, and auditing. If you are just looking to perform simple transfers, issuing assets on Stellar has all the needed capabilities. + +Stellar assets: + +Are already widely supported in the Stellar ecosystem and other ecosystems (such as Stellar USDC on Coinbase). Benefit from [anchors](../../learn/encyclopedia/anchors.mdx), the bridges between the Stellar network and traditional financial systems. Explore the global [Stellar anchor directory](https://anchors.stellar.org/) for further details. Give the issuer granular control over asset management with features that allow the issuer to [publish asset information](../../issuing-assets/publishing-asset-info.mdx), [ensure compliance](../../issuing-assets/anatomy-of-an-asset.mdx#compliance), and [regulate asset supply](../../issuing-assets/control-asset-access.mdx#limiting-the-supply-of-an-asset). + +Assets issued on the Stellar network are accessible to smart contracts with the use of that asset’s Stellar Asset Contract (SAC). + +### Stellar Asset Contract + +The Stellar Asset Contract (SAC) is compiled into the protocol layer and allows smart contracts to interact with assets issued on Stellar. Every Stellar asset has reserved a SAC on the network that can be deployed by anyone who wants to interact with the asset from a contract. The SAC has access to all account (for XLM) and trustline (for all other assets) balances as well as smart contract token balances. + +Read more about the SAC [here](./stellar-asset-contract.mdx). + +Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide](../../smart-contracts/guides/cli/deploy-stellar-asset-contract.mdx). + +**Benefits of the SAC:** + +- Compatibility: Stellar ecosystem products (such as Stellar wallets) and other ecosystem products (such as exchanges) already know how to interact with Stellar assets, making the SAC more interoperable. +- Cost and resource efficiency: the SAC is built into the protocol-level code that already runs the network. So, there is no need to spin up a Wasm contract’s VM to invoke a function. Each function within the SAC will be more resource-efficient than its custom-coded counterpart. +- Less work: you don’t have to write an entirely new contract. A Stellar asset’s SAC already exists on the network and just needs to be deployed to be used. + +**Downside of the SAC:** + +- You cannot customize the SAC (with one exception, explained below). If you’re looking to use assets in a way not supported by the SAC, you can create your own custom smart contract token using the token interface. **Exception:** the asset issuer is automatically the admin for that asset’s SAC. However, the SAC allows the asset issuer to set a different admin address. Making this admin another smart contract means that you can add a bit of customization and logic to how the asset will authorize balances and trustlines, mint tokens, etc. + +## Custom tokens + +If you have a unique use case where the SAC's predefined capabilities do not work for you, you can create a custom token using the [token interface](./token-interface.mdx). The token interface is a software interface that specifies what it means to be a smart contract token. The user can implement their own token contract that uses all the functions of this interface, and all tokens that implement this interface are interoperable with each other. The token interface executes on the smart contract layer instead of the protocol layer. + +:::note + +Tokens created with smart contracts cannot interact with Stellar assets unless that Stellar asset has a deployed SAC. + +::: + +**These example scenarios are not possible with the SAC and demonstrate what you could use the token interface for:** + +- As the creator of a new token, you decide to implement a feature within your custom token smart contract that enables you to receive a 1% fee from every transaction involving your token. Whenever someone transfers your token to another user, 1% of the transferred amount is automatically deducted and sent to a designated wallet address that you control. +- You want to develop a factory contract that automates the creation of instances of a specific token. This contract serves as a centralized and standardized way to deploy new token contracts on demand without manual intervention each time a new instance is needed. + +## Helpful links + +- [Issue an asset tutorial](../../issuing-assets/how-to-issue-an-asset.mdx) +- [Stellar Asset Contract](./stellar-asset-contract.mdx) +- [Token Interface](./token-interface.mdx) From 41f8ba1a559ade27bbe92442abf40244aafac799 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 08:50:12 -0600 Subject: [PATCH 02/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 093149f0d..eb9eb0197 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -6,7 +6,7 @@ description: Choose between the Stellar Asset Contract and Custom Tokens Tokens exist in two forms on Stellar: 1) assets issued by Stellar accounts (Stellar assets can have a [Stellar Asset Contract (SAC)](./stellar-asset-contract.mdx) implementation), and 2) as a [custom token](./token-interface.mdx) created by a smart contract. -Several factors (such as project-specific requirements and network capabilities) can help you determine whether to issue an asset on Stellar or create a custom token with a smart contract for your project. +Several factors can help you determine whether to issue an asset on Stellar or create a custom token with a smart contract for your project. However: From 6e65323facc71e6443246ac99324afe6430fbc5f Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 08:50:34 -0600 Subject: [PATCH 03/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index eb9eb0197..ec16bd5d8 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -4,7 +4,9 @@ title: Tokens Overview description: Choose between the Stellar Asset Contract and Custom Tokens --- -Tokens exist in two forms on Stellar: 1) assets issued by Stellar accounts (Stellar assets can have a [Stellar Asset Contract (SAC)](./stellar-asset-contract.mdx) implementation), and 2) as a [custom token](./token-interface.mdx) created by a smart contract. +Tokens exist in two forms on Stellar: +1. Assets issued by Stellar accounts and their built-in [Stellar Asset Contract (SAC)](./stellar-asset-contract.mdx) implementation) +2. [Custom tokens](./token-interface.mdx) issued by a deployed WASM contract. Several factors can help you determine whether to issue an asset on Stellar or create a custom token with a smart contract for your project. From 649c8c55fa8e15f5727eba9848bc25f74e120382 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 08:50:47 -0600 Subject: [PATCH 04/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index ec16bd5d8..4aeb59206 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -14,7 +14,7 @@ However: ### TL;DR -If possible, we recommend issuing a Stellar asset and (if needed) using the SAC to interact with that asset in smart contracts. More on why below. +If possible, we recommend issuing a Stellar asset and using the SAC to interact with that asset in smart contracts or to send to contract addresses. More on why below. ## Issuing assets on Stellar From 51581606d6757f57fba92ead2096ab6b0fe85252 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 08:51:05 -0600 Subject: [PATCH 05/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 4aeb59206..2584ce41f 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -18,7 +18,7 @@ If possible, we recommend issuing a Stellar asset and using the SAC to interact ## Issuing assets on Stellar -Stellar is first-class in asset tokenization — issuing an asset can be done in [just one single transaction](https://developers.stellar.org/docs). +Stellar has first-class support for asset tokenization — issuing an asset can be done using a [built-in transaction](https://developers.stellar.org/docs) without the development of a smart contract. Stellar’s transactions are fast and cost-effective, making the network great for remittances and micropayments. It also has built-in features for compliance, asset management, and auditing. If you are just looking to perform simple transfers, issuing assets on Stellar has all the needed capabilities. From 2834b3fa8ac26cb0d0ea807f7d2584710d2d58fb Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 08:51:46 -0600 Subject: [PATCH 06/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 2584ce41f..9806351c1 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -44,7 +44,7 @@ Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide] **Downside of the SAC:** -- You cannot customize the SAC (with one exception, explained below). If you’re looking to use assets in a way not supported by the SAC, you can create your own custom smart contract token using the token interface. **Exception:** the asset issuer is automatically the admin for that asset’s SAC. However, the SAC allows the asset issuer to set a different admin address. Making this admin another smart contract means that you can add a bit of customization and logic to how the asset will authorize balances and trustlines, mint tokens, etc. +- Other than the customization noted above, it is not possible to modify the behavior of Stellar Assets or their SAC. If you’re looking to use assets in a way not supported by Stellar assets, you can create your own custom smart contract token using the token interface and all applications that interact with tokens using the token interface will be able to interact with the custom token. ## Custom tokens From d43691dfd642d829596203b8c78c2e7854f77617 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 08:51:59 -0600 Subject: [PATCH 07/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 9806351c1..3e18f0f38 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -52,7 +52,7 @@ If you have a unique use case where the SAC's predefined capabilities do not wor :::note -Tokens created with smart contracts cannot interact with Stellar assets unless that Stellar asset has a deployed SAC. +Tokens created with smart contracts cannot interact with Stellar assets unless that Stellar asset has a deployed SAC. Anyone can deploy the SAC for a Stellar asset. ::: From b9928206efd20fe55b0a19ef36c6b71bda3821a3 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 08:52:16 -0600 Subject: [PATCH 08/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 3e18f0f38..f7fb4626a 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -48,7 +48,9 @@ Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide] ## Custom tokens -If you have a unique use case where the SAC's predefined capabilities do not work for you, you can create a custom token using the [token interface](./token-interface.mdx). The token interface is a software interface that specifies what it means to be a smart contract token. The user can implement their own token contract that uses all the functions of this interface, and all tokens that implement this interface are interoperable with each other. The token interface executes on the smart contract layer instead of the protocol layer. +If you have a unique use case where the SAC's capabilities are not sufficient, you can create a custom token that implements the [token interface](./token-interface.mdx). The token interface specifies the functions and events a contract must implement to be compatible with applications that use tokens. + +The SAC also implements the token interface and applications that interoperate with the token interface can seamlessly interact with Stellar assets and custom tokens. :::note From bad50ace5f660573a904cc3d5fb1728e0f71a785 Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 08:54:16 -0600 Subject: [PATCH 09/24] formatting --- docs/smart-contracts/tokens/wayfinding.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index f7fb4626a..307155249 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -5,6 +5,7 @@ description: Choose between the Stellar Asset Contract and Custom Tokens --- Tokens exist in two forms on Stellar: + 1. Assets issued by Stellar accounts and their built-in [Stellar Asset Contract (SAC)](./stellar-asset-contract.mdx) implementation) 2. [Custom tokens](./token-interface.mdx) issued by a deployed WASM contract. From 50b6cd41af6b96b611110f47a4129b80e40b7e15 Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 09:55:34 -0600 Subject: [PATCH 10/24] more updates --- docs/smart-contracts/tokens/wayfinding.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 307155249..b84bc9605 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -6,7 +6,7 @@ description: Choose between the Stellar Asset Contract and Custom Tokens Tokens exist in two forms on Stellar: -1. Assets issued by Stellar accounts and their built-in [Stellar Asset Contract (SAC)](./stellar-asset-contract.mdx) implementation) +1. Assets issued by Stellar accounts and their built-in [Stellar Asset Contract (SAC)](./stellar-asset-contract.mdx) implementation, and 2. [Custom tokens](./token-interface.mdx) issued by a deployed WASM contract. Several factors can help you determine whether to issue an asset on Stellar or create a custom token with a smart contract for your project. @@ -25,7 +25,9 @@ Stellar’s transactions are fast and cost-effective, making the network great f Stellar assets: -Are already widely supported in the Stellar ecosystem and other ecosystems (such as Stellar USDC on Coinbase). Benefit from [anchors](../../learn/encyclopedia/anchors.mdx), the bridges between the Stellar network and traditional financial systems. Explore the global [Stellar anchor directory](https://anchors.stellar.org/) for further details. Give the issuer granular control over asset management with features that allow the issuer to [publish asset information](../../issuing-assets/publishing-asset-info.mdx), [ensure compliance](../../issuing-assets/anatomy-of-an-asset.mdx#compliance), and [regulate asset supply](../../issuing-assets/control-asset-access.mdx#limiting-the-supply-of-an-asset). +- Are already widely supported in the Stellar ecosystem and other ecosystems (such as Stellar USDC on Coinbase). +- Benefit from [anchors](../../learn/encyclopedia/anchors.mdx), the bridges between the Stellar network and traditional financial systems. Explore the global [Stellar anchor directory](https://anchors.stellar.org/) for further details. +- Give the issuer granular control over asset management with features that allow the issuer to [publish asset information](../../issuing-assets/publishing-asset-info.mdx), [ensure compliance](../../issuing-assets/anatomy-of-an-asset.mdx#compliance), and [regulate asset supply](../../issuing-assets/control-asset-access.mdx#limiting-the-supply-of-an-asset). Assets issued on the Stellar network are accessible to smart contracts with the use of that asset’s Stellar Asset Contract (SAC). @@ -37,11 +39,12 @@ Read more about the SAC [here](./stellar-asset-contract.mdx). Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide](../../smart-contracts/guides/cli/deploy-stellar-asset-contract.mdx). -**Benefits of the SAC:** +**Benefits of Stellar assets and the SAC:** -- Compatibility: Stellar ecosystem products (such as Stellar wallets) and other ecosystem products (such as exchanges) already know how to interact with Stellar assets, making the SAC more interoperable. +- Compatibility: Stellar ecosystem products (such as Stellar wallets) and other ecosystem products (such as exchanges) already know how to interact with Stellar assets, making their SAC more interoperable. - Cost and resource efficiency: the SAC is built into the protocol-level code that already runs the network. So, there is no need to spin up a Wasm contract’s VM to invoke a function. Each function within the SAC will be more resource-efficient than its custom-coded counterpart. - Less work: you don’t have to write an entirely new contract. A Stellar asset’s SAC already exists on the network and just needs to be deployed to be used. +- Customization: Stellar assets have the following customizations: [naming](../../issuing-assets/control-asset-access.mdx#naming-an-asset), [access control](../../issuing-assets/control-asset-access.mdx#controlling-access-to-an-asset-with-flags), [supply control](../../issuing-assets/control-asset-access.mdx#limiting-the-supply-of-an-asset), and admin addresses can be contracts. **Downside of the SAC:** From 60bfd21f18df3704e7376c6676b2826f1ee6ae76 Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Tue, 14 May 2024 10:08:39 -0600 Subject: [PATCH 11/24] update copy --- docs/smart-contracts/tokens/wayfinding.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index b84bc9605..cec8343f1 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -25,9 +25,9 @@ Stellar’s transactions are fast and cost-effective, making the network great f Stellar assets: -- Are already widely supported in the Stellar ecosystem and other ecosystems (such as Stellar USDC on Coinbase). +- Are compatible with Stellar ecosystem products (such as Stellar wallets) and other ecosystem products (such as exchanges). - Benefit from [anchors](../../learn/encyclopedia/anchors.mdx), the bridges between the Stellar network and traditional financial systems. Explore the global [Stellar anchor directory](https://anchors.stellar.org/) for further details. -- Give the issuer granular control over asset management with features that allow the issuer to [publish asset information](../../issuing-assets/publishing-asset-info.mdx), [ensure compliance](../../issuing-assets/anatomy-of-an-asset.mdx#compliance), and [regulate asset supply](../../issuing-assets/control-asset-access.mdx#limiting-the-supply-of-an-asset). +- Give the issuer granular control over asset management with features that allow the issuer to [name the asset](../../issuing-assets/control-asset-access.mdx#naming-an-asset), [determine access control](../../issuing-assets/control-asset-access.mdx#controlling-access-to-an-asset-with-flags), [limit asset supply](../../issuing-assets/control-asset-access.mdx#limiting-the-supply-of-an-asset), [publish asset information](../../issuing-assets/publishing-asset-info.mdx), and [ensure compliance](../../issuing-assets/anatomy-of-an-asset.mdx#compliance). Assets issued on the Stellar network are accessible to smart contracts with the use of that asset’s Stellar Asset Contract (SAC). @@ -39,12 +39,12 @@ Read more about the SAC [here](./stellar-asset-contract.mdx). Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide](../../smart-contracts/guides/cli/deploy-stellar-asset-contract.mdx). -**Benefits of Stellar assets and the SAC:** +**Benefits of the SAC:** -- Compatibility: Stellar ecosystem products (such as Stellar wallets) and other ecosystem products (such as exchanges) already know how to interact with Stellar assets, making their SAC more interoperable. +- Compatibility: the SAC benefits from Stellar assets' existing interoperability. - Cost and resource efficiency: the SAC is built into the protocol-level code that already runs the network. So, there is no need to spin up a Wasm contract’s VM to invoke a function. Each function within the SAC will be more resource-efficient than its custom-coded counterpart. - Less work: you don’t have to write an entirely new contract. A Stellar asset’s SAC already exists on the network and just needs to be deployed to be used. -- Customization: Stellar assets have the following customizations: [naming](../../issuing-assets/control-asset-access.mdx#naming-an-asset), [access control](../../issuing-assets/control-asset-access.mdx#controlling-access-to-an-asset-with-flags), [supply control](../../issuing-assets/control-asset-access.mdx#limiting-the-supply-of-an-asset), and admin addresses can be contracts. +- Customization: in addition to the customizations for Stellar assets listed above, asset issuers can set a different smart contract as an admin for their asset’s SAC. Making this admin another smart contract means that that address can add a bit of customization and logic to how the asset will authorize balances and trustlines, mint tokens, etc.admin addresses can be contracts. **Downside of the SAC:** From f6e79847477530a873cbb291e3c907b68d9a5411 Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Tue, 28 May 2024 09:01:43 -0600 Subject: [PATCH 12/24] couple nits --- docs/smart-contracts/tokens/wayfinding.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index cec8343f1..bed0e00d9 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -44,11 +44,11 @@ Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide] - Compatibility: the SAC benefits from Stellar assets' existing interoperability. - Cost and resource efficiency: the SAC is built into the protocol-level code that already runs the network. So, there is no need to spin up a Wasm contract’s VM to invoke a function. Each function within the SAC will be more resource-efficient than its custom-coded counterpart. - Less work: you don’t have to write an entirely new contract. A Stellar asset’s SAC already exists on the network and just needs to be deployed to be used. -- Customization: in addition to the customizations for Stellar assets listed above, asset issuers can set a different smart contract as an admin for their asset’s SAC. Making this admin another smart contract means that that address can add a bit of customization and logic to how the asset will authorize balances and trustlines, mint tokens, etc.admin addresses can be contracts. +- Customization: in addition to the customizations for Stellar assets listed above, asset issuers can set a different smart contract as an admin for their asset’s SAC. Making this admin another smart contract means that that address can add a bit of customization and logic to how the asset will authorize balances and trustlines, mint tokens, etc. Admin addresses can be contracts. **Downside of the SAC:** -- Other than the customization noted above, it is not possible to modify the behavior of Stellar Assets or their SAC. If you’re looking to use assets in a way not supported by Stellar assets, you can create your own custom smart contract token using the token interface and all applications that interact with tokens using the token interface will be able to interact with the custom token. +- Other than the customization noted above, it is not possible to modify the behavior of Stellar assets or their SAC. If you’re looking to use assets in a way not supported by Stellar assets, you can create your own custom smart contract token using the token interface and all applications that interact with tokens using the token interface will be able to interact with the custom token. ## Custom tokens From a3ef12a2c9e9b85812ced654ab43325ad251b1b1 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Thu, 30 May 2024 08:54:19 -0600 Subject: [PATCH 13/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Jake Urban <10968980+JakeUrban@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index bed0e00d9..9f5b60392 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -44,7 +44,7 @@ Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide] - Compatibility: the SAC benefits from Stellar assets' existing interoperability. - Cost and resource efficiency: the SAC is built into the protocol-level code that already runs the network. So, there is no need to spin up a Wasm contract’s VM to invoke a function. Each function within the SAC will be more resource-efficient than its custom-coded counterpart. - Less work: you don’t have to write an entirely new contract. A Stellar asset’s SAC already exists on the network and just needs to be deployed to be used. -- Customization: in addition to the customizations for Stellar assets listed above, asset issuers can set a different smart contract as an admin for their asset’s SAC. Making this admin another smart contract means that that address can add a bit of customization and logic to how the asset will authorize balances and trustlines, mint tokens, etc. Admin addresses can be contracts. +- Customization: asset issuers can set a different smart contract as an admin for their asset’s SAC. Making this admin another smart contract means that that address can add a bit of customization and logic to how the asset will authorize balances and trustlines, mint tokens, etc. Admin addresses can be contracts. **Downside of the SAC:** From 1f90ba71c62415a67226f7c2aaaac1e11035d520 Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Thu, 30 May 2024 09:00:02 -0600 Subject: [PATCH 14/24] update wording --- docs/smart-contracts/tokens/wayfinding.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index bed0e00d9..52c5df26a 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -29,11 +29,17 @@ Stellar assets: - Benefit from [anchors](../../learn/encyclopedia/anchors.mdx), the bridges between the Stellar network and traditional financial systems. Explore the global [Stellar anchor directory](https://anchors.stellar.org/) for further details. - Give the issuer granular control over asset management with features that allow the issuer to [name the asset](../../issuing-assets/control-asset-access.mdx#naming-an-asset), [determine access control](../../issuing-assets/control-asset-access.mdx#controlling-access-to-an-asset-with-flags), [limit asset supply](../../issuing-assets/control-asset-access.mdx#limiting-the-supply-of-an-asset), [publish asset information](../../issuing-assets/publishing-asset-info.mdx), and [ensure compliance](../../issuing-assets/anatomy-of-an-asset.mdx#compliance). +:::note + +Note that while these items are also possible with custom smart contract tokens, it is more work to build the token contract rather than using the already-implemented features of Stellar asset tokens. + +::: + Assets issued on the Stellar network are accessible to smart contracts with the use of that asset’s Stellar Asset Contract (SAC). ### Stellar Asset Contract -The Stellar Asset Contract (SAC) is compiled into the protocol layer and allows smart contracts to interact with assets issued on Stellar. Every Stellar asset has reserved a SAC on the network that can be deployed by anyone who wants to interact with the asset from a contract. The SAC has access to all account (for XLM) and trustline (for all other assets) balances as well as smart contract token balances. +The Stellar Asset Contract (SAC) is compiled into the protocol layer and allows smart contracts to interact with assets issued on Stellar. A single instance of the SAC can be deployed for every Stellar asset by anyone who wants to interact with the asset from a contract. The SAC has access to all account (for XLM) and trustline (for all other assets) balances as well as smart contract token balances. Read more about the SAC [here](./stellar-asset-contract.mdx). From cc69f71e1020a1462aa7a787680ce51a3e404584 Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Thu, 30 May 2024 09:51:21 -0600 Subject: [PATCH 15/24] update note --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 52c5df26a..f2f11fd91 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -64,7 +64,7 @@ The SAC also implements the token interface and applications that interoperate w :::note -Tokens created with smart contracts cannot interact with Stellar assets unless that Stellar asset has a deployed SAC. Anyone can deploy the SAC for a Stellar asset. +Smart contracts cannot use Stellar assets unless that Stellar asset has a deployed SAC. ::: From e15efec15569826460e63d226cb690f9fc8853ec Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Thu, 30 May 2024 10:33:02 -0600 Subject: [PATCH 16/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 681eaf7cb..dcbc936f4 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -21,7 +21,7 @@ If possible, we recommend issuing a Stellar asset and using the SAC to interact Stellar has first-class support for asset tokenization — issuing an asset can be done using a [built-in transaction](https://developers.stellar.org/docs) without the development of a smart contract. -Stellar’s transactions are fast and cost-effective, making the network great for remittances and micropayments. It also has built-in features for compliance, asset management, and auditing. If you are just looking to perform simple transfers, issuing assets on Stellar has all the needed capabilities. +Stellar’s transactions are fast and cost-effective, making the network great for remittances and micropayments. It also has built-in features for compliance, asset management, and auditing. If you are looking to perform transfers of value, issuing assets on Stellar has all the needed capabilities. Stellar assets: From e0d1b06de5105a768207b8d9dc23605d611ef857 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Wed, 5 Jun 2024 08:54:39 -0600 Subject: [PATCH 17/24] G & C addresses --- docs/smart-contracts/tokens/wayfinding.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index dcbc936f4..19ca3c9bf 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -6,8 +6,8 @@ description: Choose between the Stellar Asset Contract and Custom Tokens Tokens exist in two forms on Stellar: -1. Assets issued by Stellar accounts and their built-in [Stellar Asset Contract (SAC)](./stellar-asset-contract.mdx) implementation, and -2. [Custom tokens](./token-interface.mdx) issued by a deployed WASM contract. +1. Assets issued by Stellar accounts (G... addresses) and their built-in [Stellar Asset Contract (SAC)](./stellar-asset-contract.mdx) implementation, and +2. [Custom tokens](./token-interface.mdx) issued by a deployed WASM contract (C... addresses). Several factors can help you determine whether to issue an asset on Stellar or create a custom token with a smart contract for your project. From ffb0dcac6597f3e00c96d5a5302b6abbbefdd126 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 11 Jun 2024 16:25:11 -0600 Subject: [PATCH 18/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 19ca3c9bf..3a4a10c83 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -39,7 +39,7 @@ Assets issued on the Stellar network are accessible to smart contracts with the ### Stellar Asset Contract -The Stellar Asset Contract (SAC) is compiled into the protocol layer and allows smart contracts to interact with assets issued on Stellar. A single instance of the SAC can be deployed for every Stellar asset by anyone who wants to interact with the asset from a contract. The SAC has access to all account (for XLM) and trustline (for all other assets) balances as well as smart contract token balances. +The Stellar Asset Contract (SAC) is compiled into the protocol layer and allows smart contracts to interact with assets issued on Stellar. An instance of the SAC can be deployed for every Stellar asset by anyone who wants to interact with the asset from a contract. The SAC has access to all account (for XLM) and trustline (for all other assets) balances as well as smart contract token balances. Read more about the SAC [here](./stellar-asset-contract.mdx). From c178bbb0f5a785922c57a35acee89a4338fcf55b Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 11 Jun 2024 16:29:28 -0600 Subject: [PATCH 19/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 3a4a10c83..d777e5a48 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -48,7 +48,7 @@ Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide] **Benefits of the SAC:** - Compatibility: the SAC benefits from Stellar assets' existing interoperability. -- Cost and resource efficiency: the SAC is built into the protocol-level code that already runs the network. So, there is no need to spin up a Wasm contract’s VM to invoke a function. Each function within the SAC will be more resource-efficient than its custom-coded counterpart. +- Cost and resource efficiency: the SAC is built into the protocol instead of being a contract that runs in a virtual machine. Each function within the SAC will be more resource-efficient than its custom-coded counterpart. - Less work: you don’t have to write an entirely new contract. A Stellar asset’s SAC already exists on the network and just needs to be deployed to be used. - Customization: asset issuers can set a different smart contract as an admin for their asset’s SAC. Making this admin another smart contract means that that address can add a bit of customization and logic to how the asset will authorize balances and trustlines, mint tokens, etc. Admin addresses can be contracts. From fed26c6e84772faf2b2303e408ff0e10509c5582 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 11 Jun 2024 16:45:31 -0600 Subject: [PATCH 20/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index d777e5a48..65f3afa91 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -50,7 +50,7 @@ Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide] - Compatibility: the SAC benefits from Stellar assets' existing interoperability. - Cost and resource efficiency: the SAC is built into the protocol instead of being a contract that runs in a virtual machine. Each function within the SAC will be more resource-efficient than its custom-coded counterpart. - Less work: you don’t have to write an entirely new contract. A Stellar asset’s SAC already exists on the network and just needs to be deployed to be used. -- Customization: asset issuers can set a different smart contract as an admin for their asset’s SAC. Making this admin another smart contract means that that address can add a bit of customization and logic to how the asset will authorize balances and trustlines, mint tokens, etc. Admin addresses can be contracts. +- Customization: Admin addresses can be contracts. Asset issuers can set a different smart contract as an admin for their asset’s SAC. Making the admin another smart contract allows the addition of custom and decentralized logic for the assets admin capabilities, such as authorizing balances and trust lines, minting tokens, etc. **Downside of the SAC:** From 97947102c9c85b394689762ded40a13cd64b6e25 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 11 Jun 2024 16:45:42 -0600 Subject: [PATCH 21/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index 65f3afa91..b63785116 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -58,7 +58,7 @@ Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide] ## Custom tokens -If you have a unique use case where the SAC's capabilities are not sufficient, you can create a custom token that implements the [token interface](./token-interface.mdx). The token interface specifies the functions and events a contract must implement to be compatible with applications that use tokens. +If you have a unique use case where the capabilities Stellar Assets are not sufficient, you can create a custom token that implements the [token interface](./token-interface.mdx). The token interface specifies the functions and events a contract must implement to be compatible with applications that use tokens. The SAC also implements the token interface and applications that interoperate with the token interface can seamlessly interact with Stellar assets and custom tokens. From b640c480c05d249120d53bae5a684c65af706cea Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 11 Jun 2024 16:45:52 -0600 Subject: [PATCH 22/24] Update docs/smart-contracts/tokens/wayfinding.mdx Co-authored-by: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index b63785116..b78277383 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -64,7 +64,7 @@ The SAC also implements the token interface and applications that interoperate w :::note -Smart contracts cannot use Stellar assets unless that Stellar asset has a deployed SAC. +Smart contracts cannot use Stellar assets unless that Stellar asset has a deployed SAC. Anyone can deploy the SAC for a Stellar asset to its reserved address. ::: From e4fed3e36ae99773040643c81ec06f52064b8d4a Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Tue, 11 Jun 2024 16:46:33 -0600 Subject: [PATCH 23/24] wording --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index d777e5a48..777e584fb 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -39,7 +39,7 @@ Assets issued on the Stellar network are accessible to smart contracts with the ### Stellar Asset Contract -The Stellar Asset Contract (SAC) is compiled into the protocol layer and allows smart contracts to interact with assets issued on Stellar. An instance of the SAC can be deployed for every Stellar asset by anyone who wants to interact with the asset from a contract. The SAC has access to all account (for XLM) and trustline (for all other assets) balances as well as smart contract token balances. +The Stellar Asset Contract (SAC) is compiled into the protocol layer and allows smart contracts to interact with assets issued on Stellar. An instance of the SAC can be deployed for every Stellar asset by anyone who wants to interact with the asset from a contract. The SAC has access to all account balances (for XLM) and trustline balances (for all other assets) balances as well as smart contract token balances. Read more about the SAC [here](./stellar-asset-contract.mdx). From dd227d2e38c03fe1e5d2a70e49806cf26d387286 Mon Sep 17 00:00:00 2001 From: Bri <92327786+briwylde08@users.noreply.github.com> Date: Tue, 11 Jun 2024 16:50:00 -0600 Subject: [PATCH 24/24] formatting --- docs/smart-contracts/tokens/wayfinding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/smart-contracts/tokens/wayfinding.mdx b/docs/smart-contracts/tokens/wayfinding.mdx index a3afc136d..db2f39744 100644 --- a/docs/smart-contracts/tokens/wayfinding.mdx +++ b/docs/smart-contracts/tokens/wayfinding.mdx @@ -50,7 +50,7 @@ Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide] - Compatibility: the SAC benefits from Stellar assets' existing interoperability. - Cost and resource efficiency: the SAC is built into the protocol instead of being a contract that runs in a virtual machine. Each function within the SAC will be more resource-efficient than its custom-coded counterpart. - Less work: you don’t have to write an entirely new contract. A Stellar asset’s SAC already exists on the network and just needs to be deployed to be used. -- Customization: Admin addresses can be contracts. Asset issuers can set a different smart contract as an admin for their asset’s SAC. Making the admin another smart contract allows the addition of custom and decentralized logic for the assets admin capabilities, such as authorizing balances and trust lines, minting tokens, etc. +- Customization: Admin addresses can be contracts. Asset issuers can set a different smart contract as an admin for their asset’s SAC. Making the admin another smart contract allows the addition of custom and decentralized logic for the assets admin capabilities, such as authorizing balances and trust lines, minting tokens, etc. **Downside of the SAC:**