0069 XLS-69d: Simulating Transaction Execution

[mvadari]

An updated version of this spec can be found here: XLS-69d: Simulate.

The earlier version follows:

Title:       Simulating Transaction Execution
Revision:    1 (2024-06-03)

Author:      Mayukha Vadari
             Elliot Lee

Affiliation: Ripple

Simulating Transaction Execution

Abstract

The XRPL protocol supports numerous different transaction types, with more being added over time. Many transactions are complex and can have numerous modes, flags, and parameters. Some combinations of these can lead to unpredictable results, especially since transactions frequently behave differently depending on the current state of the ledger. This is particularly paramount for high-value transactions, as it is crucial to understand the likely outcome of the transaction and ensure that its effects align with expectations.

This proposal puts forth a new API method, tentatively titled simulate, which executes a dry run of a transaction submission. Unlike the existing submit function, simulate never submits the transaction to the network. This allows users to test transactions and preview their results (including metadata) without committing them to the XRP Ledger.

The simulate API method offers an efficient way to safely experiment with transactions on any ledger, such as the Mainnet ledger. Unlike using test networks, which can require faithfully replicating an entire scenario for experimentation, simulate allows users to "apply" transactions to a Mainnet (or other) ledger without actually submitting the transaction to be applied permanently. This allows developers and users to test and refine their transactions with confidence before committing them for real.

1. Overview

This spec proposes a new RPC method called simulate.

This method has no effect on consensus or transaction processing. Therefore, this feature will not require an amendment.

2. RPC: simulate

The simulate method applies a transaction (and returns the result and metadata for review), but will never send it to the network to be confirmed or included in future ledgers. It can be thought of as a dry-run of the submit method. This method can be used to preview the potential results and effects (via the metadata) of a potential transaction, without actually sending it to the wider network.

2.1. Request Fields

Field Name	Required?	JSON Type	Description
tx_blob		string	The transaction to simulate, in binary format.
tx_json		object	The transaction to simulate, in JSON format.
binary		boolean	If true, return transaction data and metadata as binary serialized to hexadecimal strings. If false, return transaction data and metadata as JSON. The default is false.

A valid request must have exactly one of tx_blob or tx_json included. The transaction must be unsigned.

If the Fee field is omitted (not set) in the transaction, then the server will automatically fill in a value. The calculated Fee value will be present in the response. The same is true of the Sequence field.

2.2. Response Fields

The shape of the return object is very similar to the response of the tx method.

Field Name	Always Present?	JSON Type	Description
tx_json	If binary was false	object	The transaction that was simulated, including auto-filled values. Included if binary was false.
tx_blob	If binary was true	string	The serialized transaction that was simulated, including auto-filled values. Included if binary was true.
hash	✔️	string	The unique identifying hash of the transaction.
ledger_index	✔️	number	The ledger index of the ledger that includes this transaction.
meta		object (JSON) or string (binary)	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).

3. Security

The transaction will not actually be submitted. Users and tooling will have to be careful to be using the right RPC when they want to submit vs. not submit.

Since the simulated transaction must be unsigned, a malicious rippled node cannot submit a transaction that a user only wanted to simulate, not submit.

However, a malicious rippled node could still lie about what your transaction does, or front-run your transaction.

Performance tests will need to be conducted in order to ensure that a malicious user cannot DoS a rippled node by calling this function too many times, especially when pertaining to a complex transaction that affects many ledger objects. If it is too taxing on a node, it may be implemented as an admin-only method.

4. Example

4.1. Payment

4.1.1. Request

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

4.1.2. Response

{
   "result": {
     "tx_json": {
       "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
       "DeliverMax": {
         "currency": "USD",
         "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
         "value": "1"
       },
       "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
       "Fee": "10",
       "Flags": 2147483648,
       "Sequence": 360,
       "TransactionType": "Payment"
     },
     "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"
       }
     },
     "ledger_index": 21184399,
     "ledger_hash": "BA614E270F9430E6602F253905613B7A049342C4146645698A5077EBABBADF00",
   },
   "id": 2,
   "api_version": 2,
   "status": "success",
   "type": "response"
 }

Appendix

Appendix A: FAQ

A.1: Will calling this method incur any fees?

No, because the transaction is not actually submitted to the consensus ledger and isn’t shared (broadcast) with other nodes.

A.2: Is the simulate API call guaranteed to be the same as when I actually submit the transaction?

No, because the ledger state, which affects how a transaction is processed, may change between the two API calls.

A.3: Can anyone run this function on any rippled node?

If the node is configured to provide public API access, yes. The load is similar to that of the submit method. If performance tests reveal that the function takes too much of a node’s resources even with rate limits, then it may be an admin-only method, which means that you would need administrator access to a node, or need to run your own node, to call this function.

A.4: What types of transactions can be simulated?

All transaction types can be simulated.

A.5: Can I use this method for debugging transactions?

Absolutely! The simulate function is a valuable tool for debugging and troubleshooting transactions before they are submitted to the network. You can test different scenarios and identify potential issues before committing the actual transaction.

A.6: Can I use this method to test transactions sent by accounts that I don’t control (such as a customer’s account)?

Yes, since the simulated transaction does not need to be signed.

A.7: Why isn’t this function instead called [insert alternative here]?

Several other names were considered during the ideation process, such as submit_dry_run, dry_run, or preview, or even just including a dry_run: true parameter in the submit method. We decided against having the word “submit” anywhere in the name of the method to avoid confusion from people thinking that the method actually submits a transaction, and the name "simulate" has some precedent in being used by other systems and APIs.

Appendix B: Example Use Cases

This is not intended to be an exhaustive list.

• Test high-value transactions to ensure they’ll execute as expected before actually submitting them.
• Run tests or experiments on Mainnet data without needing to recreate it all in a test network environment or needing to sync a node to spin up a new testnet environment with the data.
• Debug and troubleshoot transactions when they don’t execute as expected.
• Experiment with different features of the XRPL with real-world data without needing to spend any money.
• In user interfaces, provide users with a preview of what a transaction (e.g. Payment, OfferCreate, ...) can be expected to do.
• Get the current price of an AMM (related issue).

[tequdev]

It might be better to clearly note that there is no guarantee that the results of simulate api will be identical to the actual results of submit api.

[JosepMariaVila]

And maybe statements like "allows users to "apply" transactions to a Mainnet (or other) ledger without actually submitting the transaction"could be avoided... It's like all the time the text tries to avoid saying "apply transactions to the Mainet" but ends up saying it.

[mvadari]

Added an FAQ addressing that 🙂

[Bronek]

I am slightly worried about the cost of processing such transactions in validators. We know there are certain transactions which can be expensive to process e.g. in terms of CPU time, and it would be pretty bad if validators started processing these in large numbers, without actual change in the ledger, but with all the associated data processing cost.

To address this concern, I would suggest to add an error code tecSIMULATION_UNSUPPORTED and a configuration value, defaulting to false for validators, to the effect "simulation is supported"

[Bronek]

Thanks; it seems we agree, I just want to point out that this will require a specific error value (so the users are not confused as to why their simulated transactions fail)

[mvadari]

It will not require a specific error code. You can error at the RPC level instead of at the TER level if you don't want to support this particular RPC.

[Bronek]

Good point 👍 I did not think of this. Although I am not convinced that failing at the RPC level be better, need to think it through.

[mvadari]

That's how it works for other RPCs, and how it would work if you're e.g. missing a required field in a transaction. IMO it's an RPC-level error because it's an RPC-related error, not a transaction processing error.

[intelliot]

Just to clarify: validators should not allow public API access. (And they generally do not.) simulate is in the same category as other CPU-intensive public methods like account_tx, gateway_balances, etc.

In rippled.cfg under [server], validators are not configured to provide API access to the public.

[jscottbranson]

This functionality seems useful, however, I wanted to clarify the underlying purpose. Do you see this as predictive of the outcome of large or complex transactions (i.e., the volume of currency that is delivered), or is this targeted toward ensuring the transaction is formatted and submitted correctly?

Given how dependent transaction outcomes are on the Ledger's state, it seems the former would not be possible, as the state could change substantially in the interval between the simulated and real transactions (even if the real tx hits in the subsequent ledger to the simulation).

If the latter, I'm curious how the simulated transaction benefits from being tested on the main network. I admit it is more convenient not to switch networks, but it's realistically not a massive barrier. Perhaps access to more paths and liquidity could give a more accurate simulation?

Finally, is there reason to believe a simulated transaction could take more resources than the actual transaction? It seems like the actual would always take more, since the signature needs to be verified, so I'm interested in the line where this would become admin only.

[mvadari]

Do you see this as predictive of the outcome of large or complex transactions (i.e., the volume of currency that is delivered), or is this targeted toward ensuring the transaction is formatted and submitted correctly?

I would say a bit of both.

Given how dependent transaction outcomes are on the Ledger's state, it seems the former would not be possible, as the state could change substantially in the interval between the simulated and real transactions (even if the real tx hits in the subsequent ledger to the simulation).

That could be an effect, yes. @tequdev suggested adding a caveat that you're not guaranteed to get the results you get from simulate when you actually submit the transaction for that reason. I wouldn't go so far as to say that it's "not possible", though, as you can still gain a lot of value from getting the spot result even if it would change later (just as you derive value from knowing the spot price of a trading pair even if your offer isn't processed for a couple of ledgers after that).

If the latter, I'm curious how the simulated transaction benefits from being tested on the main network. I admit it is more convenient not to switch networks, but it's realistically not a massive barrier. Perhaps access to more paths and liquidity could give a more accurate simulation?

If you're trying to run a complex transaction, or just a DEX transaction, it's rather difficult to replicate the entire system in a testnet. There may also be factors and edgecases that your transaction will run into that you simply don't think about replicating in your testnet recreation. Plus, there is much less activity on testnet compared to mainnet. So it would be much easier to just dry-run your transaction on mainnet instead.

Finally, is there reason to believe a simulated transaction could take more resources than the actual transaction? It seems like the actual would always take more, since the signature needs to be verified, so I'm interested in the line where this would become admin only.

This RPC isn't guaranteed to be admin-only right now. That decision will be made based on performance testing; if it's decided that it's too resource-intensive to be a public method, then it will be admin-only (or, like the signing RPCs, be up to the node operator to enable). Nodes don't have to deal with that much transaction processing normally, since the network is usually doing less than 30 TPS. With simulate that number could rocket up in terms of local resource usage.

[Tapanito]

I love it, it's an excellent feature!

Though, I do have one concern. While a malicious node cannot submit these transactions, they can replay them. For instance, imagine someone is testing a valuable DEX trade. A malicious node will gain information that a trader might submit this transaction in the future or verify that executing this trade is profitable. Before the user submits the real transaction, the malicious node might submit the same transaction using their own private account.

That is to say; I think it's important to also caveat this API endpoint that it should only be called on trusted nodes or, even better, on one's own node.

[Bronek]

Oh that made me aware of another gotcha - replay attack. If the node receiving the request is malicious, and tx_json is fully formed with signature, it could be passed to submit by the malicious node. Ideally we want the signature of tx_json to simulate to be different than one to submit, e.g. as-if there was some difference inside the transaction itself.

[mvadari]

That is to say; I think it's important to also caveat this API endpoint that it should only be called on trusted nodes or, even better, on one's own node.

Yes, malicious nodes are discussed in the Security section but that specific concern isn't called out.

Oh that made me aware of another gotcha - replay attack. If the node receiving the request is malicious, and tx_json is fully formed with signature, it could be passed to submit by the malicious node. Ideally we want the signature of tx_json to simulate to be different than one to submit, e.g. as-if there was some difference inside the transaction itself.

The signature must not be included in simulate, for that exact reason.

[Bronek]

The signature must not be included in simulate, for that exact reason.

Great, thanks - I missed this part. I suggest the error in this case should be the same as if the signature was invalid, i.e. temBAD_SIGNATURE

[mvadari]

The signature must not be included in simulate, for that exact reason.

Great, thanks - I missed this part. I suggest the error in this case should be the same as if the signature was invalid, i.e. temBAD_SIGNATURE

In that case, the error will be an RPC-level error. I'd prefer if the transaction processing part of rippled isn't entered at all if there is a signature included in the transaction.

[Tapanito]

So with this attack, I wouldn't be submitting your transaction, but mine. It would just do exactly the same thing as yours. The absence of the signature doesn't help against this

…

On Tue, Jun 4, 2024, 17:20 Mayukha Vadari ***@***.***> wrote: The signature *must not* be included in simulate, for that exact reason. Great, thanks - I missed this part. I suggest the error in this case should be the same as if the signature was invalid, i.e. temBAD_SIGNATURE In that case, the error will be an RPC-level error. I'd prefer if the transaction processing part of rippled isn't entered *at all* if there is a signature included in the transaction. — Reply to this email directly, view it on GitHub <#199 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABMDKUYLJ5A2WSDOC3MYAUDZFXSOBAVCNFSM6AAAAABIXCEIZSVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TMNRXGEYTK> . You are receiving this because you commented.Message ID: ***@***.***>

[mvadari]

Yes, I was responding to Bronek's concern in that comment. You always need to be aware of the possibility of a malicious node when submitting requests to the network, since they could be manipulating your data. I agree that them frontrunning you is also a concern, and will add it to the security section.

[mvadari]

Added a bit to the security section to address that concern 🙂

[mvadari]

Per the new XLS Contributing process, it is my opinion that we have reached a "well-refined standard."

As such, I propose that we move this discussion to a file (via #207) and work on final changes using additional PRs, for better change-tracking.

Please comment here if you would like to object to moving this spec/discussion forward in the process into a DRAFT spec.

(Note that per the Contributing guidelines, moving a spec into the DRAFT state does not mean any kind of endorsement, nor does it mean that this specification will become adopted. It is solely meant as a mechanism to enable better change tracking using PRs.)

[interc0der]

As someone that does not stay up-to-date with standard discussions anymore, this seems like a good one. Glad to see it is moving forward with some urgency.

[mvadari]

Closing this discussion since the spec has been initially merged via #207.

For further discussion or changes, please open a PR on XLS-69d.