-

Transactions

-

A Transaction is the only way to modify the Ripple Ledger. All transactions have certain fields in common:

+

Transactions Overview

+

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. Some ledger rules also generate 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.

-

There are several different types of transactions that do different actions, each with additional fields relevant to that type of action:

- -

Additionally, there are Pseudo-Transactions that are not created and submitted in the usual way, but may appear in ledgers:

- -

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
    • +
  • Common Fields of All Transactions
    • +
  • Transaction Types
  • Reliable Transaction Submission
  • Transaction Results - How to find and interpret transaction results
  • Full Transaction Response List - Complete table of all error codes
    • @@ -630,147 +614,27 @@ -

    Payment

    -

    [Source]

    -

    A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, this can involve additional exchanges of value, which occur atomically.)

    -

    Payments are also the only way to create accounts.

    -

    Example payment:

    -
    {
-  "TransactionType" : "Payment",
-  "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-  "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-  "Amount" : {
-     "currency" : "USD",
-     "value" : "1",
-     "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
-  },
-  "Fee": "10",
-  "Flags": 2147483648,
-  "Sequence": 2,
-}
-
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldJSON TypeInternal TypeDescription
    AmountCurrency AmountAmountThe amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the tfPartialPayment flag is set, deliver up to this amount instead.
    DestinationStringAccountThe unique address of the account receiving the payment.
    DestinationTagUnsigned IntegerUInt32(Optional) Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay.
    InvoiceIDStringHash256(Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment.
    PathsArray of path arraysPathSet(Optional, auto-fillable) Array of payment paths to be used for this transaction. Must be omitted for XRP-to-XRP transactions.
    SendMaxCurrency AmountAmount(Optional) Highest amount of source currency this transaction is allowed to cost, including transfer fees, exchange rates, and slippage. Does not include the XRP destroyed as a cost for submitting the transaction. 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.
    DeliverMinCurrency AmountAmount(Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a partial payment. For non-XRP amounts, the nested field names are lower-case.
    -

    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. However, when describing payments, there are special rules for the issuer field in the Amount and SendMax fields of a payment.

    +

    Transaction Types

    +

    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.

    +

    All transactions have certain fields in common:

      -
    • 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.
      • +
    • Common Fields
    -

    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 to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new AccountRoot node 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:

    +

    Each transaction type has additional fields relevant to the type of action it causes:

    +

    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:

    + -

    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.

    -

    Payment Flags

    -

    Transactions of the Payment type support additional values in the Flags field, as follows:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Flag NameHex ValueDecimal ValueDescription
    tfNoDirectRipple0x0001000065536Do 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.
    tfPartialPayment0x00020000131072If the specified Amount cannot be sent without spending more than SendMax, reduce the received amount instead of failing outright. See Partial Payments for more details.
    tfLimitQuality0x00040000262144Only 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 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 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 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 is always deducted from the sender’s account, regardless of the tfPartialPayment flag.

    -

    Partial Payments Warning

    -

    When the tfPartialPayment flag is enabled, the Amount field is not guaranteed to be the amount received. The 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 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 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. 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.

    AccountSet

    [Source]

    An AccountSet transaction modifies the properties of an account in the Ripple Consensus Ledger.

    @@ -977,15 +841,17 @@

    TransferRate

    The TransferRate field specifies a fee to charge whenever counterparties transfer the currency you issue. See Transfer Fees article in the Knowledge Center for more information.

    In rippled's WebSocket and JSON-RPC APIs, the TransferRate is represented as an integer, the amount that must be sent for 1 billion units to arrive. For example, a 20% transfer fee is represented as the value 1200000000. The value cannot be less than 1000000000. (Less than that would indicate giving away money for sending transactions, which is exploitable.) You can specify 0 as a shortcut for 1000000000, meaning no fee.

    -

    SetRegularKey

    -

    [Source]

    -

    A SetRegularKey transaction changes the regular key associated with an address.

    +

    OfferCancel

    +

    [Source]

    +

    An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledger.

    {
-    "Flags": 0,
-    "TransactionType": "SetRegularKey",
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
+    "TransactionType": "OfferCancel",
+    "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
     "Fee": "12",
-    "RegularKey": "rAR8rR8sUkBoCZFawhkWzY4Y5YoyuznwD"
+    "Flags": 0,
+    "LastLedgerSequence": 7108629,
+    "OfferSequence": 6,
+    "Sequence": 7
 }
    @@ -999,17 +865,15 @@ - - - - + + + +
    RegularKeyStringAccountID(Optional) A base-58-encoded Ripple address to use as the regular key. If omitted, removes the existing regular key.OfferSequenceUnsigned IntegerUInt32The 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.

    -

    A regular key pair is generated in the same way as any other Ripple keys (for example, with 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 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 without paying the transaction cost.

    -

    For even greater security, you can use multi-signing, but multi-signing requires additional XRP for the transaction cost and reserve.

    +

    Tip: To remove an old offer and replace it with a new one, you can use an OfferCreate transaction with an OfferSequence parameter, instead of using OfferCancel and another OfferCreate.

    +

    The OfferCancel method returns tesSUCCESS even if it did not find an offer with the matching sequence number.

    OfferCreate

    [Source]

    An OfferCreate transaction is effectively a limit order. 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.

    @@ -1149,17 +1013,23 @@
    • tfImmediateOrCancel and tfFillOrKill
    -

    OfferCancel

    -

    [Source]

    -

    An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledger.

    +

    Payment

    +

    [Source]

    +

    A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, this can involve additional exchanges of value, which occur atomically.)

    +

    Payments are also the only way to create accounts.

    +

    Example payment:

    {
-    "TransactionType": "OfferCancel",
-    "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-    "Fee": "12",
-    "Flags": 0,
-    "LastLedgerSequence": 7108629,
-    "OfferSequence": 6,
-    "Sequence": 7
+  "TransactionType" : "Payment",
+  "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
+  "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
+  "Amount" : {
+     "currency" : "USD",
+     "value" : "1",
+     "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
+  },
+  "Fee": "10",
+  "Flags": 2147483648,
+  "Sequence": 2,
 }
    @@ -1173,15 +1043,210 @@ - + + + + + + + + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + +
    OfferSequenceAmountCurrency AmountAmountThe amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the tfPartialPayment flag is set, deliver up to this amount instead.
    DestinationStringAccountThe unique address of the account receiving the payment.
    DestinationTag Unsigned Integer UInt32The 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.(Optional) Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay.
    InvoiceIDStringHash256(Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment.
    PathsArray of path arraysPathSet(Optional, auto-fillable) Array of payment paths to be used for this transaction. Must be omitted for XRP-to-XRP transactions.
    SendMaxCurrency AmountAmount(Optional) Highest amount of source currency this transaction is allowed to cost, including transfer fees, exchange rates, and slippage. Does not include the XRP destroyed as a cost for submitting the transaction. 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.
    DeliverMinCurrency AmountAmount(Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a partial payment. 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 transaction with an OfferSequence parameter, instead of using OfferCancel and another OfferCreate.

    -

    The OfferCancel method returns tesSUCCESS even if it did not find an offer with the matching sequence number.

    +

    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. 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 to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new AccountRoot node 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.

    +

    Payment Flags

    +

    Transactions of the Payment type support additional values in the Flags field, as follows:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Flag NameHex ValueDecimal ValueDescription
    tfNoDirectRipple0x0001000065536Do 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.
    tfPartialPayment0x00020000131072If the specified Amount cannot be sent without spending more than SendMax, reduce the received amount instead of failing outright. See Partial Payments for more details.
    tfLimitQuality0x00040000262144Only 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 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 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 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 is always deducted from the sender’s account, regardless of the tfPartialPayment flag.

    +

    Partial Payments Warning

    +

    When the tfPartialPayment flag is enabled, the Amount field is not guaranteed to be the amount received. The 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 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 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. 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]

    +

    A SetRegularKey transaction changes the regular key associated with an address.

    +
    {
+    "Flags": 0,
+    "TransactionType": "SetRegularKey",
+    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
+    "Fee": "12",
+    "RegularKey": "rAR8rR8sUkBoCZFawhkWzY4Y5YoyuznwD"
+}
+
    + + + + + + + + + + + + + + + + + +
    FieldJSON TypeInternal TypeDescription
    RegularKeyStringAccountID(Optional) A base-58-encoded Ripple address 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.

    +

    A regular key pair is generated in the same way as any other Ripple keys (for example, with 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 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 without paying the transaction cost.

    +

    For even greater security, you can use multi-signing, but multi-signing requires additional XRP for the transaction cost and reserve.

    +

    SignerListSet

    +

    [Source]

    +

    The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to multi-sign a transaction. This transaction type was introduced by the MultiSign amendment. 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
+            }
+        }
+    ]
+}
+
    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldJSON TypeInternal TypeDescription
    SignerQuorumNumberUInt32A 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.
    SignerEntriesArrayArray(Omitted when deleting) Array of SignerEntry objects, 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. 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.

    +

    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 enabled) and the account does not have a Regular Key configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error tecNO_ALTERNATIVE_KEY.

    TrustSet

    [Source]

    Create or modify a trust line linking two accounts.

    @@ -1299,66 +1364,6 @@ -

    SignerListSet

    -

    [Source]

    -

    The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to multi-sign a transaction. This transaction type was introduced by the MultiSign amendment. 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
-            }
-        }
-    ]
-}
-
    - - - - - - - - - - - - - - - - - - - - - - - -
    FieldJSON TypeInternal TypeDescription
    SignerQuorumNumberUInt32A 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.
    SignerEntriesArrayArray(Omitted when deleting) Array of SignerEntry objects, 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. 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.

    -

    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 enabled) and the account does not have a Regular Key configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error tecNO_ALTERNATIVE_KEY.

    Pseudo-Transactions

    Pseudo-Transactions are never submitted by users, nor propagated through the network. Instead, a server may choose to inject them in a proposed ledger directly. If enough servers inject an equivalent pseudo-transaction for it to pass consensus, then it becomes included in the ledger, and appears in ledger data thereafter.

    Some of the fields that are mandatory for normal transactions do not make sense for pseudo-transactions. In those cases, the pseudo-transaction has the following default values:

    @@ -1392,6 +1397,60 @@ +

    EnableAmendment

    +

    Tracks the progress of the 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.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldJSON TypeInternal TypeDescription
    AmendmentStringHash256A unique identifier for the amendment. This is not intended to be a human-readable name. See Amendments for a list of known amendments.
    LedgerSequenceNumberUInt32The 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 NameHex ValueDecimal ValueDescription
    tfGotMajority0x0001000065536Support for this amendment increased to at least 80% of trusted validators starting with this ledger version.
    tfLostMajority0x00020000131072Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version.

    SetFee

    A change in transaction cost or account reserve requirements as a result of Fee Voting.

    Note: You cannot send a pseudo-transaction, but you may find one when processing ledgers.

    @@ -1452,60 +1511,6 @@ -

    EnableAmendment

    -

    Tracks the progress of the 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.

    - - - - - - - - - - - - - - - - - - - - - - - -
    FieldJSON TypeInternal TypeDescription
    AmendmentStringHash256A unique identifier for the amendment. This is not intended to be a human-readable name. See Amendments for a list of known amendments.
    LedgerSequenceNumberUInt32The 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 NameHex ValueDecimal ValueDescription
    tfGotMajority0x0001000065536Support for this amendment increased to at least 80% of trusted validators starting with this ledger version.
    tfLostMajority0x00020000131072Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version.

    Transaction Results

    Immediate Response

    The response from the submit command contains a provisional result from the rippled server indicating what happened during local processing of the transaction.