diff --git a/docs/concepts/payment-types/escrow.md b/docs/concepts/payment-types/escrow.md index 16da562f5f..cb71c73413 100644 --- a/docs/concepts/payment-types/escrow.md +++ b/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" /%} diff --git a/docs/concepts/payment-types/payment-channels.md b/docs/concepts/payment-types/payment-channels.md index b560aa6fcc..74f17662af 100644 --- a/docs/concepts/payment-types/payment-channels.md +++ b/docs/concepts/payment-types/payment-channels.md @@ -1,24 +1,22 @@ --- -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: @@ -26,18 +24,18 @@ Payment Channels do not intrinsically specify anything about what you can buy an - 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 - + ## 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) diff --git a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_channels.md b/docs/references/http-websocket-apis/public-api-methods/account-methods/account_channels.md index 598645ad2e..e09a6cf166 100644 --- a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_channels.md +++ b/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. | diff --git a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md b/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md index ff7f7458f2..1ff39ac46b 100644 --- a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md +++ b/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`. diff --git a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md b/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md index 69f9cdfac5..b59a919901 100644 --- a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md +++ b/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: diff --git a/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_authorize.md b/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_authorize.md index ee3273cd5e..f057876f24 100644 --- a/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_authorize.md +++ b/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" /%} diff --git a/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_verify.md b/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_verify.md index a39db789e4..9ec605ec34 100644 --- a/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_verify.md +++ b/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_verify.md @@ -11,7 +11,7 @@ labels: _(Added by the [PayChan amendment][] to be enabled.)_ -The `channel_verify` method checks the validity of a signature that can be used to redeem a specific amount of XRP from a payment channel. +The `channel_verify` method checks the validity of 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: @@ -58,8 +58,8 @@ The request includes the following parameters: | Field | Type | Description | |-------|------|-------------| -| `amount` | String | The amount of [XRP, in drops][], the provided `signature` authorizes. | -| `channel_id` | String | The Channel ID of the channel that provides the XRP. This is a 64-character hexadecimal string. | +| `amount` | Object or String | The amount of [XRP, in drops][], or fungible tokens the provided `signature` authorizes. | +| `channel_id` | String | The Channel ID of the channel that provides the amount. This is a 64-character hexadecimal string. | | `public_key` | String | The public key of the channel and the key pair that was used to create the signature, in hexadecimal or the XRP Ledger's [base58][] format. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.90.0" %}Updated in: rippled 0.90.0{% /badge %} | | `signature` | String | The signature to verify, in hexadecimal. | @@ -114,7 +114,7 @@ The response follows the [standard format][], with a successful result containin |-------|------|-------------| | `signature_verified` | Boolean | If `true`, the signature is valid for the stated amount, channel, and public key. | -{% admonition type="warning" name="Caution" %}This does not indicate check that the channel has enough XRP allocated to it. Before considering a claim valid, you should look up the channel in the latest validated ledger and confirm that the channel is open and its `amount` value is equal or greater than the `amount` of the claim. To do so, use the [account_channels method][].{% /admonition %} +{% admonition type="warning" name="Caution" %}This does not check whether the channel has enough XRP allocated to it. Before considering a claim valid, you should look up the channel in the latest validated ledger and confirm that the channel is open and its `amount` value is equal or greater than the `amount` of the claim. To do so, use the [account_channels method][].{% /admonition %} ## Possible Errors diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/escrow.md b/docs/references/protocol/ledger-data/ledger-entry-types/escrow.md index 7501e507c1..f532e9962e 100644 --- a/docs/references/protocol/ledger-data/ledger-entry-types/escrow.md +++ b/docs/references/protocol/ledger-data/ledger-entry-types/escrow.md @@ -40,7 +40,7 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | Name | JSON Type | [Internal Type][] | Required? | Description | |:--------------------|:----------|:------------------|:----------|:-----------------------| | `Account` | String | AccountID | Yes | The address of the owner (sender) of this escrow. This is the account that provided the XRP, and gets it back if the escrow is canceled. | -| `Amount` | String | Amount | Yes | The amount of XRP, in drops, currently held in the escrow. | +| `Amount` | Object or String | Amount | Yes | The amount to be delivered by the payment is escrow. | | `CancelAfter` | Number | UInt32 | No | The escrow can be canceled if and only if this field is present _and_ the time it specifies has passed. Specifically, this is specified as [seconds since the Ripple Epoch][] and it "has passed" if it's earlier than the close time of the previous validated ledger. | | `Condition` | String | Blob | No | A [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1), as hexadecimal. If present, the [EscrowFinish transaction][] must contain a fulfillment that satisfies this condition. | | `Destination` | String | AccountID | Yes | The destination address where the XRP is paid if the escrow is successful. | @@ -52,6 +52,7 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | `PreviousTxnID` | String | Hash256 | Yes | The identifying hash of the transaction that most recently modified this entry. | | `PreviousTxnLgrSeq` | Number | UInt32 | Yes | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this entry. | | `SourceTag` | Number | UInt32 | No | An arbitrary tag to further specify the source for this escrow, such as a hosted recipient at the owner's address. | +| `TransferRate` | Number | UInt32 | 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. | ## {% $frontmatter.seo.title %} Flags diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/paychannel.md b/docs/references/protocol/ledger-data/ledger-entry-types/paychannel.md index 902a2fcd0d..b1a58d1ddb 100644 --- a/docs/references/protocol/ledger-data/ledger-entry-types/paychannel.md +++ b/docs/references/protocol/ledger-data/ledger-entry-types/paychannel.md @@ -42,8 +42,8 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | Name | JSON Type | [Internal Type][] | Required? | Description | |:--------------------|:----------|:------------------|:----------|:-----------------------| | `Account` | String | AccountID | Yes | The source address that owns this payment channel. This comes from the sending address of the transaction that created the channel. | -| `Amount` | String | Amount | Yes | Total [XRP, in drops][], that has been allocated to this channel. This includes XRP that has been paid to the destination address. This is initially set by the transaction that created the channel and can be increased if the source address sends a PaymentChannelFund transaction. | -| `Balance` | String | Amount | Yes | Total [XRP, in drops][], already paid out by the channel. The difference between this value and the `Amount` field is how much XRP can still be paid to the destination address with PaymentChannelClaim transactions. If the channel closes, the remaining difference is returned to the source address. | +| `Amount` | String | Amount | Yes | Total [XRP, in drops][] or tokens, that have been allocated to this channel. This includes amounts that have been paid to the destination address. This is initially set by the transaction that created the channel and can be increased if the source address sends a `PaymentChannelFund` transaction. | +| `Balance` | Object or String | Amount | Yes | Total already paid out by the channel. The difference between this value and the `Amount` field is how much can still be paid to the destination address with `PaymentChannelClaim` transactions. If the channel closes, the remaining difference is returned to the source address. | | `CancelAfter` | Number | UInt32 | No | The immutable expiration time for this payment channel, in [seconds since the Ripple Epoch][]. This channel is expired if this value is present and smaller than the previous ledger's [`close_time` field](../ledger-header.md). This is optionally set by the transaction that created the channel, and cannot be changed. | | `Destination` | String | AccountID | Yes | The destination address for this payment channel. While the payment channel is open, this address is the only one that can receive XRP from the channel. This comes from the `Destination` field of the transaction that created the channel. | | `DestinationTag` | Number | UInt32 | No | An arbitrary tag to further specify the destination for this payment channel, such as a hosted recipient at the destination address. | @@ -56,6 +56,7 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | `PublicKey` | String | Blob | Yes | Public key, in hexadecimal, of the key pair that can be used to sign claims against this channel. This can be any valid secp256k1 or Ed25519 public key. This is set by the transaction that created the channel and must match the public key used in claims against the channel. The channel source address can also send XRP from this channel to the destination without signed claims. | | `SettleDelay` | Number | UInt32 | Yes | Number of seconds the source address must wait to close the channel if it still has any XRP in it. Smaller values mean that the destination address has less time to redeem any outstanding claims after the source address requests to close the channel. Can be any value that fits in a 32-bit unsigned integer (0 to 2^32-1). This is set by the transaction that creates the channel. | | `SourceTag` | Number | UInt32 | No | An arbitrary tag to further specify the source for this payment channel, such as a hosted recipient at the owner's address. | +| `TransferRate` | Number | UInt32 | 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. | ## Channel Expiration diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md b/docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md index ff2ff67efd..974b684c22 100644 --- a/docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md +++ b/docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md @@ -58,6 +58,8 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | `HighQualityIn` | Number | UInt32 | No | The inbound quality set by the high account, as an integer in the implied ratio `HighQualityIn`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | | `HighQualityOut` | Number | UInt32 | No | The outbound quality set by the high account, as an integer in the implied ratio `HighQualityOut`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | | `LedgerEntryType` | String | UInt16 | Yes | The value `0x0072`, mapped to the string `RippleState`, indicates that this is a RippleState entry. | +| `LockCount` | Object or String | Amount | No | The total number of lock balances on a `RippleState` ledger object. | +| `LockedBalance` | Object or String | Amount | No | The total number of locked tokens on a `RippleState` ledger object. | | `LowLimit` | Object | Amount | Yes | The limit that the low account has set on the trust line. The `issuer` is the address of the low account that set this limit. | | `LowNode` | String | UInt64 | Yes | (Omitted in some historical ledgers) A hint indicating which page of the low account's owner directory links to this entry, in case the directory consists of multiple pages. | | `LowQualityIn` | Number | UInt32 | No | The inbound quality set by the low account, as an integer in the implied ratio `LowQualityIn`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | diff --git a/docs/references/protocol/transactions/types/escrowcreate.md b/docs/references/protocol/transactions/types/escrowcreate.md index b6cfb2e2af..1be482a859 100644 --- a/docs/references/protocol/transactions/types/escrowcreate.md +++ b/docs/references/protocol/transactions/types/escrowcreate.md @@ -37,7 +37,7 @@ Sequester XRP until the escrow process either finishes or is canceled. | Field | JSON Type | [Internal Type][] | Description | |:-----------------|:----------|:------------------|:--------------------------| -| `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount], to deduct from the sender's balance and escrow. Once escrowed, the XRP can either go to the `Destination` address (after the `FinishAfter` time) or returned to the sender (after the `CancelAfter` time). | +| `Amount` | Object or String | Amount | Amount of XRP or fungible tokens to deduct from the sender's balance and escrow. Once escrowed, the payment can either go to the `Destination` address (after the `FinishAfter` time) or be returned to the sender (after the `CancelAfter` time). | | `Destination` | String | AccountID | Address to receive escrowed XRP. | | `CancelAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], when this escrow expires. This value is immutable; the funds can only be returned to the sender after this time. | | `FinishAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], when the escrowed XRP can be released to the recipient. This value is immutable, and the funds can't be accessed until this time. | diff --git a/docs/references/protocol/transactions/types/paymentchannelclaim.md b/docs/references/protocol/transactions/types/paymentchannelclaim.md index bde559aeae..82fcf3c6b5 100644 --- a/docs/references/protocol/transactions/types/paymentchannelclaim.md +++ b/docs/references/protocol/transactions/types/paymentchannelclaim.md @@ -11,23 +11,23 @@ labels: _Added by the [PayChan amendment][]._ -Claim XRP from a payment channel, adjust the payment channel's expiration, or both. This transaction can be used differently depending on the transaction sender's role in the specified channel: +Claim XRP or fungible tokens from a payment channel, adjust the payment channel's expiration, or both. This transaction can be used differently depending on the transaction sender's role in the specified channel: The **source address** of a channel can: -- Send XRP from the channel to the destination with _or without_ a signed Claim. +- Send XRP or fungible tokens from the channel to the destination with _or without_ a signed Claim. - Set the channel to expire as soon as the channel's `SettleDelay` has passed. - Clear a pending `Expiration` time. -- Close a channel immediately, with or without processing a claim first. The source address cannot close the channel immediately if the channel has XRP remaining. +- Close a channel immediately, with or without processing a claim first. The source address cannot close the channel immediately if the channel has any amount remaining. The **destination address** of a channel can: -- Receive XRP from the channel using a signed Claim. -- Close the channel immediately after processing a Claim, refunding any unclaimed XRP to the channel's source. +- Receive XRP or fungible tokens from the channel using a signed Claim. +- Close the channel immediately after processing a Claim, refunding any unclaimed amount to the channel's source. **Any address** sending this transaction can: -- Cause a channel to be closed if its `Expiration` or `CancelAfter` time is older than the previous ledger's close time. Any validly-formed PaymentChannelClaim transaction has this effect regardless of the contents of the transaction. +- Cause a channel to be closed if its `Expiration` or `CancelAfter` time is older than the previous ledger's close time. Any validly formed `PaymentChannelClaim` transaction has this effect, regardless of the contents of the transaction. ## Example {% $frontmatter.seo.title %} JSON @@ -50,8 +50,8 @@ The **destination address** of a channel can: | Field | JSON Type | [Internal Type][] | Required? | Description | |:------------|:----------|:------------------|:----------|:------------| -| `Amount` | String | Amount | No | The amount of [XRP, in drops][Currency Amount], authorized by the `Signature`. This must match the amount in the signed message. This is the cumulative amount of XRP that can be dispensed by the channel, including XRP previously redeemed. | -| `Balance` | String | Amount | No | Total amount of [XRP, in drops][Currency Amount], delivered by this channel after processing this claim. Required to deliver XRP. Must be more than the total amount delivered by the channel so far, but not greater than the `Amount` of the signed claim. Must be provided except when closing the channel. | +| `Amount` | Object or String | Amount | No | The amount of [XRP, in drops][Currency Amount], or fungible tokens authorized by the `Signature`. This must match the amount in the signed message. This is the cumulative amount of XRP and fungible tokens that can be dispensed by the channel, including funds previously redeemed. | +| `Balance` | String | Amount | No | Total amount of [XRP, in drops][Currency Amount], or fungible tokens delivered by this channel after processing this claim. Required to deliver XRP or fungible tokens. Must be more than the total amount delivered by the channel so far, but not greater than the `Amount` of the signed claim. Must be provided except when closing the channel. | | `Channel` | String | Hash256 | Yes | The unique ID of the channel, as a 64-character hexadecimal string. | | `CredentialIDs` | Array of Strings | Vector256 | No | Set of Credentials to authorize a deposit made by this transaction. Each member of the array must be the ledger entry ID of a Credential entry in the ledger. For details, see [Credential IDs](./payment.md#credential-ids). | | `PublicKey` | String | Blob | No | The public key used for the signature, as hexadecimal. This must match the `PublicKey` stored in the ledger for the channel. Required unless the sender of the transaction is the source address of the channel and the `Signature` field is omitted. (The transaction includes the public key so that `rippled` can check the validity of the signature before trying to apply the transaction to the ledger.) | @@ -62,7 +62,7 @@ If the payment channel was created before the [fixPayChanRecipientOwnerDir amend ## PaymentChannelClaim Flags -Transactions of the PaymentChannelClaim type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows: +Transactions of the `PaymentChannelClaim` type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows: | Flag Name | Hex Value | Decimal Value | Description | |:----------|:-------------|:--------------|:----------------------------------| diff --git a/docs/references/protocol/transactions/types/paymentchannelcreate.md b/docs/references/protocol/transactions/types/paymentchannelcreate.md index ef8d63f2d8..d2801c0ddc 100644 --- a/docs/references/protocol/transactions/types/paymentchannelcreate.md +++ b/docs/references/protocol/transactions/types/paymentchannelcreate.md @@ -1,6 +1,4 @@ --- -html: paymentchannelcreate.html -parent: transaction-types.html seo: description: Open a new payment channel. labels: @@ -36,7 +34,7 @@ Create a [payment channel](../../../../concepts/payment-types/payment-channels.m | Field | JSON Type | [Internal Type][] | Description | |:-----------------|:----------|:------------------|:--------------------------| -| `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount], to deduct from the sender's balance and set aside in this channel. While the channel is open, the XRP can only go to the `Destination` address. When the channel closes, any unclaimed XRP is returned to the source address's balance. | +| `Amount` | Object or String | Amount | Amount to deduct from the sender's balance and set aside in this channel. While the channel is open, the amount can only go to the `Destination` address. When the channel closes, any unclaimed amount is returned to the source account's balance.| | `Destination` | String | AccountID | Address to receive XRP claims against this channel. This is also known as the "destination address" for the channel. Cannot be the same as the sender (`Account`). | | `SettleDelay` | Number | UInt32 | Amount of time the source address must wait before closing the channel if it has unclaimed XRP. | | `PublicKey` | String | Blob | The 33-byte public key of the key pair the source will use to sign claims against this channel, in hexadecimal. This can be any secp256k1 or Ed25519 public key. For more information on key pairs, see [Key Derivation](../../../../concepts/accounts/cryptographic-keys.md#key-derivation) | diff --git a/docs/references/protocol/transactions/types/paymentchannelfund.md b/docs/references/protocol/transactions/types/paymentchannelfund.md index 699b8f4469..544a2c5540 100644 --- a/docs/references/protocol/transactions/types/paymentchannelfund.md +++ b/docs/references/protocol/transactions/types/paymentchannelfund.md @@ -11,7 +11,7 @@ labels: _Added by the [PayChan amendment][]._ -Add additional [XRP](../../../../introduction/what-is-xrp.md) to an open [payment channel](../../../../concepts/payment-types/payment-channels.md), and optionally update the expiration time of the channel. Only the source address of the channel can use this transaction. +Add an additional amount to an open [payment channel](../../../../concepts/payment-types/payment-channels.md), and optionally update the expiration time of the channel. Only the source account of the channel can use this transaction. Example PaymentChannelFund: @@ -33,7 +33,7 @@ Example PaymentChannelFund: | Field | JSON Type | [Internal Type][] | Description | |:-------------|:----------|:------------------|:------------------------------| | `Channel` | String | Hash256 | The unique ID of the channel to fund, as a 64-character hexadecimal string. | -| `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount] to add to the channel. Must be a positive amount of XRP. | +| `Amount` | Object or String | Amount | Amount to add to the channel. Must be a positive amount. | | `Expiration` | Number | UInt32 | _(Optional)_ New `Expiration` time to set for the channel, in [seconds since the Ripple Epoch][]. This must be later than either the current time plus the `SettleDelay` of the channel, or the existing `Expiration` of the channel. After the `Expiration` time, any transaction that would access the channel closes the channel without taking its normal action. Any unspent XRP is returned to the source address when the channel closes. (`Expiration` is separate from the channel's immutable `CancelAfter` time.) For more information, see the [PayChannel ledger object type](../../ledger-data/ledger-entry-types/paychannel.md). | ## Error Cases @@ -46,8 +46,8 @@ Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} | `tecNO_DST` | The destination account of the channel has been deleted. This is only possible if the payment channel was created before the [fixPayChanRecipientOwnerDir amendment](/resources/known-amendments.md#fixpaychanrecipientownerdir) became enabled (on 2020-05-01). | | `tecNO_ENTRY` | The Payment Channel identified by the `Channel` field does not exist. | | `tecNO_PERMISSION` | The sender of the transaction is not the source address for the channel. | -| `tecUNFUNDED` | The sending account does not have enough XRP to fund the channel with the requested amount and still meet the [reserve requirement](../../../../concepts/accounts/reserves.md). | -| `temBAD_AMOUNT` | The `Amount` field of the transaction is invalid. The amount must be XRP and it cannot be zero or negative. | +| `tecUNFUNDED` | The sending account does not have enough XRP or fungible tokens to fund the channel with the requested amount and still meet the [reserve requirement](../../../../concepts/accounts/reserves.md). | +| `temBAD_AMOUNT` | The `Amount` field of the transaction is invalid. The amount must either be XRP or fungible tokens and cannot be zero or negative. | | `temBAD_EXPIRATION` | The `Expiration` field is invalid. | {% raw-partial file="/docs/_snippets/common-links.md" /%}