From 6c31d0288c17220d10646ac5c8309a24c4d52552 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 8 May 2018 17:53:00 -0700 Subject: [PATCH 1/3] Add transaction common fields to the reorg --- content/_snippets/rippled-api-links.md | 7 + .../transaction-common-fields.md | 121 ++++++++++++++++++ .../transaction-format-old-monolith.md | 120 ----------------- dactyl-config.yml | 4 +- 4 files changed, 130 insertions(+), 122 deletions(-) create mode 100644 content/references/rippled-api/transaction-formats/transaction-common-fields.md diff --git a/content/_snippets/rippled-api-links.md b/content/_snippets/rippled-api-links.md index 77eaba21d7..b0f5671c07 100644 --- a/content/_snippets/rippled-api-links.md +++ b/content/_snippets/rippled-api-links.md @@ -4,6 +4,10 @@ [XRP, in drops]: reference-rippled-api-conventions.html#specifying-currency-amounts [drops of XRP]: reference-rippled-api-conventions.html#specifying-currency-amounts +[Transaction Cost]: transaction-cost.html +[transaction cost]: transaction-cost.html +[ripple-lib]: https://github.com/ripple/ripple-lib + [Currency Code]: reference-rippled-api-conventions.html#currency-codes [Address]: reference-rippled-api-conventions.html#addresses [Hash]: reference-rippled-api-conventions.html#hashes @@ -25,6 +29,9 @@ [crypto-condition]: https://tools.ietf.org/html/draft-thomas-crypto-conditions-03 [crypto-conditions]: https://tools.ietf.org/html/draft-thomas-crypto-conditions-03 + +[Internal Type]: https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp + {% set api_methods = [ "account_channels", "account_currencies", diff --git a/content/references/rippled-api/transaction-formats/transaction-common-fields.md b/content/references/rippled-api/transaction-formats/transaction-common-fields.md new file mode 100644 index 0000000000..e015456464 --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-common-fields.md @@ -0,0 +1,121 @@ +# Transaction Common Fields + +Every transaction has the same set of common fields, plus additional fields based on the [transaction type][]. Field names are case-sensitive. The common fields for all transactions are: + +| Field | JSON Type | [Internal Type][] | Description | +|:-------------------|:-----------------|:------------------|:-----------------| +| Account | String | Account | _(Required)_ The unique address of the [account](accounts.html) that initiated the transaction. | +| TransactionType | String | UInt16 | _(Required)_ The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, `SetRegularKey`, `SignerListSet`, `EscrowCreate`, `EscrowFinish`, `EscrowCancel`, `PaymentChannelCreate`, `PaymentChannelFund`, and `PaymentChannelClaim`. | +| 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 | Unsigned Integer | UInt32 | _(Required; [auto-fillable][])_ The sequence number, relative to the initiating account, of this transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. For how to use the `Sequence` number to invalidate a pending transaction, see [Canceling or Skipping a Transaction](canceling-or-skipping-a-transaction.html). | +| [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][] | Unsigned Integer | 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. | +| [Memos][] | Array of Objects | Array | _(Optional)_ Additional arbitrary information used to identify this transaction. | +| [Signers][] | Array | Array | _(Optional)_ Array of objects that represent a [multi-signature](#multi-signing) which authorizes this transaction. | +| SourceTag | Unsigned Integer | 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 | PubKey | _(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. | +| TxnSignature | String | VariableLength | _(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 +[AccountTxnID]: #accounttxnid +[Flags]: #flags-field +[Memos]: #memos-field +[Signers]: #signers-field + +[Removed in: rippled 0.28.0][]: The `PreviousTxnID` field of transactions was replaced by the [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). + + +## AccountTxnID + +The `AccountTxnID` field lets you chain your transactions together, so that a current transaction is not valid unless the previous one (by Sequence Number) is also valid and matches the transaction you expected. + +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. + +To use AccountTxnID, you must first set the [asfAccountTxnID](#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. + + +## Auto-fillable Fields + +Some fields can be automatically filled in before a transaction is signed, either by a `rippled` server or by a library used for signing such as [ripple-lib][]. Auto-filling values requires an active connection to the XRP Ledger to get the latest state, so it cannot be done offline. Both [ripple-lib][] and `rippled` can automatically provide the following values: + +* `Fee` - Automatically fill in the [Transaction Cost][] based on the network. + **Note:** When using `rippled`'s [sign command][], you can limit the maximum possible auto-filled value, using the `fee_mult_max` and `fee_mult_div` parameters.) +* `Sequence` - Automatically use the next sequence number for the account sending the transaction. + +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](#paths) of the [Payment](#payment) transaction type can also be automatically filled in. + + +## Flags Field + +The `Flags` field can contain various options that affect how a transaction should behave. The options are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once. + +Most flags only have meaning for a specific transaction type. The same bitwise value may be reused for flags on different transaction types, so it is important to pay attention to the `TransactionType` field when setting and reading flags. + +The only flag that applies globally to all transactions is as follows: + +| Flag Name | Hex Value | Decimal Value | Description | +|:--------------------|:-----------|:--------------|:--------------------------| +| tfFullyCanonicalSig | 0x80000000 | 2147483648 | _(Strongly recommended)_ Require a fully-canonical signature. | + +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. + +**Warning:** If you do not enable `tfFullyCanonicalSig`, it is theoretically possible for a malicious actor to modify your transaction signature so that the transaction may succeed with a different hash than expected. In the worst case, this could trick your integration into submitting the same payment multiple times. To avoid this problem, enable the `tfFullyCanonicalSig` flag on all transactions you sign. + + +## Memos Field + +The `Memos` field includes arbitrary messaging data with the transaction. It is presented as an array of objects. Each object has only one field, `Memo`, which in turn contains another object with *one or more* of the following fields: + +| Field | Type | [Internal Type][] | Description | +|:-----------|:-------|:------------------|:-----------------------------------| +| MemoData | String | VariableLength | Arbitrary hex value, conventionally containing the content of the memo. | +| MemoFormat | String | VariableLength | Hex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a [MIME type](http://www.iana.org/assignments/media-types/media-types.xhtml). | +| MemoType | String | VariableLength | Hex value representing characters allowed in URLs. Conventionally, a unique relation (according to [RFC 5988](http://tools.ietf.org/html/rfc5988#section-4)) that defines the format of this memo. | + +The MemoType and MemoFormat fields should only consist of the following characters: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%` + +The `Memos` field is limited to no more than 1KB in size (when serialized in binary format). + +Example of a transaction with a Memos field: + +``` +{ + "TransactionType": "Payment", + "Account": "rMmTCjGFRWPz8S2zAUUoNVSQHxtRQD4eCx", + "Destination": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV", + "Memos": [ + { + "Memo": { + "MemoType": "687474703a2f2f6578616d706c652e636f6d2f6d656d6f2f67656e65726963", + "MemoData": "72656e74" + } + } + ], + "Amount": "1" +} +``` + + +## Signers Field + +The `Signers` field contains a [multi-signature](#multi-signing), which has signatures from up to 8 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 | +|:--------------|:-------|:------------------|:--------------------------------| +| Account | String | AccountID | The address associated with this signature, as it appears in the SignerList. | +| TxnSignature | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. | +| SigningPubKey | String | PubKey | 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](reference-ledger-format.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. + +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. + + + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md b/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md index 367f3724c4..a86ee5fc3a 100644 --- a/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md +++ b/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md @@ -216,55 +216,10 @@ The `"hash"` is the unique value that identifies a particular transaction. The s The transaction hash can be used as a "proof of payment" since anyone can [look up the transaction by its hash](#looking-up-transaction-results) to verify its final status. -## Common Fields - -[Internal Type]: https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp - -Every transaction type has the same set of fundamental fields. Field names are case-sensitive. The common fields for all transactions are: - -| Field | JSON Type | [Internal Type][] | Description | -|:-----------------------|:-----------------|:------------------|:-------------| -| Account | String | Account | The unique address of the account that initiated the transaction. | -| [AccountTxnID][] | String | Hash256 | _(Optional)_ Hash value identifying another transaction. This transaction is only valid if the sending account's previously-sent transaction matches the provided hash. | -| [Fee][] | String | Amount | (Required, but [auto-fillable](#auto-fillable-fields)) Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network. | -| [Flags][] | Unsigned Integer | UInt32 | _(Optional)_ Set of bit-flags for this transaction. | -| [LastLedgerSequence][] | Number | UInt32 | (Optional, but strongly recommended) Highest ledger sequence number that a transaction can appear in. | -| [Memos][] | Array of Objects | Array | _(Optional)_ Additional arbitrary information used to identify this transaction. | -| PreviousTxnID | String | Hash256 | [Removed in: rippled 0.28.0][] Use `AccountTxnID` instead. | -| [Sequence][] | Unsigned Integer | UInt32 | (Required, but [auto-fillable](#auto-fillable-fields)) The sequence number, relative to the initiating account, of this transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the last-valided transaction from the same account. | -| SigningPubKey | String | PubKey | (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. | -| [Signers][] | Array | Array | _(Optional)_ Array of objects that represent a [multi-signature](#multi-signing) which authorizes this transaction. | -| SourceTag | Unsigned Integer | 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`. | -| TransactionType | String | UInt16 | The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, `SetRegularKey`, `SignerListSet`, `EscrowCreate`, `EscrowFinish`, `EscrowCancel`, `PaymentChannelCreate`, `PaymentChannelFund`, and `PaymentChannelClaim`. | -| TxnSignature | String | VariableLength | (Automatically added when signing) The signature that verifies this transaction as originating from the account it says it is from. | - -[AccountTxnID]: #accounttxnid -[Fee]: #transaction-cost -[Flags]: #flags -[LastLedgerSequence]: #lastledgersequence -[Memos]: #memos -[Sequence]: #canceling-or-skipping-a-transaction -[Signers]: #signers-field - -### Auto-fillable Fields - -Some fields can be automatically filled in before the transaction is signed, either by a `rippled` server or by the library used for offline signing. Both [ripple-lib](https://github.com/ripple/ripple-lib) and `rippled` can automatically provide the following values: - -* `Fee` - Automatically fill in the [transaction cost](concept-transaction-cost.html) based on the network. (*Note:* `rippled`'s [sign command](reference-rippled.html#sign) supports limits on how high the filled-in-value is, using the `fee_mult_max` parameter.) -* `Sequence` - Automatically use the next sequence number for the account sending the transaction. - -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](#paths) of the [Payment](#payment) transaction type can also be automatically filled in. -### Transaction Cost -To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This _[transaction cost](concept-transaction-cost.html)_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network. -The `Fee` field specifies an amount, in [drops of XRP][Currency Amount], to destroy as the cost for relaying this transaction. If the transaction is included in a validated ledger (whether or not it achieves its intended purpose), then the amount of XRP specified in the `Fee` parameter is destroyed forever. You can [look up the transaction cost](concept-transaction-cost.html#querying-the-transaction-cost) in advance, or [let `rippled` set it automatically](concept-transaction-cost.html#automatically-specifying-the-transaction-cost) when you sign a transaction. - -**Note:** [Multi-signed transactions](#multi-signing) require additional fees to relay to the network. ### Canceling or Skipping a Transaction @@ -279,81 +234,6 @@ This approach is preferable to renumbering and resubmitting transactions 12 and In this way, an AccountSet transaction with no options is the canonical "[no-op](http://en.wikipedia.org/wiki/NOP)" transaction. -### LastLedgerSequence - -We strongly recommend that you specify the `LastLedgerSequence` parameter on every transaction. Provide a value of about 3 higher than [the most recent ledger index](reference-rippled.html#ledger) to ensure that your transaction is either validated or rejected within a matter of seconds. - -Without the `LastLedgerSequence` parameter, a transaction can become stuck in an undesirable state where it is neither validated nor rejected for a long time. Specifically, if the load-based [transaction cost](#transaction-cost) of the network increases after you send a transaction, your transaction may not get propagated enough to be included in a validated ledger, but you would have to pay the (increased) transaction cost to [send another transaction canceling it](#canceling-or-skipping-a-transaction). Later, if the transaction cost decreases again, the transaction can become included in a future ledger. The `LastLedgerSequence` places a hard upper limit on how long the transaction can wait to be validated or rejected. - -### AccountTxnID - -The `AccountTxnID` field lets you chain your transactions together, so that a current transaction is not valid unless the previous one (by Sequence Number) is also valid and matches the transaction you expected. - -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. - -To use AccountTxnID, you must first set the [asfAccountTxnID](#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. - -### Memos - -The `Memos` field includes arbitrary messaging data with the transaction. It is presented as an array of objects. Each object has only one field, `Memo`, which in turn contains another object with *one or more* of the following fields: - -| Field | Type | [Internal Type][] | Description | -|:-----------|:-------|:------------------|:-----------------------------------| -| MemoData | String | VariableLength | Arbitrary hex value, conventionally containing the content of the memo. | -| MemoFormat | String | VariableLength | Hex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a [MIME type](http://www.iana.org/assignments/media-types/media-types.xhtml). | -| MemoType | String | VariableLength | Hex value representing characters allowed in URLs. Conventionally, a unique relation (according to [RFC 5988](http://tools.ietf.org/html/rfc5988#section-4)) that defines the format of this memo. | - -The MemoType and MemoFormat fields should only consist of the following characters: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%` - -The `Memos` field is limited to no more than 1KB in size (when serialized in binary format). - -Example of a transaction with a Memos field: - -``` -{ - "TransactionType": "Payment", - "Account": "rMmTCjGFRWPz8S2zAUUoNVSQHxtRQD4eCx", - "Destination": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV", - "Memos": [ - { - "Memo": { - "MemoType": "687474703a2f2f6578616d706c652e636f6d2f6d656d6f2f67656e65726963", - "MemoData": "72656e74" - } - } - ], - "Amount": "1" -} -``` - -### Signers Field - -The `Signers` field contains a [multi-signature](#multi-signing), which has signatures from up to 8 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 | -|:--------------|:-------|:------------------|:--------------------------------| -| Account | String | AccountID | The address associated with this signature, as it appears in the SignerList. | -| TxnSignature | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. | -| SigningPubKey | String | PubKey | 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](reference-ledger-format.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. - -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](concept-transaction-cost.html) 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. - - - -### Flags - -The `Flags` field can contain various options that affect how a transaction should behave. The options are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once. - -Most flags only have meaning for a specific transaction type. The same bitwise value may be reused for flags on different transaction types, so it is important to pay attention to the `TransactionType` field when setting and reading flags. - -The only flag that applies globally to all transactions is as follows: - -| Flag Name | Hex Value | Decimal Value | Description | -|:--------------------|:-----------|:--------------|:--------------------------| -| tfFullyCanonicalSig | 0x80000000 | 2147483648 | Require a fully-canonical signature, to protect a transaction from [transaction malleability](https://wiki.ripple.com/Transaction_Malleability) exploits. | - # Transaction Types diff --git a/dactyl-config.yml b/dactyl-config.yml index 55797dc8f0..e498082e64 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -661,13 +661,13 @@ pages: targets: - local - - name: Transaction Common Fields #TODO: break off from transaction-format-old-monolith.md + - md: references/rippled-api/transaction-formats/transaction-common-fields.md html: transaction-common-fields.html funnel: Docs doc_type: References supercategory: rippled API category: Transaction Formats - blurb: Learn about individual data objects that comprise the XRP Ledger's shared state. + blurb: These common fields can be provided on any XRP Ledger transaction. targets: - local From ffc4a386f32562263c898cebd1a07c70df4e2fa3 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 8 May 2018 19:13:51 -0700 Subject: [PATCH 2/3] Add transaction types to reorg --- content/_snippets/rippled-api-links.md | 1 + content/_snippets/tx-fields-intro.md | 3 + .../concepts/decentralized-exchange/offers.md | 85 ++++++++ .../enableamendment.md | 9 +- .../pseudo-transaction-types.md | 13 ++ .../setfee.md | 7 +- .../transaction-format-old-monolith.md | 23 -- .../transaction-formats.md | 15 +- .../transaction-types/accountset.md | 23 +- .../transaction-types/checkcancel.md | 15 +- .../transaction-types/checkcash.md | 15 +- .../transaction-types/checkcreate.md | 15 +- .../transaction-types/escrowcancel.md | 13 +- .../transaction-types/escrowcreate.md | 14 +- .../transaction-types/escrowfinish.md | 13 +- .../transaction-types/offercancel.md | 15 +- .../transaction-types/offercreate.md | 102 ++------- .../transaction-types/payment.md | 27 ++- .../transaction-types/paymentchannelclaim.md | 15 +- .../transaction-types/paymentchannelcreate.md | 14 +- .../transaction-types/paymentchannelfund.md | 10 +- .../transaction-types/setregularkey.md | 26 ++- .../transaction-types/signerlistset.md | 14 +- .../transaction-types/transaction-types.md | 9 + .../transaction-types/trustset.md | 18 +- dactyl-config.yml | 205 +++++++++++++++++- 26 files changed, 542 insertions(+), 177 deletions(-) create mode 100644 content/_snippets/tx-fields-intro.md create mode 100644 content/concepts/decentralized-exchange/offers.md rename content/references/rippled-api/transaction-formats/{transaction-types => pseudo-transaction-types}/enableamendment.md (89%) create mode 100644 content/references/rippled-api/transaction-formats/pseudo-transaction-types/pseudo-transaction-types.md rename content/references/rippled-api/transaction-formats/{transaction-types => pseudo-transaction-types}/setfee.md (90%) create mode 100644 content/references/rippled-api/transaction-formats/transaction-types/transaction-types.md diff --git a/content/_snippets/rippled-api-links.md b/content/_snippets/rippled-api-links.md index b0f5671c07..2f460d1858 100644 --- a/content/_snippets/rippled-api-links.md +++ b/content/_snippets/rippled-api-links.md @@ -31,6 +31,7 @@ [Internal Type]: https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp +[common fields]: transaction-common-fields.html {% set api_methods = [ "account_channels", diff --git a/content/_snippets/tx-fields-intro.md b/content/_snippets/tx-fields-intro.md new file mode 100644 index 0000000000..ad6bc66913 --- /dev/null +++ b/content/_snippets/tx-fields-intro.md @@ -0,0 +1,3 @@ +## {{currentpage.name}} Fields + +In addition to the [common fields][], a {{currentpage.name}} transaction uses the following fields: diff --git a/content/concepts/decentralized-exchange/offers.md b/content/concepts/decentralized-exchange/offers.md new file mode 100644 index 0000000000..76f8f9e9eb --- /dev/null +++ b/content/concepts/decentralized-exchange/offers.md @@ -0,0 +1,85 @@ +# Offers + +In the XRP Ledger's decentralized exchange, orders to trade currency are called "Offers". Offers can trade XRP with issued currencies, or issued currencies with each other, including issued currencies with the same currency code but different issuers. (Currencies with the same code but different issuers can also sometimes be exchanged through [rippling](rippling.html).) + +- To create an Offer, send an [OfferCreate transaction][]. +- Offers that aren't fully filled immediately become [Offer objects](offer.html) in the ledger data. Later Offers and Payments can consume the Offer object from the ledger. +- [Cross-currency payments](cross-currency-payments.html) consume offers to provide liquidity. + +## Lifecycle of an Offer + +When an OfferCreate transaction is processed, it automatically consumes matching or crossing offers to the extent possible. (If existing offers provide a better rate than requested, the offer creator could pay less than the full `TakerGets` amount to receive the entire `TakerPays` amount.) If that does not completely fulfill the `TakerPays` amount, then the offer becomes an Offer object in the ledger. (You can use [OfferCreate Flags](offercreate.html#offercreate-flags) to modify this behavior.) + +An offer in the ledger can be fulfilled either by additional OfferCreate transactions that match up with the existing offers, or by [Payment transactions][] that use the offer to connect the payment path. Offers can be partially fulfilled and partially funded. A single transaction can consume up to 850 Offers from the ledger. (Any more than that, and the metadata becomes too large, resulting in [`tecOVERSIZE`](#tec-codes).) + +You can create an offer so long as you have at least some (any positive, nonzero amount) of the currency specified by the `TakerGets` parameter of the offer. The offer sells as much of the currency as you have, up to the `TakerGets` amount, until the `TakerPays` amount is satisfied. An offer cannot place anyone in debt. + +It is possible for an offer to become temporarily or permanently _unfunded_: + +* If the creator no longer has any of the `TakerGets` currency. + * The offer becomes funded again when the creator obtains more of that currency. +* If the currency required to fund the offer is held in a [frozen trust line](concept-freeze.html). + * The offer becomes funded again when the trust line is no longer frozen. +* If the creator does not have enough XRP for the reserve amount of a new trust line required by the offer. (See [Offers and Trust](#offers-and-trust).) + * The offer becomes funded again when the creator obtains more XRP, or the reserve requirements decrease. +* If the Expiration time included in the offer is before the close time of the most recently-closed ledger. (See [Expiration](#expiration).) + +An unfunded offer can stay on the ledger indefinitely, but it does not have any effect. The only ways an offer can be *permanently* removed from the ledger are: + +* It becomes fully claimed by a Payment or a matching OfferCreate transaction. +* An OfferCancel or OfferCreate transaction explicitly cancels the offer. +* An OfferCreate transaction from the same account crosses the earlier offer. (In this case, the older offer is automatically canceled.) +* An offer is found to be unfunded during transaction processing, typically because it was at the tip of the orderbook. + * This includes cases where one side or the other of an offer is found to be closer to 0 than `rippled`'s precision supports. + +### Tracking Unfunded Offers + +Tracking the funding status of all offers can be computationally taxing. In particular, addresses that are actively trading may have a large number of offers open. A single balance can affect the funding status of many offers to buy different currencies. Because of this, `rippled` does not proactively find and remove offers. + +A client application can locally track the funding status of offers. To do this, first retreive an order book using the [book_offers method][] and check the `taker_gets_funded` field of offers. Then, [subscribe](reference-rippled.html#subscribe) to the `transactions` stream and watch the transaction metadata to see which offers are modified. + + +## Offers and Trust + +The limit values of trust lines (See [TrustSet](#trustset)) do not affect offers. In other words, you can use an offer to acquire more than the maximum amount you trust an issuer to redeem. + +However, holding non-XRP balances still requires a trust line to the address issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because [trust lines increase the reserve an account must hold](concept-reserves.html), any offers that would require a new trust line also require the address to have enough XRP to meet the reserve for that trust line. + +A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits. + +## Offer Preference + +Existing offers are grouped by exchange rate (sometimes called "offer quality"), which is measured as the ratio between `TakerGets` and `TakerPays`. Offers with a higher exchange rate are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same exchange rate are taken on the basis of which offer was placed in the earliest ledger version. + +When offers of the same exchange rate are placed in the same ledger version, the order in which they are taken is determined by the [canonical order](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/CanonicalTXSet.cpp "Source: Transaction ordering") in which the transactions were [applied to the ledger](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/consensus/LedgerConsensus.cpp#L1435-L1538 "Source: Applying transactions"). This behavior is designed to be deterministic, efficient, and hard to game. + +### TickSize + +_Requires the [TickSize amendment](reference-amendments.html#ticksize)._ + +When an Offer is placed into an order book, its exchange rate is truncated based on the `TickSize` values set by the issuers of the currencies involved in the Offer. When a trader offers to exchange XRP and an issued currency, the `TickSize` from the issuer of the currency applies. When a trader offers to exchange two issued currencies, the offer uses the smaller `TickSize` value (that is, the one with fewer significant digits). If neither currency has a `TickSize` set, the default behavior applies. + +The `TickSize` value truncates the number of _significant digits_ in the exchange rate of an offer when it gets placed in an order book. Issuers can set `TickSize` to an integer from `3` to `15` using an [AccountSet transaction][]. The exchange rate is represented as significant digits and an exponent; the `TickSize` does not affect the exponent. This allows the XRP Ledger to represent exchange rates between assets that vary greatly in value (for example, a hyperinflated currency compared to a rare commodity). The lower the `TickSize` an issuer sets, the larger the increment traders must offer to be considered a higher exchange rate than the existing Offers. + +The `TickSize` does not affect the part of an Offer that can be executed immediately. (For that reason, OfferCreate transactions with `tfImmediateOrCancel` are unaffected by `TickSize` values.) If the Offer cannot be fully executed, the transaction processing engine calculates the exchange rate and truncates it based on `TickSize`. Then, the engine rounds the remaining amount of the Offer from the "less important" side to match the truncated exchange rate. For a default OfferCreate transaction (a "buy" Offer), the `TakerPays` amount (the amount being bought) gets rounded. If the `tfSell` flag is enabled (a "sell" Offer) the `TakerGets` amount (the amount being sold) gets rounded. + +When an issuer enables, disables, or changes the `TickSize`, Offers that were placed under the previous setting are unaffected. + + +## Expiration + +Since transactions can take time to propagate and confirm, the timestamp of a ledger is used to determine offer validity. An offer only expires when its Expiration time is before the most-recently validated ledger. In other words, an offer with an `Expiration` field is still considered "active" if its expiration time is later than the timestamp of the most-recently validated ledger, regardless of what your local clock says. + +You can determine the final disposition of an offer with an `Expiration` as soon as you see a fully-validated ledger with a close time equal to or greater than the expiration time. + +**Note:** Since only new transactions can modify the ledger, an expired offer can stay on the ledger after it becomes inactive. The offer is treated as unfunded and has no effect, but it can continue to appear in results (for example, from the [ledger_entry](reference-rippled.html#ledger-entry) command). Later on, the expired offer can get finally deleted as a result of another transaction (such as another OfferCreate) if the server finds it while processing. + +If an OfferCreate transaction has an `Expiration` time that has already passed when the transaction first gets included in a ledger, the transaction does not execute the offer. The result code of such a transaction depends on whether the [Checks amendment](reference-amendments.html#checks) is enabled. With the Checks amendment enabled, the transaction has the `tecEXPIRED` result code. Otherwise, the transaction has the `tesSUCCESS` transaction code. In either case, the transaction has no effect except to destroy the XRP paid as a [transaction cost](concept-transaction-cost.html). + +## Auto-Bridging + +Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the XRP Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate. + +Example: _Anita places an offer to sell GBP and buy BRL. She might find that this uncommon currency market has few offers. There is one offer with a good rate, but it has insufficient quantity to satisfy Anita's trade. However, both GBP and BRL have active, competitive markets to XRP. Auto-bridging software finds a way to complete Anita's offer by purchasing XRP with GBP from one trader, then selling the XRP to another trader to buy BRL. Anita automatically gets the best rate possible by combining the small offer in the direct GBP:BRL market with the better composite rates created by pairing GBP:XRP and XRP:BRL offers._ + +Auto-bridging happens automatically on any OfferCreate transaction. [Payment transactions](#payment) _do not_ autobridge by default, but path-finding can find paths that have the same effect. diff --git a/content/references/rippled-api/transaction-formats/transaction-types/enableamendment.md b/content/references/rippled-api/transaction-formats/pseudo-transaction-types/enableamendment.md similarity index 89% rename from content/references/rippled-api/transaction-formats/transaction-types/enableamendment.md rename to content/references/rippled-api/transaction-formats/pseudo-transaction-types/enableamendment.md index d7f151a0fd..3ca1524078 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/enableamendment.md +++ b/content/references/rippled-api/transaction-formats/pseudo-transaction-types/enableamendment.md @@ -1,4 +1,4 @@ -## EnableAmendment +# EnableAmendment Tracks the progress of the [amendment process](concept-amendments.html#amendment-process) for changes in transaction processing. This can indicate that a proposed amendment gained or lost majority approval, or that an amendment has been enabled. @@ -9,7 +9,7 @@ Tracks the progress of the [amendment process](concept-amendments.html#amendment | Amendment | String | Hash256 | A unique identifier for the amendment. This is not intended to be a human-readable name. See [Amendments](concept-amendments.html) for a list of known amendments. | | LedgerSequence | Number | UInt32 | The index of the ledger version where this amendment appears. This distinguishes the pseudo-transaction from other occurrences of the same change. | -### EnableAmendment Flags +## EnableAmendment Flags The `Flags` value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction. @@ -19,3 +19,8 @@ A `Flags` value of `0` (no flags) indicates that the amendment has been enabled, |:---------------|:-----------|:--------------|:-------------------------------| | 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. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/pseudo-transaction-types/pseudo-transaction-types.md b/content/references/rippled-api/transaction-formats/pseudo-transaction-types/pseudo-transaction-types.md new file mode 100644 index 0000000000..a46cb94a3d --- /dev/null +++ b/content/references/rippled-api/transaction-formats/pseudo-transaction-types/pseudo-transaction-types.md @@ -0,0 +1,13 @@ +# Pseudo-Transactions + +Pseudo-Transactions are never submitted by users, nor propagated through the network. Instead, a server may choose to inject them in a proposed ledger directly. If enough servers inject an equivalent pseudo-transaction for it to pass consensus, then it becomes included in the ledger, and appears in ledger data thereafter. + +Some of the fields that are mandatory for normal transactions do not make sense for pseudo-transactions. In those cases, the pseudo-transaction has the following default values: + +| Field | Default Value | +|:--------------|:---------------------------------------------------------| +| Account | [ACCOUNT_ZERO](concept-accounts.html#special-addresses) | +| Sequence | 0 | +| Fee | 0 | +| SigningPubKey | "" | +| Signature | "" | diff --git a/content/references/rippled-api/transaction-formats/transaction-types/setfee.md b/content/references/rippled-api/transaction-formats/pseudo-transaction-types/setfee.md similarity index 90% rename from content/references/rippled-api/transaction-formats/transaction-types/setfee.md rename to content/references/rippled-api/transaction-formats/pseudo-transaction-types/setfee.md index 1d9f1d034f..70c63a4678 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/setfee.md +++ b/content/references/rippled-api/transaction-formats/pseudo-transaction-types/setfee.md @@ -1,4 +1,4 @@ -## SetFee +# SetFee A change in [transaction cost](concept-transaction-cost.html) or [account reserve](concept-reserves.html) requirements as a result of [Fee Voting](concept-fee-voting.html). @@ -28,3 +28,8 @@ A change in [transaction cost](concept-transaction-cost.html) or [account reserv | ReserveBase | Unsigned Integer | UInt32 | The base reserve, in drops | | ReserveIncrement | Unsigned Integer | UInt32 | The incremental reserve, in drops | | LedgerSequence | Number | UInt32 | 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/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md b/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md index a86ee5fc3a..66b04fe5f8 100644 --- a/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md +++ b/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md @@ -1,13 +1,5 @@ # Transactions Overview -A _Transaction_ is the only way to modify the XRP Ledger. Transactions are only valid if signed, submitted, and accepted into a validated ledger version following the [consensus process](https://ripple.com/build/ripple-ledger-consensus-process/). Some ledger rules also generate _[pseudo-transactions](#pseudo-transactions)_, 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](concept-transaction-cost.html). - -* [Authorizing Transactions](#authorizing-transactions) -* [Common Fields of All Transactions](#common-fields) -* [Transaction Types](#transaction-types) -* [Reliable Transaction Submission](#reliable-transaction-submission) -* [Transaction Results - How to find and interpret transaction results](#transaction-results) -* [Full Transaction Response List - Complete table of all error codes](#full-transaction-response-list) ## Authorizing Transactions @@ -303,24 +295,9 @@ _Pseudo-Transactions_ that are not created and submitted in the usual way, but m {% include 'transactions/trustset.md' %} -# Pseudo-Transactions - -Pseudo-Transactions are never submitted by users, nor propagated through the network. Instead, a server may choose to inject them in a proposed ledger directly. If enough servers inject an equivalent pseudo-transaction for it to pass consensus, then it becomes included in the ledger, and appears in ledger data thereafter. - -Some of the fields that are mandatory for normal transactions do not make sense for pseudo-transactions. In those cases, the pseudo-transaction has the following default values: - -| Field | Default Value | -|:--------------|:---------------------------------------------------------| -| Account | [ACCOUNT_ZERO](concept-accounts.html#special-addresses) | -| Sequence | 0 | -| Fee | 0 | -| SigningPubKey | "" | -| Signature | "" | -{% include 'transactions/enableamendment.md' %} -{% include 'transactions/setfee.md' %} # Transaction Results diff --git a/content/references/rippled-api/transaction-formats/transaction-formats.md b/content/references/rippled-api/transaction-formats/transaction-formats.md index 512cb6a650..3bdb3d8ff4 100644 --- a/content/references/rippled-api/transaction-formats/transaction-formats.md +++ b/content/references/rippled-api/transaction-formats/transaction-formats.md @@ -1,14 +1,9 @@ # Transaction Formats -Transactions are the only way to modify the XRP Ledger. Get details about their required format. +A _Transaction_ is the only way to modify the XRP Ledger. Transactions are only final if signed, submitted, and accepted into a validated ledger version following the [consensus process](consensus.html). Some ledger rules also generate _[pseudo-transactions](#pseudo-transactions)_, 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][]. -* **[Transaction Common Fields](transaction-common-fields.html)** - -* **[Transaction Types](transaction-types.html)** - - -* **[Transaction Results](transaction-results.html)** - - - + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/accountset.md b/content/references/rippled-api/transaction-formats/transaction-types/accountset.md index 8863223dc8..c8357130de 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/accountset.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/accountset.md @@ -1,12 +1,12 @@ -## AccountSet +# AccountSet [[Source]
](https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/transactors/SetAccount.cpp "Source") An AccountSet transaction modifies the properties of an [account in the XRP Ledger](reference-ledger-format.html#accountroot). -Example AccountSet: +## Example {{currentpage.name}} JSON -``` +```json { "TransactionType": "AccountSet", "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", @@ -18,6 +18,10 @@ Example AccountSet: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + | Field | JSON Type | [Internal Type][] | Description | |:-------------------------------|:-----------------|:------------------|:-----| | [ClearFlag](#accountset-flags) | Unsigned Integer | UInt32 | _(Optional)_ Unique identifier of a flag to disable for this account. | @@ -32,7 +36,7 @@ Example AccountSet: If none of these options are provided, then the AccountSet transaction has no effect (beyond destroying the transaction cost). See [Canceling or Skipping a Transaction](#canceling-or-skipping-a-transaction) for more details. -### Domain +## Domain The `Domain` field is represented as the hex string of the lowercase ASCII of the domain. For example, the domain *example.com* would be represented as `"6578616D706C652E636F6D"`. @@ -40,7 +44,7 @@ To remove the `Domain` field from an account, send an AccountSet with the Domain Client applications can use the [ripple.txt](https://wiki.ripple.com/Ripple.txt) file hosted by the domain to confirm that the account is actually operated by that domain. -### AccountSet Flags +## AccountSet Flags There are several options which can be either enabled or disabled for an account. Account options are represented by different types of flags depending on the situation: @@ -82,7 +86,7 @@ The following [Transaction flags](#flags), specific to the AccountSet transactio **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](reference-ledger-format.html#accountroot-flags). -#### Blocking Incoming Transactions +### Blocking Incoming Transactions Incoming transactions with unclear purposes may be an inconvenience for financial institutions, who would have to recognize when a customer made a mistake, and then potentially refund accounts or adjust balances depending on the mistake. The `asfRequireDest` and `asfDisallowXRP` flags are intended to protect users from accidentally sending funds in a way that is unclear about the reason the funds were sent. @@ -90,8 +94,13 @@ 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 `rippled` because it could potentially cause accounts to become unusable. (If an account did not have enough XRP to send a transaction that disabled the flag, the account would be completely unusable.) Instead, client applications should disallow or discourage XRP payments to accounts with the `asfDisallowXRP` flag enabled. -### TransferRate +## TransferRate The TransferRate field specifies a fee to charge whenever counterparties transfer the currency you issue. See [Transfer Fees](concept-transfer-fees.html) for more information. In `rippled`'s WebSocket and JSON-RPC APIs, the TransferRate 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. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/checkcancel.md b/content/references/rippled-api/transaction-formats/transaction-types/checkcancel.md index d69a7b8f9a..1c3a213d99 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/checkcancel.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/checkcancel.md @@ -1,11 +1,11 @@ -## CheckCancel +# CheckCancel [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/CancelCheck.cpp "Source") _Requires the [Checks Amendment](reference-amendments.html#checks)._ 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 CheckCancel: +## Example {{currentpage.name}} JSON ```json { @@ -16,13 +16,22 @@ Example CheckCancel: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + In addition to the [common fields](#common-fields), a CheckCancel transaction has the following: | Field | JSON Type | [Internal Type][] | Description | |:------------|:----------|:------------------|:-------------------------------| | `CheckID` | String | Hash256 | The ID of the [Check ledger object](reference-ledger-format.html#check) to cancel, as a 64-character hexadecimal string. | -### Error Cases +## 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`. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/checkcash.md b/content/references/rippled-api/transaction-formats/transaction-types/checkcash.md index 75b575d8e6..fff7b0c02f 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/checkcash.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/checkcash.md @@ -1,4 +1,4 @@ -## CheckCash +# CheckCash [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/CashCheck.cpp "Source") _Requires the [Checks Amendment](reference-amendments.html#checks)._ @@ -7,7 +7,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 CheckCash: +## Example {{currentpage.name}} JSON ```json { @@ -19,6 +19,10 @@ Example CheckCash: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + In addition to the [common fields](#common-fields), a CheckCash transaction has the following: | Field | JSON Type | [Internal Type][] | Description | @@ -29,7 +33,7 @@ In addition to the [common fields](#common-fields), a CheckCash transaction has The transaction ***must*** include either `Amount` or `DeliverMin`, but not both. -### Error Cases +## Error Cases - If the sender of the CheckCash transaction is not the `Destination` of the check, the transaction fails with the result code `tecNO_PERMISSION`. - If the Check identified by the `CheckID` field does not exist, the transaction fails with the result `tecNO_ENTRY`. @@ -37,3 +41,8 @@ The transaction ***must*** include either `Amount` or `DeliverMin`, but not both - If the destination of the Check has the RequireDest flag enabled but the Check, as created, does not have a destination tag, the transaction fails with the result code `tecDST_TAG_NEEDED`. - 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`. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/checkcreate.md b/content/references/rippled-api/transaction-formats/transaction-types/checkcreate.md index cb18def612..58681b9253 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/checkcreate.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/checkcreate.md @@ -1,11 +1,11 @@ -## CheckCreate +# CheckCreate [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/CreateCheck.cpp "Source") _Requires the [Checks Amendment](reference-amendments.html#checks)._ 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 CheckCreate: +## Example {{currentpage.name}} JSON ```json { @@ -20,6 +20,10 @@ Example CheckCreate: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + In addition to the [common fields](#common-fields), a CheckCreate transaction has the following: | Field | JSON Type | [Internal Type][] | Description | @@ -30,7 +34,7 @@ In addition to the [common fields](#common-fields), a CheckCreate transaction ha | `Expiration` | Unsigned Integer | UInt32 | _(Optional)_ Time after which the Check is no longer valid, in [seconds since the Ripple Epoch](reference-rippled.html#specifying-time). | | `InvoiceID` | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash representing a specific reason or identifier for this Check. | -### Error Cases +## Error Cases - If the `Destination` is the sender of the transaction, the transaction fails with the result code `temREDUNDANT`. - If the `Destination` [account](concept-accounts.html) does not exist in the ledger, the transaction fails with the result code `tecNO_DST`. @@ -39,3 +43,8 @@ In addition to the [common fields](#common-fields), a CheckCreate transaction ha - 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](concept-reserves.html#owner-reserves) after adding the Check, the transaction fails with the result `tecINSUFFICIENT_RESERVE`. - If either the sender or the destination of the Check cannot own more objects in the ledger, the transaction fails with the result `tecDIR_FULL`. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/escrowcancel.md b/content/references/rippled-api/transaction-formats/transaction-types/escrowcancel.md index e72a3545e3..874186798f 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/escrowcancel.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/escrowcancel.md @@ -1,4 +1,4 @@ -## EscrowCancel +# EscrowCancel [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/Escrow.cpp "Source") @@ -6,7 +6,7 @@ _Requires the [Escrow Amendment](reference-amendments.html#escrow)._ Return escrowed XRP to the sender. -Example EscrowCancel: +## Example {{currentpage.name}} JSON ```json { @@ -17,6 +17,10 @@ Example EscrowCancel: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + | Field | JSON Type | [Internal Type][] | Description | |:----------------|:-----------------|:------------------|:--------------------------| | `Owner` | String | AccountID | Address of the source account that funded the escrow payment. @@ -26,3 +30,8 @@ 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. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/escrowcreate.md b/content/references/rippled-api/transaction-formats/transaction-types/escrowcreate.md index 669e040ef4..69fd19b1f8 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/escrowcreate.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/escrowcreate.md @@ -1,4 +1,4 @@ -## EscrowCreate +# EscrowCreate [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/Escrow.cpp "Source") @@ -6,7 +6,7 @@ _Requires the [Escrow Amendment](reference-amendments.html#escrow)._ Sequester XRP until the escrow process either finishes or is canceled. -Example EscrowCreate: +## Example {{currentpage.name}} JSON ```json { @@ -22,6 +22,10 @@ Example EscrowCreate: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + | Field | JSON Type | [Internal Type][] | Description | |:-----------------|:----------|:------------------|:--------------------------| | `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount], to deduct from the sender's balance and escrow. Once escrowed, the XRP can either go to the `Destination` address (after the `FinishAfter` time) or returned to the sender (after the `CancelAfter` time). | @@ -30,6 +34,10 @@ Example EscrowCreate: | `FinishAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch](reference-rippled.html#specifying-time), when the escrowed XRP can be released to the recipient. This value is immutable; the funds cannot move until this time is reached. | | `Condition` | String | VariableLength | _(Optional)_ Hex value representing a [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1). The funds can only be delivered to the recipient if this condition is fulfilled. | | `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag to further specify the destination for this escrowed payment, such as a hosted recipient at the destination address. | -| `SourceTag` | Number | UInt32 | _(Optional)_ Arbitrary tag to further specify the source for this escrowed payment, such as a hosted sender at the source address. | Either `CancelAfter` or `FinishAfter` must be specified. If both are included, the `FinishAfter` time must precede that of `CancelAfter`. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/escrowfinish.md b/content/references/rippled-api/transaction-formats/transaction-types/escrowfinish.md index c37cf253a0..b8adb203d5 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/escrowfinish.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/escrowfinish.md @@ -1,4 +1,4 @@ -## EscrowFinish +# EscrowFinish [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/Escrow.cpp "Source") @@ -6,7 +6,7 @@ _Requires the [Escrow Amendment](reference-amendments.html#escrow)._ Deliver XRP from a held payment to the recipient. -Example EscrowFinish: +## Example {{currentpage.name}} JSON ```json { @@ -19,6 +19,10 @@ Example EscrowFinish: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + | Field | JSON Type | [Internal Type][] | Description | |:----------------|:-----------------|:------------------|:--------------------------| | `Owner` | String | AccountID | Address of the source account that funded the held payment. @@ -33,3 +37,8 @@ Any account may submit an EscrowFinish transaction. - 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](concept-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](reference-rippled.html#specifying-currency-amounts) plus another 10 drops for every 16 bytes in size of the preimage. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/offercancel.md b/content/references/rippled-api/transaction-formats/transaction-types/offercancel.md index 17ece96340..3b7fbf196d 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/offercancel.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/offercancel.md @@ -1,10 +1,12 @@ -## OfferCancel +# OfferCancel [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CancelOffer.cpp "Source") An OfferCancel transaction removes an Offer object from the XRP Ledger. -``` +## Example {{currentpage.name}} JSON + +```json { "TransactionType": "OfferCancel", "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", @@ -16,6 +18,10 @@ An OfferCancel transaction removes an Offer object from the XRP Ledger. } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + | Field | JSON Type | [Internal Type][] | Description | |:--------------|:-----------------|:------------------|:----------------------| | OfferSequence | Unsigned Integer | UInt32 | The sequence 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. | @@ -23,3 +29,8 @@ An OfferCancel transaction removes an Offer object from the XRP Ledger. *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](#transaction-results) even if it did not find an offer with the matching sequence number. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/offercreate.md b/content/references/rippled-api/transaction-formats/transaction-types/offercreate.md index caaeeba5b8..edbdc1e38a 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/offercreate.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/offercreate.md @@ -1,10 +1,14 @@ -## OfferCreate +# OfferCreate [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp "Source") -An OfferCreate transaction is effectively a [limit order](http://en.wikipedia.org/wiki/limit_order). It defines an intent to exchange currencies, and creates an Offer object in the XRP Ledger if not completely fulfilled when placed. Offers can be partially fulfilled. +An OfferCreate transaction is effectively a [limit order](http://en.wikipedia.org/wiki/limit_order). It defines an intent to exchange currencies, and creates an [Offer object](offer.html) if not completely fulfilled when placed. Offers can be partially fulfilled. -``` +For more information about how Offers work, see [Offers](offers.html). + +## Example {{currentpage.name}} JSON + +```json { "TransactionType": "OfferCreate", "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", @@ -21,6 +25,10 @@ An OfferCreate transaction is effectively a [limit order](http://en.wikipedia.or } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + | Field | JSON Type | [Internal Type][] | Description | |:--------------------------|:--------------------|:------------------|:-------| | [Expiration](#expiration) | Unsigned Integer | UInt32 | _(Optional)_ Time after which the offer is no longer active, in [seconds since the Ripple Epoch](reference-rippled.html#specifying-time). | @@ -28,86 +36,7 @@ An OfferCreate transaction is effectively a [limit order](http://en.wikipedia.or | TakerGets | [Currency Amount][] | Amount | The amount and type of currency being provided by the offer creator. | | TakerPays | [Currency Amount][] | Amount | The amount and type of currency being requested by the offer creator. | -### Lifecycle of an Offer - -When an OfferCreate transaction is processed, it automatically consumes matching or crossing offers to the extent possible. (If existing offers provide a better rate than requested, the offer creator could pay less than the full `TakerGets` amount to receive the entire `TakerPays` amount.) If that does not completely fulfill the `TakerPays` amount, then the offer becomes an Offer object in the ledger. (You can use [OfferCreate Flags](#offercreate-flags) to modify this behavior.) - -An offer in the ledger can be fulfilled either by additional OfferCreate transactions that match up with the existing offers, or by [Payments](#payment) that use the offer to connect the payment path. Offers can be partially fulfilled and partially funded. A single transaction can consume up to 850 Offers from the ledger. (Any more than that, and the metadata becomes too large, resulting in [`tecOVERSIZE`](#tec-codes).) - -You can create an offer so long as you have at least some (any positive, nonzero amount) of the currency specified by the `TakerGets` parameter of the offer. The offer sells as much of the currency as you have, up to the `TakerGets` amount, until the `TakerPays` amount is satisfied. An offer cannot place anyone in debt. - -It is possible for an offer to become temporarily or permanently _unfunded_: - -* If the creator no longer has any of the `TakerGets` currency. - * The offer becomes funded again when the creator obtains more of that currency. -* If the currency required to fund the offer is held in a [frozen trust line](concept-freeze.html). - * The offer becomes funded again when the trust line is no longer frozen. -* If the creator does not have enough XRP for the reserve amount of a new trust line required by the offer. (See [Offers and Trust](#offers-and-trust).) - * The offer becomes funded again when the creator obtains more XRP, or the reserve requirements decrease. -* If the Expiration time included in the offer is before the close time of the most recently-closed ledger. (See [Expiration](#expiration).) - -An unfunded offer can stay on the ledger indefinitely, but it does not have any effect. The only ways an offer can be *permanently* removed from the ledger are: - -* It becomes fully claimed by a Payment or a matching OfferCreate transaction. -* An OfferCancel or OfferCreate transaction explicitly cancels the offer. -* An OfferCreate transaction from the same account crosses the earlier offer. (In this case, the older offer is automatically canceled.) -* An offer is found to be unfunded during transaction processing, typically because it was at the tip of the orderbook. - * This includes cases where one side or the other of an offer is found to be closer to 0 than `rippled`'s precision supports. - -#### Tracking Unfunded Offers - -Tracking the funding status of all offers can be computationally taxing. In particular, addresses that are actively trading may have a large number of offers open. A single balance can affect the funding status of many offers to buy different currencies. Because of this, `rippled` does not proactively find and remove offers. - -A client application can locally track the funding status of offers. To do this, first retreive an order book using the [book_offers method][] and check the `taker_gets_funded` field of offers. Then, [subscribe](reference-rippled.html#subscribe) to the `transactions` stream and watch the transaction metadata to see which offers are modified. - - -### Offers and Trust - -The limit values of trust lines (See [TrustSet](#trustset)) do not affect offers. In other words, you can use an offer to acquire more than the maximum amount you trust an issuer to redeem. - -However, holding non-XRP balances still requires a trust line to the address issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because [trust lines increase the reserve an account must hold](concept-reserves.html), any offers that would require a new trust line also require the address to have enough XRP to meet the reserve for that trust line. - -A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits. - -### Offer Preference - -Existing offers are grouped by exchange rate (sometimes called "offer quality"), which is measured as the ratio between `TakerGets` and `TakerPays`. Offers with a higher exchange rate are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same exchange rate are taken on the basis of which offer was placed in the earliest ledger version. - -When offers of the same exchange rate are placed in the same ledger version, the order in which they are taken is determined by the [canonical order](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/CanonicalTXSet.cpp "Source: Transaction ordering") in which the transactions were [applied to the ledger](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/consensus/LedgerConsensus.cpp#L1435-L1538 "Source: Applying transactions"). This behavior is designed to be deterministic, efficient, and hard to game. - -#### TickSize - -_Requires the [TickSize amendment](reference-amendments.html#ticksize)._ - -When an Offer is placed into an order book, its exchange rate is truncated based on the `TickSize` values set by the issuers of the currencies involved in the Offer. When a trader offers to exchange XRP and an issued currency, the `TickSize` from the issuer of the currency applies. When a trader offers to exchange two issued currencies, the offer uses the smaller `TickSize` value (that is, the one with fewer significant digits). If neither currency has a `TickSize` set, the default behavior applies. - -The `TickSize` value truncates the number of _significant digits_ in the exchange rate of an offer when it gets placed in an order book. Issuers can set `TickSize` to an integer from `3` to `15` using an [AccountSet transaction][]. The exchange rate is represented as significant digits and an exponent; the `TickSize` does not affect the exponent. This allows the XRP Ledger to represent exchange rates between assets that vary greatly in value (for example, a hyperinflated currency compared to a rare commodity). The lower the `TickSize` an issuer sets, the larger the increment traders must offer to be considered a higher exchange rate than the existing Offers. - -The `TickSize` does not affect the part of an Offer that can be executed immediately. (For that reason, OfferCreate transactions with `tfImmediateOrCancel` are unaffected by `TickSize` values.) If the Offer cannot be fully executed, the transaction processing engine calculates the exchange rate and truncates it based on `TickSize`. Then, the engine rounds the remaining amount of the Offer from the "less important" side to match the truncated exchange rate. For a default OfferCreate transaction (a "buy" Offer), the `TakerPays` amount (the amount being bought) gets rounded. If the `tfSell` flag is enabled (a "sell" Offer) the `TakerGets` amount (the amount being sold) gets rounded. - -When an issuer enables, disables, or changes the `TickSize`, Offers that were placed under the previous setting are unaffected. - - -### Expiration - -Since transactions can take time to propagate and confirm, the timestamp of a ledger is used to determine offer validity. An offer only expires when its Expiration time is before the most-recently validated ledger. In other words, an offer with an `Expiration` field is still considered "active" if its expiration time is later than the timestamp of the most-recently validated ledger, regardless of what your local clock says. - -You can determine the final disposition of an offer with an `Expiration` as soon as you see a fully-validated ledger with a close time equal to or greater than the expiration time. - -**Note:** Since only new transactions can modify the ledger, an expired offer can stay on the ledger after it becomes inactive. The offer is treated as unfunded and has no effect, but it can continue to appear in results (for example, from the [ledger_entry](reference-rippled.html#ledger-entry) command). Later on, the expired offer can get finally deleted as a result of another transaction (such as another OfferCreate) if the server finds it while processing. - -If an OfferCreate transaction has an `Expiration` time that has already passed when the transaction first gets included in a ledger, the transaction does not execute the offer. The result code of such a transaction depends on whether the [Checks amendment](reference-amendments.html#checks) is enabled. With the Checks amendment enabled, the transaction has the `tecEXPIRED` result code. Otherwise, the transaction has the `tesSUCCESS` transaction code. In either case, the transaction has no effect except to destroy the XRP paid as a [transaction cost](concept-transaction-cost.html). - -### Auto-Bridging - -Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the XRP Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate. - -Example: _Anita places an offer to sell GBP and buy BRL. She might find that this uncommon currency market has few offers. There is one offer with a good rate, but it has insufficient quantity to satisfy Anita's trade. However, both GBP and BRL have active, competitive markets to XRP. Auto-bridging software finds a way to complete Anita's offer by purchasing XRP with GBP from one trader, then selling the XRP to another trader to buy BRL. Anita automatically gets the best rate possible by combining the small offer in the direct GBP:BRL market with the better composite rates created by pairing GBP:XRP and XRP:BRL offers._ - -Auto-bridging happens automatically on any OfferCreate transaction. [Payment transactions](#payment) _do not_ autobridge by default, but path-finding can find paths that have the same effect. - - -### OfferCreate Flags +## OfferCreate Flags Transactions of the OfferCreate type support additional values in the [`Flags` field](#flags), as follows: @@ -122,4 +51,9 @@ The following invalid flag combination prompts a `temINVALID_FLAG` error: * tfImmediateOrCancel and tfFillOrKill -**Note:** When an OfferCreate uses tfImmediateOrCancel or tfFillOrKill and the offer cannot be executed when placed, the transaction may conclude "successfully" without trading any currency or having any effect on the order books. In this case, the transaction has the [result code](#result-categories) `tesSUCCESS`, it pays the [transaction cost](concept-transaction-cost.html) and uses up a `Sequence` number, but has no other effect. +**Note:** When an OfferCreate uses tfImmediateOrCancel or tfFillOrKill and the offer cannot be executed when placed, the transaction may conclude "successfully" without trading any currency or having any effect on the order books. In this case, the transaction has the [result code](#result-categories) `tesSUCCESS`, it pays the [transaction cost][] and uses up a `Sequence` number, but has no other effect. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/payment.md b/content/references/rippled-api/transaction-formats/transaction-types/payment.md index 5ff3117b7b..a55dced3cc 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/payment.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/payment.md @@ -1,13 +1,13 @@ -## Payment +# Payment [[Source]
](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/Payment.cpp "Source") A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, this can involve additional exchanges of value, which occur atomically.) Payments are also the only way to [create accounts](#creating-accounts). -Example payment: +## Example {{currentpage.name}} JSON -``` +```json { "TransactionType" : "Payment", "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", @@ -23,6 +23,10 @@ Example payment: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + | Field | JSON Type | [Internal Type][] | Description | |:---------------|:---------------------|:------------------|:-----------------| | Amount | [Currency Amount][] | Amount | The 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. | @@ -33,7 +37,7 @@ Example payment: | SendMax | [Currency Amount][] | Amount | _(Optional)_ Highest amount of source currency this transaction is allowed to cost, including [transfer fees](concept-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). 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. | | DeliverMin | [Currency Amount][] | Amount | _(Optional)_ Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](#partial-payments). For non-XRP amounts, the nested field names are lower-case. | -### Special issuer Values for SendMax and Amount +## Special issuer Values for SendMax and Amount Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates a financial institution's [issuing address](concept-issuing-and-operational-addresses.html). However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment. @@ -41,13 +45,13 @@ Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates * When the `issuer` field of the destination `Amount` field matches the `Destination` address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has extended trust lines, as well as issuances created by the destination which are held on other trust lines. * When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new issuances on trust lines that other accounts have extended to the source account, and sending issuances the source account holds from other issuers. -### Creating Accounts +## Creating Accounts 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](concept-accounts.html#creating-accounts). -### Paths +## Paths If present, the `Paths` field must contain a _path set_ - an array of path arrays. Each individual path represents one way value can flow from the sender to receiver through various intermediary accounts and order books. A single transaction can potentially use multiple paths, for example if the transaction exchanges currency using several different order books to achieve the best rate. @@ -62,7 +66,7 @@ The `Paths` field must not be an empty array, nor an array whose members are all For more information, see [Paths](concept-paths.html). -### Payment Flags +## Payment Flags Transactions of the Payment type support additional values in the [`Flags` field](#flags), as follows: @@ -72,7 +76,7 @@ Transactions of the Payment type support additional values in the [`Flags` field | 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) 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 +## Partial Payments A partial payment allows a payment to succeed by reducing the amount received. Partial payments are useful for [returning payments](tutorial-gateway-guide.html#bouncing-payments) 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. @@ -83,7 +87,7 @@ The [`delivered_amount`](#delivered-amount) field of a payment's metadata indica For more information, see the full article on [Partial Payments](concept-partial-payments.html). -### Limit Quality +## Limit Quality The XRP Ledger defines the "quality" of a currency exchange as the ratio of the numeric amount in to the numeric amount out. For example, if you spend $2 USD to receive £1 GBP, then the "quality" of that exchange is `0.5`. @@ -98,3 +102,8 @@ Without the tfLimitQuality flag set, this transaction would succeed, because the The tfLimitQuality flag is most useful when combined with [partial payments](#partial-payments). 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. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelclaim.md b/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelclaim.md index 38dee02ab9..45209e4618 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelclaim.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelclaim.md @@ -1,4 +1,4 @@ -## PaymentChannelClaim +# PaymentChannelClaim [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/PayChan.cpp "Source") _Requires the [PayChan Amendment](reference-amendments.html#paychan)._ @@ -21,7 +21,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 PaymentChannelClaim: +## Example {{currentpage.name}} JSON ```json { @@ -35,6 +35,10 @@ Example PaymentChannelClaim: +{% include '_snippets/tx-fields-intro.md' %} + + + | Field | JSON Type | [Internal Type][] | Description | |:------------|:----------|:------------------|:-------------------------------| | `Channel` | String | Hash256 | The unique ID of the channel, as a 64-character hexadecimal string. | @@ -44,7 +48,7 @@ Example PaymentChannelClaim: | `PublicKey` | String | PubKey | _(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 PubKey so that `rippled` can check the validity of the signature before trying to apply the transaction to the ledger.) | -### PaymentChannelClaim Flags +## PaymentChannelClaim Flags Transactions of the PaymentChannelClaim type support additional values in the [`Flags` field](#flags), as follows: @@ -52,3 +56,8 @@ Transactions of the PaymentChannelClaim type support additional values in the [` |:----------|:-----------|:--------------|:------------------------------------| | `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. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelcreate.md b/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelcreate.md index 17d51b01dc..c679a5c6cc 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelcreate.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelcreate.md @@ -1,11 +1,11 @@ -## PaymentChannelCreate +# PaymentChannelCreate [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/PayChan.cpp "Source") _Requires the [PayChan Amendment](reference-amendments.html#paychan)._ Create a unidirectional channel and fund it with XRP. The address sending this transaction becomes the "source address" of the payment channel. -Example PaymentChannelCreate: +## Example {{currentpage.name}} JSON ```json { @@ -21,6 +21,10 @@ Example PaymentChannelCreate: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + + | Field | JSON Type | [Internal Type][] | Description | |:-----------------|:----------|:------------------|:--------------------------| | `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount], to deduct from the sender's balance and set aside in this channel. While the channel is open, the XRP can only go to the `Destination` address. When the channel closes, any unclaimed XRP is returned to the source address's balance. | @@ -29,4 +33,8 @@ Example PaymentChannelCreate: | `PublicKey` | String | PubKey | The 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. | | `CancelAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch](reference-rippled.html#specifying-time), 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. | -| `SourceTag` | Number | UInt32 | _(Optional)_ Arbitrary tag to further specify the source for this payment channel, such as a hosted sender at the source address. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelfund.md b/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelfund.md index c67b30e834..ae9ed0a723 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelfund.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/paymentchannelfund.md @@ -1,4 +1,4 @@ -## PaymentChannelFund +# PaymentChannelFund [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/PayChan.cpp "Source") _Requires the [PayChan Amendment](reference-amendments.html#paychan)._ @@ -17,8 +17,16 @@ Example PaymentChannelFund: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + | 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. To set the expiration for a channel without adding more XRP, set this to `"0"`. | | `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 in formation, see the [PayChannel ledger object type](reference-ledger-format.html#paychannel). | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/setregularkey.md b/content/references/rippled-api/transaction-formats/transaction-types/setregularkey.md index 86a5db575e..cd23b963ce 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/setregularkey.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/setregularkey.md @@ -1,4 +1,4 @@ -## SetRegularKey +# SetRegularKey [[Source]
](https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp "Source") @@ -6,13 +6,9 @@ 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. -For more information about regular and master key pairs, see [Cryptographic Keys](concept-cryptographic-keys.html). +## Example {{currentpage.name}} JSON -For a tutorial on assigning a regular key pair to an account, see [Working with a Regular Key Pair](tutorial-regular-keys.html). - -For even greater security, you can use [multi-signing](#multi-signing), but multi-signing requires additional XRP for the [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html). - -``` +```json { "Flags": 0, "TransactionType": "SetRegularKey", @@ -22,6 +18,22 @@ For even greater security, you can use [multi-signing](#multi-signing), but mult } ``` +{% include '_snippets/tx-fields-intro.md' %} + + | Field | JSON Type | [Internal Type][] | Description | |:-------------|:----------|:------------------|:------------------------------| | `RegularKey` | String | AccountID | _(Optional)_ A base-58-encoded [Ripple address](reference-rippled.html#addresses) that indicates the regular key pair to be assigned to the account. If omitted, removes any existing regular key pair from the account. | + +## See Also + +For more information about regular and master key pairs, see [Cryptographic Keys](cryptographic-keys.html). + +For a tutorial on assigning a regular key pair to an account, see [Working with a Regular Key Pair](working-with-a-regular-key-pair.html). + +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). + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/signerlistset.md b/content/references/rippled-api/transaction-formats/transaction-types/signerlistset.md index 0b5360fc7f..3bc5e9859b 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/signerlistset.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/signerlistset.md @@ -1,11 +1,11 @@ -## SignerListSet +# SignerListSet [[Source]
](https://github.com/ripple/rippled/blob/ef511282709a6a0721b504c6b7703f9de3eecf38/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) a transaction. This transaction type was introduced by the [MultiSign amendment](reference-amendments.html#multisign). [New in: rippled 0.31.0][] -Example SignerListSet: +## Example {{currentpage.name}} JSON -``` +```json { "Flags": 0, "TransactionType": "SignerListSet", @@ -35,6 +35,9 @@ Example SignerListSet: } ``` +{% include '_snippets/tx-fields-intro.md' %} + + | 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 SignerList, use the value `0`. | @@ -47,3 +50,8 @@ You cannot create a SignerList such that the SignerQuorum could never be met. Th You can create, update, or remove a SignerList using the master key, regular key, or the current SignerList, 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 (it has the [`lsfDisableMaster` flag](reference-ledger-format.html#accountroot-flags) enabled) and the account does not have a [Regular Key](#setregularkey) configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error [`tecNO_ALTERNATIVE_KEY`](#tec-codes). + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/transaction-types.md b/content/references/rippled-api/transaction-formats/transaction-types/transaction-types.md new file mode 100644 index 0000000000..f4bffec743 --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-types/transaction-types.md @@ -0,0 +1,9 @@ +# Transaction Types + +The type of a transaction (`TransactionType` field) is the most fundamental information about a transaction. This indicates what type of operation the transaction is supposed to do. + +All transactions have certain fields in common: + +* [Common Fields](transaction-common-fields.html) + +Each transaction type has additional fields relevant to the type of action it causes. diff --git a/content/references/rippled-api/transaction-formats/transaction-types/trustset.md b/content/references/rippled-api/transaction-formats/transaction-types/trustset.md index be8a6bedd4..d77eba7526 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/trustset.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/trustset.md @@ -1,10 +1,12 @@ -## TrustSet +# TrustSet [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/SetTrust.cpp "Source") Create or modify a trust line linking two accounts. -``` +## Example {{currentpage.name}} JSON + +```json { "TransactionType": "TrustSet", "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", @@ -20,6 +22,9 @@ Create or modify a trust line linking two accounts. } ``` +{% include '_snippets/tx-fields-intro.md' %} + + | Field | JSON Type | [Internal Type][] | Description | |:-----------------------------|:-----------------|:------------------|:-------| | [LimitAmount](#trust-limits) | Object | Amount | Object defining the trust line to create or modify, in the format of a [Currency Amount][]. | @@ -29,7 +34,7 @@ Create or modify a trust line linking two accounts. | QualityIn | Unsigned Integer | 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 | Unsigned Integer | 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. | -### Trust Limits +## Trust Limits All balances on the XRP Ledger, except for XRP, represent value owed in the world outside the XRP Ledger. The address that issues those funds in the XRP Ledger (identified by the `issuer` field of the `LimitAmount` object) is expected to pay the balance back, outside of the XRP Ledger, when users redeem their XRP Ledger balances by returning them to the issuer. @@ -45,7 +50,7 @@ The default state of all flags is off, except for the [NoRipple flag](concept-no 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. -### TrustSet Flags +## TrustSet Flags Transactions of the TrustSet type support additional values in the [`Flags` field](#flags), as follows: @@ -56,3 +61,8 @@ Transactions of the TrustSet type support additional values in the [`Flags` fiel | tfClearNoRipple | 0x00040000 | 262144 | Clears the No-Rippling flag. (See [NoRipple](concept-noripple.html) for details.) | | tfSetFreeze | 0x00100000 | 1048576 | [Freeze](concept-freeze.html) the trustline. | | tfClearFreeze | 0x00200000 | 2097152 | [Unfreeze](concept-freeze.html) the trustline. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/dactyl-config.yml b/dactyl-config.yml index e498082e64..9ceab65b05 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -671,13 +671,15 @@ pages: targets: - local - - name: Transaction Types #TODO: pull landing content from transaction-format-old-monolith.md + - md: references/rippled-api/transaction-formats/transaction-types/transaction-types.md html: transaction-types.html funnel: Docs doc_type: References supercategory: rippled API category: Transaction Formats subcategory: Transaction Types + blurb: All the different types of transactions that the XRP Ledger can process. + template: template-landing-children.html targets: - local @@ -688,10 +690,208 @@ pages: supercategory: rippled API category: Transaction Formats subcategory: Transaction Types + blurb: Set options on an account. targets: - local - # TODO: 17 other transaction types + - md: references/rippled-api/transaction-formats/transaction-types/checkcancel.md + html: checkcancel.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Cancel a check. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/checkcash.md + html: checkcash.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Redeem a check. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/checkcreate.md + html: checkcreate.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Create a check. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/escrowcancel.md + html: escrowcancel.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Reclaim escrowed XRP. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/escrowcreate.md + html: escrowcreate.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Create an escrowed XRP payment. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/escrowfinish.md + html: escrowfinish.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Deliver escrowed XRP to recipient. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/offercancel.md + html: offercancel.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Withdraw a currency-exchange order. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/offercreate.md + html: offercreate.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Submit an order to exchange currency. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/payment.md + html: payment.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Send funds from one account to another. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/paymentchannelclaim.md + html: paymentchannelclaim.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Claim money from a payment channel. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/paymentchannelcreate.md + html: paymentchannelcreate.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Open a new payment channel. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/paymentchannelfund.md + html: paymentchannelfund.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Add more XRP to a payment channel. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/setregularkey.md + html: setregularkey.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Add, remove, or modify an account's regular key pair. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/signerlistset.md + html: signerlistset.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Add, remove, or modify an account's multi-signing list. + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-types/trustset.md + html: trustset.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Types + blurb: Add or modify a trust line. + targets: + - local + + - md: references/rippled-api/transaction-formats/pseudo-transaction-types/pseudo-transaction-types.md + html: pseudo-transaction-types.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Pseudo-Transaction Types + blurb: Formats of pseudo-transactions that validators sometimes apply to the XRP Ledger. + template: template-landing-children.html + targets: + - local + + - md: references/rippled-api/transaction-formats/pseudo-transaction-types/enableamendment.md + html: enableamendment.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Pseudo-Transaction Types + blurb: Enable a change in transaction processing. + targets: + - local + + - md: references/rippled-api/transaction-formats/pseudo-transaction-types/setfee.md + html: setfee.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Pseudo-Transaction Types + blurb: Change global reserve and transaction cost settings. + targets: + - local - name: Transaction Results #TODO: pull landing content from transaction-format-old-monolith.md html: transaction-results.html @@ -700,6 +900,7 @@ pages: supercategory: rippled API category: Transaction Formats subcategory: Transaction Results + blurb: All possible transaction result codes and their meanings. targets: - local From 3191adfc6add3eb5dc5d7d57cdc34a72cec37812 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 9 May 2018 12:00:11 -0700 Subject: [PATCH 3/3] Add transaction results to reorg --- .../transaction-format-old-monolith.md | 242 ------------------ .../transaction-metadata.md | 33 +++ .../transaction-results/tec-codes.md | 48 ++++ .../transaction-results/tef-codes.md | 31 +++ .../transaction-results/tel-codes.md | 26 ++ .../transaction-results/tem-codes.md | 46 ++++ .../transaction-results/ter-codes.md | 24 ++ .../transaction-results/tes-success.md | 12 + .../transaction-results.md | 48 ++++ dactyl-config.yml | 63 ++++- 10 files changed, 329 insertions(+), 244 deletions(-) create mode 100644 content/references/rippled-api/transaction-formats/transaction-metadata.md create mode 100644 content/references/rippled-api/transaction-formats/transaction-results/tec-codes.md create mode 100644 content/references/rippled-api/transaction-formats/transaction-results/tef-codes.md create mode 100644 content/references/rippled-api/transaction-formats/transaction-results/tel-codes.md create mode 100644 content/references/rippled-api/transaction-formats/transaction-results/tem-codes.md create mode 100644 content/references/rippled-api/transaction-formats/transaction-results/ter-codes.md create mode 100644 content/references/rippled-api/transaction-formats/transaction-results/tes-success.md create mode 100644 content/references/rippled-api/transaction-formats/transaction-results/transaction-results.md diff --git a/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md b/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md index 66b04fe5f8..452a0c3693 100644 --- a/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md +++ b/content/references/rippled-api/transaction-formats/transaction-format-old-monolith.md @@ -302,28 +302,6 @@ _Pseudo-Transactions_ that are not created and submitted in the usual way, but m # Transaction Results -## Immediate Response - -The response from the [submit method][] contains a provisional result from the `rippled` server indicating what happened during local processing of the transaction. - -The response from `submit` contains the following fields: - -| Field | Value | Description | -|:------------------------|:---------------|:----------------------------------| -| `engine_result` | String | A code that categorizes the result, such as `tecPATH_DRY` | -| `engine_result_code` | Signed Integer | A number that corresponds to the `engine_result`, although exact values are subject to change. | -| `engine_result_message` | String | A human-readable message explaining what happened. This message is intended for developers to diagnose problems, and is subject to change without notice. | - -If nothing went wrong when submitting and applying the transaction locally, the response looks like this: - -```js - "engine_result": "tesSUCCESS", - "engine_result_code": 0, - "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) for details. - ## Looking up Transaction Results To see the final result of a transaction, use the [tx method][], [account_tx method][], or other response from `rippled`. Look for `"validated": true` to indicate that this response uses a ledger version that has been validated by consensus. @@ -342,22 +320,6 @@ To see the final result of a transaction, use the [tx method][], [account_tx met "validated": true ``` -## Result Categories - -Both the `engine_result` and the `meta.TransactionResult` use standard codes to identify the results of transactions, as follows: - -| Category | Prefix | Description | -|:----------------------|:--------------------|:-------------------------------| -| Local error | [tel](#tel-codes) | 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) | The transaction was not valid, due to improper syntax, conflicting options, a bad signature, or something else. | -| Failure | [tef](#tef-codes) | 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. | -| Retry | [ter](#ter-codes) | The transaction could not be applied, but it might be possible to apply later. | -| Success | [tes](#tes-success) | (Not an error) The transaction succeeded. This result only final in a validated ledger. | -| Claimed cost only | [tec](#tec-codes) | The transaction did not achieve its intended purpose, but the [transaction cost](concept-transaction-cost.html) was destroyed. This result is only final in a validated ledger. | - -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. - -By contrast, a `tem` error implies that no server anywhere can apply the transaction, regardless of settings. Either the transaction breaks the rules of the protocol, it is unacceptably ambiguous, or it is completely nonsensical. The only way a malformed transaction could become valid is through changes in the protocol; for example, if a new feature is adopted, then transactions using that feature could be considered malformed by servers that are running older software which predates that feature. ## Claimed Cost Justification @@ -384,207 +346,3 @@ For any other result code, it can be difficult to determine if the result is fin | `tefMAX_LEDGER` | Final when a validated ledger has a sequence number higher than the transaction's `LastLedgerSequence` field, and no validated ledger includes the transaction | Any other transaction result is potentially not final. In that case, the transaction could still succeed or fail later, especially if conditions change such that the transaction is no longer prevented from applying. For example, trying to send a non-XRP currency to an account that does not exist yet would fail, but it could succeed if another transaction sends enough XRP to create the destination account. A server might even store a temporarily-failed, signed transaction and then successfully apply it later without asking first. - - - -## Understanding Transaction Metadata - -The metadata section of a transaction includes detailed information about all the changes to the shared XRP Ledger that the transaction caused. This is true of any transaction that gets included in a ledger, whether or not it is successful. Naturally, the changes are only final if the transaction is validated. - -Some fields that may appear in transaction metadata include: - -| Field | Value | Description | -|:--------------------------------------|:--------------------|:---------------| -| `AffectedNodes` | Array | List of [ledger objects](reference-ledger-format.html#ledger-object-types) that were created, deleted, or modified by this transaction, and specific changes to each. | -| `DeliveredAmount` | [Currency Amount][] | **DEPRECATED.** Replaced by `delivered_amount`. Omitted if not a partial payment. | -| `TransactionIndex` | Unsigned Integer | The transaction's position within the ledger that included it. (For example, the value `2` means it was the 2nd transaction in that ledger.) | -| `TransactionResult` | String | A [result code](#result-categories) indicating whether the transaction succeeded or how it failed. | -| [`delivered_amount`](#delivered-amount) | [Currency Amount][] | The [Currency Amount][] actually received by the `Destination` account. Use this field to determine how much was delivered, regardless of whether the transaction is a [partial payment](#partial-payments). [New in: rippled 0.27.0][] | - -### 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)**. (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 `delivered_amount` field of transaction metadata is included in all successful Payment transactions, and is formatted like a normal currency amount. However, the delivered amount is not available for transactions that meet both of the following criteria: - -* Is a partial payment, and -* Included in a validated ledger before 2014-01-20 - -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. - -See also: [Partial Payments](concept-partial-payments.html) - -## Full Transaction Response List - -[[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/TER.h "Source") - - -### tel Codes - -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, 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) and [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html). - -| 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 too long. | -| `telCAN_NOT_QUEUE` | The transaction did not meet the [open ledger cost](concept-transaction-cost.html), but this server did not queue this transaction because it did not meet the [queuing restrictions](concept-transaction-cost.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](concept-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. [New in: rippled 0.70.2][] | -| `telCAN_NOT_QUEUE_BLOCKS` | The transaction did not meet the [open ledger cost](concept-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 by changing authorization methods. (This includes all [SetRegularKey][] and [SignerListSet][] transactions, as well as [AccountSet][] transactions that change the RequireAuth/OptionalAuth, DisableMaster, or AccountTxnID flags.) You can try again later, or try submitting to a different server. [New in: rippled 0.70.2][] | -| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](concept-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. (This includes all [SetRegularKey][] and [SignerListSet][] transactions, as well as [AccountSet][] transactions that change the RequireAuth/OptionalAuth, DisableMaster, or AccountTxnID flags.) You can try again later, or try submitting to a different server. [New in: rippled 0.70.2][] | -| `telCAN_NOT_QUEUE_FEE` | The transaction did not meet the [open ledger cost](concept-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](concept-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. [New in: rippled 0.70.2][] | -| `telCAN_NOT_QUEUE_FULL` | The transaction did not meet the [open ledger cost](concept-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](concept-transaction-cost.html#fee-levels), than the transaction in the queue with the smallest transaction cost. [New in: rippled 0.70.2][] | -| `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](concept-transaction-cost.html) requirement, which is derived from its load level. | -| `telLOCAL_ERROR` | Unspecified local error. | -| `telNO_DST`_`PARTIAL` | The transaction is an XRP payment that would fund a new account, but the [tfPartialPayment flag](#partial-payments) was enabled. This is disallowed. | - -### tem Codes - -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](concept-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.) - -| Code | Explanation | -|:-----------------------------|:----------------------------------------------| -| `temBAD_AMOUNT` | An amount specified by the transaction (for example the destination `Amount` or `SendMax` values of a [Payment](#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](#setregularkey) 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. | -| `temBAD_ISSUER` | The transaction improperly specified the `issuer` field of some currency included in the request. | -| `temBAD_LIMIT` | The [TrustSet transaction][] improperly specified the `LimitAmount` value of a trustline. | -| `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](#payment) transaction specifies one or more [Paths](#paths) improperly, for example including an issuer for XRP, or specifying an account differently. | -| `temBAD_PATH_LOOP` | One of the [Paths](#paths) in the [Payment](#payment) transaction was flagged as a loop, so it cannot be processed in a bounded amount of time. | -| `temBAD_SEND_XRP_LIMIT` | The [Payment](#payment) transaction used the [tfLimitQuality](#limit-quality) flag in a direct XRP-to-XRP payment, even though XRP-to-XRP payments do not involve any conversions. | -| `temBAD_SEND_XRP_MAX` | The [Payment](#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](#payment) transaction used the [tfNoDirectRipple](#payment-flags) flag for a direct XRP-to-XRP payment, even though XRP-to-XRP payments are always direct. | -| `temBAD_SEND_XRP_PARTIAL` | The [Payment](#payment) transaction used the [tfPartialPayment](#partial-payments) flag 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](#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) 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](concept-accounts.html) address. | -| `temBAD_TRANSFER_RATE` | The [`TransferRate` field of an AccountSet transaction](#transferrate) is not properly formatted or out of the acceptable range. | -| `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](#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_FLAG` | The transaction includes a [Flag](#flags) 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][] | -| `temRIPPLE_EMPTY` | The [Payment](#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](concept-amendments.html) that is not enabled for the current ledger. | - - -### tef Codes - -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) and [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html). - -| 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](#setregularkey).) | -| `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/ripple/rippled/issues) to get it fixed. | -| `tefBAD_QUORUM` | The transaction was [multi-signed](#multi-signing), but the total weights of all included signatures did not meet the quorum. | -| `tefBAD_SIGNATURE` | The transaction was [multi-signed](#multi-signing), 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/ripple/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/ripple/rippled/issues) to get it fixed. | -| `tefINVARIANT_FAILED` | An invariant check failed when trying to claim the [transaction cost](concept-transaction-cost.html). Requires the [EnforceInvariants amendment](reference-amendments.html#enforceinvariants). If you can reproduce this error, please [report an issue](https://github.com/ripple/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`](#lastledgersequence) parameter, but the current ledger's sequence number is already higher than the specified value. | -| `tefNO_AUTH_REQUIRED` | The [TrustSet transaction][] tried to mark a trustline as authorized, but the `lsfRequireAuth` flag is not enabled for the corresponding account, so authorization is not necessary. | -| `tefNOT_MULTI_SIGNING` | The transaction was [multi-signed](#multi-signing), 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. | -| `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. | - -### ter Codes - -These codes indicate that the transaction failed, but it could apply successfully in the future, usually if some other hypothetical transaction applies first. They have numerical values in the range -99 to -1. The exact code for any given error is subject to change, so don't rely on it. - -**Caution:** Transactions with `ter` 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) and [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html). - -| Code | Explanation | -|:-----------------|:----------------------------------------------------------| -| `terFUNDS_SPENT` | **DEPRECATED.** | -| `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_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-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. | -| `terRETRY` | Unspecified retriable error. | -| `terQUEUED` | The transaction met the load-scaled [transaction cost](concept-transaction-cost.html) but did not meet the open ledger requirement, so the transaction has been queued for a future ledger. | - -### tes Success - -The code `tesSUCCESS` is the only code that indicates a transaction succeeded. This does not always mean it accomplished what you expected it to do. (For example, an [OfferCancel][] can "succeed" even if there is no offer for it to cancel.) The `tesSUCCESS` result uses the numerical value 0. - -| Code | Explanation | -|:-----------|:----------------------------------------------------------------| -| `tesSUCCESS` | The transaction was applied and forwarded to other servers. If this appears in a validated ledger, then the transaction's success is final. | - -### tec Codes - -These codes indicate that the transaction failed, but it was applied to a ledger to apply the [transaction cost](concept-transaction-cost.html). They have numerical values in the range 100 to 199. Ripple recommends using the text code, not the numeric value. - -For the most part, transactions with `tec` codes take no action other than to destroy the XRP paid as a [transaction cost](concept-transaction-cost.html), but there are some exceptions. As an exception, a transaction that results in `tecOVERSIZE` still cleans up some [unfunded offers](#lifecycle-of-an-offer). Always look at the [transaction metadata](#understanding-transaction-metadata) 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) and [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html). - -| Code | Value | Explanation | -|:---------------------------|:------|:----------------------------------------| -| `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. | -| `tecDST_TAG_NEEDED` | 143 | The [Payment](#payment) transaction omitted a destination tag, but the destination account has the `lsfRequireDestTag` flag enabled. [New in: rippled 0.28.0][] | -| `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](concept-freeze.html). | -| `tecINSUF_RESERVE_LINE` | 122 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](concept-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](concept-reserves.html)) | -| `tecINSUFFICIENT_RESERVE` | 141 | The transaction would increase the [reserve requirement](concept-reserves.html) higher than the sending account's balance. [SignerListSet][], [PaymentChannelCreate][], [PaymentChannelFund][], and [EscrowCreate][] can return this error code. See [SignerLists and Reserves](reference-ledger-format.html#signerlists-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/ripple/rippled/issues). | -| `tecINVARIANT_FAILED` | 147 | An invariant check failed when trying to execute this transaction. Requires the [EnforceInvariants amendment](reference-amendments.html#enforceinvariants). If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues). | -| `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-flags). [New in: rippled 0.28.0][] | -| `tecNO_ALTERNATIVE_KEY` | 130 | The transaction tried to remove the only available method of [authorizing transactions](#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 | Reserved for future use. | -| `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](concept-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_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](#authorizing-transactions). If [multi-signing](#multi-signing) is enabled, this code is deprecated and `tecNO_ALTERNATIVE_KEY` is used instead. | -| `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. | -| `tecOVERSIZE` | 145 | This transaction could not be processed, because the server created an excessively large amount of metadata when it tried to apply the transaction. [New in: rippled 0.29.0-hf1][] | -| `tecOWNERS` | 132 | 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-flags) flag if it has any trust lines or available offers. | -| `tecPATH_DRY` | 128 | The transaction failed because the provided paths 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. | -| `tecPATH_PARTIAL` | 101 | The transaction failed because the provided paths did not have enough liquidity to send the full amount. | -| `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 necessary to execute this transaction. (See: [Reserves](concept-reserves.html)) | -| `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. (See: [Reserves](concept-reserves.html)) | -| `tecUNFUNDED_OFFER` | 103 | The [OfferCreate transaction][] failed because the account creating the offer does not have any of the `TakerGets` currency. | - - -{% include '_snippets/rippled_versions.md' %} -{% include '_snippets/tx-type-links.md' %} - -[Currency Amount]: reference-rippled.html#specifying-currency-amounts diff --git a/content/references/rippled-api/transaction-formats/transaction-metadata.md b/content/references/rippled-api/transaction-formats/transaction-metadata.md new file mode 100644 index 0000000000..a5cd18fa7b --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-metadata.md @@ -0,0 +1,33 @@ +# Transaction Metadata + +Transaction metadata is a section of data that gets added to a transaction after it is processed. Any transaction that gets included in a ledger has metadata, regardless of whether it is successful. The transaction metadata describes the outcome of the transaction in detail. + +**Warning:** The changes described in transaction metadata are only final if the transaction is in a validated ledger version. + +Some fields that may appear in transaction metadata include: + +| Field | Value | Description | +|:--------------------------------------|:--------------------|:---------------| +| `AffectedNodes` | Array | List of [ledger objects](ledger-object-types.html) that were created, deleted, or modified by this transaction, and specific changes to each. | +| `DeliveredAmount` | [Currency Amount][] | **DEPRECATED.** Replaced by `delivered_amount`. Omitted if not a partial payment. | +| `TransactionIndex` | Unsigned Integer | The transaction's position within the ledger that included it. (For example, the value `2` means it was the 2nd transaction in that ledger.) | +| `TransactionResult` | String | A [result code](transaction-results.html) indicating whether the transaction succeeded or how it failed. | +| [`delivered_amount`](#delivered-amount) | [Currency Amount][] | The [Currency Amount][] actually received by the `Destination` account. Use this field to determine how much was delivered, regardless of whether the transaction is a [partial payment](partial-payments.html). [New in: rippled 0.27.0][] | + +## 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 `delivered_amount` field of transaction metadata is included in all successful Payment transactions, and is formatted like a normal currency amount. However, the delivered amount is not available for transactions that meet both of the following criteria: + +* Is a partial payment +* Included in a validated ledger before 2014-01-20 + +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. + +See also: [Partial Payments](partial-payments.html) + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-results/tec-codes.md b/content/references/rippled-api/transaction-formats/transaction-results/tec-codes.md new file mode 100644 index 0000000000..b63f775abc --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-results/tec-codes.md @@ -0,0 +1,48 @@ +# tec Codes + +These codes indicate that the transaction failed, but it was applied to a ledger to apply the [transaction cost](concept-transaction-cost.html). They have numerical values in the range 100 to 199. Ripple recommends using the text code, not the numeric value. + +For the most part, transactions with `tec` codes take no action other than to destroy the XRP paid as a [transaction cost](concept-transaction-cost.html), but there are some exceptions. As an exception, a transaction that results in `tecOVERSIZE` still cleans up some [unfunded offers](#lifecycle-of-an-offer). Always look at the [transaction metadata](#understanding-transaction-metadata) 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) and [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html). + +| Code | Value | Explanation | +|:---------------------------|:------|:----------------------------------------| +| `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. | +| `tecDST_TAG_NEEDED` | 143 | The [Payment](#payment) transaction omitted a destination tag, but the destination account has the `lsfRequireDestTag` flag enabled. [New in: rippled 0.28.0][] | +| `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](concept-freeze.html). | +| `tecINSUF_RESERVE_LINE` | 122 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](concept-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](concept-reserves.html)) | +| `tecINSUFFICIENT_RESERVE` | 141 | The transaction would increase the [reserve requirement](concept-reserves.html) higher than the sending account's balance. [SignerListSet][], [PaymentChannelCreate][], [PaymentChannelFund][], and [EscrowCreate][] can return this error code. See [SignerLists and Reserves](reference-ledger-format.html#signerlists-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/ripple/rippled/issues). | +| `tecINVARIANT_FAILED` | 147 | An invariant check failed when trying to execute this transaction. Requires the [EnforceInvariants amendment](reference-amendments.html#enforceinvariants). If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues). | +| `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-flags). [New in: rippled 0.28.0][] | +| `tecNO_ALTERNATIVE_KEY` | 130 | The transaction tried to remove the only available method of [authorizing transactions](#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 | Reserved for future use. | +| `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](concept-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_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](#authorizing-transactions). If [multi-signing](#multi-signing) is enabled, this code is deprecated and `tecNO_ALTERNATIVE_KEY` is used instead. | +| `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. | +| `tecOVERSIZE` | 145 | This transaction could not be processed, because the server created an excessively large amount of metadata when it tried to apply the transaction. [New in: rippled 0.29.0-hf1][] | +| `tecOWNERS` | 132 | 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-flags) flag if it has any trust lines or available offers. | +| `tecPATH_DRY` | 128 | The transaction failed because the provided paths 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. | +| `tecPATH_PARTIAL` | 101 | The transaction failed because the provided paths did not have enough liquidity to send the full amount. | +| `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 necessary to execute this transaction. (See: [Reserves](concept-reserves.html)) | +| `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. (See: [Reserves](concept-reserves.html)) | +| `tecUNFUNDED_OFFER` | 103 | The [OfferCreate transaction][] failed because the account creating the offer does not have any of the `TakerGets` currency. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-results/tef-codes.md b/content/references/rippled-api/transaction-formats/transaction-results/tef-codes.md new file mode 100644 index 0000000000..33752c7aaf --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-results/tef-codes.md @@ -0,0 +1,31 @@ +# tef Codes + +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) and [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html). + +| 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](#setregularkey).) | +| `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/ripple/rippled/issues) to get it fixed. | +| `tefBAD_QUORUM` | The transaction was [multi-signed](#multi-signing), but the total weights of all included signatures did not meet the quorum. | +| `tefBAD_SIGNATURE` | The transaction was [multi-signed](#multi-signing), 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/ripple/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/ripple/rippled/issues) to get it fixed. | +| `tefINVARIANT_FAILED` | An invariant check failed when trying to claim the [transaction cost](concept-transaction-cost.html). Requires the [EnforceInvariants amendment](reference-amendments.html#enforceinvariants). If you can reproduce this error, please [report an issue](https://github.com/ripple/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`](#lastledgersequence) parameter, but the current ledger's sequence number is already higher than the specified value. | +| `tefNO_AUTH_REQUIRED` | The [TrustSet transaction][] tried to mark a trustline as authorized, but the `lsfRequireAuth` flag is not enabled for the corresponding account, so authorization is not necessary. | +| `tefNOT_MULTI_SIGNING` | The transaction was [multi-signed](#multi-signing), 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. | +| `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. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-results/tel-codes.md b/content/references/rippled-api/transaction-formats/transaction-results/tel-codes.md new file mode 100644 index 0000000000..0bff1a5240 --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-results/tel-codes.md @@ -0,0 +1,26 @@ +# tel Codes + +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, 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) and [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html). + +| 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 too long. | +| `telCAN_NOT_QUEUE` | The transaction did not meet the [open ledger cost](concept-transaction-cost.html), but this server did not queue this transaction because it did not meet the [queuing restrictions](concept-transaction-cost.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](concept-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. [New in: rippled 0.70.2][] | +| `telCAN_NOT_QUEUE_BLOCKS` | The transaction did not meet the [open ledger cost](concept-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 by changing authorization methods. (This includes all [SetRegularKey][] and [SignerListSet][] transactions, as well as [AccountSet][] transactions that change the RequireAuth/OptionalAuth, DisableMaster, or AccountTxnID flags.) You can try again later, or try submitting to a different server. [New in: rippled 0.70.2][] | +| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](concept-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. (This includes all [SetRegularKey][] and [SignerListSet][] transactions, as well as [AccountSet][] transactions that change the RequireAuth/OptionalAuth, DisableMaster, or AccountTxnID flags.) You can try again later, or try submitting to a different server. [New in: rippled 0.70.2][] | +| `telCAN_NOT_QUEUE_FEE` | The transaction did not meet the [open ledger cost](concept-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](concept-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. [New in: rippled 0.70.2][] | +| `telCAN_NOT_QUEUE_FULL` | The transaction did not meet the [open ledger cost](concept-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](concept-transaction-cost.html#fee-levels), than the transaction in the queue with the smallest transaction cost. [New in: rippled 0.70.2][] | +| `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](concept-transaction-cost.html) requirement, which is derived from its load level. | +| `telLOCAL_ERROR` | Unspecified local error. | +| `telNO_DST`_`PARTIAL` | The transaction is an XRP payment that would fund a new account, but the [tfPartialPayment flag](#partial-payments) was enabled. This is disallowed. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-results/tem-codes.md b/content/references/rippled-api/transaction-formats/transaction-results/tem-codes.md new file mode 100644 index 0000000000..a5e6da10ee --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-results/tem-codes.md @@ -0,0 +1,46 @@ +# tem Codes + +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](concept-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.) + +| Code | Explanation | +|:-----------------------------|:----------------------------------------------| +| `temBAD_AMOUNT` | An amount specified by the transaction (for example the destination `Amount` or `SendMax` values of a [Payment](#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](#setregularkey) 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. | +| `temBAD_ISSUER` | The transaction improperly specified the `issuer` field of some currency included in the request. | +| `temBAD_LIMIT` | The [TrustSet transaction][] improperly specified the `LimitAmount` value of a trustline. | +| `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](#payment) transaction specifies one or more [Paths](#paths) improperly, for example including an issuer for XRP, or specifying an account differently. | +| `temBAD_PATH_LOOP` | One of the [Paths](#paths) in the [Payment](#payment) transaction was flagged as a loop, so it cannot be processed in a bounded amount of time. | +| `temBAD_SEND_XRP_LIMIT` | The [Payment](#payment) transaction used the [tfLimitQuality](#limit-quality) flag in a direct XRP-to-XRP payment, even though XRP-to-XRP payments do not involve any conversions. | +| `temBAD_SEND_XRP_MAX` | The [Payment](#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](#payment) transaction used the [tfNoDirectRipple](#payment-flags) flag for a direct XRP-to-XRP payment, even though XRP-to-XRP payments are always direct. | +| `temBAD_SEND_XRP_PARTIAL` | The [Payment](#payment) transaction used the [tfPartialPayment](#partial-payments) flag 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](#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) 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](concept-accounts.html) address. | +| `temBAD_TRANSFER_RATE` | The [`TransferRate` field of an AccountSet transaction](#transferrate) is not properly formatted or out of the acceptable range. | +| `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](#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_FLAG` | The transaction includes a [Flag](#flags) 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][] | +| `temRIPPLE_EMPTY` | The [Payment](#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](concept-amendments.html) that is not enabled for the current ledger. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-results/ter-codes.md b/content/references/rippled-api/transaction-formats/transaction-results/ter-codes.md new file mode 100644 index 0000000000..728f9f7f3a --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-results/ter-codes.md @@ -0,0 +1,24 @@ +# ter Codes + +These codes indicate that the transaction failed, but it could apply successfully in the future, usually if some other hypothetical transaction applies first. They have numerical values in the range -99 to -1. The exact code for any given error is subject to change, so don't rely on it. + +**Caution:** Transactions with `ter` 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) and [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html). + +| Code | Explanation | +|:-----------------|:----------------------------------------------------------| +| `terFUNDS_SPENT` | **DEPRECATED.** | +| `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_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-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. | +| `terRETRY` | Unspecified retriable error. | +| `terQUEUED` | The transaction met the load-scaled [transaction cost](concept-transaction-cost.html) but did not meet the open ledger requirement, so the transaction has been queued for a future ledger. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-results/tes-success.md b/content/references/rippled-api/transaction-formats/transaction-results/tes-success.md new file mode 100644 index 0000000000..254ee87f75 --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-results/tes-success.md @@ -0,0 +1,12 @@ +# tes Success + +The code `tesSUCCESS` is the only code that indicates a transaction succeeded. This does not always mean it accomplished what you expected it to do. (For example, an [OfferCancel][] can "succeed" even if there is no offer for it to cancel.) The `tesSUCCESS` result uses the numerical value 0. + +| Code | Explanation | +|:-----------|:----------------------------------------------------------------| +| `tesSUCCESS` | The transaction was applied and forwarded to other servers. If this appears in a validated ledger, then the transaction's success is final. | + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-results/transaction-results.md b/content/references/rippled-api/transaction-formats/transaction-results/transaction-results.md new file mode 100644 index 0000000000..f1747134e3 --- /dev/null +++ b/content/references/rippled-api/transaction-formats/transaction-results/transaction-results.md @@ -0,0 +1,48 @@ +# Transaction Results + +[[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/TER.h "Source") + +The `rippled` server summarizes transaction results with result codes, which appear in fields such as `engine_result` and `meta.TransactionResult`. These codes are grouped into several categories of with different prefixes: + +| Category | Prefix | Description | +|:----------------------|:------------------------|:---------------------------| +| 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. | +| 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. | +| Retry | [ter](ter-codes.html) | The transaction could not be applied, but it might be possible to apply later. | +| 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.html) | The transaction did not achieve its intended purpose, but the [transaction cost](concept-transaction-cost.html) was destroyed. This result is only final in a validated ledger. | + +**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. + +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. + +By contrast, a `tem` error implies that no server anywhere can apply the transaction, regardless of settings. Either the transaction breaks the rules of the protocol, it is unacceptably ambiguous, or it is completely nonsensical. The only way a malformed transaction could become valid is through changes in the protocol; for example, if a new feature is adopted, then transactions using that feature could be considered malformed by servers that are running older software which predates that feature. + + +## Immediate Response + +The response from the [submit method][] contains a provisional result from the `rippled` server indicating what happened during local processing of the transaction. + +The response from `submit` contains the following fields: + +| Field | Value | Description | +|:------------------------|:---------------|:----------------------------------| +| `engine_result` | String | A code that categorizes the result, such as `tecPATH_DRY` | +| `engine_result_code` | Signed Integer | A number that corresponds to the `engine_result`, although exact values are subject to change. | +| `engine_result_message` | String | A human-readable message explaining what happened. This message is intended for developers to diagnose problems, and is subject to change without notice. | + +If nothing went wrong when submitting and applying the transaction locally, the response looks like this: + +```js + "engine_result": "tesSUCCESS", + "engine_result_code": 0, + "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) for details. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/dactyl-config.yml b/dactyl-config.yml index 9ceab65b05..ac5a252162 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -893,7 +893,7 @@ pages: targets: - local - - name: Transaction Results #TODO: pull landing content from transaction-format-old-monolith.md + - md: references/rippled-api/transaction-formats/transaction-results/transaction-results.md html: transaction-results.html funnel: Docs doc_type: References @@ -904,7 +904,27 @@ pages: targets: - local - - name: tel Codes #TODO: break off content from transaction-format-old-monolith.md + - md: references/rippled-api/transaction-formats/transaction-results/tec-codes.md + html: tec-codes.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Results + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-results/tef-codes.md + html: tef-codes.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Results + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-results/tel-codes.md html: tel-codes.html funnel: Docs doc_type: References @@ -914,6 +934,45 @@ pages: targets: - local + - md: references/rippled-api/transaction-formats/transaction-results/tem-codes.md + html: tem-codes.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Results + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-results/ter-codes.md + html: ter-codes.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Results + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-results/tes-success.md + html: tes-success.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + subcategory: Transaction Results + targets: + - local + + - md: references/rippled-api/transaction-formats/transaction-metadata.md + html: transaction-metadata.html + funnel: Docs + doc_type: References + supercategory: rippled API + category: Transaction Formats + targets: + - local + # TODO: 5 other result code classes # --------------- end "rippled API" section --------------------------------