ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-27 23:25:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

WIP dir. reorg

Browse Source
This commit is contained in:
ddawson
2022-11-17 16:32:06 -08:00
parent 52dd90bf18
commit 7611979abf
71 changed files with 12361 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
content/concepts/transactions/payments/checks.md Normal file
View File

@@ -0,0 +1,115 @@
---
html: checks.html
parent: payments.html
blurb: Checks can be used for deferred payments that can be canceled or cashed by recipients.
labels:
- Transactions
---
# Checks
_(Added by the Checks amendment.)_
The Checks feature in the XRP Ledger allows users to create deferred payments that can be canceled or cashed by the intended recipients. Like personal paper checks, XRP Ledger Checks start with the sender of the funds creating a Check that specifies an amount and a recipient. The recipient cashes the check to pull the funds from the sender's account into the recipient's account. No money moves until the recipient cashes the Check. Because funds are not put on hold when the Check is created, cashing a Check can fail if the sender doesn't have enough funds when the recipient tries to cash it. If there's a failure cashing the check, the check's recipient can retry until the Check expires.
XRP Ledger Checks may have expiration times after which they may no longer be cashed. If the recipient doesn't successfully cash the Check before it expires, the Check can no longer be cashed, but the object remains in the XRP Ledger until someone cancels it. Anyone may cancel the Check after it expires. Only the sender and recipient can cancel the Check before it expires. The Check object is removed from the Ledger when the sender successfully cashes the check or someone cancels it.
Checks have some similarities to [escrow](escrow.md) and [payment channels](payment-channels.md), but there are some important differences between those features and checks:
* You can send [tokens](../../tokens/tokens.md) with checks. With payment channels and Escrow, you can only send XRP.
* Checks do not lock up or set aside any funds. The XRP involved in payment channels and escrow cannot be spent until it is redeemed with a claim provided by the sender (payment channels), or released by an expiration or crypto-condition (escrow).
* You can send XRP to yourself through escrow. You cannot send checks to yourself.
**Note:** The Checks amendment changes the expiration behavior of the `OfferCreate` transaction.
<!-- For more information, see [Offer Expiration](offers.html#offer-expiration). -->
## Why Checks?
Traditional paper checks allow people to transfer funds without immediately exchanging physical currency. XRP Ledger Checks allow people to exchange funds asynchronously using a process that is familiar to and accepted by the banking industry.
XRP Ledger Checks also solve a problem that is unique to the XRP Ledger: they allow users to reject unwanted payments or accept only part of a payment. This is useful for institutions that need to be careful about accepting payments for compliance reasons.
### Use Case: Payment Authorization
**Problem:** To comply with regulations like BSA, KYC, AML, and CFT, financial institutions must provide documentation about the source of funds they receive. Such regulations seek to prevent the illicit transfer of funds by requiring institutions to know the source and destination of all payments processed by the institution. Because of the nature of the XRP Ledger, anyone could potentially send XRP (and, under the right circumstances, tokens) to an institution's account on the XRP Ledger. Dealing with such unwanted payments adds significant cost and time delays to these institutions' compliance departments, including potential fines or penalties. <!-- SPELLING_IGNORE: cft -->
<!-- [BSA, KYC, AML, and CFT](become-an-xrp-ledger-gateway.html#gateway-compliance) -->
**Solution:** Institutions can enable deposit authorization on their XRP Ledger accounts by setting the `asfDepositAuth` flag in an `AccountSet` transaction. This makes the account unable to receive Payment transactions. Accounts with Deposit Authorization enabled can only receive funds through Escrow, Payment Channels, or Checks. Checks are the most straightforward, familiar, and flexible way to transfer funds if Deposit Authorization is enabled.
## Usage
Checks typically have the lifecycle described below.
<!--{# Diagram source: https://docs.google.com/drawings/d/1Ez8OZVB2TLH-b_kSFOAgfYqXlEQt4KaUBW6F3TJAv_Q/edit #}-->
[![Check flow diagram (successful cashing)](../../../../img/checks-happy-path.png)](../../../../img/checks-happy-path.png)
**Step 1:** To create a Check, the sender submits a `CheckCreate` transaction and specifies the recipient (`Destination`), expiration time (`Expiration`), and maximum amount that may be debited from the sender's account (`SendMax`).
**Step 2:** After the CheckCreate transaction is processed, a Check object is created on the XRP Ledger. This object contains the properties of the check as defined by the transaction that created it. The object can only be modified by the sender (by canceling it with a `CheckCancel` transaction) or recipient (by canceling it or cashing it) before the expiration time passes. After the expiration time, anyone may cancel the Check.
**Step 3:** To cash the check, the recipient submits a `CheckCash` transaction. The recipient has two options for cashing the check:
* `Amount` — The recipient can use this option to specify an exact amount to cash. This may be useful for cases where the sender has padded the check to cover possible [transfer fees](../../tokens/transfer-fees.md) and the recipient wants to accept the exact amount on an invoice or other contract.
* `DeliverMin` — The recipient can use this option to specify the minimum amount they are willing to receive from the Check. If the recipient uses this option, the XRP Ledger attempts to deliver as much as possible and always delivers at least this amount. The transaction fails if the amount that can be credited to the recipient is not at least the requested amount.
If the sender has enough funds to cover the Check and the expiration time has not passed, the funds are debited from the sender's account and credited to the recipient's account, and the Check object is destroyed.
#### Expiration Case
In the case of expirations, Checks have the lifecycle described below.
<!--{# Diagram source: https://docs.google.com/drawings/d/11auqa0kVUPonqlc_RaQUfHcSkUI47xneSKpwlLxzSK0/edit #}-->
[![Check flow diagram (expiration)](../../../../img/checks-expiration.png)](../../../../img/checks-expiration.png)
All Checks start the same way, so **Steps 1 and 2** are the same.
**Step 3a:** If the Check expires before the recipient can cash it, the Check can no longer be cashed but the object remains in the ledger.
**Step 4a:** After a Check expires, anyone may cancel it by submitting a [CheckCancel][] transaction. That transaction removes the Check from the ledger.
<!-- SPELLING_IGNORE: 3a, 4a -->
## Availability of Checks
The Checks amendment became enabled on the XRP Ledger Mainnet on 2020-06-18. For more information about how amendments are enabled and voted on, see [Amendment Process](../../../../amendments/amendments.md#amendment-process).
To check the status of an amendment on a test network or private network, use the `feature` method.
<!--
## See Also
For more information about Checks in the XRP Ledger, see:
- [Transaction Reference](transaction-types.html)
- [CheckCreate][]
- [CheckCash][]
- [CheckCancel][]
- [Checks Tutorials](use-checks.html)
- [Send a Check](send-a-check.html)
- [Look up Checks by sender address](look-up-checks-by-sender.html)
- [Look up Checks by recipient address](look-up-checks-by-recipient.html)
- [Cash a Check for an exact amount](cash-a-check-for-an-exact-amount.html)
- [Cash a Check for a flexible amount](cash-a-check-for-a-flexible-amount.html)
- [Cancel a Check](cancel-a-check.html)
- [Checks amendment][]
For more information about related features, see:
* [Deposit Authorization](depositauth.html)
* [Escrow](escrow.html)
* [Payment Channels Tutorial](use-payment-channels.html) -->

41
content/concepts/transactions/payments/cross-currency-payments.md Normal file
View File

@@ -0,0 +1,41 @@
---
html: cross-currency-payments.html
parent: payments.html
blurb: In the XRP Ledger, you can send cross-currency payments that exchange tokens, XRP, or both.
labels:
- Transactions
---
# Cross-Currency Payments
In the XRP Ledger, you can send cross-currency payments that exchange tokens, XRP, or both. Like [direct XRP payments](direct-xrp-payments.html), these payments use the `Payment transaction` type. Cross-currency payments within the XRP Ledger are fully atomic, meaning that either the payment fully executes or no part of it executes.
By default, cross-currency payments deliver a fixed amount to their destination at a variable cost to their source. Cross-currency payments can also be [partial payments](partial-payments.md), which deliver a variable amount to the destination within a fixed sending limit.
## Prerequisites
- By definition, a cross-currency payment involves at least two currencies, which means that at least one currency involved must be a non-XRP [token](../../tokens/tokens.md).
- There must be at least one [path](../../tokens/paths.md) between the sender and receiver, and the total liquidity across all paths must be enough to execute the payment. Cross-currency payments convert from one currency to another by consuming offers in the XRP Ledger's decentralized exchange.
<!-- [Offers](offers.html) in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). -->
## Auto-Bridging
Cross-currency payments that exchange one token for another token can automatically use XRP to bridge the tokens, when it decreases the cost of the payment. For example, a payment sending from USD to MXN automatically converts USD to XRP and then XRP to MXN if doing so is cheaper than converting USD to MXN directly. Larger trades can use a combination of direct (USD-MXN) and auto-bridged (USD-XRP-MXN) conversions.
<!--
For more information, see [Auto-Bridging](autobridging.html).
## See Also
- **Concepts:**
- [Tokens](tokens.html)
- [Decentralized Exchange](decentralized-exchange.html)
- [Paths](paths.html)
- **References:**
- [Payment transaction type][Payment transaction]
- [path_find method][]
- [ripple_path_find method][]
- [Interpreting Metadata of Cross-Currency Payments](look-up-transaction-results.html#token-payments) -->

92
content/concepts/transactions/payments/direct-xrp-payments.md Normal file
View File

@@ -0,0 +1,92 @@
---
html: direct-xrp-payments.html
parent: payments.html
blurb: Direct XRP payments are the quintessential type of payment for the XRPL.
labels:
- Transactions
---
# Direct XRP Payments
The basis of any financial system is _transferring value_: or, in one word, payments. The quintessential type of payment in the XRP Ledger is a direct XRP-to-XRP payment, which transfers XRP directly from one account in the XRP Ledger to another.
## About Direct XRP-to-XRP Payments
Generally, any address in the XRP Ledger can send XRP directly to any other address. The address on the receiving side is often called the _destination address_, and the address on the sending side is called the _source address_. To send XRP directly, the sender uses a `Payment` transaction, which can be as concise as the following:
```json
{
"TransactionType": "Payment",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Amount": "13000000"
}
```
These transaction instructions mean: Send a payment from `rf1Bi...` to `ra5nK...` delivering exactly 13 XRP. If the transaction is successfully processed, it does exactly that. Since it usually takes about 4 seconds for each new ledger version to become [validated](../../xrpl/consensus.md), a successful transaction can be created, submitted, executed, and have a final outcome in 8 seconds or less, even if gets queued for the ledger version after the current in-progress one.
**Caution:** The `Payment` transaction type can also be used for some more specialized kinds of payments, including [cross-currency payments](cross-currency-payments.md) and [partial payments](partial-payments.md). In the case of partial payments, it is possible that the `Amount` shows a large amount of XRP even if the transaction only delivered a very small amount. See [partial payments exploit](partial-payments.md#partial-payments-exploit) for how to avoid crediting a customer for the wrong amount.
Direct XRP-to-XRP payments cannot be partial payments, but partial payments can deliver XRP after converting from a different source currency.
## Funding Accounts
Any mathematically-valid address can receive a payment, even if the XRP Ledger has no record of that address existing beforehand, as long as the payment delivers enough XRP to meet the minimum [account reserve](../../accounts/reserves.md). If the payment would not deliver enough XRP, it fails.
For more information, see [Accounts](../../accounts/accounts.md#creating-accounts).
## Address Reuse
In the XRP Ledger, addresses where you can receive payments are permanent, and have a non-trivial [reserve requirement](../../accounts/reserves.md) of XRP that they cannot spend. This means that, contrary to some other blockchain systems, it is not a good idea to use a different, disposable address for every transaction. The best practice for the XRP Ledger is to reuse the same address for multiple transactions. If you use the address regularly (especially if it's managed by an internet-connected service), you should set a [regular key](../../accounts/cryptographic-keys.md) and proactively change keys on a regular basis to reduce the risk of a key compromise.
As a sender, it is best not to assume that your intended recipient is using the same address from the last time you sent them a payment. Inevitably, sometimes security compromises happen and a person or business has to change addresses. Before sending money, you should ask the recipient for their current receiving address, so you don't accidentally send money to a malicious user who has taken control of a compromised old address.
## How Direct XRP Payments Are Processed
From a relatively high level, the XRP Ledger's transaction processing engine applies a direct XRP payment as follows:
1. It validates the parameters of the `Payment` transaction. If the transaction is structured to send and deliver XRP, the transaction processing engine recognizes it as a direct XRP-to-XRP payment. Validation checks include:
- Checking that all fields are formatted correctly. For example, for direct XRP payments, the `Amount` field must be drops of XRP.
- Checking that the sending address is a funded [account](../../accounts/accounts.md) in the XRP Ledger.
- Checking that all provided signatures are valid for the sending address.
- Confirming that the destination address is different than the sender address. (It is not sufficient to send to the same address with a different [destination tag](../source-and-destination-tags.md).)
- Confirming that the sender has a high enough XRP balance to send the payment.
If any check fails, the payment fails.
2. It checks whether the receiving address is a funded account.
- If the receiving address is funded, the engine checks any additional requirements for receiving payments, such as [Deposit Authorization](../../accounts/deposit-authorization.md) or [`RequireDest`](../source-and-destination-tags.md#requiring-tags). If the payment does not satisfy any of these additional requirements, the payment fails.
- If the receiving address is not funded, it checks whether the payment would deliver enough XRP to meet the minimum [account reserve](../../accounts/reserves.md). If not, the payment fails.
3. It debits the sending account by an amount of XRP specified by the `Amount` field plus the XRP to be destroyed for the [transaction cost](../transaction-cost.md) and credits the receiving account for the same amount.
If necessary, it creates a new account (`AccountRoot` object) for the receiving address. The new account's starting balance is equal to the `Amount` of the payment.
The engine adds a `delivered_amount` field to the [transaction's metadata](../transaction-metadata.md) to indicate how much was delivered. You should always use `delivered_amount`, **not** the `Amount` field, to avoid being tricked about how much XRP you received. (Cross-currency "Partial Payments" can deliver less XRP than stated in the `Amount` field.) For more information, see [Partial Payments](partial-payments.md).
## Comparison to Other Payment Types
- **Direct XRP Payments** are the only way to both send and receive XRP in a single transaction. They are a good balance of speed, simplicity, and low cost.
- [Cross-currency payments](cross-currency-payments.md) also use the `Payment` transaction type, but can send any combination of XRP and non-XRP [tokens](../../tokens/tokens.md) except XRP-to-XRP. They can also be [partial payments](partial-payments.md). Cross-currency payments are good for payments not denominated in XRP or for taking arbitrage opportunities in the decentralized exchange.
- [Checks](checks.md) let the sender set up an obligation without transferring any money immediately. The recipient can cash it any time before it expires, but the amount is not guaranteed. Checks can send either XRP or [tokens](../../tokens/tokens.md). Checks are good for giving the recipient the autonomy to claim the payment.
- [Escrow](escrow.md) sets aside XRP which can be claimed by its intended recipient when certain conditions are met. The XRP amount is fully guaranteed and cannot be otherwise used by the sender unless the Escrow expires. Escrow is good for smart contracts in large amounts.
- [Payment Channels](payment-channels.md) set aside XRP. The recipient can claim XRP from the channel in bulk using signed authorizations. Individual authorizations can be verified without sending a full XRP Ledger transaction. Payment channels are good for extremely high-volume micropayments or "streaming" payments.
<!--
## See Also
- **Concepts:**
- [Payment System Basics](payment-system-basics.html)
- **Tutorials:**
- [Send XRP (Interactive Tutorial)](send-xrp.html)
- [Monitor Incoming Payments with WebSocket](monitor-incoming-payments-with-websocket.html)
- **References:**
- [Payment transaction][]
- [Transaction Results](transaction-results.html)
- [account_info method][] - for checking XRP balances
-->

152
content/concepts/transactions/payments/escrow.md Normal file
View File

@@ -0,0 +1,152 @@
---
html: escrow.html
parent: payments.html
blurb: Escrow holds funds and delivers them when specified criteria are fulfilled.
labels:
- Transactions
---
# Escrow
Escrow is a feature of the XRP Ledger that allows you to send conditional XRP payments. These conditional payments, called _escrows_, set aside XRP and deliver it later when certain conditions are met. Conditions to successfully finish an escrow include time-based unlocks and `crypto-conditions`. Escrows can also be set to expire if not finished in time.
The XRP set aside in an escrow is locked up. No one can use or destroy the XRP until the escrow has been successfully finished or canceled. Before the expiration time, only the intended receiver can get the XRP. After the expiration time, the XRP can only be returned to the sender.
## Usage
<!--{# Diagram sources: https://docs.google.com/presentation/d/1C-_TLkkoQEH7KJ6Gjwa1gO6EX17SLiJ8lxvFcAl6Rxo/ #}-->
[![Escrow Flow Diagram (Successful finish)](../../../../img/escrow-success-flow.png)](../../../../img/escrow-success-flow.png)
**Step 1:** To send an escrow, the sender uses an `EscrowCreate` transaction to lock up some XRP. This transaction defines a finish time, an expiration time, or both. The transaction may also define a crypto-condition that must be fulfilled to finish the escrow. This transaction must define an intended recipient for the XRP; the recipient _might_ be the same as the sender.
**Step 2:** After this transaction has been processed, the XRP Ledger has an Escrow object that holds the escrowed XRP. This object contains the properties of the escrow as defined by the transaction that created it. If this escrow has a finish time, no one can access the XRP before then.
**Step 3:** The recipient, or any other XRP Ledger address, sends an `EscrowFinish` transaction to deliver the XRP. If the correct conditions are met, this destroys the Escrow object in the ledger and credits the XRP to the intended recipient. If the escrow has a crypto-condition, this transaction must include a fulfillment for that condition. If the escrow has an expiration time that has already passed, the EscrowFinish transaction instead fails with the code [`tecNO_PERMISSION`](../transaction-results/tec-codes.html).
### Expiration Case
[![Escrow Flow Diagram (Expired escrow)](../../../../img/escrow-cancel-flow.png)](../../../../img/escrow-cancel-flow.png)
All escrows start the same way, so **Steps 1 and 2** are the same as in the successful case.
**Step 3a:** If the escrow has an expiration time, and it has not been successfully finished before then, the escrow is considered expired. It continues to exist in the XRP Ledger, but can no longer successfully finish. (Expired objects remain in the ledger until a transaction modifies them. Time-based triggers cannot change the ledger contents.)
**Step 4a:** The sender, or any other XRP Ledger address, sends an `EscrowCancel` transaction to cancel the expired escrow. This destroys the Escrow object in the ledger and returns the XRP to the sender.
<!-- SPELLING_IGNORE: 3a, 4a -->
## Limitations
Escrow is designed as a feature to enable the XRP Ledger to be used in the `Interledger Protocol` and with other smart contracts. The current version has a modest scope to avoid complexity.
- Escrow only works with XRP, not tokens.
- Escrow requires sending at least two transactions: one to create the escrow, and one to finish or cancel it. Thus, it may not be financially sensible to escrow payments for very small amounts, because the participants must destroy the [transaction cost](../transaction-cost.md) of the two transactions.
- When using Crypto-Conditions, the [cost of the transaction to finish the escrow](#escrowfinish-transaction-cost) is higher than usual.
- All escrows must be created with a "finish-after" time or a `crypto-condition`, or both. If the escrow does not have a finish-after time, it must have an expiration time.
**Note:** The _fix1571 amendment_ changed the requirements for creating an escrow. Escrows created before that amendment could provide an expiration time with no condition or finish-after time. Anyone can finish such escrows immediately (sending the funds to the intended recipient).
- None of the time values can be in the past when the escrow-creating transaction executes.
- Timed releases and expirations are limited to the resolution of XRP Ledger closes. This means that, in practice, times may be rounded to approximately 5 second intervals, depending on exactly when the ledgers close.
- The only supported `crypto-condition` type is PREIMAGE-SHA-256.
Escrow provides strong guarantees that are best suited for high-value, low-quantity payments. [Payment Channels](payment-channels.md) are better suited for fast, low-value payments. Of course, unconditional payments are also preferable for many use cases.
## State Diagram
The following diagram shows the states an Escrow can progress through:
[![State diagram showing escrows going from Held → Ready/Conditionally Ready → Expired](../../../../img/escrow-states.png)](../../../../img/escrow-states.png)
The diagram shows three different cases for three possible combinations of the escrow's "finish-after" time (`FinishAfter` field), crypto-condition (`Condition` field), and expiration time (`CancelAfter` field):
- **Time-based Escrow (left):** With only a finish-after time, the escrow is created in the **Held** state. After the specified time has passed, it becomes **Ready** and anyone can finish it. If the escrow has an expiration time and no one finishes it before that time passes, then the escrow becomes **Expired**. In the expired state, an escrow cannot be finished, and anyone can cancel it. If the escrow does not have a `CancelAfter` field, it never expires and cannot be canceled.
- **Combination Escrow (center):** If the escrow specifies both a crypto-condition (`Condition` field) _and_ a "finish-after" time (`FinishAfter` field), the escrow is **Held** until its finish-after time has passed. Then it becomes **Conditionally Ready**, and can finish it if they supply the correct fulfillment to the crypto-condition. If the escrow has an expiration time (`CancelAfter` field), and no one finishes it before that time passes, then the escrow becomes **Expired**. In the expired state, an escrow cannot be finished, and anyone can cancel it. If the escrow does not have a `CancelAfter` field, it never expires and cannot be canceled.
- **Conditional Escrow (right):** If the escrow specifies a crypto-condition (`Condition` field) and not a finish-after time, the escrow becomes **Conditionally Ready** immediately when it is created. During this time, anyone can finish the escrow, but only if they supply the correct fulfillment to the crypto-condition. If no one finishes the escrow before its expiration time (`CancelAfter` field), the escrow becomes **Expired**. (An escrow without a finish-after time _must_ have an expiration time.) In the expired state, the escrow can no longer be finished, and anyone can cancel it.
## Availability of Escrow
Conditional payments have been enabled by the ["Escrow" Amendment](../../../../amendments/known-amendments.md#escrow) to the XRP Ledger Consensus Protocol since 2017-03-31. A previous version of the same functionality was available on the XRP Ledger Test Net by the name "Suspended Payments" (SusPay) in 2016.
When testing in stand-alone mode, you can force the Escrow feature to be enabled locally regardless of the amendment status. Add the following stanza to your `rippled.cfg`:
[features]
Escrow
You can check the status of the Escrow amendment using the `feature` method.
## EscrowFinish Transaction Cost
When using `crypto-conditions`, the EscrowFinish transaction must pay a [higher transaction cost](../transaction-cost.md#special-transaction-costs) because of the higher processing load involved in verifying the crypto-condition fulfillment.
If the escrow is purely time-locked with no crypto-condition, the EscrowFinish costs only the standard [transaction cost](../transaction-cost.html) for a reference transaction.
The additional transaction cost required is proportional to the size of the fulfillment. Currently, an EscrowFinish with a fulfillment requires a minimum transaction cost of **330 drops of XRP plus 10 drops per 16 bytes in the size of the fulfillment**. If the transaction is [multi-signed](../multi-signing.md), the cost of multi-signing is added to the cost of the fulfillment.
<!--
[drops of XRP](basic-data-types.html#specifying-currency-amounts)
-->
**Note:** The above formula is based on the assumption that the reference cost of a transaction is 10 drops of XRP.
If [Fee Voting](../../../xrpl/fee-voting.html) changes the `reference_fee` value, the formula scales based on the new reference cost. The generalized formula for an EscrowFinish transaction with a fulfillment is as follows:
```
reference_fee * (signer_count + 33 + (fulfillment_bytes / 16))
```
## Why Escrow?
The age-old practice of [Escrow](https://en.wikipedia.org/wiki/Escrow) enables many kinds of financial transactions that would be considered risky otherwise, especially online. By letting a trusted third party hold the money while a transaction or evaluation period is underway, both sides can be assured that the other must hold up their end of the bargain.
The Escrow feature takes this idea further by replacing the third party with an automated system built into the XRP Ledger, so that the lock up and release of funds is impartial and can be automated.
Fully automated escrow, backed by the integrity of the XRP Ledger itself, solves important problems for Ripple, and we think there are many other use cases that escrow enables. Ripple encourages the industry to find new and unique ways to put escrow to use.
### Use Case: Time-based Lock-Up
**Background:** Ripple holds a large amount of the total XRP, which it sells methodically as a way to fund and incentivize the healthy development of the XRP Ledger and related technologies. At the same time, owning such a large chunk of XRP causes problems for the company, such as:
- Individuals and businesses who use the XRP Ledger worry that their investments in XRP could be diluted or devalued if Ripple were to flood the market by selling at a higher rate than usual.
- Although flooding the market would be a long-term loss for Ripple, the possibility that the company could do so exerts downward pressure over the price of XRP, and thus decreases the value of the company's assets.
- Ripple must carefully manage ownership of its accounts to protect against digital theft and other forms of malicious behavior, even by insiders.
**Solution:** By placing 55 billion XRP into time-based escrows, Ripple ensures that the supply of XRP in circulation is predictable and increases at a slow but steady rate. Others who hold XRP know that Ripple cannot flood the market, even if the company's priorities or strategy changes.
Placing the money into escrow does not directly protect Ripple's holdings from malicious actors, but it sharply reduces the amount of XRP that can be quickly stolen or redirected if a malicious actor gains temporary control over Ripple's XRP accounts. This reduces the risk of catastrophic losses of XRP and increases the time for Ripple to detect, prevent, and track down unintended uses of Ripple's XRP assets.
### Use Case: Interledger Payments
**Background:** In the quickly-developing world of financial technology, one of the core challenges is coordinating activities that cross multiple digital money systems, or ledgers. Many proposed solutions to this problem (including early views of the XRP Ledger!) can be reduced to creating "one ledger to rule them all." Ripple believes no single system can meet the needs of everyone in the world: in fact, some desirable features are mutually exclusive. Instead, Ripple believes that an interconnected network of ledgers—an _interledger_—is the true future of financial technology. The `Interledger Protocol` defines standards for making as many systems as possible connect securely and smoothly.
The most fundamental principle of inter-ledger payments is _conditional transfers_. Multi-hop payments have a risk problem: the more hops in the middle, the more places the payment can fail. Interledger solves this with the financial equivalent of a "[two-phase commit](https://en.wikipedia.org/wiki/Two-phase_commit_protocol)", where the two steps are (1) prepare conditional transfers, then (2) fulfill the conditions to execute the transfers. The Interledger project defined a `crypto-conditions` specification to standardize automated ways to define and verify conditions, and settled on SHA-256 hashes as a "common denominator" of such conditions.
**Solution:** The Escrow feature makes the XRP Ledger ideal for bridging multi-hop payments using the Interledger Protocol, because it natively supports transfers that deliver XRP based on PREIMAGE-SHA-256 crypto-conditions, and it executes those transfers within seconds of being presented with the matching fulfillment.
<!--
## See Also
For more information about Escrow in the XRP Ledger, see the following:
- [Escrow Tutorials](use-escrows.html)
- [Send a Time-Held Escrow](send-a-time-held-escrow.html)
- [Send a conditionally-held escrow](send-a-conditionally-held-escrow.html)
- [Look up escrows by sender or receiver](look-up-escrows.html)
- [Transaction Reference](transaction-formats.html)
- [EscrowCreate transaction][]
- [EscrowFinish transaction][]
- [EscrowCancel transaction][]
- [Ledger Reference](ledger-data-formats.html)
- [Escrow object](escrow-object.html)
For more information on Interledger and how conditional transfers enable secure payments across multiple ledgers, see [Interledger Architecture](https://interledger.org/rfcs/0001-interledger-architecture/).
For more information on Ripple's 55-billion XRP lock-up, see [Ripple's Insights Blog](https://ripple.com/insights/ripple-to-place-55-billion-xrp-in-escrow-to-ensure-certainty-into-total-xrp-supply/).
-->

138
content/concepts/transactions/payments/partial-payments.md Normal file
View File

@@ -0,0 +1,138 @@
---
html: partial-payments.html
parent: payments.html
blurb: Partial payments are useful for returning payments without incurring additional costs to oneself.
labels:
- Transactions
---
# Partial Payments
In the default case, the `Amount` field of a `Payment` transaction in the XRP Ledger specifies the exact amount to deliver, after charging for exchange rates and [transfer fees. The "Partial Payment" flag (`tfPartialPayment`) allows a payment to succeed by reducing the amount received instead of increasing the amount sent. Partial payments are useful for returning payments without incurring additional costs to oneself.
<!-- (`tfPartialPayment`](payment.md#payment-flags)) -->
<!-- [returning payments](become-an-xrp-ledger-gateway.md#bouncing-payments) -->
The amount of XRP used for the [transaction cost](../transaction-cost.md) is always deducted from the sender’s account, regardless of the type of transaction.
Partial payments can be used to exploit naive integrations with the XRP Ledger to steal money from exchanges and gateways. The [Partial Payments Exploit](#partial-payments-exploit) section of this document describes how this exploit works and how you can avoid it.
## Semantics
### Without Partial Payments
When sending a Payment that does not use the Partial Payment flag, the `Amount` field of the transaction specifies the exact amount to deliver, and the `SendMax` field specifies the maximum amount and currency to send. If a payment cannot deliver the full `Amount` without exceeding the `SendMax` parameter, or the full amount cannot be delivered for any other reason, the transaction fails. If the `SendMax` field is omitted from the transaction instructions, it is considered to be equal to the `Amount`. In this case, the payment can only succeed if the total amount of fees is 0.
In other words:
Amount + (fees) = (sent amount) ≤ SendMax
In this formula, "fees" refers to [transfer fees](../../tokens/transfer-fees.md) and currency exchange rates. The "sent amount" and the delivered amount (`Amount`) may be denominated in different currencies and converted by consuming Offers in the XRP Ledger's decentralized exchange.
**Note:** The `Fee` field of the transaction refers to the XRP [transaction cost](../transaction-cost.md), which is destroyed to relay the transaction to the network. The exact transaction cost specified is always debited from the sender and is completely separate from the fee calculations for any type of payment.
### With Partial Payments
When sending a Payment that has the Partial Payment flag enabled, the `Amount` field of the transaction specifies a maximum amount to deliver. Partial payments can succeed at sending _some_ of the intended value despite limitations including fees, not enough liquidity, not enough space in the receiving account's trust lines, or other reasons.
The optional `DeliverMin` field specifies a minimum amount to deliver. The `SendMax` field functions the same as with non-partial payments. The partial payment transaction is successful if it delivers any amount equal or greater than the `DeliverMin` field without exceeding the `SendMax` amount. If the `DeliverMin` field is not specified, a partial payment can succeed by delivering any positive amount.
In other words:
Amount ≥ (Delivered Amount) = SendMax - (Fees) ≥ DeliverMin > 0
### Partial Payment Limitations
Partial Payments have the following limitations:
- A partial payment cannot provide the XRP to fund an address; this case returns the result code `telNO_DST_PARTIAL`.
- Direct XRP-to-XRP payments cannot be partial payments; this case returns the result code `temBAD_SEND_XRP_PARTIAL`.
- However, cross-currency payments that involve XRP as one of the currencies _can_ be partial payments.
<!-- [result code]: transaction-results.html -->
### The `delivered_amount` Field
To help understand how much a partial payment actually delivered, the metadata of a successful Payment transaction includes a `delivered_amount` field. This field describes the amount actually delivered, in the same format as the `Amount` field.
<!-- [same format](basic-data-types.html#specifying-currency-amounts) -->
For non-partial payments, the `delivered_amount` field of the transaction metadata is equal to the `Amount` field of the transaction. When a payment delivers [tokens](../../tokens/tokens.md), the `delivered_amount` might be slightly different than the `Amount` field due to rounding.
The delivered amount is **not available** for transactions that meet **both** of the following criteria:
- Is a partial payment
- Is included in a validated ledger before 2014-01-20
If both conditions are true, then `delivered_amount` contains the string value `unavailable` instead of an actual amount. If this happens, you can only determine the actual delivered amount by reading the `AffectedNodes` in the transaction's metadata. If the transaction delivered tokens and the `issuer` of the `Amount` is the same account as the `Destination` address, the delivered amount may be divided among multiple `AffectedNodes` members representing trust lines to different counterparties.
You can find the `delivered_amount` field in the following places:
| API | Method | Field |
|-----|--------|-------|
| JSON-RPC / WebSocket | `account_tx` method | `result.transactions` array members' `meta.delivered_amount` |
| JSON-RPC / WebSocket | `tx` method | `result.meta.delivered_amount` |
| JSON-RPC / WebSocket | `transaction_entry` method | `result.metadata.delivered_amount` |
| JSON-RPC / WebSocket | `ledger` method (with transactions expanded) | `result.ledger.transactions` array members' `metaData.delivered_amount` New in: rippled 1.2.1 |
| WebSocket | Transaction subscriptions](subscribe.md#transaction-streams) | Subscription messages' `meta.delivered_amount` New in: rippled 1.2.1 |
| ripple-lib v1.x | `getTransaction` method | `outcome.deliveredAmount` |
| ripple-lib v1.x | `getTransactions` method | array members' `outcome.deliveredAmount` |
WebSocket: http-websocket-apis.html
JSON-RPC / WebSocket: http-websocket-apis.html
<!-- [Transaction subscriptions](subscribe.md#transaction-streams) -->
## Partial Payments Exploit
If a financial institution's integration with the XRP Ledger assumes that the `Amount` field of a Payment is always the full amount delivered, malicious actors may be able to exploit that assumption to steal money from the institution. This exploit can be used against gateways, exchanges, or merchants as long as those institutions' software does not process partial payments correctly.
**The correct way to process incoming Payment transactions is to use [the `delivered_amount` metadata field](#the-delivered_amount-field),** not the `Amount` field. This way, an institution is never mistaken about how much it _actually_ received.
### Exploit Scenario Steps
To exploit a vulnerable financial institution, a malicious actor does something like this:
1. The malicious actor sends a Payment transaction to the institution. This transaction has a large `Amount` field and has the **`tfPartialPayment`** flag enabled.
2. The partial payment succeeds (result code `tesSUCCESS`) but actually delivers a very small amount of the currency specified.
3. The vulnerable institution reads the transaction's `Amount` field without looking at the `Flags` field or `delivered_amount` metadata field.
4. The vulnerable institution credits the malicious actor in an external system, such as the institution's own ledger, for the full `Amount`, despite only receiving a much smaller `delivered_amount` in the XRP Ledger.
5. The malicious actor withdraws as much of the balance as possible to another system before the vulnerable institution notices the discrepancy.
- Malicious actors usually prefer to convert the balance to another crypto-currency such as Bitcoin, because blockchain transactions are usually irreversible. With a withdrawal to a fiat currency system, the financial institution may be able to reverse or cancel the transaction several days after it initially executes.
- In the case of an exchange, the malicious actor can also withdraw an XRP balance directly back into the XRP Ledger.
In the case of a merchant, the order of operations is slightly different, but the concept is the same:
1. The malicious actor requests to buy a large amount of goods or services.
2. The vulnerable merchant invoices the malicious actor for the price of those goods and services.
3. The malicious actor sends a Payment transaction to the merchant. This transaction has a large `Amount` field and has the **`tfPartialPayment`** flag enabled.
4. The partial payment succeeds (result code `tesSUCCESS`) but delivers only a very small amount of the currency specified.
5. The vulnerable merchant reads the transaction's `Amount` field without looking at the `Flags` field or `delivered_amount` metadata field.
6. The vulnerable merchant treats the invoice as paid and provides the goods or services to the malicious actor, despite only receiving a much smaller `delivered_amount` in the XRP Ledger.
7. The malicious actor uses, resells, or absconds with the goods and services before the merchant notices the discrepancy.
### Further Mitigations
Using [the `delivered_amount` field](#the-delivered_amount-field) when processing incoming transactions is enough to avoid this exploit. Still, additional proactive business practices can also avoid or mitigate the likelihood of this and similar exploits. For example:
- Add additional sanity checks to your business logic for processing withdrawals. Never process a withdrawal if the total balance you hold in the XRP Ledger does not match your expected assets and obligations.
- Follow "Know Your Customer" guidelines and strictly verify your customers' identities. You may be able to recognize and block malicious users in advance, or pursue legal action against a malicious actor who exploits your system.
<!--
## See Also
- **Tools:**
- [Transaction Sender](tx-sender.html)
- **Concepts:**
- [Transaction Basics](transaction-basics.html)
- **Tutorials:**
- [Look Up Transaction Results](look-up-transaction-results.html)
- [Monitor Incoming Payments with WebSocket](monitor-incoming-payments-with-websocket.html)
- [Use Specialized Payment Types](use-specialized-payment-types.html)
- [List XRP as an Exchange](list-xrp-as-an-exchange.html)
- **References:**
- [Payment transaction][]
- [Transaction Metadata](transaction-metadata.html)
- [account_tx method][]
- [tx method][] -->

50
content/concepts/transactions/payments/payment-channels.md Normal file
View File

@@ -0,0 +1,50 @@
---
html: payment-channels.html
parent: payments.html
blurb: Payment channels allow asynchronous XRP payments to be divided into smaller increments and settled later.
labels:
- Transactions
---
# Payment Channels
Payment Channels are an advanced feature for sending asynchronous XRP payments that can be divided into very small increments and settled later.
The XRP for a payment channel is set aside temporarily. The sender creates _Claims_ against the channel, which the recipient verifies without sending an XRP Ledger transaction or waiting for a new ledger version to be approved by [consensus](consensus.html). (This is an _asynchronous_ process because it happens separate from the usual pattern of getting transactions approved by consensus.) At any time, the recipient can _redeem_ a Claim to receive an amount of XRP authorized by that Claim. Settling a Claim like this uses a standard XRP Ledger transaction, as part of the usual consensus process. This single transaction can encompass any number of transactions guaranteed by smaller Claims.
Because Claims can be verified individually but settled in bulk later, payment channels make it possible to conduct transactions at a rate only limited by the participants' ability to create and verify the digital signatures of those Claims. This limit is primarily based on the speed of the participants' hardware and the complexity of the signature algorithms. For maximum speed, use Ed25519 signatures, which are faster than the XRP Ledger's default secp256k1 ECDSA signatures. Research has [demonstrated the ability to create over Ed25519 100,000 signatures per second and to verify over 70,000 per second](https://ed25519.cr.yp.to/ed25519-20110926.pdf) on commodity hardware in 2011.
## Why Use Payment Channels?
The process of using a payment channel always involves two parties, a payer and a payee. The payer is an individual person or institution using the XRP Ledger who is a customer of the payee. The payee is a person or business who receives XRP as payment for goods or services.
Payment Channels do not intrinsically specify anything about what you can buy and sell with them. However, the types of goods and services that are a good fit for payment channels are:
- Things that can be transmitted near-instantly, like digital items
- Inexpensive things, where the cost of processing a transaction is a non-trivial part of the price
- Things normally bought in bulk, where the exact quantity desired is not known in advance
## Payment Channel Lifecycle
The following diagram summarizes the lifecycle of a payment channel:
{{ include_svg("img/paychan-flow.svg", "Payment Channel Flow Diagram") }}
<!--
## See Also
- **Related Concepts:**
- [Escrow](escrow.html), a similar feature for higher-value, lower-speed conditional XRP payments.
- **Tutorials and Use Cases:**
- [Use Payment Channels](use-payment-channels.html), a tutorial stepping through the process of using a payment channel.
- [Open a Payment Channel to Enable an Inter-Exchange Network](open-a-payment-channel-to-enable-an-inter-exchange-network.html)
- **References:**
- [channel_authorize method][]
- [channel_verify method][]
- [PayChannel object](paychannel.html)
- [PaymentChannelClaim transaction][]
- [PaymentChannelCreate transaction][]
- [PaymentChannelFund transaction][]
-->

33
content/concepts/transactions/payments/payments.md Normal file
View File

@@ -0,0 +1,33 @@
---
html: payments.html
parent: transactions.html
blurb: tef code definitions.
labels:
- Transactions
---
# Payment Types
The XRP Ledger supports point-to-point XRP payments alongside other, more specialized payment types.
- [Direct XRP Payments](direct-xrp-payments.md)
Direct XRP payments are the simplest way to send value in the XRP Ledger.
- [Cross-Currency Payments](cross-currency-payments.md)
Cross-currency payments atomically deliver a different currency than they send by converting through paths and order books.
- [Checks](checks.md)
Checks let users create deferred payments that can be canceled or cashed by the intended recipients.
- [Escrow](escrow.md)
Escrows set aside XRP and deliver it later when certain conditions are met. Escrows can depend on time limits, cryptographic conditions, or both.
- [Partial Payments](partial-payments.md)
Partial payments subtract fees from the amount sent, delivering a flexible amount. Partial payments are useful for returning unwanted payments without incurring additional costs.
- [Payment Channels](payment-channels.md)
Payment Channels enable fast, asynchronous XRP payments that can be divided into very small increments and settled later.