Feature: API for AMM trade price

[mDuo13]

Summary

The price of a trade that executes against an AMM is tricky to calculate and relies on the state of the ledger. It would be great to be able to quickly query the API to see how much a proposed trade might cost, or at least get the spot price for an AMM.

This could be a new API method or extend an existing, related method such as amm_info or path_find.

Motivation

Advanced trading, such as using an AMM's auction slot to save money, involves being able to predict the outcome of various possible trades, but the various AMM formulas are tricky to replicate especially with the exact precision that the XRPL uses. It would help integration to be able to query some of this directly from the XRPL server, which already has all the requisite information and formulas implemented.

Currently you can use path_find to estimate the cost of a circular cross-currency Payment that may use an AMM, but you can't use it to compare theoreticals like "what if I bought the auction slot first?" or "What if the trading fee were voted higher/lower?" If someone else currently holds the auction slot (non-expired) and has trust lines for the appropriate in/out currencies, you might be able to do a comparison with sending from their account, but that's not reliable.

Currently there is also no API or tool to estimate the proceeds of a single-asset withdrawal or the necessary input to receive a specific amount of LP Tokens.

Solution

Add new API method(s) or feature(s) to return:

• The spot price an AMM is offering in either direction based on the state of a given ledger. (This could be added to amm_info)
• The predicted cost or proceeds of using an AMM to execute a swap with and without the discount of the auction slot, including:
  • a swap "through" (in asset → out asset)
  • a single-asset withdrawal (LP Token → out asset)
  • a single-asset deposit (in asset → LP Token).

It could also be useful to add an option to show synthetic offers from AMM and autobridging to book_offers.

Paths Not Taken

These could be implemented in client libraries or Clio as well. However, it's especially helpful to have them in rippled for these reasons:

• The calculations rely on data from the ledger on the state of the AMM, preferably as up-to-date as possible. Use cases like this with trading often want to use pending (not validated) ledgers, which Clio doesn't have access to
• The precision and rounding are often relevant, and the server has the canonical implementations of those. Re-creating that logic in client libraries could lead to mismatches.
• Required inputs, in the form of the current AMM state/balances, need to be queried from the API already. It would be efficient to provide some of these types of calculations in the same response.