mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-17 10:15:50 +00:00
add simulate method docs
This commit is contained in:
Oliver Eggert
@@ -61,10 +61,10 @@ The following amendments are open for voting with this release:
|
|||||||
|
|
||||||
### New Features
|
### New Features
|
||||||
|
|
||||||
- Added the ability to specify MPTs when defining assets in transactions. ([#5200](https://github.com/XRPLF/rippled/pull/5200)) **TODO: doc new `mpt_issuance_id` field**
|
- Added the ability to specify MPTs when defining assets in transactions. ([#5200](https://github.com/XRPLF/rippled/pull/5200))
|
||||||
- Refactored `LedgerEntry.cpp` to make it easier to read. Also added a `state` alias for `ripple_state` in the `ledger_entry` API method. ([#5199](https://github.com/XRPLF/rippled/pull/5199))
|
- Refactored `LedgerEntry.cpp` to make it easier to read. Also added a `state` alias for `ripple_state` in the `ledger_entry` API method. ([#5199](https://github.com/XRPLF/rippled/pull/5199))
|
||||||
- Improved UNL security by enabling validators to set a minimum number of UNL publishers to agree on validators. ([#5112](https://github.com/XRPLF/rippled/pull/5112))
|
- Improved UNL security by enabling validators to set a minimum number of UNL publishers to agree on validators. ([#5112](https://github.com/XRPLF/rippled/pull/5112))
|
||||||
- Added a new `simulate` API method to execute dry runs of transactions and see the simulated metadata. ([#5069](https://github.com/XRPLF/rippled/pull/5069), [#5265](https://github.com/XRPLF/rippled/pull/5265)) **TODO: doc new API method**
|
- Added a new `simulate` API method to execute dry runs of transactions and see the simulated metadata. ([#5069](https://github.com/XRPLF/rippled/pull/5069), [#5265](https://github.com/XRPLF/rippled/pull/5265))
|
||||||
- Updated the XRPL Foundation UNL keys. ([#5289](https://github.com/XRPLF/rippled/pull/5289))
|
- Updated the XRPL Foundation UNL keys. ([#5289](https://github.com/XRPLF/rippled/pull/5289))
|
||||||
- Added support to filter ledger entry types by their canonical names in the `ledger`, `ledger_data`, and `account_objects` API methods. ([#5271](https://github.com/XRPLF/rippled/pull/5271))
|
- Added support to filter ledger entry types by their canonical names in the `ledger`, `ledger_data`, and `account_objects` API methods. ([#5271](https://github.com/XRPLF/rippled/pull/5271))
|
||||||
- Added detailed logging for each validation and proposal received from the network. ([#5291](https://github.com/XRPLF/rippled/pull/5291))
|
- Added detailed logging for each validation and proposal received from the network. ([#5291](https://github.com/XRPLF/rippled/pull/5291))
|
||||||
|
|||||||
@@ -0,0 +1,193 @@
|
|||||||
|
---
|
||||||
|
seo:
|
||||||
|
description: Execute a dry run of any transaction type to preview results and metadata.
|
||||||
|
labels:
|
||||||
|
- Transaction Sending
|
||||||
|
---
|
||||||
|
# simulate
|
||||||
|
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/rpc/handlers/Simulate.cpp "Source")
|
||||||
|
|
||||||
|
The `simulate` method executes a dry run of _any_ transaction type, enabling you to preview the results and metadata of a transaction without committing them to the XRP Ledger. Since this command never submits a transaction to the network, it doesn't incur any fees.
|
||||||
|
|
||||||
|
{% admonition type="warning" name="Caution" %}
|
||||||
|
The `simulate` method isn't guaranteed to be the same when you actually submit a transaction because the ledger state--which affects how a transaction is processed--can change between the transaction simulation and submission.
|
||||||
|
{% /admonition %}
|
||||||
|
|
||||||
|
|
||||||
|
## Request Format
|
||||||
|
|
||||||
|
An example of the request format:
|
||||||
|
|
||||||
|
{% tabs %}
|
||||||
|
|
||||||
|
{% tab label="WebSocket" %}
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"command": "simulate",
|
||||||
|
"tx_json" : {
|
||||||
|
"TransactionType" : "Payment",
|
||||||
|
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||||
|
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||||||
|
"Amount" : {
|
||||||
|
"currency" : "USD",
|
||||||
|
"value" : "1",
|
||||||
|
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
{% /tab %}
|
||||||
|
|
||||||
|
{% tab label="JSON-RPC" %}
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"method": "simulate",
|
||||||
|
"params": {
|
||||||
|
"tx_json" : {
|
||||||
|
"TransactionType" : "Payment",
|
||||||
|
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||||
|
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||||||
|
"Amount" : {
|
||||||
|
"currency" : "USD",
|
||||||
|
"value" : "1",
|
||||||
|
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
{% /tab %}
|
||||||
|
|
||||||
|
{% /tabs %}
|
||||||
|
|
||||||
|
{% try-it method="simulate" /%}
|
||||||
|
|
||||||
|
The request includes the following parameters:
|
||||||
|
|
||||||
|
| Field | Type | Required? | Description |
|
||||||
|
| --------- | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||||
|
| `tx_blob` | String | Yes | The transaction to simulate, in [binary format](https://xrpl.org/docs/references/protocol/binary-format). If you include this field, do not also include `tx_json`. |
|
||||||
|
| `tx_json` | Object | Yes | The transaction to simulate, in JSON format. If you include this field, do not also include `tx_blob`. |
|
||||||
|
| `binary` | Boolean | No | The default value is `false`, which returns data and metadata in JSON format. If `true`, returns data and metadata in binary format, serialized to a hexadecimal string. |
|
||||||
|
|
||||||
|
- The simulated transaction must be unsigned.
|
||||||
|
- The server autofills `Fee`, `Sequence`, `SigningPubKey`, and `NetworkID` fields.
|
||||||
|
|
||||||
|
|
||||||
|
## Response Format
|
||||||
|
|
||||||
|
An example of a successful response:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"result": {
|
||||||
|
"applied": false,
|
||||||
|
"engine_result": "tesSUCCESS",
|
||||||
|
"engine_result_code": 0,
|
||||||
|
"engine_result_message": "The simulated transaction would have been applied.",
|
||||||
|
"ledger_index": 3,
|
||||||
|
"meta": {
|
||||||
|
"AffectedNodes": [
|
||||||
|
{
|
||||||
|
"ModifiedNode": {
|
||||||
|
"FinalFields": {
|
||||||
|
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||||
|
"AccountTxnID": "4D5D90890F8D49519E4151938601EF3D0B30B16CD6A519D9C99102C9FA77F7E0",
|
||||||
|
"Balance": "75159663",
|
||||||
|
"Flags": 9043968,
|
||||||
|
"OwnerCount": 5,
|
||||||
|
"Sequence": 361,
|
||||||
|
"TransferRate": 1004999999
|
||||||
|
},
|
||||||
|
"LedgerEntryType": "AccountRoot",
|
||||||
|
"LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
|
||||||
|
"PreviousFields": {
|
||||||
|
"AccountTxnID": "2B44EBE00728D04658E597A85EC4F71D20503B31ABBF556764AD8F7A80BA72F6",
|
||||||
|
"Balance": "75169663",
|
||||||
|
"Sequence": 360
|
||||||
|
},
|
||||||
|
"PreviousTxnID": "2B44EBE00728D04658E597A85EC4F71D20503B31ABBF556764AD8F7A80BA72F6",
|
||||||
|
"PreviousTxnLgrSeq": 18555460
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"ModifiedNode": {
|
||||||
|
"FinalFields": {
|
||||||
|
"Balance": {
|
||||||
|
"currency": "USD",
|
||||||
|
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
|
||||||
|
"value": "12.0301"
|
||||||
|
},
|
||||||
|
"Flags": 65536,
|
||||||
|
"HighLimit": {
|
||||||
|
"currency": "USD",
|
||||||
|
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||||
|
"value": "0"
|
||||||
|
},
|
||||||
|
"HighNode": "0",
|
||||||
|
"LowLimit": {
|
||||||
|
"currency": "USD",
|
||||||
|
"issuer": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||||||
|
"value": "100"
|
||||||
|
},
|
||||||
|
"LowNode": "0"
|
||||||
|
},
|
||||||
|
"LedgerEntryType": "RippleState",
|
||||||
|
"LedgerIndex": "96D2F43BA7AE7193EC59E5E7DDB26A9D786AB1F7C580E030E7D2FF5233DA01E9",
|
||||||
|
"PreviousFields": {
|
||||||
|
"Balance": {
|
||||||
|
"currency": "USD",
|
||||||
|
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
|
||||||
|
"value": "11.0301"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"PreviousTxnID": "7FFE02667225DFE39594663DEDC823FAF188AC5F036A9C2CA3259FB5379C82B4",
|
||||||
|
"PreviousTxnLgrSeq": 9787698
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"TransactionIndex": 0,
|
||||||
|
"TransactionResult": "tesSUCCESS",
|
||||||
|
"delivered_amount": {
|
||||||
|
"currency": "USD",
|
||||||
|
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||||
|
"value": "1"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"tx_json": {
|
||||||
|
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||||
|
"DeliverMax": {
|
||||||
|
"currency": "USD",
|
||||||
|
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||||
|
"value": "1"
|
||||||
|
},
|
||||||
|
"Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||||||
|
"Fee": "10",
|
||||||
|
"Sequence": 360,
|
||||||
|
"TransactionType": "Payment"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"status": "success",
|
||||||
|
"type": "response"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The response follows the [standard format][], with a successful result containing the following fields:
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
| -------------- | ------ | ----------- |
|
||||||
|
| `tx_json` | Object | The transaction that was simulated, including auto-filled values. Included if `binary` was `false`. |
|
||||||
|
| `tx_blob` | String | The serialized transaction that was simulated, including auto-filled values. Included if `binary` was `true`. |
|
||||||
|
| `ledger_index` | [Ledger Index](https://xrpl.org/docs/references/protocol/data-types/basic-data-types#ledger-index) | The ledger index of the ledger that would have included this transaction. |
|
||||||
|
| `meta` | Object | Transaction metadata, which describes the results of the transaction. Not included if the transaction fails with a code that means it wouldn’t be included in the ledger (such as a non-TEC code). Included if `binary` was `false`. |
|
||||||
|
| `meta_blob` | String | Transaction metadata, which describes the results of the transaction. Not included if the transaction fails with a code that means it wouldn’t be included in the ledger (such as a non-TEC code). Included if `binary` was `true`. |
|
||||||
|
|
||||||
|
|
||||||
|
## Possible Errors
|
||||||
|
|
||||||
|
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
|
||||||
|
* `transactionSigned` - The transaction was signed. The simulated transaction must be unsigned.
|
||||||
|
|
||||||
|
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||||
@@ -178,6 +178,21 @@
|
|||||||
{
|
{
|
||||||
"group": "Transaction Methods",
|
"group": "Transaction Methods",
|
||||||
"methods": [
|
"methods": [
|
||||||
|
{
|
||||||
|
"name": "simulate",
|
||||||
|
"description": "Executes a dry run of any transaction type, enabling you to preview the results and metadata of a transaction without committing them to the XRP Ledger.",
|
||||||
|
"link": "/docs/references/http-websocket-apis/public-api-methods/transaction-methods/simulate",
|
||||||
|
"body": {
|
||||||
|
"id": "example_simulate",
|
||||||
|
"command": "simulate",
|
||||||
|
"tx_json" : {
|
||||||
|
"TransactionType" : "Payment",
|
||||||
|
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||||
|
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||||||
|
"Amount" : "1000000"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"name": "submit",
|
"name": "submit",
|
||||||
"description": "Submits a transaction to the network to be confirmed and included in future ledgers.",
|
"description": "Submits a transaction to the network to be confirmed and included in future ledgers.",
|
||||||
|
|||||||
@@ -482,6 +482,7 @@
|
|||||||
- page: docs/references/http-websocket-apis/public-api-methods/transaction-methods/index.md
|
- page: docs/references/http-websocket-apis/public-api-methods/transaction-methods/index.md
|
||||||
expanded: false
|
expanded: false
|
||||||
items:
|
items:
|
||||||
|
- page: docs/references/http-websocket-apis/public-api-methods/transaction-methods/simulate.md
|
||||||
- page: docs/references/http-websocket-apis/public-api-methods/transaction-methods/submit.md
|
- page: docs/references/http-websocket-apis/public-api-methods/transaction-methods/submit.md
|
||||||
- page: docs/references/http-websocket-apis/public-api-methods/transaction-methods/submit_multisigned.md
|
- page: docs/references/http-websocket-apis/public-api-methods/transaction-methods/submit_multisigned.md
|
||||||
- page: docs/references/http-websocket-apis/public-api-methods/transaction-methods/transaction_entry.md
|
- page: docs/references/http-websocket-apis/public-api-methods/transaction-methods/transaction_entry.md
|
||||||
|
|||||||
Reference in New Issue
Block a user