Direct XRP Payments & restructuring

- Rename 'complex payment types' to 'specialized payment types'
- Move source/destination tag content to stand-alone pages

content/concepts/payment-system-basics/payments.md

@@ -1,40 +0,0 @@
-# Payments
-
-The basis of any financial system is _transferring value_: or, in one word, payments. The XRP Ledger supports a variety of ways to make payments, with different types specialized for various use cases. The most basic type of payment in the XRP Ledger is a direct XRP-to-XRP payment.
-
-## 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](consensus.html), a successful transaction can be created, submitted, executed, and have a completely 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][Payment] can also be used for some more specialized kinds of payments, including [cross-currency payments](cross-currency-payments.html) and [partial payments](partial-payments.html). 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.html#partial-payments-exploit) for how to avoid crediting a customer for the wrong amount.
-
-## 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](reserves.html). If the payment would not deliver enough XRP, it fails.
-
-For more information, see [Accounts](accounts.html#creating-accounts).
-
-## Blocking Incoming Payments
-
-By default, any address can send XRP to any other address. This works well for many smart contracts and for making most transactions as smooth as possible. However, you may not want to be able to receive from unknown senders because of regulatory requirements. For example, you or your business might be required to prove that you do not receive money from economically-sanctioned countries, terrorists, or known criminals. In this case, you can enable the [DepositAuth setting](depositauth.html) to block incoming payments unless you approve the sender or individual payment before receiving funds (XRP or otherwise). For more information, see [DepositAuth](depositauth.html).
-
-The [`DisallowXRP` setting](accountset.html#blocking-incoming-transactions) is a related, softer limitation which is not natively enforced in the XRP Ledger. (Doing so strictly could cause an account to become "locked" if it ran out of XRP to pay for [transaction costs](transaction-cost.html).) Instead, client applications should enforce this setting (unless explicitly overridden with user intervention) to reduce cases of accidentally sending XRP to an address that primarily deals in [issued currencies](issued-currencies.html).
-
-## Source and Destination Tags
-
-***TODO: split off from gateway guide***
-
-## See Also
-
-***TODO***

content/concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md

@@ -0,0 +1,46 @@
+# Source and Destination Tags
+
+_Source tags_ and _destination tags_ are a feature of XRP Ledger [payments](payment-types.html) that can indicate specific purposes for payments from and to multi-purpose addresses. Source and destination tags do not have direct on-ledger functionality; source and destination tags merely provide information about how off-ledger systems should process a payment. In transactions, both source and destination tags are formatted as 32-bit unsigned integers.
+
+Destination tags indicate the beneficiary or destination for a payment. For example, a payment to an [exchange](list-xrp-in-your-exchange.html) or [gateway](become-an-xrp-ledger-gateway.html) address can use a destination tag to indicate which customer to credit for the amount of the payment in that business's own systems.
+
+Source tags indicate the originator or source of a payment. Most commonly, a Source Tag is included so that the recipient of the payment knows where to send a return, or "bounced", payment. When returning an incoming payment, you should use the source tag from the incoming payment as the destination tag of the outgoing (return) payment.
+
+The practice of giving customers the ability to send and receive transactions from your XRP Ledger address using another interface is called providing _hosted accounts_. Hosted accounts typically use source and destination tags for each customer.
+
+## Rationale
+
+In other distributed ledgers, it is common to use different deposit addresses for each customer. In the XRP Ledger, an address must be a funded, permanent [account](accounts.html) to receive payments. Using this approach in the XRP Ledger wastefully consumes resources of all servers in the network, and is costly because the [reserve](reserves.html) amount must be set aside indefinitely for each address.
+
+Source and destination tags provide a more lightweight way to map deposits and payments to individual customers.
+
+## Use Cases
+
+A business may want to use source and destination tags for several purposes:
+
+- Direct mappings to customer accounts.
+- Matching return payments to the outgoing payments that prompted them.
+- Mapping payments to quotes that expire.
+- Providing disposable tags that customers can generate for specific deposits.
+
+To prevent overlap while protecting privacy, a business can divide the total range of tags available into sections for each purpose, then assign tags in an unpredictable order within the range. For example, use a hash function or a cipher such as [Hasty Pudding](http://en.wikipedia.org/wiki/Hasty_Pudding_cipher). To be safe, check for collisions with old tags before using a new tag.
+
+Assigning tags in numerical order provides less privacy to customers. Since all XRP Ledger transactions are public, assigning tags in this way can make it possible to guess which tags correspond to various users' addresses or to derive information about users' accounts based on the tags used.
+
+
+## Requiring Tags
+
+For an XRP Ledger address that may receive payments intended for several customer accounts, receiving a payment _without_ a destination tag can be a problem: it is not immediately obvious which customer to credit, which can require a manual intervention and a discussion with the sender to figure out who was the intended recipient. To reduce cases like this, you can [enable the RequireDest setting](require-destination-tags.html). That way, if a user forgets to include a destination tag in a payment, the XRP Ledger rejects their payment instead of giving you money you don't know what to do with. The user can then send the payment again, using the tag as they should have.
+
+
+## See Also
+
+- [Require Destination Tags](require-destination-tags.html)
+- [XRP Ledger Businesses](xrp-ledger-businesses.html)
+- [Payment Types](payment-types.html)
+
+
+<!--{# common link defs #}-->
+{% include '_snippets/rippled-api-links.md' %}
+{% include '_snippets/tx-type-links.md' %}
+{% include '_snippets/rippled_versions.md' %}

content/concepts/payment-types/direct-xrp-payments.md

@@ -0,0 +1,76 @@
+# Direct XRP Payments
+
+The basis of any financial system is _transferring value_: or, in one word, payments. The simplest 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](consensus.html), a successful transaction can be created, submitted, executed, and have a completely 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][Payment] can also be used for some more specialized kinds of payments, including [cross-currency payments](cross-currency-payments.html) and [partial payments](partial-payments.html). 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.html#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](reserves.html). If the payment would not deliver enough XRP, it fails.
+
+For more information, see [Accounts](accounts.html#creating-accounts).
+
+## 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.
+    - Checking that the sending address is a funded [account](accounts.html) in the XRP Ledger.
+    - Checking that all provided signatures are valid for the sending address.
+    - Confirming that the destination is different than the sender.
+    - 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, it checks whether the receiving address has any limitations on receiving payments, such as [DepositAuth](depositauth.html) or [RequireDest](source-and-destination-tags.html#requiring-tags). If the payment does not meet any such limitations, 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](reserves.html). 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.html) and credits the receiving account for the same amount.
+
+    If necessary, it creates a new account ([AccountRoot object](accountroot.html)) 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.html) 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-payment.html#partial-payments-exploit).
+
+
+## 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.html) also use the [Payment][] transaction type, but can send any combination of XRP and non-XRP [issued currencies](issued-currencies.html) except XRP-to-XRP. They can also be [partial payments](partial-payments.html). Cross-currency payments are good for payments not denominated in XRP or for taking arbitrage opportunities in the [decentralized exchange](decentralized-exchange.html).
+- [Checks](checks.html) :not_enabled: 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 issued currencies. Checks are good for giving the recipient the autonomy to claim the payment.
+- [Escrow](escrow.html) 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.html) 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
+
+- [Payment System Basics](payment-system-basics.html)
+- [Payment transaction type][Payment transaction]
+- [Transaction Results](transaction-results.html)
+- [Send XRP (Interactive Tutorial)](send-xrp.html)
+
+
+<!--{# common link defs #}-->
+{% include '_snippets/rippled-api-links.md' %}
+{% include '_snippets/tx-type-links.md' %}
+{% include '_snippets/rippled_versions.md' %}