ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-26 14:45:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Moving use cases

Browse Source
This commit is contained in:
ddawson
2022-12-12 08:59:09 -08:00
parent 06e96266d1
commit b3bab06288
8 changed files with 138 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

590
content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md
View File

@@ -1,590 +0,0 @@
---
html: become-an-xrp-ledger-gateway.html
parent: xrp-ledger-businesses.html
blurb: Stablecoin issuers link tokens in the XRP Ledger to assets in the outside world.
labels:
- Tokens
- Security
---
# Become a Stablecoin Issuer
**Stablecoin issuers** are businesses that link [tokens](tokens.html) in the XRP Ledger to assets in the outside world. An existing online financial institution can expand to issue a stablecoin in the the XRP Ledger. By doing so, the business can gain several advantages:
* By enabling its customers to send and receive value in the XRP Ledger, the business increases its value proposition to customers.
* By accepting payments from the XRP Ledger, the business increases the number of ways that customers can fund accounts at its business, even internationally.
* The business can use XRP Ledger-related services as a new source of revenue.
This guide explains the concepts and steps necessary to issue a stablecoin in the XRP Ledger, using a fictional online currency exchange named "ACME" and its customers as examples.
**Note:** Stablecoin issuers on the XRP Ledger were formerly called "gateways".
## Token Issuers Explained
There are several related business models that provide a way for money and other forms of value to move in and out of the XRP Ledger. Most of these business models fall into one of the following categories:
* A **Token Issuer** receives money (or other assets of value) outside of the XRP Ledger, and issues tokens in the XRP Ledger representing those assets. This provides a direct way for customers to get money in and out of the XRP Ledger. All currencies in the XRP Ledger, except for XRP, are tokens tied to a specific issuer.
* A **Private Exchange** holds XRP and lets its customers buy and sell that XRP in its own system. Most cryptocurrencies rely on private exchanges to provide a market for the cryptocurrency, but the XRP Ledger has [a currency exchange built into the protocol itself](decentralized-exchange.html).
* **Merchants** accept payment within the XRP Ledger in exchange for goods and services in the outside world.
This guide focuses on running a **token issuer**.
### 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 issued that are backed by balances 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).
Main article: [Trust Lines and Issuing](trust-lines-and-issuing.html).
### XRP
[**XRP**](xrp.html) 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. For more information on XRP, see the [XRP Overview](xrp-overview.html).
Token issuers do not need to accumulate or exchange XRP. They must only hold a small balance of XRP to meet the [reserve requirements](reserves.html) and pay the [cost of sending transactions](transaction-cost.html) through the network. The XRP equivalent of $10 USD should be enough for at least one year of transaction costs for a busy issuer.
Main article: [XRP](xrp.html).
### Liquidity and Currency Exchange
The XRP Ledger contains a [decentralized asset exchange](decentralized-exchange.html), where any user can place and fulfill bids to exchange XRP and tokens in any combination. [Cross-currency payments](cross-currency-payments.html) use the decentralized exchange to exchange currencies atomically when the transaction is executed. In this way, users who trade in the decentralized exchange provide the liquidity that makes cross-currency payments possible.
Traders who hold an issuer's tokens can provide liquidity to other popular currencies, without the issuer needing to float a large reserve in various destination currencies. The issuer also does not need to take on the risk of holding a variety of different tokens and assets. However, an issuer _may_ still want to provide liquidity to XRP or other popular tokens at a baseline rate, especially when their token is new to the exchange. If you do provide liquidity, **use a different address for trading than your issuing address.**
Liquidity providers can use the [HTTP / WebSocket APIs](http-websocket-apis.html), [client libraries](client-libraries.html), or another application to access the distributed exchange. It may also help client applications to display information about your business if you provide an [`xrp-ledger.toml` file](xrp-ledger-toml.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](issuing-and-operational-addresses.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.
### Hot and Cold Wallets
{% include '_snippets/issuing-and-operational-addresses-intro.md' %}
<!--{#_ #}-->
Main article: [Issuing and Operational Addresses](issuing-and-operational-addresses.html)
## Fees and Revenue Sources
There are several ways in which an issuer can seek to profit from XRP Ledger integration. These can include:
* Withdrawal and Deposit fees. Issuers typically charge a small fee (such as 1%) for the service of adding or removing money from the XRP Ledger. You have the power to determine the rate you credit people when they move money onto and off of the XRP Ledger through your tokens.
* Transfer fees. You can set a percentage fee to charge automatically when customers send each other tokens that you issued. This amount is debited from the XRP Ledger, decreasing your obligation each time your tokens change hands. See [Transfer Fees](#transfer-fees) for details.
* Indirect revenue from value added. XRP Ledger integration can provide valuable functionality for your customers that distinguishes your business from your competitors.
* Interest on XRP Ledger-backed funds. You can keep the collateral for the funds you issue in XRP Ledger in a bank account that earns interest. Make sure you can always access enough funds to service customer withdrawals.
* [Financial Exchange](#liquidity-and-currency-exchange). You also make offers to buy and sell your tokens in the XRP Ledger's 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
## Before Integration
Our example exchange, ACME, already accepts withdrawals and deposits from customers using some existing system, and uses its own system of record to track how much balance each user has with the exchange. Such a system can be modeled with a balance sheet and tracking how much currency each user has with ACME.
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
XRP Ledger payments can automatically bridge between currencies, but an issuer normally only sends single-currency payments that go directly to customers. This means debiting a customer's current balance in your system, and then sending the equivalent amount of tokens in the XRP Ledger to the customer's XRP Ledger address.
An example flow for a payment into the XRP Ledger:
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.
![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") }}
#}-->
### Requirements for Sending to XRP Ledger
There are several prerequisites that ACME must meet for this to happen:
- ACME sets aside money that is issued in the XRP Ledger. ACME can query the XRP Ledger to see who holds its tokens at any time. 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 ACME is a cryptocurrency exchange, ACME can create a separate wallet to hold the funds allocated to the XRP Ledger, as publicly-verifiable proof to customers that the issuer is solvent.
- ACME should control two separate XRP Ledger addresses. See [Issuing and Operational Addresses](issuing-and-operational-addresses.html) for details.
- ACME must enable the [Default Ripple Flag](#default-ripple) 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.
- ACME must create a user interface for Alice to send funds from ACME 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.
See [Sending Payments to Customers](#sending-payments-to-customers) for an example of how to send payments into the XRP Ledger.
## 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.
Payments going from the XRP Ledger to an issuer can be single-currency or cross-currency payments. An issuing address can only receive payments in XRP or in tokens that it previously issued.
### Requirements for Receiving from XRP Ledger
In addition to the [requirements for sending into the XRP Ledger](#requirements-for-sending-to-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.
- We recommend that ACME should [bounce any unrecognized incoming payments](#bouncing-payments) back to their sender.
- Typically, the preferred method of recognizing incoming payments is through [destination tags](#source-and-destination-tags).
## 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. We recommend the following precautions:
- Protect yourself against reversible deposits. XRP Ledger payments are irreversible, but many electronic money systems like credit cards or PayPal 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, specify the issuing address as the issuer of the currency. 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](#transfer-fees) 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](#disallow-xrp) 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](#require-auth) on all operational addresses so they cannot issue currency 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.
## 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 `rippled` server, or sign the transactions locally before sending them to a `rippled` server.
The examples in this document show API methods that include a secret key. This is only safe if you control `rippled` server yourself, *and* you connect to it over a connection that is secure from outside listeners. For instructions and examples of other secure configurations, see [Set Up Secure Signing](set-up-secure-signing.html).
## 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.
For examples of how to configure this setting, see the [Issue a Fungible Token tutorial](issue-a-fungible-token.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 strictly enforced, 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.
You should enable the Disallow XRP flag on your issuing and operational addresses unless you also use those addresses for XRP transactions. If you use the same addresses for withdrawals or deposits of XRP, you should leave this flag disabled.
For examples of how to configure this setting, see the [Issue a Fungible Token tutorial](issue-a-fungible-token.html).
## Require Auth
The Require Auth setting prevents all counterparties from holding balances issued by an address unless the address has specifically approved an accounting relationship with that counterparty. For more information, see [Authorized Trust Lines](authorized-trust-lines.html).
### Authorizing Trust Lines
If you are using the [Authorized Trust Lines](authorized-trust-lines.html) feature, customers cannot hold balances you issue unless you first authorize their accounting relationships to you in the XRP Ledger.
To authorize an accounting relationship, submit a TrustSet transaction from your issuing address, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as **0**, and enable the [`tfSetfAuth` flag](trustset.html#trustset-flags) for the transaction.
## 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](#transfer-fees), then ACME's issuing address's outstanding obligations decrease each time Bob and Charlie exchange ACME's tokens. See [Transfer Fees](#transfer-fees) for more information.
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](#transfer-fees) 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).
## Transfer Fees
The `TransferRate` setting defines a fee to charge for transferring tokens from one XRP Ledger address to another. See [Transfer Fees](transfer-fees.html) for more information.
For examples of how to configure this setting, see the [Issue a Fungible Token tutorial](issue-a-fungible-token.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 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. (The issuing address's total obligations in the XRP Ledger decrease by 0.05 EUR.ACME.) 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.
## 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.
One common pitfall is performing pathfinding before sending a payment to customers in the XRP Ledger. If you specify the issuers correctly, the [default paths](paths.html#default-paths) can deliver the currency as intended.
The following is an example of using a locally-hosted `rippled`'s [submit method][] to send a payment from the operational address `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` to the customer address `raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n`, sending and delivering funds issued by the issuing address `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW`.
Request:
```
{
"method": "submit",
"params": [{
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
"tx_json": {
"TransactionType": "Payment",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
"Amount": {
"currency": "USD",
"value": "0.13",
"issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"
},
"SendMax": {
"currency": "USD",
"value": "0.13065",
"issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"
},
"Fee": "10000"
}
}]
}
```
*Reminder: Don't send your secret to a server you do not control.*
Response:
```
{
"result": {
"engine_result": "tesSUCCESS",
"engine_result_code": 0,
"engine_result_message": "The transaction was applied. Only final in a validated ledger.",
"status": "success",
"tx_blob": "1200002280000000240000016561D4449E57D63540000000000000000000000000005553440000000000204288D2E47F8EF6C99BCC457966320D1240971168400000000000271069D444A4413C6628000000000000000000000000005553440000000000204288D2E47F8EF6C99BCC457966320D12409711732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7446304402207B75D91DC0EEE613A94E05FD5D031568D8A763E99697FF6328745BD226DA7D4E022005C75D7215FD62CB8E46C55B29FCA8E3FC62FDC55DF300597089DD29863BD3CD81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143A4C02EA95AD6AC3BED92FA036E0BBFB712C030C",
"tx_json": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Amount": {
"currency": "USD",
"issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"value": "0.13"
},
"Destination": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
"Fee": "10000",
"Flags": 2147483648,
"SendMax": {
"currency": "USD",
"issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"value": "0.13065"
},
"Sequence": 357,
"SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
"TransactionType": "Payment",
"TxnSignature": "304402207B75D91DC0EEE613A94E05FD5D031568D8A763E99697FF6328745BD226DA7D4E022005C75D7215FD62CB8E46C55B29FCA8E3FC62FDC55DF300597089DD29863BD3CD",
"hash": "37B4AA5C77A8EB889164CA012E6F064A46B6B7B51677003FC3617F614608C60B"
}
}
}
```
In particular, note the following features of the [Payment transaction][]:
- No `Paths` field. The payment only succeeds if it can use a [default path](paths.html#default-paths), which is preferable. Using less direct paths can become much more expensive.
- The `issuer` of both the `SendMax` and the `Amount` is the issuing address. This ensures that the transaction sends and delivers tokens from the intended issuer, and not from another issuer using the same currency code.
- The `value` of the `SendMax` amount is slightly higher than the destination `Amount`, to compensate for the [transfer fee](#transfer-fees). In this case, the transfer fee is 0.5%, so the `SendMax` amount is exactly 1.005 times the destination `Amount`.
## 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](set-up-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' %}

612
content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.ja.md
View File

@@ -1,612 +0,0 @@
---
html: list-xrp-as-an-exchange.html
parent: xrp-ledger-businesses.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では以下を行う必要があります。
* 新しい[アカウント](#アカウント)を作成して維持します
* [バランスシート](#バランスシート)を作成して維持します
関連項目:
* [ゲートウェイコンプライアンス](become-an-xrp-ledger-gateway.html#compliance-guidelines) — ゲートウェイと取引所は異なりますが、取引所は地域の規制に準拠し、適切な当局の監督下になければなりません。
* [Requirements for Sending to XRP Ledger](become-an-xrp-ledger-gateway.html#requirements-for-sending-to-xrp-ledger)
* [Requirements for Receiving from XRP Ledger](become-an-xrp-ledger-gateway.html#requirements-for-receiving-from-xrp-ledger)
* [ゲートウェイの注意事項](become-an-xrp-ledger-gateway.html#precautions)
### Partial Payments
追加の前に、取引所は[Partial Payments](partial-payments.html)機能について知っておく必要があります。この機能を使用すると、XRP Ledgerのユーザーは、`SendMax`を増やさずに、受取金額を減額して、支払いを正常に送信できます。この機能は、送信者側に追加費用が発生せず、[支払いの返金](become-an-xrp-ledger-gateway.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と顧客の資金を維持する[ _コールドウォレット_ ](issuing-and-operational-addresses.html#発行アドレス)。取引所にとって、これはユーザーが[預入れ](#取引所へのxrpの入金)をするアドレスです。 セキュリティを最適化するため、このアカウントのシークレットキーはオフラインにする必要があります。
取引所のコールドウォレットが悪用されると、以下のような結果が生じるおそれがあります。
* 不正使用者が、コールドウォレットの全XRPにアクセスできます。
* マスターキーが悪用されると、不正使用者は（マスターキーを無効にし、新しいレギュラーキーや署名者リストを設定することにより）そのコールドウォレットを恒久的に制御できます。これにより、その不正使用者は今後そのコールドウォレットで受信するすべてのXRPも制御できるようになります。
* このような事態が発生した場合には、取引所は新しいコールドウォレットアドレスを作成し、顧客にその新しいアドレスを伝える必要があります。
* レギュラーキーや署名者リストが悪用された場合には、取引所はコールドウォレットの制御を取り戻すことができます。ただし、不正使用者の行為の中には、以下のように簡単に元に戻せないものもあります。 <!-- STYLE_OVERRIDE: easily -->
* 不正使用者が、コールドウォレットを使用してXRP Ledgerで通貨を発行しても、その通貨の価値はだれにも認められません。（取引所が明示的にゲートウェイでもあると示した場合を除きます）。
* 不正使用者が、アカウントにasfRequireAuthフラグを設定した場合。この設定は解除できません。ただし、これは通貨の発行のみに関係し、ゲートウェイではない取引所には影響しません。不正使用者がマスターキーで設定または設定解除したその他の設定は、元に戻すことができます。
* 顧客のXRP出金や入金を管理する、日常業務を遂行するための1つ以上の[ _ホットウォレット_ ](issuing-and-operational-addresses.html#運用アドレス)。例えば、ホットウォレットがあれば、取引所はこの種のXRPの自動送金を安全にサポートできます。出金要求にただちに応じるため、ホットウォレットはオンラインである必要があります。
不正使用されたホットウォレットによって発生するおそれのある結果についての詳細は、[Operational Account Compromise](issuing-and-operational-addresses.html#運用アドレスの漏えい)を参照してください。
* オプションとして、コールドウォレットとホットウォレットの間で追加のセキュリティ層を提供する、1つ以上のウォームウォレット。ホットウォレットとは異なり、ウォームウォレットのシークレットキーはオンラインである必要はありません。さらに、ウォームウォレットのシークレットキーを複数の人に分散し、[マルチ署名](multi-signing.html)を導入してセキュリティを強化することもできます。
不正使用されたウォームウォレットによって発生するおそれのある結果についての詳細は、[スタンバイアドレスの漏えい](issuing-and-operational-addresses.html#スタンバイアドレスの漏えい)を参照してください。
関連項目:
* ["Suggested Business Practices" in the _Gateway Guide_](become-an-xrp-ledger-gateway.html#suggested-business-practices)
* [発行アドレスと運用アドレス](issuing-and-operational-addresses.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](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にある自身のアカウントに関連付けます。これは、[ _宛先タグ_ ](become-an-xrp-ledger-gateway.html#source-and-destination-tags)と呼ばれます。（これを使用するには、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' %}

630
content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md
View File

@@ -1,630 +0,0 @@
---
html: list-xrp-as-an-exchange.html
parent: xrp-ledger-businesses.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](become-an-xrp-ledger-gateway.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](become-an-xrp-ledger-gateway.html#requirements-for-sending-to-xrp-ledger)
* [Requirements for Receiving from XRP Ledger](become-an-xrp-ledger-gateway.html#requirements-for-receiving-from-xrp-ledger)
* [Precautions](become-an-xrp-ledger-gateway.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](become-an-xrp-ledger-gateway.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](accounts.html#deletion-of-accounts). 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](issuing-and-operational-addresses.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_](issuing-and-operational-addresses.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_](issuing-and-operational-addresses.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](issuing-and-operational-addresses.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](issuing-and-operational-addresses.html#standby-address-compromise).
See also:
* ["Suggested Business Practices" in the _Gateway Guide_](become-an-xrp-ledger-gateway.html#suggested-business-practices)
* [Issuing and Operational Addresses](issuing-and-operational-addresses.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](accounts.html#addresses) of the XRP holder. The counterparty to these balances is the XRP Ledger. For more information, see [XRP](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_](become-an-xrp-ledger-gateway.html#source-and-destination-tags). (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](set-up-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' %}

195
content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.ja.md
View File

@@ -1,195 +0,0 @@
---
html: list-your-exchange-on-xrp-charts.html
parent: xrp-ledger-businesses.html
blurb: 各自の取引所とそのXRP取引、およびオーダーブックのデータをXRP Chartsに登録します。
status: removed
---
# XRP Chartsへの取引所の登録
XRP Chartsは、XRP Ledgerネットワークとそのアカウントおよびトランザクションに関するデータの他に、外部取引所の[XRPマーケットデータ](https://xrpcharts.ripple.com/#/xrp-markets)も提供します。このチュートリアルでは、各自の取引所とそのXRP取引、およびオーダーブックのデータをXRP Chartsに登録する方法を説明します。
XRP Chartsの取引所リストに掲載されるには、以下のデータを使用可能にしておく必要があります。取引所に、以下のデータを提供できる既存のRESTful APIエンドポイントがある場合は、タスク1と2を実行する際に必要な開発作業はほとんどありません。
1. [最近実行された取引を返すRESTful APIエンドポイントの提供](#最近実行された取引を返すrestful-apiエンドポイントの提供)。
2. [現行オーダーブックのデータを返すRESTful APIエンドポイントの提供](#現行オーダーブックのデータを返すrestful-apiエンドポイントの提供)。
次に、[XRP Chartsへの取引所登録依頼の送信](#xrp-chartsへの取引所登録依頼の送信)を行う必要があります。
エンドポイントの仕様についてのご質問は、<xrpcharts_support@ripple.com>までお問い合わせください。
## 最近実行された取引を返すRESTful APIエンドポイントの提供
特定のXRPマーケットで実行された最新の500～1,000件の個別取引を返すRESTful APIエンドポイントを提供します。
取引の取りこぼしがないようにするため、XRP Chartsはエンドポイントを5～30秒間隔で頻繁に照会します。これは重複する取引データを含む応答を取得することを目的としています。エンドポイントにより適用されるレート制限が、この照会頻度に対応できることを確認してください。XRP Chartsは、取引が重複する場合でも一意の取引データのみを記録します。
XRP Chartsがレート制限を上回る頻度でエンドポイントを照会する必要がある場合、XRP Chartsから、レート制限を調整するか、`last_tid`パラメーターを指定するように求められます。
### 要求フォーマット
以下のような要求フォーマットを指定します。
```
GET {api_base_url}/v1/trades
```
#### 認証
XRP Chartsでは、一般にアクセス可能なエンドポイントを使用することが望まれます。
#### パラメーター
応答で返される取引をXRP Chartsで絞り込むことを可能にするパラメーターを指定します。パラメーターのフィールド名は一例です。他の名前を使用できます。エンドポイントでは省略可能なパラメーターを指定する必要はありませんが、このようなパラメーターは有用です。
| フィールド | 型 | 説明 |
|:-----------|:--------|:------------------------------------------------------|
| `market` | 文字列 | XRPがベース通貨またはクオート通貨のいずれかである特定の市場で実施された取引を返します。提案されるフォーマット（`<basecurrency>_<countercurrency>`）を使用して、有効な値（`xrp_btc`、`btc_xrp`、`xrp_usd`、`usd_xrp`など）を指定します。 |
| `last_tid` | 整数 | _（省略可）_ 特定の取引IDの後で実行された取引を返します。たとえば、XRP Chartsではこのパラメーターを使用して、サイトデータに記録されている最後の取引セット以降に行われたすべての取引を取得します。これにより、すべての取引が確実に記録されます。 |
| `limit` | 整数 | _（省略可）_ 応答で特定の数の取引のみを返します。 |
### 応答フォーマット
正常に終了した場合の応答は、各取引を表すオブジェクトのJSON配列である必要があります。パラメーターのフィールド名は一例です。他の名前を使用できます。エンドポイントでは省略可能なパラメーターを指定する必要はありませんが、このようなパラメーターは有用です。
| フィールド | 型 | 説明 |
|:------------|:-----------------|:--------------------------------------------|
| `price` | 文字列または数値 | 取引の為替レート。 |
| `amount` | 文字列または数値 | 売買するXRPの額。 |
| `timestamp` | 文字列 | [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)の日時フォーマットまたは[Unixの時刻](https://en.wikipedia.org/wiki/Unix_time)フォーマットでの取引実行時刻。 |
| `tid` | 整数 | _（省略可）_ 取引の一意のID。整数のシーケンス番号であれば理想的です。 |
| `type` | 文字列 | _（省略可）_ 取引のタイプ。有効な値には`buy`や`sell`などがあります。 |
| `size` | 文字列または数値 | _（省略可）_ 取引されたクオート通貨の額。 |
| `count` | 整数 | _（省略可）_ 応答で返す取引オブジェクトの数。 |
### 例
#### 要求の例
```
GET https://api.example.com/v1/trades?market=xrp_btc&last_tid=75208825&limit=500
```
#### 応答の例
```json
{
"trades":[
{
"tid":75209326,
"type":"buy",
"price":"0.57201",
"amount":"4954.0744",
"size":"2833.7801",
"timestamp":"2018-10-01T12:35:11.000Z"
},
...
{
"tid":75208826,
"type":"sell",
"price":"0.57201",
"amount":"4954.0744",
"size":"2833.7801",
"timestamp":"2018-10-01T12:31:16.000Z"
}
],
"count":"500"
}
```
## 現行オーダーブックのデータを返すRESTful APIエンドポイントの提供
特定マーケットの現行オーダーブックに関するデータを返すRESTful APIエンドポイントを提供します。
XRP Chartsはこのエンドポイントを約30秒間隔で照会します。
### 要求フォーマット
以下のような要求フォーマットを指定します。
```
GET {api_base_url}/v1/orderbook
```
#### 認証
XRP Chartsでは、一般にアクセス可能なエンドポイントを使用することが望まれます。
#### パラメーター
以下のパラメーターを指定します。パラメーターのフィールド名は一例です。他の名前を使用できます。
| `Field` | 型 | 説明 |
|:---------|:-------|:---------------------------------------------------------|
| `market` | 文字列 | XRPがベース通貨またはクオート通貨のいずれかである現行オーダーブックを返します。提案されるフォーマット（`<basecurrency>_<countercurrency>`）を使用して、有効な値（`xrp_btc`、`btc_xrp`、`xrp_usd`、`usd_xrp`など）を指定します。 |
### 応答フォーマット
正常に終了した場合の応答は、現行の売値と買値からなる配列とタイムスタンプを含むJSONオブジェクトである必要があります。応答にはオーダーブック全体が含まれている必要はありません。必要とされるのは、マーケットでの現在のXRP流動性を把握するのに十分なデータだけです。パラメーターのフィールド名は一例です。他の名前を使用できます。
| フィールド | 型 | 説明 |
|:------------|:-----------------|:--------------------------------------------|
| `timestamp` | 文字列 | [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)の日時フォーマットまたは[Unixの時刻](https://en.wikipedia.org/wiki/Unix_time)フォーマットの応答送信時刻。 |
| `bids` | オブジェクトの配列 | オーダーブックでの売値。配列の各オブジェクトには、オファーで示された`price`とその価格で使用可能な`amount`が含まれている必要があります。 |
| `asks` | オブジェクトの配列 | オーダーブックでの買値。配列の各オブジェクトには、オファーで示された`price`とその価格で使用可能な`amount`が含まれている必要があります。 |
### 例
#### 要求の例
```
GET https://api.example.com/v1/orderbook?market=xrp_btc
```
#### 応答の例
```json
{
"timestamp":"2018-10-01T12:41:16.000Z",
"bids":[
{
"price":0.00007103,
"amount":140
},
{
"price":0.000071,
"amount":135
},
{
"price":0.00007092,
"amount":5266
}
],
"asks":[
{
"price":0.00007108,
"amount":140
},
{
"price":0.00007109,
"amount":84
},
{
"price":0.0000711,
"amount":10650
}
]
}
```
## XRP Chartsへの取引所登録依頼の送信
XRP Chartsへの取引所登録のご依頼は、<xrpcharts_support@ripple.com>までご連絡ください。
依頼には、APIドキュメントへのリンクを必ず記述してください。

203
content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md
View File

@@ -1,203 +0,0 @@
---
html: list-your-exchange-on-xrp-charts.html
parent: xrp-ledger-businesses.html
blurb: Have your exchange and its XRP trade and order book data listed on XRP Charts.
status: removed
---
# List Your Exchange on XRP Charts
In addition to providing data about the XRP Ledger network and its accounts and transactions, XRP Charts also provides [XRP market data](https://xrpcharts.ripple.com/#/xrp-markets) from external exchanges. This tutorial describes how to have your exchange and its XRP trade and order book data listed on XRP Charts.
To enable XRP Charts to list your exchange, you'll need to make the following data available. Your exchange may have existing RESTful API endpoints that can deliver this data. If so, there may be little to no development effort required on your part to complete tasks 1 and 2.
1. [Provide a Recently Executed Trades RESTful API endpoint](#provide-a-recently-executed-trades-endpoint).
2. [Provide a Current Order Book RESTful API endpoint](#provide-a-current-order-book-endpoint).
Then, you'll need to [send an exchange listing request to XRP Charts](#send-an-exchange-listing-request-to-xrp-charts).
If you have any questions about endpoint specifications, contact <xrpcharts_support@ripple.com>. <!-- SPELLING_IGNORE: xrpcharts_support -->
## Provide a Recently Executed Trades Endpoint
Provide a RESTful API endpoint that returns the most recent 500-1,000 individual trades executed in a particular XRP market.
To ensure that it doesn't miss a trade, XRP Charts queries the endpoint between every 5 and 30 seconds, aiming to get responses that have overlapping trade data. Ensure that any rate limit enforced by your endpoint can accommodate this query frequency. XRP Charts records unique trade data only, even if it gets overlapping trades.
If XRP Charts needs to query your endpoint at a frequency that exceeds your rate limit, XRP Charts may request that you adjust the rate limit or provide the `last_tid` parameter.
### Request Format
Provide a request format like the following:
```
GET {api_base_url}/v1/trades
```
#### Authentication
XRP Charts prefers to work with a publicly accessible endpoint.
#### Parameters
Provide parameters that help XRP Charts filter trades returned in the response. The parameter field names are examples. You can use other names. Your endpoint doesn't have to provide the optional parameters, but they are useful.
| Field | Type | Description |
|:-----------|:--------|:------------------------------------------------------|
| `market` | String | Returns trades executed in a particular market in which XRP is either the base or counter currency. Use a suggested format of `<basecurrency>_<countercurrency>` to provide valid values like `xrp_btc`, `btc_xrp`, `xrp_usd`, or `usd_xrp`, for example. |
| `last_tid` | Integer | _(Optional)_ Returns trades executed after a specific trade ID. For example, XRP Charts can use this parameter to get all trades after the last set of trades recorded in site data, ensuring that it has recorded all trades. |
| `limit` | Integer | _(Optional)_ Returns no more than a specific number of trades in a response. |
### Response Format
A successful response must be a JSON array of objects, one for each trade. The parameter field names are examples. You can use other names. Your endpoint doesn't have to provide the optional parameters, but they are useful.
| Field | Type | Description |
|:------------|:-----------------|:--------------------------------------------|
| `price` | String or Number | Exchange rate of the trade. |
| `amount` | String or Number | Amount of XRP bought or sold. |
| `timestamp` | String | Time at which the trade was executed in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date-time format or [Unix time](https://en.wikipedia.org/wiki/Unix_time) format. |
| `tid` | Integer | _(Optional)_ Unique identifier of the trade. Ideally, make this a sequential integer. |
| `type` | String | _(Optional)_ Type of trade. For example, valid values can include `buy` and `sell`. |
| `size` | String or Number | _(Optional)_ Amount of counter currency traded. |
| `count` | Integer | _(Optional)_ Number of trade objects returned in the response. |
### Examples
#### Example Request
```
GET https://api.example.com/v1/trades?market=xrp_btc&last_tid=75208825&limit=500
```
#### Example Response
```json
{
"trades":[
{
"tid":75209326,
"type":"buy",
"price":"0.57201",
"amount":"4954.0744",
"size":"2833.7801",
"timestamp":"2018-10-01T12:35:11.000Z"
},
...
{
"tid":75208826,
"type":"sell",
"price":"0.57201",
"amount":"4954.0744",
"size":"2833.7801",
"timestamp":"2018-10-01T12:31:16.000Z"
}
],
"count":"500"
}
```
## Provide a Current Order Book Endpoint
Provide a RESTful API endpoint that returns data about the current order book in a particular market.
XRP Charts will query this endpoint about every 30 seconds.
### Request Format
Provide a request format like the following:
```
GET {api_base_url}/v1/orderbook
```
#### Authentication
XRP Charts prefers to work with a publicly accessible endpoint.
#### Parameter
Provide the following parameter. The parameter field name is an example. You can use another name.
| `Field` | Type | Description |
|:---------|:-------|:---------------------------------------------------------|
| `market` | String | Returns the current order book in which XRP is either the base or counter currency. Use a suggested format of `<basecurrency>_<countercurrency>` to provide valid values like `xrp_btc`, `btc_xrp`, `xrp_usd`, or `usd_xrp`, for example. |
### Response Format
A successful response must be a JSON object that includes a timestamp and arrays of current bids and asks. The response does not need to provide the entire order book, but provides enough data to provide a good idea of the current XRP liquidity available in the market. The parameter field names are examples. You can use other names.
| Field | Type | Description |
|:------------|:-----------------|:--------------------------------------------|
| `timestamp` | String | Time at which the response was sent in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date-time format or [Unix time](https://en.wikipedia.org/wiki/Unix_time) format. |
| `bids` | Array of objects | Bids in the order book. Each object in the array must provide the offered `price` and `amount` available at that price. |
| `asks` | Array of objects | Asks in the order book. Each object in the array must provide the offered `price` and `amount` available at that price. |
### Examples
#### Example Request
```
GET https://api.example.com/v1/orderbook?market=xrp_btc
```
#### Example Response
```json
{
"timestamp":"2018-10-01T12:41:16.000Z",
"bids":[
{
"price":0.00007103,
"amount":140
},
{
"price":0.000071,
"amount":135
},
{
"price":0.00007092,
"amount":5266
}
],
"asks":[
{
"price":0.00007108,
"amount":140
},
{
"price":0.00007109,
"amount":84
},
{
"price":0.0000711,
"amount":10650
}
]
}
```
## Send an Exchange Listing Request to XRP Charts
Contact <xrpcharts_support@ripple.com> to request that your exchange be listed on XRP Charts. Be sure to include a link to your API documentation.
## See Also
- **Concepts:**
- [Software Ecosystem](software-ecosystem.html)
- **Tutorials:**
- [List XRP on Your Exchange](list-xrp-as-an-exchange.html)
- **References:**
- [Ripple Data API Reference](data-api.html)