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

PayChan Use Case: Rome's feedback

Browse Source
This commit is contained in:
Jennifer Hasegawa
2019-02-13 15:24:15 -08:00
parent f3bfa40f4f
commit 8bf9d32620
3 changed files with 94 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
content/use-cases/open-a-payment-channel-to-enable-an-inter-exchange-network.md
View File

@@ -1,88 +1,149 @@
# Open a Payment Channel to Enable an Inter-Exchange Network
As a digital asset exchange, if you frequently send XRP to another exchange, you can improve the efficiency of these payments by opening an XRP Ledger [payment channel](payment-channels.html) between your exchange (the _payer_ exchange) and the other exchange (the _payee_ exchange). A payment channel enables you to send one-way, "asynchronous" XRP payments that can be divided into very small increments and settled later. If you have a two-way flow with the other exchange, you can simply open two payment channels (one for each direction).
As a digital asset exchange, if you frequently send XRP to another exchange, you can improve the efficiency of these payments by opening an XRP Ledger [payment channel](payment-channels.html) between your exchange (the _payer_ exchange) and the other exchange (the _payee_ exchange). The need to send XRP from your exchange to another exchange may originate with your customers withdrawing XRP from your exchange and depositing it to the other exchange, for example.
***TODO: Another thing: I wouldn't be surprised if some exchanges see the word "payments" and think that you're not talking about them. They may not even realize at first how many payments they're making to other exchanges! I'd try working the word "withdrawals" into the intro paragraph to help spark the recognition of what circumstances they're probably already doing this in.***
A payment channel enables you to send one-way, "asynchronous" XRP payments that can be divided into very small increments and settled later. If you have a two-way flow with the other exchange, you can simply open two payment channels (one for each direction).
Here are some of the benefits of using a payment channel to send XRP instead of using individual payment transactions:
<div>Here are some of the benefits of using a payment channel to send XRP instead of using individual payment transactions:</div>***TODO: the div workaround isn't working for all of the paras above***
- **Process payments faster:** A standard payment transaction involves submitting an XRP Ledger transaction and waiting for a new ledger version that includes the transaction to be approved by [consensus](https://developers.ripple.com/consensus.html). When you use a payment channel to send XRP, creation and verification of a claim, which guarantees the payment of XRP, all happen outside of the consensus process. This means that the payer exchange can guarantee XRP payments to the payee exchange at a rate limited only by the participants' ability to create and verify the digital signatures of the claims. ***TODO: or process withdrawals faster? Need to understand the exchange perspective on payments vs withdrawals to reword this appropriately***
- **Process withdrawals faster:** A standard payment transaction involves submitting an XRP Ledger transaction and waiting for a new ledger version that includes the transaction to be approved by [consensus](https://developers.ripple.com/consensus.html). When you use a payment channel to send XRP, creation and verification of a claim, which guarantees the payment of XRP, all happen outside of the consensus process. This means that the payer exchange can guarantee XRP payments to the payee exchange at a rate limited only by the participants' ability to create and verify the digital signatures of the claims.
- **Lower transaction costs:** The payee exchange can choose to take the claims it has received from the payer exchange and redeem them in batches to receive the guaranteed XRP amounts. Redeeming a batch of claims in a single transaction incurs a _single_ transaction cost, while processing multiple XRP payment transactions (one per claim without a payment channel in place, for example) to receive the same amount of XRP incurs _multiple_ transaction costs. ***TODO: accurately stated?***
- **Connect to the Internet of Value:** One of the key requirements of the [Internet of Value](https://ripple.com/insights/the-internet-of-value-what-it-means-and-how-it-benefits-everyone/) is interoperability. The [Interledger Protocol](https://interledger.org/) (ILP), which plays a large role in driving this interoperability, works best when it [uses payment channels](https://interledger.org/rfcs/0027-interledger-protocol-4) as its method for rebalancing accounts. In effect, when you open a payment channel from your exchange to another, you are connecting to the Internet of Value and helping to create the inter-exchange network that is fundamental to the success of the Internet of Value and the apps that are built on it.
<ul>Here’s a roadmap to the high-level tasks you’ll need to perform to implement this payment channel use case. To go directly to a full payment channels tutorial, see <a href="use-payment-channels.html">Use Payment Channels</a>.</ul> ***TODO: I put this paragraph above in an HTML ul tag to keep the CSS formatting on this page somewhat sane. I know that it is unnecessarily indented, but if I make it a regular paragraph, the formatting will break and look even more conspicuous. We can fix the CSS in a future release.***
<div>Here’s a roadmap to the high-level tasks you’ll need to perform to implement this payment channel use case. To go directly to a full payment channels tutorial, see <a href="use-payment-channels.html">Use Payment Channels</a>.</div>
<!-- #{TODO: for the future: per Warren, it would be great to add diagrams for each step in the flow - showing claims and batch redemptions moving through the payment channel}# -->
{% set n = cycler(* range(1,99)) %}
<span class="use-case-step-num">{{n.next()}}</span>
## [Understand payment channels](payment-channels.html)
Learn more about payment channels and whether they provide the features you need for your specific implementation.
<span class="use-case-step-num">{{n.next()}}</span>
## [Set up and run `rippled` servers](manage-the-rippled-server.html) (payer and payee)
To use a payment channel to send and receive payments, both the payer and payee exchanges must each have access to a `rippled` server that they can use to send transactions. A great way for an exchange to get access to a `rippled` server is to set up and run one.
<span class="use-case-step-num">{{n.next()}}</span>
## Payer and payee: [Set up and run `rippled` servers](manage-the-rippled-server.html)
To use a payment channel to send and receive XRP, both the payer and payee exchanges must each have access to a `rippled` server that they can use to send transactions. A great way for an exchange to get access to a `rippled` server is to set up and run one.
<span class="use-case-step-num">{{n.next()}}</span>
## Payer and payee: [Fund XRP Ledger accounts](accounts.html)
The payer exchange must have a funded XRP Ledger account to be used to send XRP to the payee exchange.
- The payer exchange must have a funded XRP Ledger account to be used to send XRP to the payee exchange. Aside from the [base reserve](reserves.html) (20 XRP) and the [owner reserve](reserves.html#owner-reserves) of a payment channel (5 XRP), the account must also be able to set aside enough XRP in the payment channel to cover the intended number of transactions.
The payer exchange can always top-off the channel using the [PaymentChannelFund](paymentchannelfund.html) transaction if it runs out of XRP. However, topping-off requires an actual on-ledger transaction and confirmation, so it could take 4-5 seconds of processing time and ~10 drops of XRP to complete the top-off transaction. The more XRP the payer exchange pre-funds, the less often they need to top-off, so they can save some money by pre-funding more XRP.
However, if the payer exchange puts in more XRP than they need, they need to [close the payment channel](use-payment-channels.html#9-when-the-payer-and-payee-are-done-doing-business-the-payer-requests-for-the-channel-to-be-closed) to get the XRP back, which means waiting out two transactions (a request to close the channel and another to actually close the channel) and the `SettleDelay` time.
- The payee exchange must have a funded XRP Ledger account to be used to redeem (receive) XRP sent by the payer exchange. The account needs at least 21 XRP, which provides the 20 XRP [base reserve](reserves.html), plus enough to pay the transaction costs of redeeming claims, which are trivial. For example, you could redeem thousands of claims for less than 1 XRP in total.
The payee exchange must have a funded XRP Ledger account to be used to redeem (receive) XRP sent by the payer exchange.
<span class="use-case-step-num">{{n.next()}}</span>
## [Open a payment channel](use-payment-channels.html#1-the-payer-creates-a-payment-channel-to-a-particular-recipient) (payer) and [verify it](use-payment-channels.html#2-the-payee-checks-specifics-of-the-payment-channel) (payee)
## Payer: [Open a payment channel](use-payment-channels.html#1-the-payer-creates-a-payment-channel-to-a-particular-recipient)
The payer exchange opens a payment channel from a payer exchange account to a payee exchange account. Opening a payment channel includes setting certain specifics of the channel, such as its expiration date and the amount it can hold.
The payer exchange opens a payment channel from their XRP Ledger account to the payee exchange's XRP Ledger account. Opening a payment channel includes setting certain specifics of the channel, such as its expiration date and the amount it can hold.
For this exchange use case, there is no real need to ever close the channel, so you may not want to define a `CancelAfter` (expiration) value. If you ever need to close the channel, you can still do so.
For this exchange use case, there is no real need to ever close the channel, so the payer exchange may not want to define a `CancelAfter` (expiration) value. If they ever need to close the channel, they can still do so.
Regarding the amount of XRP the payment channel should hold, consider the typical best practice of holding the vast majority of XRP across all of your user accounts in a cold wallet, with a small amount of XRP in a hot wallet. Think about your daily traded volume of XRP to help determine how much XRP in your hot wallet to make available in the payment channel. You have the option to increase the amount allocated to the payment channel after you create it.
Regarding the amount of XRP the payment channel should hold, the payer exchange should consider the typical best practice of holding the vast majority of XRP across all of their user accounts in a cold wallet, with a small amount of XRP in a hot wallet. The payer exchange should also think about their daily traded volume of XRP to help determine how much XRP in their hot wallet to make available in the payment channel. They can always add more XRP to the payment channel after they create it.
The payee exchange then reviews the details of the payment channel.
If the payer exchange has multiple XRP Ledger accounts (one for each hot wallet, for example) and wants to use them with payment channels, they must open one payment channel per pair of payer exchange and payee exchange XRP Ledger accounts. To be clear, this use case is about creating a payment channel between the exchanges' XRP Ledger accounts, not between customer accounts.
Also keep in mind that payment channels are unidirectional. So, let's say that exchange A and exchange B want to move XRP in both directions between their XRP Ledger accounts. Exchange A must open a payment channel from their XRP Ledger account to exchange B's XRP Ledger account, and exchange B must open a payment channel from their XRP Ledger account to exchange A's XRP Ledger account. ***TODO: I reworded this a bit to portray the accounts at each end of the payment channel as being owned by separate exchanges. Are both scenarios possible - both accounts owned by the same exchange, each account owned by a different exchange? Which one do we want to surface in this use case?***
If the payer exchange has multiple accounts and wants to use them with payment channels, they must open one payment channel per pair of payer and payee accounts. Also keep in mind that payment channels are unidirectional. So, let's say that exchange A wants to move XRP in both directions between an account it owns on exchange A and an account it owns on exchange B. Exchange A must open one payment channel from its exchange A account to its exchange B account, as well as a second payment channel from its exchange B account to its exchange A account. ***TODO: stated correctly? Relevant to surface this info here?***
<span class="use-case-step-num">{{n.next()}}</span>
## [Create claims](use-payment-channels.html#3-the-payer-creates-one-or-more-signed-claims-for-the-xrp-in-the-channel) and [send them](use-payment-channels.html#4-the-payer-sends-a-claim-to-the-payee-as-payment-for-goods-or-services) (payer)
## Payee: [Verify payment channel details](use-payment-channels.html#2-the-payee-checks-specifics-of-the-payment-channel)
The payee exchange reviews the details of the payment channel.
The payer exchange creates one or more claims for amounts of XRP that it wants to guarantee to the payee exchange and then sends the claim details to the payee exchange off-ledger.
<span class="use-case-step-num">{{n.next()}}</span>
## [Verify claims](use-payment-channels.html#5-the-payee-verifies-the-claims) and [redeem them in batches](use-payment-channels.html#8-when-ready-the-payee-redeems-a-claim-for-the-authorized-amount) (payee)
## Payer: [Create claims](use-payment-channels.html#3-the-payer-creates-one-or-more-signed-claims-for-the-xrp-in-the-channel)
The payer exchange creates one or more claims for amounts of XRP that it wants to guarantee to the payee exchange.
## Payer: [Send claim details to the payer exchange](use-payment-channels.html#4-the-payer-sends-a-claim-to-the-payee-as-payment-for-goods-or-services)
After creating a claim, the payer exchange must send details of the claim to the payee exchange, off-ledger.
Consider a series of claims prompted by payer exchange customers withdrawing XRP and depositing it to the payee exchange. In this case, the payer and payee exchanges should agree on the information the payer exchange must send for each claim to enable the payee exchange to correctly credit its customers' accounts. For example, consider sharing the following claim information off-ledger:
**Channel ID**: `7C02D0802B272599889ADFA4298FD92E4C8BD5120ED9A5BA3884CF636F9B4029`
**Public key**: `023D9BFCC22FB9A997E45ACA0D2D679A6A1AE5589E51546F3EDC4E9B16713FC255`
| Sequence | Signature | Amount | Destination Tag |
|:---------|:------------------|:-------|:----------------|
| 1 | 3045022100CE6E... | 1500 | 12345678 |
| 2 | 304402200C304A... | 3000 | 87654321 |
| 3 | 30450221009849... | 4000 | 18273645 |
| Claim Information | Purpose |
|:--------------------|:-------------------------------------------------------|
| **Channel ID** | Payment channel the payer exchange used to create the claim. The payee exchange needs this value to verify and redeem the claim. |
| **Public key** | Public key the payer exchange used to open the payment channel. The payee exchange needs this value to verify and redeem the claim. |
| **Sequence** | A value that indicates the sequence in which the payer exchange created the claims. The payee exchange needs this value to keep track of and redeem claims in the correct order. For example, if the payer exchange did not provide the sequence value and the payee exchange lost track of the second claim above, the payee exchange might incorrectly credit 2500 XRP to destination tag 18273645. If the payer exchange did provide the sequence value, the payee exchange would know that it needs to account for a claim between claim 1 and claim 3. With claim 2 accounted for, the payee exchange could correctly credit 1500 XRP to destination tag 87654321 and 1000 XRP to destination tag 18273645. |
| **Signature** | Signature of the claim. The payee exchange needs this value to verify and redeem the claim. |
| **Amount** | Amount of the claim created by the payer exchange. The payee exchange needs this value to verify and redeem the claim. For information about how to calculate the actual amount the payee exchange needs to credit the customer, see [Verify claims](#payee-verify-claims). |
| **Destination Tag** | Destination tag of the customer account on the payee exchange that needs to be credited based on the claim. The payer exchange can get this value from their customer's withdrawal transaction, which should require a destination tag for the deposit to the payee exchange. When the payee exchange redeems claims, the XRP is deposited into the payee exchange's XRP Ledger account. The payee exchange can then deposit the XRP from the claim to the appropriate customer account based on the destination tag provided. |
<span class="use-case-step-num">{{n.next()}}</span>
## Payee: [Verify claims](use-payment-channels.html#5-the-payee-verifies-the-claims)
The payee exchange verifies claims sent by the payer exchange.
This is usually when the payee provides goods or services to the payer in exchange for the amount of XRP listed in the claims. However, in this use case, there is likely no exchange of goods or services. The payee exchange can just redeem batches of claims to receive the XRP guaranteed by the payer exchange.
After verifying claims, the payee exchange should credit the claimed XRP to the customer accounts indicated by the destination tags sent by the payer exchange. Because claim amounts are cumulative, the payee exchange needs to be careful to credit the customer for only the _the difference from the previous claim_.
For example, to know how much to credit a customer for a claim amount of 3000, the payee exchange needs to know that the previous claim amount was 1500. The difference between the claim amount and the previous claim amount (3000 - 1500 = 1500) is the amount the payee exchange must credit to the customer account.
<span class="use-case-step-num">{{n.next()}}</span>
## [Continue to use the payment channel](use-payment-channels.html#7-repeat-steps-3-6-as-desired) (payer and payee)
## Payee: [Redeem them in batches](use-payment-channels.html#8-when-ready-the-payee-redeems-a-claim-for-the-authorized-amount)
This is usually when the payee provides goods or services to the payer in exchange for the amount of XRP listed in the claims. However, in this use case, there is likely no exchange of goods or services. The payee exchange can just redeem batches of claims after verifying them to receive the XRP guaranteed by the payer exchange.
Here are some guidelines the payee exchange can use to decide how often to redeem claims:
- Don't redeem every claim. That's not gaining any benefit from the payment channels.
- Don't wait until you have more in claims than you're scared to lose. If something goes wrong and you miss your chance to redeem a claim, you don't get paid. If that happens and you already credited someone in another system, you could be in trouble. (For example, if you credited a customer with the XRP and they've already traded it for some other cryptocurrency that they withdrew.)
- If the payer requests to close the channel, you won't get paid if you don't redeem your claims before it finishes closing. The amount of time you have is based on the `SettleDelay`.
- If the channel was created with an immutable `CancelAfter` time, be sure to redeem all outstanding claims before that time.
- You can decide to redeem, for example, after a certain amount of time, after accumulating a certain amount of credit, or based on other criteria you care about, such as how much you trust the payer exchange. The safest strategy is probably based on a combination of these criteria.
<!-- #{ TODO: Talk to some active PayChan users like Coil people to get some more specific recommendations. But I imagine that settling every few minutes or even hours could make sense depending on how much the payee exchange trusts the payer exchange, how many transactions they do how rapidly, etc. }# -->
<span class="use-case-step-num">{{n.next()}}</span>
## Payer and payee: [Continue to use the payment channel](use-payment-channels.html#7-repeat-steps-3-6-as-desired)
Payer and payee exchanges can continue to send, verify, and redeem batches of claims as needed within the parameters set by the payment channel.
<span class="use-case-step-num">{{n.next()}}</span>
## When it's time, make a request to [close the payment channel](use-payment-channels.html#9-when-the-payer-and-payee-are-done-doing-business-the-payer-requests-for-the-channel-to-be-closed) (payer)
## Payer: When it's time, make a request to [close the payment channel](use-payment-channels.html#9-when-the-payer-and-payee-are-done-doing-business-the-payer-requests-for-the-channel-to-be-closed)
When the payer exchange and payee exchange are done using the payment channel, the payer exchange can make a request to close the payment channel.
### Related Tasks
- [List XRP in Your Exchange](list-xrp-in-your-exchange.html)
<!-- #{TODO: jha rebase on master to be able to link to [List Your Exchange on XRP Charts](list-your-exchange-on-xrp-charts.html) }#-->
***TODO: any other related tasks?

2
content/use-cases/use-cases.md
View File

@@ -14,7 +14,7 @@ Here are some of our users' most popular use cases:
* **[Open a Payment Channel to Enable an Inter-Exchange Network](open-a-payment-channel-to-enable-an-inter-exchange-network.html)**
Use a payment channel to move XRP from your digital exchange to another digital exchange, while also enabling an inter-exchange network and connecting to the Internet of Value.
Use a payment channel to move XRP from your digital exchange to another digital exchange, while also creating an inter-exchange network.
* **[Contribute Code to `rippled`](contribute-code-to-rippled.html)**