ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-01 09:05:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Migrate content syntax via script

Browse Source 
The changes in this commit were auto-generated by running

tool/migrate.sh

Following this commit, the Dactyl build no longer works but the Redocly
build (mostly) should.
This commit is contained in:
mDuo13
2024-01-31 16:09:41 -08:00
parent 96121303b2
commit 554a3732d4
898 changed files with 19879 additions and 18631 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
content/references/protocol/binary-format.md
View File

@@ -16,15 +16,15 @@ curated_anchors:
# Binary Format
[[Source]](https://github.com/XRPLF/rippled/blob/develop/src/ripple/protocol/impl/STObject.cpp#L696-L718 "Source")
This page describes the XRP Ledger's canonical binary format for transactions and other data. This binary format is necessary to create and verify digital signatures of those transactions' contents, and is also used in other places including in the [peer-to-peer communications between servers](peer-protocol.html). The [`rippled` APIs](http-websocket-apis.html) typically use JSON to communicate with client applications. However, JSON is unsuitable as a format for serializing transactions for being digitally signed, because JSON can represent the same data in many different but equivalent ways.
This page describes the XRP Ledger's canonical binary format for transactions and other data. This binary format is necessary to create and verify digital signatures of those transactions' contents, and is also used in other places including in the [peer-to-peer communications between servers](../../concepts/networks-and-servers/peer-protocol.md). The [`rippled` APIs](../http-websocket-apis/index.md) typically use JSON to communicate with client applications. However, JSON is unsuitable as a format for serializing transactions for being digitally signed, because JSON can represent the same data in many different but equivalent ways.
The process of serializing a transaction from JSON or any other representation into their canonical binary format can be summarized with these steps:
1. Make sure all required fields are provided, including any required but ["auto-fillable" fields](transaction-common-fields.html#auto-fillable-fields).
1. Make sure all required fields are provided, including any required but ["auto-fillable" fields](transactions/common-fields.md#auto-fillable-fields).
The [Transaction Formats Reference](transaction-formats.html) defines the required and optional fields for XRP Ledger transactions.
The [Transaction Formats Reference](transactions/index.md) defines the required and optional fields for XRP Ledger transactions.
**Note:** The `SigningPubKey` must also be provided at this step. When signing, you can [derive this key](cryptographic-keys.html#key-derivation) from the secret key that is provided for signing.
**Note:** The `SigningPubKey` must also be provided at this step. When signing, you can [derive this key](../../concepts/accounts/cryptographic-keys.md#key-derivation) from the secret key that is provided for signing.
2. Convert each field's data into its ["internal" binary format](#internal-format).
@@ -36,7 +36,7 @@ The process of serializing a transaction from JSON or any other representation i
The result is a single binary blob that can be signed using well-known signature algorithms such as ECDSA (with the secp256k1 elliptic curve) and Ed25519. For purposes of the XRP Ledger, you must also [hash][Hash] the data with the appropriate prefix (`0x53545800` if single-signing, or `0x534D5400` if multi-signing). After signing, you must re-serialize the transaction with the `TxnSignature` field included. <!--{# TODO: link docs on how to compute a transaction signature. #}-->
**Note:** The XRP Ledger uses the same serialization format to represent other types of data, such as [ledger objects](ledger-object-types.html) and processed transactions. However, only certain fields are appropriate for including in a transaction that gets signed. (For example, the `TxnSignature` field, containing the signature itself, should not be present in the binary blob that you sign.) Thus, some fields are designated as "Signing" fields, which are included in objects when those objects are signed, and "non-signing" fields, which are not.
**Note:** The XRP Ledger uses the same serialization format to represent other types of data, such as [ledger objects](ledger-data/ledger-entry-types/index.md) and processed transactions. However, only certain fields are appropriate for including in a transaction that gets signed. (For example, the `TxnSignature` field, containing the signature itself, should not be present in the binary blob that you sign.) Thus, some fields are designated as "Signing" fields, which are included in objects when those objects are signed, and "non-signing" fields, which are not.
### Examples
@@ -44,33 +44,29 @@ Both signed and unsigned transactions can be represented in both JSON and binary
**JSON:**
```json
{% include '_code-samples/tx-serialization/py/test-cases/tx1.json' %}
```
{% code-snippet file="/_code-samples/tx-serialization/py/test-cases/tx1.json" language="json" /%}
**Binary (represented as hexadecimal):**
```text
{% include '_code-samples/tx-serialization/py/test-cases/tx1-binary.txt' %}
```
{% code-snippet file="/_code-samples/tx-serialization/py/test-cases/tx1-binary.txt" language="text" /%}
## Sample Code
The serialization processes described here are implemented in multiple places and programming languages:
- In C++ [in the `rippled` code base](https://github.com/XRPLF/rippled/blob/develop/src/ripple/protocol/impl/STObject.cpp).
- In JavaScript in [this repository's code samples section]({{target.github_forkurl}}/blob/{{target.github_branch}}/content/_code-samples/tx-serialization/).
- In Python 3 in [this repository's code samples section]({{target.github_forkurl}}/blob/{{target.github_branch}}/content/_code-samples/tx-serialization/).
- In JavaScript in {% repo-link path="content/_code-samples/tx-serialization/" %}this repository's code samples section{% /repo-link %}.
- In Python 3 in {% repo-link path="content/_code-samples/tx-serialization/" %}this repository's code samples section{% /repo-link %}.
Additionally, many [client libraries](client-libraries.html) provide serialization support under permissive open-source licenses, so you can import, use, or adapt the code for your needs.
Additionally, many [client libraries](../client-libraries.md) provide serialization support under permissive open-source licenses, so you can import, use, or adapt the code for your needs.
## Internal Format
Each field has an "internal" binary format used in the `rippled` source code to represent that field when signing (and in most other cases). The internal formats for all fields are defined in the source code of [`SField.cpp`](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/SField.cpp). (This file also includes fields other than transaction fields.) The [Transaction Format Reference](transaction-formats.html) also lists the internal formats for all transaction fields.
Each field has an "internal" binary format used in the `rippled` source code to represent that field when signing (and in most other cases). The internal formats for all fields are defined in the source code of [`SField.cpp`](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/SField.cpp). (This file also includes fields other than transaction fields.) The [Transaction Format Reference](transactions/index.md) also lists the internal formats for all transaction fields.
For example, the `Flags` [common transaction field](transaction-common-fields.html) becomes a UInt32 (32-bit unsigned integer).
For example, the `Flags` [common transaction field](transactions/common-fields.md) becomes a UInt32 (32-bit unsigned integer).
### Definitions File
@@ -83,10 +79,10 @@ The following table defines the top-level fields from the definitions file:
| Field | Contents |
|:----------------------|:-----------------------------------------------------|
| `TYPES` | Map of data types to their ["type code"](#type-codes) for constructing field IDs and sorting fields in canonical order. Codes below 1 should not appear in actual data; codes above 10000 represent special "high-level" object types such as "Transaction" that cannot be serialized inside other objects. See the [Type List](#type-list) for details of how to serialize each type. |
| `LEDGER_ENTRY_TYPES` | Map of [ledger objects](ledger-object-types.html) to their data type. These appear in ledger state data, and in the "affected nodes" section of processed transactions' [metadata](transaction-metadata.html). |
| `LEDGER_ENTRY_TYPES` | Map of [ledger objects](ledger-data/ledger-entry-types/index.md) to their data type. These appear in ledger state data, and in the "affected nodes" section of processed transactions' [metadata](transactions/metadata.md). |
| `FIELDS` | A sorted array of tuples representing all fields that may appear in transactions, ledger objects, or other data. The first member of each tuple is the string name of the field and the second member is an object with that field's properties. (See the "Field properties" table below for definitions of those fields.) |
| `TRANSACTION_RESULTS` | Map of [transaction result codes](transaction-results.html) to their numeric values. Result types not included in ledgers have negative values; `tesSUCCESS` has numeric value 0; [`tec`-class codes](tec-codes.html) represent failures that are included in ledgers. |
| `TRANSACTION_TYPES` | Map of all [transaction types](transaction-types.html) to their numeric values. |
| `TRANSACTION_RESULTS` | Map of [transaction result codes](transactions/transaction-results/transaction-results.md) to their numeric values. Result types not included in ledgers have negative values; `tesSUCCESS` has numeric value 0; [`tec`-class codes](transactions/transaction-results/tec-codes.md) represent failures that are included in ledgers. |
| `TRANSACTION_TYPES` | Map of all [transaction types](transactions/types/index.md) to their numeric values. |
For purposes of serializing transactions for signing and submitting, the `FIELDS`, `TYPES`, and `TRANSACTION_TYPES` fields are necessary.
@@ -109,8 +105,8 @@ When you combine a field's type code and field code, you get the field's unique
| | Type Code < 16 | Type Code >= 16 |
|:-----------------|:------------------------------------------------------------------------------|:--|
| **Field Code < 16** | ![1 byte: high 4 bits define type; low 4 bits define field.](img/field-id-common-type-common-field.png) | ![2 bytes: low 4 bits of the first byte define field; next byte defines type.](img/field-id-uncommon-type-common-field.png) |
| **Field Code >= 16** | ![2 bytes: high 4 bits of the first byte define type; low 4 bits of first byte are 0; next byte defines field](img/field-id-common-type-uncommon-field.png) | ![3 bytes: first byte is `0x00`, second byte defines type; third byte defines field](img/field-id-uncommon-type-uncommon-field.png) |
| **Field Code < 16** | ![1 byte: high 4 bits define type; low 4 bits define field.](/img/field-id-common-type-common-field.png) | ![2 bytes: low 4 bits of the first byte define field; next byte defines type.](/img/field-id-uncommon-type-common-field.png) |
| **Field Code >= 16** | ![2 bytes: high 4 bits of the first byte define type; low 4 bits of first byte are 0; next byte defines field](/img/field-id-common-type-uncommon-field.png) | ![3 bytes: first byte is `0x00`, second byte defines type; third byte defines field](/img/field-id-uncommon-type-uncommon-field.png) |
When decoding, you can tell how many bytes the field ID is by which bits **of the first byte** are zeroes. This corresponds to the cases in the above table:
@@ -133,11 +129,15 @@ The length prefix consists of one to three bytes indicating the length of the fi
- If the field contains 193 to 12480 bytes of data, the first two bytes indicate the length of the field with the following formula:
193 + ((byte1 - 193) * 256) + byte2
```
193 + ((byte1 - 193) * 256) + byte2
```
- If the field contains 12481 to 918744 bytes of data, the first three bytes indicate the length of the field with the following formula:
12481 + ((byte1 - 241) * 65536) + (byte2 * 256) + byte3
```
12481 + ((byte1 - 241) * 65536) + (byte2 * 256) + byte3
```
- A length-prefixed field cannot contain more than 918744 bytes of data.
@@ -176,14 +176,14 @@ 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). |
| [AccountID][] | 8 | 160 | Yes | The unique identifier for an [account](../../concepts/accounts/accounts.md). |
| [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. |
| [Hash256][] | 5 | 256 | No | A 256-bit arbitrary binary value. This usually represents the "SHA-512Half" hash of a transaction, ledger version, or ledger data object. |
| [PathSet][] | 18 | Variable | No | A set of possible [payment paths](paths.html) for a [cross-currency payment](cross-currency-payments.html). |
| [STArray][] | 15 | Variable | No | An array containing a variable number of members, which can be different types depending on the field. Two cases of this include [memos](transaction-common-fields.html#memos-field) and lists of signers used in [multi-signing](multi-signing.html). |
| [PathSet][] | 18 | Variable | No | A set of possible [payment paths](../../concepts/tokens/fungible-tokens/paths.md) for a [cross-currency payment](../../concepts/payment-types/cross-currency-payments.md). |
| [STArray][] | 15 | Variable | No | An array containing a variable number of members, which can be different types depending on the field. Two cases of this include [memos](transactions/common-fields.md#memos-field) and lists of signers used in [multi-signing](../../concepts/accounts/multi-signing.md). |
| [STIssue][] | 24 | 160 or 320 | No | An asset definition, XRP or a token, with no quantity. |
| [STObject][] | 14 | Variable | No | An object containing one or more nested fields. |
| [UInt8][] | 16 | 8 | No | An 8-bit unsigned integer. |
@@ -194,22 +194,22 @@ Transaction instructions may contain fields of any of the following types:
[Length-prefixed]: #length-prefixing
In addition to all of the above field types, the following types may appear in other contexts, such as [ledger objects](ledger-object-types.html) and [transaction metadata](transaction-metadata.html):
In addition to all of the above field types, the following types may appear in other contexts, such as [ledger objects](ledger-data/ledger-entry-types/index.md) and [transaction metadata](transactions/metadata.md):
| Type Name | Type Code | [Length-prefixed]? | Description |
|:------------|:----------|:-------------------|:------------------------------|
| Transaction | 10001 | No | A "high-level" type containing an entire [transaction](transaction-formats.html). |
| LedgerEntry | 10002 | No | A "high-level" type containing an entire [ledger object](ledger-object-types.html). |
| Validation | 10003 | No | A "high-level" type used in peer-to-peer communications to represent a validation vote in the [consensus process](consensus.html). |
| Metadata | 10004 | No | A "high-level" type containing [metadata for one transaction](transaction-metadata.html). |
| Transaction | 10001 | No | A "high-level" type containing an entire [transaction](transactions/index.md). |
| LedgerEntry | 10002 | No | A "high-level" type containing an entire [ledger object](ledger-data/ledger-entry-types/index.md). |
| Validation | 10003 | No | A "high-level" type used in peer-to-peer communications to represent a validation vote in the [consensus process](../../concepts/consensus-protocol/index.md). |
| Metadata | 10004 | No | A "high-level" type containing [metadata for one transaction](transactions/metadata.md). |
| [UInt64][] | 3 | No | A 64-bit unsigned integer. This type does not appear in transaction instructions, but several ledger objects use fields of this type. |
| Vector256 | 19 | Yes | This type does not appear in transaction instructions, but the [Amendments ledger object](amendments-object.html)'s `Amendments` field uses this to represent which [amendments](amendments.html) are currently enabled. |
| Vector256 | 19 | Yes | This type does not appear in transaction instructions, but the [Amendments ledger object](ledger-data/ledger-entry-types/amendments.md)'s `Amendments` field uses this to represent which [amendments](../../concepts/networks-and-servers/amendments.md) are currently enabled. |
### AccountID Fields
[AccountID]: #accountid-fields
Fields of this type contain the 160-bit identifier for an XRP Ledger [account](accounts.html). In JSON, these fields are represented as [base58][] XRP Ledger "addresses", with additional checksum data so that typos are unlikely to result in valid addresses. (This encoding, sometimes called "Base58Check", prevents accidentally sending money to the wrong address.) The binary format for these fields does not contain any checksum data nor does it include the `0x00` "type prefix" used in [address base58 encoding](addresses.html#address-encoding). (However, since the binary format is used mostly for signed transactions, a typo or other error in transcribing a signed transaction would invalidate the signature, preventing it from sending money.)
Fields of this type contain the 160-bit identifier for an XRP Ledger [account](../../concepts/accounts/accounts.md). In JSON, these fields are represented as [base58][] XRP Ledger "addresses", with additional checksum data so that typos are unlikely to result in valid addresses. (This encoding, sometimes called "Base58Check", prevents accidentally sending money to the wrong address.) The binary format for these fields does not contain any checksum data nor does it include the `0x00` "type prefix" used in [address base58 encoding](../../concepts/accounts/addresses.md#address-encoding). (However, since the binary format is used mostly for signed transactions, a typo or other error in transcribing a signed transaction would invalidate the signature, preventing it from sending money.)
AccountIDs that appear as stand-alone fields (such as `Account` and `Destination`) are [length-prefixed](#length-prefixing) despite being a fixed 160 bits in length. As a result, the length indicator for these fields is always the byte `0x14`. AccountIDs that appear as children of special fields ([Amount `issuer`][Amount] and [PathSet `account`][PathSet]) are _not_ length-prefixed.
@@ -228,8 +228,8 @@ The "Amount" type is a special field type that represents an amount of currency,
Tokens consist of three segments in order:
1. 64 bits indicating the amount in the [token amount format](#token-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](addresses.html#address-encoding))
2. 160 bits indicating the [currency code](data-types/currency-formats.md#currency-codes). The standard API converts 3-character codes such as "USD" into 160-bit codes using the [standard currency code format](data-types/currency-formats.md#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](../../concepts/accounts/addresses.md#address-encoding))
You can tell which of the two sub-types it is based on the first bit: `0` for XRP; `1` for tokens.
@@ -240,7 +240,7 @@ The following diagram shows the serialization formats for both XRP amounts and t
#### Token Amount Format
[[Source]](https://github.com/XRPLF/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/STAmount.cpp "Source")
{{ include_svg("img/currency-number-format.svg", "Token Amount Format diagram") }}
[{% inline-svg file="/img/currency-number-format.svg" /%}](/img/currency-number-format.svg "Token Amount Format diagram")
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:
@@ -258,9 +258,9 @@ At a protocol level, currency codes in the XRP Ledger are arbitrary 160-bit valu
- 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](http-websocket-apis.html) support a **standard format** for translating three-character ASCII codes to 160-bit hex values as follows:
The [`rippled` APIs](../http-websocket-apis/index.md) support a **standard format** for translating three-character ASCII codes to 160-bit hex values as follows:
{{ include_svg("img/currency-code-format.svg", "Standard Currency Code Format") }}
[{% inline-svg file="/img/currency-code-format.svg" /%}](/img/currency-code-format.svg "Standard Currency Code Format")
1. The first 8 bits must be `0x00`.
2. The next 88 bits are reserved, and should be all `0`'s.
@@ -274,7 +274,7 @@ The **nonstandard format** is any 160 bits of data as long as the first 8 bits a
### Array Fields
[STArray]: #array-fields
Some transaction fields, such as `SignerEntries` (in [SignerListSet transactions][]) and [`Memos`](transaction-common-fields.html#memos-field), are arrays of objects (called the "STArray" type).
Some transaction fields, such as `SignerEntries` (in [SignerListSet transactions][]) and [`Memos`](transactions/common-fields.md#memos-field), are arrays of objects (called the "STArray" type).
Arrays contain several [object fields](#object-fields) in their native binary format in a specific order. In JSON, each array member is a JSON "wrapper" object with a single field, which is the name of the member object field. The value of that field is the ("inner") object itself.
@@ -306,7 +306,7 @@ All such fields are serialized as the specific number of bits, with no length in
### Issue Fields
[STIssue]: #issue-fields
Some fields specify a _type_ of asset, which could be XRP or a fungible [token](tokens.html), without an amount. These fields have consist of one or two 160-bit segments in order:
Some fields specify a _type_ of asset, which could be XRP or a fungible [token](../../concepts/tokens/index.md), without an amount. These fields have consist of one or two 160-bit segments in order:
1. The first 160 bits are the [currency code](#currency-codes) of the asset. For XRP, this is all 0's.
2. If the first 160 bits are all 0's (the asset is XRP), the field ends there. Otherwise, the asset is a token and the next 160 bits are the [AccountID of the token issuer](#accountid-fields).
@@ -327,7 +327,7 @@ The following example shows the serialization format for an object (a single `Me
### PathSet Fields
[PathSet]: #pathset-fields
The `Paths` field of a cross-currency [Payment transaction][] is a "PathSet", represented in JSON as an array of arrays. For more information on what paths are used for, see [Paths](paths.html).
The `Paths` field of a cross-currency [Payment transaction][] is a "PathSet", represented in JSON as an array of arrays. For more information on what paths are used for, see [Paths](../../concepts/tokens/fungible-tokens/paths.md).
A PathSet is serialized as **1 to 6** individual paths in sequence[[Source]](https://github.com/XRPLF/rippled/blob/4cff94f7a4a05302bdf1a248515379da99c5bcd4/src/ripple/app/tx/impl/Payment.h#L35-L36 "Source"). Each complete path is followed by a byte that indicates what comes next:
@@ -344,9 +344,9 @@ The following table describes the possible fields and the bitwise flags to set i
| `0x10` | `currency` | [Currency Code][] | 160 bits | 2nd |
| `0x20` | `issuer` | [AccountID][] | 160 bits | 3rd |
[Currency Code]: currency-formats.html#standard-currency-codes
[Currency Code]: data-types/currency-formats.md#standard-currency-codes
Some combinations are invalid; see [Path Specifications](paths.html#path-specifications) for details.
Some combinations are invalid; see [Path Specifications](../../concepts/tokens/fungible-tokens/paths.md#path-specifications) for details.
The AccountIDs in the `account` and `issuer` fields are presented _without_ a length prefix. When the `currency` is XRP, the currency code is represented as 160 bits of zeroes.
@@ -354,7 +354,7 @@ Each step is followed directly by the next step of the path. As described above,
The following example shows the serialization format for a PathSet:
{{ include_svg("img/serialization-pathset.svg", "PathSet is several paths each followed by a continue or end byte; each path is several path steps consisting of a type byte and one or more 160-bit fields based on the type byte") }}
[{% inline-svg file="/img/serialization-pathset.svg" /%}](/img/serialization-pathset.svg "PathSet is several paths each followed by a continue or end byte; each path is several path steps consisting of a type byte and one or more 160-bit fields based on the type byte")
### UInt Fields
@@ -373,9 +373,9 @@ Another special case is the `TransactionType` field. In JSON, this field is conv
### XChainBridge Fields
[XChainBridge]: #xchainbridge-fields
{{ include_svg("img/serialization-xchainbridge.svg", "XChainBridge format diagram") }}
[{% inline-svg file="/img/serialization-xchainbridge.svg" /%}](/img/serialization-xchainbridge.svg "XChainBridge format diagram")
The `XChainBridge` field, used in transactions and ledger entries related to [cross-chain bridges](cross-chain-bridges.html), is the only field of the XChainBridge type. It consists of 4 parts which together define a bridge between blockchains:
The `XChainBridge` field, used in transactions and ledger entries related to [cross-chain bridges](../../concepts/xrpl-sidechains/cross-chain-bridges.md), is the only field of the XChainBridge type. It consists of 4 parts which together define a bridge between blockchains:
- The locking chain door account, a length-prefixed [AccountID][].
- The locking chain asset type, an [STIssue][].
@@ -389,7 +389,5 @@ The two nested [STIssue][] types are each either 160 or 320 bits. The STIssue fi
In total, an XChainBridge field is always either 656, 816, or 976 bits (82, 102, or 122 bytes) depending on whether zero, one, or both of the assets are the native asset on their respective chain.
<!-- SPELLING_IGNORE: pathset, stobject, starray, ledgerentry, vector256, accountids, uint -->
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

14
content/references/protocol/data-types/base58-encodings.md
View File

@@ -5,7 +5,7 @@ blurb: Formats for representing cryptographic keys and related data in base58 fo
---
# base58 Encodings
XRP Ledger APIs often use a "base58" encoding with a checksum (sometimes called "Base58Check") to represent [account addresses](addresses.html) and other types of values related to cryptographic keys. This encoding is the same as [the one used for Bitcoin addresses](https://en.bitcoin.it/wiki/Base58Check_encoding), except that the XRP Ledger uses the following dictionary: `rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz`.
XRP Ledger APIs often use a "base58" encoding with a checksum (sometimes called "Base58Check") to represent [account addresses](../../../concepts/accounts/addresses.md) and other types of values related to cryptographic keys. This encoding is the same as [the one used for Bitcoin addresses](https://en.bitcoin.it/wiki/Base58Check_encoding), except that the XRP Ledger uses the following dictionary: `rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz`.
The XRP Ledger prefixes different types of values with a specific 8-bit number before encoding them to distinguish between different data types. With the arrangement of characters in the XRP Ledger's base58 dictionary, the result is that the base58 representations for different types of encoded values start with specific letters by type.
@@ -20,17 +20,13 @@ The following table lists all the encodings the XRP Ledger uses:
¹ Content size excludes the 1-byte type prefix.
[Account]: accounts.html
[Account]: ../../../concepts/accounts/accounts.md
## See Also
- [Address Encoding](addresses.html#address-encoding) - detailed information on address encoding
- [Cryptographic Keys](cryptographic-keys.html) - types of cryptographic keys in the XRP Ledger and how they're used
- [Address Encoding](../../../concepts/accounts/addresses.md#address-encoding) - detailed information on address encoding
- [Cryptographic Keys](../../../concepts/accounts/cryptographic-keys.md) - types of cryptographic keys in the XRP Ledger and how they're used
- [wallet_propose Reference][wallet_propose method] - API method for generating account keys
- [validation_create Reference][validation_create method] - API method for generating validator keys
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

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

@@ -7,24 +7,24 @@ blurb: Format and meaning of fundamental data types like addresses, ledger index
Different types of objects are uniquely identified in different ways:
[Accounts](accounts.html) are identified by their [Address][], for example `"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"`. Addresses always start with "r". Many `rippled` methods also accept a hexadecimal representation.
[Accounts](../../../concepts/accounts/accounts.md) are identified by their [Address][], for example `"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"`. Addresses always start with "r". Many `rippled` methods also accept a hexadecimal representation.
[Transactions](transaction-formats.html) are identified by a [Hash][] of the transaction's binary format. You can also identify a transaction by its sending account and [Sequence Number][].
[Transactions](../transactions/index.md) are identified by a [Hash][] of the transaction's binary format. You can also identify a transaction by its sending account and [Sequence Number][].
Each closed [Ledger](ledger-data-formats.html) has a [Ledger Index][] and a [Hash][] value. When [Specifying Ledgers][] you can use either one.
Each closed [Ledger](../ledger-data/index.md) has a [Ledger Index][] and a [Hash][] value. When [Specifying Ledgers][] you can use either one.
## Addresses
[Address]: #addresses
{% include '_snippets/data_types/address.md' %}
<!--{#_ #}-->
{% partial file="/_snippets/data_types/address.md" /%}
## Hashes
[Hash]: #hashes
{% include '_snippets/data_types/hash.md' %}
<!--{#_ #}-->
{% partial file="/_snippets/data_types/hash.md" /%}
### Hash Prefixes
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/HashPrefix.h "Source")
@@ -48,24 +48,24 @@ Some types of hash appear in API requests and responses. Others are only calcula
| Validation vote | N/A | `0x56414C00` | `VAL\0` |
| Validator manifest | N/A | `0x4D414E00` | `MAN\0` |
[ledger header]: ledger-header.html
[SHAMapv2]: known-amendments.html#shamapv2
[ledger header]: ../ledger-data/ledger-header.md
[SHAMapv2]: ../../../resources/known-amendments.md#shamapv2
[Ledger objects IDs](ledger-object-ids.html) are calculated in a similar way, but they use a 2-byte prefix called a "space key" instead of a prefix in the form described here.
[Ledger objects IDs](../ledger-data/common-fields.md) are calculated in a similar way, but they use a 2-byte prefix called a "space key" instead of a prefix in the form described here.
## Account Sequence
[Sequence Number]: #account-sequence
{% include '_snippets/data_types/account_sequence.md' %}
<!--{#_ #}-->
{% partial file="/_snippets/data_types/account_sequence.md" /%}
## Ledger Index
[Ledger Index]: #ledger-index
{% include '_snippets/data_types/ledger_index.md' %}
<!--{#_ #}-->
{% partial file="/_snippets/data_types/ledger_index.md" /%}
### Specifying Ledgers
@@ -74,17 +74,23 @@ Many API methods require you to specify an instance of the ledger, with the data
1. Specify a ledger by its [Ledger Index][] in the `ledger_index` parameter. Each closed ledger has a ledger index that is 1 higher than the previous ledger. (The very first ledger had ledger index 1.)
"ledger_index": 61546724
```
"ledger_index": 61546724
```
2. Specify a ledger by its [Hash][] value in the `ledger_hash` parameter.
"ledger_hash": "8BB204CE37CFA7A021A16B5F6143400831C4D1779E6FE538D9AC561ABBF4A929"
```
"ledger_hash": "8BB204CE37CFA7A021A16B5F6143400831C4D1779E6FE538D9AC561ABBF4A929"
```
3. Specify a ledger by one of the following shortcuts, in the `ledger_index` parameter:
* `validated` for the most recent ledger that has been [validated by consensus](consensus-structure.html#validation)
* `validated` for the most recent ledger that has been [validated by consensus](../../../concepts/consensus-protocol/consensus-structure.md#validation)
"ledger_index": "validated"
```
"ledger_index": "validated"
```
* `closed` for the most recent ledger that has been closed for modifications and proposed for validation
@@ -92,7 +98,7 @@ Many API methods require you to specify an instance of the ledger, with the data
There is also a deprecated `ledger` parameter which accepts any of the above three formats. *Do not* use this parameter; it may be removed without further notice.
If you do not specify a ledger, the server decides which ledger to use to serve the request. By default, the server chooses the `current` (in-progress) ledger. In [Reporting Mode](rippled-server-modes.html#reporting-mode), the server uses the most recent validated ledger instead. Do not provide more than one field specifying ledgers.
If you do not specify a ledger, the server decides which ledger to use to serve the request. By default, the server chooses the `current` (in-progress) ledger. In [Reporting Mode](../../../concepts/networks-and-servers/rippled-server-modes.md#reporting-mode), the server uses the most recent validated ledger instead. Do not provide more than one field specifying ledgers.
**Note:** Do not rely on the default behavior for specifying a ledger; it is subject to change. Always specify a ledger version in the request if you can.
@@ -103,23 +109,27 @@ Reporting Mode does not record ledger data until it has been validated. If you m
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)).
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](../../../concepts/transactions/transaction-cost.md)).
XRP is specified as a string containing an integer number of "drops" of XRP, where 1 million drops equals 1 XRP. Tokens are instead specified as an object with fields for the decimal amount, currency code, and issuer. For example:
- **XRP** - To specify an `Amount` field with a value of 13.1 XRP:
"Amount": "13100000"
```
"Amount": "13100000"
```
- **Token** - To specify an `Amount` field with a value of 13.1 FOO issued by or to `rf1B...`:
"Amount": {
"value": "13.1",
"currency": "FOO",
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
}
```
"Amount": {
"value": "13.1",
"currency": "FOO",
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
}
```
For more information, see [Currency Formats](currency-formats.html).
For more information, see [Currency Formats](currency-formats.md).
## Specifying Time
@@ -128,7 +138,4 @@ The `rippled` server and its APIs represent time as an unsigned integer. This nu
Don't convert Ripple Epoch times to UNIX Epoch times in 32-bit variables: this could lead to integer overflows.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

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

@@ -8,7 +8,7 @@ label:
---
# Currency Formats
The XRP Ledger has two kinds of digital asset: XRP and [tokens](tokens.html). Both types have high precision, although their formats are different.
The XRP Ledger has two kinds of digital asset: XRP and [tokens](../../../concepts/tokens/index.md). Both types have high precision, although their formats are different.
## Comparison
@@ -18,16 +18,16 @@ The following table summarizes some of the differences between XRP and tokens in
|:---------------------------------------------------------|:------------------|
| Has no issuer. | Always issued by an XRP Ledger account. |
| Specified as a string. | Specified as an object. |
| Tracked in [accounts](accountroot.html). | Tracked in [trust lines](ripplestate.html). |
| Tracked in [accounts](../ledger-data/ledger-entry-types/accountroot.md). | Tracked in [trust lines](../ledger-data/ledger-entry-types/ripplestate.md). |
| 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. |
| 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. |
| Can't be [frozen](../../../concepts/tokens/fungible-tokens/freezes.md). | The issuer can [freeze](../../../concepts/tokens/fungible-tokens/freezes.md) balances. |
| No transfer fees; XRP-to-XRP payments are always direct. | Can take indirect [paths](../../../concepts/tokens/fungible-tokens/paths.md) with each issuer charging a percentage [transfer fee](../../../concepts/tokens/transfer-fees.md). |
| Can be used in [Payment Channels](../../../concepts/payment-types/payment-channels.md) and [Escrow](../../../concepts/payment-types/escrow.md). | Not compatible with Payment Channels or Escrow. |
For more information, see [What is XRP?](what-is-xrp.html) and [Tokens](tokens.html).
For more information, see [What is XRP?](../../../introduction/what-is-xrp.md) and [Tokens](../../../concepts/tokens/index.md).
## Specifying Currency Amounts
@@ -50,13 +50,13 @@ XRP amounts cannot be negative.
### Token Amounts
To specify an amount of a [(fungible) token](tokens.html), use an Amount object. This is a JSON object with three fields:
To specify an amount of a [(fungible) token](../../../concepts/tokens/index.md), use an Amount object. This is a JSON object with three fields:
| `Field` | Type | Description |
|:-----------|:---------------------------|:-----------------------------------|
| `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 (for example, in a [Clawback](clawback.html) transaction). |
| `issuer` | String | Generally, the [account](../../../concepts/accounts/accounts.md) that issues this token. In special cases, this can refer to the account that holds the token instead (for example, in a [Clawback](../transactions/types/clawback.md) transaction). |
[String Number]: #string-numbers
@@ -74,7 +74,7 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25
### Specifying Without Amounts
In some cases, you need to define an asset (which could be XRP or a token) without a specific amount, such as when defining an order book in the [decentralized exchange](decentralized-exchange.html).
In some cases, you need to define an asset (which could be XRP or a token) without a specific amount, such as when defining an order book in the [decentralized exchange](../../../concepts/tokens/decentralized-exchange/index.md).
To describe a token without an amount, specify it as a currency object, but omit the `value` field. For example:
@@ -96,7 +96,7 @@ To describe XRP without an amount, specify it as a JSON object with _only_ a `cu
## String Numbers
{% include '_snippets/string-number-formatting.md' %}
{% partial file="/_snippets/string-number-formatting.md" /%}
## XRP Precision
@@ -106,15 +106,15 @@ XRP has the same precision as a 64-bit unsigned integer where each unit is equiv
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 token 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](../binary-format.md) the amount to a 64-bit binary value.
**Tip:** For tokens that should not be divisible at all, see [Non-Fungible Tokens (NFTs)](non-fungible-tokens.html).
**Tip:** For tokens that should not be divisible at all, see [Non-Fungible Tokens (NFTs)](../../../concepts/tokens/nfts/index.md).
## Currency Codes
[Currency Code]: #currency-codes
{% include '_snippets/data_types/currency_code.md' %}
<!--{#_ #}-->
{% partial file="/_snippets/data_types/currency_code.md" /%}
### Standard Currency Codes
@@ -125,10 +125,10 @@ The standard format for currency codes is a three-character string such as `USD`
- Currency codes are case-sensitive.
- The currency code `XRP` (all-uppercase) is disallowed. Real XRP typically does not use a currency code in the XRP Ledger protocol.
At the protocol level, this format is [serialized](serialization.html#currency-codes) into a 160-bit binary value starting with `0x00`.
At the protocol level, this format is [serialized](../binary-format.md#currency-codes) into a 160-bit binary value starting with `0x00`.
### Nonstandard Currency Codes
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 codes have the first 8 bits `0x01`. Demurraging / interest-bearing currencies are no longer supported, but you may find 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 find them in ledger data. For more information, see [Demurrage](../../../concepts/tokens/fungible-tokens/demurrage.md).

23
content/references/protocol/data-types/nftoken.md
View File

@@ -11,7 +11,7 @@ The `NFToken` object represents a single non-fungible token (NFT). It is not sto
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -20,7 +20,7 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
}
```
Unlike full-fledged [ledger entries](ledger-object-types.html), `NFToken` has no field to identify the object type or current owner of the object. `NFToken` objects are grouped into pages that implicitly define the object type and identify the owner.
Unlike full-fledged [ledger entries](../ledger-data/ledger-entry-types/index.md), `NFToken` has no field to identify the object type or current owner of the object. `NFToken` objects are grouped into pages that implicitly define the object type and identify the owner.
## NFTokenID
@@ -40,7 +40,7 @@ D) A 32-bit issuer-specified [`NFTokenTaxon`](https://www.merriam-webster.com/di
E) An (automatically generated) monotonically increasing 32-bit sequence number.
![Token ID Breakdown](img/nftoken1.png "Token ID Breakdown")
![Token ID Breakdown](/img/nftoken1.png "Token ID Breakdown")
The 16-bit flags, transfer fee fields, the 32-bit `NFTokenTaxon`, and the sequence number fields are stored in big-endian format.
@@ -53,7 +53,7 @@ Flags are properties or other options associated with the `NFToken` object.
|:------------------|:-----------|:--------------------------------------------|
| `lsfBurnable` | `0x0001` | If enabled, the issuer (or an entity authorized by the issuer) can destroy this `NFToken`. The object's owner can always do so. |
| `lsfOnlyXRP` | `0x0002` | If enabled, this `NFToken` can only be offered or sold for XRP. |
| `lsfTrustLine` | `0x0004` | **DEPRECATED** If enabled, automatically create [trust lines](trust-lines-and-issuing.html) to hold transfer fees. Otherwise, buying or selling this `NFToken` for a fungible token amount fails if the issuer does not have a trust line for that token. The [fixRemoveNFTokenAutoTrustLine amendment][] makes it invalid to enable this flag. |
| `lsfTrustLine` | `0x0004` | **DEPRECATED** If enabled, automatically create [trust lines](../../../concepts/tokens/fungible-tokens/index.md) to hold transfer fees. Otherwise, buying or selling this `NFToken` for a fungible token amount fails if the issuer does not have a trust line for that token. The [fixRemoveNFTokenAutoTrustLine amendment][] makes it invalid to enable this flag. |
| `lsfTransferable` | `0x0008` | If enabled, this `NFToken` can be transferred from one holder to another. Otherwise, it can only be transferred to or from the issuer. |
| `lsfReservedFlag` | `0x8000` | This flag is reserved for future use. Attempts to set this flag fail. |
@@ -63,7 +63,7 @@ Flags are properties or other options associated with the `NFToken` object.
The example sets three flags: `lsfBurnable` (`0x0001`), `lsfOnlyXRP` (`0x0002`), `lsfTransferable` (`0x0008`). 1+2+8 = 11, or `0x000B` in big endian format.
![Flags](img/nftokena.png "Flags")
![Flags](/img/nftokena.png "Flags")
### TransferFee
<!-- SPELLING_IGNORE: transferfee -->
@@ -74,20 +74,20 @@ The `TransferFee` value specifies the percentage fee, in units of 1/100,000, cha
This value sets the transfer fee to 314, or 0.314%.
![Transfer Fee](img/nftokenb.png "Transfer Fee")
![Transfer Fee](/img/nftokenb.png "Transfer Fee")
### Issuer Identification
The third section of the `NFTokenID` is a big endian representation of the issuer’s public address.
![Issuer Address](img/nftokenc.png "Issuer Address")
![Issuer Address](/img/nftokenc.png "Issuer Address")
### NFTokenTaxon
<!-- SPELLING_IGNORE: nftokentaxon -->
The fourth section is a `NFTokenTaxon` created by the issuer.
![Diagram of `NFTokenTaxon` bits](img/nftokend.png)
![Diagram of `NFTokenTaxon` bits](/img/nftokend.png)
An issuer might issue several `NFToken` objects with the same `NFTokenTaxon`; to ensure that `NFToken` objects are spread across multiple pages, the `NFTokenTaxon` is scrambled using the fifth section, a sequential number, as the seed for a random number generator. The scrambled value is stored with the `NFToken`, but the unscrambled value is the actual `NFTokenTaxon`.
@@ -97,7 +97,7 @@ Notice that the scrambled version of the `NFTokenTaxon` is `0xBC8B858E`, the scr
The fifth section is a sequence number that increases with each `NFToken` the issuer creates.
![Sequence Number](img/nftokene.png "Sequence Number")
![Sequence Number](/img/nftokene.png "Sequence Number")
The [NFTokenMint transaction][] sets this part of the `NFTokenID` automatically based on the `MintedNFTokens` field of the `Issuer` account. If the issuer's [AccountRoot object][] does not have a `MintedNFTokens` field, the field is assumed to have the value 0; the value of the field is then incremented by exactly 1.
@@ -131,7 +131,4 @@ https://example.com/.well-known/xrpl-nft/{nftokenid}
You create `NFToken` objects using the `NFTokenMint` transaction. You can optionally destroy `NFToken` objects using the `NFTokenBurn` transaction.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/index.md
View File

@@ -1,10 +1,14 @@
---
html: protocol-reference.html
parent: references.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
eyebrow_text: Features and Rules
blurb: Features and rules of the XRP Ledger protocol, regardless of how you access it.
---
# XRP Ledger Protocol Reference
Features and rules of the XRP Ledger protocol, regardless of how you access it.
Features and rules of the XRP Ledger protocol, regardless of how you access it.
{% child-pages /%}

13
content/references/protocol/ledger-data/common-fields.md
View File

@@ -5,12 +5,12 @@ blurb: These common fields are part of every ledger entry.
# Ledger Entry Common Fields
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp)
Every entry in a [ledger](ledgers.html)'s state data has the same set of common fields, plus additional fields based on the [ledger entry type](ledger-entry-types.html). Field names are case-sensitive. The common fields for all ledger entries are:
Every entry in a [ledger](../../../concepts/ledgers/index.md)'s state data has the same set of common fields, plus additional fields based on the [ledger entry type](ledger-entry-types/index.md). Field names are case-sensitive. The common fields for all ledger entries are:
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------------------|:----------|:------------------|:----------|:------------|
| `index` or `LedgerIndex` | String | Hash256 | No | The unique ID for this ledger entry. In JSON, this field is represented with different names depending on the context and API method. (Note, even though this is specified as "optional" in the code, every ledger entry should have one unless it's legacy data from very early in the XRP Ledger's history.) |
| `LedgerEntryType` | String | UInt16 | Yes | The type of ledger entry. Valid [ledger entry types](ledger-entry-types.html) include `AccountRoot`, `Offer`, `RippleState`, and others. |
| `LedgerEntryType` | String | UInt16 | Yes | The type of ledger entry. Valid [ledger entry types](ledger-entry-types/index.md) include `AccountRoot`, `Offer`, `RippleState`, and others. |
| `Flags` | Number | UInt32 | Yes | Set of bit-flags for this ledger entry. |
**Caution:** In JSON, the ledger entry ID is in the `index` or `LedgerIndex` field. This is not the same as a [ledger index][] in the `ledger_index` field.
@@ -20,13 +20,13 @@ Every entry in a [ledger](ledgers.html)'s state data has the same set of common
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/Indexes.cpp)
Each ledger entry has a unique ID. The ID is derived by hashing important contents of the entry, along with a [namespace identifier](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/LedgerFormats.h). The [ledger entry type](ledger-entry-types.html) determines the namespace identifier to use and which contents to include in the hash. This ensures every ID is unique. The hash function is [SHA-512Half][].
Each ledger entry has a unique ID. The ID is derived by hashing important contents of the entry, along with a [namespace identifier](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/LedgerFormats.h). The [ledger entry type](ledger-entry-types/index.md) determines the namespace identifier to use and which contents to include in the hash. This ensures every ID is unique. The hash function is [SHA-512Half][].
Generally, a ledger entry's ID is returned as the `index` field in JSON, at the same level as the object's contents. In [transaction metadata](transaction-metadata.html), the ledger object's ID in JSON is `LedgerIndex`.
Generally, a ledger entry's ID is returned as the `index` field in JSON, at the same level as the object's contents. In [transaction metadata](../transactions/metadata.md), the ledger object's ID in JSON is `LedgerIndex`.
Offer directories have special IDs, where part of the hash is replaced with the exchange rate of Offers in that directory.
{{ include_svg("img/ledger-object-ids.svg", "Diagram: ID calculations for different types of ledger entries. The space key prevents IDs for different types from colliding.") }}
[{% inline-svg file="/img/ledger-object-ids.svg" /%}](/img/ledger-object-ids.svg "Diagram: ID calculations for different types of ledger entries. The space key prevents IDs for different types from colliding.")
## Flags
@@ -35,5 +35,4 @@ Flags are on/off settings, which are represented as binary values that are combi
The possible values for the flags field vary based on the ledger entry type. Some ledger entry types have no flags defined. In these cases, the `Flags` field always has the value `0`.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

10
content/references/protocol/ledger-data/index.md
View File

@@ -5,15 +5,15 @@ blurb: Learn about individual entries that comprise the XRP Ledger's shared stat
---
# Ledger Data Formats
Each [ledger version](ledgers.html) in the XRP Ledger is made up of three parts:
Each [ledger version](../../../concepts/ledgers/index.md) in the XRP Ledger is made up of three parts:
- **[Ledger Header](ledger-header.html)**: Data about this ledger version itself.
- **[Transaction Set](transaction-formats.html)**: The transactions that were executed to create this ledger version.
- **[State Data](ledger-entry-types.html)**: A list of ledger entries, representing all accounts, settings, and balances as of this ledger version. (This is also called the "account state".)
- **[Ledger Header](ledger-header.md)**: Data about this ledger version itself.
- **[Transaction Set](../transactions/index.md)**: The transactions that were executed to create this ledger version.
- **[State Data](ledger-entry-types/index.md)**: A list of ledger entries, representing all accounts, settings, and balances as of this ledger version. (This is also called the "account state".)
## State Data
{% include '_snippets/ledger-objects-intro.md' %}
{% partial file="/_snippets/ledger-objects-intro.md" /%}
{% from '_snippets/macros/page-children.md' import page_children with context %}
{{ page_children(pages|selectattr("html", "eq", "ledger-object-types.html")|first, 1, 1, True) }}

56
content/references/protocol/ledger-data/ledger-entry-types/accountroot.md
View File

@@ -9,9 +9,9 @@ labels:
# AccountRoot
[[Source]](https://github.com/XRPLF/rippled/blob/264280edd79b7f764536e02459f33f66a59c0531/src/ripple/protocol/impl/LedgerFormats.cpp#L36-L60 "Source")
An `AccountRoot` ledger entry type describes a single [account](accounts.html), its settings, and XRP balance.
An `AccountRoot` ledger entry type describes a single [account](../../../../concepts/accounts/accounts.md), its settings, and XRP balance.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -32,40 +32,40 @@ An `AccountRoot` ledger entry type describes a single [account](accounts.html),
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:------------------------------|:----------|:------------------|:----------|:-------------|
| `Account` | String | AccountID | Yes | The identifying (classic) address of this [account](accounts.html). |
| `AccountTxnID` | String | Hash256 | No | The identifying hash of the transaction most recently sent by this account. This field must be enabled to use the [`AccountTxnID` transaction field](transaction-common-fields.html#accounttxnid). To enable it, send an [AccountSet transaction with the `asfAccountTxnID` flag enabled](accountset.html#accountset-flags). |
| `AMMID` | String | Hash256 | No | _(Requires the [AMM amendment][] :not_enabled:)_ The ledger entry ID of the corresponding AMM ledger entry. Set during account creation; cannot be modified. If present, indicates that this is a special AMM AccountRoot; always omitted on non-AMM accounts. |
| `Account` | String | AccountID | Yes | The identifying (classic) address of this [account](../../../../concepts/accounts/accounts.md). |
| `AccountTxnID` | String | Hash256 | No | The identifying hash of the transaction most recently sent by this account. This field must be enabled to use the [`AccountTxnID` transaction field](../../transactions/common-fields.md#accounttxnid). To enable it, send an [AccountSet transaction with the `asfAccountTxnID` flag enabled](../../transactions/types/accountset.md#accountset-flags). |
| `AMMID` | String | Hash256 | No | _(Requires the [AMM amendment][] {% not-enabled /%})_ The ledger entry ID of the corresponding AMM ledger entry. Set during account creation; cannot be modified. If present, indicates that this is a special AMM AccountRoot; always omitted on non-AMM accounts. |
| `Balance` | String | Amount | No | The account's current [XRP balance in drops][XRP, in drops], represented as a string. |
| `BurnedNFTokens` | Number | UInt32 | No | How many total of this account's issued [non-fungible tokens](non-fungible-tokens.html) have been burned. This number is always equal or less than `MintedNFTokens`. |
| `BurnedNFTokens` | Number | UInt32 | No | How many total of this account's issued [non-fungible tokens](../../../../concepts/tokens/nfts/index.md) have been burned. This number is always equal or less than `MintedNFTokens`. |
| `Domain` | String | Blob | No | A domain associated with this account. In JSON, this is the hexadecimal for the ASCII representation of the domain. [Cannot be more than 256 bytes in length.](https://github.com/xrplf/rippled/blob/55dc7a252e08a0b02cd5aa39e9b4777af3eafe77/src/ripple/app/tx/impl/SetAccount.h#L34) |
| `EmailHash` | String | Hash128 | No | The md5 hash of an email address. Clients can use this to look up an avatar through services such as [Gravatar](https://en.gravatar.com/). |
| `FirstNFTokenSequence` | Number | UInt32 | No | The account's [Sequence Number][] at the time it minted its first [non-fungible-token](non-fungible-tokens.html). _(Added by the [fixNFTokenRemint amendment][] :not_enabled:)_ |
| `FirstNFTokenSequence` | Number | UInt32 | No | The account's [Sequence Number][] at the time it minted its first [non-fungible-token](../../../../concepts/tokens/nfts/index.md). _(Added by the [fixNFTokenRemint amendment][] {% not-enabled /%})_ |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0061`, mapped to the string `AccountRoot`, indicates that this is an AccountRoot object. |
| `MessageKey` | String | Blob | No | A public key that may be used to send encrypted messages to this account. In JSON, uses hexadecimal. Must be exactly 33 bytes, with the first byte indicating the key type: `0x02` or `0x03` for secp256k1 keys, `0xED` for Ed25519 keys. |
| `MintedNFTokens` | Number | UInt32 | No | How many total [non-fungible tokens](non-fungible-tokens.html) have been minted by and on behalf of this account. _(Added by the [NonFungibleTokensV1_1 amendment][])_ |
| `NFTokenMinter` | String | AccountID | No | Another account that can mint [non-fungible tokens](non-fungible-tokens.html) on behalf of this account. _(Added by the [NonFungibleTokensV1_1 amendment][])_ |
| `MintedNFTokens` | Number | UInt32 | No | How many total [non-fungible tokens](../../../../concepts/tokens/nfts/index.md) have been minted by and on behalf of this account. _(Added by the [NonFungibleTokensV1_1 amendment][])_ |
| `NFTokenMinter` | String | AccountID | No | Another account that can mint [non-fungible tokens](../../../../concepts/tokens/nfts/index.md) on behalf of this account. _(Added by the [NonFungibleTokensV1_1 amendment][])_ |
| `OwnerCount` | Number | UInt32 | Yes | The number of objects this account owns in the ledger, which contributes to its owner reserve. |
| `PreviousTxnID` | String | Hash256 | Yes | The identifying hash of the transaction that most recently modified this object. |
| `PreviousTxnLgrSeq` | Number | UInt32 | Yes |The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. |
| `RegularKey` | String | AccountID | No | The address of a [key pair](cryptographic-keys.html) that can be used to sign transactions for this account instead of the master key. Use a [SetRegularKey transaction][] to change this value. |
| `Sequence` | Number | UInt32 | Yes | The [sequence number](basic-data-types.html#account-sequence) of the next valid transaction for this account. |
| `TicketCount` | Number | UInt32 | No | How many [Tickets](tickets.html) this account owns in the ledger. This is updated automatically to ensure that the account stays within the hard limit of 250 Tickets at a time. This field is omitted if the account has zero Tickets. _(Added by the [TicketBatch amendment][].)_ |
| `RegularKey` | String | AccountID | No | The address of a [key pair](../../../../concepts/accounts/cryptographic-keys.md) that can be used to sign transactions for this account instead of the master key. Use a [SetRegularKey transaction][] to change this value. |
| `Sequence` | Number | UInt32 | Yes | The [sequence number](../../data-types/basic-data-types.md#account-sequence) of the next valid transaction for this account. |
| `TicketCount` | Number | UInt32 | No | How many [Tickets](../../../../concepts/accounts/tickets.md) this account owns in the ledger. This is updated automatically to ensure that the account stays within the hard limit of 250 Tickets at a time. This field is omitted if the account has zero Tickets. _(Added by the [TicketBatch amendment][].)_ |
| `TickSize` | Number | UInt8 | No | How many significant digits to use for exchange rates of Offers involving currencies issued by this address. Valid values are `3` to `15`, inclusive. _(Added by the [TickSize amendment][].)_ |
| `TransferRate` | Number | UInt32 | No | A [transfer fee](transfer-fees.html) to charge other users for sending currency issued by this account to each other. |
| `TransferRate` | Number | UInt32 | No | A [transfer fee](../../../../concepts/tokens/transfer-fees.md) to charge other users for sending currency issued by this account to each other. |
| `WalletLocator` | String | Hash256 | No | An arbitrary 256-bit value that users can set. |
| `WalletSize` | Number | UInt32 | No | Unused. (The code supports this field but there is no way to set it.) |
## Special AMM AccountRoot Entries
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
Automated Market Makers use an AccountRoot ledger entry to issue their LP Tokens and hold the assets in the AMM pool, and an [AMM ledger entry](amm.html) for tracking some of the details of the AMM. The address of an AMM's AccountRoot is randomized so that users cannot identify and fund the address in advance of the AMM being created. Unlike normal accounts, AMM AccountRoot objects are created with the following settings:
Automated Market Makers use an AccountRoot ledger entry to issue their LP Tokens and hold the assets in the AMM pool, and an [AMM ledger entry](amm.md) for tracking some of the details of the AMM. The address of an AMM's AccountRoot is randomized so that users cannot identify and fund the address in advance of the AMM being created. Unlike normal accounts, AMM AccountRoot objects are created with the following settings:
- `lsfDisableMaster` **enabled** and no means of authorizing transactions. This ensures no one can control the account directly, and it cannot send transactions.
- `lsfDepositAuth` **enabled** and no accounts preauthorized. This ensures that the only way to add money to the AMM Account is using the [AMMDeposit transaction][].
@@ -73,7 +73,7 @@ Automated Market Makers use an AccountRoot ledger entry to issue their LP Tokens
In addition, the following special rules apply to an AMM's AccountRoot entry:
- It is not subject to the [reserve requirement](reserves.html). It can hold XRP only if XRP is one of the two assets in the AMM's pool.
- It is not subject to the [reserve requirement](../../../../concepts/accounts/reserves.md). It can hold XRP only if XRP is one of the two assets in the AMM's pool.
- It cannot be the destination of Checks, Escrows, or Payment Channels. Any transactions that would create such entries instead fail with the result code `tecNO_PERMISSION`.
- Users cannot create trust lines to it for anything other than the AMM's LP Tokens. Transactions that would create such trust lines instead fail with result code `tecNO_PERMISSION`. (The AMM does have two trust lines to hold the tokens in its pool, or one trust line if the other asset in its pool is XRP.)
- If the [Clawback amendment][] is also enabled, the issuer cannot clawback funds from an AMM.
@@ -86,11 +86,11 @@ Many AccountRoot flags correspond to options you can change with an [AccountSet
AccountRoot objects can have the following flags combined in the `Flags` field:
| Flag Name | Hex Value | Decimal Value | Corresponding [AccountSet Flag](accountset.html#accountset-flags) | Description |
| Flag Name | Hex Value | Decimal Value | Corresponding [AccountSet Flag](../../transactions/types/accountset.md#accountset-flags) | Description |
|-----------------------------------|--------------|-------------------|-----------------------------------|----|
| `lsfAllowTrustLineClawback` | `0x80000000` | 2147483648 | `asfAllowTrustLineClawback` | Enable [Clawback](clawing-back-tokens.html) for this account. _(Requires the [Clawback amendment][].)_ |
| `lsfDefaultRipple` | `0x00800000` | 8388608 | `asfDefaultRipple` | Enable [rippling](rippling.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. |
| `lsfDepositAuth` | `0x01000000` | 16777216 | `asfDepositAuth` | This account has [DepositAuth](depositauth.html) enabled, meaning it can only receive funds from transactions it sends, and from [preauthorized](depositauth.html#preauthorization) accounts. _(Added by the [DepositAuth amendment][])_ |
| `lsfAllowTrustLineClawback` | `0x80000000` | 2147483648 | `asfAllowTrustLineClawback` | Enable [Clawback](../../../../concepts/tokens/fungible-tokens/clawing-back-tokens.md) for this account. _(Requires the [Clawback amendment][].)_ |
| `lsfDefaultRipple` | `0x00800000` | 8388608 | `asfDefaultRipple` | Enable [rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. |
| `lsfDepositAuth` | `0x01000000` | 16777216 | `asfDepositAuth` | This account has [DepositAuth](../../../../concepts/accounts/depositauth.md) enabled, meaning it can only receive funds from transactions it sends, and from [preauthorized](../../../../concepts/accounts/depositauth.md#preauthorization) accounts. _(Added by the [DepositAuth amendment][])_ |
| `lsfDisableMaster` | `0x00100000` | 1048576 | `asfDisableMaster` | Disallows use of the master key to sign transactions for this account. |
| `lsfDisallowIncomingCheck` | `0x08000000` | 134217728 | `asfDisallowIncomingCheck` | This account blocks incoming Checks. _(Added by the [DisallowIncoming amendment][].)_ |
| `lsfDisallowIncomingNFTokenOffer` | `0x04000000` | 67108864 | `asfDisallowIncomingNFTokenOffer` | This account blocks incoming NFTokenOffers. _(Added by the [DisallowIncoming amendment][].)_ |
@@ -103,21 +103,17 @@ AccountRoot objects can have the following flags combined in the `Flags` field:
| `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. |
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
The [reserve](reserves.html) for an AccountRoot entry is the base reserve, currently {{target.base_reserve}}, except in the case of a special AMM AccountRoot.
The [reserve](../../../../concepts/accounts/reserves.md) for an AccountRoot entry is the base reserve, currently {% $env.PUBLIC_BASE_RESERVE %}, except in the case of a special AMM AccountRoot.
This XRP cannot be sent to others but it can be burned as part of the [transaction cost][].
## {{currentpage.name}} ID Format
## {% $frontmatter.seo.title %} ID Format
The ID of an AccountRoot entry is the [SHA-512Half][] of the following values, concatenated in order:
* The Account space key (`0x0061`)
* The AccountID of the account
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

29
content/references/protocol/ledger-data/ledger-entry-types/amendments.md
View File

@@ -8,9 +8,9 @@ labels:
# Amendments
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L138-L144 "Source")
The `Amendments` ledger entry type contains a list of [Amendments](amendments.html) that are currently active. Each ledger version contains **at most one** `Amendments` entry.
The `Amendments` ledger entry type contains a list of [Amendments](../../../../concepts/networks-and-servers/amendments.md) that are currently active. Each ledger version contains **at most one** `Amendments` entry.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -34,13 +34,13 @@ The `Amendments` ledger entry type contains a list of [Amendments](amendments.ht
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), the `{{currentpage.name}}` ledger entry has the following fields:
In addition to the [common fields](../common-fields.md), the {% code-page-name /%} ledger entry has the following fields:
| Name | JSON Type | [Internal Type][] | Required? | Description |
|-------------------|-----------|-------------------|-----------|-------------|
| `Amendments` | Array | Vector256 | No | Array of 256-bit [amendment IDs](amendments.html) for all currently enabled amendments. If omitted, there are no enabled amendments. |
| `Amendments` | Array | Vector256 | No | Array of 256-bit [amendment IDs](../../../../concepts/networks-and-servers/amendments.md) for all currently enabled amendments. If omitted, there are no enabled amendments. |
| `Flags` | Number | UInt32 | Yes | A bit-map of boolean flags enabled for this object. Currently, the protocol defines no flags for `Amendments` objects. The value is always `0`. |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0066`, mapped to the string `Amendments`, indicates that this object describes the status of amendments to the XRP Ledger. |
| `Majorities` | Array | STArray | No | Array of objects describing the status of amendments that have majority support but are not yet enabled. If omitted, there are no pending amendments with majority support. |
@@ -50,23 +50,23 @@ Each member of the `Majorities` field, if it is present, is an object with one f
| Name | JSON Type | [Internal Type][] | Description |
|-------------------|-----------|-------------------|-------------|
| `Amendment` | String | Hash256 | The Amendment ID of the pending amendment. |
| `CloseTime` | Number | UInt32 | The [`close_time` field](ledger-header.html) of the ledger version where this amendment most recently gained a majority. |
| `CloseTime` | Number | UInt32 | The [`close_time` field](../ledger-header.md) of the ledger version where this amendment most recently gained a majority. |
In the [amendment process](amendments.html#amendment-process), a consensus of validators adds a new amendment to the `Majorities` field using an [EnableAmendment][] pseudo-transaction with the `tfGotMajority` flag when 80% or more of validators support it. If support for a pending amendment goes below 80%, an [EnableAmendment][] pseudo-transaction with the `tfLostMajority` flag removes the amendment from the `Majorities` array. If an amendment remains in the `Majorities` field for at least 2 weeks, an [EnableAmendment][] pseudo-transaction with no flags removes it from `Majorities` and permanently adds it to the `Amendments` field.
In the [amendment process](../../../../concepts/networks-and-servers/amendments.md#amendment-process), a consensus of validators adds a new amendment to the `Majorities` field using an [EnableAmendment][] pseudo-transaction with the `tfGotMajority` flag when 80% or more of validators support it. If support for a pending amendment goes below 80%, an [EnableAmendment][] pseudo-transaction with the `tfLostMajority` flag removes the amendment from the `Majorities` array. If an amendment remains in the `Majorities` field for at least 2 weeks, an [EnableAmendment][] pseudo-transaction with no flags removes it from `Majorities` and permanently adds it to the `Amendments` field.
**Note:** Technically, all transactions in a ledger are processed based on which amendments are enabled in the ledger version immediately before it. While applying transactions to a ledger version where an amendment becomes enabled, the rules don't change mid-ledger. After the ledger is closed, the next ledger uses the new rules as defined by any new amendments that applied.
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for the `{{currentpage.name}}` entry.
There are no flags defined for the {% code-page-name /%} entry.
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
The `{{currentpage.name}}` entry does not require a reserve.
The {% code-page-name /%} entry does not require a reserve.
## {{currentpage.name}} ID Format
## {% $frontmatter.seo.title %} ID Format
The ID of the `Amendments` entry is the hash of the `Amendments` space key (`0x0066`) only. This means that the ID is always:
@@ -76,7 +76,4 @@ The ID of the `Amendments` entry is the hash of the `Amendments` space key (`0x0
(Don't mix up the ID of the `Amendments` ledger entry type with the Amendment ID of an individual amendment.)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

21
content/references/protocol/ledger-data/ledger-entry-types/amm.md
View File

@@ -9,9 +9,9 @@ status: not_enabled
# AMM
[[Source]](https://github.com/XRPLF/rippled/blob/89780c8e4fd4d140fcb912cf2d0c01c1b260539e/src/ripple/protocol/impl/LedgerFormats.cpp#L272-L284 "Source")
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
An `AMM` ledger entry describes a single [Automated Market Maker](automated-market-makers.html) (AMM) instance. This is always paired with a [special AccountRoot entry](accountroot.html#special-amm-accountroot-entries).
An `AMM` ledger entry describes a single [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) (AMM) instance. This is always paired with a [special AccountRoot entry](accountroot.md#special-amm-accountroot-entries).
## Example AMM JSON
@@ -69,13 +69,13 @@ An `AMM` ledger entry describes a single [Automated Market Maker](automated-mark
## AMM Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-----------------|:--------------------|:------------------|:----------|--------------|
| `Asset` | Object | STIssue | Yes | The definition for one of the two assets this AMM holds. In JSON, this is an object with `currency` and `issuer` fields. |
| `Asset2` | Object | STIssue | Yes | The definition for the other asset this AMM holds. In JSON, this is an object with `currency` and `issuer` fields. |
| `Account` | String | AccountID | Yes | The address of the [special account](accountroot.html#special-amm-accountroot-entries) that holds this AMM's assets. |
| `Account` | String | AccountID | Yes | The address of the [special account](accountroot.md#special-amm-accountroot-entries) that holds this AMM's assets. |
| `AuctionSlot` | Object | STObject | No | Details of the current owner of the auction slot, as an [Auction Slot object](#auction-slot-object). |
| `LPTokenBalance` | [Currency Amount][] | Amount | Yes | The total outstanding balance of liquidity provider tokens from this AMM instance. The holders of these tokens can vote on the AMM's trading fee in proportion to their holdings, or redeem the tokens for a share of the AMM's assets which grows with the trading fees collected. |
| `TradingFee` | Number | UInt16 | Yes | The percentage fee to be charged for trades against this AMM instance, in units of 1/100,000. The maximum value is 1000, for a 1% fee. |
@@ -104,14 +104,14 @@ The `VoteSlots` field contains an array of `VoteEntry` objects with the followin
| `VoteWeight` | Number | UInt32 | Yes | The weight of the vote, in units of 1/100,000. For example, a value of 1234 means this vote counts as 1.234% of the weighted total vote. The weight is determined by the percentage of this AMM's LP Tokens the account owns. The maximum value is 100000. |
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
`{{currentpage.name}}` entries do not require a reserve.
{% code-page-name /%} entries do not require a reserve.
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for `{{currentpage.name}}` entries.
There are no flags defined for {% code-page-name /%} entries.
## AMM ID Format
@@ -126,7 +126,4 @@ The ID of an `AMM` entry is the [SHA-512Half][] of the following values, concate
For XRP, use all 0's for both the token and the issuer.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

10
content/references/protocol/ledger-data/ledger-entry-types/bridge.md
View File

@@ -7,7 +7,7 @@ labels:
status: not_enabled
---
# Bridge
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L286-L300 "Source")
@@ -46,7 +46,7 @@ The `Bridge` ledger entry represents a single cross-chain bridge that connects t
## Bridge Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Field | JSON Type | Internal Type | Required? | Description |
|:---------------------------|:--------------------|:------------------|:----------|:------------|
@@ -68,8 +68,4 @@ In addition to the [common fields](ledger-entry-common-fields.html), `{{currentp
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

25
content/references/protocol/ledger-data/ledger-entry-types/check.md
View File

@@ -10,9 +10,9 @@ labels:
_(Added by the [Checks amendment][].)_
A `Check` entry describes a [check](checks.html), similar to a paper personal check, which can be cashed by its destination to get money from its sender.
A `Check` entry describes a [check](../../../../concepts/payment-types/checks.md), similar to a paper personal check, which can be cashed by its destination to get money from its sender.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -33,9 +33,9 @@ A `Check` entry describes a [check](checks.html), similar to a paper personal ch
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:-----------------|:------------------|:----------|:----------------|
@@ -54,14 +54,14 @@ In addition to the [common fields](ledger-entry-common-fields.html), `{{currentp
| `SourceTag` | Number | UInt32 | No | An arbitrary tag to further specify the source for this Check, such as a hosted recipient at the sender's address. |
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for `{{currentpage.name}}` entries.
There are no flags defined for {% code-page-name /%} entries.
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
`{{currentpage.name}}` entries count as one item towards the owner reserve of the sender of the Check as long as the entry is in the ledger. This reserve is freed up when the check is cashed or canceled.
{% code-page-name /%} entries count as one item towards the owner reserve of the sender of the Check as long as the entry is in the ledger. This reserve is freed up when the check is cashed or canceled.
## Check ID Format
@@ -72,11 +72,8 @@ The ID of a `Check` entry is the [SHA-512Half][] of the following values, concat
* The Check space key (`0x0043`)
* The AccountID of the sender of the [CheckCreate transaction][] that created the `Check`
* The `Sequence` number of the [CheckCreate transaction][] that created the `Check`.
If the CheckCreate transaction used a [Ticket](tickets.html), use the `TicketSequence` value instead.
If the CheckCreate transaction used a [Ticket](../../../../concepts/accounts/tickets.md), use the `TicketSequence` value instead.
See the tutorial showing how to [Send a Check](send-a-check.html).
See the tutorial showing how to [Send a Check](../../../../tutorials/use-specialized-payment-types/use-checks/send-a-check.md).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

21
content/references/protocol/ledger-data/ledger-entry-types/depositpreauth.md
View File

@@ -10,9 +10,9 @@ labels:
A `DepositPreauth` entry tracks a preauthorization from one account to another. [DepositPreauth transactions][] create these entries.
This has no effect on processing of transactions unless the account that provided the preauthorization requires [Deposit Authorization](depositauth.html). In that case, the account that was preauthorized can send payments and other transactions directly to the account that provided the preauthorization. Preauthorizations are one-directional, and have no effect on payments going the opposite direction.
This has no effect on processing of transactions unless the account that provided the preauthorization requires [Deposit Authorization](../../../../concepts/accounts/depositauth.md). In that case, the account that was preauthorized can send payments and other transactions directly to the account that provided the preauthorization. Preauthorizations are one-directional, and have no effect on payments going the opposite direction.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -27,9 +27,9 @@ This has no effect on processing of transactions unless the account that provide
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:-----------------|:------------------|:----------|:----------------|
@@ -41,13 +41,13 @@ In addition to the [common fields](ledger-entry-common-fields.html), `{{currentp
| `PreviousTxnLgrSeq` | Number | UInt32 | Yes | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. |
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for `{{currentpage.name}}` entries.
There are no flags defined for {% code-page-name /%} entries.
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
`{{currentpage.name}}` entries count as one item towards the owner reserve of the account that granted preauthorization, as long as the entry is in the ledger. Unauthorizing the counterparty frees up the reserve.
{% code-page-name /%} entries count as one item towards the owner reserve of the account that granted preauthorization, as long as the entry is in the ledger. Unauthorizing the counterparty frees up the reserve.
## DepositPreauth ID Format
@@ -57,7 +57,4 @@ The ID of a `DepositPreauth` object is the [SHA-512Half][] of the following valu
* The AccountID of the owner of this object (the sender of the [DepositPreauth transaction][] that created this object; in other words, the one that granted the preauthorization)
* The AccountID of the preauthorized account (the `Authorized` field of the [DepositPreauth transaction][] that created this object; in other words, the one that received the preauthorization)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

20
content/references/protocol/ledger-data/ledger-entry-types/did.md
View File

@@ -9,9 +9,9 @@ status: not_enabled
# DID
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L330-L341 "Source")
_(Requires the [DID amendment][] :not_enabled:)_
_(Requires the [DID amendment][] {% not-enabled /%})_
A `DID` ledger entry holds references to, or data associated with, a single [DID](decentralized-identifiers.html).
A `DID` ledger entry holds references to, or data associated with, a single [DID](../../../../concepts/accounts/decentralized-identifiers.md).
## Example DID JSON
@@ -33,7 +33,7 @@ A `DID` ledger entry holds references to, or data associated with, a single [DID
## DID Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|--------------|
@@ -47,14 +47,14 @@ In addition to the [common fields](ledger-entry-common-fields.html), `{{currentp
| `URI` | String | Blob | No | The Universal Resource Identifier that points to the corresponding DID document or the data associated with the DID. This field can be an HTTP(S) URL or IPFS URI. This field isn't checked for validity and is limited to a maximum length of 256 bytes. |
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
The account that creates the `{{currentpage.name}}` object incurs one owner reserve.
The account that creates the {% code-page-name /%} object incurs one owner reserve.
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for `{{currentpage.name}}` entries.
There are no flags defined for {% code-page-name /%} entries.
## DID ID Format
@@ -64,8 +64,4 @@ The ID of a `DID` entry is the [SHA-512Half][] of the following values, concaten
1. The `DID` space key (`0x0049`).
2. The AccountID that controls the DID.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

35
content/references/protocol/ledger-data/ledger-entry-types/directorynode.md
View File

@@ -9,19 +9,18 @@ labels:
# DirectoryNode
[[Source]](https://github.com/XRPLF/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L44 "Source")
The `DirectoryNode` ledger entry type provides a list of links to other entries in the ledger's state data. A single conceptual _Directory_　takes the form of a doubly linked list, with one or more DirectoryNode entries each containing up to 32 [IDs of other entries](ledger-object-ids.html). The first DirectoryNode entry is called the root of the directory, and all entries other than the root can be added or deleted as necessary.
The `DirectoryNode` ledger entry type provides a list of links to other entries in the ledger's state data. A single conceptual _Directory_　takes the form of a doubly linked list, with one or more DirectoryNode entries each containing up to 32 [IDs of other entries](../common-fields.md). The first DirectoryNode entry is called the root of the directory, and all entries other than the root can be added or deleted as necessary.
There are two kinds of Directories:
* **Owner directories** list other entries owned by an account, such as [`RippleState` (trust line)](ripplestate.html) or [`Offer`](offer.html) entries.
* **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).
* **Owner directories** list other entries owned by an account, such as [`RippleState` (trust line)](ripplestate.md) or [`Offer`](offer.md) entries.
* **Offer directories** list the offers available in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md). 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
## Example {% $frontmatter.seo.title %} JSON
<!-- MULTICODE_BLOCK_START -->
*Offer Directory*
{% tabs %}
{% tab label="Offer Directory" %}
```json
{
"ExchangeRate": "4F069BA8FF484000",
@@ -38,9 +37,9 @@ There are two kinds of Directories:
"index": "1BBEF97EDE88D40CEE2ADE6FEF121166AFE80D99EBADB01A4F069BA8FF484000"
}
```
{% /tab %}
*Owner Directory*
{% tab label="Owner Directory" %}
```json
{
"Flags": 0,
@@ -54,10 +53,11 @@ There are two kinds of Directories:
"index": "193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94"
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
| Name | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:------------|
@@ -75,14 +75,14 @@ There are two kinds of Directories:
| `TakerPaysIssuer` | String | Hash160 | No | (Offer Directories only) The issuer of the `TakerPays` amount from the offers in this directory. |
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for `{{currentpage.name}}` entries.
There are no flags defined for {% code-page-name /%} entries.
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
`{{currentpage.name}}` entries do not require a reserve.
{% code-page-name /%} entries do not require a reserve.
## Directory ID Formats
@@ -114,7 +114,4 @@ The lower 64 bits of an Offer Directory's ID represent the `TakerPays` amount di
* The ID of the root DirectoryNode
* The page number of this object. (Since 0 is the root DirectoryNode, this value is an integer 1 or higher.)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

23
content/references/protocol/ledger-data/ledger-entry-types/escrow.md
View File

@@ -10,9 +10,9 @@ labels:
_(Added by the [Escrow amendment][].)_
An `Escrow` ledger entry represents an [escrow](escrow.html), which holds XRP until specific conditions are met.
An `Escrow` ledger entry represents an [escrow](../../../../concepts/payment-types/escrow.md), which holds XRP until specific conditions are met.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -34,9 +34,9 @@ An `Escrow` ledger entry represents an [escrow](escrow.html), which holds XRP un
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Name | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:-----------------------|
@@ -55,14 +55,14 @@ In addition to the [common fields](ledger-entry-common-fields.html), `{{currentp
| `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. |
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for `{{currentpage.name}}` entries.
There are no flags defined for {% code-page-name /%} entries.
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
`{{currentpage.name}}` entries count as one item towards the sender's owner reserve as long as the entry is in the ledger. Finishing or canceling the escrow frees up this reserve.
{% code-page-name /%} entries count as one item towards the sender's owner reserve as long as the entry is in the ledger. Finishing or canceling the escrow frees up this reserve.
## Escrow ID Format
@@ -72,9 +72,6 @@ The ID of an `Escrow` entry is the [SHA-512Half][] of the following values, conc
* The Escrow space key (`0x0075`)
* The AccountID of the sender of the [EscrowCreate transaction][] that created the `Escrow` entry
* The Sequence number of the [EscrowCreate transaction][] that created the `Escrow` entry
If the EscrowCreate transaction used a [Ticket](tickets.html), use the `TicketSequence` value instead.
If the EscrowCreate transaction used a [Ticket](../../../../concepts/accounts/tickets.md), use the `TicketSequence` value instead.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

30
content/references/protocol/ledger-data/ledger-entry-types/feesettings.md
View File

@@ -8,9 +8,9 @@ labels:
# FeeSettings
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L115-L120 "Source")
The `FeeSettings` entry contains the current base [transaction cost](transaction-cost.html) and [reserve amounts](reserves.html) as determined by [fee voting](fee-voting.html). Each ledger version contains **at most one** `FeeSettings` entry.
The `FeeSettings` entry contains the current base [transaction cost](../../../../concepts/transactions/transaction-cost.md) and [reserve amounts](../../../../concepts/accounts/reserves.md) as determined by [fee voting](../../../../concepts/consensus-protocol/fee-voting.md). Each ledger version contains **at most one** `FeeSettings` entry.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -24,18 +24,18 @@ The `FeeSettings` entry contains the current base [transaction cost](transaction
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), the `{{currentpage.name}}` ledger entry has the following fields:
In addition to the [common fields](../common-fields.md), the {% code-page-name /%} ledger entry has the following fields:
| Name | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:-----------------------|
| `BaseFee` | String | UInt64 | Yes | The [transaction cost](transaction-cost.html) of the "reference transaction" in drops of XRP as hexadecimal. |
| `BaseFee` | String | UInt64 | Yes | The [transaction cost](../../../../concepts/transactions/transaction-cost.md) of the "reference transaction" in drops of XRP as hexadecimal. |
| `Flags` | Number | UInt32 | Yes | A bit-map of boolean flags enabled for this object. Currently, the protocol defines no flags for `FeeSettings` objects. The value is always `0`. |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0073`, mapped to the string `FeeSettings`, indicates that this object contains the ledger's fee settings. |
| `ReferenceFeeUnits` | Number | UInt32 | Yes | The `BaseFee` translated into "fee units". |
| `ReserveBase` | Number | UInt32 | Yes | The [base reserve](reserves.html#base-reserve-and-owner-reserve) for an account in the XRP Ledger, as drops of XRP. |
| `ReserveIncrement` | Number | UInt32 | Yes | The incremental [owner reserve](reserves.html#base-reserve-and-owner-reserve) for owning objects, as drops of XRP. |
| `ReserveBase` | Number | UInt32 | Yes | The [base reserve](../../../../concepts/accounts/reserves.md#base-reserve-and-owner-reserve) for an account in the XRP Ledger, as drops of XRP. |
| `ReserveIncrement` | Number | UInt32 | Yes | The incremental [owner reserve](../../../../concepts/accounts/reserves.md#base-reserve-and-owner-reserve) for owning objects, as drops of XRP. |
**Warning:** The JSON format for this ledger entry type is unusual. The `BaseFee`, `ReserveBase`, and `ReserveIncrement` indicate drops of XRP but ***not*** in the usual format for [specifying XRP][Currency Amount].
@@ -44,16 +44,16 @@ If the _[XRPFees amendment][]_ is enabled, the `FeeSettings` object has these fi
| Name | JSON Type | [Internal Type][] | Required? | Description |
|:------------------------|:----------|:------------------|:----------|:-----------------------|
| `BaseFeeDrops` | String | Amount | Yes | The [transaction cost](transaction-cost.html) of the "reference transaction" in drops of XRP. |
| `BaseFeeDrops` | String | Amount | Yes | The [transaction cost](../../../../concepts/transactions/transaction-cost.md) of the "reference transaction" in drops of XRP. |
| `Flags` | Number | UInt32 | Yes | A bitmap of boolean flags enabled for this object. Currently, the protocol defines no flags for `FeeSettings` objects. The value is always `0`. |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0073`, mapped to the string `FeeSettings`, indicates that this object contains the ledger's fee settings. |
| `ReserveBaseDrops` | String | Amount | Yes | The [base reserve](reserves.html#base-reserve-and-owner-reserve) for an account in the XRP Ledger, as drops of XRP. |
| `ReserveIncrementDrops` | String | Amount | Yes | The incremental [owner reserve](reserves.html#base-reserve-and-owner-reserve) for owning objects, as drops of XRP. |
| `ReserveBaseDrops` | String | Amount | Yes | The [base reserve](../../../../concepts/accounts/reserves.md#base-reserve-and-owner-reserve) for an account in the XRP Ledger, as drops of XRP. |
| `ReserveIncrementDrops` | String | Amount | Yes | The incremental [owner reserve](../../../../concepts/accounts/reserves.md#base-reserve-and-owner-reserve) for owning objects, as drops of XRP. |
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for the `{{currentpage.name}}` entry.
There are no flags defined for the {% code-page-name /%} entry.
## FeeSettings ID Format
@@ -64,8 +64,4 @@ The ID of the `FeeSettings` entry is the hash of the `FeeSettings` space key (`0
4BC50C9B0D8515D3EAAE1E74B29A95804346C491EE1A95BF25E4AAB854A6A651
```
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/ledger-data/ledger-entry-types/index.md
View File

@@ -1,8 +1,12 @@
---
html: ledger-entry-types.html
parent: ledger-data-formats.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Ledger Entry Types
{% include '_snippets/ledger-objects-intro.md' %}
{% partial file="/_snippets/ledger-objects-intro.md" /%}
{% child-pages /%}

17
content/references/protocol/ledger-data/ledger-entry-types/ledgerhashes.md
View File

@@ -10,7 +10,7 @@ labels:
(Not to be confused with the ["ledger hash" string data type][Hash], which uniquely identifies a ledger version. This section describes the `LedgerHashes` ledger object type.)
The `LedgerHashes` object type contains a history of prior ledgers that led up to this ledger version, in the form of their hashes. Objects of this ledger type are modified automatically when closing a ledger. (This is one of the only times a ledger's state data is modified without a [transaction](transactions.html) or [pseudo-transaction](pseudo-transaction-types.html).) The `LedgerHashes` objects exist to make it possible to look up a previous ledger's hash with only the current ledger version and at most one lookup of a previous ledger version.
The `LedgerHashes` object type contains a history of prior ledgers that led up to this ledger version, in the form of their hashes. Objects of this ledger type are modified automatically when closing a ledger. (This is one of the only times a ledger's state data is modified without a [transaction](../../../../concepts/transactions/index.md) or [pseudo-transaction](../../transactions/pseudo-transaction-types/pseudo-transaction-types.md).) The `LedgerHashes` objects exist to make it possible to look up a previous ledger's hash with only the current ledger version and at most one lookup of a previous ledger version.
There are two kinds of `LedgerHashes` object. Both types have the same fields. Each ledger version contains:
@@ -39,13 +39,13 @@ Example `LedgerHashes` object (trimmed for length):
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Name | JSON Type | [Internal Type][] | Required? | Description |
|:----------------------|:-----------------|:------------------|:----------|:------------|
| `FirstLedgerSequence` | Number | UInt32 | No | **DEPRECATED** Do not use. (The "recent hashes" object on Mainnet has the value `2` in this field as a result of an old software bug. That value gets carried forward as the "recent hashes" object is updated. New "previous history" objects do not have this field, nor do "recent hashes" objects in [parallel networks](parallel-networks.html) started with more recent versions of `rippled`.) |
| `FirstLedgerSequence` | Number | UInt32 | No | **DEPRECATED** Do not use. (The "recent hashes" object on Mainnet has the value `2` in this field as a result of an old software bug. That value gets carried forward as the "recent hashes" object is updated. New "previous history" objects do not have this field, nor do "recent hashes" objects in [parallel networks](../../../../concepts/networks-and-servers/parallel-networks.md) started with more recent versions of `rippled`.) |
| `Hashes` | Array of Strings | Vector256 | Yes | An array of up to 256 ledger hashes. The contents depend on which sub-type of `LedgerHashes` object this is. |
| `LastLedgerSequence` | Number | UInt32 | No | The [Ledger Index][] of the last entry in this object's `Hashes` array. |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0068`, mapped to the string `LedgerHashes`, indicates that this object is a list of ledger hashes. |
@@ -67,9 +67,9 @@ The "previous history" `LedgerHashes` entries collectively contain the hash of e
The "previous history" `LedgerHashes` objects act as a [skip list](https://en.wikipedia.org/wiki/Skip_list) so you can get the hash of any historical flag ledger from its index. From there, you can use that flag ledger's "recent history" object to get the hash of any other ledger.
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for `{{currentpage.name}}` entries.
There are no flags defined for {% code-page-name /%} entries.
## LedgerHashes ID Formats
@@ -86,7 +86,4 @@ The **"previous history"** `LedgerHashes` objects have an ID that is the [SHA-51
**Tip:** Dividing by 65536 keeps the most significant 16 bits, which are the same for all the flag ledgers listed in a "previous history" object, and only those ledgers. You can use this fact to look up the `LedgerHashes` object that contains the hash of any flag ledger.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

17
content/references/protocol/ledger-data/ledger-entry-types/negativeunl.md
View File

@@ -9,11 +9,11 @@ labels:
_(Added by the [NegativeUNL amendment][].)_
The `NegativeUNL` ledger entry type contains the current status of the [Negative UNL](negative-unl.html), a list of trusted validators currently believed to be offline.
The `NegativeUNL` ledger entry type contains the current status of the [Negative UNL](../../../../concepts/consensus-protocol/negative-unl.md), a list of trusted validators currently believed to be offline.
Each ledger version contains **at most one** `NegativeUNL` entry. If no validators are currently disabled or scheduled to be disabled, there is no `NegativeUNL` entry.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -31,9 +31,9 @@ Each ledger version contains **at most one** `NegativeUNL` entry. If no validato
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), the `{{currentpage.name}}` ledger entry has the following fields:
In addition to the [common fields](../common-fields.md), the {% code-page-name /%} ledger entry has the following fields:
| Name | JSON Type | [Internal Type][] | Required? | Description |
|:----------------------|:----------|:------------------|:----------|:---------------------|
@@ -53,9 +53,9 @@ Each `DisabledValidator` object represents one disabled validator. In JSON, a `D
| `PublicKey` | String | Blob | The master public key of the validator, in hexadecimal. |
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for the `{{currentpage.name}}` entry.
There are no flags defined for the {% code-page-name /%} entry.
## NegativeUNL ID Format
@@ -66,7 +66,4 @@ The ID of the `NegativeUNL` entry is the hash of the `NegativeUNL` space key (`0
2E8A59AA9D3B5B186B0B9E0F62E6C02587CA74A4D778938E957B6357D364B244
```
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

22
content/references/protocol/ledger-data/ledger-entry-types/nftokenoffer.md
View File

@@ -7,11 +7,11 @@ labels:
---
# NFTokenOffer
An `NFTokenOffer` entry represents an offer to buy, sell or transfer an [NFT](non-fungible-tokens.html).
An `NFTokenOffer` entry represents an offer to buy, sell or transfer an [NFT](../../../../concepts/tokens/nfts/index.md).
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -29,7 +29,7 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
```
### {{currentpage.name}} Fields
### {% $frontmatter.seo.title %} Fields
| Name |JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:-----------------|:------------------|:------------|:-----------|
@@ -45,9 +45,9 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
| `PreviousTxnLgrSeq` | number | UInt32 | Yes | Index of the ledger that contains the transaction that most recently modified this object. |
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
{{currentpage.name}} entries can have the following flags combined in the `Flags` field:
{% $frontmatter.seo.title %} entries can have the following flags combined in the `Flags` field:
| Flag Name | Hex Value | Decimal Value | Description |
|------------------|--------------|---------------|-------------|
@@ -56,7 +56,7 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
## NFTokenOffer Transactions
Unlike [Offers for fungible tokens](offers.html), a `NFTokenOffer` is not stored in an order book and is never automatically matched or executed. A buyer must _explicitly_ choose to accept an `NFTokenOffer` that offers to sell a `NFToken`. Similarly, a seller must _explicitly_ choose to accept a specific `NFTokenOffer` that offers to buy a `NFToken` object that they own.
Unlike [Offers for fungible tokens](../../../../concepts/tokens/decentralized-exchange/offers.md), a `NFTokenOffer` is not stored in an order book and is never automatically matched or executed. A buyer must _explicitly_ choose to accept an `NFTokenOffer` that offers to sell a `NFToken`. Similarly, a seller must _explicitly_ choose to accept a specific `NFTokenOffer` that offers to buy a `NFToken` object that they own.
The transactions for `NFToken` trading are:
@@ -67,12 +67,12 @@ The transactions for `NFToken` trading are:
## Locating NFTokenOffer entries
Each unique NFT has up to two [directories](directorynode.html): one contains offers to buy the token and the other contains offers to sell the token. (These two directories are created as necessary and deleted if empty.) Marketplaces or other client applications can use these directories to find and display offers to trade `NFToken` objects to users or even automatically match them and accept them.
Each unique NFT has up to two [directories](directorynode.md): one contains offers to buy the token and the other contains offers to sell the token. (These two directories are created as necessary and deleted if empty.) Marketplaces or other client applications can use these directories to find and display offers to trade `NFToken` objects to users or even automatically match them and accept them.
### NFTokenOffer Reserve
`{{currentpage.name}}` entries each count as one item towards the owner reserve of the account placing the offer, as long as the entry is in the ledger. Accepting or canceling the offer frees up the reserve.
{% code-page-name /%} entries each count as one item towards the owner reserve of the account placing the offer, as long as the entry is in the ledger. Accepting or canceling the offer frees up the reserve.
### NFTokenOffer ID Format
@@ -83,8 +83,4 @@ The unique ID (`NFTokenOfferID`) of a `NFTokenOffer` object is the result of the
* The `AccountID` of the account placing the offer; and
* The `Sequence` (or `Ticket`) of the `NFTokenCreateOffer` transaction that created the `NFTokenOffer`.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

17
content/references/protocol/ledger-data/ledger-entry-types/nftokenpage.md
View File

@@ -7,12 +7,12 @@ labels:
---
# NFTokenPage
The `NFTokenPage` object represents a collection of [NFTs](non-fungible-tokens.html) owned by the same account. An account can have multiple `NFTokenPage` entries, which form a doubly linked list.
The `NFTokenPage` object represents a collection of [NFTs](../../../../concepts/tokens/nfts/index.md) owned by the same account. An account can have multiple `NFTokenPage` entries, which form a doubly linked list.
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -39,9 +39,9 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Field Name | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:------------|
@@ -81,9 +81,9 @@ To add an `NFToken`, find the `NFTokenPage` it should be in (using the same tech
Removing `NFToken` objects works like adding them. If the number of `NFToken` objects in the page goes below a certain threshold, the ledger combines the page with a previous or next page if possible.
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
Each `NFTokenPage` counts as one item towards its owner's [owner reserve](reserves.html#owner-reserves). Burning or trading away enough NFTs to remove the page frees up the reserve.
Each `NFTokenPage` counts as one item towards its owner's [owner reserve](../../../../concepts/accounts/reserves.md#owner-reserves). Burning or trading away enough NFTs to remove the page frees up the reserve.
Since each page can hold up to 32 entries, the _effective_ reserve cost per NFT can be as low as _R_/32 where _R_ is the incremental owner reserve for one item.
@@ -102,7 +102,4 @@ Currently, the reserve per item is 2 XRP. The table below shows how much the **t
These numbers are estimates; the actual numbers may vary.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

23
content/references/protocol/ledger-data/ledger-entry-types/offer.md
View File

@@ -8,12 +8,12 @@ labels:
# Offer
[[Source]](https://github.com/XRPLF/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L57 "Source")
The `Offer` ledger entry describes an [Offer](offers.html) to exchange currencies in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). (In finance, this is more traditionally known as an _order_.) An [OfferCreate transaction][] only creates an `Offer` entry in the ledger when the Offer cannot be fully executed immediately by consuming other Offers already in the ledger.
The `Offer` ledger entry describes an [Offer](../../../../concepts/tokens/decentralized-exchange/offers.md) to exchange currencies in the XRP Ledger's [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md). (In finance, this is more traditionally known as an _order_.) An [OfferCreate transaction][] only creates an `Offer` entry in the ledger when the Offer cannot be fully executed immediately by consuming other Offers already in the ledger.
An Offer can become unfunded through other activities in the network, while remaining in the ledger. When processing transactions, the network automatically removes any unfunded Offers that those transactions come across. (Otherwise, unfunded Offers remain, because _only_ transactions can change the ledger state.)
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -36,14 +36,14 @@ An Offer can become unfunded through other activities in the network, while rema
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Name | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:-----------------|:------------------|:----------|:------------|
| `Account` | String | AccountID | Yes | The address of the account that owns this Offer. |
| `BookDirectory` | String | Hash256 | Yes | The ID of the [Offer Directory](directorynode.html) that links to this Offer. |
| `BookDirectory` | String | Hash256 | Yes | The ID of the [Offer Directory](directorynode.md) that links to this Offer. |
| `BookNode` | String | UInt64 | Yes | A hint indicating which page of the offer directory links to this entry, in case the directory consists of multiple pages. |
| `Expiration` | Number | UInt32 | No | Indicates the time after which this Offer is considered unfunded. See [Specifying Time][] for details. |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x006F`, mapped to the string `Offer`, indicates that this is an Offer entry. |
@@ -58,15 +58,15 @@ In addition to the [common fields](ledger-entry-common-fields.html), `{{currentp
`Offer` entries can have the following flags combined into the `Flags` field:
| Flag Name | Hex Value | Decimal Value | Corresponding [OfferCreate Flag](offercreate.html#offercreate-flags) | Description |
| Flag Name | Hex Value | Decimal Value | Corresponding [OfferCreate Flag](../../transactions/types/offercreate.md#offercreate-flags) | Description |
|--------------|--------------|---------------|-------------|------------------------|
| `lsfPassive` | `0x00010000` | 65536 | `tfPassive` | The offer was placed as "passive". This has no effect after the offer is placed into the ledger. |
| `lsfSell` | `0x00020000` | 131072 | `tfSell` | The offer was placed as a "Sell" offer. This has no effect after the offer is placed in the ledger, because `tfSell` only matters if you get a better rate than you asked for, which can only happen when the offer is initially placed. |
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
`{{currentpage.name}}` entries count as one item towards the owner reserve of the account that placed the offer, as long as the entry is in the ledger. Canceling or consuming the offer frees up the reserve. The reserve is also freed up if the offer is removed because it was found unfunded.
{% code-page-name /%} entries count as one item towards the owner reserve of the account that placed the offer, as long as the entry is in the ledger. Canceling or consuming the offer frees up the reserve. The reserve is also freed up if the offer is removed because it was found unfunded.
## Offer ID Format
@@ -77,9 +77,6 @@ The ID of an `Offer` entry is the [SHA-512Half][] of the following values, conca
* The AccountID of the account placing the Offer
* The Sequence number of the [OfferCreate transaction][] that created the Offer.
If the OfferCreate transaction used a [Ticket](tickets.html), use the `TicketSequence` value instead.
If the OfferCreate transaction used a [Ticket](../../../../concepts/accounts/tickets.md), use the `TicketSequence` value instead.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

25
content/references/protocol/ledger-data/ledger-entry-types/paychannel.md
View File

@@ -10,10 +10,10 @@ labels:
_(Added by the [PayChan amendment][].)_
A `PayChannel` entry represents a [payment channel](payment-channels.html).
A `PayChannel` entry represents a [payment channel](../../../../concepts/payment-types/payment-channels.md).
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -37,20 +37,20 @@ A `PayChannel` entry represents a [payment channel](payment-channels.html).
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| 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. |
| `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.html). This is optionally set by the transaction that created the channel, and cannot be changed. |
| `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. |
| `DestinationNode` | String | UInt64 | No | A hint indicating which page of the destination's owner directory links to this entry, in case the directory consists of multiple pages. Omitted on payment channels created before enabling the [fixPayChanRecipientOwnerDir amendment][]. |
| `Expiration` | Number | UInt32 | No | The mutable expiration time for this payment channel, in [seconds since the Ripple Epoch][]. The channel is expired if this value is present and smaller than the previous ledger's [`close_time` field](ledger-header.html). See [Channel Expiration](#channel-expiration) for more details. |
| `Expiration` | Number | UInt32 | No | The mutable expiration time for this payment channel, in [seconds since the Ripple Epoch][]. The channel is expired if this value is present and smaller than the previous ledger's [`close_time` field](../ledger-header.md). See [Channel Expiration](#channel-expiration) for more details. |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0078`, mapped to the string `PayChannel`, indicates that this is a payment channel entry. |
| `OwnerNode` | String | UInt64 | Yes | A hint indicating which page of the source address's owner directory links to this entry, in case the directory consists of multiple pages. |
| `PreviousTxnID` | String | Hash256 | Yes | The identifying hash of the transaction that most recently modified this entry. |
@@ -61,7 +61,7 @@ In addition to the [common fields](ledger-entry-common-fields.html), `{{currentp
## Channel Expiration
The `Expiration` field of a payment channel is the mutable expiration time, in contrast to the immutable expiration time represented by the `CancelAfter` field. The expiration of a channel is always considered relative to the [`close_time` field](ledger-header.html) of the previous ledger. The `Expiration` field is omitted when a `PayChannel` entry is created. There are several ways the `Expiration` field of a `PayChannel` entry can be updated, which can be summarized as follows: a channel's source address can set the `Expiration` of the channel freely as long as the channel always remains open at least `SettleDelay` seconds after the first attempt to close it.
The `Expiration` field of a payment channel is the mutable expiration time, in contrast to the immutable expiration time represented by the `CancelAfter` field. The expiration of a channel is always considered relative to the [`close_time` field](../ledger-header.md) of the previous ledger. The `Expiration` field is omitted when a `PayChannel` entry is created. There are several ways the `Expiration` field of a `PayChannel` entry can be updated, which can be summarized as follows: a channel's source address can set the `Expiration` of the channel freely as long as the channel always remains open at least `SettleDelay` seconds after the first attempt to close it.
When a payment channel expires, at first it remains on the ledger, because only new transactions can modify ledger contents. Transaction processing automatically closes a payment channel when any transaction accesses it after the expiration. To close an expired channel and return the unspent XRP to the owner, some address must send a new PaymentChannelClaim or PaymentChannelFund transaction accessing the channel.
@@ -92,9 +92,9 @@ If any other address attempts to set an `Expiration` field, the transaction fail
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
`{{currentpage.name}}` entries count as one item towards the owner reserve of the account that created the payment channel, as long as the entry is in the ledger. Removing the channel frees up the reserve; this can only be done after the channel expires (including as a result of being explicitly closed).
{% code-page-name /%} entries count as one item towards the owner reserve of the account that created the payment channel, as long as the entry is in the ledger. Removing the channel frees up the reserve; this can only be done after the channel expires (including as a result of being explicitly closed).
## PayChannel ID Format
@@ -105,9 +105,6 @@ The ID of a `PayChannel` entry is the [SHA-512Half][] of the following values, c
* The AccountID of the source account
* The AccountID of the destination account
* The Sequence number of the [PaymentChannelCreate transaction][] that created the channel
If the PaymentChannelCreate transaction used a [Ticket](tickets.html), use the `TicketSequence` value instead.
If the PaymentChannelCreate transaction used a [Ticket](../../../../concepts/accounts/tickets.md), use the `TicketSequence` value instead.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

31
content/references/protocol/ledger-data/ledger-entry-types/ripplestate.md
View File

@@ -8,16 +8,16 @@ labels:
# RippleState
[[Source]](https://github.com/XRPLF/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L70 "Source")
A `RippleState` ledger entry represents a [trust line](trust-lines-and-issuing.html) between two accounts. Each account can change its own limit and other settings, but the balance is a single shared value. A trust line that is entirely in its default state is considered the same as a trust line that does not exist and is automatically deleted.
A `RippleState` ledger entry represents a [trust line](../../../../concepts/tokens/fungible-tokens/index.md) between two accounts. Each account can change its own limit and other settings, but the balance is a single shared value. A trust line that is entirely in its default state is considered the same as a trust line that does not exist and is automatically deleted.
## High vs. Low Account
There can only be one `RippleState` entry per currency for any given pair of accounts. Since no account is privileged in the XRP Ledger, a `RippleState` entry sorts account addresses numerically, to ensure a canonical form. Whichever address is numerically lower when [decoded](addresses.html#address-encoding) is deemed the "low account" and the other is the "high account". The net balance of the trust line is stored from the low account's perspective.
There can only be one `RippleState` entry per currency for any given pair of accounts. Since no account is privileged in the XRP Ledger, a `RippleState` entry sorts account addresses numerically, to ensure a canonical form. Whichever address is numerically lower when [decoded](../../../../concepts/accounts/addresses.md#address-encoding) is deemed the "low account" and the other is the "high account". The net balance of the trust line is stored from the low account's perspective.
The ["issuer"](trust-lines-and-issuing.html) for the balance in a trust line depends on whether the balance is positive or negative. If a `RippleState` entry shows a positive balance, the high account is the issuer. If the balance is negative, the low account is the issuer. Often, the issuer has its limit set to 0 and the other account has a positive limit, but this is not reliable because limits can change without affecting an existing balance.
The ["issuer"](../../../../concepts/tokens/fungible-tokens/index.md) for the balance in a trust line depends on whether the balance is positive or negative. If a `RippleState` entry shows a positive balance, the high account is the issuer. If the balance is negative, the low account is the issuer. Often, the issuer has its limit set to 0 and the other account has a positive limit, but this is not reliable because limits can change without affecting an existing balance.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -46,13 +46,13 @@ The ["issuer"](trust-lines-and-issuing.html) for the balance in a trust line dep
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Name | JSON Type | Internal Type | Required? | Description |
|:--------------------|:----------|:--------------|:----------|:------------|
| `Balance` | Object | Amount | Yes | The balance of the trust line, from the perspective of the low account. A negative balance indicates that the high account holds tokens issued by the low account. The issuer in this is always set to the neutral value [ACCOUNT_ONE](addresses.html#special-addresses). |
| `Balance` | Object | Amount | Yes | The balance of the trust line, from the perspective of the low account. A negative balance indicates that the high account holds tokens issued by the low account. The issuer in this is always set to the neutral value [ACCOUNT_ONE](../../../../concepts/accounts/addresses.md#special-addresses). |
| `Flags` | Number | UInt32 | Yes | A bit-map of boolean options enabled for this entry. |
| `HighLimit` | Object | Amount | Yes | 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. |
| `HighNode` | String | UInt64 | Yes | (Omitted in some historical ledgers) A hint indicating which page of the high account's owner directory links to this entry, in case the directory consists of multiple pages. |
@@ -70,24 +70,24 @@ In addition to the [common fields](ledger-entry-common-fields.html), `{{currentp
`RippleState` entries can have the following flags combined into the `Flags` field:
| Flag Name | Hex Value | Decimal Value | Corresponding [TrustSet Flag](trustset.html#trustset-flags) | Description |
| Flag Name | Hex Value | Decimal Value | Corresponding [TrustSet Flag](../../transactions/types/trustset.md#trustset-flags) | Description |
|-------------------|--------------|---------------|-----------------|---------|
| `lsfLowReserve` | `0x00010000` | 65536 | (None) | This entry [contributes to the low account's owner reserve](#ripplestate-reserve). |
| `lsfHighReserve` | `0x00020000` | 131072 | (None) | This entry [contributes to the high account's owner reserve](#ripplestate-reserve). |
| `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. |
| `lsfLowNoRipple` | `0x00100000` | 1048576 | `tfSetNoRipple` | The low account [has disabled rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) from this trust line. |
| `lsfHighNoRipple` | `0x00200000` | 2097152 | `tfSetNoRipple` | The high account [has disabled rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) from this trust line. |
| `lsfLowFreeze` | `0x00400000` | 4194304 | `tfSetFreeze` | The low account has frozen the trust line, preventing the high account from transferring the asset. |
| `lsfHighFreeze` | `0x00800000` | 8388608 | `tfSetFreeze` | The high account has frozen the trust line, preventing the low account from transferring the asset. |
The two accounts connected by the trust line can each change their own settings with a [TrustSet transaction][].
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
<a id="contributing-to-the-owner-reserve"></a>
A `RippleState` entry counts as one item towards the [owner reserve](reserves.html#owner-reserves) of _one or both_ of the accounts it connects. In typical cases, the holder of a token owes a reserve and the issuer of the token does not.
A `RippleState` entry counts as one item towards the [owner reserve](../../../../concepts/accounts/reserves.md#owner-reserves) of _one or both_ of the accounts it connects. In typical cases, the holder of a token owes a reserve and the issuer of the token does not.
Specifically, the entry counts towards an account's reserve if that account modifies a trust line to put it in a non-default state. The `lsfLowReserve` and `lsfHighReserve` flags indicate which account(s) are responsible for the owner reserve. The protocol automatically sets these flags when it modifies a trust line.
@@ -104,7 +104,7 @@ The values that count towards a trust line's non-default state are as follows:
The **`lsfLowAuth`** and **`lsfHighAuth`** flags do not count against the default state, because they cannot be disabled.
The default state of the two No Ripple flags depends on the state of the [`lsfDefaultRipple` flag](accountroot.html#accountroot-flags) in their corresponding AccountRoot entries. If Default Ripple is disabled (the default), then the default state of the `lsfNoRipple` flag is _enabled_ for all of an account's trust lines. If an account enables Default Ripple, then the `lsfNoRipple` flag is _disabled_ (rippling is enabled) for an account's trust lines by default.
The default state of the two No Ripple flags depends on the state of the [`lsfDefaultRipple` flag](accountroot.md#accountroot-flags) in their corresponding AccountRoot entries. If Default Ripple is disabled (the default), then the default state of the `lsfNoRipple` flag is _enabled_ for all of an account's trust lines. If an account enables Default Ripple, then the `lsfNoRipple` flag is _disabled_ (rippling is enabled) for an account's trust lines by default.
**Note:** Prior to the introduction of the Default Ripple flag in `rippled` version 0.27.3 (March 10, 2015), the default state for all trust lines was with both No Ripple flags disabled (rippling enabled).
@@ -120,7 +120,4 @@ The ID of a RippleState entry is the [SHA-512Half][] of the following values, co
* The AccountID of the high account
* The 160-bit currency code of the trust line(s)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

23
content/references/protocol/ledger-data/ledger-entry-types/signerlist.md
View File

@@ -13,7 +13,7 @@ _(Added by the [MultiSign amendment][].)_
A `SignerList` entry represents a list of parties that, as a group, are authorized to sign a transaction in place of an individual account. You can create, replace, or remove a signer list using a [SignerListSet transaction][].
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -48,9 +48,9 @@ A `SignerList` entry represents a list of parties that, as a group, are authoriz
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Name | JSON Type | Internal Type | Required? | Description |
|:--------------------|:----------|:--------------|:----------|:---------------------------|
@@ -59,7 +59,7 @@ In addition to the [common fields](ledger-entry-common-fields.html), `{{currentp
| `PreviousTxnID` | String | Hash256 | Yes | The identifying hash of the transaction that most recently modified this object. |
| `PreviousTxnLgrSeq` | Number | UInt32 | Yes | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. |
| `SignerEntries` | Array | Array | Yes | An array of Signer Entry objects representing the parties who are part of this signer list. |
| `SignerListID` | Number | UInt32 | Yes | An ID for this signer list. Currently always set to `0`. If a future [amendment](amendments.html) allows multiple signer lists for an account, this may change. |
| `SignerListID` | Number | UInt32 | Yes | An ID for this signer list. Currently always set to `0`. If a future [amendment](../../../../concepts/networks-and-servers/amendments.md) allows multiple signer lists for an account, this may change. |
| `SignerQuorum` | Number | UInt32 | Yes | A target number for signer weights. To produce a valid signature for the owner of this SignerList, the signers must provide valid signatures whose weights sum to this value or more. |
The `SignerEntries` may be any combination of funded and unfunded addresses that use either secp256k1 or ed25519 keys.
@@ -74,9 +74,9 @@ Each member of the `SignerEntries` field is an object that describes that signer
| `SignerWeight` | Number | UInt16 | The weight of a signature from this signer. A multi-signature is only valid if the sum weight of the signatures provided meets or exceeds the signer list's `SignerQuorum` value. |
| `WalletLocator` | String | Hash256 | _(Optional)_ Arbitrary hexadecimal data. This can be used to identify the signer or for other, related purposes. _(Added by the [ExpandedSignerList amendment][].)_ |
When processing a multi-signed transaction, the server looks up the `Account` values with respect to the ledger at the time of transaction execution. If the address _does not_ correspond to a funded [AccountRoot ledger entry](accountroot.html), then only the [master private key](cryptographic-keys.html) associated with that address can be used to produce a valid signature. If the account _does_ exist in the ledger, then it depends on the state of that account. If the account has a Regular Key configured, the Regular Key can be used. The account's master key can only be used if it is not disabled. A multi-signature cannot be used as part of another multi-signature.
When processing a multi-signed transaction, the server looks up the `Account` values with respect to the ledger at the time of transaction execution. If the address _does not_ correspond to a funded [AccountRoot ledger entry](accountroot.md), then only the [master private key](../../../../concepts/accounts/cryptographic-keys.md) associated with that address can be used to produce a valid signature. If the account _does_ exist in the ledger, then it depends on the state of that account. If the account has a Regular Key configured, the Regular Key can be used. The account's master key can only be used if it is not disabled. A multi-signature cannot be used as part of another multi-signature.
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
_(Added by the [MultiSignReserve amendment][].)_
@@ -84,14 +84,14 @@ SignerList entries can have the following value in the `Flags` field:
| Flag Name | Hex Value | Decimal Value | Description |
|:-------------------|:-------------|:--------------|:-------------------------|
| `lsfOneOwnerCount` | `0x00010000` | 65536 | If this flag is enabled, this SignerList counts as one item for purposes of the [owner reserve](reserves.html#owner-reserves). Otherwise, this list counts as N+2 items, where N is the number of signers it contains. This flag is automatically enabled if you add or update a signer list after the [MultiSignReserve amendment][] is enabled. |
| `lsfOneOwnerCount` | `0x00010000` | 65536 | If this flag is enabled, this SignerList counts as one item for purposes of the [owner reserve](../../../../concepts/accounts/reserves.md#owner-reserves). Otherwise, this list counts as N+2 items, where N is the number of signers it contains. This flag is automatically enabled if you add or update a signer list after the [MultiSignReserve amendment][] is enabled. |
## Signer Lists and Reserves
A signer list contributes to its owner's [reserve requirement](reserves.html). Removing the signer list frees up the reserve.
A signer list contributes to its owner's [reserve requirement](../../../../concepts/accounts/reserves.md). Removing the signer list frees up the reserve.
The [MultiSignReserve amendment][] (enabled 2019-04-17) made it so each signer list counts as one item, regardless of how many members it has. As a result, the owner reserve for any signer list added or updated after this time is {{target.owner_reserve}}.
The [MultiSignReserve amendment][] (enabled 2019-04-17) made it so each signer list counts as one item, regardless of how many members it has. As a result, the owner reserve for any signer list added or updated after this time is {% $env.PUBLIC_OWNER_RESERVE %}.
A signer list created before the [MultiSignReserve amendment][] itself counts as two items towards the owner reserve, and each member of the list counts as one. As a result, the total owner reserve associated with an old signer list is anywhere from 3 times to 10 times as much as a new signer list. To update a signer list to use the new, reduced reserve, update the signer list by sending a [SignerListSet transaction][].
@@ -104,7 +104,4 @@ The ID of a `SignerList` entry is the SHA-512Half of the following values, conca
* The AccountID of the owner of the signer list
* The `SignerListID` (currently always `0`)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

29
content/references/protocol/ledger-data/ledger-entry-types/ticket.md
View File

@@ -11,9 +11,9 @@ labels:
_(Added by the [TicketBatch amendment][].)_
A `Ticket` entry type represents a [Ticket](tickets.html), which tracks an account [sequence number][Sequence Number] that has been set aside for future use. You can create new tickets with a [TicketCreate transaction][].
A `Ticket` entry type represents a [Ticket](../../../../concepts/accounts/tickets.md), which tracks an account [sequence number][Sequence Number] that has been set aside for future use. You can create new tickets with a [TicketCreate transaction][].
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -27,31 +27,31 @@ A `Ticket` entry type represents a [Ticket](tickets.html), which tracks an accou
}
```
## {{currentpage.name}} Fields
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](ledger-entry-common-fields.html), `{{currentpage.name}}` entries have the following fields:
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Name | JSON Type | Internal Type | Required? | Description |
|:--------------------|:----------|:--------------|:----------|:---------------------------|
| `Account` | String | AccountID | Yes | The [account](accounts.html) that owns this Ticket. |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0054`, mapped to the string `Ticket`, indicates that this is a {{currentpage.name}} entry. |
| `Account` | String | AccountID | Yes | The [account](../../../../concepts/accounts/accounts.md) that owns this Ticket. |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0054`, mapped to the string `Ticket`, indicates that this is a {% $frontmatter.seo.title %} entry. |
| `OwnerNode` | String | UInt64 | Yes | A hint indicating which page of the owner directory links to this entry, in case the directory consists of multiple pages. |
| `PreviousTxnID` | String | Hash256 | Yes | The identifying hash of the [transaction](transactions.html) that most recently modified this entry. |
| `PreviousTxnID` | String | Hash256 | Yes | The identifying hash of the [transaction](../../../../concepts/transactions/index.md) 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. |
| `TicketSequence` | Number | UInt32 | Yes | The [Sequence Number][] this Ticket sets aside. |
## {{currentpage.name}} Reserve
## {% $frontmatter.seo.title %} Reserve
`{{currentpage.name}}` entries count as one item towards the owner reserve of the account that placed the created it, as long as the entry is in the ledger. Using the ticket frees up the reserve.
{% code-page-name /%} entries count as one item towards the owner reserve of the account that placed the created it, as long as the entry is in the ledger. Using the ticket frees up the reserve.
## {{currentpage.name}} Flags
## {% $frontmatter.seo.title %} Flags
There are no flags defined for `{{currentpage.name}}` entries.
There are no flags defined for {% code-page-name /%} entries.
## {{currentpage.name}} ID Format
## {% $frontmatter.seo.title %} ID Format
The ID of a Ticket object is the SHA-512Half of the following values, concatenated in order:
@@ -59,7 +59,4 @@ The ID of a Ticket object is the SHA-512Half of the following values, concatenat
* The AccountID of the owner of the Ticket
* The `TicketSequence` number of the Ticket
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

7
content/references/protocol/ledger-data/ledger-entry-types/xchainownedclaimid.md
View File

@@ -7,7 +7,7 @@ labels:
status: not_enabled
---
# XChainOwnedClaimID
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
[[Source]](https://github.com/seelabs/rippled/blob/xbridge/src/ripple/protocol/impl/LedgerFormats.cpp#L281-L293 "Source")
@@ -103,7 +103,4 @@ An `XChainCreateClaimID` transaction is used to create a new `XChainOwnedClaimID
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/ledger-data/ledger-entry-types/xchainownedcreateaccountclaimid.md
View File

@@ -7,7 +7,7 @@ labels:
status: not_enabled
---
# XChainOwnedCreateAccountClaimID
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
[[Source]](https://github.com/seelabs/rippled/blob/xbridge/src/ripple/protocol/impl/LedgerFormats.cpp#L296-L306 "Source")
@@ -86,8 +86,4 @@ The ledger object is destroyed when all the attestations have been received and
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

18
content/references/protocol/ledger-data/ledger-header.md
View File

@@ -9,7 +9,7 @@ labels:
# Ledger Header
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/ledger/ReadView.h#L71 "Source")
Every [ledger version](ledgers.html) has a unique header that describes the contents. You can look up a ledger's header information with the [ledger method][]. The contents of the ledger header are as follows:
Every [ledger version](../../../concepts/ledgers/index.md) has a unique header that describes the contents. You can look up a ledger's header information with the [ledger method][]. The contents of the ledger header are as follows:
| Field | JSON Type | [Internal Type][] | Description |
|:------------------------------|:----------|:------------------|:--------------|
@@ -17,7 +17,7 @@ Every [ledger version](ledgers.html) has a unique header that describes the cont
| `ledger_hash` | String | Hash256 | The [SHA-512Half][] of this ledger version. This serves as a unique identifier for this ledger and all its contents. |
| `account_hash` | String | Hash256 | The [SHA-512Half][] of this ledger's state tree information. |
| [`close_flags`](#close-flags) | Number | UInt8 | A bit-map of flags relating to the closing of this ledger. |
| `close_time` | Number | UInt32 | The [approximate time this ledger version closed](ledger-close-times.html), as the number of seconds since the Ripple Epoch of 2000-01-01 00:00:00 UTC. This value is rounded based on the `close_time_resolution`. |
| `close_time` | Number | UInt32 | The [approximate time this ledger version closed](../../../concepts/ledgers/ledger-close-times.md), as the number of seconds since the Ripple Epoch of 2000-01-01 00:00:00 UTC. This value is rounded based on the `close_time_resolution`. |
| `close_time_resolution` | Number | Uint8 | An integer in the range \[2,120\] indicating the maximum number of seconds by which the `close_time` could be rounded. |
| `closed` | Boolean | Boolean | If `true`, this ledger version is no longer accepting new transactions. (However, unless this ledger version is validated, it might be replaced by a different ledger version with a different set of transactions.) |
| `parent_hash` | String | Hash256 | The `ledger_hash` value of the previous ledger version that is the direct predecessor of this one. If there are different versions of the previous ledger index, this indicates from which one the ledger was derived. |
@@ -26,21 +26,17 @@ Every [ledger version](ledgers.html) has a unique header that describes the cont
## Ledger Index
{% include '_snippets/data_types/ledger_index.md' %}
<!--{#_ #}-->
{% partial file="/_snippets/data_types/ledger_index.md" /%}
## Close Flags
The ledger has only one flag defined for `closeFlags`: **`sLCF_NoConsensusTime`** (value `1`). If this flag is enabled, it means that validators had different [close times for the ledger](ledger-close-times.html), but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, official `close_time` value of the ledger is 1 second after that of the parent ledger.
The ledger has only one flag defined for `closeFlags`: **`sLCF_NoConsensusTime`** (value `1`). If this flag is enabled, it means that validators had different [close times for the ledger](../../../concepts/ledgers/ledger-close-times.md), but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, official `close_time` value of the ledger is 1 second after that of the parent ledger.
## See Also
For ledger basics, see [Ledgers](ledgers.html).
For ledger basics, see [Ledgers](../../../concepts/ledgers/index.md).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

49
content/references/protocol/transactions/common-fields.md
View File

@@ -7,28 +7,28 @@ labels:
---
# Transaction Common Fields
Every transaction has the same set of common fields, plus additional fields based on the [transaction type](transaction-types.html). Field names are case-sensitive. The common fields for all transactions are:
Every transaction has the same set of common fields, plus additional fields based on the [transaction type](types/index.md). Field names are case-sensitive. The common fields for all transactions are:
| Field | JSON Type | [Internal Type][] | Description |
|:---------------------|:-----------------|:------------------|:-----------------|
| `Account` | String | AccountID | _(Required)_ The unique address of the [account](accounts.html) that initiated the transaction. |
| `TransactionType` | String | UInt16 | _(Required)_ The type of transaction. Valid [transaction types](transaction-types.html) include: `Payment`, `OfferCreate`, `TrustSet`, and many others. |
| `Account` | String | AccountID | _(Required)_ The unique address of the [account](../../../concepts/accounts/accounts.md) that initiated the transaction. |
| `TransactionType` | String | UInt16 | _(Required)_ The type of transaction. Valid [transaction types](types/index.md) include: `Payment`, `OfferCreate`, `TrustSet`, and many others. |
| `Fee` | String | Amount | _(Required; [auto-fillable][])_ Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network. Some transaction types have different minimum requirements. See [Transaction Cost][] for details. |
| `Sequence` | Number | UInt32 | _(Required; [auto-fillable][])_ The [sequence number](basic-data-types.html#account-sequence) of the account sending the transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. The special case `0` means the transaction is using a [Ticket](tickets.html) instead _(Added by the [TicketBatch amendment][].)_. |
| `Sequence` | Number | UInt32 | _(Required; [auto-fillable][])_ The [sequence number](../data-types/basic-data-types.md#account-sequence) of the account sending the transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. The special case `0` means the transaction is using a [Ticket](../../../concepts/accounts/tickets.md) instead _(Added by the [TicketBatch amendment][].)_. |
| [`AccountTxnID`](#accounttxnid) | String | Hash256 | _(Optional)_ Hash value identifying another transaction. If provided, this transaction is only valid if the sending account's previously-sent transaction matches the provided hash. |
| [`Flags`](#flags-field) | Number | UInt32 | _(Optional)_ Set of bit-flags for this transaction. |
| `LastLedgerSequence` | Number | UInt32 | _(Optional; strongly recommended)_ Highest ledger index this transaction can appear in. Specifying this field places a strict upper limit on how long the transaction can wait to be validated or rejected. See [Reliable Transaction Submission](reliable-transaction-submission.html) for more details. |
| `LastLedgerSequence` | Number | UInt32 | _(Optional; strongly recommended)_ Highest ledger index this transaction can appear in. Specifying this field places a strict upper limit on how long the transaction can wait to be validated or rejected. See [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md) for more details. |
| [`Memos`](#memos-field) | Array of Objects | Array | _(Optional)_ Additional arbitrary information used to identify this transaction. |
| [`NetworkID`](#networkid-field) | Number | UInt32 | _(Network-specific)_ The network ID of the chain this transaction is intended for. **MUST BE OMITTED** for Mainnet and some test networks. **REQUIRED** on chains whose network ID is 1025 or higher. |
| [`Signers`](#signers-field) | Array | Array | _(Optional)_ Array of objects that represent a [multi-signature](multi-signing.html) which authorizes this transaction. |
| [`Signers`](#signers-field) | Array | Array | _(Optional)_ Array of objects that represent a [multi-signature](../../../concepts/accounts/multi-signing.md) which authorizes this transaction. |
| `SourceTag` | Number | UInt32 | _(Optional)_ Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's `SourceTag` as the refund payment's `DestinationTag`. |
| `SigningPubKey` | String | Blob | _(Automatically added when signing)_ Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the `Signers` field instead. |
| `TicketSequence` | Number | UInt32 | _(Optional)_ The sequence number of the [ticket](tickets.html) to use in place of a `Sequence` number. If this is provided, `Sequence` must be `0`. Cannot be used with `AccountTxnID`. |
| `TicketSequence` | Number | UInt32 | _(Optional)_ The sequence number of the [ticket](../../../concepts/accounts/tickets.md) to use in place of a `Sequence` number. If this is provided, `Sequence` must be `0`. Cannot be used with `AccountTxnID`. |
| `TxnSignature` | String | Blob | _(Automatically added when signing)_ The signature that verifies this transaction as originating from the account it says it is from. |
[auto-fillable]: #auto-fillable-fields
[Removed in: rippled 0.28.0][]: The `PreviousTxnID` field of transactions was replaced by the [`AccountTxnID`](#accounttxnid) field. This String / Hash256 field is present in some historical transactions. This is unrelated to the field also named `PreviousTxnID` in some [ledger objects](ledger-data-formats.html).
{% badge href="https://github.com/XRPLF/rippled/releases/tag/0.28.0" %}Removed in: rippled 0.28.0{% /badge %}: The `PreviousTxnID` field of transactions was replaced by the [`AccountTxnID`](#accounttxnid) field. This String / Hash256 field is present in some historical transactions. This is unrelated to the field also named `PreviousTxnID` in some [ledger objects](../ledger-data/index.md).
## AccountTxnID
@@ -37,17 +37,17 @@ Every transaction has the same set of common fields, plus additional fields base
The `AccountTxnID` field lets you chain your transactions together, so that a current transaction is not valid unless the previous transaction sent from the same account has a specific [transaction hash][identifying hash].
Unlike the `PreviousTxnID` field, which tracks the last transaction to _modify_ an account (regardless of sender), the `AccountTxnID` tracks the last transaction _sent by_ an account. To use `AccountTxnID`, you must first enable the [`asfAccountTxnID`](accountset.html#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. (`PreviousTxnID`, by comparison, is always tracked.)
Unlike the `PreviousTxnID` field, which tracks the last transaction to _modify_ an account (regardless of sender), the `AccountTxnID` tracks the last transaction _sent by_ an account. To use `AccountTxnID`, you must first enable the [`asfAccountTxnID`](types/accountset.md#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. (`PreviousTxnID`, by comparison, is always tracked.)
One situation in which this is useful is if you have a primary system for submitting transactions and a passive backup system. If the passive backup system becomes disconnected from the primary, but the primary is not fully dead, and they both begin operating at the same time, you could potentially have serious problems like some transactions sending twice and others not at all. Chaining your transactions together with `AccountTxnID` ensures that, even if both systems are active, only one of them can submit valid transactions at a time.
The `AccountTxnID` field cannot be used on transactions that use [Tickets](tickets.html). Transactions that use `AccountTxnID` cannot be placed in the [transaction queue](transaction-queue.html).
The `AccountTxnID` field cannot be used on transactions that use [Tickets](../../../concepts/accounts/tickets.md). Transactions that use `AccountTxnID` cannot be placed in the [transaction queue](../../../concepts/transactions/transaction-queue.md).
## Auto-fillable Fields
Some fields can be automatically filled in before a transaction is signed, either by a `rippled` server or by a [client library](client-libraries.html). Auto-filling values requires an active connection to the XRP Ledger to get the latest state, so it cannot be done offline. The details can vary by library, but auto-filling always provides suitable values for at least the following fields:
Some fields can be automatically filled in before a transaction is signed, either by a `rippled` server or by a [client library](../../client-libraries.md). Auto-filling values requires an active connection to the XRP Ledger to get the latest state, so it cannot be done offline. The details can vary by library, but auto-filling always provides suitable values for at least the following fields:
* `Fee` - Automatically fill in the [Transaction Cost][] based on the network.
@@ -57,7 +57,7 @@ Some fields can be automatically filled in before a transaction is signed, eithe
For a production system, we recommend _not_ leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.
The [`Paths` field](payment.html#paths) of the [Payment transaction][] type can also be automatically filled in.
The [`Paths` field](types/payment.md#paths) of the [Payment transaction][] type can also be automatically filled in.
## Flags Field
@@ -76,11 +76,11 @@ The only flag that applies globally to all transactions is as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:----------------------|:-----------|:--------------|:--------------------------|
| `tfFullyCanonicalSig` | `0x80000000` | 2147483648 | **DEPRECATED** No effect. (If the [RequireFullyCanonicalSig amendment][] is not enabled, this flag enforces a [fully-canonical signature](transaction-malleability.html#alternate-secp256k1-signatures).) |
| `tfFullyCanonicalSig` | `0x80000000` | 2147483648 | **DEPRECATED** No effect. (If the [RequireFullyCanonicalSig amendment][] is not enabled, this flag enforces a [fully-canonical signature](../../../concepts/transactions/finality-of-results/transaction-malleability.md#alternate-secp256k1-signatures).) |
When using the [sign method][] (or [submit method][] in "sign-and-submit" mode), `rippled` adds a `Flags` field with `tfFullyCanonicalSig` enabled unless the `Flags` field is already present. The `tfFullyCanonicalSig` flag is not automatically enabled if `Flags` is explicitly specified. The flag is not automatically enabled when using the [sign_for method][] to add a signature to a multi-signed transaction.
**Note:** The `tfFullyCanonicalSig` flag was used from 2014 until 2020 to protect against [transaction malleability](transaction-malleability.html) while maintaining compatibility with legacy signing software. The [RequireFullyCanonicalSig amendment][] ended compatibility with such legacy software and made the protections the default for all transactions. If you are using a [parallel network](parallel-networks.html) that does not have RequireFullyCanonicalSig enabled, you should always enable the `tfFullyCanonicalSig` flag to protect against transaction malleability.
**Note:** The `tfFullyCanonicalSig` flag was used from 2014 until 2020 to protect against [transaction malleability](../../../concepts/transactions/finality-of-results/transaction-malleability.md) while maintaining compatibility with legacy signing software. The [RequireFullyCanonicalSig amendment][] ended compatibility with such legacy software and made the protections the default for all transactions. If you are using a [parallel network](../../../concepts/networks-and-servers/parallel-networks.md) that does not have RequireFullyCanonicalSig enabled, you should always enable the `tfFullyCanonicalSig` flag to protect against transaction malleability.
### Flag Ranges
@@ -89,10 +89,10 @@ A transaction's `Flags` field can contain flags that apply at different levels o
| Range Name | Bit Mask | Description |
|:-----------------|:-------------|:-------------------------------------------|
| Universal Flags | `0xff000000` | Flags that apply equally to all transaction types. |
| Type-based Flags | `0x00ff0000` | Flags with different meanings depending on the [transaction type](transaction-types.html) that uses them. |
| Type-based Flags | `0x00ff0000` | Flags with different meanings depending on the [transaction type](types/index.md) that uses them. |
| Reserved Flags | `0x0000ffff` | Flags that are not currently defined. A transaction is only valid if these flags are disabled. |
**Note:** The [AccountSet transaction][] type has [its own non-bitwise flags](accountset.html#accountset-flags), which serve a similar purpose to type-based flags. [Ledger objects](ledger-object-types.html) also have a `Flags` field with different bitwise flag definitions.
**Note:** The [AccountSet transaction][] type has [its own non-bitwise flags](types/accountset.md#accountset-flags), which serve a similar purpose to type-based flags. [Ledger objects](../ledger-data/ledger-entry-types/index.md) also have a `Flags` field with different bitwise flag definitions.
## Memos Field
@@ -129,9 +129,9 @@ Example of a transaction with a Memos field:
```
## NetworkID Field
[New in: rippled 1.11.0][]
{% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %}
The `NetworkID` field is a protection against "cross-chain" transaction replay attacks, preventing the same transaction from being copied over and executing on a [parallel network](parallel-networks.html) that it wasn't intended for. For compatibility with existing chains, the `NetworkID` field must be omitted on any network with a Network ID of 1024 or less, but must be included on any network with a Network ID of 1025 or greater. The following table shows the status and values for various known networks:
The `NetworkID` field is a protection against "cross-chain" transaction replay attacks, preventing the same transaction from being copied over and executing on a [parallel network](../../../concepts/networks-and-servers/parallel-networks.md) that it wasn't intended for. For compatibility with existing chains, the `NetworkID` field must be omitted on any network with a Network ID of 1024 or less, but must be included on any network with a Network ID of 1025 or greater. The following table shows the status and values for various known networks:
| Network | ID | `NetworkID` Field |
|---------------|----|-------------------|
@@ -146,7 +146,7 @@ The `NetworkID` field is a protection against "cross-chain" transaction replay a
Transaction replay attacks are theoretically possible, but require specific conditions on the second network. All of the following must be true:
- The transaction's sender is a funded account on the second network.
- The sender's `Sequence` number on the second network matches the transaction's `Sequence`, or the transaction uses a [Ticket](tickets.html) that's available on the second network.
- The sender's `Sequence` number on the second network matches the transaction's `Sequence`, or the transaction uses a [Ticket](../../../concepts/accounts/tickets.md) that's available on the second network.
- Either the transaction does not have a `LastLedgerSequence` field, or it specifies a value that is higher than the current ledger index on the second ledger.
- Mainnet generally has a higher ledger index than test networks or sidechains, so it is easier to replay Mainnet transactions on a sidechain or test network than the other way around, when transactions use `LastLedgerSequence` as intended.
- Either the networks both have IDs of 1024 or less, both networks use the same ID, or the second network does not require the `NetworkID` field.
@@ -154,7 +154,7 @@ Transaction replay attacks are theoretically possible, but require specific cond
## Signers Field
The `Signers` field contains a [multi-signature](multi-signing.html), which has signatures from up to 32 key pairs, that together should authorize the transaction. The `Signers` list is an array of objects, each with one field, `Signer`. The `Signer` field has the following nested fields:
The `Signers` field contains a [multi-signature](../../../concepts/accounts/multi-signing.md), which has signatures from up to 32 key pairs, that together should authorize the transaction. The `Signers` list is an array of objects, each with one field, `Signer`. The `Signer` field has the following nested fields:
| Field | Type | [Internal Type][] | Description |
|:----------------|:-------|:------------------|:--------------------------------|
@@ -162,13 +162,8 @@ The `Signers` field contains a [multi-signature](multi-signing.html), which has
| `TxnSignature` | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. |
| `SigningPubKey` | String | Blob | The public key used to create this signature. |
The `SigningPubKey` must be a key that is associated with the `Account` address. If the referenced `Account` is a funded account in the ledger, then the `SigningPubKey` can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the [`lsfDisableMaster`](accountroot.html#accountroot-flags) flag is enabled. If the referenced `Account` address is not a funded account in the ledger, then the `SigningPubKey` must be the master key associated with that address.
The `SigningPubKey` must be a key that is associated with the `Account` address. If the referenced `Account` is a funded account in the ledger, then the `SigningPubKey` can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the [`lsfDisableMaster`](../ledger-data/ledger-entry-types/accountroot.md#accountroot-flags) flag is enabled. If the referenced `Account` address is not a funded account in the ledger, then the `SigningPubKey` must be the master key associated with that address.
Because signature verification is a compute-intensive task, multi-signed transactions cost additional XRP to relay to the network. Each signature included in the multi-signature increases the [transaction cost][] required for the transaction. For example, if the current minimum transaction cost to relay a transaction to the network is `10000` drops, then a multi-signed transaction with 3 entries in the `Signers` array would need a `Fee` value of at least `40000` drops to relay.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

12
content/references/protocol/transactions/index.md
View File

@@ -2,14 +2,14 @@
html: transaction-formats.html
parent: protocol-reference.html
blurb: Definitions for all the protocol's transaction types and their results.
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Transaction Reference
A _Transaction_ is the only way to cause changes in the XRP Ledger. Transactions' outcomes are only [final](finality-of-results.html) if signed, submitted, and accepted into a validated ledger version following the [consensus process](consensus.html). Some ledger rules also generate _[pseudo-transactions](pseudo-transaction-types.html)_, which aren't signed or submitted, but still must be accepted by consensus. Transactions that fail are also included in ledgers because they modify balances of XRP to pay for the anti-spam [transaction cost][].
A _Transaction_ is the only way to cause changes in the XRP Ledger. Transactions' outcomes are only [final](../../../concepts/transactions/finality-of-results/index.md) if signed, submitted, and accepted into a validated ledger version following the [consensus process](../../../concepts/consensus-protocol/index.md). Some ledger rules also generate _[pseudo-transactions](pseudo-transaction-types/pseudo-transaction-types.md)_, which aren't signed or submitted, but still must be accepted by consensus. Transactions that fail are also included in ledgers because they modify balances of XRP to pay for the anti-spam [transaction cost][].
{% raw-partial file="/_snippets/common-links.md" /%}
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% child-pages /%}

33
content/references/protocol/transactions/metadata.md
View File

@@ -13,19 +13,17 @@ Transaction metadata is a section of data that gets added to a transaction after
Some fields that may appear in transaction metadata include:
{% include '_snippets/tx-metadata-field-table.md' %} <!--_ -->
{% partial file="/_snippets/tx-metadata-field-table.md" /%}
## Example Metadata
The following JSON object shows the metadata for [a complex cross-currency payment](https://livenet.xrpl.org/transactions/8C55AFC2A2AA42B5CE624AEECDB3ACFDD1E5379D4E5BF74A8460C5E97EF8706B):
```json
{% include '_api-examples/metadata/cross-currency-payment.json' %}
```
{% code-snippet file="/_api-examples/metadata/cross-currency-payment.json" language="json" /%}
## AffectedNodes
The `AffectedNodes` array contains a complete list of the [ledger entries](ledger-object-types.html) that this transaction modified in some way. Each item in this array is an object with one top-level field indicating what happened:
The `AffectedNodes` array contains a complete list of the [ledger entries](../ledger-data/ledger-entry-types/index.md) that this transaction modified in some way. Each item in this array is an object with one top-level field indicating what happened:
- `CreatedNode` indicates that the transaction created a new ledger entry.
- `DeletedNode` indicates that the transaction removed a ledger entry
@@ -39,8 +37,8 @@ A `CreatedNode` object contains the following fields:
| Field | Value | Description |
|:------------------|:------------------|:-------------------------------------|
| `LedgerEntryType` | String | The [type of ledger entry](ledger-object-types.html) that was created. |
| `LedgerIndex` | String - [Hash][] | The [ID of this ledger entry](ledger-object-ids.html) in the ledger's [state tree](ledgers.html). **Note:** This is **not the same** as a [ledger index](basic-data-types.html#ledger-index), even though the field name is very similar. |
| `LedgerEntryType` | String | The [type of ledger entry](../ledger-data/ledger-entry-types/index.md) that was created. |
| `LedgerIndex` | String - [Hash][] | The [ID of this ledger entry](../ledger-data/common-fields.md) in the ledger's [state tree](../../../concepts/ledgers/index.md). **Note:** This is **not the same** as a [ledger index](../data-types/basic-data-types.md#ledger-index), even though the field name is very similar. |
| `NewFields` | Object | The content fields of the newly-created ledger entry. Which fields are present depends on what type of ledger entry was created. |
### DeletedNode Fields
@@ -49,8 +47,8 @@ A `DeletedNode` object contains the following fields:
| Field | Value | Description |
|:------------------|:------------------|:-------------------------------------|
| `LedgerEntryType` | String | The [type of ledger entry](ledger-object-types.html) that was deleted. |
| `LedgerIndex` | String - [Hash][] | The [ID of this ledger entry](ledger-object-ids.html) in the ledger's [state tree](ledgers.html). **Note:** This is **not the same** as a [ledger index](basic-data-types.html#ledger-index), even though the field name is very similar. |
| `LedgerEntryType` | String | The [type of ledger entry](../ledger-data/ledger-entry-types/index.md) that was deleted. |
| `LedgerIndex` | String - [Hash][] | The [ID of this ledger entry](../ledger-data/common-fields.md) in the ledger's [state tree](../../../concepts/ledgers/index.md). **Note:** This is **not the same** as a [ledger index](../data-types/basic-data-types.md#ledger-index), even though the field name is very similar. |
| `FinalFields` | Object | The content fields of the ledger entry immediately before it was deleted. Which fields are present depends on what type of ledger entry was created. |
### ModifiedNode Fields
@@ -59,8 +57,8 @@ A `ModifiedNode` object contains the following fields:
| Field | Value | Description |
|:--------------------|:--------------------------|:---------------------------|
| `LedgerEntryType` | String | The [type of ledger entry](ledger-object-types.html) that was modified. |
| `LedgerIndex` | String - [Hash][] | The [ID of this ledger entry](ledger-object-ids.html) in the ledger's [state tree](ledgers.html). **Note:** This is **not the same** as a [ledger index](basic-data-types.html#ledger-index), even though the field name is very similar. |
| `LedgerEntryType` | String | The [type of ledger entry](../ledger-data/ledger-entry-types/index.md) that was modified. |
| `LedgerIndex` | String - [Hash][] | The [ID of this ledger entry](../ledger-data/common-fields.md) in the ledger's [state tree](../../../concepts/ledgers/index.md). **Note:** This is **not the same** as a [ledger index](../data-types/basic-data-types.md#ledger-index), even though the field name is very similar. |
| `FinalFields` | Object | The content fields of the ledger entry after applying any changes from this transaction. Which fields are present depends on what type of ledger entry was created. This omits the `PreviousTxnID` and `PreviousTxnLgrSeq` fields, even though most types of ledger entries have them. |
| `PreviousFields` | Object | The previous values for all fields of the object that were changed as a result of this transaction. If the transaction _only added_ fields to the object, this field is an empty object. |
| `PreviousTxnID` | String - [Hash][] | _(May be omitted)_ The [identifying hash][] of the previous transaction to modify this ledger entry. Omitted for ledger entry types that do not have a `PreviousTxnID` field. |
@@ -74,13 +72,13 @@ Transactions (`tx` and `account_tx`) involving NFTs can contain the following fi
| Field | Value | Description |
|:--------------------|:--------------------------|:---------------------------|
| `nftoken_id` | String | Shows the `NFTokenID` for the `NFToken` that changed on the ledger as a result of the transaction. Only present if the transaction is `NFTokenMint` or `NFTokenAcceptOffer`. See [NFTokenID](nftoken.html#nftokenid). |
| `nftoken_id` | String | Shows the `NFTokenID` for the `NFToken` that changed on the ledger as a result of the transaction. Only present if the transaction is `NFTokenMint` or `NFTokenAcceptOffer`. See [NFTokenID](../data-types/nftoken.md#nftokenid). |
| `nftoken_ids` | Array | Shows all the `NFTokenIDs` for the `NFTokens` that changed on the ledger as a result of the transaction. Only present if the transaction is `NFTokenCancelOffer`. |
| `offer_id` | String | Shows the `OfferID`of a new `NFTokenOffer` in a response from a `NFTokenCreateOffer` transaction. |
## delivered_amount
The `Amount` of a [Payment transaction][] indicates the amount to deliver to the `Destination`, so if the transaction was successful, then the destination received that much -- **except if the transaction was a [partial payment](partial-payments.html)**. (In that case, any positive amount up to `Amount` might have arrived.) Rather than choosing whether or not to trust the `Amount` field, you should use the `delivered_amount` field of the metadata to see how much actually reached its destination.
The `Amount` of a [Payment transaction][] indicates the amount to deliver to the `Destination`, so if the transaction was successful, then the destination received that much -- **except if the transaction was a [partial payment](../../../concepts/payment-types/partial-payments.md)**. (In that case, any positive amount up to `Amount` might have arrived.) Rather than choosing whether or not to trust the `Amount` field, you should use the `delivered_amount` field of the metadata to see how much actually reached its destination.
The `rippled` server provides a `delivered_amount` field in JSON transaction metadata for all successful Payment transactions. This field is formatted like a normal currency amount. However, the delivered amount is not available for transactions that meet both of the following criteria:
@@ -89,14 +87,11 @@ The `rippled` server provides a `delivered_amount` field in JSON transaction met
If both conditions are true, then `delivered_amount` contains the string value `unavailable` instead of an actual amount. If this happens, you can only figure out the actual delivered amount by reading the `AffectedNodes` in the transaction's metadata.
**Note:** The `delivered_amount` field is generated on-demand for the request, and is not included in the binary format for transaction metadata, nor is it used when calculating the [hash](basic-data-types.html#hashes) of the transaction metadata. In contrast, the `DeliveredAmount` field _is_ included in the binary format for partial payment transactions after 2014-01-20.
**Note:** The `delivered_amount` field is generated on-demand for the request, and is not included in the binary format for transaction metadata, nor is it used when calculating the [hash](../data-types/basic-data-types.md#hashes) of the transaction metadata. In contrast, the `DeliveredAmount` field _is_ included in the binary format for partial payment transactions after 2014-01-20.
See also: [Partial Payments](partial-payments.html)
See also: [Partial Payments](../../../concepts/payment-types/partial-payments.md)
<!--{# Spell-check can ignore these field names used in headings #}-->
<!-- SPELLING_IGNORE: affectednodes, creatednode, deletednode, modifiednode, delivered_amount -->
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

11
content/references/protocol/transactions/pseudo-transaction-types/enableamendment.md
View File

@@ -24,7 +24,7 @@ A server only enables amendments when these conditions are met:
-->
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -39,12 +39,12 @@ A server only enables amendments when these conditions are met:
```
{% include '_snippets/pseudo-tx-fields-intro.md' %}
{% partial file="/_snippets/pseudo-tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:----------|:------------------|:--------------------------|
| `Amendment` | String | Hash256 | A unique identifier for the amendment. This is not intended to be a human-readable name. See [Amendments](amendments.html) for a list of known amendments. |
| `Amendment` | String | Hash256 | A unique identifier for the amendment. This is not intended to be a human-readable name. See [Amendments](../../../../concepts/networks-and-servers/amendments.md) for a list of known amendments. |
| `LedgerSequence` | Number | UInt32 | The [ledger index][] where this pseudo-transaction appears. This distinguishes the pseudo-transaction from other occurrences of the same change. |
## EnableAmendment Flags
@@ -58,7 +58,4 @@ A `Flags` value of `0` (no flags) or an omitted `Flags` field indicates that the
| `tfGotMajority` | `0x00010000` | 65536 | Support for this amendment increased to at least 80% of trusted validators starting with this ledger version. |
| `tfLostMajority` | `0x00020000` | 131072 | Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

15
content/references/protocol/transactions/pseudo-transaction-types/pseudo-transaction-types.md
View File

@@ -2,13 +2,14 @@
html: pseudo-transaction-types.html
parent: transaction-formats.html
blurb: Formats of pseudo-transactions that validators sometimes apply to the XRP Ledger.
template: pagetype-category.html.jinja
metadata:
indexPage: true
labels:
- Blockchain
---
# Pseudo-Transactions
Pseudo-transactions are never submitted by users, nor [propagated through the network](peer-protocol.html). Instead, a server may choose to inject pseudo-transactions in a proposed ledger directly according to specific protocol rules. If enough servers propose the exact same pseudo-transaction, the [consensus process](consensus.html) approves it, and the pseudo-transaction is included in that ledger's transaction data.
Pseudo-transactions are never submitted by users, nor [propagated through the network](../../../../concepts/networks-and-servers/peer-protocol.md). Instead, a server may choose to inject pseudo-transactions in a proposed ledger directly according to specific protocol rules. If enough servers propose the exact same pseudo-transaction, the [consensus process](../../../../concepts/consensus-protocol/index.md) approves it, and the pseudo-transaction is included in that ledger's transaction data.
## Special Values for Common Fields
@@ -16,7 +17,7 @@ Some of the required [common fields][] for normal transactions do not make sense
| Field | JSON Type | [Internal Type][] | Value |
|:----------------|:----------|:------------------|:---------------------------|
| `Account` | String | AccountID | [ACCOUNT_ZERO](addresses.html#special-addresses) |
| `Account` | String | AccountID | [ACCOUNT_ZERO](../../../../concepts/accounts/addresses.md#special-addresses) |
| `Fee` | String | Amount | `0` |
| `Sequence` | Number | UInt32 | `0` |
| `SigningPubKey` | String | Blob | `""` (Empty string) |
@@ -32,7 +33,7 @@ Pseudo-transactions use the following common fields as normal:
| `TransactionType` | String | UInt16 | _(Required)_ The type of transaction. |
| `Flags` | Number | UInt32 | _(Optional)_ A set of bit-flags for this transaction. The meaning of specific flags varies based on the transaction type. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}
{% child-pages /%}

17
content/references/protocol/transactions/pseudo-transaction-types/setfee.md
View File

@@ -7,11 +7,11 @@ labels:
---
# SetFee
A `SetFee` [pseudo-transaction](pseudo-transaction-types.html) marks a change in [transaction cost](transaction-cost.html) or [reserve requirements](reserves.html) as a result of [Fee Voting](fee-voting.html).
A `SetFee` [pseudo-transaction](pseudo-transaction-types.md) marks a change in [transaction cost](../../../../concepts/transactions/transaction-cost.md) or [reserve requirements](../../../../concepts/accounts/reserves.md) as a result of [Fee Voting](../../../../concepts/consensus-protocol/fee-voting.md).
**Note:** You cannot send a pseudo-transaction, but you may find one when processing ledgers.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -30,12 +30,12 @@ A `SetFee` [pseudo-transaction](pseudo-transaction-types.html) marks a change in
}
```
{% include '_snippets/pseudo-tx-fields-intro.md' %}
{% partial file="/_snippets/pseudo-tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:--------------------|:-----------------|:------------------|:----------------|
| `BaseFee` | String | UInt64 | The charge, in drops of XRP, for the reference transaction, as hex. (This is the [transaction cost](transaction-cost.html) before scaling for load.) |
| `BaseFee` | String | UInt64 | The charge, in drops of XRP, for the reference transaction, as hex. (This is the [transaction cost](../../../../concepts/transactions/transaction-cost.md) before scaling for load.) |
| `ReferenceFeeUnits` | Unsigned Integer | UInt32 | The cost, in fee units, of the reference transaction |
| `ReserveBase` | Unsigned Integer | UInt32 | The base reserve, in drops |
| `ReserveIncrement` | Unsigned Integer | UInt32 | The incremental reserve, in drops |
@@ -46,15 +46,12 @@ If the _[XRPFees amendment][]_ is enabled, `SetFee` pseudo-transactions use thes
| Field | JSON Type | [Internal Type][] | Description |
|:------------------------|:----------|:------------------|:----------------|
| `BaseFeeDrops` | String | Amount | The charge, in drops of XRP, for the reference transaction. (This is the [transaction cost](transaction-cost.html) before scaling for load.) |
| `BaseFeeDrops` | String | Amount | The charge, in drops of XRP, for the reference transaction. (This is the [transaction cost](../../../../concepts/transactions/transaction-cost.md) before scaling for load.) |
| `ReserveBaseDrops` | String | Amount | The base reserve, in drops |
| `ReserveIncrementDrops` | String | Amount | The incremental reserve, in drops |
| `LedgerSequence` | Number | UInt32 | _(Omitted for some historical `SetFee` pseudo-transactions)_ The index of the ledger version where this pseudo-transaction appears. This distinguishes the pseudo-transaction from other occurrences of the same change. |
{% include '_snippets/setfee_uniqueness_note.md' %}
{% partial file="/_snippets/setfee_uniqueness_note.md" /%}
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

12
content/references/protocol/transactions/pseudo-transaction-types/unlmodify.md
View File

@@ -9,11 +9,11 @@ labels:
_(Added by the [NegativeUNL amendment][].)_
A `UNLModify` [pseudo-transaction](pseudo-transaction-types.html) marks a change to the [Negative UNL](negative-unl.html), indicating that a trusted validator has gone offline or come back online.
A `UNLModify` [pseudo-transaction](pseudo-transaction-types.md) marks a change to the [Negative UNL](../../../../concepts/consensus-protocol/negative-unl.md), indicating that a trusted validator has gone offline or come back online.
**Note:** You cannot send a pseudo-transaction, but you may find one when processing ledgers.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -28,7 +28,7 @@ A `UNLModify` [pseudo-transaction](pseudo-transaction-types.html) marks a change
}
```
{% include '_snippets/pseudo-tx-fields-intro.md' %}
{% partial file="/_snippets/pseudo-tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Name | JSON Type | [Internal Type][] | Description |
@@ -38,8 +38,4 @@ A `UNLModify` [pseudo-transaction](pseudo-transaction-types.html) marks a change
| `UNLModifyDisabling` | Number | UInt8 | If `1`, this change represents adding a validator to the Negative UNL. If `0`, this change represents removing a validator from the Negative UNL. (No other values are allowed.) |
| `UNLModifyValidator` | String | Blob | The validator to add or remove, as identified by its master public key. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

63
content/references/protocol/transactions/transaction-results/tec-codes.md
View File

@@ -7,69 +7,66 @@ labels:
---
# tec Codes
These codes indicate that the transaction failed, but it was applied to a ledger to apply the [transaction cost](transaction-cost.html). They have numerical values in the range 100 to 199. It is recommended to use the text code, not the numeric value.
These codes indicate that the transaction failed, but it was applied to a ledger to apply the [transaction cost](../../../../concepts/transactions/transaction-cost.md). They have numerical values in the range 100 to 199. It is recommended to use the text code, not the numeric value.
Transactions with `tec` codes destroy the XRP paid as a [transaction cost](transaction-cost.html), and consume a [sequence number](basic-data-types.html#account-sequence). For the most part, the transactions take no other action, but there are some exceptions. For example, a transaction that results in `tecOVERSIZE` still cleans up some [unfunded offers](offers.html#lifecycle-of-an-offer). Always look at the [transaction metadata](transaction-metadata.html) to see precisely what a transaction did.
Transactions with `tec` codes destroy the XRP paid as a [transaction cost](../../../../concepts/transactions/transaction-cost.md), and consume a [sequence number](../../data-types/basic-data-types.md#account-sequence). For the most part, the transactions take no other action, but there are some exceptions. For example, a transaction that results in `tecOVERSIZE` still cleans up some [unfunded offers](../../../../concepts/tokens/decentralized-exchange/offers.md#lifecycle-of-an-offer). Always look at the [transaction metadata](../metadata.md) to see precisely what a transaction did.
**Caution:** A transaction that provisionally failed with a `tec` code may still succeed or fail with a different code after being reapplied. The result is final when it appears in a validated ledger version. For more information, see [Finality of Results](finality-of-results.html) and [Reliable Transaction Submission](reliable-transaction-submission.html).
**Caution:** A transaction that provisionally failed with a `tec` code may still succeed or fail with a different code after being reapplied. The result is final when it appears in a validated ledger version. For more information, see [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) and [Reliable Transaction Submission](../../../../concepts/transactions/reliable-transaction-submission.md).
| Code | Value | Explanation |
|:---------------------------|:------|:----------------------------------------|
| `tecAMM_ACCOUNT` | 168 | The transaction failed because the operation is not allowed on Automated Market Maker (AMM) accounts. _(Requires the [AMM amendment][] :not_enabled:)_ |
| `tecAMM_UNFUNDED` | 162 | The [AMMCreate transaction][] failed because the sender does not have enough of the specified assets to fund it. _(Requires the [AMM amendment][] :not_enabled:)_ |
| `tecAMM_BALANCE` | 163 | The [AMMDeposit][] or [AMMWithdraw][] transaction failed because either the AMM or the user does not hold enough of one of the specified assets. (For example, you tried to withdraw more than the AMM holds.) _(Requires the [AMM amendment][] :not_enabled:)_ |
| `tecAMM_EMPTY` | 166 | The AMM-related transaction failed because the AMM has no assets in its pool. In this state, you can only delete the AMM or fund it with a new deposit. _(Requires the [AMM amendment][] :not_enabled:)_ |
| `tecAMM_FAILED` | 164 | The AMM-related transaction failed. For [AMMDeposit][] or [AMMWithdraw][] this could be because the sender does not have enough of the specified assets, or the transaction requested an effective price that isn't possible with the available amounts. For [AMMBid][] this could be because the account does not have enough to win the bid or needs more than their specified maximum bid. For [AMMVote][], this could be because there are already too many votes from other accounts that hold more of this AMM's LP Tokens. _(Requires the [AMM amendment][] :not_enabled:)_ |
| `tecAMM_INVALID_TOKENS` | 165 | The AMM-related transaction failed due to insufficient LP Tokens or problems with rounding; for example, depositing a very small amount of assets could fail if the amount of LP Tokens to be returned rounds down to zero. _(Requires the [AMM amendment][] :not_enabled:)_ |
| `tecAMM_NOT_EMPTY` | 167 | The transaction was meant to operate on an AMM with empty asset pools, but the specified AMM currently holds assets. _(Requires the [AMM amendment][] :not_enabled:)_ |
| `tecCANT_ACCEPT_OWN_NFTOKEN_OFFER` | 157 | The transaction tried to accept an offer that was placed by the same account to buy or sell a [non-fungible token](non-fungible-tokens.html). _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecAMM_ACCOUNT` | 168 | The transaction failed because the operation is not allowed on Automated Market Maker (AMM) accounts. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_UNFUNDED` | 162 | The [AMMCreate transaction][] failed because the sender does not have enough of the specified assets to fund it. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_BALANCE` | 163 | The [AMMDeposit][] or [AMMWithdraw][] transaction failed because either the AMM or the user does not hold enough of one of the specified assets. (For example, you tried to withdraw more than the AMM holds.) _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_EMPTY` | 166 | The AMM-related transaction failed because the AMM has no assets in its pool. In this state, you can only delete the AMM or fund it with a new deposit. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_FAILED` | 164 | The AMM-related transaction failed. For [AMMDeposit][] or [AMMWithdraw][] this could be because the sender does not have enough of the specified assets, or the transaction requested an effective price that isn't possible with the available amounts. For [AMMBid][] this could be because the account does not have enough to win the bid or needs more than their specified maximum bid. For [AMMVote][], this could be because there are already too many votes from other accounts that hold more of this AMM's LP Tokens. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_INVALID_TOKENS` | 165 | The AMM-related transaction failed due to insufficient LP Tokens or problems with rounding; for example, depositing a very small amount of assets could fail if the amount of LP Tokens to be returned rounds down to zero. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_NOT_EMPTY` | 167 | The transaction was meant to operate on an AMM with empty asset pools, but the specified AMM currently holds assets. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecCANT_ACCEPT_OWN_NFTOKEN_OFFER` | 157 | The transaction tried to accept an offer that was placed by the same account to buy or sell a [non-fungible token](../../../../concepts/tokens/nfts/index.md). _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecCLAIM` | 100 | Unspecified failure, with transaction cost destroyed. |
| `tecCRYPTOCONDITION_ERROR` | 146 | This [EscrowCreate][] or [EscrowFinish][] transaction contained a malformed or mismatched crypto-condition. |
| `tecDIR_FULL` | 121 | The transaction tried to add an object (such as a trust line, Check, Escrow, or Payment Channel) to an account's owner directory, but that account cannot own any more objects in the ledger. |
| `tecDUPLICATE` | 149 | The transaction tried to create an object (such as a [DepositPreauth][] authorization) that already exists. |
| `tecDST_TAG_NEEDED` | 143 | The [Payment transaction][] omitted a [destination tag](source-and-destination-tags.html), but the destination account has the `lsfRequireDestTag` flag enabled. |
| `tecDST_TAG_NEEDED` | 143 | The [Payment transaction][] omitted a [destination tag](../../../../concepts/transactions/source-and-destination-tags.md), but the destination account has the `lsfRequireDestTag` flag enabled. |
| `tecEXPIRED` | 148 | The transaction tried to create an object (such as an Offer or a Check) whose provided Expiration time has already passed. |
| `tecFAILED_PROCESSING` | 105 | An unspecified error occurred when processing the transaction. |
| `tecFROZEN` | 137 | The [OfferCreate transaction][] failed because one or both of the assets involved are subject to a [global freeze](freezes.html). |
| `tecHAS_OBLIGATIONS` | 151 | The [AccountDelete transaction][] failed because the account to be deleted owns objects that cannot be deleted. See [Deleting Accounts](deleting-accounts.html) for details. |
| `tecINSUF_RESERVE_LINE` | 122 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](reserves.html)) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See `tecNO_LINE_INSUF_RESERVE` for the other case.) |
| `tecINSUF_RESERVE_OFFER` | 123 | The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: [Reserves](reserves.html)) |
| `tecINSUFF_FEE` | 136 | The transaction failed because the sending account does not have enough XRP to pay the [transaction cost](transaction-cost.html) that it specified. (In this case, the transaction processing destroys all of the sender's XRP even though that amount is lower than the specified transaction cost.) This result only occurs if the account's balance decreases _after_ this transaction has been distributed to enough of the network to be included in a consensus set. Otherwise, the transaction fails with [`terINSUF_FEE_B`](ter-codes.html) before being distributed. |
| `tecFROZEN` | 137 | The [OfferCreate transaction][] failed because one or both of the assets involved are subject to a [global freeze](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `tecHAS_OBLIGATIONS` | 151 | The [AccountDelete transaction][] failed because the account to be deleted owns objects that cannot be deleted. See [Deleting Accounts](../../../../concepts/accounts/deleting-accounts.md) for details. |
| `tecINSUF_RESERVE_LINE` | 122 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](../../../../concepts/accounts/reserves.md)) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See `tecNO_LINE_INSUF_RESERVE` for the other case.) |
| `tecINSUF_RESERVE_OFFER` | 123 | The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: [Reserves](../../../../concepts/accounts/reserves.md)) |
| `tecINSUFF_FEE` | 136 | The transaction failed because the sending account does not have enough XRP to pay the [transaction cost](../../../../concepts/transactions/transaction-cost.md) that it specified. (In this case, the transaction processing destroys all of the sender's XRP even though that amount is lower than the specified transaction cost.) This result only occurs if the account's balance decreases _after_ this transaction has been distributed to enough of the network to be included in a consensus set. Otherwise, the transaction fails with [`terINSUF_FEE_B`](ter-codes.md) before being distributed. |
| `tecINSUFFICIENT_FUNDS` | 158 | One of the accounts involved does not hold enough of a necessary asset. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecINSUFFICIENT_PAYMENT` | 161 | The amount specified is not enough to pay all fees involved in the transaction. For example, when trading a non-fungible token, the buy amount may not be enough to pay both the broker fee and the sell amount. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecINSUFFICIENT_RESERVE` | 141 | The transaction would increase the [reserve requirement](reserves.html) higher than the sending account's balance. [SignerListSet][], [PaymentChannelCreate][], [PaymentChannelFund][], and [EscrowCreate][] can return this error code. See [Signer Lists and Reserves](signerlist.html#signer-lists-and-reserves) for more information. |
| `tecINSUFFICIENT_RESERVE` | 141 | The transaction would increase the [reserve requirement](../../../../concepts/accounts/reserves.md) higher than the sending account's balance. [SignerListSet][], [PaymentChannelCreate][], [PaymentChannelFund][], and [EscrowCreate][] can return this error code. See [Signer Lists and Reserves](../../ledger-data/ledger-entry-types/signerlist.md#signer-lists-and-reserves) for more information. |
| `tecINTERNAL` | 144 | Unspecified internal error, with transaction cost applied. This error code should not normally be returned. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues). |
| `tecINVARIANT_FAILED` | 147 | An invariant check failed when trying to execute this transaction. Added by the [EnforceInvariants amendment][]. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues). |
| `tecKILLED` | 150 | The [OfferCreate transaction][] specified the `tfFillOrKill` flag and could not be filled, so it was killed. _(Added by the [fix1578 amendment][].)_ |
| `tecMAX_SEQUENCE_REACHED` | 153 | A sequence number field is already at its maximum. This includes the `MintedNFTokens` field. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecNEED_MASTER_KEY` | 142 | This transaction tried to cause changes that require the master key, such as [disabling the master key or giving up the ability to freeze balances](accountset.html#accountset-flags). |
| `tecNEED_MASTER_KEY` | 142 | This transaction tried to cause changes that require the master key, such as [disabling the master key or giving up the ability to freeze balances](../types/accountset.md#accountset-flags). |
| `tecNFTOKEN_BUY_SELL_MISMATCH` | 155 | The [NFTokenAcceptOffer transaction][] attempted to match incompatible offers to buy and sell a non-fungible token. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecNFTOKEN_OFFER_TYPE_MISMATCH` | 156 | One or more of the offers specified in the transaction was not the right type of offer. (For example, a buy offer was specified in the `NFTokenSellOffer` field.) _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecNO_ALTERNATIVE_KEY` | 130 | The transaction tried to remove the only available method of [authorizing transactions](transactions.html#authorizing-transactions). This could be a [SetRegularKey transaction][] to remove the regular key, a [SignerListSet transaction][] to delete a SignerList, or an [AccountSet transaction][] to disable the master key. (Prior to `rippled` 0.30.0, this was called `tecMASTER_DISABLED`.) |
| `tecNO_ALTERNATIVE_KEY` | 130 | The transaction tried to remove the only available method of [authorizing transactions](../../../../concepts/transactions/index.md#authorizing-transactions). This could be a [SetRegularKey transaction][] to remove the regular key, a [SignerListSet transaction][] to delete a SignerList, or an [AccountSet transaction][] to disable the master key. (Prior to `rippled` 0.30.0, this was called `tecMASTER_DISABLED`.) |
| `tecNO_AUTH` | 134 | The transaction failed because it needs to add a balance on a trust line to an account with the `lsfRequireAuth` flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, `tecNO_LINE` occurs instead. |
| `tecNO_DST` | 124 | The account on the receiving end of the transaction does not exist. This includes Payment and TrustSet transaction types. (It could be created if it received enough XRP.) |
| `tecNO_DST_INSUF_XRP` | 125 | The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it. |
| `tecNO_ENTRY` | 140 | The transaction tried to modify a [ledger object](ledger-object-types.html), such as a [Check](checks.html), [Payment Channel](payment-channels.html), or [Deposit Preauthorization](depositpreauth-object.html), but the specified object does not exist. It may have already been deleted by a previous transaction or the transaction may have an incorrect value in an ID field such as `CheckID`, `Channel`, `Unauthorize`. |
| `tecNO_ENTRY` | 140 | The transaction tried to modify a [ledger object](../../ledger-data/ledger-entry-types/index.md), such as a [Check](../../../../concepts/payment-types/checks.md), [Payment Channel](../../../../concepts/payment-types/payment-channels.md), or [Deposit Preauthorization](../../ledger-data/ledger-entry-types/depositpreauth.md), but the specified object does not exist. It may have already been deleted by a previous transaction or the transaction may have an incorrect value in an ID field such as `CheckID`, `Channel`, `Unauthorize`. |
| `tecNO_ISSUER` | 133 | The account specified in the `issuer` field of a currency amount does not exist. |
| `tecNO_LINE` | 135 | The `TakerPays` field of the [OfferCreate transaction][] specifies an asset whose issuer has `lsfRequireAuth` enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, `tecNO_AUTH` occurs instead. |
| `tecNO_LINE_INSUF_RESERVE` | 126 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](reserves.html)) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See `tecINSUF_RESERVE_LINE` for the other case.) |
| `tecNO_LINE_INSUF_RESERVE` | 126 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](../../../../concepts/accounts/reserves.md)) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See `tecINSUF_RESERVE_LINE` for the other case.) |
| `tecNO_LINE_REDUNDANT` | 127 | The transaction failed because it tried to set a trust line to its default state, but the trust line did not exist. |
| `tecNO_PERMISSION` | 139 | The sender does not have permission to do this operation. For example, the [EscrowFinish transaction][] tried to release a held payment before its `FinishAfter` time, someone tried to use [PaymentChannelFund][] on a channel the sender does not own, or a [Payment][] tried to deliver funds to an account with the "DepositAuth" flag enabled. |
| `tecNO_REGULAR_KEY` | 131 | The [AccountSet transaction][] tried to disable the master key, but the account does not have another way to [authorize transactions](transactions.html#authorizing-transactions). If [multi-signing](multi-signing.html) is enabled, this code is deprecated and `tecNO_ALTERNATIVE_KEY` is used instead. |
| `tecNO_REGULAR_KEY` | 131 | The [AccountSet transaction][] tried to disable the master key, but the account does not have another way to [authorize transactions](../../../../concepts/transactions/index.md#authorizing-transactions). If [multi-signing](../../../../concepts/accounts/multi-signing.md) is enabled, this code is deprecated and `tecNO_ALTERNATIVE_KEY` is used instead. |
| `tecNO_SUITABLE_NFTOKEN_PAGE` | 154 | The transaction tried to mint or acquire a non-fungible token but the account receiving the `NFToken` does not have a directory page that can hold it. This situation is rare. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecNO_TARGET` | 138 | The transaction referenced an Escrow or PayChannel ledger object that doesn't exist, either because it never existed or it has already been deleted. (For example, another [EscrowFinish transaction][] has already executed the held payment.) Alternatively, the destination account has `asfDisallowXRP` set so it cannot be the destination of this [PaymentChannelCreate][] or [EscrowCreate][] transaction. |
| `tecOBJECT_NOT_FOUND` | 160 | One of the objects specified by this transaction did not exist in the ledger. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecOVERSIZE` | 145 | This transaction could not be processed, because the server created an excessively large amount of [metadata](transaction-metadata.html) when it tried to apply the transaction. |
| `tecOWNERS` | 132 | The transaction cannot succeed because the sender already owns objects in the ledger. For example, an account cannot enable the [`lsfRequireAuth`](accountset.html#accountset-flags) flag if it has any trust lines or available offers. |
| `tecPATH_DRY` | 128 | The transaction failed because the provided [paths](paths.html) did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by [trust lines](trust-lines-and-issuing.html). |
| `tecPATH_PARTIAL` | 101 | The transaction failed because the provided [paths](paths.html) did not have enough liquidity to send the full amount. |
| `tecOVERSIZE` | 145 | This transaction could not be processed, because the server created an excessively large amount of [metadata](../metadata.md) when it tried to apply the transaction. |
| `tecOWNERS` | 132 | The transaction cannot succeed because the sender already owns objects in the ledger. For example, an account cannot enable the [`lsfRequireAuth`](../types/accountset.md#accountset-flags) flag if it has any trust lines or available offers. |
| `tecPATH_DRY` | 128 | The transaction failed because the provided [paths](../../../../concepts/tokens/fungible-tokens/paths.md) did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by [trust lines](../../../../concepts/tokens/fungible-tokens/index.md). |
| `tecPATH_PARTIAL` | 101 | The transaction failed because the provided [paths](../../../../concepts/tokens/fungible-tokens/paths.md) did not have enough liquidity to send the full amount. |
| `tecTOO_SOON` | 152 | The [AccountDelete transaction][] failed because the account to be deleted had a `Sequence` number that is too high. The current ledger index must be at least 256 higher than the account's sequence number. |
| `tecUNFUNDED` | 129 | The transaction failed because the account does not hold enough XRP to pay the amount in the transaction _and_ satisfy the additional [reserve](reserves.html) necessary to execute this transaction. |
| `tecUNFUNDED` | 129 | The transaction failed because the account does not hold enough XRP to pay the amount in the transaction _and_ satisfy the additional [reserve](../../../../concepts/accounts/reserves.md) necessary to execute this transaction. |
| `tecUNFUNDED_ADD` | 102 | **DEPRECATED.** |
| `tecUNFUNDED_PAYMENT` | 104 | The transaction failed because the sending account is trying to send more XRP than it holds, not counting the [reserve](reserves.html). |
| `tecUNFUNDED_PAYMENT` | 104 | The transaction failed because the sending account is trying to send more XRP than it holds, not counting the [reserve](../../../../concepts/accounts/reserves.md). |
| `tecUNFUNDED_OFFER` | 103 | The [OfferCreate transaction][] failed because the account creating the offer does not have any of the `TakerGets` currency. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

23
content/references/protocol/transactions/transaction-results/tef-codes.md
View File

@@ -10,33 +10,30 @@ labels:
These codes indicate that the transaction failed and was not included in a ledger, but the transaction could have succeeded in some theoretical ledger. Typically this means that the transaction can no longer succeed in any future ledger. They have numerical values in the range -199 to -100. The exact code for any given error is subject to change, so don't rely on it.
**Caution:** Transactions with `tef` codes are not applied to ledgers and cannot cause any changes to the XRP Ledger state. However, a transaction that provisionally failed may still succeed or fail with a different code after being reapplied. For more information, see [Finality of Results](finality-of-results.html) and [Reliable Transaction Submission](reliable-transaction-submission.html).
**Caution:** Transactions with `tef` codes are not applied to ledgers and cannot cause any changes to the XRP Ledger state. However, a transaction that provisionally failed may still succeed or fail with a different code after being reapplied. For more information, see [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) and [Reliable Transaction Submission](../../../../concepts/transactions/reliable-transaction-submission.md).
| Code | Explanation |
|:-----------------------|:----------------------------------------------------|
| `tefALREADY` | The same exact transaction has already been applied. |
| `tefBAD_ADD_AUTH` | **DEPRECATED.** |
| `tefBAD_AUTH` | The key used to sign this account is not authorized to modify this account. (It could be authorized if the account had the same key set as the [Regular Key](cryptographic-keys.html).) |
| `tefBAD_AUTH` | The key used to sign this account is not authorized to modify this account. (It could be authorized if the account had the same key set as the [Regular Key](../../../../concepts/accounts/cryptographic-keys.md).) |
| `tefBAD_AUTH_MASTER` | The single signature provided to authorize this transaction does not match the master key, but no regular key is associated with this address. |
| `tefBAD_LEDGER` | While processing the transaction, the ledger was discovered in an unexpected state. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues) to get it fixed. |
| `tefBAD_QUORUM` | The transaction was [multi-signed](multi-signing.html), but the total weights of all included signatures did not meet the quorum. |
| `tefBAD_SIGNATURE` | The transaction was [multi-signed](multi-signing.html), but contained a signature for an address not part of a SignerList associated with the sending account. |
| `tefBAD_QUORUM` | The transaction was [multi-signed](../../../../concepts/accounts/multi-signing.md), but the total weights of all included signatures did not meet the quorum. |
| `tefBAD_SIGNATURE` | The transaction was [multi-signed](../../../../concepts/accounts/multi-signing.md), but contained a signature for an address not part of a SignerList associated with the sending account. |
| `tefCREATED` | **DEPRECATED.** |
| `tefEXCEPTION` | While processing the transaction, the server entered an unexpected state. This may be caused by unexpected inputs, for example if the binary data for the transaction is grossly malformed. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues) to get it fixed. |
| `tefFAILURE` | Unspecified failure in applying the transaction. |
| `tefINTERNAL` | When trying to apply the transaction, the server entered an unexpected state. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues) to get it fixed. |
| `tefINVARIANT_FAILED` | An invariant check failed when trying to claim the [transaction cost](transaction-cost.html). Added by the [EnforceInvariants amendment][]. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues). |
| `tefINVARIANT_FAILED` | An invariant check failed when trying to claim the [transaction cost](../../../../concepts/transactions/transaction-cost.md). Added by the [EnforceInvariants amendment][]. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues). |
| `tefMASTER_DISABLED` | The transaction was signed with the account's master key, but the account has the `lsfDisableMaster` field set. |
| `tefMAX_LEDGER` | The transaction included a [`LastLedgerSequence`](reliable-transaction-submission.html#lastledgersequence) parameter, but the current ledger's sequence number is already higher than the specified value. |
| `tefNFTOKEN_IS_NOT_TRANSFERABLE` | The transaction attempted to send a [non-fungible token](non-fungible-tokens.html) to another account, but the `NFToken` has the `lsfTransferable` flag disabled and the transfer would not be to or from the issuer. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tefMAX_LEDGER` | The transaction included a [`LastLedgerSequence`](../../../../concepts/transactions/reliable-transaction-submission.md#lastledgersequence) parameter, but the current ledger's sequence number is already higher than the specified value. |
| `tefNFTOKEN_IS_NOT_TRANSFERABLE` | The transaction attempted to send a [non-fungible token](../../../../concepts/tokens/nfts/index.md) to another account, but the `NFToken` has the `lsfTransferable` flag disabled and the transfer would not be to or from the issuer. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tefNO_AUTH_REQUIRED` | The [TrustSet transaction][] tried to mark a trust line as authorized, but the `lsfRequireAuth` flag is not enabled for the corresponding account, so authorization is not necessary. |
| `tefNO_TICKET` | The transaction attempted to use a [Ticket](tickets.html), but the specified `TicketSequence` number does not exist in the ledger, and cannot be created in the future because it is earlier than the sender's current sequence number. |
| `tefNOT_MULTI_SIGNING` | The transaction was [multi-signed](multi-signing.html), but the sending account has no SignerList defined. |
| `tefNO_TICKET` | The transaction attempted to use a [Ticket](../../../../concepts/accounts/tickets.md), but the specified `TicketSequence` number does not exist in the ledger, and cannot be created in the future because it is earlier than the sender's current sequence number. |
| `tefNOT_MULTI_SIGNING` | The transaction was [multi-signed](../../../../concepts/accounts/multi-signing.md), but the sending account has no SignerList defined. |
| `tefPAST_SEQ` | The sequence number of the transaction is lower than the current sequence number of the account sending the transaction. |
| `tefTOO_BIG` | The transaction would affect too many objects in the ledger. For example, this was an [AccountDelete transaction][] but the account to be deleted owns over 1000 objects in the ledger. |
| `tefWRONG_PRIOR` | The transaction contained an `AccountTxnID` field (or the deprecated `PreviousTxnID` field), but the transaction specified there does not match the account's previous transaction. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

29
content/references/protocol/transactions/transaction-results/tel-codes.md
View File

@@ -9,28 +9,25 @@ labels:
These codes indicate an error in the local server processing the transaction; it is possible that another server with a different configuration or load level could process the transaction successfully. They have numerical values in the range -399 to -300. The exact code for any given error is subject to change, so don't rely on it.
**Caution:** Transactions with `tel` codes are not applied to ledgers and cannot cause any changes to the XRP Ledger state. However, these transactions may be automatically cached and retried later. Transactions that provisionally failed may still succeed or fail with a different code after being reapplied. For more information, see [Finality of Results](finality-of-results.html) and [Reliable Transaction Submission](reliable-transaction-submission.html).
**Caution:** Transactions with `tel` codes are not applied to ledgers and cannot cause any changes to the XRP Ledger state. However, these transactions may be automatically cached and retried later. Transactions that provisionally failed may still succeed or fail with a different code after being reapplied. For more information, see [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) and [Reliable Transaction Submission](../../../../concepts/transactions/reliable-transaction-submission.md).
| Code | Explanation |
|:----------------|:------------|
| `telBAD_DOMAIN` | The transaction specified a domain value (for example, the `Domain` field of an [AccountSet transaction][]) that cannot be used, probably because it is too long to store in the ledger. |
| `telBAD_PATH_COUNT` | The transaction contains too many paths for the local server to process. |
| `telBAD_PUBLIC_KEY` | The transaction specified a public key value (for example, as the `MessageKey` field of an [AccountSet transaction][]) that cannot be used, probably because it is not the right length. |
| `telCAN_NOT_QUEUE` | The transaction did not meet the [open ledger cost](transaction-cost.html), but this server did not queue this transaction because it did not meet the [queuing restrictions](transaction-queue.html#queuing-restrictions). For example, a transaction returns this code when the sender already has 10 other transactions in the queue. You can try again later or sign and submit a replacement transaction with a higher transaction cost in the `Fee` field. |
| `telCAN_NOT_QUEUE_BALANCE` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue because the sum of potential XRP costs of already-queued transactions is greater than the expected balance of the account. You can try again later, or try submitting to a different server. |
| `telCAN_NOT_QUEUE_BLOCKS` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue. This transaction could not replace an existing transaction in the queue because it would block already-queued transactions from the same sender. (For details, see [Queuing Restrictions](transaction-queue.html#queuing-restrictions).) You can try again later, or try submitting to a different server. |
| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue because a transaction queued ahead of it from the same sender blocks it. (For details, see [Queuing Restrictions](transaction-queue.html#queuing-restrictions).) You can try again later, or try submitting to a different server. |
| `telCAN_NOT_QUEUE_FEE` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue. This code occurs when a transaction with the same sender and sequence number already exists in the queue and the new one does not pay a large enough transaction cost to replace the existing transaction. To replace a transaction in the queue, the new transaction must have a `Fee` value that is at least 25% more, as measured in [fee levels](transaction-cost.html#fee-levels). You can increase the `Fee` and try again, send this with a higher `Sequence` number so it doesn't replace an existing transaction, or try sending to another server. |
| `telCAN_NOT_QUEUE_FULL` | The transaction did not meet the [open ledger cost](transaction-cost.html) and the server did not queue this transaction because this server's transaction queue is full. You could increase the `Fee` and try again, try again later, or try submitting to a different server. The new transaction must have a higher transaction cost, as measured in [fee levels](transaction-cost.html#fee-levels), than the transaction in the queue with the smallest transaction cost. |
| `telCAN_NOT_QUEUE` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md), but this server did not queue this transaction because it did not meet the [queuing restrictions](../../../../concepts/transactions/transaction-queue.md#queuing-restrictions). For example, a transaction returns this code when the sender already has 10 other transactions in the queue. You can try again later or sign and submit a replacement transaction with a higher transaction cost in the `Fee` field. |
| `telCAN_NOT_QUEUE_BALANCE` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and also was not added to the transaction queue because the sum of potential XRP costs of already-queued transactions is greater than the expected balance of the account. You can try again later, or try submitting to a different server. |
| `telCAN_NOT_QUEUE_BLOCKS` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and also was not added to the transaction queue. This transaction could not replace an existing transaction in the queue because it would block already-queued transactions from the same sender. (For details, see [Queuing Restrictions](../../../../concepts/transactions/transaction-queue.md#queuing-restrictions).) You can try again later, or try submitting to a different server. |
| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and also was not added to the transaction queue because a transaction queued ahead of it from the same sender blocks it. (For details, see [Queuing Restrictions](../../../../concepts/transactions/transaction-queue.md#queuing-restrictions).) You can try again later, or try submitting to a different server. |
| `telCAN_NOT_QUEUE_FEE` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and also was not added to the transaction queue. This code occurs when a transaction with the same sender and sequence number already exists in the queue and the new one does not pay a large enough transaction cost to replace the existing transaction. To replace a transaction in the queue, the new transaction must have a `Fee` value that is at least 25% more, as measured in [fee levels](../../../../concepts/transactions/transaction-cost.md#fee-levels). You can increase the `Fee` and try again, send this with a higher `Sequence` number so it doesn't replace an existing transaction, or try sending to another server. |
| `telCAN_NOT_QUEUE_FULL` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and the server did not queue this transaction because this server's transaction queue is full. You could increase the `Fee` and try again, try again later, or try submitting to a different server. The new transaction must have a higher transaction cost, as measured in [fee levels](../../../../concepts/transactions/transaction-cost.md#fee-levels), than the transaction in the queue with the smallest transaction cost. |
| `telFAILED_PROCESSING` | An unspecified error occurred when processing the transaction. |
| `telINSUF_FEE_P` | The `Fee` from the transaction is not high enough to meet the server's current [transaction cost](transaction-cost.html) requirement, which is derived from its load level and network-level requirements. If the individual server is too busy to process your transaction right now, it may cache the transaction and automatically retry later. |
| `telINSUF_FEE_P` | The `Fee` from the transaction is not high enough to meet the server's current [transaction cost](../../../../concepts/transactions/transaction-cost.md) requirement, which is derived from its load level and network-level requirements. If the individual server is too busy to process your transaction right now, it may cache the transaction and automatically retry later. |
| `telLOCAL_ERROR` | Unspecified local error. The transaction may be able to succeed if you submit it to a different server. |
| `telNETWORK_ID_MAKES_TX_NON_CANONICAL` | The transaction specifies the [`NetworkID` field](transaction-common-fields.html#networkid-field), but the current network rules require that the `NetworkID` field be omitted. (Mainnet and other networks with a chain ID of 1024 or less do not use this field.) If the transaction was intended for a network that does not use `NetworkID`, remove the field and try again. If the transaction was intended for a different network, submit it to a server that is connected to the correct network. [New in: rippled 1.11.0][] |
| `telNO_DST`_`PARTIAL` | The transaction is an XRP payment that would fund a new account, but the [`tfPartialPayment` flag](partial-payments.html) was enabled. This is disallowed. |
| `telREQUIRES_NETWORK_ID` | The transaction does not specify a [`NetworkID` field](transaction-common-fields.html#networkid-field), but the current network requires one. If the transaction was intended for a network that requires `NetworkID`, add the field and try again. If the transaction was intended for a different network, submit it to a server that is connected to the correct network. [New in: rippled 1.11.0][] |
| `telWRONG_NETWORK` | The transaction specifies the wrong [`NetworkID` value](transaction-common-fields.html#networkid-field) for the current network. Either specify the correct the `NetworkID` value for the intended network, or submit the transaction to a server that is connected to the correct network. [New in: rippled 1.11.0][] |
| `telNETWORK_ID_MAKES_TX_NON_CANONICAL` | The transaction specifies the [`NetworkID` field](../common-fields.md#networkid-field), but the current network rules require that the `NetworkID` field be omitted. (Mainnet and other networks with a chain ID of 1024 or less do not use this field.) If the transaction was intended for a network that does not use `NetworkID`, remove the field and try again. If the transaction was intended for a different network, submit it to a server that is connected to the correct network. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %} |
| `telNO_DST`_`PARTIAL` | The transaction is an XRP payment that would fund a new account, but the [`tfPartialPayment` flag](../../../../concepts/payment-types/partial-payments.md) was enabled. This is disallowed. |
| `telREQUIRES_NETWORK_ID` | The transaction does not specify a [`NetworkID` field](../common-fields.md#networkid-field), but the current network requires one. If the transaction was intended for a network that requires `NetworkID`, add the field and try again. If the transaction was intended for a different network, submit it to a server that is connected to the correct network. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %} |
| `telWRONG_NETWORK` | The transaction specifies the wrong [`NetworkID` value](../common-fields.md#networkid-field) for the current network. Either specify the correct the `NetworkID` value for the intended network, or submit the transaction to a server that is connected to the correct network. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %} |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

33
content/references/protocol/transactions/transaction-results/tem-codes.md
View File

@@ -9,13 +9,13 @@ labels:
These codes indicate that the transaction was malformed, and cannot succeed according to the XRP Ledger protocol. They have numerical values in the range -299 to -200. The exact code for any given error is subject to change, so don't rely on it.
**Tip:** Transactions with `tem` codes are not applied to ledgers, and cannot cause any changes to XRP Ledger state. A `tem` result is final unless the rules for a valid transaction change. (For example, using functionality from an [Amendment](amendments.html) before that amendment is enabled results in `temDISABLED`; such a transaction could succeed later if it becomes valid when the amendment is enabled.)
**Tip:** Transactions with `tem` codes are not applied to ledgers, and cannot cause any changes to XRP Ledger state. A `tem` result is final unless the rules for a valid transaction change. (For example, using functionality from an [Amendment](../../../../concepts/networks-and-servers/amendments.md) before that amendment is enabled results in `temDISABLED`; such a transaction could succeed later if it becomes valid when the amendment is enabled.)
| Code | Explanation |
|:------------------------------|:----------------------------------------------|
| `temBAD_AMM_TOKENS` | The transaction incorrectly specified one or more assets. For example, the asset's issuer does not match the corresponding asset in the AMM's pool, or the transaction specified the same asset twice. _(Requires the [AMM amendment][] :not_enabled:)_ |
| `temBAD_AMM_TOKENS` | The transaction incorrectly specified one or more assets. For example, the asset's issuer does not match the corresponding asset in the AMM's pool, or the transaction specified the same asset twice. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `temBAD_AMOUNT` | An amount specified by the transaction (for example the destination `Amount` or `SendMax` values of a [Payment][]) was invalid, possibly because it was a negative number. |
| `temBAD_AUTH_MASTER` | The key used to sign this transaction does not match the master key for the account sending it, and the account does not have a [Regular Key](cryptographic-keys.html) set. |
| `temBAD_AUTH_MASTER` | The key used to sign this transaction does not match the master key for the account sending it, and the account does not have a [Regular Key](../../../../concepts/accounts/cryptographic-keys.md) set. |
| `temBAD_CURRENCY` | The transaction improperly specified a currency field. See [Specifying Currency Amounts][Currency Amount] for the correct format. |
| `temBAD_EXPIRATION` | The transaction improperly specified an expiration value, for example as part of an [OfferCreate transaction][]. Alternatively, the transaction did not specify a required expiration value, for example as part of an [EscrowCreate transaction][]. |
| `temBAD_FEE` | The transaction improperly specified its `Fee` value, for example by listing a non-XRP currency or some negative amount of XRP. |
@@ -23,35 +23,32 @@ These codes indicate that the transaction was malformed, and cannot succeed acco
| `temBAD_LIMIT` | The [TrustSet transaction][] improperly specified the `LimitAmount` value of a trust line. |
| `temBAD_NFTOKEN_TRANSFER_FEE` | The [NFTokenMint transaction][] improperly specified the `TransferFee` field of the transaction. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `temBAD_OFFER` | The [OfferCreate transaction][] specifies an invalid offer, such as offering to trade XRP for itself, or offering a negative amount. |
| `temBAD_PATH` | The [Payment transaction][] specifies one or more [Paths](paths.html) improperly, for example including an issuer for XRP, or specifying an account differently. |
| `temBAD_PATH_LOOP` | One of the [Paths](paths.html) in the [Payment transaction][] was flagged as a loop, so it cannot be processed in a bounded amount of time. |
| `temBAD_SEND_XRP_LIMIT` | The [Payment transaction][] used the [`tfLimitQuality` flag](payment.html#limit-quality) in a direct XRP-to-XRP payment, even though XRP-to-XRP payments do not involve any conversions. |
| `temBAD_PATH` | The [Payment transaction][] specifies one or more [Paths](../../../../concepts/tokens/fungible-tokens/paths.md) improperly, for example including an issuer for XRP, or specifying an account differently. |
| `temBAD_PATH_LOOP` | One of the [Paths](../../../../concepts/tokens/fungible-tokens/paths.md) in the [Payment transaction][] was flagged as a loop, so it cannot be processed in a bounded amount of time. |
| `temBAD_SEND_XRP_LIMIT` | The [Payment transaction][] used the [`tfLimitQuality` flag](../types/payment.md#limit-quality) in a direct XRP-to-XRP payment, even though XRP-to-XRP payments do not involve any conversions. |
| `temBAD_SEND_XRP_MAX` | The [Payment transaction][] included a `SendMax` field in a direct XRP-to-XRP payment, even though sending XRP should never require `SendMax`. (XRP is only valid in `SendMax` if the destination `Amount` is not XRP.) |
| `temBAD_SEND_XRP_NO_DIRECT` | The [Payment transaction][] used the [`tfNoDirectRipple` flag](payment.html#payment-flags) for a direct XRP-to-XRP payment, even though XRP-to-XRP payments are always direct. |
| `temBAD_SEND_XRP_PARTIAL` | The [Payment transaction][] used the [`tfPartialPayment` flag](partial-payments.html) for a direct XRP-to-XRP payment, even though XRP-to-XRP payments should always deliver the full amount. |
| `temBAD_SEND_XRP_NO_DIRECT` | The [Payment transaction][] used the [`tfNoDirectRipple` flag](../types/payment.md#payment-flags) for a direct XRP-to-XRP payment, even though XRP-to-XRP payments are always direct. |
| `temBAD_SEND_XRP_PARTIAL` | The [Payment transaction][] used the [`tfPartialPayment` flag](../../../../concepts/payment-types/partial-payments.md) for a direct XRP-to-XRP payment, even though XRP-to-XRP payments should always deliver the full amount. |
| `temBAD_SEND_XRP_PATHS` | The [Payment transaction][] included `Paths` while sending XRP, even though XRP-to-XRP payments should always be direct. |
| `temBAD_SEQUENCE` | The transaction is references a sequence number that is higher than its own `Sequence` number, for example trying to cancel an offer that would have to be placed after the transaction that cancels it. |
| `temBAD_SIGNATURE` | The signature to authorize this transaction is either missing, or formed in a way that is not a properly-formed signature. (See [`tecNO_PERMISSION`](tec-codes.html) for the case where the signature is properly formed, but not authorized for this account.) |
| `temBAD_SRC_ACCOUNT` | The `Account` on whose behalf this transaction is being sent (the "source account") is not a properly-formed [account](accounts.html) address. |
| `temBAD_TRANSFER_RATE` | The [`TransferRate` field of an AccountSet transaction](accountset.html#transferrate) is not properly formatted or out of the acceptable range. |
| `temBAD_SIGNATURE` | The signature to authorize this transaction is either missing, or formed in a way that is not a properly-formed signature. (See [`tecNO_PERMISSION`](tec-codes.md) for the case where the signature is properly formed, but not authorized for this account.) |
| `temBAD_SRC_ACCOUNT` | The `Account` on whose behalf this transaction is being sent (the "source account") is not a properly-formed [account](../../../../concepts/accounts/accounts.md) address. |
| `temBAD_TRANSFER_RATE` | The [`TransferRate` field of an AccountSet transaction](../types/accountset.md#transferrate) is not properly formatted or out of the acceptable range. |
| `temCANNOT_PREAUTH_SELF` | The sender of the [DepositPreauth transaction][] was also specified as the account to preauthorize. You cannot preauthorize yourself. |
| `temDST_IS_SRC` | The transaction improperly specified a destination address as the `Account` sending the transaction. This includes trust lines (where the destination address is the `issuer` field of `LimitAmount`) and payment channels (where the destination address is the `Destination` field). |
| `temDST_NEEDED` | The transaction improperly omitted a destination. This could be the `Destination` field of a [Payment transaction][], or the `issuer` sub-field of the `LimitAmount` field fo a `TrustSet` transaction. |
| `temINVALID` | The transaction is otherwise invalid. For example, the transaction ID may not be the right format, the signature may not be formed properly, or something else went wrong in understanding the transaction. |
| `temINVALID_COUNT` | The transaction includes a `TicketCount` field, but the number of Tickets specified is invalid. |
| `temINVALID_FLAG` | The transaction includes a [Flag](transaction-common-fields.html#flags-field) that does not exist, or includes a contradictory combination of flags. |
| `temINVALID_FLAG` | The transaction includes a [Flag](../common-fields.md#flags-field) that does not exist, or includes a contradictory combination of flags. |
| `temMALFORMED` | Unspecified problem with the format of the transaction. |
| `temREDUNDANT` | The transaction would do nothing; for example, it is sending a payment directly to the sending account, or creating an offer to buy and sell the same currency from the same issuer. |
| `temREDUNDANT_SEND_MAX` | [Removed in: rippled 0.28.0][] |
| `temREDUNDANT_SEND_MAX` | {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.28.0" %}Removed in: rippled 0.28.0{% /badge %} |
| `temRIPPLE_EMPTY` | The [Payment transaction][] includes an empty `Paths` field, but paths are necessary to complete this payment. |
| `temBAD_WEIGHT` | The [SignerListSet transaction][] includes a `SignerWeight` that is invalid, for example a zero or negative value. |
| `temBAD_SIGNER` | The [SignerListSet transaction][] includes a signer who is invalid. For example, there may be duplicate entries, or the owner of the SignerList may also be a member. |
| `temBAD_QUORUM` | The [SignerListSet transaction][] has an invalid `SignerQuorum` value. Either the value is not greater than zero, or it is more than the sum of all signers in the list. |
| `temUNCERTAIN` | Used internally only. This code should never be returned. |
| `temUNKNOWN` | Used internally only. This code should never be returned. |
| `temDISABLED` | The transaction requires logic that is disabled. Typically this means you are trying to use an [amendment](amendments.html) that is not enabled for the current ledger. |
| `temDISABLED` | The transaction requires logic that is disabled. Typically this means you are trying to use an [amendment](../../../../concepts/networks-and-servers/amendments.md) that is not enabled for the current ledger. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

17
content/references/protocol/transactions/transaction-results/ter-codes.md
View File

@@ -7,9 +7,9 @@ labels:
---
# ter Codes
These codes indicate that the transaction has not been [applied](consensus.html) yet, and generally will be automatically retried by the server that returned the result code. The transaction could apply successfully in the future; for example, if a certain other transaction applies first. These codes have numerical values in the range -99 to -1, but the exact code for any given error is subject to change, so don't rely on it.
These codes indicate that the transaction has not been [applied](../../../../concepts/consensus-protocol/index.md) yet, and generally will be automatically retried by the server that returned the result code. The transaction could apply successfully in the future; for example, if a certain other transaction applies first. These codes have numerical values in the range -99 to -1, but the exact code for any given error is subject to change, so don't rely on it.
**Note:** Transactions with `ter` codes have not been applied to the current ledger and have not yet changed the XRP Ledger state. A transaction that provisionally got a `ter` result may still succeed or fail with a different code after being automatically applied later. For more information, see [Finality of Results](finality-of-results.html) and [Reliable Transaction Submission](reliable-transaction-submission.html).
**Note:** Transactions with `ter` codes have not been applied to the current ledger and have not yet changed the XRP Ledger state. A transaction that provisionally got a `ter` result may still succeed or fail with a different code after being automatically applied later. For more information, see [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) and [Reliable Transaction Submission](../../../../concepts/transactions/reliable-transaction-submission.md).
| Code | Explanation |
|:-----------------|:----------------------------------------------------------|
@@ -17,18 +17,15 @@ These codes indicate that the transaction has not been [applied](consensus.html)
| `terINSUF_FEE_B` | The account sending the transaction does not have enough XRP to pay the `Fee` specified in the transaction. |
| `terLAST` | Used internally only. This code should never be returned. |
| `terNO_ACCOUNT` | The address sending the transaction is not funded in the ledger (yet). |
| `terNO_AMM` | The AMM-related transaction specifies an asset pair that does not currently have an AMM instance. _(Requires the [AMM amendment][] :not_enabled:)_ |
| `terNO_AMM` | The AMM-related transaction specifies an asset pair that does not currently have an AMM instance. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `terNO_AUTH` | The transaction would involve adding currency issued by an account with `lsfRequireAuth` enabled to a trust line that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold. |
| `terNO_LINE` | Used internally only. This code should never be returned. |
| `terNO_RIPPLE` | Used internally only. This code should never be returned. |
| `terOWNERS` | The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the [`lsfRequireAuth`](accountset.html#accountset-flags) flag if it has any trust lines or available offers. |
| `terOWNERS` | The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the [`lsfRequireAuth`](../types/accountset.md#accountset-flags) flag if it has any trust lines or available offers. |
| `terPRE_SEQ` | The `Sequence` number of the current transaction is higher than the current sequence number of the account sending the transaction. |
| `terPRE_TICKET` | The transaction attempted to use a [Ticket](tickets.html), but the specified `TicketSequence` number does not exist in the ledger. However, the Ticket could still be created by another transaction. |
| `terQUEUED` | The transaction met the load-scaled [transaction cost](transaction-cost.html) but did not meet the open ledger requirement, so the transaction has been queued for a future ledger. |
| `terPRE_TICKET` | The transaction attempted to use a [Ticket](../../../../concepts/accounts/tickets.md), but the specified `TicketSequence` number does not exist in the ledger. However, the Ticket could still be created by another transaction. |
| `terQUEUED` | The transaction met the load-scaled [transaction cost](../../../../concepts/transactions/transaction-cost.md) but did not meet the open ledger requirement, so the transaction has been queued for a future ledger. |
| `terRETRY` | Unspecified retriable error. |
| `terSUBMITTED` | Transaction has been submitted, but not yet applied. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

5
content/references/protocol/transactions/transaction-results/tes-success.md
View File

@@ -13,7 +13,4 @@ The code `tesSUCCESS` is the only code that indicates a transaction succeeded. T
|:-----------|:----------------------------------------------------------------|
| `tesSUCCESS` | The transaction was applied and forwarded to other servers. If this appears in a validated ledger, then the transaction's success is final. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

23
content/references/protocol/transactions/transaction-results/transaction-results.md
View File

@@ -13,16 +13,16 @@ The `rippled` server summarizes transaction results with result codes, which app
| Category | Prefix | Description |
|:----------------------|:--------------------------|:-------------------------|
| Claimed cost only | [`tec`](tec-codes.html) | The transaction did not achieve its intended purpose, but the [transaction cost](transaction-cost.html) was destroyed. This result is only final in a validated ledger. |
| Failure | [`tef`](tef-codes.html) | The transaction cannot be applied to the server's current (in-progress) ledger or any later one. It may have already been applied, or the condition of the ledger makes it impossible to apply in the future. |
| Local error | [`tel`](tel-codes.html) | The `rippled` server had an error due to local conditions, such as high load. You may get a different response if you resubmit to a different server or at a different time. |
| Malformed transaction | [`tem`](tem-codes.html) | The transaction was not valid, due to improper syntax, conflicting options, a bad signature, or something else. |
| Retry | [`ter`](ter-codes.html) | The transaction could not be applied, but it could apply successfully in a future ledger. |
| Success | [`tes`](tes-success.html) | (Not an error) The transaction succeeded. This result only final in a validated ledger. |
| Claimed cost only | [`tec`](tec-codes.md) | The transaction did not achieve its intended purpose, but the [transaction cost](../../../../concepts/transactions/transaction-cost.md) was destroyed. This result is only final in a validated ledger. |
| Failure | [`tef`](tef-codes.md) | The transaction cannot be applied to the server's current (in-progress) ledger or any later one. It may have already been applied, or the condition of the ledger makes it impossible to apply in the future. |
| Local error | [`tel`](tel-codes.md) | The `rippled` server had an error due to local conditions, such as high load. You may get a different response if you resubmit to a different server or at a different time. |
| Malformed transaction | [`tem`](tem-codes.md) | The transaction was not valid, due to improper syntax, conflicting options, a bad signature, or something else. |
| Retry | [`ter`](ter-codes.md) | The transaction could not be applied, but it could apply successfully in a future ledger. |
| Success | [`tes`](tes-success.md) | (Not an error) The transaction succeeded. This result only final in a validated ledger. |
The `rippled` server automatically retries failed transactions. It is important not to assume that a transaction has completely failed based on a tentative failure result. A transaction may later succeed unless its success or failure is [final](finality-of-results.html).
The `rippled` server automatically retries failed transactions. It is important not to assume that a transaction has completely failed based on a tentative failure result. A transaction may later succeed unless its success or failure is [final](../../../../concepts/transactions/finality-of-results/index.md).
**Warning:** Transactions' provisional result codes may differ than their final result. Transactions that provisionally succeeded may eventually fail and transactions that provisionally failed may eventually succeed. Transactions that provisionally failed may also eventually fail with a different code. See [finality of results](finality-of-results.html) for how to know when a transaction's result is final.
**Warning:** Transactions' provisional result codes may differ than their final result. Transactions that provisionally succeeded may eventually fail and transactions that provisionally failed may eventually succeed. Transactions that provisionally failed may also eventually fail with a different code. See [finality of results](../../../../concepts/transactions/finality-of-results/index.md) for how to know when a transaction's result is final.
The distinction between a local error (`tel`) and a malformed transaction (`tem`) is a matter of protocol-level rules. For example, the protocol sets no limit on the maximum number of paths that can be included in a transaction. However, a server may define a finite limit of paths it can process. If two different servers are configured differently, then one of them may return a `tel` error for a transaction with many paths, while the other server could successfully process the transaction. If enough servers are able to process the transaction that it survives consensus, then it can still be included in a validated ledger.
@@ -49,9 +49,6 @@ If nothing went wrong when submitting and applying the transaction locally, the
"engine_result_message": "The transaction was applied. Only final in a validated ledger."
```
**Note:** A successful result at this stage does not indicate that the transaction has completely succeeded; only that it was successfully applied to the provisional version of the ledger kept by the local server. Failed results at this stage are also provisional and may change. See [Finality of Results](finality-of-results.html) for details.
**Note:** A successful result at this stage does not indicate that the transaction has completely succeeded; only that it was successfully applied to the provisional version of the ledger kept by the local server. Failed results at this stage are also provisional and may change. See [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) for details.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

32
content/references/protocol/transactions/types/accountdelete.md
View File

@@ -9,11 +9,11 @@ labels:
[[Source]](https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/tx/impl/DeleteAccount.cpp "Source")
_Added by the [DeletableAccounts amendment](known-amendments.html#deletableaccounts)_
_Added by the [DeletableAccounts amendment](../../../../resources/known-amendments.md#deletableaccounts)_
An AccountDelete transaction deletes an [account](accountroot.html) and any objects it owns in the XRP Ledger, if possible, sending the account's remaining XRP to a specified destination account. See [Deleting Accounts](deleting-accounts.html) for the requirements to delete an account.
An AccountDelete transaction deletes an [account](../../ledger-data/ledger-entry-types/accountroot.md) and any objects it owns in the XRP Ledger, if possible, sending the account's remaining XRP to a specified destination account. See [Deleting Accounts](../../../../concepts/accounts/deleting-accounts.md) for the requirements to delete an account.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -27,40 +27,36 @@ An AccountDelete transaction deletes an [account](accountroot.html) and any obje
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_AccountDelete%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%221AF19BF9717DA0B05A3BFC5007873E7743BA54C0311CCCCC60776AAEAC5C4635%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_AccountDelete%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%221AF19BF9717DA0B05A3BFC5007873E7743BA54C0311CCCCC60776AAEAC5C4635%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:-----------------|:------------------|:-------------------|
| `Destination` | String - [Address][] | AccountID | The address of an account to receive any leftover XRP after deleting the sending account. Must be a funded account in the ledger, and must not be the sending account. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary [destination tag](source-and-destination-tags.html) that identifies a hosted recipient or other information for the recipient of the deleted account's leftover XRP. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary [destination tag](../../../../concepts/transactions/source-and-destination-tags.md) that identifies a hosted recipient or other information for the recipient of the deleted account's leftover XRP. |
## Special Transaction Cost
As an additional deterrent against ledger spam, the AccountDelete transaction requires a much higher than usual [transaction cost](transaction-cost.html): instead of the standard minimum of 0.00001 XRP, AccountDelete must destroy at least the owner reserve amount, currently 2 XRP. This discourages excessive creation of new accounts because the [reserve requirement](reserves.html) cannot be fully recouped by deleting the account.
As an additional deterrent against ledger spam, the AccountDelete transaction requires a much higher than usual [transaction cost](../../../../concepts/transactions/transaction-cost.md): instead of the standard minimum of 0.00001 XRP, AccountDelete must destroy at least the owner reserve amount, currently 2 XRP. This discourages excessive creation of new accounts because the [reserve requirement](../../../../concepts/accounts/reserves.md) cannot be fully recouped by deleting the account.
The transaction cost always applies when a transaction is included in a validated ledger, even if the transaction fails to delete the account. (See [Error Cases](#error-cases).) To greatly reduce the chances of paying the high transaction cost if the account cannot be deleted, [submit the transaction](submit.html) with `fail_hard` enabled.
The transaction cost always applies when a transaction is included in a validated ledger, even if the transaction fails to delete the account. (See [Error Cases](#error-cases).) To greatly reduce the chances of paying the high transaction cost if the account cannot be deleted, [submit the transaction](../../../http-websocket-apis/public-api-methods/transaction-methods/submit.md) with `fail_hard` enabled.
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-----------|:------------|
| `temDISABLED` | Occurs if the [DeletableAccounts amendment](known-amendments.html#deletableaccounts) is not enabled. |
| `temDISABLED` | Occurs if the [DeletableAccounts amendment](../../../../resources/known-amendments.md#deletableaccounts) is not enabled. |
| `temDST_IS_SRC` | Occurs if the `Destination` matches the sender of the transaction (`Account` field). |
| `tecDST_TAG_NEEDED` | Occurs if the `Destination` account requires a [destination tag](source-and-destination-tags.html), but the `DestinationTag` field was not provided. |
| `tecDST_TAG_NEEDED` | Occurs if the `Destination` account requires a [destination tag](../../../../concepts/transactions/source-and-destination-tags.md), but the `DestinationTag` field was not provided. |
| `tecNO_DST` | Occurs if the `Destination` account is not a funded account in the ledger. |
| `tecNO_PERMISSION` | Occurs if the `Destination` account requires [deposit authorization](depositauth.html) and the sender is not preauthorized. |
| `tecNO_PERMISSION` | Occurs if the `Destination` account requires [deposit authorization](../../../../concepts/accounts/depositauth.md) and the sender is not preauthorized. |
| `tecTOO_SOON` | Occurs if the sender's `Sequence` number is too high. The transaction's `Sequence` number plus 256 must be less than the current [Ledger Index][]. This prevents replay of old transactions if this account is resurrected after it is deleted. |
| `tecHAS_OBLIGATIONS` | Occurs if the account to be deleted is connected to objects that cannot be deleted in the ledger. (This includes objects created by other accounts, such as [escrows](escrow.html) and for example [NFT's minted](nftokenmint.html), [even if owned by another account](https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/tx/impl/DeleteAccount.cpp#L197).) |
| `tecHAS_OBLIGATIONS` | Occurs if the account to be deleted is connected to objects that cannot be deleted in the ledger. (This includes objects created by other accounts, such as [escrows](../../../../concepts/payment-types/escrow.md) and for example [NFT's minted](nftokenmint.md), [even if owned by another account](https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/tx/impl/DeleteAccount.cpp#L197).) |
| `tefTOO_BIG` | Occurs if the sending account is linked to more than 1000 objects in the ledger. The transaction could succeed on retry if some of those objects were deleted separately first. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

57
content/references/protocol/transactions/types/accountset.md
View File

@@ -9,9 +9,9 @@ labels:
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/SetAccount.cpp "Source")
An AccountSet transaction modifies the properties of an [account in the XRP Ledger](accountroot.html).
An AccountSet transaction modifies the properties of an [account in the XRP Ledger](../../ledger-data/ledger-entry-types/accountroot.md).
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -25,9 +25,9 @@ An AccountSet transaction modifies the properties of an [account in the XRP Ledg
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_AccountSet%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22327FD263132A4D08170E1B01FE1BB2E21D0126CE58165C97A9173CA9551BCD70%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_AccountSet%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22327FD263132A4D08170E1B01FE1BB2E21D0126CE58165C97A9173CA9551BCD70%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
@@ -37,14 +37,14 @@ An AccountSet transaction modifies the properties of an [account in the XRP Ledg
| [`Domain`](#domain) | String | Blob | _(Optional)_ The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase. [Cannot be more than 256 bytes in length.](https://github.com/XRPLF/rippled/blob/55dc7a252e08a0b02cd5aa39e9b4777af3eafe77/src/ripple/app/tx/impl/SetAccount.h#L34) |
| `EmailHash` | String | Hash128 | _(Optional)_ An arbitrary 128-bit value. Conventionally, clients treat this as the md5 hash of an email address to use for displaying a [Gravatar](http://en.gravatar.com/site/implement/hash/) 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. |
| `NFTokenMinter` | String | Blob | _(Optional)_ Another account that can [mint NFTokens for you](assign-an-authorized-minter-using-javascript.html). _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `NFTokenMinter` | String | Blob | _(Optional)_ Another account that can [mint NFTokens for you](../../../../tutorials/quickstart/assign-an-authorized-minter-using-javascript.md). _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| [`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 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][])_ |
| [`TickSize`](../../../../concepts/tokens/decentralized-exchange/ticksize.md) | 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)_ An arbitrary 256-bit value. If specified, the value is stored as part of the account but has no inherent meaning or requirements. |
| `WalletSize` | Number | UInt32 | _(Optional)_ Not used. This field is valid in AccountSet transactions but does nothing. |
If none of these options are provided, then the AccountSet transaction has no effect (beyond destroying the transaction cost). See [Cancel or Skip a Transaction](cancel-or-skip-a-transaction.html) for more details.
If none of these options are provided, then the AccountSet transaction has no effect (beyond destroying the transaction cost). See [Cancel or Skip a Transaction](../../../../concepts/transactions/finality-of-results/canceling-a-transaction.md) for more details.
## Domain
@@ -55,7 +55,7 @@ To remove the `Domain` field from an account, send an AccountSet with the Domain
You can put any domain in your account's `Domain` field. To prove that an account and domain belong to the same person or business, you need a "two-way link":
- Accounts you own should have a domain you own in the `Domain` field.
- At that domain, host an [xrp-ledger.toml file](xrp-ledger-toml.html) listing accounts you own, and optionally other information about how you use the XRP Ledger.
- At that domain, host an [xrp-ledger.toml file](../../../xrp-ledger-toml.md) listing accounts you own, and optionally other information about how you use the XRP Ledger.
## AccountSet Flags
@@ -73,25 +73,25 @@ The available AccountSet flags are:
| Flag Name | Decimal Value | Corresponding Ledger Flag | Description |
|:----------------------------------|:--------------|:----------------------------------|:--------------|
| `asfAccountTxnID` | 5 | (None) | Track the ID of this account's most recent transaction. Required for [`AccountTxnID`](transaction-common-fields.html#accounttxnid) |
| `asfAllowTrustLineClawback` | 16 | `lsfAllowTrustlineClawback` | Allow account to claw back tokens it has issued. _(Requires the Clawback amendment :not_enabled:)_ Can only be set if the account has an empty owner directory (no trust lines, offers, escrows, payment channels, checks, or signer lists). After you set this flag, it cannot be reverted. The account permanently gains the ability to claw back issued assets on trust lines. |
| `asfAuthorizedNFTokenMinter` | 10 | (None) | Enable to allow another account to mint non-fungible tokens (NFTokens) on this account's behalf. Specify the authorized account in the `NFTokenMinter` field of the [AccountRoot](accountroot.html) object. To remove an authorized minter, enable this flag and omit the `NFTokenMinter` field. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `asfDefaultRipple` | 8 | `lsfDefaultRipple` | Enable [rippling](rippling.html) on this account's trust lines by default. |
| `asfDepositAuth` | 9 | `lsfDepositAuth` | Enable [Deposit Authorization](depositauth.html) on this account. _(Added by the [DepositAuth amendment][].)_ |
| `asfDisableMaster` | 4 | `lsfDisableMaster` | Disallow use of the master key pair. Can only be enabled if the account has configured another way to sign transactions, such as a [Regular Key](cryptographic-keys.html) or a [Signer List](multi-signing.html). |
| `asfDisallowIncomingCheck` | 13 | `lsfDisallowIncomingCheck` | Block incoming Checks. _(Requires the [DisallowIncoming amendment][] :not_enabled:)_ |
| `asfDisallowIncomingNFTokenOffer` | 12 | `lsfDisallowIncomingNFTokenOffer` | Block incoming NFTokenOffers. _(Requires the [DisallowIncoming amendment][] :not_enabled:)_ |
| `asfDisallowIncomingPayChan` | 14 | `lsfDisallowIncomingPayChan` | Block incoming Payment Channels. _(Requires the [DisallowIncoming amendment][] :not_enabled:)_ |
| `asfDisallowIncomingTrustline` | 15 | `lsfDisallowIncomingTrustline` | Block incoming trust lines. _(Requires the [DisallowIncoming amendment][] :not_enabled:)_ |
| `asfAccountTxnID` | 5 | (None) | Track the ID of this account's most recent transaction. Required for [`AccountTxnID`](../common-fields.md#accounttxnid) |
| `asfAllowTrustLineClawback` | 16 | `lsfAllowTrustlineClawback` | Allow account to claw back tokens it has issued. _(Requires the Clawback amendment {% not-enabled /%})_ Can only be set if the account has an empty owner directory (no trust lines, offers, escrows, payment channels, checks, or signer lists). After you set this flag, it cannot be reverted. The account permanently gains the ability to claw back issued assets on trust lines. |
| `asfAuthorizedNFTokenMinter` | 10 | (None) | Enable to allow another account to mint non-fungible tokens (NFTokens) on this account's behalf. Specify the authorized account in the `NFTokenMinter` field of the [AccountRoot](../../ledger-data/ledger-entry-types/accountroot.md) object. To remove an authorized minter, enable this flag and omit the `NFTokenMinter` field. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `asfDefaultRipple` | 8 | `lsfDefaultRipple` | Enable [rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) on this account's trust lines by default. |
| `asfDepositAuth` | 9 | `lsfDepositAuth` | Enable [Deposit Authorization](../../../../concepts/accounts/depositauth.md) on this account. _(Added by the [DepositAuth amendment][].)_ |
| `asfDisableMaster` | 4 | `lsfDisableMaster` | Disallow use of the master key pair. Can only be enabled if the account has configured another way to sign transactions, such as a [Regular Key](../../../../concepts/accounts/cryptographic-keys.md) or a [Signer List](../../../../concepts/accounts/multi-signing.md). |
| `asfDisallowIncomingCheck` | 13 | `lsfDisallowIncomingCheck` | Block incoming Checks. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_ |
| `asfDisallowIncomingNFTokenOffer` | 12 | `lsfDisallowIncomingNFTokenOffer` | Block incoming NFTokenOffers. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_ |
| `asfDisallowIncomingPayChan` | 14 | `lsfDisallowIncomingPayChan` | Block incoming Payment Channels. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_ |
| `asfDisallowIncomingTrustline` | 15 | `lsfDisallowIncomingTrustline` | Block incoming trust lines. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_ |
| `asfDisallowXRP` | 3 | `lsfDisallowXRP` | XRP should not be sent to this account. (Advisory; not enforced by the XRP Ledger protocol.) |
| `asfGlobalFreeze` | 7 | `lsfGlobalFreeze` | [Freeze](freezes.html) all assets issued by this account. |
| `asfNoFreeze` | 6 | `lsfNoFreeze` | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](freezes.html). This flag can never be disabled after being enabled. |
| `asfGlobalFreeze` | 7 | `lsfGlobalFreeze` | [Freeze](../../../../concepts/tokens/fungible-tokens/freezes.md) all assets issued by this account. |
| `asfNoFreeze` | 6 | `lsfNoFreeze` | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](../../../../concepts/tokens/fungible-tokens/freezes.md). This flag can never be disabled after being enabled. |
| `asfRequireAuth` | 2 | `lsfRequireAuth` | Require authorization for users to hold balances issued by this address. Can only be enabled if the address has no trust lines connected to it. |
| `asfRequireDest` | 1 | `lsfRequireDestTag` | Require a destination tag to send transactions to this account. |
To enable the `asfDisableMaster` or `asfNoFreeze` flags, you must [authorize the transaction](transactions.html#authorizing-transactions) by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can disable `asfDisableMaster` (that is, re-enable the master key pair) using a regular key pair or multi-signature.
To enable the `asfDisableMaster` or `asfNoFreeze` flags, you must [authorize the transaction](../../../../concepts/transactions/index.md#authorizing-transactions) by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can disable `asfDisableMaster` (that is, re-enable the master key pair) using a regular key pair or multi-signature.
The following [Transaction flags](transaction-common-fields.html#flags-field) (`tf` flags), specific to the AccountSet transaction type, serve the same purpose. Due to limited space, some settings do not have associated `tf` flags, and new `tf` flags are not being added to the `AccountSet` transaction type. You can use a combination of `tf` and `asf` flags to enable multiple settings with a single transaction.
The following [Transaction flags](../common-fields.md#flags-field) (`tf` flags), specific to the AccountSet transaction type, serve the same purpose. Due to limited space, some settings do not have associated `tf` flags, and new `tf` flags are not being added to the `AccountSet` transaction type. You can use a combination of `tf` and `asf` flags to enable multiple settings with a single transaction.
| Flag Name | Hex Value | Decimal Value | Replaced by AccountSet Flag |
|:--------------------|:-------------|:--------------|:----------------------------|
@@ -102,7 +102,7 @@ The following [Transaction flags](transaction-common-fields.html#flags-field) (`
| `tfDisallowXRP` | `0x00100000` | 1048576 | `asfDisallowXRP` (`SetFlag`) |
| `tfAllowXRP` | `0x00200000` | 2097152 | `asfDisallowXRP` (`ClearFlag`) |
**Caution:** The numeric values of `tf` and `asf` flags in transactions do not match up with the values they set in the accounts "at rest" in the ledger. To read the flags of an account in the ledger, see [`AccountRoot` flags](accountroot.html#accountroot-flags).
**Caution:** The numeric values of `tf` and `asf` flags in transactions do not match up with the values they set in the accounts "at rest" in the ledger. To read the flags of an account in the ledger, see [`AccountRoot` flags](../../ledger-data/ledger-entry-types/accountroot.md#accountroot-flags).
### Blocking Incoming Transactions
@@ -115,9 +115,9 @@ For example, a destination tag is typically used to identify which hosted balanc
You can protect against unwanted incoming payments for non-XRP currencies by not creating trust lines in those currencies. Since XRP does not require trust, the `asfDisallowXRP` flag is used to discourage users from sending XRP to an account. However, this flag is not enforced in the XRP Ledger protocol because it could potentially cause accounts to become unusable if they run out of XRP. Instead, client applications should disallow or discourage XRP payments to accounts with the `asfDisallowXRP` flag enabled.
If you want to block _all_ incoming payments, you can enable [Deposit Authorization](depositauth.html). This prevents any transaction from sending money to you, even XRP, unless your account is below the [reserve requirement](reserves.html).
If you want to block _all_ incoming payments, you can enable [Deposit Authorization](../../../../concepts/accounts/depositauth.md). This prevents any transaction from sending money to you, even XRP, unless your account is below the [reserve requirement](../../../../concepts/accounts/reserves.md).
If the [DisallowIncoming amendment][] :not_enabled: is enabled, you also have the option to block all incoming Checks, NFTokenOffers, Payment Channels, and trust lines. It is generally harmless to be on the receiving end of these objects, but they can block you from deleting your account and it can be confusing to have objects you didn't expect mixed in with the list of objects you created. To block incoming objects, use one or more of these account flags:
If the [DisallowIncoming amendment][] {% not-enabled /%} is enabled, you also have the option to block all incoming Checks, NFTokenOffers, Payment Channels, and trust lines. It is generally harmless to be on the receiving end of these objects, but they can block you from deleting your account and it can be confusing to have objects you didn't expect mixed in with the list of objects you created. To block incoming objects, use one or more of these account flags:
- `asfDisallowIncomingCheck` - for Check objects
- `asfDisallowIncomingNFTOffer` - for NFTokenOffer objects
@@ -133,7 +133,7 @@ The `TransferRate` field specifies a fee to charge whenever counterparties trans
In the HTTP and WebSocket APIs, the transfer fee is represented as an integer, the amount that must be sent for 1 billion units to arrive. For example, a 20% transfer fee is represented as the value `1200000000`. The value cannot be less than 1000000000. (Less than that would indicate giving away money for sending transactions, which is exploitable.) You can specify `0` as a shortcut for `1000000000`, meaning no fee.
See [Transfer Fees](transfer-fees.html) for more information.
See [Transfer Fees](../../../../concepts/tokens/transfer-fees.md) for more information.
## NFTokenMinter
@@ -141,7 +141,4 @@ To remove an authorized minter, set `ClearFlag` to 10 (`asfAuthorizedNFTokenMint
<!-- SPELLING_IGNORE: TransferRate -->
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

32
content/references/protocol/transactions/types/ammbid.md
View File

@@ -9,14 +9,14 @@ status: not_enabled
# AMMBid
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMBid.cpp "Source")
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
Bid on an [Automated Market Maker](automated-market-makers.html)'s (AMM's) auction slot. If you win, you can trade against the AMM at a discounted fee until you are outbid or 24 hours have passed. If you are outbid before 24 hours have passed, you are refunded part of the cost of your bid based on how much time remains.
Bid on an [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md)'s (AMM's) auction slot. If you win, you can trade against the AMM at a discounted fee until you are outbid or 24 hours have passed. If you are outbid before 24 hours have passed, you are refunded part of the cost of your bid based on how much time remains.
You bid using the AMM's LP Tokens; the amount of a winning bid is returned to the AMM, decreasing the outstanding balance of LP Tokens.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -52,7 +52,7 @@ You bid using the AMM's LP Tokens; the amount of a winning bid is returned to th
}
```
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:---------------|:--------------------|:------------------|:----------|:------------|
@@ -84,7 +84,9 @@ If successful, the transaction automatically outbids the previous slot owner and
- Otherwise, the price to outbid the current holder is calculated using the following formula:
P = B × 1.05 × (1 - t⁶⁰) + M
```
P = B × 1.05 × (1 - t⁶⁰) + M
```
- `P` is the price to outbid, in LP Tokens.
- `B` is the price of the current bid, in LP Tokens.
@@ -93,13 +95,17 @@ If successful, the transaction automatically outbids the previous slot owner and
There are two special cases for the cost to outbid someone. In the **first interval** after someone wins the bid, the price to outbid them is the minimum bid plus 5% more than the existing bid:
P = B × 1.05 + M
```
P = B × 1.05 + M
```
In the **last interval** of someone's slot, the cost to outbid someone is only the minimum bid:
P = M
```
P = M
```
**Note:** To make sure all servers in the network reach the same results when building a ledger, time measurements are based on the [official close time](ledger-close-times.html) of the previous ledger, which is approximate.
**Note:** To make sure all servers in the network reach the same results when building a ledger, time measurements are based on the [official close time](../../../../concepts/ledgers/ledger-close-times.md) of the previous ledger, which is approximate.
## Bid Refunds
@@ -115,11 +121,11 @@ R = B × (1 - t)
As a special case, during the final (20th) interval of the auction slot, the refunded amount is zero.
**Note:** As with all XRP Ledger times, transaction processing uses the [official close time](ledger-close-times.html) of the _previous_ ledger, which can result in a difference of up to about 10 seconds from real time.
**Note:** As with all XRP Ledger times, transaction processing uses the [official close time](../../../../concepts/ledgers/ledger-close-times.md) of the _previous_ ledger, which can result in a difference of up to about 10 seconds from real time.
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
@@ -132,8 +138,4 @@ Besides errors that can occur for all transactions, {{currentpage.name}} transac
| `terNO_ACCOUNT` | One of the accounts specified in this request do not exist. |
| `terNO_AMM` | The Automated Market Maker instance for the asset pair in this transaction does not exist. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

27
content/references/protocol/transactions/types/ammcreate.md
View File

@@ -9,15 +9,15 @@ status: not_enabled
# AMMCreate
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMCreate.cpp "Source")
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
Create a new [Automated Market Maker](automated-market-makers.html) (AMM) instance for trading a pair of assets ([fungible tokens](tokens.html) or [XRP](xrp.html)).
Create a new [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) (AMM) instance for trading a pair of assets ([fungible tokens](../../../../concepts/tokens/index.md) or [XRP](../../../../introduction/what-is-xrp.md)).
Creates both an [AMM entry][] and a [special AccountRoot entry](accountroot.html#special-amm-accountroot-entries) to represent the AMM. Also transfers ownership of the starting balance of both assets from the sender to the created `AccountRoot` and issues an initial balance of liquidity provider tokens (LP Tokens) from the AMM account to the sender.
Creates both an [AMM entry][] and a [special AccountRoot entry](../../ledger-data/ledger-entry-types/accountroot.md#special-amm-accountroot-entries) to represent the AMM. Also transfers ownership of the starting balance of both assets from the sender to the created `AccountRoot` and issues an initial balance of liquidity provider tokens (LP Tokens) from the AMM account to the sender.
**Caution:** When you create the AMM, you should fund it with (approximately) equal-value amounts of each asset. Otherwise, other users can profit at your expense by trading with this AMM ([performing arbitrage](https://www.machow.ski/posts/an_introduction_to_automated_market_makers/#price-arbitrage)). The currency risk that liquidity providers take on increases with the volatility (potential for imbalance) of the asset pair. The higher the trading fee, the more it offsets this risk, so it's best to set the trading fee based on the volatility of the asset pair.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -36,7 +36,7 @@ Creates both an [AMM entry][] and a [special AccountRoot entry](accountroot.html
}
```
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------|:--------------------|:------------------|:----------|:------------|
@@ -44,7 +44,7 @@ Creates both an [AMM entry][] and a [special AccountRoot entry](accountroot.html
| `Amount2` | [Currency Amount][] | Amount | Yes | The second of the two assets to fund this AMM with. This must be a positive amount. |
| `TradingFee` | Number | UInt16 | Yes | The fee to charge for trades against this AMM instance, in units of 1/100,000; a value of 1 is equivalent to 0.001%. The maximum value is `1000`, indicating a 1% fee. The minimum value is `0`. |
One or both of `Amount` and `Amount2` can be [tokens](tokens.html); at most one of them can be [XRP](xrp.html). They cannot both have the same currency code and issuer. The tokens' issuers must have [Default Ripple](rippling.html#the-default-ripple-flag) enabled. If the [Clawback amendment][] :not_enabled: is enabled, those issuers must not have enabled the Allow Clawback flag. The assets _cannot_ be LP tokens for another AMM.
One or both of `Amount` and `Amount2` can be [tokens](../../../../concepts/tokens/index.md); at most one of them can be [XRP](../../../../introduction/what-is-xrp.md). They cannot both have the same currency code and issuer. The tokens' issuers must have [Default Ripple](../../../../concepts/tokens/fungible-tokens/rippling.md#the-default-ripple-flag) enabled. If the [Clawback amendment][] {% not-enabled /%} is enabled, those issuers must not have enabled the Allow Clawback flag. The assets _cannot_ be LP tokens for another AMM.
## Special Transaction Cost
@@ -52,24 +52,21 @@ Since each AMM instance involves an AccountRoot ledger entry, an AMM ledger entr
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------|:---------------------------------------------|
| `tecAMM_INVALID_TOKENS` | Either `Amount` or `Amount2` has a currency code that is the same as this AMM's LP Tokens would use. (This is very unlikely to occur.) |
| `tecDUPLICATE` | There is already another AMM for this currency pair. |
| `tecFROZEN` | At least one of the deposit assets (`Amount` or `Amount2`) is currently [frozen](freezes.html). |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](reserves.html) of processing this transaction, probably because they need a new trust line to hold the LP Tokens, and they don't have enough XRP to meet the additional owner reserve for a new trust line. |
| `tecNO_AUTH` | At least one of the deposit assets uses [authorized trust lines](authorized-trust-lines.html) and the sender does not have authorization to hold that asset. |
| `tecFROZEN` | At least one of the deposit assets (`Amount` or `Amount2`) is currently [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](../../../../concepts/accounts/reserves.md) of processing this transaction, probably because they need a new trust line to hold the LP Tokens, and they don't have enough XRP to meet the additional owner reserve for a new trust line. |
| `tecNO_AUTH` | At least one of the deposit assets uses [authorized trust lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the sender does not have authorization to hold that asset. |
| `tecNO_LINE` | The sender does not have a trust line for at least one of the deposit assets. |
| `tecNO_PERMISSION` | At least one of the deposit assets cannot be used in an AMM. For example, the issuer has enabled Clawback support. |
| `tecUNFUNDED_AMM` | The sender does not hold enough of the assets specified in `Amount` and `Amount2` to fund the AMM. |
| `terNO_RIPPLE` | The issuer of at least one of the assets has not enabled the [Default Ripple flag](rippling.html#the-default-ripple-flag). |
| `terNO_RIPPLE` | The issuer of at least one of the assets has not enabled the [Default Ripple flag](../../../../concepts/tokens/fungible-tokens/rippling.md#the-default-ripple-flag). |
| `temAMM_BAD_TOKENS` | The values of `Amount` and `Amount2` are not valid: for example, both refer to the same token. |
| `temBAD_FEE` | The `TradingFee` value is invalid. It must be zero or a positive integer and cannot be over 1000. |
| `temDISABLED` | The AMM feature is not enabled on this network. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

15
content/references/protocol/transactions/types/ammdelete.md
View File

@@ -9,14 +9,14 @@ status: not_enabled
# AMMDelete
[[Source]](https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/tx/impl/AMMDelete.cpp "Source")
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
Delete an empty [Automated Market Maker](automated-market-makers.html) (AMM) instance that could not be fully deleted automatically.
Delete an empty [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) (AMM) instance that could not be fully deleted automatically.
Normally, an [AMMWithdraw transaction][] automatically deletes an AMM and all associated ledger entries when it withdraws all the assets from the AMM's pool. However, if there are too many trust lines to the AMM account to remove in one transaction, it may stop before fully removing the AMM. Similarly, an AMMDelete transaction removes up to a maximum of 512 trust lines; it may take several AMMDelete transactions to delete all the trust lines and the associated AMM. In all cases, only the last such transaction deletes the AMM and AccountRoot ledger entries.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -35,7 +35,7 @@ Normally, an [AMMWithdraw transaction][] automatically deletes an AMM and all as
}
```
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:---------------|:--------------------|:------------------|:----------|:------------|
@@ -45,7 +45,7 @@ Normally, an [AMMWithdraw transaction][] automatically deletes an AMM and all as
## Error Cases
Besides errors that can occur for all transactions, AMMCreate transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, AMMCreate transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------|:---------------------------------------------|
@@ -53,7 +53,4 @@ Besides errors that can occur for all transactions, AMMCreate transactions can r
| `tecINCOMPLETE` | There were too many associated ledger entries to fully delete, so the transaction removed as many as it could, but the AMM has not been fully deleted. You can send another AMMDelete transaction to continue and possibly finish the job. |
| `terNO_AMM` | The specified AMM does not exist. (It may have been deleted already, or you may have specified a wrong asset for the AMM you intended.) |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

28
content/references/protocol/transactions/types/ammdeposit.md
View File

@@ -9,13 +9,13 @@ status: not_enabled
# AMMDeposit
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMDeposit.cpp "Source")
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
Deposit funds into an [Automated Market Maker](automated-market-makers.html) (AMM) instance and receive the AMM's liquidity provider tokens (_LP Tokens_) in exchange. You can deposit one or both of the assets in the AMM's pool.
Deposit funds into an [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) (AMM) instance and receive the AMM's liquidity provider tokens (_LP Tokens_) in exchange. You can deposit one or both of the assets in the AMM's pool.
If successful, this transaction creates a [trust line](trust-lines-and-issuing.html) to the AMM Account (limit 0) to hold the LP Tokens.
If successful, this transaction creates a [trust line](../../../../concepts/tokens/fungible-tokens/index.md) to the AMM Account (limit 0) to hold the LP Tokens.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -40,7 +40,7 @@ If successful, this transaction creates a [trust line](trust-lines-and-issuing.h
}
```
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------|:--------------------|:------------------|:----------|:------------|
@@ -84,7 +84,7 @@ Any other combination of these fields and flags is invalid.
The formula for how many LP Tokens you receive for a double-asset deposit is:
{{ include_svg("img/amm-single-asset-deposit-formula.svg", "L = T × ( (( 1 + (B - (F × (1 - W) × B)) ÷ P)^W) - 1)") }}
[{% inline-svg file="/img/amm-single-asset-deposit-formula.svg" /%}](/img/amm-single-asset-deposit-formula.svg "L = T × ( (( 1 + (B - (F × (1 - W) × B)) ÷ P)^W) - 1)")
<!-- TODO: improve graphic -->
Where:
@@ -105,7 +105,7 @@ You can only do a special "Empty AMM" deposit if the AMM is empty.
### AMMDeposit Flags
Transactions of the AMMDeposit type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows:
Transactions of the AMMDeposit type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:--------------------|:-------------|:--------------|:----------------------|
@@ -116,20 +116,20 @@ Transactions of the AMMDeposit type support additional values in the [`Flags` fi
| `tfLimitLPToken` | `0x00400000` | 4194304 | Perform a single-asset deposit with a specified effective price. |
| `tfTwoAssetIfEmpty` | `0x00800000` | 8388608 | Perform a special double-asset deposit to an AMM with an empty pool. |
You must specify **exactly one** of these flags, plus any [global flags](transaction-common-fields.html#global-flags).
You must specify **exactly one** of these flags, plus any [global flags](../common-fields.md#global-flags).
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
| `tecAMM_EMPTY` | The AMM currently holds no assets, so you cannot do a normal deposit. You must use the Empty AMM Special Case deposit instead. |
| `tecAMM_NOT_EMPTY` | The transaction specified `tfTwoAssetIfEmpty`, but the AMM was not empty. |
| `tecAMM_FAILED` | The conditions on the deposit could not be satisfied. For example, the requested effective price in the `EPrice` field is too low. |
| `tecFROZEN` | The transaction tried to deposit a [frozen](freezes.html) token. |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](reserves.html) of processing this transaction, probably because they need a new trust line to hold the LP Tokens, and they don't have enough XRP to meet the additional owner reserve for a new trust line. |
| `tecFROZEN` | The transaction tried to deposit a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) token. |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](../../../../concepts/accounts/reserves.md) of processing this transaction, probably because they need a new trust line to hold the LP Tokens, and they don't have enough XRP to meet the additional owner reserve for a new trust line. |
| `tecUNFUNDED_AMM` | The sender does not have a high enough balance to make the specified deposit. |
| `temBAD_AMM_TOKENS` | The transaction specified the LP Tokens incorrectly. For example, the `issuer` is not the AMM's associated AccountRoot address or the `currency` is not the currency code for this AMM's LP Tokens, or the transaction specified this AMM's LP Tokens in one of the asset fields. |
| `temBAD_AMOUNT` | An amount specified in the transaction is invalid. For example, a deposit amount is negative. |
@@ -138,8 +138,4 @@ Besides errors that can occur for all transactions, {{currentpage.name}} transac
| `terNO_ACCOUNT` | An account specified in the request does not exist. |
| `terNO_AMM` | The Automated Market Maker instance for the asset pair in this transaction does not exist. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

16
content/references/protocol/transactions/types/ammvote.md
View File

@@ -9,11 +9,11 @@ status: not_enabled
# AMMVote
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMVote.cpp "Source")
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
Vote on the trading fee for an [Automated Market Maker](automated-market-makers.html) instance. Up to 8 accounts can vote in proportion to the amount of the AMM's LP Tokens they hold. Each new vote re-calculates the AMM's trading fee based on a weighted average of the votes.
Vote on the trading fee for an [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) instance. Up to 8 accounts can vote in proportion to the amount of the AMM's LP Tokens they hold. Each new vote re-calculates the AMM's trading fee based on a weighted average of the votes.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -33,7 +33,7 @@ Vote on the trading fee for an [Automated Market Maker](automated-market-makers.
}
```
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------|:----------|:------------------|:----------|:------------|
@@ -43,7 +43,7 @@ Vote on the trading fee for an [Automated Market Maker](automated-market-makers.
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
@@ -53,8 +53,4 @@ Besides errors that can occur for all transactions, {{currentpage.name}} transac
| `temBAD_FEE` | The `TradingFee` from this transaction is not valid. |
| `terNO_AMM` | The Automated Market Maker instance for the asset pair in this transaction does not exist. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

24
content/references/protocol/transactions/types/ammwithdraw.md
View File

@@ -9,11 +9,11 @@ status: not_enabled
# AMMWithdraw
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMWithdraw.cpp "Source")
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
Withdraw assets from an [Automated Market Maker](automated-market-makers.html) (AMM) instance by returning the AMM's liquidity provider tokens (LP Tokens).
Withdraw assets from an [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) (AMM) instance by returning the AMM's liquidity provider tokens (LP Tokens).
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -38,7 +38,7 @@ Withdraw assets from an [Automated Market Maker](automated-market-makers.html) (
}
```
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------|:--------------------|:------------------|:----------|:------------|
@@ -89,7 +89,7 @@ If the transaction withdraws the last of the AMM's assets, it automatically trie
### AMMWithdraw Flags
Transactions of the AMMWithdraw type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows:
Transactions of the AMMWithdraw type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:------------------------|:-------------|:--------------|:----------------------|
@@ -101,12 +101,12 @@ Transactions of the AMMWithdraw type support additional values in the [`Flags` f
| `tfOneAssetLPToken` | `0x00200000` | 2097152 | Perform a single-asset withdrawal and receive the specified amount of LP Tokens. |
| `tfLimitLPToken` | `0x00400000` | 4194304 | Perform a single-asset withdrawal with a specified effective price. |
You must specify **exactly one** of these flags, plus any [global flags](transaction-common-fields.html#global-flags).
You must specify **exactly one** of these flags, plus any [global flags](../common-fields.md#global-flags).
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
@@ -114,15 +114,11 @@ Besides errors that can occur for all transactions, {{currentpage.name}} transac
| `tecAMM_BALANCE` | The transaction would withdraw all of one asset from the pool, or rounding would cause a "withdraw all" to leave a nonzero amount behind. |
| `tecAMM_FAILED` | The conditions on the withdrawal could not be satisfied; for example, the requested effective price in the `EPrice` field is too low. |
| `tecAMM_INVALID_TOKENS` | The AMM for this token pair does not exist, or one of the calculations resulted in a withdrawal amount rounding to zero. |
| `tecFROZEN` | The transaction tried to withdraw a [frozen](freezes.html) token. |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does not meet the increased [reserve requirement](reserves.html) of processing this transaction, probably because they need at least one new trust line to hold one of the assets to be withdrawn, and they don't have enough XRP to meet the additional owner reserve for a new trust line. |
| `tecFROZEN` | The transaction tried to withdraw a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) token. |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does not meet the increased [reserve requirement](../../../../concepts/accounts/reserves.md) of processing this transaction, probably because they need at least one new trust line to hold one of the assets to be withdrawn, and they don't have enough XRP to meet the additional owner reserve for a new trust line. |
| `tecNO_AUTH` | The sender is not authorized to hold one of the AMM assets. |
| `temMALFORMED` | The transaction specified an invalid combination of fields. See [AMMWithdraw Modes](#ammwithdraw-modes). (This error can also occur if the transaction is malformed in other ways.) |
| `temBAD_AMM_TOKENS` | The transaction specified the LP Tokens incorrectly; for example, the `issuer` is not the AMM's associated AccountRoot address or the `currency` is not the currency code for this AMM's LP Tokens, or the transaction specified this AMM's LP Tokens in one of the asset fields. |
| `terNO_AMM` | The Automated Market Maker instance for the asset pair in this transaction does not exist. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

13
content/references/protocol/transactions/types/checkcancel.md
View File

@@ -12,7 +12,7 @@ _(Added by the [Checks amendment][].)_
Cancels an unredeemed Check, removing it from the ledger without sending any money. The source or the destination of the check can cancel a Check at any time using this transaction type. If the Check has expired, any address can cancel it.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -23,21 +23,18 @@ Cancels an unredeemed Check, removing it from the ledger without sending any mon
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_CheckCancel%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22D3328000315C6DCEC1426E4E549288E3672752385D86A40D56856DBD10382953%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_CheckCancel%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22D3328000315C6DCEC1426E4E549288E3672752385D86A40D56856DBD10382953%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:------------|:----------|:------------------|:-------------------------------|
| `CheckID` | String | Hash256 | The ID of the [Check ledger object](check.html) to cancel, as a 64-character hexadecimal string. |
| `CheckID` | String | Hash256 | The ID of the [Check ledger object](../../ledger-data/ledger-entry-types/check.md) to cancel, as a 64-character hexadecimal string. |
## Error Cases
- If the object identified by the `CheckID` does not exist or is not a Check, the transaction fails with the result `tecNO_ENTRY`.
- If the Check is not expired and the sender of the CheckCancel transaction is not the source or destination of the Check, the transaction fails with the result `tecNO_PERMISSION`.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

13
content/references/protocol/transactions/types/checkcash.md
View File

@@ -14,7 +14,7 @@ Attempts to redeem a Check object in the ledger to receive up to the amount auth
Since the funds for a check are not guaranteed, redeeming a Check can fail because the sender does not have a high enough balance or because there is not enough liquidity to deliver the funds. If this happens, the Check remains in the ledger and the destination can try to cash it again later, or for a different amount.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -26,14 +26,14 @@ Since the funds for a check are not guaranteed, redeeming a Check can fail becau
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_CheckCash%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%2267B71B13601CDA5402920691841AC27A156463678E106FABD45357175F9FF406%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_CheckCash%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%2267B71B13601CDA5402920691841AC27A156463678E106FABD45357175F9FF406%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-------------|:--------------------|:------------------|:--------------------|
| `CheckID` | String | Hash256 | The ID of the [Check ledger object](check.html) to cash, as a 64-character hexadecimal string. |
| `CheckID` | String | Hash256 | The ID of the [Check ledger object](../../ledger-data/ledger-entry-types/check.md) to cash, as a 64-character hexadecimal string. |
| `Amount` | [Currency Amount][] | Amount | _(Optional)_ Redeem the Check for exactly this amount, if possible. The currency must match that of the `SendMax` of the corresponding CheckCreate transaction. You must provide either this field or `DeliverMin`. |
| `DeliverMin` | [Currency Amount][] | Amount | _(Optional)_ Redeem the Check for at least this amount and for as much as possible. The currency must match that of the `SendMax` of the corresponding CheckCreate transaction. You must provide either this field or `Amount`. |
@@ -48,7 +48,4 @@ The transaction ***must*** include either `Amount` or `DeliverMin`, but not both
- If the transaction specifies both `Amount` and `DeliverMin`, or omits both, the transaction fails with the result `temMALFORMED`.
- If the `Amount` or `DeliverMin` does not match the currency (and issuer, if not XRP) of the Check, the transaction fails with the result `temBAD_CURRENCY`.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

23
content/references/protocol/transactions/types/checkcreate.md
View File

@@ -12,7 +12,7 @@ _(Added by the [Checks amendment][].)_
Create a Check object in the ledger, which is a deferred payment that can be cashed by its intended destination. The sender of this transaction is the sender of the Check.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -27,31 +27,28 @@ Create a Check object in the ledger, which is a deferred payment that can be cas
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_CheckCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%224E0AA11CBDD1760DE95B68DF2ABBE75C9698CEB548BEA9789053FCB3EBD444FB%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_CheckCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%224E0AA11CBDD1760DE95B68DF2ABBE75C9698CEB548BEA9789053FCB3EBD444FB%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:--------------------|:------------------|:----------------|
| `Destination` | String | AccountID | The unique address of the [account](accounts.html) that can cash the Check. |
| `SendMax` | [Currency Amount][] | Amount | Maximum amount of source currency the Check is allowed to debit the sender, including [transfer fees](transfer-fees.html) on non-XRP currencies. The Check can only credit the destination with the same currency (from the same issuer, for non-XRP currencies). For non-XRP amounts, the nested field names MUST be lower-case. |
| `Destination` | String | AccountID | The unique address of the [account](../../../../concepts/accounts/accounts.md) that can cash the Check. |
| `SendMax` | [Currency Amount][] | Amount | Maximum amount of source currency the Check is allowed to debit the sender, including [transfer fees](../../../../concepts/tokens/transfer-fees.md) on non-XRP currencies. The Check can only credit the destination with the same currency (from the same issuer, for non-XRP currencies). For non-XRP amounts, the nested field names MUST be lower-case. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag that identifies the reason for the Check, or a hosted recipient to pay. |
| `Expiration` | Number | UInt32 | _(Optional)_ Time after which the Check is no longer valid, in [seconds since the Ripple Epoch][]. |
| `InvoiceID` | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash representing a specific reason or identifier for this Check. |
## Error Cases
- If the `Destination` account is blocking incoming Checks, the transaction fails with the result code `tecNO_PERMISSION`. _(Requires the [DisallowIncoming amendment][] :not_enabled:)_
- If the `Destination` account is blocking incoming Checks, the transaction fails with the result code `tecNO_PERMISSION`. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_
- 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](../../../../concepts/accounts/accounts.md) 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 a token which is [frozen](freezes.html), the transaction fails with the result `tecFROZEN`.
- If `SendMax` specifies a token which is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md), 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 the sender does not have enough XRP to meet the [owner reserve](../../../../concepts/accounts/reserves.md#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`.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

15
content/references/protocol/transactions/types/clawback.md
View File

@@ -9,13 +9,13 @@ labels:
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/Clawback.cpp "Source")
{% include '_snippets/clawback-disclaimer.md' %}
{% partial file="/_snippets/clawback-disclaimer.md" /%}
Claw back tokens issued by your account.
Clawback is disabled by default. To use clawback, you must send an [AccountSet transaction][] to enable the **Allow Trust Line Clawback** setting. An issuer with any existing tokens cannot enable Clawback. You can only enable **Allow Trust Line Clawback** if you have a completely empty owner directory, meaning you must do so before you set up any trust lines, offers, escrows, payment channels, checks, or signer lists. After you enable Clawback, it cannot reverted: the account permanently gains the ability to claw back issued assets on trust lines.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -29,7 +29,7 @@ Clawback is disabled by default. To use clawback, you must send an [AccountSet t
}
```
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:-------------------|:----------|:------------------|:------------------|
@@ -40,16 +40,13 @@ Clawback is disabled by default. To use clawback, you must send an [AccountSet t
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-----------|:------------|
| `temDISABLED` | Occurs if the [Clawback amendment](known-amendments.html#clawback) is not enabled. |
| `temDISABLED` | Occurs if the [Clawback amendment](../../../../resources/known-amendments.md#clawback) is not enabled. |
| `temBAD_AMOUNT` | Occurs if the holder's balance is 0. It is not an error if the amount exceeds the holder's balance; in that case, the maximum available balance is clawed back. Also occurs if the counterparty listed in `Amount` is the same as the `Account` issuing this transaction. |
| `tecNO_LINE` | Occurs there is no trust line with the counterparty or that trust line's balance is 0. |
| `tecNO_PERMISSION` | Occurs if you attempt to set `lsfAllowTrustlineClawback` while `lsfNoFreeze` is set. Also occurs, conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set. |
<!-- {# common link defs #} -->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

24
content/references/protocol/transactions/types/depositpreauth.md
View File

@@ -10,11 +10,11 @@ labels:
_Added by the [DepositPreauth amendment][]._
A DepositPreauth transaction gives another account pre-approval to deliver payments to the sender of this transaction. This is only useful if the sender of this transaction is using (or plans to use) [Deposit Authorization](depositauth.html).
A DepositPreauth transaction gives another account pre-approval to deliver payments to the sender of this transaction. This is only useful if the sender of this transaction is using (or plans to use) [Deposit Authorization](../../../../concepts/accounts/depositauth.md).
**Tip:** You can use this transaction to preauthorize certain counterparties before you enable Deposit Authorization. This may be useful to ensure a smooth transition from not requiring deposit authorization to requiring it.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -27,9 +27,9 @@ A DepositPreauth transaction gives another account pre-approval to deliver payme
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_DepositPreauth%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22CB1BF910C93D050254C049E9003DA1A265C107E0C8DE4A7CFF55FADFD39D5656%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_DepositPreauth%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22CB1BF910C93D050254C049E9003DA1A265C107E0C8DE4A7CFF55FADFD39D5656%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
@@ -42,14 +42,10 @@ You must provide _either_ `Authorize` or `Unauthorize`, but not both.
This transaction has the following limitations:
- An account cannot preauthorize (or unauthorize) its own address. Attempting to do so fails with the result [`temCANNOT_PREAUTH_SELF`](tem-codes.html).
- Attempting to preauthorize an account which is already preauthorized fails with the result [`tecDUPLICATE`](tec-codes.html).
- Attempting to unauthorize an account which is not preauthorized fails with the result [`tecNO_ENTRY`](tec-codes.html).
- Attempting to preauthorize an address that is not funded in the ledger fails with the result [`tecNO_TARGET`](tec-codes.html).
- Adding authorization adds a [DepositPreauth object](depositpreauth-object.html) to the ledger, which counts toward the [owner reserve requirement](reserves.html#owner-reserves). If the sender of the transaction does not have enough XRP to pay for the increased reserve, the transaction fails with the result [`tecINSUFFICIENT_RESERVE`](tec-codes.html). If the sender of the account is already at the maximum number of owned objects, the transaction fails with the result [`tecDIR_FULL`](tec-codes.html).
- An account cannot preauthorize (or unauthorize) its own address. Attempting to do so fails with the result [`temCANNOT_PREAUTH_SELF`](../transaction-results/tem-codes.md).
- Attempting to preauthorize an account which is already preauthorized fails with the result [`tecDUPLICATE`](../transaction-results/tec-codes.md).
- Attempting to unauthorize an account which is not preauthorized fails with the result [`tecNO_ENTRY`](../transaction-results/tec-codes.md).
- Attempting to preauthorize an address that is not funded in the ledger fails with the result [`tecNO_TARGET`](../transaction-results/tec-codes.md).
- Adding authorization adds a [DepositPreauth object](../../ledger-data/ledger-entry-types/depositpreauth.md) to the ledger, which counts toward the [owner reserve requirement](../../../../concepts/accounts/reserves.md#owner-reserves). If the sender of the transaction does not have enough XRP to pay for the increased reserve, the transaction fails with the result [`tecINSUFFICIENT_RESERVE`](../transaction-results/tec-codes.md). If the sender of the account is already at the maximum number of owned objects, the transaction fails with the result [`tecDIR_FULL`](../transaction-results/tec-codes.md).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

14
content/references/protocol/transactions/types/diddelete.md
View File

@@ -10,14 +10,14 @@ status: not_enabled
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/DID.cpp "Source")
_(Requires the [DID amendment][] :not_enabled:)_
_(Requires the [DID amendment][] {% not-enabled /%})_
Delete the [DID ledger entry](did.html) associated with the specified `Account` field.
Delete the [DID ledger entry](../../ledger-data/ledger-entry-types/did.md) associated with the specified `Account` field.
**Note:** This transaction only uses the [common fields][].
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -33,14 +33,10 @@ Delete the [DID ledger entry](did.html) associated with the specified `Account`
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------|:---------------------------------------------|
| `tecNO_ENTRY` | The account doesn't have a DID. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

16
content/references/protocol/transactions/types/didset.md
View File

@@ -10,12 +10,12 @@ status: not_enabled
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/DID.cpp "Source")
_(Requires the [DID amendment][] :not_enabled:)_
_(Requires the [DID amendment][] {% not-enabled /%})_
Creates a new [DID ledger entry](did.html) or updates the fields of an existing one.
Creates a new [DID ledger entry](../../ledger-data/ledger-entry-types/did.md) or updates the fields of an existing one.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -29,7 +29,7 @@ Creates a new [DID ledger entry](did.html) or updates the fields of an existing
}
```
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------|:----------|:------------------|:----------|:------------|
@@ -44,15 +44,11 @@ You must include either `Data`, `DIDDocument`, or `URI` when you submit the `DID
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------|:---------------------------------------------|
| `tecEMPTY_DID` | The transaction will create an empty DID ledger entry. Check that your updates don't remove the `Data`, `DIDDocument`, and `URI` fields. |
| `temEMPTY_DID` | The transaction is malformed and missing any DID information. Include either the `Data`, `DIDDocument`, or `URI` fields. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

13
content/references/protocol/transactions/types/escrowcancel.md
View File

@@ -13,7 +13,7 @@ _Added by the [Escrow amendment][]._
Return escrowed XRP to the sender.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -24,23 +24,20 @@ Return escrowed XRP to the sender.
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_EscrowCancel%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22B24B9D7843F99AED7FB8A3929151D0CCF656459AE40178B77C9D44CED64E839B%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_EscrowCancel%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22B24B9D7843F99AED7FB8A3929151D0CCF656459AE40178B77C9D44CED64E839B%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:----------------|:----------|:------------------|:---------------------------|
| `Owner` | String | AccountID | Address of the source account that funded the escrow payment. |
| `OfferSequence` | Number | UInt32 | Transaction sequence (or [Ticket](tickets.html) number) of [EscrowCreate transaction][] that created the escrow to cancel. |
| `OfferSequence` | Number | UInt32 | Transaction sequence (or [Ticket](../../../../concepts/accounts/tickets.md) number) of [EscrowCreate transaction][] that created the escrow to cancel. |
Any account may submit an EscrowCancel transaction.
* If the corresponding [EscrowCreate transaction][] did not specify a `CancelAfter` time, the EscrowCancel transaction fails.
* Otherwise the EscrowCancel transaction fails if the `CancelAfter` time is after the close time of the most recently-closed ledger.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

12
content/references/protocol/transactions/types/escrowcreate.md
View File

@@ -13,7 +13,7 @@ _Added by the [Escrow amendment][]._
Sequester XRP until the escrow process either finishes or is canceled.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -29,9 +29,9 @@ Sequester XRP until the escrow process either finishes or is canceled.
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_EscrowCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22C44F2EB84196B9AD820313DBEBA6316A15C9A2D35787579ED172B87A30131DA7%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_EscrowCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22C44F2EB84196B9AD820313DBEBA6316A15C9A2D35787579ED172B87A30131DA7%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
@@ -58,8 +58,4 @@ It is not possible to create a conditional escrow with no expiration, but you ca
**Note:** Before the [fix1571 amendment][] became enabled on 2018-06-19, it was possible to create an escrow with `CancelAfter` only. These escrows could be finished by anyone at any time before the specified expiration.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

15
content/references/protocol/transactions/types/escrowfinish.md
View File

@@ -13,7 +13,7 @@ _Added by the [Escrow amendment][]._
Deliver XRP from a held payment to the recipient.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -26,9 +26,9 @@ Deliver XRP from a held payment to the recipient.
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_EscrowFinish%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22317081AF188CDD4DBE55C418F41A90EC3B959CDB3B76105E0CBE6B7A0F56C5F7%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_EscrowFinish%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22317081AF188CDD4DBE55C418F41A90EC3B959CDB3B76105E0CBE6B7A0F56C5F7%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
@@ -45,11 +45,8 @@ Any account may submit an EscrowFinish transaction.
- If the held payment has a `Condition`, you cannot execute it unless you provide a matching `Fulfillment` for the condition.
- You cannot execute a held payment after it has expired. Specifically, if the corresponding [EscrowCreate transaction][] specified a `CancelAfter` time that is before the close time of the most recently-closed ledger, the EscrowFinish transaction fails.
**Note:** The minimum [transaction cost](transaction-cost.html) to submit an EscrowFinish transaction increases if it contains a fulfillment. If the transaction has no fulfillment, the transaction cost is the standard 10 drops. If the transaction contains a fulfillment, the transaction cost is 330 [drops of XRP][] plus another 10 drops for every 16 bytes in size of the preimage.
**Note:** The minimum [transaction cost](../../../../concepts/transactions/transaction-cost.md) to submit an EscrowFinish transaction increases if it contains a fulfillment. If the transaction has no fulfillment, the transaction cost is the standard 10 drops. If the transaction contains a fulfillment, the transaction cost is 330 [drops of XRP][] plus another 10 drops for every 16 bytes in size of the preimage.
In [non-production networks](parallel-networks.html), it may be possible [to delete](deleting-accounts.html) the destination account of a pending escrow. In this case, an attempt to finish the escrow fails with the result `tecNO_TARGET`, but the escrow object remains unless it has expired normally. If another payment re-creates the destination account, the escrow can be finished successfully. The destination account of an escrow can only be deleted if the escrow was created before the [fix1523 amendment](known-amendments.html#fix1523) became enabled. No such escrows exist in the production XRP Ledger, so this edge case is not possible on the production XRP Ledger. This edge case is also not possible in test networks that enable both fix1523 and Escrow amendments at the same time, which is the default when you [start a new genesis ledger](start-a-new-genesis-ledger-in-stand-alone-mode.html).
In [non-production networks](../../../../concepts/networks-and-servers/parallel-networks.md), it may be possible [to delete](../../../../concepts/accounts/deleting-accounts.md) the destination account of a pending escrow. In this case, an attempt to finish the escrow fails with the result `tecNO_TARGET`, but the escrow object remains unless it has expired normally. If another payment re-creates the destination account, the escrow can be finished successfully. The destination account of an escrow can only be deleted if the escrow was created before the [fix1523 amendment](../../../../resources/known-amendments.md#fix1523) became enabled. No such escrows exist in the production XRP Ledger, so this edge case is not possible on the production XRP Ledger. This edge case is also not possible in test networks that enable both fix1523 and Escrow amendments at the same time, which is the default when you [start a new genesis ledger](../../../../infrastructure/testing-and-auditing/start-a-new-genesis-ledger-in-stand-alone-mode.md).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/transactions/types/index.md
View File

@@ -2,7 +2,8 @@
html: transaction-types.html
parent: transaction-formats.html
blurb: All the different types of transactions that the XRP Ledger can process.
template: pagetype-category.html.jinja
metadata:
indexPage: true
labels:
- Blockchain
---
@@ -12,6 +13,9 @@ The type of a transaction (`TransactionType` field) is the most fundamental info
All transactions have certain fields in common:
* [Common Fields](transaction-common-fields.html)
* [Common Fields](../common-fields.md)
Each transaction type has additional fields relevant to the type of action it causes.
{% child-pages /%}

16
content/references/protocol/transactions/types/nftokenacceptoffer.md
View File

@@ -35,7 +35,7 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenAcceptOffer%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22BEB64444C36D1072820BAED317BE2E6470AFDAD9D8FB2D16A15A4D46E5A71909%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenAcceptOffer%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22BEB64444C36D1072820BAED317BE2E6470AFDAD9D8FB2D16A15A4D46E5A71909%22%2C%22binary%22%3Afalse%7D)
## Brokered vs. Direct Mode
@@ -60,7 +60,7 @@ If the transaction succeeds:
- The `NFToken` changes ownership, meaning that the token is removed from the `NFTokenPage` of the existing owner and added to the `NFTokenPage` of the new owner.
- Funds are transferred from the buyer to the seller, as specified in the `NFTokenOffer`. If the `NFToken` has a transfer fee, then its issuer receives the specified percentage, and the rest goes to the seller.
The transaction fails with a [`tec`-class code](tec-codes.html) if:
The transaction fails with a [`tec`-class code](../transaction-results/tec-codes.md) if:
- The buyer already owns the `NFToken`.
- The seller is not the current owner of the `NFToken`.
@@ -71,7 +71,7 @@ The transaction fails with a [`tec`-class code](tec-codes.html) if:
## Fields
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:-------------------|:--------------------|:------------------|:--------------|
@@ -89,7 +89,7 @@ In brokered mode, the offers referenced by `NFTokenBuyOffer` and `NFTokenSellOff
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-----------------------------------|:----------------------------------------|
@@ -97,15 +97,11 @@ Besides errors that can occur for all transactions, {{currentpage.name}} transac
| `temMALFORMED` | The transaction was not validly formatted. For example, it specified neither `NFTokenSellOffer` nor `NFTokenBuyOffer`, or it specified a negative `NFTokenBrokerFee`. |
| `tecCANT_ACCEPT_OWN_NFTOKEN_OFFER` | The buyer and seller are the same account. |
| `tecEXPIRED` | An offer specified in the transaction has already expired. |
| `tecINSUFFICIENT_FUNDS` | The buyer does not have the full amount they are offering. If the buy amount is specified in XRP, this could be because of the [reserve requirement](reserves.html). If the buy amount is a token, it could be because the token is [frozen](freezes.html). |
| `tecINSUFFICIENT_FUNDS` | The buyer does not have the full amount they are offering. If the buy amount is specified in XRP, this could be because of the [reserve requirement](../../../../concepts/accounts/reserves.md). If the buy amount is a token, it could be because the token is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `tecINSUFFICIENT_PAYMENT` | In brokered mode, the buy amount offered is not high enough to pay the `BrokerFee` _and_ the sell cost of the `NFToken`. |
| `tecOBJECT_NOT_FOUND` | One of the offers specified in the transaction does not exist in the ledger. |
| `tecNFTOKEN_BUY_SELL_MISMATCH` | In brokered mode, the two offers are not a valid match. For example, the seller is asking more than the buyer is offering, the buy and sell offer are denominated in different assets, or the seller specified a destination that is not the buyer or the broker. |
| `tecNFTOKEN_OFFER_TYPE_MISMATCH` | The object identified by the `NFTokenBuyOffer` is not actually a buy offer, or the object identified by the `NFTokenSellOffer` is not actually a sell offer. |
| `tecNO_PERMISSION` | The seller does not own the `NFToken` being sold; or the matching offer specifies a different `Destination` account than the account accepting the offer. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

13
content/references/protocol/transactions/types/nftokenburn.md
View File

@@ -17,7 +17,7 @@ If this operation succeeds, the corresponding `NFToken` is removed. If this oper
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -29,9 +29,9 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenBurn%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%227B9EFDFDC801C58F2B61B89AA2751634F49CE2A93923671FF0F4F099C7EE17FF%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenBurn%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%227B9EFDFDC801C58F2B61B89AA2751634F49CE2A93923671FF0F4F099C7EE17FF%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:------------------|:----------|:------------------|:-------------------------|
@@ -41,7 +41,7 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-------------------|:--------------------------------------------------------|
@@ -49,7 +49,4 @@ Besides errors that can occur for all transactions, {{currentpage.name}} transac
| `tecNO_ENTRY` | The specified `TokenID` was not found. |
| `tecNO_PERMISSION` | The account does not have permission to burn the token. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

25
content/references/protocol/transactions/types/nftokencanceloffer.md
View File

@@ -12,19 +12,19 @@ The `NFTokenCancelOffer` transaction can be used to cancel existing token offers
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "NFTokenCancelOffer",
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"NFTokenOffers": [
"TransactionType": "NFTokenCancelOffer",
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"NFTokenOffers": [
"9C92E061381C1EF37A8CDE0E8FC35188BFC30B1883825042A64309AC09F4C36D"
]
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenCancelOffer%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%229FF6366C19F762AE3479DC01390CDE17F1055EFF0C52A28B8ACF0CC11AEF0CC5%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenCancelOffer%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%229FF6366C19F762AE3479DC01390CDE17F1055EFF0C52A28B8ACF0CC11AEF0CC5%22%2C%22binary%22%3Afalse%7D)
## Permissions
@@ -36,21 +36,21 @@ An existing offer, represented by an `NFTokenOffer` object, can be cancelled by:
This transaction removes the listed `NFTokenOffer` object from the ledger, if present, and adjusts the reserve requirements accordingly. It is not an error if the `NFTokenOffer` cannot be found: if that is the case, the transaction should complete successfully.
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:------------------|:----------|:------------------|:-------------------------|
| `NFTokenOffers` | Array | VECTOR256 | An array of IDs of the `NFTokenOffer` objects to cancel (not the IDs of `NFToken` objects, but the IDs of the `NFTokenOffer` objects). Each entry must be a different [object ID](ledger-object-ids.html) of an [NFTokenOffer](nftokenoffer.html) object; the transaction is invalid if the array contains duplicate entries. |
| `NFTokenOffers` | Array | VECTOR256 | An array of IDs of the `NFTokenOffer` objects to cancel (not the IDs of `NFToken` objects, but the IDs of the `NFTokenOffer` objects). Each entry must be a different [object ID](../../ledger-data/common-fields.md) of an [NFTokenOffer](../../ledger-data/ledger-entry-types/nftokenoffer.md) object; the transaction is invalid if the array contains duplicate entries. |
The transaction can succeed even if one or more of the IDs in the `NFTokenOffers` field do not refer to objects that currently exist in the ledger. (For example, those token offers might already have been deleted.) The transaction fails with an error if one of the IDs points to an object that does exist, but is not a [NFTokenOffer](nftokenoffer.html) object.
The transaction can succeed even if one or more of the IDs in the `NFTokenOffers` field do not refer to objects that currently exist in the ledger. (For example, those token offers might already have been deleted.) The transaction fails with an error if one of the IDs points to an object that does exist, but is not a [NFTokenOffer](../../ledger-data/ledger-entry-types/nftokenoffer.md) object.
It is important to note that if you inadvertently provide a `nft_id` rather than a `nft_offer_index`, you might receive a `tesSUCCESS` response. The reason is that when passed a properly formatted ID value that is not found, the system assumes that the `NFTokenOffer` has already been deleted.
The transaction fails with an error if one of the IDs points to an object that does exist, but is not a [NFTokenOffer](nftokenoffer.html) object.
The transaction fails with an error if one of the IDs points to an object that does exist, but is not a [NFTokenOffer](../../ledger-data/ledger-entry-types/nftokenoffer.md) object.
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-------------------|:--------------------------------------------------------|
@@ -58,7 +58,4 @@ Besides errors that can occur for all transactions, {{currentpage.name}} transac
| `temMALFORMED` | The transaction was not validly formatted. For example, the `NFTokenOffers` array was empty or contained more than the maximum number of offers that can be canceled at one time. |
| `tecNO_PERMISSION` | At least one of the IDs in the `NFTokenOffers` field refers to an object that cannot be canceled. For example, the sender of this transaction is not the owner or `Destination` of the offer, or the object was not an `NFTokenOffer` type object. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

43
content/references/protocol/transactions/types/nftokencreateoffer.md
View File

@@ -10,25 +10,25 @@ labels:
Creates either a new _Sell_ offer for an `NFToken` owned by the account executing the transaction, or a new _Buy_ offer for an `NFToken` owned by another account.
If successful, the transaction creates a [NFTokenOffer object][]. Each offer counts as one object towards the [owner reserve](reserves.html) of the account that placed the offer.
If successful, the transaction creates a [NFTokenOffer object][]. Each offer counts as one object towards the [owner reserve](../../../../concepts/accounts/reserves.md) of the account that placed the offer.
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "NFTokenCreateOffer",
"Account": "rs8jBmmfpwgmrSPgwMsh7CvKRmRt1JTVSX",
"NFTokenID": "000100001E962F495F07A990F4ED55ACCFEEF365DBAA76B6A048C0A200000007",
"Amount": "1000000",
"Flags": 1
"TransactionType": "NFTokenCreateOffer",
"Account": "rs8jBmmfpwgmrSPgwMsh7CvKRmRt1JTVSX",
"NFTokenID": "000100001E962F495F07A990F4ED55ACCFEEF365DBAA76B6A048C0A200000007",
"Amount": "1000000",
"Flags": 1
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenCreateOffer%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22780C44B2EDFF8FC4152B3F7E98D4C435C13DF9BB5498E4BB2D019FCC7EF45BC6%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenCreateOffer%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22780C44B2EDFF8FC4152B3F7E98D4C435C13DF9BB5498E4BB2D019FCC7EF45BC6%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:--------------|:--------------------|:------------------|:-------------------|
@@ -41,7 +41,7 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
## NFTokenCreateOffer Flags
Transactions of the NFTokenCreateOffer type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows:
Transactions of the NFTokenCreateOffer type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:----------------|:-------------|:--------------|:------------------------------|
@@ -50,28 +50,23 @@ Transactions of the NFTokenCreateOffer type support additional values in the [`F
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:---------------------------------|:------------------------------------------|
| `temDISABLED` | The [NonFungibleTokensV1 amendment][] is not enabled. |
| `temBAD_AMOUNT` | The `Amount` field is not valid. For example, the amount was zero for a buy offer, or the amount is denominated in fungible tokens but the `NFToken` has the [`lsfOnlyXRP` flag](nftoken.html#nftoken-flags) enabled. |
| `temBAD_AMOUNT` | The `Amount` field is not valid. For example, the amount was zero for a buy offer, or the amount is denominated in fungible tokens but the `NFToken` has the [`lsfOnlyXRP` flag](../../data-types/nftoken.md#nftoken-flags) enabled. |
| `temBAD_EXPIRATION` | The specified `Expiration` time is invalid (for example, `0`). |
| `tecDIR_FULL` | The sender already owns too many objects in the ledger, or there are already too many offers to buy or sell this token. |
| `tecEXPIRED` | The specified `Expiration` time has already passed. |
| `tecFROZEN` | The `Amount` is denominated in fungible tokens, but one of the trust lines that would receive tokens from this offer is [frozen](freezes.html). This could be the seller's trust line or the `NFToken`'s issuer's trust line (if the `NFToken` has a transfer fee). |
| `tecINSUFFICIENT_RESERVE` | The sender does not have enough XRP to meet the [reserve requirement](reserves.html) after placing this offer. |
| `tecFROZEN` | The `Amount` is denominated in fungible tokens, but one of the trust lines that would receive tokens from this offer is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). This could be the seller's trust line or the `NFToken`'s issuer's trust line (if the `NFToken` has a transfer fee). |
| `tecINSUFFICIENT_RESERVE` | The sender does not have enough XRP to meet the [reserve requirement](../../../../concepts/accounts/reserves.md) after placing this offer. |
| `tecNO_DST` | The account specified in the `Destination` field does not exist in the ledger. |
| `tecNO_ENTRY` | The `NFToken` is not owned by the expected account. |
| `tecNO_ISSUER` | The issuer specified in the `Amount` field does not exist. |
| `tecNO_LINE` | The `Amount` field is denominated in fungible tokens, but the `NFToken`'s issuer does not have a trust line for those tokens and the `NFToken` does not have the [`lsfTrustLine` flag](nftoken.html#nftoken-flags) enabled. |
| `tecNO_PERMISSION` | The `Destination` account blocks incoming NFTokenOffers. _(Requires the [DisallowIncoming amendment][] :not_enabled:)_
| `tecUNFUNDED_OFFER` | For a buy offer, the sender does have the funds specified in the `Amount` field available. If the `Amount` is XRP, this could be due to the reserve requirement; if the `Amount` is denominated in fungible tokens, this could be because they are [frozen](freezes.html). |
| `tefNFTOKEN_IS_NOT_TRANSFERABLE` | The `NFToken` has the [`lsfTransferable` flag](nftoken.html#nftoken-flags) disabled and this transaction would not transfer the `NFToken` to or from the issuer. |
| `tecNO_LINE` | The `Amount` field is denominated in fungible tokens, but the `NFToken`'s issuer does not have a trust line for those tokens and the `NFToken` does not have the [`lsfTrustLine` flag](../../data-types/nftoken.md#nftoken-flags) enabled. |
| `tecNO_PERMISSION` | The `Destination` account blocks incoming NFTokenOffers. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_
| `tecUNFUNDED_OFFER` | For a buy offer, the sender does have the funds specified in the `Amount` field available. If the `Amount` is XRP, this could be due to the reserve requirement; if the `Amount` is denominated in fungible tokens, this could be because they are [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `tefNFTOKEN_IS_NOT_TRANSFERABLE` | The `NFToken` has the [`lsfTransferable` flag](../../data-types/nftoken.md#nftoken-flags) disabled and this transaction would not transfer the `NFToken` to or from the issuer. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

22
content/references/protocol/transactions/types/nftokenmint.md
View File

@@ -13,7 +13,7 @@ The `NFTokenMint` transaction creates a non-fungible token and adds it to the re
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
@@ -37,9 +37,9 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenMint%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22B42C7A0C9C3061463C619999942D0F25E4AE5FB051EA0D7A4EE1A924DB6DFEE8%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenMint%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22B42C7A0C9C3061463C619999942D0F25E4AE5FB051EA0D7A4EE1A924DB6DFEE8%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:--------------|:--------------------|:------------------|:-------------------|
@@ -52,19 +52,19 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
## NFTokenMint Flags
Transactions of the NFTokenMint type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows:
Transactions of the NFTokenMint type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:--------------|:-------------|:--------------|:------------------------------|
| `tfBurnable` | `0x00000001` | 1 | Allow the issuer (or an entity authorized by the issuer) to destroy the minted `NFToken`. (The `NFToken`'s owner can _always_ do so.) |
| `tfOnlyXRP` | `0x00000002` | 2 | The minted `NFToken` can only be bought or sold for XRP. This can be desirable if the token has a transfer fee and the issuer does not want to receive fees in non-XRP currencies. |
| `tfTrustLine` | `0x00000004` | 4 | **DEPRECATED** Automatically create [trust lines](trust-lines-and-issuing.html) from the issuer to hold transfer fees received from transferring the minted `NFToken`. The [fixRemoveNFTokenAutoTrustLine amendment][] makes it invalid to set this flag. |
| `tfTrustLine` | `0x00000004` | 4 | **DEPRECATED** Automatically create [trust lines](../../../../concepts/tokens/fungible-tokens/index.md) from the issuer to hold transfer fees received from transferring the minted `NFToken`. The [fixRemoveNFTokenAutoTrustLine amendment][] makes it invalid to set this flag. |
| `tfTransferable` | `0x00000008` | 8 | The minted `NFToken` can be transferred to others. If this flag is _not_ enabled, the token can still be transferred _from_ or _to_ the issuer, but a transfer to the issuer must be made based on a buy offer from the issuer and not a sell offer from the NFT holder. |
## Embedding additional information
If you need to specify additional information during minting (for example, details identifying a property by referencing a particular [plat](https://en.wikipedia.org/wiki/Plat), a vehicle by specifying a [VIN](https://en.wikipedia.org/wiki/Vehicle_identification_number), or other object-specific descriptions) you can use a [transaction memo](transaction-common-fields.html#memos-field). Memos are a part of the signed transaction and are available from historical archives, but are not stored in the ledger's state data.
If you need to specify additional information during minting (for example, details identifying a property by referencing a particular [plat](https://en.wikipedia.org/wiki/Plat), a vehicle by specifying a [VIN](https://en.wikipedia.org/wiki/Vehicle_identification_number), or other object-specific descriptions) you can use a [transaction memo](../common-fields.md#memos-field). Memos are a part of the signed transaction and are available from historical archives, but are not stored in the ledger's state data.
## Issuing on behalf of another account
@@ -102,7 +102,7 @@ This transaction assumes that the issuer, `rNCFjv8Ek5oDrNiMJ3pw6eLLFtMjZLJnf2`,
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------------|:---------------------------------------------|
@@ -112,11 +112,7 @@ Besides errors that can occur for all transactions, {{currentpage.name}} transac
| `temMALFORMED` | The transaction was not validly specified. For example, the `URI` field is longer than 256 bytes. |
| `tecNO_ISSUER` | The `Issuer` refers to an account that does not exist in the ledger. |
| `tecNO_PERMISSION` | The account referenced by the `Issuer` field has not authorized this transaction's sender (using the `NFTokenMinter` setting) to mint on their behalf. |
| `tecINSUFFICIENT_RESERVE` | The owner would not meet the updated [reserve requirement](reserves.html) after minting the token. Note that new `NFToken`s only increase the owner's reserve if it requires a new [NFTokenPage object][], which can each hold up to 32 NFTs. |
| `tecINSUFFICIENT_RESERVE` | The owner would not meet the updated [reserve requirement](../../../../concepts/accounts/reserves.md) after minting the token. Note that new `NFToken`s only increase the owner's reserve if it requires a new [NFTokenPage object][], which can each hold up to 32 NFTs. |
| `tecMAX_SEQUENCE_REACHED` | The `Issuer`'s `MintedNFTokens` field is already at its maximum. This is only possible if 2<sup>32</sup>-1 `NFToken`s have been minted in total by the issuer or on their behalf. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

15
content/references/protocol/transactions/types/offercancel.md
View File

@@ -11,7 +11,7 @@ labels:
An OfferCancel transaction removes an Offer object from the XRP Ledger.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -25,19 +25,16 @@ An OfferCancel transaction removes an Offer object from the XRP Ledger.
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_OfferCancel%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22E7697D162A606FCC138C5732BF0D2A4AED49386DC59235FC3E218650AAC19744%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_OfferCancel%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22E7697D162A606FCC138C5732BF0D2A4AED49386DC59235FC3E218650AAC19744%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:----------------|:----------|:------------------|:-----------------------------|
| `OfferSequence` | Number | UInt32 | The sequence number (or [Ticket](tickets.html) number) of a previous OfferCreate transaction. If specified, cancel any offer object in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist. |
| `OfferSequence` | Number | UInt32 | The sequence number (or [Ticket](../../../../concepts/accounts/tickets.md) number) of a previous OfferCreate transaction. If specified, cancel any offer object in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist. |
*Tip:* To remove an old offer and replace it with a new one, you can use an [OfferCreate transaction][] with an `OfferSequence` parameter, instead of using OfferCancel and another OfferCreate.
The OfferCancel method returns [`tesSUCCESS`](tes-success.html) even if it did not find an offer with the matching sequence number.
The OfferCancel method returns [`tesSUCCESS`](../transaction-results/tes-success.md) even if it did not find an offer with the matching sequence number.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

27
content/references/protocol/transactions/types/offercreate.md
View File

@@ -9,9 +9,9 @@ labels:
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp "Source")
An OfferCreate transaction places an [Offer](offers.html) in the [decentralized exchange](decentralized-exchange.html).
An OfferCreate transaction places an [Offer](../../../../concepts/tokens/decentralized-exchange/offers.md) in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md).
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -30,27 +30,27 @@ An OfferCreate transaction places an [Offer](offers.html) in the [decentralized
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_OfferCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%220CD69FD1F0A890CC57CDA430213FD294F7D65FF4A0F379A0D09D07A222D324E6%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_OfferCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%220CD69FD1F0A890CC57CDA430213FD294F7D65FF4A0F379A0D09D07A222D324E6%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:---------------|:--------------------|:------------------|:------------------|
| [`Expiration`](offers.html#offer-expiration) | Number | UInt32 | _(Optional)_ Time after which the Offer is no longer active, in [seconds since the Ripple Epoch][]. |
| [`Expiration`](../../../../concepts/tokens/decentralized-exchange/offers.md#offer-expiration) | Number | UInt32 | _(Optional)_ Time after which the Offer is no longer active, in [seconds since the Ripple Epoch][]. |
| `OfferSequence` | Number | UInt32 | _(Optional)_ An Offer to delete first, specified in the same way as [OfferCancel][]. |
| `TakerGets` | [Currency Amount][] | Amount | The amount and type of currency being sold. |
| `TakerPays` | [Currency Amount][] | Amount | The amount and type of currency being bought. |
## OfferCreate Flags
Transactions of the OfferCreate type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows:
Transactions of the OfferCreate type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:----------------------|:-------------|:--------------|:----------------------|
| `tfPassive` | `0x00010000` | 65536 | If enabled, the Offer does not consume Offers that exactly match it, and instead becomes an Offer object in the ledger. It still consumes Offers that cross it. |
| `tfImmediateOrCancel` | `0x00020000` | 131072 | Treat the Offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel). The Offer never creates an [Offer object][] in the ledger: it only trades as much as it can by consuming existing Offers at the time the transaction is processed. If no Offers match, it executes "successfully" without trading anything. In this case, the transaction still uses the [result code](transaction-results.html) `tesSUCCESS`. |
| `tfImmediateOrCancel` | `0x00020000` | 131072 | Treat the Offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel). The Offer never creates an [Offer object][] in the ledger: it only trades as much as it can by consuming existing Offers at the time the transaction is processed. If no Offers match, it executes "successfully" without trading anything. In this case, the transaction still uses the [result code](../transaction-results/transaction-results.md) `tesSUCCESS`. |
| `tfFillOrKill` | `0x00040000` | 262144 | Treat the offer as a [Fill or Kill order](http://en.wikipedia.org/wiki/Fill_or_kill). The Offer never creates an [Offer object][] in the ledger, and is canceled if it cannot be fully filled at the time of execution. By default, this means that the owner must receive the full `TakerPays` amount; if the `tfSell` flag is enabled, the owner must be able to spend the entire `TakerGets` amount instead. |
| `tfSell` | `0x00080000` | 524288 | Exchange the entire `TakerGets` amount, even if it means obtaining more than the `TakerPays` amount in exchange. |
@@ -69,16 +69,11 @@ Transactions of the OfferCreate type support additional values in the [`Flags` f
| `temBAD_CURRENCY` | Occurs if the transaction specifies a token with the currency code "XRP". |
| `temBAD_ISSUER` | Occurs if the transaction specifies a token with an invalid `issuer` value. |
| `tecNO_ISSUER` | Occurs if the transaction specifies a token whose `issuer` value is not a funded account in the ledger. |
| `tecFROZEN` | Occurs if the transaction involves a token on a [frozen](freezes.html) trust line (including local and global freezes). |
| `tecFROZEN` | Occurs if the transaction involves a token on a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) trust line (including local and global freezes). |
| `tecUNFUNDED_OFFER` | Occurs if the owner does not hold a positive amount of the `TakerGets` currency. (Exception: if `TakerGets` specifies a token that the owner issues, the transaction can succeed.) |
| `tecNO_LINE` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](authorized-trust-lines.html) and the necessary trust line does not exist. |
| `tecNO_AUTH` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](authorized-trust-lines.html) and the the trust line that would receive the tokens exists but has not been authorized. |
| `tecNO_LINE` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the necessary trust line does not exist. |
| `tecNO_AUTH` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the the trust line that would receive the tokens exists but has not been authorized. |
| `tecINSUF_RESERVE_OFFER` | Occurs if the owner does not have enough XRP to meet the reserve requirement of adding a new Offer object to the ledger, and the transaction did not convert any currency. (If the transaction successfully traded any amount, the transaction succeeds with the result code `tesSUCCESS`, but does not create an Offer object in the ledger for the rest.) |
| `tecDIR_FULL` | Occurs if the owner owns too many items in the ledger, or the order book contains too many Offers at the same exchange rate already. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

53
content/references/protocol/transactions/types/payment.md
View File

@@ -15,7 +15,7 @@ A Payment transaction represents a transfer of value from one account to another
Payments are also the only way to [create accounts](#creating-accounts).
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -33,22 +33,22 @@ Payments are also the only way to [create accounts](#creating-accounts).
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_Payment%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%227BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_Payment%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%227BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:---------------------|:------------------|:---------------|
| `Amount` | [Currency Amount][] | Amount | [API v1][]: Only available in API v1. The maximum amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [`tfPartialPayment` flag](#payment-flags) is set, deliver _up to_ this amount instead. |
| `DeliverMax` | [Currency Amount][] | Amount | [API v2][]: Only available in API v2. The maximum amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [`tfPartialPayment` flag](#payment-flags) is set, deliver _up to_ this amount instead. [New in: rippled 2.0.0][] |
| `DeliverMin` | [Currency Amount][] | Amount | _(Optional)_ Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](partial-payments.html). For non-XRP amounts, the nested field names are lower-case. |
| `DeliverMax` | [Currency Amount][] | Amount | [API v2][]: Only available in API v2. The maximum amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [`tfPartialPayment` flag](#payment-flags) is set, deliver _up to_ this amount instead. {% badge href="https://github.com/XRPLF/rippled/releases/tag/2.0.0" %}New in: rippled 2.0.0{% /badge %} |
| `DeliverMin` | [Currency Amount][] | Amount | _(Optional)_ Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](../../../../concepts/payment-types/partial-payments.md). For non-XRP amounts, the nested field names are lower-case. |
| `Destination` | String | AccountID | The unique address of the account receiving the payment. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. |
| `InvoiceID` | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash representing a specific reason or identifier for this payment. |
| `Paths` | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](paths.html) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. |
| `SendMax` | [Currency Amount][] | Amount | _(Optional)_ Highest amount of source currency this transaction is allowed to cost, including [transfer fees](transfer-fees.html), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](transaction-cost.html). For non-XRP amounts, the nested field names MUST be lower-case. Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. |
| `Paths` | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](../../../../concepts/tokens/fungible-tokens/paths.md) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. |
| `SendMax` | [Currency Amount][] | Amount | _(Optional)_ Highest amount of source currency this transaction is allowed to cost, including [transfer fees](../../../../concepts/tokens/transfer-fees.md), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](../../../../concepts/transactions/transaction-cost.md). For non-XRP amounts, the nested field names MUST be lower-case. Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. |
## Types of Payments
@@ -57,16 +57,16 @@ The `Payment` transaction type functions differently depending on how you fill i
| Payment type | `Amount` | `SendMax` | `Paths` | `Account` = `Destination`? | Description |
|:-------------|:----------|:-----------|:----------|:---------------------------|:--|
| [Direct XRP Payment][] | String (XRP) | Omitted | Omitted | No | Transfers XRP directly from one account to another, using one transaction. Always delivers the exact amount. No fee applies other than the basic [transaction cost](transaction-cost.html). |
| [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 can't 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 different currencies, or currencies with the same currency code and different issuers. |
| [Direct XRP Payment][] | String (XRP) | Omitted | Omitted | No | Transfers XRP directly from one account to another, using one transaction. Always delivers the exact amount. No fee applies other than the basic [transaction cost](../../../../concepts/transactions/transaction-cost.md). |
| [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](../../../../concepts/tokens/transfer-fees.md) and [freezes](../../../../concepts/tokens/fungible-tokens/freezes.md) 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 can't both be XRP. These payments [ripple through](../../../../concepts/tokens/fungible-tokens/rippling.md) the issuer and can take longer [paths](../../../../concepts/tokens/fungible-tokens/paths.md) through several intermediaries if the transaction specifies a path set. [Transfer fees](../../../../concepts/tokens/transfer-fees.md) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md) to connect different currencies, or 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. This type of transaction may be classified as an "exchange" and not a "payment". |
| Currency conversion | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Required | Yes | Consumes offers in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md) 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. This type of transaction may be classified as an "exchange" and not a "payment". |
[Direct XRP Payment]: direct-xrp-payments.html
[Creating or redeeming tokens]: tokens.html
[Cross-currency Payment]: cross-currency-payments.html
[Partial payment]: partial-payments.html
[Direct XRP Payment]: ../../../../concepts/payment-types/direct-xrp-payments.md
[Creating or redeeming tokens]: ../../../../concepts/tokens/index.md
[Cross-currency Payment]: ../../../../concepts/payment-types/cross-currency-payments.md
[Partial payment]: ../../../../concepts/payment-types/partial-payments.md
## Special issuer Values for SendMax and Amount
@@ -83,7 +83,7 @@ Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates
The Payment transaction type can create new accounts in the XRP Ledger by sending enough XRP to an unfunded address. Other transactions to unfunded addresses always fail.
For more information, see [Accounts](accounts.html#creating-accounts).
For more information, see [Accounts](../../../../concepts/accounts/accounts.md#creating-accounts).
## Paths
@@ -98,27 +98,27 @@ If the `Paths` field is provided, the server decides at transaction processing t
The `Paths` field must not be an empty array, nor an array whose members are all empty arrays.
For more information, see [Paths](paths.html).
For more information, see [Paths](../../../../concepts/tokens/fungible-tokens/paths.md).
## Payment Flags
Transactions of the Payment type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows:
Transactions of the Payment type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:-------------------|:-------------|:--------------|:-----------------------------|
| `tfNoDirectRipple` | `0x00010000` | 65536 | Do not use the default path; only use paths included in the `Paths` field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this. |
| `tfPartialPayment` | `0x00020000` | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](partial-payments.html) for more details. |
| `tfPartialPayment` | `0x00020000` | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](../../../../concepts/payment-types/partial-payments.md) for more details. |
| `tfLimitQuality` | `0x00040000` | 262144 | Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of `Amount`:`SendMax`. See [Limit Quality](#limit-quality) for details. |
## Partial Payments
A partial payment allows a payment to succeed by reducing the amount received. Partial payments are useful for [returning payments](bouncing-payments.html) without incurring additional costs to oneself. However, partial payments can also be used to exploit integrations that naively assume the `Amount` field of a successful transaction always describes the exact amount delivered.
A partial payment allows a payment to succeed by reducing the amount received. Partial payments are useful for [returning payments](../../../../concepts/payment-types/bouncing-payments.md) without incurring additional costs to oneself. However, partial payments can also be used to exploit integrations that naively assume the `Amount` field of a successful transaction always describes the exact amount delivered.
A partial payment is any [Payment transaction][] with the `tfPartialPayment` flag enabled. A partial payment can be successful if it delivers any positive amount greater than or equal to its `DeliverMin` field (or any positive amount at all if `DeliverMin` is not specified) without sending more than the `SendMax` value.
The [`delivered_amount`](transaction-metadata.html#delivered_amount) field of a payment's metadata indicates the amount of currency actually received by the destination account.
The [`delivered_amount`](../metadata.md#delivered_amount) field of a payment's metadata indicates the amount of currency actually received by the destination account.
For more information, see the full article on [Partial Payments](partial-payments.html).
For more information, see the full article on [Partial Payments](../../../../concepts/payment-types/partial-payments.md).
## Limit Quality
@@ -127,17 +127,14 @@ The XRP Ledger defines the "quality" of a currency exchange as the ratio of the
The [`tfLimitQuality` flag](#payment-flags) allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination `Amount` divided by the `SendMax` amount (the numeric amounts only, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.
By itself, the `tfLimitQuality` flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall *average* quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the [transaction result](transaction-results.html) is `tecPATH_DRY`.
By itself, the `tfLimitQuality` flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall *average* quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the [transaction result](../transaction-results/transaction-results.md) is `tecPATH_DRY`.
Consider the following example. If I am trying to send you 100 Chinese Yuan (`Amount` = 100 CNY) for 20 United States dollars (`SendMax` = 20 USD) or less, then the limit quality is `5`. Imagine one trader is offering ¥95 for $15 (a ratio of about `6.3` CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of `2.5` CNY per USD). If I were to take both offers to send you 100 CNY, then it would cost me 17 USD, for an average quality of about `5.9`.
Without the `tfLimitQuality` flag set, this transaction would succeed, because the $17 it costs me is within my specified `SendMax`. However, with the `tfLimitQuality` flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of `2.5`, which is worse than the limit quality of `5`.
The `tfLimitQuality` flag is most useful when combined with [partial payments](partial-payments.html). When both `tfPartialPayment` and `tfLimitQuality` are set on a transaction, then the transaction delivers as much of the destination `Amount` as it can, without using any conversions that are worse than the limit quality.
The `tfLimitQuality` flag is most useful when combined with [partial payments](../../../../concepts/payment-types/partial-payments.md). When both `tfPartialPayment` and `tfLimitQuality` are set on a transaction, then the transaction delivers as much of the destination `Amount` as it can, without using any conversions that are worse than the limit quality.
In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is different if my transaction has both `tfPartialPayment` and `tfLimitQuality` enabled. If we keep my `SendMax` of 20 USD and a destination `Amount` of 100 CNY, then the limit quality is still `5`. However, because I am doing a partial payment, the transaction sends as much as it can instead of failing if the full destination amount cannot be sent. This means that my transaction consumes the ¥95/$15 offer, whose quality is about `6.3`, but it rejects the ¥5/$2 offer because that offer's quality of `2.5` is worse than the quality limit of `5`. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

15
content/references/protocol/transactions/types/paymentchannelclaim.md
View File

@@ -28,7 +28,7 @@ The **destination address** of a channel 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.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -40,11 +40,11 @@ The **destination address** of a channel can:
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_PaymentChannelClaim%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%229C0CAAC3DD1A74461132DA4451F9E53BDF4C93DFDBEFCE1B10021EC569013B33%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_PaymentChannelClaim%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%229C0CAAC3DD1A74461132DA4451F9E53BDF4C93DFDBEFCE1B10021EC569013B33%22%2C%22binary%22%3Afalse%7D)
<!--{# TODO: replace the above example with one where the channel, public key, signature, and balance match #}-->
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
@@ -56,19 +56,16 @@ The **destination address** of a channel can:
| `Signature` | String | Blob | _(Optional)_ The signature of this claim, as hexadecimal. The signed message contains the channel ID and the amount of the claim. Required unless the sender of the transaction is the source address of the channel. |
| `PublicKey` | String | Blob | _(Optional)_ 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.) |
If the payment channel was created before the [fixPayChanRecipientOwnerDir amendment](known-amendments.html#fixpaychanrecipientownerdir) became enabled (on 2020-05-01), it is possible that the destination of the payment channel has been [deleted](deleting-accounts.html) and does not currently exist in the ledger. If the destination has been deleted, the source account cannot send XRP from the channel to the destination; instead, the transaction fails with `tecNO_DST`. (And, of course, the deleted account cannot send any transactions at all.) Other uses of this transaction type are unaffected when the destination account has been deleted, including adjusting the channel expiration, closing a channel with no XRP, or removing a channel that has passed its expiration time.
If the payment channel was created before the [fixPayChanRecipientOwnerDir amendment](../../../../resources/known-amendments.md#fixpaychanrecipientownerdir) became enabled (on 2020-05-01), it is possible that the destination of the payment channel has been [deleted](../../../../concepts/accounts/deleting-accounts.md) and does not currently exist in the ledger. If the destination has been deleted, the source account cannot send XRP from the channel to the destination; instead, the transaction fails with `tecNO_DST`. (And, of course, the deleted account cannot send any transactions at all.) Other uses of this transaction type are unaffected when the destination account has been deleted, including adjusting the channel expiration, closing a channel with no XRP, or removing a channel that has passed its expiration time.
## PaymentChannelClaim Flags
Transactions of the PaymentChannelClaim type support additional values in the [`Flags` field](transaction-common-fields.html#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 |
|:----------|:-------------|:--------------|:----------------------------------|
| `tfRenew` | `0x00010000` | 65536 | Clear the channel's `Expiration` time. (`Expiration` is different from the channel's immutable `CancelAfter` time.) Only the source address of the payment channel can use this flag. |
| `tfClose` | `0x00020000` | 131072 | Request to close the channel. Only the channel source and destination addresses can use this flag. This flag closes the channel immediately if it has no more XRP allocated to it after processing the current claim, or if the destination address uses it. If the source address uses this flag when the channel still holds XRP, this schedules the channel to close after `SettleDelay` seconds have passed. (Specifically, this sets the `Expiration` of the channel to the close time of the previous ledger plus the channel's `SettleDelay` time, unless the channel already has an earlier `Expiration` time.) If the destination address uses this flag when the channel still holds XRP, any XRP that remains after processing the claim is returned to the source address. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

18
content/references/protocol/transactions/types/paymentchannelcreate.md
View File

@@ -10,9 +10,9 @@ labels:
_Added by the [PayChan amendment][]._
Create a [payment channel](payment-channels.html) and fund it with XRP. The address sending this transaction becomes the "source address" of the payment channel.
Create a [payment channel](../../../../concepts/payment-types/payment-channels.md) and fund it with XRP. The address sending this transaction becomes the "source address" of the payment channel.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -28,9 +28,9 @@ Create a [payment channel](payment-channels.html) and fund it with XRP. The addr
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_PaymentChannelCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22711C4F606C63076137FAE90ADC36379D7066CF551E96DA6FE2BDAB5ECBFACF2B%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_PaymentChannelCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22711C4F606C63076137FAE90ADC36379D7066CF551E96DA6FE2BDAB5ECBFACF2B%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
@@ -39,14 +39,10 @@ Create a [payment channel](payment-channels.html) and fund it with XRP. The addr
| `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. |
| `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](cryptographic-keys.html#key-derivation) <!-- STYLE_OVERRIDE: will --> |
| `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) <!-- STYLE_OVERRIDE: will --> |
| `CancelAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], when this channel expires. Any transaction that would modify the channel after this time closes the channel without otherwise affecting it. This value is immutable; the channel can be closed earlier than this time but cannot remain open after this time. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag to further specify the destination for this payment channel, such as a hosted recipient at the destination address. |
If the `Destination` account is blocking incoming payment channels, the transaction fails with result code `tecNO_PERMISSION`. _(Requires the [DisallowIncoming amendment][] :not_enabled:)_
If the `Destination` account is blocking incoming payment channels, the transaction fails with result code `tecNO_PERMISSION`. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

22
content/references/protocol/transactions/types/paymentchannelfund.md
View File

@@ -10,7 +10,7 @@ labels:
_Added by the [PayChan amendment][]._
Add additional [XRP](what-is-xrp.html) to an open [payment channel](payment-channels.html), and optionally update the expiration time of the channel. Only the source address of the channel can use this transaction.
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.
Example PaymentChannelFund:
@@ -24,33 +24,29 @@ Example PaymentChannelFund:
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_PaymentChannelFund%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22877FA6E2FF8E08597D1F24E30BE8E52D0C9C06F0D620C5721E55622B6A632DFF%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_PaymentChannelFund%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22877FA6E2FF8E08597D1F24E30BE8E52D0C9C06F0D620C5721E55622B6A632DFF%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| 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. |
| `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](paychannel.html). |
| `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
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------------|:-------------------------------------------------|
| `tecINSUFFICIENT_RESERVE` | The sending account has less XRP than the [reserve requirement](reserves.html). |
| `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](known-amendments.html#fixpaychanrecipientownerdir) became enabled (on 2020-05-01). |
| `tecINSUFFICIENT_RESERVE` | The sending account has less XRP than the [reserve requirement](../../../../concepts/accounts/reserves.md). |
| `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](reserves.html). |
| `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. |
| `temBAD_EXPIRATION` | The `Expiration` field is invalid. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

17
content/references/protocol/transactions/types/setregularkey.md
View File

@@ -13,7 +13,7 @@ A `SetRegularKey` transaction assigns, changes, or removes the regular key pair
You can protect your account by assigning a regular key pair to it and using it instead of the master key pair to sign transactions whenever possible. If your regular key pair is compromised, but your master key pair is not, you can use a `SetRegularKey` transaction to regain control of your account.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -25,9 +25,9 @@ You can protect your account by assigning a regular key pair to it and using it
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_SetRegularKey%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%226AA6F6EAAAB56E65F7F738A9A2A8A7525439D65BA990E9BA08F6F4B1C2D349B4%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_SetRegularKey%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%226AA6F6EAAAB56E65F7F738A9A2A8A7525439D65BA990E9BA08F6F4B1C2D349B4%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
@@ -36,13 +36,10 @@ You can protect your account by assigning a regular key pair to it and using it
## See Also
For more information about regular and master key pairs, see [Cryptographic Keys](cryptographic-keys.html).
For more information about regular and master key pairs, see [Cryptographic Keys](../../../../concepts/accounts/cryptographic-keys.md).
For a tutorial on assigning a regular key pair to an account, see [Working with a Regular Key Pair](assign-a-regular-key-pair.html).
For a tutorial on assigning a regular key pair to an account, see [Working with a Regular Key Pair](../../../../tutorials/manage-account-settings/assign-a-regular-key-pair.md).
For even greater security, you can use [multi-signing](multi-signing.html), but multi-signing requires additional XRP for the [transaction cost][] and [reserve](reserves.html).
For even greater security, you can use [multi-signing](../../../../concepts/accounts/multi-signing.md), but multi-signing requires additional XRP for the [transaction cost][] and [reserve](../../../../concepts/accounts/reserves.md).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

23
content/references/protocol/transactions/types/signerlistset.md
View File

@@ -9,9 +9,9 @@ labels:
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/SetSignerList.cpp "Source")
The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to [multi-sign](multi-signing.html) a transaction. This transaction type was introduced by the [MultiSign amendment][].
The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to [multi-sign](../../../../concepts/accounts/multi-signing.md) a transaction. This transaction type was introduced by the [MultiSign amendment][].
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -43,27 +43,24 @@ The SignerListSet transaction creates, replaces, or removes a list of signers th
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_SignerListSet%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%2209A9C86BF20695735AB03620EB1C32606635AC3DA0B70282F37C674FC889EFE7%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_SignerListSet%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%2209A9C86BF20695735AB03620EB1C32606635AC3DA0B70282F37C674FC889EFE7%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:--------------|:----------|:------------------|:-----------------------------|
| `SignerQuorum` | Number | UInt32 | A target number for the signer weights. A multi-signature from this list is valid only if the sum weights of the signatures provided is greater than or equal to this value. To delete a signer list, use the value `0`. |
| `SignerEntries` | Array | Array | _(Omitted when deleting)_ Array of [`SignerEntry` objects](signerlist.html#signer-entry-object), indicating the addresses and weights of signers in this list. This signer list must have at least 1 member and no more than 32 members. No address may appear more than once in the list, nor may the `Account` submitting the transaction appear in the list. _(Updated by the [ExpandedSignerList amendment][].)_ |
| `SignerEntries` | Array | Array | _(Omitted when deleting)_ Array of [`SignerEntry` objects](../../ledger-data/ledger-entry-types/signerlist.md#signer-entry-object), indicating the addresses and weights of signers in this list. This signer list must have at least 1 member and no more than 32 members. No address may appear more than once in the list, nor may the `Account` submitting the transaction appear in the list. _(Updated by the [ExpandedSignerList amendment][].)_ |
A successful SignerListSet transaction replaces the account's [`SignerList` object](signerlist.html) in the ledger, or adds one if it did not exist before. An account may not have more than one signer list. To delete a signer list, you must set `SignerQuorum` to `0` _and_ omit the `SignerEntries` field. Otherwise, the transaction fails with the error [`temMALFORMED`](tem-codes.html). A transaction to delete a signer list is considered successful even if there was no signer list to delete.
A successful SignerListSet transaction replaces the account's [`SignerList` object](../../ledger-data/ledger-entry-types/signerlist.md) in the ledger, or adds one if it did not exist before. An account may not have more than one signer list. To delete a signer list, you must set `SignerQuorum` to `0` _and_ omit the `SignerEntries` field. Otherwise, the transaction fails with the error [`temMALFORMED`](../transaction-results/tem-codes.md). A transaction to delete a signer list is considered successful even if there was no signer list to delete.
You cannot create a signer list such that the `SignerQuorum` could never be met. The `SignerQuorum` must be greater than 0 but less than or equal to the sum of the `SignerWeight` values in the list. Otherwise, the transaction fails with the error [`temMALFORMED`](tem-codes.html).
You cannot create a signer list such that the `SignerQuorum` could never be met. The `SignerQuorum` must be greater than 0 but less than or equal to the sum of the `SignerWeight` values in the list. Otherwise, the transaction fails with the error [`temMALFORMED`](../transaction-results/tem-codes.md).
You can create, update, or remove a signer list using the master key, regular key, or the current signer list, if those methods of signing transactions are available.
You cannot remove the last method of signing transactions from an account. If an account's master key is disabled (the account has the [`lsfDisableMaster` flag](accountroot.html#accountroot-flags) enabled) and the account does not have a [Regular Key](cryptographic-keys.html) configured, then you cannot delete the signer list from the account. Instead, the transaction fails with the error [`tecNO_ALTERNATIVE_KEY`](tec-codes.html).
You cannot remove the last method of signing transactions from an account. If an account's master key is disabled (the account has the [`lsfDisableMaster` flag](../../ledger-data/ledger-entry-types/accountroot.md#accountroot-flags) enabled) and the account does not have a [Regular Key](../../../../concepts/accounts/cryptographic-keys.md) configured, then you cannot delete the signer list from the account. Instead, the transaction fails with the error [`tecNO_ALTERNATIVE_KEY`](../transaction-results/tec-codes.md).
Creating or replacing a signer list enables the `lsfOneOwnerCount` flag on the [SignerList object](signerlist.html). Lists that were created before the [MultiSignReserve amendment][] became enabled do not have this flag and have a higher [owner reserve](reserves.html#owner-reserves). You can decrease the owner reserve for these lists by replacing the list with the same list. For more information, see [SignerList Flags](signerlist.html#signerlist-flags).
Creating or replacing a signer list enables the `lsfOneOwnerCount` flag on the [SignerList object](../../ledger-data/ledger-entry-types/signerlist.md). Lists that were created before the [MultiSignReserve amendment][] became enabled do not have this flag and have a higher [owner reserve](../../../../concepts/accounts/reserves.md#owner-reserves). You can decrease the owner reserve for these lists by replacing the list with the same list. For more information, see [SignerList Flags](../../ledger-data/ledger-entry-types/signerlist.md#signerlist-flags).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

19
content/references/protocol/transactions/types/ticketcreate.md
View File

@@ -11,9 +11,9 @@ labels:
_(Added by the [TicketBatch amendment][].)_
A TicketCreate transaction sets aside one or more [sequence numbers][Sequence Number] as [Tickets](tickets.html).
A TicketCreate transaction sets aside one or more [sequence numbers][Sequence Number] as [Tickets](../../../../concepts/accounts/tickets.md).
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -25,30 +25,27 @@ A TicketCreate transaction sets aside one or more [sequence numbers][Sequence Nu
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_TicketCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22738AEF36B48CA4A2D85C2B74910DC34DDBBCA4C83643F2DB84A58785ED5AD3E3%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_TicketCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22738AEF36B48CA4A2D85C2B74910DC34DDBBCA4C83643F2DB84A58785ED5AD3E3%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:-----------------|:------------------|:-------------------|
| `TicketCount` | Number | UInt32 | How many Tickets to create. This must be a positive number and cannot cause the account to own more than 250 Tickets after executing this transaction. |
If the transaction cannot create _all_ of the requested Tickets (either due to the 250-Ticket limit or the [owner reserve](reserves.html)), it fails and creates no Tickets. To look up how many Tickets an account currently owns, use the [account_info method][] and check the `account_data.TicketCount` field.
If the transaction cannot create _all_ of the requested Tickets (either due to the 250-Ticket limit or the [owner reserve](../../../../concepts/accounts/reserves.md)), it fails and creates no Tickets. To look up how many Tickets an account currently owns, use the [account_info method][] and check the `account_data.TicketCount` field.
**Tip:** This transaction increases the sending account's [sequence number][Sequence Number] by 1 _plus_ the number of tickets created (`TicketCount`). This is the only transaction that increases an account's sequence number by more than 1.
## Error Cases
Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------------|:-------------------------------------------------|
| `temINVALID_COUNT` | The `TicketCount` field is invalid. It must be an integer from 1 to 250. |
| `tecDIR_FULL` | This transaction would cause the account to own more than the limit of 250 Tickets at a time, or more than the maximum number of ledger objects in general. |
| `tecINSUFFICIENT_RESERVE` | The sending account does not have enough XRP to meet the [owner reserve](reserves.html) of all the requested Tickets. |
| `tecINSUFFICIENT_RESERVE` | The sending account does not have enough XRP to meet the [owner reserve](../../../../concepts/accounts/reserves.md) of all the requested Tickets. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

31
content/references/protocol/transactions/types/trustset.md
View File

@@ -9,9 +9,9 @@ labels:
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/SetTrust.cpp "Source")
Create or modify a [trust line](trust-lines-and-issuing.html) linking two accounts.
Create or modify a [trust line](../../../../concepts/tokens/fungible-tokens/index.md) linking two accounts.
## Example {{currentpage.name}} JSON
## Example {% $frontmatter.seo.title %} JSON
```json
{
@@ -29,42 +29,37 @@ Create or modify a [trust line](trust-lines-and-issuing.html) linking two accoun
}
```
[Query example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_TrustSet%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%228566673ECD0A9731C516906E5D2F47129C5C13713602140733831A56CEAE1A05%22%2C%22binary%22%3Afalse%7D)
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_TrustSet%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%228566673ECD0A9731C516906E5D2F47129C5C13713602140733831A56CEAE1A05%22%2C%22binary%22%3Afalse%7D)
{% include '_snippets/tx-fields-intro.md' %}
{% partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-------------------------|:----------|:------------------|:------------------|
| `LimitAmount` | Object | Amount | Object defining the trust line to create or modify, in the format of a [Currency Amount][]. |
| `LimitAmount`.`currency` | String | (Amount.currency) | The currency to this trust line applies to, as a three-letter [ISO 4217 Currency Code](https://www.xe.com/iso4217.php) or a 160-bit hex value according to [currency format](currency-formats.html). "XRP" is invalid. |
| `LimitAmount`.`currency` | String | (Amount.currency) | The currency to this trust line applies to, as a three-letter [ISO 4217 Currency Code](https://www.xe.com/iso4217.php) or a 160-bit hex value according to [currency format](../../data-types/currency-formats.md). "XRP" is invalid. |
| `LimitAmount`.`value` | String | (Amount.value) | Quoted decimal representation of the limit to set on this trust line. |
| `LimitAmount`.`issuer` | String | (Amount.issuer) | The address of the account to extend trust to. |
| `QualityIn` | Number | UInt32 | _(Optional)_ Value incoming balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. |
| `QualityOut` | Number | UInt32 | _(Optional)_ Value outgoing balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. |
If the account specified in `LimitAmount.issuer` is blocking incoming trust lines, the transaction fails with the result code `tecNO_PERMISSION`. _(Requires the [DisallowIncoming amendment][] :not_enabled:)_
If the account specified in `LimitAmount.issuer` is blocking incoming trust lines, the transaction fails with the result code `tecNO_PERMISSION`. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_
## TrustSet Flags
Transactions of the TrustSet type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows:
Transactions of the TrustSet type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:------------------|:-------------|:--------------|:--------------------------|
| `tfSetfAuth` | `0x00010000` | 65536 | Authorize the other party to hold [currency issued by this account](issued-currencies.html). (No effect unless using the [`asfRequireAuth` AccountSet flag](accountset.html#accountset-flags).) Cannot be unset. |
| `tfSetNoRipple` | `0x00020000` | 131072 | Enable the No Ripple flag, which blocks [rippling](rippling.html) between two trust lines of the same currency if this flag is enabled on both. |
| `tfClearNoRipple` | `0x00040000` | 262144 | Disable the No Ripple flag, allowing [rippling](rippling.html) on this trust line. |
| `tfSetFreeze` | `0x00100000` | 1048576 | [Freeze](freezes.html) the trust line. |
| `tfClearFreeze` | `0x00200000` | 2097152 | [Unfreeze](freezes.html) the trust line. |
| `tfSetfAuth` | `0x00010000` | 65536 | Authorize the other party to hold [currency issued by this account](../../../../concepts/tokens/index.md). (No effect unless using the [`asfRequireAuth` AccountSet flag](accountset.md#accountset-flags).) Cannot be unset. |
| `tfSetNoRipple` | `0x00020000` | 131072 | Enable the No Ripple flag, which blocks [rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) between two trust lines of the same currency if this flag is enabled on both. |
| `tfClearNoRipple` | `0x00040000` | 262144 | Disable the No Ripple flag, allowing [rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) on this trust line. |
| `tfSetFreeze` | `0x00100000` | 1048576 | [Freeze](../../../../concepts/tokens/fungible-tokens/freezes.md) the trust line. |
| `tfClearFreeze` | `0x00200000` | 2097152 | [Unfreeze](../../../../concepts/tokens/fungible-tokens/freezes.md) the trust line. |
If a transaction tries to enable No Ripple but cannot, it fails with the result code `tecNO_PERMISSION`. Before the [fix1578 amendment][] became enabled, such a transaction would result in `tesSUCCESS` (making any other changes it could) instead.
The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. An issuer can pre-authorize a trust line with the `tfSetfAuth` flag only, even if the limit and balance of the trust line are 0.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

7
content/references/protocol/transactions/types/xchainaccountcreatecommit.md
View File

@@ -9,7 +9,7 @@ status: not_enabled
# XChainAccountCreateCommit
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L466-L474 "Source")
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
This transaction can only be used for XRP-XRP bridges.
@@ -60,7 +60,4 @@ The `XChainAccountCreateCommit` transaction creates a new account for a witness
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

7
content/references/protocol/transactions/types/xchainaddaccountcreateattestation.md
View File

@@ -9,7 +9,7 @@ status: not_enabled
# XChainAddAccountCreateAttestation
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L447-L464 "Source")
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainAddAccountCreateAttestation` transaction provides an attestation from a witness server that an `XChainAccountCreateCommit` transaction occurred on the other chain.
@@ -77,7 +77,4 @@ Any account can submit signatures.
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/transactions/types/xchainaddclaimattestation.md
View File

@@ -9,7 +9,7 @@ status: not_enabled
# XChainAddClaimAttestation
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L429-L445 "Source")
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainAddClaimAttestation` transaction provides proof from a witness server, attesting to an `XChainCommit` transaction.
@@ -96,8 +96,4 @@ Any account can submit signatures.
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/transactions/types/xchainclaim.md
View File

@@ -9,7 +9,7 @@ status: not_enabled
# XChainClaim
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L418-L427 "Source")
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainClaim` transaction completes a cross-chain transfer of value. It allows a user to claim the value on the destination chain - the equivalent of the value locked on the source chain. A user can only claim the value if they own the cross-chain claim ID associated with the value locked on the source chain (the `Account` field). The user can send the funds to anyone (the `Destination` field). This transaction is only needed if an `OtherChainDestination` isn't specified in the `XChainCommit` transaction, or if something goes wrong with the automatic transfer of funds.
@@ -59,8 +59,4 @@ If the transaction succeeds in moving funds, the referenced `XChainOwnedClaimID`
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/transactions/types/xchaincommit.md
View File

@@ -9,7 +9,7 @@ status: not_enabled
# XChainCommit
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L408-L416 "Source")
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainCommit` is the second step in a cross-chain transfer. It puts assets into trust on the locking chain so that they can be wrapped on the issuing chain, or burns wrapped assets on the issuing chain so that they can be returned on the locking chain.
@@ -55,8 +55,4 @@ The `XChainCommit` is the second step in a cross-chain transfer. It puts assets
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/transactions/types/xchaincreatebridge.md
View File

@@ -9,7 +9,7 @@ status: not_enabled
# XChainCreateBridge
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L381-L388 "Source")
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainCreateBridge` transaction creates a new `Bridge` ledger object and defines a new cross-chain bridge entrance on the chain that the transaction is submitted on. It includes information about door accounts and assets for the bridge.
@@ -60,8 +60,4 @@ The complete production-grade setup would also include a `SignerListSet` transac
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/transactions/types/xchaincreateclaimid.md
View File

@@ -9,7 +9,7 @@ status: not_enabled
# XChainCreateClaimID
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L399-L406 "Source")
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainCreateClaimID` transaction creates a new cross-chain claim ID that is used for a cross-chain transfer. A cross-chain claim ID represents *one* cross-chain transfer of value.
@@ -58,8 +58,4 @@ It also includes the account on the source chain that locks or burns the funds o
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/protocol/transactions/types/xchainmodifybridge.md
View File

@@ -9,7 +9,7 @@ status: not_enabled
# XChainModifyBridge
[[Source]](https://github.com/XRPLF/rippled/blob/develop/src/ripple/protocol/impl/TxFormats.cpp#L390-L397 "Source")
_(Requires the [XChainBridge amendment][] :not_enabled:)_
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainModifyBridge` transaction allows bridge managers to modify the parameters of the bridge. They can only change the `SignatureReward` and the `MinAccountCreateAmount`.
@@ -68,8 +68,4 @@ In addition to the universal transaction flags that are applicable to all transa
|------------------------------|--------------|-------------|
| `tfClearAccountCreateAmount` | `0x00010000` | Clears the `MinAccountCreateAmount` of the bridge. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}