ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-03 18:15:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rewrite tokens section to clarify MPTs

Browse Source
This commit is contained in:
mDuo13
2025-09-23 17:30:19 -07:00
parent 49292c20ba
commit b4ba78b105
10 changed files with 235 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/concepts/tokens/fungible-tokens/index.md
View File

@@ -1,93 +1,58 @@
---
seo:
description: Learn about the properties and rationale of trust lines.
labels:
- Tokens
description: Fungible tokens are a way of representing currency or assets on the blockchain where each unit can be swapped for each other. Learn about the different fungible token standards on the XRP Ledger and which one to use.
---
# Fungible Tokens
Fungible tokens represent some sort of value, often a representation of assets that exist outside of the blockchain. Unlike [NFTs](../nfts/index.md), all units of a fungible token are interchangable for all other units of that token, just like how any US dollar is worth the same as another US dollar (even if one of them is a crisp, newly-printed dollar bill and the other is a number in a payment app on your phone).
Anyone can issue fungible tokens on the XRP Ledger, ranging from informal "IOUs" to fiat-backed stablecoins, purely digital fungible and semi-fungible tokens, and more.
There are two standards for fungible tokens in the XRP Ledger, representing an evolution based on how tokens have been used over time:
Fungible tokens are interchangeable and indistinguishable from one another. They can be swapped and substituted for other tokens of equivalent value. To create fungible tokens, you set up a _trust line_, a form of accounting relationship, between two accounts, then send payments between them. For most use cases, there are also some settings you should configure first.
- **Trust line tokens** are the "version 1" fungible token standard. They are fully available in production on the XRP Ledger, but they have some edge cases that are important to know about before using them.
- **Multi-Purpose Tokens (MPTs)** are the "version 2" fungible token standard. They are in active development, but do not have full feature parity with trust line tokens. They have been designed for greater efficiency and ease of use based on lessons learned from trust line tokens on the XRP Ledger. {% amendment-disclaimer name="MPTokensV1" /%}
## Trust Lines
Both types of tokens are built with a range of compliance-focused features such as [freezes](./freezes.md), [clawback](./clawing-back-tokens.md), and [allow-listing](./authorized-trust-lines.md), and are expected to be supported for the foreseeable future.
Trust lines are structures in the XRP Ledger for holding fungible [tokens](../index.md). Trust lines enforce the XRP Ledger's rule that you cannot cause someone else to hold a token they don't want. This precaution is necessary to enable the XRP Ledger's use case for [community credit](../index.md#community-credit) among other benefits.
## Trust Line Tokens
A trust line is defined as a [RippleState](../../../references/protocol/ledger-data/ledger-entry-types/ripplestate) object. Each trust line is a _bidirectional_ relationship consisting of:
Trust line tokens are fungible tokens that use a bidirectional trust model where users can issue tokens to one another. These tokens are tracked in on-chain data structures called _trust lines_. A trust line is a bidirectional relationship between two accounts for a single currency code.
- The identifiers for the two [accounts](../../accounts/index.md) that the trust line connects.
- A single, shared balance, which is positive from the perspective of one account and negative from the other perspective.
- The account with a negative balance is generally considered the "issuer" of the tokens. However, in the [APIs](../../../references/http-websocket-apis/index.md), the name `issuer` can refer to either side.
- Various settings and metadata. _Each_ of the two accounts can control its own settings on the trust line.
- Most importantly, each side sets a limit on the trust line, which is 0 by default. Each account's balance (from its perspective on the trust line) can't go above that account's limit, except [through that account's own actions](#going-above-the-limit).
Trust line tokens have been part of the XRP Ledger since it launched and have grown with amendments to the protocol since then. Trust line tokens can be used for [cross-currency payments](../../payment-types/cross-currency-payments.md) or traded in the [decentralized exchange](../decentralized-exchange/index.md).
Each trust line is specific to a given [currency code][]. Two accounts can have any number of trust lines between them for different currency codes, but only one shared trust line for any particular currency code.
Tokens with the same currency code but different issuers can [ripple](./rippling.md), a powerful feature for atomically settling and netting payments involving many different parties. However, when your settings are not configured correctly, rippling can lead to unexpected or undesirable movements between tokens from different issuers that use the same currency code. This feature makes trust line tokens the preferred standard for community credit use cases.
The balance on a trust line is negative or positive depending on which side you view it from. The side with the negative balance is called the "issuer" and can control some properties of how those tokens behave. When you send tokens to another account that isn't the issuer, those tokens "ripple" through the issuer and possibly other accounts using the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [No Ripple flag](rippling.md) on trust lines to prevent those trust lines from rippling.
Many properties of trust line tokens are defined at the account level, meaning that every token issued by the same account must share the same properties. Also, trust line tokens use a floating point representation which supports very large and very small quantities but can lead to suprising rounding effects in edge cases.
## Creation
See [Trust Lines Tokens](./trust-line-tokens.md) for more details about the properties and usage of trust line tokens.
Any account can unilaterally "trust" another account to issue a token by sending a [TrustSet transaction][] with a nonzero limit and their own settings. This creates a line with a zero balance, and sets the other side's settings to the default.
## Multi-Purpose Tokens
Trust lines can be implicitly created by some transactions, such as when you buy a token in the [decentralized exchange](../decentralized-exchange/index.md). In this case, the trust line uses entirely default settings.
Multi-Purpose Tokens (MPTs) are fungible tokens that use a unidirectional model where the issuer first defines an _MPT issuance_ with various properties, then issues units of that token to holders. Key features that distinguish MPTs from trust line tokens are:
- **Simpler conceptual model:** With unidirectional issuing, no rippling, and fixed-point precision, there are fewer edge cases to consider when building an integration that issues or uses MPTs.
- **Separate properties per token:** An on-chain MPT issuance definition contains the properties of the token, which can be different from other tokens from the same issuer.
- **Efficient storage format:** MPTs are designed to require less space in the shared ledger to store and send, so the network can more efficiently process large volumes of transactions.
## Going Above the Limit
See [Multi-Purpose Tokens](./multi-purpose-tokens.md) for more details about the properties and usage of MPTs.
There are three cases where you can hold a balance that is _greater_ than your limit on that trust line:
### Availability of MPT Features
1. When you acquire more of that token through [trading](../decentralized-exchange/index.md).
2. When you decrease the limit on a trust line that has a positive balance.
3. When you acquire more of that token by [cashing a Check](../../payment-types/checks.md). (_Requires the [CheckCashMakesTrustLine amendment][]_)
Functionality relating to MPTs is being added by a series of amendments to the XRP Ledger protocol to bring them to near-parity with trust line tokens. However, certain features, like rippling, are intentionally not being implemented for MPTs to keep the conceptual model simpler.
Some notable features and their status:
## Trust Line Settings
| MPT Feature | Amendment / Standard |
|-------------|----------------------|
| Issuing and direct payments | {% amendment-disclaimer name="MPTokensV1" compact="true" /%} |
| Escrow | {% amendment-disclaimer name="TokenEscrow" compact="true" /%} (implements escrow for both trust line tokens and MPTs) |
| Mutable token properties | In development: [XLS-94](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0094-dynamic-MPT) |
| Confidentiality | Proposed: [XLS-??](https://github.com/XRPLF/XRPL-Standards/discussions/372) |
| Decentralized exchange (DEX), trading, cross-currency payments, and AMM compatibility | Expected future work |
In addition to the shared balance, each account has its own settings on the trust line, which consist of the following:
## Which Fungible Token Type to Use
- The **Limit**, a number from 0 to the [maximum token amount](../../../references/protocol/data-types/currency-formats.md). Payments and other accounts' actions cannot cause the trust line's balance (from this account's perspective) to go over the limit. The default is `0`.
- **Authorized**: A true/false value used with [Authorized Trust Lines](authorized-trust-lines.md) to allow the other side to hold tokens this account issues. The default is `false`. Once set to `true`, this cannot be changed back.
- **No Ripple**: A true/false value to control whether tokens can [ripple](rippling.md) through this trust line. The default depends on the account's "Default Ripple" setting; for new accounts, "Default Ripple" is off which means that `true` is the default for No Ripple. Usually, issuers should allow rippling and non-issuers should disable rippling unless they are using trust lines for community credit.
- **Freeze**: A true/false value indicating whether an [individual freeze](freezes.md#individual-freeze) is in effect on this trust line. The default is `false`.
- **DeepFreeze**: A true/false value indicating whether a [deep freeze](deep-freeze.md) is in effect on this trust line. The default is `false`.
- **Quality In** and **Quality Out** settings, which allow the account to value tokens issued by the other account on this trust line at less (or more) than face value. For example, if a stablecoin issuer charges a 3% fee for withdrawing tokens for the equivalent off-ledger assets, you could use these settings to value those tokens at 97% of face value. The default, `0`, represents face value.
If you are creating a new token on the XRP Ledger, it may be confusing that there are two standards to choose from with different properties and strengths. If you aren't sure which one to use, the following summary should help you decide:
- If you need **compatibility with the DEX** or your use case is **community credit**, choose trust line tokens.
- For most cases, especially new tokens, MPTs are usually preferred.
## Reserves and Deletion
Since a trust line occupies space in the ledger, [a trust line increases the XRP your account must hold in reserve](../../accounts/reserves.md). Either or both accounts in the trust line may be charged the reserve for the trust line, depending on the status of the trust line: if any of your settings are not the default, or if you hold a positive balance, it counts as one item toward your owner reserve.
Generally, this means that the account that created the trust line is responsible for the reserve and the issuer is not. <!-- STYLE_OVERRIDE: is responsible for -->
Trust lines are automatically deleted if both sides' settings are in the default state and the balance is 0. This means that, to delete a trust line, you need to:
1. Send a [TrustSet transaction][] to set your settings to the defaults.
2. Offload any positive balance you have on the trust line. You could do this by sending a [payment](../../payment-types/cross-currency-payments.md), or by selling the currency in the [decentralized exchange](../decentralized-exchange/index.md).
If your balance is negative (you are the issuer) or the other side's settings are not in the default state, you cannot cause the trust line to be totally deleted, but you can make it so that it does not count towards your owner reserve by following the same steps.
Since the **Authorized** setting cannot be turned off after it has been turned on, it does not count toward the trust line's default state.
### Free Trust Lines
[[Source]](https://github.com/XRPLF/rippled/blob/2df7dcfdebcb0cdbd030c1f4b09ac748af95659c/src/xrpld/app/tx/detail/SetTrust.cpp#L387-L407 "Source")
Since trust lines are a powerful feature of the XRP Ledger, there is a special feature to make an account's first two trust lines "free".
When an account creates a new trust line, if the account owns at most 2 items in the ledger including the new line, the account's owner reserve is treated as zero instead of the normal amount. This allows the transaction to succeed even if the account does not hold enough XRP to meet the increased reserve requirement for owning objects in the ledger.
When an account owns 3 or more objects in the ledger, the full owner reserve applies.
## See Also
- **Concepts:**
- [Decentralized Exchange](../decentralized-exchange/index.md)
- [Rippling](rippling.md)
- **References:**
- [account_lines method][] - Look up trust lines attached to a given account
- [gateway_balances method][] - Look up an issuer's total balance issued
- [RippleState object](../../../references/protocol/ledger-data/ledger-entry-types/ripplestate.md) - The data format for trust lines in the ledger's state data.
- [TrustSet transaction][] - The transaction to create or modify trust lines.
{% raw-partial file="/docs/_snippets/common-links.md" /%}
There are other strengths and weaknesses of each format, such as trust line tokens' ability to represent very large and very small quantities of the same token (greater than 63 orders of magnitude apart), or compatibility with legacy software.