rippled icon indicating copy to clipboard operation
rippled copied to clipboard

feat(rpc): greatly enhance `simulate` RPC

Open mvadari opened this issue 5 months ago • 5 comments

High Level Overview of Change

Currently, the simulate RPC only supports simulating transactions in the current ledger. This PR adds support to also simulate transactions in past ledgers, as long as the rippled node has that data.

This will make it much easier to debug past transactions, without the difficulty/complexity of needing to perform a full ledger replay (although it doesn't quite have the same flexibility). It'll provide about 90-95% of the functionality of ledger replay (if not 100%) for like 1% of the effort.

Currently, you need to follow a long set of instructions with complex scripts to run ledger replay. With this feature, the process for "replaying" a transaction would be as follows:

  1. Set a breakpoint in gdb/lldb/etc in whatever transactor you're investigating
  2. Fetch the n-1 and n ledger that the transaction you're investigating is in (steps 1 and 2 are somewhat interchangeable)
  3. Use the simulate RPC to simulate the past transaction in the past ledger as described below:
{
  "command": "simulate",
  "tx_hash": <insert tx hash here>,
  "ledger_index": <n>
}

If you need to include multiple transactions (i.e. there were other relevant transactions in the same ledger):

{
  "command": "simulate",
  "transactions": [
    {
      "tx_hash": <insert tx hash here>
    }
    ...
  ],
  "ledger_index": <n>
}

Depending on performance testing results, we may want this specific feature to be admin-only.

New features:

  • Can simulate transactions on past ledgers
  • Can fetch transactions from past ledgers (only works if you're also executing on past ledgers)
  • Batch processing
  • Process many transactions in the same request
  • TODO: toggle amendments

Context of Change

Closes #5540 (probably need to still add amendment support for that)

Type of Change

  • [x] New feature (non-breaking change which adds functionality)

API Impact

  • [x] Public API: New feature (new methods and/or new fields)
  • [ ] Public API: Breaking change (in general, breaking changes should only impact the next api_version)
  • [ ] libxrpl change (any change that may affect libxrpl or dependents of libxrpl)
  • [ ] Peer protocol change (must be backward compatible or bump the peer protocol version)

Before / After

Mainly changes to the simulate RPC. Some error codes change on other RPCs, but they're pretty minor.

Test Plan

Added some basic tests

Future Tasks

  • See TODOs above
  • More tests
  • Better autofilling support for Batch/etc

mvadari avatar Jul 31 '25 13:07 mvadari

Codecov Report

:x: Patch coverage is 97.22222% with 6 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 79.1%. Comparing base (42a432c) to head (00bd84d). :warning: Report is 1 commits behind head on develop.

Files with missing lines Patch % Lines
src/xrpld/rpc/handlers/Simulate.cpp 97.9% 4 Missing :warning:
src/xrpld/app/tx/detail/apply.cpp 92.3% 2 Missing :warning:
Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff            @@
##           develop   #5637    +/-   ##
========================================
  Coverage     79.1%   79.1%            
========================================
  Files          839     839            
  Lines        71367   71503   +136     
  Branches      8339    8341     +2     
========================================
+ Hits         56425   56556   +131     
- Misses       14942   14947     +5     
Files with missing lines Coverage Δ
src/libxrpl/ledger/ApplyStateTable.cpp 93.0% <100.0%> (-<0.1%) :arrow_down:
src/xrpld/rpc/handlers/LedgerData.cpp 55.6% <100.0%> (ø)
src/xrpld/app/tx/detail/apply.cpp 91.4% <92.3%> (-1.2%) :arrow_down:
src/xrpld/rpc/handlers/Simulate.cpp 98.6% <97.9%> (-1.4%) :arrow_down:

... and 2 files with indirect coverage changes

Impacted file tree graph

:rocket: New features to boost your workflow:
  • :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

codecov[bot] avatar Jul 31 '25 14:07 codecov[bot]

  1. Set a breakpoint in gdb/lldb in whatever transactor you're investigating

Reminder that Transactor::trapTransaction was specifically created to provide a convenient location for such breakpoint, in case if you do not use simulate but replay the whole ledger instead (which is obviously more trouble that the alternative process proposed here)

https://github.com/XRPLF/rippled/blob/39b5031ab5efa543e3007fb3fc7e199381ee68fb/src/xrpld/app/tx/detail/Transactor.cpp#L1054

Bronek avatar Aug 08 '25 12:08 Bronek

  1. Set a breakpoint in gdb/lldb in whatever transactor you're investigating

Reminder that Transactor::trapTransaction was specifically created to provide a convenient location for such breakpoint, in case if you do not use simulate but replay the whole ledger instead (which is obviously more trouble that the alternative process proposed here)

https://github.com/XRPLF/rippled/blob/39b5031ab5efa543e3007fb3fc7e199381ee68fb/src/xrpld/app/tx/detail/Transactor.cpp#L1054

I would say this is still relevant for debugging with this - you essentially can skip the complicated parts of ledger replay and just "replay" the transaction via simulate instead.

mvadari avatar Aug 08 '25 15:08 mvadari

@dangell7 I added you as a reviewer as this PR touches some Batch code, so you would be a good person to take a look there.

bthomee avatar Sep 24 '25 18:09 bthomee

Some of the refactors in this PR were moved to #5684 so waiting on that to be merged before dealing with this merge conflict.

mvadari avatar Dec 04 '25 18:12 mvadari