From bf1343922dfbcca8fe5644ef21e3258150f06909 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 4 Mar 2020 17:22:41 -0800 Subject: [PATCH 1/5] submit method: new response fields (draft) --- .../public-rippled-methods/transaction-methods/submit.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md index d1e0d12d04..b85d0dd47c 100644 --- a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md +++ b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md @@ -261,6 +261,14 @@ The response follows the [standard format][], with a successful result containin | `engine_result_message` | String | Human-readable explanation of the transaction's preliminary result | | `tx_blob` | String | The complete transaction in hex string format | | `tx_json` | Object | The complete transaction in JSON format | +| `accepted` | Boolean | _(May be omitted)_ The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. A value of `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again. [New in: rippled 1.5.0][] | +| `account_sequence_available` | Number | _(May be omitted)_ The next [Sequence Number][] available for this account after all pending and queued transactions. ***TODO: queue?*** [New in: rippled 1.5.0][] | +| `account_sequence_next` | number | _(May be omitted)_ ***TODO: diff from _available?*** [New in: rippled 1.5.0][] | +| `applied` | Boolean | _(May be omitted)_ The value `true` indicates that this transaction was applied to the open ledger. ***TODO: excludes tec?*** [New in: rippled 1.5.0][] | +| `broadcast` | Boolean | _(May be omitted)_ The value `true` indicates this transaction was broadcast to other servers in the peer-to-peer XRP Ledger network. The value `false` indicates the transaction was not yet broadcast to any other servers. [New in: rippled 1.5.0][] | +| `kept` | Boolean | _(May be omitted)_ The value `true` indicates that the transaction was kept to be retried later. [New in: rippled 1.5.0][] | +| `queued` | Boolean | _(May be omitted)_ The value `true` indicates the transaction was put in the [Transaction Queue](transaction-queue.html), which means it is likely to be included in a future ledger version. [New in: rippled 1.5.0][] | +| `open_ledger_cost` | String | _(May be omitted)_ The current [open ledger cost](transaction-cost.html#open-ledger-cost) after processing this transaction. Transactions with a lower cost are likely to be [queued](transaction-queue.html). [New in: rippled 1.5.0][] | **Caution:** Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does _not_ indicate that the transaction executed successfully. Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](transaction-results.html) for details, and do not consider the transaction's results final until they appear in a validated ledger version. From fe0454e8f38173518afb9be186e35dbaae16ba28 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Thu, 5 Mar 2020 17:19:22 -0800 Subject: [PATCH 2/5] submit: clarify augmented response details --- .../transaction-methods/submit.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md index b85d0dd47c..c21f308049 100644 --- a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md +++ b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md @@ -79,9 +79,9 @@ The request includes the following parameters: | `seed_hex` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Must be in hexadecimal format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `passphrase`. | | `passphrase` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it, as a string passphrase. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `seed_hex`. | | `key_type` | String | _(Optional)_ Type of cryptographic key provided in this request. Valid types are `secp256k1` or `ed25519`. Defaults to `secp256k1`. Cannot be used with `secret`. **Caution:** Ed25519 support is experimental. | -| `fail_hard` | Boolean | (Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers | +| `fail_hard` | Boolean | _(Optional)_ If `true`, and the transaction fails locally, do not retry or relay the transaction to other servers. The default is `false`. [Updated in: rippled 1.5.0][] | | `offline` | Boolean | (Optional, defaults to false) If true, when constructing the transaction, do not try to automatically fill in or validate values. | -| `build_path` | Boolean | _(Optional)_ If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. You must omit this field if the transaction is a direct XRP-to-XRP transfer. **Caution:** The server looks for the presence or absence of this field, not its value. This behavior may change. | +| `build_path` | Boolean | _(Optional)_ If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. You must omit this field if the transaction is a direct XRP-to-XRP transfer. **Caution:** The server looks for the presence or absence of this field, not its value. This behavior may change. | | `fee_mult_max` | Integer | (Optional, defaults to 10, recommended value 1000) If the `Fee` parameter is omitted, this field limits the automatically-provided `Fee` value so that it is less than or equal to the long-term base transaction cost times this value. | | `fee_div_max` | Integer | (Optional, defaults to 1) Used with `fee_mult_max` to create a fractional multiplier for the limit. Specifically, the server multiplies its base [transaction cost](transaction-cost.html) by `fee_mult_max`, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided `Fee` value would be over the limit, the submit command fails. [New in: rippled 0.30.1][] | @@ -261,14 +261,14 @@ The response follows the [standard format][], with a successful result containin | `engine_result_message` | String | Human-readable explanation of the transaction's preliminary result | | `tx_blob` | String | The complete transaction in hex string format | | `tx_json` | Object | The complete transaction in JSON format | -| `accepted` | Boolean | _(May be omitted)_ The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. A value of `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again. [New in: rippled 1.5.0][] | -| `account_sequence_available` | Number | _(May be omitted)_ The next [Sequence Number][] available for this account after all pending and queued transactions. ***TODO: queue?*** [New in: rippled 1.5.0][] | -| `account_sequence_next` | number | _(May be omitted)_ ***TODO: diff from _available?*** [New in: rippled 1.5.0][] | -| `applied` | Boolean | _(May be omitted)_ The value `true` indicates that this transaction was applied to the open ledger. ***TODO: excludes tec?*** [New in: rippled 1.5.0][] | -| `broadcast` | Boolean | _(May be omitted)_ The value `true` indicates this transaction was broadcast to other servers in the peer-to-peer XRP Ledger network. The value `false` indicates the transaction was not yet broadcast to any other servers. [New in: rippled 1.5.0][] | -| `kept` | Boolean | _(May be omitted)_ The value `true` indicates that the transaction was kept to be retried later. [New in: rippled 1.5.0][] | -| `queued` | Boolean | _(May be omitted)_ The value `true` indicates the transaction was put in the [Transaction Queue](transaction-queue.html), which means it is likely to be included in a future ledger version. [New in: rippled 1.5.0][] | -| `open_ledger_cost` | String | _(May be omitted)_ The current [open ledger cost](transaction-cost.html#open-ledger-cost) after processing this transaction. Transactions with a lower cost are likely to be [queued](transaction-queue.html). [New in: rippled 1.5.0][] | +| `accepted` | Boolean | The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. A value of `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time. [New in: rippled 1.5.0][] | +| `account_sequence_available` | Number | The next [Sequence Number][] available for this account after all pending and [queued](transaction-queue.html) transactions. [New in: rippled 1.5.0][] | +| `account_sequence_next` | number | The next [Sequence Number][] for this account after all pending transactions, not counting transactions in the queue. [New in: rippled 1.5.0][] | +| `applied` | Boolean | The value `true` indicates that this transaction was applied to the open ledger. ***TODO: https://github.com/ripple/rippled/issues/3285*** [New in: rippled 1.5.0][] | +| `broadcast` | Boolean | The value `true` indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. (Note: if the server has no peers, such as in [stand-alone mode](rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode), the server uses the value `true` for cases where it _would_ have broadcast the transaction.) The value `false` indicates the transaction was not broadcast to any other servers. [New in: rippled 1.5.0][] | +| `kept` | Boolean | The value `true` indicates that the transaction was kept to be retried later. [New in: rippled 1.5.0][] | +| `queued` | Boolean | The value `true` indicates the transaction was put in the [Transaction Queue](transaction-queue.html), which means it is likely to be included in a future ledger version. [New in: rippled 1.5.0][] | +| `open_ledger_cost` | String | The current [open ledger cost](transaction-cost.html#open-ledger-cost) after processing this transaction. Transactions with a lower cost are likely to be [queued](transaction-queue.html). [New in: rippled 1.5.0][] | **Caution:** Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does _not_ indicate that the transaction executed successfully. Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](transaction-results.html) for details, and do not consider the transaction's results final until they appear in a validated ledger version. From db25e0124c884f5462baf268f2caed3b3712f54e Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 11 Mar 2020 02:17:06 -0700 Subject: [PATCH 3/5] Augmented submit: edits for v1.5.0-rc2 --- .../transaction-methods/submit.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md index c21f308049..c652ab412c 100644 --- a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md +++ b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md @@ -256,23 +256,23 @@ The response follows the [standard format][], with a successful result containin | `Field` | Type | Description | |:------------------------|:--------|:-----------------------------------------| -| `engine_result` | String | Code indicating the preliminary result of the transaction, for example `tesSUCCESS` | -| `engine_result_code` | Integer | Numeric code indicating the preliminary result of the transaction, directly correlated to `engine_result` | +| `engine_result` | String | Text [result code](transaction-results.html) indicating the preliminary result of the transaction, for example `tesSUCCESS` | +| `engine_result_code` | Integer | Numeric version of the [result code](transaction-results.html). **Not recommended.** | | `engine_result_message` | String | Human-readable explanation of the transaction's preliminary result | | `tx_blob` | String | The complete transaction in hex string format | | `tx_json` | Object | The complete transaction in JSON format | -| `accepted` | Boolean | The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. A value of `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time. [New in: rippled 1.5.0][] | -| `account_sequence_available` | Number | The next [Sequence Number][] available for this account after all pending and [queued](transaction-queue.html) transactions. [New in: rippled 1.5.0][] | -| `account_sequence_next` | number | The next [Sequence Number][] for this account after all pending transactions, not counting transactions in the queue. [New in: rippled 1.5.0][] | -| `applied` | Boolean | The value `true` indicates that this transaction was applied to the open ledger. ***TODO: https://github.com/ripple/rippled/issues/3285*** [New in: rippled 1.5.0][] | -| `broadcast` | Boolean | The value `true` indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. (Note: if the server has no peers, such as in [stand-alone mode](rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode), the server uses the value `true` for cases where it _would_ have broadcast the transaction.) The value `false` indicates the transaction was not broadcast to any other servers. [New in: rippled 1.5.0][] | -| `kept` | Boolean | The value `true` indicates that the transaction was kept to be retried later. [New in: rippled 1.5.0][] | -| `queued` | Boolean | The value `true` indicates the transaction was put in the [Transaction Queue](transaction-queue.html), which means it is likely to be included in a future ledger version. [New in: rippled 1.5.0][] | -| `open_ledger_cost` | String | The current [open ledger cost](transaction-cost.html#open-ledger-cost) after processing this transaction. Transactions with a lower cost are likely to be [queued](transaction-queue.html). [New in: rippled 1.5.0][] | +| `accepted` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. A value of `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time. [New in: rippled 1.5.0][] | +| `account_sequence_available` | Number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] available for this account after all pending and [queued](transaction-queue.html) transactions. [New in: rippled 1.5.0][] | +| `account_sequence_next` | number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] for this account after all pending transactions, not counting transactions in the queue. [New in: rippled 1.5.0][] | +| `applied` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that this transaction was applied to the open ledger. In this case, the transaction is likely, but not guaranteed, to be validated in the next ledger version. [New in: rippled 1.5.0][] | +| `broadcast` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. (Note: if the server has no peers, such as in [stand-alone mode](rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode), the server uses the value `true` for cases where it _would_ have broadcast the transaction.) The value `false` indicates the transaction was not broadcast to any other servers. [New in: rippled 1.5.0][] | +| `kept` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was kept to be retried later. [New in: rippled 1.5.0][] | +| `queued` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates the transaction was put in the [Transaction Queue](transaction-queue.html), which means it is likely to be included in a future ledger version. [New in: rippled 1.5.0][] | +| `open_ledger_cost` | String | _(Omitted in sign-and-submit mode)_ The current [open ledger cost](transaction-cost.html#open-ledger-cost) after processing this transaction. Transactions with a lower cost are likely to be [queued](transaction-queue.html). [New in: rippled 1.5.0][] | -**Caution:** Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does _not_ indicate that the transaction executed successfully. Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](transaction-results.html) for details, and do not consider the transaction's results final until they appear in a validated ledger version. +**Warning:** Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does _not_ indicate that the transaction executed successfully. Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](transaction-results.html) for details, and do not consider the transaction's results final until they appear in a validated ledger version. -**Caution:** If this command results in an error messages, the message can contain the secret key from the request. (This is not a problem if the request contained a signed tx_blob instead.) Make sure that these errors are not visible to others. +**Caution:** If this command results in an error message, the message can contain the secret key from the request. (This can only happen in sign-and-submit mode.) Make sure that these errors are not visible to others. * Do not write an error including your secret key to a log file that can be seen by multiple people. * Do not paste an error including your secret key to a public place for debugging. From 165100c78aaa2707615c0708b44331b208073e8d Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Fri, 13 Mar 2020 15:16:28 -0700 Subject: [PATCH 4/5] Augmented submit: rephrase some sign/submit fields --- .../transaction-methods/sign.md | 10 ++++++---- .../transaction-methods/submit.md | 16 +++++++++------- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/content/references/rippled-api/public-rippled-methods/transaction-methods/sign.md b/content/references/rippled-api/public-rippled-methods/transaction-methods/sign.md index 1f23d723e8..ca52a2fac2 100644 --- a/content/references/rippled-api/public-rippled-methods/transaction-methods/sign.md +++ b/content/references/rippled-api/public-rippled-methods/transaction-methods/sign.md @@ -85,9 +85,9 @@ The request includes the following parameters: | `passphrase` | String | _(Optional)_ The secret seed of the account supplying the transaction, used to sign it, as a string passphrase. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `seed_hex`. | | `key_type` | String | _(Optional)_ The [signing algorithm](cryptographic-keys.html#signing-algorithms) of the cryptographic key pair provided. Valid types are `secp256k1` or `ed25519`. Defaults to `secp256k1`. Cannot be used with `secret`. | | `offline` | Boolean | _(Optional)_ If `true`, when constructing the transaction, do not try to [automatically fill](#auto-fillable-fields) any transaction details. The default is `false`. | -| `build_path` | Boolean | _(Optional)_ If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. **Caution:** The server looks for the presence or absence of this field, not its value. This behavior may change. | -| `fee_mult_max` | Integer | _(Optional)_ Limits how high the [automatically-provided `Fee` field](transaction-common-fields.html#auto-fillable-fields) can be. Signing fails with the error `rpcHIGH_FEE` if the current [load multiplier on the transaction cost](transaction-cost.html#local-load-cost) is greater than (`fee_mult_max` ÷ `fee_div_max`). Ignored if you specify the `Fee` field of the transaction ([transaction cost](transaction-cost.html)). The default is `10`. | -| `fee_div_max` | Integer | _(Optional)_ Signing fails with the error `rpcHIGH_FEE` if the current [load multiplier on the transaction cost](transaction-cost.html#local-load-cost) is greater than (`fee_mult_max` ÷ `fee_div_max`). Ignored if you specify the `Fee` field of the transaction ([transaction cost](transaction-cost.html)). The default is `1`. [New in: rippled 0.30.1][] | +| `build_path` | Boolean | _(Optional)_ If this field is provided, the server [auto-fills](transaction-common-fields.html#auto-fillable-fields) the `Paths` field of a [Payment transaction][] before signing. You must omit this field if the transaction is a [direct XRP payment](direct-xrp-payments.html) or if it is not a Payment-type transaction. **Caution:** The server looks for the presence or absence of this field, not its value. This behavior may change. ([Issue #3272](https://github.com/ripple/rippled/issues/3272)) | +| `fee_mult_max` | Integer | _(Optional)_ Signing fails with the error `rpcHIGH_FEE` if the [auto-filled `Fee` value](transaction-common-fields.html#auto-fillable-fields) would be greater than the [reference transaction cost](transaction-cost.html#special-transaction-costs) × `fee_mult_max` ÷ `fee_div_max`. This field has no effect if you explicitly specify the `Fee` field of the transaction. The default is `10`. | +| `fee_div_max` | Integer | _(Optional)_ Signing fails with the error `rpcHIGH_FEE` if the [auto-filled `Fee` value](transaction-common-fields.html#auto-fillable-fields) would be greater than the [reference transaction cost](transaction-cost.html#special-transaction-costs) × `fee_mult_max` ÷ `fee_div_max`. This field has no effect if you explicitly specify the `Fee` field of the transaction. The default is `1`. [New in: rippled 0.30.1][] | ### Auto-Fillable Fields @@ -217,5 +217,7 @@ The response follows the [standard format][], with a successful result containin * `noPath` - The transaction did not include paths, and the server was unable to find a path by which this payment can occur. -{% include '_snippets/rippled_versions.md' %} + {% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md index c652ab412c..efe6c65de7 100644 --- a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md +++ b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md @@ -81,9 +81,9 @@ The request includes the following parameters: | `key_type` | String | _(Optional)_ Type of cryptographic key provided in this request. Valid types are `secp256k1` or `ed25519`. Defaults to `secp256k1`. Cannot be used with `secret`. **Caution:** Ed25519 support is experimental. | | `fail_hard` | Boolean | _(Optional)_ If `true`, and the transaction fails locally, do not retry or relay the transaction to other servers. The default is `false`. [Updated in: rippled 1.5.0][] | | `offline` | Boolean | (Optional, defaults to false) If true, when constructing the transaction, do not try to automatically fill in or validate values. | -| `build_path` | Boolean | _(Optional)_ If provided for a Payment-type transaction, automatically fill in the `Paths` field before signing. You must omit this field if the transaction is a direct XRP-to-XRP transfer. **Caution:** The server looks for the presence or absence of this field, not its value. This behavior may change. | -| `fee_mult_max` | Integer | (Optional, defaults to 10, recommended value 1000) If the `Fee` parameter is omitted, this field limits the automatically-provided `Fee` value so that it is less than or equal to the long-term base transaction cost times this value. | -| `fee_div_max` | Integer | (Optional, defaults to 1) Used with `fee_mult_max` to create a fractional multiplier for the limit. Specifically, the server multiplies its base [transaction cost](transaction-cost.html) by `fee_mult_max`, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided `Fee` value would be over the limit, the submit command fails. [New in: rippled 0.30.1][] | +| `build_path` | Boolean | _(Optional)_ If this field is provided, the server [auto-fills](transaction-common-fields.html#auto-fillable-fields) the `Paths` field of a [Payment transaction][] before signing. You must omit this field if the transaction is a [direct XRP payment](direct-xrp-payments.html) or if it is not a Payment-type transaction. **Caution:** The server looks for the presence or absence of this field, not its value. This behavior may change. ([Issue #3272](https://github.com/ripple/rippled/issues/3272)) | +| `fee_mult_max` | Integer | _(Optional)_ Sign-and-submit fails with the error `rpcHIGH_FEE` if the [auto-filled `Fee` value](transaction-common-fields.html#auto-fillable-fields) would be greater than the [reference transaction cost](transaction-cost.html#special-transaction-costs) × `fee_mult_max` ÷ `fee_div_max`. This field has no effect if you explicitly specify the `Fee` field of the transaction. The default is `10`. | +| `fee_div_max` | Integer | _(Optional)_ Sign-and-submit fails with the error `rpcHIGH_FEE` if the [auto-filled `Fee` value](transaction-common-fields.html#auto-fillable-fields) would be greater than the [reference transaction cost](transaction-cost.html#special-transaction-costs) × `fee_mult_max` ÷ `fee_div_max`. This field has no effect if you explicitly specify the `Fee` field of the transaction. The default is `1`. [New in: rippled 0.30.1][] | See the [sign method][] for detailed information on how the server automatically fills in certain fields. @@ -261,9 +261,9 @@ The response follows the [standard format][], with a successful result containin | `engine_result_message` | String | Human-readable explanation of the transaction's preliminary result | | `tx_blob` | String | The complete transaction in hex string format | | `tx_json` | Object | The complete transaction in JSON format | -| `accepted` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. A value of `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time. [New in: rippled 1.5.0][] | -| `account_sequence_available` | Number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] available for this account after all pending and [queued](transaction-queue.html) transactions. [New in: rippled 1.5.0][] | -| `account_sequence_next` | number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] for this account after all pending transactions, not counting transactions in the queue. [New in: rippled 1.5.0][] | +| `accepted` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. The value `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time. [New in: rippled 1.5.0][] | +| `account_sequence_available` | Number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] available for the sending account after all pending and [queued](transaction-queue.html) transactions. [New in: rippled 1.5.0][] | +| `account_sequence_next` | number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] for the sending account after all transactions that have been provisionally applied, but not transactions in the [queue](transaction-queue.html). [New in: rippled 1.5.0][] | | `applied` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that this transaction was applied to the open ledger. In this case, the transaction is likely, but not guaranteed, to be validated in the next ledger version. [New in: rippled 1.5.0][] | | `broadcast` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. (Note: if the server has no peers, such as in [stand-alone mode](rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode), the server uses the value `true` for cases where it _would_ have broadcast the transaction.) The value `false` indicates the transaction was not broadcast to any other servers. [New in: rippled 1.5.0][] | | `kept` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was kept to be retried later. [New in: rippled 1.5.0][] | @@ -293,5 +293,7 @@ The response follows the [standard format][], with a successful result containin * `tooBusy` - The transaction did not include paths, but the server is too busy to do pathfinding right now. Does not occur if you are connected as an admin. (Sign-and-Submit mode only) -{% include '_snippets/rippled_versions.md' %} + {% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} From c289cd00cb50b92dec461ad0e41864da1264750b Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Mon, 23 Mar 2020 17:50:23 -0700 Subject: [PATCH 5/5] augmented submit: add validated_ledger_index field, examples --- .../transaction-methods/submit.md | 87 ++++++++++++------- 1 file changed, 58 insertions(+), 29 deletions(-) diff --git a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md index efe6c65de7..bfe5861deb 100644 --- a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md +++ b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md @@ -158,15 +158,23 @@ An example of a successful response: *WebSocket* -``` +```json { "id": 1, "status": "success", "type": "response", "result": { + "accepted" : true, + "account_sequence_available" : 362, + "account_sequence_next" : 362, + "applied" : true, + "broadcast" : true, "engine_result": "tesSUCCESS", "engine_result_code": 0, "engine_result_message": "The transaction was applied. Only final in a validated ledger.", + "kept" : true, + "open_ledger_cost": "10", + "queued" : false, "tx_blob": "1200002280000000240000016861D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7446304402200E5C2DD81FDF0BE9AB2A8D797885ED49E804DBF28E806604D878756410CA98B102203349581946B0DDA06B36B35DBC20EDA27552C1F167BCF5C6ECFF49C6A46F858081144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754", "tx_json": { "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", @@ -183,20 +191,29 @@ An example of a successful response: "TransactionType": "Payment", "TxnSignature": "304402200E5C2DD81FDF0BE9AB2A8D797885ED49E804DBF28E806604D878756410CA98B102203349581946B0DDA06B36B35DBC20EDA27552C1F167BCF5C6ECFF49C6A46F8580", "hash": "4D5D90890F8D49519E4151938601EF3D0B30B16CD6A519D9C99102C9FA77F7E0" - } + }, + "validated_ledger_index" : 21184416 } } ``` *JSON-RPC* -``` +```json { "result": { + "accepted" : true, + "account_sequence_available" : 362, + "account_sequence_next" : 362, + "applied" : true, + "broadcast" : true, "engine_result": "tesSUCCESS", "engine_result_code": 0, "engine_result_message": "The transaction was applied. Only final in a validated ledger.", "status": "success", + "kept" : true, + "open_ledger_cost": "10", + "queued" : false, "tx_blob": "1200002280000000240000016961D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100A7CCD11455E47547FF617D5BFC15D120D9053DFD0536B044F10CA3631CD609E502203B61DEE4AC027C5743A1B56AF568D1E2B8E79BB9E9E14744AC87F38375C3C2F181144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754", "tx_json": { "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", @@ -214,39 +231,50 @@ An example of a successful response: "TxnSignature": "3045022100A7CCD11455E47547FF617D5BFC15D120D9053DFD0536B044F10CA3631CD609E502203B61DEE4AC027C5743A1B56AF568D1E2B8E79BB9E9E14744AC87F38375C3C2F1", "hash": "5B31A7518DC304D5327B4887CD1F7DC2C38D5F684170097020C7C9758B973847" } - } + }, + "validated_ledger_index" : 21184416 } ``` *Commandline* -``` +```json Loading: "/etc/rippled.cfg" Connecting to 127.0.0.1:5005 + { - "result" : { - "engine_result" : "tesSUCCESS", - "engine_result_code" : 0, - "engine_result_message" : "The transaction was applied. Only final in a validated ledger.", - "status" : "success", - "tx_blob" : "1200002280000000240000016A61D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100FBBF74057359EC31C3647AD3B33D8954730E9879C35034374858A76B7CFA643102200EAA08C61071396E9CF0987FBEA16CF113CBD8068AA221214D165F151285EECD81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754", - "tx_json" : { - "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "Amount" : { - "currency" : "USD", - "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value" : "1" - }, - "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "Fee" : "10000", - "Flags" : 2147483648, - "Sequence" : 362, - "SigningPubKey" : "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB", - "TransactionType" : "Payment", - "TxnSignature" : "3045022100FBBF74057359EC31C3647AD3B33D8954730E9879C35034374858A76B7CFA643102200EAA08C61071396E9CF0987FBEA16CF113CBD8068AA221214D165F151285EECD", - "hash" : "CB98A6FA1FAC47F9FCC6A233EB46F8F9AF59CC69BD69AE6D06F298F6FF52162A" - } - } + "result": { + "accepted" : true, + "account_sequence_available" : 362, + "account_sequence_next" : 362, + "applied" : true, + "broadcast" : true, + "engine_result": "tesSUCCESS", + "engine_result_code": 0, + "engine_result_message": "The transaction was applied. Only final in a validated ledger.", + "status": "success", + "kept" : true, + "open_ledger_cost": "10", + "queued" : false, + "tx_blob": "1200002280000000240000016961D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100A7CCD11455E47547FF617D5BFC15D120D9053DFD0536B044F10CA3631CD609E502203B61DEE4AC027C5743A1B56AF568D1E2B8E79BB9E9E14744AC87F38375C3C2F181144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754", + "tx_json": { + "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", + "Amount": { + "currency": "USD", + "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", + "value": "1" + }, + "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", + "Fee": "10000", + "Flags": 2147483648, + "Sequence": 361, + "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB", + "TransactionType": "Payment", + "TxnSignature": "3045022100A7CCD11455E47547FF617D5BFC15D120D9053DFD0536B044F10CA3631CD609E502203B61DEE4AC027C5743A1B56AF568D1E2B8E79BB9E9E14744AC87F38375C3C2F1", + "hash": "5B31A7518DC304D5327B4887CD1F7DC2C38D5F684170097020C7C9758B973847" + } + }, + "validated_ledger_index" : 21184416 } ``` @@ -268,7 +296,8 @@ The response follows the [standard format][], with a successful result containin | `broadcast` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. (Note: if the server has no peers, such as in [stand-alone mode](rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode), the server uses the value `true` for cases where it _would_ have broadcast the transaction.) The value `false` indicates the transaction was not broadcast to any other servers. [New in: rippled 1.5.0][] | | `kept` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was kept to be retried later. [New in: rippled 1.5.0][] | | `queued` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates the transaction was put in the [Transaction Queue](transaction-queue.html), which means it is likely to be included in a future ledger version. [New in: rippled 1.5.0][] | -| `open_ledger_cost` | String | _(Omitted in sign-and-submit mode)_ The current [open ledger cost](transaction-cost.html#open-ledger-cost) after processing this transaction. Transactions with a lower cost are likely to be [queued](transaction-queue.html). [New in: rippled 1.5.0][] | +| `open_ledger_cost` | String | _(Omitted in sign-and-submit mode)_ The current [open ledger cost](transaction-cost.html#open-ledger-cost) before processing this transaction. Transactions with a lower cost are likely to be [queued](transaction-queue.html). [New in: rippled 1.5.0][] | +| `validated_ledger_index` | String | _(Omitted in sign-and-submit mode)_ The [ledger index][] of the newest validated ledger at the time of submission. This provides a lower bound on the ledger versions that the transaction can appear in as a result of this request. (The transaction could only have been validated in this ledger version or earlier if it had already been submitted before.) | **Warning:** Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does _not_ indicate that the transaction executed successfully. Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](transaction-results.html) for details, and do not consider the transaction's results final until they appear in a validated ledger version.