diff --git a/docs/tokens/anatomy-of-an-asset.mdx b/docs/tokens/anatomy-of-an-asset.mdx index 1a1d0cd53..f95e54477 100644 --- a/docs/tokens/anatomy-of-an-asset.mdx +++ b/docs/tokens/anatomy-of-an-asset.mdx @@ -1,8 +1,246 @@ --- -title: Assets Overview +title: Assets Overview & Comparison +description: Asset Overview and Comparison of Stellar Asset (with SAC), SEP-41 Contract Token, and T-REX (Token for Regulated Exchanges) sidebar_position: 20 --- +:::info + +The term "custom token" has been deprecated in favor of "contract token". View the conversation in the [Stellar Developer Discord](https://discord.com/channels/897514728459468821/966788672164855829/1359276952971640953). + +::: + +This brief compares the three primary tokenization models available on the Stellar network: + +- Stellar 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) + +to help issuers select the most appropriate model for their use case. + +## Tokenization Model Comparison + +| Dimension | Stellar 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._ + +## 1. Stellar Assets (with Built-in [Stellar Asset Contract][sac]) + +### What this category encompasses + +All assets issued by Stellar accounts (G…` addresses) are **Stellar Assets**. These assets can be represented in two forms: + +- **Stellar Asset** Held in trustlines and transferred via payment operations. + +- **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. + +### How they work + +- 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. + +### Strengths + +- Has the benefits of 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. Assets issued by `G...` accounts 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 Stellar 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). +- Operations on Stellar Assets emit the same standardized events defined by SEP-41, because the Stellar Asset Contract implements the SEP-41 token interface, Payment operations on Stellar Assets surface identical transfer events, allowing off-chain systems and indexers to observe asset activity through a uniform way. +- By default, the admin of a Stellar Asset Contract (SAC) is the asset issuer (a `G...` address). However, the admin can be changed to a smart contract. Assigning a contract as the SAC admin enables custom, onchain policy for administrative actions for privileged operations. + +### Tradeoffs + +- 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 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 + +### Strengths + +- Fully programmable token logic beyond what Stellar Asset Contract expresses. +- [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 Stellar Asset operations. +- Less widespread ecosystem support compared to Stellar Assets, including centralized exchange support. + +### When to use + +- DeFi primitives requiring complex tokenomics. +- Asset behaviors not representable by Stellar Assets alone. +- When extending SEP-41 with custom functionality. + +## 3. ERC-3643 / SEP-57 (T-REX) Tokens + +### What these are + +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. + +### How they work + +- 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. + +### Strengths + +- On-chain compliance. +- On-chain identity. +- Role/agent-based structure tailored for institutions. + +### Tradeoffs + +- 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. + +### When to use + +- Institutional RWAs with strict on-chain compliance requirements. +- Interoperability with Ethereum’s ERC-3643 ecosystem. + +## Decision Guide + +Choose the right token model based on the use case: + +- **Assets Issued by `G...` Accounts (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 + +::::note Summary: TLDR + +- 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 about Stellar Asset Contract (SAC) + +The Stellar Asset Contract (SAC) is a contract built-in to the Stellar protocol that implements SEP-41 for assets issued by Stellar accounts (`G...`), and 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 Stellar Assets, such as transfer fees, vesting schedules, or custom mint/burn rules + +:::note + +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. + +::: + +### 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. + +- **Token Factory Pattern** + Build a factory contract that programmatically deploys new instances of a token contract, enabling standardized, on-demand token creation. + Issuing assets is a core feature of Stellar: any asset can be tokenized (or minted) on the network and then tracked, held, and traded quickly and cheaply. Assets can represent many things: cryptocurrencies (such as bitcoin or ether), fiat currencies (such as dollars or pesos), other tokens of value (such as NFTs), pool shares, or even bonds and equity. Any Stellar account can issue an asset, and since anyone can set up an account, anyone can issue assets: banks, payment processors, money service businesses, for-profit enterprises, nonprofits, local communities, and individuals. It’s a self-serve process with no permission needed. 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. @@ -27,3 +265,10 @@ As an asset issuer, you may need to comply with regulatory requirements that var - [Controlling access to an asset with flags](./control-asset-access.mdx#controlling-access-to-an-asset-with-flags) - [SEP-0008: Regulated Assets](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0008.md) - regulated assets are assets that require an issuer’s approval (or a delegated third party’s approval) on a per-transaction basis. Check out this Stellar Ecosystem Proposal to learn how to implement regulated assets into your use case. + +[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