ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-29 16:15:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Re-level non-docs content to top of repo and rename content→docs

Browse Source
This commit is contained in:
mDuo13
2024-01-31 16:24:01 -08:00
parent f841ef173c
commit c10beb85c2
2907 changed files with 1 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
docs/use-cases/defi/algorithmic-trading.md Normal file
View File

@@ -0,0 +1,102 @@
---
html: algorithmic-trading.html
parent: defi-uc.html
seo:
description: The XRP Ledger's decentralized exchange consists of an unlimited number of currency pairs, tracked on-demand when users make trades.
labels:
- Transactions
---
# Algorithmic Trading
The XRP Ledger's decentralized exchange presents an opportunity to earn money through _algorithmic trading_, which means running a computer program to find and take profitable trading opportunities automatically. In algorithmic trading, you typically make many trades based on quantitative factors to earn steady, small profits; this is unlike traditional manual trading where you make a few long-term investments based on market fundamentals and wait to earn a large return over time. Blockchains are often more suitable for algorithmic trading than manual trading, because the high volatility of cryptocurrencies in general makes them less suitable for traditional "buy and hold" investing; the XRP Ledger is particularly suited for algorithmic trading, for several reasons:
- Decentralized exchange data is public and freely available.
- Trades settle in seconds, enabling frequent trading without specialized equipment.
- Transaction costs on the XRP Ledger are low.
## Trading Strategies
Algorithmic trading can make profits through many different strategies; part of the challenge (or the fun) of algorithmic trading is designing and implementing your own unique approach. From a high level, algorithmic trading approaches often fall into the following categories:
- **Arbitrage:** Buying and immediately selling an asset to take advantages of price differences. This could involve finding sets of 3 or more assets where the prices aren't aligned, or using the XRP Ledger to move assets between private exchanges where the prices are different.
- **Quantitative Trading:** Predicting and taking advantage of future price movements based on past price movements, outside data, or both. Examples include [candlestick patterns](https://blog.quantinsti.com/candlestick-patterns-meaning/), correlating an asset's price movements with other assets, and using sentiment analysis of social media.
- **Front-running:** Taking advantage of pending trades, especially large ones, by buying and immediately reselling the assets those trades are buying. Front-running is often frowned-upon because it takes profits from other traders without adding liquidity or enabling exchanges that otherwise wouldn't occur. The XRP Ledger's canonical ordering of transactions makes front-running difficult, but not impossible.
### Arbitrage Examples
There are many ways to perform arbitrage, both within and adjacent to the XRP Ledger. The following examples are meant to illustrate potential strategies, but others are possible as well.
You can use **circular payments** to complete multi-asset trades for a profit. The XRP Ledger automatically connects overlapping trades between pairs of assets, as well as sets of 3 assets where XRP is the asset in the middle. However, the XRP Ledger protocol does not automatically find and compete trades across other, longer or more complex paths. (Finding the _best possible_ path is a category of problem that is known to be computationally intensive.) Therefore, if you do your own pathfinding, it is possible to find profitable arbitrage opportunities like this; if you do, you can specify those [paths](../../concepts/tokens/fungible-tokens/paths.md) explicitly in a [Payment transaction](../../references/protocol/transactions/types/payment.md). For example, imagine there are three tokens, FOO, BAR, and TST, each with different issuers. If you can buy 2 BAR by spending 1 FOO, then buy 3 TST by spending those 2 BAR, and finally buy 1.1 FOO by spending 3 TST, you can earn a profit of 0.1 FOO minus any costs of the transaction such as [transfer fees](../../concepts/tokens/transfer-fees.md) of the tokens involved.
You can perform **cross-exchange arbitrage** if you have accounts at multiple private exchanges where the prices for an asset are different. For example, if you can buy XRP at ACME Exchange for $0.45 per 1 XRP, then move the XRP over to WayGate Exchange where you sell it for $0.50 per 1 XRP, you can make a profit of $0.05 per XRP minus the costs of trading and sending the relevant transactions, including exchanges' fees to withdraw and deposit your profits. As a more complex example, if the BTC:ETH price shifts at ACME Exchange to make ETH cheaper relative to BTC, you could potentially take advantage of this price shift by selling ETH→XRP at one exchange, then moving the XRP to ACME Exchange and trading XRP→BTC→ETH for a profit there. Since XRP Ledger transactions settle in seconds but Ethereum transactions can take minutes and Bitcoin transactions can take hours, using XRP as a bridge currency can potentially allow you to take advantage of this opportunity sooner than simply trading ETH→BTC and then BTC→ETH at ACME Exchange. (This only works, of course, if there is enough liquidity and tight enough spreads that exchanging to XRP and back doesn't cost more than your profits.)
## Background Reading
You can familiarize yourself with algorithmic trading, in general, by reading the following resources:
- [Investopedia: Basics of Algorithmic Trading: Concepts and Examples](https://www.investopedia.com/articles/active-trading/101014/basics-algorithmic-trading-concepts-and-examples.asp)
- [_Flash Boys: A Wall Street Revolt_ by Michael Lewis](https://wwnorton.com/books/Flash-Boys/)
- [Investopedia: How Arbitraging Works in Investing, With Examples](https://www.investopedia.com/terms/a/arbitrage.asp)
The following pages describe key elements of how the XRP Ledger's decentralized exchange works:
- [Tokens](../../concepts/tokens/index.md)
- [Decentralized Exchange](../../concepts/tokens/decentralized-exchange/index.md)
- [Offers](../../concepts/tokens/decentralized-exchange/offers.md)
## Testing and Common Mistakes
Like any type of trading, algorithmic trading is not a surefire way to make money; there are many ways you might take a loss. Compared with manual trading, algorithmic trading has much less room for error. If you make a small mistake, but multiply it by a large number of trades, your losses can add up quickly before you have a chance to fix the problem. Therefore, it's wise to do various tests to make sure that your trading strategy will actually make a profit. You might do any or all of the following to test your strategy or the actual implementation of it (often called a _bot_):
- Manually calculate the potential returns based on the current ledger state or past trades.
- Record historical data and feed it to your bot, then record what actions the bot would have taken and compare the results against the actual historical price movements.
- Model or predict the results of your approach in various plausible future scenarios.
Common mistakes you might make in these calculations or in building your bot include:
- Rounding errors. If your math is not sound, or does not match the precision that the blockchain uses, you could inaccurately predict the results of a trade and take a loss, or have your trade not execute at all. The XRP Ledger uses different precision for token and XRP amounts, which can lead to rounding in unexpected places when trading one for the other. For more details on the precision used in the protocol, see [Currency Formats](../../references/protocol/data-types/currency-formats.md).
- Be aware that token issuers can further limit the precision of exchange rates involving their tokens. See [Tick Size](../../concepts/tokens/decentralized-exchange/ticksize.md) for details.
- Typically, you need to adjust your amounts by some small percentage to account for potential differences in rounding or price movements between when you looked things up and when your trade executes. This amount is called _slippage_, and it's important to get the right amount. If it's too low, your transaction may not execute at all; but if it's too high, you're vulnerable to front-running, and the higher it is the more that price movements can cut into your profits in general.
- Forgetting extra costs and delays. For example, if two stablecoins are both fully backed by US dollars, but one issuer charges a 0.5% transfer fee and a different issuer charges a 0.25% [transfer fee](../../concepts/tokens/transfer-fees.md), you should expect about a 0.25% difference in the effective price those stablecoins trade at. Don't forget the costs of sending a transaction, even though they're usually small, nor the consequences of other potential delays. For example, even if an off-ledger private exchange shows a favorable price now, if that exchange takes hours or even days to process a deposit, the price is likely to shift so you can't take advantage of it unless you already have liquidity at that exchange.
- Not accounting for rare events. Even setting aside unprecented ("black swan") events, your calculations can be skewed by individual outliers. As one example (which is a true story), a trader reported that, when calculating the potential profits of a given strategy in a specific time range, over 80% of the profits came from a single "fat-fingered" transaction where another user had accidentally added an extra zero to their price. The same strategy was far less profitable when calculated against time ranges that didn't include the outlier transaction.
- Not reading transaction flags. The flags of an XRP Ledger transaction can have significant impacts on the way that transaction is processed and when the protocol marks it as "successful". For example, the flags of "Offer" transactions can make it a "fill or kill" order that only trades if the full amount can be obtained immediately; the flags of "Payment" transactions can make them [partial payments](../../concepts/payment-types/partial-payments.md) that succeed even if they can't deliver the full amount to the intended destination. You need to do bitwise math to parse the `Flags` field of a transaction, but your expectations can be totally wrong if you skip doing so.
## Taxes and Licensing
The legal requirements for trading on a blockchain vary by jurisdiction. In many cases, there are no licensing or other legal barriers to getting started, but you may be required to report your profits for tax purposes, especially if your gains or losses are over some thresholds. In the United States, you typically report profits (or losses) from trading as capital gains, which means you need to calculate the cost basis for the assets you buy at the time you acquire them. There are various tools out there that may be able to help track your trading activity or even generate the appropriate tax forms, depending on your individual situation. Depending on which assets you are trading and your trading strategies, the details may vary. Be sure to do your research or consult with a tax professional before you get started with algorithmic trading.
## Technical Details
### Placing Trades
Buying and selling _fungible_ tokens and XRP within the XRP Ledger's decentralized exchange typically involves sending [OfferCreate transactions](../../references/protocol/transactions/types/offercreate.md). For a detailed walkthrough of the code and technical steps to place a trade this way, see [Trade in the Decentralized Exchange](../../tutorials/use-tokens/trade-in-the-decentralized-exchange.md). It is also possible to exchange currencies using the [Payment transaction type](../../references/protocol/transactions/types/payment.md). You could send a [cross-currency payment](../../concepts/payment-types/cross-currency-payments.md) to another user or even send it back to yourself, using a long [path](../../concepts/tokens/fungible-tokens/paths.md) to link arbitrage opportunities together into a single operation.
Non-fungible tokens work differently; for the code and technical steps to trade NFTs, see [Transfer NFTokens Using JavaScript](../../tutorials/quickstart/transfer-nfts-using-javascript.md).
### Reading Trade Data
There are many sources of information about the trading activity in the XRP Ledger. Depending on your trading strategy and use case, you may be able to connect to the XRP Ledger through [Public Servers](../../tutorials/get-started/public-servers.md), but you can often benefit from running your own server, and some use cases may not be practical without doing so. See [Install `rippled`](../../infrastructure/installation/index.md) for instructions on how to set up a core server in P2P mode.
If your approach involves following other transaction activity, you may need to read the transactions' detailed metadata to know exactly how much they traded. Offers can partially execute and may consume multiple matching offers. For a detailed explanation of how to interpret transaction metadata, see [Look Up Transaction Results](../../concepts/transactions/finality-of-results/look-up-transaction-results.md).
To give yourself as much time as possible to react to profit-taking opportunities, you may also want to look at pending data from the [Open Ledger](../../concepts/ledgers/open-closed-validated-ledgers.md), or even monitor for proposed transactions. If you're connected to WebSocket, you can use the [subscribe method](../../references/http-websocket-apis/public-api-methods/subscription-methods/subscribe.md) with the `transactions_proposed` stream to see transactions before they're validated by consensus; you can also limit this to a subset of transactions that affect a particular account (for example, the issuer of a token you're interested in trading) by subscribing using the `accounts_proposed` parameter.
### Future Developments
Ripple has proposed extending the XRP Ledger protocol with a native Automated Market Maker (AMM) design that would work alongside the existing central limit order based (CLOB) decentralized exchange. If this proposal is accepted and becomes enabled as an [amendment](../../concepts/networks-and-servers/amendments.md), AMMs will become an important factor in trading on the XRP Ledger. You can read more at the following links:
- [XLS-30d: Automated Market Maker standards proposal](https://github.com/XRPLF/XRPL-Standards/discussions/78)
- [AMM documentation (Ripple Open Source site)](https://opensource.ripple.com/docs/xls-30d-amm/automated-market-makers/)
## Further Reading
The following articles provide some more specific examples and interesting information about how these strategies work on other blockchains. This information isn't necessary to get started, but may help to provide perspective.
- [Ethereum is a Dark Forest](https://www.paradigm.xyz/2020/08/ethereum-is-a-dark-forest)
- [Flash Boys 2.0: Frontrunning, Transaction Reordering, and Consensus Instability in Decentralized Exchanges (PDF)](https://arxiv.org/pdf/1904.05234.pdf)
- [Slippage in AMM Markets](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=4133897)
- [Frontrunner Jones and the Raiders of the Dark Forest: An Empirical Study of Frontrunning on the Ethereum Blockchain](https://www.usenix.org/conference/usenixsecurity21/presentation/torres)
- [SoK: Transparent Dishonesty: front-running attacks on Blockchain (PDF)](https://arxiv.org/pdf/1902.05164)

15
docs/use-cases/defi/index.md Normal file
View File

@@ -0,0 +1,15 @@
---
html: defi-uc.html
parent: use-cases.html
top_nav_grouping: Article Types
metadata:
indexPage: true
seo:
description: Enabling fast, secure financial transactions without a central authority.
---
# Decentralized Finance
Decentralized Finance (DeFi) is about enabling fast, secure financial transactions without a central authority.
{% child-pages /%}

625
docs/use-cases/defi/list-xrp-as-an-exchange.md Normal file
View File

@@ -0,0 +1,625 @@
---
html: list-xrp-as-an-exchange.html
parent: defi-uc.html
seo:
description: Run a digital asset exchange? Follow these steps to add XRP.
labels:
- XRP
---
# List XRP as an Exchange
This document describes the steps that an exchange needs to take to list XRP. These steps are targeted at _custodial exchanges_ that hold funds on behalf of users, and allows users to deposit, withdraw, and trade other digital assets, fiat currencies, or other types of asset.
## Alpha Exchange
For illustrative purposes, this document uses a fictitious business called _Alpha Exchange_ to explain the high-level steps required to list XRP. For the purposes of this document, Alpha Exchange:
* Currently specializes in listing BTC/USD
* Wants to add BTC/XRP and XRP/USD trading pairs
* Maintains balances for all of its customers
* Maintains balances for each of its supported currencies
### User Benefits
Alpha Exchange wants to list BTC/XRP and XRP/USD trading pairs partially because listing these pairs benefits its users. Specifically, this support wants to enable its users to:
* Deposit XRP _to_ Alpha Exchange _from_ the XRP Ledger
* Withdraw XRP _from_ Alpha Exchange _to_ the XRP Ledger
* Trade XRP with other currencies, such as BTC, USD, among others
## Prerequisites for Supporting XRP
To support XRP, Alpha Exchange must:
* Create and maintain new [accounts](#accounts)
* Create and maintain [balance sheets](#balance-sheets)
See also:
* [Compliance Guidelines](../../concepts/tokens/fungible-tokens/stablecoins/compliance-guidelines.md) — Token issuers and exchanges are different, but exchanges should also ensure that they are complying with local regulations and reporting to the appropriate agencies.
<!-- These sections need to be topics of their own, without the story.
* [Requirements for Sending to XRP Ledger](stablecoin-issuer.html#requirements-for-sending-to-xrp-ledger)
* [Requirements for Receiving from XRP Ledger](stablecoin-issuer.html#requirements-for-receiving-from-xrp-ledger)
-->
* [Precautions](../../concepts/tokens/fungible-tokens/stablecoins/precautions.md)
### Partial Payments
Before integrating, exchanges should be aware of the [partial payments](../../concepts/payment-types/partial-payments.md) feature. This feature allows XRP Ledger users to send successful payments that reduce the amount received instead of increasing the `SendMax`. This feature can be useful for [returning payments](../../concepts/payment-types/bouncing-payments.md) without incurring additional cost as the sender.
#### Partial Payments Warning
When the [`tfPartialPayment` flag](../../references/protocol/transactions/types/payment.md#payment-flags) is enabled, the `Amount` field **_is not guaranteed to be the amount received_**. The `delivered_amount` field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use `delivered_amount` instead of the Amount field to determine how much your account received instead.
**Warning:** Be aware that malicious actors could exploit this. For more information, see [Partial Payments](../../concepts/payment-types/partial-payments.md).
### Accounts
XRP is held in _accounts_ (also referred to as _wallets_ or _addresses_ ) on the XRP Ledger. Accounts on the XRP Ledger are different than accounts on other blockchain ledgers, such as Bitcoin, where accounts incur little to no overhead. In the XRP Ledger, account state is stored per ledger and accounts are [not easy to delete](../../concepts/accounts/deleting-accounts.md). To offset the costs associated with storing accounts, each account must hold a separate [reserve of XRP](../../concepts/accounts/reserves.md) that cannot be sent to others. For these reasons, Ripple recommends that institutions not create excessive or needless accounts. <!-- STYLE_OVERRIDE: hot wallet, warm wallet, cold wallet, wallet, easy -->
To follow Ripple's recommended best practices, Alpha Exchange should create at least two new accounts on the XRP Ledger. To minimize the risks associated with a compromised secret key, Ripple recommends creating [_cold_, _hot_, and _warm_ accounts](../../concepts/accounts/account-types.md) (these are sometimes referred to, respectively, as cold, hot, and warm wallets). The hot/warm/cold model is intended to balance security and convenience. Exchanges listing XRP should create the following accounts:
* A [_cold wallet_](../../concepts/accounts/account-types.md#issuing-address) to securely hold the majority of XRP and customers' funds. For exchanges, this is also the address to which its users send [deposits](#deposit-xrp-into-exchange). To provide optimal security, this account's secret key should be offline.
If a malicious actor compromises an exchange's cold wallet, the possible consequences are:
* The malicious actor gets full access to all XRP in the cold wallet.
* If the master key is compromised, the malicious actor can irrevocably take control of the cold wallet forever (by disabling the master key and setting a new regular key or signer list). This would also give the malicious actor control over all future XRP received by the cold wallet.
* If this happens, the exchange has to make a new cold wallet address and tell its customers the new address.
* If the regular key or signer list are compromised, the exchange can regain control of the cold wallet. However, some of a malicious actor's actions cannot easily be undone: <!-- STYLE_OVERRIDE: easily -->
* The malicious actor could issue tokens in the XRP Ledger by using the cold wallet, but those tokens should not be valued by anyone (unless the exchange is also a token issuer).
* If a malicious actor enables the [Authorized Trust Lines](../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) setting for the account, that cannot be unset, although this only relates to issuing tokens and should not affect an exchange that is not also an issuer. Any other settings a malicious actor changes with a master key can be reverted.
* One or more [_hot wallets_](../../concepts/accounts/account-types.md#operational-addresses) to conduct the day-to-day business of managing customers' XRP withdrawals and deposits. For example, with a hot wallet, exchanges can securely support these types of automated XRP transfers. Hot wallets need to be online to service instant withdrawal requests.
For more information about the possible consequences of a compromised hot wallet, see [Operational Account Compromise](../../concepts/accounts/account-types.md#operational-address-compromise).
* Optionally, one or more warm wallets to provide an additional layer of security between the cold and hot wallets. Unlike a hot wallet, the secret key of a warm wallet does not need to be online. Additionally, you can distribute the secret keys for the warm wallet to several different people and implement [multi-signing](../../concepts/accounts/multi-signing.md) to increase security.
For more information about the possible consequences of a compromised warm wallet, see [Standby Account Compromise](../../concepts/accounts/account-types.md#standby-address-compromise).
See also:
* [Issuing and Operational Addresses](../../concepts/accounts/account-types.md)
* [Creating Accounts](../../concepts/accounts/accounts.md#creating-accounts)
* [Reserves](../../concepts/accounts/reserves.md)
### Balance Sheets
To custody its customers' XRP, Alpha Exchange must track each customer's XRP balance and its own holdings. To do this, Alpha Exchange must create and maintain an additional balance sheet or accounting system. The following table illustrates what this balance sheet might look like.
The new XRP Ledger accounts (_Alpha Hot_, _Alpha Warm_, _Alpha Cold_) are in the *User* column of the *XRP Balances on XRP Ledger* table.
The *Alpha Exchange XRP Balances* table represents new, additional balance sheet. Alpha Exchange’s software manages their users’ balances of XRP on this accounting system.
<table>
<tr>
<td><b><i>XRP Balances
on XRP Ledger</i></b></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchange
XRP Balances</i></b></td>
<td></td>
<td></td>
</tr>
<tr>
<td><b>User</b></td>
<td><b>Balance</b></td>
<td></td>
<td><b>Account #</b></td>
<td><b>User</b></td>
<td><b>Balance</b></td>
</tr>
<tr>
<td>Dave</td>
<td>25,000</td>
<td></td>
<td>123</td>
<td>Alice</td>
<td>0</td>
</tr>
<tr>
<td>Edward</td>
<td>45,000</td>
<td></td>
<td>456</td>
<td>Bob</td>
<td>0</td>
</tr>
<tr>
<td>Charlie</td>
<td>50,000</td>
<td></td>
<td>789</td>
<td>Charlie</td>
<td>0</td>
</tr>
<tr>
<td><i>Alpha Hot</i></td>
<td>0</td>
<td></td>
<td>...</td>
<td></td>
<td></td>
</tr>
<tr>
<td><i>Alpha Warm</i></td>
<td>0</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td><i>Alpha Cold</i></td>
<td>0</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>...</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
</table>
#### XRP Amounts
Amounts of XRP are represented on the XRP Ledger as an unsigned integer count of _drops_, where one XRP is 1,000,000 drops. Ripple recommends that software store XRP balances as integer amounts of drops, and perform integer arithmetic on these values. However, user interfaces should present balances in units of XRP.
One drop (.000001 XRP) cannot be further subdivided. Keep this in mind when calculating and displaying FX rates between XRP and other assets.
For more information, see [Specifying Currency Amounts][].
#### On-Ledger and Off-Ledger
With exchanges like _Alpha Exchange_, XRP can be "on-ledger" or "off-ledger":
* **On-Ledger XRP**: XRP that can be queried through the public XRP Ledger by specifying the public [address](../../concepts/accounts/addresses.md) of the XRP holder. The counterparty to these balances is the XRP Ledger. For more information, see [XRP](../../introduction/what-is-xrp.md).
* **Off-Ledger XRP**: XRP that is held by the accounting system of an exchange and can be queried through the exchange interface. Off-ledger XRP balances are credit-based. The counterparty is the exchange holding the XRP.
Off-ledger XRP balances are traded between the participants of an exchange. To support these trades, the exchange must hold a balance of _on-ledger XRP_ equal to the aggregate amount of _off-ledger XRP_ that it makes available for trade.
## Flow of Funds
The remaining sections describe how funds flow through the accounts managed by Alpha Exchange as its users begin to deposit, trade, and redeem XRP balances. To illustrate the flow of funds, this document uses the tables introduced in the ["Balance Sheets" section](#balance-sheets).
There are four main steps involved in an exchange's typical flow of funds:
1. [Deposit XRP into Exchange](#deposit-xrp-into-exchange)
2. [Rebalance XRP Holdings](#rebalance-xrp-holdings)
3. [Withdraw XRP from Exchange](#withdraw-xrp-from-exchange)
4. [Trade XRP on the Exchange](#trade-xrp-on-the-exchange)
This list does not include the [prerequisites](#prerequisites-for-supporting-xrp) required of an exchange.
At this point, _Alpha Exchange_ has created [hot, warm, and cold wallets](#accounts) on the XRP Ledger and added them to its balance sheet, but has not accepted any deposits from its users.
<table>
<tr>
<td><b><i>XRP Balances
on XRP Ledger</i></b></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchange
XRP Balances</i></b></td>
<td></td>
<td></td>
</tr>
<tr>
<td><b>User</b></td>
<td><b>Balance</b></td>
<td></td>
<td><b>Account #</b></td>
<td><b>User</b></td>
<td><b>Balance</b></td>
</tr>
<tr>
<td>Dave</td>
<td>25,000</td>
<td></td>
<td>123</td>
<td>Alice</td>
<td>0</td>
</tr>
<tr>
<td>Edward</td>
<td>45,000</td>
<td></td>
<td>456</td>
<td>Bob</td>
<td>0</td>
</tr>
<tr>
<td>Charlie</td>
<td>50,000</td>
<td></td>
<td>789</td>
<td>Charlie</td>
<td>0</td>
</tr>
<tr>
<td><i>Alpha Hot</i></td>
<td>0</td>
<td></td>
<td>...</td>
<td></td>
<td></td>
</tr>
<tr>
<td><i>Alpha Warm</i></td>
<td>0</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td><i>Alpha Cold</i></td>
<td>0</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>...</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
</table>
### Deposit XRP into Exchange
To track [off-ledger XRP balances](#on-ledger-and-off-ledger), exchanges need to create new [balance sheets](#balance-sheets) (or similar accounting systems). The following table illustrates the balance changes that take place on Alpha Exchange's new balance sheet as users begin to deposit XRP.
A user named Charlie wants to deposit 50,000 XRP to Alpha Exchange. Doing this involves the following steps:
1. Charlie submits a payment of 50,000 XRP to Alpha Exchange's [cold wallet](#accounts).
a. Charlie adds an identifier (in this case, `789`) to the payment to associate it with his account at Alpha Exchange. This is called a [_destination tag_](../../concepts/transactions/source-and-destination-tags.md). (To use this, Alpha Exchange should have set the `asfRequireDest` flag on all of its accounts to require all incoming payments to have a destination tag like Charlie's. For more information, see [AccountSet Flags](../../references/protocol/transactions/types/accountset.md#accountset-flags)).
2. The software at Alpha Exchange detects the incoming payment, and recognizes `789` as the destination tag for Charlie’s account.
3. When it detects the incoming payment, Alpha Exchange's software updates its balance sheet to indicate that the 50,000 XRP it received is controlled by Charlie.
Charlie can now use up to 50,000 XRP on the exchange. For example, he can create offers to trade XRP with BTC or any of the other currencies Alpha Exchange supports.
<table>
<tr>
<td><b><i>XRP Balances
on XRP Ledger</i></b></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchange
XRP Balances</i></b></td>
<td></td>
<td></td>
</tr>
<tr>
<td><b>User</b></td>
<td><b>Balance</b></td>
<td></td>
<td><b>Account #</b></td>
<td><b>User</b></td>
<td><b>Balance</b></td>
</tr>
<tr>
<td>Dave</td>
<td>25,000</td>
<td></td>
<td>123</td>
<td>Alice</td>
<td>0</td>
</tr>
<tr>
<td>Edward</td>
<td>45,000</td>
<td></td>
<td>456</td>
<td>Bob</td>
<td>0</td>
</tr>
<tr>
<td>Charlie</td>
<td><s>100,000</s>
<br>50,000</td>
<td></td>
<td>789</td>
<td>Charlie</td>
<td><s>0</s>
<br>50,000</td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Alpha Hot</td>
<td>0</td>
<td></td>
<td>...</td>
<td></td>
<td></td>
</tr>
<tr>
<td>Alpha Warm</td>
<td>0</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Alpha Cold</td>
<td><s>0</s>
<br>50,000</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>...</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
</table>
### Trade XRP on the Exchange
Alpha Exchange users (like Charlie) can trade credit-based balances on Alpha Exchange. Alpha Exchange should keep track of user balances on its new balance sheet as these trades are made. These trades are _off-ledger_ and independent from the XRP Ledger, so the balance changes are not recorded on the XRP Ledger.
Customers who hold XRP in their own XRP Ledger accounts can also use the distributed exchange built into the XRP Ledger to trade currencies issued by gateways. For more information about trading _on_ the XRP Ledger, see [Lifecycle of an Offer](../../concepts/tokens/decentralized-exchange/offers.md#lifecycle-of-an-offer).
### Rebalance XRP Holdings
Exchanges can adjust the balances between their hot and cold wallets at any time. Each balance adjustment consumes a [transaction cost](../../concepts/transactions/transaction-cost.md), but does not otherwise affect the aggregate balance of all the accounts. The aggregate, on-ledger balance should always exceed the total balance available for trade on the exchange. (The excess should be enough to cover the XRP Ledger's transaction costs.)
The following table demonstrates a balance adjustment of 80,000 XRP (via a [Payment transaction][] on the XRP Ledger) between Alpha Exchange's cold wallet and its hot wallet, where the cold wallet was debited and the hot wallet was credited. If the payment were reversed (debiting the hot wallet and crediting the cold wallet), the hot wallet balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XRP in online hot wallets.
<table>
<tr>
<td><b><i>Alpha Exchange XRP
Off-Ledger Balances</i></b></td>
<td></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchange XRP On-Ledger Balances</i></b></td>
<td></td>
</tr>
<tr>
<td><b>Account #</b></td>
<td><b>User</b></td>
<td><b>Balance</b></td>
<td></td>
<td><b>XRP Ledger Account</b></td>
<td><b>Balance</b></td>
</tr>
<tr>
<td>123</td>
<td>Alice</td>
<td>80,000</td>
<td></td>
<td>Hot</td>
<td><s>0</s>
<br>80,000</td>
</tr>
<tr>
<td>456</td>
<td>Bob</td>
<td>50,000</td>
<td></td>
<td>Warm</td>
<td>0</td>
</tr>
<tr>
<td>….</td>
<td></td>
<td></td>
<td></td>
<td>….</td>
<td></td>
</tr>
<tr>
<td>789</td>
<td>Charlie</td>
<td>50,000</td>
<td></td>
<td>Cold</td>
<td><s>180,000</s>
<br>100,000</td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>...</td>
<td></td>
<td></td>
<td></td>
<td>...</td>
<td></td>
</tr>
</table>
### Withdraw XRP from Exchange
Withdrawals allow an exchange's users to move XRP from the exchange's off-ledger balance sheet to an account on the XRP Ledger.
In this example, Charlie withdraws 25,000 XRP from Alpha Exchange. This involves the following steps:
1. Charlie initiates the process on Alpha Exchange’s website. He provides instructions to transfer 25,000 XRP to a specific account on the XRP Ledger (named "Charlie XRP Ledger" in the following table).
2. In response to Charlie’s instructions, Alpha Exchange does the following:
a. Debits the amount (25,000 XRP) from Charlie’s account on its off-ledger balance sheet
b. Submits a payment on the XRP Ledger for the same amount (25,000 XRP), from Alpha Exchange's hot wallet to Charlie’s XRP Ledger account
<table>
<tr>
<td><b><i>XRP Ledger On-Ledger XRP Balances</td>
<td></td>
<td></td>
<td><b><i>Alpha Exchange XRP
Off-Ledger Balances</td>
<td></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchange XRP On-Ledger Balances</td>
<td></td>
</tr>
<tr>
<td><b>User</td>
<td><b>Balance</td>
<td></td>
<td><b>Account #</td>
<td><b>User</td>
<td><b>Balance</td>
<td></td>
<td><b>XRP Ledger Account</td>
<td><b>Balance</td>
</tr>
<tr>
<td>Dave</td>
<td>25,000</td>
<td></td>
<td>123</td>
<td>Alice</td>
<td>80,000</td>
<td></td>
<td>Hot</td>
<td><s>80,000</s>
<br>55,000</td>
</tr>
<tr>
<td>Edward</td>
<td>45,000</td>
<td></td>
<td>456</td>
<td>Bob</td>
<td>50,000</td>
<td></td>
<td>Warm</td>
<td>0</td>
</tr>
<tr>
<td>….</td>
<td></td>
<td></td>
<td>….</td>
<td></td>
<td></td>
<td></td>
<td>….</td>
<td></td>
</tr>
<tr>
<td>Charlie XRP Ledger</td>
<td><s>50,000</s>
<br>75,000</td>
<td></td>
<td>789</td>
<td>Charlie</td>
<td><s>50,000</s>
<br>25,000</td>
<td></td>
<td>Cold</td>
<td>100,000</td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>...</td>
<td></td>
<td></td>
<td>...</td>
<td></td>
<td></td>
<td></td>
<td>...</td>
<td></td>
</tr>
</table>
## See Also
- **Concepts:**
- [Accounts](../../concepts/accounts/accounts.md)
- [Direct XRP Payments](../../concepts/payment-types/direct-xrp-payments.md)
- [Partial Payments](../../concepts/payment-types/partial-payments.md)
- [Source and Destination Tags](../../concepts/transactions/source-and-destination-tags.md)
- **Tutorials:**
- [Install `rippled`](../../infrastructure/installation/index.md)
- [Send XRP](../../tutorials/get-started/send-xrp.md)
- [Set Up Secure Signing](../../concepts/transactions/secure-signing.md)
- [Monitor Incoming Payments with WebSocket](../../tutorials/get-started/monitor-incoming-payments-with-websocket.md)
- **References:**
- [Payment transaction][]
- [account_info method][]
- [AccountRoot object](../../references/protocol/ledger-data/ledger-entry-types/accountroot.md)
{% raw-partial file="/_snippets/common-links.md" /%}

15
docs/use-cases/index.md Normal file
View File

@@ -0,0 +1,15 @@
---
html: use-cases.html
parent: docs.html
top_nav_grouping: Article Types
metadata:
indexPage: true
seo:
description: Browse the documentation based on practical use cases.
---
# Use Cases
Browse the documentation based on practical use cases.
{% child-pages /%}

15
docs/use-cases/payments/index.md Normal file
View File

@@ -0,0 +1,15 @@
---
html: payments-uc.html
parent: use-cases.html
top_nav_grouping: Article Types
metadata:
indexPage: true
seo:
description: Practical examples for using different types of payment on the XRP Ledger.
---
# Payments
Practical examples for using different types of payment on the XRP Ledger.
{% child-pages /%}

54
docs/use-cases/payments/peer-to-peer-payments-uc.md Normal file
View File

@@ -0,0 +1,54 @@
---
html: peer-to-peer-payments-uc.html
parent: payments-uc.html
seo:
description: Use the XRP Ledger to handle your day-to-day payments without a third party.
labels:
- Transactions
---
# Peer-to-Peer Payments
The XRP Ledger provides an efficient and borderless solution to handling payments. Unlike traditional payment methods, you don't need a financial institution to hold your assets and transfer value. If you have access to the internet, you can make direct payments on the XRP Ledger as easily as handing someone cash. Whether between friends, or a buyer and merchant, the XRP Ledger enables you to handle direct (peer-to-peer) payments quickly and with low network fees.
## Wallets
Before jumping into using the XRP Ledger to handle direct payments, you should settle on a crypto wallet to use. Crypto wallets make it easier to interact with the ledger and manage your funds; there are many to choose from, depending on your needs, and you can even create your own. See: [Crypto Wallets](../../introduction/crypto-wallets.md).
## Account Creation
Before creating an account, you must decide which XRP Ledger network to use. There are multiple networks for different use cases, but native XRP transactions only happen on `Mainnet`. See: [Parallel Networks](../../concepts/networks-and-servers/parallel-networks.md)
Most publicly available wallets offer the ability to create an account for you and can generate a public and private key. If they don't, you can create an account yourself, so long as it's mathematically valid. See: [Creating Accounts](../../concepts/accounts/accounts.md#creating-accounts).
## Fund Your Account
An account isn't active on the XRP Ledger until it's been funded and meets the minimum reserve requiremen. See: [Reserves](../../concepts/accounts/reserves.md).
If the wallet you're using doesn't offer the option to purchase XRP, you'll need to find a third party exchange to do so and send it to your account. Alternatively, someone you know can also send XRP to your account. See: [Payment](../../references/protocol/transactions/types/payment.md).
After funding your account, you should verify on the XRP Ledger itself that your account exists and is funded. You can do this with the:
- [XRPL Explorer](https://livenet.xrpl.org/).
- [`account_info` command](../../references/http-websocket-apis/public-api-methods/account-methods/account_info.md).
## Handling Payments
### Direct XRP Payments
XRP payments are the simplest way to pay someone on the XRP Ledger. You can use checks or escrows, but these require multiple transactions to complete. A direct XRP payment require only one transaction, making this option great for day-to-day activity. If you're a merchant handling large volumes of transactions, this may be the right choice for you due to it being quick, simple, and having the lowest fees. See: [Direct XRP Payments](../../concepts/payment-types/direct-xrp-payments.md).
To make a direct XRP payment work, you only need to know the address of the receiver.
### Cross-Currency Payments
The XRP Ledger enables you to make cross-currency payments of XRP and tokens. Cross-currency payments within the XRP Ledger are fully atomic, meaning the payment fully executes or no part of the payment executes at all.
Cross-currency payments deliver a fixed amount to their destination, but the sender can have a variable fee cost, depending on the paths taken to make the transaction work on the network. See: [Cross-currency Payments](../../concepts/payment-types/cross-currency-payments.md).
This is a great payment option if you or the receiver prefer a specific token instead of the native XRP currency.

71
docs/use-cases/payments/restricting-deposits-uc.md Normal file
View File

@@ -0,0 +1,71 @@
---
html: restricting-deposits-uc.html
parent: payments-uc.html
seo:
description: Checks enable users to create deferred payments similar to personal paper checks.
labels:
- Transactions
---
# Restricting Deposits
To comply with banking regulations, financial institutions must provide documentation about the sources of funds they receive. These regulations seek to prevent illicit activity by requiring institutions to track the source and destination of all payments they process. On the XRP Ledger, payments can be sent and received without any interaction from the receiver. This default behavior can be problematic, but you can enable deposit authorization so you only receive funds you explicitly approve.
Accounts with deposit authorization enabled can only receive funds through:
- Preauthorized Accounts
- Checks
- Escrow
<!-- - Payment Channels -->
## Set Up Deposit Authorization
To enable deposit authorization, use the `AccountSet` transaction to set the `asfDepositAuth` flag. See: [Deposit Authorization](../../concepts/accounts/depositauth.md).
## Preauthorized Accounts
When you enable deposit authorization, your account blocks all incoming transactions unless you specifically _okay_ them. This may be what you're looking for, but it can be cumbersome if you're working with high volumes of transactions. If you have trusted vendors or accounts, you can preauthorize them so that you don't have to approve transactions from them.
Preauthorized accounts are currency-agnostic, meaning you can't specify which currencies to authorize. It's all or nothing.
See: [DepositPreauth](../../references/protocol/transactions/types/depositpreauth.md).
## Accepting Deposits from Unauthorized Accounts
You can still work with unauthorized accounts, even after enabling deposit authorization. There are several payment methods that enable you to do so.
### Checks
Checks are a straightforward, familiar, and flexible way to transfer funds when deposit authorization is enabled. Checks are a two-part payment method. The sender creates the check, and then the receiver has to cash the check. Cashing the check is your explicit approval of the deposit.
While this method is the simplest, it doesn't guarantee the funds. Checks are deferred payments, meaning funds aren't moved until the moment you try to cash the check. It's possible for the sending account to not have the necessary funds at the time the check is cashed, which can cause delays or other headaches, depending on your business.
See: [Use Checks](../../tutorials/use-specialized-payment-types/use-checks/use-checks.md).
### Escrow
If you require a guarantee of funds at the time of deposit, another option is to have deposits made with an escrow. Like regular escrows, a sender sets aside funds on the ledger, effectively locking them up until certain conditions are met. This guarantees the funds will be available when you close the escrow to release the funds.
See: [Use Escrows](../../tutorials/tasks/use-specialized-payment-types/use-escrows/index.md).
<!-- Need a better understanding of Payment Channels use cases.
### Payment Channels
Payment Channels are an advanced feature for sending asynchronous XRP payments that can be divided into very small increments and settled later.
The XRP for a payment channel is set aside temporarily. The sender creates _Claims_ against the channel, which the recipient verifies without sending an XRP Ledger transaction or waiting for a new ledger version to be approved by consensus. (This is an _asynchronous_ process because it happens separate from the usual pattern of getting transactions approved by consensus.) At any time, the recipient can _redeem_ a Claim to receive an amount of XRP authorized by that Claim. Settling a Claim like this uses a standard XRP Ledger transaction, as part of the usual consensus process. This single transaction can encompass any number of transactions guaranteed by smaller Claims.
Because Claims can be verified individually but settled in bulk later, payment channels make it possible to conduct transactions at a rate only limited by the participants' ability to create and verify the digital signatures of those Claims. This limit is primarily based on the speed of the participants' hardware and the complexity of the signature algorithms. For maximum speed, use Ed25519 signatures, which are faster than the XRP Ledger's default secp256k1 ECDSA signatures. Research has demonstrated the ability to create over Ed25519 100,000 signatures per second and to verify over [70,000 per second](https://ed25519.cr.yp.to/ed25519-20110926.pdf) on commodity hardware in 2011.
Learn about [Payment Channels](payment-channels.html) on the XRP Ledger.
you may have circumstances where you want to go into contract with a contractor, but don't know the exact amount. This is common in situations such as home improvement projects where an estimate can be provided, but unforeseen circumstances can increase the final amount due. In these situations you can create a payment channel, which allocates (currently only XRP) to a payment channel. This amount would be the estimate the contractor gives you and can serve as their budget for the project. Each item they require payment for, you would submit a claim to the payment channel.
Repeating this process, you would eventually settle on the final amount due, where the contractor (payee) claims the final amount from the payment channel. This method of payment serves as a great way to track invdividual items payed for in large projects.
-->

49
docs/use-cases/payments/smart-contracts-uc.md Normal file
View File

@@ -0,0 +1,49 @@
---
html: escrow-uc.html
parent: payments-uc.html
seo:
description: Transactions allow accounts to modify the XRP Ledger.
labels:
- Ledgers
---
# Smart Contracts
A smart contract is a blockchain-based program that handles the conditions and executes the fulfillment of an agreement between two parties. Broken into its simplest components, a smart contract _does_ something if _something else_ happens.
The benefit of encoding a smart contract into a blockchain is that it enables contracts to be securely carried out without traditional third-parties, like financial or legal institutions. Instead, the contract is supervised by the distributed, decentralized network of computers that run the blockchain.
This enables you to transact with anybody without having to trust they'll uphold their end of a deal; the conditions of the smart contract will force them to.
## Conditionally Held Escrow
Smart contracts on the XRP Ledger work through conditionally held escrows.
### Create the Escrow
A conditionally held escrow is similar to a normal escrow: you set aside funds with an escrow to guarantee funds are available to a recipient. The difference is that a conditionally held escrow on the ledger has a `Condition` attached to it, which serves as a lock on the funds. The ledger won't release those funds until an `EscrowFinish` transaction is submitted with the corresponding `Fulfillment` field. The `Condition` and `Fulfillment` fields can be viewed as a lock and key on an escrow.
See: [`EscrowCreate`](../../references/protocol/transactions/types/escrowcreate.md).
### Establish the Oracle
An oracle is a neutral third-party agent that can verify real-world events to either fulfill or invalidate a smart contract. Oracles are vital to making conditional escrows work by generating the condition and fulfillment, and keeping the fulfillment secret until the terms of the contract are met.
In the context of smart contracts, an oracle will most likely be software that can read real-world data. The oracle would be programmed with the terms of the contract between parties and generate the condition and fulfillment hex values.
The oracle gives the condition hex value to the escrow creator, enabling them to set up the escrow initially.
After the oracle's programming detects the conditions are met, it gives the fulfillment hex value to the escrow recipient. It does nothing else after this point, such as finishing the escrow. The recipient of the escrow would most likely finish the escrow.
See: [Generate a condition and fulfillment](../../tutorials/use-specialized-payment-types/use-escrows/send-a-conditionally-held-escrow.md#1-generate-condition-and-fulfillment).
## Examples
Smart contracts have a wide range of uses, but some uses include:
1. Handling payments on large-value items you would otherwise need lawyers for, such as mortgages.
2. Supply-chain management to ensure funds are delivered upon receipt of goods.
3. Automating certain kinds of insurance claims that can be verified by software.
4. Ensuring payments are given for services rendered.

114
docs/use-cases/tokenization/authorized-minter.md Normal file
View File

@@ -0,0 +1,114 @@
---
html: authorized-minter.html
parent: nft-mkt-overview.html
seo:
description: Minting and selling NFTs for another account.
labels:
- Tokenization
---
# Authorized Minter
_As an authorized minter, I want to mint tokens for a token issuer at an agreed upon rate and sell the tokens at a profit, with royalties returning to the issuer._
You can act as an authorized minter for token issuers. When you do this, you own the NFToken, but royalties flow to the NFToken issuer. When you make a sale of that NFToken, the proceeds of the initial sale go to you. You can have an agreement with your issuer to pay them some or all of your portion of the initial sale amount.
You can learn more in the tutorial [Assign an Authorized Minter](../../tutorials/quickstart/assign-an-authorized-minter-using-javascript.md).
[![Authorized Minter Flow](/img/nft-mkt-auth-minter.png "Authorized Minter Flow")](/img/nft-mkt-auth-minter.png)
## Set up a rippled instance
If you want to set up a larger site with high volume, it might be worth investing in your own XRP Ledger server instance. See [Install rippled](../../infrastructure/installation/index.md).
## Set up your marketplace
Rather than designing NFTs yourself, you coordinate with an NFT creator to become an authorized minter and generate NFTs on their behalf. This allows the creator to focus on making new NFTs while you handle production and sales of the NFTs. See [Authorized Minter](../../concepts/tokens/nfts/authorizing-another-minter.md).
Once you finish creating NFTs, the creator can revoke your privileges and reassert control over the NFTs. You might also transfer the tokens to a marketplace that will handle sales of the NFTs. You can act as a broker to match sell offers to buy offers. See [Running an NFT auction](../../concepts/tokens/nfts/running-an-nft-auction.md).
![Auctioning NFTs](/img/uc-nft-transferring-nfts.png)
To mint your first NFTs on behalf of another account, see [Authorizing Another Account to Mint Your NFTs](../../tutorials/quickstart/assign-an-authorized-minter-using-javascript.md).
If you, as the owner or issuer, want to be able to burn the token in the future, set the `Flags` field to _1._ To make the NFT transferable, set the `Flags` field to _8_. Set the `Flags` field to _9_ to make the NFT both burnable and transferable. See[ Burnable flag](../../references/protocol/data-types/nftoken.md#nftoken-flags) and [Transferable flag](../../references/protocol/data-types/nftoken.md#nftoken-flags).
![Burning NFTs](/img/uc-nft-burn.png)
You can arrange for the creator to receive royalties from future sales by setting a <code>transfer fee<em>. </em></code>This is a value from 0-50000 representing 0-50% of the sale price. See [Transfer Fee](../../references/protocol/data-types/nftoken.md#transferfee).
The NFToken URL is a link to the location where the content of the NFT is stored. One option is create an IPFS account and store the NFToken content at a persistent URL. See [Best Practices for Storing NFT Data](https://docs.ipfs.io/how-to/best-practices-for-nft-data).
Considerations that might be most interesting to you:
* [Minting NFTs into Collections](../../concepts/tokens/nfts/collections.md)
Use the TokenTaxon field to gather a set of NFTs centered around a specific theme or purpose.
* [Guaranteeing a Fixed Supply of NFTs](../../concepts/tokens/nfts/guaranteeing-a-fixed-supply.md)
You can assure scarcity of NFTs you create by creating them with what might be characterized as a “burner” account that you use to mint a set number of NFTs for another account, then delete the account you used to mint the NFTs. See [Guaranteeing a Fixed Supply of NFTs](../../concepts/tokens/nfts/guaranteeing-a-fixed-supply.md).
## Transferring NFTs
You transfer NFTs by creating a sell offer or accepting a buy offer. See [Transfer NFTokens](../../tutorials/quickstart/transfer-nfts-using-javascript.md).
You can sell your NFTs in an auction format. See [Running an NFT Auction](../../concepts/tokens/nfts/running-an-nft-auction.md).
You can act as a broker, connecting sellers with bidders, completing the transfer and keeping a percentage of the purchase price. See [Broker a NFToken sale](../../tutorials/quickstart/broker-an-nft-sale-using-javascript.md).
### Reserve requirements
There are several XRP reserve requirements when you mint NFTs for sale. Each NFToken page requires a reserve of 2 XRP. A NFToken page can store 16-32 NFTs.
![Reserves](/img/uc-nft-reserves.png)
Each `NFTokenOffer` object requires a reserve of 2 XRP.
When you post the `NFTokenOffer` or sell the NFT, there are trivial transfer fees (roughly 6000 drops, or .006 XRP). When you are selling at a high volume, the trivial amounts can add up quickly, and need to be considered as part of your cost of doing business.
See:
1. [NFTokenOffer](../../concepts/tokens/nfts/reserve-requirements.md#nftokenoffer-reserve)
2. NFToken page ([Owner reserve](../../concepts/tokens/nfts/reserve-requirements.md#owner-reserve))
3. Trivial [transfer fees](../../concepts/tokens/transfer-fees.md)
### Checkout
The most straightforward payment for XRPL NFTs is XRP. For examples of selling and buying NFTs using XRP, see [Transfer NFTokens](../../tutorials/quickstart/transfer-nfts-using-javascript.md).
![Checkout](/img/uc-nft-checkout.png)
For trade in other currencies, you can leverage the DEX to accept and convert issued currencies of all kinds. See [Trade in the Decentralized Exchange](../../tutorials/use-tokens/trade-in-the-decentralized-exchange.md#trade-in-the-decentralized-exchange).
## Indexing NFTs
When listing NFTs for sale, it can be useful to use object metadata to organize them. You can use queries in the XRPL libraries, the Clio server, and extensions in the XRPL API and Bithomp libraries to sort and filter NFTs by creator, price, collection, rarity, and more.
![Indexing NFTs](/img/uc-nft-indexing.png)
See:
- [Clio setup](../../infrastructure/installation/install-clio-on-ubuntu.md)
- [XRPL Data API](https://api.xrpldata.com/docs/static/index.html#/)
- [Bithomp](https://docs.bithomp.com/#nft-xls-20)
<!--
[Clio setup](../../infrastructure/installation/install-clio-on-ubuntu.md)
[https://api.xrpldata.com/docs/static/index.html#/](https://api.xrpldata.com/docs/static/index.html#/)
[https://docs.bithomp.com/#nft-xls-20](https://docs.bithomp.com/#nft-xls-20)
Sorting and filtering [No link]
Creator - nft_info (issuer field)
Price - nft_sell_offer->offers->amount field)
Popularity - ?
Newly listed
Collection - nft_info (token taxon field)
XRP vs $ vs IOUs
Search [No link]
Featured NFTs [No link]
Supplement Information [No link]
Rarity
Floor price
History
Number of owners
Price History
-->

94
docs/use-cases/tokenization/digital-artist.md Normal file
View File

@@ -0,0 +1,94 @@
---
html: digital-artist.html
parent: nft-mkt-overview.html
seo:
description: Creating an NFT Marketplace for buying and selling NFTs.
labels:
- Tokenization
---
# Digital Artist
_As a Digital Artist, I want to use the XRPL to create a NFToken of my work and sell it on the XRPL, because the XRPL is both cost efficient and carbon neutral._
---
When you create a NFToken, you create a unique token on the XRPL that is effectively a placeholder for an actual physical or digital asset. When you create the NFToken, you provide a URL to a digital file that is the item itself, such as a digital artwork, or a URL to a placeholder that represents an item in the physical world.
As a digital artist, you’re focused on creating NFTs, presumably to sell on the XRP Ledger (it’s also possible you might create NFTs as a way of establishing provenance for your creations).
You can create NFTokens using an app such as the [Xumm app](https://xumm.app).
For a more hands-on experience, you can follow the steps in the [Quickstart Tutorial 3 - Mint and Burn NFTokens](../../tutorials/quickstart/mint-and-burn-nfts-using-javascript.md).
[![Digital Artist Flow](/img/nft-mkt-digital-artist.png "Digital Artist Flow")](/img/nft-mkt-digital-artist.png)
## Use a public server
As you get started, you will likely have comparatively few transactions. You can work with one of the free XRP Ledger public servers. As your business grows, you might consider your own NFT Ledger instance to handle increased sales traffic. See [Public servers](../../tutorials/get-started/public-servers.md).
## Create NFTs
Build your marketplace by minting NFTs to sell.
To create your first NFTs, follow the instructions in the tutorial _Mint and Burn NFTokens_. Keep the following in mind as you create your NFTs:
* You can collect royalties from future sales by setting a <code>transfer fee<em>. </em></code>This is a value from 0-50000 representing 0-50% of the sale price. See [Transfer Fee](../../references/protocol/data-types/nftoken.md#transferfee).
* The NFToken URL is a link to the location where the content of the NFT is stored. One option is create an IPFS account and store the NFToken content at a persistent URL. See [Best Practices for Storing NFT Data](https://docs.ipfs.io/how-to/best-practices-for-nft-data). [Add link to blog post about alternative NFT cache options.]
* You can mint NFTs in logical collections using the <code>TokenTaxon</code> field. See [Minting NFTs into Collections](../../concepts/tokens/nfts/collections.md).
* If you, as the issuer, want to be able to burn the token in the future, set the <code>Flags</code> field to <em>1.</em> To make the NFT transferable, set the <code>Flags</code> field to <em>8</em>. Set the <code>Flags</code> field to <em>9</em> to make the NFT both burnable and transferable. See[ Burnable flag](../../references/protocol/data-types/nftoken.md#nftoken-flags) and [Transferable flag](../../references/protocol/data-types/nftoken.md#nftoken-flags).
See [Mint and Burn NFTokens](../../tutorials/quickstart/mint-and-burn-nfts-using-javascript.md).
## Sell NFTs
You transfer NFTs by creating a sell offer. See [Transfer NFTokens](../../tutorials/quickstart/transfer-nfts-using-javascript.md).
![Transferring NFTs](/img/uc-nft-transferring-nfts.png)
You can sell your NFTs in an auction format. See [Running an NFT Auction](../../concepts/tokens/nfts/running-an-nft-auction.md).
### Reserve requirements
There are several XRP reserve requirements when you mint NFTs for sale. Each NFToken page requires a reserve of 2 XRP. A NFToken page can store 16-32 NFTs.
Each `NFTokenOffer` object requires a reserve of 2 XRP.
![Reserves](/img/uc-nft-reserves.png)
When you post the `NFTokenOffer` or sell the NFT, there are trivial transfer fees (roughly 6000 drops, or .006 XRP). When you are selling at a high volume, the trivial amounts can add up quickly, and need to be considered as part of your cost of doing business.
See:
1. [NFTokenOffer](../../concepts/tokens/nfts/reserve-requirements.md#nftokenoffer-reserve)
2. NFToken page ([Owner reserve](../../concepts/tokens/nfts/reserve-requirements.md#owner-reserve))
3. Trivial [transfer fees](../../concepts/tokens/transfer-fees.md)
### Checkout
The most straightforward payment for XRPL NFTs is XRP. For examples of selling and buying NFTs using XRP, see [Transfer NFTokens](../../tutorials/quickstart/transfer-nfts-using-javascript.md).
![Checkout](/img/uc-nft-checkout.png)
For trade in other currencies, you can leverage the DEX to accept and convert issued currencies of all kinds. See [Trade in the Decentralized Exchange](../../tutorials/use-tokens/trade-in-the-decentralized-exchange.md#trade-in-the-decentralized-exchange).
## Indexing NFTs
When listing NFTs for sale, it can be useful to use object metadata to organize them. You can use queries in the XRPL libraries, the Clio server, and extensions in the XRPL API and Bithomp libraries to sort and filter NFTs by creator, price, collection, rarity, and more.
![Indexing NFTs](/img/uc-nft-indexing.png)
See:
- [Clio setup](../../infrastructure/installation/install-clio-on-ubuntu.md)
- [XRPL Data API](https://api.xrpldata.com/docs/static/index.html#/)
- [Bithomp](https://docs.bithomp.com/#nft-xls-20)
## Burning NFTs
There are some workflows where it makes sense for the issuer to retain the right to burn the token at some point in the future, regardless of the current owner. For example, NFTs used for carbon credits can be minted and traded, but once the carbon is captured, the NFT can be burned so that it is no longer transferable. For these scenarios, set the `lsfBurnable` flag when you mint the NFT.
![Burning NFTs](/img/uc-nft-burn.png)
Another example might be burning an in-game asset that is lost by a player after losing a life in the game. You might also burn an NFT ticket after successful redemption to prevent it from being used again.

15
docs/use-cases/tokenization/index.md Normal file
View File

@@ -0,0 +1,15 @@
---
html: tokenization.html
parent: use-cases.html
top_nav_grouping: Article Types
metadata:
indexPage: true
seo:
description: Work with a variety of tokens supported by the XRP Ledger.
---
# Tokenization
Work with a variety of tokens supported by the XRP Ledger.
{% child-pages /%}

179
docs/use-cases/tokenization/nft-mkt-overview.md Normal file
View File

@@ -0,0 +1,179 @@
---
html: nft-mkt-overview.html
parent: tokenization.html
seo:
description: Overview of NFT Marketplace use cases.
labels:
- Tokenization
---
# NFT Marketplace Overview
## Key Features
XRPL native support for NFTs provides tools that let you do the following.
- Mint, sell, and burn NFTs
- Kick start an NFT project in little time at low expense
- Assign a broker to arrange transfers between sellers and bidders
- Authorize another account to mint NFTs for you
- Receive creator-friendly, on-ledger royalties that are honored by marketplaces
All this on top of the XRP Ledger’s greater than 10 years of performance and reliability.
## Understand Your Goals
Start by deciding what sort of marketplace you want to create.
- Marketplace, selling NFTs minted by others
- Authorized minter, minting NFTs for artists
- Digital artist, creating and selling your own NFTs
There are 4 essential areas of preparation for starting your NFT business.
1. Deciding how you will connect to the network
2. Setting up your blockchain behavior
3. Indexing required NFT information
4. Determining your permanent storage strategy to cache your NFTs
[![NFT Marketplace Flow](/img/nft-mkt-overview.png "NFT Marketplace Flow")](/img/nft-mkt-overview.png)
## Connect to XRPL
If you want to set up a smaller site with fewer transactions, you can work with one of the free XRP Ledger public servers. See [Public servers](../../tutorials/get-started/public-servers.md).
If you want to set up a larger site with high volume, it might be worth investing in your own XRP Ledger server instance. See [Install rippled](../../infrastructure/installation/index.md).
See also:
* [Pros and cons of running your own server](../../concepts/networks-and-servers/index.md#reasons-to-run-your-own-server).
## Set Up Basic Blockchain Functions
You can begin to build your marketplace by minting some NFTs to sell.
To create your first NFTs, follow the instructions in the tutorial _Mint and Burn NFTokens_. See [Mint and Burn NFTokens](../../tutorials/quickstart/mint-and-burn-nfts-using-javascript.md).
The NFToken URL is a link to the location where the content of the NFT is stored. One option is create an IPFS account and store the NFToken content at a persistent URL. See [Best Practices for Storing NFT Data](https://docs.ipfs.io/how-to/best-practices-for-nft-data).
If you, as the issuer, want to be able to burn the token in the future, set the `Flags` field to _1._ To make the NFT transferable, set the `Flags` field to _8_. Set the `Flags` field to _9_ to make the NFT both burnable and transferable. See [Burnable flag](../../references/protocol/data-types/nftoken.md) and [Transferable flag](../../references/protocol/data-types/nftoken.md).
![Burning a token](/img/uc-nft-burn.png)
You can collect royalties from future sales by setting a <code>transfer fee<em>. </em></code>This is a value from 0-50000 representing 0-50% of the sale price. See [Transfer Fee](../../references/protocol/data-types/nftoken.md#transferfee).
You can mint NFTs in logical collections using the `TokenTaxon` field. See [Minting NFTs into Collections](../../concepts/tokens/nfts/collections.md).
You can mint your own NFTs with content you create yourself, but you can also become an authorized minter to generate NFTs on behalf of another creator. This allows the creator to focus on making new NFTs while you handle production and sales of the NFTs.
Once the authorized minter has finished creating NFTs for you, you can revoke their privileges so that they no longer have any control over your NFTs.
See [Authorized Minter](../../concepts/tokens/nfts/authorizing-another-minter.md).
Minted NFTs are listed on a `NFTokenPage`. There is a reserve requirement of 2 XRP for every `NFTokenPage` on your account. See [NFT Reserve Requirements](../../concepts/tokens/nfts/reserve-requirements.md).
Each `NFTokenPage` holds 16-32 NFTs. Minting a large number of NFTs can tie up a great deal of your XRP. You can keep your XRP liquid by minting on demand (or _lazy minting_). For details of different approaches, see [Batch minting](../../concepts/tokens/nfts/batch-minting.md).
### Setting up a wallet
Set up a new wallet. See [Xumm](https://xumm.app/).
When you set up your account, keep in mind that there is a base reserve requirement of 10 XRP. See [Reserves](../../concepts/accounts/reserves.md#base-reserve-and-owner-reserve).
### Transferring NFTs
You transfer NFTs by creating a sell offer or accepting a buy offer. See [Transfer NFTokens](../../tutorials/quickstart/transfer-nfts-using-javascript.md).
![Transferring NFTs](/img/uc-nft-transferring-nfts.png)
You can sell your NFTs in an auction format. See [Running an NFT Auction](../../concepts/tokens/nfts/running-an-nft-auction.md).
You can act as a broker, connecting sellers with bidders, completing the transfer and keeping a percentage of the purchase price. See [Broker a NFToken sale](../../tutorials/quickstart/broker-an-nft-sale-using-javascript.md).
#### Reserve requirements
There are several XRP reserve requirements when you mint NFTs for sale. Each NFToken page requires a reserve of 2 XRP. A NFToken page can store 16-32 NFTs.
Each `NFTokenOffer` object requires a reserve of 2 XRP.
![Reserves](/img/uc-nft-reserves.png)
When you post the `NFTokenOffer` or sell the NFT, there are trivial transfer fees (roughly 6000 drops, or .006 XRP). When you are selling at a high volume, the trivial amounts can add up quickly, and need to be considered as part of your cost of doing business.
See:
1. [NFTokenOffer](../../concepts/tokens/nfts/reserve-requirements.md#nftokenoffer-reserve)
2. NFToken page ([Owner reserve](../../concepts/tokens/nfts/reserve-requirements.md#owner-reserve))
3. Trivial [transfer fees](../../concepts/tokens/transfer-fees.md)
#### Checkout
The most straightforward payment for XRPL NFTs is XRP. For examples of selling and buying NFTs using XRP, see [Transfer NFTokens](../../tutorials/quickstart/transfer-nfts-using-javascript.md).
![Checkout](/img/uc-nft-checkout.png)
For trade in other currencies, you can leverage the DEX to accept and convert issued currencies of all kinds. See [Trade in the Decentralized Exchange](../../tutorials/use-tokens/trade-in-the-decentralized-exchange.md#trade-in-the-decentralized-exchange).
<!--
- Fiat payment ([Cross-currency payments](cross-currency-payments.html))
- On-chain validation of completing transactions [No link- isn’t this just a cross-currency payment?] (Query after the transaction is completed.]
-->
## Indexing NFTs
When listing NFTs for sale, it can be useful to use object metadata to organize them.
![Indexing NFTs](/img/uc-nft-indexing.png)
You can use queries in the XRPL libraries, the Clio server, and extensions in the XRPL API and Bithomp libraries to sort and filter NFTs by creator, price, collection, rarity, and more.
See:
- [Clio setup](../../infrastructure/installation/install-clio-on-ubuntu.md)
- [XRPL Data API](https://api.xrpldata.com/docs/static/index.html#/)
- [Bithomp](https://docs.bithomp.com/#nft-xls-20)
<!--
Sorting and filtering [No link]
Creator - nft_info (issuer field)
Price - nft_sell_offer->offers->amount field)
Popularity - ?
Newly listed
Collection - nft_info (token taxon field)
XRP vs $ vs IOUs
Search [No link]
Featured NFTs [No link]
Supplement Information [No link]
Rarity
Floor price
History
Number of owners
Price History
-->
## NFT Caching
<!--
Image optimization for web experience [No link]
-->
NFTs that are created in the crypto space are expected to store metadata, including media, attributes, and so on. Currently most are stored on IPFS or Arweave to avoid centralization.
<!-- We can't use this example.
See [HERE](https://xrp.cafe/nft/00081770CCE71D9E7BD07E3A771C7619DA982D62CD37325A99B664A500000209)) -->
Although IPFS / Arweave are great solutions to promote decentralization, fetching the metadata efficiently is a problem. Reaching IPFS / Arweave directly to fetch metadata is not fast enough for modern websites that require immediate responses from users that are scrolling through multiple pages of NFTs with high-quality media. Many NFT marketplaces on XRPL today are storing cached versions of the IPFS originals to have fast and reliable responsive websites, but this process is expensive and inefficient.
Cloudflare, Infura, and many other providers are increasingly focusing on storing these decentralized files and retrieving them fast for users.
See [NFT Caching](../../references/protocol/data-types/nftoken.md#retrieving-nftoken-data-and-metadata).
<!--
You can also consider a solution such as Pinata. [https://drive.google.com/file/d/14wuulkvjVjtGlUJj0ppaJ4Sziyp5WFGA/view?usp=sharing](https://drive.google.com/file/d/14wuulkvjVjtGlUJj0ppaJ4Sziyp5WFGA/view?usp=sharing)
We can derive inspiration for the need of caching and point to some of their docs
[https://docs.pinata.cloud/gateways](https://docs.pinata.cloud/gateways)
-->

105
docs/use-cases/tokenization/nftoken-marketplace.md Normal file
View File

@@ -0,0 +1,105 @@
---
html: nftoken-marketplace.html
parent: nft-mkt-overview.html
seo:
description: Creating an NFT Marketplace for buying and selling NFTs.
labels:
- Tokenization
---
# NFT Marketplace
_In my NFToken Marketplace, I want to use the XRPL to create a web presence where I can arrange transfer of a curated selection of NFTokens to consumers, with the benefit that I can build a brand and earn broker fees based on sales._
---
NFToken Marketplaces act as intermediaries between NFToken creators and collectors. As a marketplace curator, you seek out NFToken creators and assemble a collection of items to sell. Buyers come to your site to review your selections and post offers. You match the minimum prices set by the creators with the optimal offers from the buyers, complete the transaction, and collect a broker fee.
## Creating an NFT Marketplace
[![NFT Marketplace Flow](/img/nft-mkt-marketplace.png "NFT Marketplace Flow")](/img/nft-mkt-marketplace.png)
## Set up a rippled instance
When you set up a serious marketplace site with high volume, it justifies the decision to set up your own XRP Ledger server instance. See [Install rippled](../../infrastructure/installation/index.md).
### Setting up a wallet
Set up a new wallet. See [Xumm](https://xumm.app/).
Base reserve requirements See [Reserves](../../concepts/accounts/reserves.md#base-reserve-and-owner-reserve).
### Transferring NFTs
You transfer NFTs by creating a sell offer or accepting a buy offer. See [Transfer NFTokens](../../tutorials/quickstart/transfer-nfts-using-javascript.md).
![Transferring NFTs](/img/uc-nft-transferring-nfts.png)
You can sell your NFTs in an auction format. See [Running an NFT Auction](../../concepts/tokens/nfts/running-an-nft-auction.md).
You can act as a broker, connecting sellers with bidders, completing the transfer and keeping a percentage of the purchase price. See [Broker a NFToken sale](../../tutorials/quickstart/broker-an-nft-sale-using-javascript.md).
### Reserve requirements
There are several XRP reserve requirements when you mint NFTs for sale. Each NFToken page requires a reserve of 2 XRP. A NFToken page can store 16-32 NFTs.
![Reserves](/img/uc-nft-reserves.png)
Each `NFTokenOffer` object requires a reserve of 2 XRP.
When you post the `NFTokenOffer` or sell the NFT, there are trivial transfer fees (roughly 6000 drops, or .006 XRP). When you are selling at a high volume, the trivial amounts can add up quickly, and need to be considered as part of your cost of doing business.
See:
1. [NFTokenOffer](../../concepts/tokens/nfts/reserve-requirements.md#nftokenoffer-reserve)
2. NFToken page ([Owner reserve](../../concepts/tokens/nfts/reserve-requirements.md#owner-reserve))
3. Trivial [transfer fees](../../concepts/tokens/transfer-fees.md)
You can learn more about brokered sales in the topic [Trading Tokens on the XRP Ledger](../../concepts/tokens/nfts/trading.md).
Learn more about token transfer fees in the topic [Transfer Fees](../../concepts/tokens/transfer-fees.md).
You can get started building a brokered sales marketplace by following the steps in the [Broker a NFToken Sale](../../tutorials/quickstart/broker-an-nft-sale-using-javascript.md).
### Checkout
The most straightforward payment for XRPL NFTs is XRP. For examples of selling and buying NFTs using XRP, see [Transfer NFTokens](../../tutorials/quickstart/transfer-nfts-using-javascript.md).
![Checkout](/img/uc-nft-checkout.png)
For trade in other currencies, you can leverage the DEX to accept and convert issued currencies of all kinds. See [Trade in the Decentralized Exchange](../../tutorials/use-tokens/trade-in-the-decentralized-exchange.md#trade-in-the-decentralized-exchange).
## Indexing NFTs
When listing NFTs for sale, it can be useful to use object metadata to organize them. You can use queries in the XRPL libraries, the Clio server, and extensions in the XRPL API and Bithomp libraries to sort and filter NFTs by creator, price, collection, rarity, and more.
![Indexing NFTs](/img/uc-nft-indexing.png)
See:
- [Clio setup](../../infrastructure/installation/install-clio-on-ubuntu.md)
- [XRPL Data API](https://api.xrpldata.com/docs/static/index.html#/)
- [Bithomp](https://docs.bithomp.com/#nft-xls-20)
<!--
Sorting and filtering [No link]
Creator - nft_info (issuer field)
Price - nft_sell_offer->offers->amount field)
Popularity - ?
Newly listed
Collection - nft_info (token taxon field)
XRP vs $ vs IOUs
Search [No link]
Featured NFTs [No link]
Supplement Information [No link]
Rarity
Floor price
History
Number of owners
Price History
-->

217
docs/use-cases/tokenization/stablecoin-issuer.md Normal file
View File

@@ -0,0 +1,217 @@
---
html: stablecoin-issuer.html
parent: tokenization.html
seo:
description: Issue your own stablecoin, based on assets of equal value outside of the XRP Ledger.
labels:
- Tokens
- Stablecoin
---
# Stablecoin Issuer
_As a financial professional, I want to issue a stablecoin so that I can earn revenue by charging fees for withdrawals or transfers of the stablecoin._
Stablecoins are tokens that are backed by assets outside of the XRPL. Stablecoins allow users to transact in familiar currencies, and provide a convenient way to get funds into and out of the XRPL blockchain.
The mechanics of issuing a stablecoin are not complicated.
1. Decide on the name for your stablecoin (either following the 3-character ISO standard or using a 160-bit hex string. See [Currency Codes](../../references/protocol/data-types/currency-formats.md#currency-codes)).
2. Create a trust line between the issuing account and a consuming account establishing a maximum number of stablecoins to transfer.
3. Send a payment of stablecoins to the consumer up to the maximum amount in the trust line.
While anyone can issue a token with any currency code in the XRP Ledger, stablecoin value comes from the promise that it can be redeemed for a corresponding asset. Issuing a stablecoin might involve regulatory obligations, which vary by jurisdiction. For these reasons, an established, reputable business is most likely to succeed in issuing a stablecoin.
[![Stablecoin Workflow](/img/uc-stablecoin-flow.png)](/img/uc-stablecoin-flow.png)
There are many decisions to make and artifacts to generate as you prepare to release a new stablecoin. You can use the XRPL Foundation's [Self-assessment Questionnaire](https://foundation.xrpl.org/wp-content/uploads/2022/03/self_assessment_questionnaire_140322.pdf) as a starting point to gather and produce the necessary information for a successful launch.
## Choose the Type of Stablecoin
The first step is to decide the type of stablecoin you want to create. Your choice of stablecoin type might require additional steps, such as signing on financial or audit partners.
![Stablecoin](/img/uc-stablecoin-stable-coin.png)
There are five common types of currency tokens you can create on the XRPL: fiat-backed, crypto-backed, commodity-backed, financial instrument-backed, and non-collateralized. See [Stablecoins](../../concepts/tokens/fungible-tokens/stablecoins/index.md).
## Set Up Your Node Services
For lighter use cases and individual servers, you can often rely on free public servers. However, the more serious your use of the XRP Ledger becomes, the more important it becomes to have your own infrastructure.
There are many reasons you might want to run your own servers, but most of them can be summarized as: you can trust your own server, you have control over its workload, and you're not at the mercy of others to decide when and how you can access it. See [Reasons to Run Your Own Server](../../concepts/networks-and-servers/index.md#reasons-to-run-your-own-server).
Alternatively, you can use an external node service provider like OpenNode. See [OpenNode](https://www.opennodecloud.com/).
## Sandbox Access
![Sandbox](/img/uc-stablecoin-sandbox.png)
For testing purposes, you can implement, deploy, and trade your stablecoin on the XRPL Testnet or Devnet servers. Visit the XRP Faucets page to generate your test network credentials. Use the listed server URIs on that page to connect to and interact with your chosen test network. See [XRP Faucets](/resources/dev-tools/xrp-faucets).
## Stablecoin Settings
Before you mint your new stablecoin, you need to configure settings, some of which are immutable once you issue the first coin.
See [Stablecoin Settings](../../concepts/tokens/fungible-tokens/stablecoins/settings.md).
For more detail on configuration capbilities, see [Stablecoin Issuer Configuration](../../concepts/tokens/fungible-tokens/stablecoins/configuration.md).
## Asset Information
Publish standard information about your stablecoin to enable potential traders to verify the coin's stability.
### Asset Nomenclature
Choose a 3-character string for your currency code. Per ISO 4217, supranational currency codes begin with the letter _X_ for a currency that is not associated with a country. See [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#X_currencies_(funds,_precious_metals,_supranationals,_other)).
Currency codes do not have to be unique. For instance, if you're issuing a stablecoin backed by a national fiat currency, it's better to use the official code for that currency, such as _EUR_.
### xrp-ledger.toml
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 on your website. 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.
You can use the _Currencies_ table to provide additional information about your stablecoin. This makes the information about your cryptocurrency accessible in an expected place and format, and enhances transparency. See [xrp-ledger.toml File](../../references/xrp-ledger-toml.md#currencies).
## Account and Key Management
### Multisignature Schemes
By using multiple keys and signing weights, issuers and asset holders can distribute trust and responsibility for approving transactions for an account between different users and systems. This gives you the flexibility to gate those signatures using internal processes and controls.
See [Multi-signing](../../concepts/accounts/multi-signing.md).
<!--
### Omnibus Wallets
For customers who prefer not to take custody of their own wallets, you can create an omnibus account with subaccounts, then assign these accounts to customers.
## Treasury Management
### Reconciliation
Periodically audit to verify that distributed stablecoins and stablecoins in escrow equal the total number of stablecoins.
### Checking Reserves
How to check reserves.
### Proof of Reserves
How to transparently report the current number of stablecoins held in reserve.
-->
## Token Operations
### Issue a Stablecoin
Actually issuing a new stablecoin is straightforward. In practice, there are many considerations when issuing a stablecoin that users will trade with confidence.
Before you issue your stablecoin, download and read the questions in the [Self-assessment Questionnaire](https://foundation.xrpl.org/wp-content/uploads/2022/03/self_assessment_questionnaire_140322.pdf). When you are ready to distribute your stablecoin, complete the public [Token Issuer Self-Assessment Questionnaire](https://foundation.xrpl.org/token-assessment-framework/). This allows full transparency to the XRPL community about your new stablecoin.
For additional considerations, see:
- [Stablecoin Issuer - Precautions](../../concepts/tokens/fungible-tokens/stablecoins/precautions.md)
- [Stablecoin Issuer - Compliance Guidelines](../../concepts/tokens/fungible-tokens/stablecoins/compliance-guidelines.md)
- [Issue a Fungible Token](../../tutorials/use-tokens/issue-a-fungible-token.md)
### Create a Trust Line
Trust lines are structures in the XRP Ledger for holding tokens. 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, among other benefits.
Each "trust line" is a bidirectional relationship consisting of:
- The identifiers for the two accounts that the trust line connects.
- A single, shared balance, which is positive from the perspective of one account and negative from the other perspective.
- Various settings and metadata. Each of the two accounts can control its own settings on the trust line. Each side sets a limit on the trust line.
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.
See [Trust Lines](../../concepts/tokens/fungible-tokens/index.md#trust-lines).
### Authorized Trust Lines
The Authorized Trust Lines feature enables issuers to create tokens that can only be held by accounts that the issuer specifically authorizes. This feature only applies to tokens, not XRP.
To use the Authorized Trust Lines feature, enable the `Require Auth` flag on your issuing account. While the setting is enabled, other accounts can only hold tokens you issue if you have authorized those accounts' trust lines to your issuing account.
See [Authorized Trust Lines](../../concepts/tokens/fungible-tokens/authorized-trust-lines.md).
### Freeze a Trust Line
If you issue tokens in the XRP Ledger, you can enable the _No Freeze_ setting to permanently limit your own ability to use the token freezing features of the XRP Ledger. (As a reminder, this only applies to issued tokens, not XRP.)
If you do not enable the _No Freeze_ setting, when an account shows suspicious activity or violates your institution's terms of use, you have the option of freezing the trust line while you resolve the issue.
See [Freezing Tokens](../../concepts/tokens/fungible-tokens/freezes.md).
### Global Freeze
If you see signs of suspicious activity, you can enact a global freeze on your account to prevent users from sending your tokens to each other and trading your token in the decentralized exchange.
![Global Freeze](/img/uc-stablecoin-global-freeze.png)
See [Enact Global Freeze](../../tutorials/use-tokens/enact-global-freeze.md).
### Clawback
_(Requires the [Clawback amendment][] {% not-enabled /%})_
Clawback is an optional setting that you can choose before you begin to distribute your stablecoin. For regulatory purposes, some issuers _must_ have the ability to recover issued tokens after they are distributed to accounts. For example, if an issuer were to discover that tokens were sent to an account sanctioned for illegal activity, the issuer could recover, or _claw back_, the funds.
See [Clawback](../../references/protocol/transactions/types/clawback.md).
![Clawback](/img/uc-stablecoin-clawback.png)
### Partial Payments
Look out for partial payments. 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. 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.
See [Partial Payments](../../concepts/payment-types/partial-payments.md).
### Burn
One way to manage the value of a token is to destroy, or _burn_ tokens, which reduces the number of tokens in circulation. On the XRP Ledger, fungible tokens are automatically "burned" when they are sent to the issuing address. However, the issuer can freely create more tokens.
To ensure a limited supply, you can "black hole" the issuer after issuing tokens, by setting its regular key to an address like `rrrrrrrrrrrrrrrrrrrrrhoLvTp` for which no one knows the private key, and disabling the master key pair.
**Warning:** A black hole account has no way to send transactions of any kind, so you cannot update any settings or do any maintenance on the account afterwards!
See [Disable Master Key Pair](../../tutorials/manage-account-settings/disable-master-key-pair.md).
### 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](../../references/client-libraries.md) do this by default.)
* Resubmit a transaction if it has not appeared in a validated ledger whose [ledger index][] is bigger than or equal to the transaction's `LastLedgerSequence` parameter.
For more information, see [Reliable Transaction Submission](../../concepts/transactions/reliable-transaction-submission.md).
### List on the XRPL Native DEX
Decentralized exchanges (DEXes) are integral to the decentralized finance ecosystem. Listing your token on the XRP Ledger's built-in DEX enhances its visibility and accessibility, thereby attracting more liquidity. Begin by placing sell offers using a suitable interface, such as [Sologenic](https://sologenic.org/trade). As a precaution, use a separate account, not your issuing address, to trade.
### List on an AMM
_(Requires the [AMM amendment][] {% not-enabled /%})_
Automated Market Makers (AMMs) are smart contracts that provide liquidity in the XRP Ledger's decentralized exchange. Each AMM holds a pool of two assets and enables users to swap between them at an exchange rate set by a formula.
For any given pair of assets, there can be up to one AMM in the ledger. You can create the AMM for an asset pair with your new token if it doesn't exist yet, or deposit to an existing AMM. Those who deposit assets into an AMM are called _liquidity providers_ (LPs) and receive _LP Tokens_ from the AMM.
See [Automated Market Makers](../../concepts/tokens/decentralized-exchange/automated-market-makers.md).
{% raw-partial file="/_snippets/common-links.md" /%}