mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-30 00:25:49 +00:00
Rewrite tokens section to clarify MPTs
This commit is contained in:
mDuo13
@@ -9,7 +9,7 @@ labels:
|
||||
---
|
||||
# Authorized Trust Lines
|
||||
|
||||
The Authorized Trust Lines feature enables issuers to create tokens that can only be held by accounts that the issuer specifically authorizes. This feature only applies to tokens, not XRP.
|
||||
The Authorized Trust Lines feature enables issuers to create [trust line tokens](./trust-line-tokens.md) that can only be held by accounts that the issuer specifically authorizes—in other words, allow-listing access to all of an issuer's tokens. This page describes the feature as it applies to trust line tokens, but [multi-purpose tokens](./multi-purpose-tokens.md) have a similar setting on a per-token basis. Allow-listing does not apply to XRP.
|
||||
|
||||
To use the Authorized Trust Lines feature, enable the **Require Auth** flag on your issuing account. While the setting is enabled, other accounts can only hold tokens you issue if you have authorized those accounts' trust lines to your issuing account.
|
||||
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
html: clawing-back-tokens.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
seo:
|
||||
description: Issuers can claw back their tokens for compliance purposes if they enable the Clawback feature before issuing tokens.
|
||||
labels:
|
||||
@@ -8,19 +6,25 @@ labels:
|
||||
---
|
||||
# Clawing Back Tokens
|
||||
|
||||
{% partial file="/docs/_snippets/clawback-disclaimer.md" /%}
|
||||
For regulatory purposes, some issuers need the ability to recover tokens after they are distributed to accounts. For example, if an issuer were to discover that tokens were sent to an account sanctioned for illegal activity, the issuer could recover, or *claw back*, the funds. The ability to claw back funds is controlled differently for different types of tokens:
|
||||
|
||||
For regulatory purposes, some issuers need the ability to recover tokens after they are distributed to accounts. For example, if an issuer were to discover that tokens were sent to an account sanctioned for illegal activity, the issuer could recover, or *claw back*, the funds.
|
||||
- Issuers can gain the ability to claw back any of their [trust line tokens](./trust-line-tokens.md) by enabling the **Allow Clawback** flag on their issuing account. This flag cannot be enabled if the issuer has already issued trust line tokens.
|
||||
- [MPTs](./multi-purpose-tokens.md) can be clawed back by the issuer if the **Can Clawback** flag is enabled for the MPT issuance. {% amendment-disclaimer name="MPTokensV1" /%}
|
||||
- XRP is not a token and cannot be clawed back.
|
||||
|
||||
Issuers can gain the ability to claw back their tokens by enabling the **Allow Clawback** flag on their issuing account. This flag cannot be enabled if the issuer has already issued tokens.
|
||||
{% amendment-disclaimer name="Clawback" /%}
|
||||
|
||||
{% admonition type="info" name="Note" %}You can only claw back issued tokens created by your account. You cannot claw back XRP in this way.{% /admonition %}
|
||||
## Allow Clawback for Trust Line Tokens
|
||||
|
||||
Clawback is disabled by default. To use clawback, you must send an [AccountSet transaction][] to enable the **Allow Trust Line Clawback** setting. **An issuer with any existing tokens cannot enable Clawback.** You can only enable **Allow Trust Line Clawback** if you have a completely empty owner directory, meaning you must do so before you set up any trust lines, offers, escrows, payment channels, checks, or signer lists.
|
||||
|
||||
If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trust lines.
|
||||
Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set, the transaction also returns `tecNO_PERMISSION`.
|
||||
|
||||
## Allow Clawback for MPTs
|
||||
|
||||
Clawback is disabled by default. To use clawback, the MPT must be configured with the **Can Clawback** flag enabled. This flag is part of the MPT issuance definition, which is configured before tokens are issued.
|
||||
|
||||
## Example Clawback Transaction
|
||||
|
||||
```json
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
html: freezes.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
seo:
|
||||
description: Issuers can freeze their issued tokens for compliance purposes.
|
||||
labels:
|
||||
@@ -10,18 +8,21 @@ labels:
|
||||
|
||||
Issuers can freeze the tokens they issue in the XRP Ledger. **This does not apply to XRP,** which is the native asset of the XRP Ledger, not an issued token.
|
||||
|
||||
In certain cases, to meet regulatory requirements, or while investigating suspicious activity, an exchange or gateway may want to freeze token balances.
|
||||
In certain cases, to meet regulatory requirements, or while investigating suspicious activity, an issuer may want to freeze a balance they issue. This page describes the freeze functionality of [trust line tokens](./trust-line-tokens.md).
|
||||
|
||||
{% admonition type="success" name="Tip" %}No one can freeze XRP in the XRP Ledger. However, custodial exchanges can always freeze the funds they custody at their own discretion. For more details, see [Common Misunderstandings about Freezes](common-misconceptions-about-freezes.md).{% /admonition %}
|
||||
|
||||
There are three settings related to freezes:
|
||||
Trust line tokens have these settings related to freezes:
|
||||
|
||||
* [**Individual Freeze**](#individual-freeze) - Freeze one counterparty.
|
||||
* [**Individual Freeze**](#individual-freeze) - Freeze one counterparty, so they cannot spend tokens.
|
||||
* [**Deep Freeze**](./deep-freeze.md) - Further freeze one counterparty, so that they cannot receive those tokens, either.
|
||||
* [**Global Freeze**](#global-freeze) - Freeze all counterparties.
|
||||
* [**No Freeze**](#no-freeze) - Permanently give up the ability to freeze individual counterparties, as well as the ability to end a global freeze.
|
||||
|
||||
All freeze settings can be enacted regardless of whether the balance(s) to be frozen are positive or negative. Either the token issuer or the currency holder can freeze a trust line; however, the effect is minimal when a currency holder enacts a freeze.
|
||||
|
||||
[MPTs](./multi-purpose-tokens.md) have similar functionality, but it is called "locking" and individual freezes always function like deep freeze.
|
||||
|
||||
|
||||
## Individual Freeze
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -7,82 +7,98 @@ labels:
|
||||
- Multi-purpose Tokens
|
||||
status: not_enabled
|
||||
---
|
||||
# Multi-purpose Tokens
|
||||
# Multi-Purpose Tokens
|
||||
|
||||
_(Requires the [MPTokensV1 amendment][] {% not-enabled /%})_
|
||||
Multi-Purpose Tokens (MPTs) are a form of [fungible token](./index.md) on the XRP Ledger. They have been designed for greater efficiency and ease of use based on lessons learned from [trust line tokens](./trust-line-tokens.md) on the XRP Ledger.
|
||||
|
||||
Multi-purpose tokens (MPTs) are a more compact and flexible type of [fungible token](./index.md) on the XRP Ledger.
|
||||
MPTs let you take advantage of ready-to-use tokenization features with a few lines of code. You can create many token experiences from one integration, while the code of the XRP Ledger blockchain does the heavy lifting.
|
||||
|
||||
MPTs let you take advantage of ready-to-use tokenization features with a few lines of code. You can create many token experiences from one token program itself.
|
||||
{% amendment-disclaimer name="MPTokensV1" /%}
|
||||
|
||||
## Core Properties of MPTs on XRPL
|
||||
|
||||
The following properties are inherent to all fungible tokens on the XRP Ledger, including MPTs:
|
||||
|
||||
- **Anyone can be an issuer.** Every account has the capability to be a token issuer, and you can issue a very large quantity and variety of tokens from one account. Issuers can mint new units of any of their issuances at any time, subject to configurable limits, by sending [Payment transactions][].
|
||||
- **Issuers are separate from holders.** An issuer cannot hold their own tokens. If you send tokens to the issuer, those tokens are automatically burned. Issuers should use separate [operational accounts](../../accounts/account-types.md)—also called hot wallets—if they want to hold their own tokens.
|
||||
- **You can't force someone to hold tokens.** Holders must send a transaction that indicates their willingness to hold a token before they can receive it.
|
||||
|
||||
Unlike trust line tokens, each MPT issuance is uniquely identified by an **MPT Issuance ID**, which is a 192-bit number not intended for display to humans, for example `00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000`. MPTs can be configured with metadata that affects how they are displayed, but there are no hard guarantees about the presence or uniqueness of currency codes.
|
||||
|
||||
## Key Features of MPTs on XRPL
|
||||
|
||||
The following are notable features of MPTs on XRPL.
|
||||
MPTs are designed decentralized finance, so they are ready to go with settings and features for institutional use cases:
|
||||
|
||||
**On-Chain Metadata Storage**
|
||||
- **On-Chain Metadata:** Each MPT issuance has key properties defined on the ledger, so everyone can look up its data on-chain and the ledger's transaction engine can automatically enforce specific rules. Since MPT settings are defined separately instead of at the account level, you don't have to set up separate accounts to issue tokens with different settings, which also helps minimize your exposure to cyberattacks.
|
||||
- **Transferability controls:** MPTs can be made non-transferable, or holdable only by approved users.
|
||||
- **Supply cap:** MPTs can be configured with a maximum issued quantity, so that the amount in circulation is never more than this number.
|
||||
- **Transfer fees:** The issuer can charge a percentage fee for users to transfer the tokens among themselves.
|
||||
- **Compliance controls:** The issuer can freeze holders' balances or claw back the tokens, or they can configure an MPT issuance so that those tokens can't be frozen or clawed back.
|
||||
- **Simpler conceptual model:** MPTs are unidirectional, with no balance netting and an explicit separation between holder and issuer. Additionally, they intentionally lack features like rippling which introduce more tricky edge cases.
|
||||
|
||||
- MPTs store their metadata directly on the XRPL blockchain. Once set, the metadata is immutable.
|
||||
- A 1024-byte URI field provides a metadata pointer that allows you to use an off-chain source for metadata in addition to the on-chain source. This lets your application access necessary information directly from the chain, prompting higher interoperability for tokens, without losing the ability to attach additional information.
|
||||
### On-Chain Metadata
|
||||
|
||||
**Transferability and Supply Controls**
|
||||
Every MPT issuance has a set of key properties defined in the ledger as an [MPTokenIssuance entry][]. This object contains both _functional_ and _non-functional_ data about the MPT:
|
||||
|
||||
- MPTs can have a fixed token supply where you set a cap on the maximum number of tokens that can be minted.
|
||||
- You can define MPTs as non-transferable, tokens that can only be transferred back to the issuer, but not among tokenholders. Useful for cases such as issuing airline credits or loyalty rewards.
|
||||
- Issuers can set transfer fees to collect on-chain revenue each time the token is traded among tokenholders.
|
||||
- Functional data includes settings such as the MPT's transfer fee and maximum quantity, if any. There are also on-off flags to control properties such as the transferability of the token.
|
||||
- Non-functional data includes the asset scale (how much the asset can be subdivided—that is, where to put the decimal point) and up to 1024 bytes of arbitrary metadata. By convention, the metadata should be JSON data that conforms to the schema defined in [XLS-89](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0089-multi-purpose-token-metadata-schema).
|
||||
|
||||
**Built-In Compliance Features**
|
||||
After the MPT is issued, the on-chain data cannot be changed. However, the proposed [XLS-94: Dynamic MPT standard](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0094-dynamic-MPT) {% not-enabled /%} would allow fields to be marked as mutable during creation, so that those fields can be changed later.
|
||||
|
||||
MPTs also have advanced compliance features, including:
|
||||
- The ability to lock tokens held by a tokenholder to support compliance requirements.
|
||||
- The ability to set a global lock for all MPT balances across all tokenholders.
|
||||
- The issuer can configure MPTs that can be clawed back from tokenholder wallets, either to revoke them, or to reassign them in the case of lost wallet keys.
|
||||
- An opt-in feature can allow only wallets authorized by the issuer to hold issued tokens.
|
||||
### Transferability Controls
|
||||
|
||||
## MPTs versus Trust Lines
|
||||
MPTs can be configured with different levels of transferability controls by adjusting the following flags:
|
||||
|
||||
These are the primary differences between MPTs and [trust lines](/docs/concepts/tokens/fungible-tokens#trust-lines).
|
||||
- **Can Transfer:** If this flag is enabled, holders can transfer the token to each other. Otherwise, the MPT is non-transferable, meaning it can only be sent directly back to the issuer.
|
||||
- **Require Auth:** If this flag is enabled, holders must get explicit approval from the issuer before they can hold this token—in other words, it uses allow-listing. Otherwise, anyone can hold the token if they are willing.
|
||||
- **Can Trade:** If this flag is enabled, holders are allowed to trade the token in the decentralized exchange. However, trading MPTs in the DEX is not currently implemented.
|
||||
- **Can Escrow:** If this flag is enabled, holders are allowed to place the token in escrow. Otherwise, the token cannot be escrowed. {% amendment-disclaimer name="TokenEscrow" /%}
|
||||
|
||||
**Conceptual Differences**
|
||||
### Supply Cap
|
||||
|
||||
- Unlike trust lines, MPTs do not represent bidirectional debt relationships. Instead, MPTs function more like a unidirectional trust line with only one balance. This reduces the overhead to support common tokenization requirements, including non-monetary use cases such as tracking reputation points in an online game.
|
||||
MPTs can be configured with a supply cap, such that the number of tokens in circulation is never larger than this number.
|
||||
|
||||
- MPTs offer a less complicated conceptual model than trust lines.
|
||||
Note that this is not a cap on the total number of tokens issued over time. If holders "burn" tokens by sending them back to the issuer, then the issuer can issue more tokens until the number in circulation is at the cap.
|
||||
|
||||
**Ledger Storage and Performance**
|
||||
Even though issuers can't hold their own tokens, you can view the amount of tokens held by the issuer to be equal to the supply cap minus the number of tokens currently in circulation, since burning the tokens is the same as returning them to the issuer.
|
||||
|
||||
- MPTs require significantly less space than trust lines. They require roughly 52 bytes for each MPT held by a token holder, compared to at least 234 bytes for every new trust line.
|
||||
### Transfer Fees
|
||||
|
||||
- They reduce the long-term infrastructure and storage burdens for node operators, increasing network resiliency.
|
||||
MPTs can be configured with a transfer fee, so that holders must pay a percentage fee to transfer the tokens among themselves. The transfer fee does not apply when sending directly to the issuer, and non-transferable tokens cannot have a transfer fee.
|
||||
|
||||
- MPTs also improve node perfomance when processing large volumes of transactions.
|
||||
MPTs' transfer fees have a range from **0** to **50.000%** in increments of **0.0001%**. The transfer fee is charged on top of the amount delivered, and is paid by burning the tokens. For example, to deliver $100.00 with a transfer fee of 0.5%, the sender would pay $100.50, the receiver would get $100.00, and the remaining $0.50 would be burned.
|
||||
|
||||
**Transfer Logic and Directionality**
|
||||
### Compliance Controls
|
||||
|
||||
- MPTs are unidirectional. While trust lines use "balance netting," MPTs have only a single balance.
|
||||
- An account can issue a maximum of 32 unique MPT issuances. If an issuer wants to support more than this number of MPTs, they can open additional accounts.
|
||||
- Since token holders will not acquire an MPT without first making an off-ledger trust decision, MPTs have no trust limits. For example, a common use case for an MPT is a [fiat-backed stablecoin](/docs/concepts/tokens/fungible-tokens/stablecoins#fiat-backed), where a token holder wouldn't purchase more stablecoins than they would feel comfortable holding.
|
||||
- Unlike some existing capabilities of the ledger, MPTs are not subject to [rippling](/docs/concepts/tokens/fungible-tokens/rippling) and do not require configurability settings related to that functionality.
|
||||
MPTs can be configured with different controls for managing the tokens, in addition to the [transferability controls](#transferability-controls). These controls include:
|
||||
|
||||
## MPTs versus IOUs
|
||||
- The issuer can lock and unlock a specific token holder's balance; while locked, it cannot increase or decrease except in payments directly to the issuer. This is functionally equivalent to [deep freeze](./deep-freeze.md) on trust line tokens.
|
||||
- The issuer can also globally lock (freeze) all MPTs of a particular issuance.
|
||||
- The issuer can claw back funds from a particular holder. This can be used to revoke them, or to reassign the tokens in case the holder lost the keys to their account.
|
||||
|
||||
MPTs are different from IOUs in the following ways.
|
||||
The power to perform these actions is controlled by two flags on the MPT issuance:
|
||||
|
||||
**Technical Representation on the Ledger**
|
||||
- **Can Lock:** If enabled, the issuer can lock MPTs individually or globally. Otherwise, the MPTs cannot be locked/frozen in any way.
|
||||
- **Can Clawback:** If enabled, the issuer can claw back tokens from holders. Otherwise, the MPTs cannot be clawed back.
|
||||
|
||||
On a technical level, MPTs provide a fundamentally different way to represent fungible tokens on the ledger. While IOUs are represented by trustlines and have bilateral debt relationships, MPTs use a simpler, unilateral relationship captured by an MPToken object. This results in substantial space savings on the ledger.
|
||||
### Simpler Conceptual Model
|
||||
|
||||
The representation of a fungible token as a token object instead of a trustline makes it easier to enable functionality for real-world financial assets on-chain, such as token-level metadata, fixed supply, and fixed-point balance.
|
||||
The bidirectional model of trust line tokens, where two users could swap roles between issuer and holder in the middle of processing a transaction, is a source of complexity and tricky edge cases that is intentionally omitted from the MPT design.
|
||||
|
||||
**Developer Experience and App Design**
|
||||
On a usage level, MPTs provide a straightforward conceptual model compared to [trustlines](/docs/concepts/tokens/fungible-tokens#trust-lines) and [rippling](/docs/concepts/tokens/fungible-tokens/rippling). Developers can more easily build web3 applications around `[MPToken](/docs/references/protocol/ledger-data/ledger-entry-types/mptoken)` and `[MPTokenIssuance](/docs/references/protocol/ledger-data/ledger-entry-types/mptokenissuance)` objects, with some similarities to the conceptual model of XLS-20 NFTs.
|
||||
Each MPT issuance is totally separate and there is no rippling between tokens, only transferring between holders. MPT balances are always positive and use fixed-precision integers instead of floating-point math.
|
||||
|
||||
It is also simpler for ordinary users to understand what tokens are available, what tokens they have issued, and what they hold in their wallet.
|
||||
MPTs _do_ still support [partial payments](../../payment-types/partial-payments.md), so it is still necessary to avoid the related pitfalls when processing MPT payments.
|
||||
|
||||
For both issuers and holders of MPTs, there will typically be a smaller XRP reserve compared to the equivalent representations with IOU trustlines.
|
||||
|
||||
## Use Case and Long-Term Considerations
|
||||
## Limits on Issuing
|
||||
|
||||
There is not intended to be a limit on how many MPT issuances you can create, but the technology does impose some hard and soft limits indirectly:
|
||||
|
||||
- The ledger entry that defines an MPT issuance counts as one object towards the issuer's [owner reserve](../../accounts/reserves.md#owner-reserves), so the issuer needs to set aside {% $env.PUBLIC_OWNER_RESERVE %} per MPT issuance.
|
||||
- Each holder's balance of MPTs is tracked in both the holder's and issuer's [owner directories](/docs/references/protocol/ledger-data/ledger-entry-types/directorynode). The maximum number of items that can be in an owner directory is very large, but finite, which places a hard cap on how many MPT issuances you can issue.
|
||||
|
||||
The data type that holds MPT balances has a valid range of **0** to **2<sup>63</sup>-1** (inclusive) in integer increments, so no more than that amount can exist in any one place. However, it is possible for multiple holders to each hold up to that amount at the same time, so that the total amount in circulation is higher. An MPT issuance's supply cap, if configured, is also limited by this range.
|
||||
|
||||
MPTs are intended to be complementary to IOUs. While there might be use cases where either MPTs or IOUs might be suitable, there will likely be a need for both over the long term. There will be use cases such as credit lines for lending and borrowing that might be better represented by IOUs long term. The MPT feature set should evolve in an incremental manner to unlock more common use cases first and deliver additional feature support at a later time. During the MPT development period, some cases might still be better represented by an IOU, and then later be better supported with MPTs.
|
||||
|
||||
## See Also
|
||||
|
||||
|
||||
@@ -9,11 +9,11 @@ labels:
|
||||
---
|
||||
# Paths
|
||||
|
||||
In the XRP Ledger, paths define a way for [tokens](../index.md) to flow through intermediary steps as part of a payment. Paths enable [cross-currency payments](../../payment-types/cross-currency-payments.md) by connecting sender and receiver through orders and [automated market makers (AMM)](../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) in the XRP Ledger's [decentralized exchange](../decentralized-exchange/index.md). Paths also enable complex settlement of offsetting debts.
|
||||
In the XRP Ledger, paths define a way for [trust line tokens](../trust-line-tokens.md) to flow through intermediary steps as part of a payment. Paths enable [cross-currency payments](../../payment-types/cross-currency-payments.md) by connecting sender and receiver through orders and [automated market makers (AMM)](../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) in the XRP Ledger's [decentralized exchange](../decentralized-exchange/index.md). Paths also enable complex settlement of offsetting debts.
|
||||
|
||||
A single Payment transaction in the XRP Ledger can use multiple paths, combining liquidity from different sources to deliver the desired amount. Thus, a transaction includes a _path set_, which is a collection of possible paths to take. All paths in a path set must start with the same currency, and must also end with the same currency as each other.
|
||||
|
||||
Since XRP can be sent directly to any address, an [XRP-to-XRP transaction](../../payment-types/direct-xrp-payments.md) does not use any paths.
|
||||
[XRP-to-XRP transactions](../../payment-types/direct-xrp-payments.md) and MPT transfers are always sent directly, and do not use any paths.
|
||||
|
||||
## Path Steps
|
||||
|
||||
|
||||
@@ -7,10 +7,12 @@ labels:
|
||||
---
|
||||
# Rippling
|
||||
|
||||
Rippling is the _indirect movement_ of funds that occurs for any payment of fungible tokens (except when an issuing account exchanges tokens directly with another account). This includes when one holder sends tokens to another holder of the same token.
|
||||
Rippling is the _indirect movement_ of funds that occurs for any payment of [trust line tokens](./trust-line-tokens.md) (except when an issuing account exchanges tokens directly with another account). This includes when one holder sends tokens to another holder of the same token.
|
||||
|
||||
Rippling can automatically exchange tokens that have the same currency code, even if they have different issuers. This helps to facilitate longer and more complex payments between accounts.
|
||||
|
||||
[MPTs](./multi-purpose-tokens.md) intentionally do not support rippling.
|
||||
|
||||
## Example of Rippling
|
||||
|
||||
Issuers distribute currency to holders over trust lines. When a holder creates a trust line to an issuer for a specific token, they are willing to accept payments of that token. For example, in the chart below, Holder A and Holder B both have trust lines to the Issuer of the token USD.
|
||||
|
||||
@@ -1,29 +1,27 @@
|
||||
---
|
||||
html: stablecoins.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
seo:
|
||||
description: There are five common types of stablecoin traded on the XRP Ledger.
|
||||
description: Stablecoins are a type of fungible token that are backed by various assets.
|
||||
labels:
|
||||
- XRP
|
||||
- Stablecoin
|
||||
---
|
||||
# Stablecoins
|
||||
|
||||
A Stablecoin holds assets of value outside of the XRP Ledger and issues tokens representing the equivalent value on the ledger. This type of issuer is sometimes called a _gateway_, because currency can move into and out of the XRP Ledger through their service. If the assets that back a token use the same amounts and denomination as the tokens in the ledger, that token can be considered a "stablecoin" because – in theory – the exchange rate between that token and its off-ledger representation should be stable at 1:1.
|
||||
A stablecoin is a type of fungible token that is backed by assets of value outside of the blockchain in which is issued. Typically, the stablecoin's issuer holds backing assets representing the equivalent value of the tokens issued on the XRP ledger. A stablecoin issuer is sometimes called a _gateway_, because currency can move into and out of the XRP Ledger through their service. If the assets that back a token use the same amounts and denomination as the tokens in the ledger, that token can be considered a "stablecoin" because—in theory—the exchange rate between that token and its off-ledger representation should be stable at 1:1.
|
||||
|
||||
A stablecoin issuer should offer _deposits_ and _withdrawals_ to exchange the tokens for the actual currency or asset in the world outside the XRP Ledger.
|
||||
|
||||
In practice, the XRP Ledger is a computer system that cannot enforce any rules outside of itself, so stablecoins on the XRP Ledger depend on their issuer's integrity. If you can't count on the stablecoin's issuer to redeem your tokens for the real thing on demand, then you shouldn't expect the stablecoin to hold its value. As a user, you should be mindful of who's issuing the tokens: are they reliable, lawful, and solvent? If not, it's probably best not to hold those tokens.
|
||||
In practice, the XRP Ledger is a computer system that cannot enforce any rules outside of itself, so stablecoins depend on their issuer's integrity. If you can't count on the stablecoin's issuer to redeem your tokens for the real thing on demand, then you shouldn't expect the stablecoin to hold its value. As a user, you should be mindful of who's issuing the tokens: are they reliable, lawful, and solvent? If not, it's probably best not to hold those tokens.
|
||||
|
||||
There are five common types of currency token traded on the XRP Ledger.
|
||||
|
||||
## Fiat Backed
|
||||
|
||||
Fiat-backed stablecoins are based on an existing currency such as EUR, USD, YEN, and so on. They are backed at an exchange rate of 1:1. It is a simple, stable option, but it is more centralized and susceptible to hacking. In the strictest definition of a "stablecoin", only 100% fiat-backed tokens qualify.
|
||||
Fiat-backed stablecoins are based on a government-issued currency such as the Euro, US Dollar, Japanese Yen, and so on. They are backed at an exchange rate of 1:1. It is a simple, stable option whose pricing structures exactly match what users are familiar with, but it has many of the same downsides of the underlying fiat currency including being tied to specific national interests and subject to inflation. In the strictest definition of a "stablecoin", only 100% fiat-backed tokens qualify.
|
||||
|
||||
## Crypto Backed
|
||||
|
||||
Crypto-backed stablecoins are similar to fiat-backed stablecoins, but set aside a certain amount of cryptocurrency as collateral. It's decentralized, doesn't require a custodian or audits and regulation. It's also more volatile, and reliant on the stability of the underlying cryptocurrency.
|
||||
Crypto-backed stablecoins are similar to fiat-backed stablecoins, but using cryptocurrency as collateral. They are more volatile, like their underlying cryptocurrency, and may have limitations or costs associating with withdrawing or depositing based on the underlying cryptocurrency's network and its properties. Crypto-backed stablecoins can be backed with publicly-viewable wallets, so you don't need auditors to confirm the value of the backing assets, but the backing wallets require the highest cybersecurity standards to protect them against malicious actors trying to steal the funds.
|
||||
|
||||
## Commodity Backed
|
||||
|
||||
|
||||
101
docs/concepts/tokens/fungible-tokens/trust-line-tokens.md
Normal file
101
docs/concepts/tokens/fungible-tokens/trust-line-tokens.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
seo:
|
||||
description: Learn about the properties and rationale of trust lines and fungible tokens.
|
||||
labels:
|
||||
- Tokens
|
||||
---
|
||||
# Trust Line Tokens
|
||||
|
||||
Trust lines tokens are a type of [fungible token](../index.md) in the XRP Ledger. They are tracked in trust lines, which enforce the rule that you cannot cause someone else to hold a token they don't want. This is the original token standard of the XRP Ledger, in contrast to [Multi-Purpose Tokens](./multi-purpose-tokens.md).
|
||||
|
||||
|
||||
## Structure
|
||||
|
||||
A trust line is recorded in the ledger as a [RippleState entry][]. Each trust line is a _bidirectional_ relationship consisting of:
|
||||
|
||||
- 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).
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Creation
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Going Above the Limit
|
||||
|
||||
There are three cases where you can hold a balance that is _greater_ than your limit on that trust line:
|
||||
|
||||
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][]_)
|
||||
|
||||
|
||||
## Trust Line Settings
|
||||
|
||||
In addition to the shared balance, each account has its own settings on the trust line, which consist of the following:
|
||||
|
||||
- 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.
|
||||
|
||||
|
||||
## Properties
|
||||
|
||||
Unlike XRP or MPTs, trust line tokens always exist in _trust lines_, and all transfers move along trust lines. You cannot cause someone else's account to hold more of a token than the _limit_ configured on their trust line. (You _can_ cause your own trust line to go over the limit, for example by buying more of it in the decentralized exchange or by decreasing the limit after you already have a positive balance.)
|
||||
|
||||
Anyone can issue trust line tokens by sending a [Payment transaction][] if the necessary trust lines are in place. You can "burn" tokens by sending them back to the issuer. In some cases, cross-currency payments or trades can also create more tokens according to an issuer's settings.
|
||||
|
||||
Issuers have options with tokens that are not available with XRP. Issuers can charge a [transfer fee](transfer-fees.md) that is automatically deducted when users transfer their tokens. Issuers can also define a [tick size](decentralized-exchange/ticksize.md) for exchanges rates involving their tokens. Both issuers and regular accounts can [freeze](fungible-tokens/freezes.md) trust lines, which limits how the tokens in those trust lines can be used.
|
||||
|
||||
Trust line tokens use decimal (base-10) math with 15 digits of precision and an exponent that allows them to express very large values (up to 9999999999999999 × 10<sup>80</sup>) and very small values (down to 1.0 × 10<sup>-81</sup>).
|
||||
|
||||
## 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" /%}
|
||||
@@ -1,22 +1,19 @@
|
||||
---
|
||||
html: tokens.html
|
||||
parent: concepts.html
|
||||
seo:
|
||||
description: Anyone can make tokens representing digital value on the XRP Ledger.
|
||||
description: Anyone can make tokens representing digital value on the XRP Ledger. Learn about types of tokens and how they are used.
|
||||
labels:
|
||||
- Tokens
|
||||
---
|
||||
# Tokens
|
||||
|
||||
All assets other than XRP can be represented in the XRP Ledger as _tokens_.
|
||||
All assets other than XRP can be represented in the XRP Ledger as _tokens_. Tokens can be fungible, meaning all units of that token are interchangeable and indistinguishable; or non-fungible, meaning each token is unique and indivisible. The XRP has three token standards to choose from, depending on the type of asset you need:
|
||||
|
||||
Standard tokens are fungible: meaning, all units of that token are interchangeable and indistinguishable. Tokens can be used for [cross-currency payments](../payment-types/cross-currency-payments.md) and can be traded in the [decentralized exchange](decentralized-exchange/index.md).
|
||||
- **Trust line tokens** are the "version 1" fungible token standard. They are fully available in production on the XRP Ledger, and can be used for [cross-currency payments](../payment-types/cross-currency-payments.md) or traded in the [decentralized exchange](decentralized-exchange/index.md). However, they have some edge cases that are important to know about before using them.
|
||||
{% admonition type="info" name="Note" %}Trust line tokens on the XRP Ledger have also been called "IOUs" (as in [I-owe-you](https://en.wikipedia.org/wiki/IOU)) and "issued currencies" in the past. However, these terms are not preferred because they do not cover the full range of digital assets that these tokens can represent. <!-- STYLE_OVERRIDE: ious -->{% /admonition %}
|
||||
- **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" /%}
|
||||
- **[Non-fungible tokens (NFTs)](nfts/index.md)** encode ownership of unique and indivisible tokens, which could represent physical, non-physical, or purely digital goods, such as works of art or in-game items.
|
||||
|
||||
{% admonition type="info" name="Note" %}Tokens on the XRP Ledger have also been called "IOUs" (as in [I-owe-you](https://en.wikipedia.org/wiki/IOU)) and "issued currencies" in the past. However, these terms are not preferred because they do not cover the full range of digital assets that XRP Ledger tokens can represent. <!-- STYLE_OVERRIDE: ious -->{% /admonition %}
|
||||
|
||||
Tokens can also be non-fungible. Non-fungible tokens (NFTs) serve to encode ownership of unique physical, non-physical, or purely digital goods, such as works of art or in-game items.
|
||||
|
||||
See [Fungible Tokens](fungible-tokens/index.md) and [Non-fungible Tokens](nfts/index.md).
|
||||
Anyone can issue any of these types of tokens on the XRP Ledger, for any use case ranging from informal "IOUs" to institutional-grade, fiat-backed stablecoins, purely digital fungible and semi-fungible tokens, and more.
|
||||
|
||||
## Stablecoins
|
||||
|
||||
@@ -32,20 +29,20 @@ For more on this type of usage, see [paths](fungible-tokens/paths.md). <!--{# TO
|
||||
|
||||
## Other Tokens
|
||||
|
||||
There are other use cases for tokens issued in the XRP Ledger. For example, you can create an "Initial Coin Offering" (ICO) by issuing a fixed amount of currency to a secondary address, then "throwing away the key" to the issuer.
|
||||
There are other use cases for tokens issued in the XRP Ledger, including digital-only tokens that are intended for use in various online systems. It is also common for users to create and trade "meme coins" for novelty and speculative purposes, without any more serious use case in mind. Digital first tokens are sometimes distributed with an "Initial Coin Offering" (ICO) where a fixed amount of tokens are initially created and distributed, with the issuer then "throwing away the key" to their account so that no more tokens can be issued later.
|
||||
|
||||
{% admonition type="danger" name="Warning" %}ICOs might be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA. <!-- SPELLING_IGNORE: ico, icos -->{% /admonition %}
|
||||
|
||||
Be sure to research the relevant regulations before engaging in any financial service business.
|
||||
|
||||
## Token Properties
|
||||
## Differences from XRP
|
||||
|
||||
Tokens in the XRP Ledger are fundamentally different than XRP. Tokens always exist in _trust lines_, and all transfers of tokens move along trust lines. You cannot cause someone else's account to hold more of a token than the _limit_ configured on their trust line. (You _can_ cause your own trust line to go over the limit, for example by buying more of it in the decentralized exchange or by decreasing the limit after you already have a positive balance.)
|
||||
XRP, the native digital asset of the XRP Ledger, has different technical properties than all other tokens in the XRPL, so it is not typically called a "token" in the context of XRPL. Some notable differences:
|
||||
|
||||
Anyone can issue tokens by sending a [Payment transaction][] if the necessary trust lines are in place. You can "burn" tokens by sending them back to the issuer. In some cases, cross-currency payments or trades can also create more tokens according to an issuer's settings.
|
||||
|
||||
Issuers have options with tokens that are not available with XRP. Issuers can charge a [transfer fee](transfer-fees.md) that is automatically deducted when users transfer their tokens. Issuers can also define a [tick size](decentralized-exchange/ticksize.md) for exchanges rates involving their tokens. Both issuers and regular accounts can [freeze](fungible-tokens/freezes.md) trust lines, which limits how the tokens in those trust lines can be used.
|
||||
|
||||
Tokens use decimal (base-10) math with 15 digits of precision and an exponent that allows them to express very large values (up to 9999999999999999 × 10<sup>80</sup>) and very small values (down to 1.0 × 10<sup>-81</sup>).
|
||||
- All accounts _must_ hold at least a small amount of XRP in reserve, and must burn small amounts of XRP as "gas" to pay for sending transactions.
|
||||
- XRP is tracked together with accounts on the ledger, and can be sent directly from one account to another with no fees beyond the cost of sending the transaction.
|
||||
- All accounts can receive XRP from anyone by default, in contrast to tokens which you can only receive after you have sent a transaction indicating your willingness to hold them.
|
||||
- XRP has fixed precision to 6 decimal points, and is represented as integer _drops_ such that 1 million drops equals 1 XRP.
|
||||
- All XRP was created along with the ledger itself, and no new XRP can be minted.
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
|
||||
Reference in New Issue
Block a user