From b3da7966ba4cf654d353661aa877243f5a1d98f7 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Wed, 7 Jan 2026 17:07:08 -0500 Subject: [PATCH 01/17] Add asset comparison --- docs/tokens/README.mdx | 192 +++++++++++++++++++++++++++++++++-------- 1 file changed, 154 insertions(+), 38 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index e5ee26ead1..397b45e7d6 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -1,75 +1,186 @@ --- sidebar_position: 10 -title: "Issuing Assets vs. Creating Custom Tokens: Key Differences & Best Practices" +title: "Issuing Assets 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." --- + :::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). ::: -# Stellar Assets and Contract Tokens - -Tokens exist in two forms on Stellar: - -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). +This brief compares the three primary tokenization models available on the Stellar network: Stellar Classic Assets (with built-in Stellar Asset Contract), SEP-41 Contract Tokens, and Regulated SEP-57 (T-REX) Tokens—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 Form** + 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] is 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_ in Stellar Docs. +- Implemented at the protocol level, the **Stellar Asset Contract (SAC)** provides a smart contract interface that enables Stellar assets to interoperate seamlessly with Soroban smart contracts. +- Transfers between accounts and contracts using SAC result in the same underlying trustline debit/credit. -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 Soroban contracts via SAC with a 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 (CAP-0067). -:::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 +- Native operations on Classic Assets also 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). -::: +### 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 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 +- Commonly used when custom logic is required: + - Mint/burn rules + - Vesting + - Hooks + - Custom transfer logic +- Contract tokens can be held by both `G…` accounts and `C…` accounts +- Balances are always stored in contract data entries + +### Strengths + +- Fully programmable token logic beyond what Classic Assets + SAC can express +- SEP-41 standard ensures broad tooling compatibility in Soroban +- Some ecosystem wallet support + +### When to use + +- DeFi primitives requiring complex tokenomics +- Asset behaviors not representable by Classic 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 with identity and rules enforcement. + +### Strengths + +- On-chain compliance +- On-chain identity +- Role/agent based structure tailored for institutions -Assets issued on the Stellar network are accessible to smart contracts with the use of that asset’s Stellar Asset Contract (SAC). +### Tradeoffs -### Stellar Asset Contract +- 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 + - Transfers and control functions not yet supported in wallets + - Indexer support is not provided out of the box and must be self-implemented -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. +### When to use -Read more about the SAC [here][sac]. +- Institutional RWAs with strict on-chain compliance requirements +- Interoperability with Ethereum’s ERC-3643 ecosystem -Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide](../tools/cli/cookbook/deploy-stellar-asset-contract.mdx). +## Asset Comparison Table -**Benefits of the SAC:** +| 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 | +| **Compliance 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) / Moderate (via SAC) | Moderate | Higher | +| **Ecosystem** | Stellar payments, DEX, and Soroban | Stellar DeFi & dApps / Interop with other L1s | Institutional DeFi / Interop with other L1s | +| **Ideal For** | Payments, simple assets, Soroban integration | DeFi and custom tokenomics | Institutional RWAs with compliance | +| **Source Code** | Built-in Stellar Asset Contract | OpenZeppelin Fungible Token reference | OpenZeppelin T-REX (RWA token) reference | +| **Relevant SEPs** | **SEP-0001** (Stellar Info File)
**SEP-0014** (Dynamic Asset Metadata)
**SEP-41** (Soroban Token Interface) | **SEP-0041** (Soroban Token Interface) | **SEP-0057** (T-REX / Token for Regulated Exchanges) | -- 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. +## Conclusion -**Downside of the SAC:** +- **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. -- 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. +--- + +## 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](#) +- [How to deploy a Stellar Asset Contract](#) + +### Benefits of the SAC -## Contract tokens +**Compatibility** +The SAC preserves full compatibility with the existing Stellar asset model, including trustlines, authorization flags, and the Stellar DEX. -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. +**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. -The SAC also implements the token interface and applications that interoperate with the token interface can seamlessly interact with Stellar assets and contract tokens. +**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 **token interface**. 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 +- 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 :::note @@ -77,12 +188,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] From b9458578b316a612062973bf5af1420d1f45e629 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Wed, 7 Jan 2026 20:50:21 -0500 Subject: [PATCH 02/17] Add more info --- docs/tokens/README.mdx | 81 ++++++++++++++++++++++++++++++++---------- 1 file changed, 63 insertions(+), 18 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index 397b45e7d6..ea36c3489c 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -5,14 +5,19 @@ 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." --- - :::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 Classic Assets (with built-in Stellar Asset Contract), SEP-41 Contract Tokens, and Regulated SEP-57 (T-REX) Tokens—to help issuers select the most appropriate model for their use case. +This brief compares the three primary tokenization models available on the Stellar network: + +- Stellar Classic Assets (with built-in Stellar Asset Contract), +- SEP-41 Contract Tokens, and +- Regulated SEP-57 Tokens (Tokens for Regulated EXchanges / T-REX) + +to help issuers select the most appropriate model for their use case. ## 1. Stellar Classic Assets (with Built-in [Stellar Asset Contract][sac]) @@ -28,7 +33,7 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel ### How they work -- For protocol-level behavior and trustline semantics, see _Asset Design Considerations_ in Stellar Docs. +- 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 Soroban smart contracts. - Transfers between accounts and contracts using SAC result in the same underlying trustline debit/credit. @@ -40,14 +45,12 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel - 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 (CAP-0067). +- 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). ### 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 -- Native operations on Classic Assets also 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). +- Trustlines cannot be added programmatically through contract invocations, limiting support for assets that rely on bridging or chain abstraction patterns. ### When to use @@ -62,21 +65,30 @@ Fully customizable contract tokens native to Soroban that implement the **SEP-41 ### How they work -- Issued and managed entirely in contract code +- 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 -- Contract tokens can be held by both `G…` accounts and `C…` accounts -- Balances are always stored in contract data entries + - 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 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 + ### When to use - DeFi primitives requiring complex tokenomics @@ -87,7 +99,14 @@ Fully customizable contract tokens native to Soroban that implement the **SEP-41 ### What these are -A **permissioned token standard** for regulated, compliance-aware assets that extends SEP-41 with identity and rules enforcement. +A **permissioned token standard** for regulated, compliance-aware assets that extends 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. + +### How they work + +- Extend 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) tailored for institutional use cases +- Balances are stored in contract data entries ### Strengths @@ -119,15 +138,40 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex | **Interaction Method** | Native ops (accounts) and contract calls (via SAC) | Contract calls | Contract calls | | **Compliance 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) / Moderate (via SAC) | Moderate | Higher | +| **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 | | **Ideal For** | Payments, simple assets, Soroban integration | DeFi and custom tokenomics | Institutional RWAs with compliance | | **Source Code** | Built-in Stellar Asset Contract | OpenZeppelin Fungible Token reference | OpenZeppelin T-REX (RWA token) reference | -| **Relevant SEPs** | **SEP-0001** (Stellar Info File)
**SEP-0014** (Dynamic Asset Metadata)
**SEP-41** (Soroban Token Interface) | **SEP-0041** (Soroban Token Interface) | **SEP-0057** (T-REX / Token for Regulated Exchanges) | +| **Relevant SEPs** | **SEP-0001** (Stellar Info File)
**SEP-0014** (Dynamic Asset Metadata)
**SEP-41** (Soroban Token Interface) | **SEP-41** (Soroban Token Interface) | **SEP-41** (Soroban Token Interface)
**SEP-0057** (T-REX / Token for Regulated Exchanges) | + +## 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. +- **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. @@ -149,8 +193,8 @@ The SAC has read/write access to: This allows Stellar assets to interoperate seamlessly with Soroban smart contracts. -- [Read more about the Stellar Asset Contract](#) -- [How to deploy a Stellar Asset Contract](#) +- [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 @@ -174,13 +218,14 @@ If your use case requires token behavior not supported by Stellar assets, you sh ### Contract Tokens -For advanced or non-standard use cases, you can create a **contract token** that implements the **token interface**. This interface defines the required functions and events for compatibility with applications that work with tokens. +For advanced or non-standard use cases, you can create a **contract token** that implements the **[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 +- The SAC itself implements the token interface (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 From 44c2cad404586a5c5c4feba07914415bc8d4d932 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Wed, 7 Jan 2026 21:00:50 -0500 Subject: [PATCH 03/17] Add more info --- docs/tokens/README.mdx | 46 +++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index ea36c3489c..70ae0a5535 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -14,8 +14,8 @@ The term "custom token" has been deprecated in favor of "contract token". View t This brief compares the three primary tokenization models available on the Stellar network: - Stellar Classic Assets (with built-in Stellar Asset Contract), -- SEP-41 Contract Tokens, and -- Regulated SEP-57 Tokens (Tokens for Regulated EXchanges / T-REX) +- [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. @@ -29,7 +29,7 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel Held in trustlines and transferred via native payment operations. - **Built-in Smart Contract (Stellar Asset Contract)** - A [Stellar Asset Contract (SAC)][sac] is deployed to a contract address for the asset, implementing the **SEP-41 token interface** so the asset can be used in smart contracts. + A [Stellar Asset Contract (SAC)][sac] is 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 @@ -40,7 +40,7 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel ### Strengths - Has the benefits of native Stellar assets (fast, low cost), making these great for remittances and micropayments. -- Can be used in Soroban contracts via SAC with a SEP-41 interface. +- Can be used in Soroban 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. @@ -61,7 +61,7 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel ### What these are -Fully customizable contract tokens native to Soroban that implement the **SEP-41 token standard**, with their own storage and logic. [Contract tokens][ti] issued by a deployed WASM contract (`C...` addresses). +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 @@ -80,7 +80,7 @@ Fully customizable contract tokens native to Soroban that implement the **SEP-41 ### Strengths - Fully programmable token logic beyond what Classic Assets + SAC can express -- SEP-41 standard ensures broad tooling compatibility in Soroban +- [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 @@ -99,13 +99,13 @@ Fully customizable contract tokens native to Soroban that implement the **SEP-41 ### What these are -A **permissioned token standard** for regulated, compliance-aware assets that extends 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. +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. ### How they work -- Extend SEP-41 with on-chain identity verification and compliance rules +- 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) tailored for institutional use cases +- 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 @@ -118,8 +118,8 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex - 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 +- 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 @@ -130,10 +130,10 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex ## Asset Comparison Table -| Dimension | Stellar Classic Asset (with SAC) | SEP-41 Contract Token | ERC-3643 (T-REX) | +| Dimension | Stellar Classic Asset (with SAC) | [SEP-41][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 | +| **Token Model** | Trustlines + native ops + [SEP-41][sep-41] via SAC | [SEP-41][sep-41] interface implemented by a smart contract, fully extensible | [SEP-41][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 | | **Compliance Control** | Protocol flags + optional admin via SAC | Custom contract logic | Built-in compliance and rule enforcement | @@ -143,7 +143,7 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex | **Trustline Required** | ✅ Yes | ❌ No | ❌ No | | **Ideal For** | Payments, simple assets, Soroban integration | DeFi and custom tokenomics | Institutional RWAs with compliance | | **Source Code** | Built-in Stellar Asset Contract | OpenZeppelin Fungible Token reference | OpenZeppelin T-REX (RWA token) reference | -| **Relevant SEPs** | **SEP-0001** (Stellar Info File)
**SEP-0014** (Dynamic Asset Metadata)
**SEP-41** (Soroban Token Interface) | **SEP-41** (Soroban Token Interface) | **SEP-41** (Soroban Token Interface)
**SEP-0057** (T-REX / Token for Regulated Exchanges) | +| **Relevant SEPs** | [SEP-0001][sep-1] (Stellar Info File)
[SEP-0014][sep-14] (Dynamic Asset Metadata)
[SEP-41][sep-41] (Soroban Token Interface) | [SEP-41][sep-41] (Soroban Token Interface) | [SEP-41][sep-41] (Soroban Token Interface)
[SEP-0057][sep-57] (T-REX / Token for Regulated Exchanges) | ## Decision Guide @@ -171,9 +171,9 @@ Choose the right token model based on the use case: ## 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. +- 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. --- @@ -181,7 +181,7 @@ Choose the right token model based on the use case: ### 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. +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. @@ -222,8 +222,8 @@ For advanced or non-standard use cases, you can create a **contract token** that Key points: -- The SAC itself implements the token interface (SEP-41) -- Applications built against the token interface can interact with **both** Stellar assets (via SAC) and contract tokens +- 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 @@ -235,7 +235,7 @@ Smart contracts cannot use Stellar assets unless that Stellar asset has a deploy ### When You Need a Contract Token (Examples) -The following scenarios are **not possible** using the SAC, but can be implemented with a contract token: +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. @@ -252,3 +252,7 @@ The following scenarios are **not possible** using the SAC, but can be implement [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 From b21e6ef6f87ee02e89c689da9a76266f43327420 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Wed, 7 Jan 2026 21:05:56 -0500 Subject: [PATCH 04/17] Improve links --- docs/tokens/README.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index 70ae0a5535..407eda5ba1 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -130,10 +130,10 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex ## Asset Comparison Table -| Dimension | Stellar Classic Asset (with SAC) | [SEP-41][sep-41] Contract Token | ERC-3643 (T-REX) | +| 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][sep-41] via SAC | [SEP-41][sep-41] interface implemented by a smart contract, fully extensible | [SEP-41][sep-41] with extensible compliance logic | +| **Token Model** | Trustlines + native ops + SEP-41 via SAC | SEP-41 interface implemented by a smart contract, fully extensible | [SEP-41][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 | | **Compliance Control** | Protocol flags + optional admin via SAC | Custom contract logic | Built-in compliance and rule enforcement | @@ -143,7 +143,7 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex | **Trustline Required** | ✅ Yes | ❌ No | ❌ No | | **Ideal For** | Payments, simple assets, Soroban integration | DeFi and custom tokenomics | Institutional RWAs with compliance | | **Source Code** | Built-in Stellar Asset Contract | OpenZeppelin Fungible Token reference | OpenZeppelin T-REX (RWA token) reference | -| **Relevant SEPs** | [SEP-0001][sep-1] (Stellar Info File)
[SEP-0014][sep-14] (Dynamic Asset Metadata)
[SEP-41][sep-41] (Soroban Token Interface) | [SEP-41][sep-41] (Soroban Token Interface) | [SEP-41][sep-41] (Soroban Token Interface)
[SEP-0057][sep-57] (T-REX / Token for Regulated Exchanges) | +| **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] | ## Decision Guide From f17833d74e1e89aae7cf19d8ff03f234cd12e6ef Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Wed, 7 Jan 2026 21:11:16 -0500 Subject: [PATCH 05/17] Rename page --- docs/tokens/README.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index 407eda5ba1..45e954023d 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 10 -title: "Issuing Assets on Stellar" +title: "Tokenization Models 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." --- @@ -25,11 +25,11 @@ to help issuers select the most appropriate model for their use case. All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stellar Assets**. These assets can be represented in two forms: -- **Native Classic Form** +- **Native Classic Asset** Held in trustlines and transferred via native payment operations. - **Built-in Smart Contract (Stellar Asset Contract)** - A [Stellar Asset Contract (SAC)][sac] is deployed to a contract address for the asset, implementing the SEP-41 token interface so the asset can be used in smart contracts. + 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 @@ -128,7 +128,7 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex - Institutional RWAs with strict on-chain compliance requirements - Interoperability with Ethereum’s ERC-3643 ecosystem -## Asset Comparison Table +## Tokenization Model Comparison Table | Dimension | Stellar Classic Asset (with SAC) | SEP-41 Contract Token | ERC-3643 (T-REX) | | --- | --- | --- | --- | From 2b9434d41704cbee18ee381107d5379ebdebabdb Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Wed, 7 Jan 2026 21:16:18 -0500 Subject: [PATCH 06/17] Minor edits --- docs/tokens/README.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index 45e954023d..651a6558e8 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -133,7 +133,7 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex | 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][sep-41] with extensible compliance logic | +| **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 | | **Compliance Control** | Protocol flags + optional admin via SAC | Custom contract logic | Built-in compliance and rule enforcement | @@ -141,8 +141,8 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex | **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 | -| **Ideal For** | Payments, simple assets, Soroban integration | DeFi and custom tokenomics | Institutional RWAs with compliance | -| **Source Code** | Built-in Stellar Asset Contract | OpenZeppelin Fungible Token reference | OpenZeppelin T-REX (RWA token) reference | +| **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] | ## Decision Guide @@ -214,11 +214,11 @@ The asset admin can be a smart contract. Issuers may delegate administrative cap 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. +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 **[token interface][ti]**. This interface defines the required functions and events for compatibility with applications that work with 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: From f41762e2e36a1c6bc9d695da75b993cb697c7978 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Wed, 7 Jan 2026 21:17:16 -0500 Subject: [PATCH 07/17] Update title --- docs/tokens/README.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index 651a6558e8..9d86dbf367 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 10 -title: "Tokenization Models on Stellar" +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." --- From 845848c3b54fc412319a06b7459cd38ce3747acb Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Thu, 8 Jan 2026 09:31:46 -0700 Subject: [PATCH 08/17] nits --- docs/tokens/README.mdx | 58 +++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index 9d86dbf367..f34d5b06bf 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -54,18 +54,18 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel ### When to use -- Simple payment rails with optional smart contract integration +- 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). +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, +- 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: @@ -79,54 +79,54 @@ Fully customizable contract tokens native to Soroban that implement the **[SEP-4 ### 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 +- 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 +- Higher execution costs compared to native Classic Asset operations. +- Less widespread ecosystem support compared to Classic Assets. ### When to use -- DeFi primitives requiring complex tokenomics -- Asset behaviors not representable by Classic Assets alone -- When extending SEP-41 with custom functionality +- DeFi primitives requiring complex tokenomics. +- Asset behaviors not representable by Classic 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. +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. ### 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 +- 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 +- 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 +- 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 + - 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 +- Institutional RWAs with strict on-chain compliance requirements. +- Interoperability with Ethereum’s ERC-3643 ecosystem. ## Tokenization Model Comparison Table @@ -150,7 +150,7 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex Choose the right token model based on the use case: - **Classic Stellar Assets (with SAC)**: - - Simple payment rails or fiat backed stablecoins + - 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 @@ -171,7 +171,7 @@ Choose the right token model based on the use case: ## Conclusion -- Classic Stellar Assets are best for simple payments and fiat backed assets, with optional smart contract interoperability via the Stellar Asset Contract. +- 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. From a8af3c8fed097894a10dfc2ae1d36a2d091c1157 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Fri, 9 Jan 2026 12:21:13 -0500 Subject: [PATCH 09/17] Update based on Bri's suggestions --- docs/tokens/README.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index f34d5b06bf..760168e505 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -34,13 +34,13 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel ### 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 Soroban smart contracts. -- Transfers between accounts and contracts using SAC result in the same underlying trustline debit/credit. +- 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 native Stellar assets (fast, low cost), making these great for remittances and micropayments. -- Can be used in Soroban contracts via SAC with a [SEP-41][sep-41] interface. +- 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. From b183789258b776d7c5257dcd505a54463dbb7530 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Mon, 12 Jan 2026 16:33:10 -0500 Subject: [PATCH 10/17] Add Tomer's suggestions --- docs/tokens/README.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index 760168e505..a65207fc48 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -99,7 +99,7 @@ Fully customizable contract tokens native to Soroban that implement the **[SEP-4 ### 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. +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 @@ -140,11 +140,13 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex | **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 | +| **Trustline Required** | ✅ Yes\* | ❌ No | ❌ No | | **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 as the owner of a Stellar Asset Contract, balances and transfer rules can be fully managed within the contract. This removes the need for user trustlines._ + ## Decision Guide Choose the right token model based on the use case: From 4f27866cdc7a98ddebd21a5b5d5737cb291b2097 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Mon, 12 Jan 2026 16:38:28 -0500 Subject: [PATCH 11/17] Add more info on storage --- docs/tokens/README.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index a65207fc48..14efdd2ef4 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -136,16 +136,17 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex | **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 | -| **Compliance Control** | Protocol flags + optional admin via SAC | Custom contract logic | Built-in compliance and rule enforcement | +| **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 as the owner of a Stellar Asset Contract, balances and transfer rules can be fully managed within the contract. This removes the need for user trustlines._ +_\* 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 From 265ff1840f723c83d237003efc9111383446106f Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Fri, 23 Jan 2026 16:20:05 -0500 Subject: [PATCH 12/17] Update asset comparison table --- docs/tokens/README.mdx | 240 ++++---------------------- docs/tokens/anatomy-of-an-asset.mdx | 250 +++++++++++++++++++++++++++- 2 files changed, 285 insertions(+), 205 deletions(-) diff --git a/docs/tokens/README.mdx b/docs/tokens/README.mdx index 14efdd2ef4..e5ee26ead1 100644 --- a/docs/tokens/README.mdx +++ b/docs/tokens/README.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 10 -title: "Tokenization Model Comparison on Stellar" +title: "Issuing Assets vs. Creating Custom Tokens: Key Differences & Best Practices" 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,224 +11,65 @@ The term "custom token" has been deprecated in favor of "contract token". View t ::: -This brief compares the three primary tokenization models available on the Stellar network: +# Stellar Assets and Contract Tokens -- 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) +Tokens exist in two forms on Stellar: -to help issuers select the most appropriate model for their use case. +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). -## 1. Stellar Classic Assets (with Built-in [Stellar Asset Contract][sac]) +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. -### What this category encompasses +However: -All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stellar Assets**. These assets can be represented in two forms: +### TL;DR -- **Native Classic Asset** - Held in trustlines and transferred via native payment operations. +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. -- **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. +## Issuing assets on Stellar -### How they work +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. -- 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’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. -### Strengths +Stellar assets: -- 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). +- 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). -### 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 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. - -### When to use - -- DeFi primitives requiring complex tokenomics. -- Asset behaviors not representable by Classic 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. - -## 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 +:::note -This allows Stellar assets to interoperate seamlessly with Soroban smart contracts. +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. -- [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 +Assets issued on the Stellar network are accessible to smart contracts with the use of that asset’s Stellar Asset Contract (SAC). -**Compatibility** -The SAC preserves full compatibility with the existing Stellar asset model, including trustlines, authorization flags, and the Stellar DEX. +### Stellar Asset Contract -**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. +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. -**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. +Read more about the SAC [here][sac]. -**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. +Learn how to deploy a Stellar Asset Contract for an asset in [this How-To Guide](../tools/cli/cookbook/deploy-stellar-asset-contract.mdx). -### Limitations of the SAC +**Benefits 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. +- 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. -If your use case requires token behavior not supported by Stellar assets, you should use a contract token instead. +**Downside of the SAC:** -### Contract Tokens +- 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. -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. +## Contract tokens -Key points: +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. -- 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 +The SAC also implements the token interface and applications that interoperate with the token interface can seamlessly interact with Stellar assets and contract tokens. :::note @@ -236,17 +77,12 @@ Smart contracts cannot use Stellar assets unless that Stellar asset has a deploy ::: -### 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. +**These example scenarios are not possible with the SAC and demonstrate what you could use the token interface for:** -- **Token Factory Pattern** - Build a factory contract that programmatically deploys new instances of a token contract, enabling standardized, on-demand token creation. +- 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. -## Helpful Links +## Helpful links - [Issue an asset tutorial][how-to-issue] - [Stellar Asset Contract][sac] @@ -255,7 +91,3 @@ The following scenarios are not possible using the SAC, but can be implemented w [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 diff --git a/docs/tokens/anatomy-of-an-asset.mdx b/docs/tokens/anatomy-of-an-asset.mdx index 1a1d0cd53f..ff2f1f0af4 100644 --- a/docs/tokens/anatomy-of-an-asset.mdx +++ b/docs/tokens/anatomy-of-an-asset.mdx @@ -1,8 +1,248 @@ --- -title: Assets Overview +title: Assets Overview and Comparison +description: Asset Overview and Comparison of Stellar Classic 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 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) + +to help issuers select the most appropriate model for their use case. + +## 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._ + +## 1. Stellar Classic Assets (with Built-in [Stellar Asset Contract][sac]) + +### What this category encompasses + +All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stellar Assets**. These assets can be represented in two forms: + +- **Native Classic Asset** + Held in trustlines and transferred via native 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 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). + +### 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 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. + +### When to use + +- DeFi primitives requiring complex tokenomics. +- Asset behaviors not representable by Classic 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: + +- **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 + +::::note Summary: TLDR + +- 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 about 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 + +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 +267,11 @@ 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. + +[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 From ecb4fba4258b71566858205c0115dc48809a6535 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Fri, 23 Jan 2026 16:34:53 -0500 Subject: [PATCH 13/17] Add Leigh's suggestions --- docs/tokens/anatomy-of-an-asset.mdx | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/tokens/anatomy-of-an-asset.mdx b/docs/tokens/anatomy-of-an-asset.mdx index ff2f1f0af4..9aa7a1e7af 100644 --- a/docs/tokens/anatomy-of-an-asset.mdx +++ b/docs/tokens/anatomy-of-an-asset.mdx @@ -44,8 +44,8 @@ _\* By assigning a smart contract (`C...` address) as the owner of a Stellar Ass All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stellar Assets**. These assets can be represented in two forms: -- **Native Classic Asset** - Held in trustlines and transferred via native payment operations. +- **Classic 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. @@ -58,13 +58,14 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel ### Strengths -- Has the benefits of native Stellar assets (fast, low cost), making these great for remittances and micropayments. +- 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. Classic assets are compatible with Stellar ecosystem products (such as Stellar wallets) and other ecosystem products (such as exchanges). +- 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 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). +- Operations on Classic Assets emit the same standardized events defined by SEP-41, because the Stellar Asset Contract implements the SEP-41 token interface, Payment operations on Classic Assets surface identical transfer events, allowing off-chain systems and indexers to observe asset activity through a uniform way. ### Tradeoffs @@ -80,7 +81,7 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel ### 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). +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 @@ -93,20 +94,18 @@ Fully customizable contract tokens native to Soroban that implement the **[SEP-4 - 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. +- 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 native Classic Asset operations. -- Less widespread ecosystem support compared to Classic Assets. +- Higher execution costs compared to Classic Asset operations. +- Less widespread ecosystem support compared to Classic Assets, including centralized exchange support. ### When to use @@ -118,7 +117,7 @@ Fully customizable contract tokens native to Soroban that implement the **[SEP-4 ### 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. +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 @@ -151,7 +150,7 @@ A **permissioned token standard** for regulated, compliance-aware assets that ex Choose the right token model based on the use case: -- **Classic Stellar Assets (with SAC)**: +- **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 @@ -181,7 +180,7 @@ Choose the right token model based on the use case: ## More Info about 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. +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. From 2349e0f1b4faa808f423d389c82ad0ff7d8d2413 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Fri, 23 Jan 2026 16:43:06 -0500 Subject: [PATCH 14/17] Add updates --- docs/tokens/anatomy-of-an-asset.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/tokens/anatomy-of-an-asset.mdx b/docs/tokens/anatomy-of-an-asset.mdx index 9aa7a1e7af..cfb0d52e14 100644 --- a/docs/tokens/anatomy-of-an-asset.mdx +++ b/docs/tokens/anatomy-of-an-asset.mdx @@ -1,5 +1,5 @@ --- -title: Assets Overview and Comparison +title: Assets Overview & Comparison description: Asset Overview and Comparison of Stellar Classic Asset (with SAC), SEP-41 Contract Token, and T-REX (Token for Regulated Exchanges) sidebar_position: 20 --- @@ -18,7 +18,7 @@ This brief compares the three primary tokenization models available on the Stell to help issuers select the most appropriate model for their use case. -## Tokenization Model Comparison Table +## Tokenization Model Comparison | Dimension | Stellar Classic Asset (with SAC) | SEP-41 Contract Token | ERC-3643 (T-REX) | | --- | --- | --- | --- | @@ -267,7 +267,6 @@ 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. -[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 From 16134c09870925ab33a11a3ea5b26b14185804cd Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Fri, 23 Jan 2026 16:56:17 -0500 Subject: [PATCH 15/17] Add update for assigning admin to a contract --- docs/tokens/anatomy-of-an-asset.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tokens/anatomy-of-an-asset.mdx b/docs/tokens/anatomy-of-an-asset.mdx index cfb0d52e14..fd989cfeda 100644 --- a/docs/tokens/anatomy-of-an-asset.mdx +++ b/docs/tokens/anatomy-of-an-asset.mdx @@ -66,6 +66,7 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel - 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). - Operations on Classic Assets emit the same standardized events defined by SEP-41, because the Stellar Asset Contract implements the SEP-41 token interface, Payment operations on Classic 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 From 175dca72b512474aa8d88cb22ece5eb67f8310aa Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Fri, 23 Jan 2026 17:00:34 -0500 Subject: [PATCH 16/17] Remove the word classic --- docs/tokens/anatomy-of-an-asset.mdx | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/tokens/anatomy-of-an-asset.mdx b/docs/tokens/anatomy-of-an-asset.mdx index fd989cfeda..813d627a35 100644 --- a/docs/tokens/anatomy-of-an-asset.mdx +++ b/docs/tokens/anatomy-of-an-asset.mdx @@ -1,6 +1,6 @@ --- title: Assets Overview & Comparison -description: Asset Overview and Comparison of Stellar Classic Asset (with SAC), SEP-41 Contract Token, and T-REX (Token for Regulated Exchanges) +description: Asset Overview and Comparison of Stellar Asset (with SAC), SEP-41 Contract Token, and T-REX (Token for Regulated Exchanges) sidebar_position: 20 --- @@ -12,7 +12,7 @@ The term "custom token" has been deprecated in favor of "contract token". View t This brief compares the three primary tokenization models available on the Stellar network: -- Stellar Classic Assets (with built-in Stellar Asset Contract), +- 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) @@ -20,7 +20,7 @@ to help issuers select the most appropriate model for their use case. ## Tokenization Model Comparison -| Dimension | Stellar Classic Asset (with SAC) | SEP-41 Contract Token | ERC-3643 (T-REX) | +| 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 | @@ -38,13 +38,13 @@ to help issuers select the most appropriate model for their use case. _\* 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 Classic Assets (with Built-in [Stellar Asset Contract][sac]) +## 1. Stellar Assets (with Built-in [Stellar Asset Contract][sac]) ### What this category encompasses -All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stellar Assets**. These assets can be represented in two forms: +All assets issued on the Stellar ledger (by a `G…` address) are **Stellar Assets**. These assets can be represented in two forms: -- **Classic Asset** +- **Stellar Asset** Held in trustlines and transferred via payment operations. - **Built-in Smart Contract (Stellar Asset Contract)** @@ -64,8 +64,8 @@ All assets issued on the Stellar ledger (by a `G…` address) are **Classic Stel - 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 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). -- Operations on Classic Assets emit the same standardized events defined by SEP-41, because the Stellar Asset Contract implements the SEP-41 token interface, Payment operations on Classic Assets surface identical transfer events, allowing off-chain systems and indexers to observe asset activity through a uniform way. +- 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 @@ -105,13 +105,13 @@ Fully customizable contract tokens that implement the **[SEP-41][sep-41] token s ### Tradeoffs -- Higher execution costs compared to Classic Asset operations. -- Less widespread ecosystem support compared to Classic Assets, including centralized exchange support. +- 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 Classic Assets alone. +- Asset behaviors not representable by Stellar Assets alone. - When extending SEP-41 with custom functionality. ## 3. ERC-3643 / SEP-57 (T-REX) Tokens @@ -173,7 +173,7 @@ Choose the right token model based on the use case: ::::note Summary: TLDR -- Classic Stellar Assets are best for simple payments and fiat-backed assets, with optional smart contract interoperability via the Stellar Asset Contract. +- 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. @@ -225,7 +225,7 @@ 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 +- 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 From ba1d6d682da900196b93496eb488de4a1598c944 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Fri, 23 Jan 2026 17:05:09 -0500 Subject: [PATCH 17/17] Update language --- docs/tokens/anatomy-of-an-asset.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/tokens/anatomy-of-an-asset.mdx b/docs/tokens/anatomy-of-an-asset.mdx index 813d627a35..f95e544773 100644 --- a/docs/tokens/anatomy-of-an-asset.mdx +++ b/docs/tokens/anatomy-of-an-asset.mdx @@ -42,13 +42,11 @@ _\* By assigning a smart contract (`C...` address) as the owner of a Stellar Ass ### What this category encompasses -All assets issued on the Stellar ledger (by a `G…` address) are **Stellar Assets**. These assets can be represented in two forms: +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. +- **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. +- **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