Updates to support tokens in payment channels and escrows

docs/concepts/payment-types/escrow.md

@@ -10,7 +10,7 @@ labels:
 
 Traditionally, an escrow is a contract between two parties to facilitate financial transactions. An impartial third party receives and holds funds, and only releases them to the intended recipient when conditions specified by the contract are met. This method ensures both parties meet their obligations.
 
-The XRP Ledger takes escrow a step further, replacing the third party with an automated system built into the ledger. An escrow locks up XRP, which can't be used or destroyed until conditions are met.
+The XRP Ledger takes escrow a step further, replacing the third party with an automated system built into the ledger. An escrow locks up XRP or fungible tokens, which can't be used or destroyed until conditions are met.
 
 ## Types of Escrow
 
@@ -24,15 +24,15 @@ The XRP Ledger supports three types of escrow:
 
 1. The sender creates an escrow using the `EscrowCreate` transaction. This transaction defines:
 
-    - An amount of XRP to lock up.
-    - The conditions to release the XRP.
-    - The recipient of the XRP.
+    - An number of XRP or fungible tokens to lock up.
+    - The conditions to release the XRP or fungible tokens.
+    - The recipient of the XRP or fungible tokens.
 
-2. When the transaction is processed, the XRP Ledger creates an `Escrow` object that holds the escrowed XRP.
+2. When the transaction is processed, the XRP Ledger creates an `Escrow` object that holds the escrowed XRP or fungible token.
 
-3. The recipient sends an `EscrowFinish` transaction to deliver the XRP. If the conditions have been met, this destroys the `Escrow` object and delivers the XRP to the recipient.
+3. The recipient sends an `EscrowFinish` transaction to deliver the XRP or fungible tokens. If the conditions have been met, this destroys the `Escrow` object and delivers the XRP or fungible tokens to the recipient.
 
-    {% admonition type="info" name="Note" %}If the escrow has an expiration time and isn't successfully finished before then, the escrow becomes expired. An expired escrow remains in the ledger until an `EscrowCancel` transaction cancels it, destroying the `Escrow` object and returning the XRP to the sender.{% /admonition %}
+    {% admonition type="info" name="Note" %}If the escrow has an expiration time and isn't successfully finished before then, the escrow becomes expired. An expired escrow remains in the ledger until an `EscrowCancel` transaction cancels it, destroying the `Escrow` object and returning the escrowed XRP or fungible tokens to the sender.{% /admonition %}
 
 ## Escrow States
 
@@ -51,7 +51,6 @@ The diagram shows three different cases for three possible combinations of the e
 
 ## Limitations
 
-- Escrow only works with XRP, not tokens.
 - The costs can make it infeasible for small amounts.
     - Escrow requires two transactions: one to create the escrow, and one to finish or cancel it. Crypto-Conditions incur a higher [transaction cost](../transactions/transaction-cost.md) than usual.
     - While the escrow is incomplete, the sender is responsible for the [reserve requirement](../accounts/reserves.md) of the `Escrow` object.
@@ -66,7 +65,7 @@ When using crypto-conditions, the EscrowFinish transaction must pay a [higher tr
 
 The additional transaction cost required is proportional to the size of the fulfillment. If the transaction is [multi-signed](../accounts/multi-signing.md), the cost of multi-signing is added to the cost of the fulfillment.
 
-Currently, an EscrowFinish with a fulfillment requires a minimum transaction cost of **330 [drops of XRP](../../references/protocol/data-types/basic-data-types.md#specifying-currency-amounts) plus 10 drops per 16 bytes in the size of the fulfillment**.
+Currently, an EscrowFinish with a fulfillment requires a minimum transaction cost of **330 [drops of XRP](../../references/protocol/data-types/basic-data-types.md#specifying-currency-amounts)** plus 10 drops per 16 bytes in the size of the fulfillment**.
 
 {% admonition type="info" name="Note" %}The above formula is based on the assumption that the reference cost of a transaction is 10 drops of XRP.{% /admonition %}
 
@@ -90,7 +89,4 @@ For more information about Escrow in the XRP Ledger, see the following:
 - [Ledger Reference](../../references/protocol/ledger-data/index.md)
     - [Escrow object](../../references/protocol/ledger-data/ledger-entry-types/escrow.md)
 
-
-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/).
-
 {% raw-partial file="/docs/_snippets/common-links.md" /%}

docs/concepts/payment-types/payment-channels.md

@@ -1,43 +1,39 @@
 ---
-html: payment-channels.html
-parent: payment-types.html
 seo:
-    description: Payment Channels enable fast, asynchronous XRP payments that can be divided into very small increments and settled later.
+    description: Payment Channels enable fast, asynchronous payments that can be divided into very small increments and settled later.
 labels:
   - Payment Channels
   - Smart Contracts
 ---
 # Payment Channels
 
-Payment Channels are an advanced feature for sending "asynchronous" XRP payments that can be divided into very small increments and settled later.
+Payment Channels are an advanced feature for sending "asynchronous" 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-protocol/index.md). (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.
+The XRP or fungible tokens for a payment channel are 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-protocol/index.md). (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 or fungible tokens 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.
+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 or fungible tokens 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:
 
 [{% inline-svg file="/docs/img/paychan-flow.svg" /%}](/docs/img/paychan-flow.svg "Payment Channel Flow Diagram")
 
-
 ## See Also
 
 - **Related Concepts:**
-    - [Escrow](escrow.md), a similar feature for higher-value, lower-speed conditional XRP payments.
+    - [Escrow](escrow.md), a similar feature for higher-value, lower-speed conditional payments.
 - **Tutorials and Use Cases:**
     - [Use Payment Channels](../../tutorials/how-tos/use-specialized-payment-types/use-payment-channels/index.md), a tutorial stepping through the process of using a payment channel.
     - [Open a Payment Channel to Enable an Inter-Exchange Network](../../tutorials/how-tos/use-specialized-payment-types/use-payment-channels/open-a-payment-channel-to-enable-an-inter-exchange-network.md)

docs/references/http-websocket-apis/public-api-methods/account-methods/account_channels.md

@@ -59,11 +59,14 @@ The request includes the following parameters:
 | Field                 | Type                 | Required? | Description |
 |:----------------------|:---------------------|:----------|-------------|
 | `account`             | String - [Address][] | Yes       | Look up channels where this account is the channel's owner/source. |
+| `amount`              | Object or String     | No        | The total amount allocated to this channel. |
+| `balance`             | Object or String     | No        | The total amount paid out from this channel, as of the ledger version used. (You can calculate the amount left in the channel by subtracting `balance` from `amount`). |
 | `destination_account` | String - [Address][] | No        | A second account; if provided, filter results to payment channels whose destination is this account. |
 | `ledger_hash`         | String               | No        | The unique hash of the ledger version to use. (See [Specifying Ledgers][]) |
 | `ledger_index`        | Number or String     | No        | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
 | `limit`               | Number               | No        | Limit the number of transactions to retrieve. Cannot be less than 10 or more than 400. Positive values outside this range are replaced with the closest valid option. The default is 200. |
 | `marker`              | [Marker][]           | No        | Value from a previous paginated response. Resume retrieving data where that response left off. |
+| `transfer_rate`       | Number               | No        | The fee to charge when users make claims on a payment channel, initially set on the creation of a payment channel and updated on subsequent funding or claim transactions. |
 
 ## Response Format
 
@@ -174,10 +177,10 @@ Each Channel Object has the following fields:
 | Field                 | Type             | Description                       |
 |:----------------------|:-----------------|:----------------------------------|
 | `account`             | String           | The owner of the channel, as an [Address][]. |
-| `amount`              | String           | The total amount of [XRP, in drops][] allocated to this channel. |
-| `balance`             | String           | The total amount of [XRP, in drops][], paid out from this channel, as of the ledger version used. (You can calculate the amount of XRP left in the channel by subtracting `balance` from `amount`.) |
+| `amount`              | Object or String | The total amount of [XRP, in drops][] or fungible tokens allocated to this channel. |
+| `balance`             | String           | The total amount of [XRP, in drops][] or fungible tokens paid out from this channel, as of the ledger version used. (You can calculate the amount left in the channel by subtracting `balance` from `amount`.) |
 | `channel_id`          | String           | A unique ID for this channel, as a 64-character hexadecimal string. This is also the [ID of the channel object](../../../protocol/ledger-data/ledger-entry-types/paychannel.md#paychannel-id-format) in the ledger's state data. |
-| `destination_account` | String           | The destination account of the channel, as an [Address][]. Only this account can receive the XRP in the channel while it is open. |
+| `destination_account` | String           | The destination account of the channel, as an [Address][]. Only this account can receive the `amount` in the channel while it is open. |
 | `settle_delay`        | Unsigned Integer | The number of seconds the payment channel must stay open after the owner of the channel requests to close it. |
 | `public_key`          | String           | _(May be omitted)_ The public key for the payment channel in the XRP Ledger's [base58][] format. Signed claims against this channel must be redeemed with the matching key pair. |
 | `public_key_hex`      | String           | _(May be omitted)_ The public key for the payment channel in hexadecimal format, if one was specified at channel creation. Signed claims against this channel must be redeemed with the matching key pair. |

docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md

@@ -65,6 +65,8 @@ The request accepts the following parameters:
 | `limit`          | Number               | No        | Limit the number of trust lines to retrieve. The server may return less than the specified limit, even if there are more pages of results. Must be within the inclusive range 10 to 400.  Positive values outside this range are replaced with the closest valid option. The default is 200. |
 | `marker`         | [Marker][]           | No        | Value from a previous paginated response. Resume retrieving data where that response left off. |
 | `peer`           | String - [Address][] | No        | A second account; if provided, filter results to trust lines connecting the two accounts. |
+| `locked_balance` | Object              | No         | The total amount locked in payment channels or escrow. |
+| `lock_count` | Number | UInt32         | No         | the total number of lock balances on a RippleState ledger object. |
 
 The following parameters are deprecated and may be removed without further notice: `ledger` and `peer_index`.
 

docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md

@@ -79,11 +79,13 @@ The request includes the following parameters:
 | `Field`                  | Type             | Required? | Description |
 |:-------------------------|:-----------------|:----------|-------------|
 | `account`                | String           | Yes       | A unique identifier for the account, most commonly the account's [Address][]. |
+| `amount`                 | Object or String | No        | The amount to be delivered by the held payment. |
 | `deletion_blockers_only` | Boolean          | No        | If `true`, the response only includes objects that would block this account from [being deleted](../../../../concepts/accounts/deleting-accounts.md). The default is `false`. |
 | `ledger_hash`            | [Hash][]         | No        | The unique hash of the ledger version to use. (See [Specifying Ledgers][]) |
 | `ledger_index`           | [Ledger Index][] | No        | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
 | `limit`                  | Number           | No        | 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][]       | No        | Value from a previous paginated response. Resume retrieving data where that response left off. |
+| `transfer_rate`          | Number           | No        | The fee to charge when users finish an escrow, initially set on the creation of an escrow contract, and updated on subsequent finish transactions. |
 | `type`                   | String           | No        | Filter results to a specific type of ledger entry. This field accepts canonical ledger entry names (case insensitive) or short names. |
 
 Valid `type` field values are:

docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_authorize.md

@@ -11,7 +11,7 @@ labels:
 
 _(Added by the [PayChan amendment][] to be enabled.)_
 
-The `channel_authorize` method creates a signature that can be used to redeem a specific amount of XRP from a payment channel.
+The `channel_authorize` method creates a signature that can be used to redeem a specific amount of XRP or fungible tokens from a payment channel.
 
 ## Request Format
 An example of the request format:
@@ -67,7 +67,7 @@ The request includes the following parameters:
 | `seed_hex`     | String  | _(Optional)_ The secret seed to use to sign the claim. This must be the same key pair as the public key specified in the channel. Must be in hexadecimal format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `passphrase`. |
 | `passphrase`   | String  | _(Optional)_ A string passphrase to use to sign the claim. This must be the same key pair as the public key specified in the channel. The [key derived from this passphrase](../../../../concepts/accounts/cryptographic-keys.md#key-derivation) must match the public key specified in the channel. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `seed_hex`. |
 | `key_type` | String | _(Optional)_ The [signing algorithm](../../../../concepts/accounts/cryptographic-keys.md#signing-algorithms) of the cryptographic key pair provided. Valid types are `secp256k1` or `ed25519`. The default is `secp256k1`. |
-| `amount` | String | Cumulative amount of XRP, in drops, to authorize. If the destination has already received a lesser amount of XRP from this channel, the signature created by this method can be redeemed for the difference. |
+| `amount` | Object or String | Cumulative amount of XRP, in drops, or fungible tokens to authorize. If the destination has already received a lesser amount from this channel, the signature created by this method can be redeemed for the difference. |
 
 The request **must** specify exactly one of `secret`, `seed`, `seed_hex`, or `passphrase`.
 
@@ -121,14 +121,14 @@ The response follows the [standard format][], with a successful result containin
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `signature` | String | The signature for this claim, as a hexadecimal value. To process the claim, the destination account of the payment channel must send a [PaymentChannelClaim transaction][] with this signature, the exact Channel ID, XRP amount, and public key of the channel. |
+| `signature` | String | The signature for this claim, as a hexadecimal value. To process the claim, the destination account of the payment channel must send a [PaymentChannelClaim transaction][] with this signature, the exact Channel ID, amount, and public key of the channel. |
 
 ## Possible Errors
 
 * Any of the [universal error types][].
 * `badKeyType` - The `key_type` parameter in the request is not a valid key type. (Valid types are `secp256k1` or `ed25519`.)
 * `badSeed` - The `secret` in the request is not a valid secret key.
-* `channelAmtMalformed` - The `amount` in the request is not a valid [XRP amount][XRP, in drops].
+* `channelAmtMalformed` - The `amount` in the request is not a valid amount.
 * `channelMalformed` - The `channel_id` in the request is not a valid Channel ID. The Channel ID should be a 256-bit (64-character) hexadecimal string.
 
 {% raw-partial file="/docs/_snippets/common-links.md" /%}