mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-21 04:05:49 +00:00
Clean up unused / removed pages & images
- Delete folders for new pages that are handled by templates w/ no
markdown source
- Fully remove "Use Cases", leaving redirects for deleted pages.
- Move certain pages to new areas & remove Use Case markup
- Add "Contribute Code to the XRP Ledger" draft page
- Fix image paths in some Japanese-translated pages
This commit is contained in:
mDuo13
@@ -11,11 +11,13 @@
|
||||
- XRP Ledgerの署名に対応した[専用の署名デバイスを使用](#専用の署名デバイスを使用する)
|
||||
- 信頼できる[リモート`rippled`マシンに接続するために安全なVPNを使用](#リモートrippledサーバーに対して安全なvpnを使用する)
|
||||
|
||||
<!-- Source for all diagrams in this article: https://docs.google.com/presentation/d/1BfGyWgC0njoPiKUZz3gXHMVSUINE3Q-_lHqY_D0TGwg/ -->
|
||||
<!-- Source for all diagrams in this article: https://drive.google.com/drive/u/0/folders/1MFkzxtMYpS8tzdm-TjWbLSVgU0zAG9Vh -->
|
||||
|
||||
## 安全でない構成
|
||||
|
||||
[](img/insecure-signing-options.png)
|
||||
<!-- TODO: translate diagrams -->
|
||||
{{ include_svg("img/insecure-signing-options.svg", "安全でない構成の図") }}
|
||||
|
||||
|
||||
外部のソースからあなたの秘密鍵にアクセスできる構成は危険で、不正使用者によってあなたのすべてのXRP（およびあなたのXRP Ledgerのアドレスにあるすべてのもの）が盗まれる可能性があります。そのような構成の例としては、インターネット経由で他の人の`rippled`サーバーの[signメソッド][]を使用する構成や、秘密鍵をインターネットを経由してプレーンテキストで自己所有サーバーに送信する構成などがあります。
|
||||
|
||||
@@ -26,7 +28,7 @@
|
||||
|
||||
## ローカルでrippledを実行する
|
||||
|
||||
[](img/secure-signing-local-rippled.png)
|
||||
{{ include_svg("img/secure-signing-local-rippled.svg", "署名にローカルrippledサーバーを使用する構成の図") }}
|
||||
|
||||
この構成では、トランザクションを生成するマシンで`rippled`を実行します。 秘密鍵はマシンから出ていかないため、マシンへのアクセス権がない人は秘密鍵にアクセスできません。もちろん、マシンのセキュリティ保護に関する業界標準のプラクティスに従ってください。この構成を使用するには、次の手順を実行します。
|
||||
|
||||
@@ -47,7 +49,7 @@
|
||||
|
||||
## 同じLAN内でrippledを実行する
|
||||
|
||||
[](img/secure-signing-lan-rippled.png)
|
||||
{{ include_svg("img/secure-signing-lan-rippled.svg", "署名にLAN経由でrippledサーバーを使用する構成の図") }}
|
||||
|
||||
この構成では、署名するトランザクションを生成するマシンと同じプライベートローカルエリアネットワーク（LAN）内の専用マシンで`rippled`サーバーを実行します。この構成では、`rippled`を実行する専用の1台のマシンを使用しながら、中程度のシステムスペックの1台以上のマシンでトランザクションの指示を組み立てることができます。自己所有のデータセンターやサーバールームがある場合に魅力的な選択肢です。
|
||||
|
||||
@@ -60,7 +62,7 @@
|
||||
|
||||
## ローカル署名機能のあるクライアントライブラリを使用する
|
||||
|
||||
[](img/secure-signing-client-library.png)
|
||||
{{ include_svg("img/secure-signing-client-library.svg", "[ローカル署名機能のあるクライアントライブラリを使用する構成の図") }}
|
||||
|
||||
この構成では、トランザクションにローカルで署名するために使用しているプログラミング言語のクライアントライブラリを使用します。使用しているプログラミング言語に対応するクライアントライブラリが必要です。Rippleは、XRP Ledgerのトランザクションにローカルで署名することができる次のクライアントライブラリを公開しています。
|
||||
|
||||
@@ -87,7 +89,7 @@ Rippleが公開したものでないクライアントライブラリを使用
|
||||
|
||||
## 専用の署名デバイスを使用する
|
||||
|
||||
[](img/secure-signing-dedicated-hardware.png)
|
||||
{{ include_svg("img/secure-signing-dedicated-hardware.svg", "専用の署名ハードウェアの使用の図") }}
|
||||
|
||||
専用の署名デバイスが各社から販売されており、例えば[Ledger Nano S](https://www.ledger.com/products/ledger-nano-s)は、秘密鍵をデバイスから出さずに使ってXRP Ledgerトランザクションに署名できます。すべてのタイプのトランザクションに対応していないデバイスもあります。
|
||||
|
||||
@@ -96,7 +98,7 @@ Rippleが公開したものでないクライアントライブラリを使用
|
||||
|
||||
## リモートrippledサーバーに対して安全なVPNを使用する
|
||||
|
||||
[](img/secure-signing-over-vpn.png)
|
||||
{{ include_svg("img/secure-signing-over-vpn.svg", "VPNを経由してリモート`rippled`に安全に接続する構成の図") }}
|
||||
|
||||
この構成では、コロケーション施設や遠隔地のデータセンターなどにあるリモートでホストされている`rippled`サーバーを使用し、暗号化されたVPNを使用してそのサーバーに接続します。
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ There are several configurations with varying levels of security that may be acc
|
||||
- [Use a dedicated signing device](#use-a-dedicated-signing-device) that supports XRP Ledger signatures.
|
||||
- [Use a secure VPN to connect to a remote `rippled` machine](#use-a-secure-vpn-with-a-remote-rippled-server) you trust.
|
||||
|
||||
<!-- Source for all diagrams in this article: https://docs.google.com/presentation/d/1BfGyWgC0njoPiKUZz3gXHMVSUINE3Q-_lHqY_D0TGwg/ -->
|
||||
<!-- Source for all diagrams in this article: https://drive.google.com/drive/u/0/folders/1MFkzxtMYpS8tzdm-TjWbLSVgU0zAG9Vh -->
|
||||
|
||||
## Insecure Configurations
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Whenever `rippled` closes a ledger, it reorders the transactions according to a
|
||||
- [server_info method][]
|
||||
- [`rippled` Commandline Usage](commandline-usage.html)
|
||||
- **Use Cases:**
|
||||
- [Contribute Code to `rippled`](contribute-code-to-rippled.html)
|
||||
- [Contribute Code to the XRP Ledger](contribute-code.html)
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
|
||||
@@ -74,7 +74,7 @@ rippled ledger_accept --conf=/path/to/rippled.cfg
|
||||
- [server_infoメソッド][]
|
||||
- [`rippled`コマンドラインの使用](commandline-usage.html)
|
||||
- **ユースケース:**
|
||||
- [`rippled`へのコードの提供](contribute-code-to-rippled.html)
|
||||
- [XRP Ledgerへのコードの提供](contribute-code.html)
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
|
||||
@@ -75,7 +75,7 @@ rippled ledger_accept --conf=/path/to/rippled.cfg
|
||||
- [server_info method][]
|
||||
- [`rippled` Commandline Usage](commandline-usage.html)
|
||||
- **Use Cases:**
|
||||
- [Contribute Code to `rippled`](contribute-code-to-rippled.html)
|
||||
- [Contribute Code to the XRP Ledger](contribute-code.html)
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
|
||||
@@ -35,7 +35,7 @@ By default, a new genesis ledger has no [amendments](amendments.html) enabled. I
|
||||
- [server_info method][]
|
||||
- [`rippled` Commandline Usage](commandline-usage.html)
|
||||
- **Use Cases:**
|
||||
- [Contribute Code to `rippled`](contribute-code-to-rippled.html)
|
||||
- [Contribute Code to the XRP Ledger](contribute-code-to-rippled.html)
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
|
||||
@@ -0,0 +1,179 @@
|
||||
# Open a Payment Channel to Enable an Inter-Exchange Network
|
||||
|
||||
A payment channel enables you to send one-way, "asynchronous" XRP payments that can be divided into very small increments and settled later. As a digital asset exchange, if you send many payments of 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). In the case of a two-way flow with another exchange, you can open two payment channels (one for each direction).
|
||||
|
||||
|
||||
|
||||
## Why Send XRP to Other Exchanges?
|
||||
|
||||
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. If you are a large exchange, you probably have many customers moving XRP from your exchange into another exchange. You may be processing XRP payments all day long and for each payment, you are waiting for confirmation times, potentially at both ends of the transaction, as well as paying transaction costs.
|
||||
|
||||
|
||||
|
||||
## Benefits of Using a Payment Channel
|
||||
|
||||
Here are some of the benefits of using a payment channel to send XRP instead of using individual payment transactions: <!-- {# TODO: for the future, complete https://ripplelabs.atlassian.net/browse/DOC-2243 to see if using a payment channel would actually result in a cost benefit to the sending exchange #}-->
|
||||
|
||||
- **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](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.
|
||||
|
||||
For your customers who are moving XRP to take advantage of arbitrage opportunities or to do algorithmic trading, speed matters. Enabling a customer to move XRP and start trading in an instant is a compelling differentiator for your exchange.
|
||||
|
||||
- **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.
|
||||
|
||||
Connecting your exchange to other exchanges by way of payment channels is another differentiator. For customers who are moving XRP to buy various currencies across exchanges, knowing that they can move XRP at a moment's notice from your exchange to any number of exchanges in the Internet of Value can make your exchange a preferred place to custody their assets.
|
||||
|
||||
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 [Use Payment Channels](use-payment-channels.html).
|
||||
|
||||
<!-- #{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. Also, we have any recommendations around Payment Channel Managers, we can surface that here.}# -->
|
||||
|
||||
|
||||
|
||||
## Understand payment channels
|
||||
|
||||
Learn more about payment channels and whether they provide the features you need for your specific implementation.
|
||||
|
||||
[Understand payment channels >](payment-channels.html)
|
||||
|
||||
|
||||
|
||||
## Payer and payee: Set up and run `rippled` servers
|
||||
|
||||
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. If your exchange processes XRP withdrawals directly, you are probably already running a `rippled` server that you can use for this purpose.
|
||||
|
||||
If not, a great way for an exchange to get access to a `rippled` server is to set up and run one.
|
||||
|
||||
[Set up and run rippled servers >](manage-the-rippled-server.html)
|
||||
|
||||
|
||||
|
||||
## Payer and payee: Fund XRP Ledger accounts with enough XRP
|
||||
|
||||
If your exchange processes XRP deposits and withdrawals directly, you probably have existing funded XRP Ledger accounts that you can use for this purpose. Ensure that they are funded with enough XRP as described here.
|
||||
|
||||
Along these lines, there's a good chance that you are following industry best practices and have a cold account plus one or more hot accounts. Use the hot accounts for your payment channels.
|
||||
|
||||
- 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 time and 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. This means waiting out the following events:
|
||||
|
||||
1. Completion of the payer's request to start closing the payment channel.
|
||||
2. Passage of the `SettleDelay` time set for the payment channel.
|
||||
3. Completion of a request to finish closing the payment channel after the `SettleDelay` has passed.
|
||||
|
||||
- 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.
|
||||
|
||||
[Fund XRP Ledger accounts with enough XRP >](accounts.html)
|
||||
|
||||
|
||||
## 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 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 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.
|
||||
|
||||
As the payer exchange, you can think of the payment channel as a special sub-wallet exclusively for a particular destination. Consider estimating how much XRP the payment channel requires similar to how you would estimate a hot wallet's needs. According to [typical best practices](issuing-and-operational-addresses.html), exchanges hold 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.
|
||||
|
||||
Along these lines, you should also decide approximately how often you want to add more XRP to the payment channel---for example, daily, every 4 hours, or every 15 minutes---and estimate the volume of XRP that you send to the payee exchange during that interval. You should fund the payment channel with enough to cover at least that much volume or the largest withdrawal that you want to process without delay, whichever is larger. For example, if you plan to refill the channel every 15 minutes, have an average volume of 50 XRP every 15 minutes, but occasionally send transfers of 10,000 XRP, you should supply the channel with at least 10,000 XRP.
|
||||
|
||||
For withdrawals that are larger than the amount of XRP you have in the payment channel, you must process them specially. Either you can send large withdrawals as normal XRP payments, skipping the payment channel entirely, or you can first send a transaction to add the full withdrawal amount to the payment channel before creating claims for those. (See below for details on creating claims.)
|
||||
|
||||
If either exchange has multiple hot accounts in the XRP Ledger, the two exchanges should each designate a specific hot account to use with the payment channel between them. Although there are other potentially viable configurations, this use case assumes a configuration with one payment channel connecting two exchanges. This channel can serve all customers sending XRP from the payer exchange to the payee exchange.
|
||||
|
||||
Since payment channels are unidirectional, you need a second channel in the opposite direction to send XRP from the _payee_ exchange to the _payer_ exchange. This second channel does not need to connect the exact same pair of hot accounts, but it is most convenient to do so. With two unidirectional channels, each exchange can use the XRP it redeems from its incoming channel to refill its outgoing channel.
|
||||
|
||||
|
||||
|
||||
|
||||
## Payee: Verify payment channel details
|
||||
|
||||
The payee exchange reviews the details of the payment channel.
|
||||
|
||||
[Verify payment channel details >](use-payment-channels.html#2-the-payee-checks-specifics-of-the-payment-channel)
|
||||
|
||||
|
||||
|
||||
## Payer: Create claims
|
||||
|
||||
The payer exchange creates one or more claims for amounts of XRP that it wants to guarantee to the payee exchange.
|
||||
|
||||
[Create claims >](use-payment-channels.html#3-the-payer-creates-one-or-more-signed-claims-for-the-xrp-in-the-channel)
|
||||
|
||||
|
||||
## Payer: Send claim details to the payer exchange
|
||||
|
||||
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...` | 2000 | 12345678 |
|
||||
| 2 | `304402200C304A...` | 3000 | 23456781 |
|
||||
| 3 | `30450221009849...` | 4000 | 34567812 |
|
||||
|
||||
| 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 2000 XRP to destination tag 34567812. 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 1000 XRP to destination tag 23456781 and 1000 XRP to destination tag 34567812. |
|
||||
| **Signature** | Signature of the claim. The payee exchange needs this value to verify and redeem the claim. |
|
||||
| **Amount** | Cumulative amount of the claims 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 request, which should provide 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 credit the XRP from the claim to the appropriate customer account based on the destination tag provided. |
|
||||
|
||||
[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)
|
||||
|
||||
|
||||
## Payee: Verify claims
|
||||
|
||||
The payee exchange verifies claims sent 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 2000. The difference between the claim amount and the previous claim amount (3000 - 2000 = 1000) is the amount the payee exchange must credit to the customer account.
|
||||
|
||||
[Verify claims >](use-payment-channels.html#5-the-payee-verifies-the-claims)
|
||||
|
||||
|
||||
|
||||
## Payee: Redeem them in batches
|
||||
|
||||
The payee exchange can 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 have already credited one or more customers in your system, you could be in trouble. Those customers may have already traded the XRP for other cryptocurrencies and withdrawn them. That leaves you with more XRP owed in your system than you were holding for your customers, and it's too late to correct the balances of the customers whose deposits you didn't receive.
|
||||
|
||||
- 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. }# -->
|
||||
|
||||
[Redeem them in batches >](use-payment-channels.html#8-when-ready-the-payee-redeems-a-claim-for-the-authorized-amount)
|
||||
|
||||
|
||||
|
||||
## Payer and payee: Continue to use the payment channel
|
||||
|
||||
Payer and payee exchanges can continue to send, verify, and redeem batches of claims as needed within the parameters set by the payment channel.
|
||||
|
||||
[Continue to use the payment channel >](use-payment-channels.html#7-repeat-steps-3-6-as-desired)
|
||||
|
||||
|
||||
## Payer: When it's time, make a request to close the payment channel
|
||||
|
||||
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.
|
||||
|
||||
[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)
|
||||
@@ -0,0 +1,137 @@
|
||||
# Use an Escrow as a Smart Contract
|
||||
|
||||
A smart contract is a blockchain-based program that encodes the conditions and fulfillment of an agreement between two or more parties and automatically fulfills the terms of the agreement once conditions are met. A smart contract can help you exchange anything of value in a transparent, traceable, tamper-resistant, and irreversible way.
|
||||
|
||||
The benefit of encoding a smart contract into a blockchain is that it enables the contract to be securely performed without traditional third-parties, like financial or legal institutions. Instead, the contract is supervised by the distributed, decentralized network of computers that run the blockchain.
|
||||
|
||||
You can use XRP Ledger escrows as smart contracts that release XRP after a certain time has passed or after a cryptographic condition has been fulfilled. In this case, we'll use an escrow as a smart contract that releases XRP after a cryptographic condition has been fulfilled.
|
||||
|
||||
Let's use this scenario to help illustrate this use case: A party planner uses smart contracts to manage payments from party hosts to party vendors. Specifically, the party planner wants to use a smart contract to have the party host pay the party band 2000 XRP once they are done with their set.
|
||||
|
||||
In this use case, the party host is the sender of the escrow, the party band is the receiver of the escrow, and the party planner is playing the role of an _oracle_. In the context of smart contracts, an oracle is a neutral third-party agent that can verify real-world events to either fulfill or invalidate a smart contract. This use case uses a human oracle for illustrative purposes, but in real-life, a software application would more likely play the role of the oracle.
|
||||
|
||||
Using an XRP Ledger escrow to provide this smart contract is a great arrangement because the party planner, as the third-party oracle, never "holds" the funds as one might in a traditional escrow arrangement, and can't possibly take the funds for themselves.
|
||||
|
||||
Here’s a roadmap to the high-level tasks that these participants need to complete to use an escrow as a smart contract.
|
||||
|
||||
|
||||
## Meet the prerequisites
|
||||
|
||||
The party host (sender) must have:
|
||||
|
||||
- An XRP Ledger [account](accounts.html#creating-accounts) that holds enough XRP to pay for escrow and any fees incurred.
|
||||
|
||||
- Access to a secure signing environment, which includes having a network connection to a [`rippled` server](install-rippled.html) (any server) that they can submit signed transactions to. <!--#{ once set up secure signing tutorial is available, link to it from here }# -->
|
||||
|
||||
The party band (receiver) must have:
|
||||
|
||||
- An XRP Ledger [account](accounts.html#creating-accounts) that can receive the XRP paid by the escrow.
|
||||
|
||||
- Access to a [`rippled` server](install-rippled.html) that they can use to look up the details of an XRP Ledger transaction hash and submit the fulfillment value to finish the escrow.
|
||||
|
||||
The party planner (oracle) must have:
|
||||
|
||||
- The ability to generate a condition and a fulfillment.
|
||||
|
||||
- To be able to keep a secret (the fulfillment) until the time is right.
|
||||
|
||||
- A way to communicate the fulfillment publicly or at least to the party band when the time is right.
|
||||
|
||||
- The ability to recognize whether the party band has fulfilled their end of the contract (played at the party).
|
||||
|
||||
|
||||
|
||||
|
||||
## Define the terms of the smart contract
|
||||
|
||||
To create the escrow as a smart contract, the participants must first define the terms of the contract. In this scenario, the participants need to agree on the following details.
|
||||
|
||||
- **Should the escrow disallow fulfillment until a specific time?**
|
||||
|
||||
While this is an option, the participants agree that it is unnecessary for their escrow. For conditionally-held escrows, enabling this option doesn't provide any additional security, since whether the escrow can be finished still depends entirely on whether the party planner (oracle) publishes the fulfillment before the expiration.
|
||||
|
||||
- **Should the escrow expire?**
|
||||
|
||||
Absolutely yes. The participants agree that the escrow should expire after 12 noon the day after the party. This gives the party band (receiver) enough time to finish the escrow, after the party planner verifies that they fulfilled their end of the contract and publishes the cryptographic fulfillment. After expiration, the locked XRP returns to the party host's (sender's) account.
|
||||
|
||||
If the participants don't allow the escrow to expire and the party planner doesn't release the condition, the XRP stays locked in the escrow forever.
|
||||
|
||||
- **How much XRP should the escrow lock up and potentially pay?**
|
||||
|
||||
The participants agree that the escrow should lock up and potentially pay 2000 XRP, which is the party band's fee.
|
||||
|
||||
- **From which XRP Ledger account should the escrow lock up XRP for potential payment to the party band?**
|
||||
|
||||
The participants agree that the escrow should lock up and potentially pay XRP out of the party host's XRP Ledger account.
|
||||
|
||||
- **Which XRP Ledger account should the escrow potentially pay XRP to?**
|
||||
|
||||
The participants agree that the escrow should potentially pay XRP to the party band's XRP Ledger account.
|
||||
|
||||
|
||||
|
||||
|
||||
## Oracle: Generate a condition and a fulfillment
|
||||
|
||||
Because participants want to create a conditionally-held escrow to provide the smart contract, they need a condition value and a fulfillment value. In this scenario, the participant that creates these values is the neutral party planner (oracle).
|
||||
|
||||
The party planner generates the condition and fulfillment values. The party planner provides the condition value to the party host, who creates the escrow. The part planner also provides the condition to the party band so that they know that this is the right condition.
|
||||
|
||||
The party planner must keep the fulfillment value a secret. Anyone can use the condition and fulfillment values to finish the escrow. Most often, the receiver finishes the escrow because they're the ones who are motivated to get paid.
|
||||
|
||||
[Generate a condition and a fulfillment >](send-a-conditionally-held-escrow.html#1-generate-condition-and-fulfillment)
|
||||
|
||||
|
||||
## Sender: Calculate time values needed for the escrow
|
||||
|
||||
Because the participants want the escrow to be eligible for cancellation after 12 noon the day after the party, the party host (sender) must calculate a `CancelAfter` value to include in the escrow definition.
|
||||
|
||||
[Calculate time values needed for the escrow >](send-a-conditionally-held-escrow.html#2-calculate-release-or-cancel-time)
|
||||
|
||||
|
||||
|
||||
## Sender: Create the escrow
|
||||
|
||||
The party host (sender) creates the escrow that provides the smart contract. The party host must create the escrow because they are the only participant that can authorize the lock up and potential payout of XRP from their XRP Ledger account.
|
||||
|
||||
[Create the escrow >](send-a-conditionally-held-escrow.html#3-submit-escrowcreate-transaction)
|
||||
|
||||
|
||||
|
||||
## Sender and Receiver: Wait for validation and confirm escrow creation
|
||||
|
||||
The party host (sender) waits for validation of the ledger that contains the escrow creation transaction and then confirms that the escrow was created.
|
||||
|
||||
[Wait for validation >](send-a-conditionally-held-escrow.html#4-wait-for-validation)
|
||||
|
||||
The party host then provides the escrow transaction's `hash` value to the party band (receiver). The party band can use the `hash` value to look up the escrow transaction on the XRP Ledger to ensure that it was created according to the smart contract terms they agreed to. As part of this step, the party band should confirm that the condition matches the one the party planner (oracle) provided. If the condition is wrong, the fulfillment the party planner provides won't let the party band finish the escrow and get paid.
|
||||
|
||||
[confirm escrow creation >](send-a-conditionally-held-escrow.html#5-confirm-that-the-escrow-was-created)
|
||||
|
||||
|
||||
|
||||
## Receiver: Finish the escrow
|
||||
|
||||
The party band (receiver) shows up and plays their set.
|
||||
|
||||
The party planner (oracle) is present at the party to ensure that everything is going smoothly. The party planner confirms first-hand that the party band has fulfilled their contract and publishes the fulfillment publicly, or at least to the party band.
|
||||
|
||||
The party band must finish the escrow before 12 noon. If they don't, the escrow expires and the party band doesn't get paid.
|
||||
|
||||
If the party planner does not publish the fulfillment (the party band is a no show) or if the party planner publishes the fulfillment, but no one finishes the escrow; after 12 noon the next day, anyone can [cancel the escrow](cancel-an-expired-escrow.html). Cancelling the escrow returns the held XRP to the party host's account.
|
||||
|
||||
[Finish the escrow >](send-a-conditionally-held-escrow.html#6-submit-escrowfinish-transaction)
|
||||
|
||||
|
||||
|
||||
## Receiver and Sender: Wait for validation and confirm final result
|
||||
|
||||
The party band (receiver) waits for validation of the ledger that contains the escrow finish transaction and then confirms that the escrow was finished.
|
||||
|
||||
At this time, the party band provides the transaction's `hash` value to the party host (sender). They can use the `hash` value to look up the escrow transaction on the XRP Ledger to ensure that it is been finished correctly.
|
||||
|
||||
The party band can check their XRP Ledger account balance to ensure that their balance has increased by 2000 XRP. The party host's balance won't change at this step (unless the escrow was canceled) because the escrow creation already debited the locked-up XRP from their account.
|
||||
|
||||
[Wait for validation >](send-a-conditionally-held-escrow.html#7-wait-for-validation)
|
||||
|
||||
[confirm final result >](send-a-conditionally-held-escrow.html#8-confirm-final-result)
|
||||
@@ -1,6 +1,6 @@
|
||||
# List XRP as an Exchange
|
||||
|
||||
This document describes the steps that an exchange needs to take to list XRP.
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user