diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index e5ee26ead..14efdd2ef 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 10 -title: "Issuing Assets vs. Creating Custom Tokens: Key Differences & Best Practices" +title: "Tokenization Model Comparison on Stellar" sidebar_label: Stellar Assets and Contract Tokens description: "Learn about the differences between issuing assets on the Stellar network, creating smart contract tokens, and information and best practices for each." --- @@ -11,65 +11,224 @@ The term "custom token" has been deprecated in favor of "contract token". View t ::: -# Stellar Assets and Contract Tokens +This brief compares the three primary tokenization models available on the Stellar network: -Tokens exist in two forms on Stellar: +- Stellar Classic Assets (with built-in Stellar Asset Contract), +- [SEP-41][sep-41] Contract Tokens, and +- Regulated [SEP-57][sep-57] Tokens (Tokens for Regulated EXchanges / T-REX) -1. Assets issued by Stellar accounts (`G...` addresses) and their built-in [Stellar Asset Contract (SAC)][sac] implementation, and -2. [Contract tokens][ti] issued by a deployed WASM contract (`C...` addresses). +to help issuers select the most appropriate model for their use case. -Several factors can help you determine whether to issue an asset on Stellar or create a contract token with a smart contract for your project. +## 1. Stellar Classic Assets (with Built-in [Stellar Asset Contract][sac]) -However: +### What this category encompasses -### TL;DR +All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stellar Assets**. These assets can be represented in two forms: -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. +- **Native Classic Asset** + Held in trustlines and transferred via native payment operations. -## Issuing assets on Stellar +- **Built-in Smart Contract (Stellar Asset Contract)** + A [Stellar Asset Contract (SAC)][sac] can optionally be deployed to a contract address for the asset, implementing the SEP-41 token interface so the asset can be used in smart contracts. -Stellar has first-class support for asset tokenization — issuing an asset can be done using a [built-in transaction](./quickstart.mdx) without the development of a smart contract. +### How they work -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. +- For protocol-level behavior and trustline semantics, see [Asset Design Considerations](./control-asset-access.mdx). +- Implemented at the protocol level, the **Stellar Asset Contract (SAC)** provides a smart contract interface that enables Stellar assets to interoperate seamlessly with Stellar smart contracts. +- Transfers between accounts and contracts using SAC resolve to the same trustline balance updates the Stellar protocol has always used. -Stellar assets: +### Strengths -- Are compatible with Stellar ecosystem products (such as Stellar wallets) and other ecosystem products (such as exchanges). +- Has the benefits of native Stellar assets (fast, low cost), making these great for remittances and micropayments. +- Can be used in Stellar smart contracts via SAC with a [SEP-41][sep-41] interface. +- Maintains issuer controls and trustline semantics even when used from contracts. +- Wide ecosystem wallet and indexer support. Classic assets are compatible with Stellar ecosystem products (such as Stellar wallets) and other ecosystem products (such as exchanges). - Benefit from [anchors](../learn/fundamentals/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](./control-asset-access.mdx#naming-an-asset), [determine access control](./control-asset-access.mdx#controlling-access-to-an-asset-with-flags), [limit asset supply](./control-asset-access.mdx#limiting-the-supply-of-an-asset), [publish asset information](./publishing-asset-info.mdx), and [ensure compliance](./anatomy-of-an-asset.mdx#compliance). +- Native operations on Classic Assets emit standardized events through the Stellar Asset Contract, allowing off-chain systems and indexers to observe asset activity in a uniform way. Event semantics are defined at the protocol level according to [CAP-0067](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0067.md). -:::note +### Tradeoffs -Note that while these items are also possible with smart contract tokens, it is more work to build the token contract rather than using the already-implemented features of Stellar asset tokens. +- Accounts must have an active trustline to receive, hold, and transact. +- Trustlines cannot be added programmatically through contract invocations, limiting support for assets that rely on bridging or chain abstraction patterns. -::: +### When to use + +- Simple payment rails with optional smart contract integration. +- Trustline-governed asset flows that also need Soroban composability + +## 2. SEP-41 Contract Tokens + +### What these are + +Fully customizable contract tokens native to Soroban that implement the **[SEP-41][sep-41] token standard**, with their own storage and logic. [Contract tokens][ti] issued by a deployed Wasm contract (`C...` addresses). + +### How they work + +- Issued and managed entirely in contract code. +- Can be held by both `G…` accounts and `C…` accounts (no trustlines required). +- Balances are always stored in contract data entries. +- Commonly used when custom logic is required: + - Mint/burn rules + - Vesting + - Hooks + - Custom transfer logic + - Fee structures +- Contract tokens can be held by both `G…` accounts and `C…` accounts. +- Balances are always stored in contract data. + +### Strengths + +- Fully programmable token logic beyond what Classic Assets + SAC can express. +- [SEP-41][sep-41] standard ensures broad tooling compatibility in Soroban. +- Can be integrated into existing Soroban applications and DeFi protocols. +- Some ecosystem wallet support. + +### Tradeoffs + +- Higher execution costs compared to native Classic Asset operations. +- Less widespread ecosystem support compared to Classic Assets. -Assets issued on the Stellar network are accessible to smart contracts with the use of that asset’s Stellar Asset Contract (SAC). +### When to use -### Stellar Asset Contract +- DeFi primitives requiring complex tokenomics. +- Asset behaviors not representable by Classic Assets alone. +- When extending SEP-41 with custom functionality. -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) as well as smart contract token balances. +## 3. ERC-3643 / SEP-57 (T-REX) Tokens -Read more about the SAC [here][sac]. +### What these are -Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide](../tools/cli/cookbook/deploy-stellar-asset-contract.mdx). +A **permissioned token standard** for regulated, compliance-aware assets that extends [SEP-41][sep-41] with identity and rules enforcement. T-REX tokens are issued by a deployed Wasm contract (`C...` addresses) and implement compliance logic directly in the contract suite. -**Benefits of the SAC:** +### How they work -- 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 contract-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. +- Extend [SEP-41][sep-41] with on-chain identity verification and compliance rules. +- Enforce transfer restrictions based on identity status and compliance policies. +- Support [role-based access control (RBAC)](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/access) tailored for institutional use cases. +- Balances are stored in contract data entries. -**Downside of the SAC:** +### Strengths -- 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 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 contract token. +- On-chain compliance. +- On-chain identity. +- Role/agent-based structure tailored for institutions. -## Contract tokens +### Tradeoffs -If you have a unique use case where the capabilities Stellar Assets are not sufficient, you can create a contract token that implements the [token interface][ti]. The token interface specifies the functions and events a contract must implement to be compatible with applications that use tokens. +- Higher complexity. +- Higher execution costs due to on-chain compliance and identity checks. +- Current state: + - Balance display supported in some ecosystem wallets via [SEP-41][sep-41]. + - Transfers and control functions not yet supported in wallets. + - Indexer support is not provided out of the box and must be self-implemented. -The SAC also implements the token interface and applications that interoperate with the token interface can seamlessly interact with Stellar assets and contract tokens. +### When to use + +- Institutional RWAs with strict on-chain compliance requirements. +- Interoperability with Ethereum’s ERC-3643 ecosystem. + +## Tokenization Model Comparison Table + +| Dimension | Stellar Classic Asset (with SAC) | SEP-41 Contract Token | ERC-3643 (T-REX) | +| --- | --- | --- | --- | +| **Platform** | Stellar Ledger + Soroban | Soroban on Stellar | Soroban on Stellar | +| **Token Model** | Trustlines + native ops + SEP-41 via SAC | SEP-41 interface implemented by a smart contract, fully extensible | SEP-41 with extensible compliance logic | +| **Programmability** | ❌ Protocol-defined / SAC interface not updatable | ✅ Fully customizable | ✅ Fully customizable + compliance rules | +| **Interaction Method** | Native ops (accounts) and contract calls (via SAC) | Contract calls | Contract calls | +| **Admin Control** | Protocol flags + optional admin via SAC | Custom contract logic | Built-in compliance and rule enforcement | +| **Identity Model** | Off-chain identity + optional contract logic | Programmable identity | Programmable identity with on-chain enforcement | +| **Cost & Speed** | Very low (native ops) / Moderate (via SAC) | Moderate | Higher | +| **Ecosystem** | Stellar payments, DEX, and Soroban | Stellar DeFi & dApps / Interop with other L1s | Institutional DeFi / Interop with other L1s | +| **Trustline Required** | ✅ Yes\* | ❌ No | ❌ No | +| **Ledger Storage** | Blockchain ledger (trustlines)\* | Smart contract storage | Smart contract storage | +| **Ideal For** | Payments, simple assets (fiat based stablecoins), Soroban integration | DeFi and custom tokenomics | Institutional RWAs with compliance | +| **Source Code** | [Built-in Stellar Asset Contract](https://github.com/stellar/rs-soroban-env/tree/main/soroban-env-host/src/builtin_contracts) | [OpenZeppelin Fungible Token reference](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/fungible) | [OpenZeppelin T-REX (RWA token) reference](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa) | +| **Relevant SEPs** | [SEP-0001 (Stellar Info File)][sep-1]

[SEP-0014 (Dynamic Asset Metadata)][sep-14]

[SEP-41 (Soroban Token Interface)][sep-41] | [SEP-41 (Soroban Token Interface)][sep-41] | [SEP-41 (Soroban Token Interface)][sep-41]

[SEP-0057 (T-REX / Token for Regulated EXchanges)][sep-57] | + +_\* By assigning a smart contract (`C...` address) as the owner of a Stellar Asset Contract, balances and transfer rules can be fully managed within the contract. This removes the need for trustlines, as balances are hold in the contract storage._ + +## Decision Guide + +Choose the right token model based on the use case: + +- **Classic Stellar Assets (with SAC)**: + - Simple payment rails or fiat-backed stablecoins + - Maximum ecosystem compatibility (wallets, exchanges, DEX) + - Low transaction costs and fast settlement + - Optional smart contract integration via SAC + - Regulatory controls through protocol flags + +- **SEP-41 Contract Tokens**: + - Custom token logic (transfer fees, vesting, hooks) + - DeFi primitives and complex tokenomics + - No trustline requirements + - Full programmability for innovative use cases + - Integration with advanced Soroban applications + +- **SEP-57 / ERC-3643 (T-REX) Tokens**: + - Onchain compliance and identity verification + - Institutional-grade access controls + - Regulatory requirements for Real World Assets (RWAs) + - Interoperability with Ethereum ERC-3643 + +## Conclusion + +- Classic Stellar Assets are best for simple payments and fiat-backed assets, with optional smart contract interoperability via the Stellar Asset Contract. +- SEP-41 Contract Tokens are ideal for DeFi and advanced tokenomics requiring full programmability. +- SEP-57 ERC-3643 Tokens are designed for regulated Real World Assets, offering on-chain compliance and identity with institutional-grade controls. + +--- + +## More Info + +### Stellar Asset Contract (SAC) + +The Stellar Asset Contract (SAC) is a protocol-level contract that enables smart contracts to interact with assets issued on Stellar. + +For any Stellar asset, an instance of the SAC can be deployed (by anyone) to a deterministic, reserved address. Once deployed, smart contracts can interact with that asset using standard contract calls. + +The SAC has read/write access to: + +- Account balances (for XLM) +- Trustline balances (for issued assets) +- Smart-contract token balances + +This allows Stellar assets to interoperate seamlessly with Soroban smart contracts. + +- [Read more about the Stellar Asset Contract](./stellar-asset-contract.mdx) +- [How to deploy a Stellar Asset Contract](../tools/cli/cookbook/deploy-stellar-asset-contract.mdx) + +### Benefits of the SAC + +**Compatibility** +The SAC preserves full compatibility with the existing Stellar asset model, including trustlines, authorization flags, and the Stellar DEX. + +**Cost & Resource Efficiency** +Because the SAC is compiled into the protocol (rather than implemented as a user-deployed contract running in a VM), its functions are more resource-efficient than equivalent contract-coded logic. + +**Minimal Setup** +You don’t need to write or deploy a custom token contract. A Stellar asset’s SAC already exists at the protocol level and only needs to be deployed to be used. + +**Extensible Administration** +The asset admin can be a smart contract. Issuers may delegate administrative capabilities—such as authorization, minting, or clawbacks—to another contract, enabling custom or decentralized admin logic without replacing the asset itself. + +### Limitations of the SAC + +Aside from delegating admin logic, the behavior of a Stellar asset and its SAC **cannot be modified**. Core asset semantics (balances, transfers, trustlines) are fixed at the protocol level. + +If your use case requires token behavior not supported by Stellar assets, you should use a contract token instead. + +### Contract Tokens + +For advanced or non-standard use cases, you can create a contract token that implements the **[SEP-41 token interface][ti]**. This interface defines the required functions and events for compatibility with applications that work with tokens. + +Key points: + +- The SAC itself implements the token interface ([SEP-41][sep-41]) +- Applications built against the token interface can interact with both Stellar assets (via SAC) and contract tokens +- Contract tokens allow full customization of token logic +- Contract tokens provide the flexibility to implement features not available in Classic Assets, such as transfer fees, vesting schedules, or custom mint/burn rules :::note @@ -77,12 +236,17 @@ Smart contracts cannot use Stellar assets unless that Stellar asset has a deploy ::: -**These example scenarios are not possible with the SAC and demonstrate what you could use the token interface for:** +### When You Need a Contract Token (Examples) + +The following scenarios are not possible using the SAC, but can be implemented with a contract token: + +- **Transfer Fees** + Implement a token that automatically deducts a 1% fee on every transfer and routes it to a designated address. -- As the creator of a new token, you decide to implement a feature within your 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. +- **Token Factory Pattern** + Build a factory contract that programmatically deploys new instances of a token contract, enabling standardized, on-demand token creation. -## Helpful links +## Helpful Links - [Issue an asset tutorial][how-to-issue] - [Stellar Asset Contract][sac] @@ -91,3 +255,7 @@ Smart contracts cannot use Stellar assets unless that Stellar asset has a deploy [how-to-issue]: ./how-to-issue-an-asset.mdx [sac]: ./stellar-asset-contract.mdx [ti]: ./token-interface.mdx +[sep-1]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md +[sep-14]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0014.md +[sep-41]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md +[sep-57]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0057.md