Prerelease Docs
/
simulate
Edit

simulate

[Source]

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:

FieldTypeRequiredDescription
tx_blobStringYesThe transaction to simulate, in binary format. If you include this field, do not also include tx_json.
tx_jsonObjectYesThe transaction to simulate, in JSON format. If you include this field, do not also include tx_blob.
binaryBooleanNoThe 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:

FieldTypeDescription
tx_jsonObjectThe transaction that was simulated, including auto-filled values. Included if binary was false.
tx_blobStringThe serialized transaction that was simulated, including auto-filled values. Included if binary was true.
ledger_indexLedger IndexThe ledger index of the ledger that would have included this transaction.
metaObjectTransaction 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_blobStringTransaction 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.