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

Merge pull request #1629 from XRPLF/IA-checks-tutorials

Browse Source 
Pull concept info out of checks tutorials.
This commit is contained in:
oeggert
2022-12-13 16:32:50 -08:00
committed by GitHub
parent b3bab06288 df8294862a
commit 39aa1b445c
8 changed files with 33 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
content/concepts/transactions/payments/checks.md
View File

@@ -7,94 +7,45 @@ labels:
---
# 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.
XRPL Ledger checks enable users to create deferred payments similar to personal paper checks. Unlike an escrow or payment channel, funds aren't set aside when a check is created, so money only moves when the check is cashed. If the sender doesn't have the funds at the time a check is cashed, the transaction fails; recipients can retry failed transactions until the check expires.
**Note:** The Checks amendment changes the expiration behavior of the `OfferCreate` transaction.
## Check Lifecycle
<!-- For more information, see [Offer Expiration](offers.html#offer-expiration). -->
1. The sender creates a check using the `CheckCreate` transaction to define:
- The recipient.
- An expiration date.
- The maximum amount that can be debited from their account.
2. After the transaction is processed, the XRP Ledger creates a `Check` object. The check can only be cancelled by the sender or receiver with a `CheckCancel` transaction.
3. The recipient submits a `CheckCash` transaction that transfers the funds and destroys the `Check` object.
**Note:** Recipients have two options for cashing checks.
- Exact Amount: They specify an exact amount to cash that doesn't exceed the check maximum.
- Flexible Amount: They specify a minimum amount to cash and the XRP Ledger delivers as much as possible up to the check maximum. If the sender doesn't have the funds to meet the minimum, the transaction fails.
4. If the check expires before the receiver cashes the check, the `Check` object remains until someone cancels it.
## Why Checks?
## Use Cases
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.
### Deposit Authorization
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 -->
**Problem:** To comply with banking regulations, financial institutions must provide documentation about the sources of funds they receive. These regulations seek to prevent illicit activity by requiring institutions to track the source and destination of all payments they process. Because of the nature of the XRP Ledger, anyone can send XRP to an institution's account on the ledger; to prevent this behavior, they'll enable deposit authorization to only receive funds they explicitly approve. <!-- 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.
**Solution:** Accounts with deposit authorization enabled can only receive funds through:
- Preauthorized Accounts
- Escrow
- Payment Channels
- Checks
Checks are the most straightforward, familiar, and flexible way to transfer funds when deposite authorization is enabled.
<!-- 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][]
@@ -105,11 +56,4 @@ For more information about Checks in the XRP Ledger, see:
- [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) -->
- [Cancel a Check](cancel-a-check.html)

2
content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md
View File

@@ -81,6 +81,8 @@ The request includes the following parameters:
| `limit` | Number | _(Optional)_ The maximum number of objects to include in the results. Must be within the inclusive range `10` to `400` on non-admin connections. The default is `200`. |
| `marker` | [Marker][] | _(Optional)_ Value from a previous paginated response. Resume retrieving data where that response left off. |
**Note:** The commandline interface to the `account_objects` command doesn't accept the `type` field. Use the [json method][] to send the JSON-RPC format request on the commandline instead.
## Response Format
An example of a successful response:

2
content/tutorials/use-specialized-payment-types/use-checks/cancel-a-check.md
View File

@@ -7,8 +7,6 @@ labels:
---
# Cancel a Check
_Added by the [Checks amendment][]._
This tutorial shows how to cancel a [Check](checks.html), which removes the [Check object from the ledger](check.html) without sending money.
You may want to cancel an incoming Check if you do not want it. You might cancel an outgoing Check if you made a mistake when sending it or if circumstances have changed. If a Check expires, it's also necessary to cancel it to remove it from the ledger so the sender gets their [owner reserve](reserves.html#owner-reserves) back.

2
content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md
View File

@@ -7,8 +7,6 @@ labels:
---
# Cash a Check for a Flexible Amount
_Added by the [Checks amendment][]._
As long as the Check is in the ledger and not expired, the specified recipient can cash it to receive a flexible amount by sending a [CheckCash transaction][] with a `DeliverMin` field. When cashing a Check in this way, the receiver gets as much as is possible to deliver, debiting the Check's sender for the Check's full `SendMax` amount or as much as is available. Cashing fails if it doesn't deliver at least the `DeliverMin` amount to the Check's recipient.
You might cash a Check for a flexible amount if you want to get as much as possible from the Check.

2
content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-an-exact-amount.md
View File

@@ -7,8 +7,6 @@ labels:
---
# Cash a Check for an Exact Amount
_Added by the [Checks amendment][]._
As long as the Check is in the ledger and not expired, the specified recipient can cash it to receive any exact amount up to the amount specified in the Check by sending a [CheckCash transaction][] with an `Amount` field. You would cash a Check this way if you want to receive a specific amount, for example to pay off an invoice or bill exactly.
The specified recipient can also [cash the check for a flexible amount](cash-a-check-for-a-flexible-amount.html).

3
content/tutorials/use-specialized-payment-types/use-checks/look-up-checks-by-recipient.md
View File

@@ -7,7 +7,7 @@ labels:
---
# Look Up Checks by Recipient
_Added by the [Checks amendment][]._
***TODO: Merge this with the look up checks by sender page.***
This tutorial shows how to look up [Checks](checks.html) by their recipient. You may also want to [look up Checks by sender](look-up-checks-by-sender.html).
@@ -15,6 +15,7 @@ This tutorial shows how to look up [Checks](checks.html) by their recipient. You
To get a list of all incoming and outgoing Checks for an account, use the `account_objects` command with the recipient account's address and set the `type` field of the request to `checks`.
<!-- Moved this note to the account_objects method page. -->
**Note:** The commandline interface to the `account_objects` command does not accept the `type` field. You can use the [json method][] to send the JSON-RPC format request on the commandline instead.
### Example Request

3
content/tutorials/use-specialized-payment-types/use-checks/look-up-checks-by-sender.md
View File

@@ -7,7 +7,7 @@ labels:
---
# Look Up Checks by Sender
_Added by the [Checks amendment][]._
***TODO: Merge this with the look up checks by recipient page.***
This tutorial shows how to look up [Checks](checks.html) by their sender. You may also want to [look up Checks by recipient](look-up-checks-by-recipient.html).
@@ -17,6 +17,7 @@ This tutorial shows how to look up [Checks](checks.html) by their sender. You ma
To get a list of all incoming and outgoing Checks for an account, use the `account_objects` command with the sending account's address and set the `type` field of the request to `checks`.
<!-- This note moved to account_objects method page. -->
**Note:** The commandline interface to the `account_objects` command does not accept the `type` field. You can use the [json method][] to send the JSON-RPC format request on the commandline instead.
### Example Request

4
content/tutorials/use-specialized-payment-types/use-checks/send-a-check.md
View File

@@ -7,11 +7,11 @@ labels:
---
# Send a Check
_Added by the [Checks amendment][]._
Sending a Check is like writing permission for an intended recipient to pull a payment from you. The outcome of this process is a [Check object in the ledger](check.html) which the recipient can cash later.
<!--> Moved to checks.md
In many cases, you want to send a [Payment][] instead of a Check, since that delivers the money directly to the recipient in one step. However, if your intended recipient uses [DepositAuth](depositauth.html), you cannot send them Payments directly, so a Check is a good alternative.
<-->
This tutorial uses the example of a fictitious company, BoxSend SG (whose XRP Ledger address is `rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za`) paying a fictitious cryptocurrency consulting company named Grand Payments (with XRP Ledger address `rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis`) for some consulting work. Grand Payments prefers be paid in XRP, but to simplify their taxes and regulation, only accepts payments they've explicitly approved.