ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 19:55:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

tx format - alphabetize tx types

Browse Source
This commit is contained in:
mDuo13
2016-11-22 14:05:08 -08:00
committed by Rome Reginelli
parent 3a67b0acd9
commit 55cffe3090
2 changed files with 559 additions and 540 deletions
Download Patch File Download Diff File Expand all files Collapse all files

462
content/reference-transaction-format.md
View File

@@ -1,27 +1,10 @@
# Transactions # # Transactions Overview #
A *Transaction* is the only way to modify the Ripple Ledger. All transactions have certain fields in common: A _Transaction_ is the only way to modify the Ripple 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).
* [Common Fields](#common-fields) * [Authorizing Transactions](#authorizing-transactions)
* [Common Fields of All Transactions](#common-fields)
There are several different types of transactions that do different actions, each with additional fields relevant to that type of action: * [Transaction Types](#transaction-types)
* [Payment - Send funds from one account to another](#payment)
* [AccountSet - Set options on an account](#accountset)
* [SetRegularKey - Set an account's regular key](#setregularkey)
* [OfferCreate - Submit an order to exchange currency](#offercreate)
* [OfferCancel - Withdraw a currency-exchange order](#offercancel)
* [TrustSet - Add or modify a trust line](#trustset)
* [SignerListSet - Set multi-signing settings](#signerlistset)
Additionally, there are *Pseudo-Transactions* that are not created and submitted in the usual way, but may appear in ledgers:
* [SetFee - Adjust the minimum transaction cost or account reserve](#setfee)
* [EnableAmendment - Apply a change to transaction processing](#enableamendment)
Transactions are only valid if signed, submitted, and accepted into a validated ledger version. There are many ways a transaction can fail.
* [Authorized Transactions](#authorizing-transactions)
* [Reliable Transaction Submission](#reliable-transaction-submission) * [Reliable Transaction Submission](#reliable-transaction-submission)
* [Transaction Results - How to find and interpret transaction results](#transaction-results) * [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) * [Full Transaction Response List - Complete table of all error codes](#full-transaction-response-list)
@@ -368,115 +351,28 @@ The only flag that applies globally to all transactions is as follows:
## Payment ## # Transaction Types
[[Source]<br>](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.) The type of a transaction (`TransactionType` field) is the most fundamental information about a transaction. This indicates what operations it can or is supposed to perform.
Payments are also the only way to [create accounts](#creating-accounts). All transactions have certain fields in common:
Example payment: * [Common Fields](#common-fields)
``` Each transaction type has additional fields relevant to the type of action it causes:
{
"TransactionType" : "Payment",
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Amount" : {
"currency" : "USD",
"value" : "1",
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
},
"Fee": "10",
"Flags": 2147483648,
"Sequence": 2,
}
```
| Field | JSON Type | [Internal Type][] | Description | * [AccountSet - Set options on an account](#accountset)
|:---------------|:---------------------|:------------------|:-----------------| * [OfferCreate - Submit an order to exchange currency](#offercreate)
| 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. | * [OfferCancel - Withdraw a currency-exchange order](#offercancel)
| Destination | String | Account | The unique address of the account receiving the payment. | * [Payment - Send funds from one account to another](#payment)
| DestinationTag | Unsigned Integer | UInt32 | (Optional) Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. | * [SetRegularKey - Set an account's regular key](#setregularkey)
| InvoiceID | String | Hash256 | (Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment. | * [SignerListSet - Set multi-signing settings](#signerlistset)
| Paths | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](concept-paths.html) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. | * [TrustSet - Add or modify a trust line](#trustset)
| 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 ### _Pseudo-Transactions_ that are not created and submitted in the usual way, but may be added to open ledgers according to ledger rules. They still must be approved by consensus to be included in a validated ledger. Pseudo-transactions have their own unique transaction types:
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.
* There is only ever one balance for the same currency between two addresses. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming issuances, instead of the address that created the issuances.
* 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 ###
The Payment transaction type is the only way to create new accounts in the Ripple Consensus Ledger. To do so, send an amount of XRP that is equal or greater than the [account reserve](concept-reserves.html) to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new [AccountRoot node](reference-ledger-format.html#accountroot) is added to the ledger.
If you send an insufficient amount of XRP, or any other currency, the Payment fails.
### 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.
You must omit the `Paths` field for direct payments, including:
* An XRP-to-XRP transfer.
* A direct transfer on a trust line that connects the sender and receiver.
If the `Paths` field is provided, the server decides at transaction processing time which paths to use, from the provided set plus a _default path_ (the most direct way possible to connect the specified accounts). This decision is deterministic and attempts to minimize costs, but it is not guaranteed to be perfect.
The `Paths` field must not be an empty array, nor an array whose members are all empty arrays.
For more information, see [Paths](concept-paths.html).
### Payment Flags ###
Transactions of the Payment type support additional values in the [`Flags` field](#flags), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:-----------------|:-----------|:--------------|:-----------------------------|
| tfNoDirectRipple | 0x00010000 | 65536 | Do not use the default path; only use paths included in the `Paths` field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this. |
| tfPartialPayment | 0x00020000 | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](#partial-payments) for more details. |
| tfLimitQuality | 0x00040000 | 262144 | Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of `Amount`:`SendMax`. See [Limit Quality](#limit-quality) for details. |
### Partial Payments ###
A partial payment allows a payment to succeed by reducing the amount received, instead of increasing the `SendMax`. Partial payments are useful for [returning payments](tutorial-gateway-guide.html#bouncing-payments) without incurring additional costs to oneself.
By default, the `Amount` field of a Payment transaction specifies the amount of currency that is *received* by the account that is the destination of the payment. Any additional amount needed for fees or currency exchange is deducted from the sending account's balances, up to the `SendMax` amount. (If `SendMax` is not specified, that is equivalent to setting the `SendMax` to the `Amount` field.) If the amount needed to make the payment exceeds the `SendMax` parameter, or the full amount cannot be delivered for any other reason, the transaction fails.
The [*tfPartialPayment* flag](#payment-flags) allows you to make a "partial payment" instead. When this flag is enabled for a payment, it delivers as much as possible, up to the `Amount` value, without exceeding the `SendMax` value. Fees and currency exchange rates are calculated the same way, but the amount being sent automatically scales down until the total amount deducted from the sending account's balances is within `SendMax`. The transaction is considered successful as long as it delivers equal or more than the `DeliverMin` value; if DeliverMin is omitted, then any positive amount is considered a success. This means that partial payments can succeed at sending *some* of the intended value despite limitations including fees, lack of liquidity, insufficient space in the receiving account's trustlines, or other reasons.
A partial payment cannot provide the XRP to fund an address; this case returns the error code `telNO_DST_PARTIAL`. Direct XRP-to-XRP payments also cannot be partial payments `temBAD_SEND_XRP_PARTIAL`.
The amount of XRP used for the [transaction cost](#transaction-cost) is always deducted from the sender’s account, regardless of the *tfPartialPayment* flag.
#### Partial Payments Warning ####
When the [*tfPartialPayment* flag](#payment-flags) is enabled, the `Amount` field __*is not guaranteed to be the amount received*__. The [`delivered_amount`](#delivered-amount) field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use `delivered_amount` instead of the `Amount` field to determine how much your account received instead.
### Limit Quality ###
Ripple 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`.
The [*tfLimitQuality* flag](#payment-flags) allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination `Amount` divided by the `SendMax` amount (the numeric amounts only, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.
By itself, the tfLimitQuality flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average *average* quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the [transaction result](#transaction-results) is `tecPATH_DRY`.
Consider the following example. If I am trying to send you 100 Chinese Yuan (`Amount` = 100 CNY) for 20 United States dollars (`SendMax` = 20 USD) or less, then the limit quality is `5`. Imagine one trader is offering ¥95 for $15 (a ratio of about `6.3` CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of `2.5` CNY per USD). If I were to take both offers to send you 100 CNY, then it would cost me 17 USD, for an average quality of about `5.9`.
Without the tfLimitQuality flag set, this transaction would succeed, because the $17 it costs me is within my specified `SendMax`. However, with the tfLimitQuality flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of `2.5`, which is worse than the limit quality of `5`.
The tfLimitQuality flag is most useful when combined with [partial payments](#partial-payments). 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.
* [SetFee - Adjust the minimum transaction cost or account reserve](#setfee)
* [EnableAmendment - Apply a change to transaction processing](#enableamendment)
## AccountSet ## ## AccountSet ##
@@ -576,33 +472,31 @@ In `rippled`'s WebSocket and JSON-RPC APIs, the TransferRate is represented as a
## SetRegularKey ## ## OfferCancel ##
[[Source]<br>](https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp "Source") [[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CancelOffer.cpp "Source")
A SetRegularKey transaction changes the regular key associated with an address. An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledger.
``` ```
{ {
"Flags": 0, "TransactionType": "OfferCancel",
"TransactionType": "SetRegularKey", "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12", "Fee": "12",
"RegularKey": "rAR8rR8sUkBoCZFawhkWzY4Y5YoyuznwD" "Flags": 0,
"LastLedgerSequence": 7108629,
"OfferSequence": 6,
"Sequence": 7
} }
``` ```
| Field | JSON Type | [Internal Type][] | Description | | Field | JSON Type | [Internal Type][] | Description |
|:-----------|:----------|:------------------|:--------------------------------| |:--------------|:-----------------|:------------------|:----------------------|
| RegularKey | String | AccountID | (Optional) A base-58-encoded [Ripple address](reference-rippled.html#addresses) to use as the regular key. If omitted, removes the existing regular key. | | OfferSequence | Unsigned Integer | UInt32 | The sequence number of a previous OfferCreate transaction. If specified, cancel any offer node in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist. |
In addition to the master key, which is mathematically-related to an address, you can associate **at most 1 additional key pair** with an address using this type of transaction. The additional key pair is called a _regular key_. If your address has a regular key pair defined, you can use the secret key of the regular key pair to [authorize transactions](#authorizing-transactions). *Tip:* To remove an old offer and replace it with a new one, you can use an [OfferCreate](#offercreate) transaction with an `OfferSequence` parameter, instead of using OfferCancel and another OfferCreate.
A regular key pair is generated in the same way as any other Ripple keys (for example, with [wallet_propose](reference-rippled.html#wallet-propose)), but it can be changed. A master key pair is an intrinsic part of an address's identity (the address is derived from the master public key). You can [disable](#accountset-flags) a master key but you cannot change it. The OfferCancel method returns [tesSUCCESS](#transaction-results) even if it did not find an offer with the matching sequence number.
You can protect your master secret by using a regular key instead of the master key to sign transactions whenever possible. If your regular key is compromised, but the master key is not, you can use a SetRegularKey transaction to regain control of your address. In some cases, you can even send a [key reset transaction](concept-transaction-cost.html#key-reset-transaction) without paying the [transaction cost](#transaction-cost).
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).
@@ -719,32 +613,197 @@ The following invalid flag combination prompts a temINVALID_FLAG error:
## Payment ##
[[Source]<br>](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/Payment.cpp "Source")
## OfferCancel ## 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.)
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CancelOffer.cpp "Source") Payments are also the only way to [create accounts](#creating-accounts).
An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledger. Example payment:
``` ```
{ {
"TransactionType": "OfferCancel", "TransactionType" : "Payment",
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12", "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Flags": 0, "Amount" : {
"LastLedgerSequence": 7108629, "currency" : "USD",
"OfferSequence": 6, "value" : "1",
"Sequence": 7 "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
},
"Fee": "10",
"Flags": 2147483648,
"Sequence": 2,
} }
``` ```
| Field | JSON Type | [Internal Type][] | Description | | Field | JSON Type | [Internal Type][] | Description |
|:--------------|:-----------------|:------------------|:----------------------| |:---------------|:---------------------|:------------------|:-----------------|
| OfferSequence | Unsigned Integer | UInt32 | The sequence number of a previous OfferCreate transaction. If specified, cancel any offer node in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist. | | 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. |
| Destination | String | Account | The unique address of the account receiving the payment. |
| DestinationTag | Unsigned Integer | UInt32 | (Optional) Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. |
| InvoiceID | String | Hash256 | (Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment. |
| Paths | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](concept-paths.html) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. |
| SendMax | [Currency Amount][] | Amount | (Optional) Highest amount of source currency this transaction is allowed to cost, including [transfer fees](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. |
*Tip:* To remove an old offer and replace it with a new one, you can use an [OfferCreate](#offercreate) transaction with an `OfferSequence` parameter, instead of using OfferCancel and another OfferCreate. ### 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.
* There is only ever one balance for the same currency between two addresses. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming issuances, instead of the address that created the issuances.
* 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 ###
The Payment transaction type is the only way to create new accounts in the Ripple Consensus Ledger. To do so, send an amount of XRP that is equal or greater than the [account reserve](concept-reserves.html) to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new [AccountRoot node](reference-ledger-format.html#accountroot) is added to the ledger.
If you send an insufficient amount of XRP, or any other currency, the Payment fails.
### 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.
You must omit the `Paths` field for direct payments, including:
* An XRP-to-XRP transfer.
* A direct transfer on a trust line that connects the sender and receiver.
If the `Paths` field is provided, the server decides at transaction processing time which paths to use, from the provided set plus a _default path_ (the most direct way possible to connect the specified accounts). This decision is deterministic and attempts to minimize costs, but it is not guaranteed to be perfect.
The `Paths` field must not be an empty array, nor an array whose members are all empty arrays.
For more information, see [Paths](concept-paths.html).
### Payment Flags ###
Transactions of the Payment type support additional values in the [`Flags` field](#flags), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:-----------------|:-----------|:--------------|:-----------------------------|
| tfNoDirectRipple | 0x00010000 | 65536 | Do not use the default path; only use paths included in the `Paths` field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this. |
| tfPartialPayment | 0x00020000 | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](#partial-payments) for more details. |
| tfLimitQuality | 0x00040000 | 262144 | Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of `Amount`:`SendMax`. See [Limit Quality](#limit-quality) for details. |
### Partial Payments ###
A partial payment allows a payment to succeed by reducing the amount received, instead of increasing the `SendMax`. Partial payments are useful for [returning payments](tutorial-gateway-guide.html#bouncing-payments) without incurring additional costs to oneself.
By default, the `Amount` field of a Payment transaction specifies the amount of currency that is *received* by the account that is the destination of the payment. Any additional amount needed for fees or currency exchange is deducted from the sending account's balances, up to the `SendMax` amount. (If `SendMax` is not specified, that is equivalent to setting the `SendMax` to the `Amount` field.) If the amount needed to make the payment exceeds the `SendMax` parameter, or the full amount cannot be delivered for any other reason, the transaction fails.
The [*tfPartialPayment* flag](#payment-flags) allows you to make a "partial payment" instead. When this flag is enabled for a payment, it delivers as much as possible, up to the `Amount` value, without exceeding the `SendMax` value. Fees and currency exchange rates are calculated the same way, but the amount being sent automatically scales down until the total amount deducted from the sending account's balances is within `SendMax`. The transaction is considered successful as long as it delivers equal or more than the `DeliverMin` value; if DeliverMin is omitted, then any positive amount is considered a success. This means that partial payments can succeed at sending *some* of the intended value despite limitations including fees, lack of liquidity, insufficient space in the receiving account's trustlines, or other reasons.
A partial payment cannot provide the XRP to fund an address; this case returns the error code `telNO_DST_PARTIAL`. Direct XRP-to-XRP payments also cannot be partial payments `temBAD_SEND_XRP_PARTIAL`.
The amount of XRP used for the [transaction cost](#transaction-cost) is always deducted from the sender’s account, regardless of the *tfPartialPayment* flag.
#### Partial Payments Warning ####
When the [*tfPartialPayment* flag](#payment-flags) is enabled, the `Amount` field __*is not guaranteed to be the amount received*__. The [`delivered_amount`](#delivered-amount) field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use `delivered_amount` instead of the `Amount` field to determine how much your account received instead.
### Limit Quality ###
Ripple 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`.
The [*tfLimitQuality* flag](#payment-flags) allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination `Amount` divided by the `SendMax` amount (the numeric amounts only, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.
By itself, the tfLimitQuality flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average *average* quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the [transaction result](#transaction-results) is `tecPATH_DRY`.
Consider the following example. If I am trying to send you 100 Chinese Yuan (`Amount` = 100 CNY) for 20 United States dollars (`SendMax` = 20 USD) or less, then the limit quality is `5`. Imagine one trader is offering ¥95 for $15 (a ratio of about `6.3` CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of `2.5` CNY per USD). If I were to take both offers to send you 100 CNY, then it would cost me 17 USD, for an average quality of about `5.9`.
Without the tfLimitQuality flag set, this transaction would succeed, because the $17 it costs me is within my specified `SendMax`. However, with the tfLimitQuality flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of `2.5`, which is worse than the limit quality of `5`.
The tfLimitQuality flag is most useful when combined with [partial payments](#partial-payments). 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.
## SetRegularKey ##
[[Source]<br>](https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp "Source")
A SetRegularKey transaction changes the regular key associated with an address.
```
{
"Flags": 0,
"TransactionType": "SetRegularKey",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"RegularKey": "rAR8rR8sUkBoCZFawhkWzY4Y5YoyuznwD"
}
```
| Field | JSON Type | [Internal Type][] | Description |
|:-----------|:----------|:------------------|:--------------------------------|
| RegularKey | String | AccountID | (Optional) A base-58-encoded [Ripple address](reference-rippled.html#addresses) to use as the regular key. If omitted, removes the existing regular key. |
In addition to the master key, which is mathematically-related to an address, you can associate **at most 1 additional key pair** with an address using this type of transaction. The additional key pair is called a _regular key_. If your address has a regular key pair defined, you can use the secret key of the regular key pair to [authorize transactions](#authorizing-transactions).
A regular key pair is generated in the same way as any other Ripple keys (for example, with [wallet_propose](reference-rippled.html#wallet-propose)), but it can be changed. A master key pair is an intrinsic part of an address's identity (the address is derived from the master public key). You can [disable](#accountset-flags) a master key but you cannot change it.
You can protect your master secret by using a regular key instead of the master key to sign transactions whenever possible. If your regular key is compromised, but the master key is not, you can use a SetRegularKey transaction to regain control of your address. In some cases, you can even send a [key reset transaction](concept-transaction-cost.html#key-reset-transaction) without paying the [transaction cost](#transaction-cost).
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).
## SignerListSet ##
[[Source]<br>](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](concept-amendments.html#multisign). [New in: rippled 0.31.0][]
Example SignerListSet:
```
{
"Flags": 0,
"TransactionType": "SignerListSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "10000",
"SignerQuorum": 3,
"SignerEntries": [
{
"SignerEntry": {
"Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"SignerWeight": 2
}
},
{
"SignerEntry": {
"Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
"SignerWeight": 1
}
},
{
"SignerEntry": {
"Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
"SignerWeight": 1
}
}
]
}
```
| 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`. |
| SignerEntries | Array | Array | (Omitted when deleting) Array of [SignerEntry objects](reference-ledger-format.html#signerentry-object), indicating the addresses and weights of signers in this list. A SignerList must have at least 1 member and no more than 8 members. No address may appear more than once in the list, nor may the `Account` submitting the transaction appear in the list. |
An account may not have more than one SignerList. A successful SignerListSet transaction replaces the existing SignerList, if one exists. To delete a SignerList, you must set `SignerQuorum` to `0` _and_ omit the `SignerEntries` field. Otherwise, the transaction fails with the error [temMALFORMED](#tem-codes). A transaction to delete a SignerList is considered successful even if there was no SignerList to delete.
You cannot create a SignerList such that the SignerQuorum could never be met. The SignerQuorum must be greater than 0 but less than or equal to the sum of the `SignerWeight` values in the list. Otherwise, the transaction fails with the error [temMALFORMED](#tem-codes).
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).
The OfferCancel method returns [tesSUCCESS](#transaction-results) even if it did not find an offer with the matching sequence number.
## TrustSet ## ## TrustSet ##
@@ -808,56 +867,6 @@ Transactions of the TrustSet type support additional values in the [`Flags` fiel
## SignerListSet ##
[[Source]<br>](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](concept-amendments.html#multisign). [New in: rippled 0.31.0][]
Example SignerListSet:
```
{
"Flags": 0,
"TransactionType": "SignerListSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "10000",
"SignerQuorum": 3,
"SignerEntries": [
{
"SignerEntry": {
"Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"SignerWeight": 2
}
},
{
"SignerEntry": {
"Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
"SignerWeight": 1
}
},
{
"SignerEntry": {
"Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
"SignerWeight": 1
}
}
]
}
```
| 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`. |
| SignerEntries | Array | Array | (Omitted when deleting) Array of [SignerEntry objects](reference-ledger-format.html#signerentry-object), indicating the addresses and weights of signers in this list. A SignerList must have at least 1 member and no more than 8 members. No address may appear more than once in the list, nor may the `Account` submitting the transaction appear in the list. |
An account may not have more than one SignerList. A successful SignerListSet transaction replaces the existing SignerList, if one exists. To delete a SignerList, you must set `SignerQuorum` to `0` _and_ omit the `SignerEntries` field. Otherwise, the transaction fails with the error [temMALFORMED](#tem-codes). A transaction to delete a SignerList is considered successful even if there was no SignerList to delete.
You cannot create a SignerList such that the SignerQuorum could never be met. The SignerQuorum must be greater than 0 but less than or equal to the sum of the `SignerWeight` values in the list. Otherwise, the transaction fails with the error [temMALFORMED](#tem-codes).
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).
# Pseudo-Transactions # # Pseudo-Transactions #
@@ -873,6 +882,32 @@ Some of the fields that are mandatory for normal transactions do not make sense
| SigningPubKey | "" | | SigningPubKey | "" |
| Signature | "" | | Signature | "" |
## 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.
**Note:** You cannot send a pseudo-transaction, but you may find one when processing ledgers.
| Field | JSON Type | [Internal Type][] | Description |
|:---------------|:----------|:------------------|:----------------------------|
| Amendment | String | Hash256 | A unique identifier for the amendment. This is not intended to be a human-readable name. See [Amendments](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 ###
The `Flags` value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction.
A `Flags` value of `0` (no flags) indicates that the amendment has been enabled, and applies to all ledgers afterward. Other `Flags` values are as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:---------------|:-----------|:--------------|:-------------------------------|
| 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. |
## 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). 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).
@@ -904,27 +939,6 @@ A change in [transaction cost](concept-transaction-cost.html) or [account reserv
| ReserveIncrement | Unsigned Integer | UInt32 | The incremental 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. | | 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. |
## 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.
**Note:** You cannot send a pseudo-transaction, but you may find one when processing ledgers.
| Field | JSON Type | [Internal Type][] | Description |
|:---------------|:----------|:------------------|:----------------------------|
| Amendment | String | Hash256 | A unique identifier for the amendment. This is not intended to be a human-readable name. See [Amendments](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 ###
The `Flags` value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction.
A `Flags` value of `0` (no flags) indicates that the amendment has been enabled, and applies to all ledgers afterward. Other `Flags` values are as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:---------------|:-----------|:--------------|:-------------------------------|
| 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. |

633
reference-transaction-format.html
View File

@@ -134,7 +134,7 @@
<hr /> <hr />
<h5>In this page:</h5> <h5>In this page:</h5>
<ul class="dev_nav_sidebar" id="dactyl_toc_sidebar"> <ul class="dev_nav_sidebar" id="dactyl_toc_sidebar">
<li class="level-1"><a href="#transactions">Transactions</a></li> <li class="level-1"><a href="#transactions-overview">Transactions Overview</a></li>
<li class="level-2"><a href="#authorizing-transactions">Authorizing Transactions</a></li> <li class="level-2"><a href="#authorizing-transactions">Authorizing Transactions</a></li>
<li class="level-2"><a href="#signing-and-submitting-transactions">Signing and Submitting Transactions</a></li> <li class="level-2"><a href="#signing-and-submitting-transactions">Signing and Submitting Transactions</a></li>
<li class="level-3"><a href="#unsigned-transaction-format">Unsigned Transaction Format</a></li> <li class="level-3"><a href="#unsigned-transaction-format">Unsigned Transaction Format</a></li>
@@ -150,18 +150,12 @@
<li class="level-3"><a href="#memos">Memos</a></li> <li class="level-3"><a href="#memos">Memos</a></li>
<li class="level-3"><a href="#signers-field">Signers Field</a></li> <li class="level-3"><a href="#signers-field">Signers Field</a></li>
<li class="level-3"><a href="#flags">Flags</a></li> <li class="level-3"><a href="#flags">Flags</a></li>
<li class="level-2"><a href="#payment">Payment</a></li> <li class="level-1"><a href="#transaction-types">Transaction Types</a></li>
<li class="level-3"><a href="#special-issuer-values-for-sendmax-and-amount">Special issuer Values for SendMax and Amount</a></li>
<li class="level-3"><a href="#creating-accounts">Creating Accounts</a></li>
<li class="level-3"><a href="#paths">Paths</a></li>
<li class="level-3"><a href="#payment-flags">Payment Flags</a></li>
<li class="level-3"><a href="#partial-payments">Partial Payments</a></li>
<li class="level-3"><a href="#limit-quality">Limit Quality</a></li>
<li class="level-2"><a href="#accountset">AccountSet</a></li> <li class="level-2"><a href="#accountset">AccountSet</a></li>
<li class="level-3"><a href="#domain">Domain</a></li> <li class="level-3"><a href="#domain">Domain</a></li>
<li class="level-3"><a href="#accountset-flags">AccountSet Flags</a></li> <li class="level-3"><a href="#accountset-flags">AccountSet Flags</a></li>
<li class="level-3"><a href="#transferrate">TransferRate</a></li> <li class="level-3"><a href="#transferrate">TransferRate</a></li>
<li class="level-2"><a href="#setregularkey">SetRegularKey</a></li> <li class="level-2"><a href="#offercancel">OfferCancel</a></li>
<li class="level-2"><a href="#offercreate">OfferCreate</a></li> <li class="level-2"><a href="#offercreate">OfferCreate</a></li>
<li class="level-3"><a href="#lifecycle-of-an-offer">Lifecycle of an Offer</a></li> <li class="level-3"><a href="#lifecycle-of-an-offer">Lifecycle of an Offer</a></li>
<li class="level-3"><a href="#offers-and-trust">Offers and Trust</a></li> <li class="level-3"><a href="#offers-and-trust">Offers and Trust</a></li>
@@ -169,15 +163,22 @@
<li class="level-3"><a href="#expiration">Expiration</a></li> <li class="level-3"><a href="#expiration">Expiration</a></li>
<li class="level-3"><a href="#auto-bridging">Auto-Bridging</a></li> <li class="level-3"><a href="#auto-bridging">Auto-Bridging</a></li>
<li class="level-3"><a href="#offercreate-flags">OfferCreate Flags</a></li> <li class="level-3"><a href="#offercreate-flags">OfferCreate Flags</a></li>
<li class="level-2"><a href="#offercancel">OfferCancel</a></li> <li class="level-2"><a href="#payment">Payment</a></li>
<li class="level-3"><a href="#special-issuer-values-for-sendmax-and-amount">Special issuer Values for SendMax and Amount</a></li>
<li class="level-3"><a href="#creating-accounts">Creating Accounts</a></li>
<li class="level-3"><a href="#paths">Paths</a></li>
<li class="level-3"><a href="#payment-flags">Payment Flags</a></li>
<li class="level-3"><a href="#partial-payments">Partial Payments</a></li>
<li class="level-3"><a href="#limit-quality">Limit Quality</a></li>
<li class="level-2"><a href="#setregularkey">SetRegularKey</a></li>
<li class="level-2"><a href="#signerlistset">SignerListSet</a></li>
<li class="level-2"><a href="#trustset">TrustSet</a></li> <li class="level-2"><a href="#trustset">TrustSet</a></li>
<li class="level-3"><a href="#trust-limits">Trust Limits</a></li> <li class="level-3"><a href="#trust-limits">Trust Limits</a></li>
<li class="level-3"><a href="#trustset-flags">TrustSet Flags</a></li> <li class="level-3"><a href="#trustset-flags">TrustSet Flags</a></li>
<li class="level-2"><a href="#signerlistset">SignerListSet</a></li>
<li class="level-1"><a href="#pseudo-transactions">Pseudo-Transactions</a></li> <li class="level-1"><a href="#pseudo-transactions">Pseudo-Transactions</a></li>
<li class="level-2"><a href="#setfee">SetFee</a></li>
<li class="level-2"><a href="#enableamendment">EnableAmendment</a></li> <li class="level-2"><a href="#enableamendment">EnableAmendment</a></li>
<li class="level-3"><a href="#enableamendment-flags">EnableAmendment Flags</a></li> <li class="level-3"><a href="#enableamendment-flags">EnableAmendment Flags</a></li>
<li class="level-2"><a href="#setfee">SetFee</a></li>
<li class="level-1"><a href="#transaction-results">Transaction Results</a></li> <li class="level-1"><a href="#transaction-results">Transaction Results</a></li>
<li class="level-2"><a href="#immediate-response">Immediate Response</a></li> <li class="level-2"><a href="#immediate-response">Immediate Response</a></li>
<li class="level-2"><a href="#looking-up-transaction-results">Looking up Transaction Results</a></li> <li class="level-2"><a href="#looking-up-transaction-results">Looking up Transaction Results</a></li>
@@ -200,29 +201,12 @@
</aside> </aside>
<main class="main" role="main"> <main class="main" role="main">
<div class='content'> <div class='content'>
<h1 id="transactions">Transactions</h1> <h1 id="transactions-overview">Transactions Overview</h1>
<p>A <em>Transaction</em> is the only way to modify the Ripple Ledger. All transactions have certain fields in common:</p> <p>A <em>Transaction</em> is the only way to modify the Ripple Ledger. Transactions are only valid if signed, submitted, and accepted into a validated ledger version following the <a href="https://ripple.com/build/ripple-ledger-consensus-process/">consensus process</a>. Some ledger rules also generate <em><a href="#pseudo-transactions">pseudo-transactions</a></em>, 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 <a href="concept-transaction-cost">transaction cost</a>.</p>
<ul> <ul>
<li><a href="#common-fields">Common Fields</a></li> <li><a href="#authorizing-transactions">Authorizing Transactions</a></li>
</ul> <li><a href="#common-fields">Common Fields of All Transactions</a></li>
<p>There are several different types of transactions that do different actions, each with additional fields relevant to that type of action:</p> <li><a href="#transaction-types">Transaction Types</a></li>
<ul>
<li><a href="#payment">Payment - Send funds from one account to another</a></li>
<li><a href="#accountset">AccountSet - Set options on an account</a></li>
<li><a href="#setregularkey">SetRegularKey - Set an account's regular key</a></li>
<li><a href="#offercreate">OfferCreate - Submit an order to exchange currency</a></li>
<li><a href="#offercancel">OfferCancel - Withdraw a currency-exchange order</a></li>
<li><a href="#trustset">TrustSet - Add or modify a trust line</a></li>
<li><a href="#signerlistset">SignerListSet - Set multi-signing settings</a></li>
</ul>
<p>Additionally, there are <em>Pseudo-Transactions</em> that are not created and submitted in the usual way, but may appear in ledgers:</p>
<ul>
<li><a href="#setfee">SetFee - Adjust the minimum transaction cost or account reserve</a></li>
<li><a href="#enableamendment">EnableAmendment - Apply a change to transaction processing</a></li>
</ul>
<p>Transactions are only valid if signed, submitted, and accepted into a validated ledger version. There are many ways a transaction can fail.</p>
<ul>
<li><a href="#authorizing-transactions">Authorized Transactions</a></li>
<li><a href="#reliable-transaction-submission">Reliable Transaction Submission</a></li> <li><a href="#reliable-transaction-submission">Reliable Transaction Submission</a></li>
<li><a href="#transaction-results">Transaction Results - How to find and interpret transaction results</a></li> <li><a href="#transaction-results">Transaction Results - How to find and interpret transaction results</a></li>
<li><a href="#full-transaction-response-list">Full Transaction Response List - Complete table of all error codes</a></li> <li><a href="#full-transaction-response-list">Full Transaction Response List - Complete table of all error codes</a></li>
@@ -630,147 +614,27 @@
</tr> </tr>
</tbody> </tbody>
</table> </table>
<h2 id="payment">Payment</h2> <h1 id="transaction-types">Transaction Types</h1>
<p><a href="https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/Payment.cpp" title="Source">[Source]<br/></a></p> <p>The type of a transaction (<code>TransactionType</code> field) is the most fundamental information about a transaction. This indicates what operations it can or is supposed to perform.</p>
<p>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.)</p> <p>All transactions have certain fields in common:</p>
<p>Payments are also the only way to <a href="#creating-accounts">create accounts</a>.</p>
<p>Example payment:</p>
<pre><code>{
"TransactionType" : "Payment",
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Amount" : {
"currency" : "USD",
"value" : "1",
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
},
"Fee": "10",
"Flags": 2147483648,
"Sequence": 2,
}
</code></pre>
<table>
<thead>
<tr>
<th align="left">Field</th>
<th align="left">JSON Type</th>
<th align="left"><a href="https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp">Internal Type</a></th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">Amount</td>
<td align="left"><a href="reference-rippled.html#specifying-currency-amounts">Currency Amount</a></td>
<td align="left">Amount</td>
<td align="left">The amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the <a href="#payment-flags"><strong>tfPartialPayment</strong> flag</a> is set, deliver <em>up to</em> this amount instead.</td>
</tr>
<tr>
<td align="left">Destination</td>
<td align="left">String</td>
<td align="left">Account</td>
<td align="left">The unique address of the account receiving the payment.</td>
</tr>
<tr>
<td align="left">DestinationTag</td>
<td align="left">Unsigned Integer</td>
<td align="left">UInt32</td>
<td align="left">(Optional) Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay.</td>
</tr>
<tr>
<td align="left">InvoiceID</td>
<td align="left">String</td>
<td align="left">Hash256</td>
<td align="left">(Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment.</td>
</tr>
<tr>
<td align="left">Paths</td>
<td align="left">Array of path arrays</td>
<td align="left">PathSet</td>
<td align="left">(Optional, auto-fillable) Array of <a href="concept-paths.html">payment paths</a> to be used for this transaction. Must be omitted for XRP-to-XRP transactions.</td>
</tr>
<tr>
<td align="left">SendMax</td>
<td align="left"><a href="reference-rippled.html#specifying-currency-amounts">Currency Amount</a></td>
<td align="left">Amount</td>
<td align="left">(Optional) Highest amount of source currency this transaction is allowed to cost, including <a href="concept-transfer-fees.html">transfer fees</a>, exchange rates, and <a href="http://en.wikipedia.org/wiki/Slippage_%28finance%29">slippage</a>. Does not include the <a href="#transaction-cost">XRP destroyed as a cost for submitting the transaction</a>. 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.</td>
</tr>
<tr>
<td align="left">DeliverMin</td>
<td align="left"><a href="reference-rippled.html#specifying-currency-amounts">Currency Amount</a></td>
<td align="left">Amount</td>
<td align="left">(Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a <a href="#partial-payments">partial payment</a>. For non-XRP amounts, the nested field names are lower-case.</td>
</tr>
</tbody>
</table>
<h3 id="special-issuer-values-for-sendmax-and-amount">Special issuer Values for SendMax and Amount</h3>
<p>Most of the time, the <code>issuer</code> field of a non-XRP <a href="reference-rippled.html#specifying-currency-amounts">Currency Amount</a> indicates a financial institution's <a href="concept-issuing-and-operational-addresses.html">issuing address</a>. However, when describing payments, there are special rules for the <code>issuer</code> field in the <code>Amount</code> and <code>SendMax</code> fields of a payment.</p>
<ul> <ul>
<li>There is only ever one balance for the same currency between two addresses. This means that, sometimes, the <code>issuer</code> field of an amount actually refers to a counterparty that is redeeming issuances, instead of the address that created the issuances.</li> <li><a href="#common-fields">Common Fields</a></li>
<li>When the <code>issuer</code> field of the destination <code>Amount</code> field matches the <code>Destination</code> 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.</li>
<li>When the <code>issuer</code> field of the <code>SendMax</code> 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.</li>
</ul> </ul>
<h3 id="creating-accounts">Creating Accounts</h3> <p>Each transaction type has additional fields relevant to the type of action it causes:</p>
<p>The Payment transaction type is the only way to create new accounts in the Ripple Consensus Ledger. To do so, send an amount of XRP that is equal or greater than the <a href="concept-reserves.html">account reserve</a> to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new <a href="reference-ledger-format.html#accountroot">AccountRoot node</a> is added to the ledger.</p>
<p>If you send an insufficient amount of XRP, or any other currency, the Payment fails.</p>
<h3 id="paths">Paths</h3>
<p>If present, the <code>Paths</code> field must contain a <em>path set</em> - 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.</p>
<p>You must omit the <code>Paths</code> field for direct payments, including:</p>
<ul> <ul>
<li>An XRP-to-XRP transfer.</li> <li><a href="#accountset">AccountSet - Set options on an account</a></li>
<li>A direct transfer on a trust line that connects the sender and receiver.</li> <li><a href="#offercreate">OfferCreate - Submit an order to exchange currency</a></li>
<li><a href="#offercancel">OfferCancel - Withdraw a currency-exchange order</a></li>
<li><a href="#payment">Payment - Send funds from one account to another</a></li>
<li><a href="#setregularkey">SetRegularKey - Set an account's regular key</a></li>
<li><a href="#signerlistset">SignerListSet - Set multi-signing settings</a></li>
<li><a href="#trustset">TrustSet - Add or modify a trust line</a></li>
</ul>
<p><em>Pseudo-Transactions</em> that are not created and submitted in the usual way, but may be added to open ledgers according to ledger rules. They still must be approved by consensus to be included in a validated ledger. Pseudo-transactions have their own unique transaction types:</p>
<ul>
<li><a href="#setfee">SetFee - Adjust the minimum transaction cost or account reserve</a></li>
<li><a href="#enableamendment">EnableAmendment - Apply a change to transaction processing</a></li>
</ul> </ul>
<p>If the <code>Paths</code> field is provided, the server decides at transaction processing time which paths to use, from the provided set plus a <em>default path</em> (the most direct way possible to connect the specified accounts). This decision is deterministic and attempts to minimize costs, but it is not guaranteed to be perfect.</p>
<p>The <code>Paths</code> field must not be an empty array, nor an array whose members are all empty arrays.</p>
<p>For more information, see <a href="concept-paths.html">Paths</a>.</p>
<h3 id="payment-flags">Payment Flags</h3>
<p>Transactions of the Payment type support additional values in the <a href="#flags"><code>Flags</code> field</a>, as follows:</p>
<table>
<thead>
<tr>
<th align="left">Flag Name</th>
<th align="left">Hex Value</th>
<th align="left">Decimal Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">tfNoDirectRipple</td>
<td align="left">0x00010000</td>
<td align="left">65536</td>
<td align="left">Do not use the default path; only use paths included in the <code>Paths</code> field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this.</td>
</tr>
<tr>
<td align="left">tfPartialPayment</td>
<td align="left">0x00020000</td>
<td align="left">131072</td>
<td align="left">If the specified <code>Amount</code> cannot be sent without spending more than <code>SendMax</code>, reduce the received amount instead of failing outright. See <a href="#partial-payments">Partial Payments</a> for more details.</td>
</tr>
<tr>
<td align="left">tfLimitQuality</td>
<td align="left">0x00040000</td>
<td align="left">262144</td>
<td align="left">Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of <code>Amount</code>:<code>SendMax</code>. See <a href="#limit-quality">Limit Quality</a> for details.</td>
</tr>
</tbody>
</table>
<h3 id="partial-payments">Partial Payments</h3>
<p>A partial payment allows a payment to succeed by reducing the amount received, instead of increasing the <code>SendMax</code>. Partial payments are useful for <a href="tutorial-gateway-guide.html#bouncing-payments">returning payments</a> without incurring additional costs to oneself.</p>
<p>By default, the <code>Amount</code> field of a Payment transaction specifies the amount of currency that is <em>received</em> by the account that is the destination of the payment. Any additional amount needed for fees or currency exchange is deducted from the sending account's balances, up to the <code>SendMax</code> amount. (If <code>SendMax</code> is not specified, that is equivalent to setting the <code>SendMax</code> to the <code>Amount</code> field.) If the amount needed to make the payment exceeds the <code>SendMax</code> parameter, or the full amount cannot be delivered for any other reason, the transaction fails.</p>
<p>The <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> allows you to make a "partial payment" instead. When this flag is enabled for a payment, it delivers as much as possible, up to the <code>Amount</code> value, without exceeding the <code>SendMax</code> value. Fees and currency exchange rates are calculated the same way, but the amount being sent automatically scales down until the total amount deducted from the sending account's balances is within <code>SendMax</code>. The transaction is considered successful as long as it delivers equal or more than the <code>DeliverMin</code> value; if DeliverMin is omitted, then any positive amount is considered a success. This means that partial payments can succeed at sending <em>some</em> of the intended value despite limitations including fees, lack of liquidity, insufficient space in the receiving account's trustlines, or other reasons.</p>
<p>A partial payment cannot provide the XRP to fund an address; this case returns the error code <code>telNO_DST_PARTIAL</code>. Direct XRP-to-XRP payments also cannot be partial payments <code>temBAD_SEND_XRP_PARTIAL</code>.</p>
<p>The amount of XRP used for the <a href="#transaction-cost">transaction cost</a> is always deducted from the sender’s account, regardless of the <em>tfPartialPayment</em> flag.</p>
<h4 id="partial-payments-warning">Partial Payments Warning</h4>
<p>When the <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> is enabled, the <code>Amount</code> field <strong><em>is not guaranteed to be the amount received</em></strong>. The <a href="#delivered-amount"><code>delivered_amount</code></a> field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use <code>delivered_amount</code> instead of the <code>Amount</code> field to determine how much your account received instead.</p>
<h3 id="limit-quality">Limit Quality</h3>
<p>Ripple 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 <code>0.5</code>.</p>
<p>The <a href="#payment-flags"><em>tfLimitQuality</em> flag</a> allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination <code>Amount</code> divided by the <code>SendMax</code> amount (the numeric amounts only, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.</p>
<p>By itself, the tfLimitQuality flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average <em>average</em> quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the <a href="#transaction-results">transaction result</a> is <code>tecPATH_DRY</code>.</p>
<p>Consider the following example. If I am trying to send you 100 Chinese Yuan (<code>Amount</code> = 100 CNY) for 20 United States dollars (<code>SendMax</code> = 20 USD) or less, then the limit quality is <code>5</code>. Imagine one trader is offering ¥95 for $15 (a ratio of about <code>6.3</code> CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of <code>2.5</code> CNY per USD). If I were to take both offers to send you 100 CNY, then it would cost me 17 USD, for an average quality of about <code>5.9</code>.</p>
<p>Without the tfLimitQuality flag set, this transaction would succeed, because the $17 it costs me is within my specified <code>SendMax</code>. However, with the tfLimitQuality flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of <code>2.5</code>, which is worse than the limit quality of <code>5</code>.</p>
<p>The tfLimitQuality flag is most useful when combined with <a href="#partial-payments">partial payments</a>. When both <em>tfPartialPayment</em> and <em>tfLimitQuality</em> are set on a transaction, then the transaction delivers as much of the destination <code>Amount</code> as it can, without using any conversions that are worse than the limit quality.</p>
<p>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 <code>SendMax</code> of 20 USD and a destination <code>Amount</code> of 100 CNY, then the limit quality is still <code>5</code>. 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 <code>6.3</code>, but it rejects the ¥5/$2 offer because that offer's quality of <code>2.5</code> is worse than the quality limit of <code>5</code>. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates.</p>
<h2 id="accountset">AccountSet</h2> <h2 id="accountset">AccountSet</h2>
<p><a href="https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/transactors/SetAccount.cpp" title="Source">[Source]<br/></a></p> <p><a href="https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/transactors/SetAccount.cpp" title="Source">[Source]<br/></a></p>
<p>An AccountSet transaction modifies the properties of an <a href="reference-ledger-format.html#accountroot">account in the Ripple Consensus Ledger</a>.</p> <p>An AccountSet transaction modifies the properties of an <a href="reference-ledger-format.html#accountroot">account in the Ripple Consensus Ledger</a>.</p>
@@ -977,15 +841,17 @@
<h3 id="transferrate">TransferRate</h3> <h3 id="transferrate">TransferRate</h3>
<p>The TransferRate field specifies a fee to charge whenever counterparties transfer the currency you issue. See <a href="https://ripple.com/knowledge_center/transfer-fees/">Transfer Fees article</a> in the Knowledge Center for more information.</p> <p>The TransferRate field specifies a fee to charge whenever counterparties transfer the currency you issue. See <a href="https://ripple.com/knowledge_center/transfer-fees/">Transfer Fees article</a> in the Knowledge Center for more information.</p>
<p>In <code>rippled</code>'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 <code>1200000000</code>. 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.</p> <p>In <code>rippled</code>'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 <code>1200000000</code>. 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.</p>
<h2 id="setregularkey">SetRegularKey</h2> <h2 id="offercancel">OfferCancel</h2>
<p><a href="https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp" title="Source">[Source]<br/></a></p> <p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CancelOffer.cpp" title="Source">[Source]<br/></a></p>
<p>A SetRegularKey transaction changes the regular key associated with an address.</p> <p>An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledger.</p>
<pre><code>{ <pre><code>{
"Flags": 0, "TransactionType": "OfferCancel",
"TransactionType": "SetRegularKey", "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12", "Fee": "12",
"RegularKey": "rAR8rR8sUkBoCZFawhkWzY4Y5YoyuznwD" "Flags": 0,
"LastLedgerSequence": 7108629,
"OfferSequence": 6,
"Sequence": 7
} }
</code></pre> </code></pre>
<table> <table>
@@ -999,17 +865,15 @@
</thead> </thead>
<tbody> <tbody>
<tr> <tr>
<td align="left">RegularKey</td> <td align="left">OfferSequence</td>
<td align="left">String</td> <td align="left">Unsigned Integer</td>
<td align="left">AccountID</td> <td align="left">UInt32</td>
<td align="left">(Optional) A base-58-encoded <a href="reference-rippled.html#addresses">Ripple address</a> to use as the regular key. If omitted, removes the existing regular key.</td> <td align="left">The sequence number of a previous OfferCreate transaction. If specified, cancel any offer node in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist.</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<p>In addition to the master key, which is mathematically-related to an address, you can associate <strong>at most 1 additional key pair</strong> with an address using this type of transaction. The additional key pair is called a <em>regular key</em>. If your address has a regular key pair defined, you can use the secret key of the regular key pair to <a href="#authorizing-transactions">authorize transactions</a>.</p> <p class="devportal-callout tip"><em>Tip:</em> To remove an old offer and replace it with a new one, you can use an <a href="#offercreate">OfferCreate</a> transaction with an <code>OfferSequence</code> parameter, instead of using OfferCancel and another OfferCreate.</p>
<p>A regular key pair is generated in the same way as any other Ripple keys (for example, with <a href="reference-rippled.html#wallet-propose">wallet_propose</a>), but it can be changed. A master key pair is an intrinsic part of an address's identity (the address is derived from the master public key). You can <a href="#accountset-flags">disable</a> a master key but you cannot change it.</p> <p>The OfferCancel method returns <a href="#transaction-results">tesSUCCESS</a> even if it did not find an offer with the matching sequence number.</p>
<p>You can protect your master secret by using a regular key instead of the master key to sign transactions whenever possible. If your regular key is compromised, but the master key is not, you can use a SetRegularKey transaction to regain control of your address. In some cases, you can even send a <a href="concept-transaction-cost.html#key-reset-transaction">key reset transaction</a> without paying the <a href="#transaction-cost">transaction cost</a>.</p>
<p>For even greater security, you can use <a href="#multi-signing">multi-signing</a>, but multi-signing requires additional XRP for the <a href="concept-transaction-cost.html">transaction cost</a> and <a href="concept-reserves.html">reserve</a>.</p>
<h2 id="offercreate">OfferCreate</h2> <h2 id="offercreate">OfferCreate</h2>
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp" title="Source">[Source]<br/></a></p> <p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp" title="Source">[Source]<br/></a></p>
<p>An OfferCreate transaction is effectively a <a href="http://en.wikipedia.org/wiki/limit_order">limit order</a>. It defines an intent to exchange currencies, and creates an Offer node in the Ripple Consensus Ledger if not completely fulfilled when placed. Offers can be partially fulfilled.</p> <p>An OfferCreate transaction is effectively a <a href="http://en.wikipedia.org/wiki/limit_order">limit order</a>. It defines an intent to exchange currencies, and creates an Offer node in the Ripple Consensus Ledger if not completely fulfilled when placed. Offers can be partially fulfilled.</p>
@@ -1149,17 +1013,23 @@
<ul> <ul>
<li>tfImmediateOrCancel and tfFillOrKill</li> <li>tfImmediateOrCancel and tfFillOrKill</li>
</ul> </ul>
<h2 id="offercancel">OfferCancel</h2> <h2 id="payment">Payment</h2>
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CancelOffer.cpp" title="Source">[Source]<br/></a></p> <p><a href="https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/Payment.cpp" title="Source">[Source]<br/></a></p>
<p>An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledger.</p> <p>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.)</p>
<p>Payments are also the only way to <a href="#creating-accounts">create accounts</a>.</p>
<p>Example payment:</p>
<pre><code>{ <pre><code>{
"TransactionType": "OfferCancel", "TransactionType" : "Payment",
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12", "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Flags": 0, "Amount" : {
"LastLedgerSequence": 7108629, "currency" : "USD",
"OfferSequence": 6, "value" : "1",
"Sequence": 7 "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
},
"Fee": "10",
"Flags": 2147483648,
"Sequence": 2,
} }
</code></pre> </code></pre>
<table> <table>
@@ -1173,15 +1043,210 @@
</thead> </thead>
<tbody> <tbody>
<tr> <tr>
<td align="left">OfferSequence</td> <td align="left">Amount</td>
<td align="left"><a href="reference-rippled.html#specifying-currency-amounts">Currency Amount</a></td>
<td align="left">Amount</td>
<td align="left">The amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the <a href="#payment-flags"><strong>tfPartialPayment</strong> flag</a> is set, deliver <em>up to</em> this amount instead.</td>
</tr>
<tr>
<td align="left">Destination</td>
<td align="left">String</td>
<td align="left">Account</td>
<td align="left">The unique address of the account receiving the payment.</td>
</tr>
<tr>
<td align="left">DestinationTag</td>
<td align="left">Unsigned Integer</td> <td align="left">Unsigned Integer</td>
<td align="left">UInt32</td> <td align="left">UInt32</td>
<td align="left">The sequence number of a previous OfferCreate transaction. If specified, cancel any offer node in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist.</td> <td align="left">(Optional) Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay.</td>
</tr>
<tr>
<td align="left">InvoiceID</td>
<td align="left">String</td>
<td align="left">Hash256</td>
<td align="left">(Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment.</td>
</tr>
<tr>
<td align="left">Paths</td>
<td align="left">Array of path arrays</td>
<td align="left">PathSet</td>
<td align="left">(Optional, auto-fillable) Array of <a href="concept-paths.html">payment paths</a> to be used for this transaction. Must be omitted for XRP-to-XRP transactions.</td>
</tr>
<tr>
<td align="left">SendMax</td>
<td align="left"><a href="reference-rippled.html#specifying-currency-amounts">Currency Amount</a></td>
<td align="left">Amount</td>
<td align="left">(Optional) Highest amount of source currency this transaction is allowed to cost, including <a href="concept-transfer-fees.html">transfer fees</a>, exchange rates, and <a href="http://en.wikipedia.org/wiki/Slippage_%28finance%29">slippage</a>. Does not include the <a href="#transaction-cost">XRP destroyed as a cost for submitting the transaction</a>. 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.</td>
</tr>
<tr>
<td align="left">DeliverMin</td>
<td align="left"><a href="reference-rippled.html#specifying-currency-amounts">Currency Amount</a></td>
<td align="left">Amount</td>
<td align="left">(Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a <a href="#partial-payments">partial payment</a>. For non-XRP amounts, the nested field names are lower-case.</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<p class="devportal-callout tip"><em>Tip:</em> To remove an old offer and replace it with a new one, you can use an <a href="#offercreate">OfferCreate</a> transaction with an <code>OfferSequence</code> parameter, instead of using OfferCancel and another OfferCreate.</p> <h3 id="special-issuer-values-for-sendmax-and-amount">Special issuer Values for SendMax and Amount</h3>
<p>The OfferCancel method returns <a href="#transaction-results">tesSUCCESS</a> even if it did not find an offer with the matching sequence number.</p> <p>Most of the time, the <code>issuer</code> field of a non-XRP <a href="reference-rippled.html#specifying-currency-amounts">Currency Amount</a> indicates a financial institution's <a href="concept-issuing-and-operational-addresses.html">issuing address</a>. However, when describing payments, there are special rules for the <code>issuer</code> field in the <code>Amount</code> and <code>SendMax</code> fields of a payment.</p>
<ul>
<li>There is only ever one balance for the same currency between two addresses. This means that, sometimes, the <code>issuer</code> field of an amount actually refers to a counterparty that is redeeming issuances, instead of the address that created the issuances.</li>
<li>When the <code>issuer</code> field of the destination <code>Amount</code> field matches the <code>Destination</code> 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.</li>
<li>When the <code>issuer</code> field of the <code>SendMax</code> 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.</li>
</ul>
<h3 id="creating-accounts">Creating Accounts</h3>
<p>The Payment transaction type is the only way to create new accounts in the Ripple Consensus Ledger. To do so, send an amount of XRP that is equal or greater than the <a href="concept-reserves.html">account reserve</a> to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new <a href="reference-ledger-format.html#accountroot">AccountRoot node</a> is added to the ledger.</p>
<p>If you send an insufficient amount of XRP, or any other currency, the Payment fails.</p>
<h3 id="paths">Paths</h3>
<p>If present, the <code>Paths</code> field must contain a <em>path set</em> - 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.</p>
<p>You must omit the <code>Paths</code> field for direct payments, including:</p>
<ul>
<li>An XRP-to-XRP transfer.</li>
<li>A direct transfer on a trust line that connects the sender and receiver.</li>
</ul>
<p>If the <code>Paths</code> field is provided, the server decides at transaction processing time which paths to use, from the provided set plus a <em>default path</em> (the most direct way possible to connect the specified accounts). This decision is deterministic and attempts to minimize costs, but it is not guaranteed to be perfect.</p>
<p>The <code>Paths</code> field must not be an empty array, nor an array whose members are all empty arrays.</p>
<p>For more information, see <a href="concept-paths.html">Paths</a>.</p>
<h3 id="payment-flags">Payment Flags</h3>
<p>Transactions of the Payment type support additional values in the <a href="#flags"><code>Flags</code> field</a>, as follows:</p>
<table>
<thead>
<tr>
<th align="left">Flag Name</th>
<th align="left">Hex Value</th>
<th align="left">Decimal Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">tfNoDirectRipple</td>
<td align="left">0x00010000</td>
<td align="left">65536</td>
<td align="left">Do not use the default path; only use paths included in the <code>Paths</code> field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this.</td>
</tr>
<tr>
<td align="left">tfPartialPayment</td>
<td align="left">0x00020000</td>
<td align="left">131072</td>
<td align="left">If the specified <code>Amount</code> cannot be sent without spending more than <code>SendMax</code>, reduce the received amount instead of failing outright. See <a href="#partial-payments">Partial Payments</a> for more details.</td>
</tr>
<tr>
<td align="left">tfLimitQuality</td>
<td align="left">0x00040000</td>
<td align="left">262144</td>
<td align="left">Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of <code>Amount</code>:<code>SendMax</code>. See <a href="#limit-quality">Limit Quality</a> for details.</td>
</tr>
</tbody>
</table>
<h3 id="partial-payments">Partial Payments</h3>
<p>A partial payment allows a payment to succeed by reducing the amount received, instead of increasing the <code>SendMax</code>. Partial payments are useful for <a href="tutorial-gateway-guide.html#bouncing-payments">returning payments</a> without incurring additional costs to oneself.</p>
<p>By default, the <code>Amount</code> field of a Payment transaction specifies the amount of currency that is <em>received</em> by the account that is the destination of the payment. Any additional amount needed for fees or currency exchange is deducted from the sending account's balances, up to the <code>SendMax</code> amount. (If <code>SendMax</code> is not specified, that is equivalent to setting the <code>SendMax</code> to the <code>Amount</code> field.) If the amount needed to make the payment exceeds the <code>SendMax</code> parameter, or the full amount cannot be delivered for any other reason, the transaction fails.</p>
<p>The <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> allows you to make a "partial payment" instead. When this flag is enabled for a payment, it delivers as much as possible, up to the <code>Amount</code> value, without exceeding the <code>SendMax</code> value. Fees and currency exchange rates are calculated the same way, but the amount being sent automatically scales down until the total amount deducted from the sending account's balances is within <code>SendMax</code>. The transaction is considered successful as long as it delivers equal or more than the <code>DeliverMin</code> value; if DeliverMin is omitted, then any positive amount is considered a success. This means that partial payments can succeed at sending <em>some</em> of the intended value despite limitations including fees, lack of liquidity, insufficient space in the receiving account's trustlines, or other reasons.</p>
<p>A partial payment cannot provide the XRP to fund an address; this case returns the error code <code>telNO_DST_PARTIAL</code>. Direct XRP-to-XRP payments also cannot be partial payments <code>temBAD_SEND_XRP_PARTIAL</code>.</p>
<p>The amount of XRP used for the <a href="#transaction-cost">transaction cost</a> is always deducted from the sender’s account, regardless of the <em>tfPartialPayment</em> flag.</p>
<h4 id="partial-payments-warning">Partial Payments Warning</h4>
<p>When the <a href="#payment-flags"><em>tfPartialPayment</em> flag</a> is enabled, the <code>Amount</code> field <strong><em>is not guaranteed to be the amount received</em></strong>. The <a href="#delivered-amount"><code>delivered_amount</code></a> field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use <code>delivered_amount</code> instead of the <code>Amount</code> field to determine how much your account received instead.</p>
<h3 id="limit-quality">Limit Quality</h3>
<p>Ripple 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 <code>0.5</code>.</p>
<p>The <a href="#payment-flags"><em>tfLimitQuality</em> flag</a> allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination <code>Amount</code> divided by the <code>SendMax</code> amount (the numeric amounts only, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.</p>
<p>By itself, the tfLimitQuality flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average <em>average</em> quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the <a href="#transaction-results">transaction result</a> is <code>tecPATH_DRY</code>.</p>
<p>Consider the following example. If I am trying to send you 100 Chinese Yuan (<code>Amount</code> = 100 CNY) for 20 United States dollars (<code>SendMax</code> = 20 USD) or less, then the limit quality is <code>5</code>. Imagine one trader is offering ¥95 for $15 (a ratio of about <code>6.3</code> CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of <code>2.5</code> CNY per USD). If I were to take both offers to send you 100 CNY, then it would cost me 17 USD, for an average quality of about <code>5.9</code>.</p>
<p>Without the tfLimitQuality flag set, this transaction would succeed, because the $17 it costs me is within my specified <code>SendMax</code>. However, with the tfLimitQuality flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of <code>2.5</code>, which is worse than the limit quality of <code>5</code>.</p>
<p>The tfLimitQuality flag is most useful when combined with <a href="#partial-payments">partial payments</a>. When both <em>tfPartialPayment</em> and <em>tfLimitQuality</em> are set on a transaction, then the transaction delivers as much of the destination <code>Amount</code> as it can, without using any conversions that are worse than the limit quality.</p>
<p>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 <code>SendMax</code> of 20 USD and a destination <code>Amount</code> of 100 CNY, then the limit quality is still <code>5</code>. 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 <code>6.3</code>, but it rejects the ¥5/$2 offer because that offer's quality of <code>2.5</code> is worse than the quality limit of <code>5</code>. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates.</p>
<h2 id="setregularkey">SetRegularKey</h2>
<p><a href="https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp" title="Source">[Source]<br/></a></p>
<p>A SetRegularKey transaction changes the regular key associated with an address.</p>
<pre><code>{
"Flags": 0,
"TransactionType": "SetRegularKey",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"RegularKey": "rAR8rR8sUkBoCZFawhkWzY4Y5YoyuznwD"
}
</code></pre>
<table>
<thead>
<tr>
<th align="left">Field</th>
<th align="left">JSON Type</th>
<th align="left"><a href="https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp">Internal Type</a></th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">RegularKey</td>
<td align="left">String</td>
<td align="left">AccountID</td>
<td align="left">(Optional) A base-58-encoded <a href="reference-rippled.html#addresses">Ripple address</a> to use as the regular key. If omitted, removes the existing regular key.</td>
</tr>
</tbody>
</table>
<p>In addition to the master key, which is mathematically-related to an address, you can associate <strong>at most 1 additional key pair</strong> with an address using this type of transaction. The additional key pair is called a <em>regular key</em>. If your address has a regular key pair defined, you can use the secret key of the regular key pair to <a href="#authorizing-transactions">authorize transactions</a>.</p>
<p>A regular key pair is generated in the same way as any other Ripple keys (for example, with <a href="reference-rippled.html#wallet-propose">wallet_propose</a>), but it can be changed. A master key pair is an intrinsic part of an address's identity (the address is derived from the master public key). You can <a href="#accountset-flags">disable</a> a master key but you cannot change it.</p>
<p>You can protect your master secret by using a regular key instead of the master key to sign transactions whenever possible. If your regular key is compromised, but the master key is not, you can use a SetRegularKey transaction to regain control of your address. In some cases, you can even send a <a href="concept-transaction-cost.html#key-reset-transaction">key reset transaction</a> without paying the <a href="#transaction-cost">transaction cost</a>.</p>
<p>For even greater security, you can use <a href="#multi-signing">multi-signing</a>, but multi-signing requires additional XRP for the <a href="concept-transaction-cost.html">transaction cost</a> and <a href="concept-reserves.html">reserve</a>.</p>
<h2 id="signerlistset">SignerListSet</h2>
<p><a href="https://github.com/ripple/rippled/blob/ef511282709a6a0721b504c6b7703f9de3eecf38/src/ripple/app/tx/impl/SetSignerList.cpp" title="Source">[Source]<br/></a></p>
<p>The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to <a href="#multi-signing">multi-sign</a> a transaction. This transaction type was introduced by the <a href="concept-amendments.html#multisign">MultiSign amendment</a>. <a href="https://github.com/ripple/rippled/releases/tag/0.31.0" title="New in: rippled 0.31.0"><img alt="New in: rippled 0.31.0" class="dactyl_badge" src="https://img.shields.io/badge/New%20in-rippled%200.31.0-blue.svg"/></a></p>
<p>Example SignerListSet:</p>
<pre><code>{
"Flags": 0,
"TransactionType": "SignerListSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "10000",
"SignerQuorum": 3,
"SignerEntries": [
{
"SignerEntry": {
"Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"SignerWeight": 2
}
},
{
"SignerEntry": {
"Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
"SignerWeight": 1
}
},
{
"SignerEntry": {
"Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
"SignerWeight": 1
}
}
]
}
</code></pre>
<table>
<thead>
<tr>
<th align="left">Field</th>
<th align="left">JSON Type</th>
<th align="left"><a href="https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp">Internal Type</a></th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">SignerQuorum</td>
<td align="left">Number</td>
<td align="left">UInt32</td>
<td align="left">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 <code>0</code>.</td>
</tr>
<tr>
<td align="left">SignerEntries</td>
<td align="left">Array</td>
<td align="left">Array</td>
<td align="left">(Omitted when deleting) Array of <a href="reference-ledger-format.html#signerentry-object">SignerEntry objects</a>, indicating the addresses and weights of signers in this list. A SignerList must have at least 1 member and no more than 8 members. No address may appear more than once in the list, nor may the <code>Account</code> submitting the transaction appear in the list.</td>
</tr>
</tbody>
</table>
<p>An account may not have more than one SignerList. A successful SignerListSet transaction replaces the existing SignerList, if one exists. To delete a SignerList, you must set <code>SignerQuorum</code> to <code>0</code> <em>and</em> omit the <code>SignerEntries</code> field. Otherwise, the transaction fails with the error <a href="#tem-codes">temMALFORMED</a>. A transaction to delete a SignerList is considered successful even if there was no SignerList to delete.</p>
<p>You cannot create a SignerList such that the SignerQuorum could never be met. The SignerQuorum must be greater than 0 but less than or equal to the sum of the <code>SignerWeight</code> values in the list. Otherwise, the transaction fails with the error <a href="#tem-codes">temMALFORMED</a>.</p>
<p>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.</p>
<p>You cannot remove the last method of signing transactions from an account. If an account's master key is disabled (it has the <a href="reference-ledger-format.html#accountroot-flags"><code>lsfDisableMaster</code> flag</a> enabled) and the account does not have a <a href="#setregularkey">Regular Key</a> configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error <a href="#tec-codes">tecNO_ALTERNATIVE_KEY</a>.</p>
<h2 id="trustset">TrustSet</h2> <h2 id="trustset">TrustSet</h2>
<p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/SetTrust.cpp" title="Source">[Source]<br/></a></p> <p><a href="https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/SetTrust.cpp" title="Source">[Source]<br/></a></p>
<p>Create or modify a trust line linking two accounts.</p> <p>Create or modify a trust line linking two accounts.</p>
@@ -1299,66 +1364,6 @@
</tr> </tr>
</tbody> </tbody>
</table> </table>
<h2 id="signerlistset">SignerListSet</h2>
<p><a href="https://github.com/ripple/rippled/blob/ef511282709a6a0721b504c6b7703f9de3eecf38/src/ripple/app/tx/impl/SetSignerList.cpp" title="Source">[Source]<br/></a></p>
<p>The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to <a href="#multi-signing">multi-sign</a> a transaction. This transaction type was introduced by the <a href="concept-amendments.html#multisign">MultiSign amendment</a>. <a href="https://github.com/ripple/rippled/releases/tag/0.31.0" title="New in: rippled 0.31.0"><img alt="New in: rippled 0.31.0" class="dactyl_badge" src="https://img.shields.io/badge/New%20in-rippled%200.31.0-blue.svg"/></a></p>
<p>Example SignerListSet:</p>
<pre><code>{
"Flags": 0,
"TransactionType": "SignerListSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "10000",
"SignerQuorum": 3,
"SignerEntries": [
{
"SignerEntry": {
"Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"SignerWeight": 2
}
},
{
"SignerEntry": {
"Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
"SignerWeight": 1
}
},
{
"SignerEntry": {
"Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
"SignerWeight": 1
}
}
]
}
</code></pre>
<table>
<thead>
<tr>
<th align="left">Field</th>
<th align="left">JSON Type</th>
<th align="left"><a href="https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp">Internal Type</a></th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">SignerQuorum</td>
<td align="left">Number</td>
<td align="left">UInt32</td>
<td align="left">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 <code>0</code>.</td>
</tr>
<tr>
<td align="left">SignerEntries</td>
<td align="left">Array</td>
<td align="left">Array</td>
<td align="left">(Omitted when deleting) Array of <a href="reference-ledger-format.html#signerentry-object">SignerEntry objects</a>, indicating the addresses and weights of signers in this list. A SignerList must have at least 1 member and no more than 8 members. No address may appear more than once in the list, nor may the <code>Account</code> submitting the transaction appear in the list.</td>
</tr>
</tbody>
</table>
<p>An account may not have more than one SignerList. A successful SignerListSet transaction replaces the existing SignerList, if one exists. To delete a SignerList, you must set <code>SignerQuorum</code> to <code>0</code> <em>and</em> omit the <code>SignerEntries</code> field. Otherwise, the transaction fails with the error <a href="#tem-codes">temMALFORMED</a>. A transaction to delete a SignerList is considered successful even if there was no SignerList to delete.</p>
<p>You cannot create a SignerList such that the SignerQuorum could never be met. The SignerQuorum must be greater than 0 but less than or equal to the sum of the <code>SignerWeight</code> values in the list. Otherwise, the transaction fails with the error <a href="#tem-codes">temMALFORMED</a>.</p>
<p>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.</p>
<p>You cannot remove the last method of signing transactions from an account. If an account's master key is disabled (it has the <a href="reference-ledger-format.html#accountroot-flags"><code>lsfDisableMaster</code> flag</a> enabled) and the account does not have a <a href="#setregularkey">Regular Key</a> configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error <a href="#tec-codes">tecNO_ALTERNATIVE_KEY</a>.</p>
<h1 id="pseudo-transactions">Pseudo-Transactions</h1> <h1 id="pseudo-transactions">Pseudo-Transactions</h1>
<p>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.</p> <p>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.</p>
<p>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:</p> <p>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:</p>
@@ -1392,6 +1397,60 @@
</tr> </tr>
</tbody> </tbody>
</table> </table>
<h2 id="enableamendment">EnableAmendment</h2>
<p>Tracks the progress of the <a href="concept-amendments.html#amendment-process">amendment process</a> for changes in transaction processing. This can indicate that a proposed amendment gained or lost majority approval, or that an amendment has been enabled.</p>
<p class="devportal-callout note"><strong>Note:</strong> You cannot send a pseudo-transaction, but you may find one when processing ledgers.</p>
<table>
<thead>
<tr>
<th align="left">Field</th>
<th align="left">JSON Type</th>
<th align="left"><a href="https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp">Internal Type</a></th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">Amendment</td>
<td align="left">String</td>
<td align="left">Hash256</td>
<td align="left">A unique identifier for the amendment. This is not intended to be a human-readable name. See <a href="concept-amendments.html">Amendments</a> for a list of known amendments.</td>
</tr>
<tr>
<td align="left">LedgerSequence</td>
<td align="left">Number</td>
<td align="left">UInt32</td>
<td align="left">The index of the ledger version where this amendment appears. This distinguishes the pseudo-transaction from other occurrences of the same change.</td>
</tr>
</tbody>
</table>
<h3 id="enableamendment-flags">EnableAmendment Flags</h3>
<p>The <code>Flags</code> value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction.</p>
<p>A <code>Flags</code> value of <code>0</code> (no flags) indicates that the amendment has been enabled, and applies to all ledgers afterward. Other <code>Flags</code> values are as follows:</p>
<table>
<thead>
<tr>
<th align="left">Flag Name</th>
<th align="left">Hex Value</th>
<th align="left">Decimal Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">tfGotMajority</td>
<td align="left">0x00010000</td>
<td align="left">65536</td>
<td align="left">Support for this amendment increased to at least 80% of trusted validators starting with this ledger version.</td>
</tr>
<tr>
<td align="left">tfLostMajority</td>
<td align="left">0x00020000</td>
<td align="left">131072</td>
<td align="left">Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version.</td>
</tr>
</tbody>
</table>
<h2 id="setfee">SetFee</h2> <h2 id="setfee">SetFee</h2>
<p>A change in <a href="concept-transaction-cost.html">transaction cost</a> or <a href="concept-reserves.html">account reserve</a> requirements as a result of <a href="concept-fee-voting.html">Fee Voting</a>.</p> <p>A change in <a href="concept-transaction-cost.html">transaction cost</a> or <a href="concept-reserves.html">account reserve</a> requirements as a result of <a href="concept-fee-voting.html">Fee Voting</a>.</p>
<p class="devportal-callout note"><strong>Note:</strong> You cannot send a pseudo-transaction, but you may find one when processing ledgers.</p> <p class="devportal-callout note"><strong>Note:</strong> You cannot send a pseudo-transaction, but you may find one when processing ledgers.</p>
@@ -1452,60 +1511,6 @@
</tr> </tr>
</tbody> </tbody>
</table> </table>
<h2 id="enableamendment">EnableAmendment</h2>
<p>Tracks the progress of the <a href="concept-amendments.html#amendment-process">amendment process</a> for changes in transaction processing. This can indicate that a proposed amendment gained or lost majority approval, or that an amendment has been enabled.</p>
<p class="devportal-callout note"><strong>Note:</strong> You cannot send a pseudo-transaction, but you may find one when processing ledgers.</p>
<table>
<thead>
<tr>
<th align="left">Field</th>
<th align="left">JSON Type</th>
<th align="left"><a href="https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp">Internal Type</a></th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">Amendment</td>
<td align="left">String</td>
<td align="left">Hash256</td>
<td align="left">A unique identifier for the amendment. This is not intended to be a human-readable name. See <a href="concept-amendments.html">Amendments</a> for a list of known amendments.</td>
</tr>
<tr>
<td align="left">LedgerSequence</td>
<td align="left">Number</td>
<td align="left">UInt32</td>
<td align="left">The index of the ledger version where this amendment appears. This distinguishes the pseudo-transaction from other occurrences of the same change.</td>
</tr>
</tbody>
</table>
<h3 id="enableamendment-flags">EnableAmendment Flags</h3>
<p>The <code>Flags</code> value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction.</p>
<p>A <code>Flags</code> value of <code>0</code> (no flags) indicates that the amendment has been enabled, and applies to all ledgers afterward. Other <code>Flags</code> values are as follows:</p>
<table>
<thead>
<tr>
<th align="left">Flag Name</th>
<th align="left">Hex Value</th>
<th align="left">Decimal Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">tfGotMajority</td>
<td align="left">0x00010000</td>
<td align="left">65536</td>
<td align="left">Support for this amendment increased to at least 80% of trusted validators starting with this ledger version.</td>
</tr>
<tr>
<td align="left">tfLostMajority</td>
<td align="left">0x00020000</td>
<td align="left">131072</td>
<td align="left">Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version.</td>
</tr>
</tbody>
</table>
<h1 id="transaction-results">Transaction Results</h1> <h1 id="transaction-results">Transaction Results</h1>
<h2 id="immediate-response">Immediate Response</h2> <h2 id="immediate-response">Immediate Response</h2>
<p>The response from the <a href="reference-rippled.html#submit"><code>submit</code> command</a> contains a provisional result from the <code>rippled</code> server indicating what happened during local processing of the transaction.</p> <p>The response from the <a href="reference-rippled.html#submit"><code>submit</code> command</a> contains a provisional result from the <code>rippled</code> server indicating what happened during local processing of the transaction.</p>