mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-20 11:45:50 +00:00
Reorg tokens & stablecoin use case
wip fix links fix 2 links trim and add topics Add checklist, rename sc subtopics Fix internal links Add DEX/AMM Add graphics reorg files reorg/rename Fix blurb Remove old JA files edits per review review changes rename output file name of index files to match the folder name Update output file and parent filenames add reusable links snippet fix broken links Update Ja file Move path.md to same location in i18n folder Revert naming for nft-collections page Rename to match files in En and Ja update links to reflect updated file name Rename nft-auctions under Ja folder and update links throughout Rename nftoken-authorized-minting and update links throughout Fix links Rename the nft-fixed-supply Ja file to match the reorg in English and update links Move nft-reserve-requirements file in Ja and update links Fix some more broken links Fix more broken links by renaming html files back Stablecoin reorg: fix various issues Remove nfts_by_issuer method (unreleased) page Remove redundant parent: attrs from config file Fix syntax highlighting of Authorizing Another Minter js Fix config/frontmatter errors
This commit is contained in:
ddawson
@@ -2,7 +2,7 @@
|
||||
html: decentralized-exchange.html
|
||||
parent: tokens.html
|
||||
template: pagetype-category.html.jinja
|
||||
blurb: The XRP Ledger contains a fully-functional exchange where users can trade tokens for XRP or each other.
|
||||
blurb: The XRP Ledger contains a fully functional exchange where users can trade tokens for XRP or each other.
|
||||
targets:
|
||||
- en
|
||||
---
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
html: authorized-trust-lines.html
|
||||
parent: tokens.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
blurb: Authorized trust lines is a setting to limit who can hold a token.
|
||||
labels:
|
||||
- Tokens
|
||||
@@ -129,6 +129,6 @@ In the response's `result.lines` array, find the object whose `currency` field i
|
||||
- [RippleState (trust line) Flags](ripplestate.html#ripplestate-flags)
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
html: clawing-back-tokens.html
|
||||
parent: tokens.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
blurb: Issuers can claw back their tokens for compliance purposes if they enable the Clawback feature before issuing tokens.
|
||||
labels:
|
||||
- Tokens
|
||||
@@ -17,7 +17,7 @@ Issuers can gain the ability to claw back their tokens by enabling the **Allow C
|
||||
|
||||
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.
|
||||
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`.
|
||||
|
||||
## Example Clawback Transaction
|
||||
@@ -37,6 +37,6 @@ Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is
|
||||
If successful, this transaction would claw back at most 314.159 FOO issued by rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S and held by rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW.
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
html: demurrage.html
|
||||
parent: tokens.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
blurb: (Obsolete) Some older XRP Ledger tools used to support currency codes with built-in interest and negative interest rates.
|
||||
status: removed
|
||||
---
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
html: freezes.html
|
||||
parent: tokens.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
blurb: Issuers can freeze their issued tokens for compliance purposes.
|
||||
labels:
|
||||
- Tokens
|
||||
@@ -98,6 +98,6 @@ You can only enable the No Freeze setting with a transaction signed by your addr
|
||||
- [RippleState (trust line) Flags](ripplestate.html#ripplestate-flags)
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -5,20 +5,27 @@ blurb: Learn about the properties and rationale of trust lines.
|
||||
labels:
|
||||
- Tokens
|
||||
---
|
||||
# Trust Lines and Issuing
|
||||
# Fungible Tokens
|
||||
|
||||
Trust lines are structures in the XRP Ledger for holding [tokens](tokens.html). 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](tokens.html#community-credit) among other benefits.
|
||||
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.
|
||||
|
||||
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 Lines
|
||||
|
||||
Trust lines are structures in the XRP Ledger for holding fungible [tokens](tokens.html). 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](tokens.html#community-credit) among other benefits.
|
||||
|
||||
Each "trust line" is a _bidirectional_ relationship consisting of:
|
||||
|
||||
- The identifiers for the **two [accounts](accounts.html)** 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 identifiers for the two [accounts](accounts.html) 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](http-websocket-apis.html), 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).
|
||||
- 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.html) on trust lines to prevent those trust lines from rippling.
|
||||
|
||||
## Creation
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
html: paths.html
|
||||
parent: tokens.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
blurb: Payments of tokens must traverse paths of connected users and order books.
|
||||
labels:
|
||||
- Payments
|
||||
@@ -116,6 +116,6 @@ The `type` field, used for the binary serialization of a path set, is actually c
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
html: rippling.html
|
||||
parent: tokens.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
blurb: Rippling is automatic multi-party net settlement of token balances.
|
||||
labels:
|
||||
- Tokens
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
html: stablecoin-compliance-guidelines.html
|
||||
parent: stablecoins.html
|
||||
blurb: Stablecoin issuers are responsible for complying with local regulations and reporting to appropriate agencies.
|
||||
labels:
|
||||
- Tokens
|
||||
---
|
||||
# Stablecoin Compliance Guidelines
|
||||
|
||||
Stablecoin issuers are responsible for complying with local regulations and reporting to the appropriate agencies. Regulations vary by country and state, but may include the reporting and compliance requirements described in the following sections. Before issuing a token, you should seek professional legal advice on the requirements for your jurisdiction and use case. The following resources may be useful background reading.
|
||||
|
||||
### Know Your Customer (KYC)
|
||||
|
||||
Know Your Customer (KYC) refers to due diligence activities conducted by a financial institution to determine and verify the identity of its customers to prevent use of the institution for criminal activity. Criminal activity in financial terms may include money laundering, terrorist financing, financial fraud, and identity theft. Customers may be individuals, intermediaries, or businesses.
|
||||
|
||||
The KYC process generally aims to:
|
||||
|
||||
- Identify the customer (and, in the case of organizations and businesses, any beneficial owners)
|
||||
|
||||
- Understand the purpose and intended nature of the business relationship
|
||||
|
||||
- Understand the expected transaction activity.
|
||||
|
||||
KYC is critical for financial institutions and related businesses to mitigate risk, especially legal and reputational risk. Having an inadequate or nonexistent KYC program may result in civil and criminal penalties for the institution or individual employees.
|
||||
|
||||
See also:
|
||||
|
||||
- [(USA) Bank Secrecy Act / Anti-Money Laundering Examination Manual](https://bsaaml.ffiec.gov/manual/Introduction/01)
|
||||
|
||||
- [The Non-US Standard on KYC set by the Financial Action Task Force (FATF)](http://www.fatf-gafi.org/publications/fatfrecommendations/documents/fatf-recommendations.html)
|
||||
|
||||
<!-- SPELLING_IGNORE: ffiec -->
|
||||
|
||||
### Anti-Money Laundering (AML) and Combating the Financing of Terrorism (CFT)
|
||||
|
||||
Money laundering is the process of moving illegal funds by disguising the source, nature or ownership so that funds can be legally accessed or distributed via legitimate financial channels and credible institutions. In short, it is converting “dirty money” into “clean money.” Anti-Money Laundering (AML) refers to the laws and procedures designed to stop money laundering from occurring.
|
||||
|
||||
Terrorist financing is the solicitation, collection, or provision of funds to organizations engaged in terrorist activity or organizations that support terrorism and its proliferation. Combating the Financing of Terrorism (CFT) refers to the process of identifying, reporting, and blocking flows of funds used to finance terrorism.
|
||||
|
||||
See also:
|
||||
|
||||
- [“International Standards on Combating Money Laundering and the Financing of Terrorism & Proliferation.” FATF, 2012](http://www.fatf-gafi.org/publications/fatfrecommendations/documents/fatf-recommendations.html)
|
||||
|
||||
- [“Virtual Currencies: Key Definitions and Potential AML/CFT Risks.” FATF, 2014](http://www.fatf-gafi.org/publications/methodsandtrends/documents/virtual-currency-definitions-aml-cft-risk.html)
|
||||
|
||||
<!-- SPELLING_IGNORE: fatf, cft -->
|
||||
|
||||
### Source of Funds
|
||||
|
||||
To prevent illicit funds from passing through their systems, financial institutions must be able to determine within reason if the source of a customer’s funds is linked to criminal activity.
|
||||
|
||||
Determining the exact source of funds for every customer may not be administratively feasible. As a result, some regulatory authorities may not provide specific regulation or guidance for all accounts. In specific cases, however, authorities may require financial institutions to identify and report the source of funds. Guidance by the FATF recommends that where the risks of money laundering or terrorist financing are higher (commonly referred to as a “risk-based approach”), financial institutions conduct enhanced due diligence, including but not limited to determining the customer’s source of funds.
|
||||
|
||||
<!-- STYLE_OVERRIDE: feasible -->
|
||||
|
||||
### Suspicious Activity Reporting
|
||||
|
||||
If a financial institution suspects that funds may be related to criminal activity, the institution must file a Suspicious Activity Report (SAR) with the appropriate regulatory authority. Failure to report suspicious activity may result in in penalties for the institution.
|
||||
|
||||
See also:
|
||||
|
||||
- [Suspicious Activity Reporting Overview (USA FFIEC)](https://bsaaml.ffiec.gov/manual/RegulatoryRequirements/04_ep)
|
||||
|
||||
- [FATF Recommendation 16: Reporting of suspicious transactions and compliance](http://www.fatf-gafi.org/publications/fatfrecommendations/documents/fatf-recommendations.html)
|
||||
|
||||
### Travel Rule
|
||||
|
||||
The Travel Rule is a Bank Secrecy Act (BSA) rule requiring funds-transmitting financial institutions to forward certain information to the next financial institution if the funds transmittal equals or exceeds the USD equivalent of $3,000. The following information must be included in the transmittal order:
|
||||
|
||||
- The name of the transmittor,
|
||||
- The account number of the transmittor, if used,
|
||||
- The address of the transmittor,
|
||||
- The identity of the transmittor's financial institution,
|
||||
- The amount of the transmittal order,
|
||||
- The execution date of the transmittal order, and
|
||||
- The identity of the recipient's financial institution.
|
||||
|
||||
<!-- SPELLING_IGNORE: transmittor -->
|
||||
|
||||
See also:
|
||||
|
||||
- [Funds “Travel” Regulations: Questions & Answers ](https://www.fincen.gov/resources/statutes-regulations/guidance/funds-travel-regulations-questions-answers)
|
||||
|
||||
### Fee Disclosure and Tracing Funds
|
||||
|
||||
- In the United States, Dodd Frank 1073 Electronic Fund Transfer Act (Regulation E) requires banks to provide information on cost and delivery terms for international payments originating in the US including exchange rate, fees, and the amount to be received by the designated recipient in the foreign country. "Pre-payment disclosure" is provided to a consumer when requesting an international electronic payment and “receipt disclosure” is provided to a consumer at the time consumer authorizes the transfer.
|
||||
|
||||
See also:
|
||||
|
||||
- [The Consumer Financial Protection Bureau description of the regulation and extensions for banks](https://www.consumerfinance.gov/rules-policy/final-rules/electronic-fund-transfers-regulation-e/#rule)
|
||||
|
||||
- In the European Union, EU Funds Transfer Regulation requires that the originator’s bank, the beneficiary’s bank, and any intermediary banks include certain details of the payer and payee in transaction details to detect, investigate, and prevent money laundering and terrorist financing.
|
||||
|
||||
See also:
|
||||
|
||||
- [EU Regulation (EC) No 1781/2006 description](http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2006:345:0001:0009:EN:PDF)
|
||||
|
||||
- [Effective June 26, 2017: Regulation 2015/847 on information accompanying transfers of funds](http://eur-lex.europa.eu/legal-content/EN/ALL/?uri=CELEX%3A32015R0847)
|
||||
|
||||
### Office of Foreign Assets Control (OFAC)
|
||||
|
||||
The Office of Foreign Assets Control (OFAC) is an agency of the US Department of Treasury that administers and enforces economic and trade sanctions in support of U.S. foreign policy and national security objectives. All U.S. persons and U.S. incorporated entities and their foreign branches must follow OFAC regulations. Under OFAC regulations, U.S. financial institutions are prohibited—unless authorized by OFAC or expressly exempted by statute—from conducting transactions and other dealings with individuals, entities, or countries under sanctions or embargo programs administered and enforced by OFAC.
|
||||
|
||||
See also:
|
||||
|
||||
- [A list of OFAC resources](https://www.treasury.gov/resource-center/faqs/Sanctions/Pages/ques_index.aspx)
|
||||
|
||||
<!-- SPELLING_IGNORE: ofac -->
|
||||
|
||||
### Guidance on Virtual Currency and Money Service Business
|
||||
|
||||
- United States:
|
||||
|
||||
- [FinCEN Guidance and Definitions around Virtual Currency, March 18, 2013](https://www.fincen.gov/resources/statutes-regulations/guidance/application-fincens-regulations-persons-administering)
|
||||
|
||||
- [FinCEN Publishes Two Rulings on Virtual Currency Miners and Investors, January 30, 2014](https://www.fincen.gov/news/news-releases/fincen-publishes-two-rulings-virtual-currency-miners-and-investors)
|
||||
|
||||
- Europe:
|
||||
|
||||
- [European Banking Authority Opinion on Virtual Currencies, July 4, 2014](http://www.eba.europa.eu/documents/10180/657547/EBA-Op-2014-08+Opinion+on+Virtual+Currencies.pdf)
|
||||
|
||||
- FATF Guidance for Money Service Businesses:
|
||||
|
||||
- [Financial Action Task Force, July 2009](http://www.fatf-gafi.org/media/fatf/documents/reports/Guidance-RBA-money-value-transfer-services.pdf)
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
html: stablecoin-configuration.html
|
||||
parent: stablecoins.html
|
||||
blurb: Configure your stablecoin to fine tune its capabilities.
|
||||
labels:
|
||||
- Tokens
|
||||
---
|
||||
# Stablecoin Configuration
|
||||
|
||||
There are some settings you must configure on your XRP Ledger account before you start issuing tokens. For examples of how to configure these settings, see [Issue a Fungible Token](issue-a-fungible-token.html).
|
||||
|
||||
Settings you might want to configure include:
|
||||
|
||||
| Setting | Notes |
|
||||
|---------|-------|
|
||||
| Default Ripple | Issuers must enable this field. |
|
||||
| Deposit Authorization | Block all incoming payments from users you haven't explicitly approved. |
|
||||
| Require Auth | Restrict your tokens to being held by users you've explicitly approved. |
|
||||
| Tick Size | Round off exchange rates in the decentralized exchange to facilitate faster price discovery. |
|
||||
| Transfer Fee | Charge a percentage fee when users send your token to each other. |
|
||||
|
||||
|
||||
## Default Ripple
|
||||
|
||||
The Default Ripple flag controls whether the balances on a trust line are allowed to _ripple_ by default. Rippling is what allows customers to send and trade tokens among themselves, so an issuer MUST allow rippling on all the trust lines to its issuing address. See [Rippling](rippling.html).
|
||||
|
||||
Before asking customers to create trust lines to its issuing address, an issuer should enable the Default Ripple flag on that address. Otherwise, the issuer must individually disable the No Ripple flag for each trust line that other addresses have created.
|
||||
|
||||
|
||||
## Deposit Authorization
|
||||
|
||||
The Deposit Authorization setting blocks all incoming payments to your account, unless either:
|
||||
|
||||
- You have previously preauthorized the sender.
|
||||
- You send a transaction to receive the funds. For example, you could finish an Escrow that was initiated by a stranger.
|
||||
|
||||
Deposit Authorization is most useful for blocking unwanted XRP payments, because you already can't receive tokens unless you've created a trust line to their issuer. However, as a stablecoin issuer, you need to be able to receive payments from users in order for them to redeem the stablecoin for its off-ledger value; you can preauthorize your customers but doing so requires storing an object in the ledger for each custom address, increasing your reserve requirement substantially.
|
||||
|
||||
Therefore, Deposit Authorization is not recommended for stablecoin issuers unless you need it to meet regulatory requirements about receiving money from unknown or sanctioned entities.
|
||||
|
||||
For more information, see [Deposit Authorization](depositauth.html).
|
||||
|
||||
|
||||
## Disallow XRP
|
||||
|
||||
The Disallow XRP setting is designed to discourage XRP Ledger users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments from addresses that aren't intended to receive and hold XRP. The Disallow XRP flag is not enforced at the protocol level, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the Disallow XRP flag by default, but may allow users to ignore it.
|
||||
|
||||
The Disallow XRP flag is optional, but if you don't intend to receive XRP from customers you may want to enable it on your issuing address and all your operational addresses.
|
||||
|
||||
|
||||
## Require Auth
|
||||
|
||||
The Require Auth setting blocks users from holding the tokens you issue unless you explicitly approve their trust lines first. You can use this setting to meet regulatory requirements if it matters who holds your tokens within the XRP Ledger. However, this can reduce the utility of your tokens since your approval becomes a bottleneck for users to use them.
|
||||
|
||||
Also, you must use your issuing address each time you authorize a trust line; if you must authorize a lot of trust lines, this can undermine the security of your issuing address because you have to use it so often. (If you only need to use the issuing address sparingly, you can put greater protections on its secret keys. The more often you use it, the more of a burden those protections become.)
|
||||
|
||||
For more information, see [Authorized Trust Lines](authorized-trust-lines.html).
|
||||
|
||||
|
||||
## Tick Size
|
||||
|
||||
The Tick Size setting controls how many decimal places are used when calculating exchange rates in the [Decentralized Exchange](decentralized-exchange.html). A higher Tick Size means more precision and less rounding in the amounts of various trades. Too much precision can be inconvenient because trades are ranked primarily based on exchange rate, so a trader can offer a minuscule amount more to the top of the list. A smaller Tick Size works similar to the minimum bid increment at an auction, saving everyone the time and effort of gradually bidding up a price by irrelevantly small amounts. However, a smaller Tick Size results in more rounding, which can increase the costs of trading, and sometimes has surprising results because two Offers that seemed like an exact match before rounding no longer match after rounding.
|
||||
|
||||
The Tick Size is an account-level setting and applies to all tokens issued by the same address.
|
||||
|
||||
Tick Size only controls the precision of _exchange rates_, not the precision of the token itself. Users can send and hold very large or very small amounts regardless of the Tick Size set by the token's issuer.
|
||||
|
||||
For more information, see [Tick Size](ticksize.html).
|
||||
|
||||
|
||||
## Transfer Fees
|
||||
|
||||
A transfer fee setting charges users a percentage fee when sending your tokens to each other. The transfer fee does not apply when issuing tokens or redeeming them directly with the issuing address. (It _does_ apply when users send payments to your hot wallet.) If you issue multiple tokens from the same address, the same transfer fee applies to all of them.
|
||||
|
||||
When users send a token with a transfer fee, the amount of the transfer fee is debited from the sending side in addition to the destination amount, but only the destination amount is credited to the recipient. The amount of the fee "vanishes" from the XRP Ledger. As a stablecoin issuer, this means that you gain that much equity in your reserves outside of the XRP Ledger—or, in other words, the amount you need to keep as collateral decreases each time users pay a transfer fee.
|
||||
|
||||
At a protocol level, the transfer fee is defined by the `TransferRate` account setting, which is an integer from 1 billion to 2 billion.
|
||||
|
||||
For more information, see [Transfer Fees](transfer-fees.html).
|
||||
|
||||
|
||||
### Transfer Fees with Operational and Standby Addresses
|
||||
|
||||
All XRP Ledger addresses, including operational and standby addresses, are subject to the issuer's transfer fees when sending tokens. If you set a nonzero transfer fee, then you must send extra (to pay the transfer fee) when making payments from your operational address or standby address. In other words, your addresses must pay back a little of the balance your issuing address created, each time you make a payment.
|
||||
|
||||
Set the `SendMax` transaction parameter higher than the destination `Amount` parameter by a percentage based on the `TransferRate` setting.
|
||||
|
||||
**Note:** Transfer fees do not apply when sending tokens directly from or to the issuing address. The issuing address must always accept its tokens at face value in the XRP Ledger. This means that customers don't have to pay the transfer fee if they send payments to the issuing address directly, but they do when sending to an operational address. If you accept payments at both addresses, you may want to adjust the amount you credit customers in your system of record when customers send payments to the operational address, to compensate for the transfer fee the customer pays.
|
||||
|
||||
For example: If ACME sets a transfer fee of 1%, an XRP Ledger payment to deliver 5 EUR.ACME from a customer address to ACME's issuing address would cost exactly 5 EUR.ACME. However, the customer would need to send 5.05 EUR.ACME to deliver 5 EUR.ACME to ACME's operational address. When ACME credits customers for payments to ACME's operational address, ACME credits the customer for the amount delivered to the operational address _and_ the transfer fee, giving the customer €5,05 in ACME's systems.
|
||||
|
||||
37
content/concepts/tokens/fungible-tokens/stablecoins/index.md
Normal file
37
content/concepts/tokens/fungible-tokens/stablecoins/index.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
html: stablecoins.html
|
||||
parent: trust-lines-and-issuing.html
|
||||
blurb: There are five common types of stablecoin traded on the XRP Ledger.
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Commodity Backed
|
||||
|
||||
Commodity-backed stablecoins are based on a fungible asset such as gold, real estate, oil, or electricity. Commodities are relatively stable and liquid, but are centralized and require regular audits to verify their value.
|
||||
|
||||
## Financial Instrument Backed
|
||||
|
||||
A stablecoin can be backed by financial instruments such as bonds or equity shares.
|
||||
|
||||
## Non-collateralized
|
||||
|
||||
A non-collateralized token relies on algorithm-generated smart contracts to supply or sell tokens, similar to a central bank's approach to printing and destroying currency. No collateral is required to mint tokens. Value is controlled by supply and demand through algorithms that stabilize the price. Non-collateralized tokens are typically not considered stablecoins, due to their volatility.
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
html: stablecoin-precautions.html
|
||||
parent: stablecoins.html
|
||||
blurb: Precautions to consider when transferring stablecoin funds in and out of the XRPL.
|
||||
labels:
|
||||
- Tokens
|
||||
---
|
||||
# Stablecoin Precautions
|
||||
|
||||
Processing payments to and from the XRP Ledger naturally comes with some risks, so an issuer should be sure to take care in implementing these processes. As a stablecoin issuer, you should consider the following precautions:
|
||||
|
||||
- Protect yourself against reversible deposits. XRP Ledger payments are irreversible, but many digital payments are not. Scammers can abuse this to take their fiat money back by canceling a deposit after receiving tokens in the XRP Ledger.
|
||||
- When sending into the XRP Ledger, always specify your issuing address as the issuer of the token. Otherwise, you might accidentally use paths that deliver the same currency issued by other addresses.
|
||||
- Before sending a payment into the XRP Ledger, double check the cost of the payment. A payment from your operational address to a customer should not cost more than the destination amount plus any transfer fee you have set.
|
||||
- Before processing a payment out of the XRP Ledger, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the XRP Ledger could be different than the ones that initially received the money in the XRP Ledger.
|
||||
- Follow the guidelines for reliable transaction submission when sending XRP Ledger transactions.
|
||||
- Robustly monitor for incoming payments, and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a [partial payment](partial-payments.html). See [Robustly monitoring for payments](robustly-monitoring-for-payments.html).
|
||||
- Track your obligations and balances within the XRP Ledger, and compare with the assets in your collateral account. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy.
|
||||
- Avoid ambiguous situations. We recommend the following:
|
||||
- Enable the `Disallow XRP` flag for the issuing address and all operational addresses, so customers do not accidentally send you XRP. (Private exchanges should *not* set this flag, since they trade XRP normally.)
|
||||
- Enable the [`RequireDest` flag](require-destination-tags.html) for the issuing address and all operational addresses, so customers do not accidentally send a payment without the destination tag to indicate who should be credited.
|
||||
- Enable the `RequireAuth` flag on all operational addresses so they cannot issue tokens by accident.
|
||||
- Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the XRP Ledger, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their XRP Ledger payments.
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
html: stablecoin-settings.html
|
||||
parent: stablecoins.html
|
||||
blurb: Settings to configure before issuing your stablecoin.
|
||||
labels:
|
||||
- XRP
|
||||
- Stablecoin
|
||||
---
|
||||
# Stablecoin Settings
|
||||
|
||||
Before you mint your new stablecoin, you need to configure settings, some of which are immutable once you issue the first coin.
|
||||
|
||||
## Create Your Issuing and Distribution Accounts
|
||||
|
||||
Create a new account that you designate as the _issuer_, sometimes called the "cold" wallet. There is nothing different or special about the account itself, only the way you use it. Use the account to mint your stablecoins.
|
||||
|
||||
Many implementations use a _standby_ account as a "warm" wallet. Trusted human operators use the standby account to distribute stablecoins to _operational_ accounts.
|
||||
|
||||
<div align="center">
|
||||
<img src="img/uc-stablecoin-distribution-flow.png" height="50%" width="50%"></image>
|
||||
</div>
|
||||
|
||||
Operational accounts, or "hot" wallets, trade with other accounts on the XRPL. Automated, internet-connected systems use the secret keys to these addresses to conduct day-to-day business like transfers to customers and partners.
|
||||
|
||||
Using standby and operational accounts helps to insulate the issuing account against hacking attacks, and also makes it easier to monitor the creation and destruction of your stablecoins.
|
||||
|
||||
|
||||
## Set Your Transfer Fee
|
||||
|
||||
A transfer fee setting charges users a percentage fee when transferring tokens between accounts.
|
||||
|
||||
When users send a token with a transfer fee, the amount of the transfer fee is debited from the sending side in addition to the destination amount, but only the destination amount is credited to the recipient. The amount of the fee "vanishes" from the XRP Ledger. As a stablecoin issuer, this means that you gain that much equity in your reserves outside of the XRP Ledger—or, in other words, the amount you need to keep as collateral decreases each time users pay a transfer fee.
|
||||
|
||||
For more information, see [Transfer Fees](transfer-fees.html).
|
||||
|
||||
|
||||
## Set Your Tick Size
|
||||
|
||||
The Tick Size setting controls how many decimal places are used when calculating exchange rates in the [Decentralized Exchange](decentralized-exchange.html). A higher Tick Size (more decimal places) means more precision and less rounding in the amounts of various trades. A smaller Tick Size works similar to the minimum bid increment at an auction, saving everyone the time and effort of gradually bidding up a price by unreasonably small amounts.
|
||||
|
||||
The Tick Size is an account-level setting and applies to all tokens issued by the same address.
|
||||
|
||||
See [Tick Size](ticksize.html).
|
||||
|
||||
|
||||
## Set the Default Ripple Flag
|
||||
|
||||
The Default Ripple flag controls whether the balances on a trust line are allowed to _ripple_ by default. Rippling is what allows customers to send and trade tokens among themselves. An issuer MUST allow rippling on all the trust lines to its issuing address.
|
||||
|
||||
Before asking customers to create trust lines to your issuing address, enable the Default Ripple flag on that address. Otherwise, you must individually disable the No Ripple flag for each trust line that other addresses have created.
|
||||
|
||||
See [Rippling](rippling.html).
|
||||
|
||||
|
||||
## Enable Destination Tags
|
||||
|
||||
If your stablecoin application handles transactions on behalf of several customers, it might not be immediately obvious to which account you should credit. Destination tags help to avoid this situation by requiring the sender to specify the beneficiary or destination for a payment. To enable the `RequireDest` flag, set the `asfRequireDest` value (1) in the `SetFlag` field of an `AccountSet` transaction. See [Source and Destination Tags](source-and-destination-tags.html).
|
||||
|
||||
## Asset Control Features
|
||||
|
||||
You have several options for controlling the creation and distribution of your stablecoins.
|
||||
|
||||
|
||||
### Authorized Trust Lines
|
||||
|
||||
When you need to follow compliance rules such as Know Your Customer (KYC) and Anti-Money Laundering (AML), you can use trust lines to create permissioned pools for the distribution of your stablecoin. This allows you to be certain to whom the funds are transferred.
|
||||
|
||||
See [Authorized Trust Lines](authorized-trust-lines.html).
|
||||
|
||||
|
||||
### Freeze Flags
|
||||
|
||||
You have the ability to freeze your stablecoins in your holder accounts. You might do this when you suspect fraudulent activity, or to enforce holds. You can freeze individual trust lines, or enact a global freeze of all activity.
|
||||
|
||||
Conversely, you can set the No Freeze feature, which permanently gives up the ability to freeze tokens. This makes your stablecoin more like fiat currency, in the sense that you cannot interfere with counterparties trading the tokens among themselves.
|
||||
|
||||
See [Freezing Tokens](freezes.html).
|
||||
|
||||
|
||||
### Clawback Flags
|
||||
|
||||
_(Requires the [Clawback amendment](known-amendments.html#clawback) :not_enabled:)_
|
||||
|
||||
Clawback allows you to retrieve, or _clawback_, stablecoins from a trust line under specific circumstances. This gives you added ability to respond to challenges such as lost account access or malicious activity.
|
||||
|
||||
See [Clawback](clawback.html).
|
||||
|
||||
|
||||
### Fixed Supply
|
||||
|
||||
Restricting your stablecoins to a fixed number guarantees that stablecoin value will not be diluted in the future if you decide to issue more tokens.
|
||||
|
||||
To create a fixed supply:
|
||||
|
||||
1. Create a distribution wallet with settings similar to your issuing wallet.
|
||||
2. Set up a trust line between the issuing wallet and the distribution wallet.
|
||||
3. Send all tokens from the issuing wallet to the distribution wallet.
|
||||
4. Black hole the issuing account.
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
html: stablecoin-technical-details.html
|
||||
parent: stablecoins.html
|
||||
blurb: Issue your own stablecoin, based on assets of equal value outside of the XRP Ledger.
|
||||
labels:
|
||||
- Tokens
|
||||
---
|
||||
|
||||
# Stablecoin Technical Details
|
||||
|
||||
## Infrastructure
|
||||
|
||||
For your own security as well as the stability of the network, each XRP Ledger business should [run its own XRP Ledger servers](install-rippled.html), including one [validator](rippled-server-modes.html#validators).
|
||||
|
||||
|
||||
### APIs and Middleware
|
||||
|
||||
There are several interfaces you can use to connect to the XRP Ledger, depending on your needs and your existing software:
|
||||
|
||||
- [HTTP / WebSocket APIs](http-websocket-apis.html) can be used as a low-level interface to all core XRP Ledger functionality.
|
||||
- [Client Libraries](client-libraries.html) are available in several programming languages to provide convenient utilities for accessing the XRP Ledger.
|
||||
- Other tools such as [xApps](https://xumm.readme.io/docs/xapps) are also available.
|
||||
- Third party wallet applications might also be useful, especially for humans in charge of standby addresses.
|
||||
|
||||
|
||||
## Tool Security
|
||||
|
||||
Any time you submit an XRP Ledger transaction, it must be signed using your secret key. The secret key gives full control over your XRP Ledger address. Never send your secret key to a server run by someone else. Either use your own server, or sign the transactions locally using a client library.
|
||||
|
||||
For instructions and examples of secure configurations, see [Set Up Secure Signing](secure-signing.html).
|
||||
|
||||
|
||||
## Robustly Monitoring for Payments
|
||||
|
||||
To robustly check for incoming payments, issuers should do the following:
|
||||
|
||||
* Keep a record of the most-recently-processed transaction and ledger. That way, if you temporarily lose connectivity, you know how far to go back.
|
||||
* Check the result code of every incoming payment. Some payments go into the ledger to charge an anti-spam fee, even though they failed. Only transactions with the result code `tesSUCCESS` can change non-XRP balances. Only transactions from a validated ledger are final.
|
||||
* Look out for [Partial Payments](partial-payments.html). Payments with the partial payment flag enabled can be considered "successful" if any non-zero amount is delivered, even minuscule amounts.
|
||||
* Check the transaction for a [`delivered_amount` field](partial-payments.html#the-delivered_amount-field). If present, that field indicates how much money *actually* got delivered to the `Destination` address.
|
||||
* In xrpl.js, you can use the [`xrpl.getBalanceChanges()` method](https://js.xrpl.org/modules.html#getBalanceChanges) to see how much each address received. In some cases, this can be divided into multiple parts on different trust lines.
|
||||
* Some transactions change your balances without being payments directly to or from one of your addresses. For example, if ACME sets a nonzero transfer fee, then ACME's issuing address's outstanding obligations decrease each time Bob and Charlie exchange ACME's tokens.
|
||||
|
||||
To make things simpler for your customers, we recommend accepting payments to both your operational address and your issuing addresses.
|
||||
|
||||
As an added precaution, we recommend comparing the balances of your issuing address with the collateral funds in your internal accounting system as of each new ledger version. The issuing address's negative balances should match the assets you have allocated to XRP Ledger outside the network. If the two do not match up, then you should suspend processing payments into and out of the XRP Ledger until you have resolved the discrepancy.
|
||||
|
||||
* Use the `gateway_balances` method to check your balances.
|
||||
* If you have a Transfer Fee set, then your obligations within the XRP Ledger decrease slightly whenever other XRP Ledger addresses transfer your tokens among themselves.
|
||||
|
||||
For more details on how to read the details of incoming transactions, see [Look Up Transaction Results](look-up-transaction-results.html).
|
||||
|
||||
|
||||
## Sending Payments to Customers
|
||||
|
||||
When you build an automated system to send payments into the XRP Ledger for your customers, you must make sure that it constructs payments carefully. Malicious actors are constantly trying to find ways to trick a system into paying them more money than it should.
|
||||
|
||||
Generally, when sending stablecoins, you use a Payment transaction. Some of the details are different depending on whether you are issuing tokens for the first time or transferring them from a hot wallet to a customer. Things to note include:
|
||||
|
||||
- When issuing new tokens from your issuing address, you should omit the `SendMax` field. Otherwise, malicious users can arrange their settings so that you issue the full `SendMax` amount instead of just the intended destination `Amount`.
|
||||
- When sending tokens from a hot wallet, you must specify `SendMax` if you have a nonzero transfer fee. In this case, set the `SendMax` field to the amount specified in the `Amount` field plus the transfer fee. (You may want to round up slightly, in case the precision of your calculations doesn't exactly match the XRP Ledger's. For example, if you send a transaction whose `Amount` field specifies 99.47 USD, and your transfer fee is 0.25%, you should set the `SendMax` field to 124.3375, or 124.34 USD, if you round up.)
|
||||
- Omit the `Paths` field. This field is unnecessary when sending directly from the issuer, or from a hot wallet as long as the tokens being sent and the tokens being received have the same currency code and issuer—that is, they're the same stablecoin. The `Paths` field is intended for cross-currency payments and longer multi-hop (rippling) payments. If you perform pathfinding and attach the paths to your transaction, your payment might take a more expensive indirect route rather than failing if the direct path is not available; malicious users can even set this up to fail.
|
||||
- If you get a `tecPATH_DRY` result code, this usually indicates that either the customer doesn't have the necessary trust line set up already, or your issuer's rippling settings aren't configured correctly.
|
||||
|
||||
For a detailed tutorial on issuing a token on the XRP Ledger, whether a stablecoin or otherwise, see [Issue a Fungible Token](issue-a-fungible-token.html).
|
||||
|
||||
|
||||
## Bouncing Payments
|
||||
|
||||
When one of your addresses receives a payment where the purpose is unclear, we recommend that you try to return the money to its sender. While this is more work than pocketing the money, it demonstrates good faith towards customers. You can have an operator bounce payments manually, or create a system to do so automatically.
|
||||
|
||||
The first requirement to bouncing payments is [robustly monitoring for incoming payments](#robustly-monitoring-for-payments). You do not want to accidentally refund a customer for more than they sent you! (This is particularly important if your bounce process is automated.) Malicious users can take advantage of a naive integration by sending [partial payments](partial-payments.html#partial-payments-exploit).
|
||||
|
||||
Second, you should send bounced payments as Partial Payments. Since third parties can manipulate the cost of pathways between addresses, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the XRP Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from either an operational address or a standby address.
|
||||
|
||||
To send a Partial Payment, enable the [`tfPartialPayment` flag](payment.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field. You should use the `SourceTag` value from the incoming payment as the `DestinationTag` value for the return payment.
|
||||
|
||||
To prevent two systems from bouncing payments back and forth indefinitely, you can set a new Source Tag for the outgoing return payment. If you receive an unexpected payment whose Destination Tag matches the Source Tag of a return you sent, then do not bounce it back again.
|
||||
|
||||
|
||||
## Reliable Transaction Submission
|
||||
|
||||
The goal of reliably submitting transactions is to achieve the following two properties in a finite amount of time:
|
||||
|
||||
* Idempotency - Transactions should be processed once and only once, or not at all.
|
||||
* Verifiability - Applications can determine the final result of a transaction.
|
||||
|
||||
To submit transactions reliably, follow these guidelines:
|
||||
|
||||
* Persist details of the transaction before submitting it.
|
||||
* Use the `LastLedgerSequence` parameter. (Many [client libraries](client-libraries.html) do this by default.)
|
||||
* Resubmit a transaction if it has not appeared in a validated ledger whose [ledger index][] is less than or equal to the transaction's `LastLedgerSequence` parameter.
|
||||
|
||||
For more information, see [Reliable Transaction Submission](reliable-transaction-submission.html).
|
||||
|
||||
|
||||
## xrp-ledger.toml File
|
||||
|
||||
You can publish information about what currencies you issue, and which XRP Ledger addresses you control, to protect against impostors or confusion, using an [`xrp-ledger.toml` file](xrp-ledger-toml.html). This machine-readable format is convenient for client applications to process. If you run an XRP Ledger validator, you can also publish the key in the same file.
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
53
content/concepts/tokens/index.md
Normal file
53
content/concepts/tokens/index.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
html: tokens.html
|
||||
parent: concepts.html
|
||||
blurb: Anyone can make tokens representing digital value on the XRP Ledger.
|
||||
labels:
|
||||
- Tokens
|
||||
---
|
||||
# Tokens
|
||||
|
||||
All assets other than XRP can be represented in the XRP Ledger as _tokens_.
|
||||
|
||||
Standard tokens are fungible: meaning, all units of that token are interchangeable and indistinguishable. Tokens can be used for [cross-currency payments](cross-currency-payments.html) and can be traded in the [decentralized exchange](decentralized-exchange.html).
|
||||
|
||||
**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 -->
|
||||
|
||||
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](trust-lines-and-issuing.html) and [Non-fungible Tokens](non-fungible-tokens.html).
|
||||
|
||||
## Stablecoins
|
||||
|
||||
Stablecoins are a common model for tokens in the XRP Ledger. The issuer holds assets of value outside of the XRP Ledger, and issues tokens representing the equivalent value on the ledger.
|
||||
|
||||
See [Stablecoins](stablecoins.html).
|
||||
|
||||
## Community Credit
|
||||
|
||||
Another way you can use the XRP Ledger is for "community credit", a system where individuals who know each other can use the XRP Ledger to track who owes whom how much money. One feature of the XRP Ledger is that it can automatically and atomically use these debts to settle payments through [rippling](rippling.html).
|
||||
|
||||
For more on this type of usage, see [paths](paths.html). <!--{# TODO: It would be nice to be able to link to a page with more illustrative examples of community credit. #}-->
|
||||
|
||||
## 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.
|
||||
|
||||
**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 -->
|
||||
|
||||
Be sure to research the relevant regulations before engaging in any financial service business.
|
||||
|
||||
## Token Properties
|
||||
|
||||
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.)
|
||||
|
||||
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.html) that is automatically deducted when users transfer their tokens. Issuers can also define a [tick size](ticksize.html) for exchanges rates involving their tokens. Both issuers and regular accounts can [freeze](freezes.html) 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>).
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
html: nftoken-batch-minting.html
|
||||
parent: non-fungible-tokens.html
|
||||
blurb: Minting NFToken objects in batches.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# Batch minting
|
||||
|
||||
There are two common approaches to minting NFToken objects in batches: mint on demand and scripted minting.
|
||||
|
||||
## Mint On Demand (Lazy Minting)
|
||||
|
||||
When using a mint on demand model, you and potential customers make buy or sell offers for initial sales of a NFToken object off the XRP Ledger. When you are ready to start the initial sale, you mint the token, create a sell offer or accept a buy offer, then complete the transaction.
|
||||
|
||||
### Benefits
|
||||
|
||||
* There is no reserve requirement for holding unsold NFToken objects.
|
||||
* You mint NFToken objects in real time when you know that it will sell. <!-- STYLE_OVERRIDE: will -->
|
||||
|
||||
### Downside
|
||||
|
||||
Any market activity before the initial sale of the NFToken object is not recorded on the XRP Ledger. This might not be an issue for some applications.
|
||||
|
||||
## Scripted Minting
|
||||
|
||||
Use a program or script to mint many tokens at once. You might find that [Tickets](tickets.html) help you submit transactions in parallel, up to a current limit of 200 transactions in one group.
|
||||
|
||||
For a practical example, see the [Batch Mint NFTs Using JavaScript](batch-mint-nfts-using-javascript.html) tutorial.
|
||||
|
||||
### Benefits
|
||||
|
||||
* NFToken objects are minted ahead of time
|
||||
* Market activity for the initial sale of the NFToken object is captured on the ledger
|
||||
|
||||
### Downside
|
||||
|
||||
You need to meet the [reserve requirement](reserves.html) for all of the `NFToken` objects you mint. As a rule of thumb, this is roughly 1/12th XRP per NFToken object at the current reserve rate. In the event that you do not have enough XRP in reserve, your mint transactions fail until you get more XRP.
|
||||
@@ -5,7 +5,7 @@ blurb: You can assign another account to mint NFTs in your stead.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
# Authorizing Another Account to Mint Your NFTs
|
||||
# Authorizing Another Minter
|
||||
|
||||
Each account can have 0 or 1 authorized minter that can mint NFTs on its behalf. By authorizing a minter, a creator can allow a different account to mint NFTs for them, which allows them to focus on making more NFTs.
|
||||
|
||||
@@ -13,9 +13,9 @@ Each account can have 0 or 1 authorized minter that can mint NFTs on its behalf.
|
||||
|
||||
You set the authorized minter with an `AccountSet` transaction.
|
||||
|
||||
``` json
|
||||
```js
|
||||
tx_json = {
|
||||
"TransactionType": "AccountSet",
|
||||
"TransactionType": "AccountSet",
|
||||
"Account": "rrE5EgHN4DfjXhR9USecudHm7UyhTYq6m",
|
||||
"NFTokenMinter": "r3riWB2TDWRmwmT7FRKdRHjqm6efYu4s9C",
|
||||
"SetFlag": xrpl.AccountSetAsfFlags.asfAuthorizedNFTokenMinter
|
||||
@@ -30,7 +30,7 @@ tx_json = {
|
||||
|
||||
To remove an authorized minter, use the `AccountSet` transaction and clear the `asfAuthorizedNFTokenMinter` flag.
|
||||
|
||||
``` json
|
||||
```js
|
||||
tx_json = {
|
||||
"TransactionType": "AccountSet",
|
||||
"Account": "rrE5EgHN4DfjXhR9USecudHm7UyhTYq6m",
|
||||
@@ -42,7 +42,7 @@ tx_json = {
|
||||
|
||||
You mint tokens for another account using the standard `NFTokenMint` transaction. The difference is that you must include the `Issuer` field, the account ID of the account for which you are minting the NFT.
|
||||
|
||||
```json
|
||||
```js
|
||||
const transactionBlob = {
|
||||
"TransactionType": "NFTokenMint",
|
||||
"Account": "r3riWB2TDWRmwmT7FRKdRHjqm6efYu4s9C",
|
||||
39
content/concepts/tokens/nfts/batch-minting.md
Normal file
39
content/concepts/tokens/nfts/batch-minting.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
html: nftoken-batch-minting.html
|
||||
parent: non-fungible-tokens.html
|
||||
blurb: Minting NFTs in batches.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# Batch Minting
|
||||
|
||||
There are two common approaches to minting NFTs in batches: mint on demand and scripted minting.
|
||||
|
||||
## Mint On Demand (Lazy Minting)
|
||||
|
||||
When using a mint on demand model, you and potential customers make buy or sell offers for initial sales of an NFT off the XRP Ledger. When you are ready to start the initial sale, you mint the token, create a sell offer or accept a buy offer, then complete the transaction.
|
||||
|
||||
### Benefits
|
||||
|
||||
* There is no reserve requirement for holding unsold NFTs.
|
||||
* You mint NFTs in real time when you know that it will sell. <!-- STYLE_OVERRIDE: will -->
|
||||
|
||||
### Downside
|
||||
|
||||
Any market activity before the initial sale of the NFT is not recorded on the XRP Ledger. This might not be an issue for some applications.
|
||||
|
||||
## Scripted Minting
|
||||
|
||||
Use a program or script to mint many tokens at once. You might find that [Tickets](tickets.html) help you submit transactions in parallel, up to a current limit of 200 transactions in one group.
|
||||
|
||||
For a practical example, see the [Batch Mint NFTs Using JavaScript](batch-mint-nfts-using-javascript.html) tutorial.
|
||||
|
||||
### Benefits
|
||||
|
||||
* NFTs are minted ahead of time.
|
||||
* Market activity for the initial sale of the NFT is captured on the ledger.
|
||||
|
||||
### Downside
|
||||
|
||||
You need to meet the [reserve requirement](reserves.html) for all of the NFTs you mint. As a rule of thumb, this is roughly 1/12th XRP per NFT at the current reserve rate. In the event that you do not have enough XRP in reserve, your mint transactions fail until you get more XRP.
|
||||
46
content/concepts/tokens/nfts/index.md
Normal file
46
content/concepts/tokens/nfts/index.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
html: non-fungible-tokens.html
|
||||
parent: tokens.html
|
||||
blurb: Introduction to XRPL NFTs.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# Non-Fungible Tokens
|
||||
|
||||
The XRP Ledger natively supports non-fungible tokens (NFTs, or “nifties” in the vernacular). Non-fungible tokens serve to encode ownership of unique physical, non-physical, or purely digital goods, such as works of art or in-game items.
|
||||
|
||||
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
|
||||
|
||||
To represent digital assets similar to these, use the XRP Ledger's Non-Fungible Tokens feature (sometimes referred to by its standards draft number, [XLS-20](https://github.com/XRPLF/XRPL-Standards/discussions/46)).
|
||||
|
||||
## NFTs on the XRP Ledger
|
||||
|
||||
On the XRP Ledger, an NFT is represented as a [NFToken][] object. An NFT is a unique, indivisible unit that is not used for payments. Users can mint (create), hold, buy, sell, and burn (destroy) NFTs.
|
||||
|
||||
The ledger stores up to 32 NFTa owned by the same account in a single [NFTokenPage object][] to save space. As a result, the owner's [reserve requirement](reserves.html) for NFTs only increases when the ledger needs to make a new page to store additional tokens.
|
||||
|
||||
Accounts can also name a _Broker_ or an _Authorized Minter_ who can sell or mint NFTs on their behalf.
|
||||
|
||||
NFTs have several immutable settings that are defined when the token is minted. These include:
|
||||
|
||||
- Identifying data that uniquely defines the token.
|
||||
- Whether the issuer can burn the token, regardless of who currently holds it.
|
||||
- Whether the holder of the token can transfer it to others. (An NFT can always be sent to or from the issuer directly.)
|
||||
- If transfers are allowed, the issuer can charge a transfer fee as a percentage of the sale price.
|
||||
- Whether the holder can sell the NFT for [fungible token](trust-lines-and-issuing.html) amounts, or only for XRP.
|
||||
|
||||
## NFT Lifecycle
|
||||
|
||||
Anyone can create a new NFT using the [NFTokenMint transaction][]. The NFT lives on the [NFTokenPage object][] of the issuing account. Either the owner or an interested party can send a [NFTokenCreateOffer transaction][] to propose buying or selling the NFT; the ledger tracks the proposed transfer as a [NFTokenOffer object][], and deletes the `NFTokenOffer` when either side accepts or cancels the offer. If the NFT is transferable, it can be traded multiple times between accounts.
|
||||
|
||||
You can destroy an NFT you own using the [NFTokenBurn transaction][]. If the issuer minted the token with the `tfBurnable` flag enabled, the issuer can also burn the token, regardless of the current owner. (This could be useful, for example, for a token that represents a ticket to an event that is used up at some point.)
|
||||
|
||||
|
||||
|
||||
For more info about transferring NFTs, see [Trading NFTs on the XRP Ledger](non-fungible-token-transfers.html).
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -9,12 +9,12 @@ labels:
|
||||
|
||||
This page lists the transactions and requests associated with NFTs as a handy reference.
|
||||
|
||||
## NFT Objects
|
||||
## NFT Ledger Entries
|
||||
|
||||
- [NFToken][] data type - The NFT object stored on the ledger.
|
||||
- Ledger Objects
|
||||
- [NFTokenOffer object][] - An offer to buy or sell an NFT.
|
||||
- [NFTokenPage object][] - An NFT page holds a maximum of 32 NFT objects. In practice, each NFT page typically holds 16-24 NFTs.
|
||||
- Ledger Entries
|
||||
- [NFTokenOffer entry][] - An offer to buy or sell an NFT.
|
||||
- [NFTokenPage entry][] - An NFT page holds a maximum of 32 NFTs. In practice, each NFT page typically holds 16-24 NFTs.
|
||||
|
||||
## NFT Transactions
|
||||
|
||||
@@ -38,20 +38,14 @@ This page lists the transactions and requests associated with NFTs as a handy re
|
||||
|
||||
## Clio
|
||||
|
||||
Clio servers enhance overall network performance by handling requests for information based on cached information, freeing up validators on the XRP Ledger to focus on processing transactions. In addition to all of the common XRP Ledger request types, the Clio server handles additional request types that provide more detailed responses.
|
||||
|
||||
### Clio-specific NFT requests
|
||||
[Clio servers](the-clio-server.html) also provide the following APIs related to NFTs:
|
||||
|
||||
- [nft_info](nft_info.html) - Get current status information about the specified NFT.
|
||||
- [nft_history](nft_history.html) - Get past transaction metadata for the specified NFT.
|
||||
|
||||
<!--
|
||||
[nfts_by_issuer](nfts_by_issuer.html) - Get a list of all NFTs created by the specified issuer.
|
||||
-->
|
||||
|
||||
You can access a public Clio server by sending a request to its URL and Clio port (typically 51233). Public Clio API servers come with no SLAs nor any responsibility to be fixed on priority. If your business use case requires continual monitoring and information requests, consider setting up your own Clio server instance. See [install-clio-on-ubuntu](install-clio-on-ubuntu.html).
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -65,4 +65,4 @@ If you were to mint 200 NFTs and create an `NFTokenSellOffer`for each, that woul
|
||||
| Total | 436 XRP |
|
||||
| | |
|
||||
|
||||
If the required reserves exceed the amount you are comfortable setting aside, consider using the mint-on-demand model to reduce the number of NFTs and offers you hold at any one time. See [Mint on Demand](nftoken-batch-minting.html#mint-on-demand-lazy-minting).
|
||||
If the required reserves exceed the amount you are comfortable setting aside, consider using the mint-on-demand model to reduce the number of NFTs and offers you hold at any one time. For details, see [Batch Minting](nftoken-batch-minting.html).
|
||||
@@ -15,7 +15,7 @@ This flow is the most straightforward. Note that the `NFTokenOffer` objects can
|
||||
|
||||
1. Store your bids in a private database.
|
||||
2. You take a cut of the winning bid.
|
||||
3. Send the buyer/seller the XRPL transaction to complete the purchase.
|
||||
3. Send the buyer/seller the XRPL transaction to complete the purchase.
|
||||
|
||||
## Run the Auction in Brokered Mode, with a Reserve
|
||||
|
||||
@@ -39,7 +39,7 @@ Run the auction in brokered mode, as an auction with a reserve.
|
||||
|
||||
A major mitigating factor of this downside is that if this behavior were to happen, brokers would lose their entire market share, which sellers should understand.
|
||||
|
||||
## Run the Auction in Brokered Mode, without a Reserve.
|
||||
## Run the Auction in Brokered Mode, without a Reserve.
|
||||
|
||||
This is the most complex workflow of the three.
|
||||
|
||||
76
content/concepts/tokens/nfts/trading.md
Normal file
76
content/concepts/tokens/nfts/trading.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
html: non-fungible-token-transfers.html
|
||||
parent: non-fungible-tokens.html
|
||||
blurb: Trading NFTs in direct or brokered mode.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# Trading NFTs
|
||||
|
||||
You can transfer NFTs between accounts on the XRP Ledger. You can offer to buy or sell an NFT, or accept offers from other accounts to buy an NFT you own. You can even give away an NFT by offering to sell it at a price of 0. All offers are created using [NFTokenCreateOffer transaction][].
|
||||
|
||||
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
|
||||
|
||||
## Reserve Requirements
|
||||
|
||||
Every `NFTokenOffer` object requires that your account increase its owner reserve, currently 2 XRP per `NFTokenSellOffer` and 2 XRP per `NFTokenBuyOffer`. This is to prevent accounts from spamming the ledger with offers they don't intend to complete.
|
||||
|
||||
See [NFT Reserve Requirements](nft-reserve-requirements.html).
|
||||
|
||||
## Sell Offers
|
||||
|
||||
### Create a Sell Offer
|
||||
|
||||
As the owner of an NFT, you can create a sell offer using a [NFTokenCreateOffer transaction][] with the `tfSellToken` flag. You provide the `NFTokenID` and the `Amount` you are willing to accept in payment. You can optionally specify an `Expiration` date, after which the offer is no longer valid, and a `Destination` account, which is the only account that is allowed to buy the NFT.
|
||||
|
||||
### Accept a Sell Offer
|
||||
|
||||
To buy an NFT that is offered for sale, you use a `NFTokenAcceptOffer` transaction. You provide the owner account and specify the `NFTokenOfferID` of the `NFTokenOffer` object you choose to accept.
|
||||
|
||||
## Buy Offers
|
||||
|
||||
### Create a Buy Offer
|
||||
|
||||
Any account can offer to buy an NFT. You can create a buy offer using [NFTokenCreateOffer][] _without_ the `tfSellToken` flag. You provide the `Owner` account, `NFTokenID`, and the `Amount` of your offer.
|
||||
|
||||
### Accept a Buy Offer
|
||||
|
||||
Use the `NFTokenAcceptOffer` transaction to transfer an NFT. Provide the `NFTokenOfferID` and the owner account to complete the transaction.
|
||||
|
||||
## Trading Modes
|
||||
|
||||
When trading an NFT, you can choose between a _direct_ transaction between a buyer and seller or a _brokered_ transaction, where a third party account matches a sell and buy offer to arrange the trade.
|
||||
|
||||
Trading in direct mode gives the seller control over the transfer. The seller can either post an NFT for sale so that anyone can buy it, or sell an NFT to a specific account. The seller receives the entire price for the NFT.
|
||||
|
||||
In brokered mode, the seller allows a third party account to broker the sale of the NFT. The broker account collects a broker fee for the transfer at an agreed upon rate. This happens as one transaction, paying the broker and seller from the buyer’s funds without requiring an up front investment by the broker.
|
||||
|
||||
### When to Use Brokered Mode
|
||||
|
||||
If an NFT creator has the time and patience to seek out the right buyers, the creator keeps all proceeds from the sale. This works fine for a creator who sells few NFTs at variable prices.
|
||||
|
||||
On the other hand, creators might not want to spend their time selling their creations when they could spend the time creating. Instead of handling each individual sale, the sales work can be turned over to a third-party broker account.
|
||||
|
||||
Using a broker offers several advantages. For example:
|
||||
|
||||
* The broker can act as an agent, working to maximize the selling price of the NFT. If the broker is paid a percentage of the sale price, the higher the price, the more the broker earns.
|
||||
* The broker can act as a curator, organizing NFTs based on a niche market, price point, or other criteria. This can attract groups of buyers who might not otherwise discover a creator’s work.
|
||||
* The broker can act as a marketplace, similar to Opensea.io, to handle the auction process at the application layer.
|
||||
|
||||
### Brokered Sale Workflows
|
||||
|
||||
In the most straightforward workflow, a creator mints a new NFT. The creator initiates a sell offer, entering the minimum acceptable sale price and setting the broker as the destination. Potential buyers make bids for the NFT, setting the broker as the destination for the bid. The broker selects a winning bid and completes the transaction, taking a broker’s fee. As a best practice, the broker then cancels any remaining buy offers for the NFT.
|
||||
|
||||
|
||||
|
||||
Another potential workflow would give the creator more control over the sale. In this workflow, the creator mints a new NFT. Bidders create their offers, setting the broker as the destination. The broker selects the winning bid, subtracts their broker fee, and uses `NFTokenCreateOffer` to request that the creator sign off on the offer. The creator signs the requested offer, setting the broker as the destination. The broker completes the sale using `NFTokenAcceptOffer`, retaining the broker fee. The broker cancels any remaining bids for the NFT using `NFTokenCancelOffer`.
|
||||
|
||||
|
||||
|
||||
The same workflows can be used when an owner resells an NFT created by another account.
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
html: non-fungible-token-transfers.html
|
||||
parent: non-fungible-tokens.html
|
||||
blurb: Trading NFTokens in direct or brokered mode.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# Trading NFTokens on the XRP Ledger
|
||||
|
||||
You can transfer `NFToken` objects between accounts on the XRP Ledger. You can offer to buy or sell a `NFToken`, or accept offers from other accounts to buy a `NFToken` you own. You can even give away a `NFToken` by offering to sell it at a price of 0. All offers are created using [NFTokenCreateOffer transaction][].
|
||||
|
||||
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
|
||||
|
||||
## Reserve Requirements
|
||||
|
||||
Every NFTokenOffer object requires that your account increase its owner reserve, currently 2 XRP per `NFTokenSellOffer` and 2 XRP per `NFTokenBuyOffer`. This is to prevent accounts from spamming the ledger with offers they don't intend to complete.
|
||||
|
||||
See [NFT Reserve Requirements](nft-reserve-requirements.html).
|
||||
|
||||
## Sell Offers
|
||||
|
||||
### Create a Sell Offer
|
||||
|
||||
As the owner of a `NFToken` object, you can create a sell offer using a [NFTokenCreateOffer transaction][] with the `tfSellToken` flag. You provide the `NFTokenID` and the `Amount` you are willing to accept in payment. You can optionally specify an `Expiration` date, after which the offer is no longer valid, and a `Destination` account, which is the only account that is allowed to buy the `NFToken`.
|
||||
|
||||
### Accept a Sell Offer
|
||||
|
||||
To buy a `NFToken` that is offered for sale, you use a `NFTokenAcceptOffer` transaction. You provide the owner account and specify the `NFTokenOfferID` of the `NFTokenOffer` object you choose to accept.
|
||||
|
||||
## Buy Offers
|
||||
|
||||
### Create a Buy Offer
|
||||
|
||||
Any account can offer to buy a `NFToken`. You can create a buy offer using [NFTokenCreateOffer][] _without_ the `tfSellToken` flag. You provide the `Owner` account, `NFTokenID`, and the `Amount` of your offer.
|
||||
|
||||
### Accept a Buy Offer
|
||||
|
||||
Use the `NFTokenAcceptOffer` transaction to transfer a `NFToken`. Provide the `NFTokenOfferID` and the owner account to complete the transaction.
|
||||
|
||||
## Trading Modes
|
||||
|
||||
When trading a `NFToken`, you can choose between a _direct_ transaction between a buyer and seller or a _brokered_ transaction, where a third party account matches a sell and buy offer to arrange the trade.
|
||||
|
||||
Trading in direct mode gives the seller control over the transfer. The seller can either post a `NFToken` for sale so that anyone can buy it, or sell a `NFToken` to a specific account. The seller receives the entire price for the `NFToken`.
|
||||
|
||||
In brokered mode, the seller allows a third party account to broker the sale of the `NFToken`. The broker account collects a broker fee for the transfer at an agreed upon rate. This happens as one transaction, paying the broker and seller from the buyer’s funds without requiring an up front investment by the broker.
|
||||
|
||||
### When to Use Brokered Mode
|
||||
|
||||
If a `NFToken` creator has the time and patience to seek out the right buyers, the creator keeps all proceeds from the sale. This works fine for a creator who sells few `NFToken` objects at variable prices.
|
||||
|
||||
On the other hand, creators might not want to spend their time selling their creations when they could spend the time creating. Instead of handling each individual sale, the sales work can be turned over to a third-party broker account.
|
||||
|
||||
Using a broker offers several advantages. For example:
|
||||
|
||||
* The broker can act as an agent, working to maximize the selling price of the `NFToken`. If the broker is paid a percentage of the sale price, the higher the price, the more the broker earns.
|
||||
* The broker can act as a curator, organizing `NFToken` objects based on a niche market, price point, or other criteria. This can attract groups of buyers who might not otherwise discover a creator’s work.
|
||||
* The broker can act as a marketplace, similar to Opensea.io, to handle the auction process at the application layer.
|
||||
|
||||
### Brokered Sale Workflows
|
||||
|
||||
In the most straightforward workflow, a creator mints a new `NFToken`. The creator initiates a sell offer, entering the minimum acceptable sale price and setting the broker as the destination. Potential buyers make bids for the `NFToken`, setting the broker as the destination for the bid. The broker selects a winning bid and completes the transaction, taking a broker’s fee. As a best practice, the broker then cancels any remaining buy offers for the `NFToken`.
|
||||
|
||||
|
||||
|
||||
Another potential workflow would give the creator more control over the sale. In this workflow, the creator mints a new `NFToken`. Bidders create their offers, setting the broker as the destination. The broker selects the winning bid, subtracts their broker fee, and uses `NFTokenCreateOffer` to request that the creator sign off on the offer. The creator signs the requested offer, setting the broker as the destination. The broker completes the sale using `NFTokenAcceptOffer`, retaining the broker fee. The broker cancels any remaining bids for the `NFToken` using `NFTokenCancelOffer`.
|
||||
|
||||
|
||||
|
||||
The same workflows can be used when an owner resells a `NFToken` created by another account.
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
html: non-fungible-tokens.html
|
||||
parent: tokens.html
|
||||
blurb: Introduction to XRPL NFTs.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# Non-Fungible Tokens
|
||||
|
||||
The XRP Ledger natively supports non-fungible tokens (NFTs, or “nifties” in the vernacular). Non-fungible tokens serve to encode ownership of unique physical, non-physical, or purely digital goods, such as works of art or in-game items.
|
||||
|
||||
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
|
||||
|
||||
|
||||
## Background
|
||||
|
||||
The XRP Ledger offers support for [tokens](tokens.html). Such assets are, primarily, fungible.
|
||||
|
||||
> Fun·gi·ble /´fənjəbəl/ (adj) <!-- SPELLING_IGNORE: fənjəbəl -->
|
||||
>
|
||||
> 1. able to replace or be replaced by another identical item; mutually interchangeable. <!-- STYLE_OVERRIDE: identical -->
|
||||
|
||||
Fungible tokens can be traded between users for XRP or other issued assets on the XRP Ledger's decentralized exchange. This makes them ideal for payments.
|
||||
|
||||
|
||||
A good example of a fungible item might be a postage stamp. If you are standing around in 1919 and need to send a letter by airmail, you would buy a 24-cent stamp and affix it to your envelope. If you lost that stamp, you could use a different 24-cent stamp or use 2 10-cent stamps and 2 2-cent stamps. Very fungible.
|
||||
|
||||
|
||||
|
||||
But since you are standing around in 1919, you might be offered 24-cent airmail stamps where the aeroplane on the stamp is accidentally printed upside down. These are the world famous “Inverted Jenny” stamps. Only 100 were circulated on a single sheet of stamps, making them extremely rare and sought after. The current value of each mint condition stamp is appraised at over $1.5 million dollars.
|
||||
|
||||
|
||||
|
||||
Those stamps cannot be replaced by an ordinary 24-cent stamp. They have become _non-fungible_.
|
||||
|
||||
To represent digital assets similar to these, use the XRP Ledger's Non-Fungible Tokens feature (sometimes referred to by its standards draft number, [XLS-20](https://github.com/XRPLF/XRPL-Standards/discussions/46)).
|
||||
|
||||
|
||||
## NFTs on the XRP Ledger
|
||||
|
||||
On the XRP Ledger, a non-fungible token is represented as a [NFToken][] object. A `NFToken` is a unique, indivisible unit that is not used for payments. Users can mint (create), hold, buy, sell, and burn (destroy) such tokens.
|
||||
|
||||
The ledger stores up to 32 `NFToken` objects owned by the same account in a single [NFTokenPage object][] to save space. As a result, the owner's [reserve requirement](reserves.html) for `NFToken` objects only increases when the ledger needs to make a new page to store additional tokens.
|
||||
|
||||
Accounts can also name a broker, or "Authorized Minter", who can mint and sell `NFToken` objects on their behalf.
|
||||
|
||||
`NFToken` objects have several settings that are defined when the token is minted and cannot be changed later. These include:
|
||||
|
||||
- Various identifying data that uniquely defines the token.
|
||||
- Whether the issuer can burn the token regardless of who currently holds it.
|
||||
- Whether the holder of the token can transfer it to others. (The `NFToken` can always be sent to or from the issuer directly.)
|
||||
- If transfers are allowed, the issuer can charge a transfer fee as a percentage of the sale price.
|
||||
- Whether the holder can sell the `NFToken` for [fungible token](tokens.html) amounts, or only for XRP.
|
||||
|
||||
|
||||
## `NFToken` Lifecycle
|
||||
|
||||
Anyone can create a new `NFToken` using the [NFTokenMint transaction][] type. The `NFToken` lives on the [NFTokenPage object][] of the issuing account. Either the owner or an interested party can send a [NFTokenCreateOffer transaction][] to propose buying or selling the `NFToken`; the ledger tracks the proposed transfer as a [NFTokenOffer object][], and deletes the `NFTokenOffer` when either side accepts or cancels the offer. If the `NFToken` is transferable, it can be traded multiple times between accounts.
|
||||
|
||||
You can destroy a `NFToken` you own using the [NFTokenBurn transaction][]. If the issuer minted the token with `tfBurnable` flag enabled, the issuer can also burn the token regardless of the current owner. (This could be useful, for example, for a token that represents a ticket to an event which is used up at some point.)
|
||||
|
||||
|
||||
|
||||
For more info about transferring `NFToken` objects, see [Trading NFTokens on the XRP Ledger](non-fungible-token-transfers.html).
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
parent: concepts.html
|
||||
blurb: Anyone can make tokens representing digital value on the XRP Ledger.
|
||||
labels:
|
||||
- Tokens
|
||||
---
|
||||
# Tokens
|
||||
|
||||
All assets other than XRP can be represented in the XRP Ledger as **tokens**. Standard tokens are tracked in relationships called [trust lines](trust-lines-and-issuing.html) between accounts. Any account can issue tokens to other recipients who are willing to hold them, but you cannot unilaterally give tokens away to users who don't want them. Tokens can represent any type of value, including "stablecoins" backed by assets that exist outside of the ledger, purely digital tokens created specifically on the XRP Ledger, community credit, and more.
|
||||
|
||||
**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 -->
|
||||
|
||||
Standard tokens are fungible: meaning, all units of that token are interchangeable and indistinguishable. Non-fungible tokens are also possible: see [Non-Fungible Tokens](non-fungible-tokens.html) for details of the XRP Ledger's native support.
|
||||
|
||||
Tokens can used for [cross-currency payments](cross-currency-payments.html) and can be traded in the [decentralized exchange](decentralized-exchange.html).
|
||||
|
||||
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.html) on trust lines to prevent those trust lines from rippling.
|
||||
|
||||
|
||||
## Stablecoins
|
||||
|
||||
A common model for tokens in the XRP Ledger is that an issuer holds assets of equivalent value outside of the XRP Ledger, and issues tokens representing that 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 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.
|
||||
|
||||
For more information, see [Stablecoin Issuer](stablecoin-issuer.html).
|
||||
|
||||
|
||||
## Community Credit
|
||||
|
||||
Another way you can use the XRP Ledger is for "community credit", a system where individuals who know each other can use the XRP Ledger to track who owes who else how much money. A powerful feature of the XRP Ledger is that it can automatically and atomically use these debts to settle payments through [rippling](rippling.html).
|
||||
|
||||
For example, if Asheesh owes Marcus $20, and Marcus owes Bharath $50, Bharath can "pay" Asheesh $20 by canceling that much of Marcus's debt to him in exchange for canceling Asheesh's debt to Marcus. The reverse is also possible: Asheesh can pay Bharath through Marcus by increasing their respective debts. The XRP Ledger can settle complex chains of exchanges like this in a single transaction without the accounts in the middle needing to do anything manually.
|
||||
|
||||
For more on this type of usage, see [paths](paths.html). <!--{# TODO: It would be nice to be able to link to a page with more illustrative examples of community credit. #}-->
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
**Warning:** ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA. <!-- SPELLING_IGNORE: ico, icos -->
|
||||
|
||||
Be sure to research the relevant regulations before engaging in any financial service business.
|
||||
|
||||
|
||||
## Token Properties
|
||||
|
||||
Tokens in the XRP Ledger are [fundamentally different than XRP](currency-formats.html#comparison). 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](decentralized-exchange.html) or by decreasing the limit after you already have a positive balance.)
|
||||
|
||||
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>).
|
||||
|
||||
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](cross-currency-payments.html) or trades can also create more tokens according to an issuer's settings.
|
||||
|
||||
Issuers can charge a [transfer fee](transfer-fees.html) that is automatically deducted when users transfer their tokens. Issuers can also define a [tick size](ticksize.html) for exchanges rates involving their tokens. Both issuers and regular accounts can [freeze](freezes.html) trust lines, which limits how the tokens in those trust lines can be used. (None of these things applies to XRP.)
|
||||
|
||||
For a tutorial of the technical steps involved in issuing a token, see [Issue a Fungible Token](issue-a-fungible-token.html).
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [What is XRP?](what-is-xrp.html)
|
||||
- [Cross-Currency Payments](cross-currency-payments.html)
|
||||
- [Decentralized Exchange](decentralized-exchange.html)
|
||||
- **Tutorials:**
|
||||
- [Issue a Fungible Token](issue-a-fungible-token.html)
|
||||
- [Look Up Transaction Results](look-up-transaction-results.html)
|
||||
- [Use Specialized Payment Types](use-specialized-payment-types.html)
|
||||
- **References:**
|
||||
- [Payment transaction][]
|
||||
- [TrustSet transaction][]
|
||||
- [RippleState object](ripplestate.html)
|
||||
- [account_lines method][]
|
||||
- [account_currencies method][]
|
||||
- [gateway_balances method][]
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
Reference in New Issue
Block a user