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

Tokens renaming: more find-and-replace

Browse Source
This commit is contained in:
mDuo13
2022-02-15 18:45:03 -08:00
parent a6d9b53b61
commit ca80f66efe
37 changed files with 184 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/references/protocol-reference/data-types/basic-data-types.md
View File

@@ -101,7 +101,7 @@ Reporting Mode does not record ledger data until it has been validated. If you m
## Specifying Currency Amounts
There are two kinds of currencies in the XRP Ledger: XRP, and issued currencies. These two types of currencies are specified in different formats, with different precision and rounding behavior.
There are two kinds of currencies in the XRP Ledger: XRP, and tokens. These two types of currencies are specified in different formats, with different precision and rounding behavior.
Some fields, such as the destination `Amount` of a [Payment transaction][], can be either type. Some fields only accept XRP specifically, such as the `Fee` field ([transaction cost](transaction-cost.html)).

50
content/references/protocol-reference/data-types/currency-formats.md
View File

@@ -8,13 +8,13 @@ label:
---
# Currency Formats
The XRP Ledger has two kinds of money: [XRP](xrp.html), and [issued currencies](issued-currencies.html). Both types have high precision, although their formats are different.
The XRP Ledger has two kinds of digital asset: [XRP](xrp.html), and [tokens](tokens.html). Both types have high precision, although their formats are different.
## Comparison
The following table summarizes some of the differences between XRP and [issued currencies](issued-currencies.html) in the XRP Ledger:
The following table summarizes some of the differences between XRP and tokens in the XRP Ledger:
| XRP | Issued Currencies |
| XRP | Tokens |
|:---------------------------------------------------------|:------------------|
| Has no issuer. | Always issued by an XRP Ledger account. |
| Specified as a string. | Specified as an object. |
@@ -22,19 +22,19 @@ The following table summarizes some of the differences between XRP and [issued c
| Can never be created; can only be destroyed. | Can be issued or redeemed freely. |
| Minimum value: `0`. (Cannot be negative.) | Minimum value: `-9999999999999999e80`. Minimum nonzero absolute value: `1000000000000000e-96`.
| Maximum value `100000000000` (10<sup>11</sup>) XRP. That's `100000000000000000` (10<sup>17</sup>) "drops". | Maximum value `9999999999999999e80`. |
| Precise to the nearest "drop" (0.000001 XRP) | 15 decimal digits of precision. |
| Precise to the nearest "drop" (0.000001 XRP) | 15 decimal digits of precision. |
| Can't be [frozen](freezes.html). | The issuer can [freeze](freezes.html) balances. |
| No transfer fees; XRP-to-XRP payments are always direct. | Can take indirect [paths](paths.html) with each issuer charging a percentage [transfer fee](transfer-fees.html). |
| Can be used in [Payment Channels](payment-channels.html) and [Escrow](escrow.html). | Not compatible with Payment Channels or Escrow. |
For more information, see [XRP](xrp.html) and the [Issued Currencies Overview](issued-currencies-overview.html).
For more information, see [XRP](xrp.html) and [Tokens](tokens.html).
## Specifying Currency Amounts
Use the appropriate format for the type of currency you want to specify:
- [XRP Amounts](#xrp-amounts)
- [Issued Currency Amounts](#issued-currency-amounts)
- [Token Amounts](#token-amounts)
### XRP Amounts
@@ -48,15 +48,15 @@ To specify an amount of XRP, use a [String Number][] indicating _drops_ of XRP,
XRP amounts cannot be negative.
### Issued Currency Amounts
### Token Amounts
To specify an amount of any issued currency (including fiat dollars, precious metals, cryptocurrencies, or other custom currency), use a currency specification object. This is a JSON object with three fields:
To specify an amount of a [(fungible) token](tokens.html), use an Amount object. This is a JSON object with three fields:
| `Field` | Type | Description |
|:-----------|:---------------------------|:-----------------------------------|
| `currency` | String - [Currency Code][] | Arbitrary code for currency to issue. Cannot be `XRP`. |
| `value` | [String Number][] | Quoted decimal representation of the amount of currency. This can include scientific notation, such as `1.23e11` meaning 123,000,000,000. Both `e` and `E` may be used. |
| `issuer` | String | Unique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed. |
| `currency` | String - [Currency Code][] | Arbitrary currency code for the token. Cannot be `XRP`. |
| `value` | [String Number][] | Quoted decimal representation of the amount of the token. This can include scientific notation, such as `1.23e11` meaning 123,000,000,000. Both `e` and `E` may be used. This can be negative when displaying balances, but negative values are disallowed in other contexts such as specifying how much to send. |
| `issuer` | String | Generally, the [account](accounts.html) that issues this token. In special cases, this can refer to the account that holds the token instead. |
[String Number]: #string-numbers
@@ -64,7 +64,7 @@ To specify an amount of any issued currency (including fiat dollars, precious me
For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59`, you would specify:
```
```json
{
"currency": "USD",
"value": "153.75",
@@ -72,31 +72,29 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25
}
```
### String Numbers
### Specifying Without Amounts
{% include '_snippets/string-number-formatting.md' %}
<!--{#_ #}-->
#### Specifying Currencies Without Amounts
If you are specifying a non-XRP currency without an amount (typically for defining an order book of currency exchange offers) you should specify it as above, but omit the `value` field.
If you are specifying a token without an amount (typically for defining an order book in the [decentralized exchange](decentralized-exchange.html)) you should specify it a a currency object, but omit the `value` field.
If you are specifying XRP without an amount (typically for defining an order book) you should specify it as a JSON object with _only_ a `currency` field. Never include an `issuer` field for XRP.
Finally, if the recipient account of the payment trusts multiple issuers for a currency, you can indicate that the payment should be made in any combination of issuers that the recipient accepts. To do this, specify the recipient account's address as the `issuer` value in the JSON object.
## String Numbers
{% include '_snippets/string-number-formatting.md' %}
<!--{#_ #}-->
## XRP Precision
XRP has the same precision as a 64-bit unsigned integer where each unit is equivalent to 0.000001 XRP. It uses integer math, so that any amount less than a full drop is rounded down.
## Issued Currency Precision
## Token Precision
The issued currency format can store a wide variety of assets, including those typically measured in very small or very large denominations. This format uses significant digits and a power-of-ten exponent in a similar way to scientific notation. The format supports positive and negative significant digits and exponents within the specified range. Unlike typical floating-point representations of non-whole numbers, this format uses integer math for all calculations, so it always maintains 15 decimal digits of precision. Multiplication and division have adjustments to compensate for over-rounding in the least significant digits.
Tokens can represent a wide variety of assets, including those typically measured in very small or very large denominations. This format uses significant digits and a power-of-ten exponent in a similar way to scientific notation. The format supports positive and negative significant digits and exponents within the specified range. Unlike typical floating-point representations of non-whole numbers, this format uses integer math for all calculations, so it always maintains 15 decimal digits of precision. Multiplication and division have adjustments to compensate for over-rounding in the least significant digits.
When sending issued currency amounts in the XRP Ledger's peer-to-peer network, servers [serialize](serialization.html) the amount to a 64-bit binary value.
When sending token amounts in the XRP Ledger's peer-to-peer network, servers [serialize](serialization.html) the amount to a 64-bit binary value.
**Note:** The XRP Ledger does not **natively** support issued currencies that are not [fungible](https://en.wikipedia.org/wiki/Fungibility). It also does not support limiting an issued currency to whole number amounts only. All issued currencies in the XRP Ledger are always divisible down to the minimum amount. However non-fungible issued currencies can be implemented in clients following a proposed standard like [XLS-14d](https://github.com/XRPLF/XRPL-Standards/discussions/30). <!-- SPELLING_IGNORE: xls, 14d -->
**Note:** Native support for [Non-Fungible Tokens (NFTs) :not_enabled:](non-fungible-tokens.html) is currently in an experimental state. There are also deprecated, alternative standards for implementing NFTs without changes to the XRP Ledger protocol, including [XLS-14d](https://github.com/XRPLF/XRPL-Standards/discussions/30) and [XLS-19d](https://github.com/XRPLF/XRPL-Standards/discussions/40). <!-- SPELLING_IGNORE: xls, 14d, 19d -->
## Currency Codes
[Currency Code]: #currency-codes
@@ -117,6 +115,6 @@ At the protocol level, this format is [serialized](serialization.html#currency-c
### Nonstandard Currency Codes
You can also issue currency of other types by using a 160-bit (40-character) hexadecimal string such as `015841551A748AD2C1F76FF6ECB0CCCD00000000` as the currency code. To prevent this from being treated as a "standard" currency code, the first 8 bits MUST NOT be `0x00`.
You can also use a 160-bit (40-character) hexadecimal string such as `015841551A748AD2C1F76FF6ECB0CCCD00000000` as the currency code. To prevent this from being treated as a "standard" currency code, the first 8 bits MUST NOT be `0x00`.
**Deprecated:** Some previous versions of [ripple-lib](https://github.com/XRPLF/xrpl.js) supported an "interest-bearing" or "demurraging" currency code type. These currencies have the first 8 bits `0x01`. Demurraging / interest-bearing currencies are no longer supported, but you may encounter them in ledger data. For more information, see [Demurrage](demurrage.html).
**Deprecated:** Some previous versions of [ripple-lib](https://github.com/XRPLF/xrpl.js) supported an "interest-bearing" or "demurraging" currency code type. These codes have the first 8 bits `0x01`. Demurraging / interest-bearing currencies are no longer supported, but you may encounter them in ledger data. For more information, see [Demurrage](demurrage.html).

2
content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md
View File

@@ -72,7 +72,7 @@ AccountRoot objects can have the following flag values:
| `lsfGlobalFreeze` | `0x00400000` | 4194304 | `asfGlobalFreeze` | All assets issued by this address are frozen. |
| `lsfNoFreeze` | `0x00200000` | 2097152 | `asfNoFreeze` | This address cannot freeze trust lines connected to it. Once enabled, cannot be disabled. |
| `lsfPasswordSpent` | `0x00010000` | 65536 | (None) | The account has used its free SetRegularKey transaction. |
| `lsfRequireAuth` | `0x00040000` | 262144 | `asfRequireAuth` | This account must individually approve other users for those users to hold this account's issued currencies. |
| `lsfRequireAuth` | `0x00040000` | 262144 | `asfRequireAuth` | This account must individually approve other users for those users to hold this account's tokens. |
| `lsfRequireDestTag` | `0x00020000` | 131072 | `asfRequireDest` | Requires incoming payments to specify a Destination Tag. |
## AccountRoot ID Format

2
content/references/protocol-reference/ledger-data/ledger-object-types/directorynode.md
View File

@@ -14,7 +14,7 @@ The `DirectoryNode` object type provides a list of links to other objects in the
There are two kinds of Directories:
* **Owner directories** list other objects owned by an account, such as [`RippleState` (trust line)](ripplestate.html) or [`Offer`](offer.html) objects.
* **Offer directories** list the offers available in the [decentralized exchange](decentralized-exchange.html). A single Offer directory contains all the offers that have the same exchange rate for the same issued currency.
* **Offer directories** list the offers available in the [decentralized exchange](decentralized-exchange.html). A single Offer directory contains all the offers that have the same exchange rate for the same token (currency code and issuer).
## Example {{currentpage.name}} JSON

6
content/references/protocol-reference/ledger-data/ledger-object-types/ripplestate.md
View File

@@ -54,7 +54,7 @@ A `RippleState` object has the following fields:
|-----------------|-----------|---------------|-------------|
| `LedgerEntryType` | String | UInt16 | The value `0x0072`, mapped to the string `RippleState`, indicates that this object is a RippleState object. |
| `Flags` | Number | UInt32 | A bit-map of boolean options enabled for this object. |
| `Balance` | Object | Amount | The balance of the trust line, from the perspective of the low account. A negative balance indicates that the low account has issued currency to the high account. The issuer in this is always set to the neutral value [ACCOUNT_ONE](accounts.html#special-addresses). |
| `Balance` | Object | Amount | The balance of the trust line, from the perspective of the low account. A negative balance indicates that the low account has tokens to the high account. The issuer in this is always set to the neutral value [ACCOUNT_ONE](accounts.html#special-addresses). |
| `LowLimit` | Object | Amount | 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. |
| `HighLimit` | Object | Amount | The limit that the high account has set on the trust line. The `issuer` is the address of the high account that set this limit. |
| `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. |
@@ -76,8 +76,8 @@ RippleState objects can have the following flag values:
|-------------------|--------------|---------------|-----------------|---------|
| `lsfLowReserve` | `0x00010000` | 65536 | (None) | This RippleState object [contributes to the low account's owner reserve](#contributing-to-the-owner-reserve). |
| `lsfHighReserve` | `0x00020000` | 131072 | (None) | This RippleState object [contributes to the high account's owner reserve](#contributing-to-the-owner-reserve). |
| `lsfLowAuth` | `0x00040000` | 262144 | `tfSetAuth` | The low account has authorized the high account to hold the low account's issued currency. |
| `lsfHighAuth` | `0x00080000` | 524288 | `tfSetAuth` | The high account has authorized the low account to hold the high account's issued currency. |
| `lsfLowAuth` | `0x00040000` | 262144 | `tfSetAuth` | The low account has authorized the high account to hold tokens issued by the low account. |
| `lsfHighAuth` | `0x00080000` | 524288 | `tfSetAuth` | The high account has authorized the low account to hold tokens issued by the high account. |
| `lsfLowNoRipple` | `0x00100000` | 1048576 | `tfSetNoRipple` | The low account [has disabled rippling](rippling.html) from this trust line. |
| `lsfHighNoRipple` | `0x00200000` | 2097152 | `tfSetNoRipple` | The high account [has disabled rippling](rippling.html) from this trust line. |
| `lsfLowFreeze` | `0x00400000` | 4194304 | `tfSetFreeze` | The low account has frozen the trust line, preventing the high account from transferring the asset. |

28
content/references/protocol-reference/serialization.md
View File

@@ -177,7 +177,7 @@ Transaction instructions may contain fields of any of the following types:
| Type Name | Type Code | Bit Length | [Length-prefixed]? | Description |
|:--------------|:----------|:-----------|:-------------------|----------------|
| [AccountID][] | 8 | 160 | Yes | The unique identifier for an [account](accounts.html). |
| [Amount][] | 6 | 64 or 384 | No | An amount of XRP or issued currency. The length of the field is 64 bits for XRP or 384 bits (64+160+160) for issued currencies. |
| [Amount][] | 6 | 64 or 384 | No | An amount of XRP or tokens. The length of the field is 64 bits for XRP or 384 bits (64+160+160) for tokens. |
| [Blob][] | 7 | Variable | Yes | Arbitrary binary data. One important such field is `TxnSignature`, the signature that authorizes a transaction. |
| [Hash128][] | 4 | 128 | No | A 128-bit arbitrary binary value. The only such field is `EmailHash`, which is intended to store the MD-5 hash of an account owner's email for purposes of fetching a [Gravatar](https://www.gravatar.com/). |
| [Hash160][] | 17 | 160 | No | A 160-bit arbitrary binary value. This may define a currency code or issuer. |
@@ -214,45 +214,45 @@ AccountIDs that appear as stand-alone fields (such as `Account` and `Destination
### Amount Fields
[Amount]: #amount-fields
The "Amount" type is a special field type that represents an amount of currency, either XRP or an issued currency. This type consists of two sub-types:
The "Amount" type is a special field type that represents an amount of currency, either XRP or a token. This type consists of two sub-types:
- **XRP**
XRP is serialized as a 64-bit unsigned integer (big-endian order), except that the most significant bit is always 0 to indicate that it's XRP, and the second-most-significant bit is `1` to indicate that it is positive. Since the maximum amount of XRP (10<sup>17</sup> drops) only requires 57 bits, you can calculate XRP serialized format by taking standard 64-bit unsigned integer and performing a bitwise-OR with `0x4000000000000000`.
- **Issued Currencies**
- **Tokens**
Issued currencies consist of three segments in order:
Tokens consist of three segments in order:
1. 64 bits indicating the amount in the [internal currency amount format](#issued-currency-amount-format). The first bit is `1` to indicate that this is not XRP.
2. 160 bits indicating the [currency code](currency-formats.html#currency-codes). The standard API converts 3-character codes such as "USD" into 160-bit codes using the [standard currency code format](currency-formats.html#standard-currency-codes), but custom 160-bit codes are also possible.
3. 160 bits indicating the issuer's Account ID. (See also: [Account Address Encoding](accounts.html#address-encoding))
You can tell which of the two sub-types it is based on the first bit: `0` for XRP; `1` for issued currency.
You can tell which of the two sub-types it is based on the first bit: `0` for XRP; `1` for tokens.
The following diagram shows the serialization formats for both XRP amounts and issued currency amounts:
The following diagram shows the serialization formats for both XRP amounts and token amounts:
{{ include_svg("img/serialization-amount.svg", 'XRP amounts have a "not XRP" bit, a sign bit, and 62 bits of precision. Issued currency amounts consist of a "not XRP" bit, a sign bit, an exponent (8 bits), mantissa (54 bits), currency code (160 bits), and issuer (160 bits).') }}
{{ include_svg("img/serialization-amount.svg", 'XRP amounts have a "not XRP" bit, a sign bit, and 62 bits of precision. Token amounts consist of a "not XRP" bit, a sign bit, an exponent (8 bits), mantissa (54 bits), currency code (160 bits), and issuer (160 bits).') }}
#### Issued Currency Amount Format
#### Token Amount Format
[[Source]](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/STAmount.cpp "Source")
{{ include_svg("img/currency-number-format.svg", "Issued Currency Amount Format diagram") }}
{{ include_svg("img/currency-number-format.svg", "Token Amount Format diagram") }}
The XRP Ledger uses 64 bits to serialize the numeric amount of an issued currency. (In JSON format, the numeric amount is the `value` field of a currency amount object.) In binary format, the numeric amount consists of a "not XRP" bit, a sign bit, significant digits, and an exponent, in order:
The XRP Ledger uses 64 bits to serialize the numeric amount of a (fungible) token. (In JSON format, the numeric amount is the `value` field of a currency amount object.) In binary format, the numeric amount consists of a "not XRP" bit, a sign bit, significant digits, and an exponent, in order:
1. The first (most significant) bit for an issued currency amount is `1` to indicate that it is not an XRP amount. (XRP amounts always have the most significant bit set to `0` to distinguish them from this format.)
1. The first (most significant) bit for an token amount is `1` to indicate that it is not an XRP amount. (XRP amounts always have the most significant bit set to `0` to distinguish them from this format.)
2. The sign bit indicates whether the amount is positive or negative. Unlike standard [two's complement](https://en.wikipedia.org/wiki/Two%27s_complement) integers, `1` indicates **positive** in the XRP Ledger format, and `0` indicates negative.
3. The next 8 bits represent the exponent as an unsigned integer. The exponent indicates the scale (what power of 10 the significant digits should be multiplied by) in the range -96 to +80 (inclusive). However, when serializing, we add 97 to the exponent to make it possible to serialize as an unsigned integer. Thus, a serialized value of `1` indicates an exponent of `-96`, a serialized value of `177` indicates an exponent of 80, and so on.
4. The remaining 54 bits represent the significant digits as an unsigned integer. When serializing, this value is normalized to the range 10<sup>15</sup> (`1000000000000000`) to 10<sup>16</sup>-1 (`9999999999999999`) inclusive, except for the special case of the value 0. In the special case for 0, the sign bit, exponent, and mantissa are all zeroes, so the 64-bit value is serialized as `0x8000000000000000000000000000000000000000`.
The numeric amount is serialized alongside the [currency code][] and issuer to form a full [issued currency amount](#amount-fields).
The numeric amount is serialized alongside the [currency code][] and issuer to form a full [token amount](#amount-fields).
#### Currency Codes
At a protocol level, currency codes in the XRP Ledger are arbitrary 160-bit values, except the following values have special meaning:
- The currency code `0x0000000000000000000000005852500000000000` is **always disallowed**. (This is the "standard format" for an issued currency with code "XRP".)
- The currency code `0x0000000000000000000000005852500000000000` is **always disallowed**. (This is the code "XRP" in the "standard format".)
- The currency code `0x0000000000000000000000000000000000000000` (all zeroes) is **generally disallowed**. Usually, XRP amounts are not specified with currency codes. However, this code is used to indicate XRP in rare cases where a field must specify a currency code for XRP.
The [`rippled` APIs](rippled-api.html) support a **standard format** for translating three-character ASCII codes to 160-bit hex values as follows:
@@ -262,7 +262,7 @@ The [`rippled` APIs](rippled-api.html) support a **standard format** for transla
1. The first 8 bits must be `0x00`.
2. The next 88 bits are reserved, and should be all `0`'s.
3. The next 24 bits represent 3 characters of ASCII.
Ripple recommends using [ISO 4217](https://www.xe.com/iso4217.php) codes, or popular pseudo-ISO 4217 codes such as "BTC". However, any combination of the following characters is permitted: all uppercase and lowercase letters, digits, as well as the symbols `?`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `<`, `>`, `(`, `)`, `{`, `}`, `[`, `]`, and <code>&#124;</code>. The currency code `XRP` (all-uppercase) is reserved for XRP and cannot be used by issued currencies.
Ripple recommends using [ISO 4217](https://www.xe.com/iso4217.php) codes, or popular pseudo-ISO 4217 codes such as "BTC". However, any combination of the following characters is permitted: all uppercase and lowercase letters, digits, as well as the symbols `?`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `<`, `>`, `(`, `)`, `{`, `}`, `[`, `]`, and <code>&#124;</code>. The currency code `XRP` (all-uppercase) is reserved for XRP and cannot be used by tokens.
4. The next 40 bits are reserved and should be all `0`'s.
The **nonstandard format** is any 160 bits of data as long as the first 8 bits are not `0x00`.

2
content/references/protocol-reference/transactions/transaction-types/accountset.md
View File

@@ -36,7 +36,7 @@ An AccountSet transaction modifies the properties of an [account in the XRP Ledg
| `EmailHash` | String | Hash128 | _(Optional)_ Hash of an email address to be used for generating an avatar image. Conventionally, clients use [Gravatar](http://en.gravatar.com/site/implement/hash/) to display this image. |
| `MessageKey` | String | Blob | _(Optional)_ Public key for sending encrypted messages to this account. To set the key, it must be exactly 33 bytes, with the first byte indicating the key type: `0x02` or `0x03` for secp256k1 keys, `0xED` for Ed25519 keys. To remove the key, use an empty value. |
| [`SetFlag`](#accountset-flags) | Number | UInt32 | _(Optional)_ Integer flag to enable for this account. |
| [`TransferRate`](#transferrate) | Number | UInt32 | _(Optional)_ The fee to charge when users transfer this account's issued currencies, represented as billionths of a unit. Cannot be more than `2000000000` or less than `1000000000`, except for the special case `0` meaning no fee. |
| [`TransferRate`](#transferrate) | Number | UInt32 | _(Optional)_ The fee to charge when users transfer this account's tokens, represented as billionths of a unit. Cannot be more than `2000000000` or less than `1000000000`, except for the special case `0` meaning no fee. |
| [`TickSize`](ticksize.html) | Number | UInt8 | _(Optional)_ Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are `3` to `15` inclusive, or `0` to disable. _(Added by the [TickSize amendment][].)_ |
| `WalletLocator` | String | Hash256 | _(Optional)_ Not used. |
| `WalletSize` | Number | UInt32 | _(Optional)_ Not used. |

2
content/references/protocol-reference/transactions/transaction-types/checkcreate.md
View File

@@ -43,7 +43,7 @@ Create a Check object in the ledger, which is a deferred payment that can be cas
- If the `Destination` is the sender of the transaction, the transaction fails with the result code `temREDUNDANT`.
- If the `Destination` [account](accounts.html) does not exist in the ledger, the transaction fails with the result code `tecNO_DST`.
- If the `Destination` account has the `RequireDest` flag enabled but the transaction does not include a `DestinationTag` field, the transaction fails with the result code `tecDST_TAG_NEEDED`.
- If `SendMax` specifies an issued currency which is [frozen](freezes.html), the transaction fails with the result `tecFROZEN`.
- If `SendMax` specifies a token which is [frozen](freezes.html), the transaction fails with the result `tecFROZEN`.
- If the `Expiration` of the transaction is in the past, the transaction fails with the result `tecEXPIRED`.
- If the sender does not have enough XRP to meet the [owner reserve](reserves.html#owner-reserves) after adding the Check, the transaction fails with the result `tecINSUFFICIENT_RESERVE`.
- If either the sender or the destination of the Check cannot own more objects in the ledger, the transaction fails with the result `tecDIR_FULL`.

14
content/references/protocol-reference/transactions/transaction-types/payment.md
View File

@@ -54,13 +54,13 @@ The Payment transaction type is a general-purpose tool that can represent severa
| Payment type | `Amount` | `SendMax` | `Paths` | `Address` = `Destination`? | Description |
|:-------------|:----------|:-----------|:----------|:---------------------------|:--|
| [Direct XRP-to-XRP Payment][] | String (XRP) | Omitted | Omitted | No | Transfers XRP directly from one account to another. Always delivers the exact amount. No fee applies other than the basic [transaction cost](transaction-cost.html). |
| [Creating or redeeming issued currency][] | Object | Object (optional) | Optional | No | Increases or decreases the amount of a non-XRP currency or asset tracked in the XRP Ledger. [Transfer fees](transfer-fees.html) and [freezes](freezes.html) do not apply when sending and redeeming directly. |
| [Cross-currency Payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send issued currency from one holder to another. The `Amount` and `SendMax` cannot _both_ be XRP. These payments [ripple through](rippling.html) the issuer and can take longer [paths](paths.html) through several intermediaries if the transaction specifies a path set. [Transfer fees](transfer-fees.html) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](decentralized-exchange.html) to connect between different currencies, or possibly even between currencies with the same currency code and different issuers. |
| [Creating or redeeming tokens][] | Object | Object (optional) | Optional | No | Increases or decreases the amount of a non-XRP currency or asset tracked in the XRP Ledger. [Transfer fees](transfer-fees.html) and [freezes](freezes.html) do not apply when sending and redeeming directly. |
| [Cross-currency Payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send tokens from one holder to another. The `Amount` or `SendMax` can be XRP or tokens, but they cannot both be XRP. These payments [ripple through](rippling.html) the issuer and can take longer [paths](paths.html) through several intermediaries if the transaction specifies a path set. [Transfer fees](transfer-fees.html) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](decentralized-exchange.html) to connect between different currencies, or possibly even between currencies with the same currency code and different issuers. |
| [Partial payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Sends _up to_ a specific amount of any currency. Uses the [`tfPartialPayment` flag](#payment-flags). May include a `DeliverMin` amount specifying the minimum that the transaction must deliver to be successful; if the transaction does not specify `DeliverMin`, it can succeed by delivering _any positive amount_. |
| Currency conversion | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Required | Yes | Consumes offers in the [decentralized exchange](decentralized-exchange.html) to convert one currency to another, possibly taking [arbitrage](https://en.wikipedia.org/wiki/Arbitrage) opportunities. The `Amount` and `SendMax` cannot both be XRP. Also called a _circular payment_ because it delivers money to the sender. The [Data API](data-api.html) tracks this type of transaction as an "exchange" and not a "payment". |
[Direct XRP-to-XRP Payment]: direct-xrp-payments.html
[Creating or redeeming issued currency]: issued-currencies-overview.html
[Creating or redeeming tokens]: tokens.html
[Cross-currency Payment]: cross-currency-payments.html
[Partial payment]: partial-payments.html
@@ -69,11 +69,11 @@ The Payment transaction type is a general-purpose tool that can represent severa
<!-- SPELLING_IGNORE: sendmax -->
Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates a financial institution's [issuing address](issuing-and-operational-addresses.html). However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment.
Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates the issuer of a token. However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment.
* There is only ever one balance for the same currency between two addresses. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming the issued currency, instead of the address that issued the currency.
* When the `issuer` field of the destination `Amount` field matches the `Destination` address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has extended trust lines, as well as currencies issued by the destination.
* When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new issued currencies on trust lines that other accounts have extended to the source account, and sending issued currencies the source account holds from other issuers.
* There is only ever one balance between two addresses for the same currency code. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty, instead of the address that issued the token.
* When the `issuer` field of the destination `Amount` field matches the `Destination` address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has trust lines with a positive limit, as well as tokens with the same currency code issued by the destination.
* When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new tokens on trust lines that other accounts have extended to the source account, and sending tokens the source account holds from other issuers.
## Creating Accounts