|
|
|
|
@@ -1,62 +1,69 @@
|
|
|
|
|
---
|
|
|
|
|
html: become-an-xrp-ledger-gateway.html
|
|
|
|
|
parent: xrp-ledger-businesses.html
|
|
|
|
|
blurb: Gateways are the businesses that link the XRP Ledger to the rest of the world. This tutorial demonstrates how an existing online financial institution can expand to act as a gateway in the the XRP Ledger.
|
|
|
|
|
blurb: Stablecoin issuers link tokens in the XRP Ledger to assets in the outside world.
|
|
|
|
|
labels:
|
|
|
|
|
- Tokens
|
|
|
|
|
- Security
|
|
|
|
|
---
|
|
|
|
|
# Become an XRP Ledger Gateway
|
|
|
|
|
# Become a Stablecoin Issuer
|
|
|
|
|
|
|
|
|
|
**Gateways** are the businesses that link the XRP Ledger to the rest of the world. An existing online financial institution can expand to act as a gateway in the the XRP Ledger. By becoming an XRP Ledger gateway, a financial services business can gain several advantages:
|
|
|
|
|
**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 document explains the concepts and steps necessary to become an XRP Ledger gateway. In this document, we use a fictional online currency exchange named "ACME" and its customers as examples, to show how ACME can expand its business to include being an XRP Ledger gateway.
|
|
|
|
|
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".
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Gateways Explained
|
|
|
|
|
## Token Issuers Explained
|
|
|
|
|
|
|
|
|
|
{% include '_snippets/gateways-intro.md' %}
|
|
|
|
|
<!--_ -->
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
This guide focuses on running an **issuing gateway**.
|
|
|
|
|
* 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.
|
|
|
|
|
|
|
|
|
|
### Trust Lines and Issued Currencies
|
|
|
|
|
This guide focuses on running a **token issuer**.
|
|
|
|
|
|
|
|
|
|
All assets in the XRP Ledger, except for the native cryptocurrency XRP, are represented as _issued currencies_, which are digital balances that represent currency or assets of value held by an issuer. The XRP Ledger has a system of directional accounting relationships, called _trust lines_, to make sure that users only hold issued currencies from counterparties they trust.
|
|
|
|
|
### 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, without going through a gateway or liquidity provider. This helps make XRP a convenient bridge currency. For more information on XRP, see the [XRP Overview](xrp-overview.html).
|
|
|
|
|
[**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).
|
|
|
|
|
|
|
|
|
|
Issuing gateways 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 gateway.
|
|
|
|
|
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 issued currencies in any combination. [Cross-currency payments](cross-currency-payments.html) use the decentralized exchange to convert currency atomically when the transaction is executed. In this way, users who choose make offers in the decentralized exchange provide the liquidity that makes it possible to trade issued currencies.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Currency traders who hold a gateway's issued currencies can provide liquidity to other popular currencies, without the gateway needing to float a large reserve in various destination currencies. The gateway also does not need to take on the risk of holding a variety of currencies. However, a gateway _may_ still want to provide liquidity to XRP or other popular currencies at a baseline rate, especially when the gateway is new to the exchange. If you do provide liquidity, **use a different address for trading than your issuing address.**
|
|
|
|
|
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 surface information about your gateway to clients if you provide an [`xrp-ledger.toml` file](xrp-ledger-toml.html).
|
|
|
|
|
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 gateway's issued currency in the XRP Ledger comes directly from the trust that customers can redeem the issued balance from the gateway when needed. We recommend the following precautions to reduce the risk of business interruptions:
|
|
|
|
|
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).
|
|
|
|
|
* Read and stay up-to-date with [Gateway Bulletins](#gateway-bulletins), which provide news and suggestions for XRP Ledger gateways.
|
|
|
|
|
* Complete the XRP Ledger Foundation's [token issuer self-assessment](https://foundation.xrpl.org/token-assessment-framework/).
|
|
|
|
|
* Publicize all your policies and fees.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -70,23 +77,23 @@ Main article: [Issuing and Operational Addresses](issuing-and-operational-addres
|
|
|
|
|
|
|
|
|
|
## Fees and Revenue Sources
|
|
|
|
|
|
|
|
|
|
There are several ways in which a gateway can seek to profit from XRP Ledger integration. These can include:
|
|
|
|
|
There are several ways in which an issuer can seek to profit from XRP Ledger integration. These can include:
|
|
|
|
|
|
|
|
|
|
* Withdrawal and Deposit fees. Gateways 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 gateway.
|
|
|
|
|
* Transfer fees. You can set a percentage fee to charge automatically when customers send each other issued currencies created by your issuing address. This amount is debited from the XRP Ledger, decreasing your obligation each time your issued currencies change hands. See [Transfer Fees](#transfer-fees) for details.
|
|
|
|
|
* 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). A gateway can also make offers to buy and sell its issued currencies for other issued currencies in the XRP Ledger, providing liquidity to cross-currency payments and possibly making a profit. (As with all financial exchange, profits are not guaranteed.)
|
|
|
|
|
* [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 imposed by gateways are optional. Higher fees earn more revenue when a gateway's services are used. On the other hand, high fees discourage customers from using your services. Consider the fees that are charged by other gateways, especially ones issuing similar currencies, 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.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Gateway Compliance
|
|
|
|
|
## Compliance Guidelines
|
|
|
|
|
|
|
|
|
|
Gateways 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.
|
|
|
|
|
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)
|
|
|
|
|
|
|
|
|
|
@@ -104,7 +111,7 @@ KYC is critical for financial institutions and related businesses to mitigate ri
|
|
|
|
|
|
|
|
|
|
See also:
|
|
|
|
|
|
|
|
|
|
- [Customer Identification Program (USA FFIEC)](https://bsaaml.ffiec.gov/manual/RegulatoryRequirements/01)
|
|
|
|
|
- [(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)
|
|
|
|
|
|
|
|
|
|
@@ -222,9 +229,9 @@ In the following diagram, ACME Exchange starts with €5 on hand, including €1
|
|
|
|
|
* 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 from Gateway to the XRP Ledger
|
|
|
|
|
## Sending into the XRP Ledger
|
|
|
|
|
|
|
|
|
|
XRP Ledger payments can automatically bridge between currencies, but an issuing gateway 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 issued currencies in the XRP Ledger to the customer's XRP Ledger address.
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
@@ -248,12 +255,12 @@ An example flow for a payment into the 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 issued currencies at any time. There are several ways ACME may do this:
|
|
|
|
|
- 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 gateway is solvent.
|
|
|
|
|
- ACME must control an address in the XRP Ledger. Ripple's best practices recommend using a separate issuing address and operational address. 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 issued currencies.
|
|
|
|
|
- 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.
|
|
|
|
|
@@ -262,16 +269,16 @@ There are several prerequisites that ACME must meet for this to happen:
|
|
|
|
|
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 to Gateway
|
|
|
|
|
## Sending from XRP Ledger
|
|
|
|
|
|
|
|
|
|
A payment out of the XRP Ledger means the Gateway receives a payment in the XRP Ledger, and credits a user in the gateway's system of record.
|
|
|
|
|
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 a gateway can be single-currency or cross-currency payments. The gateway's issuing address can only receive issued currencies it created (or XRP).
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
@@ -285,12 +292,12 @@ In addition to the [requirements for sending into the XRP Ledger](#requirements-
|
|
|
|
|
|
|
|
|
|
## Precautions
|
|
|
|
|
|
|
|
|
|
Processing payments to and from the XRP Ledger naturally comes with some risks, so a gateway should be sure to take care in implementing these processes. We recommend the following 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 issued currencies in the XRP Ledger.
|
|
|
|
|
- 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 Ripple, 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.
|
|
|
|
|
- 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.
|
|
|
|
|
@@ -300,14 +307,14 @@ Processing payments to and from the XRP Ledger naturally comes with some risks,
|
|
|
|
|
- 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 Ripple
|
|
|
|
|
## Trading on the XRP Ledger
|
|
|
|
|
|
|
|
|
|
After the issued currencies 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:
|
|
|
|
|
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 Ripple. If ACME issues multiple currencies on Ripple, a separate trust line is necessary for each.
|
|
|
|
|
- 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 gateway's issued currencies.
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
@@ -319,38 +326,38 @@ The following diagram depicts an XRP Ledger payment sending 2 EUR.ACME from Alic
|
|
|
|
|
|
|
|
|
|
## Freeze
|
|
|
|
|
|
|
|
|
|
A gateway can freeze accounting relationships in the XRP Ledger to meet regulatory requirements:
|
|
|
|
|
An issuer can freeze accounting relationships in the XRP Ledger to meet regulatory requirements:
|
|
|
|
|
|
|
|
|
|
* Gateways can freeze individual accounting relationships, in case a customer address shows suspicious activity or violates a gateway's terms of use.
|
|
|
|
|
* Gateways can freeze all accounting relationships to their issuing address, in case of a major security compromise or for migrating to a new issuing address.
|
|
|
|
|
* Furthermore, gateways can permanently opt out of their ability to freeze accounting relationships. This allows a gateway to assure its customers that it will continue to provide "physical-money-like" services. <!-- STYLE_OVERRIDE: will -->
|
|
|
|
|
* 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 a gateway to limit who can hold that gateway's issued currencies, so that unknown XRP Ledger addresses cannot hold the currency the gateway issues. Ripple feels this is *not necessary* in most cases, since gateways have full control over the process of redeeming XRP Ledger balances for value in the outside world. (You can collect customer information and impose limits on withdrawals at that stage without worrying about what happens within the XRP Ledger.)
|
|
|
|
|
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 a gateway may include a destination tag to indicate which customer should be credited for the payment. A gateway should keep a mapping of destination tags to accounts in the gateway's system of record.
|
|
|
|
|
*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.
|
|
|
|
|
|
|
|
|
|
Ripple recommends making a user interface to generate a destination tag on-demand when a customer intends to send money to the gateway. You should consider that destination tag valid only for a payment with the expected amount. Later, bounce any other transactions that reuse the same destination tag.
|
|
|
|
|
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 `RequireDest` flag](require-destination-tags.html) on your issuing and operational addresses so that customers must use a destination tag to indicate where funds should go when they send XRP Ledger payments to your gateway.
|
|
|
|
|
[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).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Gateway Bulletins
|
|
|
|
|
|
|
|
|
|
Historically, Ripple (the company) issued gateway bulletins to introduce new features or discuss topics related to compliance and risk. Gateway Bulletins are listed here in reverse chronological order.
|
|
|
|
|
Historically, Ripple (the company) published gateway bulletins to introduce new XRP Ledger features or discuss topics related to compliance and risk for issuers. Gateway Bulletins are listed here in reverse chronological order.
|
|
|
|
|
|
|
|
|
|
- May 13, 2015 - [GB-2015-06 Gateway Bulletin: Corrections to Autobridging (PDF)](assets/pdf/GB-2015-06.pdf) <!-- SPELLING_IGNORE: autobridging -->
|
|
|
|
|
- April 17, 2015 - [GB-2015-05 Historical Ledger Query Migration](assets/pdf/GB-2015-05.pdf)
|
|
|
|
|
@@ -372,14 +379,14 @@ Historically, Ripple (the company) issued gateway bulletins to introduce new fea
|
|
|
|
|
|
|
|
|
|
## Infrastructure
|
|
|
|
|
|
|
|
|
|
For the gateway's own security as well as the stability of the network, each gateway should run its own `rippled` servers including one [validator](rippled-server-modes.html#validators).
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
* [`rippled`](http-websocket-apis.html) provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core XRP Ledger functionality.
|
|
|
|
|
* [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.
|
|
|
|
|
|
|
|
|
|
@@ -393,157 +400,26 @@ The examples in this document show API methods that include a secret key. This i
|
|
|
|
|
|
|
|
|
|
## Default Ripple
|
|
|
|
|
|
|
|
|
|
The Default Ripple flag controls whether the balances in an accounting relationship [allowed to ripple](rippling.html) by default. Rippling is what allows customers to trade issued currencies, so a gateway must allow rippling on all the accounting relationships to its issuing address.
|
|
|
|
|
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 accounting relationships to its issuing address, a gateway should enable the Default Ripple flag on that address. Otherwise, the gateway must individually disable the No Ripple flag for each accounting relationship that other addresses have created.
|
|
|
|
|
|
|
|
|
|
The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction to enable the Default Ripple flag:
|
|
|
|
|
|
|
|
|
|
Request:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
POST http://localhost:8088/
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"method": "submit",
|
|
|
|
|
"params": [
|
|
|
|
|
{
|
|
|
|
|
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
|
|
|
|
|
"tx_json": {
|
|
|
|
|
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
|
|
|
|
"Fee": "15000",
|
|
|
|
|
"Flags": 0,
|
|
|
|
|
"SetFlag": 8,
|
|
|
|
|
"TransactionType": "AccountSet"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
{% include '_snippets/secret-key-warning.md' %}
|
|
|
|
|
<!--{#_ #}-->
|
|
|
|
|
|
|
|
|
|
Response:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"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": "1200032200000000240000003E202100000008684000000000003A98732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100D8F2DEF27DE313E3F0D1E189BF5AC8879F591045950E2A33787C3051169038C80220728A548F188F882EA40A416CCAF2AC52F3ED679563BBE1BAC014BB9E773A333581144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
|
|
|
|
|
"tx_json": {
|
|
|
|
|
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
|
|
|
|
"Fee": "15000",
|
|
|
|
|
"Flags": 0,
|
|
|
|
|
"Sequence": 62,
|
|
|
|
|
"SetFlag": 8,
|
|
|
|
|
"SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
|
|
|
|
|
"TransactionType": "AccountSet",
|
|
|
|
|
"TxnSignature": "3045022100D8F2DEF27DE313E3F0D1E189BF5AC8879F591045950E2A33787C3051169038C80220728A548F188F882EA40A416CCAF2AC52F3ED679563BBE1BAC014BB9E773A3335",
|
|
|
|
|
"hash": "665B27B64CE658704FFD326A4FE2F5F5B5E67EACA61DE08258A59D35B883E1D5"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
To confirm that an address has Default Ripple enabled, look up the address using the [account_info method][], specifying a validated ledger version. Use [a bitwise-AND operator](https://en.wikipedia.org/wiki/Bitwise_operation#AND) to compare the `Flags` field with `0x00800000` (the [ledger flag `lsfDefaultRipple`](accountroot.html#accountroot-flags)). If the result of the bitwise-AND operation is nonzero, then the address has Default Ripple enabled.
|
|
|
|
|
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, if your gateway does not trade 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.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
An issuing gateway that does not trade XRP should enable the Disallow XRP flag on the gateway's issuing and operational addresses. A private exchange that trades in XRP should only enable the Disallow XRP flag on addresses that are not expected to receive XRP.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction to enable the Disallow XRP flag:
|
|
|
|
|
|
|
|
|
|
Request:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
POST http://localhost:8088/
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"method": "submit",
|
|
|
|
|
"params": [
|
|
|
|
|
{
|
|
|
|
|
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
|
|
|
|
|
"tx_json": {
|
|
|
|
|
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
|
|
|
|
"Fee": "10000",
|
|
|
|
|
"Flags": 0,
|
|
|
|
|
"SetFlag": 3,
|
|
|
|
|
"TransactionType": "AccountSet"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
{% include '_snippets/secret-key-warning.md' %}
|
|
|
|
|
<!--{#_ #}-->
|
|
|
|
|
|
|
|
|
|
Response:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"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": "12000322000000002400000164202100000003684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100C2E38177E92C3998EB2C22978595784BC4CABCF7D57DE71FCF6CF162FB683A1D02205942D42C440D860B4CF7BB0DF77E4F2C529695854835B2F76DC2D09644FCBB2D81144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
|
|
|
|
|
"tx_json": {
|
|
|
|
|
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
|
|
|
|
"Fee": "10000",
|
|
|
|
|
"Flags": 0,
|
|
|
|
|
"Sequence": 356,
|
|
|
|
|
"SetFlag": 3,
|
|
|
|
|
"SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
|
|
|
|
|
"TransactionType": "AccountSet",
|
|
|
|
|
"TxnSignature": "3045022100C2E38177E92C3998EB2C22978595784BC4CABCF7D57DE71FCF6CF162FB683A1D02205942D42C440D860B4CF7BB0DF77E4F2C529695854835B2F76DC2D09644FCBB2D",
|
|
|
|
|
"hash": "096A89DA55A6A1C8C9EE1BCD15A8CADCC52E6D2591393F680243ECEB93161B33"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
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).
|
|
|
|
|
|
|
|
|
|
### Enabling Require Auth
|
|
|
|
|
|
|
|
|
|
The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction to enable the Require Auth flag: (This method works the same way regardless of whether the address is an issuing address, operational address, or standby address.)
|
|
|
|
|
|
|
|
|
|
Request:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
POST http://localhost:5005/
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"method": "submit",
|
|
|
|
|
"params": [
|
|
|
|
|
{
|
|
|
|
|
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
|
|
|
|
|
"tx_json": {
|
|
|
|
|
"Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
|
|
|
|
|
"Fee": "15000",
|
|
|
|
|
"Flags": 0,
|
|
|
|
|
"SetFlag": 2,
|
|
|
|
|
"TransactionType": "AccountSet"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
{% include '_snippets/secret-key-warning.md' %}
|
|
|
|
|
<!--{#_ #}-->
|
|
|
|
|
|
|
|
|
|
### Authorizing Trust Lines
|
|
|
|
|
|
|
|
|
|
@@ -551,115 +427,43 @@ If you are using the [Authorized Trust Lines](authorized-trust-lines.html) featu
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
The following is an example of using a locally-hosted `rippled`'s [submit method][] to send a TrustSet transaction authorizing the customer address `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` to hold USD issued by the address `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW`:
|
|
|
|
|
|
|
|
|
|
Request:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
POST http://localhost:8088/
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"method": "submit",
|
|
|
|
|
"params": [
|
|
|
|
|
{
|
|
|
|
|
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
|
|
|
|
|
"tx_json": {
|
|
|
|
|
"Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
|
|
|
|
|
"Fee": "15000",
|
|
|
|
|
"TransactionType": "TrustSet",
|
|
|
|
|
"LimitAmount": {
|
|
|
|
|
"currency": "USD",
|
|
|
|
|
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
|
|
|
|
"value": 0
|
|
|
|
|
},
|
|
|
|
|
"Flags": 65536
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
{% include '_snippets/secret-key-warning.md' %}
|
|
|
|
|
<!--{#_ #}-->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Robustly Monitoring for Payments
|
|
|
|
|
|
|
|
|
|
To robustly check for incoming payments, gateways should do the following:
|
|
|
|
|
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](https://ripple.com/files/GB-2014-06.pdf "Partial Payment Flag Gateway Bulletin"). Payments with the partial-payment flag enabled can be considered "successful" if any non-zero amount is delivered, even miniscule amounts.
|
|
|
|
|
* In `rippled`, check the transaction for a `meta.delivered_amount` field. If present, that field indicates how much money *actually* got delivered to the `Destination` address.
|
|
|
|
|
* 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 issued currencies. See [Transfer Fees](#transfer-fees) for more information.
|
|
|
|
|
* 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 either operational addresses and issuing addresses.
|
|
|
|
|
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 issued currencies among themselves.
|
|
|
|
|
* 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 issued currencies from one XRP Ledger address to another. See [Transfer Fees](transfer-fees.html) for more information.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction for the issuing address `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW`, setting the `TransferRate` to charge a fee of 0.5%.
|
|
|
|
|
For examples of how to configure this setting, see the [Issue a Fungible Token tutorial](issue-a-fungible-token.html).
|
|
|
|
|
|
|
|
|
|
Request:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"method": "submit",
|
|
|
|
|
"params": [
|
|
|
|
|
{
|
|
|
|
|
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
|
|
|
|
|
"tx_json": {
|
|
|
|
|
"Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
|
|
|
|
|
"Fee": "10000",
|
|
|
|
|
"Flags": 0,
|
|
|
|
|
"TransferRate": 1005000000,
|
|
|
|
|
"TransactionType": "AccountSet"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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": "1200032200000000240000000F2B3BE71540684000000000002710732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF74473045022100AAFC3360BE151299523A93F445D5F6EB58AF5A4F8586C8B7818D6C6069660B40022022F46BCDA8FEE256AEB0BA2E92947EF4571F92354AB703E3E6D77FEF7ECBF64E8114204288D2E47F8EF6C99BCC457966320D12409711",
|
|
|
|
|
"tx_json": {
|
|
|
|
|
"Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
|
|
|
|
|
"Fee": "10000",
|
|
|
|
|
"Flags": 0,
|
|
|
|
|
"Sequence": 15,
|
|
|
|
|
"SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
|
|
|
|
|
"TransactionType": "AccountSet",
|
|
|
|
|
"TransferRate": 1005000000,
|
|
|
|
|
"TxnSignature": "3045022100AAFC3360BE151299523A93F445D5F6EB58AF5A4F8586C8B7818D6C6069660B40022022F46BCDA8FEE256AEB0BA2E92947EF4571F92354AB703E3E6D77FEF7ECBF64E",
|
|
|
|
|
"hash": "24360352FBF5597F313E5985C1766BB4A0D277CE63219AC0C0D81014C1E663BB"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 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 issued currency. 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.
|
|
|
|
|
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 issued currencies directly to the issuing address. The issuing address must always accept its issued currencies 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.
|
|
|
|
|
**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.
|
|
|
|
|
|
|
|
|
|
@@ -739,7 +543,7 @@ Response:
|
|
|
|
|
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 issued currencies from the issuing address, and not from some other gateway.
|
|
|
|
|
- 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`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -747,7 +551,7 @@ In particular, note the following features of the [Payment transaction][]:
|
|
|
|
|
|
|
|
|
|
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.) The [Partial Payment Flag Gateway Bulletin (PDF)](https://ripple.com/files/GB-2014-06.pdf) explains how to avoid a common problem.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
@@ -774,7 +578,7 @@ For more information, see [Reliable Transaction Submission](reliable-transaction
|
|
|
|
|
|
|
|
|
|
## xrp-ledger.toml File
|
|
|
|
|
|
|
|
|
|
You can publish information about what currencies your gateway issues, 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.
|
|
|
|
|
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 -->
|
|
|
|
|
@@ -782,12 +586,16 @@ You can publish information about what currencies your gateway issues, and which
|
|
|
|
|
## See Also
|
|
|
|
|
|
|
|
|
|
- **Concepts:**
|
|
|
|
|
- [Issued Currencies](issued-currencies.html)
|
|
|
|
|
- [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][]
|
|
|
|
|
|
Jake