simulate

Attention

A proposed implementation is available here: XRPLF/rippled#5069.

As of 2024-10-17, the implementation is complete but awaiting code review approvals. You can build the PR branch, run rippled, sync to the network of your choice, and start using simulate today.

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.

Warning

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.

Request Format

An example of the request format:

{
    "id": 2,
    "command": "simulate",
    "tx_json" : {
        "TransactionType" : "Payment",
        "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
        "Amount" : {
            "currency" : "USD",
            "value" : "1",
            "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
        }
    }
}

The request includes the following parameters:

Field	Type	Required	Description
`tx_blob`	String	Yes	The transaction to simulate, in 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.

Transaction Notes

The simulated transaction must be unsigned.
If the SigningPubKey field is included in the transaction, it will be verified.
If Fee, Sequence, or SigningPubKey fields aren't included in the transaction, the server automatically fills in a value that will be present in the response.

Response Format

An example of a successful response:

{
  "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	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

The RPC will error if:

Both (or neither) tx_json and tx_blob are included in the request.
Any of the fields are of an incorrect type.
The transaction is signed.