ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 19:55:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Information Architecture v3 (#1934)

Browse Source 
* Update look up escrows to remove redundant info about lookups via sender/destination. Modify cancel expired escrow for brevity.

* Cancel escrow: fix notes

* Add draft of updated cancel-escrow.js.

* Update intro to escrows.

* Add Escrow Tutorial

* Minor corrections

* Fix headings, add HTML

* Update escrow docs

This commit re-creates f205a92db2 with
some adjustments:

- Omit the accidentally-created dir full of junk
- Fix some typos and one mistake in the Escrow limitations section
- Add a table to the EscrowCreate ref to clarify valid combos of fields.

* Concept info from send-a-time-held-escrow added to escrow.md

* IA: Move "Consensus Network" files

This re-creates some work from the original commit 56fffe0b9f

* Rewrite escrows article (re-created)

This commit re-creates relevant work from the following commits:

9a4a588f2b Update escrow.md context info
e1b017dc83 Remove references to using escrow for interledger payments.

* IA: Move "XRPL servers" files

This re-creates some work from original commit 7611979abf

* IA: move "production readiness" files.

Re-creates work from the following commit:

692438693a  Move tutorials to concepts

* New intro articles

Original commit: 56fffe0b9f

* IA: Reorg account concepts

Re-creates some work from original commit 56fffe0b9f

* IA: reorg transaction concepts

Original commits:
9d4eff9940  WIP - reorg accounts
7611979abf  WIP dir. reorg

* IA: reorg consensus concepts

Original commit: 56fffe0b9f

* IA: Reorg ledger docs

Original commit: 56fffe0b9f

- Rephrased some details of the section

* IA: rename issuing/operational addresses page

Original commit: 56fffe0b9f

* Moving use cases

* Fleshing out Use Cases

Note, the dactyl-config.yml file has not been fully updated.

* Clean up checks conceptual info.

* Remove redundant checks use case section

Original commit: 3c29e9c05e

* IA: move Dex under tokens

Original commit: d08b3ba7d7

* Touch up stablecoin issuer use case (#1856)

* Consolidate stablecoin use case

* Stablecoin issuer: cleanup progress through sending

* Stablecoin issuer: reorg second half

(Note: the dactyl-config.yml is not fully reconciled yet)

* Move rippled and clio tutorials into infrastructure

* Remove link to checks amendement.

* Add note to account_objects.md about commandline interface type field.

* Merge expiration case with lifecycle section.

* Interoperability Use Cases

* Add graphics to intro

* Move escrow use cases to dedicated page.

* Update use case page intros and corresponding concept info.

* Clarify meaning of direct XRP payments.

* Intro link updates

* Payment use cases

* Remove some unnecessary links in transactions section

Original commit: e6fcf4a4dc

* Link cleanup in Tokens section

Original commit: 9588dd5e70

* Touch up 'Configure Peering' section

Original commit: fc8f0990b8

* Clean up links in accounts section

Original commit: 3da5fde7a8

* Add NFT mkt use case

* p2p payments: edits to Wallets

* Clean up payments use cases

* Refine history description

* IA: use case cleanup

* IA: reconcile servers, ledgers sections

* IA: reconcile payment types, tx, tokens

* IA: reconcile accounts section

* IA: reconcile infra

* IA: Fix most broken links

* Full Docs Index: omit from sidebar

* IA: fix up most broken links

* fix Absolute path link to internal content

* Quick updates to Software Ecosystem

* Remove some absolute links to internal resources

* Fix remaining broken links in JA target

* Contributing: tweak formatting

* Tutorials: fix some minor issues

* remove interop use cases

* remove intro image and personal references to dennis

* alphabetize-transaction-nav

* Remove unused files

* Add QS escrow tutorials

* IA: move ledgers, consensus protocol files around

* IA: update nav for new page hierarchy

* reordering of topics under new networks and servers top-nav

* Move "Naming" to "What is XRP?"

* Update dactyl-config.yml

Remove xrp.md from the TOC.

* Update list-xrp-as-an-exchange.md

Update link to what-is-xrp

* Update list-xrp-as-an-exchange.ja.md

Change link to what-is-xrp

* Update currency-formats.md

Change link to what-is-xrp

* Update currency-formats.ja.md

Change link to what-is-xrp

* Update cancel-an-expired-escrow.md

Change link to what-is-xrp

* Update paymentchannelfund.md

Change link to what-is-xml

* Update look-up-escrows.md

Change link to what-is-xrp

* Update tokens.md

change link to what-is-xrp

* Update use-payment-channels.md

* Update send-a-time-held-escrow.md

Update link to what-is-xml

* fix broken links

* Update parallel-networks.md

Change link to what-is-xml

* Update parallel-networks.ja.md

* Update invariant-checking.md

Remove link to xrp.html

* Update invariant-checking.ja.md

Remove link to xrp.html

* Update transaction-cost.md

Change link to what-is-xrp

* Update transaction-cost.ja.md

Change link to what-is-xrp

* Update send-a-conditionally-held-escrow.md

Change link to what-is-xrp

* Update stablecoin-issuer.md

Change link to what-is-xrp

* Update tokens.ja.md

Change link to what-is-xml

* Update autobridging.ja.md

Change link to what-is-xrp

* Update currency-formats.md

update text

* reorganize infrastructure nav section

* Update currency-formats.md

Try removing link altogether.

* Update currency-formats.ja.md

Remove link to what-is-xrp.html

* move commandline usage topic to infrastructure

* initial intro rewrite

* minor update to language

* IA.v3: rm Production Readiness

* Delete xrp.md

* Update xrp link in snippet

* Add redirect for old xrp.html URL

* Small edits to 'What is XRP?' article

* Add missing imgs

* XRP - copy edit per @DennisDawson

* restructure tutorials nav and pages

* fix broken links

* more broken link fixes

* Algo trading: 1st draft

* Algo trading: notes on taxes

* Algo trading: edits per review

* algo trading: fix broken link

* Ledger structure: rewrite for accuracy and clarity

* Update links to removed 'tree format' header

* Ledger Structure: Update diagrams

* Re-gen CSS for ledger structure changes

* Ledger structure: edits per review

* IA.v3: fix broken NFT links introduced by rebase

* Desktop Wallet (py): update little stuff

* Update some capacity/storage details

* contribute doc nav update

* fix image link in create diagram page

* IAv3: Fix 'Ledgers' blurb

* Update full history requirements with details from community members

* add reviewer suggestions

* Edits per @trippled review

* Apply suggestions from peer review

Co-authored-by: oeggert <117319296+oeggert@users.noreply.github.com>

* FH: reword file size limit note per review

* Update software ecosystem

* updates per review

* Minor tweaks to graphics

* fixTypos

* Update content/concepts/introduction/software-ecosystem.md

Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com>

* Update content/concepts/introduction/software-ecosystem.md

Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com>

* [JA] update AccountDelete cost

* custom transactors doc

* add doc to dactyl config

* [JA] fix NonFungibleTokensV1_1 amendment status

* [JA] update NFTokenOffer page

* Remove old, unused XRP article (#2039)

* add reviewer suggestions

* Add tooling to check for file/nav consistency

- From the repo top, run tool/check_file_consistency.py to look for
  Markdown files that exist in the "content/" directory but aren't used
  in the documentation.
- New "enforce_filenames" filter prints a warning to console when
  building, if a file's path and filename don't match expectations
  based on its place in the nav and top heading.

* File consistency checker: correctly handle filenames starting in _

* Remove unused old 'get started' and associated code

* Create Resources section & reorg some files

- Rename some files/folders based on their place in the nav
- Move a bunch of non-documentation stuff, and docs on contributing code
  and/or docs to the new "Resources" section.
- Known issue: nav spills into a second row on page widths between
  993px-1110px. To be fixed in a later CSS update, maybe along with
  making the Resources dropdown multi-column.

* Fix #2078 code tab bug

CSS not built yet, to reduce merge conflicts. Won't have any effect
until that happens.

* fix Transaction JSON

* [JA] translate contributing contents

* fix contributing-to-documentation parent

* fix contribute-code blurb

* Top nav: add cols for Resources, fix broken links

* CSS: fix top nav overflows

* Fix broken link from redirect not in JA target

* Top nav: add Infra to article types

* Update contrib info & rename intro file

* [ja] Update link to suggested first page to translate

* [ja] fix contribute docs organization

* Run private network with docker tutorial (#2065)

* [NO-ISSUE] Run private network with docker tutorial

Adds a tutorial page in the Infrastructure section on how to run a private XRPL network with Docker.

Please let me know if you think this is a useful page to include for developers, whether the steps are clear or not, and if you have suggestions on what can be added to it.

* Add minor link fixes and Japanese target

* Apply suggestions from code review

Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com>

* Add link to ripple-docker-testnet setup scripts in See Also section

* Update repo URL

---------

Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com>

* add intro gfx (#2036)

* add intro gfx

* Move graphic up

* Update some graphics with their revised versions

* Add updated version of the custodial vs non-custodial graphic

---------

Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com>
Co-authored-by: Amarantha Kulkarni <akulkarni@ripple.com>

* Update to reflect current UNL publishers

* [ja] update contributing

Co-authored-by: tequ <git@tequ.dev>

* Incorporate feedback on "What is XRP" page. (#2099)

* Add trademark info for XRP

* Revert section to previous state

* Fix broken link (#2101)

---------

Co-authored-by: Oliver Eggert <oeggert@ripple.com>
Co-authored-by: ddawson <dennis.s.dawson@gmail.com>
Co-authored-by: Maria Shodunke <mshodunke@ripple.com>
Co-authored-by: tequ <git@tequ.dev>
Co-authored-by: oeggert <117319296+oeggert@users.noreply.github.com>
Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com>
Co-authored-by: develoQ <develoQ.jp@gmail.com>
Co-authored-by: Maria Shodunke <maria-robobug@users.noreply.github.com>
Co-authored-by: Amarantha Kulkarni <akulkarni@ripple.com>
This commit is contained in:
Rome Reginelli
2023-09-01 12:40:18 -07:00
committed by GitHub
parent 31a068e6ae
commit b51bcb4ea3
445 changed files with 9020 additions and 4411 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
content/use-cases/defi/algorithmic-trading.md Normal file
View File

@@ -0,0 +1,101 @@
---
html: algorithmic-trading.html
parent: defi-uc.html
blurb: 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 fees 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](paths.html) explicitly in a [Payment transaction](payment.html). 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](transfer-fees.html) 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](tokens.html)
- [Decentralized Exchange](decentralized-exchange.html)
- [Offers](offers.html)
## 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](currency-formats.html).
- Be aware that token issuers can further limit the precision of exchange rates involving their tokens. See [Tick Size](ticksize.html) 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](transfer-fees.html), 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](partial-payments.html) 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](offercreate.html). For a detailed walkthrough of the code and technical steps to place a trade this way, see [Trade in the Decentralized Exchange](trade-in-the-decentralized-exchange.html). It is also possible to exchange currencies using the [Payment transaction type](payment.html). You could send a [cross-currency payment](cross-currency-payments.html) to another user or even send it back to yourself, using a long [path](paths.html) 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](transfer-nfts-using-javascript.html).
### 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](public-servers.html), but you can often benefit from running your own server, and some use cases may not be practical without doing so. See [Install `rippled`](install-rippled.html) 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](look-up-transaction-results.html).
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](open-closed-validated-ledgers.html), or even monitor for proposed transactions. If you're connected to WebSocket, you can use the [subscribe method](subscribe.html) 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](amendments.html), 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)

610
content/use-cases/defi/list-xrp-as-an-exchange.ja.md Normal file
View File

@@ -0,0 +1,610 @@
---
html: list-xrp-as-an-exchange.html
parent: defi-uc.html
blurb: デジタルアセット取引所でXRPを上場するために必要な手順の概要を説明します。
labels:
- XRP
---
# 取引所としてのXRPの上場
本書では、取引所がXRPを上場するために必要なステップを説明します。
## Alpha Exchange
本書での説明目的で、架空の企業である _Alpha Exchange_ を使用して、XRPを上場するために必要な手順の概要を説明します。本書では、Alpha Exchangeは以下のような取引所です。
* 現在BTC/USDの上場を専門としています
* BTC/XRPとXRP/USDの取引ペアの追加を希望しています
* すべての顧客の残高を保持しています
* サポートしている各通貨の残高を保持しています
### ユーザーの利益
Alpha Exchangeは、BTC/XRPおよびXRP/USDの取引ペアを上場することを希望しています。理由の1つとして、これらのペアがユーザーにとって有用なものであることが挙げられます。特に、このサポートによりユーザーは以下ができるようになります。
* XRP Ledger _から_ Alpha Exchange _に_ XRPを入金できます
* Alpha Exchange _から_ XRP Ledger _に_ XRPを送金できます
* XRPをBTCやUSDなどの他の通貨と交換できます
## XRPをサポートするための前提条件
XRPをサポートするために、Alpha Exchangeでは以下を行う必要があります。
* 新しい[アカウント](#アカウント)を作成して維持します
* [バランスシート](#バランスシート)を作成して維持します
関連項目:
* [ゲートウェイコンプライアンス](stablecoin-issuer.html#compliance-guidelines) — ゲートウェイと取引所は異なりますが、取引所は地域の規制に準拠し、適切な当局の監督下になければなりません。
* [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)
* [ゲートウェイの注意事項](stablecoin-issuer.html#precautions)
### Partial Payments
追加の前に、取引所は[Partial Payments](partial-payments.html)機能について知っておく必要があります。この機能を使用すると、XRP Ledgerのユーザーは、`SendMax`を増やさずに、受取金額を減額して、支払いを正常に送信できます。この機能は、送信者側に追加費用が発生せず、[支払いの返金](stablecoin-issuer.html#bouncing-payments)に便利です。
#### Partial Paymentsに関する警告
[tfPartialPaymentフラグ](payment.html#paymentのフラグ)が有効にされると、`Amount`フィールド **_は受取り金額とは同じでなくなることがあります_** 。支払いのメタデータにある`delivered_amount`フィールドは、宛先アカウントが実際に受け取る通貨の金額を示しています。支払いを受信するときに、Amountフィールドの代わりに、`delivered_amount`を使用してアカウントで受信した金額を判断します。
**警告:** この機能が悪用されることがあります。詳細については、[Partial Payments](partial-payments.html)を参照してください。
### アカウント
XRPは、XRP Ledgerの _アカウント_ （ _ウォレット_ や _アドレス_ とも呼ばれる）で保持されます。XRP Ledgerのアカウントは、例えばBitcoinのような、アカウントに経費がほとんどまたは一切かからない他のブロックチェーンの台帳とは異なります。XRP Ledgerでは、[アカウントの削除](accounts.html#アカウントの削除)は可能が、各アカウントは個別の、他の人に送信することのできない、[XRPの準備金](reserves.html)を保持する必要があります。このような理由から、Rippleでは利用機関に対し、必要のない過剰なアカウントを作成しないように勧めています。
<!-- STYLE_OVERRIDE: hot wallet, warm wallet, cold wallet, wallet -->
Rippleが推奨するベストプラクティスに従い、Alpha Exchangeは、XRP Ledgerに最低2つのアカウントを作成する必要があります。シークレットキーが悪用された場合の危険を最小限にとどめるため、Rippleでは、[ _コールドアカウント_ 、 _ホットアカウント_ 、 _ウォームアカウント_ ](https://ripple.com/build/issuing-operational-addresses/)（それぞれコールドウォレット、ホットウォレット、ウォームウォレットとも呼ばれる）の作成をお勧めしています。コールド/ホット/ウォームのモデルは、セキュリティと利便性のバランスをとるためのものです。XRPを上場する取引所は、以下のアカウントを作成する必要があります。
* 大部分のXRPと顧客の資金を維持する[ _コールドウォレット_ ](account-types.html#発行アドレス)。取引所にとって、これはユーザーが[預入れ](#取引所へのxrpの入金)をするアドレスです。 セキュリティを最適化するため、このアカウントのシークレットキーはオフラインにする必要があります。
取引所のコールドウォレットが悪用されると、以下のような結果が生じるおそれがあります。
* 不正使用者が、コールドウォレットの全XRPにアクセスできます。
* マスターキーが悪用されると、不正使用者は（マスターキーを無効にし、新しいレギュラーキーや署名者リストを設定することにより）そのコールドウォレットを恒久的に制御できます。これにより、その不正使用者は今後そのコールドウォレットで受信するすべてのXRPも制御できるようになります。
* このような事態が発生した場合には、取引所は新しいコールドウォレットアドレスを作成し、顧客にその新しいアドレスを伝える必要があります。
* レギュラーキーや署名者リストが悪用された場合には、取引所はコールドウォレットの制御を取り戻すことができます。ただし、不正使用者の行為の中には、以下のように簡単に元に戻せないものもあります。 <!-- STYLE_OVERRIDE: easily -->
* 不正使用者が、コールドウォレットを使用してXRP Ledgerで通貨を発行しても、その通貨の価値はだれにも認められません。（取引所が明示的にゲートウェイでもあると示した場合を除きます）。
* 不正使用者が、アカウントにasfRequireAuthフラグを設定した場合。この設定は解除できません。ただし、これは通貨の発行のみに関係し、ゲートウェイではない取引所には影響しません。不正使用者がマスターキーで設定または設定解除したその他の設定は、元に戻すことができます。
* 顧客のXRP出金や入金を管理する、日常業務を遂行するための1つ以上の[ _ホットウォレット_ ](account-types.html#運用アドレス)。例えば、ホットウォレットがあれば、取引所はこの種のXRPの自動送金を安全にサポートできます。出金要求にただちに応じるため、ホットウォレットはオンラインである必要があります。
不正使用されたホットウォレットによって発生するおそれのある結果についての詳細は、[Operational Account Compromise](account-types.html#運用アドレスの漏えい)を参照してください。
* オプションとして、コールドウォレットとホットウォレットの間で追加のセキュリティ層を提供する、1つ以上のウォームウォレット。ホットウォレットとは異なり、ウォームウォレットのシークレットキーはオンラインである必要はありません。さらに、ウォームウォレットのシークレットキーを複数の人に分散し、[マルチシグ](multi-signing.html)を導入してセキュリティを強化することもできます。
不正使用されたウォームウォレットによって発生するおそれのある結果についての詳細は、[スタンバイアドレスの漏えい](account-types.html#スタンバイアドレスの漏えい)を参照してください。
関連項目:
* [発行アドレスと運用アドレス](account-types.html)
* [アカウントの作成](accounts.html#アカウントの作成)
* [準備金](reserves.html)
### バランスシート
顧客のXRPを管理するため、Alpha Exchangeは各顧客のXRP残高と自身の保有残高を追跡する必要があります。このためには、Alpha Exchangeは別のバランスシートまたは会計システムを作成し、維持する必要があります。以下の表は、このバランスシートを説明するものです。
新しいXRP Ledgerアカウント（ _Alpha Hot_ 、 _Alpha Warm_ 、 _Alpha Cold_ ）が、「*XRP LedgerのXRP残高*」表の*ユーザー*列に示されています。
「*Alpha ExchangeのXRP残高*」表は、新しい追加のバランスシートを表します。Alpha Exchangeのソフトウェアは、この会計システムでユーザーのXRP残高を管理します。
<table>
<tr>
<td><b><i>XRP Ledgerの
XRP残高</i></b></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchange
のXRP残高</i></b></td>
<td></td>
<td></td>
</tr>
<tr>
<td><b>ユーザー</b></td>
<td><b>残高</b></td>
<td></td>
<td><b>アカウント番号</b></td>
<td><b>ユーザー</b></td>
<td><b>残高</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の額
XRPの額は、XRP Ledgerで、符号なし整数の _drop_ として示されます。1XRPは1,000,000 dropです。Rippleでは、ソフトウェアでXRP残高をdropの整数値として格納し、これらの数値に整数演算を実行することをお勧めしています。ただし、ユーザーインターフェイスでは残高をXRPの単位で表示すべきです。
1drop（.000001XRP）はこれ以上分割できません。XRPと他の資産の間でFXレートを計算して表示するときには、この点にご注意ください。
詳細は、[通貨額の指定][]を参照してください。
#### 台帳上と台帳外
_Alpha Exchange_ のような取引所では、XRPは「台帳上」または「台帳外」に存在します。
* **台帳上のXRP**: XRP保有者のパブリック[アドレス](accounts.html#アドレス)を指定し、パブリックのXRP Ledgerを通じて照会できるXRP。これらの残高の取引相手はXRP Ledgerです。詳細については、[XRP](what-is-xrp.html)を参照してください。
* **台帳外のXRP**: 取引所の会計システムに保持されている、取引所のインターフェイスで照会できるXRP。台帳外のXRP残高はクレジットペースです。取引相手は、XRPを保有している取引所です。
台帳外のXRP残高は、取引所の参加者の間で取引されます。このような取引をサポートするため、取引所は取引で使用可能な、 _台帳外_ のXRP合計金額に等しい _台帳上_ のXRP残高を保持する必要があります。
## 資金の流れ
残りのセクションでは、ユーザーによる入金、取引、XRP残高の換金の過程で、Alpha Exchangeが管理するアカウントを通じて資金がどのように流れるのかを説明します。資金の流れを解説するため、本書では、[「バランスシート」セクション](#バランスシート)で使用した表を使用します。
取引所の一般的な資金の流れには、主要な4つステップが伴います。
1. [取引所へのXRPの入金](#取引所へのxrpの入金)
2. [XRPの保有高のリバランス](#xrpの保有高のリバランス)
3. [取引所からのXRPの出金](#取引所からのxrpの出金)
4. [取引所でのXRPの取引](#取引所でのxrpの取引)
このリストには、取引所の[前提条件](#xrpをサポートするための前提条件)が含まれていません。
この時点で、 _Alpha Exchange_ はXRP Ledgerの[ホットウォレット、ウォームウォレット、コールドウォレット](#アカウント)を作成し、それらをバランスシートに追加しましたが、ユーザーからの入金はまだ受け付けていません。
<table>
<tr>
<td><b><i>XRP Ledgerの
XRP残高</i></b></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchange
のXRP残高</i></b></td>
<td></td>
<td></td>
</tr>
<tr>
<td><b>ユーザー</b></td>
<td><b>残高</b></td>
<td></td>
<td><b>アカウント番号</b></td>
<td><b>ユーザー</b></td>
<td><b>残高</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の入金
[台帳外のXRP残高](#台帳上と台帳外)を追跡するには、取引所は新しい[バランスシート](#バランスシート)（または類似の会計システム）を作成する必要があります。以下の表は、ユーザーがXRPを入金するにつれ、Alpha Exchangeの新しいバランスシートで発生する残高の変化を示すものです。
CharlieというユーザーがAlpha Exchangeに50,000XRPを入金したいと希望しています。これには、以下のステップが伴います。
1. Charlieは50,000XRPの支払いを、Alpha Exchangeの[コールドウォレット](#アカウント)に送信します。
a. Charlieは識別子（このケースでは`789`）を支払いに追加し、Alpha Exchangeにある自身のアカウントに関連付けます。これは、[ _宛先タグ_ ](source-and-destination-tags.html)と呼ばれます。（これを使用するには、Alpha Exchangeは、すべての入金でCharlieのような宛先タグを必要とするように、すべてのアカウントでasfRequireDestフラグをオンに設定している必要があります。詳細については、[AccountSet Flags](accountset.html#accountsetのフラグ)を参照してください。）
2. Alpha Exchangeのソフトウェアは、受信される支払を検出し、`789`をチャーリーのアカウントの宛先タグとして認識します。
3. 受信される支払を検出すると、Alpha Exchangeのソフトウェアは、入金された50,000XRPがCharlieによって管理されるものであることを示すようにバランスシートを更新します。
Charlieは、これで、取引所で最大50,000XRPまで使用できます。例えば、XRPをBTCやその他のAlpha Exchangeでサポートされている通貨と取引するオファー（注文）を作成できます。
<table>
<tr>
<td><b><i>XRP Ledgerの
XRP残高</i></b></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchange
のXRP残高</i></b></td>
<td></td>
<td></td>
</tr>
<tr>
<td><b>ユーザー</b></td>
<td><b>残高</b></td>
<td></td>
<td><b>アカウント番号</b></td>
<td><b>ユーザー</b></td>
<td><b>残高</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>
### 取引所でのXRPの取引
Alpha Exchangeユーザー（Charlieなど）は、Alpha Exchangeでクレジットベースの残高を取引できます。Alpha Exchangeは、これらの取引の作成時に、新しいバランスシートでユーザーの残高を追跡する必要があります。これらの取引は、 _台帳外_ であり、XRP Ledgerから独立しています。このため、この残高の変化はXRP Ledgerには記録されません。
XRPを自身のXRP Ledgerアカウントに保有している顧客は、XRP Ledgerに組み込まれた分散型取引所 を使用して、ゲートウェイによって発行された通貨を取引することもできます。XRP Ledger _上_ での取引の詳細は、[オファーのライフサイクル](offers.html#オファーのライフサイクル)を参照してください。
### XRPの保有高のリバランス
取引所は、いつでもホットウォレットとコールドウォレットの間で残高を調整できます。各残高調整には、[トランザクションコスト](transaction-cost.html)がかかりますが、それ以外にはすべてのアカウントの合計残高に影響はありません。台帳上の合計残高は、取引所で取引に使用できる合計残高を常に上回る必要があります。（XRP Ledgerのトランザクションコストをカバーできるだけの十分な余剰が必要です。）
以下の表は、（XRP Ledgerで[Paymentトランザクション][]を介した）Alpha Exchangeのコールドウォレットとホットウォレットの間での80,000XRPの残高調整を示すものです。コールドウォレットから引き落としが行われ、ホットウォレットに入金が行われました。この支払いを逆にすると（ホットウォレットから引き落としが行われ、コールドウォレットに入金が行われる）、ホットウォレットの残高は減少します。このような残高調整は、取引所がオンラインホットウォレットにXRPを保持することに関連するリスクを抑えるために役立ちます。
<table>
<tr>
<td><b><i>Alpha Exchangeの
台帳外のXRP残高</i></b></td>
<td></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchangeの台帳上のXRP残高</i></b></td>
<td></td>
</tr>
<tr>
<td><b>アカウント番号</b></td>
<td><b>ユーザー</b></td>
<td><b>残高</b></td>
<td></td>
<td><b>XRP Ledgerアカウント</b></td>
<td><b>残高</b></td>
</tr>
<tr>
<td>123</td>
<td>Alice</td>
<td>80,000</td>
<td></td>
<td>ホット</td>
<td><s>0</s>
<br>80,000</td>
</tr>
<tr>
<td>456</td>
<td>Bob</td>
<td>50,000</td>
<td></td>
<td>ウォーム</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>コールド</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>
### 取引所からのXRPの出金
出金により、取引所のユーザーは、取引所の台帳外バランスシートから、XRP LedgerのアカウントにXRPを移動できます。
この例では、Charlieは、Alpha Exchangeから25,000XRPを出金します。これには、以下のステップが伴います。
1. Charlieは、Alpha ExchangeのWebサイトでプロセスを開始します。彼は、25,000XRPをXRP Ledgerの特定のアカウント（以下の表では、「Charlie XRP Ledger」という名前）に送金する指示を出します。
2. Charlieの指示に対応し、Alpha Exchangeは以下の作業を実行します。
A. その金額（25,000XRP）を台帳外バランスシートのCharlieのアカウントから引き出します。
B. XRP Ledgerで、Alpha ExchangeのホットウォレットからCharlieのXRP Ledgerアカウントに同じ金額（25,000XRP）の支払いを送信します。
<table>
<tr>
<td><b><i>XRP Ledger台帳上のXRP残高</td>
<td></td>
<td></td>
<td><b><i>Alpha Exchangeの
台帳外のXRP残高</td>
<td></td>
<td></td>
<td></td>
<td><b><i>Alpha Exchangeの台帳上のXRP残高</td>
<td></td>
</tr>
<tr>
<td><b>ユーザー</td>
<td><b>残高</td>
<td></td>
<td><b>アカウント番号</td>
<td><b>ユーザー</td>
<td><b>残高</td>
<td></td>
<td><b>XRP Ledgerアカウント</td>
<td><b>残高</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>ホット</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>ウォーム</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>コールド</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>
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

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

@@ -0,0 +1,626 @@
---
html: list-xrp-as-an-exchange.html
parent: defi-uc.html
blurb: 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 holds fund on behalf of users, and allows users to deposit, withdraw, and trade other digital assets, fiat currencies, or other types of assets.
## 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](stablecoin-issuer.html#compliance-guidelines) — Token issuers and exchanges are different, but exchanges should also ensure that they are complying with local regulations and reporting to the appropriate agencies.
* [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](stablecoin-issuer.html#precautions)
### Partial Payments
Before integrating, exchanges should be aware of the [partial payments](partial-payments.html) 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](stablecoin-issuer.html#bouncing-payments) without incurring additional cost as the sender.
#### Partial Payments Warning
When the [`tfPartialPayment` flag](payment.html#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](partial-payments.html).
### 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](deleting-accounts.html). To offset the costs associated with storing accounts, each account must hold a separate [reserve of XRP](reserves.html) 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](account-types.html) (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_](account-types.html#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](authorized-trust-lines.html) 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_](account-types.html#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](account-types.html#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](multi-signing.html) to increase security.
For more information about the possible consequences of a compromised warm wallet, see [Standby Account Compromise](account-types.html#standby-address-compromise).
See also:
* [Issuing and Operational Addresses](account-types.html)
* [Creating Accounts](accounts.html#creating-accounts)
* [Reserves](reserves.html)
### 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](addresses.html) of the XRP holder. The counterparty to these balances is the XRP Ledger. For more information, see [XRP](what-is-xrp.html).
* **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_](source-and-destination-tags.html). (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](accountset.html#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](offers.html#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](transaction-cost.html), 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](accounts.html)
- [Direct XRP Payments](direct-xrp-payments.html)
- [Partial Payments](partial-payments.html)
- [Source and Destination Tags](source-and-destination-tags.html)
- **Tutorials:**
- [Install `rippled`](install-rippled.html)
- [Send XRP](send-xrp.html)
- [Set Up Secure Signing](secure-signing.html)
- [Monitor Incoming Payments with WebSocket](monitor-incoming-payments-with-websocket.html)
- **References:**
- [Payment transaction][]
- [account_info method][]
- [AccountRoot object](accountroot.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

53
content/use-cases/payments/peer-to-peer-payments-uc.md Normal file
View File

@@ -0,0 +1,53 @@
---
html: peer-to-peer-payments-uc.html
parent: payments-uc.html
blurb: 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](crypto-wallets.html).
## 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](parallel-networks.html)
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](accounts.html#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](reserves.html).
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](payment.html).
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](account_info.html).
## 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](direct-xrp-payments.html).
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](cross-currency-payments.html).
This is a great payment option if you or the receiver prefer a specific token instead of the native XRP currency.

70
content/use-cases/payments/restricting-deposits-uc.md Normal file
View File

@@ -0,0 +1,70 @@
---
html: restricting-deposits-uc.html
parent: payments-uc.html
blurb: 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](depositauth.html).
## 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](depositpreauth.html).
## 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](use-checks.html).
### 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](use-escrows.html).
<!-- 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.
-->

48
content/use-cases/payments/smart-contracts-uc.md Normal file
View File

@@ -0,0 +1,48 @@
---
html: escrow-uc.html
parent: payments-uc.html
blurb: 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`](escrowcreate.html).
### 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](send-a-conditionally-held-escrow.html#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.

103
content/use-cases/tokenization/authorized-minter.md Normal file
View File

@@ -0,0 +1,103 @@
---
html: authorized-minter.html
parent: nft-mkt-overview.html
blurb: 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](assign-an-authorized-minter-using-javascript.html).
[![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](install-rippled.html).
## 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](nftoken-authorized-minting.html).
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](nftoken-auctions.html).
To mint your first NFTs on behalf of another account, see [Authorizing Another Account to Mint Your NFTs](assign-an-authorized-minter-using-javascript.html).
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](nftoken.html#nftoken-flags) and [Transferable flag](nftoken.html#nftoken-flags).
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](nftoken.html#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](nft-collections.html)
Use the TokenTaxon field to gather a set of NFTs centered around a specific theme or purpose.
* [Guaranteeing a Fixed Supply of NFTs](nft-fixed-supply.html)
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](nft-fixed-supply.html).
## Transferring NFTs
You transfer NFTs by creating a sell offer or accepting a buy offer. See [Transfer NFTokens](transfer-nfts-using-javascript.html).
You can sell your NFTs in an auction format. See [Running an NFT Auction](nftoken-auctions.html).
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](broker-an-nft-sale-using-javascript.html).
### 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.
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](nft-reserve-requirements.html#nftokenoffer-reserve)
2. NFToken page ([Owner reserve](nft-reserve-requirements.html#owner-reserve))
3. Trivial [transfer fees](transfer-fees.html)
### Checkout
The most straightforward payment for XRPL NFTs is XRP. For examples of selling and buying NFTs using XRP, see [Transfer NFTokens](transfer-nfts-using-javascript.html).
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](trade-in-the-decentralized-exchange.html#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.
See:
- [Clio setup](install-clio-on-ubuntu.html)
- [XRPL Data API](https://api.xrpldata.com/docs/static/index.html#/)
- [Bithomp](https://docs.bithomp.com/#nft-xls-20)
<!--
[Clio setup](install-clio-on-ubuntu.html)
[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
-->

83
content/use-cases/tokenization/digital-artist.md Normal file
View File

@@ -0,0 +1,83 @@
---
html: digital-artist.html
parent: nft-mkt-overview.html
blurb: 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](mint-and-burn-nfts-using-javascript.html).
[![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](public-servers.html).
## 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](nftoken.html#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](nft-collections.html).
* 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](nftoken.html#nftoken-flags) and [Transferable flag](nftoken.html#nftoken-flags).
See [Mint and Burn NFTokens](mint-and-burn-nfts-using-javascript.html).
## Sell NFTs
You transfer NFTs by creating a sell offer. See [Transfer NFTokens](transfer-nfts-using-javascript.html).
You can sell your NFTs in an auction format. See [Running an NFT Auction](nftoken-auctions.html).
### 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.
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](nft-reserve-requirements.html#nftokenoffer-reserve)
2. NFToken page ([Owner reserve](nft-reserve-requirements.html#owner-reserve))
3. Trivial [transfer fees](transfer-fees.html)
### Checkout
The most straightforward payment for XRPL NFTs is XRP. For examples of selling and buying NFTs using XRP, see [Transfer NFTokens](transfer-nfts-using-javascript.html).
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](trade-in-the-decentralized-exchange.html#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.
See:
- [Clio setup](install-clio-on-ubuntu.html)
- [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.
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.

168
content/use-cases/tokenization/nft-mkt-overview.md Normal file
View File

@@ -0,0 +1,168 @@
---
html: nft-mkt-overview.html
parent: tokenization.html
blurb: 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](public-servers.html).
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](install-rippled.html).
See also:
* [Pros and cons of running your own server](networks-and-servers.html#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](mint-and-burn-nfts-using-javascript.html).
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](nftoken.html#nftoken-flags) and [Transferable flag](nftoken.html#nftoken-flags).
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](nftoken.html#transferfee).
You can mint NFTs in logical collections using the `TokenTaxon` field. See [Minting NFTs into Collections](nft-collections.html).
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](nftoken-authorized-minting.html).
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](nft-reserve-requirements.html).
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_). See [Lazy minting](nftoken-batch-minting.html#mint-on-demand-lazy-minting) vs [Scripted minting](nftoken-batch-minting.html#scripted-minting).
### 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](reserves.html#base-reserve-and-owner-reserve).
### Transferring NFTs
You transfer NFTs by creating a sell offer or accepting a buy offer. See [Transfer NFTokens](transfer-nfts-using-javascript.html).
You can sell your NFTs in an auction format. See [Running an NFT Auction](nftoken-auctions.html).
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](broker-an-nft-sale-using-javascript.html).
#### 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.
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](nft-reserve-requirements.html#nftokenoffer-reserve)
2. NFToken page ([Owner reserve](nft-reserve-requirements.html#owner-reserve))
3. Trivial [transfer fees](transfer-fees.html)
#### Checkout
The most straightforward payment for XRPL NFTs is XRP. For examples of selling and buying NFTs using XRP, see [Transfer NFTokens](transfer-nfts-using-javascript.html).
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](trade-in-the-decentralized-exchange.html#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. 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](install-clio-on-ubuntu.html)
- [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](nftoken.html#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)
-->

101
content/use-cases/tokenization/nftoken-marketplace.md Normal file
View File

@@ -0,0 +1,101 @@
---
html: nftoken-marketplace.html
parent: nft-mkt-overview.html
blurb: 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](install-rippled.html).
### Setting up a wallet
Set up a new wallet. See [Xumm](https://xumm.app/).
Base reserve requirements See [Reserves](reserves.html#base-reserve-and-owner-reserve).
Current wallet options on XRPL: This is a good opportunity for XRPL to highlight wallet providers in the ecosystem
### Transferring NFTs
You transfer NFTs by creating a sell offer or accepting a buy offer. See [Transfer NFTokens](transfer-nfts-using-javascript.html).
You can sell your NFTs in an auction format. See [Running an NFT Auction](nftoken-auctions.html).
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](broker-an-nft-sale-using-javascript.html).
### 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.
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](nft-reserve-requirements.html#nftokenoffer-reserve)
2. NFToken page ([Owner reserve](nft-reserve-requirements.html#owner-reserve))
3. Trivial [transfer fees](transfer-fees.html)
You can learn more about brokered sales in the topic [Trading Tokens on the XRP Ledger](non-fungible-token-transfers.html).
Learn more about token transfer fees in the topic [Transfer Fees](transfer-fees.html).
You can get started building a brokered sales marketplace by following the steps in the [Broker a NFToken Sale](broker-an-nft-sale-using-javascript.html).
### Checkout
The most straightforward payment for XRPL NFTs is XRP. For examples of selling and buying NFTs using XRP, see [Transfer NFTokens](transfer-nfts-using-javascript.html).
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](trade-in-the-decentralized-exchange.html#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.
See:
- [Clio setup](install-clio-on-ubuntu.html)
- [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
-->

551
content/use-cases/tokenization/stablecoin-issuer.md Normal file
View File

@@ -0,0 +1,551 @@
---
html: stablecoin-issuer.html
parent: tokenization.html
blurb: Issue your own stablecoin, based on assets of equal value outside of the XRP Ledger.
labels:
- Tokens
---
# Stablecoin Issuer
**Stablecoin** are [tokens](tokens.html) that are backed by assets in the outside world. Stablecoins allow users to transact in familiar currencies, and provide a convenient way to get funds into and out of the blockchain. In exchange for providing these services, stablecoin issuers can earn revenue in various ways, such as fees on withdrawals or transfers of the stablecoin.
While anyone can issue a token with any currency code in the XRP Ledger, stablecoins' value comes from the promise that they can be redeemed for the corresponding assets. Issuing a stablecoin may also involve regulatory obligations, which vary by jurisdiction. For these reasons, issuing a stablecoin generally requires a reputable business.
**Note:** Stablecoin issuers on the XRP Ledger were formerly called "gateways".
This article provides information you should know before issuing a stablecoin, summarizes the choices involved in setting up a stablecoin issuer, and provides resources for implementing the technical integration with the XRP Ledger.
## Background Information
### Trust Lines and Tokens
All assets in the XRP Ledger, except for the native cryptocurrency XRP, are represented as _tokens_, which are tied to a specific issuer who defines their meaning. The XRP Ledger has a system of directional accounting relationships, called _trust lines_, to make sure that users can only hold and receive the tokens they want.
Tokens that are backed by funds in some outside system are sometimes called _stablecoins_. This includes tokens backed by fiat currency in a bank account, by cryptocurrencies on another blockchain, or other types of assets and forms of value. The term "stablecoin" comes from the idea that the exchange rate between the token and the asset it represents should be "stable" at 1:1 (minus fees).
For more information, see [Trust Lines and Issuing](trust-lines-and-issuing.html).
### XRP
**XRP** is the native cryptocurrency of the XRP Ledger. XRP can be sent directly from any XRP Ledger address to any other. This helps make XRP a convenient bridge currency.
Token issuers do not need to accumulate or exchange XRP. They must only hold a small balance of XRP to meet the reserve requirement and pay the cost of sending transactions through the network. The XRP equivalent of $10 USD should be enough for at least one year of transaction costs for a busy issuer.
For more information, see [What is XRP?](what-is-xrp.html), [Reserves](reserves.html), and [Transaction Cost](transaction-cost.html)
### Liquidity and Trading
The XRP Ledger contains a decentralized exchange, where any user can place and fulfill bids to exchange XRP and tokens in any combination. The decentralized exchange also provides the liquidity that makes atomic [cross-currency payments](cross-currency-payments.html) possible.
Stablecoin issuers aren't required to use the decentralized exchange directly, but all tokens are automatically available for trading. If a token is widely used, users should naturally trade it among themselves, creating liquidity to other popular assets. An issuer _may_ want to provide liquidity to XRP or other popular tokens at a baseline rate, especially when their token is new. If a stablecoin issuer does provide liquidity, a best practice is to **use different addresses for trading and for issuing.**
For more information on the decentralized exchange, see [Decentralized Exchange](decentralized-exchange.html).
## Suggested Business Practices
The value of a stablecoin issuer's tokens in the XRP Ledger comes directly from the trust that customers can redeem the tokens when needed. To reduce the risk of business interruptions, you should follow these best practices:
* Use separate [Issuing and Operational Addresses](account-types.html) to limit your risk profile on the network.
* Follow anti-money-laundering regulations for your jurisdiction, such as the [Bank Secrecy Act](http://en.wikipedia.org/wiki/Bank_Secrecy_Act). This usually includes requirements to collect ["Know-Your-Customer" (KYC) information](http://en.wikipedia.org/wiki/Know_your_customer).
* Complete the XRP Ledger Foundation's [token issuer self-assessment](https://foundation.xrpl.org/token-assessment-framework/).
* Publicize all your policies and fees.
* Provide an [`xrp-ledger.toml` file](xrp-ledger-toml.html) with domain verification so client applications can display relevant details about you.
### Hot and Cold Wallets
{% include '_snippets/issuing-and-operational-addresses-intro.md' %}
Main article: [Issuing and Operational Addresses](account-types.html)
## Fees and Revenue Sources
A stablecoin issuer can earn revenue in a variety of ways, including:
- Withdrawal or Deposit fees. The issuer can charge a small fee (such as 1%) for the service of moving money into or out of the XRP Ledger. This fee isn't assessed on the XRP Ledger, but in the issuer's own systems when deciding how much to issue or credit users.
- Transfer fees. The issuer can set a percentage fee to charge when users transfer the stablecoin within the XRP Ledger. This amount is debited from the XRP Ledger whenever users transact, decreasing the total obligation the stablecoin issuer owes to its users in the ledger without decreasing the amount of assets the issuer holds outside of the ledger.
- Indirect revenue from value added. Stablecoins provide convenient functionality that can ease the adoption of other, adjacent services.
- Interest on collateral. The issuer can hold the assets backing the stablecoin in an interest-earning account. Of course, they must make sure that they can always access enough funds to serve customer withdrawals.
- Financial exchange. The business can buy and sell its own stablecoins in the decentralized exchange, providing liquidity to cross-currency payments and possibly making a profit. (As with all financial exchange, profits are not guaranteed.)
### Choosing Fee Rates
Fees on tokens are optional. Higher fees earn more revenue when those tokens are used. On the other hand, high fees discourage customers from using your services. Consider the fees that are charged by other issuers, especially others with tokens backed by the same type of assets, as well as traditional payment systems outside of the XRP Ledger, such as wire fees. Choosing the right fee structure is a matter of balancing your pricing with what the market is willing to pay.
## Compliance Guidelines
Token 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)
# XRP Ledger Integration
This document uses the example of a fictional cryptocurrency exchange called ACME Exchange which decides to issue an EUR stablecoin on the XRP Ledger, to illustrate the overall process and flow of funds for a stablecoin.
## Before Integration
ACME, as a cryptocurrency exchange, already accepts withdrawals and deposits from customers using some system (such as an app or website). ACME has a _system of record_ to track how much each user holds with the exchange in each of several types of assets. Such a system can be modeled with a simple balance sheet, although in practice it probably involves databases, application servers, and various other infrastructure to ensure its reliability, information security, and so on.
In the following diagram, ACME Exchange starts with €5 on hand, including €1 that belongs to Bob, €2 that belongs to Charlie, and an additional €2 of equity that belongs to ACME itself. Alice deposits €5, so ACME adds her to its balance sheet and ends up with €10.
![Diagram: Alice sends €5 to ACME. ACME adds her balance to its balance sheet.](img/e2g-01.png)
**Assumptions:** To integrate with the XRP Ledger, we assume that an exchange such as ACME meets the following assumptions:
* ACME already has a system to accept deposits and withdrawals from some outside payment source.
* ACME waits for deposits to clear before crediting them in ACME's system of record.
* ACME always keeps enough funds on-hand to pay withdrawals on demand, subject to their terms and conditions.
* ACME can set fees, minimum withdrawals, and delay times for deposits and withdrawals as their business model demands.
## Sending into the XRP Ledger
Sending money _into_ the XRP Ledger involves issuing new stablecoins for an amount that ACME holds on behalf of one of its users. An example flow might look like this:
1. Alice asks to send €3 of her ACME balance into the XRP Ledger.
2. In its system of record, ACME debits Alice's balance €3.
3. ACME submits an XRP Ledger transaction, sending €3 to Alice's XRP Ledger address. The €3 is marked in the XRP Ledger as being "issued" by ACME (3 EUR.ACME).
**Assumptions:**
* Alice already has an address in the XRP Ledger separate from her ACME account. Alice manages her XRP Ledger address using a third-party client application (wallet).
![Diagram: ACME issues 3 EUR.ACME to Alice on the XRP Ledger](img/e2g-02.png)
<!--{# Disabled: UMLet version of this diagram.
{{ include_svg("img/gateway-to-xrpl.svg", "Diagram: ACME issues 3 EUR.ACME to Alice on the XRP Ledger") }}
#}-->
After this, Alice can send or trade her EUR.ACME to other users in the XRP Ledger at her discretion. At any time, ACME can query the XRP Ledger to see who currently holds its tokens.
### Requirements for Sending to XRP Ledger
There are several prerequisites that ACME must meet for this to happen:
- ACME sets aside the funds that back its stablecoin. There are several ways ACME may do this:
- ACME may create a XRP Ledger collateral account in ACME's system of record.
- ACME can store the funds allocated to the XRP Ledger in a separate bank account.
- If the stablecoin is backed by cryptocurrency, ACME can create a separate wallet to hold the funds allocated to the XRP Ledger, as publicly-verifiable proof of its reserves.
- ACME should control two separate XRP Ledger addresses. See [Issuing and Operational Addresses](account-types.html) for details.
- ACME must enable the Default Ripple flag on its issuing address for customers to send and receive its tokens.
- Alice must create an accounting relationship (trust line) from her XRP Ledger address to ACME's issuing address. She can do this from any XRP Ledger client application as long as she knows ACME's issuing address.
- ACME should publicize its issuing address on its website where customers can find it. It can also use an [`xrp-ledger.toml` file](xrp-ledger-toml.html) to publish the issuing address to automated systems.
- Alternatively, instead of sending a Payment, ACME can write Alice as a Check in the XRP Ledger. This does not move any money right away, but creates both the trust line and the tokens together when Alice cashes the Check.
- ACME must create a user interface for Alice to request for her funds from ACME to be sent into the XRP Ledger.
- ACME needs to know Alice's XRP Ledger address. ACME can have Alice input her XRP Ledger address as part of the interface, or ACME can require Alice to input and verify her XRP Ledger address in advance.
## Sending from XRP Ledger
A payment out of the XRP Ledger means the issuer receives a payment in the XRP Ledger, and credits a user in the issuer's system of record.
An example flow of a payment out of the XRP Ledger:
1. Bob sends an XRP Ledger transaction of €1 to ACME's issuing address.
2. In ACME's system of record, ACME credits Bob's balance €1.
3. Later, Bob can use ACME's own interface to withdraw the money to a separate account, such as requesting a bank deposit over the SEPA system (Europe) or ACH (United States), receiving a payment on another blockchain, or something else.
XRP Ledger Payments going to an issuer can be single-currency or cross-currency payments, but the amount the issuer receives is typically denominated in the stablecoin it issued.
### Requirements for Receiving from XRP Ledger
In addition to the requirements for sending into the XRP Ledger, there are several prerequisites that ACME must meet to process payments coming from the XRP Ledger:
- ACME must monitor its XRP Ledger addresses for incoming payments.
- ACME must know which user to credit in its system of record for the incoming payments.
- ACME should bounce unrecognized incoming payments back to their sender.
- Typically, the preferred method of recognizing incoming payments is through [destination tags](source-and-destination-tags.html).
## 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 take 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](#reliable-transaction-submission) when sending XRP Ledger transactions.
- [Robustly monitor for incoming payments](#robustly-monitoring-for-payments), and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a [partial payment](partial-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.
## Trading on the XRP Ledger
After the tokens have been created in the XRP Ledger, they can be freely transferred and traded by XRP Ledger users. There are several consequences of this situation:
- Anyone can buy/sell EUR.ACME on the XRP Ledger. If ACME issues multiple tokens, a separate trust line is necessary for each.
- This includes XRP Ledger users who do not have an account in ACME Exchange's systems. To withdraw the funds successfully from ACME, users still have to register with ACME.
- Optionally, ACME uses the [Authorized Trust Lines](#authorized-trust-lines) feature to limit who can hold EUR.ACME in the XRP Ledger.
- If ACME determines that a customer has acted in bad faith, ACME can [Freeze](#freeze) that user's accounting relationships to ACME in the XRP Ledger, so that the user can no longer trade in the issuer's tokens.
- XRP Ledger users trading and sending EUR.ACME to one another requires no intervention by ACME.
- All exchanges and balances in the XRP Ledger are publicly viewable.
The following diagram depicts an XRP Ledger payment sending 2 EUR.ACME from Alice to Charlie. ACME can query the XRP Ledger to see updates to its balances any time after the transaction has occurred:
![Diagram: Alice's sends 2 EUR.ACME from her trust line to Charlie's](img/e2g-03.png)
## Freeze
An issuer can freeze accounting relationships in the XRP Ledger to meet regulatory requirements:
* Issuers can freeze individual accounting relationships, in case a customer address shows suspicious activity or violates a issuer's terms of use.
* Issuers can freeze all tokens they issue, in case of a major security compromise or for migrating to a new issuing address.
* Furthermore, issuers can permanently opt out of their ability to freeze accounting relationships. This allows an issuer to assure its customers that it will continue to provide "physical-money-like" services. <!-- STYLE_OVERRIDE: will -->
For more information, see the [Freeze article](freezes.html).
## Authorized Trust Lines
The XRP Ledger's Authorized Trust Lines feature (formerly called "Authorized Accounts") enables an issuer to limit who can hold that issuer's tokens, so that unknown XRP Ledger addresses cannot hold the tokens.
For more information, see [Authorized Trust Lines](authorized-trust-lines.html).
## Source and Destination Tags
*Destination Tags* are a feature of XRP Ledger payments can be used to indicate the beneficiary or destination for a payment. For example, an XRP Ledger payment to an issuer may include a destination tag to indicate which customer should be credited for the payment. An issuer should keep a mapping of destination tags to accounts in the issuer's system of record.
Similarly, *Source Tags* indicate the originator or source of a payment. Most commonly, a Source Tag is included so that the recipient of the payment knows where to bounce the payment. When you bounce an incoming payment, use the Source Tag from the incoming payment as the Destination Tag of the outgoing (bounce) payment.
You can generate a destination tag on-demand when a customer intends to send money to you. For greater customer privacy, you should consider that destination tag valid only for that payment with the expected amount, and bounce or ignore any other transactions that reuse the same destination tag.
[Enable the Require Destination Tag setting](require-destination-tags.html) on your issuing and operational addresses so that customers must use a destination tag to indicate where funds should be credited when they send payments to you.
For more information, see [Source and Destination Tags](source-and-destination-tags.html).
# 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 may 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).
## Issuer Setup
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 the [Issue a Fungible Token tutorial](issue-a-fungible-token.html).
Settings you may 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](rippling.html) 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.
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][Payment] 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.
## 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 XRP Ledger 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](cross-currency-payments.html) and longer multi-hop (rippling) payments. If you naively perform pathfinding and attach the paths to your transaction, your payment may take a more expensive indirect route rather than failing if the direct path is not available; malicious users can even set this up to
- 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 whose 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.
<!-- STYLE_OVERRIDE: gateway, gateways -->
## See Also
- **Concepts:**
- [Tokens](tokens.html)
- [Decentralized Exchange](decentralized-exchange.html)
- [Source and Destination Tags](source-and-destination-tags.html)
- **Tutorials:**
- [Install `rippled`](install-rippled.html)
- [Set Up Secure Signing](secure-signing.html)
- [Issue a Fungible Token](issue-a-fungible-token.html)
- [Enable No Freeze](enable-no-freeze.html)
- [Freeze a Trust Line](freeze-a-trust-line.html)
- [Enact Global Freeze](enact-global-freeze.html)
- **References:**
- [Payment transaction][]
- [AccountSet transaction][]
- [TrustSet transaction][]
- [RippleState object](ripplestate.html)
- [account_lines method][]
- [gateway_balances method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}